@shirayner/ace 0.1.0-snapshot.3 → 0.1.0

package/templates/openspec/config.yaml

@@ -0,0 +1,150 @@
+schema: spec-driven
+
+# =============================================================================
+# mspec 增强配置 v5 — 寄生模式
+# =============================================================================
+# mspec 通过 context 和 rules 注入 OpenSpec 工作流，不改变 OpenSpec schema。
+# 核心目标：捕获需求/设计中的不确定性，避免基于假设实施带来的返工。
+# =============================================================================
+
+version: "5.0.3"
+language: zh
+
+context: |
+  ## 工作模式
+
+  mspec 采用"寄生模式"增强 OpenSpec 核心流程：在关键阶段注入前置/后置检查，
+  不改变 OpenSpec schema。跳过澄清 = AI 基于假设实施 = 大概率返工。
+
+  ## 门禁条件（强制，不满足时禁止继续）
+
+  | 阶段 | 前置条件 | 触发动作 |
+  |------|----------|----------|
+  | proposal 前 | spec/requirement-issues.md 状态为 `clarified` | 执行需求澄清流程 |
+  | tasks 前 | spec/design-issues.md 状态为 `clarified` 或 `resolved` | 执行设计澄清流程 |
+
+  澄清流程文档（含详细执行步骤）：
+  - 需求澄清：openspec/templates/procedures/requirement-clarification-flow.md
+  - 设计澄清：openspec/templates/procedures/design-clarification-flow.md
+  - 交互式提问通用协议：openspec/templates/procedures/interactive-clarification-protocol.md
+
+  ## 澄清状态机
+
+  需求澄清：discovering → clarifying → clarified → superseded
+  设计澄清：analyzing → clarifying → clarified → resolved
+
+  ## 问题严重程度
+
+  - 🔴 High：阻塞性，必须澄清后才能继续
+  - 🟡 Medium：重要，建议澄清
+  - 🟢 Low：建议性，可后续补充
+
+  ## 知识库索引
+
+  - 需求问题分类学（6维度）：openspec/templates/taxonomy/requirement-issue-taxonomy.md
+  - 设计问题分类学（7维度）：openspec/templates/taxonomy/design-issue-taxonomy.md
+  - 问题清单模板：openspec/templates/issues/（requirement-issues.md / design-issues.md）
+
+  ## 进化体系（v5）
+
+  mspec 在 archive 时自动积累项目知识，**使用越久，流程越精准**：
+  - Layer A（每次立即）：ADR 技术决策 / 词汇表 / 风险图谱
+  - Layer B（积累 3+ 复盘后触发）：问题分类学优化 / 任务模板 / 用户偏好
+  - Layer C（长期）：规格演化历史 / 效率指标
+
+  完整说明及 archive 操作步骤：openspec/templates/procedures/evolution-system.md
+
+  ## AI 知识库消费速查
+
+  每个阶段开始前读取对应知识库，避免重复已有决策：
+  - explore / propose：ADR + Glossary + Task Patterns
+  - specs：Glossary + Spec CHANGELOG
+  - design：ADR + Risk Map + 问题分类学
+  - tasks：Task Patterns + Risk Map
+  - apply：ADR + Risk Map
+  - archive：全部 → 更新全部 → 触发进化分析
+
+# =============================================================================
+# 阶段规则
+# =============================================================================
+
+rules:
+  # ===========================================================================
+  # proposal — 需求澄清门禁
+  # ===========================================================================
+  proposal:
+    - |
+      BEFORE creating proposal：
+      1. 检查 spec/requirement-issues.md 是否存在且状态为 clarified
+      2. 不满足 → 执行 openspec/templates/procedures/requirement-clarification-flow.md 中的完整流程
+      3. 通过后创建 proposal，在 Why / Capabilities / Impact 中引用澄清决策
+    - "🚫 禁止跳过：requirement-issues.md 不存在或状态非 clarified 时，禁止创建 proposal"
+
+  # ===========================================================================
+  # specs — 与澄清结果保持一致
+  # ===========================================================================
+  specs:
+    - |
+      创建 specs 时：
+      - 参考 requirement-issues.md 中的功能点定义，确保规格与澄清结果一致
+      - 需求有变更（MODIFIED/REMOVED/RENAMED）时，在问题清单中记录变更原因
+
+  # ===========================================================================
+  # design — 技术决策四要素 + 设计澄清门禁
+  # ===========================================================================
+  design:
+    - |
+      创建 design.md 时，每个技术决策必须包含：
+      - 选择了什么方案
+      - 为什么选择（决策理由）
+      - 考虑过哪些备选方案
+      - 为什么放弃备选方案
+      注意体现 requirement-issues.md 中澄清的约束条件。
+    - |
+      AFTER creating design.md：
+      1. 检查 spec/design-issues.md 是否存在且状态为 clarified 或 resolved
+      2. 不满足 → 执行 openspec/templates/procedures/design-clarification-flow.md 中的完整流程
+      3. 根据澄清结果更新 design.md，通过后创建 tasks
+    - "🚫 禁止跳过：design-issues.md 不存在或状态不在 {clarified, resolved} 时，禁止创建 tasks"
+
+  # ===========================================================================
+  # tasks — 基于最终方案创建任务
+  # ===========================================================================
+  tasks:
+    - |
+      创建 tasks 时：
+      - 基于最终确定的技术方案（已经过设计澄清）
+      - 确保任务覆盖 design-issues.md 中所有 🔴 High 决策
+      - 设计澄清导致 design.md 重大变更时，相应调整任务列表
+      - 任务描述中引用相关设计决策（方便追溯）
+
+  # ===========================================================================
+  # apply — 严格遵循澄清决策
+  # ===========================================================================
+  apply:
+    - |
+      实施前：读取 spec/requirement-issues.md 和 spec/design-issues.md，了解所有澄清决策。
+    - |
+      实施中：严格遵循澄清决策。发现新问题时：
+      暂停 → 评估问题类型（需求/设计）→ 更新对应问题清单 → 可选启动澄清补充 → 继续
+      完成每个任务后立即用 "- [x]" 标记完成。
+    - |
+      轻量观察（选做，记录到 spec/retrospective-notes.md，供归档时汇入复盘报告）：
+      - 澄清未覆盖但实际重要的问题 → 【需求层面的意外】
+      - 设计不明确需临时决策的问题 → 【设计层面的意外】
+      - 澄清有效避免返工的案例 → 【好的实践】
+      - 高风险代码区域或意外技术问题 → 【风险事件】
+
+  # ===========================================================================
+  # archive — 复盘 + 知识库更新 + 进化分析
+  # ===========================================================================
+  archive:
+    - |
+      BEFORE archiving — 生成复盘报告：
+      1. 读取 spec/requirement-issues.md、design-issues.md、retrospective-notes.md（如存在）、design.md、proposal.md
+      2. 在 openspec/retrospectives/{YYYY-MM-DD}-{change-name}.md 创建复盘报告
+         格式参见 openspec/templates/retrospective-template.md
+      3. 向用户展示复盘摘要（5-8 行），然后继续归档
+    - |
+      AFTER archiving — 执行进化体系更新（Layer A 立即 + Layer B 条件触发）：
+      完整操作步骤参见 openspec/templates/procedures/evolution-system.md

package/templates/openspec/evolution/adr.md

@@ -0,0 +1,23 @@
+# 技术决策账本（Architecture Decision Records）
+
+> **用途**: 记录项目中已做出的架构和技术决策，避免重复讨论已决定的事项。
+> **更新时机**: 每次 archive 时，自动从复盘报告提取新决策追加。
+>
+> **如何消费**:
+> - design 阶段：先查询此文件，已有决策不重复讨论
+> - explore 阶段：比较技术方案时直接引用
+> - propose 阶段：评估 Impact 时与已有决策对齐
+
+---
+
+<!-- 格式：
+## {决策标题} | 来源: {change-name} | 日期: {YYYY-MM-DD}
+
+**选择**: 选了什么方案
+**理由**: 为什么选择这个方案
+**备选**: 考虑过哪些其他方案
+**放弃原因**: 为什么放弃备选方案
+**状态**: active / superseded / deprecated
+-->
+
+*暂无决策记录。第一次 archive 后将自动填充。*

package/templates/openspec/evolution/glossary.md

@@ -0,0 +1,24 @@
+# 领域词汇表（Domain Glossary）
+
+> **用途**: 项目中稳定使用的业务术语、技术概念的标准定义，以及 Capability 命名规范。
+> **更新时机**: 每次 archive 时，自动从 proposal 的 Capabilities 章节提取新术语追加。
+>
+> **如何消费**:
+> - propose 阶段：Capabilities 命名时复用标准术语保持一致
+> - specs 阶段：Scenario 中使用标准术语，减少歧义
+> - 新成员加入时：快速建立项目语言认知
+
+---
+
+<!-- 格式：
+## {术语}
+
+**定义**: 一句话定义
+**首次出现**: {change-name}（{date}）
+**相关术语**: 与哪些其他术语有关联
+**备注**: 如有歧义或特殊用法说明
+
+---
+-->
+
+*暂无词汇记录。第一次 archive 后将自动填充。*

package/templates/openspec/evolution/risk-map.md

@@ -0,0 +1,43 @@
+# 风险图谱（Risk Map）
+
+> **用途**: 记录项目中已知的高风险代码区域、高频 bug 模式，以及历史上实际发生的实施问题。
+> **更新时机**: 每次 archive 时，从复盘报告"六、风险事件"章节提取新发现追加。
+>
+> **如何消费**:
+> - design 阶段：优先检查已知风险区域
+> - tasks 阶段：高风险区任务自动细化粒度、增加验证步骤
+> - apply 阶段：进入高风险区时主动预警
+
+---
+
+## 代码热点
+
+> 历史上频繁变更或容易出问题的代码区域。
+
+<!-- 格式：
+### {模块/文件路径}
+
+**风险类型**: 频繁变更 / 并发问题 / 边界复杂 / 依赖脆弱 / 其他
+**历史问题**: 具体描述
+**首次记录**: {change-name}（{date}）
+**注意事项**: 处理时需要特别关注的点
+-->
+
+*暂无记录。第一次 archive 后将自动填充。*
+
+---
+
+## 问题模式
+
+> 在多个 change 中反复出现的问题类型。
+
+<!-- 格式：
+### {问题模式名称}
+
+**描述**: 什么情况下会触发
+**影响范围**: 影响哪些功能/模块
+**出现次数**: N 次（最近一次: {change-name}）
+**预防措施**: 如何在下次避免
+-->
+
+*暂无记录。第一次 archive 后将自动填充。*

package/templates/openspec/issues/design-issues.md

@@ -0,0 +1,218 @@
+# 设计问题清单
+
+## 变更信息
+- **变更名称**: [change-name]
+- **当前阶段**: `analyzing` | `clarifying` | `clarified` | `resolved`
+- **最后更新**: [YYYY-MM-DD]
+- **下次检查**: [YYYY-MM-DD]
+
+---
+
+## 设计维度问题矩阵
+
+<!--
+说明：
+1. 按设计问题分类学维度组织
+2. 每个设计维度下列出具体问题
+3. 问题 ID 格式：D[维度序号]-[序号] 例如 D1-001
+-->
+
+---
+
+### 维度 1: 架构决策
+
+#### 问题列表
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D1-001 | [如：架构模式选择未定] | 🔴 High / 🟡 Medium / 🟢 Low | `open` / `clarifying` / `clarified` | [决策结论] |
+| D1-002 | [如：服务边界划分不清晰] | | | |
+
+**D1-001 详细说明**:
+- **问题类型**: 架构方案不确定
+- **具体表现**: [详细描述]
+- **影响范围**: [对系统的影响]
+- **可选方案**:
+  - A) [描述 + 优缺点]
+  - B) [描述 + 优缺点]
+  - C) [描述 + 优缺点]
+  - D) 自定义...
+- **决策结果**: [交互式澄清后的决策]
+- **决策理由**: [为什么选这个方案]
+- **澄清时间**: [YYYY-MM-DD]
+- **澄清人**: [@name]
+
+---
+
+### 维度 2: 技术选型
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D2-010 | [如：消息队列选型未定] | | | |
+| D2-011 | [如：缓存方案未确定] | | | |
+
+**D2-010 详细说明**:
+- **问题类型**: 核心框架/库未确定
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 3: 接口设计
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D3-020 | [如：API 版本管理策略未定] | | | |
+
+**D3-020 详细说明**:
+- **问题类型**: API 契约未定 / 数据流不清晰 / 异步处理机制
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 4: 数据与状态
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D4-030 | [如：订单状态机未定义] | | | |
+
+**D4-030 详细说明**:
+- **问题类型**: 数据模型未定 / 状态机未定义 / 数据迁移方案
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 5: 安全与合规
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D5-040 | [如：权限模型未设计] | | | |
+
+**D5-040 详细说明**:
+- **问题类型**: 认证授权未设计 / 数据安全 / 审计与日志
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 6: 性能与可靠性
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D6-050 | [如：缓存一致性策略未定] | | | |
+
+**D6-050 详细说明**:
+- **问题类型**: 性能瓶颈未识别 / 缓存策略未定 / 降级与熔断
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 7: 部署与运维
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D7-060 | [如：灰度发布策略未定] | | | |
+
+**D7-060 详细说明**:
+- **问题类型**: 部署方案未定 / 监控告警 / 配置管理
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+## 问题统计
+
+| 设计维度 | 总计 | 已澄清 | 待澄清 | 已解决 |
+|----------|------|--------|--------|--------|
+| 架构决策 | 0 | 0 | 0 | 0 |
+| 技术选型 | 0 | 0 | 0 | 0 |
+| 接口设计 | 0 | 0 | 0 | 0 |
+| 数据与状态 | 0 | 0 | 0 | 0 |
+| 安全与合规 | 0 | 0 | 0 | 0 |
+| 性能与可靠性 | 0 | 0 | 0 | 0 |
+| 部署与运维 | 0 | 0 | 0 | 0 |
+| **总计** | 0 | 0 | 0 | 0 |
+
+---
+
+## 澄清记录
+
+### 交互式澄清会话 1: [YYYY-MM-DD]
+- **参与者**: [@name1, @name2, ...]
+- **澄清模式**: 命令行交互式
+- **澄清的问题**: [问题 ID 列表]
+- **设计决策**:
+  1. [决策 1]
+  2. [决策 2]
+- **设计变更**: [design.md 的更新内容]
+- **任务调整**: [tasks.md 的调整]
+
+### 交互式澄清会话 2: [YYYY-MM-DD]
+
+[同上结构...]
+
+---
+
+## 状态流转说明
+
+```
+analyzing:      AI 正在分析设计方案，发现问题
+                → 发现问题后自动转为 clarifying
+
+clarifying:     问题已列出，等待交互式澄清
+                → 使用命令行界面一问一答澄清
+                → 每题回答后立即同步到本文档
+                → 支持 'q' 退出，下次自动恢复
+                → 支持 's' 跳过 Low 优先级问题
+
+clarified:      所有 High 和 Medium 问题已澄清
+                → 可以创建/更新 tasks
+                → 根据澄清更新 design.md
+                → 状态可转为 resolved
+
+resolved:       设计已根据澄清更新，问题已解决
+                → 可以创建/更新 tasks
+```
+
+**当前状态**: `[current-status]`
+
+**状态变更历史**:
+- [YYYY-MM-DD]: `analyzing` → `clarifying` (AI 完成问题分析)
+- [YYYY-MM-DD]: `clarifying` → `clarified` (完成澄清会话 1)
+- [YYYY-MM-DD]: `clarified` → `resolved` (design.md 已更新)
+
+---
+
+## 关联文档
+
+- **技术方案**: `design.md`
+- **实施任务**: `tasks.md`
+- **需求问题清单**: `spec/requirement-issues.md`
+- **分类学参考**: `openspec/templates/design-issue-taxonomy.md`
+
+---
+
+## 备注
+
+<!-- 任何补充说明 -->

package/templates/openspec/issues/requirement-issues.md

@@ -0,0 +1,214 @@
+# 需求问题清单
+
+## 变更信息
+- **变更名称**: [change-name]
+- **当前阶段**: `discovering` | `clarifying` | `clarified` | `superseded`
+- **最后更新**: [YYYY-MM-DD]
+- **下次检查**: [YYYY-MM-DD]
+
+---
+
+## 功能点问题矩阵
+
+<!--
+说明：
+1. 按 OpenSpec Capabilities 结构组织
+2. 每个功能点下按问题分类维度列出具体问题
+3. 问题 ID 格式：R[功能点序号]-[分类序号][序号] 例如 R1-001
+-->
+
+---
+
+### 功能点 1: [功能点名称]
+
+#### 基本信息
+- **功能点 ID**: [kebab-case-id]
+- **对应 Spec**: `specs/[功能点ID]/spec.md`
+- **优先级**: P0 / P1 / P2
+- **负责人**: [@name]
+
+#### 问题列表
+
+##### 1. 功能完整性问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-001 | [一句话描述问题] | 🔴 High / 🟡 Medium / 🟢 Low | `open` / `clarifying` / `clarified` | [澄清后的结论] |
+| R1-002 | | | | |
+
+**R1-001 详细说明**:
+- **问题类型**: 功能边界模糊 / 功能流程缺失 / 功能依赖未说明
+- **具体表现**: [详细描述问题现象，引用需求原文]
+- **影响范围**: [如果不澄清会导致什么后果]
+- **建议选项**:
+  - A) [选项A描述]
+  - B) [选项B描述]
+  - C) [选项C描述]
+  - D) 自定义...
+- **澄清后**: [交互式澄清后自动填写]
+- **澄清时间**: [YYYY-MM-DD]
+- **澄清人**: [@name]
+
+---
+
+##### 2. 数据相关问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-010 | | | | |
+| R1-011 | | | | |
+
+**R1-010 详细说明**:
+- **问题类型**: 数据定义模糊 / 数据量级未明确 / 数据一致性问题
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 3. 用户体验问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-020 | | | | |
+| R1-021 | | | | |
+
+**R1-020 详细说明**:
+- **问题类型**: 用户场景缺失 / 交互方式未确定 / 性能体验要求
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 4. 边界与异常
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-030 | | | | |
+| R1-031 | | | | |
+
+**R1-030 详细说明**:
+- **问题类型**: 边界条件未定义 / 异常场景缺失 / 权限与安全
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 5. 集成与依赖
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-040 | | | | |
+| R1-041 | | | | |
+
+**R1-040 详细说明**:
+- **问题类型**: 外部系统集成 / 内部模块依赖 / 环境依赖
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 6. 优先级与范围
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-050 | | | | |
+| R1-051 | | | | |
+
+**R1-050 详细说明**:
+- **问题类型**: 必需 vs 可选 / 时间约束 / 资源约束
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+### 功能点 2: [功能点名称]
+
+#### 基本信息
+- **功能点 ID**: [kebab-case-id]
+- **对应 Spec**: `specs/[功能点ID]/spec.md`
+- **优先级**: P0 / P1 / P2
+- **负责人**: [@name]
+
+#### 问题列表
+
+[同上结构...]
+
+---
+
+## 问题统计
+
+| 分类 | 总计 | 已澄清 | 待澄清 | 已解决 |
+|------|------|--------|--------|--------|
+| 功能完整性 | 0 | 0 | 0 | 0 |
+| 数据相关 | 0 | 0 | 0 | 0 |
+| 用户体验 | 0 | 0 | 0 | 0 |
+| 边界与异常 | 0 | 0 | 0 | 0 |
+| 集成与依赖 | 0 | 0 | 0 | 0 |
+| 优先级与范围 | 0 | 0 | 0 | 0 |
+| **总计** | 0 | 0 | 0 | 0 |
+
+---
+
+## 澄清记录
+
+### 交互式澄清会话 1: [YYYY-MM-DD]
+- **参与者**: [@name1, @name2, ...]
+- **澄清模式**: 命令行交互式
+- **澄清的问题**: [问题 ID 列表]
+- **达成的决策**:
+  1. [决策 1]
+  2. [决策 2]
+- **更新后的状态**: `clarifying` → `clarified`
+- **下一步行动**: [如果有]
+
+### 交互式澄清会话 2: [YYYY-MM-DD]
+
+[同上结构...]
+
+---
+
+## 状态流转说明
+
+```
+discovering:    AI 正在分析需求，发现问题
+                → 发现问题后自动转为 clarifying
+
+clarifying:     问题已列出，等待交互式澄清
+                → 使用命令行界面一问一答澄清
+                → 每题回答后立即同步到本文档
+                → 支持 'q' 退出，下次自动恢复
+                → 支持 's' 跳过 Low 优先级问题
+
+clarified:      所有 High 和 Medium 问题已澄清
+                → 可以创建/更新 proposal
+                → AI 检查是否发现新问题（可能回到 discovering）
+
+superseded:     需求已变更，本文档已过时
+                → 创建新的问题清单
+```
+
+**当前状态**: `[current-status]`
+
+**状态变更历史**:
+- [YYYY-MM-DD]: `discovering` → `clarifying` (AI 完成问题发现)
+- [YYYY-MM-DD]: `clarifying` → `clarified` (完成澄清会话 1)
+- ...
+
+---
+
+## 关联文档
+
+- **提案文档**: `proposal.md`
+- **功能规格**: `specs/*/spec.md`
+- **设计问题清单**: `spec/design-issues.md`
+- **分类学参考**: `openspec/templates/requirement-issue-taxonomy.md`
+
+---
+
+## 备注
+
+<!-- 任何补充说明 -->