@gong-ym/ai-spec-auto 0.2.12 → 0.2.14

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

@@ -1,9 +1,9 @@
 ---
 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.
+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.0.0"
+  version: "1.1.0"
   openclaw-user-invocable: "true"
   type: flexible
   category: code-review
@@ -55,20 +55,35 @@ metadata:
    - 如果用户指定了分支,使用用户指定的分支
    - 如果用户未指定,使用当前分支作为功能分支,自动检测主分支(优先 master,其次 main)
 
-3. **重要**: 询问用户是否提供本次开发需求的文档:
+3. **重要**: 首先检查本次开发是否已有需求文档归档:
+   ```bash
+   # 检查 .ai-spec/ 目录下是否有本次开发的需求文档
+   ls .ai-spec/ | grep -E "(spec|proposal|requirement|prd)"
+   ```
+   
+   然后根据情况询问用户:
    ```
-   请提供本次开发需求的文档路径(可选),用于业务风险分析:
-   - 需求文档类型: PRD / 用户故事 / 需求规格说明 / 其他
-   - 文档路径: [用户输入或留空]
+   请选择本次业务审查的模式:
    
-   如果不提供需求文档,将仅进行技术类风险分析。
+   1. 需求文档模式(推荐) - 使用本次开发归档的需求文档进行审查
+      - 适用场景:使用 OpenSpec/Superpowers 完成的需求开发,已有需求文档归档到 .ai-spec/
+      - 文档路径: [.ai-spec/ 下的需求文档]
+      
+   2. 外部需求文档 - 提供本次开发的需求文档路径
+      - 适用场景:需求文档在其他位置(PRD、用户故事等)
+      - 文档路径: [用户输入]
+      
+   3. 项目说明模式 - 基于项目说明文档和 master 基线进行泛类审查
+      - 适用场景:重构、优化、技术债清理等无明确需求文档的场景
+      
+   请输入选项编号(1/2/3),或直接提供文档路径(默认模式1):
+   [用户输入]
    ```
 
-4. 如果用户提供了需求文档,读取并分析:
-   - 核心业务目标
-   - 关键功能点
-   - 业务约束与规则
-   - 验收标准
+4. 根据用户选择执行:
+   - **模式1(归档需求文档)**: 读取 `.ai-spec/` 目录下的需求文档,分析核心业务目标、关键功能点、业务约束与规则、验收标准
+   - **模式2(外部需求文档)**: 读取用户提供的需求文档路径,分析核心业务目标、关键功能点、业务约束与规则、验收标准
+   - **模式3(项目说明)**: 读取项目说明文档(README.md/PROJECT.md等),提取项目定位、核心能力、关键业务模块、既有业务规则
 
 5. 输出确认信息:
    ```
@@ -172,13 +187,18 @@ metadata:
 - 更优的实现方式
 - 代码简化建议
 
-### 第四步:业务类风险分析(如果提供了需求文档)
+### 第四步:业务类风险分析
 
 **强制输出标题**: `### 第四步:业务风险分析`
 
-**仅当用户提供需求文档时执行此步骤**。
+**业务审查的三种模式**:
+1. **需求文档模式(推荐)**: 使用本次开发归档到 `.ai-spec/` 的需求文档进行审查
+2. **外部需求文档**: 用户提供本次开发的需求文档路径
+3. **项目说明模式**: 如果没有需求文档,读取项目说明文档(如 README.md、PROJECT.md、01-项目概述.md等),结合 master 分支的代码基线,进行泛类业务审查
 
-#### 4.1 需求覆盖度检查
+#### 4.1 模式一:需求文档覆盖度检查(推荐模式)
+
+**优先使用本次开发归档到 `.ai-spec/` 的需求文档**。
 
 对比代码变更与需求文档,检查:
 
@@ -187,33 +207,76 @@ metadata:
 - **业务规则**: 代码实现是否符合业务规则
 - **边界场景**: 需求文档中提到的边界场景是否都处理了
 
-#### 4.2 业务逻辑风险
+#### 4.2 模式二:外部需求文档审查
+
+用户提供本次开发的需求文档路径,检查内容同模式一。
 
-识别以下业务风险:
+#### 4.3 模式三:项目说明与基线对比审查(通用模式)
 
-- **流程缺失**: 关键业务流程是否遗漏
-  - 例如:订单创建后缺少支付流程
-  
-- **状态不一致**: 业务状态流转是否正确
-  - 例如:订单状态从"待支付"直接跳到"已完成",缺少"已支付"状态
+**当没有需求文档时,执行此模式**。
 
-- **数据一致性**: 数据操作是否符合业务约束
-  - 例如:库存扣减与订单创建不在同一事务
+1. **读取项目说明文档**:
+   - 优先读取: `README.md`、`PROJECT.md`、`01-项目概述.md`、`docs/` 目录下的项目说明
+   - 提取信息:
+     - 项目定位与核心能力
+     - 关键业务模块与功能
+     - 技术栈与架构约束
+     - 已有的业务规则与流程
 
-- **权限与合规**: 是否符合业务权限要求
-  - 例如:未校验用户权限即可操作敏感数据
+2. **对比 master 分支基线**:
+   - 分析功能分支相对于 master 的变更范围
+   - 识别变更是否影响核心业务流程
+   - 检查新增代码是否与项目既有业务逻辑一致
 
-- **异常场景**: 业务异常场景是否处理
-  - 例如:支付失败后的回滚逻辑
-  - 例如:库存不足时的降级方案
+3. **泛类业务审查维度**:
+   
+   - **业务流程完整性**:
+     - 关键业务流程是否遗漏(如:创建→审批→执行→归档)
+     - 新增功能是否缺少上下游衔接
+     - 例如:新增订单创建但缺少支付/退款流程
+   
+   - **状态流转一致性**:
+     - 业务状态流转是否符合项目既有模式
+     - 是否存在状态跳跃或缺失中间态
+     - 例如:订单状态从"待支付"直接到"已完成",缺少"已支付"
+   
+   - **数据约束与一致性**:
+     - 数据操作是否符合项目已有的数据约束
+     - 关键业务数据是否缺少校验
+     - 例如:金额字段缺少精度校验,库存扣减不在事务中
+   
+   - **权限与合规性**:
+     - 是否符合项目既有的权限控制模式
+     - 敏感操作是否缺少权限校验
+     - 例如:未校验用户角色即可删除核心数据
+   
+   - **异常场景处理**:
+     - 业务异常是否有降级方案
+     - 失败场景是否有补偿机制
+     - 例如:支付失败后无回滚逻辑,接口超时无重试
+   
+   - **与既有代码的一致性**:
+     - 新增代码是否遵循项目既有的业务抽象
+     - 是否重复实现了已有的业务逻辑
+     - 例如:项目已有统一的审批流引擎,但新代码自己实现了一套
 
 #### 4.3 业务改进建议
 
-输出具体的:
+根据审查模式输出:
+
+**需求文档模式(模式1/2)**:
 - 缺失功能点清单
 - 业务逻辑修正建议
 - 流程补充建议
 - 风险控制建议
+- 需求覆盖度评分
+
+**项目说明模式(模式3)**:
+- 与项目既有业务逻辑不一致的代码清单
+- 可能缺失的业务流程环节
+- 建议补充的异常处理场景
+- 可复用的项目既有业务抽象
+- 业务一致性评分
 
 ### 第五步:生成可视化 HTML 报告
 
@@ -272,18 +335,18 @@ metadata:
   - 示例代码
   - 关联到具体代码行
 
-##### 5. 业务风险区(Business Risks) - 如果有需求文档
+##### 5. 业务风险区(Business Risks) - 如果有业务风险分析
 
-业务风险分析结果:
+业务风险分析结果(需求文档模式或项目说明模式):
 
-- 需求覆盖度评分
-- 缺失功能点清单
+- 需求覆盖度评分(需求文档模式) / 业务一致性评分(项目说明模式)
+- 缺失功能点清单 / 与既有业务逻辑不一致的代码清单
 - 业务逻辑风险
 - 流程缺失警告
 - 状态不一致问题
 - 数据一致性问题
 - 每个业务风险关联到:
-  - 需求文档章节
+  - 需求文档章节(需求文档模式) / 项目说明文档(项目说明模式)
   - 相关代码文件
   - 风险等级
   - 修复建议
@@ -361,7 +424,9 @@ metadata:
 - ✅ HTML 必须是自包含的,复制文件到任何地方都能正常打开
 - ✅ 保持代码原有的缩进和格式
 - ✅ 中文界面,评审意见使用中文
-- ✅ 如果提供了需求文档,必须进行业务风险分析
+- ✅ 优先使用本次开发归档到 `.ai-spec/` 的需求文档进行业务审查
+- ✅ 如果用户选择需求文档模式,必须进行需求覆盖度审查
+- ✅ 如果用户选择项目说明模式,必须基于项目说明和 master 基线进行泛类业务审查
 - ✅ 技术风险和业务风险分开展示,但关联到相同代码
 
 ### 禁止做到:
@@ -371,7 +436,7 @@ metadata:
 - ❌ 不得忽略任何变更文件
 - ❌ 不得给出模糊的评审意见(如"代码需要优化")
 - ❌ 不得修改任何源代码文件
-- ❌ 不得在没有需求文档的情况下臆测业务风险
+- ❌ 不得在没有项目说明文档的情况下臆测业务风险
 
 ---
 
@@ -398,25 +463,33 @@ metadata:
 
 ## 示例用法
 
-### 示例 1: 仅技术风险分析
+### 示例 1: 技术 + 业务风险分析(项目说明模式)
 
 ```
 用户: 评审当前分支
 
 AI: ### 第一步:确认评审上下文
 
-请提供本次开发需求的文档路径(可选),用于业务风险分析:
-- 如果不提供,将仅进行技术类风险分析。
+请选择本次业务审查的模式:
+
+1. 需求文档模式 - 提供本次开发的需求文档,对照需求审查
+2. 项目说明模式 - 基于项目说明文档和 master 基线进行泛类审查
 
+请提供需求文档路径(选1时),或直接回车使用项目说明模式(选2):
 [用户留空]
 
+已读取项目说明: README.md
+- 项目定位: 风控管理系统
+- 核心能力: 规则引擎、审批流、数据权限
+- 关键业务模块: 规则配置、风险预警、审计日志
+
 ✅ 评审上下文已确认:
-- 功能分支: feature/user-management
+- 功能分支: feature/rule-optimization
 - 主分支: main
-- 需求文档: 未提供
-- 评审范围: 仅技术风险
+- 审查模式: 项目说明模式
+- 评审范围: 技术风险 + 业务风险
 
-[继续执行技术风险分析...]
+[继续执行技术 + 业务风险分析...]
 ```
 
 ### 示例 2: 技术 + 业务风险分析
@@ -456,4 +529,5 @@ AI: ### 第一步:确认评审上下文
 
 ## 版本历史
 
+- **v1.1.0** (2026-06-26): 支持双模式业务审查(需求文档模式 + 项目说明模式),新增泛类业务审查维度
 - **v1.0.0** (2026-06-22): 初始版本,支持技术风险分析、业务风险分析、可视化 HTML 报告生成

package/.qoder/README.md

@@ -1,114 +1,114 @@
-# Qoder IDE 适配说明
-
-## 概述
-
-`ai-spec-auto` 现已支持 **Qoder IDE**。Qoder 是一款面向 AI 辅助开发的智能 IDE,提供强大的代码理解和生成能力。
-
-## 安装 Qoder 适配
-
-### 方式 1: 默认安装(包含 Qoder)
-
-```bash
-npx @engineered/ai-spec-auto@latest init . --ide all
-```
-
-### 方式 2: 仅安装 Qoder
-
-```bash
-npx @engineered/ai-spec-auto@latest init . --ide qoder
-```
-
-### 方式 3: 组合安装
-
-```bash
-# Qoder + Cursor
-npx @engineered/ai-spec-auto@latest init . --ide qoder,cursor
-
-# Qoder + Claude Code
-npx @engineered/ai-spec-auto@latest init . --ide qoder,claude
-```
-
-## 安装后的目录结构
-
-```
-.your-project/
-├── .qoder/
-│   ├── rules/              → 链接到 .agents/rules/
-│   ├── skills/             → 链接到 .agents/skills/
-│   └── commands/           → 协议命令模板
-│       ├── spec-start.md
-│       ├── spec-continue.md
-│       ├── spec-update.md
-│       ├── spec-status.md
-│       └── spec-stop.md
-├── .agents/                # 规范源
-│   ├── rules/
-│   └── skills/
-└── .ai-spec/               # 运行态数据
-```
-
-## 可用命令
-
-安装完成后,在 Qoder 中可以使用以下协议命令:
-
-| 命令 | 用途 |
-|------|------|
-| `/spec-start` | 新建一个需求交付 run |
-| `/spec-continue` | 继续或恢复当前 run |
-| `/spec-update` | 增量补充需求、修正方向 |
-| `/spec-status` | 查看当前阶段、门禁和下一步 |
-| `/spec-stop` | 暂停当前 run |
-
-## 配置示例
-
-### MCP 配置(可选)
-
-如果 Qoder 支持 MCP(Model Context Protocol),可以创建 `.qoder/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "ai-spec-auto": {
-      "command": "npx",
-      "args": ["@engineered/ai-spec-auto@latest"]
-    }
-  }
-}
-```
-
-## 更新 Qoder 适配
-
-```bash
-# 更新所有 IDE 适配
-npx @engineered/ai-spec-auto@latest update .
-
-# 仅更新 Qoder
-npx @engineered/ai-spec-auto@latest update . --ide qoder
-```
-
-## 检查安装
-
-```bash
-npx @engineered/ai-spec-auto@latest check .
-```
-
-检查输出中应该包含:
-```
-✅ .qoder/rules 链接有效
-✅ .qoder/skills (N 个链接)
-✅ 协议命令可用
-```
-
-## 卸载 Qoder 适配
-
-```bash
-npx @engineered/ai-spec-auto@latest uninstall .
-```
-
-这将移除 `.qoder/` 目录及其中的所有链接和命令模板。
-
-## 技术支持
-
-- 项目仓库: https://github.com/Colouful/engineered-spec
-- 问题反馈: https://github.com/Colouful/engineered-spec/issues
-- 文档索引: docs/README.md
+# Qoder IDE 适配说明
+
+## 概述
+
+`ai-spec-auto` 现已支持 **Qoder IDE**。Qoder 是一款面向 AI 辅助开发的智能 IDE,提供强大的代码理解和生成能力。
+
+## 安装 Qoder 适配
+
+### 方式 1: 默认安装(包含 Qoder)
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --ide all
+```
+
+### 方式 2: 仅安装 Qoder
+
+```bash
+npx @engineered/ai-spec-auto@latest init . --ide qoder
+```
+
+### 方式 3: 组合安装
+
+```bash
+# Qoder + Cursor
+npx @engineered/ai-spec-auto@latest init . --ide qoder,cursor
+
+# Qoder + Claude Code
+npx @engineered/ai-spec-auto@latest init . --ide qoder,claude
+```
+
+## 安装后的目录结构
+
+```
+.your-project/
+├── .qoder/
+│   ├── rules/              → 链接到 .agents/rules/
+│   ├── skills/             → 链接到 .agents/skills/
+│   └── commands/           → 协议命令模板
+│       ├── spec-start.md
+│       ├── spec-continue.md
+│       ├── spec-update.md
+│       ├── spec-status.md
+│       └── spec-stop.md
+├── .agents/                # 规范源
+│   ├── rules/
+│   └── skills/
+└── .ai-spec/               # 运行态数据
+```
+
+## 可用命令
+
+安装完成后,在 Qoder 中可以使用以下协议命令:
+
+| 命令 | 用途 |
+|------|------|
+| `/spec-start` | 新建一个需求交付 run |
+| `/spec-continue` | 继续或恢复当前 run |
+| `/spec-update` | 增量补充需求、修正方向 |
+| `/spec-status` | 查看当前阶段、门禁和下一步 |
+| `/spec-stop` | 暂停当前 run |
+
+## 配置示例
+
+### MCP 配置(可选)
+
+如果 Qoder 支持 MCP(Model Context Protocol),可以创建 `.qoder/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ai-spec-auto": {
+      "command": "npx",
+      "args": ["@engineered/ai-spec-auto@latest"]
+    }
+  }
+}
+```
+
+## 更新 Qoder 适配
+
+```bash
+# 更新所有 IDE 适配
+npx @engineered/ai-spec-auto@latest update .
+
+# 仅更新 Qoder
+npx @engineered/ai-spec-auto@latest update . --ide qoder
+```
+
+## 检查安装
+
+```bash
+npx @engineered/ai-spec-auto@latest check .
+```
+
+检查输出中应该包含:
+```
+✅ .qoder/rules 链接有效
+✅ .qoder/skills (N 个链接)
+✅ 协议命令可用
+```
+
+## 卸载 Qoder 适配
+
+```bash
+npx @engineered/ai-spec-auto@latest uninstall .
+```
+
+这将移除 `.qoder/` 目录及其中的所有链接和命令模板。
+
+## 技术支持
+
+- 项目仓库: https://github.com/gong-chick/engineered-spec
+- 问题反馈: https://github.com/gong-chick/engineered-spec/issues
+- 文档索引: docs/README.md

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Colouful
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 gong-chick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.