给编码 agent 装工具,最亏的不是模型不够好,是它每次开局都得重新认识一遍代码库。它 grep 一个词,打开一个文件,顺着 import 往下追,退回来再试,上一小时刚画出来的结构它扔了。我盯着它跑过一次,改一个函数,前十几步全在摸路,真正改代码只占最后两步。这不是它笨,是它没有记忆。
Trail-Code 想补的正是这块记忆。它分两部分,都在本机跑:一块把代码扫成符号图谱,一块存团队对代码的结论。前者回答东西在哪,后者回答为什么长这样。我装它、跑它,就是看这两块落不落地。
装出来是 0.29.0
安装就一条命令,前提是 Node 22.3 以上。我本机 Node v22.22.2,npm 10.9.7,直接装。
npm install -g @trailhq/trail-code
我跑这条,34 秒装完 28 个包。trail --version 一打,0.29.0。README 写它原来叫 graft,改名后 graft 命令还留着,旧包 @nanonets/graft 也能用。这个我查过,两条命令指向同一份代码。
init 之前先看它会写什么
我不喜欢一个工具上来就往项目里塞文件。所以先跑 trail init --dry-run,看它打算写什么。输出我留了档:仓库里写 .claude/settings.json、.trail/、AGENTS.md、.cursor/rules/trail.mdc、.windsurf/rules/trail.md,机器上还动 ~/.claude、~/.codex 这些用户级文件。加 --no-global 能把仓库外的都按住。
$ trail init --dry-run
would write in this repo:
.claude/settings.json trail SessionStart hook, shared
.trail/hook.cjs hooks shim, shared
AGENTS.md fenced trail section
.cursor/mcp.json mcpServers.trail
.windsurf/rules/trail.md trail-owned file
这段我原文贴出来。它不碰你已有的 .claude/settings.json,是 merge 不是覆盖。真正 init 的时候我用 --no-global --no-statusline --yes,只动仓库内文件。
5 个节点,6 条边
我在一个只有 2 个 Python 文件的测试仓库里跑了 trail init。输出一句话,我盯了很久:
graph built · 5 nodes, 6 edges from 2 files
5 个节点,6 条边,从 2 个文件里解析出来。tree-sitter 把 load_config、connect、run 这几个函数和它们的调用关系都建进图里。没调模型,没要 key,纯本地解析。这一步是 graft map 的核心,后面所有检索都靠这张图。
建完图我跑 trail status,它回 code map ✓ 5 nodes · in sync with the code。这个 in sync 不是空话,它每次查询前先比工作树,未提交的改动也会算进去。还有 trail blast 这个命令,我试了 1 遍,它算一个 diff 的爆炸半径,即改了这几行会牵连到哪些依赖它的地方,PR 评审前先扫一遍很值。
符号检索和 grep 差在哪
同样是找 load_config 的调用方,两条路我各跑了一遍。先 trail callers load_config:
load_config · function · src/models.py:L1-L2
calls ← run (src/main.py:L4-L6)
5: cfg = load_config("config.yaml")
它给的是谁调用这个符号,精确到 file:line。末尾还附一行 tokens saved ≈ 37 (55%),意思是这个答案比读那两个文件省 37 个 token。我跑 trail grep connect,给的是「4 hits in 3 symbols across 2 files」,按符号分组,不是按字符串位置。
这里有个判断要说透。文本检索和符号检索的分界,就在跨文件重命名。你要把 load_config 改名,grep 给你六处长得像的字符串,其中一处可能是别的类里同名的,也可能漏掉 from x import load_config。符号检索给的是语言服务器算出来的引用集,六处就是真六处,不多不漏。我拿 load_config 这个真名跑过 1 遍,跑出来正是它被引用的那几处,一处没多。
存学习时撞了个校验
learnings 是 Trail-Code 新加的一块。我试着存一条,第一遍就碰壁。我跑 trail note --title "config loader needs timeout",正文写「config loader 应该设超时」,它拒了。报错原文是:
not saved yet:
It names no file or function in this repo.
它要求 learning 必须指名一个文件或函数,否则队友的 Claude 打开那个文件时不知道该不该弹这条。我改成 src/models.py load_config 再试,还是拒。最后加 --anyway 才强制存进去。存完我看文件,落在 .trail/learnings/ 下,带一段 YAML frontmatter。
---
title: load_config hangs without timeout
id: l-8a8ed4e1
scope: repo
status: active
src: agent
---
这个校验是个意外发现,也是我觉得它设计清醒的地方。学习不是无脑堆,它逼你挂到一个具体符号上,才可能被下一个会话接住。存完再跑 trail status,learnings 从 0 变成 1。我的判断是,graft map 让 agent 少走弯路,learnings 让团队经验不丢,两个都值钱。
值不值得上
我给个明确分界。你的 agent 天天改一两个文件、几十行代码,行号加正则够用,上 Trail-Code 多背建图和 hook 的开销,不划算。你的 agent 在几千文件的大仓里做重构,或一个团队反复踩同一批坑,那符号检索能把跨文件 rename 从十几次易错的 replace 压成一次原子调用,learnings 能让新成员少交一遍学费。README 那组数字我信方向但标出处:46% 更少工具调用、60% 更少时间是官方标的,SWE-bench Verified 33/50 对 27/50 也是官方标的,不是我测的。
一句话。Trail-Code 值钱的地方,不是多一个检索工具,是它把「重新认识代码库」这件每个 agent 都在重复的事,做成了一次性的本机资产。