sdd-flow-kit 1.0.18 → 1.0.25

package/README.md

@@ -15,9 +15,12 @@
 
 1.  进入你要开发的项目目录
 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`
+    检查是否安装（Cursor 用户看 `.cursor`，不是 `.claude`）：
+    - `ls .cursor/skills/sdd-flow-kit/SKILL.md`
+    - `ls docs/adi-doc-skill/SKILL.md`（adInsight 应为 **adi**，不是 oms）
+    - Claude Code 用户：`ls .claude/skills/sdd-flow-kit/SKILL.md`
+
+> 若在 `adInsight-web/frontend` 等子目录安装，工具会**向上识别**仓库名；仍不对时：`SDD_FLOW_KIT_PROJECT=ADI pnpm add -D sdd-flow-kit` 或 `npx sdd-flow-kit install --project ADI -y`
 3.  若 skill 未生成，执行手动兜底：
     - `node ./node_modules/sdd-flow-kit/dist/postinstall.js`（轻量，秒级）
     - 或 `npx sdd-flow-kit install -y`（完整环境）
@@ -56,10 +59,11 @@
 ##### 需求澄清：用户无需背提示词
 
 `install` 会写入 `.cursor/rules/sdd-flow-kit-gates.mdc` 与触发 Skill。  
-澄清阶段你**直接粘贴确认点**（编号列表即可），AI 应自动进入文档模式，只改 `openspec/PRD/**`，不改 `src/`。  
-写业务代码仅在 `/opsx-propose` 完成且你同意 `/opsx-apply` 之后。
+澄清阶段你**直接粘贴确认点**（编号列表即可），AI 先进入文档模式更新 `openspec/PRD/**`。  
+**默认**：03 闭环并生成 01/02/04 后，**同一回合自动** `/opsx-propose`（01+02+UI）→ `/opsx-apply`，无需再说「继续」。  
+说「只提案」或「先别写代码」可停在提案阶段；设 `autoChainOpsx: false` 可恢复人工分步。
 
-阶段口语（可选，非必须）：`继续` / `做提案` → propose；`开始 apply` → 实现。
+阶段口语（可选，用于断点续跑）：`继续` / `做提案` / `开始 apply`。
 
 ##### `/opsx-apply` 与 TDD + Playwright 检查机制
 

package/dist/adapters/index.js

@@ -42,8 +42,8 @@ async function runClaudeFlow(args) {
         "1) 01-获取需求文档指引：回填 source/PRD.md（及接口文档，如有）。",
         "2) 02-需求分析：若矛盾点未闭合，仅更新 03-待确认问题清单.md 并停止；用户确认后再生成 01/02/闭环03。",
         "3) 用户确认后补全 04-技术文档草稿.md。",
-        "4) /opsx-propose：基于 01、02 与 UI 参考生成 openspec change，并记录到 05-openspec-提案草稿.md。",
-        "5) /opsx-apply：提案 apply-ready 后执行 delivery-pipeline。",
+        "4) 03 闭环后默认同一回合：/opsx-propose（01+02+UI）→ /opsx-apply → delivery-pipeline exit 0（见 06-opsx-自动串联指引.md）。",
+        "5) 仅当用户说「只提案」或 autoChainOpsx=false 时，在 propose 后暂停等待 apply。",
         "完成后输出一句：SDD flow completed",
         "",
         "以下是第2步提示词：",

package/dist/core/inferProject.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRODUCT_PREFIX_BY_KIND = exports.DOC_SKILL_BY_KIND = exports.ALLOWED_PROJECTS = void 0;
+exports.productToKind = productToKind;
+exports.resolveDocSkillDir = resolveDocSkillDir;
+exports.inferProjectKind = inferProjectKind;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.ALLOWED_PROJECTS = ["OMS", "ADI", "欢盟", "AD Tools"];
+exports.DOC_SKILL_BY_KIND = {
+    ADI: "adi-doc-skill",
+    OMS: "oms-doc-skill",
+    欢盟: "huan-doc-skill",
+    "AD Tools": "ad-tools-doc-skill",
+};
+exports.PRODUCT_PREFIX_BY_KIND = {
+    ADI: "ADI",
+    OMS: "OMS",
+    欢盟: "HUAN",
+    "AD Tools": "ADTOOLS",
+};
+function productToKind(product) {
+    const p = product.trim().toUpperCase();
+    if (p === "ADI" || p.includes("ADINSIGHT"))
+        return "ADI";
+    if (p === "OMS" || p.includes("OPERATION"))
+        return "OMS";
+    if (p === "欢盟" || p === "HUAN")
+        return "欢盟";
+    if (p.includes("AD TOOLS") || p === "ADTOOLS")
+        return "AD Tools";
+    return "OMS";
+}
+/** 从 projectRoot 向上查找 docs/*-doc-skill（适配 frontend 子目录 + 根目录 docs） */
+async function resolveDocSkillDir(projectRoot, kind) {
+    const dirName = exports.DOC_SKILL_BY_KIND[kind];
+    let cur = node_path_1.default.resolve(projectRoot);
+    for (let i = 0; i < 8; i += 1) {
+        const candidate = node_path_1.default.join(cur, "docs", dirName);
+        if (await pathExists(node_path_1.default.join(candidate, "confluence-doc.py"))) {
+            const rel = node_path_1.default.relative(projectRoot, candidate);
+            return {
+                absPath: candidate,
+                relFromRoot: rel.startsWith("..") ? rel : node_path_1.default.join("docs", dirName),
+            };
+        }
+        const parent = node_path_1.default.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return {
+        absPath: node_path_1.default.join(projectRoot, "docs", dirName),
+        relFromRoot: node_path_1.default.join("docs", dirName),
+    };
+}
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function matchKindInText(text) {
+    const t = text.toLowerCase().replace(/_/g, "-");
+    if (t.includes("adinsight") || t.includes("adi-web") || /(^|\/|-)adi(-|\/|$)/.test(t)) {
+        return "ADI";
+    }
+    if (t.includes("operation-web") || t.includes("operation") || /(^|\/|-)oms(-|\/|$)/.test(t)) {
+        return "OMS";
+    }
+    if (t.includes("huan-union") || t.includes("huanunion") || /\bhm\b/.test(t)) {
+        return "欢盟";
+    }
+    if (t.includes("ad-tools") || t.includes("adtools")) {
+        return "AD Tools";
+    }
+    return null;
+}
+/** 从 projectRoot 向上查找已存在的 docs/*-doc-skill */
+async function inferFromExistingDocSkill(projectRoot) {
+    let dir = projectRoot;
+    for (let i = 0; i < 8; i += 1) {
+        for (const kind of exports.ALLOWED_PROJECTS) {
+            const rel = node_path_1.default.join(dir, "docs", exports.DOC_SKILL_BY_KIND[kind]);
+            if (await pathExists(node_path_1.default.join(rel, "SKILL.md"))) {
+                return kind;
+            }
+        }
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** 从目录路径（含父级）推断产品类型 */
+function inferFromPathSegments(projectRoot) {
+    const resolved = node_path_1.default.resolve(projectRoot);
+    const parts = resolved.split(node_path_1.default.sep);
+    for (let i = parts.length; i > 0; i -= 1) {
+        const segment = parts.slice(0, i).join(node_path_1.default.sep);
+        const hit = matchKindInText(segment);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+async function inferFromPackageJson(dir) {
+    try {
+        const pkgText = await promises_1.default.readFile(node_path_1.default.join(dir, "package.json"), "utf8");
+        const pkg = JSON.parse(pkgText);
+        const blob = `${pkg.name ?? ""} ${pkg.description ?? ""}`;
+        return matchKindInText(blob);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 推断 OMS / ADI / 欢盟 / AD Tools。
+ *  monorepo 子目录（如 adInsight-web/frontend）会向上扫描路径，避免误判为 OMS。
+ */
+async function inferProjectKind(projectRoot) {
+    const fromEnv = (process.env.SDD_FLOW_KIT_PROJECT ?? "").trim();
+    if (exports.ALLOWED_PROJECTS.includes(fromEnv)) {
+        return fromEnv;
+    }
+    // 路径优先于已存在的 docs skill（避免 frontend 子目录曾误装 oms-doc-skill 后一直错下去）
+    const fromPath = inferFromPathSegments(projectRoot);
+    if (fromPath)
+        return fromPath;
+    let dir = projectRoot;
+    for (let i = 0; i < 6; i += 1) {
+        const fromPkg = await inferFromPackageJson(dir);
+        if (fromPkg)
+            return fromPkg;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const fromExisting = await inferFromExistingDocSkill(projectRoot);
+    if (fromExisting)
+        return fromExisting;
+    return "OMS";
+}

package/dist/postinstall.js

@@ -1,56 +1,55 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 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 promises_1 = __importDefault(require("node:fs/promises"));
 const node_process_1 = __importDefault(require("node:process"));
+const inferProject_1 = require("./core/inferProject");
 const opsxDelivery_1 = require("./core/opsxDelivery");
 const setupProject_1 = require("./steps/setupProject");
-const ALLOWED_PROJECTS = ["OMS", "ADI", "欢盟", "AD Tools"];
-async function inferProjectKind(projectRoot) {
-    const fromEnv = (node_process_1.default.env.SDD_FLOW_KIT_PROJECT ?? "").trim();
-    if (ALLOWED_PROJECTS.includes(fromEnv)) {
-        return fromEnv;
-    }
-    const base = node_path_1.default.basename(projectRoot).toLowerCase();
-    const hit = (s) => base.includes(s);
-    if (hit("adi") || hit("adinsight"))
-        return "ADI";
-    if (hit("oms") || hit("operation"))
-        return "OMS";
-    if (hit("huan-union") || hit("hm"))
-        return "欢盟";
-    if (hit("ad-tools") || hit("adtools") || hit("tools"))
-        return "AD Tools";
-    try {
-        const pkgText = await promises_1.default.readFile(node_path_1.default.join(projectRoot, "package.json"), "utf8");
-        const pkg = JSON.parse(pkgText);
-        const name = (pkg.name ?? "").toLowerCase();
-        const has = (s) => name.includes(s);
-        if (has("adi") || has("adinsight"))
-            return "ADI";
-        if (has("oms") || has("operation"))
-            return "OMS";
-        if (has("huan-union") || has("hm"))
-            return "欢盟";
-        if (has("ad-tools") || has("adtools") || has("tools"))
-            return "AD Tools";
-    }
-    catch {
-        // ignore and fallback
-    }
-    return "OMS";
-}
 async function inferAgent(projectRoot) {
     const fromEnv = (node_process_1.default.env.SDD_FLOW_KIT_AGENT ?? "").trim();
     const allowed = ["cursor", "claude-code", "codex", "openclaw"];
     if (allowed.includes(fromEnv))
         return fromEnv;
+    const fs = await Promise.resolve().then(() => __importStar(require("node:fs/promises")));
     const exists = async (rel) => {
         try {
-            await promises_1.default.access(node_path_1.default.join(projectRoot, rel));
+            await fs.access(node_path_1.default.join(projectRoot, rel));
             return true;
         }
         catch {
@@ -76,7 +75,7 @@ async function main() {
     const projectRoot = initCwd ?? node_process_1.default.cwd();
     if (projectRoot === pkgDir)
         return;
-    const projectKind = await inferProjectKind(projectRoot);
+    const projectKind = await (0, inferProject_1.inferProjectKind)(projectRoot);
     const agent = await inferAgent(projectRoot);
     // eslint-disable-next-line no-console
     console.log(`[sdd-flow-kit] postinstall (light) at: ${projectRoot}`);
@@ -105,7 +104,11 @@ async function main() {
         console.log("[sdd-flow-kit] opsx apply stack ready");
     }
     // eslint-disable-next-line no-console
-    console.log("[sdd-flow-kit] light setup done (skills/rules). Full install: npx sdd-flow-kit install -y");
+    console.log("[sdd-flow-kit] light setup done (skills/rules). Full install: npx sdd-flow-kit install --project ADI -y");
+    if (agent === "cursor") {
+        // eslint-disable-next-line no-console
+        console.log("[sdd-flow-kit] Cursor skill: .cursor/skills/sdd-flow-kit/SKILL.md");
+    }
 }
 main().catch((err) => {
     // eslint-disable-next-line no-console

package/dist/steps/startFlow.js

@@ -9,6 +9,7 @@ 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");
+const inferProject_1 = require("../core/inferProject");
 function renderTemplate(template, vars) {
     let out = template;
     for (const [k, v] of Object.entries(vars)) {
@@ -22,8 +23,16 @@ async function startFlowScaffold(options) {
     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");
+    // 1) Step1: doc-skill 指引（按产品解析脚本路径，支持 monorepo frontend）
+    const kind = (0, inferProject_1.productToKind)(options.product);
+    const docSkill = await (0, inferProject_1.resolveDocSkillDir)(options.projectRoot, kind);
+    const step1Template = await (0, templates_1.loadTemplateText)("artifacts/01-adi-doc-skill-指引.template.md");
+    const step1 = renderTemplate(step1Template, {
+        PRODUCT: options.product,
+        PRODUCT_PREFIX: inferProject_1.PRODUCT_PREFIX_BY_KIND[kind],
+        DOC_SKILL_REL: docSkill.relFromRoot.replace(/\\/g, "/"),
+        VERSION_EXAMPLE: options.version,
+    });
     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"), [
@@ -65,6 +74,8 @@ async function startFlowScaffold(options) {
     // 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);
+    const opsxAutoChainTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-opsx-auto-chain.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, "06-opsx-自动串联指引.md"), opsxAutoChainTemplate);
     await (0, fs_1.writeTextFileEnsuredDir)(node_path_1.default.join(outputRoot, ".session-state.json"), JSON.stringify({
         product: options.product,
         version: options.version,
@@ -72,6 +83,7 @@ async function startFlowScaffold(options) {
         outputRoot,
         status: "awaiting_user_confirmation",
         docModeOnly: true,
+        autoChainOpsx: true,
         phase: "A_or_B",
         createdAtISO: new Date().toISOString(),
     }, null, 2));
@@ -101,12 +113,13 @@ async function startFlowScaffold(options) {
         "- `02-改动点清单.md`",
         "- `04-技术文档草稿.md`",
         "",
-        "## Step 5：/opsx-propose 生成提案",
-        "基于 `01`、`02` 与用户提供的 UI 参考，执行 `/opsx-propose`。",
-        "产出在 `openspec/changes/<change-name>/`；在 `05-openspec-提案草稿.md` 记录 change 名称。",
-        "门禁：仅当 03 已闭环且 01/02/04 完成后执行。",
+        "## Step 5–6：自动串联 OPSX（默认）",
+        "03 闭环且 01/02/04 完成后，**同一 AI 回合**读 `06-opsx-自动串联指引.md`：",
+        "1. `/opsx-propose`（输入 01、02、UI；UI 默认读 `source/PRD.md` 原型目录）",
+        "2. 提案 apply-ready 后立即 `/opsx-apply` + `pnpm run opsx:delivery-pipeline`（exit 0）",
+        "勿停下来问「是否继续」。仅当用户说「只提案」或 `.session-state.json` 中 `autoChainOpsx: false` 时暂停。",
         "",
-        "## Step 6：Apply + TDD + Playwright（阶段 D）",
+        "## Step 6 明细：Apply + TDD + Playwright（阶段 D）",
         "依次执行 skill：`openspec-apply-change` → `tdd-script` → `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`。",
         "仓库根执行：`pnpm run opsx:delivery-pipeline -- <change-name>`（须 exit 0）。",
         "禁止跳过 TDD / Playwright 裸写代码收尾。详见 `.cursor/skills/sdd-flow-kit/SKILL.md` 阶段 D。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.0.18",
+  "version": "1.0.25",
   "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

@@ -1,15 +1,29 @@
-# 01-获取需求文档（adi-doc-skill 指引）
+# 01-获取需求文档（{{PRODUCT}} / {{DOC_SKILL_REL}}）
 
-你的步骤 1 目标：从 Confluence 拉取指定需求版本的 Markdown，并落到本目录的 `source/` 下。
+## 必须执行（不要只用 AI 猜，要跑脚本）
 
-## 请执行
-1. 使用你当前 AI 工具（Cursor / Claude Code / Codex / OpenClaw）调用现有的 `adi-doc-skill`。
-2. 命令/动作建议：让工具“获取 ADI 2.3.2 需求文档”（或等价的触发词），并把下载结果写入本目录：
-   - `source/PRD.md`（PRD 主内容）
-   - `source/接口文档.md`（接口文档，如有）
+1. 在**仓库根**（当前工作目录，可能是 `frontend/` 或 monorepo 根）执行：
 
-## 成功校验
-- 你应该能在 `source/PRD.md` 看到完整 PRD markdown
+```bash
+cd {{DOC_SKILL_REL}}
+export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
+python3 confluence-doc.py {{VERSION_EXAMPLE}}
+```
 
-（如果你希望自动回填，请在 adapter 中实现对应能力。）
+版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。
 
+2. 脚本会依次搜索：`{{PRODUCT_PREFIX}}-V*`、`{{PRODUCT_PREFIX}}_V*`、`{{PRODUCT_PREFIX}} V*`、`V*` 等。
+
+3. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+   - `source/PRD.md`
+
+## 路径说明
+
+- 推荐脚本目录：`{{DOC_SKILL_REL}}`（已向上解析，可能是 `docs/adi-doc-skill` 或 `../docs/adi-doc-skill`）
+- **禁止**在 ADI 需求中使用 `docs/oms-doc-skill`（会搜 OMS 文档导致「未找到」）
+
+## 失败排查
+
+- 输出 `❌ 未找到`：到 Confluence 确认页面标题是否含 `{{PRODUCT_PREFIX}}-V2.3.2` 或 `{{PRODUCT_PREFIX}}_V2.3.2`
+- `playwright` 未安装：`pip install playwright && playwright install chromium`
+- 仍失败：在仓库根执行 `npx sdd-flow-kit install --project {{PRODUCT}} -y` 后重试

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

@@ -6,7 +6,8 @@
 ## 前置条件（必须全部满足）
 - [ ] `03-待确认问题清单.md` 已标注 **矛盾点池状态：已闭合**
 - [ ] `01-需求分析报告.md`、`02-改动点清单.md`、`04-技术文档草稿.md` 已生成
-- [ ] 用户已确认可进入提案阶段
+- [ ] 用户已确认可进入提案阶段（阶段 B 闭环）
+- [ ] `autoChainOpsx` 为 true（默认）→ 与用户确认后**同一回合**自动 propose，无需再等「继续」
 
 ## /opsx-propose 输入清单
 - 需求分析：`01-需求分析报告.md`

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

@@ -1,6 +1,6 @@
 ---
 name: sdd-flow-kit-trigger
-description: 开发某版本需求、SDD 流程、待确认问题澄清、用户回复确认点/矛盾点结论时触发。澄清与确认阶段仅改 openspec/PRD 文档，禁止写 src 等业务代码；仅 /opsx-apply 后可实现。
+description: 开发某版本需求、SDD 流程、待确认问题澄清、用户回复确认点/矛盾点结论时触发。阶段 A/B 仅文档；阶段 B 闭环后**自动** /opsx-propose → /opsx-apply（除非用户说只提案或 autoChainOpsx=false）。
 ---
 
 # SDD Flow Trigger Skill
@@ -20,16 +20,18 @@ description: 开发某版本需求、SDD 流程、待确认问题澄清、用户
 | 模式 | 何时 | 允许改动的路径 | 禁止 |
 |------|------|----------------|------|
 | **文档模式** | 阶段 A/B/C，含「用户发来确认点」 | 仅 `openspec/PRD/**`（及阶段 C 的 `openspec/changes/**`） | 任何 `src/`、`pages/`、`components/` 等业务代码 |
-| **实现模式** | 仅阶段 D，且用户同意 `/opsx-apply` | 按 openspec change 与 pipeline 要求 | 跳过 propose |
+| **实现模式** | 阶段 D（提案 apply-ready 后**自动进入**，无需用户再说「开始 apply」） | 按 openspec change 与 pipeline 要求 | 跳过 propose / 跳过 pipeline |
 
 **常见错误**：用户粘贴确认点后，你一边更新 `03` 一边改 `.tsx` —— **绝对禁止**。确认回复 = 只做文档，同一回合不得 touch 业务代码。
 
 ### 用户侧：零口令（不要要求加前缀）
 - 用户**直接粘贴**确认点、编号结论、「按 1/2/3 继续」即可；**禁止**要求用户输入【仅文档模式】等固定话术。
 - 你须在收到后**自动**判定为阶段 B 的文档模式；先读 `openspec/PRD/<runId>/.session-state.json`（`docModeOnly: true` 时严禁写业务代码）与 `03-待确认问题清单.md`。
-- 阶段切换口语即可，无需背提示词：
-  - 提案：`继续` / `做提案` / `propose`（执行 `/opsx-propose`）
-  - 实现：`开始 apply` / `执行 apply`（且 change 已 apply-ready）
+- **默认自动串联**（`openspec/PRD/<runId>/.session-state.json` 中 `autoChainOpsx !== false`）：
+  - 阶段 B 产出 01/02/闭环03/04 后，**同一回合**继续阶段 C→D，**不要**停下来问「是否继续」。
+  - 读 `06-opsx-自动串联指引.md` 与 `.cursor/skills/opsx-superpowers-workflow/SKILL.md`。
+- **仅当用户说**「只提案」「先别写代码」时：阶段 C 结束后停止，等待 `/opsx-apply`。
+- 口语仍可用：`继续` / `做提案` / `开始 apply`（用于断点续跑）。
 
 ## 触发后执行规则（分阶段，禁止跳步）
 
@@ -41,7 +43,10 @@ description: 开发某版本需求、SDD 流程、待确认问题澄清、用户
 ---
 
 ### 阶段 A — Step1 + Step2（必须可停顿）
-1. **Step1**：按 `01-获取需求文档指引.md` 拉取 PRD，回填 `source/PRD.md`（及可选接口文档）
+1. **Step1**：打开 `01-获取需求文档指引.md`，**在终端执行其中的 `confluence-doc.py` 命令**（不要跳过）。
+   - ADI 必须用 `docs/adi-doc-skill` 或上级 `../docs/adi-doc-skill`，**禁止**用 `docs/oms-doc-skill`。
+   - 用户说「开发 ADI_V2.3.2」时，脚本参数传 `2.3.2` 或 `ADI_V2.3.2` 均可。
+   - 将下载的 markdown 回填 `source/PRD.md`。
 2. **Step2**：执行 `02-需求分析提示词.md`（引用 `docs/` 下已下载的 PRD）
 
 **门禁（Step2）**
@@ -61,7 +66,9 @@ description: 开发某版本需求、SDD 流程、待确认问题澄清、用户
 2. 将状态改为 **矛盾点池状态：已闭合**。
 3. 再生成 `01`、`02`、`04`（路径均在 `openspec/PRD/<runId>/`）。
 4. **本回合禁止**：`StrReplace`/`Write` 任何业务源码；禁止「顺手实现一版」。
-5. 结束语简短即可（例：「已更新 01/02/03/04，未改业务代码。有 UI 参考请发路径，或回复继续做提案。」）——**不要**要求用户背固定口令。
+5. 更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
+6. **若 `autoChainOpsx !== false` 且用户未说「只提案」**：**不要结束回合**——立即打开 `06-opsx-自动串联指引.md` 执行阶段 C→D（见下文）。
+7. 若 `autoChainOpsx === false`：简短说明 01/02/03/04 已就绪，等待用户说「继续」。
 
 **本阶段只允许产出：**
 1. 更新 `03-待确认问题清单.md`（标注 **矛盾点池状态：已闭合**，写入用户确认结论）
@@ -71,34 +78,34 @@ description: 开发某版本需求、SDD 流程、待确认问题澄清、用户
 
 **本阶段禁止：**
 - 修改 `src/`、`pages/`、`components/`、`api/` 等实现代码（`02-改动点清单` 只是**计划**，不是实施许可）
-- 执行 `/opsx-propose` 或 `/opsx-apply`
-- 生成 openspec change 目录或宣称“开发完成”
-
-完成后告知用户：“01/02/03/04 已就绪。发 UI 参考路径，或回复「继续」我将执行 /opsx-propose。”
+- 在 **未闭合 03** 时执行 `/opsx-propose` 或 `/opsx-apply`
+- 在 `autoChainOpsx === false` 时未经用户同意就进入阶段 C/D
 
 ---
 
-### 阶段 C — `/opsx-propose`（生成提案，对应你说的「05」）
-**触发条件**：阶段 B 已完成，且用户确认可进入提案（可提供 UI 参考路径，如原型页面文件）。
+### 阶段 C — `/opsx-propose`（生成提案，对应 Step5）
+**触发条件**：
+- 阶段 B 已完成（03 已闭合，01/02/04 已生成），**且**
+- `autoChainOpsx !== false`（默认）→ **与用户确认同一回合内自动执行**；或用户说「继续/做提案」；或 `status` 为 `ready_for_propose` 且用户未说「只提案」。
 
 **必须执行：**
 1. 先读当前仓库 `.opsx/config.json` 与本地 OPSX skills（禁止跨项目 fallback）
-2. 执行 **`/opsx-propose`**，输入至少包含：
-   - `01-需求分析报告.md`
-   - `02-改动点清单.md`
-   - **UI 图/交互参考**（用户指定路径；无则说明缺失并继续文字 spec）
+2. 执行 **`/opsx-propose`**（遵循 `.cursor/commands/opsx-propose.md` 与 `openspec-propose` skill），输入至少包含：
+   - `openspec/PRD/<runId>/01-需求分析报告.md`
+   - `openspec/PRD/<runId>/02-改动点清单.md`
+   - **UI 图/交互参考**（按 `06-opsx-自动串联指引.md` 解析；无则注明缺失并继续）
 3. 一次性生成 openspec change（`proposal.md`、`design.md`、`specs/`、`tasks.md` 等）
+4. 更新 `05-openspec-提案草稿.md`；`.session-state.json` → `status: propose_done`
 
-**本阶段交付物 = openspec 提案产物**（即手动流程里的 Step5 结果）。  
-可在 `openspec/PRD/<runId>/05-openspec-提案草稿.md` 记录 change 名称与路径索引。
+**本阶段交付物 = openspec 提案产物**。  
+**本阶段禁止**：写 `src/`、跑 delivery-pipeline。
 
-**本阶段禁止：**
-- 执行 `/opsx-apply`（留给阶段 D）
+**默认**：提案 apply-ready 后 **立即** 进入阶段 D（勿问用户「是否 apply」），除非用户说了「只提案」。
 
 ---
 
 ### 阶段 D — Apply + TDD + Playwright 交付（禁止裸写代码收尾）
-**触发条件**：阶段 C 的 openspec 提案已 apply-ready，且用户同意实现（如「开始 apply」）。
+**触发条件**：阶段 C 的 openspec 提案已 apply-ready（`autoChainOpsx` 默认下与阶段 C **同一连续执行**）。
 
 **严禁**：跳过 skill 链、不按 `tasks.md` TDD、不跑 delivery-pipeline 就改 `src/` 并宣称完成。
 

package/src/templates/artifacts/06-opsx-auto-chain.template.md

@@ -0,0 +1,38 @@
+# 06 OPSX 自动串联（阶段 B 完成后立即执行）
+
+> **不要**在阶段 B 结束后停下来问用户「是否继续」或「是否 apply」。  
+> 除非用户明确说「只提案」「先别写代码」，或 `.session-state.json` 中 `autoChainOpsx: false`。
+
+## 输入（本 runId）
+| 文件 | 路径 |
+|------|------|
+| 需求分析 | `01-需求分析报告.md` |
+| 改动清单 | `02-改动点清单.md` |
+| 技术草稿 | `04-技术文档草稿.md` |
+| UI 参考 | 见下方「UI 路径解析」 |
+
+## UI 路径解析（按优先级）
+1. 用户本条消息给出的路径
+2. `source/PRD.md` 中的「原型图片目录」行（如 `docs/adi-v232/`）
+3. `docs/<product>-v<version无点>/` 或 `docs/<product>-<version>/` 目录（只读扫描）
+
+缺失 UI 时：**仍继续** propose，在 `proposal.md` / `design.md` 注明「UI 待补」。
+
+## 阶段 C — `/opsx-propose`（同一对话回合内）
+1. 读仓库根 `.cursor/skills/opsx-superpowers-workflow/SKILL.md` 与 `openspec-propose/SKILL.md`
+2. 执行 `/opsx-propose`（或等价的 openspec CLI 全流程），输入 = 上表 01 + 02 + UI
+3. change 名建议：`{{PRODUCT}}-v{{VERSION}}-<short-topic>`（kebab-case）
+4. 更新 `05-openspec-提案草稿.md` 与 `.session-state.json`：`status: propose_done`
+5. **禁止**在本阶段写 `src/` 或跑 delivery-pipeline
+
+## 阶段 D — `/opsx-apply`（提案 apply-ready 后**立即**执行，无需再等用户）
+1. `npx sdd-flow-kit ensure-opsx --agent cursor -y`（仓库根）
+2. 写 `.opsx-active-change` = change 名
+3. 读并执行：`openspec-apply-change` → `tdd-script` → `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
+4. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
+5. 更新 `.session-state.json`：`status: complete`，`docModeOnly: false`
+
+## 完成判定
+- [ ] `openspec/changes/<name>/` 下 applyRequires 全部 done
+- [ ] `tasks.md` 全部 `- [x]`
+- [ ] delivery-pipeline exit 0

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

@@ -86,8 +86,10 @@
 1.  更新 `03-待确认问题清单.md`，标注“**矛盾点池状态：已闭合**”，写入用户确认结论。
 2.  生成最终版 `01-需求分析报告.md` 和 `02-改动点清单.md`（清单中的路径是**计划**，不得在本回合修改这些文件）。
 3.  确认 `02-改动点清单.md` 中仅包含代码文件改动，不涉及 `openspec/spec/` 内容。
-4.  **禁止** 修改 `src/` 等业务代码；**禁止** `/opsx-propose` 或 `/opsx-apply`。
-5.  输出时附带：`01/02/03/04 已更新，未改业务代码。需要提案时回复「继续」或提供 UI 参考路径。`
+4.  **禁止** 在阶段 B 内修改 `src/` 等业务代码。
+5.  更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
+6.  **若 `autoChainOpsx !== false`（默认）且用户未说「只提案」**：同一回合继续读 `06-opsx-自动串联指引.md`，执行 `/opsx-propose`（输入 01+02+UI）→ `/opsx-apply`；**不要**要求用户再说「继续」。
+7.  仅当 `autoChainOpsx === false` 时输出：`01/02/03/04 已更新。回复「继续」进入提案。`
 
 ---
 

package/src/templates/rules/sdd-no-implement-until-apply.mdc.template

@@ -32,10 +32,15 @@ alwaysApply: true
 1. 定位最新或对话相关的 `openspec/PRD/<runId>/`（读 `RUNME.md` 或 `.session-state.json`）。
 2. **仅**更新 `03`（写入用户结论，标为已闭合）。
 3. 再生成/更新 `01`、`02`、`04`。
-4. 回复简短说明文档已更新即可；**不要**在同一回合改 `.tsx/.ts/.vue`。
-5. 主动问一句是否需要 UI 参考路径；用户说「继续/可以/做提案」即进入 `/opsx-propose`（仍不写业务代码）。
+4. 生成 `01`、`02`、`04` 后更新 `.session-state.json`：`status: ready_for_propose`，`phase: B_done`。
+5. **默认自动串联**（`autoChainOpsx !== false`，且用户未说「只提案」「先别写代码」）：
+   - **同一回合**读 `06-opsx-自动串联指引.md`，执行 `/opsx-propose` → `/opsx-apply`。
+   - UI 参考优先：`source/PRD.md` 中的原型目录（如 `docs/adi-v232/`），其次用户本条消息给出的路径。
+   - **不要**停下来问「是否继续」或「是否 apply」。
+6. 仅当 `autoChainOpsx === false` 时：文档更新后停止，等用户说「继续」再 propose。
 
 ## 唯一允许写业务代码的时机
-- 用户已走完：`/opsx-propose` → openspec change 已 apply-ready → 用户明确同意 **`/opsx-apply`**（如「开始 apply」「执行 apply」）。
+- 阶段 D：`/opsx-propose` 已完成且 change **apply-ready** 后执行 `/opsx-apply`（SDD 默认与用户确认后**自动**进入，无需再等「开始 apply」）。
+- 用户明确「只提案」时：在 apply-ready 之前**禁止**写业务代码。
 
-若用户只说「确认了」「按上面来」但未进入 apply 阶段，**仍禁止**写业务代码。
+路径 B（03 已闭合、01/02/04 已生成）中：**禁止**仅更新文档就结束回合而不进入 propose（除非 `autoChainOpsx === false` 或用户说只提案）。

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

@@ -5,7 +5,7 @@ import sys
 import os
 import re
 from pathlib import Path
-from urllib.parse import urljoin, urlparse, unquote
+from urllib.parse import quote, urljoin, urlparse, unquote
 
 try:
     from playwright.sync_api import sync_playwright
@@ -24,6 +24,11 @@ def env(name: str, default: str | None = None) -> str:
     return str(v).strip()
 
 
+def env_bool(name: str, default: bool = False) -> bool:
+    v = env(name, "1" if default else "0").lower()
+    return v in ("1", "true", "yes", "on")
+
+
 def load_env_file(file_path: Path) -> None:
     """轻量加载 .env 文件（不依赖 python-dotenv）。"""
     if not file_path.exists() or not file_path.is_file():
@@ -57,11 +62,13 @@ def version_slug(prefix: str, version: str) -> str:
 
 
 def search_keywords(prefix: str, version: str) -> list[str]:
-    # 搜索时强制带 V，并增加不带前缀的 V 兜底项：
-    # 1) ADI-V2.3.3
-    # 2) ADI_V2.3.3
-    # 3) V2.3.3
-    return [f"{prefix}-V{version}", f"{prefix}_V{version}", f"V{version}"]
+    """固定顺序（与用户 Confluence 全局搜索习惯一致）。无论用户输入 ADI 2.3.2 还是 ADI_V2.3.2 都走这一套。"""
+    return [
+        f"{prefix}_V{version}",
+        f"{prefix}-V{version}",
+        f"{prefix}_{version}",
+        f"{prefix}-{version}",
+    ]
 
 
 def sanitize_filename(name: str) -> str:
@@ -116,23 +123,54 @@ def href_path_matches_keyword(href: str, keyword: str) -> bool:
     return kw in path or compact in path_compact
 
 
-def find_search_result(page, base_url: str, keyword: str):
-    keyword_lower = keyword.lower()
+def score_link_match(text: str, href: str, prefix: str, version: str, keyword: str) -> int:
+    """对搜索结果链接打分；>=2 视为命中。"""
+    t = (text or "").lower()
+    path = unquote(urlparse(href).path).lower()
+    kw = keyword.lower()
+    p = prefix.lower()
+    v_compact = version.replace(".", "")
+    t_compact = re.sub(r"\s+", "", t)
+    path_compact = path.replace(".", "").replace("-", "").replace("_", "")
+
+    score = 0
+    if kw in t:
+        score += 4
+    if kw.replace(".", "") in t_compact:
+        score += 3
+    if p in t and version in t:
+        score += 4
+    if p in t and v_compact in t_compact:
+        score += 3
+    if href_path_matches_keyword(href, keyword):
+        score += 3
+    slug = f"{p}v{v_compact}"
+    if slug in path_compact or f"{p}-v{v_compact}" in path or f"{p}_v{v_compact}" in path:
+        score += 4
+    return score
+
+
+def collect_search_candidates(
+    page, base_url: str, prefix: str, version: str, keyword: str
+) -> list[tuple[str, str, int]]:
+    """返回 [(url, title, score), ...]"""
     seen: set[str] = set()
+    scored: list[tuple[int, str, str]] = []
+
     selectors = [
         ".search-result .title a",
         ".search-result-title a",
         "#search-results .gs-title a",
-        f"a[href*='{keyword}']",
-        f"a:has-text('{keyword}')",
-        ".search-result a",
-        "#search-results a",
+        ".search-results-panel a",
+        "a[data-linked-resource-id]",
+        "a[href*='/pages/']",
+        "a[href*='/display/']",
     ]
-    scored: list[tuple[int, str]] = []
 
     for selector in selectors:
         links = page.locator(selector)
-        for i in range(links.count()):
+        count = min(links.count(), 200)
+        for i in range(count):
             href = links.nth(i).get_attribute("href") or ""
             raw_text = (links.nth(i).inner_text() or "").strip()
             title_text = raw_text.split("\n")[0].strip()
@@ -145,23 +183,66 @@ def find_search_result(page, base_url: str, keyword: str):
                 continue
             seen.add(full_url)
 
-            text_hit = keyword_lower in text.lower()
-            path_hit = href_path_matches_keyword(href, keyword)
-            if not text_hit:
-                continue
-
-            score = 2 + (1 if path_hit else 0)
-            scored.append((score, full_url))
+            s = score_link_match(text, href, prefix, version, keyword)
+            if s >= 2:
+                scored.append((s, full_url, text[:120]))
 
-    if not scored:
-        return None
     scored.sort(key=lambda x: x[0], reverse=True)
-    best = scored[0][1]
-    print(f"   找到文档链接: {best[:100]}...")
-    return best
+    return [(u, t, s) for s, u, t in scored]
 
 
-def run_search(page, base_url: str, keyword: str) -> str | None:
+def read_breadcrumb_text(page) -> str:
+    parts: list[str] = []
+    for selector in [
+        "#breadcrumbs li",
+        "#breadcrumbs a",
+        "ol.aui-nav-breadcrumbs li",
+        ".breadcrumbs li",
+        "nav[aria-label='Breadcrumbs'] li",
+    ]:
+        loc = page.locator(selector)
+        for i in range(min(loc.count(), 20)):
+            txt = (loc.nth(i).inner_text() or "").strip()
+            if txt and txt not in parts:
+                parts.append(txt)
+    return " > ".join(parts)
+
+
+def is_prd_page(page, page_url: str) -> bool:
+    """检查页面面包屑/父级是否属于 PRD（需求文档）。"""
+    page.goto(page_url, wait_until="networkidle", timeout=60000)
+    page.wait_for_timeout(1200)
+
+    crumbs = read_breadcrumb_text(page)
+    crumbs_upper = crumbs.upper()
+    if re.search(r"\bPRD\b", crumbs_upper) or "需求" in crumbs or "PRD" in crumbs_upper:
+        print(f"      ✓ PRD 父级命中: {crumbs[:120]}")
+        return True
+
+    try:
+        title = (page.locator("#title-text").inner_text() or "").strip()
+    except Exception:
+        title = ""
+    title_upper = title.upper()
+    if re.search(r"\bPRD\b", title_upper) or "需求文档" in title:
+        print(f"      ✓ 标题含 PRD/需求: {title[:80]}")
+        return True
+
+    print(f"      ✗ 非 PRD 父级: {crumbs[:120] or title[:80]}")
+    return False
+
+
+def run_search_dosearch(page, base_url: str, prefix: str, version: str, keyword: str) -> list[tuple[str, str, int]]:
+    url = f"{base_url.rstrip('/')}/dosearchsite.action?queryString={quote(keyword)}"
+    print(f"   → 全站搜索: {url}")
+    page.goto(url, wait_until="networkidle", timeout=60000)
+    page.wait_for_timeout(2500)
+    if is_login_page(page):
+        return []
+    return collect_search_candidates(page, base_url, prefix, version, keyword)
+
+
+def run_search_quick(page, base_url: str, prefix: str, version: str, keyword: str) -> list[tuple[str, str, int]]:
     search_selector = None
     for selector in [
         "#quick-search-query",
@@ -176,14 +257,92 @@ def run_search(page, base_url: str, keyword: str) -> str | None:
             search_selector = selector
             break
     if not search_selector:
-        if page.locator("input[type='text']").count() == 0:
-            return None
-        search_selector = "input[type='text']"
+        return []
+    print(f"   → 顶栏搜索框: {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(2000)
-    return find_search_result(page, base_url, keyword)
+    page.wait_for_timeout(2500)
+    return collect_search_candidates(page, base_url, prefix, version, keyword)
+
+
+def resolve_prd_target(
+    page, base_url: str, prefix: str, version: str, keywords: list[str]
+) -> 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}")
+        batches = [
+            ("dosearchsite", run_search_dosearch(page, base_url, prefix, version, kw)),
+            ("quick-search", run_search_quick(page, base_url, prefix, version, kw)),
+        ]
+        for method_name, candidates in batches:
+            if not candidates:
+                print(f"   ({method_name}) 无结果")
+                continue
+            print(f"   ({method_name}) {len(candidates)} 条候选，检查 PRD 父级...")
+            for url, title, _score in candidates:
+                if url in seen_urls:
+                    continue
+                seen_urls.add(url)
+                print(f"    · 候选: {title[:70]}")
+                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
+    return None, None, ""
+
+
+def is_login_page(page) -> bool:
+    url = page.url.lower()
+    if "login.action" in url or "/login" in url:
+        return True
+    if page.locator("#login-form, form#login, #username-field").count() > 0:
+        if page.locator("#login-button, #login").count() > 0:
+            return True
+    return False
+
+
+def ensure_logged_in(page, base_url: str, username: str, password: str) -> None:
+    login_url = f"{base_url.rstrip('/')}/login.action"
+    page.goto(login_url, wait_until="networkidle", timeout=60000)
+    if not is_login_page(page):
+        print("✅ 已处于登录状态")
+        return
+
+    if not username or not password:
+        raise RuntimeError("需要登录但未提供 CONFLUENCE_USERNAME / CONFLUENCE_PASSWORD")
+
+    print("🔐 正在登录 Confluence...")
+    page.wait_for_selector("#username-field, input[name='os_username']", timeout=15000)
+    user_sel = "#username-field" if page.locator("#username-field").count() else "input[name='os_username']"
+    pass_sel = "#password-field" if page.locator("#password-field").count() else "input[name='os_password']"
+    btn_sel = "#login-button" if page.locator("#login-button").count() else "#login"
+    page.fill(user_sel, username, timeout=8000)
+    page.fill(pass_sel, password, timeout=8000)
+    page.click(btn_sel)
+    page.wait_for_load_state("networkidle", timeout=45000)
+    page.wait_for_timeout(1500)
+
+    if is_login_page(page):
+        err = ""
+        for sel in [".aui-message.error", ".aui-message.aui-message-error", "#login-error"]:
+            loc = page.locator(sel)
+            if loc.count():
+                err = (loc.first.inner_text() or "").strip()
+                break
+        raise RuntimeError(
+            f"Confluence 登录失败（仍在登录页）。请检查账号密码或 .env 中的 CONFLUENCE_* 配置。{err}"
+        )
+    print("✅ 登录成功")
 
 
 def main():
@@ -192,10 +351,15 @@ 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)
+    # 从脚本目录向上查找 .env（兼容 adInsight-web/frontend 子包）
+    script_dir = Path(__file__).resolve().parent
+    cur = script_dir
+    for _ in range(8):
+        for env_name in [".env.pre", ".env", ".env.local", ".env.development", ".env.test"]:
+            load_env_file(cur / env_name)
+        if cur.parent == cur:
+            break
+        cur = cur.parent
 
     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('/')}/#all-updates"
@@ -229,8 +393,21 @@ def main():
     print(f"📁 输出目录: {docs_root}")
     print(f"🖼️ 图片目录: {version_dir}")
 
+    headed = env_bool("CONFLUENCE_HEADED") or env("CONFLUENCE_HEADLESS", "1").lower() in (
+        "0",
+        "false",
+        "no",
+    )
+    headless = not headed
+    slow_mo = int(env("CONFLUENCE_SLOW_MO", "400" if headed else "0") or "0")
+
+    print(f"🖥️  浏览器: headless={headless}, slow_mo={slow_mo}ms（有头模式: CONFLUENCE_HEADED=1）")
+
     with sync_playwright() as p:
-        browser = p.chromium.launch(headless=True)
+        launch_opts: dict = {"headless": headless}
+        if slow_mo > 0:
+            launch_opts["slow_mo"] = slow_mo
+        browser = p.chromium.launch(**launch_opts)
         context = browser.new_context(
             user_agent=(
                 "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
@@ -239,44 +416,44 @@ def main():
         )
         page = context.new_page()
         try:
-            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)
-                if found:
-                    target_url = found
-                    matched_keyword = kw
-                    break
-                print(f"   未找到 {kw}，尝试下一个关键词...")
+            print("\n📄 打开 Confluence 并登录...")
+            ensure_logged_in(page, base_url, username, password)
+            print(f"📄 当前页: {page.url[:120]}")
+
+            direct_url = env("CONFLUENCE_PAGE_URL")
+            target_url = direct_url if direct_url else None
+            matched_keyword = "CONFLUENCE_PAGE_URL" if direct_url else None
+
+            matched_title = ""
+            if not target_url:
+                target_url, matched_keyword, matched_title = resolve_prd_target(
+                    page, base_url, prefix, version, keywords
+                )
 
             if not target_url or not matched_keyword:
-                print(f"❌ 未找到 {prefix} {version} 的需求文档，请检查 Confluence 页面命名。")
+                debug_path = docs_root / "confluence-search-debug.png"
+                try:
+                    page.screenshot(path=str(debug_path), full_page=True)
+                    print(f"   已保存调试截图: {debug_path}")
+                except Exception:
+                    pass
+                print(f"❌ 未找到 {prefix} {version} 的需求文档。")
+                print(
+                    "   排查：1) 是否存在 PRD 父级页面  2) 依次尝试 ADI_V2.3.2 / ADI-V2.3.2 / ADI_2.3.2 / ADI-2.3.2"
+                )
+                print("   3) 或设置 CONFLUENCE_PAGE_URL=<页面完整URL> 直接下载")
                 sys.exit(1)
 
-            print(f"✅ 命中: {matched_keyword}")
-            print(f"   进入页面: {target_url[:120]}...")
+            print(f"✅ 命中关键词: {matched_keyword}")
+            if matched_title:
+                print(f"   页面: {matched_title[:100]}")
+            print(f"   URL: {target_url[:120]}...")
             page.goto(target_url, wait_until="networkidle", timeout=60000)
 
             try:
                 title = page.locator("#title-text").text_content().strip()
             except Exception:
-                title = f"{matched_keyword} 需求文档"
+                title = matched_title or f"{matched_keyword} 需求文档"
 
             content_elem = page.locator("#main-content")
             if not content_elem.count():
@@ -331,6 +508,11 @@ def main():
             print(f"\n❌ 获取失败: {e}")
             raise
         finally:
+            if env_bool("CONFLUENCE_DEBUG_PAUSE", default=not headless):
+                try:
+                    input("\n⏸ 调试暂停：按 Enter 关闭浏览器...")
+                except (EOFError, KeyboardInterrupt):
+                    pass
             browser.close()
 
 

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

@@ -27,6 +27,12 @@ python3 confluence-doc.py <版本号>
 
 说明：脚本内置默认账号密码（`lixinxin` / `Xin@147258`），可直接执行；如需覆盖，再设置 `CONFLUENCE_USERNAME` / `CONFLUENCE_PASSWORD`。
 
+有头调试（可观察登录与搜索过程）：
+
+```bash
+CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 CONFLUENCE_DEBUG_PAUSE=1 python3 confluence-doc.py ADI_V2.3.2
+```
+
 版本号支持多种写法：
 
 ```bash
@@ -36,11 +42,14 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}-V1.2.3
 python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 ```
 
-脚本搜索顺序（强制带 `V`）：
+脚本搜索顺序（**固定**，即使用户说「{{PRODUCT_PREFIX}} 1.2.3」也按此顺序）：
+
+1. `{{PRODUCT_PREFIX}}_V<版本>`（如 ADI_V2.3.2）
+2. `{{PRODUCT_PREFIX}}-V<版本>`（如 ADI-V2.3.2）
+3. `{{PRODUCT_PREFIX}}_<版本>`（如 ADI_2.3.2）
+4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
 
-1. `{{PRODUCT_PREFIX}}-V<版本>`
-2. `{{PRODUCT_PREFIX}}_V<版本>`
-3. `V<版本>`（兜底）
+每个关键词都会走全站搜索 + 顶栏搜索；在候选结果中**优先选面包屑父级含 PRD 的页面**。
 
 ## 输出结构