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

package/files/.github/guides/architecture.md

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.4.0（2026-05-02）
+> **当前版本**：v2.5.0（2026-05-07）
 
 ---
 
@@ -58,7 +58,7 @@ AI 编辑器（Copilot / Cursor / Windsurf 等）知道通用编程知识，但
 1. 规范分层、按任务类型懒加载（token 高效利用）
 2. Skill 触发词驱动（开发者用自然语言，AI 读结构化 SKILL.md）
 3. Pre-flight 约定式声明（消除 AI "假执行"黑盒问题）
-4. 多 AI 编辑器适配（一套内容，自动生成 9 种根配置，解耦可扩展）
+4. 多 AI 编辑器适配（一套内容，自动生成 Copilot/Claude/Cursor/Windsurf/Cline/Kiro/Trae/Qoder/Agents 配置，解耦可扩展）
 5. 报告层追加不覆盖（累积团队知识，不丢失审计历史）
 
 ---
@@ -102,7 +102,9 @@ wl-skills.js init/update
     │      - reports/*.md 已存在则跳过（保护团队累积数据）
     │      - 其他文件：覆盖写入
     │
-    └─ 5. 写入/更新 .wl-skills-manifest.json（文件哈希快照）
+    ├─ 5. 写入/更新 .wl-skills-manifest.json（文件哈希快照）
+    │
+    └─ 6. 输出 wk-skills-ui 可选桥接提醒与 git-standards 规范插件建议
 ```
 
 ---
@@ -124,6 +126,7 @@ AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae
   │   Cline    → .clinerules
   │   Kiro     → .kiro/steering/conventions.md
   │   Trae     → .trae/rules/conventions.md
+  │   Qoder    → .qoder/rules/conventions.md
   │   通用     → AGENTS.md
   │
   │ 根配置包含：

package/files/.github/guides/usage.md

@@ -1,7 +1,7 @@
 # wl-skills-kit 使用指南
 
 > **目标读者**：使用 `@agile-team/wl-skills-kit` 的 Vue 3 业务项目团队成员。
-> **适用版本**：v2.0+
+> **适用版本**：v2.4.x
 > **维护者**：CHENY（工号 409322）
 
 ---
@@ -34,7 +34,7 @@ npx @agile-team/wl-skills-kit
 - Trae
 - Qoder
 
-打开项目后，AI 会自动加载 `.github/copilot-instructions.md`，你不用做任何配置。
+打开项目后，AI 会按编辑器自动加载对应规则文件：Copilot 读 `.github/copilot-instructions.md`，Claude Code 读 `CLAUDE.md`，Cline 读 `.clinerules`，通用 Agent 读 `AGENTS.md`，Qoder 读 `.qoder/rules/conventions.md`。
 
 ### 第 3 步：开始使用
 
@@ -46,6 +46,7 @@ npx @agile-team/wl-skills-kit
 "审计 src/views/sale 这个目录的代码规范"
 "提取 mmwr-rolling-management 这个页面作为模板"
 "同步菜单到后端"
+"帮我做个台账页面，后端没好先 mock，菜单也加上"
 ```
 
 AI 会自动识别意图，触发对应的 Skill。
@@ -54,17 +55,17 @@ AI 会自动识别意图，触发对应的 Skill。
 
 ## 9 个 Skill 速览
 
-| Skill              | 触发关键词                     | 用途                         |
-| ------------------ | ------------------------------ | ---------------------------- |
-| `prototype-scan`   | 扫描原型 / 解析原型 / 口述需求 | 原型 / 详设 → page-spec JSON |
-| `api-contract`     | 接口约定 / api.md / 字段定义   | 生成接口约定文档             |
-| `page-codegen`     | 生成页面 / 帮我生成            | 生成页面骨架 + 菜单注册       |
+| Skill              | 触发关键词                     | 用途                                                 |
+| ------------------ | ------------------------------ | ---------------------------------------------------- |
+| `prototype-scan`   | 扫描原型 / 解析原型 / 口述需求 | 原型 / 详设 → page-spec JSON                         |
+| `api-contract`     | 接口约定 / api.md / 字段定义   | 生成接口约定文档                                     |
+| `page-codegen`     | 生成页面 / 帮我生成            | 生成页面骨架 + 菜单注册                              |
 | `menu-sync`        | 创建菜单 / 同步菜单            | 菜单数据同步到后端（MCP 自动 / prompt 手动两种模式） |
-| `dict-sync`        | 同步字典 / 创建字典 / 字典审计   | 字典基线同步到后端（MCP 自动 / prompt 手动两种模式） |
-| `convention-audit` | 规范审计 / 代码审计            | 13 条规范扫描 + 偏差报告     |
-| `template-extract` | 提取模板 / 抄取模板            | 从现有页面沉淠领域专属模板   |
-| `permission-sync`  | 创建角色 / 角色授权 / 同步权限   | 角色+授权+动作权限同步（MCP） |
-| `code-fix`         | 自动修复 / 整改偏差 / 规范整改   | 受控自动修复审计报告中的偏差 |
+| `dict-sync`        | 同步字典 / 创建字典 / 字典审计 | 字典基线同步到后端（MCP 自动 / prompt 手动两种模式） |
+| `convention-audit` | 规范审计 / 代码审计            | 13 条规范扫描 + 偏差报告                             |
+| `template-extract` | 提取模板 / 抄取模板            | 从现有页面沉淠领域专属模板                           |
+| `permission-sync`  | 创建角色 / 角色授权 / 同步权限 | 角色+授权+动作权限同步（MCP）                        |
+| `code-fix`         | 自动修复 / 整改偏差 / 规范整改 | 受控自动修复审计报告中的偏差                         |
 
 完整调度规则见 `.github/skills/_registry.md`。
 
@@ -79,7 +80,7 @@ AI 会自动识别意图，触发对应的 Skill。
 ├── .github/
 │   ├── copilot-instructions.md      AI 主入口
 │   ├── standards/                   13 条模块化规范
-│   ├── skills/                      8 个 Skill + 1 个 PLANNED 草稿
+│   ├── skills/                      9 个启用 Skill + 多编辑器适配
 │   ├── guides/                      使用指南 + 架构设计
 │   └── reports/                     AI 生成报告（SYS_MENU_INFO 等）
 ├── docs/                            12 个组件 API 文档（jh-* / request 等）
@@ -105,9 +106,28 @@ AI 会自动识别意图，触发对应的 Skill。
 ```
 
 > **说明**：每一步都可以单独触发，也可以按用户意图自动接续。
+>
 > - `dict-sync`：首次使用先跑 **pull 模式**（「刷新字典基线」）建立本地基线，再跑 push 模式同步差异。
 > - `code-fix`：只修复 🟡/🟢 偏差；🔴 严重偏差必须人工或 page-codegen 处理。每条修复前强制 diff 预览确认。
 
+### 页面生成最终标准
+
+`page-codegen` 生成的业务列表/台账/主从/树表页面必须满足：
+
+- `AbstractPageQueryHook + BaseQuery + BaseToolbar + BaseTable + jh-pagination`
+- `BaseTable` 必须 `render-type="agGrid"`
+- 每个 `BaseTable` 必须有全局唯一 `cid`
+- 列定义必须使用 `@agile-team/wk-skills-ui/runtime` 的 `defineColumns()`
+- 操作列必须使用 `renderOps()`，禁止旧式 `operations: []`
+- mock-first：后端未就绪时生成 `mock/*.ts`，关闭 mock 后业务代码不需要改
+
+生成后建议运行：
+
+```bash
+wl-skills validate-page src/views/<页面目录>
+wl-skills doctor-ui
+```
+
 ---
 
 ## 常见问题
@@ -131,6 +151,9 @@ Windsurf、Cline、Trae、Qoder 仅支持全局配置，需手动操作一次，
 
 配置完成后在 `.github/skills/sync/env.local.json` 中填好 `token`、`gatewayPath`、`menu.domainId`，重启编辑器，对 AI 说「扩展菜单」或「加字典」，AI 会自动调用 MCP 工具完成同步，无需手动粘贴接口响应。
 
+**Q: 如何和 wk-skills-ui 一起用？**
+A: 两个包不互相依赖。先用 `wl-skills-kit` 做页面生成、规范审计、菜单字典权限同步；如需统一 UI 风格或老系统化妆层，再单独安装 `@agile-team/wk-skills-ui` 并执行 `wk-ui init/update`。
+
 **Q: 部署到生产环境前如何清理 AI 文件？**
 A: 执行 `npx @agile-team/wl-skills-kit clean`。会移除所有 AI 辅助文件，保留 `src/components/` 和 `src/types/`。
 
@@ -138,6 +161,18 @@ A: 执行 `npx @agile-team/wl-skills-kit clean`。会移除所有 AI 辅助文
 
 ## 升级与维护
 
+### 生命周期命令
+
+```bash
+npx @agile-team/wl-skills-kit check        # 环境/MCP/manifest 体检
+npx @agile-team/wl-skills-kit diff         # 查看与当前包版本差异
+npx @agile-team/wl-skills-kit validate-page src/views/xxx # 单页/目录强校验
+npx @agile-team/wl-skills-kit doctor-ui    # wk-skills-ui 接入体检
+npx @agile-team/wl-skills-kit update       # 增量更新
+npx @agile-team/wl-skills-kit clean        # 清理 AI 文件，保留 src/components + src/types
+npx @agile-team/wl-skills-kit export       # 导出菜单/字典/权限基线 xlsx
+```
+
 ### 增量更新
 
 ```bash

package/files/.github/skills/_compat/README.md

@@ -29,7 +29,8 @@ _compat/
     ├── cline.txt
     ├── kiro.txt                （.kiro/steering/conventions.md，含 frontmatter）
     ├── trae.txt                （.trae/rules/conventions.md，含 frontmatter）
-    └── agents.txt              （AGENTS.md 通用代理）
+    ├── agents.txt              （AGENTS.md 通用代理）
+    └── qoder.txt               （.qoder/rules/conventions.md）
 ```
 
 ---
@@ -57,7 +58,7 @@ bin/wl-skills.js (init/update)
 | ------------------------------------- | ----------------------------- | --------------------------- |
 | 团队不用 Cursor，从 editors.json 删除 | `.cursorrules`、`.cursor/`    | `.github/`、CLAUDE.md、其他 |
 | 团队新增某 AI 编辑器（如 Augment）    | 加 headers/augment.txt + 注册 | 其他文件不动                |
-| `copilot-instructions.md` 内容更新    | 全部 8 个根配置同步更新       | headers/ 不变（只是模板）   |
+| `copilot-instructions.md` 内容更新    | 全部编辑器根配置同步更新       | headers/ 不变（只是模板）   |
 
 ---
 
@@ -104,5 +105,6 @@ bin/wl-skills.js (init/update)
 | Kiro           | `.kiro/steering/*.md`                  | ✅                   | 需 inclusion 字段                |
 | Trae           | `.trae/rules/*.md`                     | ✅                   | 需 description 字段              |
 | 通用 Agent     | `AGENTS.md` (root)                     | ❌                   | 新兴跨平台规范                   |
+| Qoder          | `.qoder/rules/conventions.md`          | ✅                   | 项目规则文件                     |
 
 > 所有这些编辑器在加载完根配置后，**都支持按指令读取项目内任意文件**（含 `.github/standards/`、`.github/skills/`、`.github/guides/`），所以本架构的"懒加载门控 + 子目录规范"对所有编辑器**有效**。

package/files/.github/skills/_registry.md

@@ -38,17 +38,17 @@ skills/
 
 ## 启用 Skill 路由表
 
-| Skill 名         | 状态       | 路径                                         | 触发关键词                                                                 |
-| ---------------- | ---------- | -------------------------------------------- | -------------------------------------------------------------------------- |
-| prototype-scan   | ✅ 启用    | `skills/core/prototype-scan/SKILL.md`        | 扫描原型 / 解析原型 / 页面清单 / 详设文档 / 口述需求 / 建个页面 / 写个页面 |
-| api-contract     | ✅ 启用    | `skills/core/api-contract/SKILL.md`          | 接口约定 / api.md / 字段定义 / 前后端对齐 / 接口设计                       |
-| page-codegen     | ✅ 启用    | `skills/core/page-codegen/SKILL.md`          | 生成页面 / 创建页面 / 代码生成 / vue页面 / 按原型生成 / 帮我生成           |
-| convention-audit | ✅ 启用    | `skills/core/convention-audit/SKILL.md`      | 规范审计 / 代码审计 / 规范检查 / 对齐规范 / 规范偏差 / 接手新项目 / 存量代码分析 / 项目体检 |
-| template-extract | ✅ 启用    | `skills/core/template-extract/SKILL.md`      | 提取模板 / 抽取模板 / 沉淀模板 / 模板贡献                                  |
-| menu-sync        | ✅ 启用    | `skills/sync/menu-sync/SKILL.md`             | 创建菜单 / 注册菜单 / 同步菜单 / 补菜单                                    |
-| dict-sync        | ✅ 启用    | `skills/sync/dict-sync/SKILL.md`             | 同步字典 / 创建字典 / 刷新字典基线 / 字典对比 / 字典审计                           |
-| permission-sync  | ✅ 启用    | `skills/sync/permission-sync/SKILL.md`       | 创建角色 / 角色管理 / 角色授权 / 给角色分配菜单 / 挂动作 / 添加动作按钮 / 同步权限 / 权限码注册 |
-| code-fix         | ✅ 启用    | `skills/ops/code-fix/SKILL.md`               | 自动修复 / 整改偏差 / 修复报告 / 规范整改 / 修复偏差 / code fix               |
+| Skill 名         | 状态    | 路径                                    | 触发关键词                                                                                                                              |
+| ---------------- | ------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| prototype-scan   | ✅ 启用 | `skills/core/prototype-scan/SKILL.md`   | 扫描原型 / 解析原型 / 页面清单 / 详设文档 / 口述需求 / 建个页面 / 写个页面 / 根据截图 / 根据原型                                        |
+| api-contract     | ✅ 启用 | `skills/core/api-contract/SKILL.md`     | 接口约定 / api.md / 字段定义 / 前后端对齐 / 接口设计                                                                                    |
+| page-codegen     | ✅ 启用 | `skills/core/page-codegen/SKILL.md`     | 生成页面 / 创建页面 / 代码生成 / vue页面 / 按原型生成 / 帮我生成 / 列表页 / 管理页 / 台账 / mock / 假数据 / 先能跑 / AGGrid / skills-ui |
+| convention-audit | ✅ 启用 | `skills/core/convention-audit/SKILL.md` | 规范审计 / 代码审计 / 规范检查 / 对齐规范 / 规范偏差 / 接手新项目 / 存量代码分析 / 项目体检                                             |
+| template-extract | ✅ 启用 | `skills/core/template-extract/SKILL.md` | 提取模板 / 抽取模板 / 沉淀模板 / 模板贡献                                                                                               |
+| menu-sync        | ✅ 启用 | `skills/sync/menu-sync/SKILL.md`        | 创建菜单 / 注册菜单 / 同步菜单 / 补菜单 / 页面点击进不来 / 菜单打不开                                                                   |
+| dict-sync        | ✅ 启用 | `skills/sync/dict-sync/SKILL.md`        | 同步字典 / 创建字典 / 刷新字典基线 / 字典对比 / 字典审计                                                                                |
+| permission-sync  | ✅ 启用 | `skills/sync/permission-sync/SKILL.md`  | 创建角色 / 角色管理 / 角色授权 / 给角色分配菜单 / 挂动作 / 添加动作按钮 / 同步权限 / 权限码注册                                         |
+| code-fix         | ✅ 启用 | `skills/ops/code-fix/SKILL.md`          | 自动修复 / 整改偏差 / 修复报告 / 规范整改 / 修复偏差 / code fix                                                                         |
 
 ---
 
@@ -58,6 +58,8 @@ skills/
 2. SKILL.md 中标注的 `必读 standards` 按 `standards/index.md` 任务类型映射加载
 3. 如用户表达连续交付/智能体/全流程意图，同时读取 `_pipeline.md` 获取 Skill I/O 与 `next_suggest`
 4. 在 SKILL.md 指示下输出 **Pre-flight 声明**（强制约定式输出）
+5. 页面生成任务必须额外读取 `standards/12-base-table.md`，并执行 `BaseTable + render-type="agGrid" + cid + defineColumns + renderOps` 硬约束
+6. 若消息包含“风格 / skills-ui / 状态标签 / 操作列 / AGGrid”，同时建议运行 `wl-skills doctor-ui`
 
 ---
 
@@ -75,9 +77,9 @@ skills/
 
 每个启用 Skill 同目录下都有 `USAGE.md`：
 
-| 文件            | 读者           | 用途                                       |
-| --------------- | -------------- | ------------------------------------------ |
-| `SKILL.md`      | AI 编辑器/模型 | 触发规则、流程步骤、Pre-flight 声明        |
-| `USAGE.md`      | 团队成员       | 示例对话、踩坑、FAQ、快速上手              |
+| 文件            | 读者                      | 用途                                                     |
+| --------------- | ------------------------- | -------------------------------------------------------- |
+| `SKILL.md`      | AI 编辑器/模型            | 触发规则、流程步骤、Pre-flight 声明                      |
+| `USAGE.md`      | 团队成员                  | 示例对话、踩坑、FAQ、快速上手                            |
 | `_pipeline.md`  | AI 编辑器/模型 + 团队成员 | Skill 间 I/O 契约、next_suggest、Agent Pipeline 调度协议 |
-| `*.MAINTAIN.md` | kit 维护者     | 维护要点（在 `kit-internal/skills/` 目录） |
+| `*.MAINTAIN.md` | kit 维护者                | 维护要点（在 `kit-internal/skills/` 目录）               |

package/files/.github/skills/core/page-codegen/SKILL.md

@@ -119,6 +119,15 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 18. **按钮必须可交互**：所有按钮的 `onClick` 必须有真实处理逻辑，禁止空函数 `() => {}`。通用交互实现见下方 §按钮交互实现规则
 19. **未知交互兜底**：当原型未提供交互细节、且无法从通用模式推断时，`onClick` 中使用 `ElMessage.info("需业务确认交互逻辑")` 作为占位
 20. **生成后依赖自检**：代码生成完成后，检查 `package.json` 是否已安装生成代码所需的依赖（`mockjs`、`vite-plugin-mock`、`lodash-es`、`xlsx` 等），若缺失则提示用户执行安装命令。同时检查 `vite.config.ts` 是否已注册 `viteMockServe`、`mock/` 目录是否存在
+21. **默认 Mock First**：新生成页面默认必须走 `vite-plugin-mock`。必须生成 `mock/[页面kebab-name].ts`，并确保 `API_CONFIG` 中每个 URL 都有对应 mock 端点；只有当用户明确要求关闭 mock 或 `.env.dev` 中 `ENV_MOCK=false` 时，才允许直接联调真实接口。
+22. **Mock URL 必须匹配真实请求**：`API_CONFIG` 保持真实接口路径（如 `/mdata/mdataModel/list`），mock 文件端点必须带 Vite 代理前缀（如 `/dev-api/mdata/mdataModel/list`），这样关闭 mock 后无需修改业务代码。
+23. **页面初始数据必须由 mock 提供**：列表页 `onMounted(() => select())` 后必须能显示模拟数据，不允许生成空白页等待后端接口；`list` 端点返回 `{ code: 2000, data: { records, total, size, current } }`。
+24. **必须使用 wk-skills-ui runtime 风格**：当项目安装了 `@agile-team/wk-skills-ui` 时，列表列定义必须使用 `defineColumns()`，操作列必须使用 `renderOps()`，状态/字典列优先使用 runtime 渲染器或 `logicType=dict` 自动映射；不可退回默认纯文本/空函数风格。
+25. **wk-skills-ui 接入自检**：生成页面前检查项目是否已接入 `@agile-team/wk-skills-ui` 样式与 runtime。若未接入，先提示并补齐：`@use '@agile-team/wk-skills-ui/styles' as *;`、`installCommonPreset()`、必要的 design tokens 引入；否则页面风格不会自动生效。
+26. **pages.ts 分组注册**：多页面模块必须按当前业务目录分组写入 `vite/plugins/shared/pages.ts`，使用 `gProd(module, { subModule: [[page, label]] })` 结构，不允许把所有页面扁平追加到一个数组。
+27. **BaseTable 强制 AGGrid**：所有业务主列表/台账/主从表/树表/详情子表的 `BaseTable` 必须显式写 `render-type="agGrid"`，并绑定全局唯一 `cid`。弹窗小表格可豁免，但必须在生成摘要中说明理由。
+28. **cid 必须可追踪**：每个页面导出 `TABLE_CID = "{pageAbbr}-{base36Timestamp}"`；多表页面使用 `BOTTOM_TABLE_CID` / `ITEM_TABLE_CID`，列级 `cid` 必须使用 `${TABLE_CID}-fieldName` 前缀。
+29. **skills-ui 只能融合，不可生搬硬套**：不得照搬 `wk-skills-ui/templates/list-page` 中的原生 `el-form/usePageHook/el-pagination` 通用写法；本项目必须保留 `AbstractPageQueryHook + BaseQuery + BaseToolbar + BaseTable + jh-pagination` 平台骨架，只融合 `defineColumns/renderOps/tokens/preset`。
 
 ### 禁止事项（严格遵守）
 
@@ -135,6 +144,11 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 11. **❌ 禁止表单控件宽度不统一**：`jh-select`、`jh-date`、`el-input-number`、`jh-file-upload` 默认宽度可能与 `el-input` 不一致，必须在 scoped style 中用 `:deep()` 统一设为 `width: 100%`（详见 §表单页 UI 细节规范）
 12. **❌ 禁止表单页无滚动**：独立路由表单页内容超出视口时必须可滚动，`.app-page-container` 须设 `overflow-y: auto`（**不要加 `height: 100%`，全局已有 `height: calc(100vh - 100px)`，叠加会导致双滚动条**）
 13. **❌ 禁止内联 style 散落**：所有页面/组件样式统一写在 `index.scss` 中（便于复用和移动），不可在 template 中大量使用内联 `style="..."`
+14. **❌ 禁止生成无 mock 的页面**：只写 `API_CONFIG` 但不写 `mock/*.ts` 属于生成失败。
+15. **❌ 禁止生成空 onClick**：`onClick: () => {}` 属于生成失败；未知逻辑也必须用 `ElMessage.info(...)` 明示。
+16. **❌ 禁止忽略 wk-skills-ui**：项目已安装 `@agile-team/wk-skills-ui` 时，不使用 `defineColumns/renderOps` 属于生成失败。
+17. **❌ 禁止 BaseTable 非 AGGrid**：业务列表中 `<BaseTable>` 未写 `render-type="agGrid"` 或缺少 `cid/:cid` 属于生成失败。
+18. **❌ 禁止列缺 cid**：AGGrid 表格的数据列/操作列缺少列级 `cid` 属于生成失败。
 
 ### c_formModal 使用规范
 
@@ -294,18 +308,20 @@ export function createPage() {
       ];
     }
     columnsDef(): TableColumnDesc<any>[] {
-      return [
+      return defineColumns([
         // ...
         {
           label: "操作",
-          operations: [
-            {
-              label: "编辑",
-              onClick: (row: any) => navigateToForm({ id: row.id })  // 带 id：编辑
-            }
-          ]
+          name: "_action",
+          cid: `${TABLE_CID}-action`,
+          fixed: "right",
+          align: "center",
+          defaultSlot: ({ row }: any) =>
+            renderOps([
+              { type: "edit", onClick: () => navigateToForm({ id: row.id }) }  // 带 id：编辑
+            ])
         }
-      ];
+      ] as any) as TableColumnDesc<any>[];
     }
   })();
   return Page.create() as any;
@@ -401,34 +417,38 @@ const ids = rows.map((r: any) => r.id);
 ```typescript
 {
   label: "操作",
+  name: "_action",
+  cid: `${TABLE_CID}-action`,
   width: 140,
   fixed: "right",
-  operations: [
-    {
-      name: "edit",
-      label: "修改",
-      show: (row: any) => row.verifyStatus === "已核实",
-      onClick: (row: any) => _editModalRef?.value?.edit(row.id)
-    },
-    {
-      name: "danger",
-      label: "作废",
-      show: (row: any) => row.verifyStatus === "已核实",
-      onClick: (row: any) => { /* cancel API */ }
-    },
-    {
-      name: "edit",
-      label: "编辑",
-      show: (row: any) => row.verifyStatus !== "已核实",
-      onClick: (row: any) => _editModalRef?.value?.edit(row.id)
-    },
-    {
-      name: "remove",
-      label: "删除",
-      show: (row: any) => row.verifyStatus !== "已核实",
-      onClick: (row: any) => { /* remove API */ }
-    }
-  ]
+  align: "center",
+  defaultSlot: ({ row }: any) =>
+    renderOps([
+      {
+        type: "edit",
+        label: "修改",
+        show: () => row.verifyStatus === "已核实",
+        onClick: () => _editModalRef?.value?.edit(row.id)
+      },
+      {
+        type: "danger",
+        label: "作废",
+        show: () => row.verifyStatus === "已核实",
+        onClick: () => handleCancel(row)
+      },
+      {
+        type: "edit",
+        label: "编辑",
+        show: () => row.verifyStatus !== "已核实",
+        onClick: () => _editModalRef?.value?.edit(row.id)
+      },
+      {
+        type: "del",
+        label: "删除",
+        show: () => row.verifyStatus !== "已核实",
+        onClick: () => Page?.remove(row.id)
+      }
+    ])
 }
 ```
 
@@ -497,15 +517,24 @@ function renderStatusTag(row: any, field: string) {
 let Page: any = null;
 
 export function managementColumns(): TableColumnDesc<any>[] {
-  return [
+  return defineColumns([
     // ...
-    { label: "操作", fixed: "right", width: 100, operations: [
-      { name: "remove", label: "删除", onClick: (row: any) => Page?.remove(row.id) }
-    ]}
-  ];
+    {
+      label: "操作",
+      name: "_action",
+      cid: `${TABLE_CID}-management-action`,
+      fixed: "right",
+      width: 100,
+      align: "center",
+      defaultSlot: ({ row }: any) =>
+        renderOps([
+          { type: "del", label: "删除", onClick: () => Page?.remove(row.id) }
+        ])
+    }
+  ] as any) as TableColumnDesc<any>[];
 }
 export function usageColumns(): TableColumnDesc<any>[] {
-  return [ /* 使用视角列... */ ];
+  return defineColumns([ /* 使用视角列... */ ] as any) as TableColumnDesc<any>[];
 }
 
 export function createPage(editModalRef?: any) {
@@ -866,6 +895,50 @@ import { BaseQueryItemDesc } from "@jhlc/common-core/src/components/form/base-qu
 
 page-codegen 生成页面代码后，**必须追加写入菜单配置信息到 `reports/SYS_MENU_INFO.md`**。
 
+## pages.ts 分组注册规则（Module Federation 子应用）
+
+多页面子应用必须使用与 `wl-mdata` 验证一致的分组模式，禁止扁平追加：
+
+```typescript
+import type { SharedPageItem } from "./utils";
+
+type PageTuple = [string, string];
+type SubModuleMap = Record<string, PageTuple[]>;
+
+const gProd = (module: string, subModules: SubModuleMap): SharedPageItem[] =>
+  Object.entries(subModules).flatMap(([subModule, pages]) =>
+    pages.map(([page, label]) => ({
+      name: `${module}/${subModule}/${page}/index.vue`,
+      label
+    }))
+  );
+
+const mdataModule = gProd("mdata", {
+  model: [
+    ["mdata-model-config", "主数据模型配置"],
+    ["mdata-attr-mapping", "属性映射管理"]
+  ],
+  integration: [
+    ["mdata-integ-system", "集成系统管理"]
+  ]
+});
+
+export const list: SharedPageItem[] = mdataModule;
+export default list;
+```
+
+生成规则：
+
+| 字段 | 规则 |
+| --- | --- |
+| `module` | 来自项目启动参数 `--module=xxx`，如 `mdata` |
+| `subModule` | 来自页面目录第二级，如 `src/views/mdata/model/...` → `model` |
+| `page` | 页面 kebab 目录名，如 `mdata-model-config` |
+| `name` | `${module}/${subModule}/${page}/index.vue` |
+| `label` | 页面中文名 |
+
+> menu-sync 的 `component` 必须与 `pages.ts` 生成的 `name` 完全一致，否则菜单能创建但点击无法加载页面。
+
 ### 写入策略（默认追加，不覆盖）
 
 - **默认为追加模式**：保留已有内容，在末尾追加本次生成的菜单。避免覆盖团队之前累积的菜单记录。
@@ -875,24 +948,27 @@ page-codegen 生成页面代码后，**必须追加写入菜单配置信息到 `
 
 ### 生成模板
 
-每个页面生成一个菜单条目，格式如下：
+多级菜单必须先写目录（`type=M`），再在目录下写页面菜单（`type=C`）。格式如下：
 
 ```markdown
-## [序号]. [菜单名称]
-
-| 字段         | 填写值 |
-| ------------ | ------ |
-| 类型 Tab     | 选择 **菜单** |
-| 上级目录     | `[父目录名]` |
-| 应用选择     | `[应用名]` |
-| 使用缓存     | ◉ 使用 |
-| 显示排序     | `[序号]` |
-| 菜单路径     | `[camelCase目录名]` |
-| 菜单名称     | `[中文名]` |
-| 名称编码后缀 | `[菜单路径拼音小写]` |
-| 组件路径     | `[域]/[模块]/[子模块]/[kebab-目录名]/index.vue` |
-| 权限标识     | `[camelCase目录名]` |
-| 是否隐藏     | **否** / **是** |
+# 系统菜单配置 — [项目名] [业务模块]
+
+> **module 命名**：`[module]`
+> **父级菜单**：来自 `.github/skills/sync/env.local.json` 的 `menu.parentMenuId`
+
+## 一级目录（type=M）
+
+| # | 菜单名 | path | orderNum | 备注 |
+| - | ------ | ---- | -------- | ---- |
+| 1 | [目录中文名] | `[目录pathCamel]` | 1 | 含 N 个子菜单 |
+
+## 二级菜单（type=C）
+
+### 1. [目录中文名] 子菜单
+
+| 菜单名 | path | component | permission |
+| ------ | ---- | --------- | ---------- |
+| [页面中文名] | `[pageCamel]` | `[module]/[subModule]/[pageKebab]/index.vue` | `[module]:[pageCamel]:list` |
 ```
 
 ### 字段生成规则
@@ -901,8 +977,8 @@ page-codegen 生成页面代码后，**必须追加写入菜单配置信息到 `
 |------|------|------|
 | 菜单路径 | page-spec.kebabName | kebab-case → camelCase（`mmwr-customer-archive` → `mmwrCustomerArchive`） |
 | 菜单名称 | page-spec.pageName | 直接使用中文名 |
-| 组件路径 | pages.ts 注册路径 | `[域]/[模块]/[子模块]/[kebab-目录名]/index.vue` |
-| 权限标识 | 同菜单路径 | camelCase |
+| 组件路径 | pages.ts 注册路径 | `[module]/[subModule]/[kebab-目录名]/index.vue` |
+| 权限标识 | module + 菜单路径 | `[module]:[pageCamel]:list` |
 | 是否隐藏 | page-spec.features.hiddenMenu | `true` → 是，`false` → 否 |
 | 上级目录 | 用户指定 / page-spec 推断 | 如果用户在原型扫描阶段指定了上级目录，使用该值 |
 | 应用选择 | pages.ts 域名 | `produce` → 生产，`sale` → 销售 |
@@ -919,29 +995,27 @@ page-codegen 生成页面代码后，**必须追加写入菜单配置信息到 `
 ### SYS_MENU_INFO.md 文件结构
 
 ```markdown
-# 系统菜单配置 — [模块名称]（[域] / [子模块路径]）
+# 系统菜单配置 — [项目名] [模块名]
 
-> 对应系统管理 → 菜单管理 → 新增菜单，每栏直接复制粘贴。
-> **操作顺序：先建目录（第 0 步），再逐个添加菜单。**
->
-> **pages.ts 注册位置**：`vite/plugins/shared/pages.ts` → `[模块变量名]` → `[子模块key]`
+> **父级菜单**：`[parentMenuId]`
+> **应用编码**：`[sysAppNo]`
+> **module 命名**：`[module]`
 
-## 第 0 步：新建目录（如需要）
+## 一级目录（type=M）
 
-| 字段     | 值 |
-| -------- | -- |
-| 上级目录 | `[上级目录名]` |
-| 菜单名称 | `[目录名]` |
-| 显示排序 | `[序号]` |
+| # | 菜单名 | path | orderNum | 备注 |
+| - | ------ | ---- | -------- | ---- |
+| 1 | [目录名] | `[目录pathCamel]` | 1 | 含 N 个子菜单 |
 
-## 第 1 步：[页面名称]
+## 二级菜单（type=C）
 
-[菜单条目表格]
+### 1. [目录名] 子菜单
 
-> pages.ts 对应：`["[kebab-name]", "[中文名]"]`
+| 菜单名 | path | component | permission |
+| ------ | ---- | --------- | ---------- |
+| [页面名称] | `[pageCamel]` | `[module]/[subModule]/[pageKebab]/index.vue` | `[module]:[pageCamel]:list` |
 
-## 第 2 步：[页面名称]
-...
+> pages.ts 对应：`gProd("[module]", { [subModule]: [["[pageKebab]", "[页面名称]"]] })`
 ```
 
 ### 与 menu-sync 的衔接
@@ -950,6 +1024,7 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 - **自动创建**：用户说"帮我创建菜单" → menu-sync 读取 SYS_MENU_INFO.md → 调 API 逐条创建
 - **手动创建**：用户也可直接按 SYS_MENU_INFO.md 的表格在系统管理后台手动创建菜单
 - 两种方式等价，菜单创建后通过 `组件路径` 字段与 pages.ts 注册的文件路径关联
+- **自动创建顺序**：必须先调用 `wls_menu_query` 获取当前 domain 菜单树，再 `wls_menu_upsert` 创建/更新一级目录（type=M），拿到目录 id 后再创建二级菜单（type=C）。不得把二级页面全部直接挂到根 `parentMenuId`。
 
 ---
 

package/files/.github/skills/core/page-codegen/USAGE.md

@@ -7,7 +7,7 @@
 
 ## 这个 Skill 解决什么问题
 
-基于《页面清单》+ `api.md`，**自动生成符合项目规范的 Vue 页面**（标准页面骨架：index.vue / data.ts / index.scss + api.md 按需），并跑一遍内部规范自检（Pre-flight + 完成摘要）。
+基于《页面清单》+ `api.md`，**自动生成符合项目规范的 Vue 页面**（标准页面骨架：index.vue / data.ts / index.scss + api.md + mock 按需），并跑一遍内部规范自检（Pre-flight + 完成摘要）。
 
 生成出来的代码**满足 13 条 standards**，无需手工改语法/命名。
 
@@ -23,7 +23,9 @@
 
 ## 触发关键词
 
-`生成页面` / `创建页面` / `代码生成` / `vue 页面` / `按原型生成` / `帮我生成`
+`生成页面` / `创建页面` / `代码生成` / `vue 页面` / `按原型生成` / `帮我生成` / `列表页` / `管理页` / `台账` / `mock` / `先能跑` / `AGGrid` / `skills-ui`
+
+用户不需要精确说出 Skill 名。只要表达“做个页面”“根据截图生成”“先用假数据”“菜单也加上”“风格没生效”，AI 应自动进入 Intent Router，读取 `page-codegen/SKILL.md`、模板索引、匹配模板和 `standards/12-base-table.md`。
 
 ---
 
@@ -37,8 +39,9 @@ AI：[Pre-flight]
     模板基线：templates/domains/produce/customer/
     13 条 standards 自检通过项预估：
     ✓ AbstractPageQueryHook 正确继承
-    ✓ EColumn 元数据完备
-    ✓ pageRef 命名规范
+    ✓ BaseTable render-type="agGrid"
+    ✓ TABLE_CID / 列级 cid 完整
+    ✓ defineColumns / renderOps 已使用
     ✓ scoped scss
     ⚠ 待确认：customerStatus 字典 logicValue 名
     [生成中... 8 分钟]
@@ -56,10 +59,11 @@ AI：[Pre-flight]
 
 ```
 src/views/<域>/<模块>/<子模块>/<page-name>/
-├── data.ts        EColumn 定义、API_CONFIG、Hook 类
+├── data.ts        API_CONFIG、Hook 类、TABLE_CID、defineColumns/renderOps
 ├── index.vue      template + script + import data.ts
 ├── index.scss     页面专属样式（已 :deep / scoped 包好）
-└── api.md         （由 api-contract 生成，codegen 不覆盖）
+├── api.md         （由 api-contract 生成，codegen 不覆盖）
+└── mock/*.ts      mock-first 场景下生成，端点与 API_CONFIG 对齐
 ```
 
 外加生成报告：`.github/reports/PAGE_CODEGEN_<模块>_<YYYYMMDD>.md`
@@ -81,12 +85,29 @@ src/views/<域>/<模块>/<子模块>/<page-name>/
 
 ## 常见踩坑
 
-| 现象                                | 原因                                   | 解法                                                |
-| ----------------------------------- | -------------------------------------- | --------------------------------------------------- |
-| 生成出来的页面 console 报字典查不到 | 字典还没在 reports/SYS_DICT_INFO.md 中 | 先跑 `dict-sync` 拉取，或手动补 dict                |
-| 表单弹窗未加 v-loading              | api.md 没标记 save/update 为耗时操作   | 在 api.md 接口清单中加 `**预计耗时：> 2s**` 标记    |
-| `EColumn` 字段缺 `width`            | 模板默认不指定 width                   | 模板里手动加，或选用 `templates/domains/` 下的成品  |
-| AGGrid cid 重复                     | 多页面同时生成时随机数撞了             | cid 已用 `{首字母缩写}-{Unix秒后6位}`，理论极低概率 |
+| 现象                                | 原因                                   | 解法                                                                          |
+| ----------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------- |
+| 生成出来的页面 console 报字典查不到 | 字典还没在 reports/SYS_DICT_INFO.md 中 | 先跑 `dict-sync` 拉取，或手动补 dict                                          |
+| 表单弹窗未加 v-loading              | api.md 没标记 save/update 为耗时操作   | 在 api.md 接口清单中加 `**预计耗时：> 2s**` 标记                              |
+| `EColumn` 字段缺 `width`            | 模板默认不指定 width                   | 模板里手动加，或选用 `templates/domains/` 下的成品                            |
+| AGGrid cid 重复                     | cid 生成不规范                         | 使用 `{页面目录首字母缩写}-{Date.now().toString(36)}`，多表追加 `-sub1/-sub2` |
+| 表格不是 AGGrid                     | 模板未写 `render-type="agGrid"`        | 使用最新模板，或运行 `wl-skills validate-page <页面目录>`                     |
+| 操作列还是旧按钮                    | 生成了 `operations: []`                | 改成 `defaultSlot + renderOps()`                                              |
+| skills-ui 安装但风格没生效          | tokens/styles/preset/runtime 未接入    | 运行 `wl-skills doctor-ui` 查看缺项                                           |
+
+---
+
+## 生成后建议命令
+
+```bash
+wl-skills validate-page src/views/<module>/<subModule>/<page>
+wl-skills doctor-ui
+```
+
+若 AI 可调用 MCP，优先使用：
+
+- `wls_validate_page`
+- `wls_doctor_ui`
 
 ---