@agile-team/wl-skills-kit 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.1.5] - 2026-04-09
+
+### 修复：page-codegen → menu-sync 数据闭环
+
+- **问题**：page-codegen 生成分散的 `menu-config.md`（各页面目录下），menu-sync 却读取集中式 `SYS_MENU_INFO.md`，两者断裂
+- **修复**：page-codegen 统一输出到 `.github/docs/SYS_MENU_INFO.md`（追加/覆盖模式，生成前必须询问用户）
+- TPL-DETAIL-TABS 原有的 menu-config.md 模板移除，改为引用 SKILL.md 主文件的统一规则
+- 新增「api.md 生成时序」章节：明确 api.md 先于 page-codegen（Step 2 → Step 3），确保 API_CONFIG 与接口一致
+- copilot-instructions.md 流水线描述更新：Step 3 注明"追加/覆盖 SYS_MENU_INFO.md"，新增数据闭环说明
+- use-skill.md 工作流 A 更新：Step 6 增加写入模式确认，Step 8 增加手动/自动两种菜单创建方式说明
+
+## [1.1.4] - 2026-04-09
+
+### 修复
+
+- 补充遗漏的 `env.local.json` 模板文件到 `files/.github/skills/menu-sync/env/`
+- 文件内容为占位符模板（非真实凭据），安装后用户按 `guide.md` 填写实际值
+
 ## [1.1.3] - 2026-04-09
 
 ### 重构：convention-extract → convention-audit（规范审计）

package/README.md

@@ -50,7 +50,7 @@ npx @agile-team/wl-skills-kit@latest
 │   └── docs/                            ← 设计文档
 │       ├── use-skill.md                 ←   Skill 使用 + 移植一站式指南
 │       ├── menu-sync-design.md          ←   菜单同步方案设计
-│       ├── SYS_MENU_INFO.md             ←   菜单注册记录模板
+│       ├── SYS_MENU_INFO.md             ←   菜单配置（page-codegen 自动生成，menu-sync 读取）
 │       └── wl-skills-kit.md             ←   本包详细设计文档
 │
 ├── docs/                                ← 12 个平台组件 API 文档
@@ -121,13 +121,15 @@ npx @agile-team/wl-skills-kit@latest
   ① prototype-scan ─── 扫描 → page-spec JSON（结构化页面描述）
          │
          ▼
-  ② api-contract ───── 生成 → api.md（前后端接口约定）
+  ② api-contract ───── 生成 → api.md（前后端接口约定，先于代码生成）
          │
          ▼
   ③ page-codegen ───── 生成 → index.vue + data.ts + index.scss + api.md + mock
          │                     （4 文件/页 + pages.ts 注册 + mock 数据）
+         │              写入 → SYS_MENU_INFO.md（询问用户选择覆盖/追加模式）
          ▼
-  ④ menu-sync ──────── 同步 → 后端菜单表（AI 自动调 API 创建菜单）
+  ④ menu-sync ──────── 读取 SYS_MENU_INFO.md → 同步到后端菜单表
+                       （自动调 API 或手动在后台创建，效果等价）
                        
   ⑤ convention-audit    按需：用规范审计代码 → 偏差报告 + 整改建议
 ```

package/files/.github/copilot-instructions.md

@@ -219,14 +219,17 @@ onMounted(() => select());
 
 ```
 Step 1 → 读取 prototype-scan/SKILL.md → 执行原型扫描 → 输出 page-spec
-Step 2 → 读取 api-contract/SKILL.md   → 生成 api.md 接口约定
-Step 3 → 读取 page-codegen/SKILL.md   → 逐页生成代码（每页读取对应 TPL-*.md）
-Step 4 → 读取 menu-sync/SKILL.md      → 注册菜单到后端
+Step 2 → 读取 api-contract/SKILL.md   → 生成 api.md 接口约定（先于代码生成，确保 API_CONFIG 与接口一致）
+Step 3 → 读取 page-codegen/SKILL.md   → 逐页生成代码 + 追加/覆盖 SYS_MENU_INFO.md（询问用户选择写入模式）
+Step 4 → 读取 menu-sync/SKILL.md      → 读取 SYS_MENU_INFO.md → 注册菜单到后端
 ```
 
 每个 Step 开始前读取对应 SKILL.md，**前一个 Step 完成后再进入下一个**。
 上一步的输出（如 page-spec）直接作为下一步的输入，无需用户中间干预。
 
+> **数据闭环**：page-codegen 生成的 `SYS_MENU_INFO.md` 是 menu-sync 的唯一输入。
+> 菜单通过 `组件路径` 字段与 pages.ts 注册的文件路径关联，无论自动（menu-sync API）还是手动（系统管理后台）创建菜单，效果等价。
+
 ### 单独使用
 
 用户也可以只执行单个 Skill（如只说"帮我生成客户档案页面"），此时只需读取对应的 SKILL.md，不必执行完整流水线。

package/files/.github/docs/use-skill.md

@@ -44,6 +44,7 @@ Step 2  AI 执行 prototype-scan → 输出 page-spec JSON
 Step 3  确认 page-spec（检查字段数量，注意 notes 中的歧义项）
 
 Step 4  AI 执行 api-contract → 输出每个页面的 api.md
+        （api.md 先于代码生成，确保 API_CONFIG 与接口一致）
 
 Step 5  确认接口（服务缩写、资源名是否正确）
 
@@ -51,15 +52,16 @@ Step 6  AI 执行 page-codegen → 输出：
         - index.vue + data.ts + index.scss + api.md（每页 4 文件）
         - pages.ts 注册片段（已写入）
         - mock/[页面名].ts（与 api.md URL/字段一致，vite-plugin-mock 自动加载）
-        - SYS_MENU_INFO.md 追加/更新（.github/docs/ 下）
+        - AI 询问用户：SYS_MENU_INFO.md 选择【覆盖】还是【追加】模式
+        - 写入 SYS_MENU_INFO.md（.github/docs/ 下）
 
 Step 7  AI 输出校验报告（✅/❌ 各轮 diff 结果）
 
-Step 8  菜单推送（menu-sync Skill）
-        对 AI 说「帮我创建菜单」
-        → AI 读取 SYS_MENU_INFO.md + env.local.json → 调 /system/menu/save 逐条创建
-        → 输出 created/skipped 结果表
-        （Phase 2 就绪后改用 pnpm run menu:push 脚本，详见 menu-sync/SKILL.md）
+Step 8  菜单注册（二选一，效果等价）
+        方式 A - 自动：对 AI 说「帮我创建菜单」
+          → AI 读取 SYS_MENU_INFO.md + env.local.json → 调 API 逐条创建
+        方式 B - 手动：按 SYS_MENU_INFO.md 表格在系统管理后台手动创建菜单
+        两种方式的菜单通过「组件路径」与 pages.ts 注册的文件路径关联
 
 Step 9  启动开发验证
         pnpm run dev → 打开页面，mock 数据自动生效，可立即调试

package/files/.github/skills/menu-sync/env/env.local.json

@@ -0,0 +1,5 @@
+{
+  "gatewayPath": "http://你的网关地址:端口",
+  "parentMenuId": "父级菜单ID",
+  "token": "你的Bearer Token（不含bearer前缀）"
+}

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

@@ -42,7 +42,7 @@ src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
 附加输出：
 
 - `pages.ts` 注册片段
-- `menu-config.md`（页面目录下，包含系统后台创建菜单所需的 12 个字段值，供手动复制或 `pnpm run menu:push` 推送）
+- **`SYS_MENU_INFO.md`** — 集中式菜单配置（见下方 §SYS_MENU_INFO 生成规则）
 - `mock/[页面kebab-name].ts`（项目根目录 `mock/` 下，`vite-plugin-mock` 自动加载，与 api.md 的 URL 和字段完全一致）
 
 ---
@@ -806,6 +806,109 @@ import { BaseQueryItemDesc } from "@jhlc/common-core/src/components/form/base-qu
 
 ---
 
+## api.md 生成时序
+
+> **api.md 在页面代码之前生成**（Step 2: api-contract → Step 3: page-codegen）。
+> page-codegen 读取已生成的 api.md 中的 URL 和字段定义，确保 `API_CONFIG`、mock、data.ts 与接口约定一致。
+> 未来使用真实 API 设计文档时，api.md 由后端提供或 api-contract Skill 从设计文档提取，page-codegen 直接消费。
+
+---
+
+## SYS_MENU_INFO 生成规则（所有模板通用）
+
+page-codegen 生成页面代码后，**必须同步生成菜单配置信息到 `.github/docs/SYS_MENU_INFO.md`**。
+
+### 写入模式确认（必须询问用户）
+
+**在写入 SYS_MENU_INFO.md 之前，必须询问用户选择写入模式**：
+
+| 模式 | 说明 | 适用场景 |
+|------|------|---------|
+| **覆盖模式** | 清空已有内容，只写入本次生成的菜单 | 首个模块 / 上次生成失败需要重来 |
+| **追加模式** | 保留已有内容，在末尾追加本次生成的菜单 | 第二个、第三个模块接续生成 |
+
+> AI 提问示例：`本次生成了 N 个页面的菜单配置，是【覆盖】还是【追加】写入 SYS_MENU_INFO.md？`
+
+### 生成模板
+
+每个页面生成一个菜单条目，格式如下：
+
+```markdown
+## [序号]. [菜单名称]
+
+| 字段         | 填写值 |
+| ------------ | ------ |
+| 类型 Tab     | 选择 **菜单** |
+| 上级目录     | `[父目录名]` |
+| 应用选择     | `[应用名]` |
+| 使用缓存     | ◉ 使用 |
+| 显示排序     | `[序号]` |
+| 菜单路径     | `[camelCase目录名]` |
+| 菜单名称     | `[中文名]` |
+| 名称编码后缀 | `[菜单路径拼音小写]` |
+| 组件路径     | `[域]/[模块]/[子模块]/[kebab-目录名]/index.vue` |
+| 权限标识     | `[camelCase目录名]` |
+| 是否隐藏     | **否** / **是** |
+```
+
+### 字段生成规则
+
+| 字段 | 来源 | 规则 |
+|------|------|------|
+| 菜单路径 | page-spec.kebabName | kebab-case → camelCase（`mmwr-customer-archive` → `mmwrCustomerArchive`） |
+| 菜单名称 | page-spec.pageName | 直接使用中文名 |
+| 组件路径 | pages.ts 注册路径 | `[域]/[模块]/[子模块]/[kebab-目录名]/index.vue` |
+| 权限标识 | 同菜单路径 | camelCase |
+| 是否隐藏 | page-spec.features.hiddenMenu | `true` → 是，`false` → 否 |
+| 上级目录 | 用户指定 / page-spec 推断 | 如果用户在原型扫描阶段指定了上级目录，使用该值 |
+| 应用选择 | pages.ts 域名 | `produce` → 生产，`sale` → 销售 |
+| 显示排序 | 页面在模块内的序号 | 从 1 开始递增 |
+
+### 隐藏页面判断规则
+
+以下页面类型应设置 `是否隐藏: 是`：
+- 目录名含 `-form`（独立路由表单页）
+- 目录名含 `-detail`（详情页）
+- 目录名含 `-history`（历史查询页）
+- page-spec.features.hiddenMenu === true
+
+### SYS_MENU_INFO.md 文件结构
+
+```markdown
+# 系统菜单配置 — [模块名称]（[域] / [子模块路径]）
+
+> 对应系统管理 → 菜单管理 → 新增菜单，每栏直接复制粘贴。
+> **操作顺序：先建目录（第 0 步），再逐个添加菜单。**
+>
+> **pages.ts 注册位置**：`vite/plugins/shared/pages.ts` → `[模块变量名]` → `[子模块key]`
+
+## 第 0 步：新建目录（如需要）
+
+| 字段     | 值 |
+| -------- | -- |
+| 上级目录 | `[上级目录名]` |
+| 菜单名称 | `[目录名]` |
+| 显示排序 | `[序号]` |
+
+## 第 1 步：[页面名称]
+
+[菜单条目表格]
+
+> pages.ts 对应：`["[kebab-name]", "[中文名]"]`
+
+## 第 2 步：[页面名称]
+...
+```
+
+### 与 menu-sync 的衔接
+
+SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
+- **自动创建**：用户说"帮我创建菜单" → menu-sync 读取 SYS_MENU_INFO.md → 调 API 逐条创建
+- **手动创建**：用户也可直接按 SYS_MENU_INFO.md 的表格在系统管理后台手动创建菜单
+- 两种方式等价，菜单创建后通过 `组件路径` 字段与 pages.ts 注册的文件路径关联
+
+---
+
 ## 代码模板索引
 
 > 各模板完整代码见对应独立文件，按需读取。主文件（SKILL.md）包含前置检查、约束、按钮规则、Mock规范等所有共用规则。

package/files/.github/skills/page-codegen/TPL-DETAIL-TABS.md

@@ -1,7 +1,7 @@
-# DETAIL_TABS：详情Tab+子表页
-
-> 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
-
+# DETAIL_TABS：详情Tab+子表页
+
+> 见 SKILL.md 主文件（约束 + 按钮规则 + Mock 规范等共用规则）。
+
 
 > 适用场景：编辑/维护页面，上半区为多 Tab 表单（基本信息/客户信息/其他信息），下半区为子项表格。
 > 布局核心：`C_Splitter direction="vertical"` 垂直分割上下区域。
@@ -973,31 +973,9 @@ spec.features.hiddenMenu === true：
 ["[kebab-case-目录名]", "[页面中文名]"],
 ```
 
-### 菜单配置速查（menu-config.md）
-
-在模块目录下生成 `menu-config.md`，每个菜单一个表格，字段对应系统管理后台的创建菜单表单：
-
-```markdown
-## [序号]. [菜单名称]
-
-| 字段     | 填写值 |
-| -------- | ------ |
-| 类型 Tab | 选择 **菜单** |
-| 上级目录 | `[父目录名]` |
-| 菜单图标 | 按需选择 |
-| 应用选择 | `[应用名]` |
-| 使用缓存 | ◉ 使用 |
-| 页面     | 请选择 |
-| 显示排序 | `[序号]` |
-| 菜单路径 | `[camelCase目录名]` |
-| 菜单名称 | `[中文名]` |
-| 名称编码 | 前缀 `menu:[模块拼音]:` → 后缀填 `[菜单路径拼音]` |
-| 组件路径 | `[域]/[模块]/[子模块]/[kebab-目录名]/index.vue` |
-| 权限标识 | `[camelCase目录名]` |
-| 是否隐藏 | **否** 或 **是**（page-spec.features.hiddenMenu） |
-```
+### 菜单配置
 
-> 隐藏菜单：从列表页跳转进入的子页面（详情页、编辑页等）标记为 `是否隐藏: 是`
+> 菜单配置统一生成到 `.github/docs/SYS_MENU_INFO.md`（集中式），生成规则见 SKILL.md 主文件的「SYS_MENU_INFO 生成规则」章节。
 
 ---
 
@@ -1109,4 +1087,4 @@ export default mockApi;
 >
 > 参考实现：`mock/customer-archive.ts`、`mock/temp-customer-archive.ts`、`mock/customer-apply.ts`
 
----
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
   "bin": {
     "wl-skills-kit": "./bin/wl-skills.js"