用途
code-debug-skill 是一个 Bug 调查技能，适用于问题已经发生、但原因尚不清楚的场景。它的核心目标是通过收集决定性证据来确认根因，而不是凭猜测修改代码。该技能强调“调查思维”：始终以事实为主，明确区分观察到的现象与推断出的结论；同时保留多个相互竞争的假设，并按可能性与影响对它们进行排序。
主要能力
- 假设驱动调查：为每个假设定义三项内容——预测（若假设为真必须观察到什么）、反证条件（什么情况会推翻它）、所需观测手段（需要测量或记录什么）。
- 对比与二分缩小：通过“失败 vs 通过”的对比，以及尽可能采用二分搜索式的方法缩小范围。
- 单次复现捕获充足信号：假定每次复现成本高昂，因此会一次性添加足够的调试埋点，以便在不追加复现的情况下缩小根因。
- 禁止投机性修复：在有任何生产代码改动之前，必须先以证据确认根因。
使用方式
该技能使用本地 HTTP 日志收集器作为新埋点的首选工具（debugsk）。使用流程包括：
- AI 在埋点前先执行
npx debugsk@latest server start --json启动服务器，并从 JSON 输出中复制代码片段和端点。 - AI 自动生成 sessionId/runId，并直接嵌入到埋点代码中，不要求用户通过控制台设置。
- 如果可以复现，优先记录能直接检验预测的日志/指标；如果无法复现，则转向已有信号，如日志、指标、链路追踪、配置差异、数据快照、转储以及确定性探针。
- 当原生信号不足以回答问题时，优先使用 debugsk 获取新观测，以避免污染原生日志，同时将原生日志作为参考。
核心循环为：精确澄清 Bug（环境、版本/提交、频率、影响、最小复现步骤、预期与实际、错误与时间戳）→ 识别候选代码路径（按端点/路由/功能/配置键/错误文本搜索，映射请求→处理器→数据/依赖）→ 至少生成三个假设（客户端/输入、服务端逻辑、数据/状态、并发、配置、依赖、资源等）→ 启动调试服务器并生成 ID → 添加埋点验证假设 → 执行受控复现 → 收集并分析日志，对比成功与失败运行，偏好二分缩小，迭代直到确认根因。
适用场景
- 已发生但原因未知的 Bug 排查。
- 难以复现或复现成本高的问题定位。
- 需要在不污染生产日志的前提下捕获调查用信号。
- 本地、预发（staging）或生产环境中的缺陷调查。
限制与约定
- 埋点日志必须永不抛异常，避免记录机密与个人身份信息（PII），并且易于移除。
- 每条日志事件必须始终包含全部字段：timestamp、message、sessionId、runId、hypothesisId、location，不得省略任何字段。
- 不得用环境变量开关来保护埋点；调查期间写入日志，完成后移除。
- 用户只执行无法自动化的 UI 操作（点击、拖拽、填写表单等），不执行控制台命令或文件操作；服务器启动、ID 生成、日志收集与分析均由 AI 完成。
- 在埋点计划就绪前，不应要求用户复现。
- 清理策略：当用户确认问题已解决或调查关闭后，停止调试服务器并删除所有调查日志（如 .logs/）；不得使用 git checkout、git clean 等批量 git 清理来删除日志，应显式且安全地移除文件；若删除可能影响无关文件，需先确认确切路径。
- 报告格式使用 assets/report-template.md 中的模板，标题为双语（英语/日语），内容使用用户的语言。
- 参考文档：添加或验证埋点时使用 references/logging-schema.md；组织假设与预测时使用 references/hypothesis-template.md。