Code Debugger
Overview
在修改代码前先建立完整上下文关系网络，最小化变更并记录可追溯的调试文档，确保修复可验证、可回滚、可复盘。
开发环境与运行上下文（优先确认）
在执行验证、测试或 Checkfix 之前，务必确认项目的「部署-开发」架构，避免在错误环境中跑命令导致死循环或无法推进：
-
常见形态：本机 Windows 开发；WSL 内开发；内网 NAS 或云服务器上代码通过 Samba 挂载到 Windows 盘符，在本地 IDE 编辑，但实际运行/测试需 SSH 登录远程执行。
-
若无法从仓库或路径推断：主动问开发者一句，例如：「项目是否在 NAS/Samba+SSH 或远程服务器上开发？当前是怎么跑测试/构建的？」
-
若是远程/NAS-Samba+SSH 形态：
-
询问是否已有现成的 SSH 登录方式（如 ssh nas 、ssh dev 等别名或主机配置）。
-
若无，则指导用户建立公钥-私钥登录（ssh-keygen
- 将公钥写入远程 ~/.ssh/authorized_keys ），并确认项目在远程机器上的实际路径（如 /mnt/dev/xxx 、/home/user/proj ）。
-
后续验证与 Checkfix 的 shell 命令应在该上下文中执行（例如 ssh nas "cd /mnt/dev/xxx && cargo test" ），而不是在本地 Samba 映射路径下直接执行，以保障调试流畅、节省成本并防止 AI 反复无效尝试。
-
首次与用户确认后，将上述判断结果写入当前模块的 .debug 文档，作为「运行上下文/测试规则」（运行环境类型、SSH 方式、远程项目路径、验证/Checkfix 执行方式等）。后续再调用本命令时，优先从 .debug 读取该规则，不再反复询问。
Workflow
- 上下文构建
-
解析用户任务，识别涉及模块与边界。
-
使用 rg /文件浏览定位入口与相关模块，梳理调用链、变量依赖和数据流向。
-
检查 .debug/ ：若已有同模块记录则加载；若模块不同则新建，避免混杂上下文。
-
评估影响范围与潜在回归点，只改必要代码。
- 问题定位与实施
-
基于上下文网络定位根因，给出 1-2 个方案并评估风险。
-
采用最小改动原则实施修复或增量功能，保持现有架构与风格一致。
-
添加必要的边界检查和错误处理。
- 验证与记录
-
运行现有测试或提供明确的手动验证步骤。
-
Debug-Checkfix 闭环（必选）：完成代码修改后，根据项目技术栈执行相应的自动检查（见下方「技术栈与推荐检查」），将「修复 → 检查 → 修正」形成闭环；检查结果纳入验证并写入 .debug/ 。
-
更新 .debug/ 记录：问题、根因、变更、验证（含 checkfix 结果）、影响评估。
-
根据反馈迭代修复与文档。
- 文档同步与部署约束（必选）
-
前端功能变更：必须同步更新 docs/ 用户说明书，默认面向零基础用户，步骤写到可直接照做。
-
后端/API/环境变更：必须同步更新开发与部署文档，明确命令、执行顺序、预期输出、失败排查与回滚。
-
每次功能或环境更新后，必须检查既有部署指导是否需要联动修改（如 docs/DEPLOYMENT.md 、docs/README.md ）。
技术栈与推荐检查（Checkfix 闭环）
读取本 skill 的编程工具应在 debug 完成后自动考虑执行下列检查，减少开发者反复提醒的负担：
技术栈/类型 推荐检查 说明
Python 优先 uv venv
- uv sync （或 uv pip install -r requirements.txt ），并执行 ruff check . 、ruff format --check . 或 black --check .
部署优先级：uv （非 uvicorn ）> 直接部署 > conda
前端 (Node/npm) npm install （依赖变更时）、npm run lint 或 npx eslint . ，可选 npm run build
依赖与静态检查，优先用 package.json scripts
PyTorch (GPU) uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 （按目标 CUDA 版本调整） 有 NVIDIA GPU 时优先 CUDA 包，并补充 CPU 回退命令
Rust cargo check 或 cargo clippy
编译与 Clippy
Go go build ./... 、gofmt -l . 或 golangci-lint run
编译与格式/静态检查
Java/Kotlin (Maven) mvn compile 或 mvn verify
编译与测试
Java/Kotlin (Gradle) ./gradlew compileJava 或 ./gradlew check
同上
C# / .NET dotnet build 、dotnet format --verify-no-changes
编译与格式
通用 项目内已配置的 lint/format/check 脚本（如 make check 、invoke lint ） 优先执行项目既有脚本
执行原则：识别技术栈后，至少执行一类检查（lint/format/build）；若检查失败，当轮内修复并复跑直至通过或记录为技术债；结果写入验证与 .debug 记录。
文档写作标准（后端/部署）
-
读者假设：默认读者为首次接手该项目的开发者，不依赖口头传递。
-
必写要素：前置条件、环境准备、逐步命令、验证方式、常见错误处理、回滚方案。
-
文档目标：开发者仅靠文档即可完成开发、部署、验证与故障定位。
.debug 文档规则
目录与命名
-
统一放在 .debug/ 。
-
每个功能模块单独一份：.debug/<module>-debug.md 。
模块隔离
-
交叉度计算：(共享函数数 + 共享变量数 + 共享数据结构数) / 总组件数 。
-
交叉度 > 30%：合并到现有文档。
-
交叉度 < 30%：新建文档。
推荐模板（精简版）
[模块] Debug 记录
元信息
- 模块名称:
- 创建时间:
- 最后更新:
- 相关文件:
- 依赖模块:
- 用户说明书路径（涉及前端功能时）:
- 开发/部署文档路径（涉及后端或环境时）:
运行上下文与测试规则（首次确认后填写，后续优先读取此处，不再反复询问）
- 运行环境: [本机 Windows / WSL / NAS-Samba+SSH 或远程]
- SSH 方式（若远程）: [如 ssh nas、ssh user@host]
- 远程项目路径（若远程）: [如 /mnt/dev/xxx]
- 验证/Checkfix 执行方式: [如：在本地终端执行 / ssh nas "cd /mnt/dev/xxx && ..."]
上下文关系网络
- 文件结构
- 函数调用链
- 变量依赖图
- 数据流向
Debug 历史
[YYYY-MM-DD HH:MM] [任务标题]
- 问题描述
- 根因定位
- 解决方案
- 代码变更（文件/函数）
- 验证结果
- 影响评估
- 文档更新（新增/修改的 docs 文件与更新点）
待追踪问题
技术债务记录
架构决策记录（可选）
Response Format (recommended)
在开始与完成任务时，优先用以下结构输出关键信息：
任务分析
开发环境/运行上下文
[本机 / WSL / NAS-Samba+SSH 或远程；若远程，SSH 方式与项目路径如 /mnt/dev/xxx]