Roarpeng/GraphFlow

# GraphFlow — Token-First Surgical Engine (外科手术级省 Token 引擎)

Always prefer the 4 surgical `gf_*` MCP tools over raw full-file reads or verbose test runs (请优先使用以下 4 个 `gf_*` 工具代替整文件读取与全量测试):

1. **`gf_read`** (`targets`, `q`, `topK`, `skeleton`, `dedup`):
   - Read exact symbols (`"src/file.ts#symbol"`, `"src/file.ts:L1-L2"`) with automatic **Cross-File Type Closure** and receiver-type-aware `[Blast Radius]` caller snippets — blast-radius target resolution consults the self-written L0 semantic index first (confidence ≥0.75) and only then the receiver/inheritance heuristics: declarations, annotations, `new Type()`, parameters, class fields, `this`/`self`/`cls`/`Self`, `Class.`/`Class::` and the Go/Rust/C++/C# declaration forms; `super`/`base` resolve to the parent class, subclass receivers dispatch to inherited base methods unless an intermediate class overrides, last assignment wins per scope, and generic/array/nullable annotations are unwrapped, so `A.cancel` vs `B.cancel` in one file disambiguate and only matching receivers count (精准读取目标函数/类，自动附带跨文件类型定义与调用点爆炸半径；调用目标先查自研 L0 语义索引（置信度 ≥0.75），再回退接收者/继承启发式；方法调用按推断出的接收者类型消歧，`super`/`base` 指向父类，子类可命中未覆写的基类方法，最后赋值优先，泛型/数组/可空标注会解包).
   - Bilingual keyword search (`q: "keyword / 中文关键词 / pinyin"`) across symbol names, docstrings and comments — validated at **1.000 EN / 1.000 ZH recall@1/@3/@5** on the isolated + packed (6 symbols/file) corpus. Phrases outside that glossary use a repo PMI map (`.graphflow/zh-identifier-map.json`) plus a small curated colloquial lexicon; `registerZhEnModel` stays off unless `GRAPHFLOW_ZH_EN_MODEL=1`. Omitting `topK` returns one slice when the top score margin is confident, otherwise the near-tie cluster, without type closure (双语检索在孤立 + packed 语料上 EN/ZH @1/@3/@5 仍为 1.000；词表外说法走仓库 PMI 映射和小型口语词表；默认不传 `topK` 时高置信只切 1 条，接近的分数保留一小簇，且不附类型闭合).
   - Fold large files into symbol skeletons (`"src/file.ts"`, `skeleton: true`) and pass `dedup: true` to skip unchanged files.
2. **`gf_edit`** (`file`, `symbol`, `newCode`, `edits`, `renameTo`):
   - Edit symbols or line ranges in-place, apply multi-file atomic batch `edits` bottom-up with zero line drift, or run zero-LLM cross-repo symbol rename (`renameTo`) — rename asks the semantic index for a resolved target first (confidence ≥0.75) and then reuses the receiver/inheritance resolution: foreign-receiver-only files are skipped, mixed target/foreign files are rejected as `REJECTED [ambiguous-symbol]`, same-name sibling declarations are rejected before writing, and unresolved callers roll the rename back with the file list. **Import paths are never rewritten**: comments and string/template literals are masked with equal-length placeholders before replacing, so renaming `combineURLs` cannot turn `./combineURLs.js` into `./joinURLs.js` (import 路径不会被重命名改动：替换前先对注释与字符串/模板串做等长遮蔽，因此重命名 `combineURLs` 不会把 `./combineURLs.js` 改成 `./joinURLs.js`). (重命名先查语义索引（置信度 ≥0.75），再复用接收者/继承解析：跳过仅外部接收者命中的文件；目标与外部接收者混用的文件以 `REJECTED [ambiguous-symbol]` 拒绝；同名兄弟声明写入前拒绝；仍有未解析调用方则回滚并返回文件清单).
   - Syntax guards use the true-AST backends when installed — `@babel/parser` for TS/JS, tree-sitter ERROR/MISSING diagnostics for Python/Go/Rust/C/C++/C#; the structural analyzers' heuristic checks (brace/declaration, Python missing-colon/bracket diagnostics) are the fallback and apply when `GRAPHFLOW_TREE_SITTER=0`. Caller-arity checks and struct/interface field-deletion guards also apply (语法守卫使用已安装的真 AST 后端：TS/JS 用 `@babel/parser`，其余 5 种用 tree-sitter 的 ERROR/MISSING 诊断；结构化分析器的启发式检查为回退，`GRAPHFLOW_TREE_SITTER=0` 时生效；另有调用方参数个数校验与结构体字段删除引用守卫).
3. **`gf_exec`** (`cmd`, `changedFiles`, `handle`, `run`, `timeoutMs`):
   - Run `cmd: "affected-tests"` (2-hop reverse import router + `tsconfig.json`/`jsconfig.json` JSONC `baseUrl`/`paths` aliases with `extends` chains, nearest nested configs and root project `references` + dynamic `import()`/`require()`; honors `package.json` `scripts.test`) or any command with output dehydration. It recognizes `tests/`, `__tests__/`, `spec/`, `.test.*`/`.spec.*`, `.test.mts`/`.cts`, `*_test.go`, `test_*.py`, `*Tests.cs`; routing stays heuristic — no nested project-to-project reference traversal, no Node `exports` map, `node_modules` `extends` stops at the workspace root (2-hop 反向 import 路由 + tsconfig/jsconfig 别名（含 extends 链、最近嵌套配置、根 references）+ 动态 import；识别常见测试约定；不做嵌套项目间 reference 遍历、不支持 Node exports map，node_modules 的 extends 止于工作区根).
   - **`run: true` is required to execute — without it the call is a preview only** (必须传 `run: true` 才执行，否则仅返回预览；测试通过仅回 1 行 `PASS`；失败时内联最多 5 行源码上下文，包括 `Error:` 行紧跟栈帧与 Python traceback 的情况；连续 3 次失败触发死循环熔断急救包).

# GraphFlow — Token-First Surgical Engine (外科手术级省 Token 引擎)

Always prefer the 4 surgical `gf_*` MCP tools over raw full-file reads or verbose test runs (请优先使用以下 4 个 `gf_*` 工具代替整文件读取与全量测试):

1. **`gf_read`** (`targets`, `q`, `topK`, `skeleton`, `dedup`):
   - Read exact symbols (`"src/file.ts#symbol"`, `"src/file.ts:L1-L2"`) with automatic **Cross-File Type Closure** and receiver-type-aware `[Blast Radius]` caller snippets — blast-radius target resolution consults the self-written L0 semantic index first (confidence ≥0.75) and only then the receiver/inheritance heuristics: declarations, annotations, `new Type()`, parameters, class fields, `this`/`self`/`cls`/`Self`, `Class.`/`Class::` and the Go/Rust/C++/C# declaration forms; `super`/`base` resolve to the parent class, subclass receivers dispatch to inherited base methods unless an intermediate class overrides, last assignment wins per scope, and generic/array/nullable annotations are unwrapped, so `A.cancel` vs `B.cancel` in one file disambiguate and only matching receivers count (精准读取目标函数/类，自动附带跨文件类型定义与调用点爆炸半径；调用目标先查自研 L0 语义索引（置信度 ≥0.75），再回退接收者/继承启发式；方法调用按推断出的接收者类型消歧，`super`/`base` 指向父类，子类可命中未覆写的基类方法，最后赋值优先，泛型/数组/可空标注会解包).
   - Bilingual keyword search (`q: "keyword / 中文关键词 / pinyin"`) across symbol names, docstrings and comments — validated at **1.000 EN / 1.000 ZH recall@1/@3/@5** on the isolated + packed (6 symbols/file) corpus. Phrases outside that glossary use a repo PMI map (`.graphflow/zh-identifier-map.json`) plus a small curated colloquial lexicon; `registerZhEnModel` stays off unless `GRAPHFLOW_ZH_EN_MODEL=1`. Omitting `topK` returns one slice when the top score margin is confident, otherwise the near-tie cluster, without type closure (双语检索在孤立 + packed 语料上 EN/ZH @1/@3/@5 仍为 1.000；词表外说法走仓库 PMI 映射和小型口语词表；默认不传 `topK` 时高置信只切 1 条，接近的分数保留一小簇，且不附类型闭合).
   - Fold large files into symbol skeletons (`"src/file.ts"`, `skeleton: true`) and pass `dedup: true` to skip unchanged files.
2. **`gf_edit`** (`file`, `symbol`, `newCode`, `edits`, `renameTo`):
   - Edit symbols or line ranges in-place, apply multi-file atomic batch `edits` bottom-up with zero line drift, or run zero-LLM cross-repo symbol rename (`renameTo`) — rename asks the semantic index for a resolved target first (confidence ≥0.75) and then reuses the receiver/inheritance resolution: foreign-receiver-only files are skipped, mixed target/foreign files are rejected as `REJECTED [ambiguous-symbol]`, same-name sibling declarations are rejected before writing, and unresolved callers roll the rename back with the file list. **Import paths are never rewritten**: comments and string/template literals are masked with equal-length placeholders before replacing, so renaming `combineURLs` cannot turn `./combineURLs.js` into `./joinURLs.js` (import 路径不会被重命名改动：替换前先对注释与字符串/模板串做等长遮蔽，因此重命名 `combineURLs` 不会把 `./combineURLs.js` 改成 `./joinURLs.js`). (重命名先查语义索引（置信度 ≥0.75），再复用接收者/继承解析：跳过仅外部接收者命中的文件；目标与外部接收者混用的文件以 `REJECTED [ambiguous-symbol]` 拒绝；同名兄弟声明写入前拒绝；仍有未解析调用方则回滚并返回文件清单).
   - Syntax guards use the true-AST backends when installed — `@babel/parser` for TS/JS, tree-sitter ERROR/MISSING diagnostics for Python/Go/Rust/C/C++/C#; the structural analyzers' heuristic checks (brace/declaration, Python missing-colon/bracket diagnostics) are the fallback and apply when `GRAPHFLOW_TREE_SITTER=0`. Caller-arity checks and struct/interface field-deletion guards also apply (语法守卫使用已安装的真 AST 后端：TS/JS 用 `@babel/parser`，其余 5 种用 tree-sitter 的 ERROR/MISSING 诊断；结构化分析器的启发式检查为回退，`GRAPHFLOW_TREE_SITTER=0` 时生效；另有调用方参数个数校验与结构体字段删除引用守卫).
3. **`gf_exec`** (`cmd`, `changedFiles`, `handle`, `run`, `timeoutMs`):
   - Run `cmd: "affected-tests"` (2-hop reverse import router + `tsconfig.json`/`jsconfig.json` JSONC `baseUrl`/`paths` aliases with `extends` chains, nearest nested configs and root project `references` + dynamic `import()`/`require()`; honors `package.json` `scripts.test`) or any command with output dehydration. It recognizes `tests/`, `__tests__/`, `spec/`, `.test.*`/`.spec.*`, `.test.mts`/`.cts`, `*_test.go`, `test_*.py`, `*Tests.cs`; routing stays heuristic — no nested project-to-project reference traversal, no Node `exports` map, `node_modules` `extends` stops at the workspace root (2-hop 反向 import 路由 + tsconfig/jsconfig 别名（含 extends 链、最近嵌套配置、根 references）+ 动态 import；识别常见测试约定；不做嵌套项目间 reference 遍历、不支持 Node exports map，node_modules 的 extends 止于工作区根).
   - **`run: true` is required to execute — without it the call is a preview only** (必须传 `run: true` 才执行，否则仅返回预览；测试通过仅回 1 行 `PASS`；失败时内联最多 5 行源码上下文，包括 `Error:` 行紧跟栈帧与 Python traceback 的情况；连续 3 次失败触发死循环熔断急救包).