debug

Debug

用途

该技能用于调查卡住的运行与执行失败，目标是：找出某次运行为何卡住、反复重试或失败；快速将 Linear 问题身份与 Codex 会话关联；按正确顺序读取正确的日志以隔离根因。

日志来源

主运行时日志：log/symphony.log，默认来自 SymphonyElixir.LogFile（log/symphony.log），包含编排器、agent runner 和 Codex app-server 生命周期日志。

轮换运行时日志：log/symphony.log*，当相关运行时间较早时检查这些文件。

关联键

• issue_identifier：人类可读的工单键（示例：MT-625）。
• issue_id：Linear UUID（稳定的内部 ID）。
• session_id：Codex thread-turn 对（<thread_id>-<turn_id>）。

elixir/docs/logging.md 要求 issue/session 生命周期日志包含这些字段。调试时应将它们作为连接键使用。

快速分类（卡住的运行）

1. 确认该工单的调度器/worker 症状。
2. 查找该工单的近期日志行（优先用 issue_identifier）。
3. 从匹配行中提取 session_id。
4. 跨启动、流式、完成/失败以及停滞处理日志追踪该 session_id。
5. 判定失败类别：超时/停滞、app-server 启动失败、turn 失败或编排器重试循环。

命令

1) 按工单键缩小范围（最快入口）

rg -n "issue_identifier=MT-625" log/symphony.log*

2) 如需要，按 Linear UUID 缩小范围

rg -n "issue_id=<linear-uuid>" log/symphony.log*

3) 拉取该工单出现过的 session ID

rg -o "session_id=[^ ;]+" log/symphony.log* | sort -u

4) 端到端追踪单个会话

rg -n "session_id=<thread>-<turn>" log/symphony.log*

5) 聚焦卡住/重试信号

rg -n "Issue stalled|scheduling retry|turn_timeout|turn_failed|Codex session failed|Codex session ended with error" log/symphony.log*

调查流程

• 定位工单切片：按 issue_identifier=<KEY> 搜索；若噪声较多，追加 issue_id=<UUID>。
• 建立时间线：找出首个 Codex session started ... session_id=...，随后跟随 Codex session completed、ended with error 或 worker exit 行。
• 问题分类：停滞循环（Issue stalled ... restarting with backoff）；app-server 启动（Codex session failed ...）；turn 执行失败（turn_failed、turn_cancelled、turn_timeout 或 ended with error）；worker 崩溃（Agent task exited ... reason=...）。
• 验证范围：检查失败是仅限单个 issue/session，还是跨多个工单重复出现。
• 保留证据：保存关键日志行，包含时间戳、issue_identifier、issue_id 和 session_id；记录可能的根因与确切的失败阶段。

读取 Codex 会话日志

在 Symphony 中，Codex 会话诊断信息输出到 log/symphony.log，并以 session_id 为键。应按生命周期读取：

1. Codex session started ... session_id=...
2. 同一 session_id 的会话流/生命周期事件
3. 终态事件：Codex session completed ...，或 Codex session ended with error ...，或 Issue stalled ... restarting with backoff

针对单个具体会话调查时，保持追踪范围狭窄：

• 为工单捕获一个 session_id。
• 仅针对该会话构建带时间戳的切片：rg -n "session_id=<thread>-<turn>" log/symphony.log*
• 标记确切失败阶段：
  • 流事件之前的启动失败（Codex session failed ...）。
  • 流事件之后的 turn/运行时失败（turn_* / ended with error）。
  • 停滞恢复（Issue stalled ... restarting with backoff）。
• 将发现与附近行的 issue_identifier 和 issue_id 配对，确认没有混淆并发重试。务必将会话发现与 issue_identifier/issue_id 配对，以避免混淆并发运行。

注意事项

• 在大日志上优先使用 rg 而非 grep，以获得速度。
• 在断定数据缺失之前，检查轮换日志（log/symphony.log*）。
• 如果新日志语句缺少必需上下文字段，请与 elixir/docs/logging.md 的约定保持一致。

适用场景与限制

适用场景为 Symphony 运行时出现运行停滞、反复重试或执行失败时的故障定位与根因分析。该技能依赖已产生的日志文件与约定的关联字段；日志来源、路径与命令均按官方说明使用。其他功能细节、收费与平台信息暂未提供。