sdd-flow-kit 1.0.9 → 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/adapters/index.js

@@ -38,11 +38,12 @@ async function runClaudeFlow(args) {
         return false;
     const prompt = [
         `你在项目目录内执行需求流程，runId=${args.runId}。`,
-        "请按以下顺序自动完成：",
-        "1) 读取并执行 01-获取需求文档指引.md，完成 source/PRD.md 与 source/接口文档.md 回填（若无法访问外部系统，请保留占位并写明阻塞原因）。",
-        "2) 执行 02-需求分析提示词.md，更新 01-需求分析报告.md、02-改动点清单.md、03-待确认问题清单.md。",
-        "3) 基于 01/02/03 补全 04-技术文档草稿.md。",
-        "4) 更新 05-openspec-提案草稿.md 为可直接用于 openspec+superpowers 的输入。",
+        "请按分阶段门禁执行（禁止跳步）：",
+        "1) 01-获取需求文档指引：回填 source/PRD.md（及接口文档，如有）。",
+        "2) 02-需求分析：若矛盾点未闭合，仅更新 03-待确认问题清单.md 并停止；用户确认后再生成 01/02/闭环03。",
+        "3) 用户确认后补全 04-技术文档草稿.md。",
+        "4) /opsx-propose：基于 01、02 与 UI 参考生成 openspec change，并记录到 05-openspec-提案草稿.md。",
+        "5) /opsx-apply：提案 apply-ready 后执行 delivery-pipeline。",
         "完成后输出一句：SDD flow completed",
         "",
         "以下是第2步提示词：",

package/dist/steps/runFlow.js

@@ -22,11 +22,11 @@ function buildChecklist(args) {
         "- 或按 `RUNME.md` 逐步执行。",
         "",
         "## 最小闭环检查",
-        "- Step1 完成后：`source/PRD.md` 已回填",
-        "- Step2 提问模式：仅更新 `03-待确认问题清单.md`",
-        "- Step2 交付模式：产出 `01/02` 且标记“矛盾点池状态：已闭合”",
-        "- Step4 完成后：`04-技术文档草稿.md` 已补全",
-        "- Step5 完成后：`05-openspec-提案草稿.md` 已可投喂 openspec",
+        "- Step1：`source/PRD.md` 已回填",
+        "- Step2 提问模式：仅 `03`，未闭合时禁止 01/02/04",
+        "- Step4（用户确认后）：`01/02/03闭环/04` 齐全",
+        "- Step5：`/opsx-propose` 已生成 `openspec/changes/<change-name>/`，`05` 已记录 change 名",
+        "- Step6：`/opsx-apply` + delivery-pipeline exit 0",
         "",
     ].join("\n");
 }

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 自述
@@ -87,18 +89,27 @@ async function startFlowScaffold(options) {
         "请打开 `02-需求分析提示词.md`，在 Cursor/Claude Code/Codex/OpenClaw 中执行。",
         "门禁：提问模式仅允许更新 `03-待确认问题清单.md`；闭环后才允许输出最终版 `01/02`。",
         "",
-        "## Step 3：人工核验待确认问题",
-        "将 `03-待确认问题清单.md` 收敛为闭环（必要时调整 01/02）。",
+        "## Step 3：人工核验（暂停点）",
+        "用户补充待确认点并确认闭环后，才进入 Step 4。",
+        "门禁：未闭环时禁止生成 01/02/04，禁止 /opsx-propose。",
+        "**重要**：用户粘贴确认点时，AI 仅更新 `openspec/PRD` 文档，**禁止**修改 `src/` 等业务代码。",
         "",
-        "## Step 4：输出技术文档草稿",
-        "根据 `04-技术文档草稿.md` 完成技术设计说明。",
+        "## Step 4：生成 01 / 02 / 闭环03 / 04",
+        "用户确认后产出：",
+        "- `03-待确认问题清单.md`（已闭合）",
+        "- `01-需求分析报告.md`",
+        "- `02-改动点清单.md`",
+        "- `04-技术文档草稿.md`",
         "",
-        "## Step 5：触发 openspec + superpowers 提案",
-        "使用 `05-openspec-提案草稿.md` 作为 openspec 的提案输入入口。",
+        "## Step 5：/opsx-propose 生成提案",
+        "基于 `01`、`02` 与用户提供的 UI 参考，执行 `/opsx-propose`。",
+        "产出在 `openspec/changes/<change-name>/`；在 `05-openspec-提案草稿.md` 记录 change 名称。",
+        "门禁：仅当 03 已闭环且 01/02/04 完成后执行。",
         "",
-        "## Step 6：执行 /opsx-apply",
-        "必须在当前仓库的本地 OPSX skills/config 下执行，不允许跨仓 fallback 到其它目录。",
-        "门禁：delivery-pipeline 未成功（exit 0）前，禁止宣称 apply 完成。",
+        "## Step 6：/opsx-apply 实现收尾",
+        "提案 apply-ready 后，按 `.opsx/config.json` 执行 `/opsx-apply` 对应 change 的 apply 与 delivery-pipeline。",
+        "必须在当前仓库本地 OPSX 配置下执行，禁止跨仓 fallback。",
+        "门禁：delivery-pipeline exit 0 前禁止宣称流程结束。",
     ].join("\n"));
     return {
         runId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.0.9",
+  "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/05-openspec-/346/217/220/346/241/210/350/215/211/347/250/277.template.md

@@ -1,21 +1,32 @@
-# 05-openspec-提案入口草稿（由第 2/3/4 步汇总）
+# 05-openspec 提案阶段指引（阶段 C 完成后填写）
 
-> 目标：把技术文档与改动清单聚合为 openspec / superpower 模式可直接使用的提案描述。
+> 本文件不是最终提案正文，而是 **/opsx-propose 执行后的索引与交接记录**。  
+> 真正提案产物在 `openspec/changes/<change-name>/`。
 
-## 使用方式
-1. 打开你的 openspec 工作区
-2. 选择（或新建）对应 change
-3. 将本文件中的内容复制给 openspec + superpowers 的“提案输入”
-4. 进入生成 UI 图 + 任务拆解 + 开发阶段
+## 前置条件（必须全部满足）
+- [ ] `03-待确认问题清单.md` 已标注 **矛盾点池状态：已闭合**
+- [ ] `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md` 已生成
+- [ ] 用户已确认可进入提案阶段
 
-## 门禁（与手动流程一致）
-- 仅当 `03-待确认问题清单.md` 已明确“矛盾点池状态：已闭合”时，才可进入提案阶段。
-- 若 `03` 未闭合，禁止进入提案，先回到 Step3 完成确认。
-- 提案完成后进入 `/opsx-apply`，必须在当前仓库本地 OPSX 配置中执行。
+## /opsx-propose 输入清单
+- 需求分析：`01-需求分析报告.md`
+- 改动清单：`02-改动点清单.md`
+- UI/交互参考：（填写用户提供的路径，例如原型页面或设计稿目录）
 
-## 输入摘要
-- `01-需求分析报告.md`：已完成
-- `02-改动点清单.md`：已完成（仅代码文件改动）
-- `03-待确认问题清单.md`：已闭环（无悬而未决）
-- `04-技术文档草稿.md`：已完成
+## 执行命令（在 AI 工具中）
+- `/opsx-propose`
+- 说明需基于上述 01/02 + UI 参考一次性生成 change
 
+## 产出记录（执行后填写）
+- change 名称：
+- change 路径：`openspec/changes/<change-name>/`
+- 主要文件：
+  - `proposal.md`
+  - `design.md`
+  - `specs/`
+  - `tasks.md`
+- openspec status：（如 4/4 apply-ready）
+
+## 下一步
+- 阶段 D：执行 `/opsx-apply`（或 `pnpm run opsx:delivery-pipeline -- <change-name>`）
+- 禁止在 pipeline 未成功前宣称“需求开发完成”

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,23 +13,110 @@ description: 当用户说“开发 <产品> <版本> 需求/版本/PRD”或类
   - `开发XXX-V1.2.3版本`（无空格连写）
   - `开发 XXX PRD`
 - 或明确要求“按 SDD 流程”推进某版本需求
+- **用户回复待确认点 / 粘贴确认结论 / 说「按上面确认继续」**（即使未再说「开发 XX 需求」也视为 SDD 流程续跑）
 
-## 触发后必须执行
-1. 从用户输入中提取 `product` 与 `version`
-2. 在项目根目录执行：
-   - `npx sdd-flow-kit run --product <product> --version <version> -y`
-3. 按 `openspec/PRD/<runId>/RUNME.md` 严格推进第 1~5 步
-4. 交付物至少包含：
+## ⚠️ 最高优先级：文档模式 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）
+
+## 触发后执行规则（分阶段，禁止跳步）
+
+### 准备
+1. 从用户输入提取 `product`、`version`
+2. 执行：`npx sdd-flow-kit run --product <product> --version <version> -y`
+3. 工作目录：`openspec/PRD/<runId>/`（见 `RUNME.md`）
+
+---
+
+### 阶段 A — Step1 + Step2（必须可停顿）
+1. **Step1**：按 `01-获取需求文档指引.md` 拉取 PRD，回填 `source/PRD.md`（及可选接口文档）
+2. **Step2**：执行 `02-需求分析提示词.md`（引用 `docs/` 下已下载的 PRD）
+
+**门禁（Step2）**
+- 若矛盾点池**未闭合**（提问模式）：
+  - **仅允许** 输出/更新 `03-待确认问题清单.md`
+  - **禁止** 生成 `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md`
+  - **必须停止**，请用户补充/确认待确认项
+- **不得** 进入阶段 B/C/D
+
+---
+
+### 阶段 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`
+3. 生成最终版 `02-改动点清单.md`（仅代码文件改动）
+4. 生成 `04-技术文档草稿.md`
+
+**本阶段禁止：**
+- 修改 `src/`、`pages/`、`components/`、`api/` 等实现代码（`02-改动点清单` 只是**计划**，不是实施许可）
+- 执行 `/opsx-propose` 或 `/opsx-apply`
+- 生成 openspec change 目录或宣称“开发完成”
+
+完成后告知用户：“01/02/03/04 已就绪。发 UI 参考路径，或回复「继续」我将执行 /opsx-propose。”
+
+---
+
+### 阶段 C — `/opsx-propose`（生成提案，对应你说的「05」）
+**触发条件**：阶段 B 已完成，且用户确认可进入提案（可提供 UI 参考路径，如原型页面文件）。
+
+**必须执行：**
+1. 先读当前仓库 `.opsx/config.json` 与本地 OPSX skills（禁止跨项目 fallback）
+2. 执行 **`/opsx-propose`**，输入至少包含：
    - `01-需求分析报告.md`
    - `02-改动点清单.md`
-   - `03-待确认问题清单.md`
-   - `04-技术文档草稿.md`
-   - `05-openspec-提案草稿.md`
+   - **UI 图/交互参考**（用户指定路径；无则说明缺失并继续文字 spec）
+3. 一次性生成 openspec change（`proposal.md`、`design.md`、`specs/`、`tasks.md` 等）
+
+**本阶段交付物 = openspec 提案产物**（即手动流程里的 Step5 结果）。  
+可在 `openspec/PRD/<runId>/05-openspec-提案草稿.md` 记录 change 名称与路径索引。
+
+**本阶段禁止：**
+- 执行 `/opsx-apply`（留给阶段 D）
+
+---
+
+### 阶段 D — `/opsx-apply`（实现与交付收尾）
+**触发条件**：阶段 C 的 openspec 提案已生成且状态为 apply-ready。
+
+**必须执行：**
+1. 按总编排 skill（`.opsx/config.json` 中 `deliveryPipeline` 指向的 skill）执行 **`/opsx-apply`**
+2. 在当前仓库根目录跑 delivery-pipeline（如 `pnpm run opsx:delivery-pipeline -- <change-name>`）
+3. **仅在 pipeline 成功（exit 0）后** 才可宣称本需求开发流程结束
+
+---
+
+## 严禁（全局）
+- 澄清/确认阶段写业务代码（最常见违规）
+- 未闭合时一次性生成 `01~05` 或直接进入提案/实现
+- 把 `02-改动点清单.md` 当作可以立刻改文件的指令
+- 跳过用户确认点
+- 在错误仓库执行 OPSX（如 fallback 到其它项目的 poquan-web 路径）
 
 ## 非触发场景
-- 如果用户没有表达“开发某产品某版本需求”，则不要强制进入该流程
-- 继续按常规 AI 对话处理用户问题
+- 非“开发某版本需求”类对话 → 按普通问答处理
 
 ## 当前环境
 - agent: {{AGENT_NAME}}
-- 安装命令: `npx sdd-flow-kit install`
+- 安装: `npx sdd-flow-kit install`

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,21 +71,23 @@
 > **触发条件**：当你发现 PRD 与现有代码库不一致，或代码逻辑存在盲区时。
 
 **任务**：
-1.  **不要强行编写解决方案。**
+1.  **不要强行编写解决方案，不要改任何 `.tsx/.ts/.vue` 文件。**
 2.  列出所有 **断点**、**起点缺失** 和 **推测缺口**。
 3.  输出 `03-待确认问题清单.md`，并暂停生成最终报告，等待人工输入。
 4.  明确标注：`矛盾点池状态：未闭合`。
+5.  结束语（告诉用户可直接回复，无需口令）：`请直接在对话里粘贴你的确认点（编号列表即可），我会只更新 openspec/PRD 文档，不会改业务代码。`
 
 ---
 
 #### 路径 B：交付模式 (矛盾点池已闭合)
-> **触发条件**：人工纠偏后，所有疑问已解决，且无新问题产生。
+> **触发条件**：用户已回复待确认点，或明确表示矛盾点池已闭合（不得在未获用户确认时自行进入）。
 
-**任务**：
-1.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`。
-2.  在报告中明确标注“**矛盾点池状态：已闭合**”。
+**任务（本路径仅文档，不含 openspec，不含写代码）**：
+1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
+2.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
 3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
-4.  输出时附带一句：`可进入 Step4 技术文档与 Step5 提案阶段`。
+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 阶段，**仍禁止**写业务代码。

package/src/templates/skills/confluence-doc.py.template

@@ -163,7 +163,15 @@ def find_search_result(page, base_url: str, keyword: str):
 
 def run_search(page, base_url: str, keyword: str) -> str | None:
     search_selector = None
-    for selector in ["#search-query-input", "input[name='search-query']", "input.search-query", "input[id*='search']"]:
+    for selector in [
+        "#quick-search-query",
+        "#search-query-input",
+        "input[name='search-query']",
+        "input.search-query",
+        "input[placeholder*='搜索']",
+        "input[placeholder*='Search']",
+        "input[id*='search']",
+    ]:
         if page.locator(selector).count() > 0:
             search_selector = selector
             break
@@ -190,7 +198,7 @@ def main():
         load_env_file(repo_root / env_name)
 
     base_url = env("CONFLUENCE_BASE_URL", "https://confluence.huan.tv") or "https://confluence.huan.tv"
-    search_url = env("CONFLUENCE_SEARCH_URL") or f"{base_url.rstrip('/')}/dosearchsite.action?includeArchivedSpaces=false"
+    search_url = env("CONFLUENCE_SEARCH_URL") or f"{base_url.rstrip('/')}/#all-updates"
     username = (
         env("CONFLUENCE_USERNAME")
         or env("CONFLUENCE_USER")

package/src/templates/skills/doc-skill.SKILL.md.template

@@ -58,5 +58,6 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 - 脚本：`docs/{{SKILL_DIR}}/confluence-doc.py`
 - 脚本已内置默认账号密码；如需使用其他账号可用环境变量覆盖
 - 默认 Confluence 地址为 `https://confluence.huan.tv`（可用 `CONFLUENCE_BASE_URL` 覆盖）
+- 默认搜索入口为 `https://confluence.huan.tv/#all-updates`（可用 `CONFLUENCE_SEARCH_URL` 覆盖）
 - 脚本会自动尝试读取仓库根目录的 `.env.pre` / `.env` / `.env.local` / `.env.development` / `.env.test`（若其中存在 `CONFLUENCE_*` 配置可直接复用）