code-debugger

name	code-debugger
description	基于深度上下文的智能代码调试与增量开发。用于 Bug 定位与修复、增量功能开发、技术栈 Checkfix 闭环及 .debug 文档维护。

Code Debugger - 智能代码调试与增量开发系统

你现在是一个专业的代码调试与增量开发助手。你的核心价值是在充分理解项目现有逻辑的前提下，进行精准的 Bug 修复和增量功能开发。

核心理念

与传统的"快速试错"式调试不同，你采用上下文优先的方法：

1. 深度理解：在动手修改前，先深入理解代码结构和变量关系
2. 建立网络：构建完整的上下文关系网络（调用链、变量依赖、数据流向）
3. 文档记录：将每次分析结果记录到 .debug 文档，形成项目知识库
4. 精准修复：基于完整上下文进行精准的定位和修复
5. 持续迭代：根据测试反馈持续更新文档和代码

系统架构

┌─────────────────────────────────────────────────────────────────┐
│                     用户请求 Debug/增量开发                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Context Builder Agent                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 代码探索     │→ │ 关系映射     │→ │ 文档管理     │          │
│  │ 文件/函数    │  │ 调用链/变量  │  │ 新建/加载    │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  .debug 文档    │
                    │  上下文知识库   │
                    └─────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Debug Executor Agent                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ 问题定位     │→ │ 方案设计     │→ │ 代码实施     │          │
│  │ 根因分析     │  | 影响评估     │  │ 验证记录     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        反馈与迭代                               │
│  用户测试反馈 → 调整优化 → 更新 .debug 文档 → 持续改进          │
└─────────────────────────────────────────────────────────────────┘

开发环境与运行上下文（优先确认）

在执行验证、测试或 Checkfix 之前，务必确认项目的「部署-开发」架构，避免在错误环境中跑命令导致死循环或无法推进：

• 常见形态：本机 Windows 开发；WSL 内开发；内网 NAS 或云服务器上代码通过 Samba 挂载到 Windows 盘符，在本地 IDE 编辑，但实际运行/测试需 SSH 登录远程执行。
• 若无法从仓库或路径推断：主动问开发者一句，例如：「项目是否在 NAS/Samba+SSH 或远程服务器上开发？当前是怎么跑测试/构建的？」
• 若是远程/NAS-Samba+SSH 形态：询问是否已有现成 SSH 登录（如 ssh nas）；若无则指导建立公钥登录并确认项目在远程的实际路径（如 /mnt/dev/xxx）。后续验证与 Checkfix 应在该上下文中执行（如 ssh nas "cd /mnt/dev/xxx && cargo test"），保障调试流畅、节省成本并防止无效重试。
• 首次与用户确认后，将判断结果写入当前模块的 .debug 文档，作为「运行上下文/测试规则」（运行环境类型、SSH 方式、远程项目路径、验证/Checkfix 执行方式）。后续调用时优先从 .debug 读取该规则，不再反复询问。

工作流程

阶段 1: 上下文构建 (Context Building)

输入：用户的 Debug/增量开发指令

执行步骤：

1. 需求解析

   • 分析任务类型：Bug 修复 / 功能增量 / 性能优化
   • 识别涉及的功能模块
   • 判断模块归属层级：前端模块 / 后端 API 包 / 中间层 / 跨层任务。若为跨层任务，应按 API 边界拆分子任务（后端 API 包先行 → API 文档 → 前端消费），优先在各自层级内独立调试，禁止跨层"绕过"修复
   • 确定代码边界

2. Debug 文档检查

   • 检查 .debug/ 目录是否存在
   • 搜索相关模块的 Debug 文档
   • 判断：新建上下文 or 加载现有上下文

3. 模块隔离检查

   • 检查当前任务是否与已有模块存在逻辑交叉
   • 交叉度计算公式：

     交叉度 = (共享函数数 + 共享变量数 + 共享数据结构数) / 总组件数
     

   • 决策规则：
     • 交叉度 > 30% → 合并到现有文档
     • 交叉度 < 30% → 创建新文档

4. 代码探索与关系映射

   • 使用 Glob/Grep 工具定位相关文件
   • 使用 Read 工具深度阅读代码逻辑
   • 构建以下关系图：
     • 文件关系图：模块间的依赖关系
     • 函数调用链：从入口到最终执行的完整路径
     • 变量依赖图：变量的定义、赋值、使用、流转
     • 数据流向图：数据的输入、处理、输出路径

5. 生成/更新 .debug 文档

输出：完整的上下文关系网络 + .debug 文档

---

阶段 2: 调试/开发执行 (Debug Execution)

输入：上下文关系网络 + .debug 文档 + 具体任务

执行步骤：

1. 问题定位

   • 基于上下文网络，追踪问题根源
   • 分析变量状态、调用路径、数据流向
   • 确定问题的准确位置

2. 方案设计

   • 分析多种解决方案
   • 评估影响范围和风险
   • 选择最优方案

3. 代码实施

   • 遵循项目代码风格
   • 保持架构一致性
   • 最小化修改原则
   • 添加必要的错误处理

4. 验证与记录

   • 验证修改效果
   • Debug-Checkfix 闭环（必选）：根据项目技术栈执行自动检查（见下方「技术栈与推荐检查」），将「修复 → 检查 → 修正」形成闭环；检查结果纳入验证并写入 .debug 文档。
   • 更新 .debug 文档
   • 记录测试结果（含 checkfix 结果）
   • 记录文档变更（本轮更新的 docs/*.md 与对应影响）

输出：修复后的代码 + 更新的 .debug 文档

技术栈与推荐检查（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 记录。

阶段 2.5: 文档同步与部署约束（必选）

• 前端功能更新（新增/修改交互、页面流程、配置项）必须同步更新 docs/ 用户说明书，默认按零基础用户可执行标准编写。
• 后端/API/环境迭代必须同步更新开发与部署文档，写清命令顺序、预期输出、故障排查、回滚方式。
• 每次功能或环境变更后，必须检查既有部署指导是否需要联动更新（如 docs/DEPLOYMENT.md、docs/README.md）。
• Python 部署优先级固定为：uv（注意是 uv，不是 uvicorn）> 直接部署 > conda。

---

阶段 3: 反馈迭代 (Feedback Loop)

输入：用户测试反馈或自动测试结果

执行步骤：

1. 分析反馈

   • 理解用户的测试结果
   • 识别未解决的问题
   • 发现新的优化点

2. 调整优化

   • 基于反馈调整方案
   • 进行二次修复或优化

3. 更新文档

   • 将反馈和调整记录到 .debug 文档
   • 保持文档的完整性和可追溯性

输出：优化的代码 + 完整的 Debug 记录

---

.debug 文档规范

目录结构

.debug/
├── auth-login-debug.md           # 认证登录模块
├── user-profile-debug.md         # 用户资料模块
├── order-api-debug.md            # 订单 API 模块
└── payment-gateway-debug.md      # 支付网关模块

文档模板

# [功能模块名称] Debug 记录

## 元信息

| 字段 | 值 |
|------|-----|
| **模块名称** | [Module Name] |
| **模块类型** | 前端模块 / 后端API包 / 中间层 / 全栈集成 |
| **创建时间** | [YYYY-MM-DD] |
| **最后更新** | [YYYY-MM-DD HH:MM] |
| **相关文件** | [文件路径列表] |
| **依赖模块** | [其他 Debug 文档] |
| **API文档路径** | （后端API包时填写）docs/api/xxx.md |
| **用户说明书路径** | （前端功能更新时填写）docs/xxx.md |
| **开发/部署文档路径** | （后端/环境更新时填写）docs/DEPLOYMENT.md 等 |

## 运行上下文与测试规则（首次确认后填写，后续优先读取此处，不再反复询问）

| 字段 | 值 |
|------|-----|
| **运行环境** | 本机 Windows / WSL / NAS-Samba+SSH 或远程 |
| **SSH 方式（若远程）** | 如 ssh nas、ssh user@host |
| **远程项目路径（若远程）** | 如 /mnt/dev/xxx |
| **验证/Checkfix 执行方式** | 如：在本地终端执行 / ssh nas "cd /mnt/dev/xxx && ..." |

---

## 上下文关系网络

### 文件结构

| 文件路径 | 职责 | 关键函数 |
|----------|------|----------|
| `path/to/file1.ts` | [职责描述] | `func1`, `func2` |
| `path/to/file2.ts` | [职责描述] | `func3` |

### 函数调用链

[入口函数] └─> [中间处理函数] ├─> [分支处理 A] │ └─> [最终执行 A] └─> [分支处理 B] └─> [最终执行 B]

### 变量依赖图

| 变量名 | 类型 | 定义位置 | 作用域 | 依赖变量 | 被依赖变量 |
|--------|------|----------|--------|----------|------------|
| `var1` | Type | `file:line` | Scope | - | `var3` |
| `var2` | Type | `file:line` | Scope | `var1` | `var3` |
| `var3` | Type | `file:line` | Scope | `var1,var2` | - |

### 数据流向

[输入源] → [数据处理] → [存储/输出] │ │ │ └───[格式验证]─┴───[持久化]──┘

---

## Debug 历史

### [YYYY-MM-DD HH:MM] [任务标题]

**任务类型**: Bug 修复 / 功能增量 / 性能优化

**问题描述**:
[用户提供的原始问题描述]

**上下文分析**:
[基于上下文网络的分析]

**根因定位**:
[问题的根本原因]

**解决方案**:
[采用的解决方案描述]

**代码变更**:
| 文件 | 变更类型 | 关键变更 |
|------|----------|----------|
| `file1.ts` | 修改 | 修改了 xx 函数的逻辑 |
| `file2.ts` | 新增 | 新增了 xx 功能 |

**文档变更**:
| 文档 | 变更类型 | 关键更新点 |
|------|----------|------------|
| `docs/xxx.md` | 修改/新增 | [面向用户或开发者的变更说明] |

**验证结果**:
- **测试状态**: ✅ 通过 / ❌ 失败 / ⚠️ 部分通过
- **测试方法**: [手动测试 / 自动测试]
- **边界情况**: [边界测试结果]
- **性能影响**: [性能变化]

**影响评估**:
- **影响范围**: [受影响的模块/功能]
- **回归风险**: [风险等级：低/中/高]
- **缓解措施**: [降低风险的措施]

**相关链接**:
- 相关函数: `file.ts:line`
- 相关变量: `variableName`
- 相关 Issue: `#123`

---

## 待追踪问题

| ID | 问题描述 | 优先级 | 状态 | 创建时间 |
|----|----------|--------|------|----------|
| #1 | [问题描述] | 高/中/低 | 待处理/进行中 | [YYYY-MM-DD] |
| #2 | [问题描述] | 高/中/低 | 待处理/进行中 | [YYYY-MM-DD] |

---

## 技术债务记录

| ID | 债务描述 | 影响 | 建议 | 状态 |
|----|----------|------|------|------|
| TD-1 | [债务描述] | [影响范围] | [改进建议] | 待处理/已处理 |

---

## 架构决策记录 (ADR)

### ADR-[序号]: [决策标题]

**状态**: 提议 / 已接受 / 已弃用 / 已替代

**上下文**:
[决策背景和问题描述]

**决策**:
[做出的决策]

**后果**:
- **正面影响**: [优点]
- **负面影响**: [缺点]
- **风险**: [潜在风险]

## 关联 Skill（网络调度协议）

| 关系 | Skill | 场景 |
|------|-------|------|
| 可调用 | debug-ui | 调试发现问题出在前端 UI 层时 |
| 被调用 | ai-spec | 主调度分诊为 bug 修复 |
| 被调用 | ralph / ralph-yolo | 自动开发中遇到错误 |
| 被调用 | api-first | API 层出现 bug 调试 |
| 被调用 | ux-experience-audit | 体验审计发现功能性 bug |