\r \r

/dev-tools - 开发工具箱技能\r

\r 技能 ID: dev-tools\r 技能名称: 开发工具箱\r 版本: 2.0.0\r 描述: 提供开发过程中的辅助工具，包括规范管理、预提交检查、错误诊断、技术债务跟踪、代码差异对比、重构建议、依赖分析\r \r ---\r \r

触发条件\r

\r

• /dev-tools\r
• /dev-tools spec\r
• /dev-tools pre-commit\r
• /dev-tools diagnose\r
• /dev-tools debt\r
• /dev-tools diff\r
• /dev-tools refactor\r
• /dev-tools dep\r
• 规范管理、预提交检查、错误诊断、技术债务\r
• 代码差异、重构建议、依赖分析\r \r ---\r \r

技能边界（防止误触发）\r

\r

• 本技能仅当用户要「使用开发辅助工具」时触发\r
• 不得在以下场景触发本技能：\r
  • 用户要「代码审查」→ 应使用 review-code\r
  • 用户要「验证设计」→ 应使用 validate\r
  • 用户要「分析代码库」→ 应使用 analyze\r \r ---\r \r

文件落盘（P0）\r

\r 凡子命令向仓库写入报告或导出文件（Markdown、JSON、HTML 等）时，须遵守 SKILLS-FILE-OUTPUT.md：写入前确保目标父目录已存在。本子技能常见目录包括 docs/tech-debt/、docs/diff/、docs/refactor/、docs/analysis/（依子命令与参数而定）；自定义 --output 时同样须先创建父目录。\r \r ---\r \r

子命令\r

\r

1. spec - 规范管理\r

\r 功能：管理项目规范，包括规范版本管理、项目规范定制、规范冲突检测\r \r 用法：\r

/dev-tools spec              # 查看规范管理菜单\r
/dev-tools spec view         # 查看当前规范\r
/dev-tools spec customize    # 定制项目规范\r
/dev-tools spec update       # 更新规范版本\r
/dev-tools spec conflict     # 检测规范冲突\r
```\r
\r
**功能模块**：\r
- **规范版本管理**：查看规范版本、检查更新、更新规范\r
- **项目规范定制**：定制命名规范、代码格式、注释规范、技术栈规范\r
- **规范冲突检测**：检测内嵌规范与项目规范的冲突并提供解决方案\r
\r
**输出文件**：\r
```\r
.ads/project-specs/naming.md\r
.ads/project-specs/code-style.md\r
```\r
\r
---\r
\r
### 2. pre-commit - 预提交检查\r
\r
**功能**：代码提交前进行检查，确保符合规范和质量标准\r
\r
**用法**：\r
```bash\r
/dev-tools pre-commit              # 检查当前修改\r
/dev-tools pre-commit src/points/  # 检查指定目录\r
```\r
\r
**检查项目**：\r
\r
**P0 检查（必须通过）**：\r
- 编译通过\r
- 无严重安全问题\r
- 无严重空指针风险\r
- 测试通过率 100%\r
- 无敏感信息泄露\r
\r
**P1 检查（推荐通过）**：\r
- 代码规范遵循\r
- 测试覆盖率>80%\r
- 无重复代码\r
- 注释完整\r
- 提交信息规范\r
\r
**示例输出**：\r
```\r
**预提交检查**：\r
\r
P0 检查：\r
✅ 编译通过\r
✅ 无严重安全问题\r
✅ 无严重空指针风险\r
✅ 测试通过率 100%\r
✅ 无敏感信息泄露\r
\r
P1 检查：\r
✅ 代码规范遵循（95%）\r
⚠️ 测试覆盖率 78%（目标 80%）\r
✅ 无重复代码\r
✅ 注释完整\r
\r
**检查结果**：\r
- P0 检查：5/5 通过 ✅\r
- P1 检查：4/5 通过 ⚠️\r
\r
**结论**：可以通过提交，但建议提升测试覆盖率。\r
\r
是否继续提交？\r
A) 继续提交  B) 修复后重新检查  C) 取消提交\r
```\r
\r
---\r
\r
### 3. diagnose - 错误诊断\r
\r
**功能**：诊断执行过程中的错误，分析原因并给出解决方案\r
\r
**用法**：\r
```bash\r
/dev-tools diagnose              # 诊断最近一次错误\r
/dev-tools diagnose --skill=gen-code --task=Task-001  # 诊断指定技能错误\r
```\r
\r
**诊断流程**：\r
1. 收集错误信息（技能名称、错误描述、时间）\r
2. 分析可能原因（给出概率评估）\r
3. 执行诊断步骤（逐步排查）\r
4. 给出诊断结论\r
5. 提供解决方案（多个方案供选择）\r
\r
**示例输出**：\r
```\r
**错误诊断**：\r
\r
**错误信息**：\r
- 技能：/gen-code Task-001\r
- 错误：代码生成失败\r
- 时间：2026-03-01 10:30:00\r
\r
**错误分析**：\r
\r
可能原因：\r
1. 设计文档不存在（概率 60%）\r
2. 任务描述不清晰（概率 30%）\r
3. 规范冲突（概率 10%）\r
\r
**诊断步骤**：\r
\r
步骤 1/3：检查设计文档\r
✅ 设计文档存在\r
\r
步骤 2/3：检查任务描述\r
❌ 任务描述不清晰\r
\r
**诊断结论**：\r
错误原因：任务描述不清晰\r
\r
**解决方案**：\r
\r
方案 A（推荐）：\r
修改任务描述为具体内容\r
\r
方案 B：\r
重新生成任务列表\r
\r
是否需要我帮助修改任务描述？\r
A) 是  B) 否  C) 取消\r
```\r
\r
---\r
\r
### 4. debt - 技术债务跟踪\r
\r
**功能**：跟踪和管理技术债务，定期生成技术债务报告\r
\r
**用法**：\r
```bash\r
/dev-tools debt              # 查看技术债务菜单\r
/dev-tools debt list         # 列出技术债务清单\r
/dev-tools debt add          # 添加技术债务\r
/dev-tools debt report       # 生成债务报告\r
/dev-tools debt fix TD-001   # 标记债务为已修复\r
```\r
\r
**功能模块**：\r
\r
**债务清单**：\r
```\r
| 编号 | 描述 | 优先级 | 状态 |\r
|------|------|--------|------|\r
| TD-001 | 积分扣减未加事务 | P0 | 待修复 |\r
| TD-002 | 并发扣减可能超扣 | P0 | 待修复 |\r
| TD-003 | 积分规则硬编码 | P2 | 待修复 |\r
\r
**统计**：\r
- 总债务数：4\r
- P0 债务：2\r
- P1 债务：1\r
- P2 债务：1\r
```\r
\r
**添加债务**：\r
```\r
**添加技术债务**：\r
\r
描述：积分规则硬编码，不支持动态配置\r
优先级：P2\r
预计修复时间：2h\r
\r
是否添加？\r
A) 添加  B) 修改  C) 取消\r
```\r
\r
**债务报告**：\r
```\r
**技术债务报告**：\r
\r
**债务趋势**：\r
| 日期 | 新增 | 修复 | 累计 |\r
|------|------|------|------|\r
| 2026-03-01 | 4 | 0 | 4 |\r
\r
**修复建议**：\r
1. 优先修复 P0 债务（2 个）\r
2. 本周修复 P1 债务（1 个）\r
\r
**预计工时**：总计 8h\r
```\r
\r
**输出文件**：\r
```\r
docs/tech-debt/YYYY-MM-DD-debt-report.md\r
```\r
\r
---\r
\r
### 5. diff - 代码差异对比\r
\r
**功能**：对比新生成代码与现有代码的差异，生成可视化报告\r
\r
**用法**：\r
```bash\r
/dev-tools diff                                    # 对比工作区变更\r
/dev-tools diff --original=src/ --generated=.gen/  # 对比指定目录\r
/dev-tools diff --file=PointsService.java          # 对比单个文件\r
/dev-tools diff --staged                           # 对比暂存区变更\r
/dev-tools diff --commit=HEAD~1                    # 对比最近一次提交\r
```\r
\r
**参数说明**：\r
\r
| 参数 | 类型 | 说明 |\r
|------|------|------|\r
| `--original` | string | 原始代码路径，默认当前代码 |\r
| `--generated` | string | 生成的代码路径 |\r
| `--file` | string | 指定对比的文件 |\r
| `--staged` | flag | 对比暂存区变更 |\r
| `--commit` | string | 对比指定提交 |\r
| `--format` | enum | 输出格式：markdown / html / json，默认 markdown |\r
| `--context` | number | 上下文行数，默认 3 |\r
\r
**输出示例**：\r
```\r
**代码差异对比报告**\r
\r
## 概览\r
- 新增文件: 3\r
- 修改文件: 5\r
- 删除文件: 1\r
- 新增行数: 234\r
- 删除行数: 56\r
- 净增行数: 178\r
\r
## 文件变更详情\r
\r
### 新增文件\r
| 文件 | 行数 | 说明 |\r
|------|------|------|\r
| PointsServiceV2.java | 156 | 新版积分服务 |\r
\r
### 修改文件\r
#### PointsController.java\r
```diff\r
- public Result earnPoints(Long userId, Integer points) {\r
+ public Result earnPoints(Long userId, Integer points, String source) {\r
    // 新增来源参数，支持多渠道积分\r
```\r
\r
## 影响分析\r
- 影响模块: points-service\r
- 影响接口: 3 个\r
- 风险等级: 中\r
\r
是否查看详细差异？\r
A) 查看全部  B) 按文件查看  C) 导出报告\r
```\r
\r
**输出文件**：\r
```\r
docs/diff/YYYY-MM-DD-diff-report.md\r
```\r
\r
---\r
\r
### 6. refactor - 重构建议生成\r
\r
**功能**：基于代码库分析结果，自动生成重构建议和重构方案\r
\r
**用法**：\r
```bash\r
/dev-tools refactor                                          # 生成重构建议\r
/dev-tools refactor --analysis=docs/analysis/codebase-analysis.md  # 基于分析报告\r
/dev-tools refactor --scope=points-service                   # 指定模块\r
/dev-tools refactor --type=code-smell,architecture           # 指定类型\r
/dev-tools refactor --priority=high                          # 仅高优先级\r
/dev-tools refactor --apply=RF-001                           # 应用指定重构建议\r
```\r
\r
**参数说明**：\r
\r
| 参数 | 类型 | 说明 |\r
|------|------|------|\r
| `--analysis` | string | 代码库分析报告路径 |\r
| `--scope` | string | 范围：module / service / full |\r
| `--type` | array | 重构类型：code-smell / architecture / performance / security |\r
| `--priority` | enum | 优先级：high / medium / low |\r
| `--apply` | string | 应用指定重构建议的 ID |\r
\r
**重构类型说明**：\r
\r
| 类型 | 触发条件 | 重构动作 |\r
|------|----------|----------|\r
| code-smell | 重复代码、过长方法、过大类 | 提取方法、提取类 |\r
| architecture | 循环依赖、边界违规 | 解耦、分层调整 |\r
| performance | N+1查询、循环内IO | 批量查询、缓存优化 |\r
| security | SQL注入、敏感信息泄露 | 参数化查询、加密处理 |\r
\r
**输出示例**：\r
```\r
**重构建议报告**\r
\r
## 重构概览\r
- 总建议数: 12\r
- 高优先级: 3\r
- 中优先级: 5\r
- 低优先级: 4\r
- 预计收益: 代码质量提升 25%\r
\r
## 高优先级重构建议\r
\r
### RF-001: 解耦订单与支付服务\r
- **问题**: 订单服务直接调用支付服务内部实现\r
- **影响**: 违反服务边界，增加耦合\r
- **建议**: 通过API网关调用，使用事件驱动解耦\r
- **预计工时**: 8h\r
- **风险等级**: 中\r
\r
### RF-002: 提取积分计算逻辑\r
- **问题**: 积分计算逻辑散落在多个方法中\r
- **影响**: 代码重复，难以维护\r
- **建议**: 提取独立的 PointsCalculator 类\r
- **预计工时**: 4h\r
- **风险等级**: 低\r
\r
## 重构方案\r
\r
### 方案一：渐进式重构（推荐）\r
1. 先处理高优先级问题\r
2. 每次重构后运行测试\r
3. 分阶段验证\r
\r
是否查看详细方案？\r
A) 查看全部  B) 按优先级查看  C) 导出报告  D) 应用建议\r
```\r
\r
**输出文件**：\r
```\r
docs/refactor/YYYY-MM-DD-refactor-suggest.md\r
```\r
\r
---\r
\r
### 7. dep - 依赖分析与边界检查\r
\r
**功能**：分析代码依赖关系，检测循环依赖和服务边界违规\r
\r
**用法**：\r
```bash\r
/dev-tools dep                           # 完整依赖分析\r
/dev-tools dep --check-cycle             # 仅检查循环依赖\r
/dev-tools dep --check-boundary          # 仅检查边界违规\r
/dev-tools dep --module=order-service    # 分析指定模块\r
/dev-tools dep --format=mermaid          # 输出 Mermaid 图谱\r
/dev-tools dep --design-line=docs/design/design-line.md  # 基于设计主线检查\r
```\r
\r
**参数说明**：\r
\r
| 参数 | 类型 | 说明 |\r
|------|------|------|\r
| `--check-cycle` | flag | 仅检查循环依赖 |\r
| `--check-boundary` | flag | 仅检查边界违规 |\r
| `--module` | string | 分析指定模块 |\r
| `--format` | enum | 输出格式：markdown / mermaid / json |\r
| `--design-line` | string | 设计主线文档路径 |\r
\r
**分析维度**：\r
\r
| 维度 | 检查项 | 问题级别 |\r
|------|--------|----------|\r
| 模块依赖 | 循环依赖、单向依赖 | 错误 |\r
| 服务边界 | 跨服务数据库访问、内部实现调用 | 错误 |\r
| 包依赖 | 不合理依赖、反向依赖 | 警告 |\r
| 类依赖 | 高耦合、缺少接口 | 建议 |\r
\r
**输出示例**：\r
```\r
**依赖分析报告**\r
\r
## 依赖概览\r
- 总模块数: 8\r
- 总依赖数: 24\r
- 循环依赖: 2\r
- 边界违规: 3\r
- 风险等级: 高\r
\r
## 循环依赖\r
\r
### CD-001: order-service ↔ payment-service\r
```\r
order-service → payment-service → order-service\r
```\r
**影响**: 编译顺序问题、运行时风险\r
**建议**: 引入中间层或事件驱动解耦\r
\r
## 边界违规\r
\r
### BV-001: 订单服务直接访问支付数据库\r
- **位置**: OrderServiceImpl.java:156\r
- **代码**: paymentMapper.selectByOrderId(orderId)\r
- **违规类型**: 跨服务数据库访问\r
- **修复建议**: 通过支付服务API获取数据\r
\r
## 依赖图谱\r
\r
```mermaid\r
graph TD\r
    A[user-service] --> B[points-service]\r
    A --> C[order-service]\r
    C --> D[payment-service]\r
    C --> E[notification-service]\r
```\r
\r
是否查看详细分析？\r
A) 查看全部  B) 仅看问题  C) 导出图谱  D) 生成修复方案\r
```\r
\r
**输出文件**：\r
```\r
docs/analysis/dependencies.md\r
docs/analysis/dependency-graph.md\r
```\r
\r
---\r
\r
## 与其他技能的关系\r
\r
### 与 review-code 的区别\r
\r
| 维度 | dev-tools pre-commit | review-code |\r
|------|---------------------|-------------|\r
| 目的 | 提交前快速检查 | 详细代码审查 |\r
| 输出 | 通过/不通过判断 | 问题清单 |\r
| 使用时机 | 代码提交前 | 代码完成后 |\r
| 检查项 | P0/P1 关键检查项 | 完整规范对照 |\r
\r
### 典型使用场景\r
\r
```\r
# 开发过程中\r
/dev-tools spec customize     # 定制项目规范\r
\r
# 开发完成\r
/dev-tools pre-commit         # 提交前检查\r
\r
# 如果出错\r
/dev-tools diagnose           # 诊断错误\r
\r
# 代码审查后\r
/dev-tools debt add           # 记录发现的技术债务\r
\r
# 项目复盘\r
/dev-tools debt report        # 生成债务报告\r
\r
# 存量项目增强（新增）\r
/dev-tools diff               # 代码差异对比\r
/dev-tools refactor           # 生成重构建议\r
/dev-tools dep                # 依赖分析与边界检查\r
```\r
\r
### 存量项目推荐流程\r
\r
```\r
# 1. 代码变更后对比\r
/gen-code Task-001\r
/dev-tools diff --staged      # 对比生成的代码变更\r
\r
# 2. 发现问题后分析\r
/dev-tools dep --check-boundary    # 检查边界违规\r
/dev-tools refactor --priority=high  # 生成高优先级重构建议\r
\r
# 3. 技术债务管理\r
/dev-tools debt list          # 查看债务清单\r
/dev-tools debt report        # 生成债务报告\r
\r
# 4. 提交前检查\r
/dev-tools pre-commit         # 最终检查\r
```\r
\r
---\r
\r
## 相关技能\r
\r
- **review-code** / **gen-test**：审查与测试之后的**预提交**（`pre-commit`）与**债务**（`debt`）记录。\r
- **analyze**：**diff** / **refactor** / **dep** 常与分析报告、依赖图谱配合。\r
- **gen-code**：生成代码后用 **diff** 做变更可视化。\r
- **spec** 子命令：与 **`docs/coding-specs/`** 文档规范互补——前者偏工具与元数据，**团队编码约定**以 `coding.*.md` 为准。\r
\r
全链路见 [SKILL-VALUE-CHAIN.md](../SKILL-VALUE-CHAIN.md)。\r
\r
---\r
\r
## 版本历史\r
\r
| 版本 | 日期 | 变更说明 |\r
|------|------|----------|\r
| 2.0.0 | 2026-03-07 | 新增代码差异对比（diff）、重构建议生成（refactor）、依赖分析与边界检查（dep） |\r
| 1.0.0 | 2026-03-01 | 初始版本 |\r
\r
---\r
\r
*本技能是 AI Speckits 技能体系的开发工具集合。*\r