@qilitt-mickey/vue3-temp-skill 1.2.1 → 1.2.2

package/README.md

@@ -23,16 +23,31 @@ Vue 3 企业级中后台项目开发技能包。两条链路：
 
 ```text
 输入：<项目根>/.design/visual-contract-<场景>-<页型>.json
-  → 读契约（唯一输入，只读一次）
-  → 选 adapter（按 package.json 判定所用组件库）
-  → 生成 ui-tokens.css（:root 变量）
-  → 生成 ui-roles.css（.role-* 规则）
-  → 生成 ui-layout.css（.ui-page 网格）
-  → 挂载 + 目视对照
+  → ① 落地自检（六项：契约存在/完整/CSS生成/CSS引入/角色挂载/布局挂载）
+  → ② 读契约（唯一输入，只读一次）
+  → ③ 选 adapter（按 package.json 判定所用组件库）
+  → ④ 生成 ui-tokens.css（:root 变量）
+  → ⑤ 生成 ui-roles.css（.role-* 规则）
+  → ⑥ 生成 ui-layout.css（.ui-page 网格）
+  → ⑦ 挂载（.ui-page / .ui-region-* / .role-*）
+  → ⑧ 重跑自检确认六项全过 → 目视对照
 ```
 
 **AI 在链路二的工作是翻译，不是判断。** 契约写什么就生成什么——落点层级已由 `host[]` / `inner[]` 两个数组物理二分，落地端不推断属性该落哪一层。
 
+**落地自检是交付前置条件**（`npm run check:landing`）：
+
+| 检查项 | 断点含义 |
+|---|---|
+| `contract-found` | `.design/` 下没有契约 → 设计侧没落盘 |
+| `contract-valid` | 契约字段缺失 |
+| `css-generated` | 三份 CSS 未生成 |
+| `css-imported` | **生成了但没被 import** → 浏览器不加载 |
+| `roles-mounted` | **CSS 有规则但模板没挂类** → 死样式，只有个别角色生效 |
+| `layout-mounted` | 没挂 `.ui-page` → 骨架仍是项目原样 |
+
+**任何一项断掉都会表现为「CSS 写了但页面没变化」。先跑自检定位断点，不要目视猜。**
+
 ## 视觉契约的核心机制
 
 | 机制 | 说明 |
@@ -84,6 +99,7 @@ npx @qilitt-mickey/vue3-temp-skill@latest update
 | 命令 | 职责 |
 |------|------|
 | `node bin/cli.js install <target>` | 安装器统一入口：`install` / `update` / `uninstall` / `list` |
+| `npm run check:landing` | **契约落地自检**（六项）：判断「契约 → 样式 → 挂载」断在哪一环 |
 | `python scripts/match.py "需求" --json` | 能力路由：按需求返回应加载的 reference 清单 |
 | `npm run release`（`:minor` / `:major`） | 结构检查 → 升版本 → 提交 → 发布 npm |
 

package/SKILL.md

@@ -30,7 +30,14 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 
 1. **项目探查**：读取目标项目的 `package.json`、路由、页面、`Re*` 组件、Hooks、API 和样式；以源码事实为准。
 2. **能力路由**：运行 `scripts/match.py "需求" --json`，**仅**按输出中的 `load_files` 阅读 reference；禁止自行展开全部 `references/`。无 Python 时按下方能力组表手动匹配。
-3. **视觉契约落地**：输入是设计侧的视觉契约 JSON 时，走 `design-apply` 协议——照抄生成三份样式文件（令牌 / 角色 / 布局），见 §3 输入分流。
+3. **视觉契约落地**：输入是设计侧的视觉契约 JSON 时，走 `design-apply` 协议——**先跑落地自检，再照抄生成三份样式文件**，见 §3 输入分流。
+
+```bash
+node <技能>/scripts/check-landing.mjs --project <项目根>
+```
+
+**六项全过（exit 0）是交付前置条件**：契约存在 → 契约完整 → 三份 CSS 生成 → 被 import → 角色类挂载 100% → 布局类挂载。
+**任何一项断掉，都会出现「CSS 写了但页面没变化」——先修断点，不要目视猜。**
 
 ## 能力组路由
 
@@ -49,7 +56,7 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 | `files-and-editors` | 附件、预览、下载、富文本、二维码 | `file-management.md`、`download-export.md`、`rich-text.md`、`qrcode-barcode.md` |
 | `realtime-and-mobile` | WebSocket、移动端、微信、验证码、动效 | 对应专项 reference |
 | `data-compare` | 编辑页变更对比和汇总 | `data-compare.md` |
-| `design-apply` | **视觉契约落地**：读契约 → 选 adapter → 生成三份 CSS → 目视对照。**主入口 `design-apply.md`，adapter 见 `adapters/`（做到哪一步读哪一份）** | `design-apply.md`、`adapters/`、`mapping/` |
+| `design-apply` | **视觉契约落地**：落地自检 → 读契约 → 选 adapter → 生成三份 CSS → 挂载 → 覆盖验证。**主入口 `design-apply.md`，adapter 见 `adapters/`（做到哪一步读哪一份）** | `design-apply.md`、`adapters/`、`mapping/`、`scripts/check-landing.mjs` |
 
 ## 工作流
 
@@ -86,10 +93,12 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 
 使用者默认**不懂设计也不懂代码**，交互遵守四条：
 
-1. **全自动默认**：识别为视觉契约后**直接开始执行全流程**（读契约 → 选 adapter → 生成三份 CSS → 挂载 → 目视对照），不等用户逐步确认。唯一停顿点是契约文件缺失或格式不符——此时用大白话报告并给选择题。
-2. **术语不对用户出现**：对用户不说"契约 / 角色 / 令牌 / adapter / 区域"——说"设计文件 / 样式规则 / 全局变量 / 组件适配 / 页面区域"。这些词只出现在内部文档与交付说明里。
-3. **无文件时的引导**：用户说"全系统改成 XX 风格"但没给设计文件 → 提示一句话："请先在设计助手（project-ui-design 技能）里说『我要 XX 风格的全系统设计』拿到设计文件，再回来发给我"。如果本机同时装有设计技能，可直接引导用户回到设计会话完成设计，再回本项目落地。
-4. **交付话术**：完成后用大白话总结（改了哪些页面 / 哪些地方变了 / 怎么验收），不输出施工坐标等技术细节；验收引导统一为"运行 `pnpm dev` 打开页面对照看效果，哪里不满意直接说"。
+1. **全自动默认**：识别为视觉契约后**直接开始执行全流程**（落地自检 → 读契约 → 选 adapter → 生成三份 CSS → 挂载 → 验证），不等用户逐步确认。
+2. **契约缺失 = 硬阻断，不允许"边猜边改"**：`check-landing.mjs` 报 `contract-found FAIL` 时**必须停下**，用大白话报告「还没拿到设计文件」并给出下一步。**严禁在契约缺失的情况下凭理解直接改项目样式**——那是旧体系的失败模式：改了一堆 CSS 却没有任何东西对应，最后只有个别地方碰巧变了。
+3. **契约存在但 `roles-mounted` 未 100% = 不算完成**：角色类没挂满，页面上就只会有个别角色生效（常见症状：只有菜单颜色变了）。必须按 adapter 的「角色类挂载方式」补齐后重跑自检。
+4. **术语不对用户出现**：对用户不说"契约 / 角色 / 令牌 / adapter / 区域 / 自检"——说"设计文件 / 样式规则 / 全局变量 / 组件适配 / 页面区域 / 检查"。这些词只出现在内部文档与交付说明里。
+5. **无文件时的引导**：用户说"全系统改成 XX 风格"但没给设计文件 → 提示一句话："请先在设计助手（project-ui-design 技能）里说『我要 XX 风格的全系统设计』拿到设计文件，再回来发给我"。如果本机同时装有设计技能，可直接引导用户回到设计会话完成设计，再回本项目落地。
+6. **交付话术**：完成后用大白话总结（改了哪些页面 / 哪些地方变了 / 怎么验收），不输出施工坐标等技术细节；验收引导统一为"运行 `pnpm dev` 打开页面对照看效果，哪里不满意直接说"。
 
 ### 4. 验证与交付
 

package/bin/cli.js

@@ -35,7 +35,7 @@ const TRACK_FILE = path.join(HOME, ".vue3-temp-skill.json");
 // 累积性（ledger 台账）/ 终态机读凭证（四闸串联，FINAL-GATE: PASS）是落地会话的运行时闸——
 // 缺了它们「只挑主题令牌落地 + 覆盖历史成果 + 以自述结束会话」无法被静态拦截
 // （失效模式：运行时副本缺审计闸时，残缺口变更集会一路绿灯）。
-const RUNTIME_SCRIPT_FILES = ["match.py", "modules.json"];
+const RUNTIME_SCRIPT_FILES = ["match.py", "modules.json", "check-landing.mjs"];
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(SKILL_DIR, "package.json"), "utf-8")).version;
 
 // ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "type": "module",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块、视觉契约落地",
   "bin": {
@@ -25,6 +25,7 @@
     "release": "node release.js",
     "release:minor": "node release.js minor",
     "release:major": "node release.js major",
+    "check:landing": "node scripts/check-landing.mjs --project .",
     "match": "python scripts/match.py",
     "match:batch": "python scripts/match.py --batch",
     "postpublish": "echo 'Published @qilitt-mickey/vue3-temp-skill to npmjs.org'"

package/references/adapters/vue-antdv.md

@@ -44,6 +44,46 @@ description: Vue 3 + Ant Design Vue 适配。提供深度选择器语法、组
 | DatePicker | `.ant-picker` | `.ant-picker-input input` |
 | Form | `.ant-form` | `.ant-form-item` |
 
+## 角色类挂载方式（视觉不生效的头号原因）
+
+**CSS 生成了不等于视觉会变**——必须把角色类挂到组件上。
+
+| 契约角色 | 挂载写法 |
+|---|---|
+| `button.*` | `<a-button :class="[...]">` |
+| `shell.sidebar.item` | `<a-menu-item :class="[...]">` |
+| `shell.tabs.item` | `<a-tab-pane :class="[...]">` |
+| `input.base` / `filter.input` | `<a-input :class="[...]">`，`inner` 用 `:deep(.ant-input)` |
+| `select.base` | `<a-select :class="[...]">`，`inner` 用 `:deep(.ant-select-selector)` |
+| `filter.dateRange` | `<a-range-picker :class="[...]">` |
+| `tag.status` | `<a-tag :class="[...]">` |
+| `card.base` | `<a-card :class="[...]">`，`inner` 用 `:deep(.ant-card-body)` |
+| `table.wrapper` | `<a-table :class="[...]">` |
+| `table.headerCell` / `table.cell` | **用 `#headerCell` / `#bodyCell` 插槽**：`#bodyCell="{ column, record }"` 内给单元格外层元素加类 |
+| `table.cell.amount` | 同上 + `align: 'right'` |
+| `pagination.bar` | `<a-pagination :class="[...]">` |
+
+**Table 的特殊性**：`a-table` 的单元格同样由组件内部生成。推荐用 `#bodyCell` 插槽批量挂载：
+
+```vue
+<a-table :data-source="rows" :columns="columns" class="role-table-wrapper">
+  <template #headerCell="{ column }">
+    <div :class="column.dataIndex === 'name' ? 'role-table-header-cell' : 'role-table-header-cell'">
+      {{ column.title }}
+    </div>
+  </template>
+  <template #bodyCell="{ column, record }">
+    <div :class="cellRole(column, record)">{{ record[column.dataIndex] }}</div>
+  </template>
+</a-table>
+```
+
+### 批量挂载的做法
+
+一个页面有 20+ 角色时**逐个手写 class 会漏**。做法：把契约角色名转成类名清单，交给页面统一挂载，并在第 0 步自检里确认覆盖率 100%。
+
+**类名转换规则**：`table.headerCell` → `.role-table-header-cell`（点号与驼峰都转小写连字符）。
+
 ## 提权通道（唯一允许处）
 
 | 情况 | 处置 |

package/references/adapters/vue-element-plus.md

@@ -47,6 +47,48 @@ description: Vue 3 + Element Plus 适配。提供深度选择器语法、组件
 | Tabs | `.el-tabs` | `.el-tabs__item` |
 | DatePicker | `.el-date-editor` | `.el-range-input` |
 
+## 角色类挂载方式（视觉不生效的头号原因）
+
+**CSS 生成了不等于视觉会变**——必须把角色类挂到组件上。Element Plus 各组件的挂法不同：
+
+| 契约角色 | 挂载写法 | 说明 |
+|---|---|---|
+| `shell.sidebar.item` / `.active` | `<el-menu-item :class="[...]">` | 直接作用在组件根元素 |
+| `shell.header.icon` | `<el-button :class="[...]">` | 同上 |
+| `button.primary` / `.secondary` / `.danger` | `<el-button :class="[...]">` | 同上 |
+| `card.base` | `<el-card :class="[...]">` | 内边距在 `.el-card__body`，`host` 作用在根、`inner` 用 `:deep(.el-card__body)` |
+| `table.wrapper` | `<el-table :class="[...]">` | 表格**根元素**挂 wrapper |
+| `table.headerCell` | **需走插槽**：`<template #header><th class="role-table-header-cell">` | Element Plus 的 `th` 不能直接加类 |
+| `table.cell` | `<el-table-column :class="[...]">` 或插槽内 `td` | 列组件加类 |
+| `table.cell.amount` | 同上 + `:deep(.cell)` 承接 `inner` | 右对齐靠 `text-align` |
+| `tag.status` | `<el-tag :class="[...]">` | 直接作用 |
+| `input.base` / `filter.input` | `<el-input :class="[...]">` | `inner` 用 `:deep(.el-input__wrapper)` 或 `:deep(input)` |
+| `select.base` | `<el-select :class="[...]">` | `inner` 用 `:deep(.el-select__wrapper)` |
+| `filter.dateRange` | `<el-date-picker :class="[...]">` | — |
+| `pagination.bar` | `<el-pagination :class="[...]">` | 直接作用 |
+| `shell.tabs.item` | 自绘或 `<el-tab-pane>` | 激活态另由 `item.active` 角色承载 |
+
+**Table 的特殊性**：`el-table` 的 `th` / `td` 由组件内部生成，**不能直接在 `<el-table>` 上加类来影响单元格**。表头必须用 `#header` 插槽自绘：
+
+```vue
+<el-table :data="rows" class="role-table-wrapper">
+  <template #header>
+    <div class="role-table-header-cell">运单号</div>
+  </template>
+  <el-table-column prop="name" label="名称" class="role-table-cell" />
+  <el-table-column prop="fee"  label="运费" class="role-table-cell-amount" />
+  <template #default="{ row }">
+    <el-tag class="role-tag-status">{{ row.status }}</el-tag>
+  </template>
+</el-table>
+```
+
+### 批量挂载的做法
+
+一个页面有 20+ 角色时**逐个手写 class 会漏**。做法：把契约的角色名转成类名清单，交给页面统一挂载，并在第 0 步自检里确认覆盖率 100%。
+
+**类名转换规则**：`table.headerCell` → `.role-table-header-cell`（点号与驼峰都转小写连字符）。
+
 ## 提权通道（唯一允许处）
 
 角色类是独立命名空间（`role-` 前缀）+ 独立文件，**通常不需要提权**。仅两种情况需要：

package/references/design-apply.md

@@ -38,6 +38,25 @@ src/styles/ui-layout.css     区域网格
 
 ## 执行流程（六步）
 
+### 第 0 步 · 落地自检（先跑，断在哪一目了然）
+
+```bash
+node <技能>/scripts/check-landing.mjs --project <项目根>
+```
+
+**六项检查，逐项给修复动作，exit 1 表示链路有断点：**
+
+| # | 检查项 | 断点含义 |
+|---|---|---|
+| 1 | `contract-found` | `.design/visual-contract-*.json` 不存在 → 设计侧没落盘 |
+| 2 | `contract-valid` | 契约字段缺失（`meta.scene` / `tokens.color` / `roles` / `layout.areas`） |
+| 3 | `css-generated` | 三份 CSS 未生成 → 第 3/4/5 步没执行 |
+| 4 | `css-imported` | **生成了但没被 import** → 浏览器根本不加载 |
+| 5 | `roles-mounted` | **CSS 有规则但模板没挂类** → 死样式，视觉不变 |
+| 6 | `layout-mounted` | 模板没出现 `.ui-page` → 骨架仍是项目原样 |
+
+**六项全过是交付前置条件。** 不过就修断点，**不要直接目视猜问题在哪**。
+
 ### 第 1 步 · 读契约（只读一次）
 
 读取 `<项目根>/.design/visual-contract-*.json`。多份契约（多页型）逐份独立施工。
@@ -190,17 +209,19 @@ src/styles/ui-layout.css     区域网格
 
 **实现方式二选一**：能挂 class 就挂 class（简单可靠）；挂不上就用组件的 `row-class-name` 回调。**由 adapter 决定，不由落地端临时发明。**
 
-### 第 6 步 · 挂载 + 目视对照
+### 第 6 步 · 挂载 + 覆盖验证
 
 1. 在样式入口引入三份文件（一次性，入口位置按项目现状）
 2. 页面根节点挂 `.ui-page`，各区域挂 `.ui-region-<名>`
-3. 区域内组件挂对应 `.role-<名>` 类
-4. 按契约 `pages.<页型>.nodes` 把组件填进对应区域
-
-**然后目视对照**：打开页面与契约 `meta.source.mockup` 指向的效果图并排看。
+3. 按 adapter 的「角色类挂载方式」给组件挂 `.role-*`（**表格走插槽，不是在 `<el-table>` 上加类**）
+4. **重跑第 0 步的落地自检，六项全过才算挂载完成**
+5. 目视对照：打开页面与契约 `meta.source.mockup` 指向的效果图并排看
 
 | 现象 | 根因 | 修正动作 |
 |---|---|---|
+| 页面完全没变化 | 三份 CSS 没被 import | 在样式入口 import 一次 |
+| 只有个别地方变了 | 角色类挂载覆盖率低 | 按 adapter 挂法补齐，重跑自检 |
+| 布局还是项目原样 | 没挂 `.ui-page` / `.ui-region-*` | 布局组件加类 |
 | 有差异 | 契约值或落点层不对 | **改契约 → 重新生成 CSS** |
 | 颜色不对 | 令牌值抄错 | 改 `tokens` → 重新生成 |
 | 字号 / 字重不对 | 落错层（该进 `inner[]` 进了 `host[]`） | 改契约的数组归属 → 重新生成 |

package/scripts/check-landing.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+/**
+ * 契约落地自检 —— 判断「契约 → 样式 → 挂载」三个闭环在哪一环断了
+ *
+ * 用法:
+ *   node check-landing.mjs --project <项目根目录>
+ *   node check-landing.mjs --project . --json
+ *
+ * 退出码: 0 = 六项全过 / 1 = 有 FAIL 项
+ *
+ * 设计原则: 纯读取 + 确定性判断。不猜测、不修改、不联网。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const IGNORE_DIRS = new Set([
+  "node_modules", "dist", ".git", ".vite", "coverage",
+  "__pycache__", ".idea", ".vscode", ".workbuddy", "unpackage",
+]);
+
+const CSS_FILES = ["ui-tokens.css", "ui-roles.css", "ui-layout.css"];
+const SOURCE_EXT = new Set([".vue", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+const STYLE_EXT = new Set([".css", ".scss", ".less"]);
+
+const EXIT_OK = 0;
+const EXIT_FAIL = 1;
+
+// ────────────────────────────── 参数解析
+
+function parseArgs(argv) {
+  const out = { project: process.cwd(), json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--project" || a === "-p") {
+      const v = argv[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error("错误: --project 后面必须跟项目根目录路径");
+        process.exit(EXIT_FAIL);
+      }
+      out.project = path.resolve(v);
+      i++;
+    } else if (a === "--json") {
+      out.json = true;
+    } else if (a === "--help" || a === "-h") {
+      console.log("用法: node check-landing.mjs --project <项目根目录> [--json]");
+      process.exit(EXIT_OK);
+    }
+  }
+  return out;
+}
+
+// ────────────────────────────── 文件遍历
+
+function walk(dir, extSet, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name)) continue;
+      walk(path.join(dir, e.name), extSet, acc);
+    } else if (e.isFile()) {
+      if (extSet === null || extSet.has(path.extname(e.name).toLowerCase())) {
+        acc.push(path.join(dir, e.name));
+      }
+    }
+  }
+  return acc;
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function rel(root, p) {
+  return path.relative(root, p).split(path.sep).join("/");
+}
+
+function exists(p) {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ────────────────────────────── 契约侧
+
+function findContract(projectRoot) {
+  const designDir = path.join(projectRoot, ".design");
+  if (!exists(designDir)) return { file: null, reason: "项目根下没有 .design/ 目录" };
+
+  let names;
+  try {
+    names = fs.readdirSync(designDir);
+  } catch {
+    return { file: null, reason: ".design/ 目录无法读取" };
+  }
+  const hit = names.find((n) => /^visual-contract.*\.json$/.test(n));
+  if (!hit) {
+    return { file: null, reason: ".design/ 下没有 visual-contract-*.json" };
+  }
+  return { file: path.join(designDir, hit), name: hit, reason: null };
+}
+
+function inspectContract(contract) {
+  const problems = [];
+  const warns = [];
+  const info = {};
+
+  if (!contract || typeof contract !== "object") {
+    return { ok: false, problems: ["契约内容不是合法 JSON 对象"], warns, info };
+  }
+
+  info.schema = contract.schema || "(缺失)";
+  if (contract.schema !== "ui.visual-contract/1.0") {
+    warns.push(`schema 是 "${contract.schema}"，期望 "ui.visual-contract/1.0"`);
+  }
+
+  const meta = contract.meta || {};
+  info.scene = meta.scene || "(缺失)";
+  info.pageTypes = Array.isArray(meta.pageTypes) ? meta.pageTypes.join(",") : "(缺失)";
+  info.mockup = (meta.source && meta.source.mockup) || "(缺失)";
+  if (!meta.scene) problems.push("meta.scene 缺失 —— 项目侧无法判断用哪套角色与布局预期");
+  if (!meta.source || !meta.source.mockup) {
+    problems.push("meta.source.mockup 缺失 —— 目视对照没有比对目标");
+  }
+
+  const colorTokens = (contract.tokens && contract.tokens.color) || {};
+  info.tokenCount = Object.keys(colorTokens).length;
+  if (info.tokenCount === 0) problems.push("tokens.color 为空 —— 令牌层没有值");
+
+  const roles = contract.roles && typeof contract.roles === "object" ? contract.roles : {};
+  const roleNames = Object.keys(roles);
+  info.roleCount = roleNames.length;
+  const emptyRoles = roleNames.filter((n) => {
+    const r = roles[n] || {};
+    const hasHost = Array.isArray(r.host) && r.host.length > 0;
+    const hasInner = Array.isArray(r.inner) && r.inner.length > 0;
+    return !hasHost && !hasInner;
+  });
+  info.emptyRoles = emptyRoles;
+  if (roleNames.length === 0) {
+    problems.push("roles 为空 —— 角色层没抽出来，三份 CSS 只能生成空壳");
+  } else if (emptyRoles.length > 0) {
+    problems.push(`这些角色没有任何声明: ${emptyRoles.join(", ")}`);
+  }
+  if (roleNames.length > 0 && roleNames.length < 5) {
+    warns.push(`契约只有 ${roleNames.length} 个角色，很可能设计侧抽取不完整（一页通常 20+ 个角色）`);
+  }
+
+  const layout = contract.layout || {};
+  const areas = Array.isArray(layout.areas) ? layout.areas : [];
+  info.areaCount = areas.length;
+  info.grid = layout.grid || "(缺失)";
+  if (areas.length === 0) {
+    problems.push("layout.areas 为空 —— 布局层没定，骨架无法生成");
+  }
+
+  const pages = contract.pages || {};
+  info.pageTypesDeclared = Object.keys(pages).join(",");
+  if (Object.keys(pages).length === 0) {
+    warns.push("pages 为空 —— 没有区域到角色的绑定，区域内部不知道该用什么角色");
+  }
+
+  return { ok: problems.length === 0, problems, warns, info, roleNames };
+}
+
+// ────────────────────────────── CSS 侧
+
+function findGeneratedCss(projectRoot) {
+  const found = { files: [], pathOf: {} };
+  const allFiles = walk(projectRoot, null, []);
+  for (const name of CSS_FILES) {
+    const hits = allFiles.filter((p) => path.basename(p) === name);
+    if (hits.length > 0) {
+      found.files.push(hits[0]);
+      found.pathOf[name] = hits[0];
+    }
+  }
+  return found;
+}
+
+function checkImported(projectRoot, cssFileAbs) {
+  const base = path.basename(cssFileAbs);
+  const sources = walk(projectRoot, SOURCE_EXT, []);
+  const refs = [];
+  for (const s of sources) {
+    const content = readSafe(s);
+    if (content.includes(base)) refs.push(rel(projectRoot, s));
+  }
+  const styleRefs = [];
+  for (const s of walk(projectRoot, STYLE_EXT, [])) {
+    if (path.basename(s) === base) continue;
+    const content = readSafe(s);
+    if (content.includes(base)) styleRefs.push(rel(projectRoot, s));
+  }
+  return { imported: refs.length > 0 || styleRefs.length > 0, refs, styleRefs };
+}
+
+// ────────────────────────────── 挂载侧
+
+function expectedClassName(roleName) {
+  return (
+    "role-" +
+    roleName
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .replace(/\./g, "-")
+      .replace(/_/g, "-")
+      .toLowerCase()
+  );
+}
+
+function checkMounting(projectRoot, roleNames) {
+  const vueFiles = walk(projectRoot, SOURCE_EXT, []);
+  const roleClassRe = /\brole-[a-z0-9]+(?:-[a-z0-9]+)*/g;
+  const usedClasses = new Map();
+  for (const s of vueFiles) {
+    const content = readSafe(s);
+    const hits = content.match(roleClassRe);
+    if (!hits) continue;
+    for (const h of hits) {
+      if (!usedClasses.has(h)) usedClasses.set(h, new Set());
+      usedClasses.get(h).add(rel(projectRoot, s));
+    }
+  }
+
+  const expected = roleNames.map(expectedClassName);
+  const mounted = [];
+  const missing = [];
+  for (let i = 0; i < roleNames.length; i++) {
+    if (usedClasses.has(expected[i])) mounted.push(expected[i]);
+    else missing.push(`${roleNames[i]} → .${expected[i]}`);
+  }
+
+  const layoutClassRe = /\bui-(?:page|region-[a-z0-9]+(?:-[a-z0-9]+)*)\b/g;
+  const layoutClasses = new Set();
+  for (const s of vueFiles) {
+    const content = readSafe(s);
+    const hits = content.match(layoutClassRe);
+    if (hits) for (const h of hits) layoutClasses.add(h);
+  }
+
+  return {
+    scannedFileCount: vueFiles.length,
+    mounted,
+    missing,
+    layoutClasses: [...layoutClasses],
+    hasLayout: layoutClasses.has("ui-page"),
+  };
+}
+
+// ────────────────────────────── 主流程
+
+function run(projectRoot) {
+  const checks = [];
+  const add = (id, title, status, detail, fix) =>
+    checks.push({ id, title, status, detail, fix });
+
+  if (!exists(projectRoot)) {
+    console.error(`项目根目录不存在: ${projectRoot}`);
+    process.exit(EXIT_FAIL);
+  }
+
+  // 1. 契约存在
+  const cf = findContract(projectRoot);
+  if (!cf.file) {
+    add("contract-found", "契约文件存在", "FAIL", cf.reason,
+      "设计侧没有落盘契约。检查是否在项目根目录运行、是否完成了第 6 步「出契约」。");
+    return { checks, ok: false, projectRoot };
+  }
+  add("contract-found", "契约文件存在", "PASS", `.design/${cf.name}`, null);
+
+  // 2. 契约完整
+  let contract = null;
+  let parsed = null;
+  try {
+    contract = JSON.parse(readSafe(cf.file));
+  } catch (e) {
+    add("contract-valid", "契约内容完整", "FAIL", `JSON 解析失败: ${e.message}`,
+      "契约是手工编辑过的吗？重新用设计侧生成一份。");
+    return { checks, ok: false, projectRoot };
+  }
+  parsed = inspectContract(contract);
+  add(
+    "contract-valid",
+    "契约内容完整",
+    parsed.ok ? "PASS" : "FAIL",
+    `场景=${parsed.info.scene} 页型=${parsed.info.pageTypes} 角色=${parsed.info.roleCount} 区域=${parsed.info.areaCount}`,
+    parsed.problems.length ? parsed.problems.join("；") : null
+  );
+  for (const w of parsed.warns || []) {
+    add(`contract-warn-${checks.length}`, "契约告警", "WARN", w, null);
+  }
+  if (!parsed.ok) {
+    return { checks, ok: false, projectRoot, contractInfo: parsed.info };
+  }
+
+  // 3. 三份 CSS 生成
+  const css = findGeneratedCss(projectRoot);
+  const missingCss = CSS_FILES.filter((n) => !css.pathOf[n]);
+  add(
+    "css-generated",
+    "三份 CSS 已生成",
+    missingCss.length === 0 ? "PASS" : "FAIL",
+    missingCss.length === 0
+      ? CSS_FILES.map((n) => rel(projectRoot, css.pathOf[n])).join("  ")
+      : `缺: ${missingCss.join(", ")}`,
+    missingCss.length
+      ? "项目侧未完成第 3/4/5 步。按 design-apply.md 的翻译规则生成这三份文件。"
+      : null
+  );
+  if (missingCss.length === 0) {
+    // 4. CSS 被引入
+    const unimported = [];
+    const importDetail = [];
+    for (const n of CSS_FILES) {
+      const r = checkImported(projectRoot, css.pathOf[n]);
+      if (!r.imported) unimported.push(n);
+      importDetail.push(`${n}:${r.imported ? "已引入 " + (r.refs[0] || r.styleRefs[0]) : "未引入"}`);
+    }
+    add(
+      "css-imported",
+      "三份 CSS 被入口引入",
+      unimported.length === 0 ? "PASS" : "FAIL",
+      importDetail.join("  |  "),
+      unimported.length
+        ? `${unimported.join(", ")} 生成了但没被任何文件 import —— 浏览器不会加载它们。在样式入口 import 一次。`
+        : null
+    );
+  }
+
+  // 5. 角色类挂载
+  const mount = checkMounting(projectRoot, parsed.roleNames);
+  const mountRatio = parsed.roleNames.length
+    ? mount.mounted.length / parsed.roleNames.length
+    : 0;
+  add(
+    "roles-mounted",
+    "角色类挂到模板上",
+    mount.mounted.length === parsed.roleNames.length ? "PASS"
+      : mount.mounted.length === 0 ? "FAIL" : "WARN",
+    `契约 ${parsed.roleNames.length} 个角色，模板挂载 ${mount.mounted.length} 个（覆盖率 ${(mountRatio * 100).toFixed(0)}%）；扫描 ${mount.scannedFileCount} 个源文件`,
+    mount.mounted.length === 0
+      ? "没有任何 .vue 文件出现 role-* 类名 —— 三份 CSS 全是死样式（写了规则但没元素承载）。按 adapter 的挂载映射给组件加 class。"
+      : mount.missing.length
+        ? `未挂载 ${mount.missing.length} 个角色（CSS 已生成但页面上没有对应 class，视觉不会变）: ${mount.missing.slice(0, 6).join(" | ")}${mount.missing.length > 6 ? " …" : ""}`
+        : null
+  );
+
+  // 6. 布局类挂载
+  add(
+    "layout-mounted",
+    "布局类挂到容器上",
+    mount.hasLayout ? "PASS" : "FAIL",
+    mount.hasLayout
+      ? `布局类: ${mount.layoutClasses.join(", ")}`
+      : "没有任何 .vue 文件出现 .ui-page —— 布局层未接入，骨架仍是项目原有结构",
+    mount.hasLayout ? null : "布局组件需加 .ui-page 与 .ui-region-* 类，见 adapter 的「布局占位容器」。"
+  );
+
+  const ok = checks.every((c) => c.status === "PASS");
+  return { checks, ok, projectRoot, contractInfo: parsed.info, mount };
+}
+
+// ────────────────────────────── 输出
+
+function printHuman(result) {
+  const L = [];
+  L.push("");
+  L.push("契约落地自检");
+  L.push("=".repeat(64));
+  L.push(`项目根: ${result.projectRoot}`);
+  L.push("");
+  const mark = { PASS: "PASS", WARN: "WARN", FAIL: "FAIL" };
+  for (const c of result.checks) {
+    L.push(`[${mark[c.status]}] ${c.id} · ${c.title}`);
+    if (c.detail) L.push(`        ${c.detail}`);
+    if (c.fix) L.push(`        修复 → ${c.fix}`);
+  }
+  L.push("");
+  L.push("-".repeat(64));
+  const firstFail = result.checks.find((c) => c.status === "FAIL");
+  if (result.ok) {
+    L.push("结论: 六项全过 —— 契约、样式、挂载三个闭环均已接通。");
+  } else if (firstFail) {
+    L.push(`结论: 断在「${firstFail.title}」。先修这一项，重跑本脚本看下一项。`);
+    L.push("");
+    L.push("提醒: 项目侧的修正动作是「改契约或改 adapter 后重新生成」,");
+    L.push("      不要直接改已生成的 CSS —— 下次重新生成会被覆盖。");
+  } else {
+    L.push("结论: 有 WARN 项，落地链路未全覆盖。");
+  }
+  L.push("");
+  process.stdout.write(L.join("\n") + "\n");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const result = run(args.project);
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.ok ? EXIT_OK : EXIT_FAIL);
+}
+
+main();