AgentTrail

这是什么？适合谁？

AgentTrail（sodiumsun/agenttrail）是一个本地、开源的可观测性层，针对 AI coding agent。它把 Claude Code、OpenAI Codex、Cursor 或任何会改文件的 Agent 的计划、工具调用、文件变更和进度变成一张实时项目地图。

它回答的问题：你的 coding agent 已经跑了半小时——它在推进吗？卡住了吗？是不是悄悄把已经标成完成的部分又打开了？

核心机制：

• Declared（声明）：Agent 声称正在做的组件和任务
• Observed（观察）：它此刻正在改的文件，包括对已完成工作的修改

当两者不一致，你就知道该看哪里。一张完成的卡片在文件再次变化时重新点亮；一次 live run 停靠在它正在触碰的组件上。地图随着工作移动。

适合人群：长时间跑 agent 的开发者；想「人走开、回来一眼看清进度」的人；需要向团队展示「Agent 到底在干什么」的场景。

本地性：daemon 是一个无依赖的 Node 文件（约 470 行），界面是一个静态 HTML 文件。无数据库、无构建步骤、无云服务、无账号、无遥测。只绑定 127.0.0.1。

准备工作

1. Node ≥ 20。
2. 成本：MIT 开源，完全免费，无账号。
3. 安装：无需全局安装——npx agenttrail --open 即用。
4. 可选：npx agenttrail init 装完整组件地图（写 CLAUDE.md/AGENTS.md 约定 + starter PLAN.md + 本地 Claude Code hooks）。
5. 时间预算：起步 30 秒；init 完整地图约 2 分钟。

快速上手（3 步）

第一步：启动

cd your-repo
npx agenttrail --open

agenttrail 在 localhost 打开并开始监听仓库。

第二步：给完整地图（可选但推荐）

npx agenttrail init

init 添加 agenttrail 约定到 CLAUDE.md 和 AGENTS.md、创建 starter PLAN.md、安装增量式本地 Claude Code hooks。然后点 board 上的「Copy backfill prompt」粘贴给 Agent。

第三步：跑一个任务并观察

启动 Agent 工作，地图实时显示它所在的组件、正在运行的工具、正在改的文件。

成功判定：你能在 board 上看到 Agent 的 plan、streaming tool line、elapsed time、recent calls，以及组件地图的进度（done/working/blocked）。

初级用法

地图语义

• 5–9 个真实组件，带依赖箭头、虚线链接、进度，以及诚实的 done/working/blocked 状态
• 当前 Claude Code run：任务列表、流式工具行、耗时、最近调用
• 组件的会话 plan，run 结束几小时后淡出
• VS Code 风格仓库树，带实时「刚触碰」高亮和 Working 信号
• Provenance pills 把「即将发生的 Agent 意图」和「roadmap 积压」分开

PLAN.md 约定

组件用稳定 {#id}；files: 把观察到的写入连到所属组件；[~] working / [x] done / [!] stuck；needs: 画依赖箭头，links: 画虚线连接；by: 记录谁做的；from: 区分 Agent 意图和 roadmap 意图。

高级玩法

支持矩阵

巨型仓库

agenttrail 在 78k 文件的仓库上测试过：广度优先读树、每目录上限、微小 SSE 活动 tick，树被裁剪时明确告知。

让 Agent 自己维护地图

「run npx agenttrail in this repo」一句话让 Agent 加仓库，秒级出现在每个 board 的 tab 切换器里；杀掉 daemon 就到处消失。你的 Agent 边工作边维护一个小的 Markdown 文件，而非你维护 PM board。

小技巧

1. 看声明与观察的背离：完成卡片文件再变 → 该看那里；这是发现 Agent 反复推倒重来的最快信号。
2. 用 backfill prompt 建初始地图：让 Agent 先读代码、再读 git 历史、最后读规划散文，画出 5–9 个组件。
3. 一个 daemon 管一个仓库：一个 board 的 tab 切换器里切换所有 live board，不必多开。
4. plan 过期就让它重验：告诉任意 Agent「re-verify PLAN.md against the code」，board 随文件更新。
5. 无 PLAN.md 也能用：live 树、活动流、run 卡片不需要 plan，地图在 Agent 写 plan 后出现。

常见踩坑

踩坑 1：只看到树、看不到地图

• 现象：组件地图空白。
• 原因：没跑 npx agenttrail init，或 Agent 还没写 PLAN.md。
• 解决：跑 init 并用 backfill prompt 让 Agent 生成 PLAN.md；无 plan 时地图本就不出现。

踩坑 2：以为会控制 Agent

• 现象：担心 agenttrail 给 Agent 发指令。
• 原因：误解它的角色。
• 解决：它只观察和画图，从不发 prompt、不改代码；init 只打印可选 backfill prompt，board 可复制到剪贴板。

踩坑 3：init 改了仓库文件

• 现象：发现 CLAUDE.md/AGENTS.md 被追加内容。
• 原因：init 会追加约定到指令文件并建 .agenttrail/。
• 解决：这是预期行为；.agenttrail/ 已加 .gitignore，运行中的 dashboard 只读。

踩坑 4：大仓库树被裁剪

• 现象：巨型仓库里树不完整。
• 原因：广度优先读树带每目录上限。
• 解决：这是设计行为，board 会告知树被 abridged；不影响核心观察。

踩坑 5：端口/绑定误解

• 现象：想远程访问 dashboard。
• 原因：daemon 只绑 127.0.0.1。
• 解决：设计如此（本地优先）；需要远程共享用端口转发自行处理，但注意它从不发 prompt。

常见问题 FAQ

Q1: 没有 PLAN.md 能用吗？

A: 能。live 树、活动流、run 卡片不需要 plan；组件地图在 Agent 写 plan 后才出现。

Q2: 这里的「coding agent 可观测性」指什么？

A: LLM 可观测性通常关注 trace、延迟、token、成本；agenttrail 关注仓库里正在发生的工作：Agent 在哪个组件、运行什么工具、改什么文件、plan 是否在推进。

Q3: agenttrail 会控制我的 Agent 吗？

A: 不会。它观察并画图，从不发 prompt，也不编辑代码。

Q4: init 改了什么？

A: 创建 starter plan、把约定追加到指令文件、把 .agenttrail/ 加 .gitignore、装本地 Claude Code hooks。dashboard 本身只读。

Q5: plan 过期了怎么办？

A: 告诉任意 Agent「re-verify PLAN.md against the code」，board 随文件更新。

进阶学习建议

掌握基础后，建议深入：

1. 声明 vs 观察的背离审计：用完成卡片重新点亮作为「Agent 悄悄返工」的预警，复盘哪些组件反复被改，找到 Agent 卡住的根因。
2. PLAN.md 决策记录：让 Agent 在采取影响计划的行动前记录决策（from: 区分意图来源），把地图变成项目记忆。
3. 多仓库看板：给每个活跃仓库跑一个 daemon，在单个 board 里统一观察所有 Agent 活动。

参考链接

• 官方仓库
• npm: agenttrail

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成