sdd-flow-kit 1.0.11 → 1.0.14

package/README.md

@@ -48,7 +48,15 @@
 
 #### 使用说明
 
-1.  `install`（等价 `setup`）：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境，同时写入项目级 Skill
+##### 需求澄清：用户无需背提示词
+
+`install` 会写入 `.cursor/rules/sdd-flow-kit-gates.mdc` 与触发 Skill。  
+澄清阶段你**直接粘贴确认点**（编号列表即可），AI 应自动进入文档模式，只改 `openspec/PRD/**`，不改 `src/`。  
+写业务代码仅在 `/opsx-propose` 完成且你同意 `/opsx-apply` 之后。
+
+阶段口语（可选，非必须）：`继续` / `做提案` → propose；`开始 apply` → 实现。
+
+1.  `install`（等价 `setup`）：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境，同时写入项目级 Skill 与 Cursor 门禁规则
 2.  安装完成后，本工具主要负责“流程环境与模板”落地；业务需求由你在目标 AI 工具中自然语言驱动
 3.  `start`/`run`/`invoke` 属于进阶能力（脚本化或一键编排时使用）
 4.  `doctor`：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果

package/dist/steps/setupProject.js

@@ -183,6 +183,11 @@ async function installAgentSkill(projectRoot) {
         await (0, fs_1.writeTextFileEnsuredDir)(target, content);
     }
 }
+async function installSddCursorRule(projectRoot) {
+    const rulePath = node_path_1.default.join(projectRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc");
+    const template = await (0, templates_1.loadTemplateText)("rules/sdd-no-implement-until-apply.mdc.template");
+    await (0, fs_1.writeTextFileEnsuredDir)(rulePath, template);
+}
 function renderVars(template, vars) {
     let out = template;
     for (const [k, v] of Object.entries(vars)) {
@@ -304,9 +309,11 @@ async function setupProject(options) {
         const { dir } = docSkillDirName(selectedKind);
         plannedActions.push(`would install docs skill: ${node_path_1.default.join(options.projectRoot, "docs", dir)}`);
         plannedActions.push(`would install opsx config: ${node_path_1.default.join(options.projectRoot, ".opsx", "config.json")}`);
+        plannedActions.push(`would install cursor rule: ${node_path_1.default.join(options.projectRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc")}`);
     }
     else {
         await installAgentSkill(options.projectRoot);
+        await installSddCursorRule(options.projectRoot);
         skillInstalled = true;
         await installDocsSkill(options.projectRoot, selectedKind);
         docsSkillInstalled = true;

package/dist/steps/startFlow.js

@@ -70,7 +70,9 @@ async function startFlowScaffold(options) {
         version: options.version,
         runId,
         outputRoot,
-        status: "step1_prd_prompt_generated",
+        status: "awaiting_user_confirmation",
+        docModeOnly: true,
+        phase: "A_or_B",
         createdAtISO: new Date().toISOString(),
     }, null, 2));
     // runDir 自述
@@ -90,6 +92,7 @@ async function startFlowScaffold(options) {
         "## Step 3：人工核验（暂停点）",
         "用户补充待确认点并确认闭环后，才进入 Step 4。",
         "门禁：未闭环时禁止生成 01/02/04，禁止 /opsx-propose。",
+        "**重要**：用户粘贴确认点时，AI 仅更新 `openspec/PRD` 文档，**禁止**修改 `src/` 等业务代码。",
         "",
         "## Step 4：生成 01 / 02 / 闭环03 / 04",
         "用户确认后产出：",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.0.11",
+  "version": "1.0.14",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

package/src/templates/artifacts/03-/345/276/205/347/241/256/350/256/244/351/227/256/351/242/230/346/270/205/345/215/225.template.md

@@ -1,6 +1,10 @@
 # 03-待确认问题清单
 
-| 问题类型 (断点/起点缺失/推测缺口) | 问题描述 | 代码位置 (如有) | 建议/待确认项 |
-|---|---|---|---|
-| （断点/起点缺失/推测缺口） | （描述矛盾点） | （引用文件/模块） | （需要用户确认/提供信息） |
+> **门禁**：本文件为「未闭合」时，AI **只能**改本文件，禁止生成 01/02/04，**禁止**改 `src/` 等业务代码。  
+> **给用户**：澄清完成后，在对话里**直接粘贴确认点**即可，无需加任何前缀口令。
 
+**矛盾点池状态**：`未闭合` | `已闭合`（二选一，由 AI 维护）
+
+| 问题类型 | 问题描述 | 代码位置 (如有) | 建议/待确认项 | 用户确认结论 |
+|---|---|---|---|---|
+| （断点/起点缺失/推测缺口） | （描述矛盾点） | （引用文件/模块，只读） | （需要用户确认） | （用户回复后填写） |

package/src/templates/artifacts/06-agent-skill.template.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-flow-kit-trigger
-description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类似表达时，必须启动 sdd-flow-kit 分阶段流程；其它对话保持原本 AI 行为。
+description: 开发某版本需求、SDD 流程、待确认问题澄清、用户回复确认点/矛盾点结论时触发。澄清与确认阶段仅改 openspec/PRD 文档，禁止写 src 等业务代码；仅 /opsx-apply 后可实现。
 ---
 
 # SDD Flow Trigger Skill
@@ -13,6 +13,23 @@ description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类
   - `开发XXX-V1.2.3版本`（无空格连写）
   - `开发 XXX PRD`
 - 或明确要求“按 SDD 流程”推进某版本需求
+- **用户回复待确认点 / 粘贴确认结论 / 说「按上面确认继续」**（即使未再说「开发 XX 需求」也视为 SDD 流程续跑）
+
+## ⚠️ 最高优先级：文档模式 vs 实现模式
+
+| 模式 | 何时 | 允许改动的路径 | 禁止 |
+|------|------|----------------|------|
+| **文档模式** | 阶段 A/B/C，含「用户发来确认点」 | 仅 `openspec/PRD/**`（及阶段 C 的 `openspec/changes/**`） | 任何 `src/`、`pages/`、`components/` 等业务代码 |
+| **实现模式** | 仅阶段 D，且用户同意 `/opsx-apply` | 按 openspec change 与 pipeline 要求 | 跳过 propose |
+
+**常见错误**：用户粘贴确认点后，你一边更新 `03` 一边改 `.tsx` —— **绝对禁止**。确认回复 = 只做文档，同一回合不得 touch 业务代码。
+
+### 用户侧：零口令（不要要求加前缀）
+- 用户**直接粘贴**确认点、编号结论、「按 1/2/3 继续」即可；**禁止**要求用户输入【仅文档模式】等固定话术。
+- 你须在收到后**自动**判定为阶段 B 的文档模式；先读 `openspec/PRD/<runId>/.session-state.json`（`docModeOnly: true` 时严禁写业务代码）与 `03-待确认问题清单.md`。
+- 阶段切换口语即可，无需背提示词：
+  - 提案：`继续` / `做提案` / `propose`（执行 `/opsx-propose`）
+  - 实现：`开始 apply` / `执行 apply`（且 change 已 apply-ready）
 
 ## 触发后执行规则（分阶段，禁止跳步）
 
@@ -39,6 +56,13 @@ description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类
 ### 阶段 B — 用户确认后（仅文档 01/02/03/04）
 **触发条件**：用户已回复待确认点，或明确表示“矛盾点池已闭合 / 按确认点继续”。
 
+**「用户发来确认点」专用指令（本回合严格执行）**
+1. 先读 `openspec/PRD/<runId>/03-待确认问题清单.md`，把用户消息逐条写入「用户确认结论」列。
+2. 将状态改为 **矛盾点池状态：已闭合**。
+3. 再生成 `01`、`02`、`04`（路径均在 `openspec/PRD/<runId>/`）。
+4. **本回合禁止**：`StrReplace`/`Write` 任何业务源码；禁止「顺手实现一版」。
+5. 结束语简短即可（例：「已更新 01/02/03/04，未改业务代码。有 UI 参考请发路径，或回复继续做提案。」）——**不要**要求用户背固定口令。
+
 **本阶段只允许产出：**
 1. 更新 `03-待确认问题清单.md`（标注 **矛盾点池状态：已闭合**，写入用户确认结论）
 2. 生成最终版 `01-需求分析报告.md`
@@ -46,10 +70,11 @@ description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类
 4. 生成 `04-技术文档草稿.md`
 
 **本阶段禁止：**
+- 修改 `src/`、`pages/`、`components/`、`api/` 等实现代码（`02-改动点清单` 只是**计划**，不是实施许可）
 - 执行 `/opsx-propose` 或 `/opsx-apply`
 - 生成 openspec change 目录或宣称“开发完成”
 
-完成后告知用户：“01/02/03/04 已就绪，是否提供 UI 参考图路径？确认后我将执行 /opsx-propose。”
+完成后告知用户：“01/02/03/04 已就绪。发 UI 参考路径，或回复「继续」我将执行 /opsx-propose。”
 
 ---
 
@@ -83,7 +108,9 @@ description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类
 ---
 
 ## 严禁（全局）
+- 澄清/确认阶段写业务代码（最常见违规）
 - 未闭合时一次性生成 `01~05` 或直接进入提案/实现
+- 把 `02-改动点清单.md` 当作可以立刻改文件的指令
 - 跳过用户确认点
 - 在错误仓库执行 OPSX（如 fallback 到其它项目的 poquan-web 路径）
 

package/src/templates/prompts/02-sdd-loop-prompt.md

@@ -2,6 +2,12 @@
 你现在的角色是【前端架构分析专家】与【资深业务分析师】。
 你正在执行 **SDD (Software Design Description) 模式**。这是一个基于“循环探索”的工程环节，目的是在编码前，基于 PRD 和现有知识库，产出完备的需求分析与改动清单。
 
+### ⛔ 实现禁令（全文最高优先级）
+- **文档模式**：只允许创建/修改 `openspec/PRD/<runId>/` 下的 `.md` 文件。
+- **禁止**在本环节修改任何业务源码（`src/`、`pages/`、`components/`、`api/` 等），即使用户发来「确认点」也不行。
+- `02-改动点清单.md` 是**改动计划表**，不是实施指令；写代码只能发生在 `/opsx-apply` 之后。
+- 用户回复确认结论时：**仅**更新 `03` → 生成 `01/02`（及后续 `04`），并在回复中声明「未写业务代码」。
+
 ### 🔄 循环工作流 (Loop Protocol)
 请严格遵守以下循环逻辑，直到满足“循环结束条件”：
 1.  **输入**：接收 PRD 文档 和 `openspec/` 目录下的现有知识库。
@@ -65,22 +71,23 @@
 > **触发条件**：当你发现 PRD 与现有代码库不一致，或代码逻辑存在盲区时。
 
 **任务**：
-1.  **不要强行编写解决方案。**
+1.  **不要强行编写解决方案，不要改任何 `.tsx/.ts/.vue` 文件。**
 2.  列出所有 **断点**、**起点缺失** 和 **推测缺口**。
 3.  输出 `03-待确认问题清单.md`，并暂停生成最终报告，等待人工输入。
 4.  明确标注：`矛盾点池状态：未闭合`。
+5.  结束语（告诉用户可直接回复，无需口令）：`请直接在对话里粘贴你的确认点（编号列表即可），我会只更新 openspec/PRD 文档，不会改业务代码。`
 
 ---
 
 #### 路径 B：交付模式 (矛盾点池已闭合)
 > **触发条件**：用户已回复待确认点，或明确表示矛盾点池已闭合（不得在未获用户确认时自行进入）。
 
-**任务（本路径仅文档，不含 openspec）**：
+**任务（本路径仅文档，不含 openspec，不含写代码）**：
 1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
-2.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`。
+2.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
 3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
-4.  **禁止** 在本路径执行 `/opsx-propose` 或 `/opsx-apply`。
-5.  输出时附带一句：`01/02/03 已就绪，请补全 04-技术文档草稿.md 后，再执行 /opsx-propose（输入 01、02 与 UI 参考）`。
+4.  **禁止** 修改 `src/` 等业务代码；**禁止** `/opsx-propose` 或 `/opsx-apply`。
+5.  输出时附带：`01/02/03/04 已更新，未改业务代码。需要提案时回复「继续」或提供 UI 参考路径。`
 
 ---
 

package/src/templates/rules/sdd-no-implement-until-apply.mdc.template

@@ -0,0 +1,41 @@
+---
+description: SDD 门禁：存在 openspec/PRD 待确认或用户回复澄清结论时自动文档模式，禁止改业务代码；仅 /opsx-apply 后可实现
+alwaysApply: true
+---
+
+# SDD 流程：禁止提前写代码
+
+## 自动进入「文档模式」（用户无需加任何前缀）
+
+**不要要求用户粘贴【仅文档模式】等口令。** 满足以下任一条件时，你必须默认文档模式，即使用户只发了编号列表或「确认了」：
+
+1. 仓库存在 `openspec/PRD/*/03-待确认问题清单.md`，且其中 **矛盾点池状态：未闭合**（或用户本条消息明显是在回答其中的待确认项）。
+2. 上一轮你刚输出过待确认问题 / 请用户确认 / 矛盾点池未闭合。
+3. 用户消息为：编号结论、选用方案、是/否、补充业务规则、粘贴 PRD 片段说明——且当前对话上下文在 SDD/`openspec/PRD` 需求流程中。
+4. `openspec/PRD/*/.session-state.json` 中 `docModeOnly` 为 `true`（若存在则必读）。
+
+**识别到上述情况后**：在本回合**内部**执行文档模式，不要要求用户改说法。
+
+当用户处于 **需求澄清 / 待确认回复 / 矛盾点确认** 时，你必须遵守：
+
+## 本回合只允许（文档模式）
+- 读写 `openspec/PRD/**` 下的 markdown（`01`~`05`、`source/`、`RUNME.md`）
+- 只读扫描 `src/`、`pages/`、`components/` 等用于分析，**不得修改**
+
+## 本回合严禁
+- 修改或新建任何业务实现代码：`src/**`、`app/**`、`pages/**`、`components/**`、`api/**`、`store/**`、`hooks/**` 等
+- 运行会改动业务代码的 refactor / fix / feature 实现
+- 在未执行 `/opsx-propose` 前创建 `openspec/changes/**`（除非用户明确要求进入提案阶段）
+- 在用户未明确同意前执行 `/opsx-apply`
+
+## 用户直接粘贴确认点（最常见误触，勿要求用户加前缀）
+1. 定位最新或对话相关的 `openspec/PRD/<runId>/`（读 `RUNME.md` 或 `.session-state.json`）。
+2. **仅**更新 `03`（写入用户结论，标为已闭合）。
+3. 再生成/更新 `01`、`02`、`04`。
+4. 回复简短说明文档已更新即可；**不要**在同一回合改 `.tsx/.ts/.vue`。
+5. 主动问一句是否需要 UI 参考路径；用户说「继续/可以/做提案」即进入 `/opsx-propose`（仍不写业务代码）。
+
+## 唯一允许写业务代码的时机
+- 用户已走完：`/opsx-propose` → openspec change 已 apply-ready → 用户明确同意 **`/opsx-apply`**（如「开始 apply」「执行 apply」）。
+
+若用户只说「确认了」「按上面来」但未进入 apply 阶段，**仍禁止**写业务代码。