@chongyan/autospec 1.0.1

package/knowledge/guides/stages/design-planner.md

@@ -0,0 +1,401 @@
+---
+name: design-planner
+description: 当结构化需求文档通过评审、需要转化为可指导编码的技术方案时触发
+type: produce
+---
+
+## 定位
+设计阶段的核心"做"类skill。将需求文档转化为技术方案，做出关键技术决策。
+
+## 输入
+- 必须输入：经需求评审通过的结构化需求文档（含关键假设清单）
+- 可选输入：项目技术栈信息、现有系统架构信息、领域知识
+
+## 输出
+
+### Step 1: 确定模式
+
+读取 `.autospec/config.json`，检查 `subsystems` 字段：
+- **无 subsystems 或长度为1** → 单系统模式
+- **有 subsystems 且长度>1** → 多系统模式
+
+检查是否需要效果指标设计：
+- 有 `type: ai` 的子系统 → 需要效果指标设计
+- 需求文档包含效果相关指标 → 需要效果指标设计
+
+### 单系统模式（普通功能）
+
+**`.autospec/specs/{feature}/design.md`**，包含：
+- 架构设计（分层、模块、组件关系，含架构图）
+- 数据模型设计（实体、关系、存储选型）
+- 接口/API设计（输入输出、协议、错误码）
+- 技术选型及理由（含放弃方案的理由）
+- 关键决策记录（选了什么、为什么、放弃了什么）
+- 风险评估和应对策略
+- 工作量预估和任务拆分（含依赖关系和并行标记）
+- 关键假设清单（继承需求阶段 + 本阶段新增，标注已确认/待确认）
+- 证据清单（参考项目、性能数据、技术文档等）
+
+### 多系统模式
+
+产出以下文件结构：
+
+**1. `.autospec/specs/{feature}/design/overview.md`** — 整体架构
+- 系统交互图（描述各子系统如何协作）
+- 数据流向
+- 跨系统接口契约
+- 关键技术决策
+- 依赖关系（开发顺序建议）
+
+**2. `.autospec/specs/{feature}/design/{subsystem}.md`** — 各子系统设计
+为 config.json 中的每个 subsystem 产出独立文档，包含：
+- 模块设计
+- 数据模型
+- API设计（本系统负责的部分）
+- 技术细节
+- 任务拆分
+
+**3. `.autospec/specs/{feature}/contracts/api.yaml`** — API契约（如有跨系统接口）
+
+### 效果指标设计（AI/模型类功能）
+
+当项目包含 AI/模型 相关功能时，设计阶段需要额外产出：
+
+**效果指标定义**：
+- 核心效果指标（如准确率、召回率、F1、BLEU等）
+- 业务效果指标（如转化率、用户满意度、任务完成率）
+- 效果基线（最低可接受效果）
+- 效果目标（期望达到的效果）
+
+**评测方案设计**：
+- 评测数据来源（公开数据集/业务数据/人工构造）
+- 评测方法选择（自动评测/人工评测/A/B测试）
+- 评测频率（离线评测/在线评测）
+
+写入 `design.md` 的"效果指标"章节，或独立产出 `design/evaluation.md`。
+
+### 产出物模板（增强版）
+
+#### 文档头部
+
+```markdown
+---
+document_id: DES-{feature}-001
+version: v1.0
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+status: Draft/Review/Approved
+upstream: [REQ-{feature}-001]
+downstream: []
+---
+
+## 版本历史
+
+| 版本 | 日期 | 修改人 | 修改说明 |
+|-----|------|--------|---------|
+| v1.0 | YYYY-MM-DD | | 初始版本 |
+```
+
+#### 第一章：技术决策增量
+
+记录相比需求阶段新增的技术决策：
+
+```markdown
+| 决策ID | 决策名称 | 决策内容 | 决策理由 | 放弃方案 | 影响范围 |
+|--------|---------|---------|---------|---------|---------|
+| TD-01 | （决策名） | （选了什么） | （为什么） | （放弃什么） | （影响哪些模块） |
+```
+
+#### 第二章：架构设计
+
+- **系统架构图**：整体架构（使用 Mermaid）
+- **模块划分**：各模块职责
+- **数据流向**：数据如何在模块间流转
+- **与业务流程对应**：标注每个业务流程如何被技术支撑
+
+#### 第三章：接口设计
+
+- **API列表**：接口清单
+- **API详情**：每个接口的输入/输出/错误码
+- **契约定义**：OpenAPI/YAML 格式（放在 contracts/ 目录）
+
+#### 第四章：详细设计
+
+- **数据模型**：实体关系图
+- **核心算法**：关键算法伪代码
+- **状态机**：如有状态流转
+
+#### 第五章：迁移方案
+
+- **数据迁移**：如何迁移现有数据
+- **兼容性处理**：如何处理向后兼容
+- **灰度策略**：如何逐步切换
+
+```markdown
+| 迁移项 | 当前状态 | 目标状态 | 迁移方式 | 回滚方案 |
+|--------|---------|---------|---------|---------|
+| （数据/配置/代码） | | | | |
+```
+
+#### 第六章：测试计划
+
+- **测试策略**：单元/集成/E2E测试覆盖
+- **测试场景**：关键测试场景
+- **效果评测**：AI/模型功能的评测方案（如适用）
+
+#### 第七章：监控告警
+
+```markdown
+### 技术指标
+
+| 指标名称 | 计算方式 | 告警阈值 | 监控位置 |
+|---------|---------|---------|---------|
+| 响应时间 | P99 | > 1000ms | API网关 |
+| 错误率 | 错误数/总请求数 | > 1% | 应用监控 |
+
+### 业务指标
+
+| 指标名称 | 计算方式 | 告警阈值 | 监控位置 |
+|---------|---------|---------|---------|
+| 成功率 | 成功数/总数 | < 99% | 业务监控 |
+
+### 告警规则
+
+| 告警名称 | 触发条件 | 告警级别 | 处理方式 |
+|---------|---------|---------|---------|
+| （告警名） | （条件） | P0/P1/P2 | （处理步骤） |
+```
+
+#### 附录
+
+- **假设清单**：继承需求阶段 + 本阶段新增
+- **风险登记**：识别的技术风险及应对
+- **工作量预估**：任务拆分和预估工时
+
+### 自查清单（嵌入式）
+
+产出完成后，执行自查：
+
+- [ ] 每个技术决策有明确理由
+- [ ] 数据模型覆盖所有业务实体
+- [ ] API设计覆盖所有功能需求
+- [ ] 业务规则已引用 BR-ID
+- [ ] 风险已评估并有应对方案
+- [ ] 监控指标覆盖关键业务
+- [ ] 灰度和回滚方案已设计
+- [ ] 任务拆分符合 ATOMIC 原则
+
+## 执行步骤
+
+1. 分析需求文档，识别技术挑战和关键决策点
+   - 预期产出：技术挑战清单
+   - 失败处理：挑战不明确则回溯需求文档
+2. **校验需求阶段关键假设**，更新假设状态
+3. **检查是否为多系统项目**：读取 `.autospec/config.json` 的 `subsystems` 字段
+4. **检查是否需要效果指标设计**：检查是否有 ai 类型子系统或需求文档包含效果指标
+5. **识别业务主体**（点线面体法）
+   a. 识别核心业务主体（ID由谁颁发、生命周期由谁管理）
+   b. 梳理业务主体的生命周期（核心/非核心生命周期区分）
+   c. 梳理领域内概念和知识域
+6. 设计整体架构（由外到内）
+   a. 确定分层结构（三层复用：域服务→商业能力→解决方案）
+   b. 划分模块/组件边界和职责
+   c. 定义模块间通信方式
+   d. **检验抽象力度**：抽象的平台是否能处理领域固有复杂度
+   e. **多系统模式**：额外产出系统交互图和依赖顺序
+7. 设计数据模型
+   a. 识别核心实体和关系，确定聚合根
+   b. 选择存储方案（关系型/文档型/缓存等）
+   c. 设计索引策略
+   d. 区分领域模型、应用模型、数据模型的边界
+   e. **多系统模式**：明确各子系统负责的数据边界
+8. 设计接口/API
+   a. 定义每个接口的输入、输出、错误处理
+   b. 出入参设计为对象（便于扩展，保持向后兼容）
+   c. 错误码明确区分可重试/不可重试、业务异常/系统异常
+   d. **多系统模式**：跨系统接口需在 contracts/ 中定义契约
+9. 技术选型
+   a. 对关键技术点列出至少2个备选
+   b. 从性能、维护性、团队熟悉度等维度对比
+   c. 做出选择并记录理由（含放弃方案的理由）
+10. 非功能架构设计
+    a. 监控设计：技术指标 + 业务指标
+    b. 容量评估：峰值TPS、机器数量
+    c. 三板斧：灰度发布、应急回滚、降级开关
+    d. 资损防控：识别资损点、制定保障措施
+11. **效果指标设计（如需要）**
+    a. 定义核心效果指标和业务效果指标
+    b. 设定效果基线和目标
+    c. 设计评测方案
+12. 评估风险，制定应对策略
+13. 制定路线图：按最小价值单元拆分，先交付样板间再横向扩展
+    - **多系统模式**：明确各子系统开发顺序（通常：后端→前端→移动端；有ml时：ml可能需要先验证效果）
+14. **任务拆分与依赖分析**
+    a. 按 ATOMIC 原则拆分任务（每个任务 2-4 小时）
+    b. 标注依赖类型：`→data`（数据依赖）、`→logic`（逻辑依赖）、`→res`（资源依赖）
+    c. 标记可并行任务：`[P]`
+    d. 输出依赖图（文本格式）
+15. **整理关键假设清单**（继承 + 新增），标注已确认/待确认
+16. **整理证据清单**
+
+## 任务拆分输出格式
+
+任务拆分是一个统一的能力，三视角融合：系统边界 + 任务规模 + 阶段依赖。
+
+### 拆分触发条件
+
+| 视角 | 触发条件 | 拆解策略 |
+|------|----------|----------|
+| **系统边界** | 涉及多子系统 | 按系统拆 Phase，明确系统间依赖 |
+| **任务规模** | 预估 > 16 小时 | 在 Phase 内按功能拆 Task（每任务 2-4h） |
+| **阶段依赖** | 有明确阶段约束 | 按 AI验证→后端→前端 顺序排列 |
+
+### 拆分层级
+
+```
+Phase（阶段/子系统，预估 4-16 小时）
+  └── Task（具体任务，2-4 小时）
+       └── Sub-task（如需要，最大深度 2 层）
+```
+
+### 依赖解耦与并行策略
+
+**核心原则**：通过定义标准产出物（接口契约、数据Schema），将"依赖"转化为"面向标准并行开发"。
+
+**可解耦依赖**：
+| 场景 | 标准产出物 | 解耦方式 |
+|------|------------|----------|
+| 后端↔前端 | API契约（OpenAPI） | 契约定义后：后端实现 ∥ 前端Mock开发 |
+| 后端↔移动端 | API契约 | 契约定义后：后端实现 ∥ 移动端Mock开发 |
+| 数据↔后端 | 数据模型/表结构 | 结构定义后：数据管道 ∥ 后端接口 |
+| AI↔后端 | 模型接口定义 | 接口定义后：模型训练 ∥ 后端服务 |
+| 数据↔数据 | 数据交换Schema | Schema定义后：上游 ∥ 下游 |
+
+**解耦标记**：
+- `→contract`：通过契约解耦，契约定义后可并行
+- `→mock`：使用Mock数据并行开发，上游完成后联调
+
+**不可解耦依赖**（必须串行）：
+- 数据库迁移（资源依赖）
+- 配置变更影响多方（资源依赖）
+- 核心业务流程顺序（逻辑依赖：创建订单→支付→发货）
+- AI模型效果验证（逻辑依赖：效果不达标则后续无意义）
+
+### 统一输出格式
+
+在 `design.md` 或 `design/overview.md` 的"任务拆分"章节输出：
+
+```markdown
+## 任务拆分
+
+### 拆分依据
+
+- 系统边界：涉及后端、前端、AI、数据四个子系统
+- 任务规模：预估 40 人时，需拆分
+- 阶段依赖：AI 效果验证 → 后端 API → 前端/移动端
+
+### 依赖图（含解耦标记）
+
+\`\`\`
+[P1: AI模型验证] →data(不可解耦)→ [P2: 后端API]
+                                        ├─→contract→ [P3: 前端页面]
+                                        └─→contract→ [P4: 移动端适配]
+[P2: 后端API]
+    ├─→contract→ [P5: 数据管道]（数据Schema定义后并行）
+    └─→ [T2.1: 数据模型] →logic→ [T2.2: 核心接口] →logic→ [T2.3: 单元测试]
+\`\`\`
+
+### 解耦并行分析
+
+| 依赖关系 | 可解耦 | 解耦方式 | 标准产出物 |
+|----------|--------|----------|------------|
+| P2 →data→ P3 | ✅ | API契约定义后并行 | OpenAPI Schema |
+| P2 →data→ P4 | ✅ | API契约定义后并行 | OpenAPI Schema |
+| P2 →data→ P5 | ✅ | 数据Schema定义后并行 | 表结构定义 |
+| P1 →data→ P2 | ❌ | 效果不达标则后续无意义 | - |
+
+### 任务清单
+
+| ID | Phase | 任务 | 依赖 | 并行 | 预估 | 验证标准 |
+|----|-------|------|------|------|------|----------|
+| P1 | AI | 模型效果验证 | - | - | 8h | 准确率>85% |
+| P2 | Backend | 后端API开发 | P1→data | - | 12h | 全部接口测试通过 |
+| T2.0 | Backend | API契约定义 | - | - | 1h | OpenAPI文档 |
+| T2.1 | Backend | 数据模型设计 | - | - | 2h | ER图评审通过 |
+| T2.2 | Backend | 核心接口实现 | T2.1→logic | - | 6h | 接口测试通过 |
+| T2.3 | Backend | 单元测试 | T2.2→logic | - | 2h | 覆盖率>80% |
+| P3 | Frontend | 前端页面开发 | T2.0→contract | 与P4,P5并行 | 6h | E2E测试通过 |
+| P4 | Mobile | 移动端适配 | T2.0→contract | 与P3,P5并行 | 4h | 真机测试通过 |
+| P5 | Data | 数据管道开发 | T2.1→contract | 与P3,P4并行 | 4h | 数据校验通过 |
+
+### 执行批次
+
+| 批次 | 任务 | 说明 |
+|------|------|------|
+| 1 | P1 | 阻塞后续，必须先完成 |
+| 2 | T2.0, T2.1 | 契约+数据模型定义（解耦关键） |
+| 3 | T2.2, P3, P4, P5 | 契约定义后并行执行 |
+| 4 | T2.3 | T2.2 完成后执行 |
+| 5 | 联调验证 | P3/P4/P5 与 P2 联调 |
+```
+
+### 解耦并行实施要点
+
+1. **契约先行**：涉及多系统协作时，优先产出接口契约/数据Schema
+2. **Mock开发**：下游基于契约Mock数据开发，不阻塞上游实现
+3. **联调验证**：上游完成后，下游切换真实接口联调
+4. **契约变更管理**：契约变更需通知所有相关方，评估影响范围
+
+### 单系统简化格式
+
+单系统且任务简单时，可简化输出：
+
+```markdown
+## 任务拆分
+
+### 依赖图
+
+\`\`\`
+[T1: 数据模型] →data→ [T2: API实现] →data→ [T3: 集成测试]
+\`\`\`
+
+### 任务清单
+
+| ID | 任务 | 依赖 | 预估 | 验证标准 |
+|----|------|------|------|----------|
+| T1 | 数据模型设计 | - | 2h | ER图评审通过 |
+| T2 | API实现 | T1→data | 3h | 接口测试通过 |
+| T3 | 集成测试 | T2→data | 1h | 全部用例通过 |
+```
+
+### ATOMIC 检查清单
+
+每个任务必须通过以下检查：
+
+| 检查项 | 说明 | 通过标准 |
+|--------|------|----------|
+| A - Autonomous | 可独立执行 | 不依赖其他任务的中间状态 |
+| T - Testable | 有验证标准 | 明确的测试/验证方法 |
+| O - Observable | 结果可观测 | 有输出物或日志 |
+| M - Modest | 粒度适中 | 2-4 小时可完成 |
+| I - Informed | 上下文完整 | 包含必要背景信息 |
+| C - Constrained | 边界明确 | 做什么/不做什么清晰 |
+
+## 反模式清单（DP7）
+1. **过度设计**：为不存在的需求预留扩展。检测：每个设计决策回溯到具体需求，无法回溯的删除
+2. **技术偏好驱动**：选自己熟悉的而非最合适的。检测：至少列出2个备选方案并对比
+3. **忽略非功能需求**：只设计功能不考虑性能/安全。检测：用checklist强制覆盖
+4. **假设漂移**：设计偏离需求阶段的关键假设。检测：逐项校验继承假设
+5. **PPT架构**：画了漂亮的图但不可落地。检测：每个组件必须有具体技术实现方案
+6. **重复造轮子**：不搜索项目已有组件就新建。检测：选型前搜索现有技术栈
+7. **忽略效果指标**：AI/模型类功能不设计效果指标。检测：ml类型子系统必须有效果指标章节
+
+## 适用场景与边界
+- 适用：新功能开发、系统重构、技术方案选型
+- 不适用：方案已有只需评审（用design-reviewer）；纯bug修复（通常不需要完整设计）
+- 边界：产出技术方案，但不写代码
+- 前置：requirement-reviewer通过
+- 后续：design-reviewer审查 → 通过后进入code-implementer
+
+## 示例
+（待从实践中积累第一个完整示例）

package/knowledge/guides/stages/design-reviewer.md

@@ -0,0 +1,83 @@
+---
+name: design-reviewer
+description: 当技术方案文档完成、需要评审其合理性和完整性以决定是否可进入编码阶段时触发
+type: review
+---
+
+## 定位
+设计阶段的"审"类skill。独立审查技术方案质量，作为进入编码阶段的Layer 2质量关卡。
+
+> **做审分离（DP2）**：必须由独立于design-planner的AI实例执行。
+
+## 输入
+- 必须输入：技术方案文档（design-planner的输出）、结构化需求文档（对照覆盖度）
+- 可选输入：methodology/checklists/design.md（检查标准）、需求阶段关键假设清单
+
+## 评判标准
+必须满足：
+- [ ] 方案覆盖需求文档中的所有功能点
+- [ ] 关键技术决策有明确理由（不是拍脑袋）
+- [ ] 接口/API定义清晰，模块间可独立开发
+- [ ] 数据模型设计合理
+- [ ] 复杂度与需求匹配，不过度设计
+- [ ] 安全性已考虑
+- [ ] 关键假设清单完整，需求阶段假设已校验
+- [ ] 待确认假设不超过3个
+
+建议满足：
+- [ ] 可扩展性已考虑
+- [ ] 性能预估和瓶颈分析
+- [ ] 技术风险已识别并有降级方案
+- [ ] 对比了备选方案
+
+## 评审步骤
+1. 对照需求文档，逐条检查方案是否覆盖（无遗漏）
+   - 证据获取：建立需求→设计的映射表
+2. 审查架构设计的合理性（分层清晰、职责单一、耦合度低）
+   - 证据获取：指出具体的耦合点或职责混淆
+3. 审查接口设计（输入输出明确、错误处理完善、命名规范）
+4. 审查数据模型（实体关系合理、索引策略得当、存储选型匹配）
+5. 审查技术选型的理由（是否充分、是否有更优选择）
+6. 检查是否过度设计（每个设计决策能否回溯到具体需求）
+   - 证据获取：无法回溯到需求的设计元素列表
+7. 检查安全性考虑（认证、授权、数据保护）
+8. **校验关键假设跨阶段一致性**（需求→设计是否漂移）
+9. 逐项输出判定结果，**每项附具体证据**
+
+## 输出格式
+
+```
+## 审查结论：通过 / 不通过
+
+### 逐项判定
+| 检查项 | 结论 | 证据 | 备注 |
+|--------|------|------|------|
+| 需求覆盖度 | ✅/❌ | {需求→设计映射} | {遗漏项} |
+| 架构合理性 | ✅/❌ | {具体分析} | {修复建议} |
+| ... | ... | ... | ... |
+
+### 必须修复（blocking）
+- ...
+
+### 建议改进（non-blocking）
+- ...
+
+### 关键假设验证
+- 需求假设X：在设计中已体现/存在漂移（证据：...）
+- 设计新假设Y：合理/存疑（证据：...）
+```
+
+## 反模式清单（DP7）
+1. **橡皮图章**：无证据通过。检测：每条"通过"必须附具体证据
+2. **吹毛求疵**：纠结技术选型的微小差异。检测：技术选型偏好不可blocking
+3. **脱离上下文**：不参照需求审查方案。检测：审查步骤第一步必须对照需求
+4. **假设漂移忽视**：不校验跨阶段假设一致性。检测：输出必须包含假设验证section
+5. **反向过度设计**：审查中建议增加方案复杂度。检测：建议改进不可增加已排除的需求
+
+## 适用场景与边界
+- 适用：技术方案完成后，进入编码阶段前
+- 不适用：方案还在草稿阶段（先完成方案再评审）
+- 对应做类skill：design-planner
+
+## 示例
+（待从实践中积累第一个完整示例）

package/knowledge/guides/stages/integration-test-runner.md

@@ -0,0 +1,105 @@
+---
+name: integration-test-runner
+description: 当需要检测并执行项目已有集成测试、验证模块间协作时触发
+type: execute
+---
+
+## 定位
+
+集成测试执行阶段的"执行"类skill。负责智能检测项目中的集成测试并执行。
+
+> **使用场景**：单元测试通过后，需要验证模块间协作是否正常。
+
+## 输入
+
+- 必须输入：项目代码、单元测试已通过
+- 可选输入：项目构建配置
+
+## 执行步骤
+
+### Step 1: 智能检测测试框架
+
+1. 检测项目测试框架：
+   - 读取 `package.json`, `pom.xml`, `build.gradle`, `pyproject.toml` 等
+   - 识别测试框架：pytest, JUnit, Jest, Vitest 等
+
+2. 识别测试文件（不限于特定目录）：
+   - 根据框架惯例：test_*.py, *_test.py, *.test.js, *Test.java
+   - 根据测试内容：class Test*, def test_*, it('*'), @Test
+   - 扫描项目根目录和子目录
+
+### Step 2: 区分单元测试 vs 集成测试
+
+1. **单元测试特征**：
+   - 只 import 项目内部模块
+   - 无外部依赖（数据库、API、文件系统）
+   - 使用 mock 替代外部依赖
+
+2. **集成测试特征**：
+   - import 外部模块（数据库、缓存、消息队列）
+   - 涉及真实环境配置
+   - 无 mock 或少量 mock
+   - 测试文件名包含 integration, e2e, endtoend
+
+3. **分类输出**：
+   - 列出识别出的集成测试文件
+   - 说明分类依据
+
+### Step 3: 执行集成测试
+
+1. 准备测试环境（如需要）
+2. 执行集成测试
+3. 收集测试输出和结果
+
+### Step 4: 分析测试结果
+
+1. 解析测试输出
+2. 统计：通过/失败/跳过/错误
+3. 记录失败的测试用例和错误信息
+
+## 输出格式
+
+```
+## 集成测试执行结果
+
+### 测试框架检测
+- 检测到的框架：{framework}
+- 测试命令：{command}
+
+### 测试文件识别
+- 总测试文件数：{total}
+- 单元测试：{unit_count}
+- 集成测试：{integration_count}
+
+### 集成测试列表
+| 文件路径 | 测试用例数 | 分类依据 |
+|----------|------------|----------|
+| ... | ... | ... |
+
+### 执行结果
+- 通过：{passed}
+- 失败：{failed}
+- 跳过：{skipped}
+- 错误：{errors}
+
+### 失败详情（如有）
+| 测试文件 | 测试用例 | 错误信息 |
+|----------|----------|----------|
+| ... | ... | ... |
+
+### 结论
+- 集成测试通过：✅ 是/❌ 否
+- 需要修复：{需要修复的测试数}
+```
+
+## 判定标准
+
+- **通过**：所有集成测试通过
+- **不通过**：有集成测试失败，需要修复
+- **无集成测试**：项目中未发现集成测试，跳过
+
+## 适用场景
+
+- 适用：单元测试通过后，需要验证模块间协作
+- 不适用：需要生成新测试（使用 test-generator）
+- 对应做类skill：test-generator