@tfdesign/b-end 1.0.4

package/scripts/check-tfds-contract.mjs

@@ -0,0 +1,334 @@
+/**
+ * TFDS 规范契约轻量自检（只读，不改写用户任何配置文件）
+ *
+ * 在对方项目根目录执行：
+ *   node node_modules/@tfdesign/b-end/scripts/check-tfds-contract.mjs
+ *
+ * 目标：在未接入 @tfds/eslint-config 时，提供一层“最低成本”的漂移提示。
+ * 注意：这是启发式扫描，不等价于 ESLint 的完整硬门禁。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const projectRoot = path.resolve(process.env.TFDS_PROJECT_ROOT || process.cwd());
+
+/** 只扫描常见业务源码目录 */
+const SCAN_DIR_CANDIDATES = ['src', 'app', 'pages', 'components'];
+const SCAN_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.css']);
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function read(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function walk(dir, out) {
+  const ents = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of ents) {
+    if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (e.isFile()) out.push(p);
+  }
+}
+
+function rel(p) {
+  return path.relative(projectRoot, p) || p;
+}
+
+function main() {
+  const issues = [];
+  const ok = [];
+
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!exists(pkgPath)) {
+    issues.push(`未找到 package.json（当前检测根目录：${projectRoot}）。请在对方项目根目录执行本脚本。`);
+    print(issues, ok);
+    process.exit(1);
+  }
+
+  // 只读提示：若已接入 eslint-config，可少依赖本脚本
+  const depsRaw = read(pkgPath);
+  if (depsRaw) {
+    try {
+      const pkg = JSON.parse(depsRaw);
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (deps['@tfds/eslint-config']) ok.push('检测到 @tfds/eslint-config（推荐作为 CI 硬门禁）');
+    } catch {
+      // ignore
+    }
+  }
+
+  const scanRoots = SCAN_DIR_CANDIDATES.map((d) => path.join(projectRoot, d)).filter(exists);
+  if (scanRoots.length === 0) {
+    issues.push(`未找到可扫描的源码目录（候选：${SCAN_DIR_CANDIDATES.join(', ')}）。跳过规则扫描。`);
+    print(issues, ok);
+    process.exit(0);
+  }
+  ok.push(`将扫描：${scanRoots.map(rel).join(', ')}`);
+
+  /** @type {string[]} */
+  const files = [];
+  for (const r of scanRoots) walk(r, files);
+  const targets = files.filter((f) => SCAN_EXTS.has(path.extname(f)));
+  if (targets.length === 0) {
+    issues.push('未找到可扫描的 .js/.jsx/.ts/.tsx/.css 文件。');
+    print(issues, ok);
+    process.exit(0);
+  }
+
+  // Heuristics:
+  // - Tailwind 任意值：[...]（强烈建议禁止）
+  // - CSS / JSX 内硬编码 hex：#fff / #ffffff（建议走 token/theme）
+  // - 明显的 spacing 任意值：p-[..] / m-[..] / gap-[..]
+  // - 伪 FormTitle：原生 h2/h3/h4 或自绘左竖条标题（应改用 <FormTitle />）
+  const reArbitrary = /\[[^\]]+\]/g;
+  const reHex = /#[0-9a-fA-F]{3,8}\b/g;
+  const reArbSpacing = /\b(?:p|px|py|pt|pr|pb|pl|m|mx|my|mt|mr|mb|ml|gap|gap-x|gap-y)-\[[^\]]+\]\b/g;
+  const reNativeHeading = /<h[2-4]\b[^>]*>/g;
+  const reClassAttr = /\b(?:className|class)\s*=\s*["']([^"']+)["']/g;
+
+  const hit = new Map(); // file -> collected heuristic hits
+
+  function collectPseudoTitleHits(text) {
+    const hits = [];
+    hits.push(...(text.match(reNativeHeading) || []).slice(0, 6));
+
+    for (const m of text.matchAll(reClassAttr)) {
+      const cls = m[1];
+      const hasTinyRailWidth = /\bw-1\b|\bw-\[(?:3|4|6)px\]/.test(cls);
+      const hasRailHeight = /\bh-(?:3\.5|4|5|6|8)\b|\bh-\[(?:14|16|18|20|24|32)px\]/.test(cls);
+      const hasAccentBg = /\bbg-(?:brand|teal|cyan|emerald|green|primary|sky|blue)-/.test(cls);
+      const hasLeftBorderTitle = /\bborder-l(?:-\d+)?\b/.test(cls) && /\b(?:font-medium|font-semibold|text-base|text-lg|text-xl)\b/.test(cls);
+      if ((hasTinyRailWidth && hasRailHeight && hasAccentBg) || hasLeftBorderTitle) {
+        hits.push(`className="${cls}"`);
+      }
+      if (hits.length >= 10) break;
+    }
+    return hits.slice(0, 10);
+  }
+
+  function collectAiEntryWhiteWrapperHits(text) {
+    const looksLikeAiEntry =
+      /<ChatInput\b/.test(text) &&
+      /<Card\b/.test(text) &&
+      /(今天想做什么|从模板|模板广场|模板中心|搜索助手|助手广场|Agent|AI\s*入口|AI\s*首页|AI\s*工作台|智能分析入口)/i.test(text);
+
+    if (!looksLikeAiEntry) return [];
+
+    const hits = [];
+    const classWrapper = /<(?:main|section|div)\b[^>]*(?:className|class)\s*=\s*["'][^"']*(?:bg-surface|bg-white)[^"']*(?:rounded|rounded-)[^"']*["'][^>]*>/gi;
+    const classWrapperReverse = /<(?:main|section|div)\b[^>]*(?:className|class)\s*=\s*["'][^"']*(?:rounded|rounded-)[^"']*(?:bg-surface|bg-white)[^"']*["'][^>]*>/gi;
+    const styleWrapper = /<(?:main|section|div)\b[^>]*style=\{\{[^}]*background\s*:\s*['"`](?:var\(--color-surface\)|#fff(?:fff)?|white)[^}]*\}\}[^>]*>/gi;
+
+    hits.push(...(text.match(classWrapper) || []).slice(0, 4));
+    hits.push(...(text.match(classWrapperReverse) || []).slice(0, 4));
+    hits.push(...(text.match(styleWrapper) || []).slice(0, 4));
+    return [...new Set(hits)].slice(0, 8);
+  }
+
+  function collectMainSpacingHits(text) {
+    const hits = [];
+    const reMainSpacing = /<main\b[^>]*(?:className|class)\s*=\s*["'][^"']*\b(?:p-2|p-6|p-8|px-6|px-8|py-6|py-8)\b[^"']*["'][^>]*>/gi;
+    hits.push(...(text.match(reMainSpacing) || []).slice(0, 8));
+    return hits;
+  }
+
+  function collectCenteredShellHits(text) {
+    const hits = [];
+    const reCentered =
+      /<(?:main|section|div)\b[^>]*(?:className|class)\s*=\s*["'][^"']*\bmax-w-(?:screen|[0-9a-zA-Z_-]+)[^"']*\bmx-auto\b[^"']*["'][^>]*>/gi;
+    const reCenteredReverse =
+      /<(?:main|section|div)\b[^>]*(?:className|class)\s*=\s*["'][^"']*\bmx-auto\b[^"']*\bmax-w-(?:screen|[0-9a-zA-Z_-]+)[^"']*["'][^>]*>/gi;
+    hits.push(...(text.match(reCentered) || []).slice(0, 4));
+    hits.push(...(text.match(reCenteredReverse) || []).slice(0, 4));
+    return [...new Set(hits)].slice(0, 8);
+  }
+
+  function collectSurfaceChromeHits(text) {
+    const hits = [];
+    const classChrome =
+      /<(?:main|section|div|Card)\b[^>]*(?:className|class)\s*=\s*["'][^"']*(?:bg-surface|bg-white)[^"']*\b(?:border|ring|shadow)\b[^"']*["'][^>]*>/gi;
+    const styleChrome =
+      /<(?:main|section|div)\b[^>]*style=\{\{[^}]*background\s*:\s*['"`](?:var\(--color-surface\)|white|#fff(?:fff)?)[^}]*\b(?:border|borderColor|boxShadow)\b[^}]*\}\}[^>]*>/gi;
+    hits.push(...(text.match(classChrome) || []).slice(0, 4));
+    hits.push(...(text.match(styleChrome) || []).slice(0, 4));
+    return [...new Set(hits)].slice(0, 8);
+  }
+
+  function collectAiEntryCardColorHits(text) {
+    const looksLikeAiEntry =
+      /<ChatInput\b/.test(text) &&
+      /<Card\b/.test(text) &&
+      /(今天想做什么|从模板|模板广场|模板中心|搜索助手|助手广场|Agent|AI\s*入口|AI\s*首页|AI\s*工作台|智能分析入口)/i.test(text);
+    if (!looksLikeAiEntry) return [];
+    return (text.match(/<Card\b[^>]*\bcolor\s*=\s*["']grey["'][^>]*>/gi) || []).slice(0, 8);
+  }
+
+  function collectTabsSizeDriftHits(text) {
+    const looksLikeContentTabs =
+      /(筛选|filter|FilterBar|模板|卡片|Card|panel|Panel|Playground|工作区|白卡|section|Section)/i.test(text);
+    if (!looksLikeContentTabs) return [];
+    const hits = [];
+    const reTabsLarge = /<Tabs\b[^>]*\bsize\s*=\s*["'](?:md|lg)["'][^>]*>/gi;
+    for (const m of text.matchAll(reTabsLarge)) {
+      const before = text.slice(Math.max(0, m.index - 360), m.index);
+      const match = m[0];
+      const allowedTopNavContext = /(TopBar|Header|PAGE_TABS|页面级|顶导|一级导航|顶部\s*header)/i.test(before);
+      if (allowedTopNavContext) continue;
+      hits.push(match);
+      if (hits.length >= 8) break;
+    }
+    return hits;
+  }
+
+  function collectFilterFullWidthHits(text) {
+    const looksLikeFilterBar = /(function|const)\s+\w*Filter\w*|筛选栏|FilterBar|filter bar/i.test(text);
+    if (!looksLikeFilterBar) return [];
+    const hits = [];
+    const inputFullWidth = /<Input\b[^>]*(?:className|class)\s*=\s*["'][^"']*\bw-full\b[^"']*["'][^>]*>/gi;
+    const inputStyleFull = /<Input\b[^>]*style=\{\{[^}]*(?:width\s*:\s*['"`]100%|flex\s*:\s*['"`]1)[^}]*\}\}[^>]*>/gi;
+    hits.push(...(text.match(inputFullWidth) || []).slice(0, 4));
+    hits.push(...(text.match(inputStyleFull) || []).slice(0, 4));
+    return [...new Set(hits)].slice(0, 8);
+  }
+
+  function collectRemoteAvatarHits(text) {
+    const hits = [];
+    const componentRemote =
+      /<(?:Avatar|ChatBubble|NavBar|ChatMessage)\b[^>]*(?:src|avatarSrc)\s*=\s*["']https?:\/\/[^"']+["'][^>]*>/gi;
+    const objectRemote =
+      /\b(?:avatarSrc|avatarUrl|avatarURL|profileImage|profilePic)\s*:\s*["']https?:\/\/[^"']+["']/gi;
+    const roundedImgRemote =
+      /<img\b(?=[^>]*src\s*=\s*["']https?:\/\/[^"']+["'])(?=[^>]*(?:rounded-full|avatar|头像))[^>]*>/gi;
+
+    hits.push(...(text.match(componentRemote) || []).slice(0, 4));
+    hits.push(...(text.match(objectRemote) || []).slice(0, 4));
+    hits.push(...(text.match(roundedImgRemote) || []).slice(0, 4));
+    return [...new Set(hits)].slice(0, 8);
+  }
+
+  for (const f of targets) {
+    const t = read(f);
+    if (!t) continue;
+    const arbitrary = (t.match(reArbitrary) || []).slice(0, 10);
+    const hex = (t.match(reHex) || []).slice(0, 10);
+    const arbSpacing = (t.match(reArbSpacing) || []).slice(0, 10);
+    const pseudoTitle = collectPseudoTitleHits(t);
+    const aiEntryWhiteWrapper = collectAiEntryWhiteWrapperHits(t);
+    const mainSpacing = collectMainSpacingHits(t);
+    const centeredShell = collectCenteredShellHits(t);
+    const surfaceChrome = collectSurfaceChromeHits(t);
+    const aiEntryCardColor = collectAiEntryCardColorHits(t);
+    const tabsSizeDrift = collectTabsSizeDriftHits(t);
+    const filterFullWidth = collectFilterFullWidthHits(t);
+    const remoteAvatar = collectRemoteAvatarHits(t);
+    if (
+      arbitrary.length ||
+      hex.length ||
+      arbSpacing.length ||
+      pseudoTitle.length ||
+      aiEntryWhiteWrapper.length ||
+      mainSpacing.length ||
+      centeredShell.length ||
+      surfaceChrome.length ||
+      aiEntryCardColor.length ||
+      tabsSizeDrift.length ||
+      filterFullWidth.length ||
+      remoteAvatar.length
+    ) {
+      hit.set(f, {
+        arbitrary,
+        hex,
+        arbSpacing,
+        pseudoTitle,
+        aiEntryWhiteWrapper,
+        mainSpacing,
+        centeredShell,
+        surfaceChrome,
+        aiEntryCardColor,
+        tabsSizeDrift,
+        filterFullWidth,
+        remoteAvatar,
+      });
+    }
+  }
+
+  if (hit.size === 0) {
+    ok.push('未发现明显的 Tailwind 任意值 / hex 硬编码（启发式）');
+    print(issues, ok);
+    process.exit(0);
+  }
+
+  for (const [f, v] of hit.entries()) {
+    if (v.arbSpacing.length) {
+      issues.push(`[${rel(f)}] 发现 spacing 任意值（示例）：${v.arbSpacing.join(', ')}`);
+    }
+    // 注意：arbitrary 会包含很多场景（如 grid-cols-[...]），这里不全禁，但先提示
+    if (v.arbitrary.length) {
+      issues.push(`[${rel(f)}] 发现 Tailwind 任意值（示例）：${v.arbitrary.join(', ')}`);
+    }
+    if (v.hex.length) {
+      issues.push(`[${rel(f)}] 发现 hex 硬编码颜色（示例）：${v.hex.join(', ')}`);
+    }
+    if (v.pseudoTitle.length) {
+      issues.push(`[${rel(f)}] 发现疑似手写标题 / 伪 FormTitle（示例）：${v.pseudoTitle.join(', ')}。白卡、面板、卡片、section 标题必须改用 <FormTitle />。`);
+    }
+    if (v.aiEntryWhiteWrapper.length) {
+      issues.push(`[${rel(f)}] AI 入口页疑似被大白卡包住（示例）：${v.aiEntryWhiteWrapper.join(', ')}。ChatHomePagePattern 应直接坐浅灰底，Hero / ChatInput / Tabs / 模板 Card 网格外层不要包 bg-surface / 白色圆角大容器；模板卡自身用 <Card color="white" />。`);
+    }
+    if (v.mainSpacing.length) {
+      issues.push(`[${rel(f)}] main 外框间距疑似不符合 TFDS（示例）：${v.mainSpacing.join(', ')}。通用白卡工作区 main 应使用 p-4（16px），禁止 p-2 / p-6 / p-8 / px-6 / px-8。`);
+    }
+    if (v.centeredShell.length) {
+      issues.push(`[${rel(f)}] 主工作区疑似被 max-w + mx-auto 居中收窄（示例）：${v.centeredShell.join(', ')}。TFDS B 端页应撑满浏览器可用宽度，禁止在 main/主内容外层套居中容器。`);
+    }
+    if (v.surfaceChrome.length) {
+      issues.push(`[${rel(f)}] 白色工作卡疑似带外层描边/阴影（示例）：${v.surfaceChrome.join(', ')}。最外层 WorkSurface 只允许纯白底 + 12px 圆角，不加 border/ring/shadow；内部控件描边可保留。`);
+    }
+    if (v.aiEntryCardColor.length) {
+      issues.push(`[${rel(f)}] AI 入口页模板卡疑似使用 Card color="grey"（示例）：${v.aiEntryCardColor.join(', ')}。ChatHome 父级是浅灰底，模板卡必须用 <Card color="white" />。`);
+    }
+    if (v.tabsSizeDrift.length) {
+      issues.push(`[${rel(f)}] 内容区 Tabs 疑似使用 md/lg 尺寸（示例）：${v.tabsSizeDrift.join(', ')}。白卡内、筛选维度、卡片内、Playground 面板内 Tabs 默认 size="sm"；md/lg 只用于平台顶部一级导航。`);
+    }
+    if (v.filterFullWidth.length) {
+      issues.push(`[${rel(f)}] 筛选栏 Input 疑似误用全宽（示例）：${v.filterFullWidth.join(', ')}。FilterBar 搜索框默认约 240px，枚举/状态/时间控件 160-200px；白卡正文单列字段才默认 w-full。`);
+    }
+    if (v.remoteAvatar.length) {
+      issues.push(`[${rel(f)}] 头像疑似使用随机外链或手写 img（示例）：${v.remoteAvatar.join(', ')}。TFDS 人像类头像默认应使用包内本地成员头像素材；Avatar/ChatBubble/NavBar/Table avatar/avatarText 缺省会自动取本地成员头像，只有业务真实接口返回头像 URL 时才传远程 src。`);
+    }
+  }
+
+  issues.push('建议：接入 @tfds/eslint-config 并在 CI 执行 npx eslint . 作为硬门禁（比本脚本更准确）。');
+  print(issues, ok);
+  process.exit(1);
+}
+
+function print(issues, ok) {
+  // eslint-disable-next-line no-console
+  console.log('\n[tfds-contract-check] 项目根:', projectRoot);
+  // eslint-disable-next-line no-console
+  console.log('\n── 已通过 ──');
+  if (ok.length === 0) console.log('（无）');
+  else ok.forEach((l) => console.log('✓', l));
+  // eslint-disable-next-line no-console
+  console.log('\n── 待处理 / 提示 ──');
+  if (issues.length === 0) console.log('（无）— 未发现明显漂移信号。');
+  else issues.forEach((l) => console.log('!', l));
+  // eslint-disable-next-line no-console
+  console.log('');
+}
+
+main();

package/scripts/check-tfds-integration.mjs

@@ -0,0 +1,263 @@
+/**
+ * TFDS 集成自检（只读，不改写用户任何配置文件）
+ *
+ * 在对方项目根目录执行：
+ *   node node_modules/@tfdesign/b-end/scripts/check-tfds-integration.mjs
+ *
+ * 或通过环境变量指定根目录：
+ *   TFDS_PROJECT_ROOT=/path/to/app node .../check-tfds-integration.mjs
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const projectRoot = path.resolve(process.env.TFDS_PROJECT_ROOT || process.cwd());
+const codexHome = process.env.CODEX_HOME
+  ? path.resolve(process.env.CODEX_HOME)
+  : path.join(os.homedir(), '.codex');
+
+function read(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const REQUIRED_TFDS_SKILL_FILES = [
+  'SKILL.md',
+  'DESIGN_PRINCIPLES.md',
+  'PAGE_ARCHETYPES.md',
+  'LAYOUT_RECIPES.md',
+  'components.summary.json',
+  'components.index.json',
+  'LAYOUT_RULES.md',
+  'GLOBAL_DESIGN_RULES.md',
+  'CHECKLIST.md',
+  'COMMON_FAILURES.md',
+];
+
+function displayPath(p) {
+  const home = os.homedir();
+  if (p === home) return '~';
+  if (p.startsWith(home + path.sep)) return path.join('~', path.relative(home, p));
+  const rel = path.relative(projectRoot, p);
+  return rel && !rel.startsWith('..') ? rel : p;
+}
+
+/** 常见入口样式候选（存在则检查内容） */
+function candidateCssFiles() {
+  const rels = [
+    'src/index.css',
+    'src/main.css',
+    'src/styles.css',
+    'src/global.css',
+    'app/globals.css',
+    'styles/globals.css',
+    'index.css',
+  ];
+  return rels.map((r) => path.join(projectRoot, r)).filter(exists);
+}
+
+function candidateConfigFiles() {
+  const names = [
+    'vite.config.js',
+    'vite.config.mjs',
+    'vite.config.ts',
+    'vite.config.mts',
+    'tailwind.config.js',
+    'tailwind.config.mjs',
+    'tailwind.config.ts',
+  ];
+  return names.map((n) => path.join(projectRoot, n)).filter(exists);
+}
+
+function hasThemeImport(cssText) {
+  return /@tfdesign\/b-end\/theme\.css/.test(cssText);
+}
+
+function hasTailwindImport(cssText) {
+  return /@import\s+["']tailwindcss["']/.test(cssText) || /@import\s+['"]tailwindcss['"]/.test(cssText);
+}
+
+function hasSourceScanForPackage(cssText) {
+  return /@source[^;]*@tfdesign\/b-end|@source[^;]*node_modules\/@tfdesign\/b-end/i.test(cssText);
+}
+
+function hasContentScanInConfigs(text) {
+  return /node_modules\/@tfdesign\/b-end|@tfdesign\/b-end\/\*\*/.test(text);
+}
+
+function main() {
+  const issues = [];
+  const ok = [];
+
+  const pkgPath = path.join(projectRoot, 'package.json');
+  const pkgRaw = read(pkgPath);
+  if (!pkgRaw) {
+    issues.push(`未找到 package.json（当前检测根目录：${projectRoot}）。请在对方项目根目录执行本脚本。`);
+    printReport(issues, ok);
+    process.exit(1);
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(pkgRaw);
+  } catch {
+    issues.push('package.json 无法解析为 JSON');
+    printReport(issues, ok);
+    process.exit(1);
+  }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+  if (!deps['@tfdesign/b-end']) {
+    issues.push('package.json 中未声明依赖 @tfdesign/b-end（dependencies / devDependencies / peerDependencies）。');
+  } else {
+    ok.push('已声明依赖 @tfdesign/b-end');
+  }
+
+  if (!exists(path.join(projectRoot, 'node_modules', '@tfdesign', 'b-end'))) {
+    issues.push('未找到 node_modules/@tfdesign/b-end/。请先在该目录执行 npm install。');
+  } else {
+    ok.push('node_modules/@tfdesign/b-end 目录存在');
+  }
+
+  const cssFiles = candidateCssFiles();
+  let themeOk = false;
+  let tailwindOk = false;
+  let sourceOk = false;
+
+  if (cssFiles.length === 0) {
+    issues.push('未在常见路径找到入口 CSS（如 src/index.css）。请手动确认已 @import "@tfdesign/b-end/theme.css"。可重新执行 npm i 触发 postinstall 自动补丁。');
+  } else {
+    ok.push(`将检查以下样式文件：${cssFiles.map((f) => path.relative(projectRoot, f)).join(', ')}`);
+    for (const f of cssFiles) {
+      const t = read(f);
+      if (!t) continue;
+      if (hasThemeImport(t)) themeOk = true;
+      if (hasTailwindImport(t)) tailwindOk = true;
+      if (hasSourceScanForPackage(t)) sourceOk = true;
+    }
+    if (!themeOk) issues.push('入口 CSS 中未发现 @import "@tfdesign/b-end/theme.css"（须在 @import "tailwindcss" 之后）。可重新执行 npm i 触发 postinstall 自动补丁，或手动追加。');
+    else ok.push('已检测到 theme.css 引入');
+
+    if (!tailwindOk) issues.push('入口 CSS 中未发现 @import "tailwindcss"（请确认 Tailwind v4 入口写法与官方一致）。');
+    else ok.push('已检测到 tailwindcss 引入');
+
+    if (sourceOk) ok.push('已检测到 @source 扫描 node_modules/@tfdesign/b-end');
+  }
+
+  let configScanHint = false;
+  for (const cf of candidateConfigFiles()) {
+    const t = read(cf);
+    if (t && hasContentScanInConfigs(t)) {
+      configScanHint = true;
+      ok.push(`在 ${path.relative(projectRoot, cf)} 中发现对 @tfdesign/b-end 的 content/扫描配置线索`);
+      break;
+    }
+  }
+
+  if (cssFiles.length > 0 && !sourceOk && !configScanHint) {
+    issues.push(
+      '未检测到 Tailwind 对 @tfdesign/b-end 的扫描：入口 CSS 缺少 @source … @tfdesign/b-end，且配置文件中无 content 线索。可重新执行 npm i 触发 postinstall 自动补丁，详见 README.md → "TL;DR 快速开始"。',
+    );
+  } else if (cssFiles.length > 0 && !sourceOk && configScanHint) {
+    ok.push('未使用 @source，但配置文件中出现对 @tfdesign/b-end 的扫描路径（方式 B），可接受');
+  }
+
+  function checkSkillDir(label, dir, options = {}) {
+    const { required = false, whenParentExists = null, successSuffix = '' } = options;
+    const parentExists = whenParentExists ? exists(whenParentExists) : false;
+
+    if (!exists(dir)) {
+      if (required || parentExists) {
+        issues.push(`未找到 ${label} Skill：${displayPath(dir)}。请执行 npm i 触发 postinstall 自动复制，或从包内 skills/tfds 目录手动复制。`);
+      }
+      return false;
+    }
+
+    const missing = REQUIRED_TFDS_SKILL_FILES.filter((file) => !exists(path.join(dir, file)));
+    if (missing.length > 0) {
+      issues.push(
+        `${label} Skill 目录存在但不完整：${displayPath(dir)} 缺少 ${missing.join(', ')}。这通常是旧版 Skill 残留；请删除该目录后重新执行 npm i，或重新复制 node_modules/@tfdesign/b-end/skills/tfds/。`,
+      );
+      return false;
+    }
+
+    ok.push(`已安装 ${label} Skill：${displayPath(dir)}${successSuffix}`);
+    return true;
+  }
+
+  checkSkillDir('Cursor', path.join(projectRoot, '.cursor', 'skills', 'tfds'), {
+    required: true,
+    successSuffix: '（唤起：/tfds）',
+  });
+
+  checkSkillDir('Claude Code', path.join(projectRoot, '.claude', 'skills', 'tfds'), {
+    whenParentExists: path.join(projectRoot, '.claude'),
+    successSuffix: '（唤起：/tfds）',
+  });
+
+  checkSkillDir('Codex 项目内参考', path.join(projectRoot, '.codex', 'skills', 'tfds'), {
+    whenParentExists: path.join(projectRoot, '.codex'),
+  });
+
+  checkSkillDir('Codex 用户级', path.join(codexHome, 'skills', 'tfds'), {
+    required: true,
+    successSuffix: '（新开/重启 Codex 后 /tfds）',
+  });
+
+  checkSkillDir('Agents', path.join(projectRoot, '.agents', 'skills', 'tfds'), {
+    whenParentExists: path.join(projectRoot, '.agents'),
+    successSuffix: '（通用 agent 兜底）',
+  });
+
+  // Trae：故意不自动写入 .trae/rules/（避免 always-on 污染）
+  if (exists(path.join(projectRoot, '.trae'))) {
+    ok.push('Trae 用户提示：把 skills/tfds/ 加入 Trae 项目知识库（命名 tfds），之后 @tfds 引用。本工具不会写入 .trae/rules/。');
+  }
+
+  printReport(issues, ok);
+
+  const critical = issues.some(
+    (m) =>
+      m.includes('未声明依赖') ||
+      m.includes('未找到 node_modules/@tfdesign') ||
+      m.includes('未发现 @import "@tfdesign/b-end/theme.css"'),
+  );
+  process.exit(critical ? 1 : 0);
+}
+
+function printReport(issues, ok) {
+  // eslint-disable-next-line no-console
+  console.log('\n[tfds-integration-check] 项目根:', projectRoot);
+  // eslint-disable-next-line no-console
+  console.log('\n── 已通过 ──');
+  if (ok.length === 0) // eslint-disable-next-line no-console
+    console.log('（无）');
+  else ok.forEach((l) => console.log('✓', l));
+  // eslint-disable-next-line no-console
+  console.log('\n── 待处理 / 提示 ──');
+  if (issues.length === 0) // eslint-disable-next-line no-console
+    console.log('（无）— 基础集成项已齐。');
+  else issues.forEach((l) => console.log('!', l));
+  // eslint-disable-next-line no-console
+  console.log('\n详细步骤见：node_modules/@tfdesign/b-end/README.md → "TL;DR 快速开始"');
+  // eslint-disable-next-line no-console
+  console.log('');
+}
+
+main();