workflow_error_recording

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/workflow_error_recording.md</code> 的逐字投影（仅隐私清洗，零改写）。

name: workflow_error_recording
description: 多 provider、长链路、多目标、多 domain 任务执行中的错误记录与复用方法论（道）。遇到错误时按统一两轴 taxonomy（category × signal_source）分类、把「问题 + 解决办法」记进一个持久跨域 append-only 台账、再遇相似问题先 query 取回既有 resolution——把「遇到问题→记录→后续查阅复用」闭合，避免重复踩坑。扎根六次 buildout run 的 23 个真实错误。配套确定层工具 tools/error_ledger/（record/query/schema），记录/查询由干净 context 的专门 sub-agent 承担。
type: Workflow（道层 / 运行时错误治理方法论）
status: draft (Beta) — 晋级前需在 ≥1 次真实多 provider 运行里按本 skill 记录+查询并过 dogfood 两层 oracle，证据到 bounded 以上
created: 2026-06-30
version: 0.1.0 (draft)

错误记录与复用：记问题、记办法、先查后做

一句话

多 provider 长链路运行里错误是常态（六次 buildout run 实测 23 个，provider 类占 15）。把每次错误连同解决办法记进一个持久、跨域、append-only 的统一台账，下次遇到相似问题先查台账拿既有解决办法——让运行系统化、不重复踩同一个坑（用户原话：「一旦遇到问题，就把问题记录下来，方便后续查阅。同时，也要在记录中提到解决方法」）。记录与查询交给一个干净 context 的专门 sub-agent。

何时用

• 多 provider（Claude / Codex / Kimi / GLM / OpenCode）、长链路（多 phase 多 step）、多 domain 任务执行中遇到错误：provider 不可用 / 工具失败 / 编排失败 / 静默无产出。
• 遇到一个问题，想先查「这类问题过去怎么解决的」。
• 判一条错误记录是否良构（分类对不对、有没有解决办法、证据锚全不全）。

非 trivial 单步任务不必。纯代码单元 bug 走 BUG_TRACKER（git 域持续 bug）/ pytest，不走本机制（本机制记运行时一次性 error 事件，见边界）。

核心原则（扎根六次 run 实证）

1. 两轴分类，silent 是盲区。错误按 category（性质：provider/工具/编排/环境，9 类封闭词表）× signal_source（怎么暴露：http_hard 有错误码 / router_soft 路由器分类 / silent 无错误码无报错但零有效产出）两轴定位。silent 类（零字节 JSON、0-turn 冒充推理、进程 stall、context 截断）是既往记录最大盲区——它没有错误码，必须靠间接信号（超时、产物形态、modelUsage 对账）主动判读才记得下来。分类真源 design/error_taxonomy.md（在 adhoc_jobs/error_recording_mechanism_20260630/）。遇阻当场的动作阶梯分类见 workflow_manage_unexpected；本 skill 的 category×signal_source 是事后记录分类，两者互补不重叠。

1. 记录必带解决办法。一条只记「发生了什么」不记「怎么解决的」的记录无法复用——避免重复踩坑靠的正是 resolution 字段。每条记 resolution + resolution_status（resolved/workaround/waived/unresolved/deferred）；当下没解决就显式标 unresolved，不留空冒充已处理。

1. 持久跨域单一台账，不每 run 重造。既往六次 run 的教训：r002 建 MODEL_DEVIATION_LEDGER、r003 另建 PROVIDER_GAP_MATRIX，每 run 各自重造结构、跨 run 查不到。统一台账 contexts/runtime/error_ledger/errors.jsonl 一处 append，跨 run 跨 domain 跨 session 持久，recurrence 字段把跨 run 复发模式（kimi_ollama_stall / wrong_family_fallback / glm_quota_limit / opencode_completion_detection）串起来可聚合查询。

1. 与现有手段 interoperate 不重复（SSOT）。receipt_id 引用 receipts.jsonl 的 TR-NNN（raw exit_code/error 留在 receipts，不复制），台账只加 receipts 没有的三样：provider 归因、解决办法、长链路 step 定位（chain_step）。git 域持续 bug 仍走 BUG_TRACKER，台账记运行时事件。

1. 先查后做。遇到错误第一步不是硬刚，是 query 既有 resolution——命中就复用过去验证过的办法（如 GLM quota → 切 Ollama Cloud repair），无命中再现场解决并记录新条目。

操作流程（记录 / 查询两条，派给干净 context sub-agent）

记录一条错误：

1. 分类：判 category（对照 taxonomy 9 类）+ signal_source（http_hard/router_soft/silent）。
2. 落账：python3 tools/error_ledger/record.py --category ... --signal-source ... --provider ... --chain-step ... --what "<逐字现象>" --evidence <file:line> --resolution "<怎么解决>" --resolution-status ... --recurrence ... --receipt-id TR-NNN。多 provider 长链路场景 provider + chain_step 必填（否则跨 provider 归因失效）。
3. 工具自动分配 error_id + ts，append 不覆盖。

查询既有解决办法：

1. python3 tools/error_ledger/query.py --category provider_quota --provider claude-zai（按性质+provider）或 --recurrence kimi_ollama_stall（按复发模式）或 --keyword "Not logged in"（跨字段子串）。
2. 取回匹配行的 resolution，复用或据此现场解决。无命中则记一条新的。

两个动作都交给一个干净 context 的记录/查询 sub-agent（REQ-06）：主 session 把错误现象 / 待查问题给它，它不拿主 session 的成功叙事，只按操作指南分类→record 或 query→回报 error_id+分类 或 既有 resolution。完整操作指南 = adhoc_jobs/error_recording_mechanism_20260630/reports/ERROR_RECORDING_AGENT_OPERATION_GUIDE.md。

验收标准（一条错误记录是否良构）

无上下文 agent 据这几条也能判：

• category + signal_source 在封闭词表内（非法值 record 工具会 fail-fast）。
• what 是逐字现象（有 raw message 抄原文，不转述）。
• resolution + resolution_status 非空，或显式 unresolved（不留空冒充已处理）。
• evidence 有锚（file:line 或 raw JSON 路径）。
• 多 provider / 长链路场景：provider + chain_step 必填。
• 有对应 receipt 时 receipt_id 对接 TR-NNN，不复制 raw error。
• 任一条缺 = 这条记录将来查不回来或不可复用。

可用资源

• 确定层工具：tools/error_ledger/（record.py 记 / query.py 查 / schema.py 封闭词表+校验+台账 I/O 唯一真源），路径查 tools/INDEX.md。
• 统一台账：contexts/runtime/error_ledger/errors.jsonl（持久 append-only）。
• 分类真源：adhoc_jobs/error_recording_mechanism_20260630/design/error_taxonomy.md（9 category × 3 signal_source + recurrence 模式 + 与既往结构 subsume 映射）。
• 架构/schema：adhoc_jobs/error_recording_mechanism_20260630/design/architecture.md。
• 实证来源：adhoc_jobs/error_recording_mechanism_20260630/research/research_{A,C}_*.md（六次 run 23 错误 + provider 三分类）。
• 道层联系：[[workflow_buildout_real_session_eval]]（平行兄弟测试机制，dogfood 本机制）/ [[workflow_manage_unexpected]]（遇阻动作阶梯，记录前先按它系统尝试）/ [[workflow_tool_receipt_discipline]]（receipt 对接）。

诚实 claim ceiling / 缺口

• 证据等级 bounded（设计 + 工具落地 + dogfood 1 case）：taxonomy 扎根六次 run 23 个真实错误（强实证），record/query 工具 smoke + dogfood 过一条真实错误。未经大规模真实多 provider 运行长期采用验证。
• 不实现 UR-2 自动恢复探测回路（额度耗尽→等刷新→探测→续跑）——属运行时控制回路，本机制只记 quota 错误 + 已知解决办法，回路 deferred。
• 不自动 hook 捕获（运行时自动写入留后续切片）；本轮 record 由 sub-agent / 主 session 显式调用，schema 已含 receipt_id/task_id 锚兼容未来 hook。
• 既往 run 内快照（MODEL_DEVIATION_LEDGER 等）本轮不批量回填进统一台账，留后续 run。