@xulthekl/team-flow 0.53.0 → 0.55.0

package/scripts/check-project-config.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// check-project-config.mjs — 项目配置漂移检查（v0.55.0，设计 §8.5 N2）
+//
+// ── 动机 ─────────────────────────────────────────────────────────────────────
+// 现场实测（workflow-feedback 2026-09-11）的三类漂移：
+//   ① `version` 落后于插件版本（0.48.0 vs 0.54.0）——用户以为在用新版
+//   ② `designSystemC` 指向**不存在**的 c-end.md
+//   ③ `versionWorktree` 指向**不存在**的 .worktrees/ 目录
+// 三者都不会报错，只会在用到时静默失效。
+//
+// ── 检查面（P1.5 三轮校正：按"实际被消费"分级）──────────────────────────────
+//   真调用点：`prototype.designSystem`（ce-brainstorm/references/prototype-loop.md）
+//   声明级：  `prototype.designSystemBase` / `prototype.entry`（多处文档声明、无 --get 调用点）
+//   零消费者：`prototype.designSystemC` / `prototype.versionWorktree`（全仓无引用）
+// → 前两类做**存在性检查**；后两类只报"未被消费"（不是错误，是配置残留）。
+//
+// Usage: node scripts/check-project-config.mjs [项目根，默认 cwd]
+// 退出码：0 = 正常（含仅警告）；1 = 配置存在但不可解析
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+const root = resolve(process.argv[2] || process.cwd());
+const cfgPath = join(root, '.team-flow', 'team-flow.config.json');
+
+if (!existsSync(cfgPath)) {
+  console.log(`ℹ️  未找到 ${cfgPath}（跳过配置漂移检查）`);
+  process.exit(0);
+}
+
+let cfg;
+try {
+  cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+} catch (e) {
+  console.error(`❌ 配置无法解析：${cfgPath}`);
+  console.error(`   ${e.message}`);
+  process.exit(1);
+}
+
+const proto = cfg.prototype || {};
+const warnings = [];
+
+// ①–② 存在性检查（真调用点 + 声明级）
+const CONSUMED = [
+  { key: 'designSystem', level: '真调用点' },
+  { key: 'designSystemBase', level: '声明级' },
+  { key: 'entry', level: '声明级' },
+];
+for (const { key, level } of CONSUMED) {
+  const v = proto[key];
+  if (!v || typeof v !== 'string') continue;
+  if (!existsSync(resolve(root, v))) {
+    warnings.push(`prototype.${key}（${level}）指向的路径不存在：${v}`);
+  }
+}
+
+// ③ 零消费者键（配置残留，不是错误）
+for (const key of ['designSystemC', 'versionWorktree']) {
+  if (proto[key]) {
+    warnings.push(`prototype.${key} 在插件内**零消费者**（全仓无引用）——该键不会被读取，可删除或忽略`);
+  }
+}
+
+// ④ 版本漂移
+if (cfg.version) {
+  const pkgPath = join(PLUGIN_DIR, 'package.json');
+  const pluginVersion = existsSync(pkgPath)
+    ? JSON.parse(readFileSync(pkgPath, 'utf-8')).version
+    : null;
+  if (pluginVersion && cfg.version !== pluginVersion) {
+    warnings.push(`配置 version=${cfg.version} 与插件版本 ${pluginVersion} 不一致（配置由项目侧维护，请确认是否需更新）`);
+  }
+}
+
+if (warnings.length === 0) {
+  console.log(`✅ 配置无漂移（${cfgPath}）`);
+  process.exit(0);
+}
+
+console.log(`⚠️  配置漂移 ${warnings.length} 项（${cfgPath}）——**均为提示，不阻断**：`);
+for (const w of warnings) console.log(`   - ${w}`);
+process.exit(0);

package/scripts/design-system-clone.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// design-system-clone.mjs — 设计系统移植（v0.55.0，设计 §8.2.4 形态 B / D-22）
+//
+// ── 为什么需要 ───────────────────────────────────────────────────────────────
+// 设计系统就是 `.team-flow/design-system/` 下的 markdown，技术上 `cp -r` 即可。
+// 但直接复制会留 4 个坑，本脚本把它们自动化：
+//   ① **来源与裁决记录失真**——复制后仍写着原项目的导入记录（如"从 page-gen 导入于 X"），
+//      而目标项目并未导入过 → **追加**移植条目（**保留**原裁决历史：其裁决依据仍有参考价值）
+//   ② **primer.md 的 digest 失效**——它锚定源 base.md 内容；改一个字即 STALE，
+//      而 prototype Step 0 对 `contract: v1` 系统会 **blocked** → **强制重生成 + 校验**
+//   ③ **业务专属组件残留**（如"协议富文本编辑器/内容预览画布"）→ 输出契约表清单供调用方
+//      （design-system skill）**逐条问询**
+//   ④ **授权边界**——源系统 `references/` 下可能是企业内部资产 → 输出提示（不自动判定）
+//
+// 交互部分（业务组件"要不要保留"）**不在本脚本**：脚本只做确定性动作 + 输出问询素材。
+//
+// Usage: node scripts/design-system-clone.mjs --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>
+
+import { readFileSync, writeFileSync, existsSync, statSync, cpSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, join, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseComponentsTable } from './lib/ds-parse.mjs';
+
+const argv = process.argv.slice(2);
+const fromIdx = argv.indexOf('--from');
+const toIdx = argv.indexOf('--to');
+const fromArg = fromIdx !== -1 ? argv[fromIdx + 1] : null;
+const toArg = toIdx !== -1 ? argv[toIdx + 1] : null;
+
+if (!fromArg || !toArg) {
+  console.error('Usage: node scripts/design-system-clone.mjs --from <源项目路径 | 源设计系统目录> --to <目标设计系统目录>');
+  process.exit(1);
+}
+
+const PLUGIN_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+const GUARD = join(PLUGIN_DIR, 'scripts', 'guard', 'design-token-guard.mjs');
+const GEN_PRIMER = join(PLUGIN_DIR, 'scripts', 'gen-primer.mjs');
+
+// ── 源定位：既接受项目根，也接受设计系统目录本身 ──
+
+const fromAbs = resolve(fromArg);
+if (!existsSync(fromAbs) || !statSync(fromAbs).isDirectory()) {
+  console.error(`源路径不存在或不是目录：${fromAbs}`);
+  process.exit(1);
+}
+const nested = join(fromAbs, '.team-flow', 'design-system');
+const srcDir = existsSync(nested) ? nested : fromAbs;
+if (!existsSync(join(srcDir, 'base.md'))) {
+  console.error(`源目录内未找到 base.md：${srcDir}`);
+  console.error('（--from 可指向项目根，或直接指向 .team-flow/design-system）');
+  process.exit(1);
+}
+
+// ── 目标：必须不存在或为空（移植是**新建**；已有设计系统请走 iterate 的 MERGE 语义）──
+
+const dstDir = resolve(toArg);
+if (existsSync(dstDir) && existsSync(join(dstDir, 'base.md'))) {
+  console.error(`目标目录已存在 base.md：${dstDir}`);
+  console.error('目标已有设计系统 → 请走 design-system 的 **iterate** 模式（MERGE 不 OVERWRITE），不要 clone。');
+  process.exit(1);
+}
+
+// ── ① 校验源系统（警告不阻断：源可能是 legacy 系统）──
+
+console.log('① 校验源系统…');
+const srcGuard = spawnSync('node', [GUARD, srcDir], { encoding: 'utf-8' });
+const srcOk = srcGuard.status === 0;
+console.log(srcOk
+  ? '   源系统硬校验通过'
+  : `   ⚠️  源系统硬校验未通过（exit ${srcGuard.status}）——移植后需一并修复`);
+if (!srcOk && srcGuard.stdout) {
+  const failed = srcGuard.stdout.split('\n').filter(l => l.trim().startsWith('❌'));
+  failed.slice(0, 5).forEach(l => console.log(`     ${l.trim()}`));
+}
+
+// ── ② 复制（排除 primer.md / pending.md / showcase/）──
+
+const EXCLUDE = new Set(['primer.md', 'pending.md', 'showcase']);
+mkdirSync(dstDir, { recursive: true });
+cpSync(srcDir, dstDir, {
+  recursive: true,
+  filter: (src) => !EXCLUDE.has(basename(src)),
+});
+console.log(`② 已复制到 ${dstDir}（排除：primer.md / pending.md / showcase/）`);
+
+// ── ③ 追加移植记录（保留原裁决历史）──
+
+const basePath = join(dstDir, 'base.md');
+let base = readFileSync(basePath, 'utf-8');
+const stamp = new Date().toISOString().slice(0, 10);
+const entry = `> **移植记录**：${stamp} 由 \`design-system-clone\` 从 \`${srcDir}\` 移植。`
+  + '原「来源与裁决记录」**保留**——其裁决依据对理解本系统的取值仍有参考价值。';
+
+if (/^##\s+来源与裁决记录\s*$/m.test(base)) {
+  base = base.replace(/^(##\s+来源与裁决记录\s*)$/m, `$1\n\n${entry}`);
+} else {
+  // 无该段 → 在文档头部（首个 ## 段之前）创建
+  const firstSection = base.search(/^##\s+/m);
+  const insertAt = firstSection === -1 ? base.length : firstSection;
+  base = `${base.slice(0, insertAt)}## 来源与裁决记录\n\n${entry}\n\n${base.slice(insertAt)}`;
+}
+writeFileSync(basePath, base, 'utf-8');
+console.log('③ 已追加移植记录（原来源与裁决记录保留）');
+
+// ── ④ 输出业务组件清单（供调用方逐条问询）──
+
+const table = parseComponentsTable(base);
+const rows = table ? table.rows : [];
+console.log(`④ 契约表共 ${rows.length} 类组件 —— **请逐条确认目标项目是否需要**（不需要的删除后重跑 guard；`);
+console.log('   注意组件数跌破档位会改变 L2 标签：<10 FAIL / 10-14 WARN / ≥15 PASS）：');
+for (const r of rows) console.log(`     - ${r.name}（${r.type}）`);
+
+// ── ⑤ 重生成 primer + 校验（digest 锚定的是新路径下的 base 内容）──
+
+console.log('⑤ 重生成 primer…');
+const gen = spawnSync('node', [GEN_PRIMER, basePath], { encoding: 'utf-8' });
+if (gen.status !== 0) {
+  console.error(`   ❌ primer 生成失败：${(gen.stderr || gen.stdout || '').trim()}`);
+  process.exit(1);
+}
+const check = spawnSync('node', [GEN_PRIMER, basePath, '--check'], { encoding: 'utf-8' });
+// v0.55.0 §8.2.4 修订：`--check` 紧跟在"刚重生成"之后运行，两者不一致 = 生成器自相矛盾
+// （而非用户输入问题）——属于内部一致性错误，**必须参与退出码**，否则脚本报成功而产物对
+// `contract: v1` 系统实为 blocked（prototype Step 0 会拒绝），问题被推迟到使用现场才暴露。
+if (check.status !== 0) {
+  console.error(`   ❌ primer 自检失败（exit ${check.status}）：刚生成的 primer 与其输入不一致。`);
+  console.error((check.stderr || check.stdout || '').trim());
+  console.error('   这是生成器缺陷（非用户输入问题），请上报；移植产物暂不可用。');
+  process.exit(1);
+}
+console.log('   primer --check：OK（digest 一致）');
+
+// ── ⑥ 跑 guard 并输出结论 ──
+
+console.log('⑥ 对移植结果跑 guard…');
+const dstGuard = spawnSync('node', [GUARD, dstDir], { encoding: 'utf-8' });
+if (dstGuard.stdout) {
+  const lines = dstGuard.stdout.split('\n');
+  const auditStart = lines.findIndex(l => l.startsWith('## 六层审计报告'));
+  if (auditStart !== -1) lines.slice(auditStart).forEach(l => console.log(`   ${l}`));
+}
+
+console.log('');
+console.log('移植完成。**仍需人工处理的事项**：');
+console.log('  a) 业务组件裁剪（见 ④ 的清单）—— 删除后重跑 guard');
+console.log('  b) 品牌适配：若目标项目主色/字体不同 → 改 base.md 的 color 段 → **重跑 gen-primer**（digest 会变）');
+console.log('  c) 授权：源系统 references/ 下若含企业内部资产，跨企业边界复用时须自行确认授权');
+console.log('  d) `contract`：移植产物继承源系统的取值；若源为 v1 而目标尚未达标，可考虑降为 legacy');
+process.exit(dstGuard.status === 0 ? 0 : 1);

package/scripts/design-system-import.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+// design-system-import.mjs — open-design DESIGN.md / 内置 profile → team-flow base.md 转换器（v0.55.0，设计 §4.5.2 / §8.2.4）
+//
+// 解析 open-design 九节 DESIGN.md，映射到 team-flow 的 9 段 schema（A1/A2/B-slot + 组件契约表 + principles/governance）。
+// 关键约束：**转换后必须补齐完整度**（palette 阶梯 / A2 派生公式 / B-slot 别名 / 组件契约表基线）——
+//           来源原文没有这些，转换器按 team-flow 规则生成。
+//
+// v0.55.0 变更（设计 §8.2.4 / D-18）：
+//   - 新增 `--profile antd`：无外部源的**确定性 B 端起点**（Ant Design v5 seed token，MIT）。
+//     与 reference 导入走同一条生成路径（合成源文本 → 复用解析）。**零 LLM、零外部资产**。
+//   - 产物 `contract` 由 `v1` 改 **`legacy`**：导入的既有资产天然未经校准，按 v1 最严档判会一落盘
+//     即 blocked（死循环）。用户裁决达标后经 iterate 升 v1。
+//   - `layout` 段增「容器骨架」块与「页面范式」声明：内置 `template.html` 的骨架是营销向的
+//     `hero/cta/log`，**缺 B 端容器类** → 不给物料则 builder 每页要手写整套骨架 CSS。
+//   - 新增 `来源与裁决记录` 段（导入类条件必填，审计层 advisory，不进硬校验）。
+//
+// Usage:
+//   node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]
+//   node scripts/design-system-import.mjs --profile antd [--out <base.md 路径>]
+// 输出后建议运行：node scripts/guard/design-token-guard.mjs <base.md>
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, basename, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ── 内置 profile（v0.55.0，设计 §8.2.4 形态 A）──
+//
+// "全新项目且无任何规范"时的确定性起点。规格全部来自 **Ant Design v5 seed token**（MIT）
+// 或 team-flow 自有规范——**不含任何项目补录值**（原方案的模板内容表多数条目实为某项目的
+// 补录而非通用惯例，P1.5 反方逐条实查 page-gen 全树后推翻，见设计 §8.2.4"为何取消"）。
+//
+// 实现方式：合成一份 open-design 形态的源文本，复用下方的既有解析路径（零新增解析逻辑）。
+const SYNTHETIC_SOURCES = {
+  antd: `# B-end Admin (Ant Design v5 basis)
+
+> Category: Enterprise Admin
+> 通用 B 端后台基线——规格取自 Ant Design v5 seed token（MIT）与 team-flow 自有规范，不含项目专属值。
+
+**Primary:** \`#1677FF\`
+**Surface:** \`#FFFFFF\`
+**Text:** \`#000000E0\`
+**Secondary:** \`#8C8C8C\`
+**Families:** primary=-apple-system, Segoe UI, system-ui; display=-apple-system, Segoe UI, system-ui; mono=ui-monospace
+**Scale:** 12/14/16/20/24
+**Spacing scale:** 4/8/12/16/24/32/40/48
+`,
+};
+
+const argv = process.argv.slice(2);
+const outIdx = argv.indexOf('--out');
+const outArg = outIdx !== -1 ? argv[outIdx + 1] : null;
+const idIdx = argv.indexOf('--id');
+const idArg = idIdx !== -1 ? argv[idIdx + 1] : null;
+const profileIdx = argv.indexOf('--profile');
+const profileArg = profileIdx !== -1 ? argv[profileIdx + 1] : null;
+const positional = argv.filter((a, i) =>
+  !a.startsWith('--') && !(outIdx !== -1 && i === outIdx + 1)
+  && !(idIdx !== -1 && i === idIdx + 1) && !(profileIdx !== -1 && i === profileIdx + 1));
+const srcPath = positional[0];
+
+if (profileArg && !SYNTHETIC_SOURCES[profileArg]) {
+  console.error(`未知 profile：${profileArg}（可用：${Object.keys(SYNTHETIC_SOURCES).join(', ')}）`);
+  process.exit(1);
+}
+if (!profileArg && !srcPath) {
+  console.error('Usage: node scripts/design-system-import.mjs <DESIGN.md 路径> [--out <base.md 路径>] [--id <标识>]');
+  console.error('       node scripts/design-system-import.mjs --profile antd [--out <base.md 路径>]');
+  process.exit(1);
+}
+const srcAbs = srcPath ? resolve(srcPath) : null;
+if (srcAbs && !existsSync(srcAbs)) {
+  console.error(`DESIGN.md not found: ${srcAbs}`);
+  process.exit(1);
+}
+
+const src = profileArg ? SYNTHETIC_SOURCES[profileArg] : readFileSync(srcAbs, 'utf-8');
+// 标识：显式 --id > profile 名 > 文件名（非约定名 `DESIGN.md` 时）> 目录名（约定名的旧行为）。
+// v0.55.0：原实现恒取目录名——内置模板库（`templates/design-systems/references/linear-app.md`）
+// 会得到无意义的 `references`，写进「来源与裁决记录」段后无法辨认来源。
+const id = idArg || (profileArg
+  ? `profile-${profileArg}`
+  : basename(srcAbs).toLowerCase() === 'design.md'
+    ? basename(dirname(srcAbs))
+    : basename(srcAbs, extname(srcAbs)));
+
+// ── 解析 open-design 九节 ──
+
+function grab(pattern) {
+  const m = src.match(pattern);
+  return m ? m[1].trim() : null;
+}
+
+const title = grab(/^#\s+(.+)$/m) || `Design System Inspired by ${id}`;
+const category = grab(/> Category:\s*(.+)/) || 'Uncategorized';
+const summary = grab(/>\s*(?!Category)(.+\S)/) || '';
+
+// A 类模板格式：`**Primary:** \`#hex\``
+let primary = grab(/\*\*Primary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let surface = grab(/\*\*Surface:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+let text = grab(/\*\*Text:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+
+// B 类精细格式 fallback：找 brand/accent/primary 上下文附近的 hex（自动提取，需人工核对）
+let autoExtracted = false;
+if (!primary) {
+  const m = src.match(/(?:brand|accent|primary)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  if (m) { primary = m[1]; autoExtracted = true; }
+}
+if (!surface) {
+  const m = src.match(/(?:background|surface|canvas)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  surface = m ? m[1] : '#FFFFFF';
+  if (m) autoExtracted = true;
+}
+if (!text) {
+  const m = src.match(/(?:text|foreground)[^\n]{0,100}?(#[0-9a-fA-F]{6})/i);
+  text = m ? m[1] : '#111827';
+  if (m) autoExtracted = true;
+}
+
+const secondary = grab(/\*\*Secondary:\*\*\s*`(#[0-9a-fA-F]{3,8})`/);
+const success = grab(/\*\*Success:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#16A34A';
+const warning = grab(/\*\*Warning:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#D97706';
+const danger = grab(/\*\*Danger:\*\*\s*`(#[0-9a-fA-F]{3,8})`/) || '#DC2626';
+const families = grab(/\*\*Families:\*\*\s*(.+)/) || 'primary=Inter, display=Inter, mono=ui-monospace';
+const scale = grab(/\*\*Scale:\*\*\s*(.+)/) || '12/14/16/20/24/32';
+const spacingScale = grab(/\*\*Spacing scale:\*\*\s*(.+)/) || '4/8/12/16/24/32';
+
+if (!primary) {
+  console.error(`未能从 ${srcAbs} 解析出 Primary 色。`);
+  console.error('A 类格式需 `**Primary:** \\`#hex\\``；B 类格式自动提取失败。');
+  console.error('B 类设计系统建议走人工路径：浏览参考文档 → 提取配色 → 用 create-from-code 或手工创建。');
+  process.exit(1);
+}
+if (autoExtracted) {
+  console.warn('⚠️  B 类格式：配色为自动提取（brand/surface/text 上下文匹配），**请人工核对后再采用**。');
+}
+
+// 字体族解析：primary=X, display=Y, mono=Z → 系统栈兜底（零依赖：不引 webfont，仅保留字体名首选 + 系统栈）
+function fontStack(family) {
+  const f = (family || 'Inter').trim().replace(/^['"]|['"]$/g, '');
+  const isMono = /mono|code|menlo|consolas/i.test(f);
+  if (isMono) return `'${f}', ui-monospace, SFMono-Regular, Menlo, monospace`;
+  return `'${f}', -apple-system, 'Segoe UI', system-ui, 'PingFang SC', 'Microsoft YaHei', sans-serif`;
+}
+const famMap = Object.fromEntries(families.split(',').map(p => {
+  const [k, v] = p.split('=').map(x => (x || '').trim());
+  return [k, v];
+}));
+const fontDisplay = fontStack(famMap.display || famMap.primary);
+const fontBody = fontStack(famMap.primary);
+const fontMono = fontStack(famMap.mono || 'ui-monospace');
+
+// 字号阶梯：open-design 的 "12/14/16/20/24/32" → type scale 名称映射
+const scaleNums = scale.split('/').map(s => s.trim()).filter(Boolean);
+const typeScale = scaleNums.slice(0, 7).map((v, i) => {
+  const names = ['--text-xs', '--text-sm', '--text-base', '--text-lg', '--text-xl', '--text-2xl', '--text-3xl'];
+  return `${names[i]}: ${v}px`;
+}).join('；') || '--text-xs: 12px；--text-sm: 14px；--text-base: 16px；--text-lg: 20px；--text-xl: 24px；--text-2xl: 32px';
+
+// ── 组件契约表基线（20 类，来自 design-system-architect.md 的完整基线）──
+
+const CONTRACT_ROWS = [
+  '| Button | 交互 | primary / secondary / ghost / danger | sm / md / lg | default / hover / focus-visible / active / disabled / loading | 触发动作 | 用颜色单独传状态 |',
+  '| Input | 交互 | default / error / success | sm / md / lg | default / focus / disabled / readonly / error / filled | 文本录入 | 无 label |',
+  '| Select | 交互 | default / multiple / searchable | sm / md / lg | default / focus / disabled / error / open | 选项选择 | 超 10 项不用搜索 |',
+  '| Checkbox | 交互 | default / indeterminate | sm / md | default / hover / focus / disabled / checked | 多选 | — |',
+  '| Radio | 交互 | default | sm / md | default / focus / disabled / selected | 单选 | 超 7 项改用 Select |',
+  '| Switch | 交互 | default | md | default / focus / disabled / on / off | 二元开关 | 高危操作须确认 |',
+  '| Tag | 轻量 | default / success / warning / danger / info | sm / md | default / hover / closable¹ | 状态标记 | 用作按钮 |',
+  '| Icon | 豁免 | — | sm / md / lg | — | 语义图示 | emoji |',
+  '| Avatar | 轻量 | circle / square | sm / md / lg | default / fallback / loading | 用户标识 | — |',
+  '| Tooltip | 轻量 | default | — | hidden / visible | 补充说明 | 承载关键操作 |',
+  '| Modal | 交互 | default / confirm / destructive | sm / md / lg | open / loading / error / closing | 阻断式交互 | 嵌套 Modal |',
+  '| Drawer | 交互 | left / right / bottom | sm / md / lg | open / loading / error | 侧边任务面板 | — |',
+  '| Tabs | 交互 | line / pill | — | default / active / disabled / loading | 内容分组 | 超 7 个 tab |',
+  '| Table | 交互 | default / compact / striped | — | default / loading / empty / error / selected | 结构化数据 | 无分页超长列表 |',
+  '| Form | 交互 | single / two-column | — | untouched / dirty / submitted-pending / error | 字段集合 | 单页超 20 字段 |',
+  '| Card | 交互 | default / interactive / stat | — | default / hover / selected / loading | 内容容器 | 嵌套超 2 层 |',
+  '| Pagination | 交互 | default / simple | sm / md | default / disabled / loading | 分页导航 | — |',
+  '| FilterBar | 交互 | default / collapsible | — | default / expanded / applied | 筛选条件集合 | — |',
+  '| EmptyState | 豁免 | default / filtered / error | — | — | 空态承载 | 只有"暂无数据" |',
+  '| Toast | 交互 | success / warning / error / info | — | entering / visible / exiting | 轻量反馈 | 承载需用户操作的信息 |',
+];
+
+// ── 生成 base.md ──
+
+const base = `# ${title}
+
+> a11y: WCAG 2.2 AA（对比度 4.5:1 / 大字 3:1 / 焦点可见 / 键盘可达）
+
+> 由 open-design 设计系统 \`${id}\`（Category: ${category}）转换生成（scripts/design-system-import.mjs v0.54.0）。
+> ${summary}
+> 来源归因：open-design（nexu-io）MIT License，"inspired by" 逆向工程描述，非官方资产。
+
+## 来源与裁决记录
+
+> **原始来源**：${profileArg ? `内置 profile \`${profileArg}\`（Ant Design v5 seed token，MIT）` : `open-design \`${id}\`（Category: ${category}）`}
+> **导入日期**：${new Date().toISOString().slice(0, 10)}
+> **导入方式**：转换器确定性生成（\`scripts/design-system-import.mjs\`）—— **未做语义裁决**
+> **为什么不是直接采纳**：① **结构**——来源是描述性散文，team-flow 需 9 段 schema；② **Token 形式**——需补 A2 派生公式与 B-slot 别名；③ **消费入口**——需生成 primer 供 builder 使用
+> **★ 主色裁决**：无（单一来源，取自 \`accent\`）${autoExtracted ? '\n> **⚠️ B 类自动提取**：原来源未以 A 类格式声明配色，\`accent\` 等值由正则自动提取——**须人工核对**' : ''}
+> **待清理项**：组件契约表为 20 类通用基线（与来源无关），须对照项目实际增删；本段为**审计层 advisory**，不参与 guard 硬校验
+
+## color
+
+**A1-identity（8 必选）**
+- \`--bg\`: color-mix(in oklab, var(--surface), var(--fg) 3%)
+- \`--surface\`: ${surface}
+- \`--fg\`: ${text}
+- \`--muted\`: color-mix(in oklab, var(--fg), var(--surface) 45%)
+- \`--border\`: color-mix(in oklab, var(--fg), var(--surface) 88%)
+- \`--accent\`: ${primary}
+- \`--font-display\`: ${fontDisplay}
+- \`--font-body\`: ${fontBody}
+
+**语义色**：success ${success} / warning ${warning} / danger ${danger}${secondary ? ` / secondary ${secondary}` : ''}
+
+**A2-derived（color-mix 公式）**：--accent-hover / --accent-active / --focus-ring / --elev-raised（公式见 token-derivation.md）
+
+**B-slot 别名**：--fg-2 → var(--fg) / --meta → var(--muted) / --border-soft → var(--border) / --surface-warm → var(--surface)
+
+## typography
+
+- 字阶：${typeScale}
+- 行高：正文 1.5 / 标题 1.2
+- 字重：400（正文）/ 500-600（标题）
+
+## spacing
+
+- 阶梯（4 基数）：${spacingScale.split('/').map((v, i) => `${v.trim()}px`).join(' / ')}
+
+## layout
+
+- 栅格 12 列 / 断点：sm 640 / md 1024 / lg 1440 / 容器 max-width 1200px
+
+### 容器骨架
+
+| 容器 | 类名 | 关键 CSS 声明 |
+|------|------|--------------|
+| 顶栏 | \`app-header\` | \`position: sticky; top: 0; height: 64px; z-index: 100\` |
+| 侧栏 | \`app-sider\` | \`width: 200px; flex: 0 0 200px; overflow-y: auto\` |
+| 主区 | \`app-main\` | \`flex: 1; min-width: 0; padding: 24px\` |
+
+> 上述类**不在**内置 \`template.html\` 中——按类清单契约在页面 \`<style>\` 内定义。
+> （v0.55.0 说明：内置骨架是营销向的 \`hero/cta/log\`，**缺 B 端容器类**，故这里必须给出物料。）
+
+### 页面范式
+
+**页面范式来源**：引用内置
+
+| 页面类型 | 骨架/容器组合 | 参考 |
+|---------|-------------|------|
+| 列表页 | app-header + app-sider + app-main > ds-table + stat | layouts.md 管理后台列表页 |
+| 表单页 | app-header + app-sider + app-main > field / input / textarea | layouts.md 表单页 |
+| 仪表盘 | app-header + app-sider + app-main > stat + grid-2-1 | layouts.md 仪表盘 |
+
+> 第二列的组合**全部取自** \`layouts.md\` 的类清单契约 + 上方容器骨架块（\`ds-table\` / \`stat\` /
+> \`field\` / \`input\` / \`textarea\` / \`grid-2-1\`）——不引入表外类名（v0.55.0 修正：原表用了
+> \`filterbar\` / \`table\` / \`form\` / \`grid\`，均不在类清单契约内，builder 照抄会得到无 CSS 支撑的类）。
+> 本表仅为**内置节奏的示意**；声明 \`引用内置\` 时 L4b 免检，实际节奏以内置 \`layouts.md\` 为准。
+
+## components
+
+| 组件 | 类型 | variants | sizes | states | 用途 | 禁止 |
+|------|------|----------|-------|--------|------|------|
+${CONTRACT_ROWS.join('\n')}
+
+## motion
+
+- duration 150–250ms / easing ease-out（\`cubic-bezier(0.2, 0, 0, 1)\`）
+
+## voice
+
+- 语气：${category} 语境的简洁专业表达——具体文案要求由项目 PRD 补充。
+
+## brand
+
+- 品牌主色：${primary}（accent 用法：主 CTA / 链接 / 选中态）
+
+## anti-patterns
+
+1. 禁止内联样式漂移
+2. 禁止非 token 颜色
+3. ${category} 语境：不得引入与来源风格冲突的装饰效果
+
+## palette
+
+- neutral / primary / success / warning / danger 各 50–900 阶梯（primary 以 ${primary} 为 500 锚点，公式见 token-derivation.md）
+
+## principles
+
+1. 一致性优先于局部创意——同类信息用同一呈现
+2. 清晰优于装饰——信息层级先于视觉效果
+3. 可访问性默认开启——所有交互元素满足 WCAG AA
+
+## governance
+
+- contract: legacy
+- version: 0.1.0
+- 负责人: {项目角色}
+- 弃用策略: 组件弃用需在 changelog 记录 + 保留 1 个迭代周期
+- changelog: 见文末"变更履历"段
+
+## 变更履历
+
+| 时间 | 变更内容 | 来源 |
+|------|---------|------|
+| ${new Date().toISOString().slice(0, 10)} | 从 open-design \`${id}\` 转换生成 | design-system-import.mjs |
+`;
+
+const outPath = outArg ? resolve(outArg) : resolve(`.team-flow/design-system/base.md`);
+mkdirSync(dirname(outPath), { recursive: true });
+writeFileSync(outPath, base, 'utf-8');
+
+console.log(`base.md 已生成：${outPath}`);
+console.log(profileArg
+  ? `  来源：内置 profile ${profileArg}（Ant Design v5 seed token，MIT + team-flow 自有规范）`
+  : `  来源：open-design ${id}（${category}）`);
+console.log(`  accent=${primary} / surface=${surface} / text=${text}`);
+console.log(`  组件契约表：20 类基线（待审阅调整）`);
+console.log('  contract: legacy（导入类默认 —— 用户裁决达标后经 iterate 升 v1）');
+// 提示中的脚本路径用**本脚本所在插件目录**解析（绝对路径，可直接复制执行）——
+// 裸 `node scripts/...` 在插件零拷贝安装下不解析（v0.54.0 P4 根因）。
+const pluginDir = dirname(dirname(fileURLToPath(import.meta.url)));
+console.log('\n下一步（由 design-system skill 的 Step 5 评审 → Step 6 落盘承接）：');
+console.log(`  1) node ${join(pluginDir, 'scripts', 'gen-primer.mjs')} ${outPath}     # 生成 primer（组件白名单 + digest，缺失会阻断 prototype Step 0）`);
+console.log(`  2) node ${join(pluginDir, 'scripts', 'guard', 'design-token-guard.mjs')} ${dirname(outPath)}  # 硬校验 + 六层审计`);