@agile-team/wl-skills-kit 1.2.1 → 2.1.0

package/files/.github/skills/core/convention-audit/USAGE.md

@@ -0,0 +1,99 @@
+# 使用指南：convention-audit（规范审计）
+
+> **谁读这个文档**：团队成员（主要前端、code reviewer）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+对**指定文件/目录**或**全量项目**跑一遍 13 条 standards 检查，输出：
+
+1. **AI 自查报告**（reports/AUDIT*AI*\*.md）— 给 AI 看的，含修复建议
+2. **人读摘要报告**（reports/AUDIT*HUMAN*\*.md）— 给团队 review 用的，含通过率/Top 偏差
+
+---
+
+## 何时使用
+
+- code review 前自检
+- 接手老页面，想知道偏差有多大
+- 重构大模块前，先量化欠债
+- PR 卡住找原因（哪条规范没过）
+
+---
+
+## 触发关键词
+
+`规范审计` / `代码审计` / `规范检查` / `对齐规范` / `规范偏差`
+
+---
+
+## 标准对话示例
+
+```
+你：审计 src/views/produce/aiflow/mmwr-customer-archive/ 这个页面
+AI：[Pre-flight]
+    审计目标：1 个页面（4 个文件）
+    应用规范：13 条 standards
+    输出：
+    - reports/AUDIT_AI_mmwr-customer-archive_20260426.md
+    - reports/AUDIT_HUMAN_mmwr-customer-archive_20260426.md
+    [扫描中...]
+    完成。13 条标准通过 11 条，2 条需关注：
+    ⚠ standards/data-ts.md - EColumn.cid 缺失 1 处
+    ⚠ standards/scss.md - 全局样式污染（缺 :scoped）
+    详见 reports/。
+```
+
+---
+
+## 输出物结构
+
+### AI 自查报告（详细）
+
+按规范逐条列：
+
+- ✅ 通过：simple count
+- ⚠ 偏差：文件路径 + 行号 + 偏差描述 + 修复建议（含代码片段）
+- ❌ 严重：阻断性问题
+
+### 人读摘要
+
+- 总体通过率
+- Top 5 偏差类型
+- 最严重的 3 个文件
+- 修复优先级建议（高/中/低）
+
+---
+
+## 团队使用流程
+
+1. **PR 自检**：作者先跑一遍审计，修掉高优先级再提 PR
+2. **CR 辅助**：reviewer 看人读摘要快速定位
+3. **季度健康度**：每季度跑一次全量审计，跟踪趋势
+4. **新人培训**：让新人审计自己写的页面，对照标准学
+
+---
+
+## 常见踩坑
+
+| 现象                                 | 原因                                   | 解法                                    |
+| ------------------------------------ | -------------------------------------- | --------------------------------------- |
+| 审计跑很久（> 10 分钟）              | 一次性审了上千文件                     | 缩小范围到模块或页面级                  |
+| 偏差数据"漂移"（同代码两次结果不同） | AI 模型版本不同                        | 锁定 IDE 模型版本，或以 AI 自查报告为准 |
+| 误报字典字段未定义                   | 字典在 reports/SYS_DICT_INFO.md 但跨域 | 在 standards/data-ts.md 里允许跨域字典  |
+| Pre-flight 没声明                    | AI 跳过了门控                          | 显式说"按 SKILL.md 执行 Pre-flight"     |
+
+---
+
+## FAQ
+
+**Q：审计结果可以自动修复吗？**
+A：单个偏差可以让 AI 修，但**不要让它批量自动改**。建议：人工挑 review 通过的，逐个让 AI 改。code-fix Skill（PLANNED）将提供受控自动修复。
+
+**Q：两份报告为什么要分开？**
+A：AI 报告冗长（含每行修复建议），人读摘要简洁（只看趋势/优先级）。两者读者不同。
+
+**Q：自定义规范怎么加？**
+A：往 `.github/standards/` 加一份 `*.md`，更新 `standards/index.md`，convention-audit 自动 pickup。

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

@@ -5,7 +5,53 @@ description: "Use when: generating complete Vue 3 page code (index.vue + data.ts
 
 # Skill: 页面代码生成（page-codegen）
 
-基于《页面清单》+ 原型信息，生成符合 cx-ui-produce 规范的完整 Vue 3 页面代码。
+基于《页面清单》+ 原型信息，生成符合项目规范的完整 Vue 3 页面代码。
+
+---
+
+## Pre-flight 规范声明（执行前必须输出）
+
+```
+🚀 已触发技能 page-codegen/SKILL.md          → 页面代码生成：4文件 + 模板调度 + 前置检查
+✅ 已读取 templates/_index.md                → 模板注册表，匹配 → {TPL路径}
+✅ 已读取 templates/{universal|domains/xxx}/TPL-XXX.md → {当前模板说明}
+✅ 已读取 standards/index.md                 → 规范门控（任务类型 A：生成新页面）
+✅ 已读取 standards/02-code-structure.md     → 4文件原则 + 三段式 + script 9段顺序
+✅ 已读取 standards/12-base-table.md         → AGGrid必用 + cid命名规范
+✅ 已读取 standards/13-platform-components.md → 平台组件对照表 + docs前置读取清单
+✅ 已读取 docs/{涉及的jh-*文档}              → 当前页涉及组件的使用规范
+✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓  [全部就绪]
+✅ cid 已生成：{value}（{首字母缩写说明}）
+```
+
+**工具链失败时（红叉 + 暂停）**：
+
+```
+❌ 工具链检测失败：未找到 .prettierrc.js / eslint.config.ts / .husky/
+   → 请执行：npx @robot-admin/git-standards init
+   → 或联系 CHENY（工号 409322）解决
+   → ⛔ 代码生成已暂停，修复后重新触发
+```
+
+**生成完成摘要（生成结束后输出）**：
+
+```
+📦 本次生成完成
+────────────────────────────────────────────────
+✅ src/views/.../{页面}/index.vue
+✅ src/views/.../{页面}/data.ts
+✅ src/views/.../{页面}/index.scss
+✅ src/views/.../{页面}/api.md
+✅ reports/SYS_MENU_INFO.md  → 已追加菜单条目
+────────────────────────────────────────────────
+📌 后续步骤：
+   1. 在 router/pages.ts 注册路由
+   2. 提交：git cz（禁止直接 git commit）
+   3. 可选：触发 convention-audit 扫描本次生成文件
+────────────────────────────────────────────────
+```
+
+---
 
 ## 前置检查
 
@@ -44,7 +90,7 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 附加输出：
 
 - `pages.ts` 注册片段
-- **`SYS_MENU_INFO.md`** — 集中式菜单配置（见下方 §SYS_MENU_INFO 生成规则）
+- **`reports/SYS_MENU_INFO.md`** — 集中式菜单配置，**追加写入**（见下方 §SYS_MENU_INFO 生成规则）
 - `mock/[页面kebab-name].ts`（项目根目录 `mock/` 下，`vite-plugin-mock` 自动加载，与 api.md 的 URL 和字段完全一致）
 
 ---
@@ -818,18 +864,14 @@ import { BaseQueryItemDesc } from "@jhlc/common-core/src/components/form/base-qu
 
 ## SYS_MENU_INFO 生成规则（所有模板通用）
 
-page-codegen 生成页面代码后，**必须同步生成菜单配置信息到 `.github/docs/SYS_MENU_INFO.md`**。
-
-### 写入模式确认（必须询问用户）
+page-codegen 生成页面代码后，**必须追加写入菜单配置信息到 `reports/SYS_MENU_INFO.md`**。
 
-**在写入 SYS_MENU_INFO.md 之前，必须询问用户选择写入模式**：
+### 写入策略（默认追加，不覆盖）
 
-| 模式 | 说明 | 适用场景 |
-|------|------|---------|
-| **覆盖模式** | 清空已有内容，只写入本次生成的菜单 | 首个模块 / 上次生成失败需要重来 |
-| **追加模式** | 保留已有内容，在末尾追加本次生成的菜单 | 第二个、第三个模块接续生成 |
+- **默认为追加模式**：保留已有内容，在末尾追加本次生成的菜单。避免覆盖团队之前累积的菜单记录。
+- **如需重置**：用户明确说“覆盖”才走覆盖逻辑。
 
-> AI 提问示例：`本次生成了 N 个页面的菜单配置，是【覆盖】还是【追加】写入 SYS_MENU_INFO.md？`
+> AI 询问示例（仅当用户意图不明时）：`本次生成了 N 个页面的菜单配置，默认追加到 reports/SYS_MENU_INFO.md，是否需要覆盖已有内容？`
 
 ### 生成模板
 
@@ -917,14 +959,15 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 
 | 交互模式 | 文件 | 适用场景 | 典型参考页面 |
 |---|---|---|---|
-| LIST | TPL-LIST.md | 标准查询+工具栏+表格+分页 | mmwr-customer-archive |
-| MASTER_DETAIL | TPL-MASTER-DETAIL.md | jh-drag-row 主从表，双击联动 | ompt-ht-plan-order |
-| TREE_LIST | TPL-TREE-LIST.md | 左侧 C_Tree + 右侧列表 | — |
-| DETAIL_TABS | TPL-DETAIL-TABS.md | C_Splitter 上Tab表单+下子表 | add-demo / domestic-trade-order |
-| FORM_ROUTE | TPL-FORM-ROUTE.md | 复杂表单独立路由（非弹窗） | mmwr-customer-apply-add-form |
-| CHANGE_HISTORY | TPL-CHANGE-HISTORY.md | 左历史时间线+右变更详情 | mmwr-customer-apply-change-history |
-| RECORD_FORM | TPL-RECORD-FORM.md | BaseQuery选主记录+Form+Table无分页 | mmsm-convert-progress |
-| OPERATION_STATION | TPL-OPERATION-STATION.md | 工序站点操作（待处理↔已处理+操作表单） | mmwr-rolling-management |
-
-> **配置驱动模板页**（ResultQueryTemplate / FinishingAchievementTemplate 等）：见 TPL-DRIVEN.md，仅需生成 config 对象，不套用以上模板。
+| LIST | templates/universal/TPL-LIST.md | 标准查询+工具栏+表格+分页 | mmwr-customer-archive |
+| MASTER_DETAIL | templates/universal/TPL-MASTER-DETAIL.md | jh-drag-row 主从表，双击联动 | ompt-ht-plan-order |
+| TREE_LIST | templates/universal/TPL-TREE-LIST.md | 左侧 C_Tree + 右侧列表 | — |
+| DETAIL_TABS | templates/universal/TPL-DETAIL-TABS.md | C_Splitter 上Tab表单+下子表 | add-demo / domestic-trade-order |
+| FORM_ROUTE | templates/universal/TPL-FORM-ROUTE.md | 复杂表单独立路由（非弹窗） | mmwr-customer-apply-add-form |
+| CHANGE_HISTORY | templates/universal/TPL-CHANGE-HISTORY.md | 左历史时间线+右变更详情 | mmwr-customer-apply-change-history |
+| RECORD_FORM | templates/universal/TPL-RECORD-FORM.md | BaseQuery选主记录+Form+Table无分页 | mmsm-convert-progress |
+| OPERATION_STATION | templates/domains/produce/TPL-OPERATION-STATION.md | 工序站点操作（待处理↔已处理+操作表单） | mmwr-rolling-management |
+
+> **配置驱动模板页**（ResultQueryTemplate / FinishingAchievementTemplate 等）：见 templates/universal/TPL-DRIVEN.md，仅需生成 config 对象，不套用以上模板。
+> **领域模板查询**：完整路径以 `templates/_index.md` 注册表为准，新增领域模板见 `templates/domains/_CONTRIBUTING.md`。
 

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

@@ -0,0 +1,102 @@
+# 使用指南：page-codegen（页面代码生成）
+
+> **谁读这个文档**：团队成员（主要前端）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+基于《页面清单》+ `api.md`，**自动生成符合项目规范的 Vue 页面**（4 文件骨架：data.ts / index.vue / index.scss / api.md），并跑一遍内部规范自检（Pre-flight + 完成摘要）。
+
+生成出来的代码**满足 13 条 standards**，无需手工改语法/命名。
+
+---
+
+## 何时使用
+
+- 已完成 prototype-scan + api-contract，需要批量生成页面代码
+- 复用相同模板做新页面（基于 templates/domains/）
+- 教新人时希望"按一键就能看到合规示例"
+
+---
+
+## 触发关键词
+
+`生成页面` / `创建页面` / `代码生成` / `vue 页面` / `按原型生成` / `帮我生成`
+
+---
+
+## 标准对话示例
+
+```
+你：基于 reports/PROTOTYPE_SCAN_客户管理_20260426.md 和各页面的 api.md，生成全部 7 个页面代码
+AI：[Pre-flight]
+    将创建 7 个目录到 src/views/produce/aiflow/
+    每个目录包含：data.ts / index.vue / index.scss / api.md（已存在则跳过）
+    模板基线：templates/domains/produce/customer/
+    13 条 standards 自检通过项预估：
+    ✓ AbstractPageQueryHook 正确继承
+    ✓ EColumn 元数据完备
+    ✓ pageRef 命名规范
+    ✓ scoped scss
+    ⚠ 待确认：customerStatus 字典 logicValue 名
+    [生成中... 8 分钟]
+    完成摘要：
+    - 新建 7 个页面共 28 个文件
+    - 5 处需要人工 review（详见报告）
+    - 输出报告：reports/PAGE_CODEGEN_客户管理_20260426.md
+```
+
+---
+
+## 输出物
+
+每个页面目录：
+
+```
+src/views/<域>/<模块>/<子模块>/<page-name>/
+├── data.ts        EColumn 定义、API_CONFIG、Hook 类
+├── index.vue      template + script + import data.ts
+├── index.scss     页面专属样式（已 :deep / scoped 包好）
+└── api.md         （由 api-contract 生成，codegen 不覆盖）
+```
+
+外加生成报告：`.github/reports/PAGE_CODEGEN_<模块>_<YYYYMMDD>.md`
+
+---
+
+## 模板复用机制
+
+`page-codegen` 读取 `templates/` 下两个层级：
+
+- **`templates/universal/`**：跨业务通用骨架（LIST / MASTER_DETAIL / TREE_LIST）
+- **`templates/domains/<域>/<场景>/`**：领域专属（如 produce/customer/、sale/order/）
+
+**优先级**：domain 命中则用 domain，未命中回落 universal。
+
+> 想沉淀新模板？用 `template-extract` Skill 从已有页面抽取。
+
+---
+
+## 常见踩坑
+
+| 现象                                | 原因                                   | 解法                                                |
+| ----------------------------------- | -------------------------------------- | --------------------------------------------------- |
+| 生成出来的页面 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位}`，理论极低概率 |
+
+---
+
+## FAQ
+
+**Q：生成完了但 build 报错？**
+A：跑一下 `convention-audit` Skill，会扫出 13 条规范偏差并给出修复建议。
+
+**Q：能否只生成 data.ts 不生成 index.vue？**
+A：可以，告诉 AI"只生成 data.ts"。但通常一起生成，因为它们字段必须对齐。
+
+**Q：能否覆盖已有页面？**
+A：默认不覆盖。需要明确说"覆盖现有 src/views/xxx/" + AI 会让你二次确认。

package/files/.github/skills/core/page-codegen/templates/_index.md

@@ -0,0 +1,46 @@
+# 模板注册表（page-codegen 模板单一数据源）
+
+> AI 在生成页面前，**先读取本文件**，定位匹配的 TPL 路径，再读取该 TPL。
+
+---
+
+## 通用模板（与业务域无关）
+
+| 交互模式        | TPL 路径                                    | 适用场景                                |
+| --------------- | ------------------------------------------- | --------------------------------------- |
+| LIST            | `templates/universal/TPL-LIST.md`           | 标准列表页（查询+工具栏+表格+分页）     |
+| FORM_ROUTE      | `templates/universal/TPL-FORM-ROUTE.md`     | 复杂表单独立路由页（多 Tab / 多子表）   |
+| MASTER_DETAIL   | `templates/universal/TPL-MASTER-DETAIL.md`  | 主从表页（jh-drag-row 上下分栏）        |
+| TREE_LIST       | `templates/universal/TPL-TREE-LIST.md`      | 左树右列表页（C_Splitter 布局）         |
+| DETAIL_TABS     | `templates/universal/TPL-DETAIL-TABS.md`    | 详情 Tab 页（上方表单 + 下方 Tab 子表） |
+| CHANGE_HISTORY  | `templates/universal/TPL-CHANGE-HISTORY.md` | 变更历史比对页（时间线 + 字段差异）     |
+| RECORD_FORM     | `templates/universal/TPL-RECORD-FORM.md`    | 录入型实绩页（无分页，查询 + 内联表单） |
+| TEMPLATE_DRIVEN | `templates/universal/TPL-DRIVEN.md`         | 配置驱动识别参考（非代码生成模板）      |
+
+---
+
+## 领域专属模板
+
+### produce（生产域）
+
+| 模板              | TPL 路径                                             | 适用场景                            |
+| ----------------- | ---------------------------------------------------- | ----------------------------------- |
+| OPERATION_STATION | `templates/domains/produce/TPL-OPERATION-STATION.md` | 工序操作站（双清单联动 + 内联表单） |
+
+### sale（销售域）
+
+> 暂无领域专属模板。可通过 `template-extract` Skill 从现有页面提取并贡献。
+
+---
+
+## 选择规则
+
+1. AI 优先匹配通用模板（universal/）
+2. 若用户明确指定领域且通用模板不适用，匹配 `domains/{domain}/`
+3. 若都不匹配，反问用户描述更详细的交互模式，或建议使用 template-extract 先提取标杆页面
+
+---
+
+## 贡献新模板
+
+使用 `template-extract` Skill 从现有项目页面自动提取，详见 `templates/domains/_CONTRIBUTING.md`。

package/files/.github/skills/core/page-codegen/templates/domains/_CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# 领域模板贡献规范
+
+> 如何向 `domains/` 贡献领域专属模板。
+
+---
+
+## 何时贡献领域模板
+
+✅ **建议提取**的场景：
+
+- 同一业务域内 **3+ 个页面**遵循相同的非标准交互模式
+- 该模式无法通过通用模板（`universal/`）覆盖
+- 标杆页面已稳定运行，业务字段已成熟
+
+❌ **不建议提取**的场景：
+
+- 该模式未来 6 个月可能频繁变化
+- 仅 1~2 个页面使用
+- 通用模板稍加配置即可满足
+
+---
+
+## 推荐方式：使用 template-extract Skill
+
+最低门槛，**全 AI 辅助**：
+
+```
+开发者：触发模板提取，目标页：src/views/produce/.../mmwr-rolling-management/
+
+AI: 1. 读取目标页 4 文件（index.vue + data.ts + index.scss + api.md）
+    2. 自动识别交互模式，对比已有 TPL，输出识别结论
+    3. 反问 3 个问题：领域归属 / 模板命名 / 脱敏需求
+    4. 生成标准 TPL 文件
+    5. 写入 domains/{domain}/
+    6. 自动更新 templates/_index.md
+    7. 输出后续提交步骤
+```
+
+详见 `skills/core/template-extract/SKILL.md`。
+
+---
+
+## TPL 文件格式规范
+
+每个领域模板必须包含以下章节：
+
+```markdown
+# {TPL_NAME}：{中文名}
+
+> **适用场景**：（一句话场景描述）
+> **识别特征**：（原型/详设中如何识别本模式）
+> **布局核心**：（关键组件 / 布局方式）
+> **⚠️ 重要约束**：（与通用模板的核心区别）
+> **参考标杆**：`src/views/.../{kebab-page-name}/`
+
+---
+
+## 识别规则
+
+（5 条以内的明确判定条件）
+
+---
+
+## 代码模板
+
+### index.vue
+
+（完整可运行代码，使用占位符 `[资源名]` `[服务缩写]`）
+
+### data.ts
+
+（同上）
+
+### index.scss
+
+---
+
+## 注意事项
+
+（陷阱 / 易错点 / 性能提示）
+```
+
+---
+
+## 命名规范
+
+- TPL 文件名：`TPL-{ALL-CAPS-KEBAB}.md`
+  示例：`TPL-OPERATION-STATION.md`、`TPL-BATCH-INSPECT.md`
+- 模板标识符：与文件名一致，全大写下划线
+  示例：`OPERATION_STATION`、`BATCH_INSPECT`
+
+---
+
+## 提交流程
+
+1. 通过 `template-extract` Skill 生成 TPL 文件
+2. 人工 review 生成的内容（脱敏 / 占位符 / 注意事项）
+3. 提交 PR：`feat(template): 新增领域模板 TPL-XXX`
+4. CHENY 评审合入
+
+---
+
+## 模板维护
+
+- 标杆页面变更 → 同步更新 TPL（保持模板与实际代码一致）
+- 模板使用频率低于预期 → 评估是否归档或合并到通用模板
+- 通过 `convention-audit` 定期对比各 TPL 标杆页面与最新规范的一致性