graft

用途

graft 用于在代码库中定位、理解和追踪代码，帮助完成理解代码如何运行、查找代码位置、追踪符号调用关系等任务。它把仓库保存为一张关系图，由小型 Markdown 节点组成，每个节点用散文解释一部分代码，并标注其覆盖的确切 file:line 范围，另有“谁调用谁”的连通图。查询一个节点的成本约几百 token，而通过阅读源码重建同样的理解需要数千 token，且容易遗漏边关系。

主要能力

graft 提供六个命令，均为 $0、无需 API 密钥、不到一秒返回，多数任务只需一次调用：

1. graft ask "<question>" --source：在图上进行排序检索，自动在散文节点和连通图之间路由，返回带确切 file:line 的头部命中。--source 内联每个命中的代码，即每个定义的 ≤8 行关键片段，使结果本身就是所需代码，无需再读文件。--full 仅在关键片段太小不足以行动时添加。--in <path> 在排序前缩小到子树，-n N 限制结果数（默认 8）。适用于概念性或位置性问题，如“auth 如何工作”“rate-limiting 在哪里处理”。

2. graft grep "<pattern>"：对所有已索引文件进行正则（或 --fixed 用于字面量）穷尽查找，命中按所在符号分组并按耦合度排序，同时报告无法读取的文件。适用于需要每一次出现的情况，如所有调用点、常量的所有使用、所有 provider。搜索短符号名或字面量，不要搜索猜测的完整签名。-i 不区分大小写，--in <path> 限定子树。原始 grep -rn 仅用于 graft 确实不索引的文件（文档、配置、全新文件）。

3. graft skeleton <file>：以仅签名视图查看单个文件（每个函数/方法/类型及其范围），约 200 token，比读取文件便宜约 10 倍。适用于编辑或接入某文件前了解“这个文件里有什么/我可以调用什么”。

4. graft callers <symbol>：预计算的调用/引用边，而非文本搜索。符号可以是裸名（Foo）、限定名（Class.method）或包限定名（pkg.Fn）。默认 --direction in 显示谁调用/引用此符号，在重命名、删除或更改签名前运行。--direction out 显示该符号自身调用/依赖什么。--depth N 传递 N 跳以获得完整影响范围，--depth 2 通常是“改动这个会破坏什么”。--depth all 显示整个连通闭包，在重构、重命名或任何多文件更改前使用。

5. graft map：对不熟悉的仓库或区域进行定向浏览：目录簇、每目录枢纽和全局热点，直接来自连通图。适用于冷启动进入仓库或需要“架构”说明时。--max-dirs N 可扩大范围。

6. 生命周期：graft build / graft check。上述每个工具在回答前会自动刷新图，因此返回结果始终描述代码当前状态，包括刚做出但未提交的编辑。无需在编辑后运行 build。但若直接 grep graft/ 下的 Markdown，这些卡片是投影，在回合结束时重建而非每次查询时重建，因此编辑后可能滞后。build 用于 LLM 层（--deep 添加概念图，除非被要求否则跳过）；check 在 graft/ 过期时失败，用于 CI。

使用方式

根据任务选择最合适的命令，运行一次，然后基于答案行动，不要为了更多结果而串联工具。大多数任务只需一次调用。

常见场景：入门/“解释这个代码库”使用 graft map，然后阅读它命名的枢纽卡片；理解流程（“X 如何工作”）使用 graft ask "<flow>" --source；找到更改所属位置使用 graft ask "where is <behavior>" --source；编辑已能命名的符号使用 graft grep "<symbol>"，在 file:line 处编辑；重命名/删除/更改签名先运行 graft callers <sym> --depth 2；重构/多文件更改（编辑前）使用 graft callers <sym> --depth all；“这依赖什么？”使用 graft callers <sym> --direction out；查找某个模式的所有出现使用 graft grep "<literal>"；“这个文件的 API 是什么？”使用 graft skeleton <file>；调试区域 X 的失败使用 graft ask "<symptom>" --source，然后对可疑对象运行 callers；合并前判断 diff 风险使用 graft callers <changed sym> --depth 2；在 monorepo 的某个仓库内工作，在 ask/grep/callers 后添加 --in <scope>/。

在多仓库工作区中，graft 会公平排序，最大的仓库不会淹没其余部分，每个命中带有 [scope/] 标签标明其子项目；当已知工作位置时，用 graft ask "<task>" --in <scope>/ 缩小范围。

节点的 covers: 列表已给出每个符号的确切 file:line，可直接引用。范围由源码生成且具有权威性，不要重新打开或 grep 文件来“复核”。当任务已命名要更改的文件或符号时，直接前往：用 graft grep "<symbol>" 获取确切 file:line，然后编辑。把 graft ask 留给尚不知道代码位置时。

信任答案并行动。只有当第一个工具确实不足时才使用第二个工具：命中微弱、范围被截断或需要穷尽时。

如果 graft 命名的路径不在磁盘上，说明其索引领先于检出（分支切换或未拉取的移动）。不要读取缺失文件，用 graft grep 查找符号现在所在位置，或运行 graft build 刷新。

适用场景与限制

每个检索工具的输出开头有一行 [graft] tokens saved ≈ N，是相对于整文件读取所节省的估计 token 数。使用任何 graft 工具后，应在回复结尾用一行汇总该回合所有 graft 调用的数字。没有该行的调用（小文件，指针成本与源码相当）没有节省，跳过。已产生计费的回合，每行还会按会话实际输入 token 费率说明该调用的美元价值；没有美元数字时只报告 token，不要自行定价。

不要将 graft 命令通过 head、tail 或 sed -n 管道。每个工具已有上限并说明丢弃了什么；裁剪会损失请求的命中，并静默丢弃状态栏解析的节省行。

当 graft 不够时：范围被截断（“+N more lines”）时打开该确切范围的文件；节点缺少细节时先问更具体的问题，然后才读取确切 file:line 的源码，绝不读整个文件来重建 graft 给出的理解。也可以直接 grep/ls/cat graft/ 目录（纯 Markdown；graft/INDEX.md 索引节点），但上述工具更快且在需要时穷尽，应优先使用。

当 graft MCP 服务器连接时，这些命令也作为工具暴露：graft_find_code、graft_find_all、graft_file_api、graft_trace_calls（带 direction/depth）、graft_repo_map、graft_check_freshness。使用可用的界面，指导相同。