sdd-flow-kit 1.3.15 → 1.3.21

package/scripts/lib/snake-camel.mjs

@@ -0,0 +1,74 @@
+/**
+ * snake_case ↔ camelCase（与 src/core/snakeCamel.ts 语义一致）。
+ */
+
+export function snakeKeyToCamel(key) {
+  return key.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+export 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;
+}
+
+export 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;
+}
+
+export 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 keys = Object.keys(input);
+    if (keys.length === 0) return out;
+    const allPrimitive = keys.every(
+      (k) => input[k] === null || ["string", "number", "boolean"].includes(typeof input[k]),
+    );
+    if (allPrimitive) {
+      for (const k of keys) out.add(k);
+      return out;
+    }
+    for (const k of keys) collectLeafCamelKeys(input[k], out);
+    return out;
+  }
+  return out;
+}
+
+export function extractFirstListRow(payload) {
+  const normalized = snakeToCamelDeep(payload);
+  const candidates = [
+    normalized,
+    normalized.data,
+    normalized.records,
+    normalized.data?.records,
+    normalized.data?.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/scripts/lib/test-assertion-analysis.mjs

@@ -0,0 +1,148 @@
+/**
+ * 测试断言分析（与 src/core/testAssertionAnalysis.ts 保持语义一致，供 scripts 独立运行）。
+ */
+
+const TEST_TITLE_RE = /(?:^|\n)\s*(?:test|it)(?:\.(?:only|skip))?\s*\(\s*(?:async\s*)?[`'"]([^`'"]*)[`'"]/g;
+const EXPECT_RE = /\bexpect\s*\(/;
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const REGISTRY_STUB_FILE_RE = /prd-atoms-coverage|prd-atoms-registry|semantic-registry/i;
+const PLACEHOLDER_ONLY_RE = /getByPlaceholder|getByLabel|getByTestId/i;
+const DATA_ASSERTION_RE =
+  /getByRole\s*\(\s*['"]cell|getByRole\s*\(\s*['"]row|toContainText|waitForResponse|\.n-data-table|data-table-tbody|data-table-body/i;
+const HOOK_TITLE_RE = /^(?:beforeEach|afterEach|beforeAll|afterAll)$/i;
+
+export function stripComments(content) {
+  let out = "";
+  let i = 0;
+  while (i < content.length) {
+    if (content[i] === "/" && content[i + 1] === "/") {
+      while (i < content.length && content[i] !== "\n") i += 1;
+      continue;
+    }
+    if (content[i] === "/" && content[i + 1] === "*") {
+      i += 2;
+      while (i < content.length && !(content[i] === "*" && content[i + 1] === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    out += content[i];
+    i += 1;
+  }
+  return out;
+}
+
+export function parseTestBlocks(content) {
+  const stripped = stripComments(content);
+  const blocks = [];
+  const re = new RegExp(TEST_TITLE_RE.source, "g");
+  let m;
+  const indices = [];
+  let idx = 0;
+  while ((m = re.exec(stripped)) !== null) {
+    indices.push({ title: m[1] ?? "", start: m.index, index: idx });
+    idx += 1;
+  }
+  for (let i = 0; i < indices.length; i += 1) {
+    const cur = indices[i];
+    const nextStart = indices[i + 1]?.start ?? stripped.length;
+    const slice = stripped.slice(cur.start, Math.min(cur.start + 4000, nextStart));
+    blocks.push({ title: cur.title, body: slice, index: cur.index });
+  }
+  return blocks;
+}
+
+export function isRegistryStubFile(relPath, content) {
+  const norm = relPath.replace(/\\/g, "/");
+  if (REGISTRY_STUB_FILE_RE.test(norm)) return true;
+  if (!E2E_DIR_RE.test(norm)) return false;
+  const blocks = parseTestBlocks(content);
+  if (blocks.length === 0) return false;
+  const allShallow = blocks.every((b) => {
+    const hasExpect = EXPECT_RE.test(b.body);
+    const onlyCount =
+      /expect\s*\([^)]*\)\s*\.toBeGreaterThan\s*\(\s*0\s*\)/.test(b.body) &&
+      !DATA_ASSERTION_RE.test(b.body) &&
+      !/\bpage\.goto\b/.test(b.body);
+    return !hasExpect || onlyCount;
+  });
+  return allShallow && blocks.length >= 3;
+}
+
+export function testBlockIsPlaceholderOnly(block) {
+  if (HOOK_TITLE_RE.test(block.title.trim())) return false;
+  if (!EXPECT_RE.test(block.body)) return false;
+  const hasPlaceholder = PLACEHOLDER_ONLY_RE.test(block.body);
+  const hasData = DATA_ASSERTION_RE.test(block.body);
+  const hasInteraction = /\b(?:click|dblclick|fill|press|selectOption)\b/.test(block.body);
+  return hasPlaceholder && !hasData && !hasInteraction;
+}
+
+export function testBlockHasExpect(block) {
+  return EXPECT_RE.test(block.body);
+}
+
+export function testBlockReferencesAc(block, acId) {
+  const bracket = `[${acId}]`;
+  const upper = acId.toUpperCase();
+  return (
+    block.title.includes(bracket) ||
+    block.title.toUpperCase().includes(upper) ||
+    block.body.includes(bracket)
+  );
+}
+
+export function analyzeE2eSpecDepth(relPath, content) {
+  const issues = [];
+  if (isRegistryStubFile(relPath, content)) {
+    return {
+      ok: false,
+      issues: ["伪覆盖登记文件，不能作为 change 级 E2E 验收"],
+      stats: { testCount: 0, testsWithExpect: 0, hasGoto: false, hasDataAssertion: false, hasInteraction: false },
+    };
+  }
+
+  const stripped = stripComments(content);
+  const blocks = parseTestBlocks(content);
+  const hookBlocks = blocks.filter((b) => HOOK_TITLE_RE.test(b.title.trim()));
+  const testBlocks = blocks.filter((b) => !HOOK_TITLE_RE.test(b.title.trim()));
+  const testsWithExpect = testBlocks.filter((b) => EXPECT_RE.test(b.body)).length;
+  const hasGoto = /\bpage\.goto\b/.test(stripped);
+  const hasDataInTests = testBlocks.some((b) => DATA_ASSERTION_RE.test(b.body));
+  const hasInteractionInTests = testBlocks.some((b) =>
+    /\b(?:click|dblclick|fill|press|selectOption)\b/.test(b.body),
+  );
+  const placeholderOnlyTests = testBlocks.filter((b) => testBlockIsPlaceholderOnly(b));
+
+  if (testBlocks.length === 0) issues.push("未解析到 test/it 用例（不含 hook）");
+  if (testsWithExpect === 0) issues.push("无含 expect( 的 test/it 块");
+  if (!hasGoto && !hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) {
+    issues.push("缺少 page.goto（页面可达性未验证）");
+  }
+  if (placeholderOnlyTests.length > 0) {
+    issues.push(
+      `以下用例仅断言 placeholder/label: ${placeholderOnlyTests.map((t) => t.title).join(", ")}`,
+    );
+  }
+  if (!hasDataInTests && !hasInteractionInTests) {
+    issues.push("所有 test 块均缺少数据展示断言或交互操作");
+  }
+
+  const ok =
+    testBlocks.length > 0 &&
+    testsWithExpect > 0 &&
+    (hasGoto || hookBlocks.some((b) => /\bpage\.goto\b/.test(b.body))) &&
+    placeholderOnlyTests.length === 0 &&
+    (hasDataInTests || hasInteractionInTests);
+
+  return {
+    ok,
+    issues,
+    stats: {
+      testCount: testBlocks.length,
+      testsWithExpect,
+      hasGoto,
+      hasDataAssertion: hasDataInTests,
+      hasInteraction: hasInteractionInTests,
+    },
+  };
+}

package/scripts/lib/visual-regression.mjs

@@ -0,0 +1,191 @@
+/**
+ * L4 视觉回归分析（与 src/core/visualRegression.ts 语义一致）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseTestBlocks, stripComments, testBlockReferencesAc } from "./test-assertion-analysis.mjs";
+
+const IMAGE_REF_RE =
+  /(?:source\/[\w/.-]+\.(?:png|jpe?g|webp)|visual-baseline\/[\w/.-]+\.(?:png|jpe?g|webp)|image_\d+\.(?:png|jpe?g|webp))/gi;
+const DIFF_PERCENT_RE = /diff\s*[≤<=]\s*(\d+(?:\.\d+)?)\s*%/i;
+const TO_HAVE_SCREENSHOT_RE = /\btoHaveScreenshot\s*\(/;
+const PAGE_SCREENSHOT_ONLY_RE = /\bpage\.screenshot\s*\(/;
+
+export function parseAcMatrixFrom05(content) {
+  const items = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|")) continue;
+    if (/^\|\s*[-:]+/.test(trimmed)) continue;
+    if (/^\|\s*ID\s*\|/i.test(trimmed)) continue;
+    const cells = trimmed
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 5) continue;
+    const id = (cells[0] ?? "").toUpperCase();
+    if (!/^AC-\d{2,}/.test(id)) continue;
+    items.push({
+      id,
+      criterion: cells[2] ?? "",
+      testType: cells[3] ?? "",
+      priority: cells[4] ?? "",
+    });
+  }
+  return items;
+}
+
+export function parseVisualAcRequirements(items) {
+  const out = [];
+  for (const item of items) {
+    if (!/visual/i.test(item.testType ?? "")) continue;
+    const criterion = item.criterion ?? "";
+    const baselineRefs = [...new Set((criterion.match(IMAGE_REF_RE) ?? []).map((s) => s.trim()))];
+    const diffMatch = criterion.match(DIFF_PERCENT_RE);
+    out.push({
+      acId: item.id,
+      criterion,
+      baselineRefs,
+      maxDiffPercent: diffMatch ? Number(diffMatch[1]) : null,
+    });
+  }
+  return out;
+}
+
+function walkImages(dir, out) {
+  if (!fs.existsSync(dir)) return;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkImages(full, out);
+    else if (/\.(png|jpe?g|webp)$/i.test(ent.name)) out.push(full);
+  }
+}
+
+export function listPrdSourceImages(outputRoot) {
+  const images = [];
+  walkImages(path.join(outputRoot, "source"), images);
+  return images;
+}
+
+export function resolveBaselinePath(pkgRoot, outputRoot, ref, prdImages) {
+  const normalized = ref.replace(/\\/g, "/");
+  const candidates = [];
+  if (outputRoot) {
+    candidates.push(path.join(outputRoot, normalized));
+    candidates.push(path.join(outputRoot, "visual-baseline", path.basename(normalized)));
+  }
+  candidates.push(path.join(pkgRoot, normalized));
+  candidates.push(path.join(pkgRoot, "visual-baseline", path.basename(normalized)));
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  if (/^image_\d+\./i.test(normalized)) {
+    const hit = prdImages.find((p) => path.basename(p) === path.basename(normalized));
+    if (hit) return hit;
+  }
+  return prdImages.find((p) => p.endsWith(`/${path.basename(normalized)}`)) ?? null;
+}
+
+function e2eBlockHasVisualAssertion(body) {
+  return TO_HAVE_SCREENSHOT_RE.test(stripComments(body));
+}
+
+function e2eReferencesBaseline(body, baselineRefs) {
+  const stripped = stripComments(body);
+  if (baselineRefs.length === 0) return TO_HAVE_SCREENSHOT_RE.test(stripped);
+  return baselineRefs.some((ref) => {
+    const base = path.basename(ref).replace(/\.(png|jpe?g|webp)$/i, "");
+    return (
+      stripped.includes(ref) ||
+      stripped.includes(base) ||
+      stripped.includes(`'${base}'`) ||
+      stripped.includes(`"${base}"`)
+    );
+  });
+}
+
+export function collectChangeE2eSpecs(root, changeName) {
+  const changeDir = path.join(root, "openspec/changes", changeName);
+  const specs = new Set();
+  let blob = "";
+  for (const f of ["tasks.md", "proposal.md", "design.md"]) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    blob += fs.readFileSync(fp, "utf8");
+  }
+  const re = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+  let m;
+  while ((m = re.exec(blob)) !== null) {
+    const rel = m[0];
+    if (fs.existsSync(path.join(root, rel))) specs.add(rel);
+  }
+  return [...specs].sort();
+}
+
+export function assessVisualRegression(root, outputRoot, changeName, acItems) {
+  const errors = [];
+  const visualReqs = parseVisualAcRequirements(acItems);
+  const prdImages = outputRoot ? listPrdSourceImages(outputRoot) : [];
+  const specPaths = collectChangeE2eSpecs(root, changeName);
+
+  const tasksPath = path.join(root, "openspec/changes", changeName, "tasks.md");
+  if (fs.existsSync(tasksPath) && /^VISUAL_REGRESSION_EXEMPT:/m.test(fs.readFileSync(tasksPath, "utf8"))) {
+    return { errors: [], visualReqs, exempt: true };
+  }
+
+  if (prdImages.length > 0 && visualReqs.length === 0) {
+    errors.push(
+      `PRD source 含 ${prdImages.length} 张原型图，但 05 无 visual AC；请补充基线对比验收项`,
+    );
+    return { errors, visualReqs, exempt: false };
+  }
+
+  if (visualReqs.length === 0) return { errors: [], visualReqs, exempt: false };
+
+  let e2eBlob = "";
+  const e2eBlocks = [];
+  for (const rel of specPaths) {
+    const content = fs.readFileSync(path.join(root, rel), "utf8");
+    e2eBlob += content;
+    for (const block of parseTestBlocks(content)) {
+      e2eBlocks.push({ spec: rel, title: block.title, body: block.body });
+    }
+  }
+
+  if (specPaths.length === 0) errors.push("含 visual AC 但未绑定 e2e spec");
+  else if (!TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+    errors.push("e2e 须使用 toHaveScreenshot（禁止仅 page.screenshot）");
+  }
+
+  for (const req of visualReqs) {
+    if (req.baselineRefs.length === 0) {
+      errors.push(`${req.acId}: visual AC 须写明基线路径`);
+      continue;
+    }
+    for (const ref of req.baselineRefs) {
+      if (!resolveBaselinePath(root, outputRoot, ref, prdImages)) {
+        errors.push(`${req.acId}: 基线图不存在 ${ref}`);
+      }
+    }
+    const bound = e2eBlocks.filter(
+      (b) =>
+        testBlockReferencesAc({ title: b.title, body: b.body, index: 0 }, req.acId) &&
+        e2eBlockHasVisualAssertion(b.body),
+    );
+    if (bound.length === 0) {
+      errors.push(`${req.acId}: e2e 须含 [${req.acId}] + toHaveScreenshot`);
+      continue;
+    }
+    if (!bound.some((b) => e2eReferencesBaseline(b.body, req.baselineRefs))) {
+      errors.push(
+        `${req.acId}: toHaveScreenshot 须引用 ${req.baselineRefs.map((r) => path.basename(r)).join("、")}`,
+      );
+    }
+  }
+
+  if (PAGE_SCREENSHOT_ONLY_RE.test(e2eBlob) && !TO_HAVE_SCREENSHOT_RE.test(e2eBlob)) {
+    errors.push("仅有 page.screenshot 无 toHaveScreenshot");
+  }
+
+  return { errors, visualReqs, exempt: false };
+}

package/scripts/resolve-playwright-e2e-scope.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * 根据 OpenSpec change / 显式模块名解析 Playwright 运行范围。
+ *
+ * scope 三级（见 e2e/e2e-scope.config.json defaultScope）：
+ * - change（默认）：优先 change 文档中的 e2e/*.spec.ts；未写明则按 changeScopeFallback 回退（默认 module）
+ * - module：解析到的 e2e/<module>/ 整个目录
+ * - full：输出 FULL，由调用方跑全量 e2e/**
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const CONFIG_PATH = path.join(ROOT, "e2e/e2e-scope.config.json");
+
+const VALID_SCOPES = new Set(["change", "module", "full"]);
+
+function loadConfig() {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+}
+
+function resolveDefaultScope(config) {
+  const fromEnv = process.env.OPSX_PLAYWRIGHT_SCOPE || process.env.POQUAN_PLAYWRIGHT_SCOPE;
+  if (fromEnv) return fromEnv;
+  return config.defaultScope || "change";
+}
+
+function parseArgs(argv) {
+  const config = loadConfig();
+  const out = {
+    change: "",
+    scope: resolveDefaultScope(config),
+    modules: "",
+  };
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) {
+      out.change = argv[++i];
+    } else if (a === "--scope" && argv[i + 1]) {
+      out.scope = argv[++i];
+    } else if (a === "--modules" && argv[i + 1]) {
+      out.modules = argv[++i];
+    } else if (!a.startsWith("-") && !out.change) {
+      out.change = a;
+    }
+  }
+  const envModules = process.env.OPSX_E2E_MODULES || process.env.POQUAN_E2E_MODULES;
+  if (envModules) {
+    out.modules = envModules;
+  }
+  if (!VALID_SCOPES.has(out.scope)) {
+    console.error(
+      `[resolve-playwright-e2e-scope] 无效 scope="${out.scope}"；允许: change | module | full`,
+    );
+    process.exit(2);
+  }
+  return out;
+}
+
+function findChangeDir(changeName) {
+  const active = path.join(ROOT, "openspec/changes", changeName);
+  if (fs.existsSync(active)) return active;
+  const archiveRoot = path.join(ROOT, "openspec/changes/archive");
+  if (!fs.existsSync(archiveRoot)) return null;
+  const hit = fs
+    .readdirSync(archiveRoot)
+    .filter((d) => d.endsWith(changeName) || d.includes(changeName))
+    .sort()
+    .pop();
+  return hit ? path.join(archiveRoot, hit) : null;
+}
+
+/** 从 change 文档中提取显式声明的 e2e spec 路径（tasks / proposal / design） */
+function collectSpecPathsFromChangeDir(changeDir) {
+  const specs = new Set();
+  const specRe = /\be2e\/[\w/.-]+\.spec\.(?:ts|js)\b/g;
+  const files = ["tasks.md", "proposal.md", "design.md"];
+  for (const f of files) {
+    const fp = path.join(changeDir, f);
+    if (!fs.existsSync(fp)) continue;
+    const content = fs.readFileSync(fp, "utf8");
+    let m;
+    while ((m = specRe.exec(content)) !== null) {
+      const rel = m[0];
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs)) specs.add(rel);
+    }
+  }
+  return [...specs].sort();
+}
+
+function resolveChangeSpecPaths(changeName, config) {
+  const paths = new Set();
+  const changeDir = findChangeDir(changeName);
+  if (changeDir) {
+    collectSpecPathsFromChangeDir(changeDir).forEach((p) => paths.add(p));
+  }
+  const overrides = config.changeNameToSpecs?.[changeName];
+  if (overrides) {
+    for (const raw of overrides) {
+      const rel = raw.startsWith("e2e/") ? raw : `e2e/${raw}`;
+      const abs = path.join(ROOT, rel);
+      if (fs.existsSync(abs)) paths.add(rel);
+    }
+  }
+  return [...paths].sort();
+}
+
+function collectCapabilities(changeDir) {
+  const caps = [];
+  const specsDir = path.join(changeDir, "specs");
+  if (!fs.existsSync(specsDir)) return caps;
+  for (const ent of fs.readdirSync(specsDir, { withFileTypes: true })) {
+    if (ent.isDirectory()) caps.push(ent.name);
+  }
+  return caps;
+}
+
+function scanFeatureDirs(text) {
+  const found = new Set();
+  const re = /src\/features\/([a-z0-9-]+)/gi;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    found.add(m[1]);
+  }
+  return [...found];
+}
+
+function matchChangeNameKeywords(changeName, config) {
+  const mods = new Set();
+  for (const { pattern, modules } of config.changeNameKeywords || []) {
+    if (new RegExp(pattern, "i").test(changeName)) {
+      modules.forEach((mod) => mods.add(mod));
+    }
+  }
+  return [...mods];
+}
+
+function modulesToPaths(moduleIds, config) {
+  const paths = new Set();
+  for (const id of moduleIds) {
+    const dirs = config.modules[id];
+    if (!dirs) continue;
+    dirs.forEach((p) => {
+      const abs = path.join(ROOT, p);
+      if (fs.existsSync(abs)) paths.add(p);
+    });
+  }
+  return [...paths].sort();
+}
+
+function resolveModules({ change, modules }, config) {
+  if (modules) {
+    return modules
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  const moduleSet = new Set();
+  if (change) {
+    const changeDir = findChangeDir(change);
+    if (changeDir) {
+      for (const cap of collectCapabilities(changeDir)) {
+        (config.capabilityToModules[cap] || []).forEach((m) => moduleSet.add(m));
+      }
+      const textFiles = ["proposal.md", "design.md", "tasks.md"];
+      let blob = "";
+      for (const f of textFiles) {
+        const fp = path.join(changeDir, f);
+        if (fs.existsSync(fp)) blob += `${fs.readFileSync(fp, "utf8")}\n`;
+      }
+      for (const feat of scanFeatureDirs(blob)) {
+        (config.featureDirToModules[feat] || []).forEach((m) => moduleSet.add(m));
+      }
+    }
+    matchChangeNameKeywords(change, config).forEach((m) => moduleSet.add(m));
+  }
+  return [...moduleSet];
+}
+
+/** 按 change / OPSX_E2E_MODULES / POQUAN_E2E_MODULES 解析模块 id 与 e2e 目录路径 */
+function resolveModuleScope(args, config) {
+  const moduleIds = resolveModules(args, config);
+  const paths = modulesToPaths(moduleIds, config);
+  return { moduleIds, paths };
+}
+
+function emitModulePaths(args, config, logPrefix) {
+  const { moduleIds, paths } = resolveModuleScope(args, config);
+  if (paths.length === 0) {
+    console.error(
+      "[resolve-playwright-e2e-scope] 未能解析模块；请设置 OPSX_E2E_MODULES=auth,review / POQUAN_E2E_MODULES=auth,review 或 OPSX_PLAYWRIGHT_SCOPE=full",
+    );
+    process.exit(2);
+  }
+  process.stderr.write(
+    `${logPrefix} scope=module change=${args.change || "-"} modules=${moduleIds.join(",")} paths=${paths.join(" ")}\n`,
+  );
+  paths.forEach((p) => process.stdout.write(`${p}\n`));
+}
+
+function main() {
+  const config = loadConfig();
+  const args = parseArgs(process.argv);
+
+  if (args.scope === "full") {
+    process.stdout.write("FULL\n");
+    return;
+  }
+
+  if (args.scope === "change") {
+    if (!args.change) {
+      console.error(
+        "[resolve-playwright-e2e-scope] scope=change 需要 change 名；示例: node scripts/resolve-playwright-e2e-scope.mjs <change-name>",
+      );
+      process.exit(2);
+    }
+    const specPaths = resolveChangeSpecPaths(args.change, config);
+    if (specPaths.length > 0) {
+      process.stderr.write(
+        `[resolve-playwright-e2e-scope] scope=change（文档 spec） change=${args.change} specs=${specPaths.join(" ")}\n`,
+      );
+      specPaths.forEach((p) => process.stdout.write(`${p}\n`));
+      return;
+    }
+
+    const fallback = config.changeScopeFallback ?? "module";
+    if (fallback === "module") {
+      process.stderr.write(
+        `[resolve-playwright-e2e-scope] scope=change 未在 tasks/proposal/design 中找到 spec，` +
+          `已按 changeScopeFallback=module 回退模块目录（change=${args.change}）\n`,
+      );
+      emitModulePaths(args, config, "[resolve-playwright-e2e-scope]");
+      return;
+    }
+
+    console.error(
+      `[resolve-playwright-e2e-scope] scope=change 未找到 e2e/*.spec.ts，且 changeScopeFallback=${fallback}；` +
+        `可配置 changeNameToSpecs、将 changeScopeFallback 设为 module，或 OPSX_PLAYWRIGHT_SCOPE=module|full`,
+    );
+    process.exit(2);
+  }
+
+  emitModulePaths(args, config, "[resolve-playwright-e2e-scope]");
+}
+
+main();

package/src/templates/artifacts/01-adi-doc-skill-/346/214/207/345/274/225.template.md

@@ -7,9 +7,12 @@
 ```bash
 cd {{DOC_SKILL_REL}}
 export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
+export SDD_SYNC_SOURCE_DIR="{{SYNC_SOURCE_DIR_REL}}"
 python3 confluence-doc.py {{VERSION_EXAMPLE}}
 ```
 
+脚本成功后会自动将 `docs/<版本目录>/*.md` 与 `image/` 同步到本 run 的 `source/PRD.md` 与 `source/image/`（也可手动执行 `npx sdd-flow-kit sync-source-prd --run-id <runId>`）。
+
 版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。
 
 2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。
@@ -24,8 +27,9 @@ python3 confluence-doc.py {{VERSION_EXAMPLE}}
 
 5. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。
 
-6. 成功后把生成的 `docs/*.md` **主文档**复制/回填到本 run 目录：
-   - `source/PRD.md`
+6. 同步结果（自动，无需手抄）：
+   - `source/PRD.md`（含 `> 原型图片目录: image/` 元数据行）
+   - `source/image/`（正文图片，与 docs 版本目录一致）
 
 ## 直链兜底（可选，非默认）
 

package/src/templates/artifacts/02-/351/234/200/346/261/202/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.template.md

@@ -23,6 +23,11 @@
 - `01-需求分析报告.md`
 - `02-改动点清单.md`
 - `03-待确认问题清单.md`
+- 阶段 B 交付模式另产出：`05-验收清单.md`、**填写完成的** `04-技术文档草稿.md`（须符合 `04-技术文档生成指引.md`，禁止摘要版）
+
+## 04 技术文档（阶段 B 必读）
+- 同 run 目录：`04-技术文档生成指引.md`
+- 脚手架已生成完整模板 `04-技术文档草稿.md` → **在原文件上填内容，勿删章节**
 
 ## 输出话术（建议固定）
 - 提问模式：`SDD 模式：提问模式；矛盾点池状态：未闭合；仅更新 03，等待人工确认。`