sdd-flow-kit 1.3.13 → 1.3.14

package/dist/core/prdArtifacts.js

@@ -16,6 +16,31 @@ const PRD_PLACEHOLDER_MARKERS = [
     "占位",
     "placeholder",
 ];
+const PRD_TECHNICAL_TITLE_MARKERS = [
+    "技术文档",
+    "技术方案",
+    "详细设计",
+    "接口文档",
+    "后端",
+    "数据库",
+    "实现文档",
+    "设计文档",
+    "开发文档",
+];
+/**
+ * 判断 PRD 标题是否属于技术/后端/设计类文档，避免错误进入需求分析链路。
+ */
+function hasForbiddenPrdTitle(title) {
+    const upper = (title || "").toUpperCase();
+    return PRD_TECHNICAL_TITLE_MARKERS.some((marker) => upper.includes(marker.toUpperCase()));
+}
+/**
+ * 从 Markdown 主标题读取 Confluence 页面标题，作为 prd-fetched 的类型校验入口。
+ */
+function extractPrdTitle(content) {
+    var _a, _b;
+    return (_b = (_a = content.split("\n").find((line) => line.trim().startsWith("# "))) === null || _a === void 0 ? void 0 : _a.replace(/^#\s*/, "").trim()) !== null && _b !== void 0 ? _b : "";
+}
 async function isPrdFetched(outputRoot) {
     const prdPath = path_1.default.join(outputRoot, "source", "PRD.md");
     const content = await (0, fs_1.readFileIfExists)(prdPath);
@@ -25,6 +50,10 @@ async function isPrdFetched(outputRoot) {
     if (PRD_PLACEHOLDER_MARKERS.some((m) => content.includes(m))) {
         return { ok: false, detail: "source/PRD.md 仍为占位内容，请先执行 Step1 拉取 PRD" };
     }
+    const title = extractPrdTitle(content);
+    if (title && hasForbiddenPrdTitle(title)) {
+        return { ok: false, detail: `source/PRD.md 命中技术文档标题: ${title}` };
+    }
     return { ok: true, detail: "PRD 已回填" };
 }
 async function isQuestionsClosed(outputRoot) {

package/dist/core/writeNext.js

@@ -35,7 +35,7 @@ async function writeInitialNext(outputRoot, projectRoot, runId) {
         "| `tasks.md` | AC 的可执行映射（`[AC-XX]`） |",
         "",
         "## 1. Step1 — 拉取 PRD",
-        "按 `01-获取需求文档指引.md` 执行 confluence 脚本，然后：",
+        "按 `01-获取需求文档指引.md` 执行 confluence 脚本；脚本和 gate 会拒绝 `技术文档`/`后端`/`详细设计` 等非 PRD 页面，然后：",
         "```bash",
         `npx sdd-flow-kit gate --project-root "${pr}" --run-id ${runId} --expect prd-fetched`,
         `npx sdd-flow-kit phase advance --project-root "${pr}" --run-id ${runId} --to after-prd`,

package/package.json

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

@@ -14,11 +14,17 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
 
-3. 匹配规则：**标题包含关键词或以关键词为前缀**，或 **URL 路径包含关键词**，任一满足即命中（Confluence 列表标题常被截断）。
+3. 匹配规则：先收集 **标题包含关键词或以关键词为前缀**、或 **URL 路径包含关键词** 的候选页，再执行 PRD 类型校验。
 
-4. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+4. PRD 类型校验（强制黑名单）：候选页必须通过脚本内 `is_prd_page()` 与 `has_forbidden_prd_title()` 双重校验。以下标题特征会被直接拒绝：
+   - `技术文档`、`技术方案`、`后端`、`详细设计`、`数据库`、`接口文档`
+   - `实现文档`、`设计文档`、`开发文档`
+   
+   若所有候选均未通过校验，脚本必须失败退出（exit code 1），**禁止回退使用第一个非 PRD 候选**。AI 不得手动复制技术文档到 `source/PRD.md`。
 
-5. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
+5. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
+
+6. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
    - `source/PRD.md`
 
 ## 直链兜底（可选，非默认）
@@ -49,6 +55,10 @@ python3 confluence-doc.py 2.3.4
 ## 失败排查
 
 - 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）；可尝试输入更长关键词如 `ADI_V2.3.4结算`
+- 输出 `✗ 命中技术文档标题，拒绝作为 PRD` 或 `跳过技术文档候选` 或 `⚠ 搜索结果均未通过 PRD 校验` 时：
+  - **禁止**手动复制技术/后端/设计页到 `source/PRD.md`
+  - 应在 Confluence 中找到真正的业务 PRD 页面（通常标题含「结算」「开票」「回款」「数据对接」等业务词汇）
+  - 使用该页面的 pageId 或 URL 直链重跑：`CONFLUENCE_PAGE_ID=<正确pageId> python3 confluence-doc.py 2.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`

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

@@ -292,10 +292,36 @@ def read_breadcrumb_text(page) -> str:
     return " > ".join(parts)
 
 
+PRD_TECHNICAL_TITLE_MARKERS = (
+    "技术文档",
+    "技术方案",
+    "详细设计",
+    "接口文档",
+    "后端",
+    "数据库",
+    "实现文档",
+    "设计文档",
+    "开发文档",
+    "API文档",
+    "数据结构",
+    "表设计",
+)
+
+
+def has_forbidden_prd_title(title: str) -> bool:
+    """技术文档/后端设计页必须在 PRD 拉取阶段直接拦截。"""
+    title_upper = (title or "").upper()
+    return any(marker.upper() in title_upper for marker in PRD_TECHNICAL_TITLE_MARKERS)
+
+
 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 has_forbidden_prd_title(title):
+        print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+        return False
     if re.search(r"ADI[_-]?V\d+\.\d+\.\d+", title_upper):
         print(f"      ✓ ADI 版本标题命中: {title[:80]}")
         return True
@@ -326,6 +352,10 @@ def is_prd_page(page, page_url: str) -> bool:
     except Exception:
         title = ""
 
+    if has_forbidden_prd_title(title):
+        print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+        return False
+
     # ADI：标题常无「PRD/需求」字样，单独识别
     if prefix == "ADI" and is_adi_requirement_page(title, crumbs, page_url):
         return True
@@ -445,7 +475,9 @@ def rest_search_candidates(
     for item in data.get("results", []):
         title = (item.get("title") or "").strip()
         page_id = str(item.get("id", ""))
-        if not page_id:
+        if not page_id or has_forbidden_prd_title(title):
+            if title and has_forbidden_prd_title(title):
+                print(f"   跳过技术文档候选: {title[:80]}")
             continue
         href = f"/spaces/{(item.get('space') or {}).get('key', '')}/pages/{page_id}/"
         score = score_link_match(title, href, prefix, version, keyword)
@@ -462,10 +494,13 @@ def rest_resolve_target(
     direct_id = resolve_direct_page_id()
     if direct_id:
         page = rest_fetch_page(base_url, token, direct_id)
+        if has_forbidden_prd_title(page["title"]):
+            print(f"❌ 直链页面不是业务 PRD，命中技术文档黑名单: {page['title']}")
+            print("   请确认提供的 pageId 是业务需求文档，而非技术文档/后端设计文档")
+            raise RuntimeError(f"直链页面不是 PRD，命中技术文档标题: {page['title']}")
         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)
@@ -475,17 +510,25 @@ def rest_resolve_target(
         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):
+            # 双重校验：标题黑名单 + ADI 特殊规则
+            if has_forbidden_prd_title(page["title"]):
+                print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {page['title'][:80]}")
+                continue
+            if prefix.upper() == "ADI" and is_adi_title_match(page["title"], version):
+                print(f"      ✓ ADI 业务 PRD 命中")
                 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
+    print("   ⚠ REST 搜索结果均未通过 PRD 校验")
+    print("      → 所有候选页面要么是技术/后端/设计文档，要么评分不足")
+    print("      → 不回退到非 PRD 候选；请确认业务需求文档的 pageId")
+    return None
 
 
 def is_adi_title_match(title: str, version: str) -> bool:
     """ADI 长标题页识别（面包屑可无 PRD 字样）。"""
+    if has_forbidden_prd_title(title):
+        return False
     title_upper = (title or "").upper()
     v_compact = version.replace(".", "")
     if re.search(rf"ADI[_-]?V{re.escape(version)}", title_upper):
@@ -702,7 +745,6 @@ def resolve_prd_target(
 ) -> 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}")
@@ -720,15 +762,16 @@ def resolve_prd_target(
                     continue
                 seen_urls.add(url)
                 print(f"    · 候选: {title[:70]}")
+                # 先执行标题级黑名单快速拒绝
+                if has_forbidden_prd_title(title):
+                    print(f"      ✗ 命中技术文档标题，拒绝作为 PRD: {title[:80]}")
+                    continue
                 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
+    print("   ⚠ 搜索结果均未通过 PRD 校验")
+    print("      → 所有候选页面要么是技术/后端/设计文档，要么面包屑不含 PRD 父级")
+    print("      → 不回退到非 PRD 候选；请确认业务需求文档的 Confluence 标题与 pageId")
     return None, None, ""
 
 
@@ -919,8 +962,12 @@ def main():
             return
 
     print("\n❌ PRD 拉取失败：Playwright 与 REST 均未成功。")
-    print("   排查：CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 有头模式观察登录")
-    print("   或直链：CONFLUENCE_PAGE_ID=<pageId> python3 confluence-doc.py <版本>")
+    print("   排查：")
+    print("     1. CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500 有头模式观察登录与搜索结果")
+    print("     2. 到 Confluence 确认业务 PRD 页面的准确标题与 pageId")
+    print("     3. 若搜索命中了技术/后端/设计文档，这些已被黑名单拒绝")
+    print("     4. 使用业务 PRD 的直链重跑：CONFLUENCE_PAGE_ID=<pageId> python3 confluence-doc.py <版本>")
+    print("     5. 禁止手动复制非 PRD 页面到 source/PRD.md")
     sys.exit(1)
 
 
@@ -976,23 +1023,42 @@ def _download_via_playwright(
                     print(f"   已保存调试截图: {debug_path}")
                 except Exception:
                     pass
-                print(f"❌ 未找到 {prefix} {version} 的需求文档。")
+                print(f"❌ 未找到 {prefix} {version} 的业务需求文档（PRD）。")
                 print(
                     "   排查：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_ID=109609740 或 CONFLUENCE_PAGE_URL=<完整URL>")
-                print("   4) ADI 页面包屑可能无 PRD 字样，脚本已按 ADI_V* 标题规则识别")
+                print("   3) 若搜索命中了「技术文档」「后端」「详细设计」等页面，这些已被黑名单自动拒绝")
+                print("   4) 直链解决：CONFLUENCE_PAGE_ID=<正确pageId> 或 CONFLUENCE_PAGE_URL=<完整URL>")
+                print("   5) ADI 页面包屑可能无 PRD 字样，脚本已按 ADI_V* 标题规则识别")
+                print("   6) 禁止手动复制技术文档到 source/PRD.md，必须找到真正的业务 PRD")
                 return False
 
             print(f"✅ 命中关键词: {matched_keyword}")
             if matched_title:
                 print(f"   页面: {matched_title[:100]}")
             print(f"   URL: {target_url[:120]}...")
+            
+            # 直链模式下也需检查标题黑名单
+            if direct_url:
+                page.goto(target_url, wait_until="domcontentloaded", timeout=60000)
+                try:
+                    direct_title = page.locator("#title-text").text_content().strip()
+                    if has_forbidden_prd_title(direct_title):
+                        print(f"❌ 直链页面不是业务 PRD，命中技术文档黑名单: {direct_title}")
+                        print("   请确认提供的 pageId/URL 是业务需求文档，而非技术文档/后端设计文档")
+                        raise RuntimeError("直链页面命中技术文档标题，拒绝作为 PRD")
+                except Exception as e:
+                    if "技术文档" in str(e) or "黑名单" in str(e):
+                        raise
+            
             page.goto(target_url, wait_until="networkidle", timeout=60000)
 
+            if not is_prd_page(page, target_url):
+                raise RuntimeError("命中的页面未通过 PRD 校验，疑似技术文档或设计文档")
+
             try:
                 title = page.locator("#title-text").text_content().strip()
             except Exception:

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

@@ -2,7 +2,7 @@
 name: {{SKILL_NAME}}
 description: |
   当用户说「获取 {{PRODUCT}} Vx.y.z 需求文档」「下载 {{PRODUCT}}-Vx.y.z PRD」「查询 {{PRODUCT}} x.y.z 版本需求」时触发。
-  自动从 Confluence 搜索对应版本 PRD 页面，下载图片并生成 Markdown 到本仓库 `docs/`。
+  自动从 Confluence 搜索对应版本 PRD 页面；`技术文档`、`后端`、`详细设计` 类页面会被拒绝，避免误下载为 PRD；下载图片并生成 Markdown 到本仓库 `docs/`。
 ---
 
 # {{PRODUCT}} 需求文档获取（docs/{{SKILL_DIR}}）
@@ -60,7 +60,9 @@ python3 confluence-doc.py {{PRODUCT_PREFIX}}_V1.2.3
 4. `{{PRODUCT_PREFIX}}-<版本>`（如 ADI-2.3.2）
 5. `ADI_V<版本>结算`（ADI 长标题页，如 V2.3.4 结算对接欢聚）
 
-每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时 **标题或 URL 路径** 任一命中即可，并忽略 `-`/`_` 差异；ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+每个关键词优先走 **`dosearchsite.action?queryString=...` 专用搜索页**（比首页 `#all-updates` 顶栏搜索稳定）；无结果时再兜底顶栏搜索。匹配时先收集 **标题或 URL 路径** 命中的候选，再执行 PRD 类型校验；`技术文档`、`技术方案`、`后端`、`详细设计`、`数据库`、`接口文档` 等页面会被直接拒绝。ADI 页按 `ADI_V*` 标题规则识别（面包屑可无 PRD 字样）。
+
+若所有候选均未通过 PRD 校验，脚本必须失败退出，**禁止回退使用第一个非 PRD 候选**；此时应改用正确 PRD 的 `CONFLUENCE_PAGE_ID` / `CONFLUENCE_PAGE_URL` 直链。
 
 调试搜索解析：