sdd-flow-kit 0.1.0

package/README.en.md

@@ -0,0 +1,36 @@
+# sdd-flow-kit
+
+#### Description
+自动化开发流程
+
+#### Software Architecture
+Software architecture description
+
+#### Installation
+
+1.  xxxx
+2.  xxxx
+3.  xxxx
+
+#### Instructions
+
+1.  xxxx
+2.  xxxx
+3.  xxxx
+
+#### Contribution
+
+1.  Fork the repository
+2.  Create Feat_xxx branch
+3.  Commit your code
+4.  Create Pull Request
+
+
+#### Gitee Feature
+
+1.  You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md
+2.  Gitee blog [blog.gitee.com](https://blog.gitee.com)
+3.  Explore open source project [https://gitee.com/explore](https://gitee.com/explore)
+4.  The most valuable open source project [GVP](https://gitee.com/gvp)
+5.  The manual of Gitee [https://gitee.com/help](https://gitee.com/help)
+6.  The most popular members  [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)

package/README.md

@@ -0,0 +1,54 @@
+# sdd-flow-kit
+
+#### 介绍
+跨工具（Cursor Claude Code / OpenClaw / Codex 等）的“SDD 需求分析 + 产物编排”自动化工程骨架。
+
+它把你的 5 步流程拆成可复用的“流程引擎 + 产物模板 + Adapter 适配层”，并在目标项目下生成固定结构的产物文件。
+
+注意：不同 AI 工具在“真正执行 LLM/写入报告”的能力不同；因此当前版本会把第 2 步 SDD 提示词、产物模板与调用指引打通，让你在 Cursor/Claude/Codex/OpenClaw 中直接执行提示词完成内容生成。
+
+#### 软件架构
+软件架构说明
+
+
+#### 安装教程
+
+1.  进入你要开发的项目目录（例如 `adInsight-web` 或任意工程根目录）
+2.  安装（本地/私有 npm 方式均可）：`npm i -D /Users/lixinxin/Desktop/Huanwang/sdd-flow-kit` 或发布后 `npm i -D sdd-flow-kit`
+3.  先初始化环境（默认 `claude-code`）：`npx sdd-flow-kit setup`
+4.  启动：`npx sdd-flow-kit run --product ADI --version 2.3.2`
+5.  预演：`npx sdd-flow-kit run --product ADI --version 2.3.2 --dry-run`
+6.  一句话触发：`npx sdd-flow-kit invoke "开发 ADI 2.3.2 需求"`
+7.  环境健检：`npx sdd-flow-kit doctor --agent claude-code`
+
+#### 使用说明
+
+1.  `setup`：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境
+2.  `start`：创建 `openspec/PRD/<YYYYMMDD>-<product>-<version>/` 并生成 1~5 步所需模板
+3.  `run`：先执行 `setup` 逻辑，再生成流程骨架与 `AUTO-RUN-CHECKLIST.md`
+4.  第 2 步 SDD 循环提示词与第 4/5 步入口文件可直接在 Cursor/Claude/Codex/OpenClaw 使用
+5.  `invoke`：从自然语言解析 product/version，并自动触发 `run`
+6.  `doctor`：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果
+
+#### 当前自动化边界
+
+- 已支持：跨工具统一目录结构、提示词、报告模板、执行清单
+- 已支持：环境检测与按工具自动执行 `npx @lixin5257xxx/opsx-workflow setup ...`
+- 自动化增强：`claude-code` adapter 支持 `claude -p` 自动执行并记录 `AUTO-RUN-LOG.md`（失败自动降级人工）
+
+#### 参与贡献
+
+1.  Fork 本仓库
+2.  新建 Feat_xxx 分支
+3.  提交代码
+4.  新建 Pull Request
+
+
+#### 特技
+
+1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
+2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
+3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
+4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
+5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
+6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)

package/dist/adapters/index.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAdapter = getAdapter;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const fs_1 = require("../core/fs");
+function hasCommand(cmd) {
+    const result = (0, node_child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" });
+    return result.status === 0;
+}
+function createManualAdapter(name, displayName, bins) {
+    return {
+        name,
+        displayName,
+        async checkAvailable() {
+            return bins.some((bin) => hasCommand(bin));
+        },
+        async runFlow() {
+            return false;
+        },
+    };
+}
+async function runClaudeFlow(args) {
+    const hasClaude = hasCommand("claude");
+    if (!hasClaude)
+        return false;
+    const sddPrompt = await (0, fs_1.readFileIfExists)(node_path_1.default.join(args.outputRoot, "02-需求分析提示词.md"));
+    if (!sddPrompt)
+        return false;
+    const prompt = [
+        `你在项目目录内执行需求流程，runId=${args.runId}。`,
+        "请按以下顺序自动完成：",
+        "1) 读取并执行 01-获取需求文档指引.md，完成 source/PRD.md 与 source/接口文档.md 回填（若无法访问外部系统，请保留占位并写明阻塞原因）。",
+        "2) 执行 02-需求分析提示词.md，更新 01-需求分析报告.md、02-改动点清单.md、03-待确认问题清单.md。",
+        "3) 基于 01/02/03 补全 04-技术文档草稿.md。",
+        "4) 更新 05-openspec-提案草稿.md 为可直接用于 openspec+superpowers 的输入。",
+        "完成后输出一句：SDD flow completed",
+        "",
+        "以下是第2步提示词：",
+        sddPrompt,
+    ].join("\n");
+    const commandResult = (0, node_child_process_1.spawnSync)("claude", ["-p", prompt], {
+        cwd: args.outputRoot,
+        encoding: "utf8",
+        env: node_process_1.default.env,
+    });
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(args.outputRoot, "AUTO-RUN-LOG.md"), [
+        "# AUTO-RUN-LOG",
+        "",
+        `agent: claude-code`,
+        `status: ${commandResult.status ?? "unknown"}`,
+        "",
+        "## stdout",
+        commandResult.stdout || "",
+        "",
+        "## stderr",
+        commandResult.stderr || "",
+    ].join("\n"));
+    if (commandResult.status !== 0)
+        return false;
+    return /SDD flow completed/i.test(commandResult.stdout || "");
+}
+function getAdapter(name) {
+    switch (name) {
+        case "cursor":
+            return createManualAdapter("cursor", "Cursor", ["cursor"]);
+        case "claude-code":
+            return {
+                name: "claude-code",
+                displayName: "Claude Code",
+                async checkAvailable() {
+                    return hasCommand("claude");
+                },
+                async runFlow(args) {
+                    return runClaudeFlow(args);
+                },
+            };
+        case "codex":
+            return createManualAdapter("codex", "Codex", ["codex"]);
+        case "openclaw":
+            return createManualAdapter("openclaw", "OpenClaw", ["openclaw"]);
+        default:
+            return createManualAdapter("custom", "Custom Agent", []);
+    }
+}

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const startFlow_1 = require("./steps/startFlow");
+const runFlow_1 = require("./steps/runFlow");
+const utils_1 = require("./core/utils");
+const setupProject_1 = require("./steps/setupProject");
+const doctor_1 = require("./steps/doctor");
+const invokeFlow_1 = require("./steps/invokeFlow");
+const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
+function getArgValue(flag) {
+    const idx = node_process_1.default.argv.indexOf(flag);
+    if (idx === -1)
+        return null;
+    const v = node_process_1.default.argv[idx + 1];
+    if (!v)
+        return null;
+    return v;
+}
+function printHelp() {
+    // eslint-disable-next-line no-console
+    console.log([
+        "sdd-flow-kit 用法：",
+        "",
+        "1) 生成流程产物骨架：",
+        "   npx sdd-flow-kit start --product ADI --version 2.3.2",
+        "",
+        "2) 初始化环境（环境选择 + 分支处理 + opsx 检测安装）：",
+        "   npx sdd-flow-kit setup --agent claude-code",
+        "",
+        "3) 生成骨架并进入可执行模式（推荐）：",
+        "   npx sdd-flow-kit run --product ADI --version 2.3.2 --agent claude-code",
+        "",
+        "4) 一句话触发：",
+        "   npx sdd-flow-kit invoke \"开发 ADI 2.3.2 需求\"",
+        "",
+        "5) 环境健检：",
+        "   npx sdd-flow-kit doctor --agent claude-code",
+        "",
+        "可选参数：",
+        "   --projectRoot <path>   目标项目根目录（默认当前目录）",
+        "   --agent <name>         cursor | claude-code | codex | openclaw | custom（默认 claude-code）",
+        "   --branch <name>        开发分支；不存在会自动创建",
+        "   -y                     非交互模式（使用默认值）",
+        "   --dry-run              预演模式：仅检测并输出计划，不执行写入/安装/切分支",
+        "   --plan-json            输出机器可读 JSON 计划结果",
+        "",
+        "说明：当前版本会生成 openspec/PRD/<runId>/ 下的模板与提示词文件，",
+        "并把“需要你在 Cursor/Claude Code/Codex/OpenClaw 中执行”的任务显式化。",
+    ].join("\n"));
+}
+async function main() {
+    const cmd = node_process_1.default.argv[2];
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        printHelp();
+        return;
+    }
+    if (cmd !== "start" && cmd !== "run" && cmd !== "setup" && cmd !== "doctor" && cmd !== "invoke") {
+        printHelp();
+        node_process_1.default.exitCode = 1;
+        return;
+    }
+    const product = getArgValue("--product");
+    const version = getArgValue("--version");
+    const projectRoot = getArgValue("--projectRoot") ?? node_process_1.default.cwd();
+    const branch = getArgValue("--branch") ?? undefined;
+    const yes = node_process_1.default.argv.includes("-y");
+    const dryRun = node_process_1.default.argv.includes("--dry-run");
+    const planJson = node_process_1.default.argv.includes("--plan-json");
+    const agentValue = getArgValue("--agent") ?? "claude-code";
+    if (!ALLOWED_AGENTS.includes(agentValue)) {
+        // eslint-disable-next-line no-console
+        console.error(`不支持的 --agent: ${agentValue}`);
+        printHelp();
+        node_process_1.default.exitCode = 1;
+        return;
+    }
+    const agent = agentValue;
+    if (cmd === "doctor") {
+        const doctor = await (0, doctor_1.runDoctor)({ projectRoot: node_path_1.default.resolve(projectRoot), agent });
+        // eslint-disable-next-line no-console
+        console.log(`doctor=${doctor.ok ? "ok" : "failed"}, agent=${agent}`);
+        for (const check of doctor.checks) {
+            // eslint-disable-next-line no-console
+            console.log(`[${check.ok ? "OK" : "FAIL"}] ${check.name}: ${check.detail}`);
+        }
+        if (planJson) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({ command: "doctor", projectRoot: node_path_1.default.resolve(projectRoot), result: doctor }, null, 2));
+        }
+        if (!doctor.ok)
+            node_process_1.default.exitCode = 1;
+        return;
+    }
+    if (cmd === "setup") {
+        const result = await (0, setupProject_1.setupProject)({
+            projectRoot: node_path_1.default.resolve(projectRoot),
+            agent,
+            branch,
+            yes,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(`setup 完成：agent=${result.agent}, branch=${result.branch}, setupExecuted=${result.setupExecuted}, dryRun=${dryRun}`);
+        if (result.plannedActions.length > 0) {
+            // eslint-disable-next-line no-console
+            console.log(`planned: ${result.plannedActions.join(" | ")}`);
+        }
+        if (planJson) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({
+                command: "setup",
+                projectRoot: node_path_1.default.resolve(projectRoot),
+                dryRun,
+                result,
+            }, null, 2));
+        }
+        return;
+    }
+    if (!product || !version) {
+        if (cmd === "invoke") {
+            const raw = node_process_1.default.argv
+                .slice(3)
+                .filter((token) => !token.startsWith("--") && token !== "-y")
+                .join(" ")
+                .trim();
+            const fromFlag = getArgValue("--text");
+            const text = (fromFlag ?? raw).trim();
+            const parsed = (0, invokeFlow_1.parseInvokeText)(text);
+            if (!parsed) {
+                throw new Error("invoke 解析失败，请使用：开发 ADI 2.3.2 需求");
+            }
+            const resolvedRoot = node_path_1.default.resolve(projectRoot);
+            const options = (0, invokeFlow_1.toRunOptions)({
+                parsed,
+                projectRoot: resolvedRoot,
+                branch,
+                yes,
+                dryRun,
+                agent,
+            });
+            const result = await (0, runFlow_1.runFlow)(options);
+            // eslint-disable-next-line no-console
+            console.log(`invoke 成功：${parsed.product} ${parsed.version} -> runId=${result.runId}`);
+            if (planJson) {
+                // eslint-disable-next-line no-console
+                console.log(JSON.stringify({ command: "invoke", input: text, parsed, result }, null, 2));
+            }
+            return;
+        }
+        printHelp();
+        node_process_1.default.exitCode = 1;
+        return;
+    }
+    const resolvedRoot = node_path_1.default.resolve(projectRoot);
+    const runId = `${(0, utils_1.formatYYYYMMDD)(new Date())}-${product}-${version}`;
+    if (cmd === "start") {
+        await (0, startFlow_1.startFlowScaffold)({
+            product,
+            version,
+            projectRoot: resolvedRoot,
+        });
+        // eslint-disable-next-line no-console
+        console.log(`已生成 SDD 流程产物骨架：openspec/PRD/${runId}/`);
+        return;
+    }
+    const result = await (0, runFlow_1.runFlow)({
+        product,
+        version,
+        projectRoot: resolvedRoot,
+        agent,
+        branch,
+        yes,
+        dryRun,
+    });
+    if (dryRun) {
+        // eslint-disable-next-line no-console
+        console.log("dry-run 模式：未创建流程文件，仅输出检测与计划。");
+    }
+    // eslint-disable-next-line no-console
+    console.log(`流程已初始化：openspec/PRD/${result.runId}/`);
+    // eslint-disable-next-line no-console
+    console.log(`agent=${result.adapterName}, cli=${result.adapterAvailable ? "detected" : "missing"}, autoExecute=${result.executed ? "yes" : "manual"}`);
+    // eslint-disable-next-line no-console
+    console.log(`branch=${result.branch}, envSetup=${result.setupExecuted ? "installed" : "already-ready"}`);
+    if (result.plannedActions.length > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`planned: ${result.plannedActions.join(" | ")}`);
+    }
+    if (planJson) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify({
+            command: "run",
+            projectRoot: resolvedRoot,
+            dryRun,
+            product,
+            version,
+            result,
+        }, null, 2));
+    }
+}
+main().catch((e) => {
+    // eslint-disable-next-line no-console
+    console.error(e);
+    node_process_1.default.exitCode = 1;
+});

package/dist/core/fs.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFileIfExists = readFileIfExists;
+exports.writeTextFileEnsuredDir = writeTextFileEnsuredDir;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function readFileIfExists(filePath) {
+    try {
+        return await promises_1.default.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        // 仅吞掉文件不存在错误，其它错误需要抛出便于定位问题。
+        if (err && typeof err === "object" && "code" in err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                return null;
+        }
+        throw err;
+    }
+}
+async function writeTextFileEnsuredDir(filePath, content) {
+    await promises_1.default.mkdir(node_path_1.default.dirname(filePath), { recursive: true });
+    await promises_1.default.writeFile(filePath, content, "utf8");
+}

package/dist/core/templates.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTemplateText = loadTemplateText;
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("./fs");
+function resolveCandidatePaths(relPathFromPackageRoot) {
+    // 在 TS 开发态：<pkg>/src/templates/xxx
+    // 在编译态：<pkg>/dist/cli.js -> __dirname=<pkg>/dist，所以 src/templates 要向上找两级
+    const here = __dirname; // src/core/* 或 dist/*
+    const pkgRoot = node_path_1.default.resolve(here, "../.."); // 兼容 src/ 与 dist/
+    return [
+        node_path_1.default.join(pkgRoot, "src", "templates", relPathFromPackageRoot),
+        node_path_1.default.join(pkgRoot, "dist", "templates", relPathFromPackageRoot),
+    ];
+}
+async function loadTemplateText(relPathFromPackageRoot) {
+    const candidates = resolveCandidatePaths(relPathFromPackageRoot);
+    for (const filePath of candidates) {
+        const content = await (0, fs_1.readFileIfExists)(filePath);
+        if (content != null)
+            return content;
+    }
+    throw new Error(`模板文件未找到：${relPathFromPackageRoot}`);
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/utils.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatYYYYMMDD = formatYYYYMMDD;
+exports.ensurePosixRelativePath = ensurePosixRelativePath;
+/**
+ * 生成 YYYYMMDD 字符串，用于 openspec/PRD 目录命名。
+ */
+function formatYYYYMMDD(d) {
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return `${yyyy}${mm}${dd}`;
+}
+function ensurePosixRelativePath(p) {
+    // 用于模板占位符中展示，避免反斜杠导致工具误解析。
+    return p.replaceAll("\\", "/");
+}

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRunOptions = exports.parseInvokeText = exports.runDoctor = exports.setupProject = exports.runFlow = exports.startFlowScaffold = void 0;
+var startFlow_1 = require("./steps/startFlow");
+Object.defineProperty(exports, "startFlowScaffold", { enumerable: true, get: function () { return startFlow_1.startFlowScaffold; } });
+var runFlow_1 = require("./steps/runFlow");
+Object.defineProperty(exports, "runFlow", { enumerable: true, get: function () { return runFlow_1.runFlow; } });
+var setupProject_1 = require("./steps/setupProject");
+Object.defineProperty(exports, "setupProject", { enumerable: true, get: function () { return setupProject_1.setupProject; } });
+var doctor_1 = require("./steps/doctor");
+Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return doctor_1.runDoctor; } });
+var invokeFlow_1 = require("./steps/invokeFlow");
+Object.defineProperty(exports, "parseInvokeText", { enumerable: true, get: function () { return invokeFlow_1.parseInvokeText; } });
+Object.defineProperty(exports, "toRunOptions", { enumerable: true, get: function () { return invokeFlow_1.toRunOptions; } });

package/dist/steps/doctor.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+function hasCommand(cmd) {
+    const out = (0, node_child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" });
+    return out.status === 0;
+}
+async function hasPath(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function agentBin(agent) {
+    if (agent === "claude-code")
+        return "claude";
+    if (agent === "cursor")
+        return "cursor";
+    if (agent === "codex")
+        return "codex";
+    if (agent === "openclaw")
+        return "openclaw";
+    return null;
+}
+async function runDoctor(options) {
+    const checks = [];
+    checks.push({
+        name: "git",
+        ok: hasCommand("git"),
+        detail: "git 命令可用性",
+    });
+    checks.push({
+        name: "npx",
+        ok: hasCommand("npx"),
+        detail: "npx 命令可用性",
+    });
+    const bin = agentBin(options.agent);
+    if (bin) {
+        checks.push({
+            name: `${options.agent}-cli`,
+            ok: hasCommand(bin),
+            detail: `${bin} 命令可用性`,
+        });
+    }
+    checks.push({
+        name: "openspec-dir",
+        ok: await hasPath(node_path_1.default.join(options.projectRoot, "openspec")),
+        detail: "openspec 目录存在性",
+    });
+    const toolDirMap = {
+        cursor: ".cursor",
+        "claude-code": ".claude",
+        codex: ".codex",
+        openclaw: ".openclaw",
+        custom: null,
+    };
+    const expectedDir = toolDirMap[options.agent];
+    if (expectedDir) {
+        checks.push({
+            name: `${options.agent}-dir`,
+            ok: await hasPath(node_path_1.default.join(options.projectRoot, expectedDir)),
+            detail: `${expectedDir} 目录存在性`,
+        });
+    }
+    const ok = checks.every((c) => c.ok);
+    return { ok, checks };
+}

package/dist/steps/invokeFlow.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseInvokeText = parseInvokeText;
+exports.toRunOptions = toRunOptions;
+function parseInvokeText(text) {
+    const normalized = text.trim();
+    const match = normalized.match(/开发\s*([A-Za-z][A-Za-z0-9_-]*)\s*([0-9]+(?:\.[0-9]+){1,3})\s*需求?/i);
+    if (!match)
+        return null;
+    const product = match[1].toUpperCase();
+    const version = match[2];
+    return { product, version };
+}
+function toRunOptions(args) {
+    return {
+        product: args.parsed.product,
+        version: args.parsed.version,
+        projectRoot: args.projectRoot,
+        branch: args.branch,
+        yes: args.yes,
+        dryRun: args.dryRun,
+        agent: args.agent ?? args.parsed.agent ?? "claude-code",
+    };
+}

package/dist/steps/runFlow.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFlow = runFlow;
+const node_path_1 = __importDefault(require("node:path"));
+const adapters_1 = require("../adapters");
+const fs_1 = require("../core/fs");
+const startFlow_1 = require("./startFlow");
+const setupProject_1 = require("./setupProject");
+function buildChecklist(args) {
+    const availability = args.adapterAvailable ? "已检测到" : "未检测到";
+    return [
+        "# AUTO-RUN-CHECKLIST",
+        "",
+        `runId: \`${args.runId}\``,
+        `agent: \`${args.adapterName}\`（${availability}本地 CLI）`,
+        "",
+        "## 你现在可以直接执行",
+        `- 在目标 AI 工具中输入：\`开发 ${args.product} ${args.version} 需求\``,
+        "- 或按 `RUNME.md` 逐步执行。",
+        "",
+        "## 最小闭环检查",
+        "- Step1 完成后：`source/PRD.md` 已回填",
+        "- Step2 提问模式：仅更新 `03-待确认问题清单.md`",
+        "- Step2 交付模式：产出 `01/02` 且标记“矛盾点池状态：已闭合”",
+        "- Step4 完成后：`04-技术文档草稿.md` 已补全",
+        "- Step5 完成后：`05-openspec-提案草稿.md` 已可投喂 openspec",
+        "",
+    ].join("\n");
+}
+async function runFlow(options) {
+    const setup = await (0, setupProject_1.setupProject)({
+        projectRoot: options.projectRoot,
+        agent: options.agent,
+        branch: options.branch,
+        yes: options.yes,
+        dryRun: options.dryRun,
+    });
+    const scaffold = options.dryRun
+        ? {
+            runId: "dry-run-no-files-generated",
+            outputRoot: node_path_1.default.join(options.projectRoot, "openspec", "PRD"),
+        }
+        : await (0, startFlow_1.startFlowScaffold)(options);
+    const adapter = (0, adapters_1.getAdapter)(setup.agent);
+    const adapterAvailable = await adapter.checkAvailable();
+    const executed = options.dryRun
+        ? false
+        : await adapter.runFlow({
+            runId: scaffold.runId,
+            outputRoot: scaffold.outputRoot,
+            product: options.product,
+            version: options.version,
+        });
+    const checklist = buildChecklist({
+        runId: scaffold.runId,
+        outputRoot: scaffold.outputRoot,
+        adapterName: adapter.displayName,
+        adapterAvailable,
+        product: options.product,
+        version: options.version,
+    });
+    if (!options.dryRun) {
+        await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(scaffold.outputRoot, "AUTO-RUN-CHECKLIST.md"), checklist);
+    }
+    return {
+        ...scaffold,
+        adapterName: adapter.displayName,
+        adapterAvailable,
+        executed,
+        branch: setup.branch,
+        setupExecuted: setup.setupExecuted,
+        dryRun: Boolean(options.dryRun),
+        plannedActions: setup.plannedActions,
+    };
+}

package/dist/steps/setupProject.js

@@ -0,0 +1,189 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupProject = setupProject;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_2 = require("node:readline/promises");
+const node_process_1 = __importDefault(require("node:process"));
+const fs_1 = require("../core/fs");
+const EDITOR_CHOICES = ["claude-code", "cursor", "codex", "openclaw"];
+function runGit(args, cwd) {
+    const out = (0, node_child_process_1.spawnSync)("git", args, { cwd, encoding: "utf8" });
+    if (out.status !== 0) {
+        const err = out.stderr?.trim() || out.stdout?.trim() || `git ${args.join(" ")} failed`;
+        throw new Error(err);
+    }
+    return out.stdout.trim();
+}
+function pickDefaultBranch(projectRoot) {
+    try {
+        const current = runGit(["rev-parse", "--abbrev-ref", "HEAD"], projectRoot);
+        if (current && current !== "HEAD")
+            return current;
+    }
+    catch {
+        // ignore and fallback
+    }
+    return "develop";
+}
+function listLocalBranches(projectRoot) {
+    try {
+        const output = runGit(["branch", "--format", "%(refname:short)"], projectRoot);
+        return output
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+async function askAgent(defaultAgent) {
+    if (!node_process_1.default.stdin.isTTY)
+        return defaultAgent;
+    const rl = (0, promises_2.createInterface)({ input: node_process_1.default.stdin, output: node_process_1.default.stdout });
+    const prompt = [
+        "请选择开发环境：",
+        "1) claude-code (default)",
+        "2) cursor",
+        "3) codex",
+        "4) openclaw",
+        "输入编号（回车默认 1）：",
+    ].join("\n");
+    const answer = (await rl.question(`${prompt}\n`)).trim();
+    rl.close();
+    if (!answer)
+        return defaultAgent;
+    const idx = Number(answer);
+    if (Number.isNaN(idx) || idx < 1 || idx > EDITOR_CHOICES.length)
+        return defaultAgent;
+    return EDITOR_CHOICES[idx - 1];
+}
+async function askBranch(defaultBranch) {
+    if (!node_process_1.default.stdin.isTTY)
+        return defaultBranch;
+    const rl = (0, promises_2.createInterface)({ input: node_process_1.default.stdin, output: node_process_1.default.stdout });
+    const answer = (await rl.question(`请输入开发分支（默认 ${defaultBranch}）：\n`)).trim();
+    rl.close();
+    return answer || defaultBranch;
+}
+function isEditorEnvironmentReady(projectRoot, agent) {
+    const checks = {
+        cursor: ["openspec", ".cursor"],
+        "claude-code": ["openspec", ".claude"],
+        codex: ["openspec", ".codex"],
+        openclaw: ["openspec", ".openclaw"],
+        custom: ["openspec"],
+    };
+    const targetPaths = checks[agent] ?? ["openspec"];
+    return Promise.all(targetPaths.map(async (p) => {
+        try {
+            await promises_1.default.access(node_path_1.default.join(projectRoot, p));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })).then((arr) => arr.every(Boolean));
+}
+function buildSetupCommand(projectRoot, agent) {
+    const baseArgs = ["@lixin5257xxx/opsx-workflow", "setup"];
+    if (agent === "cursor") {
+        return {
+            cmd: "npx",
+            args: [...baseArgs, "--editor", "cursor", "--project", projectRoot, "-y"],
+        };
+    }
+    if (agent === "claude-code") {
+        return {
+            cmd: "npx",
+            args: [...baseArgs, "--editor", "claude-code", "-y"],
+        };
+    }
+    if (agent === "openclaw") {
+        return {
+            cmd: "npx",
+            args: [...baseArgs, "--editor", "openclaw", "-y"],
+        };
+    }
+    return {
+        cmd: "npx",
+        args: [...baseArgs, "--editor", "codex", "-y"],
+    };
+}
+function ensureBranch(projectRoot, branch) {
+    const branches = listLocalBranches(projectRoot);
+    if (branches.includes(branch)) {
+        runGit(["checkout", branch], projectRoot);
+        return { branch, created: false };
+    }
+    runGit(["checkout", "-b", branch], projectRoot);
+    return { branch, created: true };
+}
+async function setupProject(options) {
+    const defaultAgent = options.agent ?? "claude-code";
+    const selectedAgent = options.yes ? defaultAgent : await askAgent(defaultAgent);
+    const defaultBranch = options.branch ?? pickDefaultBranch(options.projectRoot);
+    const selectedBranch = options.yes ? defaultBranch : await askBranch(defaultBranch);
+    const plannedActions = [];
+    const branches = listLocalBranches(options.projectRoot);
+    const branchExists = branches.includes(selectedBranch);
+    const branchResult = options.dryRun
+        ? { branch: selectedBranch, created: !branchExists }
+        : ensureBranch(options.projectRoot, selectedBranch);
+    if (options.dryRun) {
+        plannedActions.push(branchExists
+            ? `would checkout existing branch: ${selectedBranch}`
+            : `would create and checkout branch: ${selectedBranch}`);
+    }
+    let environmentReady = await isEditorEnvironmentReady(options.projectRoot, selectedAgent);
+    let setupExecuted = false;
+    if (!environmentReady) {
+        const { cmd, args } = buildSetupCommand(options.projectRoot, selectedAgent);
+        if (options.dryRun) {
+            plannedActions.push(`would run: ${cmd} ${args.join(" ")}`);
+        }
+        else {
+            const ret = (0, node_child_process_1.spawnSync)(cmd, args, {
+                cwd: options.projectRoot,
+                stdio: "inherit",
+                env: node_process_1.default.env,
+            });
+            if (ret.status !== 0) {
+                throw new Error(`环境安装失败：${cmd} ${args.join(" ")}`);
+            }
+            setupExecuted = true;
+            environmentReady = await isEditorEnvironmentReady(options.projectRoot, selectedAgent);
+        }
+    }
+    else if (options.dryRun) {
+        plannedActions.push("environment already ready, no setup needed");
+    }
+    const summary = [
+        "# SETUP-SUMMARY",
+        "",
+        `agent: ${selectedAgent}`,
+        `branch: ${branchResult.branch}`,
+        `branchCreated: ${branchResult.created}`,
+        `environmentReady: ${environmentReady}`,
+        `setupExecuted: ${setupExecuted}`,
+        `dryRun: ${Boolean(options.dryRun)}`,
+        "",
+        "plannedActions:",
+        ...plannedActions.map((x) => `- ${x}`),
+        "",
+    ].join("\n");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(options.projectRoot, ".sdd-flow-kit", "setup-summary.md"), summary);
+    return {
+        agent: selectedAgent,
+        branch: branchResult.branch,
+        branchCreated: branchResult.created,
+        environmentReady,
+        setupExecuted,
+        plannedActions,
+    };
+}

package/dist/steps/startFlow.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startFlowScaffold = startFlowScaffold;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const utils_1 = require("../core/utils");
+const fs_1 = require("../core/fs");
+const templates_1 = require("../core/templates");
+function renderTemplate(template, vars) {
+    let out = template;
+    for (const [k, v] of Object.entries(vars)) {
+        out = out.replaceAll(`{{${k}}}`, v);
+    }
+    return out;
+}
+async function startFlowScaffold(options) {
+    const now = new Date();
+    const runId = `${(0, utils_1.formatYYYYMMDD)(now)}-${options.product}-${options.version}`;
+    const outputRoot = node_path_1.default.join(options.projectRoot, "openspec", "PRD", runId);
+    const sourceDir = node_path_1.default.join(outputRoot, "source");
+    await promises_1.default.mkdir(sourceDir, { recursive: true });
+    // 1) Step1: adi-doc-skill 指引
+    const step1 = await (0, templates_1.loadTemplateText)("artifacts/01-adi-doc-skill-指引.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "01-获取需求文档指引.md"), step1);
+    // source 占位：让第 2 步提示词在任何工具里都能直接读
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(sourceDir, "PRD.md"), [
+        "# source/PRD.md",
+        "",
+        "请把《PRD》markdown 内容粘贴到这里（由 `adi-doc-skill` 下载并回填）。",
+        "",
+        "- 建议：保持原有标题层级与编号。",
+    ].join("\n"));
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(sourceDir, "接口文档.md"), [
+        "# source/接口文档.md",
+        "",
+        "（可选）如果你已经有接口文档，请粘贴到这里；没有也不影响后续 SDD 循环。",
+        "",
+        "- 注意：接口文档中的字段/示例越完整，分析报告越贴近落地。",
+    ].join("\n"));
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(sourceDir, "openspec-knowledge-base-summary.md"), [
+        "# source/openspec-knowledge-base-summary.md",
+        "",
+        "（可选）现有知识库摘要/快速索引，建议由你在执行第 2 步前手动整理。",
+        "",
+        "如果没有这份摘要，你也可以在运行提示词时留空。",
+    ].join("\n"));
+    // 2) Step2: SDD 循环提示词
+    const sddLoopPrompt = await (0, templates_1.loadTemplateText)("prompts/02-sdd-loop-prompt.md");
+    const step2PromptTemplate = await (0, templates_1.loadTemplateText)("artifacts/02-需求分析提示词.template.md");
+    const step2Prompt = renderTemplate(step2PromptTemplate, { SDD_LOOP_PROMPT: sddLoopPrompt });
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "02-需求分析提示词.md"), step2Prompt);
+    // 3) Step2 输出文件占位（由 AI 工具生成并覆盖）
+    const file01Template = await (0, templates_1.loadTemplateText)("artifacts/01-需求分析报告.template.md");
+    const file02Template = await (0, templates_1.loadTemplateText)("artifacts/02-改动点清单.template.md");
+    const file03Template = await (0, templates_1.loadTemplateText)("artifacts/03-待确认问题清单.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "01-需求分析报告.md"), file01Template);
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "02-改动点清单.md"), file02Template);
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "03-待确认问题清单.md"), file03Template);
+    // 4) Step4 技术文档入口（草稿）
+    const techDocTemplate = await (0, templates_1.loadTemplateText)("artifacts/04-技术文档.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "04-技术文档草稿.md"), techDocTemplate);
+    // 5) Step5 openspec 提案入口（草稿）
+    const openspecEntryTemplate = await (0, templates_1.loadTemplateText)("artifacts/05-openspec-提案草稿.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "05-openspec-提案草稿.md"), openspecEntryTemplate);
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, ".session-state.json"), JSON.stringify({
+        product: options.product,
+        version: options.version,
+        runId,
+        outputRoot,
+        status: "step1_prd_prompt_generated",
+        createdAtISO: new Date().toISOString(),
+    }, null, 2));
+    // runDir 自述
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "RUNME.md"), [
+        "# RUNME（SDD 流程执行说明）",
+        "",
+        `本次 runId: \`${runId}\``,
+        "",
+        "## Step 1：获取需求文档（adi-doc-skill）",
+        "请打开 `01-获取需求文档指引.md`，并使用你的 AI 工具执行相应动作，把 PRD/接口文档回填到 `source/`。",
+        "",
+        "## Step 2：执行 SDD 循环并生成 01/02/03 文件",
+        "请打开 `02-需求分析提示词.md`，在 Cursor/Claude Code/Codex/OpenClaw 中执行，并覆盖生成 `01-需求分析报告.md`、`02-改动点清单.md`、`03-待确认问题清单.md`。",
+        "",
+        "## Step 3：人工核验待确认问题",
+        "将 `03-待确认问题清单.md` 收敛为闭环（必要时调整 01/02）。",
+        "",
+        "## Step 4：输出技术文档草稿",
+        "根据 `04-技术文档草稿.md` 完成技术设计说明。",
+        "",
+        "## Step 5：触发 openspec + superpowers 提案",
+        "使用 `05-openspec-提案草稿.md` 作为 openspec 的提案输入入口。",
+    ].join("\n"));
+    return {
+        runId,
+        outputRoot,
+    };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "sdd-flow-kit",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "src/templates",
+    "README.md"
+  ],
+  "bin": {
+    "sdd-flow-kit": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "typescript": "^5.6.3"
+  }
+}
+

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

@@ -0,0 +1,15 @@
+# 01-获取需求文档（adi-doc-skill 指引）
+
+你的步骤 1 目标：从 Confluence 拉取指定需求版本的 Markdown，并落到本目录的 `source/` 下。
+
+## 请执行
+1. 使用你当前 AI 工具（Cursor / Claude Code / Codex / OpenClaw）调用现有的 `adi-doc-skill`。
+2. 命令/动作建议：让工具“获取 ADI 2.3.2 需求文档”（或等价的触发词），并把下载结果写入本目录：
+   - `source/PRD.md`（PRD 主内容）
+   - `source/接口文档.md`（接口文档，如有）
+
+## 成功校验
+- 你应该能在 `source/PRD.md` 看到完整 PRD markdown
+
+（如果你希望自动回填，请在 adapter 中实现对应能力。）
+

package/src/templates/artifacts/01-/351/234/200/346/261/202/345/210/206/346/236/220/346/212/245/345/221/212.template.md

@@ -0,0 +1,22 @@
+# 01-需求分析报告
+
+## 业务概述
+- （在此处总结 PRD 核心目标）
+
+## 现状映射
+- （引用 openspec 中的现有定义/模块说明）
+
+## 差异分析
+- 新增：
+- 修改：
+- 删除：
+
+## 风险评估
+- 技术风险：
+- 兼容性问题：
+- 副作用分析：
+
+---
+
+> 矛盾点池状态：待填写（提问模式/交付模式）
+

package/src/templates/artifacts/02-/346/224/271/345/212/250/347/202/271/346/270/205/345/215/225.template.md

@@ -0,0 +1,8 @@
+# 02-改动点清单
+
+| 文件路径 | 改动类型 (Add/Modify/Delete) | 模块类型 (Component/Store/API) | 依赖关系 | 预估影响 |
+|---|---|---|---|---|
+| （仅代码文件） | Add/Modify/Delete | Component/Store/API | （依赖哪个模块） | （影响范围/风险） |
+
+> 重要约束：本清单仅记录代码文件改动；不包含 `openspec/spec/` 目录下规格文档的改动。
+

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

@@ -0,0 +1,20 @@
+# 02-需求分析提示词（SDD 循环）
+
+你需要在 AI 工具中把以下内容作为“用户输入/提示词”执行：
+
+--- 你将要运行的提示词开始 ---
+
+{{SDD_LOOP_PROMPT}}
+
+--- 你将要运行的提示词结束 ---
+
+## 输入注入（建议做法）
+- 将 `source/PRD.md` 的内容作为 `{{PRD_MARKDOWN}}` 注入
+- 将 `source/接口文档.md` 的内容作为 `{{INTERFACE_DOC_MARKDOWN}}` 注入（没有则忽略）
+- 将 `openspec/` 目录的现有知识库摘要作为 `{{KNOWLEDGE_BASE_SUMMARY}}` 注入（没有则留空或描述为空）
+
+## 输出要求（AI 应该生成的文件）
+- `01-需求分析报告.md`
+- `02-改动点清单.md`
+- `03-待确认问题清单.md`
+

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

@@ -0,0 +1,6 @@
+# 03-待确认问题清单
+
+| 问题类型 (断点/起点缺失/推测缺口) | 问题描述 | 代码位置 (如有) | 建议/待确认项 |
+|---|---|---|---|
+| （断点/起点缺失/推测缺口） | （描述矛盾点） | （引用文件/模块） | （需要用户确认/提供信息） |
+

package/src/templates/artifacts/04-/346/212/200/346/234/257/346/226/207/346/241/243.template.md

@@ -0,0 +1,21 @@
+# 04-技术文档草稿（由第 2/3 步产物生成）
+
+> 使用输入：
+> - `01-需求分析报告.md`
+> - `02-改动点清单.md`
+> - `03-待确认问题清单.md`
+>
+> 说明：请先把第 3 步“提问/待确认”闭环，否则技术设计可能缺失关键约束。
+
+## 总体方案
+- （架构改动概述）
+
+## 模块/页面/接口改动
+- （按 `02-改动点清单.md` 列表逐条描述）
+
+## 关键数据流与状态治理
+- （说明前端状态/服务端状态边界）
+
+## 风险与回滚预案
+- （列出关键风险点与回滚方式）
+

package/src/templates/artifacts/05-openspec-/346/217/220/346/241/210/350/215/211/347/250/277.template.md

@@ -0,0 +1,16 @@
+# 05-openspec-提案入口草稿（由第 2/3/4 步汇总）
+
+> 目标：把技术文档与改动清单聚合为 openspec / superpower 模式可直接使用的提案描述。
+
+## 使用方式
+1. 打开你的 openspec 工作区
+2. 选择（或新建）对应 change
+3. 将本文件中的内容复制给 openspec + superpowers 的“提案输入”
+4. 进入生成 UI 图 + 任务拆解 + 开发阶段
+
+## 输入摘要
+- `01-需求分析报告.md`：已完成
+- `02-改动点清单.md`：已完成（仅代码文件改动）
+- `03-待确认问题清单.md`：已闭环（无悬而未决）
+- `04-技术文档草稿.md`：已完成
+

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

@@ -0,0 +1,84 @@
+### 角色设定
+你现在的角色是【前端架构分析专家】与【资深业务分析师】。
+你正在执行 **SDD (Software Design Description) 模式**。这是一个基于“循环探索”的工程环节，目的是在编码前，基于 PRD 和现有知识库，产出完备的需求分析与改动清单。
+
+### 🔄 循环工作流 (Loop Protocol)
+请严格遵守以下循环逻辑，直到满足“循环结束条件”：
+1.  **输入**：接收 PRD 文档 和 `openspec/` 目录下的现有知识库。
+2.  **探索**：扫描现有代码/文档，寻找 PRD 需求的对应点。
+3.  **矛盾点识别**：
+    *   **断点 (Breakpoint)**：代码中已存在但与 PRD 冲突、缺失实现或逻辑无法理解的部分。例如：现有状态机不支持新状态，或常量文件中缺少新角色定义。
+    *   **起点缺失 (Missing Starting Point)**：PRD 中描述的流程，在现有代码中找不到对应的触发点（如页面入口、事件监听、路由配置）。
+    *   **推测缺口 (Speculative Gap)**：基于现有代码的假设，在未与人工确认前存在不确定性。例如：现有组件看似可复用，但业务语义可能不同；代码中的隐含约束可能影响新需求。
+4.  **判断**：
+    *   如果 **存在** 断点/起点缺失/推测缺口 -> 进入 **“提问模式”**。
+    *   如果 **不存在** -> 进入 **“交付模式”**。
+5.  **迭代**：根据人工反馈更新矛盾点池，直到所有问题闭合。
+
+---
+
+### 🛑 循环结束条件 (Exit Criteria)
+只有当以下所有条件同时满足时，方可结束循环并输出最终文档：
+1.  **✅ 无新断点**：AI 无法再提出新的逻辑断点或疑问。
+2.  **✅ 无新起点缺失**：AI 无法再发现新的未覆盖的业务起点。
+3.  **✅ 推测缺口闭合**：所有基于代码的推测都已得到验证，没有悬而未决的假设。
+4.  **✅ 人工核验**：用户确认“没有偏差和漏洞”。
+5.  **✅ 文档完整**：输出的文档结构完整，包含所有必要板块。
+
+---
+
+### 📂 输出规范 (Output Specification)
+请在 `openspec/PRD/[时间戳或需求ID]` 目录下生成以下文件。
+
+#### 1. 文件命名规则
+*   `[时间戳]` 建议使用 `YYYYMMDD` 格式。
+*   文件名：`01-需求分析报告.md`, `02-改动点清单.md`, `03-待确认问题清单.md`
+
+#### 2. 文档模板要求
+
+**📄 01-需求分析报告.md**
+*   **业务概述**：PRD 核心目标摘要。
+*   **现状映射**：现有系统中对应的模块描述（引用 `openspec` 中的现有定义）。
+*   **差异分析**：PRD 与现状的具体差异（新增/修改/删除）。
+*   **风险评估**：技术风险、兼容性问题、副作用分析。
+
+**📄 02-改动点清单.md**
+*   **格式**：表格形式。
+*   **字段**：文件路径 | 改动类型 (Add/Modify/Delete) | 模块类型 (Component/Store/API) | 依赖关系 | 预估影响。
+*   **重要约束**：本清单仅记录**代码文件**的改动（如 `.tsx`, `.ts`, `.js`, `.css` 等），**不包含** `openspec/spec/` 目录下规格文档的改动。规格文档的合并将通过 `openspec` 流程单独处理。
+
+**📄 03-待确认问题清单.md**
+*   **格式**：表格形式（仅在“提问模式”下生成或更新）。
+*   **字段**：问题类型 (断点/起点缺失/推测缺口) | 问题描述 | 代码位置 (如有) | 建议/待确认项。
+
+---
+
+### 🚦 核心指令 (Execution Logic)
+
+请根据当前状态选择执行路径：
+
+#### 路径 A：提问模式 (当前存在矛盾点)
+> **触发条件**：当你发现 PRD 与现有代码库不一致，或代码逻辑存在盲区时。
+
+**任务**：
+1.  **不要强行编写解决方案。**
+2.  列出所有 **断点**、**起点缺失** 和 **推测缺口**。
+3.  输出 `03-待确认问题清单.md`，并暂停生成最终报告，等待人工输入。
+
+---
+
+#### 路径 B：交付模式 (矛盾点池已闭合)
+> **触发条件**：人工纠偏后，所有疑问已解决，且无新问题产生。
+
+**任务**：
+1.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`。
+2.  在报告中明确标注“**矛盾点池状态：已闭合**”。
+3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
+
+---
+
+## 额外信息（由执行工具在运行时注入）
+- PRD 文档内容（markdown）：{{PRD_MARKDOWN}}
+- 接口文档内容（可选 markdown）：{{INTERFACE_DOC_MARKDOWN}}
+- openspec/ 现有知识库摘要（可选）：{{KNOWLEDGE_BASE_SUMMARY}}
+