debugging

# Debugging（系统性调试） 家里的真实教训是猜根因、反复补症状，以及无证据把问题归咎于 runtime 没更新。诊断要回答发生了什么、为什么、修复是否有效；方法与记录格式可以按现场选择。 ## 必须做到 - 明确预期与实际差异，拿到复现、错误输出或其他能定位问题的观察证据；不能稳定复现时，说明已知条件和剩余缺口。 - 根因判断有能区分候选解释的证据。可以提出假设和小实验，但不能把猜测说成已查明，也不能只凭一次偶然成功宣称修复。 - 修复针对已查到的机制。按 `tdd` 保留可信 RED → GREEN：已有精准失败检查可复用；缺少行为保护时补回归测试。相关回归检查与影响面匹配。 - 无法稳定自动化复现时，保留可复核的手工步骤、观察结果与限制；验证未完成就如实报告。 - 诊断、修复与验证信息留在可追溯的 issue、PR、thread 或 bug report。已有记录足够时不用再抄一份。 - 实例、权限和数据隔离仍服从家规；方法选择不改变实际运行边界。 下面的方法和模板是可选参考，可以直接使用、改造或替换。无需按模型资格决定能否换方法；自检看诊断与结果是否有依据，不检查模板是否填满。 ## Runtime 状态断言：先核实对象 声称“没更新 / 没编译 / 没重启 / 还是旧代码”时，必须有对应运行证据。怀疑验证对象、版本或配置错配时，先核对实际实例，再归因。 - 未合入改动的验证使用当前 feature worktree；已合入改动按 Alpha 通道验收。`3003/3004` 默认是 runtime，不能冒充开发实例。 - 仓库 HEAD、进程启动时间、日志行数各自只是线索，不能单独证明进程已加载目标构建。结合构建/版本标识、实例日志与目标行为确认。 - 纯函数失败、明确堆栈等已经提供有效诊断路径时，可以沿证据调查，不为填表先查无关 API PID。尚未做版本核验，不妨碍说明其他已经查实的现象。 来源：2026-04-05 runtime 状态误判教训；边界见 `../.cat-cafe-shared-refs/shared-rules.md` §12、§16a。 ### 可选参考：实例取证 需要排除错实例时，可从这些线索入手。端口与路径从实际启动配置取得，不套用默认值： ```text 实例：目标 URL / API 端口 / worktree 进程：监听 PID 与启动时间 构建：实际加载的版本或构建标识，是否包含目标变更 行为：本次请求对应的日志、输出或复现结果 ``` 可用 `lsof -nP -iTCP:<实际端口> -sTCP:LISTEN`、`ps -p <PID> -o lstart=` 和目标仓库的 Git 信息协助核对；这些命令不代替构建与行为证据。 ## 可选参考：四阶段调查 需要组织调查时，可以按下面的顺序起步，也可以根据新证据返回、合并步骤或换方法。 1. **根因调查**：读完整错误和堆栈、复现条件、最近改动；多组件问题从输入/输出边界追踪状态，找出最早偏离的位置。 2. **模式对比**：找同仓可工作的路径，读相关实现，比较与失败路径的关键差异。 3. **假设实验**：写下候选原因及依据，选择能区分解释的小实验，一次尽量只改变一个因素；结果不支持就更新假设。 4. **修复验证**：确认 RED 真实覆盖问题，实现修复，复验同一信号与受影响路径；出现新症状时回查机制。 相关历史可以用 `search_evidence` 查询；已知精确代码位置则直接 Read/Grep。搜索服务当前诊断，不是每次开工固定多轮。 ### 反复失败时 多次修复没有新证据、同一状态对象反复暴露缺边，或修一处坏一处时，应停下检查当前假设、共享状态和契约。次数是警报，不是“架构有问题”的证明。 排除修复未加载、复现条件变化等解释后，若确实缺状态契约，回 `writing-plans` 补清生命周期与不变量；需要不同视角时找合适伙伴。价值取舍、权限或跨猫僵局才按决策漏斗交给 operator。 ## 可选参考：诊断胶囊与报告 [八栏诊断胶囊](../.cat-cafe-shared-refs/bug-diagnosis-capsule.md)可帮助整理复杂调查。小问题可以只记“现象 → 证据 → 假设/根因 → 修复 → 验证”，也可以直接引用已有 PR/issue。 需要独立 bug report 时可放在 `docs/bug-report/<bug-name>/bug-report.md`，保留来源、复现、根因、修复和验证；无需先写工作表、再重复写一份报告。 ## 常见误区 | 误区 | 正确做法 | |---|---| | 猜“旧 runtime”就建议重启 | 查真实实例与加载证据，重启仍走原授权边界 | | 胶囊填满就认为根因已知 | 判断依据来自复现与区分实验 | | 同时改多处后碰巧绿了 | 缩小变量，确认哪个机制解释了问题 | | 已有精准 RED 仍另造同义测试 | 复用已有信号，补它未覆盖的行为风险 | | 三次失败就断言需要重构 | 先检查竞争解释与状态契约，不用次数代替根因 | ## 下一步 根因确认后按 `tdd` 修复与验证；交付时用与当前声明相匹配的 `quality-gate` 自证。仍未解决时留下证据、剩余假设和可行动的下一步。