sdd-flow-kit 1.0.18 → 1.0.22

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`（完整环境）

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"), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.0.18",
+  "version": "1.0.22",
   "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/06-agent-skill.template.md

@@ -41,7 +41,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）**

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 的页面**。
 
 ## 输出结构