sdd-flow-kit 1.3.15 → 1.3.21

package/scripts/assess-visual-regression.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * L4 视觉回归门禁：05 visual AC + 基线图 + E2E toHaveScreenshot。
+ *
+ * 用法:
+ *   node scripts/assess-visual-regression.mjs --change <name> --run-dir openspec/PRD/<runId>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  assessVisualRegression,
+  parseAcMatrixFrom05,
+} from "./lib/visual-regression.mjs";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function parseArgs(argv) {
+  let change = "";
+  let runDir = "";
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--change" && argv[i + 1]) change = argv[++i];
+    else if (a === "--run-dir" && argv[i + 1]) runDir = argv[++i];
+    else if (!a.startsWith("-") && !change) change = a;
+  }
+  return { change, runDir };
+}
+
+function resolveRunDir(arg) {
+  if (!arg) return "";
+  const candidates = [
+    path.isAbsolute(arg) ? arg : path.join(ROOT, arg),
+    path.join(ROOT, "openspec/PRD", arg),
+    path.join(ROOT, "frontend/openspec/PRD", arg),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "05-验收清单.md"))) return c;
+  }
+  return "";
+}
+
+function fail(messages) {
+  console.error("[assess-visual-regression] FAIL");
+  for (const m of messages) console.error(`  - ${m}`);
+  console.error(
+    "  修复: 05 增加 visual AC（含基线路径 + diff≤N%）；e2e 使用 toHaveScreenshot；基线图放 source/ 或 visual-baseline/",
+  );
+  process.exit(1);
+}
+
+function main() {
+  const skip = process.env.OPSX_SKIP_VISUAL_REGRESSION;
+  if (skip === "1") {
+    console.warn("[assess-visual-regression] SKIP");
+    process.exit(0);
+  }
+
+  const { change, runDir: runDirArg } = parseArgs(process.argv);
+  if (!change) {
+    console.error("[assess-visual-regression] 缺少 --change <name>");
+    process.exit(2);
+  }
+
+  const changeDir = path.join(ROOT, "openspec/changes", change);
+  if (!fs.existsSync(changeDir)) {
+    console.error(`[assess-visual-regression] change 不存在: openspec/changes/${change}`);
+    process.exit(2);
+  }
+
+  const runDir = resolveRunDir(runDirArg);
+  if (!runDir) {
+    console.error("[assess-visual-regression] 缺少 --run-dir（须含 05-验收清单.md）");
+    process.exit(2);
+  }
+
+  const acItems = parseAcMatrixFrom05(fs.readFileSync(path.join(runDir, "05-验收清单.md"), "utf8"));
+  const { errors, visualReqs, exempt } = assessVisualRegression(ROOT, runDir, change, acItems);
+
+  if (exempt) {
+    console.log("[assess-visual-regression] PASS（豁免）");
+    process.exit(0);
+  }
+
+  if (errors.length > 0) fail(errors);
+
+  console.log(
+    `[assess-visual-regression] PASS change=${change} visualAc=${visualReqs.length}`,
+  );
+}
+
+main();

package/scripts/install-git-hooks.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# 安装 pre-commit：提交前执行 opsx:gate（见 AGENTS.md）
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HOOK_PATH="$(git -C "$ROOT_DIR" rev-parse --git-dir 2>/dev/null)/hooks/pre-commit"
+
+if [[ ! -d "$(dirname "$HOOK_PATH")" ]]; then
+  echo "[opsx:install-hooks] ERROR: 不在 git 仓库内" >&2
+  exit 1
+fi
+
+cat >"$HOOK_PATH" <<'HOOK'
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+if command -v pnpm >/dev/null 2>&1; then
+  pnpm run opsx:gate
+else
+  bash scripts/assert-active-openspec-change.sh
+fi
+HOOK
+
+chmod +x "$HOOK_PATH"
+echo "[opsx:install-hooks] 已安装 pre-commit -> $HOOK_PATH"
+echo "[opsx:install-hooks] 提交含 src/ 或 e2e/ 改动时将校验 OpenSpec change 绑定"

package/scripts/lib/ac-assertion-binding.mjs

@@ -0,0 +1,119 @@
+/**
+ * AC 断言绑定（与 src/core/acAssertionBinding.ts 语义一致）。
+ */
+import {
+  parseTestBlocks,
+  stripComments,
+  testBlockHasExpect,
+  testBlockReferencesAc,
+} from "./test-assertion-analysis.mjs";
+
+const E2E_DIR_RE = /(^|\/)(e2e|playwright)(\/|$)/i;
+const MIN_LITERAL_LEN = 4;
+const FUZZY_ONLY_ASSERT_RE =
+  /expect\s*\([^)]*\)\s*\.toContain(?:Text)?\s*\(\s*['"](?:成功|失败|错误|保存|完成)['"]\s*\)/;
+
+export function extractCriterionLiterals(criterion) {
+  const out = new Set();
+  const text = criterion ?? "";
+  const quotedPatterns = [/「([^」]{3,})」/g, /"([^"]{3,})"/g, /'([^']{3,})'/g, /`([^`]{3,})`/g];
+  for (const re of quotedPatterns) {
+    let m;
+    const r = new RegExp(re.source, re.flags);
+    while ((m = r.exec(text)) !== null) {
+      const v = m[1]?.trim();
+      if (v && v.length >= MIN_LITERAL_LEN) out.add(v);
+    }
+  }
+  const placeholder = text.match(/请输入[^\s，,。；;]+/);
+  if (placeholder?.[0] && placeholder[0].length >= MIN_LITERAL_LEN) out.add(placeholder[0]);
+  return [...out];
+}
+
+export function testBlockBindsCriterionLiterals(blockBody, literals) {
+  if (literals.length === 0) return true;
+  const body = stripComments(blockBody);
+  if (!/\bexpect\s*\(/.test(body)) return false;
+  if (literals.some((lit) => body.includes(lit))) return true;
+  return literals.some((lit) => lit.length >= 8 && body.includes(lit.slice(0, 8)));
+}
+
+export function testBlockIsFuzzyOnly(blockBody, literals) {
+  if (literals.length === 0) return false;
+  const body = stripComments(blockBody);
+  if (!FUZZY_ONLY_ASSERT_RE.test(body)) return false;
+  return !testBlockBindsCriterionLiterals(blockBody, literals);
+}
+
+export function checkAcAssertionBinding(items, testFiles) {
+  const errors = [];
+  const mustCover = items.filter(
+    (i) => /^P0$/i.test(i.priority.trim()) || /e2e/i.test(i.testType ?? ""),
+  );
+
+  for (const ac of mustCover) {
+    const isP0 = /^P0$/i.test(ac.priority.trim());
+    const testType = (ac.testType ?? "").trim();
+    const literals = extractCriterionLiterals(ac.criterion ?? "");
+
+    if (isP0 && /^manual$/i.test(testType)) {
+      errors.push(`${ac.id}: P0 禁止纯 manual，须 unit/e2e`);
+      continue;
+    }
+
+    const e2eRequired = /e2e/i.test(testType);
+    let bound = false;
+    let e2eBound = false;
+
+    for (const tf of testFiles) {
+      const blocks = parseTestBlocks(tf.content);
+      for (const block of blocks) {
+        if (!testBlockReferencesAc(block, ac.id)) continue;
+        if (!testBlockHasExpect(block)) continue;
+        const literalOk = testBlockBindsCriterionLiterals(block.body, literals);
+        const fuzzy = testBlockIsFuzzyOnly(block.body, literals);
+        if ((literalOk && !fuzzy) || literals.length === 0) {
+          bound = true;
+          if (E2E_DIR_RE.test(tf.rel)) e2eBound = true;
+        }
+      }
+    }
+
+    if (!bound) {
+      const hint =
+        literals.length > 0
+          ? `expect 须含: ${literals.slice(0, 2).join("、")}`
+          : "须有 expect";
+      errors.push(`${ac.id}: 未绑定验收字面量；${hint}`);
+    } else if (e2eRequired && !e2eBound) {
+      errors.push(`${ac.id}: 测试类型含 e2e 但 e2e/ 无绑定字面量的 test`);
+    }
+  }
+
+  return errors;
+}
+
+/** 解析 05-验收清单 AC 表格 */
+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,
+      priority: cells[4] ?? "",
+      criterion: cells[2] ?? "",
+      testType: cells[3] ?? "",
+    });
+  }
+  return items;
+}

package/scripts/lib/api-field-coverage.mjs

@@ -0,0 +1,238 @@
+/**
+ * API 字段级覆盖（与 src/core/apiFieldCoverage.ts 语义一致）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  collectLeafCamelKeys,
+  extractFirstListRow,
+  hasSnakeCaseKeys,
+  snakeToCamelDeep,
+} from "./snake-camel.mjs";
+
+const FIELD_TABLE_HEADER_RE = /\|\s*后端字段\s*\|\s*前端字段\s*\|/m;
+const NORMALIZE_TEST_RE = /caseTransform|snakeToCamel|normalize\w*Api/i;
+const FIXTURE_LOAD_RE = /fixtures\/|readFileSync|import\s+\w+\s+from\s+['"].*\.json['"]/;
+
+export function parseFieldMappingTable(content) {
+  const rows = [];
+  if (!FIELD_TABLE_HEADER_RE.test(content)) return rows;
+  const section =
+    content.match(/###\s*4\.3[\s\S]*?(?=###\s*4\.4|##\s*5\.)/m)?.[0] ??
+    content.match(/##\s*API\s*字段契约[\s\S]*/im)?.[0] ??
+    content;
+  const lines = section.split("\n");
+  let inTable = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("|") && FIELD_TABLE_HEADER_RE.test(trimmed)) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable || !trimmed.startsWith("|")) continue;
+    if (/^\|\s*[-:]+/.test(trimmed)) continue;
+    const cells = trimmed
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 2) continue;
+    if (/后端字段|backend/i.test(cells[0])) continue;
+    const backendField = cells[0].replace(/`/g, "").trim();
+    const frontendField = cells[1].replace(/`/g, "").trim();
+    if (!backendField || !frontendField || /填写/.test(backendField)) continue;
+    rows.push({ backendField, frontendField, displayLocation: cells[2] });
+  }
+  return rows;
+}
+
+export function readChangeBlob(changeDir) {
+  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");
+  }
+  return blob;
+}
+
+export function collectApiModules(blob) {
+  const mods = new Set();
+  const re = /config\/api\/modules\/([\w/-]+)/g;
+  let m;
+  while ((m = re.exec(blob)) !== null) {
+    mods.add(m[1].replace(/\/index$/, "").replace(/\/$/, ""));
+  }
+  return mods;
+}
+
+export function listFixtureFiles(root, moduleName) {
+  const dirs = [
+    path.join(root, "tests/fixtures", moduleName),
+    path.join(root, "frontend/tests/fixtures", moduleName),
+    path.join(root, "tests/fixtures"),
+    path.join(root, "frontend/tests/fixtures"),
+  ];
+  const files = [];
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (name.endsWith(".json")) files.push(path.join(dir, name));
+    }
+  }
+  return [...new Set(files)];
+}
+
+function walkSource(dir, acc) {
+  if (!fs.existsSync(dir)) return acc;
+  let out = acc;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === "node_modules") continue;
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) out = walkSource(full, out);
+    else if (/\.(vue|tsx?|ts)$/.test(ent.name)) {
+      out += fs.readFileSync(full, "utf8");
+    }
+  }
+  return out;
+}
+
+export function collectSourceCorpus(root, changeDir) {
+  let blob = readChangeBlob(changeDir);
+  const fileRefs = new Set();
+  const patterns = [
+    /(?:src|frontend\/src)\/[\w/.-]+\.(vue|tsx?|ts)/g,
+    /views\/[\w/.-]+\.(vue|tsx?)/g,
+  ];
+  for (const re of patterns) {
+    let m;
+    const r = new RegExp(re.source, "g");
+    while ((m = r.exec(blob)) !== null) {
+      fileRefs.add(m[0].replace(/^frontend\//, ""));
+    }
+  }
+  for (const ref of fileRefs) {
+    for (const fp of [
+      path.join(root, ref),
+      path.join(root, "frontend", ref),
+      path.join(root, "src", ref.replace(/^src\//, "")),
+    ]) {
+      if (fs.existsSync(fp)) {
+        blob += fs.readFileSync(fp, "utf8");
+        break;
+      }
+    }
+  }
+  for (const vr of [
+    path.join(root, "src/views"),
+    path.join(root, "frontend/src/views"),
+  ]) {
+    blob = walkSource(vr, blob);
+  }
+  return blob;
+}
+
+function walkTests(dir, moduleName, hits) {
+  if (!fs.existsSync(dir)) return;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, ent.name);
+    if (ent.isDirectory()) walkTests(full, moduleName, hits);
+    else if (/\.(spec|test)\.(t|j)sx?$/.test(ent.name)) {
+      const content = fs.readFileSync(full, "utf8");
+      if (NORMALIZE_TEST_RE.test(content) && /snakeToCamel|caseTransform/.test(content)) {
+        hits.push(full);
+      }
+    }
+  }
+}
+
+export function findNormalizeTests(root, moduleName) {
+  const hits = [];
+  for (const r of [path.join(root, "tests"), path.join(root, "frontend/tests")]) {
+    walkTests(r, moduleName, hits);
+  }
+  return hits;
+}
+
+export function corpusContainsField(corpus, field) {
+  if (!field || field.length < 2) return true;
+  const snake = field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+  return corpus.includes(field) || corpus.includes(`'${field}'`) || corpus.includes(snake);
+}
+
+export function assessApiFieldCoverage(root, changeName, fieldDoc) {
+  const errors = [];
+  const passed = [];
+  const changeDir = path.join(root, "openspec/changes", changeName);
+  const blob = readChangeBlob(changeDir);
+  const modules = collectApiModules(blob);
+  if (modules.size === 0) return { errors, passed, mappingRows: [] };
+
+  const mappingRows = parseFieldMappingTable(fieldDoc);
+  const corpus = collectSourceCorpus(root, changeDir);
+
+  if (mappingRows.length === 0) {
+    errors.push("04/design 缺少 §4.3.1 字段映射表（| 后端字段 | 前端字段 |）");
+  }
+
+  for (const mod of modules) {
+    const fixtures = listFixtureFiles(root, mod);
+    const validFixtures = [];
+    for (const fp of fixtures) {
+      try {
+        const payload = JSON.parse(fs.readFileSync(fp, "utf8"));
+        if (hasSnakeCaseKeys(payload)) validFixtures.push({ path: fp, payload });
+      } catch {
+        // skip
+      }
+    }
+    if (validFixtures.length === 0) {
+      errors.push(
+        `${mod}: 缺少 tests/fixtures/${mod}/*.json（须含 snake_case，来自联调抓包）`,
+      );
+      continue;
+    }
+
+    const normalizeTests = findNormalizeTests(root, mod);
+    const strongTest = normalizeTests.some((tp) => {
+      const t = fs.readFileSync(tp, "utf8");
+      return (
+        /expect\s*\(/.test(t) &&
+        /snakeToCamel|normalize/.test(t) &&
+        (FIXTURE_LOAD_RE.test(t) || /subject_id|_[a-z]/.test(t))
+      );
+    });
+    if (!strongTest) {
+      errors.push(
+        `${mod}: 缺少 caseTransform 单测（expect 断言 camelCase；建议加载 fixtures/${mod}/*.json）`,
+      );
+    }
+
+    const fixtureKeys = new Set();
+    for (const f of validFixtures) {
+      const row = extractFirstListRow(f.payload);
+      const normalized = snakeToCamelDeep(f.payload);
+      if (row) Object.keys(row).forEach((k) => fixtureKeys.add(k));
+      for (const k of collectLeafCamelKeys(normalized)) fixtureKeys.add(k);
+    }
+
+    const keysToCheck =
+      mappingRows.length > 0
+        ? mappingRows.map((r) => r.frontendField)
+        : [...fixtureKeys].filter((k) => k.length >= 3).slice(0, 12);
+
+    const missing = keysToCheck.filter((k) => !corpusContainsField(corpus, k));
+    if (keysToCheck.length > 0 && missing.length === keysToCheck.length) {
+      errors.push(
+        `${mod}: 字段 [${keysToCheck.slice(0, 5).join(", ")}] 在源码中无消费点`,
+      );
+    } else if (missing.length > 0 && mappingRows.length > 0) {
+      errors.push(`${mod}: 映射表字段未在源码出现: ${missing.slice(0, 6).join(", ")}`);
+    } else {
+      passed.push(
+        `${mod}(fixtures=${validFixtures.length}, ok=${keysToCheck.length - missing.length}/${keysToCheck.length})`,
+      );
+    }
+  }
+
+  return { errors, passed, mappingRows };
+}

package/scripts/lib/component-substance.mjs

@@ -0,0 +1,117 @@
+/**
+ * 组件实质分析（与 src/core/componentSubstance.ts 语义一致）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const MIN_EFFECTIVE_LINES = 40;
+const VUE_TEMPLATE_RE = /<template[^>]*>([\s\S]*?)<\/template>/i;
+const INTERACTIVE_CONTROL_RE =
+  /<(?:n-button|a-button|el-button|NButton|AButton|ElButton|button|n-input|a-input|el-input|input|n-data-table|a-table|el-table|NDataTable|ATable|n-drawer|a-drawer)[\s/>]/i;
+const API_BEHAVIOR_RE =
+  /from\s+['"][^'"]*(?:config\/api|api\/modules)|useMutation|useQuery|Api\s*\(|financePost|financeGet/i;
+const EMIT_HANDLER_RE = /defineEmits|emit\s*\(|@\w+\s*=\s*["']|onClick|onSubmit/i;
+const CHILD_COMPONENT_RE = /(?:Section|Modal|Panel|Form)\.vue$/i;
+const PARENT_CONTAINER_RE = /(?:Drawer|index)\.vue$/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 countEffectiveLines(content) {
+  return stripComments(content)
+    .split("\n")
+    .filter((l) => l.trim().length > 0).length;
+}
+
+export function signalPresentInComponent(content, signal) {
+  if (!signal || signal.length < 2) return true;
+  const stripped = stripComments(content);
+  const template = stripped.match(VUE_TEMPLATE_RE)?.[1] ?? "";
+  const script = stripped.replace(VUE_TEMPLATE_RE, "");
+  return template.includes(signal) || script.includes(signal);
+}
+
+export function analyzeComponentSubstance(relPath, content, interactionSignals) {
+  const issues = [];
+  const stripped = stripComments(content);
+  const effectiveLines = countEffectiveLines(content);
+
+  if (effectiveLines < MIN_EFFECTIVE_LINES) {
+    issues.push(`有效代码行 ${effectiveLines} < ${MIN_EFFECTIVE_LINES}（疑似空壳）`);
+  }
+
+  if (/\.vue$/i.test(relPath)) {
+    const template = content.match(VUE_TEMPLATE_RE)?.[1] ?? "";
+    if (!template.trim()) issues.push("缺少 <template> 区块");
+    else if (!INTERACTIVE_CONTROL_RE.test(template)) {
+      issues.push("template 中未发现 button/input/table 等可交互控件");
+    }
+  }
+
+  const hasBehavior = API_BEHAVIOR_RE.test(stripped) || EMIT_HANDLER_RE.test(stripped);
+  const meaningfulSignals = interactionSignals.filter((s) => s.length >= 2);
+  if (!hasBehavior && meaningfulSignals.length > 0) {
+    issues.push("script 中未发现 API 调用或 emit/事件处理（疑似只读骨架）");
+  }
+
+  const missingSignals = meaningfulSignals.filter((s) => !signalPresentInComponent(content, s));
+  if (meaningfulSignals.length > 0 && missingSignals.length === meaningfulSignals.length) {
+    issues.push(`交互信号均未出现在 template/script: ${meaningfulSignals.join("、")}`);
+  } else if (missingSignals.length > 0) {
+    issues.push(`缺少交互信号: ${missingSignals.join("、")}`);
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
+export async function checkChildComponentsImported(pkgRoot, mappings) {
+  const failures = [];
+  const paths = mappings.map((m) => m.productionPath.replace(/^\.\//, ""));
+
+  for (const m of mappings) {
+    const rel = m.productionPath.replace(/^\.\//, "");
+    if (!CHILD_COMPONENT_RE.test(rel)) continue;
+    if (PARENT_CONTAINER_RE.test(rel)) continue;
+
+    const base = path.basename(rel, path.extname(rel));
+    let imported = false;
+
+    for (const otherRel of paths) {
+      if (otherRel === rel) continue;
+      const fp = path.join(pkgRoot, otherRel);
+      if (!fs.existsSync(fp)) continue;
+      const content = fs.readFileSync(fp, "utf8");
+      if (
+        new RegExp(`import\\s+\\w+\\s+from\\s+['"][^'"]*${base}['"]`).test(content) ||
+        content.includes(`<${base}`) ||
+        content.includes(`<${base} `)
+      ) {
+        imported = true;
+        break;
+      }
+    }
+
+    if (!imported) {
+      failures.push(`${m.moduleName}: ${rel} 未被父组件 import/挂载`);
+    }
+  }
+
+  return failures;
+}

package/scripts/lib/demo-reference-parse.mjs

@@ -0,0 +1,55 @@
+/**
+ * 演示参照章节解析（与 src/core/demoImplementationCoverage.ts 语义一致）。
+ */
+const DEMO_SECTION_RE = /^##\s*(演示代码参照|Demo Reference)\s*$/im;
+const DEMO_EXEMPT_RE = /^DEMO_REFERENCE_EXEMPT:\s*(.+)$/m;
+const MAPPING_HEADER_RE = /演示模块|Demo Module/i;
+
+export function parseDemoReferenceSection(content) {
+  const exemptMatch = content.match(DEMO_EXEMPT_RE);
+  const exempt = exemptMatch?.[1]?.trim() || null;
+
+  const sectionMatch = content.match(DEMO_SECTION_RE);
+  if (!sectionMatch || sectionMatch.index === undefined) {
+    return { hasSection: false, exempt, demoRoot: null, demoStack: null, mappings: [] };
+  }
+
+  const sectionBody = content.slice(sectionMatch.index);
+  const demoRoot =
+    sectionBody.match(/演示代码根路径[：:]\s*`?([^`\n]+)`?/i)?.[1]?.trim() || null;
+  const demoStack =
+    sectionBody.match(/技术栈[：:]\s*`?(vue|react|其他)[^`\n]*`?/i)?.[1]?.trim() || null;
+
+  const mappings = [];
+  const lines = sectionBody.split("\n");
+  let inTable = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (line.startsWith("|") && MAPPING_HEADER_RE.test(line)) {
+      inTable = true;
+      continue;
+    }
+    if (!inTable || !line.startsWith("|")) continue;
+    if (/^\|\s*[-:]+/.test(line)) continue;
+    const cells = line
+      .split("|")
+      .map((c) => c.trim())
+      .filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+    if (cells.length < 4) continue;
+    if (/演示模块|Demo Module/i.test(cells[0])) continue;
+
+    const signals = (cells[3] ?? "")
+      .split(/[、,，|；;]/)
+      .map((s) => s.trim())
+      .filter((s) => s.length >= 2);
+
+    mappings.push({
+      moduleName: cells[0],
+      demoRef: cells[1],
+      productionPath: cells[2].replace(/\\/g, "/"),
+      interactionSignals: signals,
+    });
+  }
+
+  return { hasSection: true, exempt, demoRoot, demoStack, mappings };
+}

package/scripts/lib/e2e-demo-signal-clicks.mjs

@@ -0,0 +1,43 @@
+/**
+ * E2E 演示信号点击（与 src/core/e2eDemoSignalClicks.ts 语义一致）。
+ */
+import { parseDemoReferenceSection } from "./demo-reference-parse.mjs";
+
+const CLICKABLE_SIGNAL_RE = /编辑|保存|删除|新增|导入|拉取|提交|确认|取消|打开|修改|添加/i;
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export 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(`getByText\\s*\\(\\s*['"\`]${esc}`),
+    new RegExp(`getByText\\s*\\(\\s*[^)]*${esc}`),
+    new RegExp(`locator\\s*\\([^)]*${esc}[^)]*\\)\\.click`),
+  ];
+  return clickPatterns.some((re) => re.test(stripped));
+}
+
+export function checkE2eDemoSignalClicks(designContent, e2eBlob) {
+  const parsed = parseDemoReferenceSection(designContent ?? "");
+  if (parsed.exempt || parsed.mappings.length === 0) return [];
+
+  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/getByText 覆盖「${clickable.join("、")}」`,
+      );
+    }
+  }
+  return failures;
+}