@specpow/framework 0.5.10 → 0.5.12

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 buchengjin
-
-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 buchengjin
+
+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.

package/bin/specpow.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-
-/**
- * SpecPow CLI 入口
- * Spec-Powered AI Development Framework
- */
-
-import { runCli } from '../dist/cli/index.js';
-
-runCli();
+
+/**
+ * SpecPow CLI 入口
+ * Spec-Powered AI Development Framework
+ */
+
+import { runCli } from '../dist/cli/index.js';
+
+runCli();

package/builtin/schemas/bug-fix/schema.yaml

@@ -0,0 +1,64 @@
+# Bug 修复 Schema
+# 用于快速定位和修复 Bug 的工件流
+
+name: bug-fix
+description: 系统化定位和修复 Bug
+
+apply:
+  requires:
+    - tasks
+
+artifacts:
+  - id: proposal
+    name: Bug 描述
+    description: 描述 Bug 现象和复现步骤
+    requires: []
+    template: proposal.md
+    instruction: |
+      记录 Bug 信息：
+      - Bug 标题
+      - 复现步骤（Step 1, 2, 3...）
+      - 预期行为
+      - 实际行为
+      - 环境信息
+      - 影响范围
+    output: proposal.md
+
+  - id: analysis
+    name: 根因分析
+    description: 分析 Bug 根因
+    requires: [proposal]
+    template: analysis.md
+    instruction: |
+      根因分析（4 阶段）：
+      1. 调查 — 收集日志、堆栈、复现
+      2. 模式分析 — 识别错误模式
+      3. 假设 — 提出根因假设
+      4. 验证 — 验证假设正确性
+    output: analysis.md
+
+  - id: fix-plan
+    name: 修复计划
+    description: 制定修复方案
+    requires: [analysis]
+    template: fix-plan.md
+    instruction: |
+      修复方案：
+      - 修复策略（热修复/正常修复/重构修复）
+      - 修改文件列表
+      - 回归测试计划
+    output: fix-plan.md
+
+  - id: tasks
+    name: 修复任务
+    description: 修复步骤拆分
+    requires: [fix-plan]
+    template: tasks.md
+    instruction: |
+      修复任务拆分：
+      1. 编写失败测试（复现 Bug）
+      2. 修复代码
+      3. 验证测试通过
+      4. 回归测试
+      5. 更新文档
+    output: tasks.md

package/builtin/schemas/bug-fix/templates/analysis.md

@@ -0,0 +1,43 @@
+# 根因分析
+
+## 1. 调查
+
+### 错误日志
+```
+（关键错误日志）
+```
+
+### 堆栈跟踪
+```
+（关键堆栈）
+```
+
+### 复现结果
+- 是否可稳定复现: 是/否
+- 复现频率: 
+
+## 2. 模式分析
+
+### 错误模式
+- 错误类型: 
+- 涉及模块: 
+- 最近变更: 
+
+## 3. 假设
+
+### 假设 1: [描述]
+- 证据: 
+- 验证方法: 
+
+### 假设 2: [描述]
+- 证据: 
+- 验证方法: 
+
+## 4. 结论
+
+### 根因
+[确认的根因描述]
+
+### 影响分析
+- 直接影响: 
+- 间接影响: 

package/builtin/schemas/bug-fix/templates/fix-plan.md

@@ -0,0 +1,19 @@
+# 修复方案
+
+## 修复策略
+- [ ] 热修复（紧急上线）
+- [ ] 正常修复（下个版本）
+- [ ] 重构修复（技术债务）
+
+## 修改文件
+| 文件 | 修改类型 | 说明 |
+|------|----------|------|
+| | | |
+
+## 修复描述
+
+
+## 回归测试计划
+- [ ] 原 Bug 场景验证
+- [ ] 相关功能回归
+- [ ] 边界条件验证

package/builtin/schemas/bug-fix/templates/proposal.md

@@ -0,0 +1,30 @@
+# Bug 描述
+
+## Bug 标题
+{{bugTitle}}
+
+## 复现步骤
+1. 
+2. 
+3. 
+
+## 预期行为
+
+
+## 实际行为
+
+
+## 环境信息
+- 环境: 
+- 版本: 
+- 浏览器/客户端: 
+
+## 影响范围
+- 影响用户: 
+- 影响功能: 
+- 严重程度: Critical / Major / Minor
+
+## 相关日志
+```
+（粘贴错误日志）
+```

package/builtin/schemas/crud-module/schema.yaml

@@ -0,0 +1,65 @@
+# CRUD 模块 Schema
+# 用于快速生成标准 CRUD 模块的工件流
+
+name: crud-module
+description: 快速生成标准 CRUD 模块（Entity/Mapper/Service/Controller/页面）
+
+apply:
+  requires:
+    - tasks
+
+artifacts:
+  - id: proposal
+    name: 模块提案
+    description: 描述要生成的 CRUD 模块
+    requires: []
+    template: proposal.md
+    instruction: |
+      根据用户描述，生成 CRUD 模块提案。
+      包含：模块名称、核心实体、CRUD 操作列表、业务规则。
+    output: proposal.md
+
+  - id: specs
+    name: 模块规范
+    description: 定义 CRUD 接口规范
+    requires: [proposal]
+    template: spec.md
+    instruction: |
+      定义 CRUD 接口规范：
+      - GET /api/{entity} — 分页查询
+      - GET /api/{entity}/:id — 详情查询
+      - POST /api/{entity} — 新增
+      - PUT /api/{entity}/:id — 修改
+      - DELETE /api/{entity}/:id — 删除
+      每个接口定义请求参数和响应格式。
+    output: specs/spec.md
+
+  - id: design
+    name: 模块设计
+    description: 数据库设计和接口定义
+    requires: [proposal, specs]
+    template: design.md
+    instruction: |
+      设计数据库表结构和接口定义：
+      - 表结构（字段、类型、索引）
+      - 接口签名
+      - 前后端分工
+    output: design.md
+
+  - id: tasks
+    name: 任务列表
+    description: 代码生成任务拆分
+    requires: [design]
+    template: tasks.md
+    instruction: |
+      按以下顺序拆分任务：
+      1. Entity 实体类
+      2. Mapper + XML
+      3. Service 接口 + 实现
+      4. Controller
+      5. 前端 API 接口
+      6. 前端列表页
+      7. 前端表单页
+      8. 菜单注册
+      9. 单元测试
+    output: tasks.md

package/builtin/schemas/crud-module/templates/design.md

@@ -0,0 +1,36 @@
+# CRUD 模块设计
+
+## 1. 数据库设计
+
+### 表结构
+```sql
+CREATE TABLE `{{table_name}}` (
+  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  -- 业务字段（根据提案填充）
+  `create_by` varchar(64) DEFAULT '' COMMENT '创建人',
+  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_by` varchar(64) DEFAULT '' COMMENT '更新人',
+  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `is_deleted` tinyint(1) DEFAULT 0 COMMENT '逻辑删除',
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='{{table_comment}}';
+```
+
+## 2. 接口定义
+
+| Method | Path | 描述 | 请求参数 | 响应 |
+|--------|------|------|----------|------|
+| GET | /api/{{entity}} | 分页查询 | page, size, 查询条件 | PageResult |
+| GET | /api/{{entity}}/:id | 详情 | - | EntityVO |
+| POST | /api/{{entity}} | 新增 | EntityDTO | id |
+| PUT | /api/{{entity}}/:id | 修改 | EntityDTO | - |
+| DELETE | /api/{{entity}}/:id | 删除 | - | - |
+
+## 3. 前后端分工
+
+| 功能 | 前端 | 后端 |
+|------|------|------|
+| 列表页 | 表格+搜索+分页 | 分页查询接口 |
+| 新增 | 表单弹窗 | 新增接口 |
+| 编辑 | 表单弹窗 | 修改接口 |
+| 删除 | 确认弹窗 | 删除接口 |

package/builtin/schemas/crud-module/templates/proposal.md

@@ -0,0 +1,30 @@
+# CRUD 模块提案
+
+## 模块名称
+{{moduleName}}
+
+## 核心实体
+- 实体名: 
+- 表名: 
+- 描述: 
+
+## CRUD 操作
+- [ ] 分页查询（列表）
+- [ ] 详情查询
+- [ ] 新增
+- [ ] 修改
+- [ ] 删除
+- [ ] 导出（可选）
+- [ ] 导入（可选）
+
+## 业务规则
+1. 
+2. 
+
+## 字段清单
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| | | | |
+
+## 非目标
+- 不包含: 

package/builtin/schemas/crud-module/templates/spec.md

@@ -0,0 +1,33 @@
+# CRUD 接口规范
+
+## ADDED Requirements
+
+### API-001: 分页查询
+系统应当提供 `GET /api/{{entity}}` 接口，支持分页查询。
+
+**验收标准:**
+- **Given** 数据库中存在 {{entity}} 记录
+- **When** 用户请求 `GET /api/{{entity}}?page=1&size=10`
+- **Then** 返回分页数据，包含 total、list、page、size
+
+### API-002: 详情查询
+系统应当提供 `GET /api/{{entity}}/:id` 接口。
+
+**验收标准:**
+- **Given** 存在 ID 为 1 的记录
+- **When** 用户请求 `GET /api/{{entity}}/1`
+- **Then** 返回该记录详情
+
+### API-003: 新增
+系统应当提供 `POST /api/{{entity}}` 接口。
+
+**验收标准:**
+- **Given** 用户提供必填字段
+- **When** 用户请求 `POST /api/{{entity}}`
+- **Then** 创建记录并返回新 ID
+
+### API-004: 修改
+系统应当提供 `PUT /api/{{entity}}/:id` 接口。
+
+### API-005: 删除
+系统应当提供 `DELETE /api/{{entity}}/:id` 接口（逻辑删除）。

package/builtin/schemas/crud-module/templates/tasks.md

@@ -0,0 +1,57 @@
+# CRUD 任务列表
+
+## 全局约束
+- 分支: feature/{{branch}}
+- 基础: main 分支最新代码
+
+## 后端任务
+
+### Task-001: 创建 Entity
+- 文件: `src/main/java/com/company/{{module}}/entity/{{Entity}}.java`
+- 依赖: 无
+- 描述: 创建实体类，字段与数据库对应
+- 验证: 编译通过
+
+### Task-002: 创建 Mapper
+- 文件: `src/main/java/com/company/{{module}}/mapper/{{Entity}}Mapper.java`, `src/main/resources/mapper/{{Entity}}Mapper.xml`
+- 依赖: Task-001
+- 描述: 创建数据访问层
+- 验证: 编译通过
+
+### Task-003: 创建 Service
+- 文件: `src/main/java/com/company/{{module}}/service/{{Entity}}Service.java`, `src/main/java/com/company/{{module}}/service/impl/{{Entity}}ServiceImpl.java`
+- 依赖: Task-002
+- 描述: 创建业务逻辑层（CRUD 方法）
+- 验证: 编译通过
+
+### Task-004: 创建 Controller
+- 文件: `src/main/java/com/company/{{module}}/controller/{{Entity}}Controller.java`
+- 依赖: Task-003
+- 描述: 创建 RESTful 接口
+- 验证: 编译通过，接口可访问
+
+## 前端任务
+
+### Task-005: 创建 API 接口文件
+- 文件: `src/api/{{entity}}.js`
+- 依赖: Task-004
+- 描述: 封装 axios 请求
+- 验证: 无语法错误
+
+### Task-006: 创建列表页
+- 文件: `src/views/{{module}}/{{entity}}/index.vue`
+- 依赖: Task-005
+- 描述: 列表页（搜索+表格+分页+操作按钮）
+- 验证: 页面可渲染
+
+### Task-007: 创建表单弹窗
+- 文件: `src/views/{{module}}/{{entity}}/form.vue`
+- 依赖: Task-005
+- 描述: 新增/编辑表单弹窗
+- 验证: 表单验证生效
+
+### Task-008: 注册路由和菜单
+- 文件: `src/router/modules/{{module}}.js`
+- 依赖: Task-006
+- 描述: 配置路由和菜单 SQL
+- 验证: 菜单可见，页面可访问

package/builtin/schemas/spec-driven/schema.yaml

@@ -0,0 +1,87 @@
+# SpecPow 默认 Schema: spec-driven
+# 四阶段工件流: proposal → specs → design → tasks → apply
+# 融合 OpenSpec 的规范驱动 + Superpowers 的执行方法论
+
+name: spec-driven
+description: |
+  规格驱动开发工作流。
+  在 AI 写代码之前，让人类和 AI 对"要构建什么"达成一致。
+  然后通过 SDD 子代理驱动引擎高质量地执行实现。
+
+apply:
+  requires:
+    - tasks    # 实施前必须完成所有工件
+
+artifacts:
+  - id: proposal
+    name: 提案
+    description: 为什么做这个变更？解决什么问题？
+    requires: []
+    template: proposal.md
+    instruction: |
+      创建变更提案。回答：
+      1. 为什么要做这个变更？（动机）
+      2. 要解决什么问题？
+      3. 成功标准是什么？
+      4. 影响范围和风险？
+      
+      注意：先使用 brainstorming 技能进行需求探索，再写提案。
+    output: proposal.md
+
+  - id: specs
+    name: 规范
+    description: 系统必须做什么？（行为契约，不是实现计划）
+    requires:
+      - proposal
+    template: spec.md
+    instruction: |
+      创建 Delta 规范。使用增量操作描述变更：
+      - ADDED Requirements: 新增的需求
+      - MODIFIED Requirements: 修改的需求（包含完整更新内容）
+      - REMOVED Requirements: 移除的需求（含原因和迁移方案）
+      - RENAMED Requirements: 重命名的需求
+      
+      规范是行为契约，描述系统做什么，不描述怎么做。
+      每个需求必须可验证。
+    output: specs/<capability>/spec.md
+
+  - id: design
+    name: 设计
+    description: 怎么做？技术方案和架构决策
+    requires:
+      - proposal
+      - specs
+    template: design.md
+    instruction: |
+      创建技术设计文档。包含：
+      1. 架构决策（ADR 格式）
+      2. 模块划分和接口定义
+      3. 数据模型设计
+      4. 前后端分工
+      5. 关键实现路径
+      
+      如果变更较小（< 3个文件），可以跳过此工件。
+    output: design.md
+    conditional: true
+
+  - id: tasks
+    name: 任务
+    description: 实施步骤（SDD 引擎将逐个执行）
+    requires:
+      - proposal
+      - specs
+      - design
+    template: tasks.md
+    instruction: |
+      创建实现任务列表。每个任务应该：
+      1. 足够小（2-5分钟完成）
+      2. 包含精确的文件路径
+      3. 包含完整的代码或明确的修改指令
+      4. 包含验证步骤
+      5. 任务之间尽量独立（便于 SDD 并行）
+      
+      格式：
+      - [ ] Task 1: <标题>
+        <详细描述，包含精确文件路径和代码>
+        验证: <如何验证>
+    output: tasks.md

package/builtin/schemas/spec-driven/templates/design.md

@@ -0,0 +1,54 @@
+# 技术设计: <变更名称>
+
+## 架构决策
+
+### ADR-001: <决策标题>
+
+**状态**: 已采纳
+
+**背景**: <为什么需要这个决策>
+
+**决策**: <选择了什么方案>
+
+**备选方案**:
+- 方案 A: <描述> — 优点/缺点
+- 方案 B: <描述> — 优点/缺点
+
+**后果**: <这个决策带来的影响>
+
+---
+
+## 模块划分
+
+```
+<模块图>
+```
+
+## 接口定义
+
+### <接口名>
+
+- **路径**: `METHOD /api/xxx`
+- **请求**: 
+- **响应**: 
+- **错误码**: 
+
+## 数据模型
+
+### <表名/实体名>
+
+| 字段 | 类型 | 说明 | 约束 |
+|------|------|------|------|
+|      |      |      |      |
+
+## 前后端分工
+
+| 功能 | 前端 | 后端 | 说明 |
+|------|------|------|------|
+|      |      |      |      |
+
+## 关键实现路径
+
+1. <步骤 1>
+2. <步骤 2>
+3. <步骤 3>

package/builtin/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,31 @@
+# 变更提案: <变更名称>
+
+## 动机
+
+为什么要做这个变更？解决什么问题？
+
+## 目标
+
+- 目标 1
+- 目标 2
+
+## 成功标准
+
+- [ ] 标准 1
+- [ ] 标准 2
+
+## 影响范围
+
+- 影响的模块：
+- 影响的接口：
+- 影响的数据表：
+
+## 风险评估
+
+| 风险 | 影响 | 概率 | 应对 |
+|------|------|------|------|
+|      |      |      |      |
+
+## 非目标
+
+明确列出这次不做什么。

package/builtin/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,42 @@
+# 规范: <能力路径>
+
+## ADDED Requirements
+
+### REQ-001: <需求标题>
+
+**描述**: <系统应该做什么>
+
+**验收标准**:
+- Given <前置条件>
+- When <操作>
+- Then <预期结果>
+
+**约束**:
+- <性能/安全/兼容性约束>
+
+---
+
+## MODIFIED Requirements
+
+### REQ-XXX: <需求标题>
+
+**变更原因**: <为什么修改>
+
+**更新内容**:
+<完整的新需求描述>
+
+---
+
+## REMOVED Requirements
+
+### REQ-XXX: <需求标题>
+
+**移除原因**: <为什么移除>
+
+**迁移方案**: <现有用户/数据如何处理>
+
+---
+
+## RENAMED Requirements
+
+### <旧需求名称> → <新需求名称>