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

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

---

触发条件

• - INLINECODE1
• INLINECODE2
• INLINECODE3
• INLINECODE4
• INLINECODE5
• INLINECODE6
• INLINECODE7
• INLINECODE8
• INLINECODE9、预提交检查、错误诊断、INLINECODE12
• INLINECODE13、重构建议、INLINECODE15

---

技能边界（防止误触发）

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

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

---

文件落盘（P0）

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

---

子命令

1. spec - 规范管理

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

用法：
CODEBLOCK0

功能模块：

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

输出文件：

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

---

2. pre-commit - 预提交检查

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

用法：
CODEBLOCK2

检查项目：

P0 检查（必须通过）：

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

P1 检查（推荐通过）：

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

示例输出：

**预提交检查**：

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

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

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

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

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

---

3. diagnose - 错误诊断

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

用法：
CODEBLOCK4

诊断流程：

1. 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 - 技术债务跟踪

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

用法：
CODEBLOCK6

功能模块：

债务清单：
CODEBLOCK7

添加债务：
CODEBLOCK8

债务报告：
CODEBLOCK9

输出文件：

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

---

5. diff - 代码差异对比

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

用法：
CODEBLOCK11

参数说明：

参数	类型	说明
INLINECODE21	string	原始代码路径，默认当前代码
INLINECODE22

string | 生成的代码路径 |
| --file | string | 指定对比的文件 |
| --staged | flag | 对比暂存区变更 |
| --commit | string | 对比指定提交 |
| --format | enum | 输出格式：markdown / html / json，默认 markdown |
| --context | number | 上下文行数，默认 3 |

输出示例：

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

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

## 文件变更详情

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

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

diff

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

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

输出文件：

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

---

6. refactor - 重构建议生成

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

用法：
CODEBLOCK15

参数说明：

参数	类型	说明
INLINECODE28	string	代码库分析报告路径
INLINECODE29

string | 范围：module / service / full |
| --type | array | 重构类型：code-smell / architecture / performance / security |
| --priority | enum | 优先级：high / medium / low |
| --apply | string | 应用指定重构建议的 ID |

重构类型说明：

类型	触发条件	重构动作
code-smell	重复代码、过长方法、过大类	提取方法、提取类
architecture

循环依赖、边界违规 | 解耦、分层调整 |
| performance | N+1查询、循环内IO | 批量查询、缓存优化 |
| security | SQL注入、敏感信息泄露 | 参数化查询、加密处理 |

输出示例：
CODEBLOCK16

输出文件：

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

---

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

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

用法：
CODEBLOCK18

参数说明：

参数	类型	说明
INLINECODE33	flag	仅检查循环依赖
INLINECODE34

flag | 仅检查边界违规 |
| --module | string | 分析指定模块 |
| --format | enum | 输出格式：markdown / mermaid / json |
| --design-line | string | 设计主线文档路径 |

分析维度：

维度	检查项	问题级别
模块依赖	循环依赖、单向依赖	错误
服务边界

跨服务数据库访问、内部实现调用 | 错误 |
| 包依赖 | 不合理依赖、反向依赖 | 警告 |
| 类依赖 | 高耦合、缺少接口 | 建议 |

输出示例：

**依赖分析报告**

## 依赖概览
- 总模块数: 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获取数据

## 依赖图谱

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

输出文件：

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

---

与其他技能的关系

与 review-code 的区别

维度	dev-tools pre-commit	review-code
目的	提交前快速检查	详细代码审查
输出

通过/不通过判断 | 问题清单 | | 使用时机 | 代码提交前 | 代码完成后 | | 检查项 | P0/P1 关键检查项 | 完整规范对照 |

典型使用场景

CODEBLOCK23

存量项目推荐流程

CODEBLOCK24

---

相关技能

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

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

---

版本历史

版本	日期	变更说明
2.0.0	2026-03-07	新增代码差异对比（diff）、重构建议生成（refactor）、依赖分析与边界检查（dep）
1.0.0

2026-03-01 | 初始版本 |

---

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