debug

调试诊断 (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: 复现与信息收集

1. 解析错误信息，提取关键信号: 文件路径、行号、异常类型、错误消息
2. 如有复现命令，执行以确认问题可复现
3. 如错误信息不完整（缺少 stacktrace 或文件路径），通过 AskUserQuestion 请求补充（每批问题数不超过 MAX_QUESTIONS_PER_BATCH）

Step 2: 定位根因

1. 从 stacktrace 最内层帧开始，Read 相关文件和行号
2. 向调用链上游追溯，理解数据流和控制流
3. 识别根因类别:
   • 编码/环境: 字符编码、路径分隔符、平台差异、语言运行时版本
   • 数据/类型: 空值、类型不匹配、格式解析错误、边界条件
   • 依赖/配置: 缺失依赖、版本不兼容、配置错误
   • 逻辑: 算法错误、状态管理、竞态条件
4. 形成根因假设并通过代码阅读或小范围测试验证

Step 3: 应用修复

1. 使用 Edit 工具应用最小化修复（只改必要的代码）
2. 如修复模式适用于多个文件，使用 Grep 扫描同类问题并一并修复
3. 确保修复不改变公共接口行为（如需改变，返回 needs_input）

Step 4: 回归验证

1. 重新执行触发错误的命令，确认问题已修复
2. 运行相关测试套件（如有），确认未引入新失败
3. 如无自动化测试，手动验证关键路径

Step 5: 总结

1. 输出执行摘要: 根因（一句话）、修复措施、验证结果、同类修复（如有）

指令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 复杂度指数上升
• 避免: 一次改多个变量再跑验证 —— 失败时无法定位是哪个改动生效，回到二分查找