sdd-flow-kit 1.0.5 → 1.0.7

package/README.md

@@ -14,13 +14,13 @@
 #### 安装教程
 
 1.  进入你要开发的项目目录
-2.  安装：`pnpm add -D sdd-flow-kit && pnpm rebuild sdd-flow-kit`
-    - 安装后会自动执行一次初始化（postinstall）
-    - 交互终端下会提示选择项目类型（OMS / ADI / 欢盟 / AD Tools，默认 OMS）
-    - 非交互环境自动使用默认值（agent=claude-code, project=OMS）
-3.  安装流程（安装即用，默认 `claude-code`）：`npx sdd-flow-kit install`
-    - 会自动安装对应 AI 环境并写入项目级触发 Skill（仅在“开发 <产品> <版本> 需求/版本/PRD”场景触发）
-    - 会在项目根目录生成 `docs/<项目>-doc-skill/`（用于 PRD 下载脚本与说明），可通过 `--project` 选择：`OMS` / `ADI` / `欢盟` / `AD Tools`（默认 `OMS`）
+2.  安装：`pnpm add -D sdd-flow-kit `
+    检查是否安装  - `ls .cursor/skills/sdd-flow-kit/SKILL.md`
+    - `ls .claude/skills/sdd-flow-kit/SKILL.md`
+    - `ls docs/*-doc-skill/SKILL.md`
+3.  若仍未生成，执行手动兜底（100%触发初始化）：
+    - `node ./node_modules/sdd-flow-kit/dist/postinstall.js`
+    
 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

@@ -81,9 +81,11 @@ async function startFlowScaffold(options) {
         "",
         "## 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.5",
+  "version": "1.0.7",
   "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

@@ -1,23 +1,5 @@
 #!/usr/bin/env python3
-"""
-Confluence 需求文档获取脚本（Playwright）
-
-用法:
-  python3 confluence-doc.py <版本号>
-
-环境变量:
-  CONFLUENCE_BASE_URL      例如 https://confluence.huan.tv
-  CONFLUENCE_SEARCH_URL    例如 https://confluence.huan.tv/dosearchsite.action?includeArchivedSpaces=false
-  CONFLUENCE_USERNAME
-  CONFLUENCE_PASSWORD
-  DOC_PRODUCT_PREFIX       例如 ADI / OMS / HUAN / ADTOOLS
-  DOC_DOWNLOAD_DIR         输出目录（默认当前脚本所在目录的上级 docs/）
-
-注意:
-  - 为安全起见，本模板不包含任何默认账号密码
-  - 你需要先安装 playwright:
-      pip install playwright && playwright install chromium
-"""
+"""Confluence 需求文档获取脚本（Playwright - 通用版）"""
 
 import sys
 import os
@@ -34,9 +16,9 @@ except ImportError:
 
 def env(name: str, default: str | None = None) -> str:
     v = os.environ.get(name, default)
-    if v is None or str(v).strip() == "":
-        raise RuntimeError(f"缺少环境变量: {name}")
-    return str(v)
+    if v is None:
+        return ""
+    return str(v).strip()
 
 
 def load_env_file(file_path: Path) -> None:
@@ -89,6 +71,11 @@ def parse_html_to_markdown(html_content: str) -> str:
     md = re.sub(r"<li[^>]*>(.*?)</li>", r"- \1\n", md, flags=re.DOTALL | re.IGNORECASE)
     md = re.sub(r'<a[^>]*href="([^"]+)"[^>]*>(.*?)</a>', r"[\2](\1)", md, flags=re.DOTALL | re.IGNORECASE)
     md = re.sub(r'<img[^>]*src="([^"]+)"[^>]*>', r"![](\1)", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<table[^>]*>", r"\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"</table>", r"\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<tr[^>]*>", r"|", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"</tr>", r"\n", md, flags=re.DOTALL | re.IGNORECASE)
+    md = re.sub(r"<t[dh][^>]*>(.*?)</t[dh]>", r"|\1", md, flags=re.DOTALL | re.IGNORECASE)
     md = re.sub(r"<p[^>]*>(.*?)</p>", r"\1\n\n", md, flags=re.DOTALL | re.IGNORECASE)
     md = re.sub(r"<br[^>]*>", r"\n", md, flags=re.DOTALL | re.IGNORECASE)
     md = re.sub(r"<strong[^>]*>(.*?)</strong>", r"**\1**", md, flags=re.DOTALL | re.IGNORECASE)
@@ -167,20 +154,20 @@ def find_search_result(page, base_url: str, keyword: str):
     return best
 
 
-def run_search(page, base_url: str, keyword: str, search_url: str) -> str | None:
-    page.goto(search_url, wait_until="networkidle", timeout=60000)
-    page.wait_for_timeout(800)
+def run_search(page, base_url: str, keyword: str) -> str | None:
     search_selector = None
     for selector in ["#search-query-input", "input[name='search-query']", "input.search-query", "input[id*='search']"]:
         if page.locator(selector).count() > 0:
             search_selector = selector
             break
     if not search_selector:
+        if page.locator("input[type='text']").count() == 0:
+            return None
         search_selector = "input[type='text']"
-    page.fill(search_selector, keyword)
+    page.fill(search_selector, keyword, timeout=8000)
     page.keyboard.press("Enter")
     page.wait_for_load_state("networkidle", timeout=30000)
-    page.wait_for_timeout(1500)
+    page.wait_for_timeout(2000)
     return find_search_result(page, base_url, keyword)
 
 
@@ -195,10 +182,10 @@ def main():
     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")
-    password = env("CONFLUENCE_PASSWORD")
+    base_url = env("CONFLUENCE_BASE_URL", "https://confluence.huan.tv") or "https://confluence.huan.tv"
+    search_url = env("CONFLUENCE_SEARCH_URL") or f"{base_url.rstrip('/')}/dosearchsite.action?includeArchivedSpaces=false"
+    username = env("CONFLUENCE_USERNAME") or env("CONFLUENCE_USER")
+    password = env("CONFLUENCE_PASSWORD") or env("CONFLUENCE_PASS")
     prefix = os.environ.get("DOC_PRODUCT_PREFIX", "{{DOC_PRODUCT_PREFIX}}").strip() or "{{DOC_PRODUCT_PREFIX}}"
     version = normalize_version(sys.argv[1])
     keywords = search_keywords(prefix, version)
@@ -221,23 +208,34 @@ def main():
 
     with sync_playwright() as p:
         browser = p.chromium.launch(headless=True)
-        context = browser.new_context()
+        context = browser.new_context(
+            user_agent=(
+                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+            )
+        )
         page = context.new_page()
         try:
-            # 登录（如需要）
-            page.goto(search_url, wait_until="networkidle", timeout=60000)
+            print("\n📄 访问搜索页面...")
+            response = page.goto(search_url, wait_until="networkidle", timeout=60000)
+            if response:
+                print(f"   状态码: {response.status}")
             if "login" in page.url.lower():
+                if not username or not password:
+                    raise RuntimeError("检测到登录页但未提供 CONFLUENCE_USERNAME / CONFLUENCE_PASSWORD")
+                print("🔐 检测到需要登录，开始自动登录...")
                 page.wait_for_selector("#username-field", timeout=10000)
                 page.fill("#username-field", username)
                 page.fill("#password-field", password)
                 page.click("#login-button")
                 page.wait_for_load_state("networkidle", timeout=30000)
+                print("✅ 登录完成")
 
             target_url = None
             matched_keyword = None
             for kw in keywords:
                 print(f"\n🔍 搜索关键词: {kw}")
-                found = run_search(page, base_url, kw, search_url)
+                found = run_search(page, base_url, kw)
                 if found:
                     target_url = found
                     matched_keyword = kw
@@ -260,6 +258,8 @@ def main():
             content_elem = page.locator("#main-content")
             if not content_elem.count():
                 content_elem = page.locator(".wiki-content")
+            if not content_elem.count():
+                content_elem = page.locator(".content-body")
             content_html = content_elem.inner_html() if content_elem.count() else ""
 
             img_urls = re.findall(r'<img[^>]*src="([^"]+)"', content_html)
@@ -304,6 +304,9 @@ def main():
             print("\n✅ 获取完成！")
             print(f"📄 主文档: {md_path}")
             print(f"🖼️ 图片目录: {version_dir}")
+        except Exception as e:
+            print(f"\n❌ 获取失败: {e}")
+            raise
         finally:
             browser.close()
 

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

@@ -21,7 +21,6 @@ description: |
 
 ```bash
 cd docs/{{SKILL_DIR}}
-export CONFLUENCE_BASE_URL="https://confluence.huan.tv"
 export CONFLUENCE_USERNAME="<你的账号>"
 export CONFLUENCE_PASSWORD="<你的密码>"
 export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
@@ -52,5 +51,6 @@ 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_*` 配置可直接复用）
+- 默认 Confluence 地址为 `https://confluence.huan.tv`（可用 `CONFLUENCE_BASE_URL` 覆盖）
+- 脚本会自动尝试读取仓库根目录的 `.env.pre` / `.env` / `.env.local` / `.env.development` / `.env.test`（若其中存在 `CONFLUENCE_*` 配置可直接复用）