kld-sdd 2.4.7

package/templates/opsx-commands/archive.md

@@ -0,0 +1,85 @@
+---
+name: OPSX: Archive
+description: "归档变更 - 将已完成或取消的变更归档，清理活动状态"
+argument-hint: "[change-name]"
+---
+
+归档变更 - 将已完成实施或决定取消的变更移出活动状态，保留文档供后续参考。
+
+> **📊 Telemetry（必做，不得跳过）**
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=archive --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+
+---
+
+**输入**: `/opsx:archive` 后跟变更名称（kebab-case）
+
+**执行步骤**
+
+0. **【Telemetry 必做】记录阶段开始**
+
+   在终端执行（若命令失败必须中止本阶段，不得跳过）：
+   ```bash
+   node skywalk-sdd/log.js start --command=archive --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   ```
+   保存输出 JSON 中的 `event_id`，供阶段结束使用。
+
+1. **【交互引导】确认变更名称**
+
+   若未提供，列出当前所有变更供用户选择：
+   ```bash
+   openspec list
+   ```
+   展示每个变更的状态（PENDING / IMPLEMENTING / ARCHIVED），引导用户选择。
+
+2. **获取变更状态**
+
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   检查变更当前状态：
+   - `PENDING`：尚未申请实施（提醒用户是否跳过实施直接归档）
+   - `IMPLEMENTING`：正在实施中（提醒用户确认是否全部任务已完成）
+   - `ARCHIVED`：已归档（提示用户该变更已归档，无需操作）
+
+   **【状态异常处理】**：
+   - 若变更为 `PENDING`（从未实施）：
+     > "变更 `<name>` 尚未申请实施，确定要直接归档？
+     > - A. 确认归档（变更已取消/搁置）
+     > - B. 先申请实施（运行 `/opsx:apply <name>`）"
+   - 若变更为 `IMPLEMENTING`（实施中）：
+     > "变更 `<name>` 正在实施中，请确认所有 tasks.md 任务已完成：
+     > - A. 确认全部完成，归档变更
+     > - B. 取消（继续实施中状态）"
+
+3. **【交互引导】确认归档原因**
+
+   > "请确认归档原因（将记录在归档日志中）：
+   > - A. 变更已完成实施 ✅（所有任务已完成并验收）
+   > - B. 变更已取消 ❌（业务原因取消）
+   > - C. 变更已搁置 ⏸（暂缓实施，保留文档）
+   > - D. 其他（请输入原因）"
+
+4. **执行归档**
+
+   ```bash
+   openspec archive "<name>"
+   ```
+
+5. **输出结果**
+
+   > "✅ 变更 `<name>` 已归档！
+   > - 归档原因：[用户选择的原因]
+   > - 文档路径：openspec/changes/<name>/（已保留，可随时查阅）
+   > - 如需查看所有归档变更，运行 `/opsx:explore`"
+
+---
+
+**护栏规则**
+
+- 归档操作执行前必须用户明确确认，不可自动执行
+- 归档后文档仍保留在 `openspec/changes/<name>/` 目录，不会删除
+- 若变更状态已是 `ARCHIVED`，提示用户直接跳过，无需重复操作
+
+> **📊 Telemetry（必做，不得跳过）**
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="归档结果摘要" --project=<项目根目录绝对路径>`

package/templates/opsx-commands/check.md

@@ -0,0 +1,344 @@
+---
+name: OPSX: Check
+description: "质量检查 - 验证文档完整性、一致性、算法正确性及可执行性"
+argument-hint: "[change-name] [上下文文件...]"
+---
+
+执行 **质量门禁检查** - 验证 proposal → specs → design → tasks 文档链的完整性、一致性、算法正确性和可执行性。
+
+> **📊 Telemetry（必做，不得跳过）**
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js start --command=check --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>`，记录返回的 event_id。
+
+> **⚠️ 阶段边界提示**
+>
+> 当前处于 **Check（检查）阶段**，此阶段：
+> - ✅ **允许**：读取并检查文档、读取代码作为验证参考
+> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
+>
+> 即使检查发现代码相关问题，也只记录在检查报告中，**不自动修复代码**。
+> 代码修复将在 `/opsx:apply` 阶段进行。
+
+---
+
+**执行步骤**
+
+0. **【Telemetry 必做】记录阶段开始**
+
+   在终端执行（若命令失败必须中止本阶段，不得跳过）：
+   ```bash
+   node skywalk-sdd/log.js start --command=check --project=<项目根目录绝对路径> --change=<变更名称> --agent=<Agent类型>
+   ```
+   保存输出 JSON 中的 `event_id`，供阶段结束使用。
+
+1. **确认变更名称**
+
+   若未提供，列出当前所有变更供用户选择：
+   ```bash
+   openspec list
+   ```
+   
+   若变更不存在，提示用户先运行 `/opsx:propose <name>` 创建变更。
+
+2. **读取完整文档链**
+
+   按顺序读取以下文档（如存在）：
+   - `proposal.md`（或 propose.md，兼容旧格式）（业务意图）
+   - `specs/<capability>/spec.md`（技术契约）
+   - `design.md`（实现方案）
+   - `tasks.md`（或 task.md，兼容旧格式）（任务拆解）
+
+3. **【上下文加载】识别并读取用户提供的文件**
+
+   **自动识别上下文文件**：
+   若用户在命令中指定了文件路径（如 `/opsx:check atp-calc ./需求.md`），
+   或在对话中附加/引用了文件，**必须自动读取这些文件**。
+
+   **上下文类型与检查维度**：
+   | 上下文类型 | 检查用途 | 对应检查维度 |
+   |------------|---------|----------|
+   | 需求文档 (.md) | 需求追溯检查基线 | 4.6 需求追溯检查 |
+   | 算法说明 (.md) | 伪代码正确性参考 | 4.4 算法正确性检查 |
+   | 参考实现 (.java/.ts) | 一致性检查参考 | 4.2 一致性检查 |
+
+   **示例**：
+   ```
+   /opsx:check atp-calc ./ATP引擎算法逻辑.md
+   /opsx:check atp-calc ./需求文档.md ./erp-algorithm-atp/
+   ```
+
+4. **【交互引导】上下文补充提示**
+
+   **若用户未提供任何上下文文件**，AI 分析文档内容后，**主动提示用户补充**：
+
+   **【关键】具体化建议**：
+   AI 必须**引用文档中的具体内容**给出建议：
+   ```
+   ❌ 错误："建议提供需求文档"
+   ✅ 正确："design.md 包含《正差反差计算》伪代码，建议提供该算法的需求文档进行一致性检查"
+   ```
+
+   **主动提示模板**：
+   > "📌 **建议提供上下文信息以进行更深度的检查**：
+   > 
+   > 文档中包含：
+   > - **《[XX算法]》** - 建议提供算法说明文档进行算法正确性检查
+   > - **原始需求** - 建议提供需求文档进行需求追溯检查
+   >
+   > 您可以：
+   > - **在命令后追加文件路径**：`/opsx:check atp-calc ./需求.md`
+   > - **在对话中上传文件**或粘贴内容
+   >
+   > 或者选择：
+   > - A. 仅检查内部一致性（跳过需要外部上下文的检查项）
+   > - B. 已提供全部信息"
+
+5. **【交互引导】询问用户检查重点**
+
+   使用 **AskUserQuestion** 询问用户：
+   > "请选择本次检查的重点（可多选）：
+   > - [ ] 完整性检查：文档链是否完整
+   > - [ ] 一致性检查：文档间是否存在矛盾
+   > - [ ] 可执行性检查：task.md 任务是否可落地
+   > - [ ] **算法正确性检查**：design.md 伪代码是否自洽
+   > - [ ] **场景完整性检查**：spec.md Scenario 是否完整
+   > - [ ] **需求追溯检查**：需求→代码链路是否完整（需要上下文）
+   > - [ ] 全量检查：以上全部"
+   
+   根据用户选择执行对应检查项。
+
+6. **执行质量检查**
+
+   ### 4.1 完整性检查
+   
+   检查项清单：
+   - [ ] proposal.md 存在且非空
+   - [ ] specs 目录存在且非空
+   - [ ] design.md 存在且非空
+   - [ ] tasks.md 存在且非空
+   
+   **缺失文档处理**：
+   - 若发现缺失文档，列出缺失清单
+   - 询问用户："是否立即创建缺失文档？"
+   - 用户确认后，引导执行对应命令创建
+
+   ### 4.2 一致性检查
+   
+   **文档间引用一致性**：
+   - [ ] proposal.md 的业务目标在 specs 中有对应技术实现
+   - [ ] specs 的需求定义在 design.md 中有对应模块设计
+   - [ ] design.md 的模块在 tasks.md 中有对应任务
+   - [ ] tasks.md 的任务数量与 design.md 模块数量匹配
+   
+   **数据一致性**：
+   - [ ] 接口参数在 specs/design/tasks 中定义一致
+   - [ ] 错误码定义在各文档中一致
+   - [ ] 模块名称在各文档中一致
+   
+   **【发现不一致时的澄清机制】**：
+   - 列出所有不一致项
+   - 对每个不一致项，分析影响范围
+   - 询问用户："请选择修复策略：
+     - A. 以 proposal.md 为准，同步修改下游文档
+     > - B. 以 specs 为准，同步修改上下游文档
+     - C. 手动指定正确版本"
+   - 根据用户选择，生成修复建议或引导用户澄清
+
+   ### 4.3 可执行性检查
+   
+   **任务可执行性**：
+   - [ ] 每个任务有明确的输入/输出定义
+   - [ ] 每个任务有具体的实现步骤
+   - [ ] 每个任务有明确的验收标准
+   - [ ] 任务依赖关系无循环依赖
+   - [ ] 任务颗粒度符合"5分钟可完成"标准
+   
+   **【不可执行任务的处理】**：
+   - 标记不可执行任务
+   - 分析原因：颗粒度过大？依赖不明确？验收标准模糊？
+   - 询问用户："是否自动拆分/优化这些任务？"
+   - 用户确认后，生成优化建议
+
+   ### 4.4 算法正确性检查（新增）
+   
+   **❗ 此检查针对 design.md 中的伪代码**
+   
+   #### 4.4.1 伪代码自洽性检查
+   
+   | 检查项 | 要求 | 未通过处理 |
+   |---------|------|------------|
+   | 变量声明 | 伪代码中的变量在使用前已赋值 | ❌ 错误 |
+   | 循环边界 | for 循环的起始/结束条件明确 | ❌ 错误 |
+   | 分支覆盖 | switch 有 default，if 有 else | ⚠️ 警告 |
+   | 数据来源 | 关键变量有来源说明 | ⚠️ 警告 |
+   
+   #### 4.4.2 算法一致性检查（需要 --context 算法文档）
+   
+   若提供了算法参考文档，检查：
+   - [ ] design.md 伪代码与参考算法逻辑一致
+   - [ ] 核心计算逻辑（循环、分支、累加顺序）一致
+   - [ ] 边界条件处理一致
+   
+   **【模糊伪代码检测】**：
+   - "累加计算数量（需求取负数）" → ❌ 模糊，需要明确 calcQuantity 本身是否已为负数
+   - "if (direction == -1) subtract" → ⚠️ 警告，需要说明 calcQuantity 的符号
+
+   ### 4.5 场景完整性检查（新增）
+   
+   **❗ 此检查针对 spec.md 中的 Scenario**
+   
+   #### 4.5.1 需求项-场景配比检查
+   
+   | 检查项 | 要求 | 未通过处理 |
+   |---------|------|------------|
+   | 场景数量 | 每个需求项至少 1 个场景 | ❌ 错误 |
+   | 场景结构 | 每个场景必须有 当/预期 | ❌ 错误 |
+   | 预期结果 | 每个场景必须有可验证的预期 | ⚠️ 警告 |
+   | 边界条件 | 关键场景应包含边界条件 | ⚠️ 警告 |
+   
+   #### 4.5.2 场景缺失检测
+   
+   若发现以下情况，标记为警告：
+   - 场景只有需求项声明但无详细描述
+   - 场景描述使用 “等”、“之类” 等模糊词汇
+   - 场景的预期结果无法量化验证
+
+   ### 4.6 需求追溯检查（新增）
+   
+   **❗ 此检查需要 --context 提供需求文档基线**
+   
+   若未提供 --context，跳过此检查并警告：
+   > "⚠️ 需求追溯检查已跳过（未提供 --context 需求文档）"
+   
+   #### 4.6.1 需求追溯矩阵检查
+   
+   从需求文档中提取需求项，检查：
+   - [ ] 每个需求项在 spec.md 中有对应需求项
+   - [ ] 每个 spec.md 需求项在 design.md 中有对应实现
+   - [ ] 每个 design.md 实现在 tasks.md 中有对应任务
+   
+   **【追溯矩阵格式】**：
+   ```markdown
+   | 需求ID | 需求描述 | 规格需求项 | 设计算法 | 测试场景 | 追溯状态 |
+   |--------|---------|-----------------|-------------|---------|----------|
+   | REQ-001 | 离散 ATP 计算 | RLT-处理 | 5.2 | TASK-CA-05-TEST | ✅ |
+   | REQ-002 | 存储地点 ATP | 存储地点级别 ATP | 5.5 | 未覆盖 | ❌ 缺失 |
+   ```
+   
+   #### 4.6.2 缺失需求检测
+   
+   若发现需求文档中存在但未在 SDD 文档链中覆盖的需求：
+   > "⚠️ **需求追溯检查发现以下缺失**：
+   > - '存储地点级别 ATP' 在需求文档中存在，但测试场景未覆盖
+   > - '工厂日历计算' 在需求文档中存在，但 spec.md 完全缺失
+   >
+   > 请选择：
+   > - A. 返回 spec 阶段补充缺失场景
+   > - B. 标记为 '已知风险' 继续
+   > - C. 确认缺失需求不在本次范围内"
+
+7. **【交互引导】补充上下文信息**
+
+   若检查过程中发现以下情况，主动询问用户：
+   
+   **信息缺失时**：
+   > "propose.md 中 [具体章节] 缺少 [具体信息]，请补充："
+   
+   **逻辑矛盾时**：
+   > "检查中发现 [文档A] 和 [文档B] 在 [具体点] 存在矛盾：
+   > - 文档A描述：...
+   > - 文档B描述：...
+   > 请澄清正确意图："
+   
+   **模糊描述时**：
+   > "检查中发现 [具体章节] 存在模糊描述 '[原文]'，请明确："
+
+8. **生成检查报告**
+
+   生成 `check-report.md` 到变更目录：
+
+   ```markdown
+   # 质量检查报告
+
+   ## 检查概览
+   - 变更名称：[name]
+   - 检查时间：[timestamp]
+   - 检查范围：[完整性/一致性/可执行性/全量]
+   - 总体状态：[通过/需修复/严重问题]
+
+   ## 文档完整性
+   | 文档 | 状态 | 说明 |
+   |-----|------|-----|
+   | proposal.md | ✅/❌ | 存在/缺失 |
+   | specs/ | ✅/❌ | 存在/缺失 |
+   | design.md | ✅/❌ | 存在/缺失 |
+   | tasks.md | ✅/❌ | 存在/缺失 |
+
+   ## 一致性检查结果
+   ### 通过项
+   - [x] [检查项描述]
+   
+   ### 问题项
+   - [ ] [问题描述]
+     - 影响：[影响范围]
+     - 建议：[修复建议]
+     - 优先级：[高/中/低]
+
+   ## 可执行性评估
+   ### 任务统计
+   - 总任务数：X
+   - 可执行任务：X
+   - 需优化任务：X
+   
+   ### 问题任务清单
+   | 任务 | 问题 | 优化建议 |
+   |-----|------|---------|
+   | | | |
+
+   ## 修复建议
+   1. [优先级：高] [具体建议]
+   2. [优先级：中] [具体建议]
+
+   ## 下一步行动
+   - [ ] 修复标记为"高优先级"的问题
+   - [ ] 运行 `/opsx:check <name>` 重新验证
+   - [ ] 通过后运行 `/opsx:apply` 开始实现
+   ```
+
+9. **【AI 分析澄清】智能问题诊断**
+
+   若发现严重问题，AI 应主动分析并引导澄清：
+   
+   **严重问题类型**：
+   - 文档链断裂（缺少关键中间文档）
+   - 核心逻辑矛盾（业务目标与技术实现冲突）
+   - 无法落地的任务（缺少必要依赖或资源）
+   
+   **澄清流程**：
+   1. AI 分析问题根因
+   2. 提供 2-3 个可能的解决方案
+   3. 询问用户："请确认采用哪种方案，或提供更多信息："
+   4. 根据用户反馈，更新文档或调整检查标准
+
+10. **显示检查结果**
+
+   完成后显示：
+   - 检查报告路径
+   - 问题统计（通过 X 项，警告 Y 项，错误 Z 项）
+   - 关键问题摘要（如有）
+   - 下一步建议：
+     - 检查通过："✅ 质量检查通过！可以运行 `/opsx:apply` 开始实现"
+     - 有问题："⚠️  发现 X 个问题，请查看检查报告并修复后重新检查"
+
+---
+
+**护栏规则**
+
+- 检查是**辅助手段**，最终决策权在用户
+- 发现问题时**必须提供具体位置和修复建议**，不要只报告"有问题"
+- **区分严重程度**：错误（必须修复）vs 警告（建议优化）vs 建议（可选改进）
+- 用户选择"忽略"某问题时，记录原因到检查报告
+- 检查报告本身也是文档，需保持清晰、可追踪
+- **⛔ 阶段边界**：本阶段仅执行检查，禁止自动修复代码。若发现代码问题，记录到检查报告并提示用户：「代码修复请使用 `/opsx:apply` 执行。」
+
+> **📊 Telemetry（必做，不得跳过）**
+> 在终端执行（必须成功）：`node skywalk-sdd/log.js end --event-id=<开头记录的event_id> --result=success/failure --summary="检查结果摘要" --project=<项目根目录绝对路径>`