graphflow git:20261019.64f09e1A

Immutable. This exact content never changes and is served at /api/v1/blob/0634c31e8e24fe06.

---
name: graphflow
description: Token-First Surgical Code Engine (gf_read, gf_edit, gf_exec, gf_macro) for TS/JS, Python, Go, Rust, C/C++, C# — true AST for all six language families (TS/JS via `@babel/parser`; Python/Go/Rust/C/C++/C# via optional tree-sitter grammars, structural fallback), self-written L0 semantic index, inheritance-aware blast-radius guards, ambiguous-safe rename, type-aware knowledge-graph calls with alias-resolved imports, precision-capped BM25 doc↔code links, `extends`-aware affected-test routing, six-language parity (51 tests) with packed EN/ZH recall 1.000, offline task reflection/auto-harvest, dehydrated test logs (1-line PASS), bilingual 中文/pinyin code search, git co-change habit macros. 外科手术级省 Token 代码引擎：6 种语言真 AST（TS/JS 用 `@babel/parser`；其余用可选 tree-sitter，缺省回退结构化分析）、自研 L0 语义索引、含继承/super 的爆炸半径守卫、歧义安全重命名、类型感知知识图谱 calls 与别名解析 imports、BM25 上限控制的文档↔代码链接、extends 感知的受影响测试路由、六语言平价（51 项）与 packed EN/ZH 召回 1.000、离线任务反射/自动收割、测试日志脱水、双语检索、习惯宏。
---

# 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 (重命名先查语义索引（置信度 ≥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`):
   - 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 次失败触发死循环熔断急救包).
   - Recall full archived output any time via the returned `handle` + `range`.
4. **`gf_macro`** (`action: "list" | "run" | "save" | "mine" | "mine-git" | "visualize" | "brief" | "task-list" | "task-run" | "task-record" | "task-harvest"`):
   - Mine git history co-change coupling (`mine-git`), run auto-compiled `.graphflow/macros/*.mjs` scripts with zero LLM turns, export the interactive knowledge-graph HTML, or manage local reflected tasks (`task-list` / `task-run` / `task-record` / `task-harvest` with `instruction` + `steps`) — see Task reflection below. Graph: a real best-effort graph with type-aware `calls` (receiver-matched targets; foreign receivers dropped), `imports` (relative paths + root tsconfig/jsconfig aliases), `defines` (file → symbol), `doc-links-code` and `co-edit` edges; method ids are class-qualified (`sym:file#Class.method`). `doc-links-code` edges are self-written BM25/IDF + PMI scored with per-section/per-symbol caps (≤3) and a global `GRAPHFLOW_DOC_LINKS_MAX` (default 400), confidence-labelled; `.graphflow/doc-link-feedback.json` is read-only accept/reject feedback. Edges are best-effort heuristics, not type-checked, capped at 5000; Go/C# import edges use a stem/dir fallback (知识图谱 HTML 为真实依赖图：类型感知 calls（按接收者匹配目标、外部接收者丢弃）、imports（相对路径 + 根 tsconfig/jsconfig 别名）、defines/doc-links-code/co-edit 五种边，方法节点 id 带类名；文档↔代码边为自研 BM25/IDF + PMI 打分，受每小节/每符号上限（≤3）与全局 `GRAPHFLOW_DOC_LINKS_MAX`（默认 400）约束并带置信度；`.graphflow/doc-link-feedback.json` 为只读的接受/拒绝反馈；边为启发式、非类型检查、上限 5000；另可管理本地任务反射：task-list / task-run / task-record / task-harvest).

## Setup — register the MCP server (安装 MCP 服务器)

This skill is the usage layer; the `gf_*` tools live in the GraphFlow MCP server. If they are not registered yet, run this **from the project you want to work on** — the workspace root is captured as the server's `cwd`:

```bash
npx @roarpeng/graphflow@latest install            # or scope it: ... install --agents deepseek-harness
```

That auto-detects your agents and registers MCP + Skill + Rules + Hooks, merging GraphFlow hooks into existing host hook configs and preserving user hooks (从工作区根目录执行；安装器会探测已安装 Agent 并注册 MCP + Skill + Rules + Hooks，钩子为合并写入并保留用户钩子). Check what is registered with `graphflow status` — it prints one line per agent, e.g. `[MCP ✓] [Skill ✓] [Rule -] [Hook ✓] Cursor (cursor)` (每个 Agent 一行显示 MCP/Skill/Rule/Hook 注册状态). `graphflow uninstall` removes only GraphFlow-owned registrations, including only GraphFlow's own hook entries (卸载只删除 GraphFlow 自己的注册项与钩子条目).

Check parser backends with `graphflow doctor parsers` (add `--strict` to fail when true AST is unavailable; alias `graphflow parsers`). From a source checkout, `npm run verify:parsers` runs the true-AST vs forced-structural matrix (`GRAPHFLOW_TREE_SITTER=0`) and `npm run preflight` runs the static release gate (解析器后端用 `graphflow doctor parsers` 查看，`--strict` 在真 AST 不可用时失败，别名为 `graphflow parsers`；源码检出下 `npm run verify:parsers` 跑真 AST/强制结构化矩阵，`npm run preflight` 跑静态发布预检).

### DeepSeek Harness (DSH)

DSH does **not** read `~/.dsh/mcp.json` — its MCP servers are Cordis plugin inserts in `~/.dsh/cordis.patch.yml`. `graphflow install` writes a managed block there inserting `@deepseek-ai/dsh-mcp-client` (`serverName: graphflow`, `transport: stdio`, `command: npx`, `args: ["-y","--package=@roarpeng/graphflow","graphflow-mcp"]`), with `cwd` set to your workspace and `GRAPHFLOW_WORKSPACE_ROOT` in its env, and installs this skill to `~/.dsh/skills/graphflow/SKILL.md` (DSH 不读 `~/.dsh/mcp.json`；安装器改为写入 `~/.dsh/cordis.patch.yml` 的托管块，`cwd` 指向工作区并设置 `GRAPHFLOW_WORKSPACE_ROOT`，Skill 装到 `~/.dsh/skills/graphflow/SKILL.md`).

`cwd` matters: without it the MCP child process starts in the DSH profile directory, so every `gf_*` target must pass an explicit `rootDir`. After a workspace install, relative targets such as `src/app.ts#main` resolve normally; if you registered manually or get wrong-root errors, pass `rootDir` explicitly (没有 `cwd` 时子进程在 DSH 配置目录启动，需显式传 `rootDir`；在工作区安装后相对目标即可正常解析).

**Bundle alternative (配置包替代方案).** `@roarpeng/graphflow-dsh` is a configuration-only DSH Cordis bundle (version mirrors the CLI): its patch inserts the same `mcp-graphflow` stdio row (cwd from `GRAPHFLOW_WORKSPACE_ROOT`, else DSH's default working directory) and ships this skill. Install it via `plugin_manager install_bundle` (or `node scripts/install-dsh-bundle.mjs --print|--stage|--check`). Honest DSH matrix: **MCP ✅ · Skill ✅ · Rules ❌ · Hooks ❌**. Use the bundle **or** `graphflow install --agents deepseek-harness`, not both (same row id/serverName) (配置包...：纯配置 DSH Cordis bundle，插入同一条 mcp-graphflow 行并携带 Skill；通过 plugin_manager install_bundle 或安装脚本使用；DSH 能力矩阵 MCP ✅ · Skill ✅ · Rules ❌ · Hooks ❌；与 CLI 安装器二选一).

Other agents that read an `mcpServers` JSON block can register manually:

```json
{ "mcpServers": { "graphflow": { "command": "npx", "args": ["-y", "@roarpeng/graphflow@latest", "graphflow-mcp"] } } }
```

### Task reflection — offline command replay (本地任务反射)

Repeat a shell workflow and GraphFlow can replay it locally with no LLM/network call (重复的 shell 流程可记录并在本地重放，无需 LLM/网络). Two paths — explicit record, or an externally written instruction log:

```bash
# explicit: record twice to promote
graphflow task record "run parser matrix" --step "npm run build" --step "node scripts/verify-parsers.mjs"
graphflow task record "run parser matrix" --step "npm run build" --step "node scripts/verify-parsers.mjs"
graphflow reflect "run parser matrix"                 # compiled .graphflow/tasks/<id>.mjs; near-match (Jaccard 0.86) replays offline

# auto-harvest: an external writer appends to the JSONL log, then harvest promotes repeats
graphflow task log "run parser matrix" --step "npm run build" --step "node scripts/verify-parsers.mjs"
graphflow task harvest [--log .graphflow/instruction-log.jsonl]   # incremental via .graphflow/task-harvest.json
```

Or from MCP: `gf_macro({ action: "task-record", instruction, steps })` / `gf_macro({ action: "task-harvest", instruction, steps })` (bare `task-harvest` harvests the log), then `task-list` / `task-run`. `graphflow reflect` returns `MISS` when nothing matches. Recording is explicit unless a log writer exists: **auto-harvest still needs an external writer** (shell wrapper / DSH skill — no host hook or daemon), shell steps run locally with the recorder's privileges, `{{argN}}` is manual, and concurrent cross-process records are last-writer-wins (`npm run task` / `npm run reflect` equivalents; 记录写入 `.graphflow/tasks.json` 并编译为 `.graphflow/tasks/<id>.mjs`；自动收割读取 `.graphflow/instruction-log.jsonl`，按字节偏移增量处理并写入 `.graphflow/task-harvest.json`；未知指令返回 MISS；自动收割需要外部写入者，无宿主钩子/守护进程；步骤以记录者权限本地执行、`{{argN}}` 需手工参数化、并发记录最后写入者胜出).

### Limits (边界)

- Exactly 4 tools: no knowledge-graph, planning, or artifact surface (只有 4 个工具).
- True AST is the default for all six languages: TS/JS via `@babel/parser`; Python/Go/Rust/C/C++/C# via optional tree-sitter grammars, with the built-in structural analyzers as the fallback when a grammar is missing. tree-sitter is syntax-only — no semantic type resolution — so cross-file inference stays heuristic (documented limits: Python import aliases/nested functions, Go grouped params/embedded fields, Rust macros/trait-macro edge cases, C/C++ macros/namespaces, C# properties-as-fields/non-record constructors). Set `GRAPHFLOW_TREE_SITTER=0` to force structural (6 种语言默认真 AST：TS/JS 用 `@babel/parser`，其余用可选 tree-sitter，缺语法包时回退结构化分析；tree-sitter 仅语法、无语义类型解析；`GRAPHFLOW_TREE_SITTER=0` 强制结构化).
- Runtime deps: `@babel/parser`, `@modelcontextprotocol/sdk`, `tree-sitter` (required); the six grammar packages are optionalDependencies — peer-range install warnings are expected, and a missing grammar falls back to structural for that language (必需依赖：`@babel/parser`、`@modelcontextprotocol/sdk`、`tree-sitter`；6 个语法包为可选依赖，peer 范围警告属正常，缺包即回退结构化分析).
- Blast radius and rename are receiver-type-aware heuristics, not a type checker: known-mismatched receivers are excluded, same-file same-name methods disambiguate, `super`/`base` and subclass→base dispatch are inheritance-aware (when no intermediate class overrides), last assignment wins per scope (conflicting branch assignments are unknown), and generic/array/nullable wrappers are unwrapped. Residual: ambiguous unions/factory returns and dynamic receivers stay unknown; multi-level override chains need the intermediate class parseable; Rust trait dispatch resolves to the trait method but trait+impl atomic rename stays conservative, and Go embedding is intentionally not inherited (接收者类型推断是启发式，不是类型检查器；含继承/super 与最后赋值，泛型/数组/可空解包；歧义联合/工厂返回/动态接收者未知；多级覆写需中间类可解析；Rust trait 分派解析到 trait 方法，但 trait+impl 原子重命名保持保守；Go 嵌入不做继承).
- Blast radius and rename consult a self-written L0 semantic index first (`src/semantic-index.ts`, confidence ≥0.75): module graph with root tsconfig/jsconfig aliases + barrel/re-exports, workspace symbol table, per-file type env, and resolved call targets. Residual: root config only (no `extends`/project references), default/namespace import limits, no flow narrowing or generic substitution (爆炸半径/重命名先查自研 L0 语义索引（置信度 ≥0.75）：模块图（根 tsconfig/jsconfig 别名 + barrel/re-export）、工作区符号表、逐文件类型环境、调用目标解析；残余：仅根配置（不支持 extends/project references）、default/namespace import 限制、无流敏感收窄/泛型替换).
- Optional semantic acceleration: `src/ts-semantic.ts` uses the installed TypeScript compiler package when present (lazily; `resolveCallTarget`/`getReferences`/`getTypeAt`), and `src/lsp-bridge.ts` drives user-installed stdio language servers (pyright/pylsp, gopls, rust-analyzer, clangd, OmniSharp/csharp-ls, typescript-language-server). Neither is a required dependency and no servers are bundled — availability depends on your environment (可选语义加速：...；均非必需依赖、不捆绑语言服务器，可用性取决于用户环境).
- Knowledge-graph `calls` edges are best-effort (receiver-type-aware when resolvable, not type-checked) and capped at 5000; `imports` use relative resolution plus root tsconfig/jsconfig aliases; Go/C# `imports` edges use a stem/dir fallback (知识图谱边为启发式，非类型检查).
- Affected-test routing is heuristic: `tsconfig`/`jsconfig` `extends` chains (relative + node_modules, arrays, cycle-safe), nearest nested configs, `jsconfig` inheritance and root `references` are supported; no nested project-to-project reference traversal, no Node `exports` map, `node_modules` `extends` stops at the workspace root, configs are cached for the process lifetime (受影响测试路由支持 extends 链/最近嵌套配置/根 references；不做嵌套项目间 reference 遍历、不支持 Node exports map).
- Doc↔code linking is a self-written BM25/IDF + PMI pipeline with reciprocal top-K, per-section/per-symbol caps (≤3), `GRAPHFLOW_DOC_LINKS_MAX` (default 400) and confidence labels; concept links require margin/confidence. `.graphflow/doc-link-feedback.json` is read-only accept/reject input; `@brief` remains heuristic (文档↔代码链接为自研 BM25/IDF + PMI 流水线，双向 Top-K、每小节/每符号上限 ≤3、全局 `GRAPHFLOW_DOC_LINKS_MAX`（默认 400）与置信度）；反馈文件只读；`@brief` 仍为启发式).
- Six-language parity residuals (51-test matrix): **Go same-package imports is the honest remaining gap** — same-package sibling files have no file-level `imports` edge (no invented edges; package-scope calls/edges resolve). Rust trait dispatch and C# `record`/`record struct` + namespace-map resolution are closed; remaining residuals are trait+impl atomic rename rejected safely, `impl Trait for Type` not modelled as subclassing, ambiguous doc-graph KG `calls` now resolved via the semantic index's namespace map (confidence ≥0.75; fixture `using Demo.Two; g.Cancel()` → `two/Gadget.cs#Gadget.Cancel`; residual only the one-time cold semantic-index build ~+120 ms, then cached, and the `GRAPHFLOW_KG_SEMANTIC=0` escape hatch), C function-level, Go models only the first embedded type, conservative rename, and best-effort C++ prototype targeting; the structural fallback is not covered by the parity matrix (六语言平价残余（51 项矩阵）：Go 同包 imports 为仅存的诚实缺口（同包兄弟文件无文件级 imports 边，不虚构；包作用域 calls/边可解析）；Rust trait 分派与 C# record/record struct + namespace 映射已闭环；剩余：trait+impl 原子重命名安全拒绝、impl Trait for Type 不视为继承、doc-graph KG 的歧义 calls 现经语义索引 namespace 映射解析（置信度 ≥0.75；fixture：`using Demo.Two; g.Cancel()` → `two/Gadget.cs#Gadget.Cancel`；残余仅为首次歧义工作区的一次性冷启动构建约 +120 ms 后缓存，以及 `GRAPHFLOW_KG_SEMANTIC=0` 逃生开关）、C 为函数级、Go 只建模第一个嵌入类型、重命名保守、C++ 原型定位尽力而为；结构化回退不在平价矩阵内).
- Task reflection: explicit `task record` plus optional external-log auto-harvest (`task log` → `.graphflow/instruction-log.jsonl`, incremental `task harvest` via `.graphflow/task-harvest.json`). Auto-harvest still needs an external writer (shell wrapper / DSH skill — no host hook or daemon); recorded shell steps run locally with the recorder's privileges; `{{argN}}` parameters are manual; concurrent cross-process records are last-writer-wins (任务反射：显式 `task record`，并可选用外部日志自动收割（`task log` → `.graphflow/instruction-log.jsonl`，`task harvest` 按字节偏移增量处理）；自动收割仍需外部写入者（shell wrapper / DSH skill，无宿主钩子或守护进程）；步骤以记录者权限本地执行；`{{argN}}` 需手工参数化；并发记录最后写入者胜出).
- Release/CI: `npm run preflight` / `preflight:release` gate the repo; CI (6 jobs) and the parser matrix (7 jobs) are green across ubuntu/windows/macos × Node 20/22, and the suite has 26 test files (发布/CI：CI 6 job + 解析器矩阵 7 job 在三大 OS × Node 20/22 全绿；共 26 个测试文件).
- `gf_exec` executes nothing unless `run: true` (只有 `run: true` 才会执行).

Verify with `graphflow status`, then call `gf_read({ targets: ["src/some-file.ts"], skeleton: true })` for a ~300-token project orientation (`@brief` target returns the cross-agent handoff brief).