@agile-team/wl-skills-ui 1.6.8 → 1.6.9

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.6.9] - 2026-05-11
+
+### Changed
+
+- `vendors/jh-components` 明确采用 `<jh-*>` 全量通配治理，当前文档中的 `jh-table`、`jh-form`、`jh-tree`、`jh-pagination`、`jh-drag-col` 仅作为代表性基线，不是完整清单。
+- README、架构边界和检测速查表补齐复杂 `jh-*` 封装升级为专项样式覆盖的准入条件，避免盲目穷举或局部补丁污染。
+- 同步 `styles/vendors/index.scss` 中 Base、jh、C、AG Grid、custom wrappers 的 L2 优先级注释。
+
 ## [1.6.8] - 2026-05-11
 
 ### Changed

package/README.md

@@ -193,12 +193,13 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.6.8 版本重点强化“统一规则源 + 多编辑器分发 + 项目集群封装必覆盖 + UI 细节精准修复”的闭环：
+当前 v1.6.9 版本重点强化“统一规则源 + 多编辑器分发 + 项目集群封装必覆盖 + UI 细节精准修复”的闭环：
 
 - `skills/**/*.md` 作为唯一规则源，`wl-ui init/update` 会按编辑器格式转换并覆盖写入目标 rules
 - `skills/_meta/_compat/editors.json` 作为 AI 编辑器安装配置唯一来源，CLI 不再维护第二份编辑器路径映射
 - `wl-ui update --editor all --force` 可一次性刷新全部支持编辑器；未指定编辑器时会刷新 manifest 与项目中已存在的编辑器规则目录
 - `standards/architecture/01-layer-boundaries.md` 固化 tokens、Element Plus、Project Vendors、layouts、runtime、scanner、skills 的扩展边界，明确 `Base*` / `jh-*` / `C_*` / AG Grid 是当前项目集群必覆盖层
+- `vendors/jh-components` 使用 `<jh-*>` 全量通配治理，当前只维护代表性基线和专项覆盖准入，避免遗漏新增 jh 封装
 - `npm run docs:check` 校验旧命名、旧命令、版本文案和编辑器配置，防止规则文档回退
 - 表格空状态改为对应表格区域内自适应居中，避免嵌套表格靠固定高度猜效果
 - 查询区/工具栏按钮补齐 token fallback，禁用按钮独立保留清晰禁用态
@@ -380,7 +381,7 @@ wl-ui add-preset <name>     # 脚手架新业务 preset
 AI 按 _flows/legacy-skin-align.md 严格 6 phase 执行：
   1. 接入 tokens
   2. 接入 skin preset
-  3. 触发 vendors/* skill 修复（按优先级 Base > jh > C_ > custom）
+  3. 触发 vendors/* skill 修复（按优先级 Base > jh-* > C_ > AG Grid > custom）
   4. 触发 element/* skill 修复
   5. 触发 tokens/* 规则修复
   6. 不动业务代码
@@ -427,14 +428,26 @@ installMyBizPreset();
 4. 在 `skills/_meta/_detection.md` 追加识别特征
 5. 在 `scanner/rules/` 追加规则（带 `category: 'vendor-xxx'`，自动获得 `layer:'L2'`）
 
-### 3. 新增一类页面骨架
+### 3. 新增复杂 jh-* 封装专项覆盖
+
+`<jh-*>` 默认已由 `vendors/jh-components` 全量识别。只有当某个 jh 组件满足以下条件之一时，才升级为专项样式：
+
+1. 内部包含多个 Element Plus 组件或复杂 DOM
+2. 默认样式明显偏离当前项目集群 tokens / spacing / radius
+3. 高频出现在列表、树表、弹窗、详情、上传、流程等核心页面
+4. scanner 或人工审计反复发现相同视觉问题
+5. AI 按通用 jh 规则无法稳定修复
+
+专项覆盖落地时，新增 `styles/vendors/_jh-xxx.scss`，并同步 `skills/vendors/jh-components/SKILL.md` 的代表性基线。
+
+### 4. 新增一类页面骨架
 
 1. 在 `styles/layouts/` 新建 `_xxx.scss`
 2. 在 `styles/layouts/index.scss` `@forward` 进去
 3. 在 `templates/xxx/` 新建 `TPL-XXX.md`
 4. 在 `skills/layouts/xxx/` 新建 `SKILL.md`
 
-### 4. 新增一条扫描规则
+### 5. 新增一条扫描规则
 
 ```js
 // scanner/rules/my-rule.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.6.8",
+  "version": "1.6.9",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/skills/_meta/_detection.md

@@ -31,7 +31,7 @@
 | ---------------------------------------------------------------------- | ------ | ------------------------------------------ |
 | `<BaseTable>` `<base-table>` `<BaseDataTable>`                         | #1     | vendors/base-table                         |
 | `<BaseQuery>` `<BaseToolbar>` `<base-*>` 其它                          | #1     | vendors/base-components（暂随 base-table） |
-| `<jh-table>` `<jh-form>` `<jh-tree>` `<jh-pagination>` `<jh-drag-col>` | #2     | vendors/jh-components                      |
+| `<jh-*>` 全量通配；代表性基线含 `jh-table` / `jh-form` / `jh-tree` / `jh-pagination` / `jh-drag-col` | #2     | vendors/jh-components                      |
 | `<C_*>` `<c-*>`                                                        | #3     | vendors/c-components                       |
 | `src/components/PascalCase.vue` 无前缀                                 | #4     | vendors/custom-wrappers                    |
 | `.ag-root-wrapper` / AG Grid API                                       | —      | vendors/ag-grid                            |

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

@@ -1,6 +1,6 @@
 ---
 description: |
-  jh-* 前缀的封装组件系列（jh-form / jh-table / jh-tree / jh-pagination / jh-drag-col 等）
+  jh-* 前缀的封装组件系列（不限于 jh-form / jh-table / jh-tree / jh-pagination / jh-drag-col）
   的识别、诊断和修复规则。Layer L2，优先级 #2（次于 Base*）。
 applyTo: "**/*.vue"
 ---
@@ -11,13 +11,16 @@ applyTo: "**/*.vue"
 
 ## Detect（识别）
 
-| 子组件 | 标签 | 关键类名 |
-|---|---|---|
-| jh-table | `<jh-table>` | `.jh-table` |
-| jh-form | `<jh-form>` | `.jh-form` |
-| jh-tree | `<jh-tree>` | `.jh-tree` / `.base-tree` |
-| jh-pagination | `<jh-pagination>` | `.jh-pagination` |
-| jh-drag-col | `<jh-drag-col>` | `.drag-col-container` / `.drag-left` / `.slider-col` |
+所有 `<jh-*>` 标签均归入本 Skill。下表是当前项目集群的代表性基线，不是完整清单。
+
+| 类型 | 子组件 | 标签 | 关键类名 | 治理方式 |
+|---|---|---|---|---|
+| 专项样式覆盖 | 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` |
+| 通用规则治理 | jh-table | `<jh-table>` | `.jh-table` | 继承 L0 tokens + L1 table 视觉原则 |
+| 通用规则治理 | jh-form | `<jh-form>` | `.jh-form` | 继承 L0 tokens + L1 form 视觉原则 |
+| 通用规则治理 | 其它 jh-* | `<jh-*>` | `.jh-*` / 组件内部 Element Plus 类 | 先按 jh 通用规则治理，复杂结构再升级专项样式 |
 
 ## Diagnose
 
@@ -25,6 +28,7 @@ applyTo: "**/*.vue"
 - ❌ jh-drag-col 内自定义 padding 破坏拖拽条对齐
 - ❌ jh-pagination 未对齐到右侧（同 R011）
 - ❌ jh-form 内不用 `size="small"` 控件（同 R006）
+- ❌ 发现新的复杂 `<jh-*>` 组件后只在页面局部写补丁，而不沉淀到 L2 Project Vendors
 
 ## Repair
 
@@ -34,9 +38,20 @@ applyTo: "**/*.vue"
 
 ### B 类
 - 直接全局覆盖 `.jh-*` → 改为引入 `wl-skills-ui/styles` 由 vendors 层处理
+- 新的复杂 `<jh-*>` 组件 → 先判断是否只是 Element Plus 薄封装；若不是，应新增 `styles/vendors/_jh-xxx.scss` 和对应 Skill/检测规则
 
 ## 全局样式来源
 
 - `styles/vendors/_jh-tree.scss`
 - `styles/vendors/_jh-pagination.scss`
 - `styles/vendors/_jh-drag-col.scss`
+
+## 新增 jh 专项覆盖准入
+
+满足任一条件时，应从通用规则治理升级为专项样式覆盖：
+
+- 组件内部包含多个 Element Plus 组件或复杂 DOM 结构
+- 默认样式明显偏离当前项目集群 tokens / spacing / radius
+- 高频出现在列表、树表、弹窗、详情、上传、流程等核心页面
+- scanner 或人工审计反复发现相同视觉问题
+- AI 按通用规则无法稳定修复

package/standards/architecture/01-layer-boundaries.md

@@ -84,6 +84,8 @@ Base* > jh-* > C_*/c_* > AG Grid > custom wrappers
 
 这些组件虽然不是 Element Plus 原生选择器，但在当前项目集群中同样属于统一 UI 风格体系的一部分，必须使用 L0 tokens 和 L1 组件视觉原则进行对齐。
 
+`jh-*` 采用通配治理：所有 `<jh-*>` 标签先统一归入 `vendors/jh-components`。当前只维护代表性基线与专项覆盖准入，避免为了追求清单完整而制造过期枚举；当某个 jh 组件复杂、高频或反复出现视觉偏差时，再沉淀为 `styles/vendors/_jh-xxx.scss` 专项覆盖。
+
 新增 vendor 覆盖时应同时补齐：
 
 1. `styles/vendors/_xxx.scss`

package/styles/vendors/index.scss

@@ -2,7 +2,7 @@
 //
 // 加载顺序：从最高优先级到兜底（同选择器特异性下，后加载会覆盖前面）
 // 优先级约定（v3 团队规范）：
-//   Base*  >  jh-*  >  C_*/c_*  >  custom wrappers
+//   Base*  >  jh-*  >  C_*/c_*  >  AG Grid  >  custom wrappers
 // → 但 SCSS 加载顺序里我们反过来：兜底先加载，让高优先级覆盖
 
 @forward './_portal';            // 弹层/popper 通用（基础设施层）