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

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.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
+
+- 修正架构边界文档中 L1/L2 的表述：L1 负责 Element Plus 原生组件族，L2 Project Vendors 是当前项目集群的必需覆盖层。
+- README 和架构文档明确 `Base*`、`jh-*`、`C_*`、AG Grid、自研封装和 custom wrappers 都必须按统一 tokens 与 Element Plus 基础视觉对齐，不应被理解为可选补丁。
+
 ## [1.6.7] - 2026-05-11
 
 ### Added

package/README.md

@@ -193,12 +193,13 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.6.7 版本重点强化“统一规则源 + 多编辑器分发 + 分层边界治理 + 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、vendors、layouts、runtime、scanner、skills 的扩展边界，避免胶水补丁污染
+- `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. 不动业务代码
@@ -396,11 +397,11 @@ AI 按 _flows/legacy-skin-align.md 严格 6 phase 执行：
 ### Skin 模式优先级（团队约定）
 
 ```
-Base* > jh-* > C_*/c_* > custom wrappers
+Base* > jh-* > C_*/c_* > AG Grid > custom wrappers
        (高)            (低)
 ```
 
-样式文件加载顺序在 `styles/vendors/index.scss` 中固化，确保高优先级覆盖低优先级。
+样式文件加载顺序在 `styles/vendors/index.scss` 中固化，确保高优先级覆盖低优先级。vendor 层不是可选补丁层，而是当前项目集群统一风格的必需适配层。
 
 ---
 
@@ -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
@@ -457,7 +470,7 @@ export const myRules = [
 
 ## Element Plus 组件族样式管控
 
-`wl-skills-ui` 的核心是样式绝对管控。加载 `styles`、`styles/presets/skin` 或 `styles/presets/element-only` 后，会统一覆盖首批 B 端高频 Element Plus 组件族：
+`wl-skills-ui` 的核心是样式绝对管控。加载 `styles`、`styles/presets/skin` 或 `styles/presets/element-only` 后，会先统一覆盖首批 B 端高频 Element Plus 组件族；基于 Element Plus 的 `Base*`、`jh-*`、`C_*`、AG Grid 等封装/组合组件由 `styles/vendors` 继续承接，确保当前项目集群不管怎么封装组装，都收敛到同一套视觉体系：
 
 | 组件族       | 覆盖标签                                                   | 典型场景                         |
 | ------------ | ---------------------------------------------------------- | -------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.6.7",
+  "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

@@ -7,7 +7,7 @@
 任何新增能力都必须遵守：
 
 - 单一事实源：同一类配置只能有一个权威来源。
-- 分层隔离：tokens、Element Plus 原子覆盖、vendor 封装覆盖、layouts、runtime、scanner、skills 各自负责自己的边界。
+- 分层隔离：tokens、Element Plus 原子覆盖、项目集群封装覆盖、layouts、runtime、scanner、skills 各自负责自己的边界。
 - 向下依赖：上层可以使用下层 token 和规范，下层不能反向依赖上层实现。
 - 覆盖有序：后写入和高优先级覆盖必须有明确目录和加载顺序，不能靠零散 `!important` 补丁堆叠。
 - 项目集群优先：当前风格先服务当前项目集群；未来多项目集群主题替换应通过 theme/tokens/preset 入口扩展，而不是修改组件规则本身。
@@ -17,8 +17,8 @@
 | 层级 | 目录 | 职责 | 不允许做的事 |
 | --- | --- | --- | --- |
 | L0 Design Tokens | `design/tokens`、`styles/tokens` | 定义颜色、圆角、间距、字号、阴影等基础变量 | 不写具体组件选择器，不绑定业务组件名 |
-| L1 Element Plus | `styles/element`、`skills/element` | 统一 Element Plus 原生组件视觉 | 不处理 `Base*`、`jh-*`、`C_*` 等封装私有结构 |
-| L2 Vendors | `styles/vendors`、`skills/vendors` | 覆盖业务项目封装组件和第三方组合组件 | 不重新定义品牌色体系，不覆盖 layout 骨架语义 |
+| L1 Element Plus | `styles/element`、`skills/element` | 统一 Element Plus 原生组件视觉，作为全部封装层的基础视觉规则 | 不把 `Base*`、`jh-*`、`C_*`、AG Grid 的私有选择器混入原子层 |
+| L2 Project Vendors | `styles/vendors`、`skills/vendors` | 必须覆盖当前项目集群里的 `Base*`、`jh-*`、`C_*`、自研封装、AG Grid 等封装/组合组件，使其继承同一套风格 | 不重新定义品牌色体系，不脱离 L0/L1 另起一套视觉规则，不覆盖 layout 骨架语义 |
 | L3 Layouts | `styles/layouts`、`skills/layouts`、`templates` | 约束列表页、树表页、表单弹窗等页面骨架 | 不改 token，不写 vendor 私有修复 |
 | L4 Runtime | `runtime`、`reference` | 提供 `defineColumns`、`renderOps`、preset 等业务渲染能力 | 不直接承担老项目 skin 化妆职责 |
 | Automation | `scanner`、`mcp` | 扫描、检查、dry-run 修复和 AI 工具入口 | 不绕过 skills/standards 私自定义新规则语义 |
@@ -72,14 +72,20 @@ styles/element/_upload.scss
 
 每个文件只处理对应组件族或强相关子组件。跨组件一致性通过 token 解决，例如表单圆角统一使用 `--wk-form-control-radius`，不能在 input、select、upload 中分别写不同硬编码。
 
-## Vendor 覆盖边界
+L1 的“不处理封装私有结构”不是“不覆盖封装组件”，而是要求封装组件进入 L2，由 L2 按当前项目集群真实封装形态做统一风格适配。
 
-vendor 层用于承接老项目封装和组合组件，优先级必须明确：
+## Project Vendors 覆盖边界
+
+Project Vendors 层是当前项目集群的必需覆盖层，不是可选补丁层。它用于承接所有基于 Element Plus 或与 Element Plus 共同组成页面的封装/组合组件，包括：
 
 ```text
-Base* > jh-* > C_*/c_* > custom wrappers
+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 通用（基础设施层）