codegraph 让编码 Agent 真正用上代码知识图谱:Read 平价文件视图与 MCP 启动握手解耦的设计复盘

本文基于 codegraph 仓库的设计文档 agent-codegraph-adoption.md 展开,讲清两个真实工程问题:编码 Agent 在实现代码时为什么"绕开" codegraph 工具而反复使用 Read/grep,以及 MCP 服务在会话启动瞬间处于 pending 状态导致 Agent 全程没有 codegraph 可用。读完你可以掌握:一次"工具重定向 hook"被 A/B 实验否决的完整决策过程、codegraph_node 如何做到与 Read 工具逐字节平价的文件读取模式(file-view)及其源码实现,以及 MCP 本地握手代理如何用"静态工具列表即时应答 + 后台解析 daemon"消掉启动竞态。

两个问题:Agent 不用 codegraph 的两种失败模式

设计文档把问题收敛为两个(P1 与 P2),这也是整篇设计笔记的骨架:

• P1 — 实现阶段的工具替代问题:即使 codegraph 已连接、指令已重写,Agent 在写代码过程中仍会条件反射地 Read/grep,而不去查已经建好的索引。
• P2 — 启动竞态问题:serve --mcp 在 Agent 第一轮对话触发时还没就绪(宿主把 MCP 服务标记为 status:"pending"、工具数为 0),于是 Agent 从一开始就没有 codegraph 可用,只能 Read/grep,且之后也不会回头使用。

文档明确强调,所有方案必须服从 CLAUDE.md 中"Retrieval performance & dynamic-dispatch coverage"一节确立的教条(doctine),其中有四条约束在笔记中被反复引用,值得原样继承:

1. 适配工具去迁就 Agent,而不是靠文案。改工具描述或 server-instructions.ts 是"低显著性(low-salience)"改动,历史上曾让 wall-clock 倒退;光靠措辞无法可靠改变工具选择。
2. 新工具的表现劣于扩展现有工具。Agent 连 trace 都低选择率,codegraph_context 因此被移除。
3. 历史上真正起效的杠杆只有两个:覆盖度(coverage)——更多执行流被静态连通,explore 就能直接呈现;充分性(sufficiency)——输出完整到 Agent 不再需要去读文件。
4. 优化目标是 wall-clock + 工具调用次数 + Read=0,而不是 token 成本(token 成本降低只是副产品)。

P1:为什么 Agent 在实现阶段不用 codegraph

症状与第一轮尝试:重写指令确实动了行为,但没动到点子上

设计文档记录了 PR #733(7175dc4)的改动:把面向 Agent 的引导文案(src/mcp/server-instructions.ts 与 src/mcp/tools.ts 中 codegraph_node/codegraph_explore 的描述)从"回答问题"扩展到"实现代码",并给 codegraph_node 新增了 file-view 模式——只传 file 不传 symbol 时,返回该文件的符号地图、依赖方(blast radius)与源码。

随后的 A/B 对比(新旧构建均连接 codegraph,同一实现任务)结果很干净:

组	codegraph 调用	Read 次数
baseline(旧构建)	0 次	8 次(Agent 完全无视可用的 codegraph)
新构建	2 次 codegraph_explore	5 次

结论:文案重构确实改变了工具选择(n=1/arm),但 Agent 只用了 codegraph_explore,从未使用 file-view,而且仍然 Read 了 5 次。这说明"低显著性之墙"是真实存在的——描述改了,行为没有完全跟上来。

同期还修了评估框架本身(#735):嵌套 attach 本质是启动延迟问题而非硬阻塞,scripts/agent-eval/ab-new-vs-baseline.sh 现在会预热 daemon 并跳过 re-exec,评估时应跑非嵌套模式以获得最干净的数字。

候选方案排序:按预期杠杆从高到低

文档给出了四个按杠杆排序的候选方案,全部保留如下,因为它们各自代表一类通用思路:

1. PreToolUse(Read/Grep) hook 重定向到 codegraph —— 当时被判定为"最高杠杆;唯一真正能改变行为的通道"。Claude Code 的 hooks 可以拦截工具调用并注入上下文或直接 block,这与描述文案不同,不是低显著性的。评估框架里已有现成的强制 Read=0 hook(scripts/agent-eval/block-read-hook.sh + scripts/agent-eval/hook-settings.json)。设计是做一个推荐(opt-in)hook:当 Agent 对某个已索引路径发起 Read(或 Grep)时,注入提示"该文件已索引——codegraph_node {file} 能一次拿到源码 + 影响面,请把它当作已 Read";软提示而非硬 block,避免在 codegraph 不索引的配置/文档类文件上惹恼用户。安装器(src/installer/targets/claude.ts)可以像 auto-allow 权限那样提供这个 hook。开放问题:hook 内部如何判断路径是否已索引、如何避免对非索引文件产生噪音、各语言的误报率。
2. 充分性:让 file-view 成为显而易见的 Read 替代品,让 Agent 主动想用。A/B 显示 Agent 从不给 codegraph_node 传 file,要调查的是:file-view 的价值(符号 + 依赖方 + 正文)对 Agent 的下一步动作(Edit)是否真的优于 Read?如果正文不足以让人放心 Edit,Agent 还是会去 Read。另一个方向是修上游充分性:让先前的 explore/node 输出已经给足所需内容,而不是事后拦截 Read。
3. 覆盖度——可持续的杠杆。每一条被静态连通的执行流,都是 Agent 不再需要 Read 来重建的一条流。持续补齐动态分发缺口(src/resolution/)。这不是"阻止 Read",而是"根本不需要 Read"。
4. 命名/可用性实验(低置信度、低成本)。file-view 埋在 codegraph_node 里,一个专门的、名字显眼的入口也许会被选得更多——但按"新工具劣于扩展现有工具"的教条,大概率会输。如果试,必须 A/B。

终局:被否决的 hook 与被采纳的 Read 平价

文档的状态更新(2026-06-08,标记 RESOLVED)是这篇设计笔记最有价值的部分:最终解法不是 hook,而是"Read 平价(Read-parity)"——让 codegraph_node 读文件与 Read 工具完全一样,只是更快,Agent 自然会顺手用掉它,无需任何强制。负责人的一句话定调:"codegraph 应该能像 Read 工具一样去 Read……把它做到和 Read 一样好。Read 又慢又老,查索引是快的。"

hook 方案为什么被否决,A/B 数据(每臂 2 次,devpit 任务"添加 dp ping 并构建",两臂均连接 codegraph):

臂	结果
nohook	0 次 codegraph 调用,1 次 Read,5–7 次工具调用,6–8 轮,55–77 秒(复现了 P1,但"读一次就改"在这个任务上本身就是高效的)
hook(deny-redirect)	0 次成功 Read + 1 次 file-view 调用(平价机制本身工作、改动能编译),但 8–9 次工具调用,9–10 轮,200–239 秒,且 Agent 在对抗 deny:用 ToolSearch 找工具、条件反射地再 Read(被拒)、最后用 Bash python3 绕开拦截读文件

结论:一刀切的 Read 禁止在简单编辑任务上让目标指标全面倒退(约 2 倍工具调用、更多轮次),且 Agent 会绕道。强制是错的杠杆,把工具做到真正优于 Read 才是对的杠杆。hook 只作为评估工件保留在 scripts/agent-eval/redirect-read-hook.sh 与 scripts/agent-eval/ab-hook.sh。该 hook 脚本本身写得值得注意:它只对源码扩展名做 deny-redirect,配置/文档/lockfile 放行;对被重定向但实际未索引的文件(比如刚创建的文件),file-view 会回答"No indexed file matches … Read it directly",实现自纠正、不会死锁。文档也留了口子:如果将来重访路由方案,不做一刀切 hook,要么窄触发(仅大文件 / 连续 N 次 Read 之后)并在 Read 密集的多文件任务上做干净 A/B,要么继续走覆盖度 + 充分性。

源码级实现:handleFileView 的 Read 平价契约

"Read 平价"不是口号,src/mcp/tools.ts 中 handleFileView(约 L6125–L6249)的实现逐条兑现了文档承诺,这里给出可核验的源码事实:

入口判定(handleNode,约 L6007–L6014):file 存在且无 symbol 时进入文件读取模式——codegraph_node 由此具有双模式:文件读取模式与符号查询模式。

路径解析:支持完整路径或 basename,先精确匹配(小写归一),再后缀匹配、再子串匹配;歧义时返回候选列表(最多 25 条)让调用方传更长路径;未命中时返回明确提示"codegraph 索引的是源码文件,不解析的配置/文档请直接用 Read"。

核心平价契约——返回的行内容格式与 Read 逐字节一致:<n>\t<line>,行号不做左填充,符号之间的注释和顶层代码行(Read 有、旧的重建式输出会丢)全部保留,末尾空行也计入行号,保证行号对齐。唯一的增值是一行 blast-radius 头部:

**src/a.ts** — 120 lines, 4 symbols · used by 1 file: src/b.ts
1	import { x } from './a';
2	
3	export function f() { ... }

窗口语义与 Read 完全相同:offset/limit 为 1-based 起始行号与最大行数,默认全文件但上限 2000 行(与 Read 一致),另有一条 38000 字符的预算(CHAR_BUDGET,与 explore 已被验证安全的响应上限对齐)。大文件诚实分页,输出 (lines 1000–1002 of 2003 — pass offset/limit…) 这样的显式窗口说明,而不是旧版 15k truncateOutput 的静默截断;offset 越过文件末尾会明确报告"past the end"而非崩溃。

默认即内容:不再需要 includeCode: true 才拿到正文;symbolsOnly: true 则返回便宜的结构化符号地图(符号名、kind、签名、行号,上限 200 条)。

安全性两条底线都写进了实现注释:

• yaml/properties 等配置/数据文件只按 key 摘要、绝不原样倾倒(问题 #383,值可能是密钥);
• 读盘走 validatePathWithinRoot 安全收口,拦截 ../ 穿越与符号链接逃逸(问题 #527)。

测试证据:tests/node-file-view.test.ts 共 9 个用例,覆盖了上述每一条契约,其中两个断言值得单独点名:

// 严格格式平价:窗口第一行精确为 "1000<TAB>  const v998 = 998;"
expect(out).toMatch(/^1000\t {2}const v998 = 998;$/m);
// 行 1 不做空格填充:"1<TAB>import …"
expect(out).toMatch(/^1\timport \{ helper \} from '\.\/a';$/m);

其余用例包括:注释与符号间隙完整保留、输出无代码围栏(与 Read 一致)、blast-radius 头部正确、越界 offset 不崩溃、2000 行大文件默认分页且无"(output truncated)"、application.properties 中的 SUPERSECRET123 绝不出现在输出里、symbolsOnly 不含函数体、原有符号查询模式无回归。工具描述与 server-instructions.ts 也同步改成了"用 codegraph_node 代替 Read 读源码文件——同样的字节,更快"。

一个值得注意的配套设计:从 src/mcp/tools.ts 的结构看,默认只对 Agent 暴露 codegraph_explore 一个工具(DEFAULT_MCP_TOOLS),node/search/callers 等保留完整 handler 但不列入默认清单——"存在本身就会诱导误选"。CODEGRAPH_MCP_TOOLS=explore,node,… 环境变量可重新开启任意工具。这正体现了教条第 2 条的落地:工具暴露面本身就是行为干预的一部分。

P2:启动即 pending——Agent 全程没有 codegraph

症状与根因

serve --mcp 在工具可用之前要做两件事:一次 --liftoff-only re-exec(为设置 node 内存标志)和一个 detached daemon 的生成/绑定。宿主会在 MCP 启动窗口内检查服务状态,负载下这个窗口会被超掉:嵌套评估里启动约 2–3 秒,而 Agent 的第一轮对话已经开火——Agent 于是从第一轮就开始 Read/grep,且此后也不会再回头用 codegraph。真实用户遇到的是更温和的版本:会话的第一次查询可能没有 codegraph。

文档给出的根因定位与两条已验证的缓解路径:设 CODEGRAPH_WASM_RELAUNCHED=1 可跳过 re-exec;预热 daemon 可消掉绑定延迟(两者都在 ab-new-vs-baseline.sh 中验证过)。但真实用户无法预热。

四个候选方案(按排序原文继承)

1. CODEGRAPH 侧——把静态工具列表即时暴露,与 daemon 解耦。"最大的可交付收益,惠及所有用户。" 假设:宿主把 codegraph 标记为 pending 是因为 tools/list(工具暴露)在等 daemon 连接。本地握手应答 initialize 本身很快(约 107ms,见 src/mcp/proxy.ts 的 runLocalHandshakeProxy,getStaticTools 就在那里被引用)。要验证:serve --mcp 是本地即时用 getStaticTools 应答 tools/list,还是把它转发给仍在连接中的 daemon?若是后者,就解耦:客户端一问就立刻广播静态工具、标记 connected,daemon 在后台解析、只服务实际的工具调用。验证方法:printf '<initialize>\n<initialized>\n<tools/list>\n' | node dist/bin/codegraph.js serve --mcp --path <repo> 计时 daemon 模式与进程内模式的 tools/list 响应(进程内约 165ms,daemon 模式是嫌疑对象)。若落地,pending 问题基本消失且不需要宿主做任何改动。
2. CODEGRAPH 侧——加速或跳过 MCP serve 路径上的 re-exec。re-exec 的存在只为一个 V8 内存标志(src/extraction/wasm-runtime-flags.ts,守卫变量 RELAUNCH_GUARD_ENV = CODEGRAPH_WASM_RELAUNCHED)。对普通仓库的 MCP 服务,该标志可能并不必要,或可以不靠整进程 re-exec 来设置。从冷路径上去掉一次进程生成,直接压缩启动窗口。
3. CODEGRAPH 侧——SessionStart hook 预热 daemon。交付一个 opt-in 的 Claude Code SessionStart hook(安装器写入),在会话开始时为该工程生成/预热 daemon,保证第一次查询前 socket 已绑定。这是方案 1 落地困难时的缓解措施。
4. 宿主侧——"pending 时等待/重试"——这是文档作者被问及的点,但它是 Claude Code(MCP 客户端)的行为,不是 codegraph 能修的。codegraph 无法让 Agent 重试。选项:(a) 作为 MCP 客户端改进向 Anthropic 提出(不要在有配置的 MCP 服务未连完前放行 Agent 第一轮,或对 pending 服务重试);(b) 指出 MCP_TIMEOUT 存在但在本场景无效,因为问题出在工具暴露时序而非连接超时。应作为诉求提出,但工程重心押在 (1)–(3) 这些自己可控的部分。

当时的建议:主攻方案 1(解耦 tools/list 与 daemon),这是让 codegraph 对所有人"即时 connected"的修复;并行交付方案 3(SessionStart 预热 hook)作为廉价缓解;把宿主侧诉求提了但别依赖它。

源码现状核验:tools/list 已本地即时应答

从当前仓库的 src/mcp/proxy.ts 看,方案 1 的核心改动已经落地:runLocalHandshakeProxy 的函数注释直接写着"Answers initialize + tools/list from STATIC constants the instant the client asks —— tools register in ~process-startup time instead of waiting ~600ms for the daemon to spawn+bind"。源码行为与注释一致:

• 收到 initialize:立即用 PROTOCOL_VERSION/SERVER_INFO/initializeInstructions(SERVER_INSTRUCTIONS) 本地应答,同时把该消息转发给 daemon "预热"(daemon 的回复会被抑制,客户端只拿到本地那份);
• 收到 tools/list:直接 writeClient({ …, result: { tools: getStaticTools() } }),不经过 daemon;
• resources/list、prompts/list 等探测也全部本地应答空列表,避免落到 daemon 上变成未处理方法;
• 工具调用(tools/call)则转发给共享 daemon(daemon 在后台连接),daemon 连接前的消息进 pending 缓冲,daemon 就绪后冲刷;若 daemon 始终起不来(版本不匹配/生成失败),惰性创建的进程内引擎兜底服务调用——注释明确这是为了不丢失旧的直连回退鲁棒性;
• 还有两个配套防御:已转发未应答的请求按 JSON-RPC id 记账,daemon 中途死亡(宿主 SIGTERM)时改由进程内引擎重新应答,宿主永远不会挂死;stdin 静默超时(CODEGRAPH_STARTUP_HANDSHAKE_TIMEOUT_MS 可调,0 关闭)兜底"被遗弃的启动"。

getStaticTools 本身在 src/mcp/tools.ts 中实现:未设 CODEGRAPH_MCP_TOOLS 时返回默认集合(当前仅 explore),设置了则按白名单过滤。这也意味着"即时应答"返回的工具清单与 daemon 就绪后一致,宿主不会看到工具集跳变。

如何验证这类改动(文档的验证方法论)

文档末尾的验证方法同样值得作为可复用清单继承:

• P1(Read 替代):bash scripts/agent-eval/ab-new-vs-baseline.sh <indexed-repo> "<implementation task>" [baseline-ref],对比 Read 与 mcp__codegraph__* 的次数;每臂至少 2 次运行(n=1 噪音大);跑非嵌套模式;任务必须是真正未实现的新功能(第一次 A/B 就浪费在一个已实现的 --quiet 上)。
• P2(启动):按上文 printf 管道计时 tools/list;统计冷启动中 init 显示 connected 且工具数 > 0 的比例;不要只信单次 pending 的 init 快照——以 Agent 是否真的调用了 codegraph 为准。scripts/agent-eval/parse-run.mjs 提供分工具类型的计数,其中 codegraph tools exposed: 0 + 0 次 codegraph 调用 = 该轮实际无 codegraph 参与。

文档"Constraints / gotchas"一节最后提醒的约束:描述/指令是低显著性的——任何行为性主张都要 A/B,不要凭措辞信心就发布;宿主 init 快照说 pending 不代表服务最终没连上,判断以实际使用为准;除非已预热,否则不要跑嵌套评估来要"干净"数字,即便如此,真实终端仍然更好。

关键文件索引

关注点	路径
Agent 引导文案(initialize 指令,单一事实来源)	src/mcp/server-instructions.ts
工具描述与 handler(handleNode/handleFileView/handleSearch/getStaticTools)	src/mcp/tools.ts
本地握手代理、PPID watchdog	src/mcp/proxy.ts
runProxyWithLocalHandshake、spawnDetachedDaemon	src/mcp/index.ts
共享 daemon	src/mcp/daemon.ts
re-exec 守卫(CODEGRAPH_WASM_RELAUNCHED、CODEGRAPH_HOST_PPID)	src/extraction/wasm-runtime-flags.ts
评估用 Read 拦截 hook / 配置	scripts/agent-eval/block-read-hook.sh、scripts/agent-eval/hook-settings.json、scripts/agent-eval/redirect-read-hook.sh
新 vs baseline A/B 框架(预热已内置)	scripts/agent-eval/ab-new-vs-baseline.sh、scripts/agent-eval/run-all.sh、scripts/agent-eval/parse-run.mjs
file-view 平价测试(9 用例)	tests/node-file-view.test.ts
教条原文	CLAUDE.md "Retrieval performance & dynamic-dispatch coverage"

这篇设计笔记的方法论价值在于它完整展示了一条"行为干预"的完整证据链:文案重构的 A/B 部分生效 → 强制 hook 的 A/B 全面否决 → 转向"把工具做到优于 Read"这一根本解,并用逐字节格式平价、诚实分页、密钥安全收口和 9 个平价断言把它钉死;启动竞态一侧则用"静态工具列表即时应答 + 后台 daemon 解析 + 进程内兜底"把 pending 从根上去掉,且每一步都给出了可复跑的验证命令。对任何希望让自己的 MCP 工具被编码 Agent 真实使用(而不是躺在工具列表里)的项目,这套"先证明哪个杠杆有效、再用平价能力取代强制"的思路比任何单点技巧都更可复用。