Agenttrail
在本地观察 AI 编码代理的项目变更、任务进度与角色贡献。
按维度查看评分与理由
材料明确说明服务仅绑定 127.0.0.1、不需要账户或云服务、正常监视不修改仓库，并具体列出读取、浏览器传输、本地保存及可见敏感信息，因此数据流透明度充分。GitHub Actions 权限仅为 contents: read，外部 action 固定到提交，体现了最小权限和供应链防护。扣分在于 Map init 会创建或编辑多个文件，非交互模式默认同意；可选钩子会修改提供方设置，而所给材料未展示逐项确认、完整回滚步骤、依赖审计或敏感字段过滤实现。来源由仓库地址、MIT 版权人和贡献入口标示，但发布者未获企业注册表验证，维护身份只能视为项目内自述。
README、package.json、许可证和 CI 对产品定位、Node.js 20+、MIT 许可及两个独立视图的描述相互一致，且 CI 覆盖 Node 20/22/24、Linux、macOS、构建、检查、测试及打包。依赖安装使用 npm ci，但材料没有提供锁文件内容、离线策略或依赖不可用时的保障。FAQ 给出了安静界面、日志缺失和远程会话等排障线索，但未展示代码级错误消息及所有失败模式。
文档清楚区分 Map、Kitchen、Codex、Claude Code、Cursor、VS Code 和其他工具的适用场景，并明确产品只观察、不执行代理、不批准操作、不判断真正交付，能力边界优秀。触发和接入方式有命令、显式 Connect agents、可选钩子及 PLAN.md 约定，但原生事件覆盖因提供方而异，日志格式可能变化。环境支持明确要求 Node.js 20+、浏览器 WebGL 和本地日志；macOS 有人工使用记录、Linux 有自动检查，但 Windows、原生 Cursor 和无本地日志的远程环境仍未验证。
README 的导航、对照表、安装命令、PLAN.md 示例、FAQ、限制说明和贡献入口组织完整；LICENSE 是完整 MIT 文本，且 package.json 元数据一致。Map 与 Kitchen 的产品关系得到解释，但两个包使用不同版本线，Kitchen 仍为 alpha，可能增加命名和版本理解成本。材料仅链接发布说明而未提供变更日志内容、发布节奏或兼容性政策，因此 versioning_changelog 较薄；有版权人、问题和贡献入口，但没有明确维护团队、支持承诺或更新责任制度。
界面映射表、截图、演示模式和可检查证据的描述表明输出可用于理解文件活动、任务和角色贡献；同时它补足多终端观察的可见性，且无需账户、API 密钥或构建即可试用发布包。扣分在于效果主要由项目文档和录制演示陈述，未提供用户研究或对照数据；两个独立本地服务、实验性 3D 界面、适配器差异及日志依赖会增加认知和维护成本。
关键主张通常关联到具体命令、配置文件、数据源、CI 步骤或仓库内文档，且 README、package.json、LICENSE 与工作流之间存在良好的一致性。材料没有提供所链接文档、实现代码、测试文件或测试输出，因此隐私、字段白名单和实际适配器行为只能获得部分可追溯与交叉佐证。对脚本示例、真实观察、推断角色、原生 todo 完成、待验证平台和未实现功能的区分非常明确，事实与推断分离充分。
- Map 的非交互式 init 默认同意并会创建或修改 PLAN.md、CLAUDE.md、AGENTS.md 和 .gitignore；只应在明确准备配置仓库时运行，并应先保存或审查现有改动。
- 工具会读取本地代理日志、任务标题、路径和部分工具详情；录屏、共享浏览器画面或暴露 ~/.agenttrail 数据前应检查其中是否包含敏感项目或命令信息。
- Kitchen 是实验性 alpha；Windows 与原生 Cursor 实时行为尚未验证，远程会话若主机上没有日志也不会被自动发现。
- 所给材料未包含实现代码、锁文件或测试结果；本评估不能独立确认本地绑定、字段白名单、钩子可逆性或依赖安全声明。
这个 Agent 能做什么，适合哪些场景？
Agenttrail 是面向 AI 编码代理的本地可观测性项目，由独立运行的 Map 和 Kitchen 两个视图组成。Map 将 PLAN.md 中声明的计划与文件变更结合，展示组件、依赖、进度、实时文件树和会话轨迹。Kitchen 通过浏览器中的 3D 厨房场景呈现当前任务、职责角色、工作过程、协作贡献和已完成事项。两项服务都绑定到 127.0.0.1，不要求账户、API 密钥、模型调用、遥测或云端服务，也不会启动代理、分配工作、批准操作或自行判定任务完成。它适合希望在 Codex、Claude Code 或受支持的 Cursor 工作流旁边查看本地活动证据，而不想把代理日志上传到外部平台的开发者。
Kitchen 通过 npx agenttrail-kitchen . 启动本地服务，读取可访问的本地 Codex 或 Claude Code 会话日志、受支持的原生待办事项、文件活动以及可选的 Claude/Cursor 钩子事件，并在浏览器中把职责显示为厨师、把待办显示为订单和菜品、把工作及完成状态显示为烹饪和交付。它可以推断项目职责及待办完成情况，但跨会话共享同一待办和经过确认的交接需要额外元数据；点击厨师或订单可以检查相关证据。Map 通过 npx agenttrail 运行，把 PLAN.md 中的组件、任务状态、files: 文件匹配、needs: 依赖和 links: 连接与实际文件变更组合成项目图，并提供会话轨迹和多仓库概览。可选的 Claude Code 钩子为 Map 增加会话、工具活动及旧版 TodoWrite 列表；Codex、Cursor 和其他工具在 Map 中主要通过文件观察与共享计划约定提供信号。正常观察不会编辑项目，但 npx agenttrail init 会创建初始计划和代理约定、提供可选钩子，并修改 .gitignore。
- 同时使用本地 Codex 或 Claude Code 的开发者，希望在一个浏览器视图中查看当前任务、会话活动和职责变化。
- 维护具有多个组件和依赖关系的代码库的团队，希望用 PLAN.md 与真实文件写入对照项目进度。
- 录制或演示代理工作过程的开发者，希望使用 Kitchen 的 3D 场景展示任务处理，同时保留可检查的底层证据。
- 在 VS Code 中使用 Codex 或 Claude Code 的工程师，希望通过集成终端启动一个并排运行的浏览器伴侣，而不是安装编辑器扩展。
- 评估本地优先监控方案的安全敏感团队，希望避免账户、遥测、转录上传和云端模型调用。
- 尚未连接真实代理的试用者，希望用
--example的标注脚本流程先体验 Kitchen。
这个 Agent 有哪些优点和局限？
- 本地优先：服务仅绑定 127.0.0.1，不要求账户、API 密钥、遥测、转录上传、模型调用或云服务。
- 提供两种互补视角：Map 面向组件、依赖和文件活动，Kitchen 面向任务、职责贡献和完成情况。
- Kitchen 可自动读取可访问的本地 Codex 与 Claude Code 日志，基础观察无需 PLAN.md、复制文件或启动新代理会话。
- 将推断与事实边界区分得较清楚：结束一轮对话不会自动被视为交付，缺失计划会显示为进度未知。
- 正常观察不会启动或控制代理，也不会编辑被观察的仓库。
- Kitchen 仍是公开实验预览，本地提供商日志格式可能变化，重启后的历史记录只能依据现有观测重建。
- 要求 Node.js 20+ 和支持 WebGL 的浏览器；无本地日志的云端或远程会话不会被自动发现。
- Windows 和 Cursor 原生实时行为尚未验证；Cursor 目前只有适配器测试通过。
- Map 与 Kitchen 使用不同的本地服务和提供商适配器，活动覆盖范围及历史记录并不完全一致。
- 跨会话共享待办和已确认的工件交接需要显式元数据，不能从普通仓库活动自动可靠推断。
- 尚无 Agenttrail 的 VS Code Marketplace 扩展，用户需要在编辑器旁保留浏览器伴侣。
如何安装或部署这个 Agent？
前提条件：Node.js 20+、支持 WebGL 的浏览器以及一个本地项目目录。基本使用不需要账户或 API 密钥。进入要观察的仓库后直接运行：
npx agenttrail-kitchen .Map 可独立运行：
npx agenttrail若要固定 README 中给出的 Kitchen 预览版本，可运行：
npx [email protected] .从源码构建 Kitchen：
git clone https://github.com/sodiumsun/agenttrail.git
cd agenttrail
npm ci --prefix packages/kitchen
npm run build --prefix packages/kitchen
npm start --prefix packages/kitchen -- --project /absolute/path/to/your/repo如何使用这个 Agent？
在目标仓库中运行 npx agenttrail-kitchen . 并保持终端开启；浏览器会在 localhost:4780 或下一个空闲端口打开。继续在本地 Codex 或 Claude Code 会话中工作，Kitchen 会从可访问的日志和待办数据中发现活动；Claude Code 与 Cursor 还可通过界面的 Connect agents 配置可选钩子。没有真实活动时，可运行 npx agenttrail-kitchen . --example，点击 Next example step 查看脚本示例，再点击 Live 返回实际仓库。若需要组件级项目图，运行 npx agenttrail init，检查其写入操作，并按生成的约定维护 PLAN.md；之后用 npx agenttrail 打开 Map。Map 的 init 在非交互环境中默认同意配置，因此只应在确实准备修改仓库时使用。
这个 Agent 与同类方案有什么区别？
Map 与 Kitchen 是同一仓库内可独立使用的两种选择。需要查看组件结构、依赖、文件活动和基于 PLAN.md 的进度时选择 Map；需要查看当前待办、职责贡献和完成事项，并偏好 3D 协作场景时选择 Kitchen。Kitchen 拥有本地 Codex/Claude 会话适配器和可选 Cursor 钩子，而 Map 对 Codex、Cursor 等工具主要依赖文件观察与计划约定；两者的活动覆盖和历史并不相同。
常见问题
使用 Agenttrail 是否需要付费账户或 API 密钥？
它会控制或协调我的编码代理吗？
为什么 Kitchen 中没有活动？
运行它会修改代码仓库吗？
npx agenttrail init 则会创建计划和代理约定，并把 .agenttrail/ 加入 .gitignore。