Bug Hunter — 结构化调试协议

版本: 1.1.0 | 作者: Shadows Company | 许可证: MIT

触发时机

• 运行时错误、异常、堆栈跟踪（stack traces）
• UI 渲染问题或视觉类缺陷（visual bugs）
• 近期变更后出现的回归问题（regression）
• 用户明确提出 “debug”、“fix this bug”、“it's broken”、“not working” 等请求
• 测试失败且根因不明确
• 性能下降

不触发时机

• 功能需求（应使用 brainstorming 技能）
• 代码风格 / 格式问题
• 明显可修复的简单拼写错误

前提条件

必需项：

• git — 在 Triage 步骤中用于通过 git log --oneline -10 检查最近变更。检测方式：which git 或 git --version。

可选项（按项目自动检测）：

• pytest — Python 测试运行器，用于 Technique 4。通过 python -m pytest --version 或是否存在 pytest.ini / pyproject.toml [tool.pytest] 检测。
• jest — JavaScript 测试运行器，用于 Technique 4。通过 npx jest --version 或是否存在 jest.config.* 检测。
• vitest — 基于 Vite 的测试运行器，用于 Technique 4。通过 npx vitest --version 或是否存在 vitest.config.* 检测。

若未检测到任何测试运行器，则 Technique 4（Test-Driven Fix）仅限于编写测试文件——执行需延后处理。

协议 — 四种技术

选择具体技术前，必须首先执行 Triage：

Triage（强制执行 — 最长 60 秒）

1. 完整阅读错误信息 — 它实际表达了什么？
2. 问题何时开始出现？ 检查近期 git 变更：git log --oneline -10
3. 是否可复现？ 尝试一次失败操作
4. 分类严重程度：崩溃（Crash）/ 错误结果（Wrong result）/ 视觉问题（Visual）/ 性能问题（Performance）

根据 Triage 结果，选择最适用的技术：

Technique 1 — 日志注入（Log Injection）（最适合：后端逻辑、数据流、异步问题）

1. 在关键决策点插入策略性 console.log / print()
2. 记录可疑函数的输入 AND 输出
3. 运行失败场景
4. 通过日志定位“预期值 ≠ 实际值”的位置
5. 修复根本原因
6. 清理（CLEANUP）：提交前必须移除所有调试日志

[LOG] function_name() called with: {params}
[LOG] function_name() returned: {result}
[LOG] condition_check: variable = {value}

警告：该技术会临时修改源文件。所有注入的调试代码必须在任何提交前彻底移除。详见下方 CLEANUP GUARANTEE。

Technique 2 — 截图分析（Screenshot Analysis）（最适合：UI 缺陷、布局问题）

1. 截取或描述当前（异常）状态
2. 明确“应显示内容”与“实际显示内容”的差异
3. 自上而下检查组件树（component tree）
4. 核查：CSS 特异性（specificity）、z-index、overflow、flexbox/grid 对齐方式
5. 修复样式或渲染逻辑
6. 在断点尺寸下验证：375px、768px、1024px、1440px

Technique 3 — 手动追踪（Manual Trace）（最适合：逻辑错误、算法缺陷）

1. 逐行阅读出错函数
2. 手动计算每一步的预期值
3. 定位预期与现实发生偏差的确切行号
4. 检查边界情况：null、undefined、空数组、零值、负数
5. 修复逻辑，并为该边界情况补充测试

Technique 4 — 测试驱动修复（Test-Driven Fix）（最适合：回归问题、复杂交互）

1. 首先编写一个复现该缺陷的失败测试
2. 运行测试确认其失败：python -m pytest {test_file} -x -q 或 npx jest {test_file} 或 npx vitest run {test_file}
3. 修复代码直至测试通过（绿色状态）
4. 运行完整测试套件以检查是否引入新回归：python -m pytest -x -q 或 npx jest 或 npx vitest run
5. 如有必要，进行重构（refactor）

注意：Technique 4 将执行项目自身的测试套件，即运行仓库中的代码。仅可在可信仓库中使用，或在沙箱（sandbox）环境中执行。

流程

TRIAGE → SELECT TECHNIQUE → INVESTIGATE → HYPOTHESIZE → FIX → VERIFY → CLEANUP

修复后验证清单

• 原始缺陷已修复
• 未引入新错误
• 现有测试全部通过
• 已清除所有调试产物（日志、console.log、print、debugger、TODO 等）
• 已覆盖相关边界情况

CLEANUP GUARANTEE（清理保障）

每次修复完成后，代理必须执行最终验证环节：

1. 在已修改文件中搜索调试标记：grep -n "\[LOG\]|console\.log|print(|debugger|# DEBUG|// DEBUG" {modified_files}
2. 移除所有残留的调试产物
3. 确认工作区（working tree）中无任何注入的调试代码，方可报告完成

该步骤不可协商，适用于全部四种技术，而不仅限于 Technique 1。

规则

1. 先阅读，再猜测 — 始终阅读真实错误信息，切勿主观假设
2. 一次只改一处 — 每次仅变更一项，测试通过后再继续
3. 修复根因，而非表象 — 解决“为何出错”，而非仅掩盖表面症状
4. 禁止霰弹式调试（shotgun debugging） — 不得随机修改多处代码、寄希望于“碰巧修好”
5. 务必清理 — 提交前必须移除所有调试代码
6. 回归测试 — 必须添加测试用例，防止同一缺陷再次出现

安全考量

• 执行的命令：git log（只读）。Technique 4 运行项目测试套件（pytest、jest、vitest），将执行仓库中的代码。
• 读取的数据：本地仓库中的源文件。
• 文件修改：Technique 1（Log Injection）会临时修改源文件以注入调试语句。所有注入代码必须在提交前彻底移除（参见 CLEANUP GUARANTEE）。
• 网络访问：无。
• 持久化：无。
• 凭据：无需任何凭据。
• 沙箱（Sandboxing）：在非可信仓库中使用 Technique 4 时，强烈建议启用沙箱环境，因其测试执行会运行任意项目代码。

输出格式

## Bug Report
- **Error**: [精确的错误信息]
- **Severity**: [Crash/Wrong Result/Visual/Performance]
- **Reproducible**: [Yes/No + 复现步骤]

## Root Cause
[缺陷发生原因的解释]

## Fix Applied
[修复描述，含 file:line 引用]

## Verification
- [x] 原始缺陷已解决
- [x] 所有测试通过
- [x] 无残留调试产物

发布方：Shadows Company — “我们于暗影中工作，只为服务光明。”