@agile-team/wl-skills-ui 1.6.14 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.7.1] - 2026-05-12
+
+### Added
+
+- 新增 Vite 插件 `@agile-team/wl-skills-ui/vite`：消费方在 `vite.config.ts` 加一行 `wlSkillsCheck()` 即可在每次 `dev/build` 启动期自动校验 vendor 版本配对，偏离推荐组合时彩色打印警告与一键修复片段（`enforce: 'warn' | 'error' | 'silent'`）。
+- 新增 `npx wl-ui doctor --print-overrides` 子命令：检测到偏离时直接输出 pnpm/npm/yarn `overrides` JSON 片段，复制即可修复。
+- `skills/_meta/_compat/loader.mjs` 抽出共享 compat 加载器，统一 `evaluateVendor` / `buildOverridesSnippet` 语义，scanner、MCP、Vite、CLI 单源共用。
+- `vendors.json` 的 `compat` 升级为结构化 schema（`peers / gatingPeer / conflictsWith / domAssumptions`），同时保留旧平铺字段兜底；未来新增 vendor 配对无需改读取方代码。
+
+### Changed
+
+- scanner `I005` 改为遍历全部声明 `compat` 的 vendor，输出按 vendor 拆分的子检查项 `I005:<id>`，更易定位。
+- MCP `wl_ui_detect_skin` 返回结构升级：`vendors[].verdict`、`fixSnippet`、`summary` 统一暴露，AI 一次拿全多 vendor 评估结果。
+- `package.json` `files` 字段加入 `runtime/vite`，确保 Vite 插件随包发布。
+
+## [1.7.0] - 2026-05-12
+
+### Added
+
+- 新增 `docs/compat-matrix.md`：项目集群推荐版本与 wl-skills-ui 的适配矩阵单一事实源（`element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`）。
+- `skills/_meta/_compat/vendors.json` 在 `jh.compat` 字段钉死推荐 EP/jh-ui 版本与 EP 2.2 vs 2.3 DOM 差异说明。
+- scanner 接入完整性新增 `I005`：从 `vendors.json` 读取推荐版本，校验消费方 `package.json` 是否命中推荐组合。
+- MCP 新增 `wl_ui_detect_skin` 工具：读取项目 `package.json` 返回 `verdict (match / mismatch / no-jh-ui)` 与推荐 SCSS 列表。
+
+### Changed
+
+- `legacy-skin-align` flow 增加 Phase 0.5 强约束：写样式前必须先识别 jh-ui ↔ EP 版本配对。
+- `skills/vendors/jh-components/SKILL.md` 补全反例（`.el-input__wrapper.is-focus` 在 EP 2.2 永远命中不到等），并显式钉死推荐组合。
+- `scripts/check-docs.mjs` 扩展：`docs/compat-matrix.md` 的 EP/jh-ui 版本必须与 `vendors.json` 一致。
+- README 新增「项目-依赖适配矩阵速查」章节，引导消费方一键判断推荐组合是否命中。
+
 ## [1.6.14] - 2026-05-12
 
 ### Added

package/README.md

@@ -191,11 +191,44 @@ yarn add @agile-team/wl-skills-ui
 
 ---
 
+## 项目-依赖适配矩阵速查
+
+集团项目集群推荐组合（**单一事实源**：`docs/compat-matrix.md` + `skills/_meta/_compat/vendors.json` 的 `jh.compat`）：
+
+| 依赖 | 推荐版本 | 备注 |
+|---|---|---|
+| `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版；EP 2.3.0 起引入 `.el-input__wrapper`，与 jh-ui 3.x 不兼容 |
+| `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹 + `.has-colon` 冒号注入 |
+| `@agile-team/wl-skills-ui` | `^1.7.0` | 已对齐上述组合的 DOM 假设 |
+
+三种识别方式，任选其一：
+
+- **启动期自动**：`vite.config.ts` 加一行 `import { wlSkillsCheck } from '@agile-team/wl-skills-ui/vite'; export default defineConfig({ plugins: [wlSkillsCheck()] })`，每次 `dev/build` 偏离推荐组合时彩色打印警告（支持 `enforce: 'error'` 阻断）。
+- **手动 CLI**：`npx wl-ui check --project .` 看 `I005:<vendor>`；偏离时执行 `npx wl-ui doctor --print-overrides` 拿到可直接复制的 `pnpm.overrides` 修复片段。
+- **AI 协作**：MCP 工具 `wl_ui_detect_skin` 一次返回多 vendor 评估结果（`vendors[].verdict / fixSnippet / summary`）。
+
+完整版本-项目实测表见 `docs/compat-matrix.md`。
+
+---
+
 ## 版本亮点
 
-当前 v1.6.14 版本继续强化“统一规则源 + 单一事实源 + 项目集群封装必覆盖 + UI 细节精准修复”的闭环，并补齐销售报价页暴露出的通用 UI 细节：
+当前 v1.7.1 版本在 v1.7.0「单一事实源」基础上，把"识别"升级为"启动期自动 + 一键修复"：
+
+- 新增 Vite 插件 `@agile-team/wl-skills-ui/vite`：消费方一行配置即可在每次启动 dev/build 时自动跑版本配对校验，偏离时彩色提示 + 修复片段
+- 新增 `npx wl-ui doctor --print-overrides`：检测到偏离直接输出 pnpm/npm/yarn overrides JSON，复制粘贴即可修复
+- `vendors.json` `compat` 升级为 `peers / gatingPeer / conflictsWith / domAssumptions` 结构化 schema，未来新增 vendor 配对零代码改动
+- scanner `I005` 拆为 `I005:<vendor>`，MCP `wl_ui_detect_skin` 一次返回多 vendor 结果
+- 抽出 `skills/_meta/_compat/loader.mjs` 共享加载器，scanner/MCP/Vite/CLI 单源共用
+
+历史亮点（v1.7.0 起）：
 
-- 新增 `@jhlc/jh-ui` SCSS 皮肤包专项适配（`styles/vendors/_jh-ui.scss`），精准覆盖 `.com-text` label、`.com-input` / `.com-textarea` 控件 wrapper、`.has-colon` 冒号注入等 jh-ui 特有 DOM
+- 新增 `docs/compat-matrix.md` 作为项目集群推荐版本与 wl-skills-ui 的适配矩阵单一事实源；`skills/_meta/_compat/vendors.json` 在 `jh.compat` 字段钉死 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`
+- scanner 接入完整性新增 `I005`：基于 `vendors.json` 校验消费方 `package.json` 是否锚定推荐组合，偏离时给出明确建议
+- MCP 新增 `wl_ui_detect_skin` 工具，AI 写样式前可一键拿到 `verdict: match | mismatch | no-jh-ui` 与推荐 SCSS 列表
+- `legacy-skin-align` flow 增加 Phase 0.5 强约束：写样式前必须先识别版本配对；`jh-components` SKILL 补全反例（`.el-input__wrapper.is-focus` 在 EP 2.2 永远命中不到等）
+- `docs:check` 扩展校验：`docs/compat-matrix.md` 中的版本号必须与 `vendors.json` 同步，避免事实源漂移
+- 沿用 v1.6.14 的 `_jh-ui.scss` 适配层（`.com-text` label / EP 2.2.x `.el-input__inner` focus + error / 必填星号）
 - 兼容 Element Plus 2.2.x（`.el-input__inner` 直挂结构）下输入、选择、日期控件的圆角 / focus / error 三态，jh-select 与 jh-date-picker focus 行为稳定
 - 补强输入、选择、日期、文本域 focus 品牌色边框和必填星号红色显示规则，兼容 Element Plus 定制版本差异
 - 修复表单必填星号、错误 label、错误提示和错误边框红色态，避免校验反馈被通用 label/input 样式覆盖

package/bin/wl-ui.js

@@ -207,9 +207,16 @@ if (subcommand === "clean") {
 if (subcommand === "doctor") {
   const { values } = parseArgs({
     args: rawArgs,
-    options: { project: { type: "string", default: "." } },
+    options: {
+      project: { type: "string", default: "." },
+      "print-overrides": { type: "boolean", default: false },
+    },
     strict: false,
   });
+  if (values["print-overrides"]) {
+    await printOverrides(resolve(values.project));
+    process.exit(0);
+  }
   runDoctor(resolve(values.project));
   process.exit(0);
 }
@@ -895,6 +902,40 @@ function runClean(projectRoot, dryRun) {
   );
 }
 
+async function printOverrides(projectRoot) {
+  const pkgPath = join(projectRoot, "package.json");
+  if (!existsSync(pkgPath)) {
+    console.error(`[wl-ui doctor] 未找到 ${pkgPath}`);
+    process.exit(1);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const loader = await import("../skills/_meta/_compat/loader.mjs");
+  const vendors = loader.listCompatVendors();
+  const evaluations = vendors
+    .map((c) => loader.evaluateVendor(c, deps))
+    .filter((e) => e.verdict !== "not-applicable");
+  if (evaluations.length === 0) {
+    console.log(
+      "[wl-ui doctor] 当前项目未命中任何 vendor 适配矩阵，无需 overrides",
+    );
+    return;
+  }
+  const snippet = loader.buildOverridesSnippet(evaluations);
+  if (!snippet) {
+    console.log("[wl-ui doctor] 当前项目所有 vendor 配对已命中推荐组合 ✓");
+    return;
+  }
+  console.log(
+    "\n[wl-ui doctor --print-overrides] 检测到 vendor 版本偏离，复制以下片段到 package.json：\n",
+  );
+  console.log("// pnpm");
+  console.log(JSON.stringify(snippet.pnpm, null, 2));
+  console.log("\n// npm / yarn");
+  console.log(JSON.stringify(snippet.npmYarn, null, 2));
+  console.log("\n复制后执行：pnpm install（或对应包管理器的 install 命令）\n");
+}
+
 function runDoctor(projectRoot) {
   const pkgPath = join(projectRoot, "package.json");
   let pkg = null;
@@ -973,8 +1014,9 @@ wl-ui — @agile-team/wl-skills-ui 统一 CLI v${PKG.version}
                 对比已安装文件与 manifest
   wl-ui clean  [--project <path>] [--dry-run]
                 清理 wl-skills-ui 安装文件
-  wl-ui doctor [--project <path>]
-                检查安装状态 / MCP / 桥接 / 规范插件
+  wl-ui doctor [--project <path>] [--print-overrides]
+                检查安装状态 / MCP / 桥接 / 规范插件；
+                --print-overrides 时输出 vendor 版本偏离的 pnpm/npm/yarn overrides 修复片段
   wl-ui prompts
                 打印 AI 触发提示词
 

package/docs/compat-matrix.md

@@ -0,0 +1,68 @@
+# 项目-依赖适配矩阵
+
+> 单一事实源，集团项目集群推荐版本与 wl-skills-ui 适配关系。  
+> scanner / MCP / Skill 文档统一从本表派生。
+
+## 推荐版本（集团内推荐组合）
+
+| 依赖 | 推荐版本 | 说明 |
+|---|---|---|
+| `vue` | `~3.2.25` 或 `^3.2.25` | 与项目集群保持一致 |
+| `element-plus` | **`2.2.6-prod.3`** | 集团 jh- 定制版，搭配 `@jhlc/jh-ui` 使用，DOM 仍为 `.el-input > .el-input__inner` 直挂结构（**EP 2.3.0 起才引入 `.el-input__wrapper`**） |
+| `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹、`.has-colon ::after` 冒号注入、`.el-form-item--default { margin-bottom: 24px }` 等强约束 |
+| `@jhlc/common-core` | `3.1.0` 或 `3.1.0-prod.x` | 基础 util/types，`@jhlc/jh-ui` 间接依赖 |
+| `@agile-team/wl-skills-ui` | `^1.7.0` | 已对齐 jh-ui 3.1.0 + EP 2.2.6-prod.3 的 DOM 假设 |
+
+## 项目集群当前实测
+
+| 项目 | element-plus | @jhlc/jh-ui | 适配状态 |
+|---|---|---|---|
+| `wl-ui-sale` | `2.2.6-prod.3` | `3.1.0` | ✅ 推荐组合 |
+| `wl-ui-public` | `2.2.6-prod.3` | `3.1.0` | ✅ 推荐组合 |
+| `wl-ui-safe` | `2.2.6-prod.3` | `3.1.0` | ✅ 推荐组合 |
+| `wl-ui-security` | `2.2.6-prod.3` | `3.1.0` | ✅ 推荐组合 |
+| `wl-mdata` | `2.2.6-prod.3` | — | ⚠️ 仅 `@jhlc/common-core`，未装 jh-ui，本表 jh-ui 相关规则不生效 |
+
+## EP 2.2.x vs EP 2.3+ DOM 差异（适配关键依据）
+
+| 维度 | EP 2.2.x（jh-ui 配套） | EP 2.3+（社区主流） |
+|---|---|---|
+| 输入控件 | `.el-input > .el-input__inner` | `.el-input > .el-input__wrapper > .el-input__inner` |
+| focus 标志 | `.el-input.is-focus` / `.el-input__inner:focus` | `.el-input__wrapper.is-focus` / `:focus-within` |
+| select | `.el-select .el-input > .el-input__inner` | `.el-select__wrapper` |
+| 错误态 | `.el-form-item.is-error .el-input__inner` | `.el-form-item.is-error .el-input__wrapper` |
+| 表单 label | jh-ui 注入 `<span class="com-text">` 包裹文本 | EP 默认直接渲染文本节点 |
+
+## 适配建议
+
+- 集团内项目：**统一锚定 `element-plus@2.2.6-prod.3` + `@jhlc/jh-ui@3.1.0`**，与 wl-skills-ui v1.7.0 三方对齐。
+- 升级 `element-plus` 到 2.3+ 前，必须同步升级 `@jhlc/jh-ui` 到对应支持版本，否则 `.com-text` / `.el-input__inner` DOM 与 EP `__wrapper` 体系不兼容。
+- 新项目接入：见 README 「快速接入」章节，默认会按本表声明 peerDependency 范围。
+
+## 维护流程
+
+- 推荐版本字段统一在 `skills/_meta/_compat/vendors.json` 的 `vendors[id=jh].compat`（结构化 schema：`peers / gatingPeer / conflictsWith / domAssumptions`）。
+- 共享加载器 `skills/_meta/_compat/loader.mjs` 暴露 `listCompatVendors / evaluateVendor / buildOverridesSnippet`，scanner、MCP、Vite 插件、CLI 单源共用。
+- 本文档由 `scripts/check-docs.mjs` 校验：版本号必须与 `vendors.json` 一致，避免漂移。
+- scanner `I005:<vendor>` 接入完整性检查会按本表校验消费方项目是否使用推荐组合。
+- MCP 工具 `wl_ui_detect_skin` 直接读取消费方 `package.json` 给 AI 返回结构化结果。
+- Vite 插件 `@agile-team/wl-skills-ui/vite` 在启动期自动校验，无需手动调用。
+- `npx wl-ui doctor --print-overrides` 在检测到偏离时输出可直接复制的 pnpm/npm/yarn `overrides` 片段。
+
+## 启动期自动校验（推荐）
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { wlSkillsCheck } from '@agile-team/wl-skills-ui/vite';
+
+export default defineConfig({
+  plugins: [
+    wlSkillsCheck({
+      // enforce: 'warn' | 'error' | 'silent'  默认 'warn'
+      // includeVendors: ['jh']                  只校验指定 vendor
+      // verbose: true                            额外打印 match 项
+    }),
+  ],
+});
+```

package/docs/team-intro.md

@@ -0,0 +1,168 @@
+# @agile-team/wl-skills-ui — 团队接入指南
+
+> 版本：v1.6.0 · 适用：所有基于 Vue 3 + Element Plus 的业务子应用
+
+---
+
+## 我们现在有什么问题？
+
+各个子系统独自维护样式，导致：
+
+- 同一个按钮，各系统颜色/大小/间距都不一样
+- 弹窗、表格、分页、标签——每个系统长一个样
+- 模块联邦把各系统挂在同一个平台，视觉割裂感很强
+- 改一处要在多个仓库重复改，越改越乱
+
+---
+
+## 这个包解决什么？
+
+**一套 CSS + 一行导入，所有子系统统一视觉。**
+
+核心做三件事：
+
+| 能力 | 说明 |
+|------|------|
+| **设计令牌** | 统一定义颜色、按钮尺寸、间距、圆角、阴影。改一个变量，全系统生效 |
+| **样式化妆层** | 不改业务代码，直接覆盖 Element Plus 原生控件 + 内部封装组件（`Base*` / `jh-*` / `C_*` / `c_*` / AG Grid） |
+| **扫描 & 修复** | 自动扫描项目里哪些地方写死了颜色、不合规范，一键 dry-run 预览修复内容，确认后批量修复 |
+
+---
+
+## 两种接入方式，选一种就行
+
+### 方式 A — 化妆模式（推荐老项目，不动业务代码）
+
+适合：**项目已有大量业务代码，不想动**。一行样式导入，立刻对齐视觉。
+
+```bash
+pnpm add @agile-team/wl-skills-ui
+```
+
+```scss
+// src/styles/index.scss（或项目全局样式入口）
+@use "@agile-team/wl-skills-ui/styles/presets/skin" as *;
+```
+
+完成。刷新页面，按钮、表格、分页、弹窗、标签全部对齐统一风格。
+
+> **可以回退**：把这一行 `@use` 删掉，样式立刻恢复原状，零风险。
+
+---
+
+### 方式 B — 原生模式（推荐新项目 / 可以重构的项目）
+
+适合：**新项目，或者想进一步把业务写法也规范化**。
+
+```scss
+// src/styles/index.scss
+@use "@agile-team/wl-skills-ui/styles" as *;
+```
+
+```ts
+// src/main.ts
+import { installCommonPreset } from "@agile-team/wl-skills-ui/runtime/common-preset";
+installCommonPreset();
+```
+
+额外获得：
+- 状态字段（启用/禁用/审核/已验证）自动渲染为 Tag，不用手写模板
+- 操作列（查看/编辑/删除）按统一规范生成，不用每个页面重复写
+- 页面骨架（列表页/左树右表/弹窗表单/详情页）有现成模板
+
+---
+
+## 现在就能看效果吗？
+
+可以，3 分钟验证：
+
+```bash
+# 1. 安装
+pnpm add @agile-team/wl-skills-ui
+
+# 2. 在全局样式入口加一行
+#    @use "@agile-team/wl-skills-ui/styles/presets/skin" as *;
+
+# 3. 启动项目，浏览器看效果
+pnpm dev
+```
+
+如果效果不对 / 有冲突，删掉那一行即可完全还原。
+
+---
+
+## 想知道项目哪里不符合规范？先扫描
+
+```bash
+# 扫描 src 目录，输出报告
+npx wl-ui scan --target src --outFile ui-audit.md
+
+# 预览修复内容（不实际写入）
+npx wl-ui fix --target src --dry-run
+
+# 确认没问题，执行修复
+npx wl-ui fix --target src
+```
+
+扫描报告会告诉你：哪些文件写死了颜色、哪些按钮不合尺寸规范、哪些封装组件需要覆盖样式。
+
+---
+
+## 能回退吗？
+
+**完全可以，三个层面都支持回退：**
+
+| 操作 | 回退方式 |
+|------|----------|
+| 样式导入 | 删除 `@use` 那一行，立即恢复 |
+| 扫描修复 | 修复前有 `--dry-run` 预览；git 可随时 `revert` |
+| CLI 工具安装 | `npx wl-ui clean --project .` 一键卸载所有注入文件 |
+
+---
+
+## 各系统哪些组件会被统一？
+
+接入后，以下内容会自动对齐视觉（无需任何额外配置）：
+
+**Element Plus 原生控件**
+- 按钮颜色、尺寸、间距
+- 表格（行高、边框、斑马纹、操作列）
+- 表单（Label 宽度、输入框尺寸）
+- 弹窗（标题栏、底部按钮位置）
+- 分页（对齐方式、按钮样式）
+- Tag（颜色语义：成功/警告/危险/信息）
+- Card、Tabs、Tree、Drawer、Upload、Steps、Tooltip、Dropdown...
+
+**内部封装组件（有源码没源码都能覆盖）**
+- `BaseTable` / `BaseQuery` / `BaseToolbar` / `BaseDialog`
+- `jh-tree` / `jh-pagination` / `jh-drag-col`
+- `C_*` / `c_*` 前缀组件
+- AG Grid 表格主题
+
+---
+
+## 如果用了 AI 编辑器（Copilot / Cursor / Cline 等）
+
+可以一句话触发 AI 自动帮你把整个项目的样式对齐：
+
+```
+用 wl-ui 的 legacy-skin-align 流程对当前项目做老项目化妆对齐
+```
+
+AI 会按照 6 个阶段依次执行：接入 tokens → 引入 skin preset → 修复各类封装组件样式 → 修复 Element Plus 控件 → 修复硬编码颜色 → 全程不动业务逻辑。
+
+---
+
+## 安装一览
+
+```bash
+pnpm add @agile-team/wl-skills-ui
+```
+
+要求：Node ≥ 18，Vue ≥ 3.2，Element Plus ≥ 2.2
+
+NPM：[@agile-team/wl-skills-ui](https://www.npmjs.com/package/@agile-team/wl-skills-ui)
+
+---
+
+*有问题找杨晨誉，或直接群里说。*

package/mcp/server.js

@@ -83,6 +83,21 @@ const TOOLS = [
       required: ["text"],
     },
   },
+  {
+    name: "wl_ui_detect_skin",
+    description:
+      "读取目标项目 package.json，识别 @jhlc/jh-ui 与 element-plus 版本配对，返回适配矩阵建议。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project: {
+          type: "string",
+          description: "项目根目录，默认 WL_PROJECT_ROOT 或当前目录",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "wl_ui_recommend_flow",
     description:
@@ -113,6 +128,60 @@ function projectRoot(args = {}) {
   return resolve(args.project || process.env.WL_PROJECT_ROOT || process.cwd());
 }
 
+async function detectSkin(args = {}) {
+  const root = projectRoot(args);
+  const pkgPath = join(root, "package.json");
+  const fs = require("node:fs");
+  if (!fs.existsSync(pkgPath)) {
+    return { ok: false, reason: `未找到 ${pkgPath}` };
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const loader = await import("../skills/_meta/_compat/loader.mjs");
+  const vendors = loader.listCompatVendors();
+  const evaluations = vendors.map((c) => ({
+    compat: c,
+    evaluation: loader.evaluateVendor(c, deps),
+  }));
+  const applicable = evaluations.filter(
+    (e) => e.evaluation.verdict !== "not-applicable",
+  );
+  const overrides = loader.buildOverridesSnippet(
+    applicable.map((e) => e.evaluation),
+  );
+  return {
+    ok: true,
+    project: pkg.name,
+    vendors: evaluations.map(({ compat, evaluation }) => ({
+      vendorId: compat.vendorId,
+      vendorLabel: compat.vendorLabel,
+      gatingPeer: compat.gatingPeer,
+      verdict: evaluation.verdict,
+      peers: evaluation.peers,
+      conflictsWith: compat.conflictsWith,
+      domAssumptions: compat.domAssumptions,
+      note: compat.note,
+    })),
+    summary:
+      applicable.length === 0
+        ? "no-applicable-vendor"
+        : applicable.every((e) => e.evaluation.verdict === "match")
+          ? "all-match"
+          : "has-mismatch",
+    fixSnippet: overrides,
+    recommendedScss: applicable.some(
+      ({ compat }) => compat.vendorId === "jh" && deps["@jhlc/jh-ui"],
+    )
+      ? [
+          "styles/vendors/_jh-ui.scss",
+          "styles/vendors/_jh-tree.scss",
+          "styles/vendors/_jh-pagination.scss",
+          "styles/vendors/_jh-drag-col.scss",
+        ]
+      : ["styles/vendors/_base-components.scss"],
+  };
+}
+
 function runScanner(command, args = {}) {
   const root = projectRoot(args);
   const scanner = join(PKG_ROOT, "scanner", "index.mjs");
@@ -333,6 +402,13 @@ async function dispatchTool(id, name, args) {
       });
       return;
     }
+    if (name === "wl_ui_detect_skin") {
+      const result = await detectSkin(args);
+      sendResult(id, {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      });
+      return;
+    }
     if (name === "wl_ui_recommend_flow") {
       sendResult(id, {
         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.6.14",
+  "version": "1.7.1",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",
@@ -19,6 +19,7 @@
       "types": "./es/presets/security.d.ts"
     },
     "./runtime/presets/*": "./runtime/presets/*",
+    "./vite": "./runtime/vite/check.mjs",
     "./styles": "./styles/index.scss",
     "./styles/*": "./styles/*",
     "./design/tokens": "./design/tokens/index.css",
@@ -52,10 +53,12 @@
   "files": [
     "dist",
     "es",
+    "runtime/vite",
     "scanner",
     "standards",
     "styles",
     "design",
+    "docs",
     "skills",
     "templates",
     "bin",

package/runtime/vite/check.mjs

@@ -0,0 +1,130 @@
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// @agile-team/wl-skills-ui/vite — 启动期自检 Vite 插件
+//
+// 用法（消费方 vite.config.ts）：
+//   import { wlSkillsCheck } from '@agile-team/wl-skills-ui/vite';
+//   export default defineConfig({ plugins: [wlSkillsCheck()] });
+//
+// 选项：
+//   enforce: 'warn' | 'error' | 'silent'  默认 'warn'
+//   includeVendors: string[]              只校验指定 vendor id，默认全部
+//   verbose: boolean                       默认 false，true 时也打印 match 项
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  listCompatVendors,
+  evaluateVendor,
+  buildOverridesSnippet,
+} from "../../skills/_meta/_compat/loader.mjs";
+
+const C_RESET = "\x1b[0m";
+const C_YELLOW = "\x1b[33m";
+const C_RED = "\x1b[31m";
+const C_GREEN = "\x1b[32m";
+const C_DIM = "\x1b[2m";
+
+/**
+ * Vite 插件：启动期校验项目依赖是否锚定 wl-skills-ui 推荐组合
+ * @param {{enforce?: 'warn'|'error'|'silent', includeVendors?: string[], verbose?: boolean}} options
+ */
+export function wlSkillsCheck(options = {}) {
+  const enforce = options.enforce ?? "warn";
+  const includeVendors = options.includeVendors ?? null;
+  const verbose = options.verbose ?? false;
+  let hasRun = false;
+
+  return {
+    name: "wl-skills-ui:check",
+    configResolved(config) {
+      if (hasRun || enforce === "silent") return;
+      hasRun = true;
+      runCheck({
+        projectRoot: config.root,
+        enforce,
+        includeVendors,
+        verbose,
+        logger: config.logger,
+      });
+    },
+  };
+}
+
+function runCheck({ projectRoot, enforce, includeVendors, verbose, logger }) {
+  const pkgPath = join(projectRoot, "package.json");
+  if (!existsSync(pkgPath)) return;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return;
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const vendors = listCompatVendors().filter(
+    (v) => !includeVendors || includeVendors.includes(v.vendorId),
+  );
+
+  const mismatches = [];
+  const matches = [];
+  const evaluations = [];
+  for (const compat of vendors) {
+    const ev = evaluateVendor(compat, deps);
+    evaluations.push(ev);
+    if (ev.verdict === "match") matches.push({ compat, ev });
+    else if (ev.verdict === "mismatch") mismatches.push({ compat, ev });
+  }
+
+  if (verbose && matches.length > 0) {
+    const lines = matches.map(
+      ({ compat, ev }) =>
+        `  ${C_GREEN}✓${C_RESET} ${compat.vendorId}: ${ev.peers
+          .map((p) => `${p.name}@${p.actual}`)
+          .join(" + ")}`,
+    );
+    print(logger, "info", `${C_DIM}[wl-skills-ui] 适配矩阵命中：${C_RESET}\n${lines.join("\n")}`);
+  }
+
+  if (mismatches.length === 0) return;
+
+  const overrides = buildOverridesSnippet(evaluations);
+  const header =
+    enforce === "error"
+      ? `${C_RED}[wl-skills-ui] 启动期版本配对失败（enforce=error）${C_RESET}`
+      : `${C_YELLOW}[wl-skills-ui] 启动期版本配对警告${C_RESET}`;
+
+  const detail = mismatches
+    .map(({ compat, ev }) => {
+      const peers = ev.peers
+        .map(
+          (p) =>
+            `    - ${p.name}: 实际 ${p.actual || "未安装"} / 推荐 ${p.expected} ${p.ok ? `${C_GREEN}✓${C_RESET}` : `${C_RED}✗${C_RESET}`}`,
+        )
+        .join("\n");
+      return `  vendor=${compat.vendorId}\n${peers}\n    ${C_DIM}→ ${compat.note || ""}${C_RESET}`;
+    })
+    .join("\n\n");
+
+  const fix = overrides
+    ? `\n${C_DIM}修复建议（复制到 package.json）：${C_RESET}\n${C_DIM}${JSON.stringify(overrides.pnpm, null, 2)}${C_RESET}\n或执行：${C_DIM}npx wl-ui doctor --print-overrides${C_RESET}`
+    : "";
+
+  const message = `${header}\n${detail}${fix}`;
+
+  if (enforce === "error") {
+    print(logger, "error", message);
+    throw new Error("[wl-skills-ui] vendor 版本配对偏离推荐组合，详见上方提示");
+  } else {
+    print(logger, "warn", message);
+  }
+}
+
+function print(logger, level, msg) {
+  if (logger && typeof logger[level] === "function") {
+    logger[level](msg);
+  } else {
+    console[level === "error" ? "error" : "warn"](msg);
+  }
+}
+
+export default wlSkillsCheck;

package/scanner/integration.mjs

@@ -7,9 +7,18 @@
  *   I002 — main.scss / 全局入口是否引入 @agile-team/wl-skills-ui/styles 或 shared/index.scss
  *   I003 — src/util/ 是否有 ag-cell-renders.ts 或者 main.ts 中安装了 runtime
  *   I004 — element-plus 是否在 dependencies 中（peer 兼容）
+ *   I005 — @jhlc/jh-ui ↔ element-plus 版本配对是否符合推荐组合（vendors.json 单一事实源）
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { fileURLToPath } from "node:url";
+import {
+  listCompatVendors,
+  evaluateVendor,
+} from "../skills/_meta/_compat/loader.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 
 /**
  * @param {string} projectRoot — 项目根目录（包含 index.html / src / package.json）
@@ -140,6 +149,42 @@ export function checkIntegration(projectRoot) {
             : `peer 依赖缺失：${!hasVue ? "vue " : ""}${!hasEp ? "element-plus" : ""}`,
         suggestion: hasEp && hasVue ? "" : "pnpm add vue element-plus",
       });
+
+      // ── I005: vendor 配对（jh-ui / 未来 vendor 都走这条） ─────────────
+      const vendors = listCompatVendors();
+      let anyEvaluated = false;
+      for (const compat of vendors) {
+        const ev = evaluateVendor(compat, deps);
+        if (ev.verdict === "not-applicable") continue;
+        anyEvaluated = true;
+        const ok = ev.verdict === "match";
+        const actuals = ev.peers
+          .map((p) => `${p.name} ${p.actual || "未安装"}`)
+          .join(" + ");
+        const expecteds = ev.peers
+          .map((p) => `${p.name}@${p.expected}`)
+          .join(" + ");
+        checks.push({
+          id: `I005:${compat.vendorId}`,
+          severity: ok ? "info" : "warning",
+          ok,
+          description: ok
+            ? `${compat.vendorId} 推荐组合命中（${actuals}）`
+            : `${compat.vendorId} 版本配对偏离推荐（实际 ${actuals}）`,
+          suggestion: ok
+            ? ""
+            : `推荐组合：${expecteds}（详见 docs/compat-matrix.md，或执行 npx wl-ui doctor --print-overrides）`,
+        });
+      }
+      if (!anyEvaluated) {
+        checks.push({
+          id: "I005",
+          severity: "info",
+          ok: true,
+          description: "未命中任何已声明 compat 的 vendor，跳过配对校验",
+          suggestion: "",
+        });
+      }
     } catch {
       checks.push({
         id: "I004",

package/scripts/check-docs.mjs

@@ -97,6 +97,28 @@ if (existsSync(jhSkill)) {
   }
 }
 
+// compat-matrix.md ↔ vendors.json 一致性
+const vendorsJson = JSON.parse(
+  readFileSync(join(root, "skills", "_meta", "_compat", "vendors.json"), "utf8"),
+);
+const jhCompat = vendorsJson.vendors.find((v) => v.id === "jh")?.compat || {};
+const compatMatrixPath = join(root, "docs", "compat-matrix.md");
+if (existsSync(compatMatrixPath)) {
+  const matrix = readFileSync(compatMatrixPath, "utf8");
+  if (jhCompat.elementPlus && !matrix.includes(jhCompat.elementPlus)) {
+    errors.push(
+      `docs/compat-matrix.md: 缺少推荐 element-plus 版本 ${jhCompat.elementPlus}（与 vendors.json jh.compat 不一致）`,
+    );
+  }
+  if (jhCompat.jhUi && !matrix.includes(jhCompat.jhUi)) {
+    errors.push(
+      `docs/compat-matrix.md: 缺少推荐 @jhlc/jh-ui 版本 ${jhCompat.jhUi}（与 vendors.json jh.compat 不一致）`,
+    );
+  }
+} else {
+  errors.push("docs/compat-matrix.md: 文件不存在，无法校验适配矩阵");
+}
+
 if (!readme.includes(`当前 v${pkg.version}`)) {
   errors.push(
     `README.md: 当前版本文案未同步 package.json version ${pkg.version}`,

package/skills/_flows/legacy-skin-align.md

@@ -27,6 +27,20 @@ npx wl-ui doctor --project .
 
 （AI 严格按序）
 
+### Phase 0.5 — 识别 jh-ui ↔ Element Plus 版本配对（强约束）
+
+在写任何样式前，**必须先**通过下列任一方式确认推荐组合命中情况：
+
+- MCP：调用 `wl_ui_detect_skin`，读取项目 `package.json` 返回 `verdict`（`match` / `mismatch` / `no-jh-ui`）。
+- CLI：执行 `npx wl-ui check --project .`，关注 `I005` 项。
+- 文档：对照 `docs/compat-matrix.md` 的「推荐版本」表。
+
+判定规则：
+
+- `verdict === "match"`（推荐组合）：`_jh-ui.scss` 等 EP 2.2.x 适配规则可全量启用。
+- `verdict === "mismatch"`（版本偏离）：禁止套用 EP 2.6+ `.el-input__wrapper` 规则；先与项目方对齐版本再继续 Phase 1。
+- `verdict === "no-jh-ui"`：无需启用 `_jh-ui.scss`，按 EP 默认 DOM 处理。
+
 ### Phase 1 — 接入 tokens
 1. 检查 `index.html`，在 `<head>` 内追加：
    ```html

package/skills/_meta/_compat/loader.mjs

@@ -0,0 +1,96 @@
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// vendors.json 适配矩阵共享加载器
+//
+// 所有读取方（scanner I005 / MCP wl_ui_detect_skin / Vite 插件 / bin doctor /
+// scripts/check-docs.mjs）统一从这里取数据，避免逻辑漂移。
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VENDORS_JSON_PATH = join(__dirname, "vendors.json");
+
+let _cache = null;
+
+/** 加载 vendors.json（带进程内缓存） */
+export function loadVendorsJson() {
+  if (_cache) return _cache;
+  _cache = JSON.parse(readFileSync(VENDORS_JSON_PATH, "utf8"));
+  return _cache;
+}
+
+/** 规范化单个 vendor 的 compat（兼容旧平铺字段） */
+export function normalizeCompat(vendor) {
+  const c = vendor?.compat;
+  if (!c) return null;
+  const peers = c.peers || {};
+  // 旧平铺字段兜底
+  if (!peers["element-plus"] && c.elementPlus) {
+    peers["element-plus"] = c.elementPlus;
+  }
+  if (!peers["@jhlc/jh-ui"] && c.jhUi) {
+    peers["@jhlc/jh-ui"] = c.jhUi;
+  }
+  return {
+    vendorId: vendor.id,
+    vendorLabel: vendor.label,
+    peers,
+    gatingPeer: c.gatingPeer || Object.keys(peers).find((k) => k.startsWith("@")) || null,
+    conflictsWith: c.conflictsWith || [],
+    domAssumptions: c.domAssumptions || [],
+    note: c.note || "",
+  };
+}
+
+/** 返回所有声明了 compat 的 vendor */
+export function listCompatVendors() {
+  const { vendors = [] } = loadVendorsJson();
+  return vendors.map(normalizeCompat).filter(Boolean);
+}
+
+/**
+ * 针对一个项目的 dependencies + devDependencies 判定 vendor 配对状态
+ * @returns {{vendorId, gatingInstalled, peers: Array<{name, expected, actual, ok}>, verdict}}
+ *   verdict: 'match' | 'mismatch' | 'not-applicable'
+ */
+export function evaluateVendor(compat, deps) {
+  const gating = compat.gatingPeer;
+  const gatingInstalled = gating ? Boolean(deps[gating]) : true;
+  if (gating && !gatingInstalled) {
+    return {
+      vendorId: compat.vendorId,
+      gatingInstalled: false,
+      peers: [],
+      verdict: "not-applicable",
+    };
+  }
+  const peers = Object.entries(compat.peers).map(([name, expected]) => {
+    const actual = deps[name] || null;
+    const ok = !!actual && actual.includes(expected);
+    return { name, expected, actual, ok };
+  });
+  const allOk = peers.every((p) => p.ok);
+  return {
+    vendorId: compat.vendorId,
+    gatingInstalled: true,
+    peers,
+    verdict: allOk ? "match" : "mismatch",
+  };
+}
+
+/** 输出 pnpm overrides 修复片段（仅对 mismatch 的 peers） */
+export function buildOverridesSnippet(evaluations) {
+  const overrides = {};
+  for (const ev of evaluations) {
+    if (ev.verdict !== "mismatch") continue;
+    for (const p of ev.peers) {
+      if (!p.ok) overrides[p.name] = p.expected;
+    }
+  }
+  if (Object.keys(overrides).length === 0) return null;
+  return {
+    pnpm: { overrides },
+    npmYarn: { resolutions: overrides, overrides },
+  };
+}

package/skills/_meta/_compat/vendors.json

@@ -39,7 +39,30 @@
         "_jh-tree.scss",
         "_jh-pagination.scss",
         "_jh-drag-col.scss"
-      ]
+      ],
+      "compat": {
+        "peers": {
+          "element-plus": "2.2.6-prod.3",
+          "@jhlc/jh-ui": "3.1.0"
+        },
+        "gatingPeer": "@jhlc/jh-ui",
+        "conflictsWith": [
+          {
+            "name": "element-plus",
+            "rangeNote": ">=2.3.0",
+            "reason": "EP 2.3.0 起引入 .el-input__wrapper，与 jh-ui 3.x 假设的 .el-input>.el-input__inner DOM 不兼容"
+          }
+        ],
+        "domAssumptions": [
+          ".el-input>.el-input__inner",
+          ".el-form-item__label>.com-text",
+          ".has-colon .com-text::after"
+        ],
+        "elementPlus": "2.2.6-prod.3",
+        "elementPlusRange": "<2.3.0",
+        "jhUi": "3.1.0",
+        "note": "jh-ui 3.x 假设 EP 2.2.x DOM (.el-input>.el-input__inner)，EP 2.3 起引入 .el-input__wrapper 后不再兼容"
+      }
     },
     {
       "id": "c",

package/skills/vendors/jh-components/SKILL.md

@@ -25,13 +25,22 @@ applyTo: "**/*.vue"
 
 ### `@jhlc/jh-ui` SCSS 皮肤包识别
 
-项目同时安装 `@jhlc/jh-ui` 与 `element-plus`（常为 `2.2.6-prod.3` 定制版）时，输入控件 DOM 为 `.el-input > .el-input__inner`（无 `.el-input__wrapper`），表单 label 文本被包成 `<span class="com-text">`，并由 `.has-colon .com-text::after` 注入冒号。`_jh-ui.scss` 已经精准覆盖：
+**推荐组合（钉死版本）**：`@jhlc/jh-ui@3.1.0` + `element-plus@2.2.6-prod.3`。详见 `docs/compat-matrix.md` 与 `skills/_meta/_compat/vendors.json` 的 `jh.compat` 字段。
+
+项目同时安装 `@jhlc/jh-ui` 与 `element-plus@2.2.x` 时，输入控件 DOM 为 `.el-input > .el-input__inner`（**无 `.el-input__wrapper`**，EP 2.3.0 起才引入），表单 label 文本被包成 `<span class="com-text">`，并由 `.has-colon .com-text::after` 注入冒号。`_jh-ui.scss` 已精准覆盖：
 
 - label `.com-text` 单行省略 + has-colon 冒号保留
 - EP 2.2.x `.el-input__inner` 圆角 / focus / error 三态
 - jh-select / jh-date-picker 的 `.el-select.is-focus` / `.el-input.is-focus` 兼容
 - 必填星号在 inline-flex label 下显式声明颜色
 
+**反例**（常见错误覆盖姿势）：
+
+- ❌ 在 jh-ui 项目里用 `.el-input__wrapper.is-focus` —— EP 2.2.x 没有 `__wrapper`，规则永不生效。
+- ❌ 直接给 `.el-form-item__label` 写 `text-overflow: ellipsis` —— jh-ui 把它设为 `inline-flex`，文本在 `.com-text` 里，省略不会触发。
+- ❌ 给 `.el-form-item__label` 加 `padding-right` 期望腾出冒号位 —— 冒号是 `.com-text::after`，应在 `.com-text` 上加 padding。
+- ❌ 在不确定 EP 版本的情况下下笔修复 —— 必须先跑 `wl_ui_detect_skin` 或 `wl-ui check` 看 I005 结果。
+
 ## Diagnose
 
 - ❌ 自行给 `.jh-tree` 写颜色覆盖（应用全局 `vendors/_jh-tree.scss`）