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

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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

package/README.md

@@ -201,13 +201,27 @@ yarn add @agile-team/wl-skills-ui
 | `@jhlc/jh-ui` | **`3.1.0`** | SCSS 皮肤包，`.com-text` label 包裹 + `.has-colon` 冒号注入 |
 | `@agile-team/wl-skills-ui` | `^1.7.0` | 已对齐上述组合的 DOM 假设 |
 
-新接入项目可执行 `npx wl-ui check --project .`（看 `I005`）或 MCP 工具 `wl_ui_detect_skin` 自动判断当前组合是否命中推荐。完整版本-项目实测表见 `docs/compat-matrix.md`。
+三种识别方式，任选其一：
+
+- **启动期自动**：`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.7.0 版本聚焦“**项目集群依赖配对单一事实源 + AI/Skill 强约束识别**”：
+当前 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 起）：
 
 - 新增 `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` 是否锚定推荐组合，偏离时给出明确建议

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

@@ -41,7 +41,28 @@
 
 ## 维护流程
 
-- 推荐版本字段统一在 `skills/_meta/_compat/vendors.json` 的 `vendors[id=jh].compat` 字段。
+- 推荐版本字段统一在 `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` 接入完整性检查会按本表校验消费方项目是否使用推荐组合。
+- 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/mcp/server.js

@@ -128,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");
@@ -349,10 +403,9 @@ 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(detectSkin(args), null, 2) },
-        ],
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
       });
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.7.0",
+  "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,6 +53,7 @@
   "files": [
     "dist",
     "es",
+    "runtime/vite",
     "scanner",
     "standards",
     "styles",

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

@@ -12,16 +12,13 @@
 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);
-const VENDORS_JSON = JSON.parse(
-  readFileSync(
-    join(__dirname, "..", "skills", "_meta", "_compat", "vendors.json"),
-    "utf8",
-  ),
-);
-const JH_COMPAT = VENDORS_JSON.vendors.find((v) => v.id === "jh")?.compat || {};
 
 /**
  * @param {string} projectRoot — 项目根目录（包含 index.html / src / package.json）
@@ -153,30 +150,38 @@ export function checkIntegration(projectRoot) {
         suggestion: hasEp && hasVue ? "" : "pnpm add vue element-plus",
       });
 
-      // ── I005: jh-ui ↔ element-plus 版本配对 ──────────────────────────
-      const jhUi = deps["@jhlc/jh-ui"];
-      const ep = deps["element-plus"];
-      if (jhUi) {
-        const epOk = ep && ep.includes(JH_COMPAT.elementPlus || "2.2.6-prod.3");
-        const jhOk = jhUi.includes(JH_COMPAT.jhUi || "3.1.0");
-        const ok = epOk && jhOk;
+      // ── 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",
+          id: `I005:${compat.vendorId}`,
           severity: ok ? "info" : "warning",
           ok,
           description: ok
-            ? `jh-ui 推荐组合命中（@jhlc/jh-ui ${jhUi} + element-plus ${ep}）`
-            : `jh-ui 版本配对偏离推荐（实际 @jhlc/jh-ui ${jhUi} + element-plus ${ep || "未安装"}）`,
+            ? `${compat.vendorId} 推荐组合命中（${actuals}）`
+            : `${compat.vendorId} 版本配对偏离推荐（实际 ${actuals}）`,
           suggestion: ok
             ? ""
-            : `推荐组合：@jhlc/jh-ui@${JH_COMPAT.jhUi} + element-plus@${JH_COMPAT.elementPlus}（详见 docs/compat-matrix.md）`,
+            : `推荐组合：${expecteds}（详见 docs/compat-matrix.md，或执行 npx wl-ui doctor --print-overrides）`,
         });
-      } else {
+      }
+      if (!anyEvaluated) {
         checks.push({
           id: "I005",
           severity: "info",
           ok: true,
-          description: "未检测到 @jhlc/jh-ui，跳过 jh-ui 配对校验",
+          description: "未命中任何已声明 compat 的 vendor，跳过配对校验",
           suggestion: "",
         });
       }

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

@@ -41,6 +41,23 @@
         "_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",