Graft

Graft 是一个给编码 agent 用的命令行上下文层，TypeScript 写的，MIT 许可。它把仓库读两遍：一遍是确定性的 tree-sitter 解析，产出带跨文件调用与 import 边的逐符号代码图；另一遍是可选的模型层，为每个文件写摘要，再把这些摘要归并成几十个互相链接、用固定动词连边的 markdown 节点。结果落在一个被 gitignore 的目录里；每次查询先用上一次构建的指纹比对工作区——没动过时大约三毫秒——所以未提交的改动也能被如实描述。agent 有三条取用路径：init 命令写进九种宿主 agent 的围栏段落或独立 skill 文件；六个 MCP 工具由 agent 自己调用；Claude Code 另有钩子，在每次提示前注入匹配节点，在文件改完后打印它的爆炸半径。深度摘要用使用者自己的 key，结构化那张图则完全不调用模型。

谁做的仓库归 trailhq 这个组织账号所有，所以这里写的是贡献最多的人，不是所有者：512 次提交里 Shrish Dwivedi 写了 235 次、Anirudh Kumar 160 次，其后是 Dependabot 25 次、Alex Matthews 25 次、Frankie-Xu 20 次。贡献者列表里一共 36 个账号，111 条共同作者尾注里另有约十个名字，多半只出现一次。这个项目是从 NanoNets 名下的仓库长出来的——npm 包至今仍发布在 NanoNets 的 scope 下，仓库自己的开发说明也仍然让人去 clone NanoNets/context-graph-engine。

1. 01

   十三周、两个人、十四个 tag

   仓库建于 2026-07-03，第一次提交叫 Initial commit: Context Graph Engine；到 2026-09-30 已有 512 次提交——7 月 243 次、8 月 213 次、9 月 56 次，正是第一波冲刺在项目转入维护之后慢下来的形状。绝大部分由两个人写完：Shrish Dwivedi 235 次、Anirudh Kumar 160 次，后面是 Dependabot 25 次、Alex Matthews 25 次、Frankie-Xu 20 次。贡献者列表里一共 36 个账号，111 条共同作者尾注里另有约十个名字，多半只出现一次：其中 47 条署名 Claude 系列模型、20 条写 Cursor、25 条是依赖机器人。版本以 tag 的形式存在而没有 release——GitHub 上一个 release 都没有——tag 从 v0.7.1 起，经 v0.8.1、v0.8.2、v0.9.0、v0.12.1 一路到 v0.21.1，其中 v0.10、v0.11、v0.17 没有留下记录，另有 39,765 字节的 CHANGELOG.md 承担发布说明的角色。升级路径刻意安静：CLI 每天查一次 npm，有新版本就提示，装完之后的下一个会话会自己把仓库里的接线刷新一遍。这个项目也在自己身上用自己，而且看得见——每个 pull request 下面都有机器人贴出的爆炸半径图和一张托管页面，blast 工作流、它的缓存工作流、15 KB 的 Pages 发布器和一个 9 KB 的复合 action 就是为此存在的。周围是 9,431 个星、865 个 fork、188 个未关的 issue。

2. 02

   两层索引、两级缓存、一次三毫秒的比对

   理解分两层做，而这两层的成本毫无关系。第一层是确定性的 tree-sitter：每个函数、每个类、每条调用边，不用模型也不用 key，写进 graft/.graph/wiring.json，外加一份镜像源码树的逐文件卡片。可选的深度层为每个符号补一行摘要和一段 crux 摘录，再把逐文件摘要归并成用固定动词连边的概念节点。所有环节——包括解析本身——都按内容哈希缓存，所以 README 给出它自己这个仓库的数字（124 个文件）是：冷启 0.74 秒，改一个文件后 0.18 秒，什么都没改也是 0.18 秒；--no-reuse 用来强制走冷路径。这份便宜买下的正是检索的设计：与其用守护进程焐着一个索引，不如让每次查询先拿上一次构建的指纹比对工作区——约三毫秒、结构化、不调用模型——只有字节真的变了才重建，于是 ask、grep、callers、skeleton、map 对未提交和未暂存的改动一视同仁，也于是有了 GRAFT_REFRESH=hash，给不肯相信体积与修改时间的人用。graft check 是刻意的例外：它从不刷新，发现漂移就退出 1，因为它就是那份漂移报告。注入走的是同一批产物，共三扇门——init 命令按九种宿主 agent 写下的围栏段落或独立 skill 文件；六个由 agent 自己调用的 MCP 工具；以及 Claude Code 的钩子，在每次提示时探一次，在文件改完后打印爆炸半径。

3. 03

   速度与省钱的说法，以及每个数字怎么测的

   最上面那句话是项目自己的：最高便宜 4 倍、快 3 倍，而旁边就写着方法，来自三组实验。第一组让同一个 Claude Sonnet 5 agent 跑三种变体、用同一套文件工具——冷启、把 graft ask --source 的结果先推上去、以及只给 MCP 工具的拉取变体——由 Opus 4.8 当裁判、带必含关键词的下限，成本按缓存计价（读约 0.1×、写 1.25×），共 162 次运行、两个仓库、每个三次。它报出的每任务成本从 $0.0429 降到 $0.0292（+32%），token 从 8,070 降到 4,650（+42%），工具调用从 4.2 降到 2.3（+46%），延迟从 39.8 秒降到 15.8 秒（+60%），正确率两边一样是 93%；而什么都不注入的拉取变体到了 98%。第二组是 SWE-bench Verified：50 个实例、两边同一模型、官方 4.1.0 评分器——50 个里解决 27 个对 33 个，142.0M token 对 109.4M，$52.34 对 $42.43，1,370 次工具调用对 1,031 次，13,094 秒墙钟对 8,922 秒。第三组把 PocketBase 五个已合并的 pull request 从各自基线提交重做一遍，共 15 个任务：$13.91 降到 $11.02，2,044 秒降到 1,762 秒，五个全部复现。README 顶上那张表把前两组混在了一起——它那一行正确率 54% 到 66% 来自 SWE-bench，而受控对比里正确率没有变化。这些数字没有任何一个是第三方复现过的。

4. 04

   用户测回来的东西

   最近三十个 issue 里有几个不是 bug 报告而是反向测量，也是整份历史里最锋利的部分。一位用户在 291 个文件的 Swift 与 Kotlin 应用上拿 graft ask --source 和自己「一次 ripgrep 加一次定点阅读」的基线对比：构建 3.7 秒，得到 3,217 个节点和 9,743 条边，三个问题里正确答案都在结果包里，但排第一的命中只有一个是对的，而且包的体积是 grep 路径的 2.5 到 4 倍——一条带着数字的排序投诉。另一位把 331 次钩子输出和触发它们的提示一一配对，发现注入的那些「没有强匹配」里多数来自机器生成的后台任务通知，而不是用户写的提示。第三位记录的是一个装着若干仓库的普通文件夹（从未被索引）：每一轮都把它标脏，每一次 Stop 都触发一次撞上 120 秒超时的构建——持续占着 0.8 个核和 2.5 GB 内存，统计文件里的 syncedAt 是 null、节点数为零。这一条还带着材料里最坦白的一句话：被旧版本污染过的文件夹会被一直认作已接入，所以新的门槛照样放它过去，除非手动删掉那个残留缓存。

5. 05

   会覆盖用户手改内容的生成文件

   最响的两个 bug 共用一个成因：graft 会往并非完全属于它的文件里写。第一个里，会话启动时的接线刷新用一个裸 JSON.parse 读 .claude/settings.json，解析失败就落进空对象，然后再用截断写回合并结果；于是任何留着合并冲突标记的文件——或在另一个写入者持有时被读到的文件——回来时用户的 permissions.deny、permissions.allow、outputStyle 和钩子全没了，而且改动足以被提交。修它的那个 pull request 直接删掉了这条兜底，理由是：解析失败的 settings 文件决不能被覆盖。第二个是一位用户一口气开了七个 issue，全是关于生成的指令段落：重新生成会无声地回滚 marker 围栏里手写的更正；删掉生成的 ignore 文件会在同一个会话里被自动恢复；graft build 把接线文件追加进 .gitignore，而它的输出只提到缓存目录；模板指向 graft/INDEX.md，构建写出的却是 graft/index.md——在任何大小写敏感的文件系统上都是死路径；而那份 ignore 文件用一个没锚定的模式又把卡片树放了回来。节点文件恰恰是按这种压力设计的：用户写在生成块下面的任何内容都能活过重新生成。

6. 06

   适配器、一个被关掉的 pull request，和先查指标再上功能

   这些 pull request 里有很大一部分是同一个题材：让模型网关听话。一条报告说，OpenAI 兼容网关会用 HTTP 200 返回一个错误对象、里面没有 choices，这让响应解析器抛出 TypeError；另一些模型根本吃不下强制的 tool_choice，于是文件和概念批次都是空的——用 OpenRouter 上的一个隐身模型复现过。紧接着的一条专门处理推理模型在长度上限处被截断的结构化调用：每一档重试一次，把 token 额度乘四、最多 32,768，并且不再把这种停止原因当成「该端点忽略强制 tool_choice」的证据。再一条修的是 crux 环节：有些模型把整行目标原样回填成标识符，于是所有摘要都被悄悄丢掉。最新的一条把概念综合批次并行化，用一个新的 --synth-concurrency 开关、默认 4；它特地为第二个旋钮辩解，因为第一阶段是几百次小的逐文件调用，第二阶段只是几次 48,000 字符的请求——图与串行跑出来的结果逐字节相同。这些周围是维护者的习惯：一个把 SQLite 统计库、五个宿主归因适配器和抬高 Node 版本下限捆在一起的 52 文件 pull request 被直接关掉，要求先开 issue，再拆成保住 Node 20 下限的小改动发过来；给托管的 Trail 流程加的遥测事件只带封闭集合和分桶，并被一份契约测试钉住；而在加「有多少建议在等你审」这个计数之前，作者先查了数据库，七天内这样的事件是零、唯一的动静来自一个内部测试者，然后照样发了。