kld-sdd 2.4.14 → 2.4.15

package/templates/opsx-commands/spec.md

@@ -1,526 +0,0 @@
----
-name: OPSX: Spec
-description: "创建技术契约文档 - 为每个能力定义业务场景与技术规范"
-argument-hint: "[change-name] [上下文文件...]"
----
-
-创建 **specs/<capability>/spec.md** - 业务场景与技术契约文档（代码生成的唯一真理，聚焦 What）。
-
-> **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
-> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
-> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
-
-> **⚠️ 阶段边界提示**
->
-> 当前处于 **Spec（契约）阶段**，此阶段：
-> - ✅ **允许**：创建/编辑 spec.md 文档、读取代码/文档作为上下文分析
-> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
-> - ⛔ **单阶段原则**：完成 spec.md 后**必须立即停止**，等待用户主动触发下一阶段
->
-> 即使用户提供了代码作为上下文，也只用于分析现有实现，**不执行任何代码操作**。
-> 代码实现将在 `/opsx:apply` 阶段进行。
-> **完成本阶段后，绝对禁止自动继续执行 design/task 等后续阶段。**
-
-**【文件结构】**：每个 capability 生成一个独立的 spec 文件：
-```
-openspec/changes/<name>/
-├── proposal.md
-├── specs/
-│   ├── user-auth/
-│   │   └── spec.md      # capability 1 的规格
-│   ├── data-export/
-│   │   └── spec.md      # capability 2 的规格
-│   └── ...
-├── design.md
-└── tasks.md
-```
-
----
-
-**前置要求**: 已运行 `/opsx:propose` 且 proposal.md 中已定义能力列表
-
-**执行步骤**
-
-0. **【Telemetry 必做】记录阶段开始**
-
-   在终端执行（若命令失败必须中止本阶段，不得跳过）：
-   ```bash
-   node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
-   ```
-   保存输出 JSON 中的 `event_id`，供阶段结束使用。
-
-1. **【交互引导】确认变更名称**
-
-   若未提供，列出当前所有变更供用户选择：
-   ```bash
-   openspec list
-   ```
-   若变更不存在，引导用户先运行 `/opsx:propose <name>`。
-
-   **【变更选择交互】**：
-   > "请选择要创建 specs 的变更：
-   > 1. [变更1名称] - [变更描述]
-   > 2. [变更2名称] - [变更描述]
-   > ..."
-
-   若只有一个变更，直接确认："是否继续变更 `[name]`？(y/n)"
-
-2. **【关键步骤】读取 proposal.md 并提取 Capabilities**
-
-   读取 `openspec/changes/<name>/proposal.md`，**重点提取 Capabilities 章节**：
-
-   ```markdown
-   ## 3. 能力分解
-
-   ### 3.1 新增能力
-   - `user-auth`: 用户认证能力
-   - `data-export`: 数据导出能力
-
-   ### 3.2 修改能力
-   - `existing-feature`: 修改某需求
-   ```
-
-   **解析规则**：
-   - 新增能力：创建 `specs/<capability-name>/spec.md`
-   - 修改能力：创建 `specs/<existing-name>/spec.md`（增量规格）
-
-   **【上下文完整性检查】**：
-   - [ ] proposal.md 是否存在？
-   - [ ] 能力分解章节是否存在？
-   - [ ] 是否列出了至少一个 capability？
-
-   **【发现上下文不足时】**：
-   > "proposal.md 中未定义能力列表，请选择：
-   > - A. 先运行 `/opsx:propose` 补充能力分解章节
-   - B. 在此处定义需要创建的能力
-   > - C. 取消操作"
-
-3. **【上下文加载】识别并读取用户提供的文件**
-
-   **自动识别上下文文件**：
-   若用户在命令中指定了文件路径（如 `/opsx:spec atp-calc ./算法逻辑.md ./testcase/`），
-   或在对话中附加/引用了文件，**必须自动读取这些文件**。
-
-   **文件识别规则**：
-   - 以 `.md`、`.txt`、`.java`、`.ts`、`.xml`、`.json` 等扩展名结尾 → 识别为文件路径
-   - 以 `/` 或 `./` 开头 → 识别为路径
-   - 目录路径 → 递归读取目录下的文件
-
-   **上下文类型与用途**：
-   | 文件类型 | 用途 | 用法 |
-   |---------|------|------|
-   | 需求文档 (.md) | 提取业务规则、算法逻辑 | 生成 Requirement |
-   | 代码文件 (.java/.ts) | 理解现有实现 | 提取接口定义 |
-   | 测试文件 (*Test.java) | 提取测试场景 | 生成 Scenario |
-   | 测试数据 (.xml/.json) | 理解边界条件 | 补充 Scenario 边界 |
-
-   **示例**：
-   ```
-   /opsx:spec atp-calc ./ATP引擎算法逻辑.md
-   /opsx:spec atp-calc ./erp-algorithm-atp/src/ ./testcase/ATP1.xml
-   ```
-
-4. **【交互引导】上下文补充提示**
-
-   **若用户未提供任何上下文文件**，AI 分析 proposal.md 后，**主动提示用户补充**：
-
-   **【关键】具体化建议**：
-   AI 必须**引用 proposal.md 中的具体内容**给出建议：
-   ```
-   ❌ 错误："建议提供测试用例"
-   ✅ 正确："proposal.md 提到了《ATP计算》，建议提供 ATP 算法逻辑文档或测试用例"
-   ```
-
-   **主动提示模板**：
-   > "📌 **建议提供更丰富的上下文信息**：
-   > 
-   > proposal.md 中提到：
-   > - **《[XX算法/功能]》** - 建议提供详细算法说明文档
-   > - **《[XX测试场景]》** - 建议提供测试用例或测试数据
-   >
-   > 您可以：
-   > - **在命令后追加文件路径**：`/opsx:spec atp-calc ./算法.md ./testcase/`
-   > - **在对话中上传文件**或粘贴内容
-   > - **告诉我文件位置**，我会自动读取
-   >
-   > 或者选择：
-   > - A. 基于现有信息继续（Scenario 可能不完整）
-   > - B. 已提供全部信息"
-
-5. **【关键步骤】读取本地模板文件**
-
-   **必须先读取** `openspec-templates/spec.md` 作为文档结构模板：
-   ```
-   使用 Read 工具读取：openspec-templates/spec.md
-   ```
-
-   此模板用于每个 capability 的 spec.md 文件，定义了：
-   - 需求项格式（`### 需求项：<name>`）
-   - 场景格式（`#### 场景：<name>` + 当/预期）
-   - 变更操作（新增/修改/移除）
-
-   **【重要】不得使用 `openspec instructions` 返回的简化 template，必须以 `openspec-templates/spec.md` 为准。**
-
-6. **获取项目上下文（可选）**
-   ```bash
-   openspec instructions specs --change "<name>" --json
-   ```
-   解析返回的 JSON，仅获取：
-   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
-   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
-   - `outputPath`：文档输出路径（`specs/**/*.md`）
-
-   **注意**：忽略返回的 `template` 字段，使用步骤 3 读取的本地模板。
-
-7. **【交互引导】确认要创建的 specs 列表**
-
-   向用户展示即将创建的 spec 文件：
-   > "根据 proposal.md 中的 Capabilities，将创建以下 spec 文件：
-   > - specs/user-auth/spec.md（新增）
-   > - specs/data-export/spec.md（新增）
-   > - specs/existing-feature/spec.md（修改）
-   >
-   > 请确认：
-   > - A. 确认列表，开始创建
-   > - B. 跻加更多 capabilities
-   > - C. 跳过某些 capabilities"
-
-8. **【AI 分析澄清】识别模糊点**
-
-   对每个 capability，分析是否有需要澄清的技术点：
-
-   **常见需要澄清的场景**：
-   - 业务规则存在多种技术实现可能
-   - 性能要求未量化（"高性能"→具体 QPS/RT）
-   - 安全要求不明确（"安全"→具体认证/加密方式）
-   - 边界场景未覆盖
-   - **技术选型缺少版本信息**（框架、库、中间件等）
-
-   **【主动询问机制】**：
-   > "capability '原文' 存在多种技术实现可能：
-   > - 方案A：[技术方案A]
-   > - 方案B：[技术方案B]
-   > 请确认采用哪种方案，或提供更多信息："
-
-   **【技术选型版本引导】**：
-   当发现技术选型（框架、库、中间件、数据库等）未指定版本时，主动询问：
-   > "检测到以下技术选型未指定版本：
-   > | 技术组件 | 当前描述 | 需要补充 |
-   > |---------|---------|---------|
-   > | Redis | 仅提及使用 | 版本号（如 7.x） |
-   > | Spring Boot | 仅提及使用 | 版本号（如 3.2.x） |
-   > | MySQL | 仅提及使用 | 版本号（如 8.0） |
-   >
-   > 版本信息对后续开发至关重要，请补充：
-   > - A. 逐个指定版本
-   > - B. 使用项目当前已有版本（若有）
-   > - C. 使用最新稳定版（将自动查询）"
-
-9. **【循环】为每个 capability 创建 spec.md**
-
-   **以 `openspec-templates/spec.md` 的结构为骨架**，为每个 capability 创建独立的 spec 文件：
-
-   **【输出路径】**：`specs/<capability-name>/spec.md`
-
-   **【质量红线】生成文档必须使用完整模板结构：**
-
-   ```markdown
-   # spec.md - 能力规格定义
-
-   > **定位**：单个能力（capability）的技术规格定义
-   > **【质量红线】严禁描述模糊；约束必须量化
-   > **【格式要求】** 需求项使用 `####`（4个#），场景必须使用 `#####`（5个#）
-
-   ---
-
-   ## 1. 需求规格
-
-   ### 新增需求
-
-   #### 需求项：<!-- 需求名称 -->
-   系统必须 ...
-
-   ##### 场景：<!-- 场景名称 -->
-   - **当** <!-- 触发条件 -->
-   - **预期** <!-- 预期结果 -->
-
-   ### 修改需求
-   <!-- 仅当修改已有需求时使用，必须复制完整原需求内容再修改 -->
-
-   #### 需求项：<!-- 已有需求名称 -->
-   系统必须 ...
-
-   ### 移除需求
-   <!-- 仅当移除已有需求时使用 -->
-
-   #### 需求项：<!-- 被移除的需求名称 -->
-   **移除原因**：<!-- 移除原因 -->
-   **迁移方案**：<!-- 迁移方案 -->
-
-   ---
-
-   ## 2. 技术契约（SDD 扩展）
-
-   <!-- 具体的技术实现契约，代码生成的“唯一真理” -->
-
-   ### 2.1 接口定义
-   #### 接口基本信息
-   - **路径**：`/api/v1/xxx`
-   - **方法**：GET/POST/PUT/DELETE
-   - **内容类型**：application/json
-
-   #### 请求参数
-   | 参数名 | 类型 | 必填 | 说明 | 示例值 | 约束条件 |
-   |-------|------|------|------|--------|----------|
-   | | | | | | |
-
-   #### 响应结构
-   ```json
-   { "code": 0, "message": "success", "data": {} }
-   ```
-
-   #### 错误码定义
-   | 错误码 | 含义 | 触发条件 |
-   |-------|------|----------|
-   | | | |
-
-   ---
-
-   ## 3. 物理约束
-
-   <!-- 【质量红线】所有约束必须量化 -->
-
-   ### 3.1 性能约束
-   | 指标 | 约束值 | 说明 |
-   |------|-------|------|
-   | 响应时间 | < X 毫秒 (P99) | |
-   | 吞吐量 | > X QPS | |
-   | 并发数 | 最大 X | |
-
-   ### 3.2 资源约束
-   | 资源 | 限制 | 说明 |
-   |------|------|------|
-   | 内存 | < X MB | |
-   | CPU | < X% | |
-   | 存储 | < X GB | |
-
-   ### 3.3 超时配置
-   - 连接超时：X 毫秒
-   - 读取超时：X 毫秒
-   - 总超时：X 毫秒
-
-   ---
-
-   ## 4. 影响模块
-
-   ### 4.1 内部依赖
-   - [ ] 服务A：调用方式、用途
-
-   ### 4.2 外部依赖
-   <!-- 【质量红线】技术选型必须包含版本信息 -->
-   | 组件类型 | 组件名称 | 版本 | 用途 | 降级策略 |
-   |---------|---------|------|------|--------|
-   | 框架 | | | | |
-   | 数据库 | | | | |
-   | 缓存 | | | | |
-   | 消息队列 | | | | |
-   | 第三方 SDK | | | | |
-
-   ### 4.3 数据存储
-   - [ ] 数据库（版本 X.x）：表名、操作类型
-   - [ ] 缓存（版本 X.x）：Key 模式、过期时间
-
-   ---
-
-   ## 5. 安全与合规
-
-   ### 5.1 权限要求
-   - 认证方式：
-   - 授权范围：
-
-   ### 5.2 数据安全
-   - 敏感字段：
-   - 加密要求：
-
-   ### 5.3 审计要求
-   - 日志记录：
-   - 操作追踪：
-
-   ---
-
-   ## 6. 兼容性
-
-   ### 6.1 接口兼容性
-   - 是否向后兼容：是/否
-   - 版本控制策略：
-
-   ### 6.2 数据兼容性
-   - 数据迁移方案：
-   - 回滚策略：
-
-   ---
-
-   > **质量红线检查清单**
-   > - [ ] 每个需求项至少有一个场景
-   > - [ ] 使用「必须」强制要求，而非「应该」「可以」
-   > - [ ] 所有接口参数已量化（类型、必填、范围、示例）
-   > - [ ] 物理约束已量化（并发、超时、性能指标）
-   > - [ ] 错误码已定义
-   > - [ ] **技术选型已包含版本信息**
-   > - [ ] 若跳过 proposal.md，影响范围已在此补齐
-   ```
-
-   **【关键格式要求】**：
-   - 每个需求项使用 `#### 需求项：<name>` 格式（4个 #）
-   - 每个场景 **必须**使用 `##### 场景：<name>`（5个 #）
-   - 每个需求项 **必须**有至少一个场景
-   - 使用 当/预期 格式描述场景
-
-10. **质量红线自检**
-
-   对每个 spec.md 文件，逐项确认：
-   - [ ] 需求项格式正确（`#### 需求项：`，4个#）
-   - [ ] 场景格式正确（`##### 场景：`，5个#）
-   - [ ] 每个需求项至少有一个场景
-   - [ ] 使用「必须」强制要求，而非「应该」「可以」
-   - [ ] 修改需求包含完整内容而非部分内容
-   - [ ] **技术选型已包含版本信息**（框架、库、中间件、数据库等）
-
-11. **【新增】场景完整性检查**
-
-   **❗ 此步骤是防止场景缺失的关键门禁**
-
-   #### 9.1 需求项-场景配比检查
-   
-   | 检查项 | 要求 | 未通过处理 |
-   |---------|------|------------|
-   | 场景数量 | 每个需求项至少 1 个场景 | ❗ 警告并要求补充 |
-   | 场景结构 | 每个场景必须有 当/预期 | ❌ 拒绝通过 |
-   | 预期结果 | 每个场景必须有可验证的预期 | ❗ 警告 |
-
-   #### 9.2 场景可测试性检查
-   
-   - [ ] 输入参数是否可构造（测试数据是否可获取）
-   - [ ] 预期结果是否可断言（不能是 "XXX 应该正确"）
-   - [ ] 边界条件是否明确（空值、零值、极值）
-
-   #### 9.3 场景缺失预警
-   
-   若发现以下情况，**必须**标记为警告：
-   - 场景只有需求声明但无详细描述
-   - 场景描述使用 "等"、"之类" 等模糊词汇
-   - 场景的预期结果无法量化验证
-
-   **【检查报告格式】**：
-   ```markdown
-   ### 场景完整性检查结果
-   
-   | 需求项 | 场景数量 | 状态 | 缺失场景 |
-   |-------------|--------------|------|----------|
-   | 离散 ATP 计算 | 2 | ✅ 完整 | - |
-   | 存储地点级别 ATP | 1 | ⚠️ 需补充 | 存储地点 ATP 合并场景 |
-   | 补货提前期 | 0 | ❌ 缺失 | 采购件/生产件 RLT 场景 |
-   ```
-
-   **【缺失场景处理】**：
-   > "⚠️ **场景完整性检查发现以下问题**：
-   > - 需求项「存储地点级别 ATP」只有 1 个场景，建议补充：存储地点 ATP 合并场景
-   > - 需求项「补货提前期」缺少场景，需要定义：采购件/生产件场景
-   >
-   > 请选择：
-   > - A. 补充上下文文档后重新生成
-   > - B. 手动定义缺失场景
-   > - C. 标记为 '已知风险' 继续"
-
-   **【技术选型版本自检】**：
-   扫描文档中提及的技术组件，确认版本信息完整：
-   - 框架（Spring Boot、Django、Express 等）
-   - 数据库（MySQL、PostgreSQL、MongoDB 等）
-   - 缓存（Redis、Memcached 等）
-   - 消息队列（Kafka、RabbitMQ 等）
-   - 第三方 SDK/库
-
-   **版本格式要求**：
-   - 明确主版本号（如 `Redis 7.x`、`MySQL 8.0`）
-   - 若有特殊版本要求，说明原因（如"需要 Redis 7.0+ 支持 Functions"）
-
-   **【自检发现问题时的澄清】**：
-   - 标记未通过项
-   - 向用户说明具体问题：
-     > "质量自检发现以下问题需要澄清：
-     > - [问题1]：[具体描述]
-     > - [问题2]：[具体描述]
-     > 请补充信息或确认标准："
-   - 获取用户反馈后，重新生成对应章节
-
-   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
-
-   **【必须输出】质量自检报告**：
-
-   所有检查完成后，**必须**向用户展示结构化的自检报告（合并步骤10和步骤11的检查结果）：
-
-   > "✅ **质量自检报告** - `specs/<capability>/spec.md`
-   >
-   > | 检查项 | 状态 | 说明 |
-   > |--------|------|------|
-   > | 需求项格式正确（4个#） | ✅/❌ | 共 N 个需求项 |
-   > | 场景格式正确（5个#） | ✅/❌ | 共 M 个场景 |
-   > | 每个需求项至少一个场景 | ✅/❌ | |
-   > | 使用「必须」强制要求 | ✅/⚠️ | |
-   > | 修改需求包含完整内容 | ✅/❌ | |
-   > | 技术选型包含版本 | ✅/⚠️ | |
-   > | 场景完整性 | ✅/⚠️ | 见下方详情 |
-   > | 场景可测试性 | ✅/⚠️ | |
-   >
-   > **结论**：全部通过 ✅ / 存在问题需修复 ❌"
-
-   **未通过项处理**：若有 ❌ 项，自动修复后重新输出报告，直至全部 ✅。
-
-12. **【交互引导】确认文档并输出结果**
-
-    生成所有 spec 文件后，向用户展示概要：
-    > "已创建以下 spec 文件：
-    > - specs/user-auth/spec.md：[X] 个需求项，[Y] 个场景
-    > - specs/data-export/spec.md：[X] 个需求项，[Y] 个场景
-    >
-    > 请确认：
-    > - A. 确认无误，继续创建 design.md
-    > - B. 需要调整 [具体 capability]
-    > - C. 补充更多需求项/场景"
-
-    根据用户反馈处理：
-    - 选择 A：保存文档，提示下一步
-    - 选择 B/C：根据反馈修改文档
-
-    最终输出：
-    - 创建的文件列表（`specs/<capability>/spec.md`）
-    - 各文件的需求项和场景数量
-    - 下一步提示："运行 `/opsx:design` 创建技术实现方案"
-
----
-
-**护栏规则**
-
-- **必须先读取 proposal.md 的能力分解章节**，根据其中定义的能力列表创建对应的 spec 文件
-- **每个 capability 创建独立的 `specs/<capability>/spec.md`**
-- **必须以 `openspec-templates/spec.md` 为模板基准**，不得使用 `openspec instructions` 返回的简化 template
-- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
-- **需求项格式必须正确**：`#### 需求项：<name>`（4个 #）
-- **场景必须使用 5 个 #**：`##### 场景：<name>`（5个 #）
-- 每个需求项必须有至少一个场景
-- 使用「必须」强制要求，而非「应该」「可以」
-- 文档写入后验证文件确实存在
-- **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Spec 阶段，代码操作请在完成文档后使用 `/opsx:apply` 执行。」
-- **⛔ 单阶段原则：完成 spec.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:design`，**绝对禁止自动执行 design/task 等后续阶段**。每个阶段必须由用户主动触发。
-
-> **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
-> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
-> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
-> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
-> **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.cjs end --event-id=<开头记录的event_id> --command=spec --project=. --change=<变更名称> --capability=<capability-name> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`