sdd-flow-kit 1.3.0 → 1.3.5

package/README.md

@@ -35,6 +35,7 @@ npx sdd-flow-kit doctor --agent cursor
 ```bash
 cd <你的项目目录>                    # cd 到哪，装到哪
 pnpm add -D sdd-flow-kit             # ① postinstall 自动轻量写入 skill
+pnpm add -D sdd-flow-kit@latest
 npx sdd-flow-kit install --project <类型> -y   # ② 全量 OPSX（按需）
 ```
 
@@ -55,136 +56,9 @@ ls docs/*-doc-skill/SKILL.md
 ls .claude/skills/sdd-flow-kit/SKILL.md
 ```
 
-**postinstall 行为（v1.2.4+）**：
+如果找不到，则执行下面的命令
 
-- 默认 **light**：写入 SDD skill、Cursor 规则、docs-skill、`.opsx/config.json`；**不**跑 `opsx-workflow`（避免 `pnpm i` 卡住）
-- 自动解析项目根：`INIT_CWD`（pnpm/npm）→ 从 `node_modules` 向上找消费方 `package.json` → `process.cwd()`（手动执行时）
-- 全量 postinstall：`SDD_FLOW_KIT_POSTINSTALL_FULL=1 pnpm add -D sdd-flow-kit`
-- 跳过 postinstall：`SDD_FLOW_KIT_SKIP_POSTINSTALL=1 pnpm add -D sdd-flow-kit`
-
-> 环境变量覆盖项目类型：`SDD_FLOW_KIT_PROJECT=ADI pnpm add -D sdd-flow-kit`
-
-#### 安装失败排查
-
-当没有生成 `.cursor/skills/sdd-flow-kit/SKILL.md` 时：
-
-1. 检查包是否已安装：`pnpm list sdd-flow-kit --depth 0`
-2. **pnpm v10** 若出现 `Ignored build scripts: sdd-flow-kit`：
-   - `pnpm approve-builds` 选中 `sdd-flow-kit`，或
-   - 在 `package.json` 加 `"pnpm": { "onlyBuiltDependencies": ["sdd-flow-kit"] }` 后 `pnpm install`
-3. 若出现 `ERR_PNPM_UNEXPECTED_STORE`，对齐 store 后重装：`pnpm install`
-4. 手动触发轻量安装（任选其一，**须在项目根目录**）：
-   - `node ./node_modules/sdd-flow-kit/dist/postinstall.js`（v1.2.4+ 无需 `INIT_CWD`）
-   - `pnpm rebuild sdd-flow-kit`
-   - `npx sdd-flow-kit install --project OMS -y`（按项目改类型，全量）
-5. 验证：`ls .cursor/skills/sdd-flow-kit/SKILL.md docs/*-doc-skill/SKILL.md`
-
-首次跑任意 CLI（`doctor` / `run` / `gate` 等）也会自动 bootstrap 补装缺失的 SDD skill 或 OPSX。
-
-##### `pnpm add` 后依赖全被删掉（`Packages: +1 -932`）
-
-**原因**：`pnpm` 会按当前 `package.json` **同步** `node_modules`。若 manifest 里只剩 `sdd-flow-kit`（或文件被误保存成几行空壳），就会卸载其它所有包——**不是** `pnpm add` 单独删包，而是 manifest 已不完整。
-
-**恢复**（在业务仓如 `adInsight-web/frontend`）：
-
-1. 用 Git 恢复完整 `package.json`：`git checkout -- package.json`
-2. 重装：`pnpm install`
-3. 再装 kit（建议 **≥ 1.1.2**，且必须在有完整 `package.json` 的目录执行）：
-   - `cd frontend && pnpm add -D sdd-flow-kit@1.1.2`
-   - 或本地联调：`pnpm add -D file:../../sdd-flow-kit`
-
-**v1.1.2+ 防护**：`repairOpsxDeliveryScripts` 仅合并 `scripts`，写入前检查依赖条数与文件体积。
-
-**v1.2.4+ postinstall**：默认 light；自动解析消费方项目根（不依赖 `INIT_CWD`）；首次安装后会写入 `pnpm.onlyBuiltDependencies` 以便后续 `pnpm install` 执行脚本。
-
-#### 使用说明
-
-##### 安装根：cd 到哪，装到哪（v1.2+）
-
-默认 **`installRoot = 你执行命令时的当前目录`**（`process.cwd()`），也可用 `--project-root` / `SDD_FLOW_KIT_INSTALL_ROOT` 指定。
-
-| 你 cd 到 | 会安装到 |
-|----------|----------|
-| `adInsight-web/frontend` | `frontend/package.json`、`.cursor/skills`、`.opsx`、`pnpm run opsx:delivery-pipeline` |
-| `adInsight-web`（仓库根） | 仓库根（需根目录也有 `package.json`，否则会失败） |
-
-```bash
-cd /path/to/adInsight-web/frontend
-npx sdd-flow-kit install --project ADI -y
-npx sdd-flow-kit run --product ADI --version 2.3.2 -y
-```
-
-**PRD / gate 的 `--project-root`**：与安装根相同；若 `openspec/` 在上级目录，工具会**向上查找**已有 `openspec/PRD`（不把安装写到上级）。
-
-旧行为（在仓库根执行时自动落到 `frontend/`）：设置 `SDD_FLOW_KIT_LEGACY_MONOREPO=1`。
-
-##### 脚本门禁（v1.1+，**不依赖自然语言**）
-
-`run` 会在 `openspec/PRD/<runId>/NEXT.md` 写入**必须按顺序执行的命令**。AI 与人都以 **exit code** 为准：失败则不得进入下一阶段、不得改 `src/`。
-
-```bash
-# 门禁（失败 exit 1）
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-fetched
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect docs-closed      # 含 05 已定义 + 无 src 改动
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect propose-ready --change <name>
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect ac-ready --change <name>
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect impl-allowed --change <name>
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect ac-signed
-npx sdd-flow-kit gate --project-root . --run-id <runId> --expect shipped --change <name>
-
-# 阶段推进（更新 .session-state.json + NEXT.md）
-npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to after-prd
-npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to docs-done
-npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to propose-done --change <name>
-npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to impl --change <name>
-npx sdd-flow-kit phase advance --project-root . --run-id <runId> --to shipped --change <name>
-
-# 提案 / 交付
-npx sdd-flow-kit propose --project-root . --run-id <runId> --change <name>
-npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>
-```
-
-`docs-closed` 会在 git 仓库中扫描 `src/`、`frontend/src/` 等路径；文档阶段若已有实现层改动，**gate 失败**。同时要求 `05-验收清单.md` 已标注「定义状态：已定义」且含 P0 项。
-
-##### v1.3.0 — 验收清单（AC Matrix）流程
-
-| 文档/门禁 | 说明 |
-|-----------|------|
-| `05-验收清单.md` | 从 `source/PRD.md` 逐条抽 AC；**唯一验收 SSOT** |
-| `gate docs-closed` | 含 05 已定义 + 01/02/04 + 03 闭合 |
-| `gate ac-ready` | propose 后：每条 P0 在 `tasks.md`/`spec.md` 含 `[AC-XX]` |
-| `gate ac-signed` | deliver 前：05 中 P0 已验收 + 「签收状态：已签收」 |
-| `LAYERED-TESTING.md` | 安装到 `.cursor/skills/sdd-flow-kit/`（L1–L4 测试策略） |
-
-推荐文档顺序：**03 闭合 → 05 → 04（引用 AC）→ 01/02**。
-
-原 `05-openspec-提案草稿` / `06-opsx` 已顺延为 **`06-openspec-提案草稿`** / **`07-opsx-自动串联指引`**。
-
-##### 需求澄清：用户无需背提示词
-
-`install` 会写入 `.cursor/rules/sdd-flow-kit-gates.mdc` 与触发 Skill（已改为**脚本优先**）。  
-用户粘贴确认点后：先更新 **05→04→01/02/03**，再执行 `gate docs-closed` → `phase advance --to docs-done`；propose 后 `gate ac-ready`；deliver 前 `gate ac-signed`。**禁止**跳过 gate 直接改代码。
-
-##### `/opsx-apply` 与 TDD + Playwright 检查机制
-
-| 环节 | 实现 | 说明 |
-|------|------|------|
-| 安装时 | `postinstall`（light） | 只写 sdd skill/rule；**不**自动跑 opsx-workflow（避免 `pnpm i` 卡住） |
-| 完整安装 | `npx sdd-flow-kit install -y` | 缺什么跑什么 → `ensureOpsxWorkflow` → `npx @lixin5257xxx/opsx-workflow setup` |
-| Apply 前 | `npx sdd-flow-kit ensure-opsx -y` | **阶段 D 第 0 步**；doctor 加 `--fix` 等价修复 |
-| Apply 时 | Cursor 读 skill 链 + `pnpm run opsx:delivery-pipeline` | 由 `AGENTS.md` / `06-agent-skill` 约束 AI，非 Node 自动执行 |
-
-```bash
-npx sdd-flow-kit ensure-opsx --agent cursor -y   # /opsx-apply 前
-npx sdd-flow-kit doctor --agent cursor --fix     # 检查并尝试修复
-```
-
-常见遗漏：只 `pnpm add sdd-flow-kit` 未跑 `ensure-opsx`；或 AI 跳过 skill 直接改代码。
-
-1.  `install`（等价 `setup`）：提示选择开发环境（cursor/claude-code/codex/openclaw，默认 claude-code）与开发分支（无则自动创建），并检测/安装 openspec+superpower 基础环境，同时写入项目级 Skill 与 Cursor 门禁规则
-2.  安装完成后，本工具主要负责“流程环境与模板”落地；业务需求由你在目标 AI 工具中自然语言驱动
-3.  `start`/`run`/`invoke` 属于进阶能力（脚本化或一键编排时使用）
-4.  `doctor`：检查 git/npx/agent CLI/openspec/tool 目录，输出可机读诊断结果
+node ./node_modules/sdd-flow-kit/dist/postinstall.js
 
 #### 当前自动化边界
 
@@ -204,25 +78,11 @@ npx sdd-flow-kit doctor --agent cursor --fix     # 检查并尝试修复
     - 非 scoped 或后续版本：`npm publish`
 6.  发布后验证：在任意项目执行 `npm i -D sdd-flow-kit`，再执行 `npx sdd-flow-kit install`
 
-版本升级建议：
-
-1.  修改版本号：`npm version patch`（或 `minor` / `major`）
-2.  重新执行构建与发布步骤
-3.  在 `README.md` 或变更记录中补充本次升级说明
-
-#### 参与贡献
-
-1.  Fork 本仓库
-2.  新建 Feat_xxx 分支
-3.  提交代码
-4.  新建 Pull Request
-
+#### 变更记录
 
-#### 特技
+**1.3.3** — Confluence PRD 拉取修复（ADI 长标题页）
 
-1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
-2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
-3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
-4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
-5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
-6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+- `confluence-doc.py`：匹配时统一 `-`/`_`；ADI 增加 `ADI_V*结算` 关键词
+- ADI 需求页无「PRD」面包屑时按 `ADI_V*` / 结算开票回款标题识别
+- 支持 `CONFLUENCE_PAGE_ID` 直链（如 V2.3.4 → `109609740`）
+- `dosearchsite` 搜索改用 `domcontentloaded`，降低网络抖动失败率

package/package.json

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

@@ -12,11 +12,31 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 版本号可传：`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*` 等。
+2. 脚本会依次搜索（含用户原样输入）：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
 
-3. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+3. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+
+4. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
    - `source/PRD.md`
 
+## 直链兜底（已知 pageId 时推荐）
+
+ADI V2.3.4 示例（`yyzcpt` 空间 pageId `109609740`）：
+
+```bash
+cd {{DOC_SKILL_REL}}
+export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
+export CONFLUENCE_PAGE_ID=109609740
+python3 confluence-doc.py 2.3.4
+```
+
+或：
+
+```bash
+export CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/ADI_V2.3.4结算、开票、回款数据对接欢聚"
+python3 confluence-doc.py 2.3.4
+```
+
 ## 路径说明
 
 - 推荐脚本目录：`{{DOC_SKILL_REL}}`（已向上解析，可能是 `docs/adi-doc-skill` 或 `../docs/adi-doc-skill`）
@@ -24,6 +44,10 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 ## 失败排查
 
-- 输出 `❌ 未找到`：到 Confluence 确认页面标题是否含 `{{PRODUCT_PREFIX}}-V2.3.2` 或 `{{PRODUCT_PREFIX}}_V2.3.2`
+- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）
+- 页面存在但搜不到：设置 `CONFLUENCE_PAGE_ID=<pageId>` 或 `CONFLUENCE_PAGE_URL=<完整URL>` 直链下载
+- Playwright 失败且设置 `CONFLUENCE_USE_REST=1` 时才回退 Token；登录最多重试 3 次，并用 `expect_navigation` 避免竞态
+- 登录偶发失败：用 `CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500` 有头观察；失败截图 `confluence-login-fail-*.png`
 - `playwright` 未安装：`pip install playwright && playwright install chromium`
+- Token 仅作应急回退：`CONFLUENCE_USE_REST=1`（Token 会过期，不作为默认路径）
 - 仍失败：在仓库根执行 `npx sdd-flow-kit install --project {{PRODUCT}} -y` 后重试

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

@@ -1,11 +1,14 @@
 #!/usr/bin/env python3
 """Confluence 需求文档获取脚本（Playwright - 通用版）"""
 
+import json
 import sys
 import os
 import re
 from pathlib import Path
-from urllib.parse import quote, urljoin, urlparse, unquote
+from urllib.parse import quote, urlencode, urljoin, urlparse, unquote
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
 
 try:
     from playwright.sync_api import sync_playwright
@@ -15,6 +18,8 @@ except ImportError:
 
 DEFAULT_CONFLUENCE_USERNAME = "lixinxin"
 DEFAULT_CONFLUENCE_PASSWORD = "Xin@147258"
+# Confluence REST API Bearer Token（优先于 Playwright 登录，确保 Step1 可稳定拉取 PRD）
+DEFAULT_CONFLUENCE_API_TOKEN = "NTc3NDMzNjQxNjE3OiDitymjYiVP9cQ4PfTzkgOeb+DA"
 
 
 def env(name: str, default: str | None = None) -> str:
@@ -61,24 +66,64 @@ def version_slug(prefix: str, version: str) -> str:
     return prefix.lower() + "-v" + version.replace(".", "")
 
 
-def search_keywords(prefix: str, version: str) -> list[str]:
-    """固定顺序（与用户 Confluence 全局搜索习惯一致）。"""
+def dedupe_keywords(items: list[str]) -> list[str]:
+    """去重并保持顺序。"""
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        key = item.strip()
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        out.append(key)
+    return out
+
+
+def normalize_match_token(text: str) -> str:
+    """匹配时统一 -/_ 与大小写，避免 ADI-V 与 ADI_V 标题不一致导致漏命中。"""
+    return text.lower().replace("-", "_").replace(".", "")
+
+
+def search_keywords(prefix: str, version: str, raw_input: str | None = None) -> list[str]:
+    """固定顺序（与用户 Confluence 全局搜索习惯一致）。
+
+    ADI 等产品的典型降级链：
+    用户原样输入 → ADI_V2.3.4 → ADI-V2.3.4 → ADI_2.3.4 → ADI-2.3.4
+    → ADI_v2.3.4 → ADI-v2.3.4 → ADI V2.3.4 → ADI_V2.3.4结算 → V2.3.4
+    """
     p = prefix.strip()
     # BreakX（破圈引擎）PRD 在 xhs 空间，页面标题多为 V1.0.2 xxx，而非 BreakX_V1.0.2
     if p.upper() in ("BREAKX", "BX"):
-        return [
+        return dedupe_keywords(
+            [
+                *( [raw_input.strip()] if raw_input and raw_input.strip() else [] ),
+                f"V{version}",
+                f"BreakX V{version}",
+                f"BreakX_V{version}",
+                f"BreakX-V{version}",
+                f"xhs V{version}",
+            ]
+        )
+    adi_long_title_kw: list[str] = []
+    if p.upper() == "ADI":
+        adi_long_title_kw = [
+            f"ADI_V{version}结算",
+            f"ADI_V{version}结算、开票、回款",
+        ]
+    return dedupe_keywords(
+        [
+            *( [raw_input.strip()] if raw_input and raw_input.strip() else [] ),
+            f"{prefix}_V{version}",
+            f"{prefix}-V{version}",
+            f"{prefix}_{version}",
+            f"{prefix}-{version}",
+            f"{prefix}_v{version}",
+            f"{prefix}-v{version}",
+            f"{prefix} V{version}",
+            *adi_long_title_kw,
             f"V{version}",
-            f"BreakX V{version}",
-            f"BreakX_V{version}",
-            f"BreakX-V{version}",
-            f"xhs V{version}",
         ]
-    return [
-        f"{prefix}_V{version}",
-        f"{prefix}-V{version}",
-        f"{prefix}_{version}",
-        f"{prefix}-{version}",
-    ]
+    )
 
 
 def sanitize_filename(name: str) -> str:
@@ -126,36 +171,40 @@ def absolutize_href(base_url: str, href: str) -> str:
 
 
 def href_path_matches_keyword(href: str, keyword: str) -> bool:
-    path = unquote(urlparse(href).path).lower()
-    kw = keyword.lower()
-    compact = kw.replace(".", "")
-    path_compact = path.replace(".", "")
-    return kw in path or compact in path_compact
+    path_norm = normalize_match_token(unquote(urlparse(href).path))
+    kw_norm = normalize_match_token(keyword)
+    return kw_norm in path_norm
+
+
+def text_matches_keyword(text: str, keyword: str) -> bool:
+    """标题/链接文案匹配：忽略 -/_ 差异。"""
+    return normalize_match_token(keyword) in normalize_match_token(text)
 
 
 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()
+    kw_norm = normalize_match_token(keyword)
     p = prefix.lower()
     v_compact = version.replace(".", "")
-    t_compact = re.sub(r"\s+", "", t)
-    path_compact = path.replace(".", "").replace("-", "").replace("_", "")
+    t_norm = normalize_match_token(text or "")
+    t_compact = re.sub(r"\s+", "", t_norm)
+    path_norm = normalize_match_token(path)
 
     score = 0
-    if kw in t:
+    if text_matches_keyword(text, keyword):
         score += 4
-    if kw.replace(".", "") in t_compact:
+    if kw_norm 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:
+    if p in t_norm and v_compact in t_compact:
         score += 3
     if href_path_matches_keyword(href, keyword):
-        score += 3
+        score += 4
     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:
+    if slug in path_norm or f"{p}-v{v_compact}" in path or f"{p}_v{v_compact}" in path:
         score += 4
     # BreakX：标题以 V1.0.2 开头时加分
     if p in ("breakx", "bx") and (t.startswith(f"v{version}") or f"v{version}" in t[:12]):
@@ -224,14 +273,44 @@ def read_breadcrumb_text(page) -> str:
     return " > ".join(parts)
 
 
+def is_adi_requirement_page(title: str, crumbs: str, page_url: str) -> bool:
+    """ADI 需求页常无 PRD 字样，标题形如 ADI_V2.3.4结算、开票、回款数据对接欢聚。"""
+    title_upper = (title or "").upper()
+    crumbs_upper = (crumbs or "").upper()
+    if re.search(r"ADI[_-]?V\d+\.\d+\.\d+", title_upper):
+        print(f"      ✓ ADI 版本标题命中: {title[:80]}")
+        return True
+    adi_markers = ("结算", "开票", "回款", "对接欢聚", "数据对接")
+    if any(m in title for m in adi_markers) and "ADI" in title_upper:
+        print(f"      ✓ ADI 财务对接标题命中: {title[:80]}")
+        return True
+    if "ADI" in crumbs_upper and re.search(r"V\d+\.\d+\.\d+", title_upper + crumbs_upper):
+        print(f"      ✓ ADI 面包屑+版本命中: {crumbs[:80]} / {title[:60]}")
+        return True
+    if "/spaces/yyzcpt/" in page_url.lower() and re.search(r"ADI[_-]?V", title_upper):
+        print(f"      ✓ yyzcpt 空间 ADI 页面: {title[:80]}")
+        return True
+    return False
+
+
 def is_prd_page(page, page_url: str) -> bool:
     """检查页面面包屑/父级是否属于 PRD（需求文档）。"""
-    page.goto(page_url, wait_until="networkidle", timeout=60000)
+    page.goto(page_url, wait_until="domcontentloaded", timeout=60000)
     page.wait_for_timeout(1200)
 
     crumbs = read_breadcrumb_text(page)
     crumbs_upper = crumbs.upper()
     prefix = env("DOC_PRODUCT_PREFIX", "").upper()
+
+    try:
+        title = (page.locator("#title-text").inner_text() or "").strip()
+    except Exception:
+        title = ""
+
+    # ADI：标题常无「PRD/需求」字样，单独识别
+    if prefix == "ADI" and is_adi_requirement_page(title, crumbs, page_url):
+        return True
+
     # BreakX：xhs 空间 PRD 挂在「产品设计」下，不一定有 PRD 字样
     if prefix in ("BREAKX", "BX") and "/spaces/xhs/" in page_url.lower():
         if "产品设计" in crumbs or "BREAKX" in crumbs_upper or "破圈" in crumbs:
@@ -241,10 +320,6 @@ def is_prd_page(page, page_url: str) -> bool:
         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]}")
@@ -254,10 +329,308 @@ def is_prd_page(page, page_url: str) -> bool:
     return False
 
 
+def resolve_direct_page_url(base_url: str) -> str | None:
+    """支持 CONFLUENCE_PAGE_URL 或 CONFLUENCE_PAGE_ID 直链，跳过搜索。"""
+    page_url = env("CONFLUENCE_PAGE_URL")
+    if page_url:
+        return page_url
+    page_id = resolve_direct_page_id()
+    if page_id:
+        return f"{base_url.rstrip('/')}/pages/viewpage.action?pageId={page_id}"
+    return None
+
+
+def resolve_direct_page_id() -> str | None:
+    """从环境变量或 URL 中解析 pageId。"""
+    page_id = env("CONFLUENCE_PAGE_ID")
+    if page_id:
+        return page_id
+    page_url = env("CONFLUENCE_PAGE_URL")
+    if not page_url:
+        return None
+    m = re.search(r"/pages/(\d+)", page_url)
+    if m:
+        return m.group(1)
+    m = re.search(r"pageId=(\d+)", page_url, flags=re.IGNORECASE)
+    if m:
+        return m.group(1)
+    return None
+
+
+def get_api_token() -> str:
+    """读取 Confluence REST Bearer Token。"""
+    return (
+        env("CONFLUENCE_API_TOKEN")
+        or env("CONFLUENCE_TOKEN")
+        or env("CONFLUENCE_BEARER_TOKEN")
+        or DEFAULT_CONFLUENCE_API_TOKEN
+    )
+
+
+def rest_request(base_url: str, token: str, path: str, params: dict | None = None) -> dict:
+    """调用 Confluence REST API，失败时抛出可读异常。"""
+    query = f"?{urlencode(params)}" if params else ""
+    url = f"{base_url.rstrip('/')}{path}{query}"
+    req = Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urlopen(req, timeout=60) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")[:300]
+        raise RuntimeError(f"REST API HTTP {e.code}: {body}") from e
+    except URLError as e:
+        raise RuntimeError(f"REST API 网络错误: {e}") from e
+
+
+def rest_fetch_page(base_url: str, token: str, page_id: str) -> dict:
+    """按 pageId 拉取页面标题与 storage HTML。"""
+    data = rest_request(
+        base_url,
+        token,
+        f"/rest/api/content/{page_id}",
+        {"expand": "body.storage,space"},
+    )
+    html = data.get("body", {}).get("storage", {}).get("value", "")
+    if not html or len(html) < 20:
+        raise RuntimeError(f"pageId={page_id} 正文为空或过短")
+    return {
+        "id": str(data.get("id", page_id)),
+        "title": data.get("title", "").strip() or f"page-{page_id}",
+        "html": html,
+        "space": (data.get("space") or {}).get("key", ""),
+        "url": f"{base_url.rstrip('/')}/pages/viewpage.action?pageId={page_id}",
+    }
+
+
+def rest_search_candidates(
+    base_url: str, token: str, prefix: str, version: str, keyword: str
+) -> list[tuple[int, str, str]]:
+    """CQL 搜索页面，返回 [(score, page_id, title), ...]。"""
+    cql = f'type=page and title ~ "{keyword.replace(chr(34), "")}"'
+    space = env("CONFLUENCE_SPACE")
+    if space:
+        cql = f'space="{space}" and {cql}'
+    data = rest_request(
+        base_url,
+        token,
+        "/rest/api/content/search",
+        {"cql": cql, "limit": "15"},
+    )
+    scored: list[tuple[int, str, str]] = []
+    for item in data.get("results", []):
+        title = (item.get("title") or "").strip()
+        page_id = str(item.get("id", ""))
+        if not page_id:
+            continue
+        href = f"/spaces/{(item.get('space') or {}).get('key', '')}/pages/{page_id}/"
+        score = score_link_match(title, href, prefix, version, keyword)
+        if score >= 2:
+            scored.append((score, page_id, title))
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return scored
+
+
+def rest_resolve_target(
+    base_url: str, token: str, prefix: str, version: str, keywords: list[str]
+) -> tuple[str, str, str, str] | None:
+    """REST 搜索命中页面，返回 (page_id, title, keyword, url)。"""
+    direct_id = resolve_direct_page_id()
+    if direct_id:
+        page = rest_fetch_page(base_url, token, direct_id)
+        kw = keywords[0] if keywords else f"{prefix}_V{version}"
+        return page["id"], page["title"], kw, page["url"]
+
+    fallback: tuple[str, str, str, str] | None = None
+    for kw in keywords:
+        print(f"\n🔍 [REST] 搜索: {kw}")
+        candidates = rest_search_candidates(base_url, token, prefix, version, kw)
+        if not candidates:
+            print(f"   未找到 {kw}")
+            continue
+        for score, page_id, title in candidates:
+            print(f"   候选 (score={score}): {title[:80]}")
+            page = rest_fetch_page(base_url, token, page_id)
+            if prefix.upper() == "ADI" and is_adi_title_match(title, version):
+                return page_id, page["title"], kw, page["url"]
+            if score >= 4:
+                return page_id, page["title"], kw, page["url"]
+            if fallback is None:
+                fallback = (page_id, page["title"], kw, page["url"])
+    return fallback
+
+
+def is_adi_title_match(title: str, version: str) -> bool:
+    """ADI 长标题页识别（面包屑可无 PRD 字样）。"""
+    title_upper = (title or "").upper()
+    v_compact = version.replace(".", "")
+    if re.search(rf"ADI[_-]?V{re.escape(version)}", title_upper):
+        return True
+    if re.search(rf"ADI[_-]?V{v_compact}", normalize_match_token(title)):
+        return True
+    markers = ("结算", "开票", "回款", "对接欢聚", "数据对接", "蒲公英", "报价单")
+    return "ADI" in title_upper and any(m in title for m in markers)
+
+
+def clean_confluence_storage_html(html: str) -> str:
+    """清理 Confluence storage 宏标签，便于转 Markdown。"""
+    html = re.sub(
+        r"<ac:structured-macro[^>]*>.*?</ac:structured-macro>",
+        "",
+        html,
+        flags=re.DOTALL,
+    )
+    html = re.sub(r"<ac:parameter[^>]*>.*?</ac:parameter>", "", html, flags=re.DOTALL)
+    html = re.sub(
+        r"<ac:plain-text-body><!\[CDATA\[(.*?)\]\]></ac:plain-text-body>",
+        r"\1",
+        html,
+        flags=re.DOTALL,
+    )
+    html = re.sub(r"<ac:link[^>]*><ri:page[^>]*></ac:link>", "", html)
+    html = re.sub(r"<ac:image[^>]*>.*?</ac:image>", "", html, flags=re.DOTALL)
+    return html
+
+
+def download_images_http(
+    base_url: str,
+    token: str,
+    content_html: str,
+    version_dir: Path,
+    slug: str,
+    request_get=None,
+) -> str:
+    """下载正文图片并改写相对路径；request_get 可注入 Playwright page.request.get。"""
+    img_urls = re.findall(r'<img[^>]*src="([^"]+)"', content_html)
+    for i, img_url in enumerate(img_urls):
+        original_url = img_url
+        if img_url.startswith("//"):
+            img_url = "https:" + img_url
+        elif img_url.startswith("/"):
+            img_url = base_url.rstrip("/") + img_url
+        elif not img_url.startswith("http"):
+            img_url = urljoin(base_url, img_url)
+
+        if not img_url.startswith("http") or img_url.startswith("data:"):
+            continue
+        parsed = urlparse(img_url)
+        ext = os.path.splitext(parsed.path)[1] or ".png"
+        filename = f"image_{i + 1}{ext}"
+        filepath = version_dir / filename
+        try:
+            if request_get:
+                resp = request_get(img_url)
+                body = resp.body() if hasattr(resp, "body") else resp.read()
+                ok = resp.ok if hasattr(resp, "ok") else True
+            else:
+                req = Request(
+                    img_url,
+                    headers={"Authorization": f"Bearer {token}"},
+                )
+                with urlopen(req, timeout=30) as resp:
+                    body = resp.read()
+                    ok = True
+            if ok and body:
+                filepath.write_bytes(body)
+                content_html = content_html.replace(
+                    f'src="{original_url}"', f'src="{slug}/{filename}"'
+                )
+        except Exception:
+            pass
+    return content_html
+
+
+def write_prd_markdown(
+    docs_root: Path,
+    title: str,
+    matched_keyword: str,
+    target_url: str,
+    content_html: str,
+    prefix: str,
+    base_url: str,
+    token: str,
+    version_dir: Path,
+    slug: str,
+    request_get=None,
+) -> Path:
+    """将 HTML 转 Markdown 并写入 docs 目录。"""
+    html = clean_confluence_storage_html(content_html)
+    html = download_images_http(base_url, token, html, version_dir, slug, request_get)
+    content_md = parse_html_to_markdown(html)
+    md_content = f"""# {title}
+
+> 版本: {matched_keyword}
+> 来源: {target_url}
+
+---
+
+{content_md}
+"""
+    md_filename = sanitize_filename(title) + ".md"
+    if not re.search(rf"{prefix}[-_]?V", md_filename, flags=re.IGNORECASE):
+        md_filename = f"{matched_keyword}-{md_filename}"
+    md_path = docs_root / md_filename
+    md_path.write_text(md_content, encoding="utf-8")
+    return md_path
+
+
+def try_rest_download(
+    base_url: str,
+    prefix: str,
+    version: str,
+    keywords: list[str],
+    docs_root: Path,
+    version_dir: Path,
+    slug: str,
+) -> bool:
+    """REST API 主路径：Bearer Token 拉取 PRD，不依赖 Playwright 登录。"""
+    token = get_api_token()
+    if not token:
+        print("   ⚠ 未配置 CONFLUENCE_API_TOKEN，跳过 REST")
+        return False
+    try:
+        resolved = rest_resolve_target(base_url, token, prefix, version, keywords)
+        if not resolved:
+            print("   REST 未命中任何页面")
+            return False
+        page_id, title, matched_keyword, target_url = resolved
+        print(f"✅ [REST] 命中: {matched_keyword} | {title[:80]}")
+        page = rest_fetch_page(base_url, token, page_id)
+        md_path = write_prd_markdown(
+            docs_root,
+            page["title"],
+            matched_keyword,
+            target_url,
+            page["html"],
+            prefix,
+            base_url,
+            token,
+            version_dir,
+            slug,
+        )
+        if md_path.stat().st_size < 80:
+            raise RuntimeError("生成的 Markdown 过短")
+        print("\n✅ 获取完成（REST API）！")
+        print(f"📄 主文档: {md_path}")
+        print(f"🖼️ 图片目录: {version_dir}")
+        return True
+    except Exception as e:
+        print(f"   REST 拉取失败: {e}")
+        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)
+    try:
+        page.goto(url, wait_until="domcontentloaded", timeout=60000)
+    except Exception:
+        page.goto(url, wait_until="load", timeout=60000)
     page.wait_for_timeout(2500)
     if is_login_page(page):
         return []
@@ -324,47 +697,96 @@ def resolve_prd_target(
 
 
 def is_login_page(page) -> bool:
+    """判断是否仍在登录页（禁止用宽泛的 'login' in url，避免误判）。"""
     url = page.url.lower()
-    if "login.action" in url or "/login" in url:
+    if "login.action" in url:
         return True
-    if page.locator("#login-form, form#login, #username-field").count() > 0:
-        if page.locator("#login-button, #login").count() > 0:
+    user_field = page.locator("#username-field, input[name='os_username']")
+    pass_field = page.locator("#password-field, input[name='os_password']")
+    if user_field.count() > 0 and pass_field.count() > 0:
+        try:
+            if user_field.first.is_visible() and pass_field.first.is_visible():
+                return True
+        except Exception:
             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
+def is_session_authenticated(page, base_url: str) -> bool:
+    """通过 Confluence 页面 meta 与会话页探测是否已登录（比 URL 判断更可靠）。"""
+    try:
+        remote_user = page.locator('meta[name="ajs-remote-user"]').get_attribute("content") or ""
+        if remote_user.strip():
+            return True
+    except Exception:
+        pass
+    return not is_login_page(page)
 
+
+def ensure_logged_in(page, base_url: str, username: str, password: str, max_retries: int = 3) -> None:
+    """登录 Confluence；用 expect_navigation 包裹点击，并以 remote-user 校验会话。"""
+    login_url = f"{base_url.rstrip('/')}/login.action"
     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)
+    last_err = ""
+    for attempt in range(1, max_retries + 1):
+        page.goto(login_url, wait_until="domcontentloaded", timeout=60000)
+        if is_session_authenticated(page, base_url):
+            print("✅ 已处于登录状态")
+            return
+
+        print(f"🔐 正在登录 Confluence...（第 {attempt}/{max_retries} 次）")
+        page.wait_for_selector("#username-field, input[name='os_username']", state="visible", timeout=15000)
+        # 等待 Atlassian 登录网关 React 表单可交互，避免偶发「点了但没提交」
+        page.wait_for_timeout(400)
+
+        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.wait_for_timeout(200)
+
+        btn = page.locator(btn_sel)
+        try:
+            # 关键：导航与点击同一事务，避免 click 后 wait_for_url 的竞态（旧逻辑约 30% 失败）
+            with page.expect_navigation(timeout=45000, wait_until="domcontentloaded"):
+                btn.click()
+        except Exception as nav_err:
+            last_err = f"点击登录后未发生导航: {nav_err}"
+            print(f"   ⚠ {last_err}")
+            page.wait_for_timeout(2000)
+
+        page.wait_for_timeout(1500)
+
+        if is_session_authenticated(page, base_url):
+            ru = page.locator('meta[name="ajs-remote-user"]').get_attribute("content") or ""
+            print(f"✅ 登录成功（用户: {ru or username}）")
+            return
 
-    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("✅ 登录成功")
+        last_err = err or f"仍在登录页 ({page.url[:80]})"
+        print(f"   ⚠ 登录未成功: {last_err}")
+
+        debug_path = Path.cwd() / f"confluence-login-fail-{attempt}.png"
+        try:
+            page.screenshot(path=str(debug_path), full_page=True)
+            print(f"   已保存登录失败截图: {debug_path}")
+        except Exception:
+            pass
+
+        page.context.clear_cookies()
+
+    raise RuntimeError(
+        f"Confluence 登录失败（已重试 {max_retries} 次）。请检查账号密码或 .env 中的 CONFLUENCE_* 配置。{last_err}"
+    )
 
 
 def main():
@@ -398,8 +820,9 @@ def main():
     prefix = os.environ.get("DOC_PRODUCT_PREFIX", "{{DOC_PRODUCT_PREFIX}}").strip() or "{{DOC_PRODUCT_PREFIX}}"
     if prefix.upper() in ("BREAKX", "BX") and not os.environ.get("CONFLUENCE_SPACE"):
         os.environ["CONFLUENCE_SPACE"] = "xhs"
-    version = normalize_version(sys.argv[1])
-    keywords = search_keywords(prefix, version)
+    raw_arg = sys.argv[1].strip()
+    version = normalize_version(raw_arg)
+    keywords = search_keywords(prefix, version, raw_input=raw_arg)
 
     # 输出目录默认为仓库 docs/ 下
     default_download = os.environ.get("DOC_DOWNLOAD_DIR")
@@ -427,6 +850,58 @@ def main():
 
     print(f"🖥️  浏览器: headless={headless}, slow_mo={slow_mo}ms（有头模式: CONFLUENCE_HEADED=1）")
 
+    force_playwright = env_bool("CONFLUENCE_FORCE_PLAYWRIGHT")
+    use_rest = env_bool("CONFLUENCE_USE_REST")  # 默认关闭；仅显式开启时才走 Token
+    skip_playwright = env_bool("CONFLUENCE_SKIP_PLAYWRIGHT")
+
+    playwright_ok = False
+    if not skip_playwright:
+        print("\n📄 使用 Playwright 登录并拉取 PRD（主路径）...")
+        try:
+            playwright_ok = _download_via_playwright(
+                base_url=base_url,
+                username=username,
+                password=password,
+                prefix=prefix,
+                version=version,
+                keywords=keywords,
+                docs_root=docs_root,
+                version_dir=version_dir,
+                slug=slug,
+                headless=headless,
+                slow_mo=slow_mo,
+            )
+        except Exception as e:
+            print(f"\n⚠ Playwright 拉取失败: {e}")
+
+    if playwright_ok:
+        return
+
+    if use_rest:
+        print("\n🌐 Playwright 未成功，回退 REST API（Bearer Token）...")
+        if try_rest_download(base_url, prefix, version, keywords, docs_root, version_dir, slug):
+            return
+
+    print("\n❌ PRD 拉取失败：Playwright 与 REST 均未成功。")
+    print("   排查：CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 有头模式观察登录")
+    print("   或直链：CONFLUENCE_PAGE_ID=<pageId> python3 confluence-doc.py <版本>")
+    sys.exit(1)
+
+
+def _download_via_playwright(
+    base_url: str,
+    username: str,
+    password: str,
+    prefix: str,
+    version: str,
+    keywords: list[str],
+    docs_root: Path,
+    version_dir: Path,
+    slug: str,
+    headless: bool,
+    slow_mo: int,
+) -> bool:
+    """Playwright 主路径：登录 → 搜索/直链 → 写 Markdown。"""
     with sync_playwright() as p:
         launch_opts: dict = {"headless": headless}
         if slow_mo > 0:
@@ -444,9 +919,13 @@ def main():
             ensure_logged_in(page, base_url, username, password)
             print(f"📄 当前页: {page.url[:120]}")
 
-            direct_url = env("CONFLUENCE_PAGE_URL")
+            direct_url = resolve_direct_page_url(base_url)
             target_url = direct_url if direct_url else None
-            matched_keyword = "CONFLUENCE_PAGE_URL" if direct_url else None
+            matched_keyword = (
+                "CONFLUENCE_PAGE_URL"
+                if env("CONFLUENCE_PAGE_URL")
+                else ("CONFLUENCE_PAGE_ID" if env("CONFLUENCE_PAGE_ID") else None)
+            )
 
             matched_title = ""
             if not target_url:
@@ -463,10 +942,14 @@ def main():
                     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"
+                    "   排查：1) 页面标题是否含 ADI_V2.3.4（下划线，非 ADI-V）及中文后缀"
+                )
+                print(
+                    "   2) 依次尝试 ADI_V2.3.4 / ADI-V2.3.4 / ADI_V2.3.4结算 / V2.3.4"
                 )
-                print("   3) 或设置 CONFLUENCE_PAGE_URL=<页面完整URL> 直接下载")
-                sys.exit(1)
+                print("   3) 直链：CONFLUENCE_PAGE_ID=109609740 或 CONFLUENCE_PAGE_URL=<完整URL>")
+                print("   4) ADI 页面包屑可能无 PRD 字样，脚本已按 ADI_V* 标题规则识别")
+                return False
 
             print(f"✅ 命中关键词: {matched_keyword}")
             if matched_title:
@@ -485,52 +968,31 @@ def main():
             if not content_elem.count():
                 content_elem = page.locator(".content-body")
             content_html = content_elem.inner_html() if content_elem.count() else ""
+            if len(content_html.strip()) < 20:
+                raise RuntimeError("Playwright 拉取正文为空，请检查登录态或 pageId")
+
+            token = get_api_token()
+            md_path = write_prd_markdown(
+                docs_root,
+                title,
+                matched_keyword,
+                target_url,
+                content_html,
+                prefix,
+                base_url,
+                token,
+                version_dir,
+                slug,
+                request_get=page.request.get,
+            )
 
-            img_urls = re.findall(r'<img[^>]*src="([^"]+)"', content_html)
-            for i, img_url in enumerate(img_urls):
-                original_url = img_url
-                if img_url.startswith("//"):
-                    img_url = "https:" + img_url
-                elif img_url.startswith("/"):
-                    img_url = base_url.rstrip("/") + img_url
-                elif not img_url.startswith("http"):
-                    img_url = urljoin(base_url, img_url)
-
-                if img_url.startswith("http") and not img_url.startswith("data:"):
-                    parsed = urlparse(img_url)
-                    ext = os.path.splitext(parsed.path)[1] or ".png"
-                    filename = f"image_{i + 1}{ext}"
-                    filepath = version_dir / filename
-                    try:
-                        resp = page.request.get(img_url)
-                        if resp.ok:
-                            filepath.write_bytes(resp.body())
-                            content_html = content_html.replace(f'src="{original_url}"', f'src="{slug}/{filename}"')
-                    except Exception:
-                        pass
-
-            content_md = parse_html_to_markdown(content_html)
-            md_content = f"""# {title}
-
-> 版本: {matched_keyword}
-> 来源: {target_url}
-
----
-
-{content_md}
-"""
-            md_filename = sanitize_filename(title) + ".md"
-            if not re.search(rf"{prefix}[-_]?V", md_filename, flags=re.IGNORECASE):
-                md_filename = f"{matched_keyword}-{md_filename}"
-            md_path = docs_root / md_filename
-            md_path.write_text(md_content, encoding="utf-8")
-
-            print("\n✅ 获取完成！")
+            print("\n✅ 获取完成（Playwright）！")
             print(f"📄 主文档: {md_path}")
             print(f"🖼️ 图片目录: {version_dir}")
+            return True
         except Exception as e:
-            print(f"\n❌ 获取失败: {e}")
-            raise
+            print(f"\n❌ Playwright 获取失败: {e}")
+            return False
         finally:
             if env_bool("CONFLUENCE_DEBUG_PAUSE", default=not headless):
                 try:

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

@@ -27,6 +27,16 @@ python3 confluence-doc.py <版本号>
 
 说明：脚本内置默认账号密码（`lixinxin` / `Xin@147258`），可直接执行；如需覆盖，再设置 `CONFLUENCE_USERNAME` / `CONFLUENCE_PASSWORD`。
 
+**下载策略（v1.3.4+）**：默认 **Playwright 登录 + 搜索** 拉取 PRD（主路径，不依赖会过期的 Token）。仅当 Playwright 失败且显式设置 `CONFLUENCE_USE_REST=1` 时才回退 REST API。
+
+```bash
+# 有头模式排查登录（推荐）
+CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 CONFLUENCE_DEBUG_PAUSE=1 python3 confluence-doc.py 2.3.4
+
+# 可选：Playwright 失败后回退 Token（不推荐作默认）
+CONFLUENCE_USE_REST=1 python3 confluence-doc.py 2.3.4
+```
+
 有头调试（可观察登录与搜索过程）：
 
 ```bash
@@ -48,8 +58,17 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 2. `{{PRODUCT_PREFIX}}-V<版本>`（如 ADI-V2.3.2）
 3. `{{PRODUCT_PREFIX}}_<版本>`（如 ADI_2.3.2）
 4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
+5. `ADI_V<版本>结算`（ADI 长标题页，如 V2.3.4 结算对接欢聚）
 
-每个关键词都会走全站搜索 + 顶栏搜索；在候选结果中**优先选面包屑父级含 PRD 的页面**。
+每个关键词都会走 **dosearchsite 全站搜索** + 顶栏搜索；匹配时忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+
+## 直链（跳过搜索）
+
+```bash
+CONFLUENCE_PAGE_ID=109609740 python3 confluence-doc.py 2.3.4
+# 或
+CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/..." python3 confluence-doc.py 2.3.4
+```
 
 ## 输出结构