如何用 Agent Observatory 与会话 replay 定位 oh-my-claudecode 的慢 Agent 与工具瓶颈【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode当你在 oh-my-claudecode 的多 Agent 工作流里发现某个 Agent 跑了很久还没结束整体并行效率变低时需要回答两个具体问题是哪个 Agent 慢、慢在哪个工具调用上。oh-my-claudecode 内置了两层监控面可以支撑这个排查Agent 运行期间的Agent ObservatoryHUD 中实时显示每个 Agent 的状态与瓶颈指标以及会话结束后写入.omc/state/agent-replay-{sessionId}.jsonl的Session Replay事件日志按工具调用粒度记录时长。本文的排查路径是先在 HUD 里用 Observatory 找到可疑 Agent再用 replay 文件与会话摘要确认是哪些工具调用拖慢了整个会话。前提是 hooks 已正常安装可用/oh-my-claudecode:hud setup检查且 Session Replay 默认自动启用无需额外开关。准备让 HUD 显示 Agent 面板Observatory 会在有 Agent 运行时自动出现在 HUD 中。要让 HUD 持续提供 Agent 与上下文可见性在~/.claude/settings.json里使用支持的 preset如focused或full{ omcHud: { preset: focused } }文档给出的完整配置示例如下可按需保留元素开关{ omcHud: { preset: focused, elements: { agents: true, todos: true, contextBar: true, analytics: true } } }agents元素显示活跃 Agent 数量与状态contextBar显示上下文窗口占用百分比analytics显示 token/成本摘要。preset 的可选值及用途minimal仅上下文条、focusedTodos、agents、modes、full全部元素、analytics成本跟踪、dense紧凑格式。第一步在 Agent Observatory 中定位可疑 AgentObservatory 的头部行给出会话级总览例如Agent Observatory (3 active, 85% efficiency)其中 efficiency 是并行效率分0–100。文档给出的输出示例示例结果数值非固定预期Agent Observatory (3 active, 85% efficiency) [a1b2c3d] executor 45s tools:12 tokens:8k $0.15 files:3 [e4f5g6h] document-specialist 30s tools:5 tokens:3k $0.08 [i7j8k9l] architect 120s tools:8 tokens:15k $0.42 └─ bottleneck: Grep (2.3s avg) ⚠ architect: Cost $0.42 exceeds threshold判断规则来自文档状态灯 正常 建议介入 陈旧 Agent运行超过 5 分钟。每行指标tools:N工具调用次数、tokens:Nk近似 token 用量、$X.XX估算成本、files:N正在修改的文件数。└─ bottleneck: 工具 (Ns avg)表示该 Agent 最慢的重复工具操作瓶颈的判定标准是被调用 2 次以上且平均耗时最高的工具所以只调用过一次的慢工具不会出现在这里。效率分的解读100% 表示所有 Agent 都在活跃工作低于 80% 表示有 Agent 陈旧或处于等待低于 50% 说明存在明显的并行问题。文档特别强调这是实时的活跃度/健康度信号不是模型质量、token 成本或延迟的基准。尾部的⚠行是自动干预建议。文档定义的触发条件timeout运行超过 5 分钟建议 kill超过 10 分钟标记为可自动执行、excessive_cost成本超过每个 Agent 默认的 $1.00 上限给出警告、file_conflict多个 Agent 改同一文件给出警告。按文档给出的Identifying Slow Agents流程在 Observatory 里优先看运行超过 2 分钟的 Agent、出现 bottleneck 指标的 Agent、以及 efficiency 明显低于 100 的会话。如果 HUD 不方便也可以程序化查询process.cwd()换成你的项目目录import { getAgentObservatory } from oh-my-claudecode/hooks/subagent-tracker; const obs getAgentObservatory(process.cwd()); console.log(obs.header); // Agent Observatory (3 active, 85% efficiency) obs.lines.forEach(line console.log(line));第二步对慢 Agent 查看工具计时详情锁定可疑 AgentObservatory 行里的短 id如i7j8k9l对应的完整agent_id后用getAgentPerformance拿到它的完整工具计时统计import { getAgentPerformance } from oh-my-claudecode/hooks/subagent-tracker; const perf getAgentPerformance(process.cwd(), agentId); console.log(Tool timings:, perf.tool_timings); console.log(Bottleneck:, perf.bottleneck);tool_timings按工具聚合出count、avg_ms、max_ms、total_ms、failuresbottleneck是其中调用 2 次以上、平均耗时最高的那个工具格式如Grep (2.3s avg)上面示例中的数值仅用于演示格式。这一步能把这个 Agent 慢细化成是它反复执行的某个工具平均耗时高。第三步用 Session Replay 复核整个会话的时间线会话结束后replay 数据落在.omc/state/agent-replay-{sessionId}.jsonl每行是一个 JSON 事件记录agent_start/agent_stop含时长、tool_start/tool_end含duration_ms、file_touch、intervention等。文档给出的事件示例示例结果{t:0.0,agent:a1b2c3d,agent_type:executor,event:agent_start,task:Implement feature,parent_mode:ultrawork} {t:5.2,agent:a1b2c3d,event:tool_start,tool:Read} {t:5.4,agent:a1b2c3d,event:tool_end,tool:Read,duration_ms:200,success:true}先用 shell 快速定位与查看ls .omc/state/agent-replay-*.jsonl tail -20 .omc/state/agent-replay-*.jsonl再做会话级瓶颈分析。getReplaySummary会汇总时长、Agent 数量、tool_summary每个工具的 count/total_ms/avg_ms/max_ms、files_touched以及bottlenecks列表。文档定义的瓶颈规则是同一 Agent 的同一工具组合被调用 2 次以上且平均耗时超过 1 秒并按平均耗时降序排列import { getReplaySummary } from oh-my-claudecode/hooks/subagent-tracker/session-replay; const summary getReplaySummary(process.cwd(), sessionId); console.log(Duration: ${summary.duration_seconds}s); console.log(Agents: ${summary.agents_spawned} spawned, ${summary.agents_completed} completed); console.log(Bottlenecks:, summary.bottlenecks); console.log(Files touched:, summary.files_touched);bottlenecks中每一项是{ tool, agent, avg_ms }即哪个 Agent 的哪个工具平均慢了这是把第二步的单 Agent 结论扩展到全会话的方式。排查建议与已知限制文档在 Slow Agent Execution 一节针对Agent 运行超过 5 分钟、并行效率低的症状给出的处理顺序在 Observatory 中查看 bottleneck 指标复核tool_usage中的慢操作考虑把大任务拆分成更小的 Agent简单验证类任务改用architect-low而不是architect。与慢 Agent 直接相关的边界条件均来自同一文档会话结束时没有.omc/sessions/*.json摘要时先确认是正常结束让session-endhook 跑完并用/oh-my-claudecode:hud setup验证 HUD/hooks 安装需要计时证据时改用.omc/state/agent-replay-*.jsonl。Observatory 显示了实际未在运行的 Agent陈旧状态时可程序化执行cleanupStaleAgents(cwd)或删除.omc/state/subagent-tracking.json重置并检查孤儿锁文件.omc/state/subagent-tracker.lock。旧的omc-analytics、omc cost、omc backfill与analytics数据回填流程已不在当前版本中当前支持的监控面是 HUD/API 中的 Agent Observatory、.omc/state/agent-replay-*.jsonl、.omc/sessions/sessionId.json与会话结束通知。效率分只反映 Agent 活跃度不能据此判断模型能力或成本问题benchmarks/下的诊断报告也不把多维度指标合并成单一效率分。完整指标与 API 参考见 docs/PERFORMANCE-MONITORING.md核心实现可查看 Observatory 与性能统计 和 replay 记录与摘要。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考