sdd-flow-kit 1.0.16 → 1.0.22

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