sdd-flow-kit 1.0.4 → 1.0.6

package/README.md

@@ -21,6 +21,7 @@
 3.  安装流程（安装即用，默认 `claude-code`）：`npx sdd-flow-kit install`
     - 会自动安装对应 AI 环境并写入项目级触发 Skill（仅在“开发 <产品> <版本> 需求/版本/PRD”场景触发）
     - 会在项目根目录生成 `docs/<项目>-doc-skill/`（用于 PRD 下载脚本与说明），可通过 `--project` 选择：`OMS` / `ADI` / `欢盟` / `AD Tools`（默认 `OMS`）
+    - 会自动注入 `.opsx/config.json`（按所选工具写入 editor/skillsDir/commandsDir）
 4.  （可选）预演安装：`npx sdd-flow-kit install --dry-run --plan-json`
 5.  （可选）环境健检：`npx sdd-flow-kit doctor --agent claude-code`
 6.  完成后，直接在 Cursor / Claude Code / Codex / OpenClaw 中用自然语言发起需求，例如：`开发 ADI 2.3.2 需求`

package/dist/cli.js

@@ -122,7 +122,7 @@ async function main() {
             projectKind: projectKind,
         });
         // eslint-disable-next-line no-console
-        console.log(`setup 完成：agent=${result.agent}, project=${result.projectKind}, branch=${result.branch}, setupExecuted=${result.setupExecuted}, skillInstalled=${result.skillInstalled}, docsSkillInstalled=${result.docsSkillInstalled}, dryRun=${dryRun}`);
+        console.log(`setup 完成：agent=${result.agent}, project=${result.projectKind}, branch=${result.branch}, setupExecuted=${result.setupExecuted}, skillInstalled=${result.skillInstalled}, docsSkillInstalled=${result.docsSkillInstalled}, opsxConfigInstalled=${result.opsxConfigInstalled}, dryRun=${dryRun}`);
         if (result.plannedActions.length > 0) {
             // eslint-disable-next-line no-console
             console.log(`planned: ${result.plannedActions.join(" | ")}`);

package/dist/steps/setupProject.js

@@ -220,6 +220,39 @@ async function installDocsSkill(projectRoot, kind) {
     await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(docsDir, "confluence-doc.py"), py);
     return { dirPath: docsDir };
 }
+function getOpsxPathsByAgent(agent) {
+    switch (agent) {
+        case "cursor":
+            return { editor: "cursor", skillsDir: ".cursor/skills", commandsDir: ".cursor/commands" };
+        case "claude-code":
+            return { editor: "claude-code", skillsDir: ".claude/skills", commandsDir: ".claude/commands" };
+        case "codex":
+            return { editor: "codex", skillsDir: ".codex/skills", commandsDir: ".codex/commands" };
+        case "openclaw":
+            return { editor: "openclaw", skillsDir: ".openclaw/skills", commandsDir: ".openclaw/commands" };
+        default:
+            return { editor: "custom", skillsDir: ".sdd-flow-kit/skills", commandsDir: ".sdd-flow-kit/commands" };
+    }
+}
+async function installOpsxConfig(projectRoot, agent) {
+    const target = node_path_1.default.join(projectRoot, ".opsx", "config.json");
+    const paths = getOpsxPathsByAgent(agent);
+    const config = {
+        version: 1,
+        editor: paths.editor,
+        skillsDir: paths.skillsDir,
+        commandsDir: paths.commandsDir,
+        deliveryPipeline: {
+            skillName: "opsx-dev-delivery-pipeline",
+            packageManager: "pnpm",
+            unitScript: "unit",
+            playwrightCommand: "exec playwright test",
+            devServerUrl: "http://localhost:5173",
+            playwrightPicDir: "playwright-pic",
+        },
+    };
+    await (0, fs_1.writeTextFileEnsuredDir)(target, JSON.stringify(config, null, 2));
+}
 async function setupProject(options) {
     const defaultAgent = options.agent ?? "claude-code";
     const selectedAgent = options.yes ? defaultAgent : await askAgent(defaultAgent);
@@ -242,6 +275,7 @@ async function setupProject(options) {
     let setupExecuted = false;
     let skillInstalled = false;
     let docsSkillInstalled = false;
+    let opsxConfigInstalled = false;
     if (!environmentReady) {
         const { cmd, args } = buildSetupCommand(options.projectRoot, selectedAgent);
         if (options.dryRun) {
@@ -269,12 +303,15 @@ async function setupProject(options) {
         }
         const { dir } = docSkillDirName(selectedKind);
         plannedActions.push(`would install docs skill: ${node_path_1.default.join(options.projectRoot, "docs", dir)}`);
+        plannedActions.push(`would install opsx config: ${node_path_1.default.join(options.projectRoot, ".opsx", "config.json")}`);
     }
     else {
         await installAgentSkill(options.projectRoot);
         skillInstalled = true;
         await installDocsSkill(options.projectRoot, selectedKind);
         docsSkillInstalled = true;
+        await installOpsxConfig(options.projectRoot, selectedAgent);
+        opsxConfigInstalled = true;
     }
     const summary = [
         "# SETUP-SUMMARY",
@@ -287,6 +324,7 @@ async function setupProject(options) {
         `setupExecuted: ${setupExecuted}`,
         `skillInstalled: ${skillInstalled}`,
         `docsSkillInstalled: ${docsSkillInstalled}`,
+        `opsxConfigInstalled: ${opsxConfigInstalled}`,
         `dryRun: ${Boolean(options.dryRun)}`,
         "",
         "plannedActions:",
@@ -304,5 +342,6 @@ async function setupProject(options) {
         plannedActions,
         skillInstalled,
         docsSkillInstalled,
+        opsxConfigInstalled,
     };
 }

package/dist/steps/startFlow.js

@@ -79,11 +79,13 @@ async function startFlowScaffold(options) {
         "",
         `本次 runId: \`${runId}\``,
         "",
-        "## Step 1：获取需求文档（adi-doc-skill）",
+        "## Step 1：获取需求文档（docs/<project>-doc-skill）",
         "请打开 `01-获取需求文档指引.md`，并使用你的 AI 工具执行相应动作，把 PRD/接口文档回填到 `source/`。",
+        "门禁：`source/PRD.md` 若仍是占位文本，禁止进入 Step2。",
         "",
         "## Step 2：执行 SDD 循环并生成 01/02/03 文件",
-        "请打开 `02-需求分析提示词.md`，在 Cursor/Claude Code/Codex/OpenClaw 中执行，并覆盖生成 `01-需求分析报告.md`、`02-改动点清单.md`、`03-待确认问题清单.md`。",
+        "请打开 `02-需求分析提示词.md`，在 Cursor/Claude Code/Codex/OpenClaw 中执行。",
+        "门禁：提问模式仅允许更新 `03-待确认问题清单.md`；闭环后才允许输出最终版 `01/02`。",
         "",
         "## Step 3：人工核验待确认问题",
         "将 `03-待确认问题清单.md` 收敛为闭环（必要时调整 01/02）。",
@@ -93,6 +95,10 @@ async function startFlowScaffold(options) {
         "",
         "## Step 5：触发 openspec + superpowers 提案",
         "使用 `05-openspec-提案草稿.md` 作为 openspec 的提案输入入口。",
+        "",
+        "## Step 6：执行 /opsx-apply",
+        "必须在当前仓库的本地 OPSX skills/config 下执行，不允许跨仓 fallback 到其它目录。",
+        "门禁：delivery-pipeline 未成功（exit 0）前，禁止宣称 apply 完成。",
     ].join("\n"));
     return {
         runId,

package/package.json

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

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

@@ -8,6 +8,11 @@
 
 --- 你将要运行的提示词结束 ---
 
+## 执行门禁（必须遵守，和手动流程一致）
+- `source/PRD.md` 若仍是占位文本（没有真实 PRD 内容），**禁止**继续 Step2，先返回“Step1 未完成”并停止。
+- 当处于“提问模式”时，**只允许更新** `03-待确认问题清单.md`；**禁止**产出最终版 `01-需求分析报告.md` / `02-改动点清单.md`。
+- 只有当用户明确确认“矛盾点池已闭合”后，才可进入“交付模式”并输出最终版 `01` / `02`。
+
 ## 输入注入（建议做法）
 - 将 `source/PRD.md` 的内容作为 `{{PRD_MARKDOWN}}` 注入
 - 将 `source/接口文档.md` 的内容作为 `{{INTERFACE_DOC_MARKDOWN}}` 注入（没有则忽略）
@@ -18,3 +23,7 @@
 - `02-改动点清单.md`
 - `03-待确认问题清单.md`
 
+## 输出话术（建议固定）
+- 提问模式：`SDD 模式：提问模式；矛盾点池状态：未闭合；仅更新 03，等待人工确认。`
+- 交付模式：`SDD 模式：交付模式；矛盾点池状态：已闭合；已输出最终版 01/02/03。`
+

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

@@ -8,6 +8,11 @@
 3. 将本文件中的内容复制给 openspec + superpowers 的“提案输入”
 4. 进入生成 UI 图 + 任务拆解 + 开发阶段
 
+## 门禁（与手动流程一致）
+- 仅当 `03-待确认问题清单.md` 已明确“矛盾点池状态：已闭合”时，才可进入提案阶段。
+- 若 `03` 未闭合，禁止进入提案，先回到 Step3 完成确认。
+- 提案完成后进入 `/opsx-apply`，必须在当前仓库本地 OPSX 配置中执行。
+
 ## 输入摘要
 - `01-需求分析报告.md`：已完成
 - `02-改动点清单.md`：已完成（仅代码文件改动）

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

@@ -57,6 +57,10 @@
 
 请根据当前状态选择执行路径：
 
+### 0) 前置门禁（必须先检查）
+- 若 `source/PRD.md` 未回填真实 PRD（仍为占位），立即停止并返回：`Step1 未完成：请先完成 PRD 回填`。
+- 不得在 PRD 缺失时产出 `01/02/03` 的“最终版”内容。
+
 #### 路径 A：提问模式 (当前存在矛盾点)
 > **触发条件**：当你发现 PRD 与现有代码库不一致，或代码逻辑存在盲区时。
 
@@ -64,6 +68,7 @@
 1.  **不要强行编写解决方案。**
 2.  列出所有 **断点**、**起点缺失** 和 **推测缺口**。
 3.  输出 `03-待确认问题清单.md`，并暂停生成最终报告，等待人工输入。
+4.  明确标注：`矛盾点池状态：未闭合`。
 
 ---
 
@@ -74,6 +79,7 @@
 1.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`。
 2.  在报告中明确标注“**矛盾点池状态：已闭合**”。
 3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
+4.  输出时附带一句：`可进入 Step4 技术文档与 Step5 提案阶段`。
 
 ---
 

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

@@ -39,6 +39,25 @@ def env(name: str, default: str | None = None) -> str:
     return str(v)
 
 
+def load_env_file(file_path: Path) -> None:
+    """轻量加载 .env 文件（不依赖 python-dotenv）。"""
+    if not file_path.exists() or not file_path.is_file():
+        return
+    try:
+        for raw in file_path.read_text(encoding="utf-8").splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if key and key not in os.environ:
+                os.environ[key] = value
+    except Exception:
+        # 失败不阻断，继续走显式环境变量
+        pass
+
+
 def normalize_version(raw: str) -> str:
     """将 1.2.3 / V1.2.3 / XXX-V1.2.3 / XXX_V1.2.3 统一为 1.2.3"""
     v = raw.strip()
@@ -171,6 +190,11 @@ def main():
         print("   用法: python3 confluence-doc.py <版本号>")
         sys.exit(1)
 
+    # 自动尝试从项目常见 env 文件加载配置，降低手工配置成本
+    repo_root = Path(__file__).resolve().parents[2]
+    for env_name in [".env.pre", ".env", ".env.local", ".env.development", ".env.test"]:
+        load_env_file(repo_root / env_name)
+
     base_url = env("CONFLUENCE_BASE_URL")
     search_url = env("CONFLUENCE_SEARCH_URL", base_url.rstrip("/") + "/dosearchsite.action?includeArchivedSpaces=false")
     username = env("CONFLUENCE_USERNAME")

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

@@ -52,4 +52,5 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 - 依赖 Playwright：`pip install playwright && playwright install chromium`
 - 脚本：`docs/{{SKILL_DIR}}/confluence-doc.py`
 - 为安全起见，脚本不包含默认账号密码，请用环境变量注入
+- 脚本会自动尝试读取仓库根目录的 `.env.pre` / `.env` / `.env.local`（若其中存在 `CONFLUENCE_*` 配置可直接复用）