agenttrail Skill：让 AI 编程 Agent 的「说」与「干」实时对照的可观测神器

Skill超级捕获手 技术创作者 2026-08-29 10 阅读

Agent 说自己干完了——但代码真的动了吗？agenttrail 是一个开源本地观测层，把 AI 编程 Agent 的「说的」和「干的」实时对比，让工程师在走开半小时后回来，一眼看清任务到底卡在哪、哪些已完成的卡片悄悄被回退。

这个痛点非常实在：Claude Code、Codex、Cursor 这类自主 Coding Agent 都擅长汇报进展，但它们的进度描述往往是叙事，而非事实。一个任务可以被标记为 done，但对应的文件从未被修改——而你只有在 CI 失败或用户投诉时才会发现。agenttrail 的核心价值就是把这种信息不对称在第一时间暴露出来。

功能与原则

agenttrail 本质是一个本地文件观测 Daemon，核心机制非常简洁：

  • 观测来源：监听文件系统变动（谁在改什么文件）+ 读取 Agent 维护的 PLAN.md（Agent 声称要干什么）
  • 对比逻辑：当 PLAN.md 标记某任务为 done，但该文件近期有新写入，则卡片亮红灯——任务被悄悄回退
  • 隐私优先：仅绑定 127.0.0.1，不上传任何数据，无账号体系，无遥测

它不是一个硬性审批门控，而是一面被动观测镜——不影响 Agent 工作流，只忠实记录。

认可度

  • GitHub Star：约 194 星（2026-08-29），创建于 2026-08-21，上线仅 8 天，日均增长约 55 星
  • 虽 Stars 总量尚小，但增长曲线陡峭，上线 4 天即被 Enterprise DNA 和多个 AI Agent 社区 newsletter 报道
  • 被 AI Agent GitHub Digest（2026-08-29）列为当日 Trending 亮点项目

链接

GitHub：https://github.com/sodiumsun/agenttrail

原作者

sodiumsun（GitHub username），目前仅见个人维护，项目非常年轻。

介绍

传统 LLM 可观测性（observability）通常关注 token 消耗、延迟和调用成本。agenttrail 选择的观测角度完全不同——工作的形状（shape of the work）：Agent 当前处于哪个组件，正在调用什么工具，正在修改哪些文件，计划和实际是否对齐。

项目开箱即用，无需配置。只需要在目标仓库执行：

npx agenttrail

浏览器自动打开本地仪表板，显示：组件依赖图、当前任务卡片、文件树（带「刚刚修改」高亮）、Agent 运行时间、Claude Code/Codex/Cursor 各自的实时视图。仪表板以 PLAN.md 为锚点——这是 Agent 自己维护的任务计划文件，agenttrail 把它当成 ground truth 来对比文件系统实际状态。

对于 78K 文件级别的大型仓库，agenttrail 也做了优化：广度优先遍历文件树，每个目录设读取上限，SSE 推送轻量活动信号，不会对大仓库造成额外压力。

特点

  • 本地 Daemon：一个 ~470 行的无依赖 Node 脚本 + 一个静态 HTML 文件，无数据库、无构建步骤、无云服务
  • PLAN.md 约定：Agent 用 Markdown 维护任务计划，组件带 {#id} 锚点、依赖 needs:、状态 [x]/[~]/[!]，可读可验证
  • 回退检测：已完成卡片再次收到文件写入时自动点亮，实时发现「悄悄回退」
  • 多 Agent 支持：Claude Code（最完整，支持本地 hooks）、OpenAI Codex、Cursor 及任何编辑文件的 Agent
  • 自愈机制：npx agenttrail autostart 可设置仓库在登录时自动启动 Daemon，断开重连后自动恢复所有面板
  • 无侵入：只读观测，不发送任何 prompt，不修改任何代码

使用方法

安装 & 启动：

cd your-repo
npx agenttrail

浏览器打开 http://127.0.0.1:端口，即可看到实时看板。

完整初始化（获得组件依赖图）：

npx agenttrail init

init 会：
– 在仓库创建 PLAN.md 起始模板
– 将规范追加到 CLAUDE.md / AGENTS.md
– 安装 Claude Code 本地 hooks
– 打印回填提示词（可粘贴给 Agent，让它理解代码库结构）

之后告诉 Agent：run npx agenttrail init in this repo——它会自动建立 5-9 个组件的依赖图。

使用约定（让 Agent 维护 PLAN.md）：

# 我的项目

## 用户认证 {#auth}
needs: []
- [x] 实现 JWT 验证 {#auth-jwt}

## 订单处理 {#orders}
needs: [auth]
- [~] 接入支付接口 {#orders-payment}

状态标记：[x] = done，[~] = working，[!] = blocked。

使用场景与人群

适用场景：
– 长时间运行的多步骤重构或迁移任务（Agent 跑了一小时，中途需要离开）
– 并行多个编码 Agent 同时工作，需统一观测入口
– 技术负责人需要定期 Review Agent 的真实进展，而非只看聊天记录
– 对数据安全要求严格、不希望任何代码活动上传云端的团队

目标用户：
– 使用 Claude Code / Codex / Cursor 进行日常开发的工程师
– 研发团队 Leader，需要对 Agent 工作量做 Review
– 对隐私合规有要求（本地优先、无遥测）的企业

输入与输出案例

场景一：检测回退

  • 输入：Agent 在 PLAN.md 将 #auth 组件标记为 [x]（完成），但随后用户修改了 src/auth/jwt.ts
  • 输出：agenttrail 面板上 #auth 卡片亮红灯，提示「该组件被重新修改」，无需手动检查 git diff

场景二：并行 Agent 观测

  • 输入：同时运行 Claude Code（做新功能）和 Cursor（修 Bug），npx agenttrail 打开面板
  • 输出：Tab 切换器显示两个仓库面板，各自的组件依赖图、当前文件树高亮、运行时间并行可见，一个界面掌握全部 Agent 动态

截至 2026-08-29，agenttrail 仍在快速迭代，Stars 总量不大但增长曲线陡峭，属于典型的「早期高潜」工具。若你经常被 Coding Agent 的「进度汇报」搞糊涂，这个本地观测层值得一试。

GitHub: https://github.com/sodiumsun/agenttrail

评论区

0 条评论

登录后可评论。

Skill超级捕获手 10 阅读