@qilitt-mickey/vue3-temp-skill 1.1.35 → 1.1.36

package/parser/index.js

@@ -0,0 +1,553 @@
+#!/usr/bin/env node
+
+/**
+ * index.js — 映射体系解析执行入口
+ *
+ * 职责（V3.0 §3.4.2 / §4.1）：
+ *   1. 读取：递归合并 mapping/ 全目录 → 完整映射数据集
+ *   2. 校验：调用 validator 全量校验，失败 exit 1
+ *   3. 编译：调用 generator 生成 dist/ 产物
+ *   4. 匹配：对设计变更集（design-changeset/v1）执行三级匹配，输出逐 ID 转换计划
+ *      - 一级匹配：ID 完整命中 mappings
+ *      - 二级匹配：父模块（去掉最后一段）命中
+ *      - 三级匹配：全新模块 → 待补充映射清单
+ *
+ * CLI：
+ *   node parser/index.js build [--dry]                      # 校验 + 生成产物
+ *   node parser/index.js match <changeset.json...>          # 三级匹配（可多文件）
+ *   node parser/index.js match --batch <dir>                # 项目级批量匹配目录下全部变更集
+ *   node parser/index.js list [--scene admin] [--verbose]   # 列出全部语义 ID（--verbose 含字段与形态）
+ *   node parser/index.js query <semantic.id>                # 查询单个 ID 映射详情
+ *   node parser/watch.js                                    # 开发态监听 mapping/ 自动重编译（§3.4.3）
+ */
+
+import { readFileSync, statSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildMappingDataset } from "./loader.js";
+import { validateMappingDataset, buildMergedIndex } from "./validator.js";
+import { generateAll } from "./generator.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+
+/** 定性值（非色彩类语义描述，如 中等/全圆角/宽松）：不参与译表，AI 按字段语义施工，不告警。
+ *  注意：模块级常量必须在 main() 调用前声明（TDZ），勿下移到文件底部。 */
+const QUALITATIVE_RE = /^(中等|加粗|常规|细|粗|小圆角|全圆角|直角|宽松|紧凑|标准|大|中|小)$/;
+
+main();
+
+function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+
+  // 每个命令先构建 + 校验（保证在任何操作前映射数据可信）
+  const dataset = buildMappingDataset();
+  const { errors, warnings } = validateMappingDataset(dataset);
+  if (errors.length > 0) {
+    console.error(`✖ 映射表校验失败（${errors.length} 项）：`);
+    for (const e of errors)
+      console.error(`  ✘ ${e}`);
+    process.exit(1);
+  }
+
+  switch (cmd) {
+    case "build":
+      return cmdBuild(args, warnings);
+    case "match":
+      return cmdMatch(args, dataset);
+    case "list":
+      return cmdList(args, dataset);
+    case "query":
+      return cmdQuery(args, dataset);
+    default:
+      printHelp();
+  }
+}
+
+function printHelp() {
+  console.log(`vue3-temp-skill mapping parser
+
+用法：
+  node parser/index.js build [--dry]                      校验映射表并生成 dist/ 产物
+  node parser/index.js match <changeset.json...>          对设计变更集执行三级匹配（可多文件）
+  node parser/index.js match --batch <dir>                项目级批量匹配：目录下全部变更集 + 跨文件汇总
+  node parser/index.js list [--scene admin] [--verbose]   列出全部语义 ID（--verbose 含字段与形态，供下发词汇约束）
+  node parser/index.js query <semantic.id>                查询单个 ID 的映射详情
+  node parser/watch.js                                    开发态监听 mapping/ 变更自动重编译
+  node parser/override.js <overrides.json>                业务级映射覆写调试（API 见 parser/override.js）`);
+}
+
+// ---- build ----
+function cmdBuild(args, warnings) {
+  const dry = args.includes("--dry");
+  for (const w of warnings)
+    console.warn(`  ⚠ ${w}`);
+  const { written, tokenCount } = generateAll(path.join(ROOT, "dist"), dry);
+  console.log(`✔ 映射表校验通过（token ${tokenCount} 项）`);
+  if (dry)
+    console.log(`[dry-run] 将生成：${written.join("、")}`);
+  else
+    console.log(`✔ 产物已生成 → dist/：${written.join("、")}`);
+}
+
+// ---- match：三级匹配 ----
+function cmdMatch(args, dataset) {
+  const files = args.filter(a => !a.startsWith("--"));
+  if (files.length === 0) {
+    console.error("✖ 缺少变更集文件参数：node parser/index.js match <changeset.json...|--batch <dir>>");
+    process.exit(1);
+  }
+
+  // --batch 目录模式：批量读取目录下全部变更集（V3.1 设计侧项目级模式产出
+  // 「一份全局变更集 + 各页面变更集」，项目侧需一次性匹配）
+  let targets = [];
+  if (args.includes("--batch")) {
+    const dir = files[0];
+    const stat = statSync(path.resolve(dir));
+    if (!stat.isDirectory()) {
+      console.error(`✖ --batch 参数应为目录：${dir}`);
+      process.exit(1);
+    }
+    targets = readdirSync(path.resolve(dir))
+      .filter(f => f.endsWith(".json") && !f.startsWith("_"))
+      .sort()
+      .map(f => path.join(path.resolve(dir), f));
+    if (targets.length === 0) {
+      console.error(`✖ 目录内无变更集 JSON：${dir}`);
+      process.exit(1);
+    }
+    console.log(`── 批量模式：${targets.length} 份变更集（${dir}）──`);
+  }
+  else {
+    targets = files.map(f => path.resolve(f));
+  }
+
+  // 跨文件汇总（项目级模式对账用）
+  const batchSummary = { files: 0, l1: 0, l2: 0, l3: 0, pendingIds: [], fieldPending: [], invalid: [] };
+
+  for (const target of targets) {
+    batchSummary.files++;
+    if (targets.length > 1)
+      console.log(`\n════ 变更集 ${batchSummary.files}/${targets.length}：${path.basename(target)} ════`);
+    matchOne(target, dataset, batchSummary);
+  }
+
+  // 任一文件被拒（schema/版本/禁词校验失败）→ 进程退出码 1（v1.0 修正：单文件模式此前误返回 0）
+  if (batchSummary.invalid.length > 0)
+    process.exitCode = 1;
+
+  // 项目级汇总输出
+  if (targets.length > 1) {
+    console.log(`\n════════ 项目级汇总（${targets.length} 份变更集）════════`);
+    console.log(`L1=${batchSummary.l1}（100%） L2=${batchSummary.l2}（85-90%） L3=${batchSummary.l3}（70-80%，补映射后 100%）`);
+    if (batchSummary.invalid.length > 0) {
+      console.log(`✖ 校验失败文件：${batchSummary.invalid.join("、")}`);
+    }
+    if (batchSummary.pendingIds.length > 0) {
+      const uniq = [...new Set(batchSummary.pendingIds)];
+      console.log(`待补充映射 ID（去重 ${uniq.length}）：`);
+      for (const id of uniq)
+        console.log(`  - ${id}`);
+    }
+    if (batchSummary.fieldPending.length > 0) {
+      console.log(`字段级待补充：`);
+      for (const f of batchSummary.fieldPending)
+        console.log(`  - ${f.id}: ${f.fields.join("、")}`);
+    }
+  }
+}
+
+/** 单份变更集匹配（cmdMatch 内部复用） */
+function matchOne(file, dataset, batchSummary) {
+  let changeset;
+  try {
+    changeset = JSON.parse(readFileSync(file, "utf-8"));
+  }
+  catch (e) {
+    console.error(`✖ 变更集读取/解析失败：${e.message}`);
+    batchSummary?.invalid.push(path.basename(file));
+    if (!batchSummary)
+      process.exit(1);
+    return;
+  }
+
+  // 协议校验（canonical：design.changeset/1.0，见 project-ui-design references/changeset-schema.md v1.0；
+  // 兼容历史值 design-changeset/v1，仅告警不阻断）
+  const SUPPORTED_SCHEMAS = ["design.changeset/1.0", "design-changeset/v1"];
+  if (!SUPPORTED_SCHEMAS.includes(changeset.schema)) {
+    console.error(`✖ schema 应为 "design.changeset/1.0"，实际 "${changeset.schema ?? "缺失"}"`);
+    batchSummary?.invalid.push(path.basename(file));
+    if (!batchSummary)
+      process.exit(1);
+    return;
+  }
+  if (changeset.schema === "design-changeset/v1") {
+    console.warn(`  ⚠ schema "${changeset.schema}" 为历史值，建议设计侧升级为 "design.changeset/1.0"`);
+  }
+
+  // 版本校验（v1.0 硬校验：mapping_version 缺失或不匹配 → 拒绝，与双侧文档承诺一致）
+  const versions = new Set(
+    Object.values(dataset.files).map(d => d.meta?.version).filter(Boolean),
+  );
+  const required = changeset.mapping_version;
+  if (!required) {
+    console.error(`✖ 缺少 mapping_version（v1.0 协议必填；获取方式：parser list 输出头部的映射集版本）`);
+    batchSummary?.invalid.push(path.basename(file));
+    if (!batchSummary)
+      process.exit(1);
+    return;
+  }
+  if (!versions.has(required)) {
+    console.error(`✖ 变更集依赖映射表版本 ${required}，当前映射集版本为 ${[...versions].join("/")}，不兼容 → 拒绝执行`);
+    batchSummary?.invalid.push(path.basename(file));
+    if (!batchSummary)
+      process.exit(1);
+    return;
+  }
+
+  // 禁词校验（v1.0：双侧文档承诺「协议违规 = parser 阻断」，此处实现）
+  const banned = checkBannedWords(changeset);
+  if (banned.length > 0) {
+    console.error(`✖ 协议违规（禁词出现即阻断，共 ${banned.length} 处）：`);
+    for (const b of banned)
+      console.error(`  ✘ ${b}`);
+    batchSummary?.invalid.push(path.basename(file));
+    if (!batchSummary)
+      process.exit(1);
+    return;
+  }
+
+  const index = buildMergedIndex(dataset);
+  const valueDict = buildSemanticValueIndex(dataset);
+  const plan = [];
+  const pending = [];
+  const fieldPending = []; // 字段级待补充：ID 命中但 style 字段两层映射均未命中
+
+  // global 令牌翻译（design-apply 第 3 步：走 basic/ 词典，主色另需 setEpThemeColor 链路）
+  if (changeset.global && Object.keys(changeset.global).length > 0) {
+    const tokenDict = buildTokenIndex(dataset);
+    console.log(`\n=== global 令牌翻译（basic/ 词典 + 语义值译表）===`);
+    const gPending = [];
+    for (const [field, value] of Object.entries(changeset.global)) {
+      const def = tokenDict[field];
+      const resolved = resolveSemanticValue(value, valueDict);
+      if (def)
+        console.log(`  . ${field}: ${value} → 令牌 ${def.token}${resolved ? `（精确值 ${resolved}）` : ""}${def.hook ? `（钩子 ${def.hook}）` : ""} @ ${def.file}`);
+      else
+        gPending.push(field);
+      if (!resolved && def && !QUALITATIVE_RE.test(String(value).trim()) && !/^(#|rgb|hsl)/.test(String(value).trim()))
+        console.log(`    ⚠ 值 "${value}" 未命中语义值译表且非 hex，施工前需确认精确值`);
+    }
+    if (gPending.length > 0)
+      console.log(`  ⚠ 未匹配令牌（跳过）：${gPending.join("、")}`);
+  }
+
+  // layout_type 枚举校验（shell-geometry layout_modes）
+  // 兼容读取：设计侧 v0.2 曾误用顶层 `layout` 键——读出来并告警，防止布局意图静默丢失
+  let layoutValue = changeset.layout_type;
+  if (!layoutValue && changeset.layout !== undefined) {
+    layoutValue = changeset.layout;
+    console.warn(`  ⚠ 顶层字段名 "layout" 已废弃（v1.0 协议为 "layout_type"），本次按值 "${changeset.layout}" 兼容处理；请上游更正字段名`);
+  }
+  if (layoutValue) {
+    const layoutModes = collectLayoutModes(dataset);
+    if (layoutModes.size > 0 && !layoutModes.has(layoutValue)) {
+      console.warn(`  ⚠ layout_type "${layoutValue}" 不在标准枚举 [${[...layoutModes].join("/")}] 内 → 按变体/定制布局流程处理（design-apply §4.3）`);
+    }
+  }
+
+  for (const change of changeset.changes || []) {
+    const id = change.id;
+    // 一级：完整命中
+    if (index[id]) {
+      plan.push({ level: 1, id, entry: index[id], change });
+      continue;
+    }
+    // 二级：父模块命中
+    const parentId = id.split(".").slice(0, -1).join(".");
+    if (parentId && index[parentId]) {
+      plan.push({ level: 2, id, parent: parentId, entry: index[parentId], change });
+      continue;
+    }
+    // 三级：全新模块
+    plan.push({ level: 3, id, change });
+    pending.push(id);
+  }
+
+  // pending[] 解析（v1.0：设计侧新 ID 通道，function/parent 供 L3 施工与临时映射生成）
+  if (Array.isArray(changeset.pending) && changeset.pending.length > 0) {
+    console.log(`\n=== pending 新增 ID（${changeset.pending.length} 条，归入 L3 施工，携带功能描述）===`);
+    for (const p of changeset.pending) {
+      if (!p || !p.proposed_id)
+        continue;
+      const hit = pending.includes(p.proposed_id);
+      console.log(`  - ${p.proposed_id}${hit ? "" : "（注意：未出现在 changes[] 中，本次不落地）"}`);
+      console.log(`    功能：${p.function || "（未提供）"}；父模块：${p.parent || "（未提供）"}`);
+    }
+  }
+
+  // 输出转换计划
+  console.log(`\n=== 三级匹配结果（scene=${changeset.scene}，${plan.length} 条）===`);
+  for (const p of plan) {
+    if (p.level === 1) {
+      console.log(`\n[L1 完整命中] ${p.id}`);
+      checkFormEnum(p.entry, p.change);
+      printStyleTranslation(p.entry, p.change, p.id, fieldPending, valueDict);
+    }
+    else if (p.level === 2) {
+      console.log(`\n[L2 父模块命中] ${p.id} → 继承 ${p.parent}（${p.entry.selector ?? p.entry.component ?? "?"}）`);
+      console.log(`  结构：定位父容器按相对位置增量插入；样式：复用父模块映射 + 全局组件映射`);
+      printStyleTranslation(p.entry, p.change, `${p.id}（继承 ${p.parent}）`, fieldPending, valueDict);
+    }
+    else {
+      console.log(`\n[L3 全新模块] ${p.id} → 按场景规范生成默认结构，复用全局原子层映射`);
+    }
+  }
+
+  if (pending.length > 0) {
+    console.log(`\n=== 待补充映射清单（${pending.length}）===`);
+    for (const id of pending)
+      console.log(`  - ${id}`);
+  }
+
+  if (fieldPending.length > 0) {
+    console.log(`\n=== 字段级待补充（ID 命中但 style 字段两层均未命中，跳过不猜）===`);
+    for (const f of fieldPending)
+      console.log(`  - ${f.id}: ${f.fields.join("、")}`);
+  }
+
+  const l1 = plan.filter(p => p.level === 1).length;
+  const l2 = plan.filter(p => p.level === 2).length;
+  const l3 = plan.filter(p => p.level === 3).length;
+  console.log(`\n汇总：L1=${l1}（还原度 100%） L2=${l2}（85-90%） L3=${l3}（70-80%，补映射后可达 100%）`);
+
+  // 汇入跨文件统计（项目级批量模式）
+  if (batchSummary) {
+    batchSummary.l1 += l1;
+    batchSummary.l2 += l2;
+    batchSummary.l3 += l3;
+    batchSummary.pendingIds.push(...pending);
+    batchSummary.fieldPending.push(...fieldPending);
+  }
+}
+
+/** 禁词校验（v1.0 守门员）：DOM/CSS/技术栈词与 hex 位置违规 → 违规描述数组（空 = 通过）
+ *  口径与 project-ui-design changeset-schema.md §禁词校验 一致：
+ *  - hex 仅允许出现在 changes[].style 值与 notes 中
+ *  - id/position/form/visible 等字段出现 hex、CSS 变量名（--el-* / --vts-* / --*）、
+ *    选择器写法（.xxx / #xxx 开头）、伪类（::v-deep / :deep()）即阻断
+ *  - 语义 ID 命名合法性（小写下划线 2~4 段） */
+function checkBannedWords(changeset) {
+  const violations = [];
+  const HEX_RE = /#[0-9a-fA-F]{3,8}\b/;
+  const CSSVAR_RE = /--[a-z][a-z0-9-]*/i;
+  const DEEP_RE = /::?(v-)?deep\(/;
+  const SEL_RE = /^[.#]|[\s]+[.][a-z]|[\s]+#[a-z0-9]/i;
+  const TECH_WORDS = [":deep", "::v-deep", "!important", "el-button", "el-menu", "el-input", "element-plus", "querySelector"];
+  const ID_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,3}$/;
+
+  const scan = (label, value) => {
+    const s = String(value);
+    if (HEX_RE.test(s))
+      violations.push(`${label}：出现 hex 色值 "${s}"（hex 仅允许在 style 值与 notes）`);
+    if (CSSVAR_RE.test(s))
+      violations.push(`${label}：出现 CSS 变量名 "${s}"`);
+    if (DEEP_RE.test(s))
+      violations.push(`${label}：出现穿透写法 "${s}"`);
+    if (SEL_RE.test(s))
+      violations.push(`${label}：疑似选择器写法 "${s}"`);
+    for (const w of TECH_WORDS) {
+      if (s.toLowerCase().includes(w.toLowerCase()))
+        violations.push(`${label}：出现技术栈词 "${w}"`);
+    }
+  };
+
+  for (const [i, c] of (changeset.changes || []).entries()) {
+    const label = `changes[${i}]`;
+    if (!c.id || !ID_RE.test(c.id))
+      violations.push(`${label}.id "${c.id}" 不符合语义 ID 命名规范（小写下划线、2~4 段点分层级）`);
+    if (c.position !== undefined && c.position !== null)
+      scan(`${label}.position`, c.position);
+    if (c.form !== undefined && c.form !== null)
+      scan(`${label}.form`, c.form);
+    if (c.id)
+      scan(`${label}.id`, c.id);
+  }
+  return violations;
+}
+
+function extractForms(e) {
+  if (!e.forms)
+    return [];
+  if (Array.isArray(e.forms))
+    return e.forms.map(f => (typeof f === "string" ? f : f[0])).filter(Boolean);
+  // 对象形态：{ chrome: "说明", card: "说明" } 取键；{ mode: [a,b,c] } 取数组值
+  const out = [];
+  for (const v of Object.values(e.forms)) {
+    if (Array.isArray(v))
+      out.push(...v.filter(x => typeof x === "string"));
+    else if (typeof v === "string" && /^[a-z][a-z0-9_]*$/.test(v))
+      out.push(v);
+  }
+  return out.length > 0 ? out : Object.keys(e.forms);
+}
+
+/** 全局令牌索引：basic/ + layout/ 词典摊平为 { abstractField: {token, hook, file} } */
+function buildTokenIndex(dataset) {
+  const dict = {};
+  for (const [file, data] of Object.entries(dataset.files)) {
+    if (!data.tokens)
+      continue;
+    for (const [field, def] of Object.entries(data.tokens)) {
+      if (field.startsWith("$") || typeof def !== "object")
+        continue;
+      dict[field] = {
+        token: Array.isArray(def.token) ? def.token.join(" → ") : (def.token || "(value token)"),
+        hook: def.hook || null,
+        file: `mapping/${file}`,
+      };
+    }
+  }
+  return dict;
+}
+
+/** 标准布局枚举集合：取 layout 域文件的 layout_modes 键 */
+function collectLayoutModes(dataset) {
+  const modes = new Set();
+  for (const data of Object.values(dataset.files)) {
+    if (data.layout_modes) {
+      for (const k of Object.keys(data.layout_modes)) {
+        if (!k.startsWith("$"))
+          modes.add(k);
+      }
+    }
+  }
+  return modes;
+}
+
+/** form 枚举校验：条目定义了 forms 时，form 值必须在其枚举内（守门员职责，§4.5.2） */
+function checkFormEnum(entry, change) {
+  if (!change.form || !entry.forms)
+    return;
+  const formKeys = extractForms(entry);
+  if (formKeys.length > 0 && !formKeys.includes(change.form)) {
+    console.log(`  ✘ form "${change.form}" 不在条目枚举 [${formKeys.join("/")}] 内 → 报告不猜（design-apply §第2步）`);
+  }
+}
+
+/** 两层样式转换：css_vars 优先 → custom_style_map 兜底 → 未匹配记待补充 */
+function printStyleTranslation(entry, change, idLabel, fieldPending, valueDict) {
+  const styles = change.style || {};
+  if (Object.keys(styles).length === 0)
+    return;
+  const lines = [];
+  const unmatched = [];
+  for (const [field, value] of Object.entries(styles)) {
+    const resolved = resolveSemanticValue(value, valueDict);
+    const valueLabel = resolved ? `${value} → ${resolved}` : value;
+    if (entry.css_vars && entry.css_vars[field]) {
+      lines.push(`  . ${field}: ${valueLabel} → var 覆盖 ${entry.css_vars[field]}（@ ${entry.style_scope}）`);
+    }
+    else if (entry.custom_style_map && entry.custom_style_map[field]) {
+      lines.push(`  . ${field}: ${valueLabel} → 自定义 ${entry.custom_style_map[field]}（@ ${entry.style_scope} + :deep() 隔离）`);
+    }
+    else {
+      unmatched.push(field);
+      continue;
+    }
+    // 字段命中但值未消歧：非 hex、非定性值、不在译表 → 提示（不阻断，AI 施工前须确认）
+    if (!resolved && !QUALITATIVE_RE.test(String(value).trim()) && !/^(#|rgb|hsl|var\(|calc\()/.test(String(value).trim()))
+      lines.push(`    ⚠ 值 "${value}" 未命中语义值译表且非 hex，施工前需确认精确值`);
+  }
+  for (const l of lines)
+    console.log(l);
+  if (unmatched.length > 0) {
+    console.log(`  ⚠ 未匹配字段（跳过）：${unmatched.join("、")}`);
+    if (fieldPending)
+      fieldPending.push({ id: idLabel || change.id, fields: unmatched });
+  }
+}
+
+/** 语义值译表索引：mapping 中 semantic-values.json 摊平为 { 语义名(中/英): 精确值 } */
+function buildSemanticValueIndex(dataset) {
+  const dict = {};
+  for (const data of Object.values(dataset.files)) {
+    if (!data.themes)
+      continue;
+    for (const theme of Object.values(data.themes)) {
+      if (theme && theme.values && typeof theme.values === "object" && !theme.values.$comment) {
+        const label = theme.label || "";
+        for (const [name, hex] of Object.entries(theme.values)) {
+          dict[name] = hex;
+          // 英文别名：钴蓝-5 ↔ cobalt-5（主题 label 的拼音对应 themes 键名）
+        }
+      }
+    }
+    // 英文拼写别名：theme 键名（cobalt/emerald/...）+ 级别号
+    for (const [key, theme] of Object.entries(data.themes)) {
+      if (key.startsWith("$") || !theme || !theme.values)
+        continue;
+      for (let i = 1; i <= 10; i++)
+        dict[`${key}-${i}`] = theme.values[`${theme.label}-${i}`] || "";
+      dict[`${key}-success`] = theme.values["成功色"] || "";
+      dict[`${key}-error`] = theme.values["错误色"] || "";
+      dict[`${key}-warning`] = theme.values["警告色"] || "";
+      dict[`${key}-info`] = theme.values["信息色"] || "";
+      dict[`${key}-link`] = theme.values["链接色"] || "";
+    }
+  }
+  // 清空串
+  for (const k of Object.keys(dict))
+    if (!dict[k])
+      delete dict[k];
+  return dict;
+}
+
+/** 语义值解析：hex 透传 → 中文名查表 → 英文名查表 → null（未命中） */
+function resolveSemanticValue(value, valueDict) {
+  const v = String(value).trim();
+  if (/^#([0-9a-fA-F]{3,8})$/.test(v) || /^(rgb|hsl)a?\(/i.test(v))
+    return v;
+  if (valueDict && valueDict[v])
+    return valueDict[v];
+  return null;
+}
+
+// ---- list ----
+function cmdList(args, dataset) {
+  const sceneIdx = args.indexOf("--scene");
+  const scene = sceneIdx > -1 ? args[sceneIdx + 1] : null;
+  const verbose = args.includes("--verbose") || args.includes("-v");
+  const index = buildMergedIndex(dataset);
+  const ids = Object.keys(index).sort();
+  const filtered = scene ? ids.filter(id => id.startsWith(`${scene}.`) || !/^(admin|portal|dashboard)\./.test(id)) : ids;
+  // v1.0：头部输出映射集版本（供设计侧填 mapping_version，词汇约束下发时随清单同步）
+  const versions = [...new Set(Object.values(dataset.files).map(d => d.meta?.version).filter(Boolean))];
+  console.log(`映射集版本：${versions.join(" / ")}（变更集 mapping_version 应填其中之一）`);
+  console.log(`共 ${filtered.length} 条语义 ID${scene ? `（scene=${scene} + 全局）` : ""}：`);
+  for (const id of filtered) {
+    const e = index[id];
+    console.log(`  ${id.padEnd(46)} [${e.type}] ${e.selector ?? e.component ?? ""}`);
+    if (verbose) {
+      // 词汇约束模式：输出设计侧可用的 style 字段与 form 形态枚举（供下发词汇约束）
+      const fields = [...Object.keys(e.css_vars || {}), ...Object.keys(e.custom_style_map || {})];
+      const forms = extractForms(e);
+      if (fields.length > 0)
+        console.log(`      style 字段：${fields.join(" ")}`);
+      if (forms.length > 0)
+        console.log(`      form 形态：${forms.join(" / ")}`);
+    }
+  }
+}
+
+// ---- query ----
+function cmdQuery(args, dataset) {
+  const id = args.find(a => !a.startsWith("--"));
+  const index = buildMergedIndex(dataset);
+  const entry = index[id];
+  if (!entry) {
+    console.error(`✖ 语义 ID「${id}」未在映射表中定义`);
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ id, ...entry }, null, 2));
+}

package/parser/loader.js

@@ -0,0 +1,66 @@
+/**
+ * loader.js — mapping/ 目录读取与合并
+ *
+ * 递归遍历 mapping/ 下所有 .json 文件，按目录层级合并为完整映射数据集。
+ * 合并顺序（后加载覆盖先加载，同 ID 时场景级扩展全局定义）：
+ *   basic/ → layout/ → component/ → scenes/<scene>/
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const MAPPING_ROOT = path.resolve(__dirname, "..", "mapping");
+
+/** 递归收集 JSON 文件（按目录名字典序，保证合并顺序稳定） */
+function collectJsonFiles(dir) {
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (name.startsWith("_") || name.startsWith("."))
+      continue;
+    const full = path.join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory())
+      out.push(...collectJsonFiles(full));
+    else if (name.endsWith(".json"))
+      out.push(full);
+  }
+  return out;
+}
+
+/**
+ * 构建映射数据集。
+ * @returns {{ files: Record<string, object>, fileCount: number, ids: Record<string, {file, meta}> }}
+ */
+export function buildMappingDataset() {
+  const files = {};
+  const idSource = {};
+
+  for (const filePath of collectJsonFiles(MAPPING_ROOT)) {
+    const rel = path.relative(MAPPING_ROOT, filePath).replaceAll("\\", "/");
+    let data;
+    try {
+      data = JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch (e) {
+      throw new Error(`[mapping/${rel}] JSON 解析失败：${e.message}`);
+    }
+    files[rel] = data;
+
+    if (data.mappings) {
+      for (const id of Object.keys(data.mappings)) {
+        if (id.startsWith("$"))
+          continue;
+        if (idSource[id])
+          console.warn(`  ⚠ 语义 ID「${id}」在 ${idSource[id].file} 与 ${rel} 中重复，后者覆盖`);
+        idSource[id] = { file: rel, meta: data.meta || {} };
+      }
+    }
+  }
+
+  return { files, fileCount: Object.keys(files).length, idSource };
+}
+
+/** 供 validator 使用的别名（保持独立可测） */
+export { buildMappingDataset as buildMappingDatasetForValidator };