kld-sdd 2.4.13 → 2.4.15

package/templates/opsx-commands/propose.md

@@ -1,405 +0,0 @@
----
-name: OPSX: Propose
-description: "创建业务意图文档 - 定义变更的 Why 和上下文总览"
-argument-hint: "[change-name] [上下文文件...]"
----
-
-创建 **proposal.md** - 业务意图与上下文总览文档（聚焦 Why）。
-
-> **🖥️ 跨平台执行规则**
-> - 先确认当前终端工作目录是项目根目录；若不是，先 `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=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`，记录返回的 event_id。
-
-> **⚠️ 阶段边界提示**
->
-> 当前处于 **Propose（规划）阶段**，此阶段：
-> - ✅ **允许**：创建/编辑 proposal.md 文档、读取代码/文档作为上下文分析
-> - ❌ **禁止**：创建/修改任何代码文件、执行代码生成、运行测试
-> - ⛔ **单阶段原则**：完成 proposal.md 后**必须立即停止**，等待用户主动触发下一阶段
->
-> 即使用户提供了代码作为上下文，也只用于理解需求背景，**不执行任何代码操作**。
-> 代码实现将在 `/opsx:apply` 阶段进行。
-> **完成本阶段后，绝对禁止自动继续执行 spec/design/task 等后续阶段。**
-
----
-
-**执行步骤**
-
-0. **【Telemetry 必做】记录阶段开始**
-
-   在终端执行（若命令失败必须中止本阶段，不得跳过）：
-   ```bash
-   node skywalk-sdd/log.cjs start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>
-   ```
-   保存输出 JSON 中的 `event_id`，供阶段结束使用。
-
-1. **【交互引导】若未提供输入，询问用户**
-
-   使用 **AskUserQuestion** 询问用户：
-   > "请描述本次变更的业务需求：
-   > 1. 要解决什么问题？（现状痛点）
-   > 2. 达成什么目标？（期望结果）
-   > 3. 涉及哪些模块/系统？
-   > 4. 有什么约束条件？（时间/技术/资源）"
-
-   从描述中推导 kebab-case 名称，如 "add user authentication" → `add-user-auth`。
-
-   **【澄清机制】若用户描述模糊，主动追问**：
-   - 若目标不明确："请用一句话明确本次变更要达成的具体目标"
-   - 若影响范围不清："请列出本次变更涉及的所有模块/服务"
-   - 若约束未提及："是否有时间限制、技术约束或依赖前提？"
-
-   **重要**：未明确需求前不得继续。
-
-2. **【上下文加载】识别并读取用户提供的文件**
-
-   **自动识别上下文文件**：
-   若用户在命令中指定了文件路径（如 `/opsx:propose atp-calc ./需求.md ./算法逻辑.md`），
-   或在对话中附加/引用了文件，**必须自动读取这些文件**。
-
-   **文件识别规则**：
-   - 以 `.md`、`.txt`、`.java`、`.ts` 等扩展名结尾的参数 → 识别为文件路径
-   - 以 `/` 或 `./` 开头的参数 → 识别为路径
-   - 目录路径 → 递归读取目录下的文件
-
-   **示例**：
-   ```
-   /opsx:propose atp-calc ./需求文档/ATP引擎算法逻辑.md
-   /opsx:propose atp-calc ./需求.md ./erp-algorithm-atp/src/
-   ```
-
-   **上下文记录**：
-   如果用户提供了参考文档，在 proposal.md 中记录：
-   ```markdown
-   ## 参考上下文
-   
-   | 上下文来源 | 文件路径 | 用途说明 |
-   |------------|---------|----------|
-   | 需求文档 | ./ATP引擎算法逻辑.md | 算法需求详细定义 |
-   | 参考代码 | ./erp-algorithm-atp/ | 现有实现参考 |
-   ```
-
-3. **【交互引导】上下文补充提示**
-
-   **若用户未提供任何上下文文件**，AI 分析需求描述后，**主动提示用户补充**：
-
-   **上下文缺失检测**：
-   - 需求描述中提及复杂算法或业务规则，但未提供详细定义
-   - 提及现有系统/代码，但未提供参考
-   - 涉及迁移、重构或算法复制
-
-   **【关键】具体化建议**：
-   AI 必须**引用用户需求中的具体内容**给出建议：
-   ```
-   ❌ 错误（太泛泛）："建议提供算法说明文档"
-   ✅ 正确（具体）："您提到了《ATP计算引擎》，建议提供 ATP 引擎算法逻辑文档"
-   ✅ 正确（具体）："您提到要迁移 erp-algorithm-atp，建议提供该项目的源代码"
-   ```
-
-   **主动提示模板**：
-   > "📌 **建议提供更丰富的上下文信息**：
-   > 
-   > 您的需求中提到：
-   > - **《[XX算法/规则]》** - 建议提供该算法的详细逻辑说明文档
-   > - **《[XX现有项目]》** - 建议提供该项目的源代码作为参考
-   >
-   > 您可以：
-   > - **在命令后追加文件路径**：`/opsx:propose atp-calc ./需求.md ./参考代码/`
-   > - **在对话中上传文件**或粘贴内容
-   > - **告诉我文件位置**，我会自动读取
-   >
-   > 或者选择：
-   > - A. 基于现有信息继续（可能导致缺失）
-   > - B. 已提供全部信息"
-
-4. **创建变更目录（如不存在则新建）**
-   ```bash
-   openspec new change "<name>"
-   ```
-   此命令在 `openspec/changes/<name>/` 创建变更目录和 `.openspec.yaml`。
-
-   **【交互引导】若变更已存在**：
-   - 询问用户："变更 `<name>` 已存在，请选择：
-     - A. 覆盖原有变更（删除重建）
-     - B. 继续编辑现有变更
-     - C. 取消操作"
-   - 根据用户选择执行对应操作
-
-5. **【关键步骤】读取本地模板文件**
-
-   **必须先读取** `openspec-templates/proposal.md` 作为文档结构模板：
-   ```
-   使用 Read 工具读取：openspec-templates/proposal.md
-   ```
-
-   此模板定义了文档的完整结构，包括：
-   - 章节编号和命名
-   - 子章节结构（如 1.1 现状问题、1.2 业务诉求）
-   - 格式要求（checkbox、代码块、表格等）
-   - 质量红线检查清单
-
-   **【重要】不得使用 `openspec instructions` 返回的简化 template，必须以 `openspec-templates/proposal.md` 为准。**
-
-6. **获取项目上下文（可选）**
-   ```bash
-   openspec instructions proposal --change "<name>" --json
-   ```
-   解析返回的 JSON，仅获取：
-   - `context`：项目背景约束（**仅供你参考，不要写入文档**）
-   - `rules`：文档编写规则（**仅供你参考，不要写入文档**）
-   - `outputPath`：文档输出路径
-   - `dependencies`：前置依赖文件路径（如有，先读取）
-
-   **注意**：忽略返回的 `template` 字段，使用步骤 3 读取的本地模板。
-
-7. **读取已有上下文（如有依赖）**
-
-   按 `dependencies` 中的路径读取已完成文件，作为编写参考。
-
-8. **【AI 分析澄清】分析需求完整性**
-
-   在生成文档前，AI 应分析用户提供的信息：
-
-   **完整性检查**：
-   - [ ] 是否有明确的问题描述？
-   - [ ] 是否有可衡量的目标？
-   - [ ] 是否涉及具体模块？
-   - [ ] 是否有时间/资源约束？
-
-   **【发现缺失时主动询问】**：
-   > "我发现以下信息还不够清晰，请补充：
-   > - [具体问题]
-   > 补充后我将重新生成文档。"
-
-9. **【交互引导】文档拆分模式选择**
-
-   **❗ 必须主动询问用户，不得默认选择**
-
-   分析需求中的能力域数量后，使用 **AskUserQuestion** 询问用户：
-   > "📋 **检测到需求包含以下能力域：**
-   > - [能力域列表]
-   >
-   > 🤔 **请选择文档拆分模式：**
-   >
-   > **A) 完整模式** - 每个能力域独立文档
-   >    - 目录结构：`specs/<capability>/spec.md`, `specs/<capability>/design.md`, `specs/<capability>/tasks.md`
-   >    - 适合：大需求、多人协作、需要精细管控
-   >
-   > **B) 简化模式** - 单一文档
-   >    - 目录结构：`spec.md`, `design.md`, `tasks.md`（合并所有能力域）
-   >    - 适合：小需求、单人快速迭代
-   >
-   > **C) 自动判断** - 根据能力域数量自动选择
-   >    - 单个能力域 → 简化模式
-   >    - 多个能力域 → 完整模式"
-
-   根据用户选择：
-   - 选择 A：设置 `mode: full`
-   - 选择 B：设置 `mode: simple`
-   - 选择 C：根据能力域数量自动判断并设置
-
-   **将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
-
-10. **【交互引导】测试策略选择**
-
-   **❗ 必须主动询问用户，不得默认选择**
-
-   使用 **AskUserQuestion** 询问用户：
-   > "🧪 **请选择测试策略：**
-   >
-   > **A) 测试驱动 (TDD)** - 测试先行
-   >    - 先生成测试任务，实现任务依赖测试任务
-   >    - DAG: 测试骨架 → 实现代码 → 测试验证
-   >    - 适合：核心业务逻辑、质量要求高
-   >
-   > **B) 实现优先** - 代码先行
-   >    - 先生成实现任务，测试作为验证步骤
-   >    - DAG: 实现代码 → 测试验证
-   >    - 适合：UI 层、配置类、快速原型
-   >
-   > **C) 无测试** - 仅实现
-   >    - 不生成测试任务，仅编译检查
-   >    - 适合：简单配置、文档更新"
-
-   根据用户选择：
-   - 选择 A：设置 `test-strategy: tdd`
-   - 选择 B：设置 `test-strategy: impl-first`
-   - 选择 C：设置 `test-strategy: none`
-
-   **将用户选择记录到 proposal.md 的 YAML frontmatter 中。**
-
-11. **创建 proposal.md**
-
-   **以 `openspec-templates/proposal.md` 的结构为骨架**，填充内容到 `outputPath`：
-
-   **【质量红线】生成文档必须严格遵循模板结构：**
-
-   ```markdown
-   # proposal.md - 业务意图与上下文总览
-
-   > **定位**：变更的业务意图（Why）与上下文总览
-   >
-   > **可选性**：【可跳过，直入spec】若跳过，必须将"影响范围"在 specs 中补齐
-   
-   ---
-   
-   ## 1. 需求背景
-   
-   ### 1.1 现状问题
-   - [具体痛点，禁止泛化描述]
-   
-   ### 1.2 业务诉求
-   - [为什么要做这件事]
-   
-   ---
-   
-   ## 2. 业务目标
-   
-   | 目标维度 | 具体描述 | 验收标准 |
-   |---------|---------|----------|
-   | 功能目标 | | |
-   | 性能目标 | | |
-   | 体验目标 | | |
-   
-   ---
-   
-   ## 3. 能力分解
-   
-   <!-- 【关键章节】此处定义的 capability 决定后续 specs/ 的文件结构 -->
-   
-   ### 3.1 新增能力
-   <!-- 每个能力会创建 specs/<name>/spec.md，使用 kebab-case 命名 -->
-   - `<capability-name>`: <能力简要描述>
-   
-   ### 3.2 修改能力
-   <!-- 仅当已有能力的需求级别变更时填写，检查 openspec/specs/ 现有规格 -->
-   - `<existing-name>`: <修改什么需求>
-   
-   ---
-   
-   ## 4. 影响范围
-
-   ### 4.1 涉及模块
-   - [ ] 模块A：影响描述
-   - [ ] 模块B：影响描述
-
-   ### 4.2 依赖关系
-   ```
-   [上游依赖] --> [本变更] --> [下游影响]
-   ```
-
-   ### 4.3 数据影响
-   - 数据库表变更：
-   - 接口变更：
-   - 配置变更：
-
-   ---
-
-   ## 5. 约束与假设
-
-   ### 5.1 业务约束
-   -
-
-   ### 5.2 技术约束
-   -
-
-   ### 5.3 前置依赖
-   - [ ] 依赖项1：状态
-   - [ ] 依赖项2：状态
-
-   ---
-
-   ## 6. 风险评估
-
-   | 风险项 | 概率 | 影响 | 应对策略 |
-   |-------|------|------|---------|
-   | | | | |
-
-   ---
-
-   ## 7. 相关文档
-
-   - 需求文档：
-   - 原型链接：
-   - 参考文档：
-
-   ---
-
-   > **质量红线检查清单**
-   > - [ ] 逻辑链路已闭环
-   > - [ ] 受影响模块已明确
-   > - [ ] 依赖关系已梳理
-   > - [ ] 若跳过本文档，影响范围已在 specs 中补齐
-   > - [ ] 能力分解章节已明确列出所有能力
-   ```
-
-12. **质量红线自检**
-
-   写入文档前，逐项确认：
-   - [ ] 文档结构完全符合 `openspec-templates/proposal.md` 模板
-   - [ ] 章节编号和命名正确（如 `## 1. 需求背景` 而非 `## Why`）
-   - [ ] 子章节结构正确（如 `### 1.1 现状问题`、`### 1.2 业务诉求`）
-   - [ ] 涉及模块使用 checkbox 格式（`- [ ] 模块A`）
-   - [ ] 依赖关系使用代码块图示
-   - [ ] 前置依赖使用 checkbox 格式
-   - [ ] 文档末尾包含质量红线检查清单
-
-   **【自检发现问题时的处理】**：
-   - 标记未通过的项
-   - 分析问题原因（信息不足/理解偏差/描述模糊）
-   - 向用户说明问题并请求澄清：
-     > "质量自检发现 [问题描述]，请补充以下信息："
-   - 获取补充信息后，重新生成对应章节
-
-   **如有任意一项未满足，重新生成对应章节，直至全部通过。**
-
-13. **【交互引导】确认文档并输出结果**
-
-   生成文档后，向用户展示文档概要：
-   > "已生成 proposal.md 草案，概要如下：
-   > - 变更名称：[name]
-   > - 核心目标：[一句话总结]
-   > - 影响模块：[模块列表]
-   >
-   > 请确认：
-   > - A. 确认无误，继续创建 specs
-   > - B. 需要修改 [具体章节]
-   > - C. 补充更多信息"
-
-   根据用户反馈：
-   - 选择 A：保存文档，提示下一步
-   - 选择 B/C：根据反馈修改文档
-
-   **【关键提示】**：向用户确认能力列表：
-   > "根据 proposal，将创建以下 specs 文件：
-   > - specs/<capability-1>/spec.md
-   > - specs/<capability-2>/spec.md
-   > ...
-   > 请确认能力列表是否完整？"
-
-   最终输出：
-   - 文档路径（来自 `outputPath`）
-   - 内容摘要（背景 + 目标 + 影响模块）
-   - 下一步提示："运行 `/opsx:spec` 创建技术契约文档 (specs/<capability>/spec.md)"
-
----
-
-**护栏规则**
-
-- **必须以 `openspec-templates/proposal.md` 为模板基准**，不得使用 `openspec instructions` 返回的简化 template
-- `context` 和 `rules` 是你的约束条件，**不得出现在生成的文档中**
-- proposal.md 聚焦【Why】，不要写技术实现细节（留给 design.md）
-- 不要写 API 细节（留给 specs）
-- **能力分解章节是关键**：每个列出的 capability 会创建对应的 `specs/<name>/spec.md`
-- 若跳过此文档，后续 specs 必须补齐影响范围
-- 文档写入后验证文件确实存在于 `outputPath`
-- **⛔ 阶段边界**：本阶段禁止执行任何代码创建/修改操作。若用户要求处理代码，回复：「当前处于 Propose 阶段，代码操作请在完成文档后使用 `/opsx:apply` 执行。」
-- **⛔ 单阶段原则：完成 proposal.md 后必须立即停止**。仅提示用户下一步可运行 `/opsx:spec`，**绝对禁止自动执行 spec/design/task 等后续阶段**。每个阶段必须由用户主动触发。
-
-> **📊 Telemetry（必做，不得跳过）**
-> 在终端执行（必须成功）：`node skywalk-sdd/log.cjs end --event-id=<开头记录的event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success/failure --summary="一句话摘要"`