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

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.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
+
+- 新增 `styles/vendors/_jh-ui.scss` 专项承接 `@jhlc/jh-ui` SCSS 皮肤包，覆盖 `.com-text` label 包裹、`.has-colon` 冒号注入、`.com-input` / `.com-textarea` 控件 wrapper 等 jh-ui 特有 DOM 模式。
+- 新增 Element Plus 2.2.x（`.el-input__inner` 直挂结构、无 `.el-input__wrapper`）下输入、选择、日期控件的圆角 / focus / error 三态规则，jh-select 与 jh-date-picker focus 表现稳定。
+- `skills/_meta/_compat/vendors.json` 在 jh vendor 下登记 `@jhlc/jh-ui` baseline 与 `_jh-ui.scss` 样式来源；`skills/vendors/jh-components/SKILL.md` 补齐识别表与全局样式来源。
+
 ## [1.6.13] - 2026-05-12
 
 ### Fixed

package/README.md

@@ -191,10 +191,31 @@ 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 假设 |
+
+新接入项目可执行 `npx wl-ui check --project .`（看 `I005`）或 MCP 工具 `wl_ui_detect_skin` 自动判断当前组合是否命中推荐。完整版本-项目实测表见 `docs/compat-matrix.md`。
+
+---
+
 ## 版本亮点
 
-当前 v1.6.13 版本继续强化“统一规则源 + 单一事实源 + 项目集群封装必覆盖 + UI 细节精准修复”的闭环，并补齐销售报价页暴露出的通用 UI 细节：
+当前 v1.7.0 版本聚焦“**项目集群依赖配对单一事实源 + AI/Skill 强约束识别**”：
 
+- 新增 `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 样式覆盖
 - 优化 BaseToolbar 下拉/分裂按钮组，让“主动作 + 下拉动作”按一个动作组展示，避免视觉割裂

package/docs/compat-matrix.md

@@ -0,0 +1,47 @@
+# 项目-依赖适配矩阵
+
+> 单一事实源，集团项目集群推荐版本与 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` 字段。
+- 本文档由 `scripts/check-docs.mjs` 校验：版本号必须与 `vendors.json` 一致，避免漂移。
+- scanner `I005` 接入完整性检查会按本表校验消费方项目是否使用推荐组合。
+- MCP 工具 `wl_ui_detect_skin` 直接读取消费方 `package.json` 给 AI 返回结构化结果。

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:
@@ -333,6 +348,14 @@ async function dispatchTool(id, name, args) {
       });
       return;
     }
+    if (name === "wl_ui_detect_skin") {
+      sendResult(id, {
+        content: [
+          { type: "text", text: JSON.stringify(detectSkin(args), 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.13",
+  "version": "1.7.0",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",
@@ -56,6 +56,7 @@
     "standards",
     "styles",
     "design",
+    "docs",
     "skills",
     "templates",
     "bin",

package/scanner/integration.mjs

@@ -7,9 +7,21 @@
  *   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";
+
+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）
@@ -140,6 +152,34 @@ export function checkIntegration(projectRoot) {
             : `peer 依赖缺失：${!hasVue ? "vue " : ""}${!hasEp ? "element-plus" : ""}`,
         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;
+        checks.push({
+          id: "I005",
+          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 || "未安装"}）`,
+          suggestion: ok
+            ? ""
+            : `推荐组合：@jhlc/jh-ui@${JH_COMPAT.jhUi} + element-plus@${JH_COMPAT.elementPlus}（详见 docs/compat-matrix.md）`,
+        });
+      } else {
+        checks.push({
+          id: "I005",
+          severity: "info",
+          ok: true,
+          description: "未检测到 @jhlc/jh-ui，跳过 jh-ui 配对校验",
+          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/vendors.json

@@ -31,13 +31,21 @@
         "jh-form",
         "jh-tree",
         "jh-pagination",
-        "jh-drag-col"
+        "jh-drag-col",
+        "@jhlc/jh-ui"
       ],
       "styles": [
+        "_jh-ui.scss",
         "_jh-tree.scss",
         "_jh-pagination.scss",
         "_jh-drag-col.scss"
-      ]
+      ],
+      "compat": {
+        "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

@@ -15,6 +15,7 @@ applyTo: "**/*.vue"
 
 | 类型 | 子组件 | 标签 | 关键类名 | 治理方式 |
 |---|---|---|---|---|
+| SCSS 皮肤适配 | `@jhlc/jh-ui` | — | `.com-text` / `.com-input` / `.com-textarea` / `.com-input-tip` | `styles/vendors/_jh-ui.scss` |
 | 专项样式覆盖 | jh-tree | `<jh-tree>` | `.jh-tree` / `.base-tree` | `styles/vendors/_jh-tree.scss` |
 | 专项样式覆盖 | jh-pagination | `<jh-pagination>` | `.jh-pagination` | `styles/vendors/_jh-pagination.scss` |
 | 专项样式覆盖 | jh-drag-col | `<jh-drag-col>` | `.drag-col-container` / `.drag-left` / `.slider-col` | `styles/vendors/_jh-drag-col.scss` |
@@ -22,6 +23,24 @@ applyTo: "**/*.vue"
 | 通用规则治理 | jh-form | `<jh-form>` | `.jh-form` | 继承 L0 tokens + L1 form 视觉原则 |
 | 通用规则治理 | 其它 jh-* | `<jh-*>` | `.jh-*` / 组件内部 Element Plus 类 | 先按 jh 通用规则治理，复杂结构再升级专项样式 |
 
+### `@jhlc/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`）
@@ -42,6 +61,7 @@ applyTo: "**/*.vue"
 
 ## 全局样式来源
 
+- `styles/vendors/_jh-ui.scss`
 - `styles/vendors/_jh-tree.scss`
 - `styles/vendors/_jh-pagination.scss`
 - `styles/vendors/_jh-drag-col.scss`

package/styles/vendors/_jh-ui.scss

@@ -0,0 +1,102 @@
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// @jhlc/jh-ui adapter — L2 vendor 化妆层（项目集群专用）
+//
+// 背景
+//   `@jhlc/jh-ui@3.x` 是项目集群在用的 Element Plus SCSS 皮肤包，
+//   常与 Element Plus 2.2.x（如 `element-plus@2.2.6-prod.3`）配套使用。
+//   它对 Element Plus 的 DOM/选择器约定与社区版（2.6+）不一致：
+//
+//     1. 表单 label 文本被包成 `<span class="com-text">`，
+//        `.el-form-item__label` 自身是 `display: inline-flex`。
+//        → 直接在 label 上写 ellipsis 不生效，必须落到 `.com-text`。
+//     2. `.has-colon .el-form-item__label .com-text::after` 注入冒号。
+//        → ellipsis 容器必须给 `::after` 预留空间。
+//     3. 输入控件 DOM 为 `.el-input > .el-input__inner`（无 `.el-input__wrapper`）。
+//        → focus / error 必须命中 `.el-input__inner`，
+//          `.el-input__wrapper.is-focus` 这类 EP 2.6+ 规则在这里不生效。
+//     4. select 用 `.el-select .el-input > .el-input__inner`，
+//        focus 标志位为 `.el-select.is-focus` 或 `.el-input.is-focus`。
+//     5. `.com-input` / `.com-textarea` / `.com-input-tip` 是 jh-ui 的控件
+//        外层 wrapper，承载 form-item 的 has-tip / is-error 形态。
+//
+// 边界
+//   - 本文件只负责修复 jh-ui DOM 与 wl-skills-ui 统一规则的对接差异。
+//   - 不重复 jh-ui 已经设好的视觉（如下拉项 padding/radius、表单 margin-bottom）。
+//   - Element Plus 2.6+ 项目的 `.el-input__wrapper` 规则继续由
+//     `_base-components.scss` 统一处理。
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// 1) label 文本容器（.com-text） — 单行省略，允许收缩
+//    .el-form-item__label 在 jh-ui 中是 inline-flex，
+//    必须放开 min-width 才能让内部 .com-text 真的 shrink。
+.el-form-item__label {
+  min-width: 0;
+}
+
+.el-form-item__label > .com-text,
+.el-form-item__label .com-text {
+  display: inline-block;
+  min-width: 0;
+  max-width: 100%;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  vertical-align: middle;
+}
+
+// has-colon 模式下，.com-text::after 注入冒号，
+// 给一点 padding 避免冒号被 ellipsis 裁掉
+.has-colon .el-form-item__label > .com-text,
+.has-colon .el-form-item__label .com-text {
+  padding-right: 6px;
+}
+
+// 2) Element Plus 2.2.x 输入控件统一圆角（无 .el-input__wrapper）
+.el-input > .el-input__inner,
+.el-textarea > .el-textarea__inner,
+.el-date-editor > .el-input__inner {
+  border-radius: 6px;
+  transition: box-shadow 0.15s ease, border-color 0.15s ease;
+}
+
+// 3) focus 品牌色边框（兼容 EP 2.2.x DOM 与 jh-select / jh-date-picker）
+.el-input.is-focus > .el-input__inner,
+.el-input > .el-input__inner:focus,
+.el-textarea.is-focus > .el-textarea__inner,
+.el-textarea > .el-textarea__inner:focus,
+.el-select.is-focus .el-input > .el-input__inner,
+.el-select .el-input.is-focus > .el-input__inner,
+.el-date-editor.is-focus > .el-input__inner,
+.el-date-editor .el-input.is-focus > .el-input__inner {
+  border-color: var(--el-color-primary, #2254f4) !important;
+  box-shadow: 0 0 0 1px var(--el-color-primary, #2254f4) inset;
+}
+
+// 4) error 红色边框（兼容 EP 2.2.x DOM；
+//    error label / message 颜色由 _base-components.scss 已统一处理）
+.el-form-item.is-error .el-input > .el-input__inner,
+.el-form-item.is-error .el-textarea > .el-textarea__inner,
+.el-form-item.is-error .el-date-editor > .el-input__inner {
+  border-color: var(--el-color-danger, #f56c6c) !important;
+  box-shadow: 0 0 0 1px var(--el-color-danger, #f56c6c) inset !important;
+}
+
+// 5) com-input / com-textarea / com-input-tip — jh-ui form-item wrapper
+//    保留 jh-ui 自身 margin-bottom、has-tip 间距，不覆盖；
+//    仅对齐内部输入控件圆角，避免在 wrapper 内 fallback 成方角。
+.com-input > .el-input > .el-input__inner,
+.com-input > .el-textarea > .el-textarea__inner,
+.com-textarea > .el-textarea > .el-textarea__inner {
+  border-radius: 6px;
+}
+
+// 6) 必填星号兼容 jh-ui label 结构
+//    Element Plus 把 `::before` 放在 `.el-form-item__label` 上，
+//    jh-ui 没改这一点；但 label 自身是 inline-flex，部分浏览器下
+//    `::before` 会作为 flex 项参与排版，必须显式声明颜色/显示。
+.el-form-item.is-required:not(.is-no-asterisk) > .el-form-item__label::before,
+.el-form-item.is-required:not(.is-no-asterisk) > .el-form-item__label::after,
+.el-form-item.is-required:not(.is-no-asterisk) > .el-form-item__label > .com-text::before,
+.el-form-item.is-required:not(.is-no-asterisk) > .el-form-item__label > .com-text::after {
+  color: var(--el-color-danger, #f56c6c) !important;
+}

package/styles/vendors/index.scss

@@ -9,6 +9,7 @@
 @forward './_ag-grid';           // AG Grid 完整主题
 @forward './_custom-wrappers';   // 兜底：野路子自封装
 @forward './_c-components';      // C_/c_ 前缀
+@forward './_jh-ui'; // @jhlc/jh-ui SCSS 皮肤包（EP 2.2.x + .com-text label）
 @forward './_jh-tree';           // jh-tree
 @forward './_jh-pagination';     // jh-pagination
 @forward './_jh-drag-col';       // jh-drag-col（含左树右表骨架）