trailhq/Trail-Code

Trail（前身为 Graft）——一个代码库感知的助手辅助工具

它是什么 – Trail 是一个 TypeScript/Node.js CLI，它构建一个轻量级的、本地的仓库“图”。该图由包含简短、通俗英语摘要、关键代码片段（核心）以及概念之间类型化链接的 Markdown 文件组成。通过将此图连接到编码代理，如 Claude Code、Cursor、Codex、Gemini 或任何 LLM 驱动的“编码助手”，Trail 让代理在会话开始时就已经了解项目的结构，避免了通常消耗令牌、工具调用和延迟的昂贵的“重新探索”阶段。

为什么重要 – 典型的 AI 编码助手将每个新任务视为从未见过代码库。它们反复 grep、打开文件并跟踪导入，这增加了令牌使用量并减慢了响应速度。Trail 一次性捕获这种理解，将其存储在本地，并将其注入代理的提示中。README 声称最多 4 倍便宜 和 3 倍快，且不损失正确性，甚至在 SWE-bench 基准测试中准确率也有可测量的提升。

主要特性

• 一次性图构建（graft init / trail init），使用 tree-sitter 解析源文件（无需模型，无需 API 密钥），并可选地对每个文件运行一次语言模型以生成人类可读的摘要。
• Markdown 节点：每个节点包含摘要、最相关的代码行、源文件哈希和 wikilink 风格的类型化边（depends_on、uses 等）。
• 本地缓存：graft/ 文件夹被添加到 .gitignore；只提交微小的接线文件（.claude/、AGENTS.md）。
• 自动新鲜度：在回答之前，工具检查文件哈希并仅重建更改的部分，因此代理始终看到当前工作树状态，即使有未提交的编辑。
• 代理集成：内置支持 Claude Code（深度集成）和用于其他代理的通用 MCP 服务器钩子。
• CLI 工具 – graft ask、graft grep、graft map、graft viz 和 graft check，用于搜索、可视化和验证图。
• 多仓库 / monorepo 支持 和广泛的语言覆盖（23 种语言，包括 TS/JS、Python、Go、Java、Rust、C/C++ 等）。
• 提供商无关的 LLM 使用 – 您可以为摘要步骤插入 OpenAI、Anthropic、OpenRouter、Groq、LiteLLM 或本地模型，使用您自己的 API 密钥。

典型工作流程

1. 安装 CLI（npm i -g @trailhq/trail 或 npm i -g @nanonets/graft）。
2. 运行 trail init（或 graft init）– 选择您使用的代理，工具会创建 graft/ 目录和接线文件。
3. 下次启动 Claude Code 会话时，Trail 将相关节点摘要注入提示中，因此模型可以用更少的工具调用回答。
4. 每次编码会话后，您所做的任何更正都会作为“经验”保存在 .trail/learnings/ 下。这些成为代理在未来会话中自动应用的规则。
5. 在 PR 之前，trail check 会标记与现有经验冲突的更改。

基准测试（如报告）

• 冷启动 vs. Graft（Claude Code）：工具调用减少 46%，令牌减少 42%，延迟减少 60%，在 SWE-bench 上正确性提升 12 个百分点（54% → 66%）。
• 成本：每个任务 $0.029 vs. $0.042（约便宜 32%）。

谁可能使用它 – 严重依赖基于 LLM 的编码助手并希望降低 API 成本、加快响应速度并直接在仓库中捕获机构知识（团队特定决策、模式和修复）的开发团队。

---

TL;DR：Trail（前身为 Graft）是一个 CLI，它构建代码库的人类可读、基于 Markdown 的知识图，并将其连接到 AI 编码代理，减少重复的代码探索，节省令牌和时间，并持久化团队经验以供未来会话使用。