Trail-code

Trail-code 快速入门：先给编码 Agent 一张代码图

这是什么？适合谁？

Trail-code 是 Trail 团队做的命令行工具，走的是「先让 Agent 知道你这份代码长什么样」这条路。它做两件事： 把仓库解析成一张代码图（每个文件、每个函数、谁调用谁），以及把你和团队在会话里得出的经验存成 Markdown 文件。

这个项目此前叫 Graft。官方仓库的 README 写明「Graft is now Trail-code」， 原来的 graft 命令继续可用，旧仓库地址会跳到新仓库；产品页仍是 trailhq.com/graft。 所以你在网上看到的 Graft 教程，多数仍然适用，只是名字换了。

适合谁：已经在用 Claude Code、Codex、Cursor 这类编码 Agent，但经常遇到「它又打开了错的文件」「同一个约定每次都要重讲」 「队友上周否掉的做法这次又被捡回来」的开发者和团队。它的价值随仓库规模与协作人数上升，单人小脚本收益有限。

不适合谁：只在网页里让模型写零散代码片段、没有本地仓库的人；不愿意让 Agent 读取本地历史会话的人； 希望「装上就自动变强」而不打算付初始化与审阅成本的人。

需要说明的边界：README 里给出的效率数字（例如同样的 162 次运行里少 46% 工具调用、少 60% 时间， SWE-bench Verified 50 个真实 issue 里解出 33 个而基线 27 个）都是项目方自己的基准， 本站没有独立复现，也没有做代码级安全审计。

核验日期：2026-10-31。功能依据官方产品页、仓库 README 与遥测说明。

准备工作

• 一个用 Git 管理的代码仓库；没有 Git 的目录不在这套流程的取证范围内。
• Node.js 22.3 或更新（README 同时说明 20.16 也可用）。先 node -v 确认，不要靠猜。
• 一个你常用的编码 Agent（Claude Code / Codex / Cursor / Kiro / Gemini 等）。
• 若你要让 trail init 顺便读仓库的 PR 评审意见，需要本机装好并登录 gh（GitHub CLI）；不装也能用，只是少了这部分种子经验。
• 时间预算：首次 trail init 通常几分钟级；官方说读取你过去的 Claude Code 会话「大约一分钟」， 但这一步会占用你自己的 Claude 额度，仓库越大、历史越多，耗时越长。
• 一颗能接受「提交一批新文件」的心：它会往仓库里写 .trail/、.mcp.json、以及 Claude Code 的配置与钩子。

安装前的通用检查：确认当前目录是仓库根（git rev-parse --show-toplevel 一行就能看）， 不要在父目录或桌面这种非仓库位置初始化，否则代码图的范围会变成一堆无关文件。

安装与初始化

第一步：装 CLI

npm install -g @trailhq/trail-code

如果报 EACCES，说明 Node 的全局目录需要提权。README 给的做法不是加 sudo（那样以后每次升级都要提权）， 而是把全局前缀改到用户目录：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# 把 ~/.npm-global/bin 加进 PATH，然后开一个新终端
npm install -g @trailhq/trail-code

第二步：在仓库里初始化

cd /path/to/your-repo
trail init

trail init 会做这几件事：问你要接哪些编码 Agent；用 tree-sitter 解析仓库生成代码图；创建 .trail/ 存团队经验； 给 Claude Code 加状态栏与钩子；并一次性读取你在这个仓库里过去的 Claude Code 会话， 把「你在两个以上会话里重复讲过的事」沉淀成经验；如果 gh 可用，还会读该仓库最近 50 个已合并 PR 的评审意见。

想先看它准备写什么，再决定要不要动手：

trail init --dry-run          # 只显示将要写入的 Agent 接线
trail init --agents claude    # 只接 Claude Code 一个

第三步：把配置提交进仓库

git add .claude .mcp.json .trail .gitignore .ignore
git commit -m "set up Trail-code"

注意不要提交 graft/：代码图是本地缓存，性质和 node_modules 一样，README 明确说它被加进 .gitignore。 换句话说，队友拿到的是「经验」（.trail/），代码图要各自在本机构建。

第四步：确认它真的在工作

trail status

它会把代码图、经验数量和节省的 token 显示在一屏里。看到这一屏才算初始化完成； 只看到「安装成功」不足以说明图建好了、Agent 真的会去读它。

第一个可完成的任务

别一上来就改核心模块。选一个边界清楚的小改动，例如给某个函数加参数校验、修一个已有测试暴露的边界问题。

1. 让 Agent 做这个改动，观察它的第一步是不是直接落到正确的文件与函数上，而不是先 grep 半天。
2. 改完后要求它说明「这个函数被谁调用、改动会影响哪些地方」——它应该能从图里答出来，而不是重新搜一遍。
3. 需要时手动看一眼影响面：

trail ask "这个函数被谁调用"

4. 提交前跑一次检查：

trail check

成功判据有三条：trail status 有代码图与经验的计数；Agent 在第一次检索时就命中目标文件； trail check 能对你这次改动给出「与既有经验冲突/不冲突」的结论。三条都满足，才算这套流程真的接上了。

初级用法

日常只有三个动作：让它读图、让它存经验、提交前检查。

• 读图：Agent 通过 MCP 工具（trail_find_code、trail_file_api、trail_trace_calls、trail_find_all、trail_repo_map 等） 拿文件、函数签名和调用关系。你在提示词里说明「先用 trail 定位」，命中率会更稳定。
• 存经验：当你纠正它一次（「这里用 pnpm 不用 npm」「重试次数固定 4 次」），让它写成一条经验：

trail note --title "包管理与重试约定"

正文从标准输入给，--personal 会把这条留在 ~/.trail 而不是仓库里。

• 提交前检查：trail check 会把你当前分支的改动与仓库经验、你个人经验比对， 冲突时会把「谁在什么时候决定的、为什么」一起引出来。

第一次使用建议只做「读图」这一步：先确认它在你的仓库里能正确找到文件， 再考虑把经验共享给团队——否则你会一次改动太多变量，出问题时分不清是哪一环。

高级玩法

一、把 trail check 当作 PR 前置门禁。 README 说 trail init 会给 Agent 写入「提交、推送或开 PR 之前先跑 trail check」的指令。 实践中更稳的做法是把它写进你自己的提交前脚本，让「人」和「Agent」走同一条检查， 避免 Agent 换了会话就忘掉这条约定。

二、用 trail_trace_calls 评估爆炸半径。 改一个被几十处引用的函数之前， 先问「谁依赖它」，比改完再看测试报错省事。这是代码图相对纯 grep 的主要差异： grep 给你字符串命中，图给你调用关系。

三、多仓/单体仓分层处理。 单个 .git 的 monorepo 会被自动识别成多个排名范围， 查询时各自打分再融合，不会让最大的子项目压掉小项目；Git 子模块默认被排除， 需要 trail build --follow-submodules；被克隆进仓库、没有 gitlink 的第三方目录用 trail build --follow-nested-repos。这两种选择会写进 .graft/config.json，后续构建与 MCP 自动刷新沿用同一套边界。

四、把重复出现的评审意见变成经验。 如果 gh 可用，初始化时已经读过最近 50 个已合并 PR 的评审意见； 之后每遇到一次「同样的意见第二次出现」，就用 trail note 记一条，团队的口味才真正被固化下来。

五、审计遥测。 想确认「到底会发什么」，先看：

trail telemetry debug

它打印你机器上「如果发送会发出去的内容」，比读文档更直接。

小技巧

• 在子目录里也能跑 trail ask：不带 [dir] 参数时它会向上找最近的 graft/，不用每次 cd 回根目录。
• 大仓库先 trail build --check 看图的时效性，再让 Agent 干活，避免拿旧图定位。
• --in <scope>/ 可以把查询窄化到某个子项目，monorepo 里尤其有用。
• 初始化时若不想让它读你的历史会话与 PR，先跑 --dry-run 看清范围再决定。
• 关遥测有两条路：trail telemetry disable 关掉使用统计；DO_NOT_TRACK=1 连每日版本检查一起关。
• 团队协作靠 Git 而不是服务器：git add .trail/ 并在 PR 里像审代码一样审经验文件。

常见踩坑

踩坑 1：npm install -g 报 EACCES，然后一路 sudo。 现象：装上了，但每次升级都要提权，团队成员环境各不相同。 原因：Node 全局目录默认在系统路径下。 解决：按 README 把 prefix 改到 ~/.npm-global 并加进 PATH，再重装一次，不要用 sudo 硬装。

踩坑 2：以为 graft/ 会随仓库共享。 现象：队友克隆下来后 Agent 依然找不到文件，你以为图建好了。 原因：graft/ 是本机缓存，被 .gitignore 忽略；共享的是 .trail/ 里的经验。 解决：每个队友各自在自己的机器上初始化/构建，仓库里只提交 .trail/ 等配置文件。

踩坑 3：未提交的改动不会出现在共享层。 现象：你在本地改了三个文件，队友的 Agent 完全不知道。 原因：官方说明里，未提交的编辑、以及 Git 不跟踪的文件都留在你本机；能共享的是已提交的经验。 解决：把经验随代码一起提交，或者明确接受「本地改动只对自己生效」。

踩坑 4：多人同时改 .trail/ 产生冲突，当成垃圾直接丢弃。 现象：合并时 .trail/ 冲突，有人图省事把对方条目删了。 原因：经验文件是普通 Markdown，走的是普通 Git 流程，没有自动合并语义。 解决：把 .trail/ 当代码审，冲突时保留双方条目；不确定就让两条并存，让 trail check 在后续改动里暴露矛盾。

踩坑 5：初始化默认会读你的历史会话，产生额度消耗和隐私顾虑。 现象：跑完 trail init 发现消耗了一段时间和你自己的 Claude 额度，并生成了大量经验条目。 原因：初始化要读你过去的会话与最近 50 个已合并 PR 的评审意见来「冷启动」，README 说这一步由你自己的 Claude 完成。 解决：先在干净分支上跑，看清产出再决定保留哪些；不想读就先 --dry-run，或者只接一个 Agent 试水。

踩坑 6：把 trail build --deep 当成默认步骤，意外产生模型调用。 现象：以为「不用 API key」，结果某条命令要了 key 并产生了费用。 原因：结构化代码图是确定性计算、不需要 key；只有 --deep 的书面摘要是模型生成的。 解决：默认路径只用确定性命令；要 --deep 就明确知道它在花钱。

踩坑 7：从 graft 升级后队友还在旧结构。 现象：你本机迁移好了，队友的 Agent 行为没变。 原因：仓库第一次在 Claude Code 里打开时会自动迁移，但迁移产生的改动需要提交。 解决：迁移后把变更提交推走，让队友拉到同一套结构。

踩坑 8：按官网动画以为已经有跨仓团队面板。 现象：找「团队页/工作区」找不到。 原因：产品页与 README 都把 Trail workspace 标为「即将推出」（coming soon），当前团队协同靠 Git。 解决：现阶段只用 .trail/ + trail team（最近 7 天团队经验与工作重叠），不要按未上线功能做承诺。

常见问题 FAQ

Q1：它和 CLAUDE.md、AGENTS.md 这类指令文件冲突吗？

A：官方 README 明确说 trail init 不会改动你的 CLAUDE.md，两者并存：指令文件写「你要它怎么做」， 经验写「这次具体得出什么结论」。真出现矛盾时，以你当场的要求为准，并考虑把结论沉淀成新经验。

Q2：必须用 API key 吗？

A：不需要。README 说明代码图、trail ask、经验与 trail check 都是确定性、不调用模型的； 只有 trail build --deep 生成的书面摘要需要 key。

Q3：会把我的代码上传吗？

A：默认不会。README 说代码图与检查在你本机完成、不联网；匿名使用统计只发固定标签与分桶，不发代码、路径、仓库名或经验正文， 可用 trail telemetry disable 或 DO_NOT_TRACK=1 关闭。只有你主动连接 Trail 工作区之后，被提交的经验才会同步给 Trail，而该工作区当前尚未上线。

Q4：支持哪些编码 Agent？

A：官方列出 Claude Code、Codex、Cursor、Kiro 等，并说明通用 MCP 客户端也能用。 trail init 会问你要接哪个，--agents claude 可以只接一个。其他 Agent 的实际体验以你本地接线为准。

Q5：monorepo、子模块、把别的仓库克隆进来，能处理吗？

A：能，但边界要自己定。单 .git 的 monorepo 自动分范围；Git 子模块默认排除，要 --follow-submodules； 没有 gitlink 的嵌套仓库要 --follow-nested-repos；顶层是一堆独立仓库的目录会各自建图并在父级做联邦查询。 设置在 .graft/config.json 里持久化。

Q6：团队怎么同步经验？

A：走 Git。提交 .trail/ 后每个克隆都有；队友已推送未合并分支上的经验也会以「pushed and not merged yet」形式出现。 trail team 可以在终端里看最近 7 天团队学到了什么、哪里工作重叠。

Q7：能省多少钱/多少 token？

A：项目方自述在 162 次同任务运行里成本低 32%、未缓存输入 token 少 42%、时间少 60%， SWE-bench Verified 50 个真实 issue 上从 27 个解出提升到 33 个。这些是官方基准， 本站未复现；你自己的收益取决于仓库规模、Agent 与任务类型，建议用 trail status 自己看数字。

进阶学习建议

• 先把代码图这一层吃透：trail build（接线图 + 每文件卡片）、trail build --check、 trail ask、trail map 各自的输出结构不同，读一遍 README 里这几节再动手，能少踩一半坑。
• 再学经验层的三个动作：trail note（写入）、trail check（提交前比对）、trail team（团队视角）。 这三个命令对应「记下来 → 用起来 → 看出来」的闭环，缺一环经验就会烂在文件里。
• 想评估真实收益，按官方基准的形态做小规模对照：同一批任务，一次不带图（冷启动）、 一次用 trail ask 主动查询，记录工具调用次数与未缓存输入 token，而不是凭体感判断。
• 多仓团队的进阶路线是「边界先定、再联邦」：先用 --follow-submodules / --follow-nested-repos 把该进图的目录合进来，再用 --in <scope>/ 把查询收窄，最后才考虑跨仓工作区（当前未上线）。
• 阅读顺序建议：README 的「How it works」→「What stays on your machine」→「Monorepos, submodules & multi-repo folders」， 最后再看 TELEMETRY.md 的字段清单，你就能判断它在你的合规环境下能不能用。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。 文中的效率与解决率数字均为项目方自述基准；安装、初始化、经验读写与遥测开关未在本站环境逐一验证， 正式采用前请在你自己的仓库小范围试用，并核对所用版本的 trail init --dry-run 输出。

参考链接

• Trail-code 官方产品页
• 官方仓库 trailhq/Trail-Code
• 仓库 README（快速开始、代码图、多仓与隐私边界）
• 遥测说明 TELEMETRY.md
• npm 包 @trailhq/trail-code
• 原仓库地址 trailhq/Graft（现跳转到 Trail-Code）