Agents Observe
为 Claude Code 与多智能体（multi-agent）会话提供实时可观测性面板，让每个子代理、每次工具调用和 Token 消耗一目了然。
数据流文档较清晰（本地SQLite、环境变量、存储路径、迁移记录），外部效果限于本机端口，无远程外传证据；但该工具完整捕获所有hook事件payload（含命令、文件读取内容），无脱敏或保留策略说明，捕获面为全部事件而非最小必要，扣分明显；依赖安全仅有allowScripts白名单，无审计证据；回滚仅有db-reset，无通用回滚。
故障排查章节和/observe debug命令较为完善，failure_messages给2；但自相矛盾处可见：副标题宣称支持Codex而ROADMAP又列为待办，README中出现0.9.7版本注记而package.为0.9.12，还有重复的'just health'行，self_consistency扣至1；依赖Docker+Node+Bash三件套，缺失即无法加载，dependency_availability仅1。
面向Claude Code多智能体会话观测，受众与场景描述清楚；hook事件、端口、路径、环境变量均可配置，trigger_precision与environment_fit可给2；但能力边界表述矛盾（Codex既在宣传又在路线图），known/边界说明不一致故capability_boundaries仅1。
README结构完整（快速开始、架构、项目结构、排错），install_notes和information_architecture可给3；MIT LICENSE明确署名Joe Johnston，license给3；发布流程引用CHANGELOG.md并有tag发布流水线，versioning给2；但已知限制无专门章节，维护者/贡献/更新承诺信息缺失且发布者未验证，maintenance_responsibility仅1。
仪表盘功能（实时流、过滤、agent层级、token统计、回放）描述具体且通过截图/演示佐证，output_usability与marginal_value给2；但运行需Docker+Node常驻容器与hook注入，成本不低，且有fresh-install测试框架证明安装链路复杂，cost_benefit保持2未加分。
架构声明与项目结构、测试夹具（健康端点/api/health、sessions接口）可交叉印证，claim_traceability与cross_source_corroboration给2；但关键实现文件（observe_cli.mjs、server源码、CHANGELOG正文）未在证据中，README的0.9.7与package.的0.9.12版本不一致，事实与推断难以严格分离，fact_inference_separation仅1。
- 该工具会完整捕获所有hook事件payload（包括执行的命令和读取的文件内容）并存储到本地SQLite，使用前请确认无脱敏/加密需求未被满足，并注意数据库文件的访问权限。
- 运行需要Docker、Node和Bash三者齐备，任一缺失插件将无法加载；服务器默认监听本机端口4981，若改动AGENTS_OBSERVE_BIND为0.0.0.0请注意网络暴露面。
- 文档存在版本不一致（README提及0.9.7，package.为0.9.12）与Codex支持表述矛盾，实际功能以执行验证为准。
- 发布者未经验证，无明确维护承诺与贡献流程，长期维护风险自担。
这个 Agent 能做什么，适合哪些场景？
Agents Observe（GitHub: simple10/agents-observe）是一个面向 Claude Code 会话的实时可观测性仪表盘，以 Claude Code 插件形式分发，也可脱离插件独立运行。它通过 Claude Code Hooks 捕获每个事件（工具调用、提示、停止、子代理生命周期），经 observe_cli.mjs 通过 HTTP POST 发送到一个 Hono + SQLite + WebSocket 的 Node 服务器，再由 React 19 客户端实时展示。仪表盘支持强大的过滤、搜索与可视化，可展开查看事件的完整载荷（命令与结果），查看子代理与父代理的层级关系，并通过会话回放追踪历史，最新版本（0.9.7）还增加了会话 Token 用量与成本统计。生产模式下服务器以 Docker 容器运行，默认面板地址为 http://localhost:4981，数据默认存放在插件数据目录或 ~/.agents-observe/ 下的 SQLite 数据库中。如果你的团队经常运行多代理并行任务，需要事后排查或实时监控代理行为，这个工具直接针对该痛点。
工作流程为：Claude Code Hooks 在每个事件上触发 hooks.sh 与 observe_cli.mjs，后者从 stdin 读取原始事件，经由 hooks/scripts/lib/agents/<class>.mjs 中的 buildHookEvent() 构建包含代理类别标志（如 meta.isNotification）的事件封套，POST 到 API 服务器。服务器提取结构化字段（事件类型、工具名、代理 ID），存储代理元数据（名称、描述、类型、父子关系），写入 SQLite（observe.db），并将事件转发给订阅该会话的 WebSocket 客户端。React 客户端首次加载时通过 REST API 拉取事件，之后通过 WebSocket 增量接收；客户端将 PreToolUse 与 PostToolUse 合并为单行展示，所有代理状态（状态、事件计数、耗时）均从事件流推导。可通过 /observe 技能（view、stats、status、start、stop、restart、logs、debug）在 Claude 中管理服务器。
- 运行协调者模式的 Claude Code 用户同时派生代码审查、测试运行和文档子代理，需要在面板上实时看到每个子代理在做什么
- 开发者调试一个深度嵌套的并行代理执行中出现的问题，需要回放完整事件时间线与载荷定位破坏性命令
- 团队负责人想统计各会话的 Token 用量与成本分布，通过会话统计弹窗评估支出
- 独立开发者离线运行 Codex 或手动 CLI 场景（数据目录 ~/.agents-observe/），需要独立安装方式监控代理事件
- 工程师需要排查插件服务器故障，用 /observe debug 检查服务器健康、Docker 容器日志、mcp.log 和 cli.log
这个 Agent 有哪些优点和局限？
- 实时流式展示每个工具调用（PreToolUse → PostToolUse 含结果），而终端只能看到一小部分活动，子代理通常完全不可见
- 展示完整的代理层级关系，能看出哪个子代理由哪个父代理派生，这是多数日志方案不具备的
- 事件存入 SQLite 支持历史会话回放与跨会话行为模式分析，调试相当于"时间旅行"
- 0.9.7 起内置 Token 用量与成本分解统计，可直接评估代理运行成本
- 以官方插件市场方式一键安装，升级自动保留数据库，并提供 /observe debug 自诊断
- 强制依赖 Docker 运行服务器，同时需要 Node.js 和 Bash，任一缺失插件将无法正常加载
- 核心基于 Claude Code Hooks，对其他代理框架（Codex、OpenClaw、pi-code）的支持仍在路线图中尚未实现
- 多占一个本地端口（默认 4981，占用时会自动换端口），生产与开发模式端口不同可能造成混淆
- 从 ≤0.9.8 旧版本升级需要依赖首次启动时的数据库迁移扫描，存在迁移风险（迁移记录见 .migrated-from.）
- 服务器跟踪会话状态但不跟踪代理状态，代理状态完全由客户端从事件流推导，实时性依赖 WebSocket 连接（断线每 3 秒重连）
如何安装或部署这个 Agent？
前提：主机需安装 Docker、Node.js 和 Bash。以 Claude Code 插件方式安装：
bash
# 将本仓库添加为插件市场
claude plugin marketplace add simple10/agents-observe# 安装插件
claude plugin install agents-observe插件会自动启动 MCP 服务器并捕获事件。数据默认存于 ~/.claude/plugins/data/agents-observe-agents-observe/（市场安装）。如需自定义数据位置，在 ~/.claude/settings. 中设置 env.AGENTS_OBSERVE_LOCAL_DATA_ROOT。
独立安装（开发或非插件方式）：
bash
git clone https://github.com/simple10/agents-observe.git agents-observe
cd agents-observebrew install just # 如未安装
just start # 启动 Docker 容器
# 或本地开发：just install && just dev
独立模式还需将 .claude/settings. 中的 hooks 复制到项目或用户级 Claude Code 设置中，并将 $CLAUDE_PROJECT_DIR 路径指向安装位置。
如何使用这个 Agent？
插件安装后直接运行 claude，服务器自动启动并捕获事件；浏览器打开 http://localhost:4981 查看仪表盘（开发模式为 http://localhost:5174）。在 Claude 中使用 /observe 技能：/observe status 查看服务器健康与版本，/observe view 打开当前会话，/observe stats 打开 Token 统计，/observe logs 查看 Docker 日志，/observe debug 诊断问题。独立模式下可用 just 命令：just health 检查服务器，just test-event 发送测试事件，just dev 热重载开发，just db-reset 重置数据库。常用环境变量：AGENTS_OBSERVE_SERVER_PORT（默认 4981）、AGENTS_OBSERVE_PROJECT_SLUG、AGENTS_OBSERVE_API_BASE_URL、AGENTS_OBSERVE_NOTIFICATION_ON_EVENTS，完整列表见 docs/ENVIRONMENT.md。
这个 Agent 与同类方案有什么区别？
README 提到相关项目：Agent Super Spy（作者同为此仓库作者，提供可本地或远程运行的完整代理可观测性栈）、Multi-Agent Observability System（本项目的灵感来源）、Claude DevTools（针对 Claude 会话文件的可视化工具，需在本地机器运行）。
常见问题
必须安装 Docker 吗？
just start-local 或 start.mjs 不经 Docker 本地启动服务器，但仍需 Node.js 和 Bash。支持 Claude Code 以外的代理工具吗？
数据存在哪里，升级会丢数据吗？
端口 4981 被占用怎么办？
面板上看不到事件怎么排查？
just health 或 /observe status 确认服务器在运行；确认 hooks 已复制到项目设置；用 just test-event 发送测试事件验证链路；WebSocket 断线时客户端每 3 秒自动重连，重连后事件会补齐。