| name | code-bug-hunter |
| description | 查找、复现、根因分析、排序和修复代码 bug。Use when Codex is asked to locate or modify bugs, 根因分析, 复现问题, 别瞎猜, 逻辑错误, 数据处理缺陷, 深度学习框架问题, 爬虫故障, 网站/前端/后端问题, 小程序 bug, 安全漏洞, flaky tests, regressions, or GitHub-style bugfix patterns in code. |
Code Bug Hunter
用于审计代码库、定位可疑 bug、证明根因、修复真正源头，并用测试或复现路径验证结果。这里的 bug 包括：逻辑错误、边界条件、数据污染、竞态、依赖/API 变化、安全漏洞、爬虫漏采/重复采、深度学习训练异常、前端状态错乱、小程序生命周期问题，以及会破坏行为的性能或稳定性问题。
铁律
未完成根因调查前，不得提出或实施修复。可疑代码只是线索，必须经过复现、证据、测试、日志、静态分析或代码路径推理确认后，才能称为 bug。
任务模式
- 已知故障/报错/异常现象：先复现，再追根因，最后修复。不要一开始就大范围扫描，除非复现被阻塞。
- 宽泛审计/“找所有 bug”：先识别项目栈、入口、测试、CI、数据流和高风险模块；运行启发式/静态扫描；按严重程度排序；逐个用证据确认。
- 只做 review：只输出可执行发现和文件/行号，不修改代码。
- 要求修复：优先创建失败测试、最小复现、一次性验证脚本或明确的手动复现记录，再修改行为。
四阶段工作流
- 根因调查
- 完整阅读错误、警告、stack trace、日志、失败断言、坏输出或用户可见症状。
- 用最窄命令、测试、页面、脚本、notebook cell、API 请求或真机/模拟器路径稳定复现。
- 检查近期 diff、依赖版本、配置、环境、平台、数据、权限和部署差异。
- 沿调用链和组件边界反向追踪坏值，直到找到最初触发点。
- 多组件系统要在边界收集证据：输入、输出、状态、配置/env 传递、重试和副作用。
- 模式分析
- 在同仓库找相似且正常工作的实现，对比生命周期、输入归一化、校验、缓存、清理和副作用。
- 阅读相关框架、库或上游实现，确认正确模式；不要凭印象改。
- 列出依赖、隐含假设、数据契约、权限、平台 API 和外部服务。
- 假设与最小验证
- 写清楚一个假设：
我认为 X 是根因，因为 Y；我将用 Z 验证。
- 每次只验证一个变量，不叠加多个猜测性修复。
- 假设失败就带着新证据回到根因调查。
- 实施与验证
- 增加或更新一个修复前会失败的最小回归测试/复现。
- 修复根因，不只修症状；避免顺手重构和无关美化。
- 先跑聚焦验证，再跑更广的测试、lint、类型检查、build、浏览器/真机检查。
- 如果 3 次修复尝试失败，或每次修复都暴露新的耦合问题，停止并质疑架构。
严重程度排序
先处理会造成真实损害或阻断验证的项：
- P0：权限绕过、数据破坏、远程代码执行、密钥泄露、不可逆生产副作用、主流程完全不可用。
- P1：高概率安全漏洞、严重数据错误、训练/推理结果系统性错误、爬虫大面积漏采/重复采、线上功能阻塞。
- P2：普通逻辑错误、边界条件、状态竞态、flaky 测试、局部性能导致的行为错误。
- P3：诊断不足、潜在风险、可维护性导致的未来 bug、低影响 TODO/FIXME。
排序时同时考虑：影响面、可达性、复现概率、数据/安全风险、用户可见度、是否有测试保护。
资源使用
- 运行
python scripts/repo_bug_triage.py <repo> 获取按领域和严重程度分组的轻量线索。
- 加
--json 可输出结构化结果，便于后续自动排序、报告或二次分析。
- 读
references/case-patterns.md 获取真实场景微案例，特别适合数据处理、ML、爬虫、前端和小程序 bug。
- 读
references/bug-patterns.md 获取领域清单、根因模板、排序规则和输出模板。
- 读
references/debugging-playbook.md 处理深层调用栈、flaky、race、多组件和容易 quick fix 的问题。
- 读
references/frontend-mini-program.md 处理网站、前端框架、SSR、水合、小程序生命周期和真机差异。
领域排查
- 核心逻辑：off-by-one、布尔优先级、共享可变状态、默认值错误、缓存失效、时间/单位/排序、吞错、部分失败。
- 数据处理：schema 漂移、dtype 推断、缺失值、重复 key、join 行数膨胀、训练/测试泄露、编码、分块聚合。
- 深度学习/ML：shape broadcasting、CPU/GPU device、dtype、train/eval、梯度、seed、checkpoint、label/loss、分布式同步。
- 爬虫：timeout/retry、分页死循环、漏页/重复 URL、选择器脆弱、编码/cookie/session、robots/rate limit、解析安全。
- 网站/后端/前端：注入、XSS、CSRF、SSRF、鉴权绕过、重定向、状态陈旧、hydration mismatch、未处理 promise。
- 小程序：
onLoad/onShow 竞态、setData 大对象/频率/嵌套路径、dataset 类型、页面栈、权限、域名限制。
GitHub 案例迁移
当用户要求参考 GitHub 或真实开源修复时：
- 搜索对应库的 issue、PR、changelog、advisory、CodeQL 示例和框架 release note。
- 优先使用一手来源：项目仓库、官方文档、安全公告、GitHub Security Lab、CodeQL query help。
- 提炼模式而不是照抄补丁：触发条件、错误假设、修复后新增不变量、回归测试形状。
- 检查本地 API、版本和架构后再迁移。
输出要求
修复类任务结尾必须包含：
- 根因和证据。
- 已修复 bug，按严重程度排序。
- 修改文件和原因。
- 运行的测试/命令及通过或失败状态。
- 剩余风险、未验证部分或假设。
无法复现或未能修复时，说明已排除项、当前最佳假设、下一步需要的证据。审计类、失败修复类和安全类任务的详细模板见 references/bug-patterns.md。
