用途
agentwatch 为在同一台机器上运行多个 AI 编程智能体的用户提供本地可观测能力。当同时使用 Claude Code、Codex、Gemini CLI、Cursor、Hermes、OpenClaw 等工具时，每个智能体各自拥有日志、权限模型和会话定义，彼此之间互不可见。agentwatch 将这些事件汇聚到一条统一时间线，帮助用户了解各智能体做了什么、花费多少，以及何时出现异常。
主要能力
- 多智能体统一时间线：所有事件按事件时间戳排序（而非到达顺序），列包含时间、智能体、类型、项目摘要、耗时与错误。
- 事件详情面板：按 Enter 打开，显示元数据、token/成本/耗时、工具结果（含语法高亮）、完整提示或回复文本、扩展思考块与工具输入 JSON。
- 子智能体下钻：按 x 将时间线限定到某个子智能体的内部工具调用。
- 项目与会话导航：项目网格汇总各智能体的会话数、总成本与最近活动。
- 跨会话搜索：按 ? 对所有会话文件进行模糊子串搜索，优先使用 ripgrep。
- 按会话成本核算：内置按模型费率表（Claude opus/sonnet/haiku、GPT-5/GPT-5-mini、Gemini 2.5 Pro/Flash），考虑 cache_read 与 cache_creation 的计费权重，计算每回合真实美元成本。
- 按回合 token 归因：按 t 查看每回合堆叠条形图，区分 user、memory file、tool I/O、thinking、input/cache read/cache create/output。
- 上下文压缩可视化：按 C 查看上下文填充百分比及自动压缩标记，显示压缩前后 token 数。
- 预算告警：通过 ~/.agentwatch/budgets.json 配置上限，超限时显示红色横幅并触发系统通知。
- 异常检测：基于成本、耗时、输入 token 的 MAD z-score 离群值检测，以及检测 1–4 周期的卡死循环检测器。
- 用户自定义通知触发器：通过 ~/.agentwatch/triggers.json 配置，热重载。
- 桌面通知：对敏感事件（如 .env 访问、rm -rf、sudo、curl | sh、工具错误、预算超限、异常）发出提醒，有限速。
- 各智能体权限视图：按 p 查看各智能体的权限与配置状态。
- 会话导出：按 e 导出 Markdown 与 JSON。
- 语法高亮、过期会话检测、剪贴板复制。
- MCP 服务器模式：其他智能体可查询自身历史。
- OpenTelemetry 导出：设置 AGENTWATCH_OTLP_ENDPOINT 后按 GenAI 语义约定发出 OTLP/HTTP span。
使用方式
需要 Node ≥ 20，支持 macOS 或 Linux（Windows 暂不在 v0.x 范围内）。通过 npm 安装（包名位于 @misha_misha scope），安装后二进制名为 agentwatch。可通过 --no-web（仅 TUI）、--port/--host 或 AGENTWATCH_PORT/AGENTWATCH_HOST 环境变量控制 Web 服务绑定。TUI 为实时日志流，Web UI 默认位于 http://127.0.0.1:3456，按 w 在浏览器打开。⌘K / Ctrl+K 打开命令面板，/ 聚焦时间线过滤。
适用场景
- 多智能体任务排查与事后复盘
- 成本超支调查
- 安全审计与 .env 泄漏告警
- 卡死循环检测
- 子智能体事后分析
限制
- agentwatch 是查看器而非守护进程，仅在 TUI 运行时捕获事件，后台捕获守护进程尚在计划中。
- 启动时回填读取各活动会话文件最后约 4 MB，长时间间隔可能遗漏最早事件。
- Cursor 仅捕获配置层面状态，其 AI 活动存于尚未解析的 SQLite 数据库。
- Gemini CLI 不持久化压缩标记；OpenClaw 不持久化 tool_result 内容与压缩标记，属数据结构性限制。
- Windsurf、Aider、Cline 可被检测但尚未接入。
- 仅支持 macOS 与 Linux。
- tokenizer 为 cl100k_base，对 Claude 约有 5% 误差，仅影响归因视图中的 user/thinking/tool I/O/memory-file 分类；精确 token 来自模型自身 usage 记录。
- 定位边界：非云端、非 SaaS、非智能体本身、非生产级 LLM 应用追踪、非企业合规、非编排、非记忆、非治理与策略执行工具。
- 本地优先为硬性不变量：除非显式设置 AGENTWATCH_OTLP_ENDPOINT，否则无网络调用；无遥测；除剪贴板与显式导出外所有文件只读。
