18
Session Debug · workflow

agent-session-debug-to-patch

18-agent-session-debug-to-patch.md
🔍
P0 source: codex-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

从一个真实 session_id 或 conversation_id 出发，还原 Agent 运行时链路，并把根因落到 patch、配置修正或文档决策。它解决的不是“代码哪里看起来有问题”，而是“这一次用户为什么失败”。

⚡

TRIGGERS

触发场景
▸用户给出 session id，问为什么不能发布、查询、展示图片、走 SSE。
▸前端看起来失败，但后端 tool call 可能已经成功。
▸route decision、capability、skill、tool schema、child run、UI 展示之间状态不一致。
▸本地代码、DB 配置、线上运行态可能不一致。
▸用户多次重试同一问题，每次失败点不同。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • session_id、conversation_id 或 run id。
  • tenant id，可从 DB 反查。
  • 相关 repo 路径。
  • DB 连接或只读查询方式。
  • 相关日志、audit table、tool call records。
  • 前端页面或用户看到的错误文案。
↗ OUTPUT
  • 运行时链路时间线。
  • 根因分层：router、capability、skill、tool discover、tool execution、child loop、final response、UI。
  • 最小修复 patch 或配置 seed。
  • Targeted regression tests。
  • DB/seed 同步说明。
  • 用户可复验步骤。
🪜

STEPS

编排步骤
  1. 1
    判定 ID 类型
    确认输入是 session、conversation、run、message 还是 tool call id，反查 tenant 和 conversation。
  2. 2
    还原消息链
    抽取用户输入、assistant 回复、route decision、child run、tool call、audit event 的时间线。
  3. 3
    判定是否进入目标能力
    看 route status、candidates、primary capability、missing inputs、confirmation 状态，不先猜 tool 后端失败。
  4. 4
    检查 capability 和 skill
    对比 DB 当前 agent skills、capability registry、本地 seed、skill files、agent instructions。
  5. 5
    检查 tool discover 和执行
    确认目标工具是否出现在 allowlist、read/write 池、sideEffectLevel、riskLevel、调用参数和返回值。
  6. 6
    检查最终收尾
    写操作成功后，确认 child loop、final LLM、timeout、assistant text 和 UI toast 是否把成功误报为失败。
  7. 7
    落 patch 或配置
    代码 bug 写 regression；配置漂移改 seed 并同步 DB；文档过期同步 docs。
  8. 8
    复验同类路径
    不用同一已完成写操作重复验证，改用未处理样本或只读状态查询。
⚙

AGENT ROLES

Agent 分工
⚙
Session Historian
定位 ID、还原消息和时间线。
⚙
Router Auditor
检查 route decision、候选和 missing inputs。
⚙
Capability Auditor
核对 capability、agent skills、seed、DB。
⚙
Tool Auditor
核对 discover、sideEffectLevel、tool result。
⚙
Patch Agent
做最小修复和 regression。
⚙
Verifier Agent
跑 DB 验证、targeted tests、用户复验路径。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⊘
如果 DB 或日志不可读，输出缺失证据，不猜根因。
⊘
如果本地代码不是线上版本，先标出版本漂移，再决定是否 pull 或查部署版本。
⤳
如果根因是 contract 跨 repo 不一致，转 →#01。
⤳
如果根因是 tool contract 不闭合，转 →#21。
⤳
如果证据显示写操作已成功但 final response 或 UI 把它误报为失败，转 →#19。
⤳
如果根因是 DB/seed/prompt 漂移导致 agent 进不去目标能力，转 →#20。
⌘

TEMPLATE

报告模板
TEMPLATE
## Session Debug Report

- Input id:
- Tenant:
- Conversation:
- User symptom:
- Route decision:
- Capability:
- Tool calls:
- Side effect result:
- Final response source:
- Root cause:
- Patch/config:
- Tests:
- Recheck path: