@agile-team/wl-skills-kit 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [2.5.0] - 2026-05-07
+
+### Added
+
+- 强化 page-codegen 模板，统一 `BaseTable render-type="agGrid"`、唯一 `cid`、`defineColumns()` 和 `renderOps()` 标准写法。
+- 增强菜单同步、项目工具和 MCP 工作流能力，补齐 17 个 MCP Tool 的 README 描述。
+
+### Changed
+
+- 同步 README、Copilot 指南、Skill registry、page-codegen 文档和菜单同步文档。
+- 明确 `wl-skills-kit` 与 `wk-skills-ui` 的协作边界：kit 负责规范化生成，ui 负责样式绝对管控。
+
+## [2.4.2] - 2026-05-05
+
+### Changed
+
+- 更新 README、业务项目指南、架构说明和多编辑器兼容文档，补齐 2.4.x 生命周期、MCP、manifest、规范插件和桥接说明
+- 同步版本文案到 2.4.2，避免发布文档仍停留在 2.4.0/2.4.1
+- 明确 `@agile-team/wk-skills-ui` 仅为可选桥接包，两者不建立强依赖
+
+## [2.4.1] - 2026-05-04
+
+### Added
+
+- CLI 安装完成后新增 `@agile-team/wk-skills-ui` 可选桥接提醒，保持两包独立分工、不强耦合
+- 新增 `standards:init` 脚本，统一指向 `npx @robot-admin/git-standards init`
+- README 补充 wk-skills-ui 可选桥接说明与规范插件入口
+
 ## [2.4.0] - 2026-05-02
 
 ### 🚀 Agent Pipeline + MCP 项目感知 + CLI 质量工具
@@ -107,6 +135,7 @@
 新增完整的"角色 → 菜单授权 → 动作按钮 → v-permission"闭环能力。
 
 #### 新增 6 个 MCP 工具
+
 - `wls_role_query` — 查询角色列表（支持分页）
 - `wls_role_upsert` — 批量新增角色（按 `code` 字段去重）
 - `wls_assignable_menus_query` — 查询全量可授权菜单
@@ -115,20 +144,24 @@
 - `wls_action_upsert` — 批量新增动作（按 `permission` 字段去重）
 
 #### Skill 工作模式
+
 - `role-manage` — 角色查询/创建
 - `role-assign` — 角色授权菜单
 - `action-attach` — 挂动作 + 自动改造代码加 `v-permission` 指令
 
 #### 安全约束（强制）
+
 - 生产环境拒绝直接 push（gatewayPath 含 `prod` / `.com` 时切换导出模式）
 - 角色分配二次确认（Pre-flight 必须列出完整菜单清单）
 - 仅新增不删除（防误删导致大面积失权）
 
 #### 文档
+
 - `files/.github/skills/sync/permission-sync/SKILL.md` — AI 触发协议
 - `files/.github/skills/sync/permission-sync/USAGE.md` — 团队成员使用示例
 
 #### 配套更新
+
 - `_registry.md` permission-sync 状态 ⏳ → ✅
 - `kit-internal/skills/_planned-skills.md` 已清空（无草稿状态 Skill）
 - `kit-internal/architecture.md` 决策 7 更新
@@ -149,6 +182,7 @@
 ### 🔌 全编辑器 MCP 支持 + Qoder 新增
 
 #### MCP 配置自动生成（补全实现）
+
 - `wl-skills init` 现在自动生成 4 个项目级 MCP 配置文件：
   - `.cursor/mcp.json` — Cursor
   - `.mcp.json` — Claude Code（project scope，随 VCS 共享）
@@ -157,14 +191,17 @@
 - 修复 `usage.md` 中错误的配置路径描述（原来写的 `.claude/settings.json` 实际不存在）
 
 #### 手动配置指南
+
 - 新增 `.github/guides/mcp-setup.md`：Windsurf / Cline / Trae / Qoder 的手动 MCP 配置步骤
 
 #### Qoder 编辑器支持（新增第 10 个编辑器）
+
 - `editors.json` 新增 `qoder` 条目，自动生成 `.qoder/rules/conventions.md`
 - Qoder 同时通过现有 `AGENTS.md` 天然兼容（无需额外操作）
 - 新增 `_compat/headers/qoder.txt` 规则头部
 
 #### 文档更新
+
 - `usage.md` 推荐编辑器列表补全（Cline / Kiro / Trae / Qoder）
 - `usage.md` 编辑器数量 8 → 9
 
@@ -175,6 +212,7 @@
 ### 🔧 组件三文件分离规范补全 + 文档精准化
 
 #### global/local 组件
+
 - **C_SvgIcon**: Options API → `<script setup lang="ts">`，修复 `scope` typo，提取内联样式到 `index.scss`
 - **C_Splitter / C_TagStatus**: 内嵌样式提取到 `index.scss`，改为外链引用
 - **C_Tree**: 所有逻辑提取到 `data.ts`（`createTree()`），vue 文件精简为纯模板层
@@ -182,6 +220,7 @@
 - **c_listModal**: 新增 `index.scss`，消除空 style 块
 
 #### 文档与规范
+
 - `docs/request.md`: 补充 `ApiResult<T>` 显式类型定义，说明 mock `code:200` 与真实后端 `code:2000` 均被 interceptor 接受
 - `page-codegen/SKILL.md` + `TPL-*.md`: mock 响应格式统一为 `code:2000 + message`
 - `package.json`: `files` 补加 `mcp/`，修复 MCP server 从未被 npm 打包的 bug
@@ -194,7 +233,7 @@
 
 - `page-codegen/SKILL.md`：mock 响应码 `code: 200` → `code: 2000`，`msg` → `message`，与真实后端格式完全一致
 - `TPL-DETAIL-TABS.md`：全部 mock 端点（list/getById/remove/save/update）响应格式同步修正
-- `TPL-RECORD-FORM.md`：getBy*/saveOrUpdate mock 端点响应格式同步修正
+- `TPL-RECORD-FORM.md`：getBy\*/saveOrUpdate mock 端点响应格式同步修正
 - 修复后 AI 生成的 mock 文件与真实后端响应结构一致，避免前端 `res.code === 2000` 判断在 mock 模式下永远失败的问题
 
 ---
@@ -204,6 +243,7 @@
 ### 🔧 组件规范补全 + API 文档修正 + MCP 发布修复
 
 #### global 组件三文件分离规范补全
+
 - **C_SvgIcon**: Options API → `<script setup lang="ts">` 重构；修复 `<style scope>` typo（改为 `scoped`）；提取内联样式到新增 `index.scss`
 - **C_Splitter**: 将 `<style scoped>` 内嵌样式全部提取到新增 `index.scss`，vue 文件改为外链引用
 - **C_TagStatus**: 将 `<style scoped>` 内嵌样式全部提取到新增 `index.scss`，vue 文件改为外链引用
@@ -211,13 +251,16 @@
 - **C_RightToolbar**: 将全部业务逻辑（列显隐、拖拽排序、保存接口调用）提取到新增 `data.ts`（`createRightToolbar()` 函数）；将 `<style scoped>` 内嵌样式提取到新增 `index.scss`
 
 #### local 组件规范补全
+
 - **c_listModal**: 补充 `index.scss`（空 style 块改为外链引用）
 
 #### API 文档修正 (code:200 → code:2000)
+
 - `demo/produce/aiflow/mmwr-customer-apply-add/api.md`: 响应示例 `code:200, result:{}` → `code:2000, data:{}`
 - `docs/request.md`: 响应示例 `code: 200` → `code: 2000`，保持与架构规范一致
 
 #### MCP Server npm 发布修复
+
 - `package.json` `files` 字段补充 `"mcp/"` 目录，修复之前 MCP Server 代码未被打包到 npm 的严重缺失（导致 `wl-skills init` 后 `.cursor/mcp.json` 指向的 `node_modules/.../mcp/server.js` 实际不存在）
 
 ---
@@ -235,10 +278,12 @@
 ### 🔧 修复与迁移增强
 
 #### bin 字段修复
+
 - `package.json` 新增 `"main": "./bin/wl-skills.js"` —— 修复 npm v9+ 发布时 bin 条目被剔除导致 `npx` 无法找到入口的问题
 - bin 命令从 `wl-skills-kit` 重命名为 `wl-skills`（避免与包名重复触发 npm 校验警告；全局安装后可直接用 `wl-skills update`）
 
 #### 旧版用户升级支持
+
 - `bin/wl-skills.js` 新增 `LEGACY_PATHS` 迁移清理机制：
   - `update` 时自动检测并移除 v1.x/v2.0 遗留文件（旧 flat 结构 Skill 路径、废弃 `docs/` 文件等）
   - 共 24 个旧版路径纳入清理名单，避免新旧结构并存产生 AI 调度歧义
@@ -252,6 +297,7 @@
 ### 🎯 多 AI 编辑器适配解耦 + 文档体系完善
 
 #### 解耦的多 AI 配置层
+
 - `files/.github/skills/_compat/` 由"说明文档"重构为**可执行配置层**：
   - 新增 `editors.json`：编辑器注册表（bin 读此文件决定生成什么）
   - 新增 `headers/`：每个编辑器特化 frontmatter 模板（cursor-mdc / kiro / trae 等）
@@ -260,30 +306,36 @@
 - 各编辑器特化 frontmatter：Cursor 含 `description+globs+alwaysApply`，Kiro 含 `inclusion`，Trae 含 `description+globs`，等
 
 #### Skill 分级目录
+
 - `skills/` 重组为 `core/`（5 个）+ `sync/`（3 个）+ `ops/`（1 个）+ `domain/`（占位）
 - 16 处旧路径引用已批量更新
 
 #### 完善 Skill 文档（人读 vs AI 读）
+
 - 每个启用 Skill 同目录新增 `USAGE.md`（团队成员阅读，含示例对话/踩坑/FAQ），与 `SKILL.md`（AI 触发用）并存
 - 维护文档 `*.MAINTAIN.md` 已在 `kit-internal/skills/`
 
 #### api-contract 基于真实响应重写
+
 - 响应外壳：`{ code: 2000, message, data }`（**非 result，非 200**）
 - 分页字段完整描述：`records / total / current / size / pages / countId / maxLimit / orders / searchCount`
 - 增加成功/失败/字典/单条/数组各形态示例
 - 业务代码 `.then(res => res)` 拿到的就是 `data`（拦截器已剥壳）
 
 #### PLANNED Skill 草稿补全
+
 - `dict-sync/SKILL.draft.md`：完整设计（数据流/三种模式/冲突策略/转正任务）
 - `permission-sync/SKILL.draft.md`：权限码命名规范 + 三种模式 + 安全约束
 - `code-fix/SKILL.draft.md`：受控修复工作流 + 偏差类型对照 + 防御对抗 prompt
 
 #### 仓库结构治理
+
 - `ARCHITECTURE-PLAN.md` 归档至 `kit-internal/history/`
 - 新增 `kit-internal/jenkins-pipeline.md`（Jenkins 参考模板，不强加业务项目）
 - README 重写：**严格区分** A. 本仓库结构（维护用）vs B. 业务项目安装结构（业务方用），杜绝混淆
 
 #### 验证
+
 - `npm pack --dry-run`：157 文件 / 247kB（kit-internal 已正确排除）
 - 端到端 `init`：149 个文件正确生成；禁用 kiro 后只少 1 个文件（解耦验证通过）
 

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.4.0** — 一条命令将 13 条编码规范、9 个 AI Skill、14 个 MCP Tool、组件文档、领域样例导入 Vue 3 项目。
+**AI Skill 模板包 v2.5.0** — 一键将 13 条规范、9 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -11,11 +11,30 @@
 ```bash
 npx @robot-admin/git-standards init      # 工程化前置（必须）
 npx @agile-team/wl-skills-kit            # 安装 AI 体系
+npm run standards:init                   # 本包维护/业务项目均可复用的规范插件入口
 # 在 AI 对话中：
 "扫描 docs/prototypes/ 下的原型生成页面清单"
 "基于上一步生成所有 api.md，再 codegen 出页面"
 ```
 
+> 可选桥接：如业务项目也需要统一 UI 风格、老系统化妆层和 UI 扫描修复，可单独安装 `@agile-team/wk-skills-ui`。两包职责独立，不互相强依赖：`wl-skills-kit` 负责编码规范/页面生成/菜单字典权限，`wk-skills-ui` 负责视觉一致性/设计令牌/化妆层/Runtime 渲染。
+
+---
+
+## 版本亮点
+
+当前 2.4.x 版本重点完善生命周期、规范插件和跨包协作体验：
+
+- `init/update/diff/clean/check/validate/export` 覆盖安装、升级、对比、清理、体检、页面完整性检查和基线导出
+- 页面模板升级为 `BaseTable + render-type="agGrid" + cid + defineColumns + renderOps` 最终标准，融合 `wk-skills-ui` runtime，但保留 `common-core` 平台骨架
+- 新增 `doctor-ui` / `validate-page`：检查 `wk-skills-ui` 接入、AGGrid/cid、操作列、mock-first、api.md 等关键偏差
+- 增强 Intent Router：用户只需说“做个页面 / 先 mock / 菜单同步 / 风格不生效”，AI 自动识别触发 Skill/MCP
+- manifest 记录安装文件哈希，`reports/`、`src/components/`、`src/types/` 等关键资产受到保护
+- 自动生成 Copilot、Claude Code、Cursor、Windsurf、Cline、Kiro、Trae、Qoder、通用 Agents 规则文件
+- 内置 MCP Server，支持菜单、字典、权限和项目感知类工具
+- 接入 `@robot-admin/git-standards`，仓库维护和业务项目可共用 lint、commitlint、husky、commitizen
+- 可选桥接 `@agile-team/wk-skills-ui`：kit 负责页面/规范/菜单字典权限，wk-skills-ui 负责 UI 风格/化妆层/Runtime
+
 ---
 
 ## 这个包到底干什么？
@@ -85,6 +104,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ```
 
 > **维护准则**：
+>
 > - 业务规范要改 → 改 `files/.github/standards/*.md`
 > - Skill 流程要改 → 改 `files/.github/skills/<scope>/<name>/SKILL.md`
 > - 多 AI 编辑器适配要改 → 改 `files/.github/skills/_compat/`（**不是**改业务项目里的根配置文件）
@@ -134,6 +154,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ├── .clinerules                           Cline
 ├── .kiro/steering/conventions.md         Kiro（含 inclusion frontmatter）
 ├── .trae/rules/conventions.md            Trae（含 alwaysApply frontmatter）
+├── .qoder/rules/conventions.md           Qoder
 │
 ├── docs/                                 12 个组件 API 文档
 ├── demo/                                 13 个领域样例
@@ -143,7 +164,8 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ```
 
 > **业务项目方准则**：
-> - 主入口是 `.github/copilot-instructions.md`（Copilot 用），**其他 9 个根配置文件是它的拷贝 + 各自特化 frontmatter**
+>
+> - 主入口是 `.github/copilot-instructions.md`（Copilot 用），**其他根配置文件是它的拷贝 + 各自特化 frontmatter**
 > - 修改规范 → **不要**改业务项目里的副本，**升级 wl-skills-kit 包 + `update`** 才不会被覆盖
 > - reports/ 里的内容是团队累积数据，`update` 不会覆盖，可放心 commit
 
@@ -151,6 +173,8 @@ wl-skills-kit/                            ← 你正看的这个仓库
 
 ## CLI 命令
 
+所有命令默认作用于当前工作目录；如需先预览，请加 `--dry-run`。
+
 ```bash
 # 全量安装（默认）
 npx @agile-team/wl-skills-kit
@@ -164,9 +188,15 @@ npx @agile-team/wl-skills-kit check
 # 对比已安装文件与当前 kit 版本差异
 npx @agile-team/wl-skills-kit diff
 
-# 静态检查 src/views 页面文件完整性
+# 静态检查 src/views 页面文件完整性 + AGGrid/cid/skills-ui/mock
 npx @agile-team/wl-skills-kit validate
 
+# 单页/指定目录校验
+npx @agile-team/wl-skills-kit validate-page src/views/mdata/model/mdata-model-config
+
+# 检查 wk-skills-ui 是否真正接入
+npx @agile-team/wl-skills-kit doctor-ui
+
 # 导出菜单/字典/权限基线为 xlsx
 npx @agile-team/wl-skills-kit export
 
@@ -184,16 +214,27 @@ npx @agile-team/wl-skills-kit update --dry-run
 
 ---
 
+## 生命周期文件
+
+安装后会生成 `.wl-skills-manifest.json`，记录本次安装版本和文件哈希：
+
+- `update`：对比 manifest 与包内文件，仅更新有变化的内容
+- `diff`：查看当前项目与最新 kit 内容差异
+- `clean`：按 manifest 清理 AI 辅助文件，默认保留 `src/components/` 和 `src/types/`
+- `check`：检查 Node、MCP、manifest 和工程化配置
+
+---
+
 ## MCP Tools 概览
 
-| 类别 | Tools |
-| --- | --- |
-| 菜单 | `wls_menu_query` / `wls_menu_upsert` |
-| 字典 | `wls_dict_query` / `wls_dict_upsert` |
-| 权限 | `wls_role_query` / `wls_role_upsert` / `wls_assignable_menus_query` / `wls_role_assign_menus` / `wls_action_query` / `wls_action_upsert` |
-| 项目感知 | `wls_code_scan` / `wls_route_check` / `wls_git_log_extract` / `wls_audit_report_push` |
+| 类别     | Tools                                                                                                                                    |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| 菜单     | `wls_menu_query` / `wls_menu_upsert` / `wls_menu_sync_from_report`                                                                       |
+| 字典     | `wls_dict_query` / `wls_dict_upsert`                                                                                                     |
+| 权限     | `wls_role_query` / `wls_role_upsert` / `wls_assignable_menus_query` / `wls_role_assign_menus` / `wls_action_query` / `wls_action_upsert` |
+| 项目感知 | `wls_code_scan` / `wls_route_check` / `wls_validate_page` / `wls_doctor_ui` / `wls_git_log_extract` / `wls_audit_report_push`            |
 
-`wls_code_scan`、`wls_route_check`、`wls_git_log_extract` 不依赖后端 token，可用于 Agent Pipeline 前置感知项目结构。
+`wls_code_scan`、`wls_route_check`、`wls_validate_page`、`wls_doctor_ui`、`wls_git_log_extract` 不依赖后端 token，可用于 Agent Pipeline 前置感知项目结构。
 
 ---
 
@@ -207,6 +248,7 @@ npx @agile-team/wl-skills-kit update
 ```
 
 `update` 命令会自动完成：
+
 1. **写入新文件** — 新结构下的所有文件覆盖写入
 2. **迁移清理** — 检测并移除旧版遗留文件（如 `skills/prototype-scan/`、`docs/menu-sync-design.md` 等），避免新旧路径并存产生歧义
 3. **保护累积数据** — `reports/*.md` 已存在则跳过，团队累积的菜单/字典数据不丢失
@@ -217,17 +259,17 @@ npx @agile-team/wl-skills-kit update
 
 ## Skill 概览
 
-| Skill              | 状态      | 路径                                     | 核心用途                      |
-| ------------------ | --------- | ---------------------------------------- | ----------------------------- |
-| `prototype-scan`   | ✅ 启用    | `skills/core/prototype-scan/`            | 原型/详设/口述 → 页面清单     |
-| `api-contract`     | ✅ 启用    | `skills/core/api-contract/`              | 生成 api.md 前后端契约        |
-| `page-codegen`     | ✅ 启用    | `skills/core/page-codegen/`              | 页面骨架生成 + 模板调度      |
-| `convention-audit` | ✅ 启用    | `skills/core/convention-audit/`          | 13 条规范扫描 + 双报告        |
-| `template-extract` | ✅ 启用    | `skills/core/template-extract/`          | 现有页面 → 领域模板           |
-| `menu-sync`        | ✅ 启用    | `skills/sync/menu-sync/`                 | 菜单基线 ↔ 后端接口          |
-| `dict-sync`        | ✅ 启用    | `skills/sync/dict-sync/`                 | 字典基线 ↔ 后端接口          |
-| `permission-sync`  | ✅ 启用    | `skills/sync/permission-sync/`           | 角色管理 + 角色授权 + 挂动作 + v-permission |
-| `code-fix`         | ✅ 启用    | `skills/ops/code-fix/`                   | 受控自动修复偏差              |
+| Skill              | 状态    | 路径                            | 核心用途                                    |
+| ------------------ | ------- | ------------------------------- | ------------------------------------------- |
+| `prototype-scan`   | ✅ 启用 | `skills/core/prototype-scan/`   | 原型/详设/口述 → 页面清单                   |
+| `api-contract`     | ✅ 启用 | `skills/core/api-contract/`     | 生成 api.md 前后端契约                      |
+| `page-codegen`     | ✅ 启用 | `skills/core/page-codegen/`     | 页面骨架生成 + 模板调度                     |
+| `convention-audit` | ✅ 启用 | `skills/core/convention-audit/` | 13 条规范扫描 + 双报告                      |
+| `template-extract` | ✅ 启用 | `skills/core/template-extract/` | 现有页面 → 领域模板                         |
+| `menu-sync`        | ✅ 启用 | `skills/sync/menu-sync/`        | 菜单基线 ↔ 后端接口                         |
+| `dict-sync`        | ✅ 启用 | `skills/sync/dict-sync/`        | 字典基线 ↔ 后端接口                         |
+| `permission-sync`  | ✅ 启用 | `skills/sync/permission-sync/`  | 角色管理 + 角色授权 + 挂动作 + v-permission |
+| `code-fix`         | ✅ 启用 | `skills/ops/code-fix/`          | 受控自动修复偏差                            |
 
 每个启用 Skill 同目录都有 **`SKILL.md`（AI 触发用）+ `USAGE.md`（团队成员阅读）**。
 
@@ -237,18 +279,18 @@ npx @agile-team/wl-skills-kit update
 
 `init` / `update` 读取 `files/.github/skills/_compat/editors.json` 生成对应配置：
 
-| 编辑器         | 输出路径                            | Frontmatter             |
-| -------------- | ----------------------------------- | ----------------------- |
-| GitHub Copilot | `.github/copilot-instructions.md`   | -                       |
-| Claude Code    | `CLAUDE.md`                         | -                       |
-| Cursor (rules) | `.cursorrules`                      | -                       |
-| Cursor (mdc)   | `.cursor/rules/conventions.mdc`     | description+globs+alwaysApply |
-| Windsurf       | `.windsurfrules`                    | -                       |
-| Cline          | `.clinerules`                       | -                       |
-| Kiro           | `.kiro/steering/conventions.md`     | inclusion: always       |
-| Trae           | `.trae/rules/conventions.md`        | description+globs+alwaysApply |
-| 通用 Agent     | `AGENTS.md`                         | -                       |
-| Qoder          | `.qoder/rules/conventions.md`       | description             |
+| 编辑器         | 输出路径                          | Frontmatter                   |
+| -------------- | --------------------------------- | ----------------------------- |
+| GitHub Copilot | `.github/copilot-instructions.md` | -                             |
+| Claude Code    | `CLAUDE.md`                       | -                             |
+| Cursor (rules) | `.cursorrules`                    | -                             |
+| Cursor (mdc)   | `.cursor/rules/conventions.mdc`   | description+globs+alwaysApply |
+| Windsurf       | `.windsurfrules`                  | -                             |
+| Cline          | `.clinerules`                     | -                             |
+| Kiro           | `.kiro/steering/conventions.md`   | inclusion: always             |
+| Trae           | `.trae/rules/conventions.md`      | description+globs+alwaysApply |
+| 通用 Agent     | `AGENTS.md`                       | -                             |
+| Qoder          | `.qoder/rules/conventions.md`     | description                   |
 
 **解耦验证**：在 `editors.json` 中将任意编辑器 `enabled: false`，重新 `update` —— 该编辑器配置不再生成，其他编辑器**完全不受影响**。
 
@@ -256,11 +298,34 @@ npx @agile-team/wl-skills-kit update
 
 ## 受保护路径
 
-| 命令                     | 保护路径                          | 说明                       |
-| ------------------------ | --------------------------------- | -------------------------- |
-| `init` / `update`        | `.github/reports/*.md`            | 已存在则跳过，不覆盖累积   |
-| `clean`（默认）          | `src/components/` + `src/types/`  | 业务代码必需，永不删除     |
-| `clean --keep-reports`   | + `.github/reports/`              | 保留菜单/字典/权限基线     |
+| 命令                   | 保护路径                         | 说明                     |
+| ---------------------- | -------------------------------- | ------------------------ |
+| `init` / `update`      | `.github/reports/*.md`           | 已存在则跳过，不覆盖累积 |
+| `clean`（默认）        | `src/components/` + `src/types/` | 业务代码必需，永不删除   |
+| `clean --keep-reports` | + `.github/reports/`             | 保留菜单/字典/权限基线   |
+
+---
+
+## 与 wk-skills-ui 的边界
+
+`wl-skills-kit` 和 `wk-skills-ui` 是可组合但不强耦合的两个包：
+
+| 包              | 主要职责                                                         | 典型触发                                |
+| --------------- | ---------------------------------------------------------------- | --------------------------------------- |
+| `wl-skills-kit` | 编码规范、页面生成、菜单/字典/权限同步、Agent Pipeline           | “生成页面”“同步菜单”“规范审计”          |
+| `wk-skills-ui`  | UI 风格一致性、老项目化妆层、设计令牌、Runtime 渲染、UI 扫描修复 | “统一 UI 风格”“老项目化妆”“UI 扫描修复” |
+
+如果业务项目同时安装两者，`wl-skills-kit` 的页面模板会直接融合 `wk-skills-ui/runtime`：
+
+- `defineColumns()`：列定义自动套用字段映射、宽度、状态渲染建议
+- `renderOps()`：操作列统一为图标按钮系统
+- `doctor-ui`：检查 tokens、styles、`installCommonPreset()` 是否真实接入
+
+注意：不会生搬硬套 `wk-skills-ui` 通用模板里的 `usePageHook/el-form/el-pagination`。本包的最终页面标准仍是：
+
+```text
+AbstractPageQueryHook + BaseQuery + BaseToolbar + BaseTable(render-type="agGrid") + jh-pagination
+```
 
 ---
 
@@ -269,7 +334,7 @@ npx @agile-team/wl-skills-kit update
 - 📚 业务方使用指南：`.github/guides/usage.md`（业务项目内）
 - 🏗️ 架构与决策：`.github/guides/architecture.md`（业务项目内）
 - 🔧 维护者文档：[kit-internal/README.md](kit-internal/README.md)（仅本仓库）
-- 🤖 多编辑器适配机制：[files/.github/skills/_compat/README.md](files/.github/skills/_compat/README.md)
+- 🤖 多编辑器适配机制：[files/.github/skills/\_compat/README.md](files/.github/skills/_compat/README.md)
 - 🛠️ Jenkins 流水线参考：[kit-internal/jenkins-pipeline.md](kit-internal/jenkins-pipeline.md)
 
 ---