dev-tools（开发工具）

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

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

触发条件

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

技能边界（防止误触发）

• 本技能仅当用户要「使用开发辅助工具」时触发
• 不得在以下场景触发本技能：

- 用户要「代码审查」→ 应使用 review-code - 用户要「验证设计」→ 应使用 validate - 用户要「分析代码库」→ 应使用 analyze

文件落盘（P0）

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

子命令

1. spec - 规范管理

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

用法：

/dev-tools spec              # 查看规范管理菜单
/dev-tools spec view         # 查看当前规范
/dev-tools spec customize    # 定制项目规范
/dev-tools spec update       # 更新规范版本
/dev-tools spec conflict     # 检测规范冲突

功能模块：

• 规范版本管理：查看规范版本、检查更新、更新规范
• 项目规范定制：定制命名规范、代码格式、注释规范、技术栈规范
• 规范冲突检测：检测内嵌规范与项目规范的冲突并提供解决方案

输出文件：

.ads/project-specs/naming.md
.ads/project-specs/code-style.md

2. pre-commit - 预提交检查

功能：代码提交前进行检查，确保符合规范和质量标准

用法：

/dev-tools pre-commit              # 检查当前修改
/dev-tools pre-commit src/points/  # 检查指定目录

检查项目：

P0 检查（必须通过）：

• 编译通过
• 无严重安全问题
• 无严重空指针风险
• 测试通过率 100%
• 无敏感信息泄露

P1 检查（推荐通过）：

• 代码规范遵循
• 测试覆盖率>80%
• 无重复代码
• 注释完整
• 提交信息规范

示例输出：

**预提交检查**：

P0 检查：
✅ 编译通过
✅ 无严重安全问题
✅ 无严重空指针风险
✅ 测试通过率 100%
✅ 无敏感信息泄露

P1 检查：
✅ 代码规范遵循（95%）
⚠️ 测试覆盖率 78%（目标 80%）
✅ 无重复代码
✅ 注释完整

**检查结果**：
- P0 检查：5/5 通过 ✅
- P1 检查：4/5 通过 ⚠️

**结论**：可以通过提交，但建议提升测试覆盖率。

是否继续提交？
A) 继续提交  B) 修复后重新检查  C) 取消提交

3. diagnose - 错误诊断

功能：诊断执行过程中的错误，分析原因并给出解决方案

用法：

/dev-tools diagnose              # 诊断最近一次错误
/dev-tools diagnose --skill=gen-code --task=Task-001  # 诊断指定技能错误

诊断流程：

1. 收集错误信息（技能名称、错误描述、时间）
2. 分析可能原因（给出概率评估）
3. 执行诊断步骤（逐步排查）
4. 给出诊断结论
5. 提供解决方案（多个方案供选择）

示例输出：

**错误诊断**：

**错误信息**：
- 技能：/gen-code Task-001
- 错误：代码生成失败
- 时间：2026-03-01 10:30:00

**错误分析**：

可能原因：
1. 设计文档不存在（概率 60%）
2. 任务描述不清晰（概率 30%）
3. 规范冲突（概率 10%）

**诊断步骤**：

步骤 1/3：检查设计文档
✅ 设计文档存在

步骤 2/3：检查任务描述
❌ 任务描述不清晰

**诊断结论**：
错误原因：任务描述不清晰

**解决方案**：

方案 A（推荐）：
修改任务描述为具体内容

方案 B：
重新生成任务列表

是否需要我帮助修改任务描述？
A) 是  B) 否  C) 取消

4. debt - 技术债务跟踪

功能：跟踪和管理技术债务，定期生成技术债务报告

用法：

/dev-tools debt              # 查看技术债务菜单
/dev-tools debt list         # 列出技术债务清单
/dev-tools debt add          # 添加技术债务
/dev-tools debt report       # 生成债务报告
/dev-tools debt fix TD-001   # 标记债务为已修复

功能模块：

债务清单：

| 编号 | 描述 | 优先级 | 状态 |
|------|------|--------|------|
| TD-001 | 积分扣减未加事务 | P0 | 待修复 |
| TD-002 | 并发扣减可能超扣 | P0 | 待修复 |
| TD-003 | 积分规则硬编码 | P2 | 待修复 |

**统计**：
- 总债务数：4
- P0 债务：2
- P1 债务：1
- P2 债务：1

添加债务：

**添加技术债务**：

描述：积分规则硬编码，不支持动态配置
优先级：P2
预计修复时间：2h

是否添加？
A) 添加  B) 修改  C) 取消

债务报告：

**技术债务报告**：

**债务趋势**：
| 日期 | 新增 | 修复 | 累计 |
|------|------|------|------|
| 2026-03-01 | 4 | 0 | 4 |

**修复建议**：
1. 优先修复 P0 债务（2 个）
2. 本周修复 P1 债务（1 个）

**预计工时**：总计 8h

输出文件：

docs/tech-debt/YYYY-MM-DD-debt-report.md

5. diff - 代码差异对比

功能：对比新生成代码与现有代码的差异，生成可视化报告

用法：

/dev-tools diff                                    # 对比工作区变更
/dev-tools diff --original=src/ --generated=.gen/  # 对比指定目录
/dev-tools diff --file=PointsService.java          # 对比单个文件
/dev-tools diff --staged                           # 对比暂存区变更
/dev-tools diff --commit=HEAD~1                    # 对比最近一次提交

参数说明：

输出示例：

**代码差异对比报告**

## 概览
- 新增文件: 3
- 修改文件: 5
- 删除文件: 1
- 新增行数: 234
- 删除行数: 56
- 净增行数: 178

## 文件变更详情

### 新增文件
| 文件 | 行数 | 说明 |
|------|------|------|
| PointsServiceV2.java | 156 | 新版积分服务 |

### 修改文件
#### PointsController.java

• public Result earnPoints(Long userId, Integer points) {

+ public Result earnPoints(Long userId, Integer points, String source) { // 新增来源参数，支持多渠道积分

## 影响分析
- 影响模块: points-service
- 影响接口: 3 个
- 风险等级: 中

是否查看详细差异？
A) 查看全部  B) 按文件查看  C) 导出报告

输出文件：

docs/diff/YYYY-MM-DD-diff-report.md

6. refactor - 重构建议生成

功能：基于代码库分析结果，自动生成重构建议和重构方案

用法：

/dev-tools refactor                                          # 生成重构建议
/dev-tools refactor --analysis=docs/analysis/codebase-analysis.md  # 基于分析报告
/dev-tools refactor --scope=points-service                   # 指定模块
/dev-tools refactor --type=code-smell,architecture           # 指定类型
/dev-tools refactor --priority=high                          # 仅高优先级
/dev-tools refactor --apply=RF-001                           # 应用指定重构建议

参数说明：

重构类型说明：

输出示例：

**重构建议报告**

## 重构概览
- 总建议数: 12
- 高优先级: 3
- 中优先级: 5
- 低优先级: 4
- 预计收益: 代码质量提升 25%

## 高优先级重构建议

### RF-001: 解耦订单与支付服务
- **问题**: 订单服务直接调用支付服务内部实现
- **影响**: 违反服务边界，增加耦合
- **建议**: 通过API网关调用，使用事件驱动解耦
- **预计工时**: 8h
- **风险等级**: 中

### RF-002: 提取积分计算逻辑
- **问题**: 积分计算逻辑散落在多个方法中
- **影响**: 代码重复，难以维护
- **建议**: 提取独立的 PointsCalculator 类
- **预计工时**: 4h
- **风险等级**: 低

## 重构方案

### 方案一：渐进式重构（推荐）
1. 先处理高优先级问题
2. 每次重构后运行测试
3. 分阶段验证

是否查看详细方案？
A) 查看全部  B) 按优先级查看  C) 导出报告  D) 应用建议

输出文件：

docs/refactor/YYYY-MM-DD-refactor-suggest.md

7. dep - 依赖分析与边界检查

功能：分析代码依赖关系，检测循环依赖和服务边界违规

用法：

/dev-tools dep                           # 完整依赖分析
/dev-tools dep --check-cycle             # 仅检查循环依赖
/dev-tools dep --check-boundary          # 仅检查边界违规
/dev-tools dep --module=order-service    # 分析指定模块
/dev-tools dep --format=mermaid          # 输出 Mermaid 图谱
/dev-tools dep --design-line=docs/design/design-line.md  # 基于设计主线检查

参数说明：

分析维度：

输出示例：

**依赖分析报告**

## 依赖概览
- 总模块数: 8
- 总依赖数: 24
- 循环依赖: 2
- 边界违规: 3
- 风险等级: 高

## 循环依赖

### CD-001: order-service ↔ payment-service

order-service → payment-service → order-service

**影响**: 编译顺序问题、运行时风险
**建议**: 引入中间层或事件驱动解耦

## 边界违规

### BV-001: 订单服务直接访问支付数据库
- **位置**: OrderServiceImpl.java:156
- **代码**: paymentMapper.selectByOrderId(orderId)
- **违规类型**: 跨服务数据库访问
- **修复建议**: 通过支付服务API获取数据

## 依赖图谱

graph TD A[user-service] --> B[points-service] A --> C[order-service] C --> D[payment-service] C --> E[notification-service]

是否查看详细分析？
A) 查看全部  B) 仅看问题  C) 导出图谱  D) 生成修复方案

输出文件：

docs/analysis/dependencies.md
docs/analysis/dependency-graph.md

与其他技能的关系

与 review-code 的区别

典型使用场景

# 开发过程中
/dev-tools spec customize     # 定制项目规范

# 开发完成
/dev-tools pre-commit         # 提交前检查

# 如果出错
/dev-tools diagnose           # 诊断错误

# 代码审查后
/dev-tools debt add           # 记录发现的技术债务

# 项目复盘
/dev-tools debt report        # 生成债务报告

# 存量项目增强（新增）
/dev-tools diff               # 代码差异对比
/dev-tools refactor           # 生成重构建议
/dev-tools dep                # 依赖分析与边界检查

存量项目推荐流程

# 1. 代码变更后对比
/gen-code Task-001
/dev-tools diff --staged      # 对比生成的代码变更

# 2. 发现问题后分析
/dev-tools dep --check-boundary    # 检查边界违规
/dev-tools refactor --priority=high  # 生成高优先级重构建议

# 3. 技术债务管理
/dev-tools debt list          # 查看债务清单
/dev-tools debt report        # 生成债务报告

# 4. 提交前检查
/dev-tools pre-commit         # 最终检查

相关技能

• review-code / gen-test：审查与测试之后的预提交（pre-commit）与债务（debt）记录。
• analyze：diff / refactor / dep 常与分析报告、依赖图谱配合。
• gen-code：生成代码后用 diff 做变更可视化。
• spec 子命令：与 docs/coding-specs/ 文档规范互补——前者偏工具与元数据，团队编码约定以 coding.*.md 为准。

全链路见 SKILL-VALUE-CHAIN.md。

版本历史

*本技能是 AI Speckits 技能体系的开发工具集合。*