sdd-flow-kit 1.3.6 → 1.3.12

package/dist/steps/runValidate.js

@@ -47,10 +47,16 @@ const projectRoots_1 = require("../core/projectRoots");
 const sessionState_1 = require("../core/sessionState");
 const fs_1 = require("../core/fs");
 const openspecGate_1 = require("../core/openspecGate");
+const playwrightEnsure_1 = require("../core/playwrightEnsure");
+const prdCoverage_1 = require("../core/prdCoverage");
+const runPrdReview_1 = require("./runPrdReview");
+const prdRemediate_1 = require("../core/prdRemediate");
+const runPrdDiff_1 = require("./runPrdDiff");
 /** 验收回退最大次数，超过需用户确认 */
 exports.MAX_VALIDATE_RETRIES = 3;
 /**
- * 验收命令：跑 lint+type+unit（delivery-pipeline:short）+ e2e/Playwright，写入 .validate-pass.json 或 .validate-fail.json。
+ * 验收命令：PRD 一致性复查门禁 + lint+type+unit + 强制 E2E（缺 Playwright 则自动安装）。
+ * 写入 .validate-pass.json 或 .validate-fail.json。
  * 验收不通过时回退到 apply_in_progress，超过 MAX_VALIDATE_RETRIES 次则需用户确认。
  */
 async function runValidate(options) {
@@ -72,7 +78,7 @@ async function runValidate(options) {
     }
     const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
     const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
-    const agent = options.agent || "cursor";
+    const agent = options.agent || "claude-code";
     if (options.dryRun) {
         return { ok: true, detail: `dry-run: would validate in ${pkgRoot} (installRoot=${installRoot})`, needUserConfirm: false };
     }
@@ -81,6 +87,65 @@ async function runValidate(options) {
     if (!ensured.ready) {
         return { ok: false, detail: "ensure-opsx 未就绪", needUserConfirm: false };
     }
+    // ---- 检查0: PRD 一致性复查 + 自动修复循环（最多 3 次）----
+    await (0, runPrdReview_1.runPrdReview)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        dryRun: false,
+    });
+    let needUserConfirmFromRemediate = false;
+    const remediateLoop = await (0, prdRemediate_1.runPrdRemediateLoop)({
+        projectRoot: pkgRoot,
+        outputRoot: loaded.resolved.outputRoot,
+        runId: loaded.resolved.runId,
+        change: options.change,
+        agent,
+        dryRun: false,
+        maxAttempts: prdRemediate_1.MAX_PRD_FIX_RETRIES,
+        runDiff: async () => {
+            const diff = await (0, runPrdDiff_1.runPrdDiff)({
+                projectRoot: options.projectRoot,
+                runId: loaded.resolved.runId,
+                dryRun: false,
+            });
+            return { ok: diff.ok, semantic: diff.semantic };
+        },
+    });
+    if (remediateLoop.escalated) {
+        needUserConfirmFromRemediate = true;
+    }
+    let prdCoverage = await (0, prdCoverage_1.checkPrdCoverage)(loaded.resolved.outputRoot, pkgRoot);
+    if (!prdCoverage.ok) {
+        const failed = prdCoverage.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`);
+        const payload = {
+            change: options.change,
+            verdict: "fail",
+            prdCoverageFailed: failed,
+            remediateAttempts: remediateLoop.attempts,
+            remediateEscalated: remediateLoop.escalated,
+            at: new Date().toISOString(),
+        };
+        await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(loaded.resolved.outputRoot, ".validate-fail.json"), `${JSON.stringify(payload, null, 2)}\n`);
+        if (loaded.session) {
+            await (0, sessionState_1.writeSession)(loaded.resolved.outputRoot, {
+                ...loaded.session,
+                prdFixRetryCount: remediateLoop.attempts,
+                status: remediateLoop.escalated ? "awaiting_user_confirmation" : "apply_in_progress",
+            });
+        }
+        return {
+            ok: false,
+            detail: remediateLoop.escalated
+                ? `${remediateLoop.detail}。请处理 08 待人工确认汇总后重试 validate`
+                : `prd-coverage 未通过: ${failed.slice(0, 3).join("; ")}`,
+            needUserConfirm: needUserConfirmFromRemediate || remediateLoop.needUserConfirm,
+        };
+    }
+    await (0, prdCoverage_1.writePrdCoveragePassMarker)(loaded.resolved.outputRoot, {
+        change: options.change,
+        atomCount: (_b = (_a = prdCoverage.checks.find((c) => c.name === "prd-atoms")) === null || _a === void 0 ? void 0 : _a.detail) !== null && _b !== void 0 ? _b : "",
+        at: new Date().toISOString(),
+    });
     // ---- 检查1: tasks.md 全完成 ----
     const tasks = await (0, openspecGate_1.checkTasksAllDone)(installRoot, options.change);
     // ---- 检查2: delivery-pipeline:short（lint + type check + unit test） ----
@@ -89,43 +154,13 @@ async function runValidate(options) {
         stdio: "inherit",
         shell: process.platform === "win32",
     });
-    const shortExitCode = (_a = shortRet.status) !== null && _a !== void 0 ? _a : 1;
-    // ---- 检查3: e2e / Playwright ----
-    let e2eExitCode = 0;
-    let e2eDetail = "e2e 未执行";
-    const hasPlaywrightScript = await hasScript(pkgRoot, "test:e2e");
-    if (hasPlaywrightScript) {
-        const e2eRet = (0, child_process_1.spawnSync)("pnpm", ["run", "test:e2e"], {
-            cwd: pkgRoot,
-            stdio: "inherit",
-            shell: process.platform === "win32",
-            env: { ...process.env, CI: "1" },
-        });
-        e2eExitCode = (_b = e2eRet.status) !== null && _b !== void 0 ? _b : 1;
-        e2eDetail = e2eExitCode === 0 ? "e2e/Playwright 全通过" : `e2e/Playwright 退出码 ${e2eExitCode}`;
-    }
-    else {
-        // 尝试直接用 npx playwright test
-        const hasPlaywrightCli = (0, child_process_1.spawnSync)("npx", ["playwright", "--version"], {
-            cwd: pkgRoot,
-            stdio: "ignore",
-        }).status === 0;
-        if (hasPlaywrightCli) {
-            const e2eRet = (0, child_process_1.spawnSync)("npx", ["playwright", "test"], {
-                cwd: pkgRoot,
-                stdio: "inherit",
-                shell: process.platform === "win32",
-                env: { ...process.env, CI: "1" },
-            });
-            e2eExitCode = (_c = e2eRet.status) !== null && _c !== void 0 ? _c : 1;
-            e2eDetail = e2eExitCode === 0 ? "Playwright test 全通过" : `Playwright test 退出码 ${e2eExitCode}`;
-        }
-        else {
-            e2eDetail = "未检测到 Playwright，跳过 e2e（建议配置 test:e2e 脚本）";
-        }
-    }
+    const shortExitCode = (_c = shortRet.status) !== null && _c !== void 0 ? _c : 1;
+    // ---- 检查3: 强制 E2E / Playwright（缺则自动安装） ----
+    const e2eResult = await (0, playwrightEnsure_1.runMandatoryE2e)(pkgRoot, false);
+    const e2eExitCode = e2eResult.exitCode;
+    const e2eDetail = e2eResult.detail;
     // ---- 综合判定 ----
-    const allPassed = tasks.ok && shortExitCode === 0 && e2eExitCode === 0;
+    const allPassed = tasks.ok && shortExitCode === 0 && e2eResult.ok;
     const verdict = allPassed ? "pass" : "fail";
     const payload = {
         change: options.change,
@@ -173,20 +208,11 @@ async function runValidate(options) {
             needUserConfirm,
         };
     }
-    return { ok: true, detail: "验收通过（lint+type+unit+e2e），可进入交付", needUserConfirm: false };
-}
-/** 检查 package.json 是否有指定 script */
-async function hasScript(pkgRoot, scriptName) {
-    var _a;
-    try {
-        const { readFile: readFileFs } = await Promise.resolve().then(() => __importStar(require("fs/promises")));
-        const pkgText = await readFileFs(path_1.default.join(pkgRoot, "package.json"), "utf8");
-        const pkg = JSON.parse(pkgText);
-        return Boolean((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a[scriptName]);
-    }
-    catch {
-        return false;
-    }
+    return {
+        ok: true,
+        detail: "验收通过（prd-coverage + lint+type+unit + 强制 e2e），可进入交付",
+        needUserConfirm: false,
+    };
 }
 /** 清理验收标记文件，重新实现后需要重新验收 */
 async function cleanupValidateMarkers(outputRoot) {

package/dist/steps/startFlow.js

@@ -82,6 +82,11 @@ async function startFlowScaffold(options) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-openspec-提案草稿.md"), openspecEntryTemplate);
     const opsxAutoChainTemplate = await (0, templates_1.loadTemplateText)("artifacts/07-opsx-auto-chain.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "07-opsx-自动串联指引.md"), opsxAutoChainTemplate);
+    const prdReviewReportTemplate = await (0, templates_1.loadTemplateText)("artifacts/08-PRD一致性复查报告.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "08-PRD一致性复查报告.md"), prdReviewReportTemplate
+        .replace("{{ATOM_COUNT}}", "0")
+        .replace("{{REVIEW_TABLE_ROWS}}", "| （运行 prd-review 后生成） | | | | |")
+        .replace("{{GENERATED_AT}}", new Date().toISOString()));
     const session = (0, sessionState_1.defaultSession)({
         product: options.product,
         version: options.version,

package/package.json

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

@@ -41,7 +41,7 @@ npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --ag
 3. propose 后 **必须** `gate ac-ready`（P0 映射到 spec/tasks）才能 `phase impl`。
 4. **仅当** `gate --expect impl-allowed` 通过后，才允许按 `tasks.md` 改业务代码。
 5. **Apply 前必读**：`source/PRD.md` 对应章节 + `05-验收清单.md`（tasks 是子集，不能替代 PRD）。
-6. **deliver 前必须** `gate ac-signed`（05 中 P0 已验收且已签收）。
+6. **deliver 前必须** `prd-diff` + `gate prd-coverage`（脚本 PRD 语义 diff + 08 复查）+ `gate ac-signed`。
 7. 提案/实现 **必须** 读并执行：
    - `.cursor/skills/opsx-superpowers-workflow/SKILL.md`
    - `openspec-propose` → `openspec-apply-change` → `pnpm run opsx:delivery-pipeline -- <change>`
@@ -77,7 +77,7 @@ npx sdd-flow-kit run --product {{DEFAULT_PRODUCT}} --version <版本号> -y --ag
 | B | 用户确认后 **05→04→01/02** → `gate docs-closed` → `phase docs-done` |
 | C | `propose` + artifacts → `gate propose-ready` + **`gate ac-ready`** → `phase propose-done` |
 | D | `phase impl` → `gate impl-allowed` → `/opsx-apply`（读 PRD+05） |
-| E | `validate` → **05 签收** → `gate ac-signed` → `deliver` → `phase shipped` |
+| E | `prd-review` → AI 填 08 → `prd-diff` → `gate prd-coverage` → `validate`（强制 E2E）→ **05 签收** → `deliver` |
 
 ## 环境
 

package/src/templates/artifacts/07-opsx-auto-chain.template.md

@@ -45,12 +45,22 @@
 4. 读并执行：`openspec-apply-change` → `tdd-script`（分层测试策略）→ `openspec-superpowers-pipeline` → `opsx-dev-delivery-pipeline`
 5. Red 断言须写死 PRD/05 原文（toast、tooltip、列序等）
 6. `pnpm run opsx:delivery-pipeline -- <change-name>` 直至 **exit 0**
-7. deliver 前执行 `gate ac-signed`，再 `deliver`
+
+## 阶段 E — PRD 一致性复查 + 脚本语义 diff + 强制验收（交付前）
+
+1. `npx sdd-flow-kit prd-review --project-root <repo> --run-id <runId>`
+2. AI 执行 `08-PRD一致性复查提示词.md`：**最细粒度**逐条对比 PRD 原子 × 代码，禁止揣摩/兜底
+3. `npx sdd-flow-kit prd-diff --project-root <repo> --run-id <runId>`（脚本 PRD×代码字面量 diff → `09-PRD语义diff报告.md`）
+4. 若 diff 失败：`prd-remediate --change <name>` 或 `validate` 内置循环（按 09 调 `/opsx-apply` 修，**每项最多 3 次**、每轮只修剩余失败项，重试附带上次错误代码摘要；仍失败 → 08 待人工确认）
+5. `npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect prd-coverage`
 
 ## 完成判定
 
 - [ ] `gate ac-ready` 通过（P0 已映射）
 - [ ] `openspec/changes/<name>/` 下 applyRequires 全部 done
 - [ ] `tasks.md` 全部 `- [x]` 且含 `[AC-XX]`
+- [ ] `prd-diff` 通过（09 报告无 missing/partial/report_mismatch）
+- [ ] `gate prd-coverage` 通过（08 报告 + 语义 diff + 全量 E2E 测试覆盖）
+- [ ] `validate` 通过（含强制 e2e）
 - [ ] `gate ac-signed` 通过
 - [ ] delivery-pipeline exit 0

package/src/templates/artifacts/08-PRD/344/270/200/350/207/264/346/200/247/345/244/215/346/237/245/346/212/245/345/221/212.template.md

@@ -0,0 +1,93 @@
+# 08-PRD一致性复查报告
+
+> **交付前强制门禁**。按 `source/PRD.md` **最细粒度**逐条对比已实现代码。  
+> **禁止**揣摩、禁止兜底方案；无法确认则标 `待人工确认`，不得自行假设。
+
+## 复查状态
+
+- **复查状态**：未复查（完成后改为 `复查完成`）
+- **PRD 原子条目数**：{{ATOM_COUNT}}
+- **生成时间**：{{GENERATED_AT}}
+
+## 填写规则（强制）
+
+1. **粒度**：本表每一行对应 `.prd-review-atoms.json` 中的一条 PRD 原子（标题 / 列表项 / 表格行 / 实质段落），不得合并或省略。
+2. **代码证据**：必须写可核对位置，例如 `src/pages/foo/index.tsx:42`、E2E `e2e/foo.spec.ts` 中断言原文、DOM 选择器 + 期望文案。
+3. **结论**（仅允许三选一）：
+   - `一致` — 代码与 PRD 该条完全一致
+   - `不一致-按PRD修复` — 代码与 PRD 冲突，须按 PRD 改代码（不得改 PRD 迁就实现）
+   - `待人工确认` — 无法从 PRD 或代码得出确定结论，须人工裁定
+4. **禁止措辞**（出现在证据/备注中将导致 gate 失败）：推测、兜底、暂定、可能、大概、应该可以、或沿用、默认处理、先这样、暂时、估计、猜测、或许。
+5. **不一致处理**：标 `不一致-按PRD修复` 的项必须在修复代码后改为 `一致`，方可 deliver。
+6. **待人工确认**：不得自行「合理推断」；须在下方汇总表列出，交付前必须清零或用户明确签收。
+
+## 填写示例（参考格式；示例在代码块内，不会被 gate 解析，填表时勿照抄 ID）
+
+以下演示**合格写法**。填「逐条对比」表时：按 `.prd-review-atoms.json` 的真实 `PRD-001…` 逐条填写，证据粒度须达到示例水平。
+
+### 示例 A — `一致`
+
+```
+| PRD-ID | PRD 原文（摘要） | 代码证据 | 结论 | 备注 |
+| PRD-0xx | 列表页「导出」后 toast 为「导出成功，请稍后查看下载中心」 | src/views/order/List.vue:88 message.success('导出成功，请稍后查看下载中心'); E2E e2e/order-export.spec.ts:34 getByText('导出成功，请稍后查看下载中心') | 一致 | §3.2 列表操作 > 导出 L156 |
+```
+
+### 示例 B — `不一致-按PRD修复`
+
+```
+| PRD-ID | PRD 原文（摘要） | 代码证据 | 结论 | 备注 |
+| PRD-0xx | 筛选「状态」默认选中「全部」 | List.vue:41 statusDefault:'pending'（PRD 要求「全部」） | 不一致-按PRD修复 | §3.1 筛选 > 状态 L142 |
+```
+
+修复追踪写法：
+
+```
+| PRD-ID | 修复说明 | 修复后证据 | 状态 |
+| PRD-0xx | statusDefault 改为 'all' | List.vue:41 + e2e/order-filter.spec.ts:12 断言默认「全部」 | 已关闭 |
+```
+
+### 示例 C — `待人工确认`
+
+```
+| PRD-ID | PRD 原文（摘要） | 代码证据 | 结论 | 备注 |
+| PRD-0xx | 批量审核在选中 0 条时的交互 | BatchAudit.vue:67 仅 selected.length>0 时渲染按钮；PRD 未定义 0 条时行为 | 待人工确认 | §4.5 批量操作 L203 |
+```
+
+待人工确认汇总：
+
+```
+| PRD-ID | PRD 原文 | 不确定原因 | 需确认人 |
+| PRD-0xx | 批量审核 0 条交互 | PRD 未写隐藏/disabled/toast，代码为隐藏 | 产品负责人 |
+```
+
+### 不合格写法（gate 会失败）
+
+- 「推测 PRD 意思是…」— 含禁止词
+- 「先沿用旧版，后续再改」— 兜底措辞
+- 「组件里应该有处理」— 无路径/行号/断言
+- 「基本满足」— 结论不在三选一内
+
+## 逐条对比（PRD 原子 × 代码）
+
+| PRD-ID | PRD 原文（摘要） | 代码证据（路径+行号/选择器/断言） | 结论 | 备注（章节路径） |
+|--------|-----------------|----------------------------------|------|-----------------|
+{{REVIEW_TABLE_ROWS}}
+
+## 待人工确认汇总
+
+| PRD-ID | PRD 原文 | 不确定原因 | 需确认人 |
+|--------|---------|-----------|---------|
+| （无则写「无」） | | | |
+
+## 不一致项修复追踪（须全部关闭）
+
+| PRD-ID | 修复说明（按 PRD 改了什么） | 修复后证据 | 状态 |
+|--------|---------------------------|-----------|------|
+| （无则写「无」） | | | 已关闭 |
+
+## 复查完成签收
+
+- [ ] 全部 PRD 原子条目已逐条填写
+- [ ] 无 `不一致-按PRD修复` 未关闭项
+- [ ] 无未解决的 `待人工确认` 项
+- [ ] 已将「复查状态」改为 `复查完成`

package/src/templates/prompts/08-prd-consistency-review-prompt.md

@@ -0,0 +1,49 @@
+# PRD 一致性复查提示词（最细粒度，禁止揣摩）
+
+你正在执行 **PRD × 已实现代码** 的一致性复查。输入：
+
+- `source/PRD.md`（唯一需求来源）
+- `.prd-review-atoms.json`（已拆好的最细粒度 PRD 原子，**不得删行**）
+- `08-PRD一致性复查报告.md`（待填写）
+- `05-验收清单.md`（AC 映射参考，**不能替代** PRD 全文）
+- 业务代码 `src/`、`frontend/src/`、相关 `e2e/` 测试
+
+## 强制原则
+
+1. **拆分粒度**：以 `.prd-review-atoms.json` 为准，**一条 PRD 原子 = 报告表格一行**，不得合并、不得跳过。
+2. **只陈述可核对事实**：代码证据必须可定位（文件路径 + 行号，或 E2E 测试名 + 断言字符串）。
+3. **禁止揣摩**：不得写「可能」「大概」「推测」「兜底」「暂定」「或沿用」「默认」等措辞。
+4. **禁止兜底方案**：不得建议「先这样」「暂时接受」「后续再改」来绕过 PRD。
+5. **不一致时**：结论标 `不一致-按PRD修复`，并在「不一致项修复追踪」登记；**以 PRD 为准改代码**，不得改 PRD 迁就实现。
+6. **无法确认时**：结论标 `待人工确认`，写入「待人工确认汇总」，写清**缺什么信息**才能判断；**不得自行假设**。
+
+## 填写格式
+
+填表前阅读 `08-PRD一致性复查报告.md` 中的 **「填写示例」** 一节（含 `一致` / `不一致-按PRD修复` / `待人工确认` 三种合格写法，以及不合格反例）。  
+你的每一行须达到示例中的证据粒度（路径+行号 或 E2E 断言原文），不得照抄示例中的 PRD-ID 与业务内容。
+
+## 执行步骤
+
+1. 读取 `.prd-review-atoms.json`，确认共 {{ATOM_COUNT}} 条（与报告行数一致）。
+2. 对每条 PRD 原子：
+   - 在 PRD 中定位原文（章节路径 + 行号）
+   - 在代码/测试中查找**直接实现**该条的证据
+   - 填写 `08-PRD一致性复查报告.md` 对应行
+3. 若实现与 PRD 冲突 → `不一致-按PRD修复`
+4. 若 PRD 要求明确但代码找不到对应实现 → `不一致-按PRD修复`
+5. 若 PRD 表述模糊且代码有多种解读 → `待人工确认`（说明歧义点，不要猜）
+6. 全部填完后：
+   - 更新「待人工确认汇总」「不一致项修复追踪」
+   - 将「复查状态」改为 `复查完成`（仅当无未关闭不一致、无待人工确认时）
+
+## 完成后执行门禁
+
+```bash
+npx sdd-flow-kit prd-diff --project-root <repo> --run-id <runId>
+npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect prd-coverage
+```
+
+`prd-diff` 会机械扫描 PRD 字面量是否在代码/测试中出现，并生成 `09-PRD语义diff报告.md`。  
+若 08 报告标「一致」但脚本 diff 为 `missing_in_code` / `report_mismatch`，gate 将失败。
+
+gate 失败则根据 `09-PRD语义diff报告.md` 修正报告或代码，**不得**跳过 gate。

package/src/templates/rules/sdd-no-implement-until-apply.mdc.template

@@ -1,5 +1,5 @@
 ---
-description: SDD 脚本门禁：必须执行 sdd-flow-kit gate/phase；docModeOnly 时禁止改 src；交付前必须 ac-signed + deliver 成功
+description: SDD 脚本门禁：必须执行 sdd-flow-kit gate/phase；docModeOnly 时禁止改 src；交付前必须 prd-coverage + ac-signed + deliver 成功
 alwaysApply: true
 ---
 
@@ -22,7 +22,7 @@ alwaysApply: true
    - `npx sdd-flow-kit gate --expect docs-closed`（含 `05-验收清单.md` 已定义）
    - `npx sdd-flow-kit gate --expect ac-ready --change <name>`（P0 已映射到 spec/tasks）
    - `npx sdd-flow-kit phase advance --to impl` + `gate --expect impl-allowed`（阶段 D 前）
-4. **禁止**在未执行 `gate ac-signed` 与 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
+4. **禁止**在未执行 `gate prd-coverage`、`gate ac-signed` 与 `npx sdd-flow-kit deliver` 成功前宣称需求开发完成。
 
 ## docModeOnly
 
@@ -59,6 +59,10 @@ npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-ready -
 npx sdd-flow-kit phase advance --project-root <repo> --run-id <runId> --to impl --change <name>
 # Apply 前必读 source/PRD.md + 05-验收清单.md
 # … 实现 …
+npx sdd-flow-kit prd-review --project-root <repo> --run-id <runId>
+# AI 执行 08-PRD一致性复查提示词.md（最细粒度，禁止揣摩）
+npx sdd-flow-kit prd-diff --project-root <repo> --run-id <runId>
+npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect prd-coverage
 npx sdd-flow-kit validate --project-root <repo> --run-id <runId> --change <name>
 # 05 签收：P0 已验收 + 签收状态已签收
 npx sdd-flow-kit gate --project-root <repo> --run-id <runId> --expect ac-signed

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_*` 配置可直接复用）