sdd-flow-kit 1.3.11 → 1.3.12

package/README.md

@@ -92,6 +92,14 @@ node ./node_modules/sdd-flow-kit/dist/postinstall.js
 - Claude Code 安装（`.claude/skills`）时默认用 `claude -p` 执行修复，不限于 Cursor
 - 可用 `--agent claude-code` 或 `SDD_FLOW_KIT_ENABLE_*_AUTORUN=0` 控制
 
+**1.3.12** — Confluence 关键字搜索稳定性（dosearchsite 主路径）
+
+- `confluence-doc.py`：每个关键词优先打开 `dosearchsite.action?queryString=...` 专用搜索页（不再依赖 `#all-updates` 顶栏搜索）
+- 匹配放宽：**标题命中或 URL 路径命中** 均可得分（`score_link_match` 原已支持，增强前缀匹配与 ADI 加权）
+- `run_search_dosearch`：处理 `ERR_ABORTED`、搜索结果页导航重试；顶栏搜索降为兜底
+- 新增 `CONFLUENCE_DEBUG=1` 输出选择器解析日志
+- 更新 `01-adi-doc-skill-指引` / `doc-skill.SKILL`：关键字搜索为主，pageId 直链为可选兜底
+
 **1.3.9** — PRD 不一致自动修复循环（最多 3 次）
 
 - 新增 `prd-remediate`：`prd-diff` 失败 → 按 `09` 生成修复指引 → 调 AI 工具 `/opsx-apply` 修代码 → 再 `prd-diff`（**每项**最多 3 次）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.3.11",
+  "version": "1.3.12",
   "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,14 +12,18 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。
 
-2. 脚本会依次搜索（含用户原样输入）：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
+2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
 
-3. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+3. 匹配规则：**标题包含关键词或以关键词为前缀**，或 **URL 路径包含关键词**，任一满足即命中（Confluence 列表标题常被截断）。
 
-4. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+4. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+
+5. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
    - `source/PRD.md`
 
-## 直链兜底（已知 pageId 时推荐）
+## 直链兜底（可选，非默认）
+
+仅在关键字搜索全部失败、且已知 pageId 时使用：
 
 ADI V2.3.4 示例（`yyzcpt` 空间 pageId `109609740`）：
 
@@ -44,8 +48,8 @@ python3 confluence-doc.py 2.3.4
 
 ## 失败排查
 
-- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）
-- 页面存在但搜不到：设置 `CONFLUENCE_PAGE_ID=<pageId>` 或 `CONFLUENCE_PAGE_URL=<完整URL>` 直链下载
+- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）；可尝试输入更长关键词如 `ADI_V2.3.4结算`
+- 页面存在但搜不到：加 `CONFLUENCE_DEBUG=1` 查看选择器解析日志；或（可选）设置 `CONFLUENCE_PAGE_ID` / `CONFLUENCE_PAGE_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`

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

@@ -177,8 +177,10 @@ def href_path_matches_keyword(href: str, keyword: str) -> bool:
 
 
 def text_matches_keyword(text: str, keyword: str) -> bool:
-    """标题/链接文案匹配：忽略 -/_ 差异。"""
-    return normalize_match_token(keyword) in normalize_match_token(text)
+    """标题/链接文案匹配：忽略 -/_ 差异；支持前缀命中（如 ADI_V2.3.4结算…）。"""
+    t_norm = normalize_match_token(text or "")
+    kw_norm = normalize_match_token(keyword)
+    return kw_norm in t_norm or t_norm.startswith(kw_norm)
 
 
 def score_link_match(text: str, href: str, prefix: str, version: str, keyword: str) -> int:
@@ -212,22 +214,34 @@ def score_link_match(text: str, href: str, prefix: str, version: str, keyword: s
     space = env("CONFLUENCE_SPACE", "").lower()
     if space and f"/spaces/{space}/" in href.lower():
         score += 5
+    # ADI/产品 PRD 标题或 URL 含版本号时加权，降低误命中其他空间页面
+    if re.search(r"adi[-_]?v", text, re.IGNORECASE) or re.search(
+        r"adi[-_]?v", unquote(href), re.IGNORECASE
+    ):
+        score += 2
     return score
 
 
 def collect_search_candidates(
     page, base_url: str, prefix: str, version: str, keyword: str
 ) -> list[tuple[str, str, int]]:
-    """返回 [(url, title, score), ...]"""
+    """返回 [(url, title, score), ...]；标题命中或 URL 路径命中均可得分（>=2）。"""
     seen: set[str] = set()
     scored: list[tuple[int, str, str]] = []
+    debug = env_bool("CONFLUENCE_DEBUG")
 
     selectors = [
         ".search-result .title a",
         ".search-result-title a",
         "#search-results .gs-title a",
+        "ol.search-results-list a",
+        ".search-results a",
+        ".search-result a",
+        "#search-results a",
         ".search-results-panel a",
         "a[data-linked-resource-id]",
+        f"a[href*='{keyword}']",
+        f"a:has-text('{keyword}')",
         "a[href*='/pages/']",
         "a[href*='/display/']",
     ]
@@ -235,6 +249,8 @@ def collect_search_candidates(
     for selector in selectors:
         links = page.locator(selector)
         count = min(links.count(), 200)
+        if debug and count:
+            print(f"   [debug] selector={selector!r} count={count}")
         for i in range(count):
             href = links.nth(i).get_attribute("href") or ""
             raw_text = (links.nth(i).inner_text() or "").strip()
@@ -252,6 +268,9 @@ def collect_search_candidates(
             if s >= 2:
                 scored.append((s, full_url, text[:120]))
 
+    if debug and not scored:
+        print("   [debug] 未解析到 score>=2 的 wiki 页面链接")
+
     scored.sort(key=lambda x: x[0], reverse=True)
     return [(u, t, s) for s, u, t in scored]
 
@@ -625,19 +644,36 @@ def try_rest_download(
 
 
 def run_search_dosearch(page, base_url: str, prefix: str, version: str, keyword: str) -> list[tuple[str, str, int]]:
+    """打开 Confluence 全站专用搜索页（dosearchsite），比首页 #all-updates 顶栏搜索更稳定。"""
     url = f"{base_url.rstrip('/')}/dosearchsite.action?queryString={quote(keyword)}"
-    print(f"   → 全站搜索: {url}")
-    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 []
+    print(f"   → 专用搜索页: .../dosearchsite.action?queryString={quote(keyword)}")
+    for attempt in range(2):
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=60000)
+        except Exception as exc:
+            # 搜索页常有重定向/长连接，networkidle 易误报 ERR_ABORTED
+            if "ERR_ABORTED" not in str(exc) and "Timeout" not in str(exc):
+                raise
+            if attempt == 0:
+                print("   导航被中断，等待搜索结果页稳定...")
+            try:
+                page.goto(url, wait_until="load", timeout=60000)
+            except Exception:
+                pass
+        page.wait_for_load_state("domcontentloaded", timeout=30000)
+        page.wait_for_timeout(2500)
+        if is_login_page(page):
+            return []
+        current = page.url.lower()
+        on_search = "dosearchsite" in current or "search" in current
+        if on_search or attempt == 1:
+            break
+        print("   未停留在搜索结果页，重试一次...")
     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]]:
+    """顶栏快速搜索（dosearchsite 无结果时的兜底，非主路径）。"""
     search_selector = None
     for selector in [
         "#quick-search-query",
@@ -653,10 +689,10 @@ def run_search_quick(page, base_url: str, prefix: str, version: str, keyword: st
             break
     if not search_selector:
         return []
-    print(f"   → 顶栏搜索框: {search_selector}  关键词: {keyword}")
+    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_load_state("domcontentloaded", timeout=30000)
     page.wait_for_timeout(2500)
     return collect_search_candidates(page, base_url, prefix, version, keyword)
 

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

@@ -60,9 +60,15 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
 5. `ADI_V<版本>结算`（ADI 长标题页，如 V2.3.4 结算对接欢聚）
 
-每个关键词都会走 **dosearchsite 全站搜索** + 顶栏搜索；匹配时忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时 **标题或 URL 路径** 任一命中即可，并忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
 
-## 直链（跳过搜索）
+调试搜索解析：
+
+```bash
+CONFLUENCE_DEBUG=1 python3 confluence-doc.py ADI_V2.3.4
+```
+
+## 直链（可选，跳过搜索）
 
 ```bash
 CONFLUENCE_PAGE_ID=109609740 python3 confluence-doc.py 2.3.4
@@ -88,6 +94,6 @@ CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/..
 - 脚本：`docs/{{SKILL_DIR}}/confluence-doc.py`
 - 脚本已内置默认账号密码；如需使用其他账号可用环境变量覆盖
 - 默认 Confluence 地址为 `https://confluence.huan.tv`（可用 `CONFLUENCE_BASE_URL` 覆盖）
-- 默认搜索入口为 `https://confluence.huan.tv/#all-updates`（可用 `CONFLUENCE_SEARCH_URL` 覆盖）
+- 搜索主路径为 `dosearchsite.action?queryString=<关键词>`（全站专用搜索页）
 - 脚本会自动尝试读取仓库根目录的 `.env.pre` / `.env` / `.env.local` / `.env.development` / `.env.test`（若其中存在 `CONFLUENCE_*` 配置可直接复用）