sdd-flow-kit 1.3.14 → 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/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/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.14",
+  "version": "1.3.15",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

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/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
+```