sdd-flow-kit 1.3.15 → 1.3.21

package/dist/core/e2eDemoSignalClicks.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.e2eExercisesSignal = e2eExercisesSignal;
+exports.checkE2eDemoSignalClicks = checkE2eDemoSignalClicks;
+/**
+ * E2E 演示信号点击门禁：design 映射表中的可点击交互信号须在 change 级 e2e 中有 click/getByRole。
+ */
+const path_1 = __importDefault(require("path"));
+const demoImplementationCoverage_1 = require("./demoImplementationCoverage");
+const fs_1 = require("./fs");
+/** 须在 E2E 中验证点击的信号特征 */
+const CLICKABLE_SIGNAL_RE = /编辑|保存|删除|新增|导入|拉取|提交|确认|取消|打开|修改|添加/i;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * 判断 E2E 源码是否对某交互信号做了点击类操作。
+ */
+function e2eExercisesSignal(e2eContent, signal) {
+    if (!signal || signal.length < 2)
+        return true;
+    const stripped = e2eContent.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    if (!stripped.includes(signal))
+        return false;
+    const esc = escapeRegExp(signal);
+    const clickPatterns = [
+        new RegExp(`\\.click\\s*\\([^)]*${esc}`),
+        new RegExp(`getByRole\\s*\\(\\s*['"]button['"][^)]*${esc}`),
+        new RegExp(`getByRole\\s*\\(\\s*['"][^'"]+['"][^)]*name:\\s*[^)]*${esc}`),
+        new RegExp(`getByText\\s*\\(\\s*['"\`]${esc}`),
+        new RegExp(`getByText\\s*\\(\\s*[^)]*${esc}`),
+        new RegExp(`locator\\s*\\([^)]*${esc}[^)]*\\)\\.click`),
+    ];
+    return clickPatterns.some((re) => re.test(stripped));
+}
+/**
+ * UI 类 change：映射表中可点击信号须在绑定的 e2e spec 中出现 click/getByRole。
+ */
+async function checkE2eDemoSignalClicks(pkgRoot, designContent, specPaths) {
+    var _a;
+    const skip = process.env.POQUAN_SKIP_E2E_DEMO_CLICKS === "1" ||
+        process.env.OPSX_SKIP_E2E_DEMO_CLICKS === "1";
+    if (skip) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_E2E_DEMO_CLICKS=1",
+        };
+    }
+    const parsed = (0, demoImplementationCoverage_1.parseDemoReferenceSection)(designContent !== null && designContent !== void 0 ? designContent : "");
+    if (parsed.exempt || parsed.mappings.length === 0) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: true,
+            detail: "无演示映射或已豁免，跳过 E2E 点击检查",
+        };
+    }
+    if (specPaths.length === 0) {
+        return {
+            name: "e2e-demo-signal-clicks",
+            ok: false,
+            detail: "有演示映射但未绑定 e2e spec，无法校验交互点击",
+        };
+    }
+    let e2eBlob = "";
+    for (const rel of specPaths) {
+        const content = (_a = (await (0, fs_1.readFileIfExists)(path_1.default.join(pkgRoot, rel)))) !== null && _a !== void 0 ? _a : "";
+        e2eBlob += `\n// ${rel}\n${content}`;
+    }
+    const failures = [];
+    for (const m of parsed.mappings) {
+        const clickable = m.interactionSignals.filter((s) => CLICKABLE_SIGNAL_RE.test(s));
+        if (clickable.length === 0)
+            continue;
+        const uncovered = clickable.filter((s) => !e2eExercisesSignal(e2eBlob, s));
+        if (uncovered.length === clickable.length) {
+            failures.push(`${m.moduleName}: E2E 须 click/getByRole/getByText 覆盖信号「${clickable.join("、")}」`);
+        }
+    }
+    return {
+        name: "e2e-demo-signal-clicks",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `E2E 已覆盖演示映射中的可点击信号（${specPaths.join(", ")}）`
+            : failures.join(" | "),
+    };
+}

package/dist/core/prdArtifacts.js

@@ -11,6 +11,7 @@ exports.isAcceptanceChecklistSigned = isAcceptanceChecklistSigned;
 const path_1 = __importDefault(require("path"));
 const acMatrix_1 = require("./acMatrix");
 const fs_1 = require("./fs");
+const techDocQuality_1 = require("./techDocQuality");
 const PRD_PLACEHOLDER_MARKERS = [
     "请把《PRD》",
     "占位",
@@ -81,7 +82,17 @@ async function areAnalysisDocsReady(outputRoot) {
             return { ok: false, detail: `${name} 仍为模板占位` };
         }
     }
-    return { ok: true, detail: "01/02/04 文档齐全" };
+    const techDoc = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "04-技术文档草稿.md"));
+    if (process.env.OPSX_SKIP_TECH_DOC_QUALITY !== "1") {
+        const techQuality = (0, techDocQuality_1.checkTechDocStructure)(techDoc !== null && techDoc !== void 0 ? techDoc : "");
+        if (!techQuality.ok) {
+            return {
+                ok: false,
+                detail: `tech-doc-structure: ${techQuality.detail}。请读 04-技术文档生成指引.md，在模板原文件上逐节填写`,
+            };
+        }
+    }
+    return { ok: true, detail: "01/02/04 文档齐全且 04 符合模板结构" };
 }
 /** 05-验收清单是否已从 PRD 定义完成（含至少一条 P0）。 */
 async function isAcceptanceChecklistDefined(outputRoot) {

package/dist/core/prdCoverage.js

@@ -15,6 +15,12 @@ const acMatrix_1 = require("./acMatrix");
 const fs_1 = require("./fs");
 const prdParse_1 = require("./prdParse");
 const prdSemanticDiff_1 = require("./prdSemanticDiff");
+const e2eAssertionDepth_1 = require("./e2eAssertionDepth");
+const apiFieldContract_1 = require("./apiFieldContract");
+const apiFieldCoverage_1 = require("./apiFieldCoverage");
+const visualRegression_1 = require("./visualRegression");
+const demoImplementationCoverage_1 = require("./demoImplementationCoverage");
+const acAssertionBinding_1 = require("./acAssertionBinding");
 const VALID_VERDICTS = ["一致", "不一致-按PRD修复", "待人工确认"];
 /** 禁止在证据/结论中出现的揣摩或兜底措辞 */
 const FORBIDDEN_SPECULATION = [
@@ -33,7 +39,6 @@ const FORBIDDEN_SPECULATION = [
     "或许",
 ];
 const TEST_FILE_RE = /\.(spec|test)\.(t|j)sx?$/i;
-const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
 async function walkFiles(dir, out) {
     let entries;
     try {
@@ -99,6 +104,22 @@ function hasForbiddenSpeculation(text) {
     }
     return null;
 }
+/** 08 报告中的无效/敷衍证据（如 index.vue:1、prd-atoms 注释覆盖） */
+function isWeakCodeEvidence(evidence) {
+    const e = evidence.trim();
+    if (!e)
+        return "空证据";
+    if (/:(1|2)\s*(\||$)/.test(e) && !/expect\(|getByText|getByRole|message\.|toast/.test(e)) {
+        return "证据仅指向文件首行，无具体交互/断言";
+    }
+    if (/prd-atoms-coverage|semantic-registry/i.test(e)) {
+        return "伪覆盖登记文件不能作为实现证据";
+    }
+    if (/index\.vue:1|index\.tsx:1/i.test(e) && e.split(/[;；]/).length < 2) {
+        return "禁止用列表页首行代替详情子模块证据";
+    }
+    return null;
+}
 async function writePrdAtomsManifest(outputRoot, atoms) {
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, ".prd-review-atoms.json"), `${JSON.stringify({ count: atoms.length, atoms }, null, 2)}\n`);
 }
@@ -116,40 +137,12 @@ async function loadPrdAtomsFromManifest(outputRoot) {
     }
 }
 function checkAcTestMapping(items, testContents) {
-    var _a;
-    const checks = [];
-    // P0 全量 + 所有声明 e2e 的 AC（含 P1/P2 边缘场景）
-    const mustCover = items.filter((i) => { var _a; return /^P0$/i.test(i.priority.trim()) || /e2e/i.test((_a = i.testType) !== null && _a !== void 0 ? _a : ""); });
-    for (const ac of mustCover) {
-        const bracket = `[${ac.id}]`;
-        const hits = testContents.filter((t) => t.content.includes(bracket) || t.content.includes(ac.id));
-        const e2eRequired = /e2e/i.test((_a = ac.testType) !== null && _a !== void 0 ? _a : "");
-        const e2eHits = hits.filter((h) => E2E_DIR_RE.test(h.file.replace(/\\/g, "/")));
-        if (hits.length === 0) {
-            checks.push({
-                name: `ac-test-${ac.id}`,
-                ok: false,
-                detail: `${ac.id}(${ac.priority}) 未在测试文件中找到 [${ac.id}] 映射`,
-            });
-            continue;
-        }
-        if (e2eRequired && e2eHits.length === 0) {
-            checks.push({
-                name: `ac-e2e-${ac.id}`,
-                ok: false,
-                detail: `${ac.id} 测试类型含 e2e，但 e2e/ 或 playwright/ 下无对应测试`,
-            });
-            continue;
-        }
-        checks.push({
-            name: `ac-test-${ac.id}`,
-            ok: true,
-            detail: e2eRequired
-                ? `${ac.id} 已映射（含 e2e: ${e2eHits.map((h) => path_1.default.basename(h.file)).join(", ")})`
-                : `${ac.id} 已映射: ${hits.map((h) => path_1.default.basename(h.file)).join(", ")}`,
-        });
-    }
-    return checks;
+    const bindingChecks = (0, acAssertionBinding_1.checkAcAssertionBinding)(items, testContents.map((t) => ({ rel: t.rel, content: t.content })));
+    return bindingChecks.map((c) => ({
+        name: c.name,
+        ok: c.ok,
+        detail: c.detail,
+    }));
 }
 function checkSemanticDiffItems(semantic) {
     const checks = [];
@@ -246,7 +239,7 @@ function checkSemanticDiffItems(semantic) {
 /**
  * gate prd-coverage：PRD 最细粒度条目全覆盖 + 08 复查报告合规 + P0 AC 测试映射。
  */
-async function checkPrdCoverage(outputRoot, pkgRoot) {
+async function checkPrdCoverage(outputRoot, pkgRoot, options) {
     const checks = [];
     const prdContent = await (0, fs_1.readFileIfExists)(path_1.default.join(outputRoot, "source", "PRD.md"));
     if (!prdContent) {
@@ -314,6 +307,7 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
     const needHuman = [];
     const speculationHits = [];
     const emptyEvidence = [];
+    const weakEvidence = [];
     for (const atom of atoms) {
         const row = rowById.get(atom.id);
         if (!row)
@@ -329,6 +323,11 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
         if (!evidence || evidence.length < 8 || /（填写）|待填写|TBD/i.test(evidence)) {
             emptyEvidence.push(atom.id);
         }
+        if (row.verdict === "一致") {
+            const weak = isWeakCodeEvidence(evidence);
+            if (weak)
+                weakEvidence.push(`${atom.id}(${weak})`);
+        }
         const combined = `${row.codeEvidence} ${row.note} ${row.verdict}`;
         const forbidden = hasForbiddenSpeculation(combined);
         if (forbidden)
@@ -355,6 +354,13 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
             ? "每条均有可核对代码证据（文件路径+行号/选择器/断言）"
             : `缺少代码证据: ${emptyEvidence.slice(0, 8).join(", ")}`,
     });
+    checks.push({
+        name: "code-evidence-quality",
+        ok: weakEvidence.length === 0,
+        detail: weakEvidence.length === 0
+            ? "未发现敷衍证据（index.vue:1 / prd-atoms 登记等）"
+            : `证据质量不足: ${weakEvidence.slice(0, 8).join(", ")}`,
+    });
     checks.push({
         name: "no-prd-mismatch-open",
         ok: needFix.length === 0,
@@ -385,10 +391,20 @@ async function checkPrdCoverage(outputRoot, pkgRoot) {
             var _a;
             return ({
                 file: f,
+                rel: path_1.default.relative(pkgRoot, f).replace(/\\/g, "/"),
                 content: (_a = (await (0, fs_1.readFileIfExists)(f))) !== null && _a !== void 0 ? _a : "",
             });
         }));
         checks.push(...checkAcTestMapping(acParsed.items, testContents));
+        if (options === null || options === void 0 ? void 0 : options.changeName) {
+            checks.push(...(await (0, visualRegression_1.checkVisualRegression)(pkgRoot, outputRoot, options.changeName, acParsed.items)));
+        }
+    }
+    if (options === null || options === void 0 ? void 0 : options.changeName) {
+        checks.push(...(await (0, e2eAssertionDepth_1.checkE2eAssertionDepth)(pkgRoot, outputRoot, options.changeName)));
+        checks.push(...(await (0, apiFieldContract_1.checkApiFieldContract)(pkgRoot, options.changeName)));
+        checks.push(...(await (0, apiFieldCoverage_1.checkApiFieldCoverage)(pkgRoot, options.changeName, outputRoot)));
+        checks.push(...(await (0, demoImplementationCoverage_1.checkDemoImplementationCoverage)(pkgRoot, options.changeName)));
     }
     const ok = checks.every((c) => c.ok);
     return { ok, checks };

package/dist/core/prdSemanticDiff.js

@@ -18,6 +18,7 @@ exports.writeSemanticDiffArtifacts = writeSemanticDiffArtifacts;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
 const SOURCE_EXT = /\.(vue|tsx?|jsx?|json|css|less|scss)$/i;
 const TEST_EXT = /\.(spec|test)\.(t|j)sx?$/i;
 const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
@@ -170,15 +171,17 @@ async function verifyEvidenceRefs(pkgRoot, evidence, signals) {
     }
     return { ok: true, detail: "证据路径与字面量可核对" };
 }
+/** PRD 原子须有 test/it 块内 expect 断言；禁止注释或 prd-atoms 登记类伪覆盖 */
 function hasTestCoverageForAtom(atomId, signals, testCorpus) {
     let hasTest = false;
     let hasE2e = false;
     for (const entry of testCorpus) {
-        const hasId = entry.content.includes(atomId) || entry.content.includes(`[${atomId}]`);
-        const hasSignal = signals.some((s) => s.length >= 4 && entry.content.includes(s));
-        if (hasId || hasSignal) {
+        if (!entry.isTest)
+            continue;
+        const { covered, hasE2e: fileE2e } = (0, testAssertionAnalysis_1.hasMeaningfulAtomCoverageInFile)(entry.rel, entry.content, atomId, signals);
+        if (covered) {
             hasTest = true;
-            if (entry.isE2e)
+            if (fileE2e)
                 hasE2e = true;
         }
     }

package/dist/core/snakeCamel.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * snake_case ↔ camelCase 深转换（与前端 caseTransform 语义一致，供门禁脚本使用）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snakeKeyToCamel = snakeKeyToCamel;
+exports.snakeToCamelDeep = snakeToCamelDeep;
+exports.hasSnakeCaseKeys = hasSnakeCaseKeys;
+exports.collectLeafCamelKeys = collectLeafCamelKeys;
+exports.extractFirstListRow = extractFirstListRow;
+function snakeKeyToCamel(key) {
+    return key.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+}
+function snakeToCamelDeep(input) {
+    if (input === null || input === undefined) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map((item) => snakeToCamelDeep(item));
+    }
+    if (typeof input === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(input)) {
+            result[snakeKeyToCamel(key)] = snakeToCamelDeep(value);
+        }
+        return result;
+    }
+    return input;
+}
+/** 对象是否含 snake_case 键（判定为后端样例 fixture） */
+function hasSnakeCaseKeys(input) {
+    if (input === null || typeof input !== "object")
+        return false;
+    if (Array.isArray(input)) {
+        return input.some((item) => hasSnakeCaseKeys(item));
+    }
+    for (const key of Object.keys(input)) {
+        if (key.includes("_"))
+            return true;
+        if (hasSnakeCaseKeys(input[key]))
+            return true;
+    }
+    return false;
+}
+/** 收集对象所有叶子路径的 camelCase 键名（末级 key） */
+function collectLeafCamelKeys(input, out = new Set()) {
+    if (input === null || input === undefined)
+        return out;
+    if (Array.isArray(input)) {
+        for (const item of input)
+            collectLeafCamelKeys(item, out);
+        return out;
+    }
+    if (typeof input === "object") {
+        const obj = input;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return out;
+        const allPrimitive = keys.every((k) => obj[k] === null || ["string", "number", "boolean"].includes(typeof obj[k]));
+        if (allPrimitive) {
+            for (const k of keys)
+                out.add(k);
+            return out;
+        }
+        for (const k of keys)
+            collectLeafCamelKeys(obj[k], out);
+        return out;
+    }
+    return out;
+}
+/** 从常见分页响应结构取首条列表行 */
+function extractFirstListRow(payload) {
+    var _a, _b;
+    const normalized = snakeToCamelDeep(payload);
+    const candidates = [
+        normalized,
+        normalized.data,
+        normalized.records,
+        (_a = normalized.data) === null || _a === void 0 ? void 0 : _a.records,
+        (_b = normalized.data) === null || _b === void 0 ? void 0 : _b.items,
+        normalized.items,
+        normalized.list,
+    ];
+    for (const c of candidates) {
+        if (Array.isArray(c) && c.length > 0 && typeof c[0] === "object" && c[0] !== null) {
+            return c[0];
+        }
+    }
+    if (typeof normalized === "object" && normalized !== null && !Array.isArray(normalized)) {
+        return normalized;
+    }
+    return null;
+}

package/dist/core/syncSourcePrd.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildVersionSlug = buildVersionSlug;
+exports.resolveDocsVersionDir = resolveDocsVersionDir;
+exports.findMainPrdMarkdown = findMainPrdMarkdown;
+exports.ensurePrdImageDirMetadata = ensurePrdImageDirMetadata;
+exports.syncSourcePrdFromDocs = syncSourcePrdFromDocs;
+exports.tryAutoSyncSourcePrd = tryAutoSyncSourcePrd;
+exports.resolveSyncSourceDirRel = resolveSyncSourceDirRel;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const inferProject_1 = require("./inferProject");
+const IMAGE_SUBDIR = "image";
+const PRD_PLACEHOLDER_MARKERS = ["请把《PRD》", "占位", "placeholder"];
+/**
+ * 与 confluence-doc.py 的 version_slug 保持一致：1.2.3 → adi-v123。
+ */
+function buildVersionSlug(productPrefix, version) {
+    const normalized = version
+        .trim()
+        .replace(/^[A-Z]+[-_]?V?/i, "")
+        .replace(/^V/i, "");
+    return `${productPrefix.toLowerCase()}-v${normalized.replace(/\./g, "")}`;
+}
+/**
+ * 解析 docs 下当前版本的 PRD 目录（含主文档与 image/）。
+ */
+async function resolveDocsVersionDir(projectRoot, product, version) {
+    const kind = (0, inferProject_1.productToKind)(product);
+    const prefix = inferProject_1.PRODUCT_PREFIX_BY_KIND[kind];
+    const slug = buildVersionSlug(prefix, version);
+    const docSkill = await (0, inferProject_1.resolveDocSkillDir)(projectRoot, kind);
+    const docsRoot = path_1.default.dirname(docSkill.absPath);
+    const versionDir = path_1.default.join(docsRoot, slug);
+    try {
+        const st = await promises_1.default.stat(versionDir);
+        if (!st.isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { docsRoot, versionDir, slug };
+}
+/**
+ * 在版本目录根下选取体积最大的 .md 作为主 PRD（排除子目录）。
+ */
+async function findMainPrdMarkdown(versionDir) {
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(versionDir);
+    }
+    catch {
+        return null;
+    }
+    const mdFiles = entries.filter((name) => name.toLowerCase().endsWith(".md"));
+    if (mdFiles.length === 0)
+        return null;
+    let best = null;
+    for (const name of mdFiles) {
+        const full = path_1.default.join(versionDir, name);
+        const st = await promises_1.default.stat(full);
+        if (!st.isFile())
+            continue;
+        if (!best || st.size > best.size) {
+            best = { name, size: st.size };
+        }
+    }
+    return best ? path_1.default.join(versionDir, best.name) : null;
+}
+/**
+ * 在 PRD 头部补充原型图片相对路径，供 OPSX UI 解析使用。
+ */
+function ensurePrdImageDirMetadata(content) {
+    if (/原型图片目录/.test(content)) {
+        return content;
+    }
+    const lines = content.split("\n");
+    const titleIdx = lines.findIndex((line) => line.trim().startsWith("# "));
+    const insertAt = titleIdx >= 0 ? titleIdx + 1 : 0;
+    const meta = `> 原型图片目录: ${IMAGE_SUBDIR}/`;
+    lines.splice(insertAt, 0, "", meta);
+    return lines.join("\n");
+}
+async function copyDirRecursive(srcDir, destDir) {
+    await promises_1.default.mkdir(destDir, { recursive: true });
+    const entries = await promises_1.default.readdir(srcDir, { withFileTypes: true });
+    let count = 0;
+    for (const entry of entries) {
+        const srcPath = path_1.default.join(srcDir, entry.name);
+        const destPath = path_1.default.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            count += await copyDirRecursive(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            await promises_1.default.copyFile(srcPath, destPath);
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * 将 docs/<版本目录> 下的 PRD 主文档与 image/ 同步到 openspec run 的 source/。
+ */
+async function syncSourcePrdFromDocs(options) {
+    const resolved = await resolveDocsVersionDir(options.projectRoot, options.product, options.version);
+    if (!resolved) {
+        const slug = buildVersionSlug(inferProject_1.PRODUCT_PREFIX_BY_KIND[(0, inferProject_1.productToKind)(options.product)], options.version);
+        return {
+            ok: false,
+            attempted: true,
+            detail: `未找到 docs 版本目录（期望 docs/${slug}/，请先执行 confluence-doc.py）`,
+        };
+    }
+    const mainMd = await findMainPrdMarkdown(resolved.versionDir);
+    if (!mainMd) {
+        return {
+            ok: false,
+            attempted: true,
+            detail: `docs/${resolved.slug}/ 下无 PRD 主文档（*.md）`,
+        };
+    }
+    const sourceDir = path_1.default.join(options.outputRoot, "source");
+    const destPrd = path_1.default.join(sourceDir, "PRD.md");
+    const raw = await promises_1.default.readFile(mainMd, "utf8");
+    if (raw.trim().length < 80) {
+        return {
+            ok: false,
+            attempted: true,
+            detail: `docs 主文档过短: ${path_1.default.basename(mainMd)}`,
+        };
+    }
+    const content = ensurePrdImageDirMetadata(raw);
+    await (0, fs_1.writeTextFileEnsuredDir)(destPrd, content);
+    const srcImageDir = path_1.default.join(resolved.versionDir, IMAGE_SUBDIR);
+    const destImageDir = path_1.default.join(sourceDir, IMAGE_SUBDIR);
+    let imageCount = 0;
+    try {
+        const st = await promises_1.default.stat(srcImageDir);
+        if (st.isDirectory()) {
+            await promises_1.default.rm(destImageDir, { recursive: true, force: true });
+            imageCount = await copyDirRecursive(srcImageDir, destImageDir);
+        }
+    }
+    catch {
+        // 无图片目录不阻断同步
+    }
+    return {
+        ok: true,
+        attempted: true,
+        detail: `已同步 ${path_1.default.basename(mainMd)} → source/PRD.md${imageCount > 0 ? `，${imageCount} 张图片 → source/${IMAGE_SUBDIR}/` : "（无图片）"}`,
+        sourcePrdPath: destPrd,
+        imageCount,
+    };
+}
+/**
+ * gate 前自动同步：source/PRD.md 仍为占位且 docs 版本目录已存在时尝试回填。
+ */
+async function tryAutoSyncSourcePrd(options) {
+    const existing = await (0, fs_1.readFileIfExists)(path_1.default.join(options.outputRoot, "source", "PRD.md"));
+    if (existing && !PRD_PLACEHOLDER_MARKERS.some((m) => existing.includes(m)) && existing.trim().length >= 80) {
+        return { ok: true, attempted: false, detail: "source/PRD.md 已回填，跳过同步" };
+    }
+    return syncSourcePrdFromDocs(options);
+}
+/**
+ * 从 run 目录相对 doc-skill 脚本目录的 source 路径（供 confluence-doc.py 环境变量）。
+ */
+async function resolveSyncSourceDirRel(projectRoot, sourceDir, product) {
+    const kind = (0, inferProject_1.productToKind)(product);
+    const docSkill = await (0, inferProject_1.resolveDocSkillDir)(projectRoot, kind);
+    const rel = path_1.default.relative(docSkill.absPath, sourceDir).replace(/\\/g, "/");
+    if (!rel || rel.startsWith("..")) {
+        return rel;
+    }
+    return `./${rel}`;
+}

package/dist/core/techDocQuality.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 04-技术文档草稿 结构质量门禁：与 artifacts/04-技术文档.template.md 对齐，禁止摘要版替换完整模板。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIRED_TECH_DOC_SECTIONS = void 0;
+exports.checkTechDocStructure = checkTechDocStructure;
+/** 与模板一致的必备二级章节（允许「## 1. 改造范围」类带后缀标题） */
+exports.REQUIRED_TECH_DOC_SECTIONS = [
+    { id: "meta", pattern: /##\s*文档元信息/m, label: "文档元信息" },
+    { id: "scope", pattern: /##\s*1\.\s*改造范围/m, label: "1. 改造范围" },
+    { id: "ui", pattern: /##\s*2\.\s*页面与交互设计/m, label: "2. 页面与交互设计" },
+    { id: "demo", pattern: /###\s*2\.4\s*演示代码参照/m, label: "2.4 演示代码参照" },
+    { id: "state", pattern: /##\s*3\.\s*前端状态与数据模型设计/m, label: "3. 前端状态与数据模型设计" },
+    { id: "api", pattern: /##\s*4\.\s*接口与数据交互设计/m, label: "4. 接口与数据交互设计" },
+    { id: "form", pattern: /##\s*5\.\s*表单与校验设计/m, label: "5. 表单与校验设计" },
+    { id: "edge", pattern: /##\s*6\.\s*异常、边界与降级方案/m, label: "6. 异常、边界与降级方案" },
+    { id: "files", pattern: /##\s*7\.\s*改造清单/m, label: "7. 改造清单" },
+    { id: "risk", pattern: /##\s*8\.\s*风险点与应对策略/m, label: "8. 风险点与应对策略" },
+    { id: "release", pattern: /##\s*9\.\s*发布、灰度与回滚/m, label: "9. 发布、灰度与回滚" },
+    { id: "test", pattern: /##\s*10\.\s*测试与验收要点/m, label: "10. 测试与验收要点" },
+    { id: "pending", pattern: /##\s*11\.\s*待确认事项/m, label: "11. 待确认事项" },
+];
+const MIN_LINES = 150;
+const MIN_H3_UNDER_SCOPE = 2;
+const API_TABLE_RE = /\|\s*接口\s*\|\s*Method\s*\|/m;
+const FIELD_MAPPING_TABLE_RE = /\|\s*后端字段\s*\|\s*前端字段\s*\|/m;
+const DEMO_TABLE_RE = /\|\s*演示模块\s*\|\s*演示文件\/组件\s*\|/m;
+const AC_REF_RE = /\[AC-\d{2,}\]/g;
+/** 典型「摘要版」反模式：仅若干条顶层 [AC-xx]  bullet，无三级标题 */
+const SUMMARY_ANTIPATTERN_RE = /^#\s*04-技术文档草稿\s*\n+##\s*文档元信息[\s\S]{0,800}##\s*7\.\s*权限/m;
+/**
+ * 校验 04 技术文档是否按模板填满（非摘要替换版）。
+ */
+function checkTechDocStructure(content) {
+    var _a, _b, _c, _d;
+    const missingSections = [];
+    const warnings = [];
+    if (!content || content.trim().length < 80) {
+        return {
+            ok: false,
+            detail: "04-技术文档草稿.md 缺失或过短",
+            missingSections: exports.REQUIRED_TECH_DOC_SECTIONS.map((s) => s.label),
+            warnings: [],
+        };
+    }
+    const lines = content.split("\n");
+    if (lines.length < MIN_LINES) {
+        warnings.push(`行数 ${lines.length} < ${MIN_LINES}（模板级文档通常 ≥150 行）`);
+    }
+    for (const sec of exports.REQUIRED_TECH_DOC_SECTIONS) {
+        if (!sec.pattern.test(content)) {
+            missingSections.push(sec.label);
+        }
+    }
+    const h3InScope = ((_b = (_a = content.match(/##\s*1\.\s*改造范围[\s\S]*?(?=##\s*2\.)/m)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "").match(/^###\s+/gm);
+    if (!h3InScope || h3InScope.length < MIN_H3_UNDER_SCOPE) {
+        missingSections.push("1.x 改造目标/In Scope 等三级小节");
+    }
+    if (!API_TABLE_RE.test(content)) {
+        missingSections.push("4.1 接口清单表格（| 接口 | Method |）");
+    }
+    if (API_TABLE_RE.test(content) && !FIELD_MAPPING_TABLE_RE.test(content)) {
+        missingSections.push("4.3.1 响应字段映射表（| 后端字段 | 前端字段 |）");
+    }
+    if (!DEMO_TABLE_RE.test(content)) {
+        missingSections.push("2.4 演示模块映射表格（| 演示模块 | 演示文件/组件 |）");
+    }
+    const acRefs = (_c = content.match(AC_REF_RE)) !== null && _c !== void 0 ? _c : [];
+    if (acRefs.length < 3) {
+        warnings.push("文中 [AC-XX] 引用过少（建议在各章节分散标注）");
+    }
+    if (SUMMARY_ANTIPATTERN_RE.test(content) && lines.length < 80) {
+        missingSections.push("禁止摘要版：须保留模板全部 11 章并逐节填写");
+    }
+    const placeholderHeavy = ((_d = content.match(/（填写）|待填写|TBD|示例：/g)) !== null && _d !== void 0 ? _d : []).length > 25 &&
+        lines.length < MIN_LINES;
+    if (placeholderHeavy) {
+        warnings.push("占位符过多且篇幅过短，疑似未按 PRD/接口/演示填充");
+    }
+    const ok = missingSections.length === 0 && lines.length >= MIN_LINES;
+    const detail = ok
+        ? `04 技术文档结构合格（${lines.length} 行，${exports.REQUIRED_TECH_DOC_SECTIONS.length} 章齐全）`
+        : `04 技术文档不符合模板: 缺 ${missingSections.join("、")}${warnings.length ? `；${warnings.join("；")}` : ""}`;
+    return {
+        ok,
+        detail,
+        missingSections,
+        warnings,
+    };
+}