| name | debug |
| description | 调试诊断 — 结构化错误定位、根因分析、最小化修复与回归验证。当用户报告运行时错误 / stacktrace / 测试失败 / 脚本异常 / testing 阶段缺陷清单待修复时使用此 skill。本 skill 处理已知症状的根因定位与最小修补；新功能开发循环由 tdd-engine 负责，新测试编写由 testing 负责。 |
| argument-hint | <错误信息或stacktrace> |
| suggested-tools | file_read, file_edit, file_glob, file_grep, shell_exec |
| depends | ["context"] |
| disable-model-invocation | false |
| user-invocable | true |
调试诊断 (debug)
能力边界
- 能做: 分析错误/stacktrace、定位根因、应用最小修复、回归验证、检查同类问题
- 不做: 功能开发、性能优化、架构重构、需求变更
输入规范
调用方提供以下信息（至少一项）:
- 错误信息 / stacktrace
- 触发命令或复现步骤
- 期望 vs 实际行为描述
输出规范
- 修复后的文件（就地修改）
- 回归验证结果（测试通过或命令成功）
- 执行摘要: 根因 + 修复措施 + 验证结果
操作指令
语言细则: 根据 framework.json project.languages，按需载入本 skill references/lang-<lang>.md（仅 active 语言，逐个 Read），获取对应语言的调试诊断细则（调试器使用、traceback 解读、日志实践、运行时问题定位）。与本 skill references/debug-patterns.md（scan-similar 的特征模式范例）分工：lang-.md 为完整调试细则，debug-patterns 为同类扫描的模式库。
指令1: 完整调试流程 (full)
适用于: 收到错误报告，需要从零开始诊断和修复。
Step 1: 复现与信息收集
- 解析错误信息，提取关键信号: 文件路径、行号、异常类型、错误消息
- 如有复现命令，执行以确认问题可复现
- 如错误信息不完整（缺少 stacktrace 或文件路径），通过 AskUserQuestion 请求补充（每批问题数不超过 MAX_QUESTIONS_PER_BATCH）
Step 2: 定位根因
- 从 stacktrace 最内层帧开始，Read 相关文件和行号
- 向调用链上游追溯，理解数据流和控制流
- 识别根因类别:
- 编码/环境: 字符编码、路径分隔符、平台差异、语言运行时版本
- 数据/类型: 空值、类型不匹配、格式解析错误、边界条件
- 依赖/配置: 缺失依赖、版本不兼容、配置错误
- 逻辑: 算法错误、状态管理、竞态条件
- 形成根因假设并通过代码阅读或小范围测试验证
Step 3: 应用修复
- 使用 Edit 工具应用最小化修复（只改必要的代码）
- 如修复模式适用于多个文件，使用 Grep 扫描同类问题并一并修复
- 确保修复不改变公共接口行为（如需改变，返回 needs_input）
Step 4: 回归验证
- 重新执行触发错误的命令，确认问题已修复
- 运行相关测试套件（如有），确认未引入新失败
- 如无自动化测试，手动验证关键路径
Step 5: 总结
- 输出执行摘要: 根因（一句话）、修复措施、验证结果、同类修复（如有）
指令2: 快速修复 (quick-fix)
适用于: 根因已明确（如用户已定位到具体文件和行），剩余动作仅为应用修复和验证。
Step 1: Read 相关文件确认问题
Step 2: 应用修复（Edit）
Step 3: Grep 检查同类问题并一并修复
Step 4: 回归验证（Bash 运行命令/测试）
Step 5: 输出摘要
指令3: 同类扫描 (scan-similar)
适用于: 已修复一个问题，需要检查整个项目中是否存在同类问题。
Step 1: 从已修复的问题中提取特征模式（如未显式声明编码的文件读写、未转义的正则元字符；语言特定示例见 debug-patterns.md）
Step 2: 使用 Grep 在项目范围内搜索该模式
Step 3: 逐一检查匹配项，判断是否存在同类问题
Step 4: 对确认存在问题的文件应用修复
Step 5: 汇总扫描结果: 检查了 N 个文件，修复了 M 个
常见问题模式库
语言/平台特定的症状—修复对照（Python/Windows 等）见 debug-patterns.md，新增语言在该文档增条。
Anti-Patterns
- 禁止: 修复表面 symptom 而不查 root cause —— 让最近一次报错消失不等于修了 bug，root_cause 可能在两层调用栈以上
- 禁止: 改测试让它通过而非改实现 —— 测试是契约，把红灯绿掉是把契约改成了已坏状态的快照
- 禁止: 静默
catch + pass 吞异常 —— 信号被埋掉后续 debug 复杂度指数上升
- 避免: 一次改多个变量再跑验证 —— 失败时无法定位是哪个改动生效，回到二分查找
效率策略
- stacktrace 最内层帧优先 — 80% 的问题在最内层 1-2 帧
- 修复前先 Grep 同类 — 避免修一个漏一个，减少反复调试
- 就地验证 — 修复后立即运行，不等到所有文件都改完
