代码知识图谱 Roarpeng/GraphFlow

GraphFlow

面向编码 agent 的省 Token 外科手术引擎（v3.9.0）。 四个确定性 MCP 工具加 0-LLM 提示词反射——全本地执行，引擎环内无 LLM。

四个外科手术工具

| 工具 | 能力 |
| gf_read | 精确切片符号（file.ts#fn），自动跨文件类型闭合 + 爆炸半径调用点；中英双语关键词检索（q: "启动 / launch"）；AST 骨架折叠（−93% token）。 |
| gf_edit | 符号/行级就地编辑、自底向上原子批改、跨仓重命名——带 AST 语法回滚、调用方参数个数与结构体字段守卫。 |
| gf_exec | affected-tests 路由（两跳反向导入）或任意命令的脱水执行：1 行 PASS 回执、5 行失败源码窗口、三连败熔断。run:true 执行，否则预览。 |
| gf_macro | 习惯挖掘的确定性宏：重复读取 → 上下文捆绑；重复命令 → 单步 pipeline / 参数化模板；同构编辑 → codemod。回放零 LLM。 |

Prompt Reflex（0-LLM 本地反射）

短命令式输入（如 启动项目）命中宏触发词 → 本地执行宏并阻断 prompt 进入模型；长句降级为注入提示；其余静默放行。总闸：GRAPHFLOW_PROMPT_REFLEX=0。

- 第一档 —— 完整阻断（自动注册）：ZCode、Claude Code、Codex CLI、Gemini CLI、Cursor、Windsurf、Trae、Qoder、Kimi Code、Continue CLI。
- 第二档 —— 注入/改写：OpenCode、Kilo Code、Cline（Unix）、DeepSeek Harness。
- 第三档 —— 回退（gf_macro MCP）：VS Code Copilot、Zed、Claude Desktop、PearAI、Antigravity、Roo Code（已归档）。

逐宿主配置与安全说明：docs/prompt-reflex.md。

快速开始

npm install -g @roarpeng/graphflow # Node 18+
graphflow install # 一键注册 MCP + Skill + Rules + Hooks 到检测到的 agent graphflow status # 各 agent 注册状态 graphflow-mcp # stdio MCP 服务器

仅装技能：npx skills add Roarpeng/GraphFlow。读 mcpServers JSON 的宿主手动注册：{ "mcpServers": { "graphflow": { "command": "graphflow-mcp" } } }。

支持语言

| 语言 | 后端 |
| TypeScript / JavaScript | 真 AST（@babel/parser） |
| Python / Go / Rust / C / C++ / C# | 可选 tree-sitter-* 语法的真 AST（缺失时结构化兜底；GRAPHFLOW_TREE_SITTER=0 关闭） |

运行时依赖：@babel/parser、@modelcontextprotocol/sdk、tree-sitter + 可选语法包。tree-sitter 仅做语法；跨文件类型推断保持启发式（有已记录的边界）。

22-agent 自动安装器

graphflow install 检测已装 agent 并注册 MCP + Skill + Rules + Hooks——钩子合并幂等且保留用户条目；graphflow uninstall 只移除 GraphFlow 拥有的注册。用 --agents <id1,id2> / --all / --workspace 收窄范围。

覆盖：Cursor、VS Code、Windsurf、Trae、Zed、Claude Code、Codex、Gemini CLI、Antigravity、Kimi Code、DeepSeek Harness、OpenCode、ZCode、Cline、Roo Code、Kilo Code、Continue、PearAI、Qoder、Claude Desktop、Amazon Q、WorkBuddy。

DeepSeek Harness（DSH）

DSH 读 Cordis patch 而非 mcp.json。graphflow install 在 ~/.dsh/cordis.patch.yml 写入托管块（# GRAPHFLOW-DSH-BEGIN/END）并把 cwd 钉到你的工作区——请在工作区里运行以保证相对目标可解析。替代方案：纯配置 bundle @roarpeng/graphflow-dsh（二选一，同时用会产生重复行）。

VS Code 扩展

Marketplace / Open VSX 搜索 "GraphFlow"（roarpeng.graphflow）——预构建启动器：安装 / 挖掘 git / 查看状态三个命令。手动 VSIX：VSIX-INSTALL.md。

CLI 参考

| 命令 | 用途 |
| graphflow install [--workspace] [--agents <id1,id2>] | 注册 MCP + Skill + Rules + Hooks（钩子合并，保留用户条目） |
| graphflow uninstall [--agents <id1,id2>] [--all] | 移除 GraphFlow 注册（仅自有条目）；默认检测到的 agent，--all 清理全部 |
| graphflow status [--agents <id1,id2>] [--all] | 各 agent 注册状态（[MCP ✓] [Skill ✓] [Rule -] [Hook ✓]） |
| graphflow read [targets...] [-q <query>] [--skeleton] [--dedup] | 终端外科读取 |
| graphflow edit <file> [--symbol <sym>] [--new ] [--rename <name>] | 外科编辑 / 重命名 |
| graphflow exec [cmd] [--run] [--root <dir>] | affected-tests 路由或任意命令脱水执行（--run 才执行） |
| graphflow macro <list\|run\|save\|mine\|mine-git> [id] [args...] | 宏与 git 共变挖掘 |
| graphflow task <list\|show\|record\|run\|log\|harvest> | 本地任务反射：记录、提升重复指令、离线回放 |
| graphflow reflect "<instruction>" [args...] | 本地运行已记录/近似的任务指令（未知返回 MISS） |
| graphflow hook [--protocol generic\|cursor\|gemini] | 宿主钩子拦截入口（内部） |
| graphflow graph / graphflow brief | 知识图谱 HTML 导出 / 跨 agent 交接简报 |
| graphflow doctor parsers [--strict] / graphflow parsers | tree-sitter 引擎诊断（--strict 无真 AST 时非零退出） |
| graphflow version \| help | 版本 / 用法 |

环境变量与调优

| 变量 | 默认 | 作用 |
| GRAPHFLOW_EXEC_TIMEOUT_MS | 600000 | 单条 gf_exec 命令的墙钟预算。被预算截断时返回 TIMEOUT（exit 124）并附最后输出与 handle，不会伪装成普通 FAIL。 |
| GRAPHFLOW_MAX_FILES | 20000 | 工作区扫描上限。旧版硬编码 5000，会静默截断更大的仓库。 |
| GRAPHFLOW_SEMANTIC_CACHE | 开 | 持久化 L0 语义索引（semantic-index.json 及其 semantic-index-delta.json 覆盖层）。=0 关闭。 |
| GRAPHFLOW_SEMANTIC_FRESH_MS | 50 | 语义索引的新鲜度复检窗口；0 表示每次查询都复检。 |
| GRAPHFLOW_NAME_INDEX | 开 | 逐文件标识符集合，用于在不读源码的情况下预过滤爆炸半径候选。=0 回退为原文扫描。 |
| GRAPHFLOW_AST_CACHE | 开 | .graphflow/ast-cache/ 下的 AST 分片持久化。 |
| GRAPHFLOW_GRAPH_DEBUG | 关 | 打印知识图谱构建的分阶段耗时。 |

在 9 902 文件的合成工作区实测：单符号读取（含爆炸半径）0.62–0.69 s，知识图谱无改动重建 0.17–0.28 s、改 1 个文件 约 1.7 s、全冷建 约 30 s。

开发

npm install && npm test # 40 个测试文件（含 MCP stdio e2e）
npm run build # tsc → dist/
npm run bench # 本地基准 → benchmarks/latest.md
npm run verify:parsers # 真 AST vs 结构化矩阵
npm run preflight # 发布前静态检查

文档

- Prompt Reflex —— 宿主矩阵与配置
- VSIX 安装