@agile-team/wl-skills-ui 1.6.2

package/skills/layouts/form-dialog/SKILL.md

@@ -0,0 +1,128 @@
+---
+description: |
+  表单弹窗骨架 Skill — 检测/对齐 .form-dialog 标准结构（el-dialog + el-form + footer 操作按钮），
+  适用于新增/编辑/详情三合一弹窗模式。
+applyTo: "**/*.vue"
+---
+
+# layouts/form-dialog SKILL
+
+## 适用场景
+
+以 `el-dialog` 承载 `el-form` 的新增/编辑/详情弹窗，支持 `optr: 'add' | 'edit' | 'view'` 三态切换。
+
+---
+
+## Detect — 识别表单弹窗
+
+```
+检测条件（满足任意 2 项即判定）：
+✓ 文件名含 Modal / Dialog / Form（如 AddModal.vue / EditDialog.vue）
+✓ 存在 el-dialog 包裹 el-form
+✓ defineExpose 中有 add / edit / view 方法
+✓ 存在 optr ref 用于控制表单只读/可写状态
+✓ el-dialog footer 中有"确定"/"取消"按钮
+```
+
+---
+
+## Diagnose — 诊断问题
+
+| 问题 | 规则 | 说明 |
+|---|---|---|
+| el-dialog 缺 `.form-dialog` class | L-201 | 应加 `class="form-dialog"` 便于全局覆盖 |
+| el-form 缺 `labelWidth="150px"` | R008 | 统一 label 宽度 |
+| el-input/el-select 缺 `size="small"` | R006 | 表单控件统一 small |
+| el-date-picker 缺 `style="width:100%"` | R007 | 日期控件需撑满容器 |
+| footer 中含分页组件 | R011 | 分页不应在 footer 内 |
+| 弹窗内嵌套 el-table 操作列用文字按钮 | R015 | 应用 jh-op-btn 图标 |
+| 详情态（optr=view）没有禁用所有输入 | L-202 | 应统一用 `:disabled="optr==='view'"` |
+
+---
+
+## Repair — 修复指引
+
+### 标准结构
+
+```vue
+<template>
+  <el-dialog
+    v-model="visible"
+    class="form-dialog"
+    :title="title"
+    width="700px"
+    :close-on-click-modal="false"
+    @closed="reset"
+  >
+    <el-form
+      ref="formRef"
+      :model="form"
+      :rules="optr !== 'view' ? rules : {}"
+      label-width="150px"
+      label-position="right"
+    >
+      <el-row :gutter="20">
+        <el-col :span="12">
+          <el-form-item label="名称" prop="name">
+            <el-input
+              v-model="form.name"
+              size="small"
+              placeholder="请输入"
+              :disabled="optr === 'view'"
+            />
+          </el-form-item>
+        </el-col>
+        <el-col :span="12">
+          <el-form-item label="日期" prop="date">
+            <el-date-picker
+              v-model="form.date"
+              type="date"
+              size="small"
+              style="width:100%"
+              :disabled="optr === 'view'"
+            />
+          </el-form-item>
+        </el-col>
+      </el-row>
+    </el-form>
+
+    <template #footer>
+      <el-button @click="visible = false">取消</el-button>
+      <el-button
+        v-if="optr !== 'view'"
+        type="primary"
+        :loading="saving"
+        @click="handleSubmit"
+      >确定</el-button>
+    </template>
+  </el-dialog>
+</template>
+
+<script setup>
+const visible = ref(false);
+const optr = ref('add'); // 'add' | 'edit' | 'view'
+const title = computed(() => ({ add: '新增', edit: '编辑', view: '详情' }[optr.value]);
+
+function add() { optr.value = 'add'; reset(); visible.value = true; }
+function edit(id) { optr.value = 'edit'; load(id); visible.value = true; }
+function view(id) { optr.value = 'view'; load(id); visible.value = true; }
+
+defineExpose({ add, edit, view });
+</script>
+```
+
+### 三态最佳实践
+
+| 态 | optr | 输入控件 | footer 按钮 |
+|---|---|---|---|
+| 新增 | `'add'` | 可编辑 | 取消 + 确定 |
+| 编辑 | `'edit'` | 可编辑 | 取消 + 确定 |
+| 详情 | `'view'` | `disabled` | 仅取消/关闭 |
+
+---
+
+## 关联资源
+
+- 样式实现：[styles/layouts/_form-dialog.scss](../../../styles/layouts/_form-dialog.scss)
+- 代码模板：[templates/form-dialog/TPL-FORM-DIALOG.md](../../../templates/form-dialog/TPL-FORM-DIALOG.md)
+- 相关 skills：[layouts/list-page](../list-page/SKILL.md) | [element/el-form](../../element/el-form/SKILL.md)

package/skills/layouts/list-page/SKILL.md

@@ -0,0 +1,111 @@
+---
+description: |
+  列表页骨架 Skill — 检测/对齐 .list-page 标准布局（搜索区 + 工具栏 + 表格 + 分页），
+  适用于 Native 模式新项目；同时提供 AI 修复指引。
+applyTo: "**/*.vue"
+---
+
+# layouts/list-page SKILL
+
+## 适用场景
+
+页面结构为：**搜索栏 → 工具栏（增删按钮） → 数据表格 → 分页器** 的经典 CRUD 列表页。
+
+---
+
+## Detect — 识别列表页
+
+### 方式一：结构特征识别
+```
+检测条件（满足任意 2 项即判定为列表页）：
+✓ 根节点或第一子节点含 class="list-page" / "page-wrapper" / "table-page"
+✓ 存在 <BaseTable> 或 <el-table>
+✓ 存在 <BaseQuery> 或包含搜索条件的 el-form
+✓ 存在 <jh-pagination> 或 <el-pagination>
+✓ 存在工具栏区域（包含"新增"按钮的 el-row / div.toolbar）
+```
+
+### 方式二：命令触发
+```
+用 wk-ui 的 layouts/list-page skill 检查这个文件
+→ AI 加载本 SKILL.md，对当前文件做 Detect → Diagnose → Repair
+```
+
+---
+
+## Diagnose — 诊断问题
+
+### 结构层问题
+
+| 问题 | 规则 | 说明 |
+|---|---|---|
+| 根节点缺少 `.list-page` | L-001 | 应为 `<div class="list-page">` |
+| 搜索区未用 `.list-page__query` | L-002 | 内部结构应遵循 BEM |
+| 工具栏未用 `.list-page__toolbar` | L-003 | 按钮组应在 `.list-page__toolbar` 内 |
+| 表格区未用 `.list-page__table` | L-004 | 表格容器应有独立 class |
+| 分页区未用 `.list-page__pagination` | L-005 | 分页器位置需在 **内容区**，不得在 dialog footer |
+
+### 内容层问题（复用 scanner 规则）
+
+- R001 ~ R003：表格列对齐 + empty-text
+- R005：工具栏按钮缺 icon
+- R006：搜索区输入框缺 `size="small"`
+- R011：分页在 footer 内（严重）
+
+---
+
+## Repair — 修复指引
+
+### 标准结构
+
+```vue
+<template>
+  <div class="list-page">
+    <!-- 搜索区 -->
+    <div class="list-page__query">
+      <BaseQuery :params="searchParams" @search="reload" @reset="reset" />
+    </div>
+
+    <!-- 工具栏 -->
+    <div class="list-page__toolbar">
+      <el-button type="primary" icon="Plus" @click="modal.add()">新增</el-button>
+      <el-button icon="Download" @click="handleExport">导出</el-button>
+    </div>
+
+    <!-- 表格 -->
+    <div class="list-page__table">
+      <BaseTable :hook="page" empty-text="暂无数据" :columns="columns" />
+    </div>
+
+    <!-- 分页 -->
+    <div class="list-page__pagination">
+      <jh-pagination :hook="page" />
+    </div>
+  </div>
+</template>
+```
+
+### SCSS 对应（由 styles/layouts/_list-page.scss 提供）
+
+```scss
+// 业务侧无需手写，全局 @use 后自动生效
+// 如需定制，在组件 <style scoped> 内覆盖：
+.list-page {
+  // 自定义
+}
+```
+
+### 使用脚手架
+
+```bash
+# 直接在编辑器让 AI：
+# 按 wk-ui 的 templates/list-page/TPL-LIST.md 创建该页面
+```
+
+---
+
+## 关联资源
+
+- 样式实现：[styles/layouts/_list-page.scss](../../../styles/layouts/_list-page.scss)
+- 代码模板：[templates/list-page/TPL-LIST.md](../../../templates/list-page/TPL-LIST.md)
+- 相关 skills：[vendors/base-table](../../vendors/base-table/SKILL.md) | [vendors/jh-components](../../vendors/jh-components/SKILL.md)

package/skills/layouts/tree-list/SKILL.md

@@ -0,0 +1,108 @@
+---
+description: |
+  左树右表骨架 Skill — 检测/对齐 .tree-list 双栏布局（左侧分类树 + 右侧数据列表），
+  含 jh-drag-col 拖拽分割条处理；适用于组织/分类驱动的管理页面。
+applyTo: "**/*.vue"
+---
+
+# layouts/tree-list SKILL
+
+## 适用场景
+
+页面结构为：**左侧分类/组织树 + 右侧数据列表（含搜索 + 表格 + 分页）** 的双栏页面。
+
+---
+
+## Detect — 识别左树右表页
+
+```
+检测条件（满足任意 2 项即判定）：
+✓ 页面存在并排的 el-tree 或 jh-tree
+✓ 存在 jh-drag-col（拖拽分割条）
+✓ 根节点含 class="tree-list" / "tree-page" / "left-tree-right-table"
+✓ 布局中有宽度约 240px 的左侧容器 + 弹性宽度的右侧容器
+✓ 存在 @node-click / @current-change 事件绑定
+```
+
+---
+
+## Diagnose — 诊断问题
+
+| 问题 | 规则 | 说明 |
+|---|---|---|
+| 根节点缺少 `.tree-list` | L-101 | 应为 `<div class="tree-list">` |
+| 左侧区未用 `.tree-list__aside` | L-102 | 树容器应有独立 class |
+| 右侧区未用 `.tree-list__main` | L-103 | 右侧内容区应有独立 class |
+| 缺少 `jh-drag-col` 分割条 | L-104 | 应支持拖拽调整左右宽度 |
+| 树节点点击后未触发右侧列表刷新 | L-105 | `@node-click` 应调用 `reload()` 并传入分类参数 |
+| 左侧树无搜索/过滤 | L-106 | 数据量大时应加 `filter-node-method` |
+
+---
+
+## Repair — 修复指引
+
+### 标准结构
+
+```vue
+<template>
+  <div class="tree-list">
+    <!-- 左侧树 -->
+    <div class="tree-list__aside" :style="{ width: treeWidth + 'px' }">
+      <el-tree
+        :data="treeData"
+        :props="{ label: 'name', children: 'children' }"
+        node-key="id"
+        highlight-current
+        @node-click="handleNodeClick"
+      />
+    </div>
+
+    <!-- 拖拽分割条 -->
+    <jh-drag-col v-model="treeWidth" :min="180" :max="360" />
+
+    <!-- 右侧内容 -->
+    <div class="tree-list__main">
+      <!-- 复用 list-page 结构（搜索 + 工具栏 + 表格 + 分页） -->
+      <div class="list-page">
+        <div class="list-page__query"> ... </div>
+        <div class="list-page__toolbar"> ... </div>
+        <div class="list-page__table">
+          <BaseTable :hook="page" empty-text="暂无数据" :columns="columns" />
+        </div>
+        <div class="list-page__pagination">
+          <jh-pagination :hook="page" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+const treeWidth = ref(240);
+
+function handleNodeClick(node) {
+  searchParams.value.classifyId = node.id;
+  page.reload();
+}
+</script>
+```
+
+### SCSS 对应
+
+```scss
+// styles/layouts/_tree-list.scss 已提供基础骨架
+// 业务侧如需定制左侧宽度：
+.tree-list__aside {
+  min-width: 180px;
+  max-width: 400px;
+}
+```
+
+---
+
+## 关联资源
+
+- 样式实现：[styles/layouts/_tree-list.scss](../../../styles/layouts/_tree-list.scss)
+- 拖拽列样式：[styles/vendors/_jh-drag-col.scss](../../../styles/vendors/_jh-drag-col.scss)
+- 代码模板：[templates/tree-list/TPL-TREE-LIST.md](../../../templates/tree-list/TPL-TREE-LIST.md)
+- 相关 skills：[layouts/list-page](../list-page/SKILL.md) | [vendors/jh-components](../../vendors/jh-components/SKILL.md)

package/skills/ops/audit/SKILL.md

@@ -0,0 +1,109 @@
+---
+description: |
+  审计 Skill — 对项目做只读的全量 UI 规范合规审计，输出分层问题报告（不自动修改任何文件）。
+  支持 --layer / --vendor / --mode 精准过滤，生成 markdown 报告供人工或 AI 渐进修复。
+applyTo: "**"
+---
+
+# ops/audit SKILL
+
+## 一、审计目标
+
+对目标项目做**完整只读扫描**，产出：
+
+1. 接入完整性报告（I001-I005：tokens/styles/runtime/skills 是否接入）
+2. 风格合规报告（R001-R018：按 layer/vendor 分组）
+3. 优先级建议（高危 → 中危 → 低危 三层）
+
+**本 skill 不修改任何文件，仅审计和报告。**
+
+---
+
+## 二、审计命令
+
+### 全量审计（推荐）
+
+```bash
+npx wk-ui all --project . --outFile audit-report.md
+```
+
+### 分层审计
+
+```bash
+# 仅看 L0 颜色 token 违规
+npx wk-ui scan --target src --layer L0 --outFile l0-report.md
+
+# 仅看 L1 Element Plus 控件问题
+npx wk-ui scan --target src --layer L1 --outFile l1-report.md
+
+# 仅看 L2 封装组件问题（vendor 层）
+npx wk-ui scan --target src --layer L2 --outFile l2-report.md
+
+# 化妆模式项目只看 L0/L1/L2（跳过 L3/L4）
+npx wk-ui scan --target src --mode skin --outFile skin-audit.md
+```
+
+### 精准 vendor 审计
+
+```bash
+# 仅扫描 BaseTable 相关规则
+npx wk-ui scan --target src --vendor base-table
+
+# 仅扫描 Element Plus 原生控件
+npx wk-ui scan --target src --vendor element
+```
+
+---
+
+## 三、AI 审计流程
+
+在 AI 编辑器中触发：
+
+```
+用 wk-ui 的 ops/audit skill 对当前项目做全量审计
+```
+
+**AI 执行步骤：**
+
+1. `npx wk-ui check --project .` → 接入完整性（I001-I005）
+2. `npx wk-ui scan --target src --output json --outFile /tmp/audit.json` → JSON 格式结果
+3. 读取 JSON，按如下格式汇报：
+
+```markdown
+## 审计摘要
+- 扫描文件数：XX
+- 发现问题数：XX（高危 X / 中危 X / 低危 X）
+- 接入完整性：✅ X 项通过 / ❌ X 项缺失
+
+### 高危（直接影响视觉一致性）
+| 规则 | 文件 | 行号 | 说明 |
+| R001 | src/pages/Foo.vue | 45 | 列缺少 align="center" |
+...
+
+### 修复建议（优先级排序）
+1. 运行 `npx wk-ui fix --target src --dry-run` 先预览 A 类自动修复
+2. 对 R009/R010 状态字段手工确认并应用 renderTagNode
+3. 对 L0 颜色违规批量替换为 CSS Token
+```
+
+4. 询问用户：是否进入修复阶段（`ops/fix` skill），还是只看报告？
+
+---
+
+## 四、接入完整性检查项（I001-I005）
+
+| 编号 | 检查项 | 说明 |
+|---|---|---|
+| I001 | tokens.css / base.css 已引入 | index.html `<head>` 中有 wk-skills-ui tokens |
+| I002 | styles 预设已引入 | SCSS 入口含 `@use '@agile-team/wk-skills-ui/styles...'` |
+| I003 | runtime preset 已安装 | main.ts 含 `installCommonPreset()` |
+| I004 | skills 已安装 | `.github/instructions/` 或 `.cursor/rules/` 等目录存在 wk-skills 文件 |
+| I005 | package.json 版本 | @agile-team/wk-skills-ui 版本 ≥ 0.3.0 |
+
+---
+
+## 关联资源
+
+- 修复：[ops/fix](../fix/SKILL.md)
+- 渐进迁移：[runtime/migration](../../runtime/migration/SKILL.md)
+- 全审计流程：[_flows/full-audit]( ../../_flows/full-audit.md)

package/skills/ops/fix/SKILL.md

@@ -0,0 +1,52 @@
+---
+description: |
+  wk-ui fix 自动修复指南 — A 类问题（attr 缺失、hex 颜色）的批量自动修复，
+  支持 dry-run 预览，幂等安全，不修改已符合标准的文件。
+applyTo: "**"
+---
+
+# 自动修复指南
+
+## 可自动修复的问题（A 类）
+
+| 规则      | 修复内容                                          |
+| --------- | ------------------------------------------------- |
+| R006      | el-input / el-select 补充 `size="small"`          |
+| R007      | el-date-picker 补充 `style="width:100%"`          |
+| R002/R003 | el-table / BaseTable 补充 `empty-text="暂无数据"` |
+| R001      | el-table-column 补充 `align="center"`             |
+| R016/R017 | style/template 块 hex 颜色替换为 CSS Token        |
+
+## 命令
+
+```bash
+# 先预览（推荐！）
+npx wk-ui fix --target src --dry-run
+
+# 确认后执行
+npx wk-ui fix --target src
+
+# 只修复特定目录
+npx wk-ui fix --target src/views/check
+```
+
+## 修复后必须验证
+
+```bash
+npx wk-ui scan --target src --outFile /tmp/after-fix.md
+```
+
+对比修复前后报告，确认 A 类问题归零，剩余仅为需人工处理的规则。
+
+## 无法自动修复（B 类，需 AI 辅助人工处理）
+
+| 规则      | 原因                                           |
+| --------- | ---------------------------------------------- |
+| R004/R013 | 操作列结构改造，需改写 defaultSlot + renderOps |
+| R008      | labelWidth 需人工判断布局需求                  |
+| R009/R010 | 状态字段语义需人工识别                         |
+| R015      | 弹窗内操作按钮结构改造                         |
+
+## 幂等性保证
+
+修复脚本可重复运行，已符合标准的文件不会被修改。

package/skills/ops/fix/USAGE.md

@@ -0,0 +1,24 @@
+# USAGE — 自动修复 Skill
+
+## 调用方式
+
+```
+帮我修复扫描到的所有 A 类问题
+批量修复这个目录的 hex 颜色
+```
+
+## 最佳实践
+
+```bash
+# 1. 先扫描了解情况
+npx wk-ui scan --target src --outFile /tmp/before.md
+
+# 2. dry-run 预览修复效果
+npx wk-ui fix --target src --dry-run
+
+# 3. 确认无误后执行
+npx wk-ui fix --target src
+
+# 4. 验证效果
+npx wk-ui scan --target src --outFile /tmp/after.md
+```

package/skills/ops/migrate/SKILL.md

@@ -0,0 +1,157 @@
+---
+description: |
+  渐进迁移 Skill — 指导老项目从 Skin 化妆模式渐进迁移到 Native 原生模式（按模块、按 vendor、按层次）。
+  明确迁移触发条件、安全顺序和回退机制。
+applyTo: "**"
+---
+
+# ops/migrate SKILL
+
+## 一、迁移目标
+
+从 **Skin 模式**（只有 L0/L1/L2 化妆）升级到 **Native 模式**（全五层），同时保证：
+- 迁移期间业务功能不中断
+- 按模块/按 vendor 逐步替换，不做大爆炸式重写
+- 每步可回退
+
+---
+
+## 二、迁移触发条件
+
+以下任意条件满足时，建议启动对应模块的迁移：
+
+| 条件 | 建议迁移内容 |
+|---|---|
+| 拿到封装组件源码（如 BaseTable）| 把 L2 化妆 → L4 runtime 调用 |
+| 新增模块（CRUD 列表页）| 直接用 Native 骨架（list-page + defineColumns）|
+| 发现大量 R009 状态字段纯文本 | 迁移到 renderTagNode / COLUMN_AUTO_MAP |
+| 性能优化需要（减少全局 CSS override）| L2 vendor 选择器精细化 |
+| 业务 preset 需要扩展 | 用 createPreset() / installPreset() 替代手写 map |
+
+---
+
+## 三、迁移安全顺序
+
+```
+Step 1 — 接入 design/tokens/base.css        (可立即，无风险)
+Step 2 — 接入 styles/presets/skin            (可立即，只加不改)
+Step 3 — 接入 styles/presets/full            (替换 skin，确认布局无冲突)
+Step 4 — 接入 installCommonPreset()          (仅影响新页面，旧页面不动)
+Step 5 — 新模块用 defineColumns + renderOps  (只影响新写代码)
+Step 6 — 旧模块逐批迁移 columnsDef → defineColumns
+Step 7 — 旧 vendor 化妆层（_base-table.scss 等）按需保留或删除
+```
+
+---
+
+## 四、AI 辅助迁移流程
+
+在 AI 编辑器中触发：
+
+```
+用 wk-ui 的 ops/migrate skill 帮我迁移 src/pages/safety/ 目录
+```
+
+**AI 执行步骤：**
+
+1. 扫描目标目录：`npx wk-ui scan --target src/pages/safety --output json`
+2. 识别迁移优先级：
+   - R013（columnsDef 旧格式）→ 优先迁移到 `defineColumns`
+   - R004/R005（按钮规则）→ 用 `renderOps` 替换
+   - R009（状态字段）→ 注册到 COLUMN_AUTO_MAP
+3. 逐文件迁移，**每文件迁移后立即验证**（重跑 scan 确认问题归零）
+4. 汇报迁移结果
+
+---
+
+## 五、具体迁移操作
+
+### 5.1 columnsDef → defineColumns
+
+```typescript
+// ❌ 旧写法
+columnsDef() {
+  return [
+    { label: '名称', name: 'name' },
+    { label: '状态', name: 'enableStatus', logicType: BusLogicDataType.dict },
+    { label: '操作', operations: [
+      { name: 'edit', label: '编辑', onClick: (row) => modal.edit(row.id) },
+    ]},
+  ];
+}
+
+// ✅ 新写法
+import { defineColumns, renderOps } from '@agile-team/wk-skills-ui/runtime';
+
+columnsDef() {
+  return defineColumns([
+    { label: '名称', name: 'name' },
+    { label: '状态', name: 'enableStatus' },           // 自动 Tag（已注册）
+    { label: '操作', width: 100, align: 'center',
+      defaultSlot: ({ row }) => renderOps([
+        { type: 'edit', onClick: () => modal.edit(row.id) },
+      ]),
+    },
+  ]);
+}
+```
+
+### 5.2 新增 COLUMN_AUTO_MAP 字段
+
+当项目有自定义状态字段时，扩展到 common preset：
+
+```typescript
+// runtime/presets/my-biz.ts（用 wk-ui add-preset my-biz 生成）
+import { createPreset } from '@agile-team/wk-skills-ui/runtime';
+
+export const installMyBizPreset = createPreset({
+  name: 'my-biz',
+  columnAutoMap: {
+    myStatus: {
+      width: 90, align: 'center',
+      defaultSlot: ({ row }) => renderMyStatus(row.myStatus),
+    },
+  },
+  tagMaps: {
+    myStatus: {
+      '0': { label: '待处理', type: 'info' },
+      '1': { label: '处理中', type: '' },
+      '2': { label: '已完成', type: 'success' },
+    },
+  },
+});
+```
+
+### 5.3 styles/presets/skin → full 切换
+
+```scss
+// 确认没有布局冲突后，把：
+@use '@agile-team/wk-skills-ui/styles/presets/skin' as *;
+// 改为：
+@use '@agile-team/wk-skills-ui/styles' as *;
+```
+
+**验证方式：** 跑冒烟测试，确认以下页面类型视觉无异常：
+- 列表页（.list-page 骨架生效）
+- 左树右表页（.tree-list 骨架生效）
+- 表单弹窗（.form-dialog 骨架生效）
+
+---
+
+## 六、回退机制
+
+每步迁移都是**加法或替换**，不是删除原有代码：
+
+| 步骤 | 回退方式 |
+|---|---|
+| styles full → skin | 改回 `@use '...presets/skin'` |
+| defineColumns 迁移 | git revert 单个文件 |
+| installCommonPreset | 注释掉 `installCommonPreset()` 调用 |
+
+---
+
+## 关联资源
+
+- 渐进迁移流程：[_flows/progressive-migrate](../../_flows/progressive-migrate.md)
+- 审计先行：[ops/audit](../audit/SKILL.md)
+- 运行时迁移：[runtime/migration](../../runtime/migration/SKILL.md)