bmad-run-inspector

用途

BMAD Run Inspector 用于检查与解释 bmad-loop 在 .bmad-loop/runs/ 下留下的运行产物。它面向两类问题：实时健康检查（“它卡住了吗？”“循环还活着吗？”“智能体在做什么？”）以及运行结束后的取证分析。核心目标是诚实读取证据：说明证据能证明什么，并拒绝声称证据无法支持的内容。

主要能力

• 探测运行状态：通过 run_probe.py 输出健康标志、每个任务的阶段/尝试/审查周期、心跳、日志大小、journal 尾部、ATTENTION 元数据、待处理的硬停止或优雅停止请求，以及发现列表。
• 重建叙事：通过 extract_transcript.py 提取工具调用、子智能体、错误、结果、散文和进度等部分，并报告日志中被折叠隐藏的内容量。
• 交叉核对工作树：结合 state.json 中的 baseline_commit，使用 git status --short 和 git diff --stat 检查智能体实际落地的代码，而非仅凭日志叙述。
• 判断验证结果：依据 journal.jsonl 中的 dev-decision.action、终端 journal 类型和 state.json 中的 tasks.<story>.phase 来判定故事结局，而非依赖 session-end.status。
• 异常分级：将异常分为三级——第一级需要人工立即介入，第二级即将失败，第三级是静默腐化（只有通过读取产物并随时间比较才能发现）。

使用方式

1. 先了解项目：读取 _project/bmad-loop/environment.toml 和 environment.md。若缺失，运行 python3 <skill>/scripts/bootstrap_adapter.py --repo-root /path/to/repo 生成骨架，并逐一确认所有 TODO 值。
2. 在读取磁盘前检查 CLI：优先尝试 bmad-loop list、status、diagnose、validate、adapters 和裸 mux。注意不要运行会改变状态的命令，如 mux set、confirm、decisions、attach、probe-adapter --probe、run、sweep、clean、cleanup 和 tui。
3. 探测状态：运行 python3 <skill>/scripts/run_probe.py --project /path/to/repo。实时观察时按间隔运行并比较前后快照；事后取证一次探测即可。
4. 重建叙事：运行 extract_transcript.py --section tools、--section subagents、--collapsed 等。
5. 交叉核对工作树：读取 tasks.<story>.baseline_commit，然后执行 git status --short 和 git diff --stat <baseline_commit>。
6. 判断验证是否通过：读取 journal.jsonl，按顺序检查 dev-decision.action、终端 journal 类型和 tasks.<story>.phase。

适用场景

• 实时监控 bmad-loop 运行，判断是否卡住或存活。
• 对已完成的运行进行事后取证，重建智能体行为并核对实际代码变更。
• 诊断环境问题，如多路复用器可用性、编码 CLI 是否在 PATH 中、钩子注册与陈旧性、工作树清洁度。
• 识别静默腐化：日志增长但进度计数器冻结、重复相同工具调用、延迟工作台账膨胀、积压停滞等。

限制

• .log 文件是终端重绘捕获，不是转录。每行逻辑内容会出现数百次，空白被不可预测地丢弃，长工具输出被折叠为 … +N lines (ctrl+o to expand) 且从未绘制。因此不能根据日志报告测试通过或失败，只能报告运行了哪些测试命令。
• 启发式规则与具体技术栈相关，且会静默失败。更换编码 CLI 或测试栈后，脚本不会报错，但匹配的模式会减少，仍返回结果。空的 --section errors 或 --section results 是未命中，不是好消息。
• session-end.status 不是验证结论，它只描述 CLI 会话是否正常结束。
• 故事可能停留在 story-awaiting-operator，这是终态而非卡住，只有人工运行 bmad-loop confirm <story-key> 才能清除。
• 故事升级到 story-escalated 会暂停运行，其原因文本被截断至 2000 字符，五个位置携带字节相同的截断副本，需读取故事规格的 ## Auto Run Result 部分获取未截断文本。
• || true 会吞掉失败，验证命令以 || true 结尾时总是退出 0。
• 验证每个故事运行两次，超时时会丢弃输出。
• 当 scm.isolation 为 none 时，差异位于用户的活动检出中，运行失败时这些更改会保留，且 rollback_on_failure = false 意味着不会自动清理。
• 技能已验证兼容 bmad-loop 0.11.1，脚本需要 Python 3.9+，而 bmad-loop 本身需要 3.11+。

诚实规则

• 区分“我读到的”与“我推断的”。
• 没有错误行不是成功的证据，尤其因为错误行在捕获中结构性缺失。
• 没有声明的阻塞不是没有阻塞的证据。通知被截断时，说明文本是部分的，并前往未截断来源。
• 读取有歧义时，指出能解决它的额外命令，并主动提出运行。
• 永远不要因为智能体说故事完成了就声称它完成了，要检查阶段和差异。