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](../SKILLS-FILE-OUTPUT.md)**：写入前确保目标父目录已存在。本子技能常见目录包括 `docs/tech-debt/`、`docs/diff/`、`docs/refactor/`、`docs/analysis/`（依子命令与参数而定）；自定义 `--output` 时同样须先创建父目录。 --- ## 子命令 ### 1. spec - 规范管理 **功能**：管理项目规范，包括规范版本管理、项目规范定制、规范冲突检测 **用法**： ```bash /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 - 预提交检查 **功能**：代码提交前进行检查，确保符合规范和质量标准 **用法**： ```bash /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 - 错误诊断 **功能**：诊断执行过程中的错误，分析原因并给出解决方案 **用法**： ```bash /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 - 技术债务跟踪 **功能**：跟踪和管理技术债务，定期生成技术债务报告 **用法**： ```bash /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 - 代码差异对比 **功能**：对比新生成代码与现有代码的差异，生成可视化报告 **用法**： ```bash /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 # 对比最近一次提交 ``` **参数说明**： | 参数 | 类型 | 说明 | |------|------|------| | `--original` | string | 原始代码路径，默认当前代码 | | `--generated` | 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) { // 新增来源参数，支持多渠道积分 ``` ## 影响分析 - 影响模块: points-service - 影响接口: 3 个 - 风险等级: 中 是否查看详细差异？ A) 查看全部 B) 按文件查看 C) 导出报告 ``` **输出文件**： ``` docs/diff/YYYY-MM-DD-diff-report.md ``` --- ### 6. refactor - 重构建议生成 **功能**：基于代码库分析结果，自动生成重构建议和重构方案 **用法**： ```bash /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 # 应用指定重构建议 ``` **参数说明**： | 参数 | 类型 | 说明 | |------|------|------| | `--analysis` | string | 代码库分析报告路径 | | `--scope` | 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注入、敏感信息泄露 | 参数化查询、加密处理 | **输出示例**： ``` **重构建议报告** ## 重构概览 - 总建议数: 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 - 依赖分析与边界检查 **功能**：分析代码依赖关系，检测循环依赖和服务边界违规 **用法**： ```bash /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 # 基于设计主线检查 ``` **参数说明**： | 参数 | 类型 | 说明 | |------|------|------| | `--check-cycle` | flag | 仅检查循环依赖 | | `--check-boundary` | 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] ``` 是否查看详细分析？ A) 查看全部 B) 仅看问题 C) 导出图谱 D) 生成修复方案 ``` **输出文件**： ``` docs/analysis/dependencies.md docs/analysis/dependency-graph.md ``` --- ## 与其他技能的关系 ### 与 review-code 的区别 | 维度 | dev-tools pre-commit | review-code | |------|---------------------|-------------| | 目的 | 提交前快速检查 | 详细代码审查 | | 输出 | 通过/不通过判断 | 问题清单 | | 使用时机 | 代码提交前 | 代码完成后 | | 检查项 | P0/P1 关键检查项 | 完整规范对照 | ### 典型使用场景 ``` # 开发过程中 /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](../SKILL-VALUE-CHAIN.md)。 --- ## 版本历史 | 版本 | 日期 | 变更说明 | |------|------|----------| | 2.0.0 | 2026-03-07 | 新增代码差异对比（diff）、重构建议生成（refactor）、依赖分析与边界检查（dep） | | 1.0.0 | 2026-03-01 | 初始版本 | --- *本技能是 AI Speckits 技能体系的开发工具集合。*