debug

name	debug
description	当用户报告 bug、报错、崩溃、异常输出、行为不符合预期，或测试/构建失败，询问为什么失败、 哪一行出错，或要求调试、debug、定位、排查、调查、修复问题时使用。
metadata	{"openclaw":{"emoji":"🐞"}}

debug — 调试与问题定位技能

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

核心原则

1. 先复现，后定位：不能稳定复现的问题无法验证修复是否有效；复现路径必须最小化。
2. 证据驱动：以报错文本、退出码、诊断输出和 Git 变更为证据，禁止凭印象猜测。
3. 二分收敛：用 delta-debug 思想缩小嫌疑范围（注释代码段、加打印、git bisect）。
4. 不变量校验：以守恒律/不变量与边界情形（空输入、0、越界、退化情形）校验结论； "行为无报错但结果错"的常见根因是不变量被破坏。
5. 最小修复：只改导致问题的行，遵循代码库既有约定；修复与重构分离。
6. 验证闭环：修复后用原复现路径回归，再跑仓库的 lint/typecheck/test （纯 shell 仓库至少 bash -n）。
7. 循环尝试直至成功：一次修复失败不停止——回到定位阶段，基于新证据重新分析、 优化方案后再执行，循环迭代直至成功或用户终止；每次迭代都要更新终端摘要。

铁律：无根因调查，禁止修复

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

• 未完成根因调查（复现→证据→定位）之前，不得提出任何修复方案；症状修复等于失败。
• 连续 3 次修复失败时停止逐症状修复，质疑架构本身： 若每修一处就暴露新的耦合问题，说明问题在架构/模式层面而非单点代码， 与用户讨论是否重构，而非继续第 4 次盲修。
• 这个原则是调试的精神内核：过程即立场，任何一步跳过都意味着退回到猜测式调试。

红旗清单（出现即回到根因调查）

调试过程中一旦出现以下想法或话语，立即停下，回到「Step 3 缩小范围」：

红旗	含义
"先快速修一下，以后再调查"	快速修复=症状修复，第一次修复就决定后续方向
"试试改 X 看行不行"	猜测，不是假设；假设必须说明"因为 Y 所以 X"
"同时改多个地方，一起跑测试"	无法隔离哪个改动生效，且会引入新 bug
"跳过测试，手动验证就行"	未测的修复不成立；先写失败用例再修
"大概是 X 的问题，改掉它"	看到症状≠理解根因
"不太懂但这样可能行"	承认"我不懂 X"，去查证，不装懂
"再试一次就好"（已失败 2+ 次）	3 次失败=架构问题，不是运气问题
每次修复都在不同位置暴露新问题	架构耦合的证据，停止修复，质疑设计

触发时机

• 用户报告 bug："报错"、"出错"、"崩溃"、"异常"、"行为不对"、"为什么失败"、"定位问题"
• 用户明确要求调试："debug"、"调试"、"排查"、"调查"、"修 bug"、"哪一行出错"
• 测试/脚本失败："test 挂了"、"运行报错"、"exit code"、"command not found"、"Permission denied"
• 行为不符合预期但无报错：输出错误、路径错误、环境变量未生效
• 与其他技能配合：性能问题 → optim；查看引入问题的变更 → diff；修复后打标 → tag； 修复后验证 → test；初始化相关 → init； 多个独立失败（互不相关的文件/子系统）→ dispatch 并行排查（相关失败不并行， 修一个可能带好另一个时先合并调查）

工作流程

Step 1. 理解问题（先问对问题）

收集并确认以下信息，缺项时先向用户提问（所有问题在第一次交互一次性全部提出，用户一次回答，不逐次追问），不臆断：

信息项	说明
期望行为	用户期望发生什么
实际行为	实际发生了什么（含完整报错文本，不截断）
触发条件	什么命令/输入/环境触发；是否稳定复现
变更范围	问题出现前后改了什么（git status / git diff / 最近 tag 区间）
环境	shell 类型、OS、相关环境变量

Step 2. 复现并建立证据基线

1. 按用户描述复现，收集完整报错（stderr、退出码 $?）。
2. 复现不稳定时：询问触发频率与依赖条件（输入、环境变量、网络、时间）——与其余缺项一次性全部列出，不逐次追问。
3. 无法复现时：要求用户提供报错全文、诊断输出和最小示例；不跳过验证。
4. 多组件系统先加诊断插桩（CI→构建→签名、API→服务→数据库等多层场景， 修复提议之前）：对每个组件边界核对"什么数据进入该组件、什么数据离开"、 验证环境/配置是否传播、检查各层状态；运行一次收集证据，定位在哪一层断裂， 再深入调查该组件（吸收 systematic-debugging Phase 1 证据收集）。
5. 完整读取错误信息：不跳过错误与警告；栈追踪读完整，记下行号/文件路径/ 错误码——它们常包含精确解法。

Step 3. 缩小范围（二分定位）

1. 最近变更优先（有 git 时）：

git status
git diff HEAD --stat
git log --oneline -10

2. 按假设二分：
   • 注释/删除嫌疑代码段，确认错误是否消失（delta-debug）；
   • 在关键路径加诊断输出（shell 用 bash -x 逐行跟踪；应用代码用结构化输出）；
   • 验证"最近改动引入"假设：git stash 或 checkout 到上一 tag 对比行为。
3. git bisect（回归型 bug 且历史较长时）：

git bisect start
git bisect bad HEAD              # 当前坏
git bisect good <最近正常tag>     # 上次好
git bisect run <复现命令>         # 自动二分

4. shell 脚本专有排查：

bash -x <script>        # 逐行跟踪执行
bash -n <script>        # 语法检查（本库规范）
# set -euxo pipefail 脚本失败时，先定位是哪个命令退出非零

5. 不变量与边界校验（物理直觉，适用时）：
   • 量纲/类型一致性（如时间单位混用 s/ms、数值与字符串比较）；
   • 边界情形：空串、0、负数、越界索引、路径含空格/中文；
   • 极限行为：大输入、长路径、深递归、重复执行（幂等性）；
   • 环境假设：PATH、rc 文件是否被 source 干扰（对比干净环境 env -i bash 运行）。
6. 模式分析（有相似代码/参考实现时）：先找代码库中相似的工作代码作对照， 完整阅读参考实现（不跳行、不凭印象"适配"），逐项列出工作与损坏之间的 差异——不假设"这不可能有关系"，任何差异都值得验证（吸收 systematic-debugging Phase 2 模式分析）。
7. 沿调用栈向后追溯（错误深在调用栈时，吸收 systematic-debugging root-cause-tracing）：从错误点沿调用链逐层向上回溯——"谁用坏值调用了这里？ 坏值从哪来？"直至找到源头，在源头修复而非症状处打补丁；每层记录进出数据， 坏值首次出现的位置即根因候选（与二分互补：二分砍范围，追溯找源头）。
8. 超时类 bug 用条件轮询替代固定超时（吸收 systematic-debugging condition-based-waiting）：不要盲目加大 sleep——轮询真实完成条件 （文件出现/端口就绪/进程退出/明确完成输出），带超时上限与失败诊断输出：

   for i in $(seq 1 30); do [ -f done.flag ] && break; sleep 2; done
   [ -f done.flag ] || { echo "TIMEOUT: done.flag 30s 内未出现"; ps -ef | grep <task>; }
   

Step 4. 确定根因

• 根因 = 能解释全部观测证据的最小原因（奥卡姆剃刀）；
• 输出根因说明：发生了什么、为什么发生、受影响路径与范围；
• 多个候选根因时按证据强度排序、逐项验证；一次只修一处，不并排盲补；
• 单假设原则：每次只验证一个假设（"我认为 X 是根因，因为 Y"）， 测试最小改动（一次一个变量），成功→进入修复，失败→回到 Step 3 形成新假设，不叠加改动。

Step 5. 修复

• 最小改动：只改根因所在行/块；遵循代码库约定与既有 API；
• 修复与重构分离：顺手重构不属于本技能职责，除非用户要求；
• 触及系统配置（PATH、rc 文件、全局配置）前先说明意图与回滚方式，经用户同意后执行；
• 修复不得删除或覆盖用户文件，先备份或仅记录计划；
• 修复前先建立失败用例（最小复现脚本/测试），修复后用它验证闭环（红→绿）， 不留"未测修复"。

Step 6. 验证

1. 用原复现路径回归：错误消失、期望行为达成；
2. 检查边界情形：空输入、缺参数、重复执行（幂等）、路径含空格、权限位；
3. 跑仓库校验：bash -n <改动脚本>；有测试框架则运行相关测试； lint/typecheck 若存在必须运行；
4. git diff 审查：改动仅含预期内容，无引入新问题。
5. 多层防御验证（吸收 systematic-debugging defense-in-depth）：根因修复后， 在数据流各层（输入校验、中间处理、输出边界）确认坏值不再到达——单一位置 修复可能只堵住当前路径，其他入口同样可能把坏值带进来；验证修复处前后各层 的进出值一致。

Step 7. 总结（结构化输出）

✓ 修复完成
  根因:   <一句话根因>
  证据:   <支持的报错/诊断输出/复现>
  改动:   <文件:行号>  <改动说明>
  验证:   <原复现路径回归通过; bash -n 通过; 相关测试 N 个通过>

  遗留:   <未处理项/风险，无则省略>

错误处理

场景	处理
无法复现	收集更多证据（报错全文、诊断输出、最小示例），必要时向用户提问（一次问全）
报错信息不明确	提升诊断级别（bash -x、verbose、--debug），加打印定位
修复后错误仍在	回到 Step 3 检查假设是否成立，不叠加盲改
首次修复失败	不放弃、不盲改：基于新证据重新定位、优化方案后再次执行（循环尝试直至成功），并在终端摘要补充调试过程
连续 3 次修复失败	停止逐症状修复：说明架构层问题信号（每修一处暴露新耦合），与用户讨论是否重构/换方案
多次迭代仍失败	检查证据是否不足或假设方向错误；向用户报告进展与下一步计划，不无限循环
多个根因并存	逐项验证，先修证据最强的；一次只改一处
怀疑环境问题	对比干净环境（env -i bash）运行；检查 PATH/rc 干扰
用户发出"方向不对"信号（"这不是在发生吗/停下瞎猜/我们卡住了"）	停下回到 Step 3：假设未验证、证据未收集或方向错误，从新证据重新分析
编码/权限类错误	检查文件编码（UTF-8）、行尾（CRLF）、权限位
修复触及系统配置	先说明影响与回滚方式，经用户同意后执行
仓库无测试框架	纯 shell 至少 bash -n + 原复现路径手动回归

注意事项

• 不确定时向用户提问（一次问全，不逐次追问），不臆断根因；
• 调试过程以终端摘要和验证输出为准，不创建或读取过程记录文件。