@gong-ym/ai-spec-auto 0.2.13 → 0.2.15

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

@@ -1,459 +1,533 @@
----
-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 报告生成
+---
+name: branch-code-reviewer
+description: 分支代码评审专家。将功能分支与主分支(master/main)进行代码比对分析,自动识别技术风险和业务风险,生成可视化HTML评审报告。当需要进行分支间代码评审、合并前代码检查、代码质量分析时使用。
+compatibility: Requires git repository with at least two branches. Supports both requirement documentation mode and project documentation mode for business risk analysis.
+metadata:
+  version: "1.1.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. **重要**: 首先检查本次开发是否已有需求文档归档:
+   ```bash
+   # 检查 .ai-spec/ 目录下是否有本次开发的需求文档
+   ls .ai-spec/ | grep -E "(spec|proposal|requirement|prd)"
+   ```
+   
+   然后根据情况询问用户:
+   ```
+   请选择本次业务审查的模式:
+   
+   1. 需求文档模式(推荐) - 使用本次开发归档的需求文档进行审查
+      - 适用场景:使用 OpenSpec/Superpowers 完成的需求开发,已有需求文档归档到 .ai-spec/
+      - 文档路径: [.ai-spec/ 下的需求文档]
+      
+   2. 外部需求文档 - 提供本次开发的需求文档路径
+      - 适用场景:需求文档在其他位置(PRD、用户故事等)
+      - 文档路径: [用户输入]
+      
+   3. 项目说明模式 - 基于项目说明文档和 master 基线进行泛类审查
+      - 适用场景:重构、优化、技术债清理等无明确需求文档的场景
+      
+   请输入选项编号(1/2/3),或直接提供文档路径(默认模式1):
+   [用户输入]
+   ```
+
+4. 根据用户选择执行:
+   - **模式1(归档需求文档)**: 读取 `.ai-spec/` 目录下的需求文档,分析核心业务目标、关键功能点、业务约束与规则、验收标准
+   - **模式2(外部需求文档)**: 读取用户提供的需求文档路径,分析核心业务目标、关键功能点、业务约束与规则、验收标准
+   - **模式3(项目说明)**: 读取项目说明文档(README.md/PROJECT.md等),提取项目定位、核心能力、关键业务模块、既有业务规则
+
+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 技术改进建议
+
+输出具体的:
+- 代码重构建议
+- 性能优化方案
+- 更优的实现方式
+- 代码简化建议
+
+### 第四步:业务类风险分析
+
+**强制输出标题**: `### 第四步:业务风险分析`
+
+**业务审查的三种模式**:
+1. **需求文档模式(推荐)**: 使用本次开发归档到 `.ai-spec/` 的需求文档进行审查
+2. **外部需求文档**: 用户提供本次开发的需求文档路径
+3. **项目说明模式**: 如果没有需求文档,读取项目说明文档(如 README.md、PROJECT.md、01-项目概述.md等),结合 master 分支的代码基线,进行泛类业务审查
+
+#### 4.1 模式一:需求文档覆盖度检查(推荐模式)
+
+**优先使用本次开发归档到 `.ai-spec/` 的需求文档**。
+
+对比代码变更与需求文档,检查:
+
+- **功能完整性**: 需求文档中的所有功能点是否都已实现
+- **验收标准**: 是否满足需求文档中的验收标准
+- **业务规则**: 代码实现是否符合业务规则
+- **边界场景**: 需求文档中提到的边界场景是否都处理了
+
+#### 4.2 模式二:外部需求文档审查
+
+用户提供本次开发的需求文档路径,检查内容同模式一。
+
+#### 4.3 模式三:项目说明与基线对比审查(通用模式)
+
+**当没有需求文档时,执行此模式**。
+
+1. **读取项目说明文档**:
+   - 优先读取: `README.md`、`PROJECT.md`、`01-项目概述.md`、`docs/` 目录下的项目说明
+   - 提取信息:
+     - 项目定位与核心能力
+     - 关键业务模块与功能
+     - 技术栈与架构约束
+     - 已有的业务规则与流程
+
+2. **对比 master 分支基线**:
+   - 分析功能分支相对于 master 的变更范围
+   - 识别变更是否影响核心业务流程
+   - 检查新增代码是否与项目既有业务逻辑一致
+
+3. **泛类业务审查维度**:
+   
+   - **业务流程完整性**:
+     - 关键业务流程是否遗漏(如:创建→审批→执行→归档)
+     - 新增功能是否缺少上下游衔接
+     - 例如:新增订单创建但缺少支付/退款流程
+   
+   - **状态流转一致性**:
+     - 业务状态流转是否符合项目既有模式
+     - 是否存在状态跳跃或缺失中间态
+     - 例如:订单状态从"待支付"直接到"已完成",缺少"已支付"
+   
+   - **数据约束与一致性**:
+     - 数据操作是否符合项目已有的数据约束
+     - 关键业务数据是否缺少校验
+     - 例如:金额字段缺少精度校验,库存扣减不在事务中
+   
+   - **权限与合规性**:
+     - 是否符合项目既有的权限控制模式
+     - 敏感操作是否缺少权限校验
+     - 例如:未校验用户角色即可删除核心数据
+   
+   - **异常场景处理**:
+     - 业务异常是否有降级方案
+     - 失败场景是否有补偿机制
+     - 例如:支付失败后无回滚逻辑,接口超时无重试
+   
+   - **与既有代码的一致性**:
+     - 新增代码是否遵循项目既有的业务抽象
+     - 是否重复实现了已有的业务逻辑
+     - 例如:项目已有统一的审批流引擎,但新代码自己实现了一套
+
+#### 4.3 业务改进建议
+
+根据审查模式输出:
+
+**需求文档模式(模式1/2)**:
+- 缺失功能点清单
+- 业务逻辑修正建议
+- 流程补充建议
+- 风险控制建议
+- 需求覆盖度评分
+
+**项目说明模式(模式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 必须是自包含的,复制文件到任何地方都能正常打开
+- ✅ 保持代码原有的缩进和格式
+- ✅ 中文界面,评审意见使用中文
+- ✅ 优先使用本次开发归档到 `.ai-spec/` 的需求文档进行业务审查
+- ✅ 如果用户选择需求文档模式,必须进行需求覆盖度审查
+- ✅ 如果用户选择项目说明模式,必须基于项目说明和 master 基线进行泛类业务审查
+- ✅ 技术风险和业务风险分开展示,但关联到相同代码
+
+### 禁止做到:
+
+- ❌ 不得引用外部 CDN 资源
+- ❌ 不得生成不完整的 HTML
+- ❌ 不得忽略任何变更文件
+- ❌ 不得给出模糊的评审意见(如"代码需要优化")
+- ❌ 不得修改任何源代码文件
+- ❌ 不得在没有项目说明文档的情况下臆测业务风险
+
+---
+
+## 风险等级定义
+
+### 技术风险等级
+
+| 等级 | 标识 | 说明 | 处理建议 |
+|------|------|------|----------|
+| 严重 | 🔴 | 会导致崩溃、安全漏洞、数据丢失 | 必须修复后才能合并 |
+| 警告 | 🟡 | 会影响性能、可维护性、用户体验 | 建议修复后合并 |
+| 建议 | 🔵 | 代码优化、重构建议 | 可在后续迭代中处理 |
+| 提示 | ⚪ | 信息说明、最佳实践提醒 | 可选处理 |
+
+### 业务风险等级
+
+| 等级 | 标识 | 说明 | 处理建议 |
+|------|------|------|----------|
+| 严重 | 🔴 | 缺失核心功能、业务流程错误 | 必须修复后才能上线 |
+| 警告 | 🟡 | 缺少异常场景处理、边界条件遗漏 | 建议补充后上线 |
+| 建议 | 🔵 | 体验优化、流程改进 | 可在后续迭代中优化 |
+
+---
+
+## 示例用法
+
+### 示例 1: 技术 + 业务风险分析(项目说明模式)
+
+```
+用户: 评审当前分支
+
+AI: ### 第一步:确认评审上下文
+
+请选择本次业务审查的模式:
+
+1. 需求文档模式 - 提供本次开发的需求文档,对照需求审查
+2. 项目说明模式 - 基于项目说明文档和 master 基线进行泛类审查
+
+请提供需求文档路径(选1时),或直接回车使用项目说明模式(选2):
+[用户留空]
+
+已读取项目说明: README.md
+- 项目定位: 风控管理系统
+- 核心能力: 规则引擎、审批流、数据权限
+- 关键业务模块: 规则配置、风险预警、审计日志
+
+✅ 评审上下文已确认:
+- 功能分支: feature/rule-optimization
+- 主分支: main
+- 审查模式: 项目说明模式
+- 评审范围: 技术风险 + 业务风险
+
+[继续执行技术 + 业务风险分析...]
+```
+
+### 示例 2: 技术 + 业务风险分析
+
+```
+用户: 评审当前分支,需求文档在 docs/prd-order-module.md
+
+AI: ### 第一步:确认评审上下文
+
+已读取需求文档: docs/prd-order-module.md
+- 核心业务目标: 实现完整的订单管理模块
+- 关键功能点: 订单创建、支付、退款、订单列表
+- 业务约束: 库存不足时不允许下单
+- 验收标准: 支持微信/支付宝支付
+
+✅ 评审上下文已确认:
+- 功能分支: feature/order-module
+- 主分支: master
+- 需求文档: 已读取
+- 评审范围: 技术风险 + 业务风险
+
+[继续执行技术 + 业务风险分析...]
+```
+
+---
+
+## 与其他技能的协作
+
+- **依赖技能**: 无
+- **被依赖技能**: `execute-task`(可基于评审结果生成修复任务)
+- **配合使用**: 
+  - 评审完成后,可使用 `/spec-update` 更新需求
+  - 发现问题后,可使用 `execute-task` 创建修复任务
+  - 修复完成后可再次运行本技能验证
+
+---
+
+## 版本历史
+
+- **v1.1.0** (2026-06-26): 支持双模式业务审查(需求文档模式 + 项目说明模式),新增泛类业务审查维度
+- **v1.0.0** (2026-06-22): 初始版本,支持技术风险分析、业务风险分析、可视化 HTML 报告生成