kld-sdd 1.0.0

package/templates/opsx-commands/design.md

@@ -0,0 +1,164 @@
+---
+name: OPSX: Design
+description: "创建技术实现方案文档 - 定义业务维度的具体实现"
+argument-hint: "[change-name]"
+---
+
+创建 **design.md** - 业务维度的技术实现方案文档（聚焦 How，但不是全局架构选型）。
+
+---
+
+**输入**: `/opsx:design` 后跟变更名称（kebab-case）
+
+**前置要求**: 已运行 `/opsx:spec` 或 spec.md 已存在
+
+**执行步骤**
+
+1. **确认变更名称**
+
+   若未提供，列出当前所有变更供用户选择：
+   ```bash
+   openspec list
+   ```
+   若 spec.md 不存在，提示用户先运行 `/opsx:spec <name>`。
+
+2. **读取前置文档**
+
+   按以下顺序读取已存在的文档，作为 design.md 的输入上下文：
+   - `propose.md` / `proposal.md`（业务背景）
+   - `spec.md` / `specs.md`（技术契约）—— **必须存在**
+
+3. **获取 design artifact 的编写指导**
+   ```bash
+   openspec instructions design --change "<name>" --json
+   ```
+   解析返回的 JSON，获取：
+   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
+   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
+   - `template`：文档结构模版（用于生成文档的骨架）
+   - `outputPath`：文档输出路径
+   - `dependencies`：前置依赖文件路径（先读取）
+
+4. **读取已有依赖文档**
+
+   按 `dependencies` 中的路径读取已完成文件，作为编写参考。
+
+5. **创建 design.md**
+
+   以 `template` 为骨架、`context` 和 `rules` 为约束，写入以下内容到 `outputPath`：
+
+   **【质量红线】生成文档必须聚焦本业务落地细节，不得写全局架构：**
+
+   #### 1. 总体设计
+
+   **1.1 设计目标**
+   本设计要解决的具体问题
+
+   **1.2 核心流程**
+   ```
+   [步骤1] --> [步骤2] --> [步骤3]
+      |           |
+      v           v
+   [分支A]     [分支B]
+   ```
+
+   **1.3 时序图**
+   ```
+   参与者A -> 参与者B: 消息描述
+   参与者B -> 参与者C: 消息描述
+   参与者C --> 参与者B: 响应
+   参与者B --> 参与者A: 响应
+   ```
+
+   #### 2. 模块设计【每个模块必须有明确职责】
+
+   **模块A：XXX**
+   - 职责：
+   - 输入：
+   - 输出：
+   - 核心逻辑：
+
+   #### 3. 接口调用关系【质量红线：必须明确到接口级别】
+
+   **3.1 内部接口调用**
+   | 调用方 | 被调用接口 | 调用方式 | 用途 | 失败处理 |
+   |-------|-----------|---------|------|---------|
+   | | | HTTP/RPC/本地 | | |
+
+   **3.2 复用模块**
+   | 复用模块 | 复用能力 | 集成方式 | 约束条件 |
+   |---------|---------|---------|---------|
+   | | | | |
+
+   **3.3 第三方服务调用**
+   | 服务 | 接口 | 用途 | 超时配置 | 降级策略 |
+   |-----|------|------|---------|---------|
+   | | | | | |
+
+   #### 4. 数据设计【质量红线：必须到字段/Key 级别】
+
+   **数据库表：xxx_table**
+   | 字段名 | 类型 | 长度 | 必填 | 默认值 | 说明 | 索引 |
+   |-------|------|------|------|--------|------|------|
+   | id | BIGINT | | 是 | 自增 | 主键 | PK |
+   | | | | | | | |
+
+   索引设计：主键 / 唯一索引 / 普通索引
+
+   **缓存设计**
+   | 缓存Key | 数据类型 | 过期时间 | 更新策略 | 说明 |
+   |--------|---------|---------|---------|------|
+   | | | | | |
+
+   #### 5. 异常处理
+
+   **5.1 异常分类**
+   | 异常类型 | 触发条件 | 处理策略 | 用户感知 |
+   |---------|---------|---------|---------|
+   | 业务异常 | | | |
+   | 系统异常 | | | |
+   | 第三方异常 | | | |
+
+   **5.2 重试策略**
+   - 重试次数：
+   - 重试间隔：
+   - 退避策略：
+
+   #### 6. 关键算法/逻辑（如有）
+
+   算法描述 / 状态机（所有可能的状态和事件转换）
+
+   #### 7. 局部配置
+   | 配置项 | 配置Key | 默认值 | 说明 |
+   |-------|---------|-------|------|
+   | | | | |
+
+6. **质量红线自检**
+
+   写入文档前，逐项确认：
+   - [ ] 无全局中间件或框架选型内容（聚焦本业务）
+   - [ ] 内部接口调用已明确（接口名、调用方式、失败处理）
+   - [ ] 复用模块已明确列出
+   - [ ] 数据库表结构已详细到字段级别（类型、索引）
+   - [ ] 缓存设计已详细到 Key 级别（过期、更新策略）
+   - [ ] 异常处理策略已定义（业务/系统/第三方三类）
+   - [ ] 内容足够支撑 task.md 的原子任务拆解
+
+   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+7. **显示输出结果**
+
+   完成后显示：
+   - 文档路径（来自 `outputPath`）
+   - 模块划分摘要（模块名 + 职责）
+   - 下一步提示："运行 `/opsx:task` 拆解实现任务"
+
+---
+
+**Guardrails**
+
+- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
+- 全局架构约束由框架 Skill 兜底，此文档不要重复写
+- 设计必须可验证：每个设计点都能在代码中找到对应
+- 状态转换必须完整：所有可能的状态和事件都要覆盖
+- 文档写入后验证文件确实存在于 `outputPath`

package/templates/opsx-commands/propose.md

@@ -0,0 +1,106 @@
+---
+name: OPSX: Propose
+description: "创建业务意图文档 - 定义变更的 Why 和上下文总览"
+argument-hint: "[change-name-or-description]"
+---
+
+创建 **propose.md** - 业务意图与上下文总览文档（聚焦 Why）。
+
+---
+
+**输入**: `/opsx:propose` 后跟变更名称（kebab-case）或需求描述
+
+**执行步骤**
+
+1. **若未提供输入，询问用户**
+
+   使用 **AskUserQuestion 工具**（开放式问题）询问：
+   > "请描述本次变更的业务需求：要解决什么问题？达成什么目标？"
+
+   从描述中推导 kebab-case 名称，如 "add user authentication" → `add-user-auth`。
+
+   **重要**：未明确需求前不得继续。
+
+2. **创建变更目录（如不存在则新建）**
+   ```bash
+   openspec new change "<name>"
+   ```
+   此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
+   若变更已存在，询问用户是否继续该变更。
+
+3. **获取 proposal artifact 的编写指导**
+   ```bash
+   openspec instructions proposal --change "<name>" --json
+   ```
+   解析返回的 JSON，获取：
+   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
+   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
+   - `template`：文档结构模版（用于生成文档的骨架）
+   - `outputPath`：文档输出路径
+   - `dependencies`：前置依赖文件路径（如有，先读取）
+
+4. **读取已有上下文（如有依赖）**
+
+   按 `dependencies` 中的路径读取已完成文件，作为编写参考。
+
+5. **创建 propose.md**
+
+   以 `template` 为骨架、`context` 和 `rules` 为约束，写入以下内容到 `outputPath`：
+
+   **【质量红线】生成文档必须包含以下所有章节，且不得模糊：**
+
+   #### 1. 需求背景
+   - 现状问题（具体痛点，禁止泛化描述）
+   - 业务诉求（为什么要做这件事）
+
+   #### 2. 业务目标【SMART 原则，必须可验收】
+   | 目标维度 | 具体描述 | 验收标准 |
+   |---------|---------|---------|
+   | 功能目标 | | |
+   | 性能目标 | | |
+   | 体验目标 | | |
+
+   #### 3. 影响范围【必须明确，不得遗漏】
+   - 涉及模块清单（逐一列举）
+   - 依赖关系（上游依赖 / 下游影响）
+   - 数据影响（表 / 接口 / 配置变更）
+
+   #### 4. 约束与假设
+   - 业务约束
+   - 技术约束
+   - 前置依赖清单
+
+   #### 5. 风险评估
+   | 风险项 | 概率 | 影响 | 应对策略 |
+   |-------|------|------|---------|
+   | | | | |
+
+   #### 6. 相关文档
+   - 需求文档 / 原型链接
+
+6. **质量红线自检**
+
+   写入文档前，逐项确认：
+   - [ ] 逻辑链路闭环：说清楚【为什么做】→【做什么】→【影响什么】
+   - [ ] 受影响模块已完整列出，无遗漏
+   - [ ] 业务目标有可验收的具体标准（符合 SMART）
+   - [ ] 上游依赖与下游影响均已明确
+
+   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+7. **显示输出结果**
+
+   完成后显示：
+   - 文档路径（来自 `outputPath`）
+   - 内容摘要（背景 + 目标 + 影响模块）
+   - 下一步提示："运行 `/opsx:spec` 创建技术契约文档"
+
+---
+
+**Guardrails**
+
+- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
+- propose.md 聚焦【Why】，不要写技术实现细节（留给 design.md）
+- 不要写 API 细节（留给 spec.md）
+- 若跳过此文档，后续 spec.md 必须补齐影响范围
+- 文档写入后验证文件确实存在于 `outputPath`

package/templates/opsx-commands/spec.md

@@ -0,0 +1,145 @@
+---
+name: OPSX: Spec
+description: "创建技术契约文档 - 定义业务场景与技术规范"
+argument-hint: "[change-name]"
+---
+
+创建 **spec.md** - 业务场景与技术契约文档（代码生成的唯一真理，聚焦 What）。
+
+---
+
+**输入**: `/opsx:spec` 后跟变更名称（kebab-case）
+
+**前置要求**: 已运行 `/opsx:propose` 或变更目录已存在
+
+**执行步骤**
+
+1. **确认变更名称**
+
+   若未提供，列出当前所有变更供用户选择：
+   ```bash
+   openspec list
+   ```
+   若变更不存在，引导用户先运行 `/opsx:propose <name>`。
+
+2. **读取前置文档（如存在）**
+
+   读取 `openspec/changes/<name>/proposal.md`（或 propose.md），获取业务背景作为上下文输入。
+
+3. **获取 specs artifact 的编写指导**
+   ```bash
+   openspec instructions specs --change "<name>" --json
+   ```
+   解析返回的 JSON，获取：
+   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
+   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
+   - `template`：文档结构模版（用于生成文档的骨架）
+   - `outputPath`：文档输出路径
+   - `dependencies`：前置依赖文件路径（先读取）
+
+4. **读取已有依赖文档**
+
+   按 `dependencies` 中的路径读取已完成文件，作为编写参考。
+
+5. **创建 spec.md**
+
+   以 `template` 为骨架、`context` 和 `rules` 为约束，写入以下内容到 `outputPath`：
+
+   **【质量红线】生成文档必须包含以下所有章节，且所有描述必须精确无歧义：**
+
+   #### 1. 业务场景描述
+
+   **1.1 场景概述**
+   一句话描述业务场景
+
+   **1.2 业务规则【每条规则必须明确、无歧义】**
+   1.
+   2.
+
+   **1.3 边界场景【必须覆盖正常+所有异常】**
+   | 场景 | 预期行为 |
+   |-----|---------|
+   | 正常流程 | |
+   | 异常流程A | |
+   | 异常流程B | |
+
+   #### 2. 技术契约【严禁模糊描述】
+
+   **2.1 API 定义**
+   - 路径：`/api/v1/xxx`
+   - Method：GET/POST/PUT/DELETE
+   - Content-Type：application/json
+
+   **请求参数【每个参数必须有：类型、必填、范围、示例值】**
+   | 参数名 | 类型 | 必填 | 说明 | 示例值 | 约束条件 |
+   |-------|------|------|------|--------|---------|
+   | | | | | | |
+
+   **响应结构**
+   ```json
+   {
+     "code": 0,
+     "message": "success",
+     "data": {}
+   }
+   ```
+
+   **错误码定义【每个错误码必须有触发条件】**
+   | 错误码 | 含义 | 触发条件 |
+   |-------|------|---------|
+   | | | |
+
+   #### 3. 物理约束【必须量化，禁止范围模糊】
+
+   **性能约束**
+   | 指标 | 约束值 | 说明 |
+   |------|-------|------|
+   | 响应时间 | < X ms (P99) | |
+   | 吞吐量 | > X QPS | |
+   | 并发数 | 最大 X | |
+
+   **超时配置**
+   - 连接超时：X ms
+   - 读取超时：X ms
+   - 总超时：X ms
+
+   #### 4. 影响模块【若跳过 propose.md 必须在此补齐】
+   - 内部依赖服务（调用方式、用途、降级策略）
+   - 外部第三方服务
+   - 数据存储（表名、操作类型、缓存 Key）
+
+   #### 5. 安全与合规
+   - 认证方式 / 授权范围
+   - 敏感字段 / 加密要求
+
+   #### 6. 兼容性
+   - 是否向后兼容：是/否
+   - 版本控制策略 / 数据迁移方案 / 回滚策略
+
+6. **质量红线自检**
+
+   写入文档前，逐项确认：
+   - [ ] 所有参数已量化（类型、必填、范围、示例值）
+   - [ ] 物理约束已量化（并发、超时、性能指标均为具体数字）
+   - [ ] 边界场景已覆盖（正常流程 + 所有异常流程）
+   - [ ] 所有错误码已定义，并有触发条件
+   - [ ] 若跳过 propose.md，影响范围已在此文档补齐
+
+   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+7. **显示输出结果**
+
+   完成后显示：
+   - 文档路径（来自 `outputPath`）
+   - API 清单摘要（接口名 + 参数数量）
+   - 下一步提示："运行 `/opsx:design` 创建技术实现方案"
+
+---
+
+**Guardrails**
+
+- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
+- 此文档是代码生成的【唯一依据】，必须准确无歧义
+- 不要写具体实现代码（留给 task.md）
+- 参数约束必须可验证（正则、范围、枚举值）
+- 文档写入后验证文件确实存在于 `outputPath`

package/templates/opsx-commands/task.md

@@ -0,0 +1,179 @@
+---
+name: OPSX: Task
+description: "创建任务拆解文档 - 定义 AI 编码的极小执行单元"
+argument-hint: "[change-name]"
+---
+
+创建 **task.md** - AI 编码引擎的极小执行单元与指令集（聚焦 Do）。
+
+---
+
+**输入**: `/opsx:task` 后跟变更名称（kebab-case）
+
+**前置要求**: 已运行 `/opsx:design` 或 design.md 已存在
+
+**执行步骤**
+
+1. **确认变更名称**
+
+   若未提供，列出当前所有变更供用户选择：
+   ```bash
+   openspec list
+   ```
+   若 design.md 不存在，提示用户先运行 `/opsx:design <name>`。
+
+2. **读取前置文档**
+
+   按以下顺序读取所有已存在的文档，作为任务拆解的输入：
+   - `propose.md` / `proposal.md`（业务背景）
+   - `spec.md` / `specs.md`（技术契约）—— **每个 API 和约束都必须有对应任务**
+   - `design.md`（实现方案）—— **每个模块和接口都必须有对应任务**
+
+3. **获取 tasks artifact 的编写指导**
+   ```bash
+   openspec instructions tasks --change "<name>" --json
+   ```
+   解析返回的 JSON，获取：
+   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
+   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
+   - `template`：文档结构模版（用于生成文档的骨架）
+   - `outputPath`：文档输出路径
+   - `dependencies`：前置依赖文件路径（先读取）
+
+4. **读取已有依赖文档**
+
+   按 `dependencies` 中的路径读取已完成文件，作为编写参考。
+
+5. **创建 task.md**
+
+   以 `template` 为骨架、`context` 和 `rules` 为约束，写入以下内容到 `outputPath`：
+
+   **【质量红线】每个任务必须是 AI 能在 5 分钟内完成的原子操作：**
+
+   #### 1. 任务总览
+
+   **1.1 关联文档**
+   - propose.md：路径
+   - spec.md：路径
+   - design.md：路径
+
+   **1.2 实现范围**
+   本次编码要覆盖的功能范围
+
+   **1.3 技术栈**
+   - 语言：
+   - 框架：
+   - 依赖：
+
+   #### 2. 原子任务清单【质量红线：5 分钟可实现】
+
+   <!-- 按「数据层 → 业务层 → 接口层」顺序拆解，无依赖的任务优先 -->
+
+   **任务 1：XXX**
+
+   - 任务描述：一句话描述本任务要做什么
+   - 输入：
+   - 输出：
+   - 实现步骤：
+     1.
+     2.
+     3.
+   - 验收标准：
+     - [ ] 标准1
+     - [ ] 标准2
+   - 关联设计：spec.md 章节 / design.md 章节
+
+   ---
+
+   **任务 2：XXX**
+
+   - 任务描述：
+   - 输入：
+   - 输出：
+   - 实现步骤：
+     1.
+     2.
+     3.
+   - 验收标准：
+     - [ ]
+     - [ ]
+   - 关联设计：spec.md 章节 / design.md 章节
+
+   #### 3. 验证方式【质量红线：每个任务必须有测试】
+
+   **3.1 单元测试要求**
+   | 任务 | 测试类型 | 测试场景 | 断言内容 |
+   |-----|---------|---------|---------|
+   | 任务1 | | | |
+   | 任务2 | | | |
+
+   **3.2 集成测试场景**
+   | 场景 | 前置条件 | 操作步骤 | 预期结果 |
+   |-----|---------|---------|---------|
+   | | | | |
+
+   **3.3 手动验证清单**
+   - [ ] 验证项1
+   - [ ] 验证项2
+
+   #### 4. 依赖关系
+
+   **4.1 任务依赖图**
+   ```
+   任务1 --> 任务2 --> 任务4
+      |         |
+      v         v
+   任务3 --> 任务5
+   ```
+
+   **4.2 外部依赖**
+   | 依赖项 | 提供方 | 状态 | 备注 |
+   |-------|-------|------|------|
+   | | | | |
+
+   #### 5. 代码规范
+
+   - 命名规范（类名、方法名、变量名）
+   - 代码风格（缩进、注释、异常处理）
+
+   #### 6. 交付物
+
+   **6.1 代码文件**
+   | 文件路径 | 说明 | 对应任务 |
+   |---------|------|---------|
+   | | | |
+
+   **6.2 测试文件**
+   | 文件路径 | 说明 | 对应任务 |
+   |---------|------|---------|
+   | | | |
+
+6. **质量红线自检【100% 覆盖检查】**
+
+   写入文档前，逐项确认：
+   - [ ] 每个任务颗粒度符合"5 分钟可实现"标准（过大则继续拆分）
+   - [ ] 任务清单 100% 覆盖 spec.md 定义（每个 API、每个约束都有对应任务）
+   - [ ] 任务清单 100% 覆盖 design.md 定义（每个模块、每个接口都有对应任务）
+   - [ ] 每个任务都有明确的验收标准（可验证，能判断完成/未完成）
+   - [ ] 每个任务都有对应的单元测试要求
+   - [ ] 任务依赖关系已明确（无循环依赖）
+
+   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
+
+7. **显示输出结果**
+
+   完成后显示：
+   - 文档路径（来自 `outputPath`）
+   - 任务清单摘要（共 X 个任务）
+   - 依赖关系图
+   - 完成提示："所有任务已拆解完成！运行 `/opsx:apply` 开始实现"
+
+---
+
+**Guardrails**
+
+- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
+- 任务颗粒度宁可过细也不要过粗，复杂任务继续拆分为子任务
+- 验收标准必须是可验证的（能通过测试或人工检查确认）
+- 任务拆解顺序：按「数据层 → 业务层 → 接口层」，无依赖的任务优先
+- 文档写入后验证文件确实存在于 `outputPath`