@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/common/branch-code-reviewer/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: branch-code-reviewer
+description: 分支代码评审专家。将功能分支与主分支(master/main)进行代码比对分析,自动识别技术风险和业务风险,生成可视化HTML评审报告。当需要进行分支间代码评审、合并前代码检查、代码质量分析时使用。
+compatibility: Requires git repository with at least two branches. Works best when combined with requirement documentation for business risk analysis.
+metadata:
+  version: "1.0.0"
+  openclaw-user-invocable: "true"
+  type: flexible
+  category: code-review
+  tags: ["branch-diff", "code-review", "risk-analysis", "business-risk", "technical-risk", "html-report"]
+---
+
+# 分支代码评审专家 (Branch Code Reviewer)
+
+> 本技能专注于**分支间代码差异分析**与**多维度风险识别**,不仅检查技术类风险,还结合需求文档分析业务类风险,最终生成精美的可视化 HTML 评审报告。
+
+## 触发条件
+
+当用户输入以下类似指令时,**必须**强制调用此技能:
+
+- "评审当前分支"
+- "对比分支差异"
+- "分析代码风险"
+- "生成评审报告"
+- "检查合并风险"
+- "/branch-review"
+
+## 环境依赖
+
+- Git 仓库,至少有两个分支(功能分支 + 主分支)
+- 可选:需求文档路径(用于业务风险分析)
+- 需要文件读写权限以生成 HTML 报告
+
+## 前置要求
+
+1. 必须在 Git 仓库中执行
+2. 必须确认要对比的两个分支(功能分支 vs 主分支)
+3. 如果用户提供了需求文档路径,必须读取该文档用于业务风险分析
+4. 确保 `.code-review/` 目录存在,不存在则创建
+
+---
+
+## 工作流程
+
+### 第一步:确认分支信息与需求文档
+
+**强制输出标题**: `### 第一步:确认评审上下文`
+
+1. 获取当前 Git 仓库的分支列表:
+   ```bash
+   git branch -a
+   ```
+
+2. 确认要对比的功能分支和目标分支:
+   - 如果用户指定了分支,使用用户指定的分支
+   - 如果用户未指定,使用当前分支作为功能分支,自动检测主分支(优先 master,其次 main)
+
+3. **重要**: 询问用户是否提供本次开发需求的文档:
+   ```
+   请提供本次开发需求的文档路径(可选),用于业务风险分析:
+   - 需求文档类型: PRD / 用户故事 / 需求规格说明 / 其他
+   - 文档路径: [用户输入或留空]
+   
+   如果不提供需求文档,将仅进行技术类风险分析。
+   ```
+
+4. 如果用户提供了需求文档,读取并分析:
+   - 核心业务目标
+   - 关键功能点
+   - 业务约束与规则
+   - 验收标准
+
+5. 输出确认信息:
+   ```
+   ✅ 评审上下文已确认:
+   - 功能分支: [branch-name]
+   - 主分支: [master/main]
+   - 需求文档: [已读取/未提供]
+   - 评审范围: [技术风险 + 业务风险 / 仅技术风险]
+   ```
+
+### 第二步:获取代码差异与提交历史
+
+**强制输出标题**: `### 第二步:收集代码差异数据`
+
+1. 获取两个分支间的完整差异:
+   ```bash
+   git diff [main-branch]..[feature-branch] > diff-full.patch
+   ```
+
+2. 获取文件级别的变更统计:
+   ```bash
+   git diff --stat [main-branch]..[feature-branch]
+   ```
+
+3. 获取每个文件的增删行数统计:
+   ```bash
+   git diff --numstat [main-branch]..[feature-branch]
+   ```
+
+4. 获取功能分支相对于主分支的提交历史:
+   ```bash
+   git log [main-branch]..[feature-branch] --oneline
+   ```
+
+5. 获取变更文件列表:
+   ```bash
+   git diff --name-status [main-branch]..[feature-branch]
+   ```
+
+6. 对于每个变更文件,获取足够的上下文代码(至少前后10行):
+   ```bash
+   git diff [main-branch]..[feature-branch] -- [file-path]
+   ```
+
+7. 输出收集结果:
+   ```
+   📊 差异数据已收集:
+   - 变更文件数: X
+   - 新增行数: +X
+   - 删除行数: -X
+   - 提交次数: X
+   - 变更文件列表: [file1, file2, ...]
+   ```
+
+### 第三步:技术类风险代码分析
+
+**强制输出标题**: `### 第三步:技术风险分析`
+
+针对每个变更文件进行深度技术分析:
+
+#### 3.1 代码质量检查
+
+- **命名规范**: 变量、函数、组件命名是否符合项目规范
+- **代码重复度**: 是否存在复制粘贴代码
+- **函数复杂度**: 函数是否过长,圈复杂度是否过高
+- **代码可读性**: 逻辑是否清晰,注释是否充分
+
+#### 3.2 潜在技术问题识别
+
+- **性能问题**:
+  - 不必要的重渲染(React/Vue)
+  - 内存泄漏(未清理的监听器、定时器等)
+  - 大循环或嵌套循环性能瓶颈
+  - 未使用缓存导致重复计算
+
+- **安全漏洞**:
+  - XSS 攻击风险(未转义的用户输入)
+  - SQL/命令注入攻击
+  - 敏感信息暴露(硬编码密钥、密码等)
+  - CSRF 防护缺失
+
+- **错误处理缺失**:
+  - Promise 未 catch
+  - try-catch 缺失
+  - 边界条件未处理
+  - 空值/undefined 未检查
+
+#### 3.3 最佳实践检查
+
+- 设计模式是否恰当
+- API 使用是否正确
+- 是否遵循项目既有规范(参考 `.agents/rules/`)
+- 组件化与模块化程度
+- 测试覆盖率是否足够
+
+#### 3.4 技术改进建议
+
+输出具体的:
+- 代码重构建议
+- 性能优化方案
+- 更优的实现方式
+- 代码简化建议
+
+### 第四步:业务类风险分析(如果提供了需求文档)
+
+**强制输出标题**: `### 第四步:业务风险分析`
+
+**仅当用户提供需求文档时执行此步骤**。
+
+#### 4.1 需求覆盖度检查
+
+对比代码变更与需求文档,检查:
+
+- **功能完整性**: 需求文档中的所有功能点是否都已实现
+- **验收标准**: 是否满足需求文档中的验收标准
+- **业务规则**: 代码实现是否符合业务规则
+- **边界场景**: 需求文档中提到的边界场景是否都处理了
+
+#### 4.2 业务逻辑风险
+
+识别以下业务风险:
+
+- **流程缺失**: 关键业务流程是否遗漏
+  - 例如:订单创建后缺少支付流程
+  
+- **状态不一致**: 业务状态流转是否正确
+  - 例如:订单状态从"待支付"直接跳到"已完成",缺少"已支付"状态
+
+- **数据一致性**: 数据操作是否符合业务约束
+  - 例如:库存扣减与订单创建不在同一事务
+
+- **权限与合规**: 是否符合业务权限要求
+  - 例如:未校验用户权限即可操作敏感数据
+
+- **异常场景**: 业务异常场景是否处理
+  - 例如:支付失败后的回滚逻辑
+  - 例如:库存不足时的降级方案
+
+#### 4.3 业务改进建议
+
+输出具体的:
+- 缺失功能点清单
+- 业务逻辑修正建议
+- 流程补充建议
+- 风险控制建议
+
+### 第五步:生成可视化 HTML 报告
+
+**强制输出标题**: `### 第五步:生成可视化评审报告`
+
+生成一个独立的 HTML 文件(无需外部依赖),包含以下功能模块:
+
+#### 5.1 HTML 报告结构
+
+##### 1. 概览面板(Overview Dashboard)
+
+```
+┌─────────────────────────────────────────────┐
+│  📊 代码评审报告 - [分支名] vs [主分支名]      │
+├─────────────────────────────────────────────┤
+│  变更文件数 | 新增行数 | 删除行数 | 修改行数    │
+│  提交次数   | 技术风险数 | 业务风险数 | 通过率  │
+└─────────────────────────────────────────────┘
+```
+
+##### 2. 文件导航树(File Tree Navigator)
+
+- 左侧显示文件树结构
+- 使用不同颜色/图标标注文件状态(新增/修改/删除)
+- 支持目录折叠/展开
+- 显示每个文件的变更行数统计
+- 点击文件快速跳转到对应差异区域
+
+##### 3. 差异展示区(Diff Viewer)
+
+- **并排模式(Side-by-Side)**: 左侧显示旧代码,右侧显示新代码
+- **统一模式(Unified)**: 在同一列中显示差异,使用颜色区分增删
+- 支持两种模式切换
+- 代码语法高亮(根据文件类型)
+- 行号显示
+- 变更行用背景色标注:
+  - 绿色: 新增行
+  - 红色: 删除行
+  - 黄色: 修改行
+- 折叠未变更的代码区域,保留上下文(可点击展开)
+
+##### 4. 技术风险区(Technical Risks)
+
+每个文件的技术评审结果:
+
+- 问题按严重程度分级:
+  - 🔴 严重(Critical): 必须修复
+  - 🟡 警告(Warning): 建议修复
+  - 🔵 建议(Suggestion): 可选优化
+  - ⚪ 提示(Info): 信息说明
+
+- 每个问题包含:
+  - 问题描述
+  - 风险原因
+  - 修复建议
+  - 示例代码
+  - 关联到具体代码行
+
+##### 5. 业务风险区(Business Risks) - 如果有需求文档
+
+业务风险分析结果:
+
+- 需求覆盖度评分
+- 缺失功能点清单
+- 业务逻辑风险
+- 流程缺失警告
+- 状态不一致问题
+- 数据一致性问题
+- 每个业务风险关联到:
+  - 需求文档章节
+  - 相关代码文件
+  - 风险等级
+  - 修复建议
+
+##### 6. 交互功能
+
+- **搜索**: 支持全局搜索文件名和代码内容
+- **过滤**: 按文件类型、变更类型、问题严重程度、风险类型(技术/业务)筛选
+- **导航**: 上一个/下一个文件、上一个/下一个问题快速跳转
+- **统计图表**: 使用 CSS 绘制变更统计图、风险分布图
+- **主题切换**: 支持亮色/暗色主题
+- **评论功能**: 可以在代码行上添加评论(存储在 localStorage)
+- **标记功能**: 可以标记已审阅/未审阅的文件
+- **导出功能**: 导出评审结果为 JSON 或 Markdown
+
+#### 5.2 HTML 技术要求
+
+1. **纯 HTML/CSS/JavaScript**: 不依赖任何外部 CDN 或库
+2. **响应式设计**: 适配不同屏幕尺寸
+3. **高性能**: 大量代码差异时也能流畅滚动
+4. **可访问性**: 支持键盘导航
+5. **打印友好**: 支持导出打印
+
+#### 5.3 CSS 样式要求
+
+- 使用现代 CSS(Grid、Flexbox)
+- 代码字体使用等宽字体
+- 颜色方案协调,适合长时间阅读
+- 动画过渡效果自然
+- 暗色主题配色参考主流代码编辑器
+
+### 第六步:输出报告与后续建议
+
+**强制输出标题**: `### 第六步:输出评审结果`
+
+1. 将 HTML 报告保存到项目根目录下的 `.code-review/` 目录中
+2. 文件名格式: `review-[功能分支名]-[日期].html`
+3. 确保目录存在,不存在则创建:
+   ```bash
+   mkdir -p .code-review
+   ```
+
+4. 完成后在终端输出:
+   ```
+   ✅ 评审报告已生成:
+   📄 报告路径: .code-review/review-[branch]-[date].html
+   
+   📊 评审统计:
+   - 技术风险: X 个(🔴 X | 🟡 X | 🔵 X | ⚪ X)
+   - 业务风险: X 个(🔴 X | 🟡 X | 🔵 X)
+   - 需求覆盖度: X%
+   - 整体通过率: X%
+   
+   🎯 关键发现:
+   1. [最严重的技术风险]
+   2. [最严重的业务风险]
+   3. [关键改进建议]
+   
+   💡 后续建议:
+   - 建议优先修复 🔴 严重问题
+   - 建议补充缺失的业务功能
+   - 建议合并前解决所有 🟡 警告
+   ```
+
+5. 如果条件允许,自动在浏览器中打开报告
+
+---
+
+## 输出规范
+
+### 必须做到:
+
+- ✅ 所有代码差异必须完整展示,不可省略
+- ✅ 评审意见必须具体,关联到具体代码行
+- ✅ HTML 必须是自包含的,复制文件到任何地方都能正常打开
+- ✅ 保持代码原有的缩进和格式
+- ✅ 中文界面,评审意见使用中文
+- ✅ 如果提供了需求文档,必须进行业务风险分析
+- ✅ 技术风险和业务风险分开展示,但关联到相同代码
+
+### 禁止做到:
+
+- ❌ 不得引用外部 CDN 资源
+- ❌ 不得生成不完整的 HTML
+- ❌ 不得忽略任何变更文件
+- ❌ 不得给出模糊的评审意见(如"代码需要优化")
+- ❌ 不得修改任何源代码文件
+- ❌ 不得在没有需求文档的情况下臆测业务风险
+
+---
+
+## 风险等级定义
+
+### 技术风险等级
+
+| 等级 | 标识 | 说明 | 处理建议 |
+|------|------|------|----------|
+| 严重 | 🔴 | 会导致崩溃、安全漏洞、数据丢失 | 必须修复后才能合并 |
+| 警告 | 🟡 | 会影响性能、可维护性、用户体验 | 建议修复后合并 |
+| 建议 | 🔵 | 代码优化、重构建议 | 可在后续迭代中处理 |
+| 提示 | ⚪ | 信息说明、最佳实践提醒 | 可选处理 |
+
+### 业务风险等级
+
+| 等级 | 标识 | 说明 | 处理建议 |
+|------|------|------|----------|
+| 严重 | 🔴 | 缺失核心功能、业务流程错误 | 必须修复后才能上线 |
+| 警告 | 🟡 | 缺少异常场景处理、边界条件遗漏 | 建议补充后上线 |
+| 建议 | 🔵 | 体验优化、流程改进 | 可在后续迭代中优化 |
+
+---
+
+## 示例用法
+
+### 示例 1: 仅技术风险分析
+
+```
+用户: 评审当前分支
+
+AI: ### 第一步:确认评审上下文
+
+请提供本次开发需求的文档路径(可选),用于业务风险分析:
+- 如果不提供,将仅进行技术类风险分析。
+
+[用户留空]
+
+✅ 评审上下文已确认:
+- 功能分支: feature/user-management
+- 主分支: main
+- 需求文档: 未提供
+- 评审范围: 仅技术风险
+
+[继续执行技术风险分析...]
+```
+
+### 示例 2: 技术 + 业务风险分析
+
+```
+用户: 评审当前分支,需求文档在 docs/prd-order-module.md
+
+AI: ### 第一步:确认评审上下文
+
+已读取需求文档: docs/prd-order-module.md
+- 核心业务目标: 实现完整的订单管理模块
+- 关键功能点: 订单创建、支付、退款、订单列表
+- 业务约束: 库存不足时不允许下单
+- 验收标准: 支持微信/支付宝支付
+
+✅ 评审上下文已确认:
+- 功能分支: feature/order-module
+- 主分支: master
+- 需求文档: 已读取
+- 评审范围: 技术风险 + 业务风险
+
+[继续执行技术 + 业务风险分析...]
+```
+
+---
+
+## 与其他技能的协作
+
+- **依赖技能**: 无
+- **被依赖技能**: `execute-task`(可基于评审结果生成修复任务)
+- **配合使用**: 
+  - 评审完成后,可使用 `/spec-update` 更新需求
+  - 发现问题后,可使用 `execute-task` 创建修复任务
+  - 修复完成后可再次运行本技能验证
+
+---
+
+## 版本历史
+
+- **v1.0.0** (2026-06-22): 初始版本,支持技术风险分析、业务风险分析、可视化 HTML 报告生成