sdd-flow-kit 1.3.11 → 1.3.13

package/README.md

@@ -63,7 +63,7 @@ node ./node_modules/sdd-flow-kit/dist/postinstall.js
 #### 当前自动化边界
 
 - 已支持：跨工具统一目录结构、提示词、报告模板、**NEXT.md 脚本清单**
-- 已支持：**gate / phase / propose / deliver** 命令（exit code 机械门禁）
+- 已支持：**gate / phase / propose / deliver / chain / session mode** 命令（exit code 机械门禁）
 - 已支持：`ensure-opsx` + `openspec status` 校验 apply-ready
 - 未支持：在 Cursor 内全自动跑完全流程（Cursor adapter 仍为 manual）；可选 `SDD_FLOW_KIT_ENABLE_CLAUDE_AUTORUN=1` 给 Claude Code
 
@@ -80,6 +80,13 @@ node ./node_modules/sdd-flow-kit/dist/postinstall.js
 
 #### 变更记录
 
+**1.3.13** — 执行模式拆分 + 回合结束约束 + chain 机械串联
+
+- 新增 `executionMode`：`full-chain`（默认）与 `staged-confirm`（分阶段确认），正交于 `strictCommands`
+- 兼容「严格SOP，不可替代」→ `staged-confirm` + `strictCommands`
+- 模板写入回合结束条件，禁止待办清单式提前收尾
+- 新增 `chain`、`session mode` CLI；`invoke` 自动解析执行模式
+
 **1.3.11** — PRD 自动修复改为「每项最多 3 次」
 
 - 每轮只修 `prd-diff` 仍失败的剩余项；8 项已修好则下轮只盯剩下 2 项
@@ -92,6 +99,14 @@ node ./node_modules/sdd-flow-kit/dist/postinstall.js
 - Claude Code 安装（`.claude/skills`）时默认用 `claude -p` 执行修复，不限于 Cursor
 - 可用 `--agent claude-code` 或 `SDD_FLOW_KIT_ENABLE_*_AUTORUN=0` 控制
 
+**1.3.12** — Confluence 关键字搜索稳定性（dosearchsite 主路径）
+
+- `confluence-doc.py`：每个关键词优先打开 `dosearchsite.action?queryString=...` 专用搜索页（不再依赖 `#all-updates` 顶栏搜索）
+- 匹配放宽：**标题命中或 URL 路径命中** 均可得分（`score_link_match` 原已支持，增强前缀匹配与 ADI 加权）
+- `run_search_dosearch`：处理 `ERR_ABORTED`、搜索结果页导航重试；顶栏搜索降为兜底
+- 新增 `CONFLUENCE_DEBUG=1` 输出选择器解析日志
+- 更新 `01-adi-doc-skill-指引` / `doc-skill.SKILL`：关键字搜索为主，pageId 直链为可选兜底
+
 **1.3.9** — PRD 不一致自动修复循环（最多 3 次）
 
 - 新增 `prd-remediate`：`prd-diff` 失败 → 按 `09` 生成修复指引 → 调 AI 工具 `/opsx-apply` 修代码 → 再 `prd-diff`（**每项**最多 3 次）

package/dist/adapters/index.js

@@ -43,8 +43,9 @@ async function runClaudeFlow(args) {
         "1) 01-获取需求文档指引：回填 source/PRD.md（及接口文档，如有）。",
         "2) 02-需求分析：若矛盾点未闭合，仅更新 03-待确认问题清单.md 并停止；用户确认后生成 05→04→01/02/闭环03。",
         "3) 用户确认后从 source/PRD.md 填写 05-验收清单.md（定义状态：已定义），再补全 04-技术文档草稿.md（引用 AC-ID）。",
-        "4) 03 闭环后默认同一回合：/opsx-propose（05+04+02+UI）→ gate ac-ready → /opsx-apply → gate ac-signed → delivery-pipeline exit 0（见 07-opsx-自动串联指引.md）。",
+        "4) 03 闭环后：读 .session-state.json 的 executionMode；full-chain（默认）同一回合 C→D→E 直至 deliver exit 0；staged-confirm 每阶段等人确认。",
         "5) 仅当用户说「只提案」或 autoChainOpsx=false 时，在 propose 后暂停等待 apply。",
+        "6) full-chain 时禁止以待办清单结束；唯一出口 deliver exit 0。",
         "完成后输出一句：SDD flow completed",
         "",
         "以下是第2步提示词：",
@@ -92,12 +93,14 @@ async function runCursorFlow(args) {
         "强约束：",
         "1) 在 docs 阶段（docModeOnly=true）只允许改 openspec/PRD/**，禁止改 src/。",
         "2) 若矛盾点池未闭合：仅更新 03-待确认问题清单.md 并停止，等待用户确认点。",
-        "3) 若矛盾点池已闭合：同一回合生成 05→04→01/02，并自动衔接 openspec+superpowers（autoChainOpsx=true 时）。",
+        "3) 若矛盾点池已闭合：同一回合生成 05→04→01/02；executionMode=full-chain 时继续 C→D→E 直至 deliver exit 0。",
+        "4) executionMode=staged-confirm 时：每阶段输出门禁结果后暂停等人确认。",
+        "5) 禁止用「后续待办」「骨架已完成」结束回合（full-chain 时）。",
         "",
         "执行顺序：",
         "A) 先按 01-获取需求文档指引.md 执行 confluence-doc.py，把 PRD 回填到 source/PRD.md。",
         "B) 再执行 02-需求分析提示词.md（如下）生成/更新 03（必要时）或生成 05/04/01/02。",
-        "C) 若满足自动串联条件（autoChainOpsx!==false 且用户未说只提案）：继续按 07-opsx-自动串联指引.md 走 propose→ac-ready→apply→ac-signed→delivery-pipeline。",
+        "C) full-chain：按 07-opsx-自动串联指引.md 走 propose→ac-ready→apply→validate→deliver；可用 chain 命令机械串联 gate。",
         "",
         "完成判定：",
         "- 若停在澄清：输出一句 `SDD_STATUS=AWAIT_CONFIRMATION`。",

package/dist/cli.js

@@ -20,6 +20,8 @@ const runDeliver_1 = require("./steps/runDeliver");
 const runPrdReview_1 = require("./steps/runPrdReview");
 const runPrdDiff_1 = require("./steps/runPrdDiff");
 const runPrdRemediate_1 = require("./steps/runPrdRemediate");
+const runChain_1 = require("./steps/runChain");
+const runSessionMode_1 = require("./steps/runSessionMode");
 const bootstrap_1 = require("./core/bootstrap");
 const projectRoots_1 = require("./core/projectRoots");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
@@ -85,6 +87,14 @@ function printHelp() {
         "   npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to validate-done --change <name>",
         "   npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>",
         "",
+        "11) 机械串联 gate→phase→validate→deliver（AI 步骤须先完成）：",
+        "   npx sdd-flow-kit chain --project-root . --run-id <runId> --change <name> --from docs-done",
+        "   # --from: docs-done | propose-done | impl | validate-done",
+        "",
+        "12) 设置执行模式：",
+        "   npx sdd-flow-kit session mode --run-id <runId> --execution-mode full-chain",
+        "   npx sdd-flow-kit session mode --run-id <runId> --execution-mode staged-confirm --strict-commands",
+        "",
         "可选参数：",
         "   --projectRoot <path>   目标项目根目录（默认当前目录 = 安装根，cd 到哪装到哪）",
         "   环境变量 SDD_FLOW_KIT_INSTALL_ROOT 可覆盖安装根（绝对路径）",
@@ -101,7 +111,7 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
@@ -127,6 +137,7 @@ async function main() {
         "validate-done",
         "shipped",
     ];
+    const CHAIN_FROM = ["docs-done", "propose-done", "impl", "validate-done"];
     if (cmd !== "start" &&
         cmd !== "run" &&
         cmd !== "setup" &&
@@ -141,7 +152,9 @@ async function main() {
         cmd !== "prd-review" &&
         cmd !== "prd-diff" &&
         cmd !== "prd-remediate" &&
-        cmd !== "deliver") {
+        cmd !== "deliver" &&
+        cmd !== "chain" &&
+        cmd !== "session") {
         printHelp();
         process_1.default.exitCode = 1;
         return;
@@ -188,6 +201,8 @@ async function main() {
         "prd-diff",
         "prd-remediate",
         "deliver",
+        "chain",
+        "session",
     ]);
     if (!skipBootstrap && !dryRun && bootstrapCommands.has(cmd)) {
         await (0, bootstrap_1.bootstrapProjectIfNeeded)({
@@ -354,6 +369,59 @@ async function main() {
             process_1.default.exitCode = 1;
         return;
     }
+    if (cmd === "chain") {
+        if (!changeName) {
+            // eslint-disable-next-line no-console
+            console.error("chain 需要 --change <kebab-name>");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const from = ((_j = getArgValue("--from")) !== null && _j !== void 0 ? _j : "docs-done");
+        if (!CHAIN_FROM.includes(from)) {
+            // eslint-disable-next-line no-console
+            console.error(`chain 需要 --from ${CHAIN_FROM.join("|")}`);
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runChain_1.runChain)({
+            projectRoot,
+            runId,
+            change: changeName,
+            from,
+            agent,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "session") {
+        const sub = process_1.default.argv[3];
+        if (sub !== "mode") {
+            // eslint-disable-next-line no-console
+            console.error("用法: sdd-flow-kit session mode --execution-mode full-chain|staged-confirm [--strict-commands]");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const modeArg = (_k = getArgValue("--execution-mode")) !== null && _k !== void 0 ? _k : getArgValue("--executionMode");
+        const textArg = getArgValue("--text");
+        const strictCommands = process_1.default.argv.includes("--strict-commands");
+        const result = await (0, runSessionMode_1.runSessionMode)({
+            projectRoot,
+            runId,
+            executionMode: modeArg === "full-chain" || modeArg === "staged-confirm" ? modeArg : null,
+            strictCommands: strictCommands || undefined,
+            text: textArg,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
     if (cmd === "doctor" || cmd === "ensure-opsx") {
         const fix = cmd === "ensure-opsx" || process_1.default.argv.includes("--fix");
         const doctor = await (0, doctor_1.runDoctor)({
@@ -426,6 +494,9 @@ async function main() {
                 agent,
             });
             const result = await (0, runFlow_1.runFlow)(options);
+            if (!dryRun) {
+                await (0, runSessionMode_1.applyInvokeTextToSession)(projectRoot, result.runId, text);
+            }
             // eslint-disable-next-line no-console
             console.log(`invoke 成功：${parsed.product} ${parsed.version} -> runId=${result.runId}`);
             if (planJson) {

package/dist/core/executionMode.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseExecutionModeFromText = parseExecutionModeFromText;
+exports.applyExecutionModeToSession = applyExecutionModeToSession;
+exports.shouldAutoChainAfterConfirm = shouldAutoChainAfterConfirm;
+exports.shouldPauseBetweenPhases = shouldPauseBetweenPhases;
+exports.requiresStrictCommands = requiresStrictCommands;
+exports.normalizeExecutionModeFields = normalizeExecutionModeFields;
+const DEFAULT_MODE = {
+    executionMode: "full-chain",
+    strictCommands: false,
+    legacyStrictSop: false,
+};
+/**
+ * 从用户自然语言解析执行模式（invoke / 确认点粘贴均可调用）。
+ */
+function parseExecutionModeFromText(text) {
+    const t = text.trim();
+    if (!t)
+        return { ...DEFAULT_MODE };
+    const legacyStrictSop = /严格\s*SOP|不可替代/.test(t);
+    let executionMode = "full-chain";
+    if (/分阶段确认|staged-confirm|阶段确认制/.test(t) ||
+        legacyStrictSop) {
+        executionMode = "staged-confirm";
+    }
+    if (/确认后全链路|full-chain|禁止中途停止|全链路/.test(t)) {
+        executionMode = "full-chain";
+    }
+    const strictCommands = legacyStrictSop ||
+        /严格命令|strict-commands|禁止.*等价/.test(t);
+    return { executionMode, strictCommands, legacyStrictSop };
+}
+/**
+ * 将解析结果写入 session；force=true 时无条件覆盖。
+ */
+function applyExecutionModeToSession(session, parsed, force = false) {
+    const isDefault = parsed.executionMode === "full-chain" &&
+        !parsed.strictCommands &&
+        !parsed.legacyStrictSop;
+    if (!force && isDefault)
+        return session;
+    return {
+        ...session,
+        executionMode: parsed.executionMode,
+        strictCommands: parsed.strictCommands || session.strictCommands === true,
+    };
+}
+/** 矛盾点闭合后是否同一回合自动 propose→apply（不看 staged-confirm，那是阶段间暂停） */
+function shouldAutoChainAfterConfirm(session) {
+    if (session.autoChainOpsx === false)
+        return false;
+    return true;
+}
+/** 完成一个阶段（C/D/E）后是否必须等待用户确认再进下一阶段 */
+function shouldPauseBetweenPhases(session) {
+    if (session.executionMode === "staged-confirm")
+        return true;
+    return false;
+}
+/** 是否禁止用「等价命令」替代 NEXT.md / gate 链路 */
+function requiresStrictCommands(session) {
+    return session.strictCommands === true;
+}
+function normalizeExecutionModeFields(raw) {
+    const modeRaw = raw.executionMode;
+    let executionMode = "full-chain";
+    if (modeRaw === "staged-confirm" || modeRaw === "full-chain") {
+        executionMode = modeRaw;
+    }
+    else if (raw.legacyStrictSop === true || raw.strictSop === true) {
+        executionMode = "staged-confirm";
+    }
+    return {
+        executionMode,
+        strictCommands: raw.strictCommands === true,
+    };
+}

package/dist/core/sessionState.js

@@ -9,6 +9,7 @@ exports.defaultSession = defaultSession;
 exports.normalizeSession = normalizeSession;
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("./fs");
+const executionMode_1 = require("./executionMode");
 const SESSION_FILE = ".session-state.json";
 async function readSession(outputRoot) {
     const raw = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, SESSION_FILE));
@@ -29,6 +30,8 @@ function defaultSession(args) {
         status: "awaiting_user_confirmation",
         docModeOnly: true,
         autoChainOpsx: true,
+        executionMode: "full-chain",
+        strictCommands: false,
         activeChange: null,
         createdAtISO: new Date().toISOString(),
         implGitBaseline: null,
@@ -50,6 +53,7 @@ function normalizeSession(raw, outputRoot) {
         status,
         docModeOnly: raw.docModeOnly !== false,
         autoChainOpsx: raw.autoChainOpsx !== false,
+        ...(0, executionMode_1.normalizeExecutionModeFields)(raw),
         activeChange: raw.activeChange ? String(raw.activeChange) : null,
         createdAtISO: String((_e = raw.createdAtISO) !== null && _e !== void 0 ? _e : new Date().toISOString()),
         implGitBaseline: raw.implGitBaseline ? String(raw.implGitBaseline) : null,

package/dist/core/turnEndPolicy.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTurnEndPolicyMarkdown = getTurnEndPolicyMarkdown;
+exports.getExecutionModeGuideMarkdown = getExecutionModeGuideMarkdown;
+/**
+ * 回合结束条件（写入 NEXT.md / 07 指引，约束 AI 不得「待办清单式」提前收尾）。
+ */
+function getTurnEndPolicyMarkdown() {
+    return [
+        "## 回合结束条件（唯一合法出口）",
+        "",
+        "- ✅ `gate shipped` 通过 **且** `deliver` exit 0",
+        "- ⛔ **禁止**在 `tasks.md` 未全 `- [x]`、delivery-pipeline 未 exit 0 时结束回合",
+        "- ⛔ **禁止**用「后续待办」「骨架已完成」「文档已更新」作为结束语",
+        "- ⛔ **禁止**输出仅含待办清单的收尾（`executionMode=full-chain` 时）",
+        "- 唯一允许暂停：",
+        "  - `gate` / `validate` / `deliver` exit≠0",
+        "  - `prd-remediate` 单项 3 次未果需人工裁定",
+        "  - 矛盾点池未闭合（提问模式）",
+        "  - `executionMode=staged-confirm` 且当前阶段已完成（输出门禁结果后等人确认）",
+        "  - 用户明确说「只提案」「先别写代码」或 `autoChainOpsx=false`",
+        "",
+    ];
+}
+function getExecutionModeGuideMarkdown() {
+    return [
+        "## 执行模式（`.session-state.json`）",
+        "",
+        "| 字段 | 值 | 含义 |",
+        "|------|-----|------|",
+        "| `executionMode` | `full-chain`（默认） | 矛盾点闭合后 C→D→E 同一回合跑到底 |",
+        "| `executionMode` | `staged-confirm` | 每阶段完成后暂停，等人确认再继续 |",
+        "| `strictCommands` | `true` | 禁止用等价命令替代 NEXT.md 中的 gate/phase 链路 |",
+        "| `autoChainOpsx` | `false` | 文档完成后停止，不自动 propose/apply |",
+        "",
+        "**用户口令示例**",
+        "- 确认后全链路：`执行模式：确认后全链路，禁止中途停止`",
+        "- 分阶段确认：`执行模式：分阶段确认`",
+        "- 严格命令（可与全链路组合）：`执行模式：严格命令`",
+        "- 兼容旧版：`执行模式：严格SOP，不可替代` → `staged-confirm` + `strictCommands`",
+        "",
+        "设置模式：",
+        "```bash",
+        "npx sdd-flow-kit session mode --run-id <runId> --execution-mode full-chain",
+        "npx sdd-flow-kit session mode --run-id <runId> --execution-mode staged-confirm --strict-commands",
+        "```",
+        "",
+    ];
+}

package/dist/core/writeNext.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeInitialNext = writeInitialNext;
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("./fs");
+const turnEndPolicy_1 = require("./turnEndPolicy");
 /**
  * run 初始化后写入 NEXT.md，强制 AI 按脚本推进而非自然语言跳步。
  */
@@ -16,6 +17,14 @@ async function writeInitialNext(outputRoot, projectRoot, runId) {
         "",
         "> **禁止**跳过下列命令。失败 (exit≠0) 时不得进入下一阶段或修改 `src/`。",
         "",
+        ...(0, turnEndPolicy_1.getTurnEndPolicyMarkdown)(),
+        ...(0, turnEndPolicy_1.getExecutionModeGuideMarkdown)(),
+        "## 机械串联（可选，AI 步骤完成后）",
+        "```bash",
+        `npx sdd-flow-kit chain --project-root "${pr}" --run-id ${runId} --change <kebab-name> --from docs-done`,
+        "# --from 可选：docs-done | propose-done | impl | validate-done",
+        "```",
+        "",
         "## 文档职责（SSOT）",
         "",
         "| 文档 | 职责 |",

package/dist/steps/runChain.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runChain = runChain;
+const runGate_1 = require("./runGate");
+const runPhaseAdvance_1 = require("./runPhaseAdvance");
+const runPrdReview_1 = require("./runPrdReview");
+const runPrdDiff_1 = require("./runPrdDiff");
+const runValidate_1 = require("./runValidate");
+const runDeliver_1 = require("./runDeliver");
+const resolveRun_1 = require("./resolveRun");
+/**
+ * 机械串联 gate / phase / validate / deliver；AI 步骤（propose、apply、填 08）须先完成，否则在对应 gate 失败即停。
+ */
+async function runChain(options) {
+    var _a, _b;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, runId: null, detail: "未找到 PRD run" };
+    }
+    const runId = loaded.resolved.runId;
+    const pr = options.projectRoot;
+    const change = options.change;
+    const agent = (_a = options.agent) !== null && _a !== void 0 ? _a : "cursor";
+    const allSteps = [
+        {
+            label: "gate docs-closed",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "docs-closed" });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "phase advance docs-done",
+            run: async () => {
+                const r = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+                    projectRoot: pr,
+                    runId,
+                    to: "docs-done",
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.message };
+            },
+        },
+        {
+            label: "gate propose-ready",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "propose-ready", change });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "gate ac-ready",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "ac-ready", change });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "phase advance propose-done",
+            run: async () => {
+                const r = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+                    projectRoot: pr,
+                    runId,
+                    to: "propose-done",
+                    change,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.message };
+            },
+        },
+        {
+            label: "phase advance impl",
+            run: async () => {
+                const r = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+                    projectRoot: pr,
+                    runId,
+                    to: "impl",
+                    change,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.message };
+            },
+        },
+        {
+            label: "gate impl-allowed",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "impl-allowed", change });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "prd-review",
+            run: async () => {
+                const r = await (0, runPrdReview_1.runPrdReview)({ projectRoot: pr, runId, dryRun: options.dryRun });
+                return { ok: r.ok, detail: r.detail };
+            },
+        },
+        {
+            label: "prd-diff",
+            run: async () => {
+                const r = await (0, runPrdDiff_1.runPrdDiff)({ projectRoot: pr, runId, dryRun: options.dryRun });
+                return { ok: r.ok, detail: r.detail };
+            },
+        },
+        {
+            label: "gate prd-coverage",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "prd-coverage", change });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "validate",
+            run: async () => {
+                const r = await (0, runValidate_1.runValidate)({
+                    projectRoot: pr,
+                    runId,
+                    change,
+                    agent,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.detail };
+            },
+        },
+        {
+            label: "phase advance validate-done",
+            run: async () => {
+                const r = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+                    projectRoot: pr,
+                    runId,
+                    to: "validate-done",
+                    change,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.message };
+            },
+        },
+        {
+            label: "gate ac-signed",
+            run: async () => {
+                const g = await (0, runGate_1.runGate)({ projectRoot: pr, runId, expect: "ac-signed" });
+                if (!g.ok)
+                    (0, runGate_1.printGateResult)(g);
+                return { ok: g.ok, detail: g.checks.map((c) => c.detail).join("; ") };
+            },
+        },
+        {
+            label: "deliver",
+            run: async () => {
+                const r = await (0, runDeliver_1.runDeliver)({
+                    projectRoot: pr,
+                    runId,
+                    change,
+                    agent,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.detail };
+            },
+        },
+        {
+            label: "phase advance shipped",
+            run: async () => {
+                const r = await (0, runPhaseAdvance_1.runPhaseAdvance)({
+                    projectRoot: pr,
+                    runId,
+                    to: "shipped",
+                    change,
+                    dryRun: options.dryRun,
+                });
+                return { ok: r.ok, detail: r.message };
+            },
+        },
+    ];
+    const startIndex = {
+        "docs-done": 0,
+        "propose-done": 3,
+        impl: 5,
+        "validate-done": 11,
+    };
+    const steps = allSteps.slice(startIndex[options.from]);
+    if (options.dryRun) {
+        return {
+            ok: true,
+            runId,
+            detail: `dry-run: 将依次执行 ${steps.map((s) => s.label).join(" → ")}`,
+        };
+    }
+    for (const step of steps) {
+        // eslint-disable-next-line no-console
+        console.log(`[chain] ${step.label} ...`);
+        const result = await step.run();
+        if (!result.ok) {
+            return {
+                ok: false,
+                runId,
+                failedStep: step.label,
+                detail: `${step.label} 失败：${(_b = result.detail) !== null && _b !== void 0 ? _b : "exit≠0"}。请先完成 AI 步骤（propose/apply/填 08/签收 05）后重试 chain。`,
+            };
+        }
+    }
+    return { ok: true, runId, detail: "chain 完成：已执行至 shipped" };
+}

package/dist/steps/runSessionMode.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSessionMode = runSessionMode;
+exports.applyInvokeTextToSession = applyInvokeTextToSession;
+const sessionState_1 = require("../core/sessionState");
+const executionMode_1 = require("../core/executionMode");
+const resolveRun_1 = require("./resolveRun");
+/**
+ * 更新 run 的 executionMode / strictCommands（用户口令或 CLI flag）。
+ */
+async function runSessionMode(options) {
+    var _a;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved) || !loaded.session) {
+        return { ok: false, runId: null, detail: "未找到 run 或 .session-state.json" };
+    }
+    const { resolved, session } = loaded;
+    let parsed = (0, executionMode_1.parseExecutionModeFromText)((_a = options.text) !== null && _a !== void 0 ? _a : "");
+    if (options.executionMode) {
+        parsed = { ...parsed, executionMode: options.executionMode };
+    }
+    if (options.strictCommands === true) {
+        parsed = { ...parsed, strictCommands: true };
+    }
+    const next = (0, executionMode_1.applyExecutionModeToSession)(session, parsed, true);
+    if (!options.dryRun) {
+        await (0, sessionState_1.writeSession)(resolved.outputRoot, next);
+    }
+    return {
+        ok: true,
+        runId: resolved.runId,
+        detail: `executionMode=${next.executionMode}, strictCommands=${next.strictCommands === true}`,
+    };
+}
+/** invoke 完成后根据用户口令写入 session 模式 */
+async function applyInvokeTextToSession(projectRoot, runId, invokeText) {
+    const loaded = await (0, resolveRun_1.loadRunSession)(projectRoot, runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved))
+        return;
+    const session = await (0, sessionState_1.readSession)(loaded.resolved.outputRoot);
+    if (!session)
+        return;
+    const parsed = (0, executionMode_1.parseExecutionModeFromText)(invokeText);
+    const next = (0, executionMode_1.applyExecutionModeToSession)(session, parsed, false);
+    if (next.executionMode !== session.executionMode ||
+        next.strictCommands !== session.strictCommands) {
+        await (0, sessionState_1.writeSession)(loaded.resolved.outputRoot, next);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.3.11",
+  "version": "1.3.13",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",
@@ -26,6 +26,10 @@
   "devDependencies": {
     "@types/node": "^20.14.10",
     "typescript": "^5.6.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "sdd-flow-kit"
+    ]
   }
 }
-

package/src/templates/artifacts/01-adi-doc-skill-/346/214/207/345/274/225.template.md

@@ -12,14 +12,18 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。
 
-2. 脚本会依次搜索（含用户原样输入）：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
+2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
 
-3. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+3. 匹配规则：**标题包含关键词或以关键词为前缀**，或 **URL 路径包含关键词**，任一满足即命中（Confluence 列表标题常被截断）。
 
-4. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+4. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+
+5. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
    - `source/PRD.md`
 
-## 直链兜底（已知 pageId 时推荐）
+## 直链兜底（可选，非默认）
+
+仅在关键字搜索全部失败、且已知 pageId 时使用：
 
 ADI V2.3.4 示例（`yyzcpt` 空间 pageId `109609740`）：
 
@@ -44,8 +48,8 @@ python3 confluence-doc.py 2.3.4
 
 ## 失败排查
 
-- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）
-- 页面存在但搜不到：设置 `CONFLUENCE_PAGE_ID=<pageId>` 或 `CONFLUENCE_PAGE_URL=<完整URL>` 直链下载
+- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）；可尝试输入更长关键词如 `ADI_V2.3.4结算`
+- 页面存在但搜不到：加 `CONFLUENCE_DEBUG=1` 查看选择器解析日志；或（可选）设置 `CONFLUENCE_PAGE_ID` / `CONFLUENCE_PAGE_URL` 直链下载
 - Playwright 失败且设置 `CONFLUENCE_USE_REST=1` 时才回退 Token；登录最多重试 3 次，并用 `expect_navigation` 避免竞态
 - 登录偶发失败：用 `CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500` 有头观察；失败截图 `confluence-login-fail-*.png`
 - `playwright` 未安装：`pip install playwright && playwright install chromium`

package/src/templates/artifacts/02-/351/234/200/346/261/202/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.template.md

@@ -12,6 +12,7 @@
 - `source/PRD.md` 若仍是占位文本（没有真实 PRD 内容），**禁止**继续 Step2，先返回“Step1 未完成”并停止。
 - 当处于“提问模式”时，**只允许更新** `03-待确认问题清单.md`；**禁止**产出最终版 `01-需求分析报告.md` / `02-改动点清单.md`。
 - 只有当用户明确确认“矛盾点池已闭合”后，才可进入“交付模式”并输出最终版 `01` / `02`。
+- 用户口令 `执行模式：确认后全链路` → `.session-state.json` 中 `executionMode: full-chain`（矛盾点闭合后禁止中途停止）。
 
 ## 输入注入（建议做法）
 - 将 `source/PRD.md` 的内容作为 `{{PRD_MARKDOWN}}` 注入

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

@@ -46,27 +46,43 @@ npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --ag
    - `.cursor/skills/opsx-superpowers-workflow/SKILL.md`
    - `openspec-propose` → `openspec-apply-change` → `pnpm run opsx:delivery-pipeline -- <change>`
 8. TDD/Playwright 遵循 `LAYERED-TESTING.md`（L2 交互契约、L3 每页 E2E）。
+9. **`executionMode=full-chain`（默认）**：矛盾点闭合后 **禁止** 以待办清单结束回合；必须 C→D→E 直至 `deliver` exit 0。
 
-## 严格 SOP 模式（用户声明后强制生效，不可替代）
+## 执行模式（`.session-state.json`）
 
-当用户明确声明「执行模式：严格SOP，不可替代」时，以下规则优先于默认自动串联：
+| 口令 | `executionMode` | `strictCommands` | 行为 |
+|------|-----------------|------------------|------|
+| （默认） | `full-chain` | `false` | 确认后同一回合跑到底 |
+| `执行模式：确认后全链路` | `full-chain` | — | 同上，禁止中途停止 |
+| `执行模式：分阶段确认` | `staged-confirm` | — | 每阶段完成后等人确认 |
+| `执行模式：严格命令` | — | `true` | 禁止等价命令替代 gate 链路 |
+| `严格SOP，不可替代`（兼容） | `staged-confirm` | `true` | 分阶段确认 + 严格命令 |
 
-1. 必须严格按仓库已安装的 `sdd-flow-kit` 流程执行，禁止“等价方式”替代。
-2. Step1 必须执行用户指定的文档获取流程（Confluence/脚本链路）；除非用户明确说“允许替代”，否则禁止用本地文件手动回填代替。
-3. 阶段 B 产出的 `04-技术文档草稿.md` 必须是可执行技术方案，禁止模板占位；且需逐条引用 `05-验收清单.md` 的 AC-ID。
-4. 阶段 C 必须执行 `/opsx-propose`（输入 **05 + 04 + 02 + UI**），禁止用 `npx sdd-flow-kit propose` 代替提案生成。
-5. 每完成一个阶段，必须先输出：`门禁结果 + 证据文件路径 + 下一步命令`，等待用户确认后再继续。
-6. 任一步骤不满足 SOP，必须立即停止并先询问用户，不得自行继续。
-7. 禁止将“门禁通过”视为“流程正确”；必须同时满足：命令正确 + 产物正确 + 顺序正确。
-8. 若需要替代方案，必须先提出并等待用户确认。
+```bash
+npx sdd-flow-kit session mode --run-id <runId> --execution-mode full-chain
+npx sdd-flow-kit chain --run-id <runId> --change <name> --from docs-done
+```
+
+## 回合结束条件
+
+- ✅ 唯一合法出口：`gate shipped` + `deliver` exit 0
+- ⛔ 禁止「骨架已完成」「后续待办」式收尾（`full-chain` 时）
+- ⛔ 禁止在 `tasks.md` 未全 `[x]` 时宣称完成
+
+## 严格命令模式（`strictCommands=true`）
 
-### 严格 SOP 的固定预执行动作
+与是否分阶段暂停**正交**；可与 `full-chain` 组合：
 
-进入每个阶段前，先输出：
+1. 必须严格按 `NEXT.md` 中的 gate/phase 链路执行，禁止“等价方式”替代。
+2. Step1 须走 Confluence/脚本链路；除非用户明确允许，禁止手动回填代替。
+3. 阶段 B 的 `04` 须可执行且逐条引用 AC-ID。
+4. 阶段 C 须 `/opsx-propose`（输入 **05 + 04 + 02 + UI**），禁止仅用 `sdd-flow-kit propose` 代替 AI 提案生成。
 
-`本次计划命令清单（逐条）`
+## 分阶段确认模式（`executionMode=staged-confirm`）
 
-并等待用户确认后再执行命令。
+1. 每阶段前先输出：`本次计划命令清单（逐条）`
+2. 每阶段后输出：`门禁结果 + 证据文件路径 + 下一步命令`
+3. **等待用户确认**后再进入下一阶段
 
 ## 阶段摘要
 

package/src/templates/artifacts/07-opsx-auto-chain.template.md

@@ -2,7 +2,28 @@
 
 > **不要**在阶段 B 结束后停下来问用户「是否继续」或「是否 apply」。  
 > 除非用户明确说「只提案」「先别写代码」，或 `.session-state.json` 中 `autoChainOpsx: false`。
-> 若用户声明「执行模式：严格SOP，不可替代」，则本文件的“自动串联”必须降级为“分阶段确认执行”：每阶段先输出`本次计划命令清单（逐条）`并等待用户确认。
+
+## 执行模式（读 `.session-state.json`）
+
+| `executionMode` | 行为 |
+|-----------------|------|
+| `full-chain`（**默认**） | 矛盾点闭合后 **同一回合** C→D→E，直至 `deliver` exit 0 |
+| `staged-confirm` | 每阶段完成后输出门禁结果，**等待用户确认**再进下一阶段 |
+
+| `strictCommands` | 行为 |
+|------------------|------|
+| `true` | 禁止用等价命令替代 NEXT.md 中的 gate/phase 链路（可与 full-chain 组合） |
+| `false`（默认） | 按 NEXT.md 执行即可 |
+
+**用户口令**：`执行模式：确认后全链路` → `full-chain`；`执行模式：分阶段确认` → `staged-confirm`；`执行模式：严格命令` → `strictCommands: true`。  
+**兼容旧版**：`执行模式：严格SOP，不可替代` → `staged-confirm` + `strictCommands: true`。
+
+## 回合结束条件（唯一合法出口）
+
+- ✅ `gate shipped` 通过 **且** `deliver` exit 0
+- ⛔ **禁止**在 `tasks.md` 未全 `- [x]`、pipeline 未 exit 0 时结束回合
+- ⛔ **禁止**用「后续待办」「骨架已完成」作为结束语
+- 唯一允许暂停：gate exit≠0、prd-remediate 3 次未果、矛盾点未闭合、`staged-confirm` 阶段间确认、`autoChainOpsx=false`
 
 ## 输入（本 runId）
 
@@ -33,18 +54,20 @@
    ```
 5. 更新 `06-openspec-提案草稿.md` 与 `.session-state.json`：`status: propose_done`
 6. **禁止**在本阶段写 `src/` 或跑 delivery-pipeline
-7. 阶段完成后先输出：`门禁结果 + 证据文件路径 + 下一步命令`；严格SOP模式下等待用户确认再进入阶段 D。
+7. 阶段完成后输出：`门禁结果 + 证据文件路径 + 下一步命令`
+8. **`executionMode=staged-confirm` 时**：等待用户确认后再进入阶段 D；**`full-chain` 时不得停止**
 
-## 阶段 D — `/opsx-apply`（ac-ready 后**立即**执行，无需再等用户）
+## 阶段 D — `/opsx-apply`（ac-ready 后执行）
 
-> 严格SOP模式下，本阶段不允许“立即执行”，必须先获得用户确认。
+> `full-chain`：**立即**执行，无需再等用户。`staged-confirm`：须先获得用户确认。
 
 1. `npx sdd-flow-kit ensure-opsx --agent cursor -y`（仓库根）
-2. 写 `.opsx-active-change` = change 名
-3. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`
-4. 读并执行：`openspec-apply-change` → `tdd-script`（分层测试策略）→ `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
-5. Red 断言须写死 PRD/05 原文（toast、tooltip、列序等）
-6. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
+2. `npx sdd-flow-kit phase advance --to impl --change <name>`
+3. 写 `.opsx-active-change` = change 名
+4. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`
+5. 读并执行：`openspec-apply-change` → `tdd-script`（分层测试策略）→ `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
+6. Red 断言须写死 PRD/05 原文（toast、tooltip、列序等）
+7. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
 
 ## 阶段 E — PRD 一致性复查 + 脚本语义 diff + 强制验收（交付前）
 
@@ -53,6 +76,7 @@
 3. `npx sdd-flow-kit prd-diff --project-root <repo> --run-id <runId>`（脚本 PRD×代码字面量 diff → `09-PRD语义diff报告.md`）
 4. 若 diff 失败：`prd-remediate --change <name>` 或 `validate` 内置循环（按 09 调 `/opsx-apply` 修，**每项最多 3 次**、每轮只修剩余失败项，重试附带上次错误代码摘要；仍失败 → 08 待人工确认）
 5. `npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect prd-coverage`
+6. 机械串联（AI 步骤完成后）：`npx sdd-flow-kit chain --from validate-done --change <name>`
 
 ## 完成判定
 

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

@@ -98,20 +98,21 @@
 #### 路径 B：交付模式 (矛盾点池已闭合)
 > **触发条件**：用户已回复待确认点，或明确表示矛盾点池已闭合（不得在未获用户确认时自行进入）。
 
-**任务（本路径仅文档，不含 openspec，不含写代码）**：
+**任务（阶段 B 文档产出；`full-chain` 模式下不得在本路径结束回合）**：
 1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
 2.  **从 `source/PRD.md` 生成 `05-验收清单.md`**（标注「定义状态：已定义」），再生成 `04-技术文档草稿.md`（引用 AC-ID）。
 3.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
 4.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
 5.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
-6.  更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
-7.  **若 `autoChainOpsx !== false`（默认）且用户未说「只提案」**：同一回合继续读 `07-opsx-自动串联指引.md`，执行 `/opsx-propose`（输入 **05+04+02**+UI）→ `/opsx-apply`；**不要**要求用户再说「继续」。
-8.  仅当 `autoChainOpsx === false` 时输出：`05/01/02/03/04 已更新。回复「继续」进入提案。`
-9.  若用户已声明「执行模式：严格SOP，不可替代」：本路径必须改为“阶段确认制”：
+6.  更新 `.session-state.json`：`status: ready_for_propose`；若用户口令含执行模式，同步 `executionMode` / `strictCommands`。
+7.  执行 `gate docs-closed` → `phase advance --to docs-done`（exit 0 才继续）。
+8.  **若 `autoChainOpsx !== false` 且 `executionMode !== staged-confirm`（默认 full-chain）**：**不得结束回合**，同一回合继续读 `07-opsx-自动串联指引.md`，执行 C→D→E 直至 `deliver` exit 0；**不要**要求用户再说「继续」。
+9.  仅当 `autoChainOpsx === false` 时输出：`05/01/02/03/04 已更新。回复「继续」进入提案。`
+10. **`executionMode=staged-confirm` 时**（含兼容口令「严格SOP，不可替代」）：
     - 每阶段执行前先输出：`本次计划命令清单（逐条）`
     - 每阶段执行后输出：`门禁结果 + 证据文件路径 + 下一步命令`
     - 等待用户确认后再进入下一阶段
-    - 禁止用等价命令替代用户指定命令链路
+11. **`strictCommands=true` 时**：禁止用等价命令替代 NEXT.md 中的 gate/phase 链路（可与 full-chain 组合，不强制每阶段暂停）
 
 ---
 

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

@@ -24,6 +24,17 @@ alwaysApply: true
    - `npx sdd-flow-kit phase advance --to impl` + `gate --expect impl-allowed`（阶段 D 前）
 4. **禁止**在未执行 `gate prd-coverage`、`gate ac-signed` 与 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
 
+## 禁止过早结束（对称于「禁止过早写代码」）
+
+当 `executionMode=full-chain`（默认）且 `autoChainOpsx !== false`：
+
+- **禁止**在 propose/apply/validate/deliver 未完成前结束回合
+- **禁止**输出仅含「后续待办」「骨架已完成」的收尾
+- 矛盾点闭合后须同一回合继续 C→D→E，直至 `deliver` exit 0
+- 唯一允许暂停：gate exit≠0、prd-remediate 需人工裁定、用户说「只提案」
+
+`executionMode=staged-confirm` 时：每阶段完成后可暂停等人确认。
+
 ## docModeOnly
 
 当 `openspec/PRD/*/.session-state.json` 中 `docModeOnly: true`：
@@ -68,6 +79,8 @@ npx sdd-flow-kit validate --project-root <repo> --run-id <runId> --change <name>
 npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-signed
 npx sdd-flow-kit deliver --project-root <repo> --run-id <runId> --change <name>
 npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to shipped --change <name>
+# 或机械串联（AI 步骤完成后）：
+npx sdd-flow-kit chain --project-root <repo> --run-id <runId> --change <name> --from docs-done
 ```
 
 ## 分层测试（L1–L4）

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

@@ -177,8 +177,10 @@ def href_path_matches_keyword(href: str, keyword: str) -> bool:
 
 
 def text_matches_keyword(text: str, keyword: str) -> bool:
-    """标题/链接文案匹配：忽略 -/_ 差异。"""
-    return normalize_match_token(keyword) in normalize_match_token(text)
+    """标题/链接文案匹配：忽略 -/_ 差异；支持前缀命中（如 ADI_V2.3.4结算…）。"""
+    t_norm = normalize_match_token(text or "")
+    kw_norm = normalize_match_token(keyword)
+    return kw_norm in t_norm or t_norm.startswith(kw_norm)
 
 
 def score_link_match(text: str, href: str, prefix: str, version: str, keyword: str) -> int:
@@ -212,22 +214,34 @@ def score_link_match(text: str, href: str, prefix: str, version: str, keyword: s
     space = env("CONFLUENCE_SPACE", "").lower()
     if space and f"/spaces/{space}/" in href.lower():
         score += 5
+    # ADI/产品 PRD 标题或 URL 含版本号时加权，降低误命中其他空间页面
+    if re.search(r"adi[-_]?v", text, re.IGNORECASE) or re.search(
+        r"adi[-_]?v", unquote(href), re.IGNORECASE
+    ):
+        score += 2
     return score
 
 
 def collect_search_candidates(
     page, base_url: str, prefix: str, version: str, keyword: str
 ) -> list[tuple[str, str, int]]:
-    """返回 [(url, title, score), ...]"""
+    """返回 [(url, title, score), ...]；标题命中或 URL 路径命中均可得分（>=2）。"""
     seen: set[str] = set()
     scored: list[tuple[int, str, str]] = []
+    debug = env_bool("CONFLUENCE_DEBUG")
 
     selectors = [
         ".search-result .title a",
         ".search-result-title a",
         "#search-results .gs-title a",
+        "ol.search-results-list a",
+        ".search-results a",
+        ".search-result a",
+        "#search-results a",
         ".search-results-panel a",
         "a[data-linked-resource-id]",
+        f"a[href*='{keyword}']",
+        f"a:has-text('{keyword}')",
         "a[href*='/pages/']",
         "a[href*='/display/']",
     ]
@@ -235,6 +249,8 @@ def collect_search_candidates(
     for selector in selectors:
         links = page.locator(selector)
         count = min(links.count(), 200)
+        if debug and count:
+            print(f"   [debug] selector={selector!r} count={count}")
         for i in range(count):
             href = links.nth(i).get_attribute("href") or ""
             raw_text = (links.nth(i).inner_text() or "").strip()
@@ -252,6 +268,9 @@ def collect_search_candidates(
             if s >= 2:
                 scored.append((s, full_url, text[:120]))
 
+    if debug and not scored:
+        print("   [debug] 未解析到 score>=2 的 wiki 页面链接")
+
     scored.sort(key=lambda x: x[0], reverse=True)
     return [(u, t, s) for s, u, t in scored]
 
@@ -625,19 +644,36 @@ def try_rest_download(
 
 
 def run_search_dosearch(page, base_url: str, prefix: str, version: str, keyword: str) -> list[tuple[str, str, int]]:
+    """打开 Confluence 全站专用搜索页（dosearchsite），比首页 #all-updates 顶栏搜索更稳定。"""
     url = f"{base_url.rstrip('/')}/dosearchsite.action?queryString={quote(keyword)}"
-    print(f"   → 全站搜索: {url}")
-    try:
-        page.goto(url, wait_until="domcontentloaded", timeout=60000)
-    except Exception:
-        page.goto(url, wait_until="load", timeout=60000)
-    page.wait_for_timeout(2500)
-    if is_login_page(page):
-        return []
+    print(f"   → 专用搜索页: .../dosearchsite.action?queryString={quote(keyword)}")
+    for attempt in range(2):
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=60000)
+        except Exception as exc:
+            # 搜索页常有重定向/长连接，networkidle 易误报 ERR_ABORTED
+            if "ERR_ABORTED" not in str(exc) and "Timeout" not in str(exc):
+                raise
+            if attempt == 0:
+                print("   导航被中断，等待搜索结果页稳定...")
+            try:
+                page.goto(url, wait_until="load", timeout=60000)
+            except Exception:
+                pass
+        page.wait_for_load_state("domcontentloaded", timeout=30000)
+        page.wait_for_timeout(2500)
+        if is_login_page(page):
+            return []
+        current = page.url.lower()
+        on_search = "dosearchsite" in current or "search" in current
+        if on_search or attempt == 1:
+            break
+        print("   未停留在搜索结果页，重试一次...")
     return collect_search_candidates(page, base_url, prefix, version, keyword)
 
 
 def run_search_quick(page, base_url: str, prefix: str, version: str, keyword: str) -> list[tuple[str, str, int]]:
+    """顶栏快速搜索（dosearchsite 无结果时的兜底，非主路径）。"""
     search_selector = None
     for selector in [
         "#quick-search-query",
@@ -653,10 +689,10 @@ def run_search_quick(page, base_url: str, prefix: str, version: str, keyword: st
             break
     if not search_selector:
         return []
-    print(f"   → 顶栏搜索框: {search_selector}  关键词: {keyword}")
+    print(f"   → 顶栏搜索框（兜底）: {search_selector}  关键词: {keyword}")
     page.fill(search_selector, keyword, timeout=8000)
     page.keyboard.press("Enter")
-    page.wait_for_load_state("networkidle", timeout=30000)
+    page.wait_for_load_state("domcontentloaded", timeout=30000)
     page.wait_for_timeout(2500)
     return collect_search_candidates(page, base_url, prefix, version, keyword)
 

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

@@ -60,9 +60,15 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
 5. `ADI_V<版本>结算`（ADI 长标题页，如 V2.3.4 结算对接欢聚）
 
-每个关键词都会走 **dosearchsite 全站搜索** + 顶栏搜索；匹配时忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时 **标题或 URL 路径** 任一命中即可，并忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
 
-## 直链（跳过搜索）
+调试搜索解析：
+
+```bash
+CONFLUENCE_DEBUG=1 python3 confluence-doc.py ADI_V2.3.4
+```
+
+## 直链（可选，跳过搜索）
 
 ```bash
 CONFLUENCE_PAGE_ID=109609740 python3 confluence-doc.py 2.3.4
@@ -88,6 +94,6 @@ CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/..
 - 脚本：`docs/{{SKILL_DIR}}/confluence-doc.py`
 - 脚本已内置默认账号密码；如需使用其他账号可用环境变量覆盖
 - 默认 Confluence 地址为 `https://confluence.huan.tv`（可用 `CONFLUENCE_BASE_URL` 覆盖）
-- 默认搜索入口为 `https://confluence.huan.tv/#all-updates`（可用 `CONFLUENCE_SEARCH_URL` 覆盖）
+- 搜索主路径为 `dosearchsite.action?queryString=<关键词>`（全站专用搜索页）
 - 脚本会自动尝试读取仓库根目录的 `.env.pre` / `.env` / `.env.local` / `.env.development` / `.env.test`（若其中存在 `CONFLUENCE_*` 配置可直接复用）