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

package/README.md

@@ -1,118 +1,131 @@
 # vue3-temp-skill
 
-Vue 3 企业级项目开发技能包。面向 vue3-web-temp 及其派生项目，把产品点子快速做成可演示、可验证、可继续演进的 Demo，同时约束代码质量。
+Vue 3 企业级中后台项目开发技能包。两条链路：
 
-## 文档分工
+- **常规开发** —— 能力组路由（列表页 / 表单 / API / 权限 / 可视化 …）
+- **视觉契约落地** —— 读设计侧契约，照抄生成三份 CSS
 
-| 文档 | 读者 | 内容 |
-|------|------|------|
-| `SKILL.md` | AI | 何时做什么、禁止什么、工作流约束 |
-| `README.md`（本文件） | 维护者 / 人类开发者 | 安装、脚本命令、本地调试、发布 |
-| `references/*.md` | AI（写代码时） | 标准样板、专项细则、硬失败表 |
-| `scripts/modules.json` | 匹配器 + 维护者 | 能力组关键词、同批加载、闸门项 |
+与设计侧 `project-ui-design` 构成双端体系。
 
 ## 这是什么
 
-`/vue3-temp-skill <需求>` → 项目探查 → 能力路由 → 按约定实现 → `code-quality` 闸门。
-
-- **始终加载** `core-kernel`
-- **按需** `project-inventory`（查依赖 / 装包 / 查 Re* 名录）
-- **按需** `addon-enable` — 只有目标项目确实存在排除项、占位插件或缺失接线时才读
-- **生成后闸门** `code-quality`：清单 + `pnpm lint:fix` + `pnpm type-check` + 结果块
+### 链路一 · 常规开发
 
-## 使用方式
-
-```
-/vue3-temp-skill <你的需求描述>
+```text
+/vue3-temp-skill <自然语言需求>
+  → 项目探查（package.json / 路由 / Re* / Hooks / API）
+  → 能力路由（match.py "需求" --json，按 load_files 读）
+  → 业务闭环实现（页面 + 路由 + API + 类型 + mock）
+  → code-quality 清单 + lint / type-check
 ```
 
-示例：
+### 链路二 · 视觉契约落地
+
+```text
+输入：<项目根>/.design/visual-contract-<场景>-<页型>.json
+  → ① 落地自检（六项：契约存在/完整/CSS生成/CSS引入/角色挂载/布局挂载）
+  → ② 读契约（唯一输入，只读一次）
+  → ③ 选 adapter（按 package.json 判定所用组件库）
+  → ④ 生成 ui-tokens.css（:root 变量）
+  → ⑤ 生成 ui-roles.css（.role-* 规则）
+  → ⑥ 生成 ui-layout.css（.ui-page 网格）
+  → ⑦ 挂载（.ui-page / .ui-region-* / .role-*）
+  → ⑧ 重跑自检确认六项全过 → 目视对照
+```
 
-- `/vue3-temp-skill 帮我开发一个客户管理模块，按名称、状态查询`
-- `/vue3-temp-skill 远程搜索下拉，支持分页与回写`
-- `/vue3-temp-skill 编辑页加数据变更对比`
-- `/vue3-temp-skill 关系图谱，力导向布局`
-- `/vue3-temp-skill 移动端客户列表用 Vant`
+**AI 在链路二的工作是翻译，不是判断。** 契约写什么就生成什么——落点层级已由 `host[]` / `inner[]` 两个数组物理二分，落地端不推断属性该落哪一层。
 
-## 模块一览
+**落地自检是交付前置条件**（`npm run check:landing`）：
 
-| 类型 | 能力组 |
-|------|------|
-| 始终 | core-kernel |
-| 闸门 | code-quality |
-| 高频 | page-crud、page-detail、data-service、forms、access、theme-layout、shared-ui |
-| 专项 | table-advanced、visualization、workflow、files-and-editors、realtime-and-mobile、data-compare、i18n |
-| 工程 | project-setup（project-inventory + addon-enable） |
+| 检查项 | 断点含义 |
+|---|---|
+| `contract-found` | `.design/` 下没有契约 → 设计侧没落盘 |
+| `contract-valid` | 契约字段缺失 |
+| `css-generated` | 三份 CSS 未生成 |
+| `css-imported` | **生成了但没被 import** → 浏览器不加载 |
+| `roles-mounted` | **CSS 有规则但模板没挂类** → 死样式，只有个别角色生效 |
+| `layout-mounted` | 没挂 `.ui-page` → 骨架仍是项目原样 |
 
-能力组定义、关键词和参考文件由 `scripts/modules.json` 维护。
+**任何一项断掉都会表现为「CSS 写了但页面没变化」。先跑自检定位断点，不要目视猜。**
 
-## 维护者：扩展能力组
+## 视觉契约的核心机制
 
-新增能力时先判断能否并入已有组；确需扩展时编辑 `scripts/modules.json`（关键词、`load` 映射），再运行 `npm run validate` 校验。
+| 机制 | 说明 |
+|---|---|
+| **照抄不判断** | 不判断落点层级、不合并声明、不补角色库没有的角色、不改契约值 |
+| **布局由 CSS 网格决定** | 项目布局组件退化为占位容器（只提供插槽）；设计布局与项目布局不一致时，差异只体现在 `ui-layout.css` 的取值上 |
+| **角色类独立命名空间** | `role-` 前缀独立类 + 独立文件，天然不与组件库同类规则竞争；确需提权走 adapter 唯一通道 |
+| **令牌全站联动** | 契约令牌编译为 CSS 变量；改一个令牌值，全站引用它的地方同步变化 |
+| **契约不含技术栈信息** | 只有 CSS 属性、令牌引用、区域与角色；组件库差异（深度选择器语法、穿透前缀、落点文件）全在 adapter |
 
-## 脚本与 npm 命令
+## 文档分工
 
-### 运行时（AI / 本地调试）
+| 文件 | 读者 | 内容 |
+|------|------|------|
+| `SKILL.md` | AI | 触发方式、目标、能力组路由、工作流、视觉契约落地要点、红线 |
+| `README.md`（本文件） | 维护者 / 开发者 | 安装、命令、扩展、新增 adapter、与模板的关系 |
+| `references/*.md` | AI | 40+ 专项能力 reference（业务开发用） |
+| `references/design-apply.md` | AI | **视觉契约落地协议**：六步流程 + 三列映射表 + 翻译规则 |
+| `references/adapters/*.md` | AI | Vue 组件库适配：深度选择器语法 / 穿透前缀 / 落点文件 |
+| `mapping/<场景>.json` | AI + 维护者 | 区域名 ↔ 项目现状对照（scope / var / fallback 三列） |
 
-| 脚本 | 职责 |
-|------|------|
-| `scripts/match.py` | 能力路由器：输入需求，输出 JSON（`load_files`、同批加载、闸门项） |
-| `parser/index.js` | 设计变更集解析器：`build` 校验编译 / `match` 三级匹配 / `list` 词典清单 / `query` 单条详情（design-apply 能力组） |
-| `parser/watch.js` / `npm run mapping:watch` | 开发态监听 mapping/ 变更自动重编译 dist/ |
-| `parser/override.js` | 业务级映射覆写 API（链路 A 配套，`overrideMapping` / `overrideMappings`） |
+## 安装
 
-**匹配器调用（本地环境）：**
+Node.js >= 22.12.0
 
 ```bash
-# Windows 优先
-py -3 scripts/match.py "客户列表查询跳转详情" --json
-
-# 通用
-python scripts/match.py "客户列表查询跳转详情" --json
-python scripts/match.py --batch   # 15 个典型场景回归
+npx @qilitt-mickey/vue3-temp-skill@latest install all
 ```
 
-**npm 封装：**
+一键安装到本机检测到的全部 AI 编程工具；也可显式指定：
 
 ```bash
-npm run match          # python scripts/match.py
-npm run match:batch    # 批量回归
+npx @qilitt-mickey/vue3-temp-skill@latest install cursor
+npx @qilitt-mickey/vue3-temp-skill@latest install all --project ./my-app
+npx @qilitt-mickey/vue3-temp-skill@latest update
 ```
 
-### 维护者（不随技能安装分发）
+| 目标 | 级别 |
+|------|------|
+| cursor / qoder / claude / universal / windsurf / trae | 全局（个人目录） |
+| copilot / gemini | 项目级（需 `--project <dir>`） |
 
-| 脚本 / 命令 | 职责 |
-|-------------|------|
-| `scripts/validate.mjs` / `npm run validate` | 结构校验：frontmatter、路由引用、交叉引用 |
-| `scripts/check.mjs` / `npm run check` | 发布前检查：validate + match 批量回归 |
-| `scripts/cli.mjs` | 统一入口：`--validate` / `--route` / `--list` |
-| `npm run release` | 先 check，再升版本、提交、发布 npm |
+安装器复制运行时文件：`references/`（含 `adapters/`）、`scripts/`（`match.py` + `modules.json`）、`mapping/`、`SKILL.md`、`README.md`。`release.js` 留在技能包仓库供维护使用。
 
-```bash
-node scripts/cli.mjs --list
-node scripts/cli.mjs --route "客户列表跳转详情"
-node scripts/cli.mjs --validate
-npm run check
-```
+开发期调试可直接从源码目录安装：`node bin/cli.js install claude`。
 
-## 安装
+## 命令
 
-Node.js >= 22.12.0
+| 命令 | 职责 |
+|------|------|
+| `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 |
 
-```bash
-npx @qilitt-mickey/vue3-temp-skill@latest install all
-```
+## 扩展
 
-安装器复制 AI 运行时文件：`match.py`、`modules.json`、`mapping/`（语义 ID 词典）、`parser/`（变更集解析器）。validate / check / cli / release 留在技能包仓库供维护使用。
+| 要加什么 | 怎么做 | 哪些文件不动 |
+|---|---|---|
+| 新业务能力 | 在 `references/` 加一份专项 md + 在 `scripts/modules.json` 登记 | 其余全部 |
+| 新组件库适配 | 照 `references/adapters/_new-adapter.md` 写一份 Vue 组件库 adapter | 契约、`design-apply.md`、其他 adapter |
+| 新场景的变量映射 | 加 `mapping/<场景>.json` | adapter 与契约 |
+| 项目自身能力 | 写进 `references/project-inventory.md` | 全部 |
 
-| 目标 | 说明 |
-|------|------|
-| 个人 Skill 目录 | 安装器写入当前 AI 环境支持的 Skill 目录 |
-| 项目级说明 | 部分环境支持写入项目内说明文件 |
+**新增 adapter 的判据**：写完后同一份契约应能不改一行内容地落到用该组件库的项目。若需要改契约，说明 adapter 越界了。
+
+**关于跨前端框架**：契约格式本身不含技术栈信息，因此可以交给不同框架的项目技能消费。但**本技能只服务 Vue 3**，adapter 只覆盖 Vue 组件库——支持 React / Angular 等框架时，由对应框架的项目技能自带 adapter，契约无需改动。
 
-具体路径因 AI 环境而异，安装完成后以安装器输出为准。
+## 与设计侧的关系
+
+| 契约 | 说明 |
+|------|------|
+| 视觉契约 | 设计侧唯一交付物，协议 `ui.visual-contract/1.0`；只有 CSS 属性、令牌引用、区域与角色 |
+| 落点路径 | 设计侧写 `<项目根>/.design/`，本技能从同一路径读——目录通用，与 AI 工具无关 |
+| 三列映射表 | 本技能侧的 `mapping/<场景>.json`，把契约的区域名对到项目现状的承载类名 |
+| adapter | 承接组件库差异，本技能侧维护；设计侧不感知 |
 
-## 与模版的关系
+## 与模板的关系
 
 本 Skill 约定对齐 **vue3-web-temp** 精简脚手架：
 
@@ -123,7 +136,11 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 | 本包 `references/` | AI + 开发者 | **标准样板**、专项细则、addon 安装表 |
 | 本包 `addon-enable.md` | AI + 开发者 | **出厂已删依赖的逐文件恢复代码** |
 
-- 模板仓库：布局壳 + `Re*` 源码 + 多种已接线能力；具体依赖和构建状态以目标项目当前源码为准
-- **标准样板**：在本包 `references/`；模板 `views/` 主要用于确认真实接线，不直接复制演示文案
-- 壳层、组件和 API 以当前项目源码为准；规范文档只补充实现方法
-- HTTP：仅经 `@/utils/http`；版本以目标项目 `package.json` 和锁文件为准
+## 工具中立
+
+本包与任何 AI 工具无关。`references/` / `scripts/` / `mapping/` / `SKILL.md` 内不出现任何特定 AI 工具的名称或专有路径；`bin/cli.js` 的多工具安装清单是**分发特性**，不是内容绑定。
+
+## 发布
+
+- 维护侧：`npm run release` 自动完成结构检查、升版本与发布（支持 `--dry-run` / `--no-push`）
+- 用户侧：发布后经 `npx @qilitt-mickey/vue3-temp-skill@latest update` 更新已安装目标

package/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: "vue3-temp-skill"
-description: "Vue 3 企业级项目开发技能。面向 vue3-web-temp 及其派生项目，帮助产品经理和前端快速把点子做成可演示、可验证、可继续演进的 Demo；同时约束真实模板复用和代码质量。"
+description: "Vue 3 企业级项目开发技能。面向 vue3-web-temp 及其派生项目，帮助产品经理和前端快速把点子做成可演示、可验证、可继续演进的 Demo；同时约束真实模板复用、代码质量，并支持把设计侧的视觉契约照抄落地。"
 scope: project
 agent_created: true
-tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-quality]
+tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-quality, visual-contract]
 ---
 
 # Vue 3 项目开发技能
 
-> **体系版本：1.0.0**（双 Skill 唯一版本声明点之一；设计侧 project-ui-design 同版）。版本恒定策略：双侧始终同版，不随内容修改递增，仅协议破坏性变更时双侧同步升版。mapping/*.json 的 `meta.version` 与变更集校验均恒为 `1.0.0`，不单独演进。
-
 ## 目标
 
 把产品点子快速落到真实 Vue 3 项目中，先形成客户可看的完整 Demo，再保留后续正式开发所需的代码边界。页面可以使用 mock 和最小数据，但不得使用模板演示噪音、虚构项目能力或堆叠无法维护的代码。
@@ -26,13 +24,20 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 - 做一个订单仪表盘，含统计卡片和趋势图
 - 给现有 Demo 增加附件上传、导出或审批流
 - 把一个页面从 mock 改成真实 API
-- 「按这份设计方案改造全系统」/ 落地设计技能产出的设计文件（用户可能是小白，只会给文件路径或拖入文件；见 §3b）
+- 「按这份设计契约改造全系统」（用户可能是小白，只会给文件路径或拖入文件；见 §3b）
 
 ## 运行时只保留三件事
 
 1. **项目探查**：读取目标项目的 `package.json`、路由、页面、`Re*` 组件、Hooks、API 和样式；以源码事实为准。
 2. **能力路由**：运行 `scripts/match.py "需求" --json`，**仅**按输出中的 `load_files` 阅读 reference；禁止自行展开全部 `references/`。无 Python 时按下方能力组表手动匹配。
-3. **质量闸门**：代码完成后读取 `references/code-quality.md`，执行清单和项目命令。设计变更集落地后追加**设计层闭环审计**：`node scripts/design-audit.mjs --project <落地项目> --container-width <内容区实际宽>`（ERROR 必须清零；无落地项目时自动跳过）。**会话结束前必须跑通终态凭证闸**：`node scripts/apply-final-gate.mjs --project <落地项目> --container-width <内容区实际宽>`（串联 changeset-selfcheck → parser match → parser audit → design-audit 四闸，`FINAL-GATE: PASS` 才算交付完成，凭证写入 `.design/ledger.json`）。
+3. **视觉契约落地**：输入是设计侧的视觉契约 JSON 时，走 `design-apply` 协议——**先跑落地自检，再照抄生成三份样式文件**，见 §3 输入分流。
+
+```bash
+node <技能>/scripts/check-landing.mjs --project <项目根>
+```
+
+**六项全过（exit 0）是交付前置条件**：契约存在 → 契约完整 → 三份 CSS 生成 → 被 import → 角色类挂载 100% → 布局类挂载。
+**任何一项断掉，都会出现「CSS 写了但页面没变化」——先修断点，不要目视猜。**
 
 ## 能力组路由
 
@@ -51,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` | 设计变更集落地：语义 ID 三级匹配、结构/形态/两层样式转换、锚点与结构施工、覆写提权、渲染态验收、合规闸门。**主入口 `design-apply.md`（红线+契约+步骤索引），各步骤明细见 `references/steps/`——做到哪一步读哪一份** | `design-apply.md`、`steps/`、`mapping/`、`parser/`、`scripts/design-audit.mjs`、`scripts/apply-final-gate.mjs` |
+| `design-apply` | **视觉契约落地**：落地自检 → 读契约 → 选 adapter → 生成三份 CSS → 挂载 → 覆盖验证。**主入口 `design-apply.md`，adapter 见 `adapters/`（做到哪一步读哪一份）** | `design-apply.md`、`adapters/`、`mapping/`、`scripts/check-landing.mjs` |
 
 ## 工作流
 
@@ -65,7 +70,7 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 
 - 先读 `references/core-kernel.md`。
 - 运行 `scripts/match.py "需求" --json`，按 `load_files` 阅读。
-- 读取目标项目当前 `package.json` 和锁文件；不要根据“core/addon”标签猜依赖是否存在。
+- 读取目标项目当前 `package.json` 和锁文件；不要根据"core/addon"标签猜依赖是否存在。
 - 扫描已有 `Re*`、Hooks、`src/api`、路由和相关页面；已有封装优先于技能示例。
 
 ### 3. 实现闭环
@@ -76,40 +81,70 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 - Demo 可以最小化数据和接口，但目录、类型、命名和组件边界要能承接后续开发。
 - 新依赖先检查目标项目；缺失时说明精确版本、原因和构建接线，确认后再安装。
 - 只有目标项目确实存在排除项、占位插件或缺失接线时，才读取 `addon-enable.md` 恢复配置。
-- **输入为设计文件时**：用户给出设计技能（project-ui-design）产出的 JSON 文件（无论叫"设计方案/设计文件/变更集"）→ 不走常规闭环，改走 `design-apply.md` 协议——先跑 `node parser/index.js audit` 复核锚点（挂载点/死通道），再按「结构先行（`structure_ops`）、样式两层转换、必要时覆写提权（`priority`）」落地，最后过变更集合规闸门。变更集新增三类声明维度：`apply_via`（落点通道）/ `layer`（`host` 宿主盒 / `inner` 内层文本盒）/ `structure_ops`（数据·结构驱动点位的结构操作）；词典条目对应新增 `anchors` / `preconditions` / `priority`。
+
+**输入分流**：
+
+| 输入 | 走哪条链路 |
+|---|---|
+| 自然语言需求（业务功能） | 常规闭环（见上） |
+| **设计侧的视觉契约 JSON**（`ui.visual-contract/1.0`，落盘在 `.design/`） | **`design-apply.md` 协议** —— 照抄生成 `ui-tokens.css` / `ui-roles.css` / `ui-layout.css` |
 
 ### 3b. 小白用户执行纪律（design-apply 场景）
 
 使用者默认**不懂设计也不懂代码**，交互遵守四条：
 
-1. **全自动默认**：识别为设计文件落地后**直接开始执行 parser match → 结构 → 样式 → 闸门全流程**，不等用户逐步确认，不询问"是否继续"；唯一停顿点是文件缺失/版本不匹配/parser 报错——此时用大白话报告并给选择题。
-   **禁止以「待确认」搁置可落地项**：词典缺 ID / 缺字段枚举 / 缺 form 属**能力缺口**，当场补临时映射并落地（出厂文件仅在补通道时可动，交付说明单列申报）；只有「设计侧没给值」才是**意图缺口**，去向是回流设计侧补齐，不是问用户要不要做。
-2. **术语不对用户出现**：对用户不说"变更集/语义 ID/三级匹配/pending/令牌"——说"设计方案/设计点位/自动适配/新增点位/全局样式"。这些词只出现在内部文档与交付说明里。
-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. 验证与交付
 
 - 对照 `references/code-quality.md` 检查类型、组件复用、API、路由、权限、安全、异常反馈、响应式和可演进性。
-- 在目标项目执行 `pnpm lint:fix`、`pnpm type-check`；改动构建配置时再执行 `pnpm build`。**本轮产出或修改设计变更集时，这两条不含还原度检查——必须按 code-quality 协议 3 同链追加终态闸 `apply-final-gate`（串联 selfcheck → match → audit → design-audit，取得 FINAL-GATE: PASS），禁止只跑 lint 链就报「全部质量闸门通过」。**
-- **设计文件落地时追加渲染态验收**：变更集含 `oracle`（或效果图带 `data-sid`）时，跑 `node parser/index.js verify`——抽取项目同名 `data-sid` 元素的 computed style，与效果图期望值逐点 diff；缺口按四类归因（选择器落空 / 权重被压 / 语境错位 / **存在性缺口 G12**：`oracle.absent` 点位仍可见）修正，禁止用 `!important` 掩盖。多轮迭代场景每轮动工前先 `--snapshot` 导快照、交付前 `--baseline` 比对——上轮命中本轮退步 = 基线漂移，先回归上轮修法。申报过的固有残差（`oracle.residual_accepted`）不计缺口。
-- **设计文件落地时核对登记表覆盖率**：变更集带登记表（`coverage.registry` 或 `--registry`）时，跑 `node parser/index.js match <cs.json> --registry <restore-registry.json>`——`C = A` 且无缺口才可交付；parser **当场以登记表为权威重算**，设计侧自报的 `coverage` 数字不参与。单独核验登记表对词典的通道就绪度用 `node parser/index.js registry <restore-registry.json>`（硬缺口 exit 1、通道缺口列出待补字段）。
+- 在目标项目执行 `pnpm lint:fix`、`pnpm type-check`；改动构建配置时再执行 `pnpm build`。
+- **设计契约落地时追加目视对照**：打开页面与契约 `meta.source.mockup` 指向的效果图并排看；有差异 → **改契约 → 重新生成 CSS**（改契约远比改代码便宜）。不建期望值文件、不跑采集脚本、不做逐点 diff 报告。
 - 最终说明：命中能力组、修改文件、功能验证、命令结果、未解决问题和下一步。
 
-## 出厂中性 · 变更集驱动（design-apply 架构红线）
+## 视觉契约落地（design-apply 架构要点）
+
+契约是设计侧产出的**项目完整视觉事实源**，协议 `ui.visual-contract/1.0`。
 
-目标项目源码 = **中性初始化**，只提供能力通道（CSS 变量的消费者挂载点、form 枚举、DOM/属性钩子、正确的层叠优先级），**不预置任何具体设计的结论**（某个颜色、某句问候语、某个方位的指示条、某个硬编码尺寸）。
+| 原则 | 含义 |
+|---|---|
+| **照抄不判断** | 契约写什么就生成什么。落点层级已由 `host[]` / `inner[]` 两个数组物理二分，落地端不推断「这属性落哪层」 |
+| **契约是唯一事实源** | 不读项目现有样式来决定怎么落地；冲突时以契约为准 |
+| **布局由 CSS 网格决定** | 项目布局组件退化为**占位容器**（只提供插槽，不参与布局决策）；设计布局与项目布局不一致时，差异只体现在 `ui-layout.css` 的取值上，不需要适配、不需要切形态、不需要结构手术 |
+| **角色类独立命名空间** | 角色类是 `role-` 前缀的独立类 + 独立文件，天然不与组件库同类规则竞争；确需提权时走 adapter 的唯一通道，**不在角色类里整条加 `!important`** |
+| **契约不含技术栈** | 契约里只有 CSS 属性、令牌引用、区域与角色——本技能据此生成样式，无需理解组件内部实现 |
+| **组件库差异只在 adapter** | 深度选择器语法、穿透前缀、落点文件——adapter 的全部职责；本技能只服务 Vue 3，adapter 只覆盖 Vue 组件库 |
 
-- 一切设计决策由设计变更集驱动，经 `design-apply` 动态落到「设计层文件 `src/styles/design-shell.scss` / 页面级 scoped 样式 / DOM 属性与配置」，不落到出厂样式文件与出厂组件里。
-- **效果图页面 = 设计角色坐标系，不是页面增量（G13 页面绑定闸）**：效果图页面（如「运单管理」）是设计侧为承载设计语言虚构的演示标题，**默认映射到项目已有页面**——落地动作恒为「在已有页面上同步结构与样式」，**禁止因效果图新增页面 / 路由 / 菜单项**；唯一例外是变更集 `page_bindings` 显式声明 `target:"new"` 且在 `notes` 申报。判据：换一张效果图不需要改项目的页面/路由/菜单清单 ⇒ 架构正确；需要新增页面才能换 ⇒ 设计演示页被误当业务增量，必须回退。
-- **演示占位内容 = 效果的角色承载，不是还原目标（演示内容等价）**：项目演示页上为展示"此处可放控件"而写的占位说明文字 / 演示按钮，既不是效果图的角色、也不是设计意图。落地时必须把落在效果图对应角色上的演示占位**替换为设计对应内容**，或对效果图没有该位置的点位**收口隐藏**——**还原后的页面不得残留模板演示说明性文字与占位按钮**。判据：残留演示文案说明「效果 vs 内容」混淆——把模板演示内容当成设计还原，必须回退（详见 design-apply 第 2 步「出厂演示占位内容等价」）。
-- 判据：换一张效果图只需换变更集、不必改源码 ⇒ 架构正确；需要改源码才能换 ⇒ 设计结论被烧进源码，必须回退为通道。
-- 出厂文件仅在「通道缺失」时可动（补变量消费者 / 补 form 枚举 / 修层叠优先级），且必须在交付说明中单列「补通道」条目写明缺失点。
+**三条产物的命名空间互不干扰**：
+
+| 命名空间 | 归属 | 产物 |
+|---|---|---|
+| 页面私有样式 | 常规开发 | 页面 scoped 样式 |
+| `role-` | 视觉契约落地 | `src/styles/ui-roles.css` |
+| `ui-` | 视觉契约落地 | `src/styles/ui-tokens.css` + `src/styles/ui-layout.css` |
 
 ## 项目事实优先级
 
 `目标项目当前源码` > `目标项目 package.json / 锁文件` > `本 Skill reference` > `通用 Vue 习惯`。
 
+## 工具中立（不可越）
+
+本技能包**与任何 AI 工具无关**，可被任意工具识别与调用。
+
+| 约束 | 说明 |
+|---|---|
+| **技能内容零工具痕迹** | `references/` / `scripts/` / `mapping/` / `SKILL.md` 内不出现任何特定 AI 工具的名称、专有目录、专有文件格式 |
+| **路径约定用通用目录** | 读契约：`<项目根>/.design/`；写样式：`src/styles/`。都是通用项目目录 |
+| **分发靠 CLI 多目标** | `bin/cli.js` 的多工具安装能力是**分发特性，不是内容绑定**；工具清单可增删，不影响技能内容 |
+| **触发用 Slash Command** | `/vue3-temp-skill`，各工具通用约定 |
+
+**判据**：把本包放进任何一个支持 Markdown + JSON + Python 的 AI 环境，不改任何一行内容就能用。
+
 ## 默认禁止
 
 - 不在页面内直接使用 `axios` / `fetch`，不虚构 API 前缀。
@@ -117,6 +152,10 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 - 不使用裸 `v-if` 代替权限指令，不使用不可信 `v-html`。
 - 不为了视觉效果引入未经确认的新 UI 框架或图表库。
 - 不把 lint 通过当成业务闭环完成。
+- **不改组件库源码**；样式调整只经 `ui-*.css` 三份文件与项目自身样式层。
+- **不直接改生成出来的 `ui-*.css`**——要改改契约或改 adapter，然后重新生成。直接改会被下次生成覆盖，且不留痕迹。
+- **不在角色类里整条加 `!important`**——层叠问题走 adapter 的唯一提权通道。
+- **不为契约新增技术栈字段**——组件库差异进 adapter，契约保持中立。
 
 ## 最终回复格式
 
@@ -131,7 +170,5 @@ tags: [vue3, typescript, element-plus, pinia, vite, unocss, crud, demo, code-qua
 - 功能：...
 - `pnpm lint:fix`：通过 | 失败（原因）
 - `pnpm type-check`：通过 | 失败（原因）
-- 设计闸（本轮有设计变更集时必填，无则 N/A）：`apply-final-gate` → FINAL-GATE: PASS ✅（凭证已写入 ledger.json）
-- 设计验收：无 oracle 时 N/A | 逐点 diff 结果（命中 N / 缺口 M，归因与修正）
-- 缺口回流：无 | 仅限「设计侧未给值」的维度（列出维度名，注明已回流设计侧补齐）
-```
+- 视觉契约落地（本轮有契约输入时必填，无则 N/A）：三份 CSS 已生成 → 目视对照差异 N 处（已改契约重新生成 / 待确认）
+```

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", "design-audit.mjs", "check.mjs", "apply-final-gate.mjs"];
+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;
 
 // ============================================================
@@ -266,11 +266,10 @@ function installSkills(targetKey, projectDir) {
     }
   }
 
-  // design-apply 能力组依赖：mapping/ 词典 + parser/ 解析器（变更集落地的运行时依赖）
-  // parser/fixtures/ 为作者侧回归夹具（A-O 回归步骤的测试数据），不随技能分发，保留在仓库
-  for (const runtimeDir of ["mapping", "parser"]) {
-    const src = path.join(SKILL_DIR, runtimeDir);
-    if (fs.existsSync(src)) copyDir(src, path.join(dest, runtimeDir), ["fixtures"]);
+  // 视觉契约落地依赖：mapping/ 三列变量映射表（区域名 ↔ 项目现状对照）
+  const mappingSrc = path.join(SKILL_DIR, "mapping");
+  if (fs.existsSync(mappingSrc)) {
+    copyDir(mappingSrc, path.join(dest, "mapping"));
   }
 
   // Cursor：清理旧版 rules/*.mdc，避免与 skills 重复

package/mapping/admin.json

@@ -0,0 +1,60 @@
+{
+  "schema": "ui.var-map/1.0",
+  "$comment": "项目视觉变量映射表：契约区域名 ↔ 项目现状的对照。只有三列——scope（承载类名）/ var（项目侧尺寸变量，可选）/ fallback（缺区域时的占位值）。落点层级由契约的 host/inner 二分承载，优先级由 adapter 统一，形态由契约声明本身承载——本表不承载这三件事。",
+
+  "scene": "admin",
+  "stack": "vue3 + element-plus",
+  "adapter": "vue-element-plus",
+
+  "layoutHost": {
+    "path": "src/layout/lay-admin/index.vue",
+    "note": "退化为占位容器：只提供插槽，不参与布局决策。页面骨架由 ui-layout.css 的 .ui-page 网格决定。"
+  },
+
+  "regions": {
+    "sidebar": {
+      "scope": ".lay-sidebar",
+      "var": "--ui-sidebar-w",
+      "collapsedVar": "--ui-sidebar-w-collapsed",
+      "fallback": "208px"
+    },
+    "header": {
+      "scope": ".lay-header",
+      "var": "--ui-header-h",
+      "fallback": "54px"
+    },
+    "tabs": {
+      "scope": ".lay-tabs",
+      "var": "--ui-tabs-h",
+      "fallback": "40px"
+    },
+    "content": {
+      "scope": ".lay-content",
+      "var": "--ui-content-padding",
+      "fallback": "24px"
+    }
+  },
+
+  "penetrable": [
+    ".el-menu",
+    ".el-menu-item",
+    ".el-table",
+    ".el-table__cell",
+    ".el-table__empty-text",
+    ".el-input__wrapper",
+    ".el-select__wrapper",
+    ".el-tag",
+    ".el-pagination",
+    ".el-card__body",
+    ".el-dialog__body",
+    ".el-tabs__item",
+    ".el-date-editor",
+    ".el-range-input"
+  ],
+
+  "notes": [
+    "penetrable 是需要 inner 穿透的组件库前缀，由 adapter 提供语法，落地时按角色的 inner 落点选取对应目标。",
+    "var 字段是项目侧可选变量名：项目已有则复用（便于项目自身主题切换联动），没有则直接用契约值写入 ui-layout.css。",
+    "布局占位改造范围限定在布局组件的模板与样式层，业务插槽内的代码不动。"
+  ]
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.76",
+  "version": "1.2.2",
   "type": "module",
-  "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
+  "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块、视觉契约落地",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"
   },
@@ -15,8 +15,6 @@
     "references/",
     "scripts/",
     "mapping/",
-    "parser/",
-    "dist/",
     "SKILL.md",
     "README.md"
   ],
@@ -27,16 +25,9 @@
     "release": "node release.js",
     "release:minor": "node release.js minor",
     "release:major": "node release.js major",
-    "check": "node scripts/check.mjs",
-    "prepack": "node scripts/check.mjs",
-    "validate": "node scripts/validate.mjs",
-    "audit": "node scripts/design-audit.mjs",
-    "final-gate": "node scripts/apply-final-gate.mjs",
+    "check:landing": "node scripts/check-landing.mjs --project .",
     "match": "python scripts/match.py",
     "match:batch": "python scripts/match.py --batch",
-    "mapping:build": "node parser/index.js build",
-    "mapping:watch": "node parser/watch.js",
-    "regression": "node parser/regression.js",
     "postpublish": "echo 'Published @qilitt-mickey/vue3-temp-skill to npmjs.org'"
   },
   "keywords": [
@@ -49,7 +40,8 @@
     "element-plus",
     "vant",
     "pinia",
-    "vite"
+    "vite",
+    "visual-contract"
   ],
   "author": "qilitt",
   "license": "MIT",

package/references/adapters/_new-adapter.md

@@ -0,0 +1,88 @@
+---
+adapter: _new-adapter
+description: 新增 Vue 组件库适配的书写模板。照此填写即可接入一个未内置的 Vue 组件库，不接触契约。
+---
+
+# 新增 adapter · 书写模板
+
+项目用了本技能尚未覆盖的 **Vue 组件库**时，照此填写一份 adapter。**不改契约、不改核心编排、不改其他 adapter。**
+
+## 先确认三件事
+
+| 问题 | 为什么重要 |
+|---|---|
+| 深度选择器用什么语法？ | Vue 下都是 `:deep()`，但要写清是 SFC scoped 还是全局文件 |
+| 组件库类名前缀是什么？ | 决定 `inner[]` 的穿透目标怎么写 |
+| 三份 CSS 放哪、怎么全局引入？ | 决定样式接入方式 |
+
+答不出这三问，说明该组件库还没在项目里用起来——**先在项目里跑通再写 adapter**。
+
+## 填写模板
+
+```markdown
+---
+adapter: <组件库标识>
+description: <一句话说明>
+---
+
+# adapter · Vue 3 + <组件库名称>
+
+## 深度选择器语法
+| 场景 | 语法 |
+|---|---|
+| SFC `<style scoped>` | `:deep(.<前缀>-xxx)` |
+| 全局样式文件 | `.<前缀>-xxx` 直接写 |
+
+`ui-roles.css` 写成 <全局文件 / scoped>。
+
+## 内层穿透语法
+| 角色 | 穿透目标 |
+|---|---|
+| table.headerCell | <选择器> |
+| table.cell | <选择器> |
+
+规则：`host[]` 挂组件根元素；`inner[]` 定位内部文本盒。
+
+## 组件库前缀速查
+| 组件 | 前缀 | 角色类挂载位置 |
+|---|---|---|
+| <组件> | .<前缀> | <位置> |
+
+## 提权通道（唯一允许处）
+| 情况 | 处置 |
+|---|---|
+| 组件库行内 style 注入 | 该属性加 `!important`，仅此一处允许 |
+
+## 三份 CSS 的落点
+| 文件 | 落点 | 引入时机 |
+|---|---|---|
+| src/styles/ui-tokens.css | <目录> | <时机> |
+| src/styles/ui-roles.css | <目录> | <时机> |
+| src/styles/ui-layout.css | <目录> | <时机> |
+
+## 布局占位容器
+<如何让项目布局组件退化为插槽容器，给一段可粘贴的 Vue 模板>
+
+## 与内置 adapter 的差异
+<哪些角色的 inner 落点不同，为什么>
+```
+
+## adapter 的边界
+
+| 承载 | 禁止 |
+|---|---|
+| 深度选择器语法 | 定义设计意图 |
+| 组件库穿透前缀 | 定义风格 |
+| 提权通道的唯一出口 | 改写契约值 |
+| 三份 CSS 的落点与引入 | 修改契约结构 |
+| 布局占位挂载点 | 增加新字段 |
+
+**判据**：写完 adapter 后，同一份契约应能不改一行内容地落到用该组件库的项目。若需要改契约，说明 adapter 越界了。
+
+## 登记
+
+写完在 `design-apply.md` 的 adapter 选择表加一行：
+
+| 项目依赖 | adapter |
+|---|---|
+| `<组件库名>` | `adapters/<标识>.md` |