sdd-flow-kit 1.3.13 → 1.3.15

package/dist/cli.js

@@ -22,8 +22,10 @@ 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 runGuard_1 = require("./steps/runGuard");
 const bootstrap_1 = require("./core/bootstrap");
 const projectRoots_1 = require("./core/projectRoots");
+const versionIntent_1 = require("./core/versionIntent");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
 function getArgValue(flag) {
     const idx = process_1.default.argv.indexOf(flag);
@@ -34,6 +36,42 @@ function getArgValue(flag) {
         return null;
     return v;
 }
+function getFreeTextArgs(startIndex) {
+    const flagsWithValue = new Set([
+        "--agent",
+        "--project",
+        "--product",
+        "--version",
+        "--project-root",
+        "--projectRoot",
+        "--run-id",
+        "--runId",
+        "--change",
+        "--branch",
+        "--from",
+        "--to",
+        "--expect",
+        "--execution-mode",
+        "--executionMode",
+        "--text",
+    ]);
+    const parts = [];
+    const tokens = process_1.default.argv.slice(startIndex);
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "-y" || token === "--dry-run" || token === "--plan-json" || token === "--strict-commands") {
+            continue;
+        }
+        if (flagsWithValue.has(token)) {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--"))
+            continue;
+        parts.push(token);
+    }
+    return parts.join(" ").trim();
+}
 function printHelp() {
     // eslint-disable-next-line no-console
     console.log([
@@ -51,7 +89,8 @@ function printHelp() {
         "3) 生成骨架并进入可执行模式（推荐）：",
         "   npx sdd-flow-kit run --product ADI --version 2.3.2 --agent claude-code",
         "",
-        "4) 一句话触发（可选能力）：",
+        "4) 一句话触发（版本开发强制入口）：",
+        "   npx sdd-flow-kit guard \"开发 ADI_V2.3.4版本\" -y --agent cursor",
         "   npx sdd-flow-kit invoke \"开发 XXX 1.2.3 需求\"",
         "",
         "5) 环境健检：",
@@ -111,7 +150,7 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
@@ -144,6 +183,7 @@ async function main() {
         cmd !== "install" &&
         cmd !== "doctor" &&
         cmd !== "ensure-opsx" &&
+        cmd !== "guard" &&
         cmd !== "invoke" &&
         cmd !== "gate" &&
         cmd !== "phase" &&
@@ -169,7 +209,11 @@ async function main() {
     const dryRun = process_1.default.argv.includes("--dry-run");
     const planJson = process_1.default.argv.includes("--plan-json");
     const agentValue = (_g = getArgValue("--agent")) !== null && _g !== void 0 ? _g : "claude-code";
-    const projectKind = ((_h = getArgValue("--project")) !== null && _h !== void 0 ? _h : "OMS");
+    const rawGuardText = cmd === "guard"
+        ? ((_h = getArgValue("--text")) !== null && _h !== void 0 ? _h : getFreeTextArgs(3)).trim()
+        : "";
+    const guardIntent = rawGuardText ? (0, versionIntent_1.parseVersionIntent)(rawGuardText) : null;
+    const projectKind = ((_k = (_j = getArgValue("--project")) !== null && _j !== void 0 ? _j : guardIntent === null || guardIntent === void 0 ? void 0 : guardIntent.product) !== null && _k !== void 0 ? _k : "OMS");
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -189,6 +233,7 @@ async function main() {
     const bootstrapCommands = new Set([
         "doctor",
         "ensure-opsx",
+        "guard",
         "run",
         "invoke",
         "install",
@@ -211,6 +256,36 @@ async function main() {
             projectKind: projectKind,
         });
     }
+    if (cmd === "guard") {
+        const text = rawGuardText;
+        if (!text) {
+            // eslint-disable-next-line no-console
+            console.error("guard 需要自然语言文本，例如：npx sdd-flow-kit guard \"开发 ADI_V2.3.4版本\" -y --agent cursor");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runGuard_1.runGuard)({
+            text,
+            projectRoot,
+            branch,
+            yes,
+            dryRun,
+            agent,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `ℹ️ ${result.detail}`);
+        if (result.ok && result.nextPath) {
+            // eslint-disable-next-line no-console
+            console.log(`下一步：读取 ${result.nextPath} 与同目录 .session-state.json`);
+        }
+        if (planJson) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({ command: "guard", projectRoot, dryRun, result }, null, 2));
+        }
+        if (!result.ok)
+            process_1.default.exitCode = 2;
+        return;
+    }
     if (cmd === "gate") {
         const expect = getArgValue("--expect");
         if (!expect || !GATE_EXPECTS.includes(expect)) {
@@ -376,7 +451,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const from = ((_j = getArgValue("--from")) !== null && _j !== void 0 ? _j : "docs-done");
+        const from = ((_l = getArgValue("--from")) !== null && _l !== void 0 ? _l : "docs-done");
         if (!CHAIN_FROM.includes(from)) {
             // eslint-disable-next-line no-console
             console.error(`chain 需要 --from ${CHAIN_FROM.join("|")}`);
@@ -405,7 +480,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const modeArg = (_k = getArgValue("--execution-mode")) !== null && _k !== void 0 ? _k : getArgValue("--executionMode");
+        const modeArg = (_m = getArgValue("--execution-mode")) !== null && _m !== void 0 ? _m : getArgValue("--executionMode");
         const textArg = getArgValue("--text");
         const strictCommands = process_1.default.argv.includes("--strict-commands");
         const result = await (0, runSessionMode_1.runSessionMode)({
@@ -474,11 +549,7 @@ async function main() {
     }
     if (!product || !version) {
         if (cmd === "invoke") {
-            const raw = process_1.default.argv
-                .slice(3)
-                .filter((token) => !token.startsWith("--") && token !== "-y")
-                .join(" ")
-                .trim();
+            const raw = getFreeTextArgs(3);
             const fromFlag = getArgValue("--text");
             const text = (fromFlag !== null && fromFlag !== void 0 ? fromFlag : raw).trim();
             const parsed = (0, invokeFlow_1.parseInvokeText)(text);

package/dist/core/prdArtifacts.js

@@ -16,6 +16,31 @@ const PRD_PLACEHOLDER_MARKERS = [
     "占位",
     "placeholder",
 ];
+const PRD_TECHNICAL_TITLE_MARKERS = [
+    "技术文档",
+    "技术方案",
+    "详细设计",
+    "接口文档",
+    "后端",
+    "数据库",
+    "实现文档",
+    "设计文档",
+    "开发文档",
+];
+/**
+ * 判断 PRD 标题是否属于技术/后端/设计类文档，避免错误进入需求分析链路。
+ */
+function hasForbiddenPrdTitle(title) {
+    const upper = (title || "").toUpperCase();
+    return PRD_TECHNICAL_TITLE_MARKERS.some((marker) => upper.includes(marker.toUpperCase()));
+}
+/**
+ * 从 Markdown 主标题读取 Confluence 页面标题，作为 prd-fetched 的类型校验入口。
+ */
+function extractPrdTitle(content) {
+    var _a, _b;
+    return (_b = (_a = content.split("\n").find((line) => line.trim().startsWith("# "))) === null || _a === void 0 ? void 0 : _a.replace(/^#\s*/, "").trim()) !== null && _b !== void 0 ? _b : "";
+}
 async function isPrdFetched(outputRoot) {
     const prdPath = path_1.default.join(outputRoot, "source", "PRD.md");
     const content = await (0, fs_1.readFileIfExists)(prdPath);
@@ -25,6 +50,10 @@ async function isPrdFetched(outputRoot) {
     if (PRD_PLACEHOLDER_MARKERS.some((m) => content.includes(m))) {
         return { ok: false, detail: "source/PRD.md 仍为占位内容，请先执行 Step1 拉取 PRD" };
     }
+    const title = extractPrdTitle(content);
+    if (title && hasForbiddenPrdTitle(title)) {
+        return { ok: false, detail: `source/PRD.md 命中技术文档标题: ${title}` };
+    }
     return { ok: true, detail: "PRD 已回填" };
 }
 async function isQuestionsClosed(outputRoot) {

package/dist/core/versionIntent.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVersionIntent = parseVersionIntent;
+exports.normalizeProductName = normalizeProductName;
+exports.isVersionDevelopmentIntent = isVersionDevelopmentIntent;
+exports.getVersionIntentInvokeCommand = getVersionIntentInvokeCommand;
+/**
+ * 解析“开发某产品某版本”的自然语言意图。
+ * 该解析器只负责提取产品与版本，不承担后续流程执行。
+ */
+function parseVersionIntent(text) {
+    const normalized = text.trim();
+    if (!normalized)
+        return null;
+    const normalizedText = normalized
+        .replace(/[：:，,。；;！!？?]/g, " ")
+        .replace(/[_-]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const patterns = [
+        /(?:开发|进行|实现|处理|做)\s*([\u4e00-\u9fa5A-Za-z][\u4e00-\u9fa5A-Za-z\s]*?)\s*[Vv]?\s*([0-9]+(?:\.[0-9]+){1,3})\s*(?:版本|需求|PRD)?/i,
+        /([\u4e00-\u9fa5A-Za-z][\u4e00-\u9fa5A-Za-z\s]*?)\s*[Vv]?\s*([0-9]+(?:\.[0-9]+){1,3})\s*(?:版本|需求)?\s*(?:开发|进行|实现|处理|做)?/i,
+    ];
+    for (const re of patterns) {
+        const match = normalizedText.match(re);
+        if (!match)
+            continue;
+        const product = normalizeProductName(match[1]);
+        const version = match[2];
+        if (!product || !version)
+            continue;
+        return { product, version };
+    }
+    return null;
+}
+function normalizeProductName(raw) {
+    const value = raw
+        .replace(/\b(PRD|需求|版本|开发|进行|实现|处理|做)\b/gi, " ")
+        .replace(/需求|版本|开发|进行|实现|处理|做/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!value)
+        return "";
+    const upper = value.toUpperCase();
+    if (upper === "ADI" || /ADINSIGHT/i.test(value))
+        return "ADI";
+    if (upper === "OMS" || /OPERATION/i.test(value))
+        return "OMS";
+    if (/BREAK\s*X/i.test(value) || /BREAKX/i.test(value))
+        return "BreakX";
+    if (/欢盟|HUANMENG|HM/i.test(value))
+        return "欢盟";
+    if (/AD\s*TOOLS/i.test(value) || /ADTOOLS/i.test(value))
+        return "AD Tools";
+    return value;
+}
+function isVersionDevelopmentIntent(text) {
+    return parseVersionIntent(text) !== null;
+}
+function getVersionIntentInvokeCommand(options) {
+    const parsed = parseVersionIntent(options.rawText);
+    if (!parsed)
+        return null;
+    return `npx sdd-flow-kit invoke "开发 ${parsed.product} ${parsed.version} 需求" -y --agent ${options.agent}`;
+}

package/dist/core/writeNext.js

@@ -35,7 +35,7 @@ async function writeInitialNext(outputRoot, projectRoot, runId) {
         "| `tasks.md` | AC 的可执行映射（`[AC-XX]`） |",
         "",
         "## 1. Step1 — 拉取 PRD",
-        "按 `01-获取需求文档指引.md` 执行 confluence 脚本，然后：",
+        "按 `01-获取需求文档指引.md` 执行 confluence 脚本；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
         "```bash",
         `npx sdd-flow-kit gate --project-root "${pr}" --run-id ${runId} --expect prd-fetched`,
         `npx sdd-flow-kit phase advance --project-root "${pr}" --run-id ${runId} --to after-prd`,

package/dist/steps/invokeFlow.js

@@ -2,26 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseInvokeText = parseInvokeText;
 exports.toRunOptions = toRunOptions;
+const versionIntent_1 = require("../core/versionIntent");
 function parseInvokeText(text) {
-    const normalized = text.trim();
-    const patterns = [
-        /(?:开发|进行)\s*(.+?)(?:[-_\s]*)V?([0-9]+(?:\.[0-9]+){1,3})\s*(?:版本)?\s*(?:需求|PRD)?/i,
-        /([A-Za-z\u4e00-\u9fa5]+)[_\s-]?V?([0-9]+(?:\.[0-9]+){1,3})\s*版本/i,
-        /([A-Za-z]+)[_\s-]([0-9]+(?:\.[0-9]+){2,3})(?:\s|$)/i,
-    ];
-    for (const re of patterns) {
-        const match = normalized.match(re);
-        if (!match)
-            continue;
-        let product = match[1].replace(/[-_\s]+$/g, "").trim();
-        product = product.replace(/^进行/, "").trim();
-        if (/^adi$/i.test(product) || product.toUpperCase() === "ADI")
-            product = "ADI";
-        if (/^oms$/i.test(product))
-            product = "OMS";
-        return { product: product.toUpperCase(), version: match[2] };
-    }
-    return null;
+    const parsed = (0, versionIntent_1.parseVersionIntent)(text);
+    if (!parsed)
+        return null;
+    return { product: parsed.product, version: parsed.version };
 }
 function toRunOptions(args) {
     var _a, _b;

package/dist/steps/runGuard.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGuard = runGuard;
+const runFlow_1 = require("./runFlow");
+const invokeFlow_1 = require("./invokeFlow");
+const runSessionMode_1 = require("./runSessionMode");
+/**
+ * 识别“开发产品版本”的自然语言入口，并在命中时直接启动 SDD 流程。
+ * 该守卫用于压过普通 OpenSpec/OPSX 入口，避免版本需求误走自由提案流程。
+ */
+async function runGuard(options) {
+    const text = options.text.trim();
+    const parsed = (0, invokeFlow_1.parseInvokeText)(text);
+    if (!parsed) {
+        return {
+            ok: false,
+            action: "noop",
+            input: text,
+            detail: "未识别到版本开发意图，无需启动 sdd-flow-kit invoke。",
+        };
+    }
+    const runOptions = (0, invokeFlow_1.toRunOptions)({
+        parsed,
+        projectRoot: options.projectRoot,
+        branch: options.branch,
+        yes: options.yes,
+        dryRun: options.dryRun,
+        agent: options.agent,
+    });
+    const result = await (0, runFlow_1.runFlow)(runOptions);
+    if (!options.dryRun) {
+        await (0, runSessionMode_1.applyInvokeTextToSession)(options.projectRoot, result.runId, text);
+    }
+    return {
+        ok: true,
+        action: "invoke",
+        input: text,
+        product: parsed.product,
+        version: parsed.version,
+        runId: result.runId,
+        nextPath: `openspec/PRD/${result.runId}/NEXT.md`,
+        detail: `已识别版本开发意图并启动 SDD 流程：${parsed.product} ${parsed.version} -> runId=${result.runId}`,
+    };
+}

package/dist/steps/setupProject.js

@@ -152,6 +152,28 @@ async function installAgentSkill(projectRoot, projectKind) {
         await (0, fs_1.writeTextFileEnsuredDir)(layeredPath, layered);
     }
 }
+async function installSddVersionTriggerRule(projectRoot, agent) {
+    const template = await (0, templates_1.loadTemplateText)("rules/sdd-version-trigger.mdc.template");
+    const content = renderVars(template, {
+        AGENT_NAME: agent,
+    });
+    if (agent === "cursor" || agent === "custom") {
+        const rulePath = path_1.default.join(projectRoot, ".cursor", "rules", "00-sdd-flow-kit-version-trigger.mdc");
+        await (0, fs_1.writeTextFileEnsuredDir)(rulePath, content);
+    }
+}
+async function installSddVersionTriggerSkills(projectRoot) {
+    const template = await (0, templates_1.loadTemplateText)("skills/version-trigger.SKILL.md.template");
+    const targets = [
+        { agent: "cursor", relPath: ".cursor/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "claude-code", relPath: ".claude/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "codex", relPath: ".codex/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+        { agent: "openclaw", relPath: ".openclaw/skills/00-sdd-flow-kit-version-trigger/SKILL.md" },
+    ];
+    for (const target of targets) {
+        await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(projectRoot, target.relPath), renderVars(template, { AGENT_NAME: target.agent }));
+    }
+}
 async function installSddCursorRule(projectRoot) {
     const rulePath = 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");
@@ -343,6 +365,8 @@ async function setupProject(options) {
         const { dir } = docSkillDirName(selectedKind);
         plannedActions.push(`would install docs skill: ${path_1.default.join(installRoot, "docs", dir)}`);
         plannedActions.push(`would install opsx config: ${path_1.default.join(installRoot, ".opsx", "config.json")}`);
+        plannedActions.push(`would install highest-priority version trigger rule: ${path_1.default.join(installRoot, ".cursor", "rules", "00-sdd-flow-kit-version-trigger.mdc")}`);
+        plannedActions.push("would install cross-agent version trigger skills: cursor/claude-code/codex/openclaw");
         plannedActions.push(`would install cursor rule: ${path_1.default.join(installRoot, ".cursor", "rules", "sdd-flow-kit-gates.mdc")}`);
     }
     else {
@@ -352,6 +376,10 @@ async function setupProject(options) {
             plannedActions.push("added pnpm.onlyBuiltDependencies: sdd-flow-kit");
         }
         await installAgentSkill(installRoot, selectedKind);
+        await installSddVersionTriggerRule(installRoot, selectedAgent);
+        await installSddVersionTriggerSkills(installRoot);
+        plannedActions.push("installed highest-priority version trigger rule (.cursor/rules/00-sdd-flow-kit-version-trigger.mdc)");
+        plannedActions.push("installed cross-agent version trigger skills (cursor/claude-code/codex/openclaw)");
         await installSddCursorRule(installRoot);
         skillInstalled = true;
         await installDocsSkill(installRoot, selectedKind);

package/package.json

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

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

@@ -14,11 +14,17 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
 
-3. 匹配规则：**标题包含关键词或以关键词为前缀**，或 **URL 路径包含关键词**，任一满足即命中（Confluence 列表标题常被截断）。
+3. 匹配规则：先收集 **标题包含关键词或以关键词为前缀**、或 **URL 路径包含关键词** 的候选页，再执行 PRD 类型校验。
 
-4. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+4. PRD 类型校验（强制黑名单）：候选页必须通过脚本内 `is_prd_page()` 与 `has_forbidden_prd_title()` 双重校验。以下标题特征会被直接拒绝：
+   - `技术文档`、`技术方案`、`后端`、`详细设计`、`数据库`、`接口文档`
+   - `实现文档`、`设计文档`、`开发文档`
+   
+   若所有候选均未通过校验，脚本必须失败退出（exit code 1），**禁止回退使用第一个非 PRD 候选**。AI 不得手动复制技术文档到 `source/PRD.md`。
 
-5. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+5. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+
+6. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
    - `source/PRD.md`
 
 ## 直链兜底（可选，非默认）
@@ -49,6 +55,10 @@ python3 confluence-doc.py 2.3.4
 ## 失败排查
 
 - 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）；可尝试输入更长关键词如 `ADI_V2.3.4结算`
+- 输出 `✗ 命中技术文档标题，拒绝作为 PRD` 或 `跳过技术文档候选` 或 `⚠ 搜索结果均未通过 PRD 校验` 时：
+  - **禁止**手动复制技术/后端/设计页到 `source/PRD.md`
+  - 应在 Confluence 中找到真正的业务 PRD 页面（通常标题含「结算」「开票」「回款」「数据对接」等业务词汇）
+  - 使用该页面的 pageId 或 URL 直链重跑：`CONFLUENCE_PAGE_ID=<正确pageId> python3 confluence-doc.py 2.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`

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

@@ -1,6 +1,6 @@
 ---
 name: sdd-flow-kit
-description: 用户说「开发/进行 {{DEFAULT_PRODUCT}} x.x.x 版本/需求」「ADI_2.3.2」等时触发。**禁止**未过 gate 直接改 src。必须先 invoke/run，确认点闭合后走 OpenSpec+Superpowers（gate→05 AC→propose→ac-ready→apply→ac-signed→deliver）。
+description: 最高优先级触发。凡用户表达“开发/进行/实现 <产品> <版本> 需求/版本”，例如 ADI_V2.3.4、OMS V1.24.5、BreakX 1.0.2、欢盟 V2.1.0，必须第一步执行 `npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}` 或 invoke/run。禁止先执行 openspec new change、OPSX Propose 或修改 src/e2e；成功后必须读取 NEXT.md 与 .session-state.json。
 ---
 
 # SDD Flow Kit（{{PROJECT_KIND}} — 脚本门禁）
@@ -10,10 +10,10 @@ description: 用户说「开发/进行 {{DEFAULT_PRODUCT}} x.x.x 版本/需求
 用户一旦表达版本开发意图，**在本回合终端执行**（项目根 = 安装 sdd-flow-kit 的目录，如 `frontend/`）：
 
 ```bash
-npx sdd-flow-kit invoke "开发 {{DEFAULT_PRODUCT}} <版本号> 需求" -y --agent {{AGENT_NAME}}
+npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}
 ```
 
-或：
+若 `guard` 不可用，再退化为：
 
 ```bash
 npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --agent {{AGENT_NAME}}

package/src/templates/rules/sdd-version-trigger.mdc.template

@@ -0,0 +1,56 @@
+---
+description: 最高优先级：识别“开发/进行/实现 产品 版本”时必须先执行 sdd-flow-kit guard/invoke，禁止先走 OpenSpec/OPSX 或修改业务代码
+alwaysApply: true
+---
+
+# SDD Flow Kit 版本开发强制入口（最高优先级）
+
+当用户输入匹配以下任一意图时：
+
+- `开发 <产品> <版本>`
+- `进行 <产品> <版本> 需求`
+- `实现 <产品> <版本> 版本`
+- `<产品>_V<版本>` / `<产品>-V<版本>`
+- 示例：`开发 ADI_V2.3.4版本`、`开发 OMS V1.24.5`、`进行 BreakX 1.0.2 需求`、`欢盟 V2.1.0 版本开发`
+
+## 第一动作（必须）
+
+必须先执行：
+
+```bash
+npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}
+```
+
+若无法使用 `guard`，退化为：
+
+```bash
+npx sdd-flow-kit invoke "开发 <产品> <版本> 需求" -y --agent {{AGENT_NAME}}
+```
+
+## 严格禁止
+
+在 `guard/invoke` 成功前，禁止：
+
+- 创建 `openspec/changes/**`
+- 执行 `openspec new change`
+- 执行 OPSX / OpenSpec Propose
+- 修改 `src/**`、`frontend/src/**`、`e2e/**`
+- 用自然语言计划替代脚本入口
+
+## 成功后继续
+
+`guard/invoke` 成功后，必须读取并遵循：
+
+- `openspec/PRD/<runId>/NEXT.md`
+- `openspec/PRD/<runId>/.session-state.json`
+
+若 `.session-state.json` 中 `docModeOnly=true`，仍然禁止修改业务代码，直到 `gate docs-closed`、`gate ac-ready`、`phase impl` 与 `gate impl-allowed` 全部通过。
+
+## 优先级
+
+本规则优先于普通 OpenSpec/OPSX 自然语言需求入口：
+
+```text
+版本开发意图 → sdd-flow-kit guard/invoke → NEXT.md
+普通代码需求 → OPSX/OpenSpec
+```

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

@@ -292,10 +292,36 @@ def read_breadcrumb_text(page) -> str:
     return " > ".join(parts)
 
 
+PRD_TECHNICAL_TITLE_MARKERS = (
+    "技术文档",
+    "技术方案",
+    "详细设计",
+    "接口文档",
+    "后端",
+    "数据库",
+    "实现文档",
+    "设计文档",
+    "开发文档",
+    "API文档",
+    "数据结构",
+    "表设计",
+)
+
+
+def has_forbidden_prd_title(title: str) -> bool:
+    """技术文档/后端设计页必须在 PRD 拉取阶段直接拦截。"""
+    title_upper = (title or "").upper()
+    return any(marker.upper() in title_upper for marker in PRD_TECHNICAL_TITLE_MARKERS)
+
+
 def is_adi_requirement_page(title: str, crumbs: str, page_url: str) -> bool:
     """ADI 需求页常无 PRD 字样，标题形如 ADI_V2.3.4结算、开票、回款数据对接欢聚。"""
     title_upper = (title or "").upper()
     crumbs_upper = (crumbs or "").upper()
+
+    if has_forbidden_prd_title(title):
+        print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+        return False
     if re.search(r"ADI[_-]?V\d+\.\d+\.\d+", title_upper):
         print(f"      ✓ ADI 版本标题命中: {title[:80]}")
         return True
@@ -326,6 +352,10 @@ def is_prd_page(page, page_url: str) -> bool:
     except Exception:
         title = ""
 
+    if has_forbidden_prd_title(title):
+        print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+        return False
+
     # ADI：标题常无「PRD/需求」字样，单独识别
     if prefix == "ADI" and is_adi_requirement_page(title, crumbs, page_url):
         return True
@@ -445,7 +475,9 @@ def rest_search_candidates(
     for item in data.get("results", []):
         title = (item.get("title") or "").strip()
         page_id = str(item.get("id", ""))
-        if not page_id:
+        if not page_id or has_forbidden_prd_title(title):
+            if title and has_forbidden_prd_title(title):
+                print(f"   跳过技术文档候选: {title[:80]}")
             continue
         href = f"/spaces/{(item.get('space') or {}).get('key', '')}/pages/{page_id}/"
         score = score_link_match(title, href, prefix, version, keyword)
@@ -462,10 +494,13 @@ def rest_resolve_target(
     direct_id = resolve_direct_page_id()
     if direct_id:
         page = rest_fetch_page(base_url, token, direct_id)
+        if has_forbidden_prd_title(page["title"]):
+            print(f"❌ 直链页面不是业务 PRD，命中技术文档黑名单: {page['title']}")
+            print("   请确认提供的 pageId 是业务需求文档，而非技术文档/后端设计文档")
+            raise RuntimeError(f"直链页面不是 PRD，命中技术文档标题: {page['title']}")
         kw = keywords[0] if keywords else f"{prefix}_V{version}"
         return page["id"], page["title"], kw, page["url"]
 
-    fallback: tuple[str, str, str, str] | None = None
     for kw in keywords:
         print(f"\n🔍 [REST] 搜索: {kw}")
         candidates = rest_search_candidates(base_url, token, prefix, version, kw)
@@ -475,17 +510,25 @@ def rest_resolve_target(
         for score, page_id, title in candidates:
             print(f"   候选 (score={score}): {title[:80]}")
             page = rest_fetch_page(base_url, token, page_id)
-            if prefix.upper() == "ADI" and is_adi_title_match(title, version):
+            # 双重校验：标题黑名单 + ADI 特殊规则
+            if has_forbidden_prd_title(page["title"]):
+                print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {page['title'][:80]}")
+                continue
+            if prefix.upper() == "ADI" and is_adi_title_match(page["title"], version):
+                print(f"      ✓ ADI 业务 PRD 命中")
                 return page_id, page["title"], kw, page["url"]
             if score >= 4:
                 return page_id, page["title"], kw, page["url"]
-            if fallback is None:
-                fallback = (page_id, page["title"], kw, page["url"])
-    return fallback
+    print("   ⚠ REST 搜索结果均未通过 PRD 校验")
+    print("      → 所有候选页面要么是技术/后端/设计文档，要么评分不足")
+    print("      → 不回退到非 PRD 候选；请确认业务需求文档的 pageId")
+    return None
 
 
 def is_adi_title_match(title: str, version: str) -> bool:
     """ADI 长标题页识别（面包屑可无 PRD 字样）。"""
+    if has_forbidden_prd_title(title):
+        return False
     title_upper = (title or "").upper()
     v_compact = version.replace(".", "")
     if re.search(rf"ADI[_-]?V{re.escape(version)}", title_upper):
@@ -702,7 +745,6 @@ def resolve_prd_target(
 ) -> tuple[str | None, str | None, str]:
     """依次用每个关键词搜索，直到找到父级为 PRD 的页面。"""
     seen_urls: set[str] = set()
-    fallback: tuple[str, str, str] | None = None  # url, title, keyword
 
     for kw in keywords:
         print(f"\n🔍 搜索关键词: {kw}")
@@ -720,15 +762,16 @@ def resolve_prd_target(
                     continue
                 seen_urls.add(url)
                 print(f"    · 候选: {title[:70]}")
+                # 先执行标题级黑名单快速拒绝
+                if has_forbidden_prd_title(title):
+                    print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+                    continue
                 if is_prd_page(page, url):
                     return url, kw, title
-                if fallback is None:
-                    fallback = (url, kw, title)
 
-    if fallback:
-        url, kw, title = fallback
-        print(f"   ⚠ 未找到 PRD 父级，回退使用: {title[:70]}")
-        return url, kw, title
+    print("   ⚠ 搜索结果均未通过 PRD 校验")
+    print("      → 所有候选页面要么是技术/后端/设计文档，要么面包屑不含 PRD 父级")
+    print("      → 不回退到非 PRD 候选；请确认业务需求文档的 Confluence 标题与 pageId")
     return None, None, ""
 
 
@@ -919,8 +962,12 @@ def main():
             return
 
     print("\n❌ PRD 拉取失败：Playwright 与 REST 均未成功。")
-    print("   排查：CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 有头模式观察登录")
-    print("   或直链：CONFLUENCE_PAGE_ID=<pageId> python3 confluence-doc.py <版本>")
+    print("   排查：")
+    print("     1. CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 有头模式观察登录与搜索结果")
+    print("     2. 到 Confluence 确认业务 PRD 页面的准确标题与 pageId")
+    print("     3. 若搜索命中了技术/后端/设计文档，这些已被黑名单拒绝")
+    print("     4. 使用业务 PRD 的直链重跑：CONFLUENCE_PAGE_ID=<pageId> python3 confluence-doc.py <版本>")
+    print("     5. 禁止手动复制非 PRD 页面到 source/PRD.md")
     sys.exit(1)
 
 
@@ -976,23 +1023,42 @@ def _download_via_playwright(
                     print(f"   已保存调试截图: {debug_path}")
                 except Exception:
                     pass
-                print(f"❌ 未找到 {prefix} {version} 的需求文档。")
+                print(f"❌ 未找到 {prefix} {version} 的业务需求文档（PRD）。")
                 print(
                     "   排查：1) 页面标题是否含 ADI_V2.3.4（下划线，非 ADI-V）及中文后缀"
                 )
                 print(
                     "   2) 依次尝试 ADI_V2.3.4 / ADI-V2.3.4 / ADI_V2.3.4结算 / V2.3.4"
                 )
-                print("   3) 直链：CONFLUENCE_PAGE_ID=109609740 或 CONFLUENCE_PAGE_URL=<完整URL>")
-                print("   4) ADI 页面包屑可能无 PRD 字样，脚本已按 ADI_V* 标题规则识别")
+                print("   3) 若搜索命中了「技术文档」「后端」「详细设计」等页面，这些已被黑名单自动拒绝")
+                print("   4) 直链解决：CONFLUENCE_PAGE_ID=<正确pageId> 或 CONFLUENCE_PAGE_URL=<完整URL>")
+                print("   5) ADI 页面包屑可能无 PRD 字样，脚本已按 ADI_V* 标题规则识别")
+                print("   6) 禁止手动复制技术文档到 source/PRD.md，必须找到真正的业务 PRD")
                 return False
 
             print(f"✅ 命中关键词: {matched_keyword}")
             if matched_title:
                 print(f"   页面: {matched_title[:100]}")
             print(f"   URL: {target_url[:120]}...")
+            
+            # 直链模式下也需检查标题黑名单
+            if direct_url:
+                page.goto(target_url, wait_until="domcontentloaded", timeout=60000)
+                try:
+                    direct_title = page.locator("#title-text").text_content().strip()
+                    if has_forbidden_prd_title(direct_title):
+                        print(f"❌ 直链页面不是业务 PRD，命中技术文档黑名单: {direct_title}")
+                        print("   请确认提供的 pageId/URL 是业务需求文档，而非技术文档/后端设计文档")
+                        raise RuntimeError("直链页面命中技术文档标题，拒绝作为 PRD")
+                except Exception as e:
+                    if "技术文档" in str(e) or "黑名单" in str(e):
+                        raise
+            
             page.goto(target_url, wait_until="networkidle", timeout=60000)
 
+            if not is_prd_page(page, target_url):
+                raise RuntimeError("命中的页面未通过 PRD 校验，疑似技术文档或设计文档")
+
             try:
                 title = page.locator("#title-text").text_content().strip()
             except Exception:

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

@@ -2,7 +2,7 @@
 name: {{SKILL_NAME}}
 description: |
   当用户说「获取 {{PRODUCT}} Vx.y.z 需求文档」「下载 {{PRODUCT}}-Vx.y.z PRD」「查询 {{PRODUCT}} x.y.z 版本需求」时触发。
-  自动从 Confluence 搜索对应版本 PRD 页面，下载图片并生成 Markdown 到本仓库 `docs/`。
+  自动从 Confluence 搜索对应版本 PRD 页面；`技术文档`、`后端`、`详细设计` 类页面会被拒绝，避免误下载为 PRD；下载图片并生成 Markdown 到本仓库 `docs/`。
 ---
 
 # {{PRODUCT}} 需求文档获取（docs/{{SKILL_DIR}}）
@@ -60,7 +60,9 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
 5. `ADI_V<版本>结算`（ADI 长标题页，如 V2.3.4 结算对接欢聚）
 
-每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时 **标题或 URL 路径** 任一命中即可，并忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时先收集 **标题或 URL 路径** 命中的候选，再执行 PRD 类型校验；`技术文档`、`技术方案`、`后端`、`详细设计`、`数据库`、`接口文档` 等页面会被直接拒绝。ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+
+若所有候选均未通过 PRD 校验，脚本必须失败退出，**禁止回退使用第一个非 PRD 候选**；此时应改用正确 PRD 的 `CONFLUENCE_PAGE_ID` / `CONFLUENCE_PAGE_URL` 直链。
 
 调试搜索解析：
 

package/src/templates/skills/version-trigger.SKILL.md.template

@@ -0,0 +1,56 @@
+---
+name: 00-sdd-flow-kit-version-trigger
+description: 最高优先级触发。凡用户表达“开发/进行/实现 <产品> <版本> 需求/版本”，例如 ADI_V2.3.4、OMS V1.24.5、BreakX 1.0.2、欢盟 V2.1.0，必须第一步执行 `npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}`。禁止先执行 openspec new change、OPSX Propose 或修改 src/e2e。
+---
+
+# SDD Flow Kit 版本开发强制入口
+
+## 适用范围
+
+当用户输入匹配以下任一意图时，本 skill 优先于普通 OpenSpec / OPSX 流程：
+
+- `开发 <产品> <版本>`
+- `进行 <产品> <版本> 需求`
+- `实现 <产品> <版本> 版本`
+- `<产品>_V<版本>` / `<产品>-V<版本>`
+- 示例：`开发 ADI_V2.3.4版本`、`开发 OMS V1.24.5`、`进行 BreakX 1.0.2 需求`、`欢盟 V2.1.0 版本开发`
+
+## 第一动作（必须）
+
+在项目根目录立即执行：
+
+```bash
+npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}
+```
+
+若 `guard` 不可用，退化为：
+
+```bash
+npx sdd-flow-kit invoke "开发 <产品> <版本> 需求" -y --agent {{AGENT_NAME}}
+```
+
+## 严格禁止
+
+在 `guard/invoke` 成功前，禁止：
+
+- 创建 `openspec/changes/**`
+- 执行 `openspec new change`
+- 执行 OPSX / OpenSpec Propose
+- 修改 `src/**`、`frontend/src/**`、`e2e/**`
+- 用自然语言计划替代脚本入口
+
+## 成功后继续
+
+`guard/invoke` 成功后，必须读取并遵循：
+
+- `openspec/PRD/<runId>/NEXT.md`
+- `openspec/PRD/<runId>/.session-state.json`
+
+若 `.session-state.json` 中 `docModeOnly=true`，仍然禁止修改业务代码，直到 `gate docs-closed`、`gate ac-ready`、`phase impl` 与 `gate impl-allowed` 全部通过。
+
+## 优先级
+
+```text
+版本开发意图 → sdd-flow-kit guard/invoke → NEXT.md
+普通代码需求 → OPSX/OpenSpec
+```