@agile-team/wl-skills-kit 2.3.5 → 2.3.7

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [2.3.7] - 2026-04-29
+
+### 🔐 permission-sync 闭环完善（数据驱动权限）
+
+- **修正权限落地方式**：`action-attach` 模式改为在 `data.ts` 的 `ActionButtonDesc` 上加 `permission: []` 字段，而非错误的 `v-permission` 指令（`BaseToolbar` 内部已做权限拦截）
+- **简化角色授权备份说明**：平台侧已防重复分配；AI 内部做"查旧 menuIds + 合并"，不再建议额外备份
+- **联动说明更新**：`page-codegen` 预留 `permission: []` 占位；`convention-audit` 改为审计 `data.ts` 按钮是否有非空 `permission` 字段
+- `USAGE.md` 补充"为什么不用 v-permission 指令"说明 + Q2 权限码写法示例
+
+## [2.3.6] - 2026-04-29
+
+### 🔐 permission-sync Skill 正式激活
+
+新增完整的"角色 → 菜单授权 → 动作按钮 → v-permission"闭环能力。
+
+#### 新增 6 个 MCP 工具
+- `wls_role_query` — 查询角色列表（支持分页）
+- `wls_role_upsert` — 批量新增角色（按 `code` 字段去重）
+- `wls_assignable_menus_query` — 查询全量可授权菜单
+- `wls_role_assign_menus` — 给角色批量分配菜单（**全量覆盖式**，使用前需确认）
+- `wls_action_query` — 查询页面菜单下的动作（type=A）
+- `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 更新
+- `docs/ai全景分析.md` MCP Tools 表新增 6 个工具，路线图描述更新
+- `README.md` skill 目录与概览表更新
+
 ## [2.3.5] - 2026-04-29
 
 ### 📄 文档与内容修正

package/README.md

@@ -102,7 +102,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   │   ├── 02-code-structure.md
 │   │   ├── ... (共 13 条)
 │   │   └── 13-platform-components.md
-│   ├── skills/                           8 个启用 Skill + 1 个 PLANNED 草稿
+│   ├── skills/                           9 个启用 Skill（全部激活）
 │   │   ├── _registry.md                  ★ 触发词 → SKILL 路径单一数据源
 │   │   ├── _compat/                      多 AI 编辑器适配（配置 + headers）
 │   │   ├── core/                         核心通用 Skill
@@ -114,7 +114,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   │   ├── sync/                         数据同步类
 │   │   │   ├── menu-sync/        { SKILL.md, USAGE.md, env/ }
 │   │   │   ├── dict-sync/        { SKILL.md }  已启用
-│   │   │   └── permission-sync/  [PLANNED] SKILL.draft.md  设计中
+│   │   │   └── permission-sync/  { SKILL.md, USAGE.md }  已启用（角色+授权+动作+v-permission）
 │   │   ├── ops/                          运维类
 │   │   │   └── code-fix/         { SKILL.md }  已启用
 │   │   └── domain/                       领域专属（按需创建）
@@ -201,7 +201,7 @@ npx @agile-team/wl-skills-kit update
 | `template-extract` | ✅ 启用    | `skills/core/template-extract/`          | 现有页面 → 领域模板           |
 | `menu-sync`        | ✅ 启用    | `skills/sync/menu-sync/`                 | 菜单基线 ↔ 后端接口          |
 | `dict-sync`        | ✅ 启用    | `skills/sync/dict-sync/`                 | 字典基线 ↔ 后端接口          |
-| `permission-sync`  | ⏳ PLANNED | `skills/sync/permission-sync/`           | 权限基线 ↔ 后端接口          |
+| `permission-sync`  | ✅ 启用    | `skills/sync/permission-sync/`           | 角色管理 + 角色授权 + 挂动作 + v-permission |
 | `code-fix`         | ✅ 启用    | `skills/ops/code-fix/`                   | 受控自动修复偏差              |
 
 每个启用 Skill 同目录都有 **`SKILL.md`（AI 触发用）+ `USAGE.md`（团队成员阅读）**。

package/files/.github/reports/README.md

@@ -13,8 +13,8 @@
 | 文件                               | 写入方             | 读取方          | 说明                   |
 | ---------------------------------- | ------------------ | --------------- | ---------------------- |
 | `SYS_MENU_INFO.md`                 | page-codegen       | menu-sync       | 页面生成时追加菜单条目 |
-| `SYS_DICT_INFO.md` [PLANNED]       | dict-collect       | dict-sync       | 字典数据汇总           |
-| `SYS_PERMISSION_INFO.md` [PLANNED] | permission-collect | permission-sync | 权限数据汇总           |
+| `SYS_DICT_INFO.md`                 | dict-collect       | dict-sync       | 字典数据汇总           |
+| `SYS_PERMISSION_INFO.md` [PLANNED] | permission-collect | permission-sync | 权限数据汇总（可选基线，当前 permission-sync 不强依赖） |
 
 **写入规则**：每条数据带生成时间戳；新条目追加到末尾；不删除历史。
 

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

@@ -21,7 +21,7 @@ skills/
 ├── sync/                数据同步类（与后端联动）
 │   ├── menu-sync/
 │   ├── dict-sync/
-│   └── permission-sync/  [PLANNED]
+│   └── permission-sync/  ✅ v2.3.6 激活
 │
 ├── ops/                 运维/构建类
 │   └── code-fix/
@@ -47,7 +47,7 @@ skills/
 | 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  | ⏳ PLANNED | `skills/sync/permission-sync/SKILL.draft.md` | （草稿，不参与调度）                                                       |
+| permission-sync  | ✅ 启用    | `skills/sync/permission-sync/SKILL.md`       | 创建角色 / 角色管理 / 角色授权 / 给角色分配菜单 / 挂动作 / 添加动作按钮 / 同步权限 / 权限码注册 |
 | code-fix         | ✅ 启用    | `skills/ops/code-fix/SKILL.md`               | 自动修复 / 整改偏差 / 修复报告 / 规范整改 / 修复偏差 / code fix               |
 
 ---

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

@@ -14,10 +14,5 @@
   "dict": {
     "_comment": "dict-sync 专属配置",
     "moduleId": "字典所属模块ID（从字典管理后台获取，如 7C909G0U2F8HI7E305LV0135LSJ3UBIO）"
-  },
-
-  "permission": {
-    "_comment": "permission-sync 专属配置 — 待启用，字段待确认",
-    "parentPermissionId": ""
   }
 }

package/files/.github/skills/sync/permission-sync/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: permission-sync
+description: "Use when: managing roles, authorizing menus to roles, attaching action buttons (type=A) to page menus, or wiring permission field in data.ts toolbar config. Triggers on: 创建角色, 角色管理, 角色授权, 给角色分配菜单, 挂动作, 添加动作按钮, 同步权限, 权限码注册, role assign, permission sync."
+---
+
+# Skill: 权限同步（permission-sync）
+
+将系统的**角色 → 菜单授权 → 动作按钮 → `data.ts` 权限码字段**串成一条链路，覆盖从权限注册到代码落地的全流程。
+
+> **与 menu-sync / dict-sync 的关系**：完全对称，统一从 `.github/skills/sync/env.local.json` 读取配置。`menu-sync` 负责页面菜单（type=M/C），`permission-sync` 负责其上的角色与动作（type=A）。
+
+---
+
+## 配置（统一配置文件，复用 menu-sync 的配置）
+
+读取 `.github/skills/sync/env.local.json`：
+
+```json
+{
+  "gatewayPath": "http://你的网关地址:端口",
+  "sysAppNo": "应用编码",
+  "token": "Bearer Token（不含 bearer 前缀）"
+}
+```
+
+**permission-sync 不需要额外字段**——角色和动作的 `parentId` 由 AI 在执行流程中通过查询接口动态获取。
+
+---
+
+## 三种工作模式
+
+| 模式             | 触发关键词                         | 动作                                                                                            |
+| ---------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `role-manage`    | 创建角色 / 角色管理 / 列出角色     | 查询/新增角色（按 `code` 去重，幂等）                                                           |
+| `role-assign`    | 角色授权 / 给 XX 角色分配菜单      | 查询全量可授权菜单 → 选定 menuIds → 调用 `saveRoleMenus` 批量分配                               |
+| `action-attach`  | 挂动作 / 给页面加按钮 / 注册权限码 | 注册 type=A 动作到后端 + 在 `data.ts` 对应按钮的 `ActionButtonDesc` 加 `permission` 字段，形成完整闭环 |
+
+---
+
+## Pre-flight 声明（执行前必须输出）
+
+```
+🚀 已触发技能 permission-sync/SKILL.md → 权限同步
+✅ 已读取 skills/sync/env.local.json   → 网关地址、token、sysAppNo
+✅ 操作模式：{role-manage / role-assign / action-attach}
+✅ 目标：{角色名 / roleId / 页面菜单 menuId 与权限码列表}
+✅ 安全检查：{生产环境拒绝 / 角色分配二次确认 / 仅新增不删除}
+```
+
+---
+
+## MCP 工具调用规范
+
+permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch）：
+
+| 工具                          | 用途                                       |
+| ----------------------------- | ------------------------------------------ |
+| `wls_role_query`              | 查询角色列表（带分页）                     |
+| `wls_role_upsert`             | 批量新增角色（按 code 去重）               |
+| `wls_assignable_menus_query`  | 查询全量可授权菜单                         |
+| `wls_role_assign_menus`       | 给角色批量分配菜单（**全量覆盖**，注意！） |
+| `wls_action_query`            | 查询页面菜单下的动作（type=A）             |
+| `wls_action_upsert`           | 批量新增动作（按 permission 去重）         |
+
+> 编辑器不支持 MCP 时（如纯命令行使用），可参考 §6 调用接口直连方式手动跑通。
+
+---
+
+## 1. role-manage（角色管理）
+
+### 输入示例
+
+> "创建一个测试角色，code 是 test_qa，描述：QA 测试用"
+
+### 流程
+
+1. AI 调用 `wls_role_query` 检查 `code=test_qa` 是否已存在
+2. 若不存在，调用 `wls_role_upsert`：
+   ```json
+   {
+     "items": [
+       { "roleName": "测试角色（QA）", "code": "test_qa", "configDesc": "QA 测试用" }
+     ]
+   }
+   ```
+3. 输出表格：角色名 / code / 状态（✅ 创建成功 / ⏭ 已存在）
+
+---
+
+## 2. role-assign（角色授权）
+
+### 输入示例
+
+> "给『档案普通人员』角色挂上『客户档案』『客户申请』两个菜单"
+
+### 流程
+
+1. **查询角色 id**：`wls_role_query` → 找到 `roleName="档案普通人员"` 对应的 `id`
+2. **查询可授权菜单**：`wls_assignable_menus_query` → 获取全部菜单清单
+3. **匹配 menuIds**：在结果中找到「客户档案」「客户申请」对应的 menu id
+4. **⚠️ 二次确认**：在 Pre-flight 中列出"将给角色 X 分配菜单 [A, B]"，得到用户 yes 才执行
+5. **调用授权**：`wls_role_assign_menus`
+   ```json
+   {
+     "roleId": "VERUFQ77SS0BCCE6GJVU21IFEP1EKFBQ",
+     "menuIds": ["2049380552157999105", "2049388746804604929"]
+   }
+   ```
+
+### ⚠️ 全量覆盖式陷阱
+
+后端 `saveRoleMenus` 是**全量覆盖**：
+- 传 `[A, B]` 后，原先 `[A, B, C]` 中的 C 会被移除
+- AI 在执行前**必须先告知用户**："此操作会替换该角色全部菜单，原有未列出的将被移除"
+- 若用户只是想"追加 C"，AI 应自行合并：取出旧 menuIds + 新增的 → 一起传
+
+---
+
+## 3. action-attach（挂动作 + 加 v-permission）
+
+### 输入示例
+
+> "给『客户档案』页面挂上 新增/编辑/删除/导出 四个动作按钮"
+
+### 流程
+
+#### 3.1 服务端注册动作
+
+1. **查询页面菜单 id**：先用 `wls_menu_query` 或 `wls_assignable_menus_query` 找到「客户档案」页面菜单 id（type=C）
+2. **查询已有动作**：`wls_action_query({ menuId: <页面id> })` 看哪些已存在
+3. **批量新增**：`wls_action_upsert`
+   ```json
+   {
+     "parentId": "<页面菜单 id>",
+     "items": [
+       { "menuName": "新增", "permission": "customer_add",    "orderNum": 1 },
+       { "menuName": "编辑", "permission": "customer_edit",   "orderNum": 2 },
+       { "menuName": "删除", "permission": "customer_remove", "orderNum": 3 },
+       { "menuName": "导出", "permission": "customer_export", "orderNum": 4 }
+     ]
+   }
+   ```
+
+#### 3.2 在 `data.ts` 中给对应按钮加 `permission` 字段
+
+本项目使用 `@jhlc/common-core` 的 `ActionButtonDesc` 类型，`BaseToolbar` 内部根据 `permission` 字段做权限拦截——**这是数据驱动方式，无需修改模板，无需 `v-permission` 指令**。
+
+由于 page-codegen 保证 `data.ts` 结构一致，toolbar 按钮配置始终在 `data.ts` 内。注册动作后，AI 找到对应按钮对象，添加 `permission` 数组字段：
+
+```ts
+// data.ts — 工具栏按钮配置（ActionButtonDesc[]）
+{
+  name: 'add',
+  label: '新增',
+  type: 'primary',
+  permission: ['customer_add'],          // ← 新增此字段
+  onClick: () => modalRef.value?.open()
+},
+{
+  name: 'edit',
+  label: '编辑',
+  permission: ['customer_edit'],          // ← 新增此字段
+  onClick: (row: any) => modalRef.value?.edit(row.id)
+},
+{
+  name: 'remove',
+  label: '删除',
+  type: 'danger',
+  permission: ['customer_remove'],        // ← 新增此字段
+  onClick: (row: any) => handleRemove(row.id)
+},
+```
+
+`permission` 值与 §3.1 中注册到后端的动作 `permission` 字段**完全一致**，直接复制使用。`BaseToolbar` 内部读取当前用户权限列表（由登录态注入），自动控制按钮显示/隐藏——无需任何额外处理。
+
+---
+
+## 4. 权限码命名规范（项目内统一）
+
+```
+{资源camelCase}_{动作}      ← 当前项目主流（短，便于阅读）
+{模块}:{资源}:{动作}          ← 通用平台风格（语义完整）
+```
+
+| 动作         | 含义     | 示例（短）                  | 示例（长）                       |
+| ------------ | -------- | --------------------------- | -------------------------------- |
+| `add`        | 新增     | `customer_add`              | `mmwr:customer:add`              |
+| `edit`       | 编辑     | `customer_edit`             | `mmwr:customer:edit`             |
+| `remove`     | 删除     | `customer_remove`           | `mmwr:customer:remove`           |
+| `export`     | 导出     | `customer_export`           | `mmwr:customer:export`           |
+| `import`     | 导入     | `customer_import`           | `mmwr:customer:import`           |
+| `submit`     | 提交审批 | `customer_submit`           | `mmwr:customer:submit`           |
+| `approve`    | 审批通过 | `customer_approve`          | `mmwr:customer:approve`          |
+| `reject`     | 审批驳回 | `customer_reject`           | `mmwr:customer:reject`           |
+| `{custom}`   | 自定义   | `customer_convertToFormal`  | `mmwr:customer:convertToFormal`  |
+
+> AI 在生成时**先扫描项目内已有 v-permission 用法**，沿用现有风格；项目无既定风格时优先短形式（`xxx_add`），与示例数据保持一致。
+
+---
+
+## 5. 安全约束（强制）
+
+- ✅ **生产环境拒绝直接 push**：`gatewayPath` 含 `prod` / `.com` 时切换为"导出 SQL/JSON"模式，不直接调接口
+- ✅ **角色分配全量覆盖处理**：`role-assign` 模式下，AI 内部自动"查旧 menuIds + 合并新增"再调用，防止漏带原有菜单。平台侧已防重复分配，无需额外备份机制
+- ✅ **仅新增不删除**：所有 upsert 工具按唯一键去重跳过；删除走人工 SQL（防误删导致大面积失权）
+- ✅ **审计报告**：每次执行后，在 `reports/PERMISSION_SYNC_<YYYYMMDD>.md` 追加日志（角色/动作变更、接口调用、data.ts 修改行位置）
+
+---
+
+## 6. 直连接口参考（无 MCP 时的兜底）
+
+所有接口共用 Headers：
+
+```
+Content-Type: application/json
+Authorization: Bearer <token>
+```
+
+| 操作                 | 方法 | 路径                                                | Body                                                          |
+| -------------------- | ---- | --------------------------------------------------- | ------------------------------------------------------------- |
+| 查询角色列表         | GET  | `/system/role/list?current=1&size=100`              | -                                                             |
+| 新增角色             | POST | `/system/role/save`                                 | `{ roleName, code, configDesc }`                              |
+| 查询全量可授权菜单   | GET  | `/system/menu/get/subMenu?size=999`                 | -                                                             |
+| 角色分配菜单         | POST | `/system/role/saveRoleMenus`                        | `{ roleId, menuIds: "id1,id2" }` （**逗号分隔字符串**）         |
+| 查询页面下子菜单/动作 | GET  | `/system/menu/children?current=1&size=10&menuId=X` | -                                                             |
+| 新增动作（type=A）   | POST | `/system/menu/save`                                 | `{ parentId, type:"A", menuName, permission, icon, orderNum, sysAppNo, intIsActive:1, useCache:1 }` |
+
+---
+
+## 7. 与其他 Skill 联动
+
+- **page-codegen**：生成 toolbar 按钮时，若 api.md 中声明了操作集，在 `data.ts` 的 `ActionButtonDesc` 中预留 `permission: []`（空数组占位），等待 permission-sync 后续填入真实权限码
+- **menu-sync**：菜单注册成功后，AI 应主动询问"是否给该页面挂动作？" → 触发 action-attach
+- **convention-audit**：审计 `data.ts` 工具栏按钮是否都设置了非空的 `permission` 字段（字段缺失或为 `[]` 视为偏差）
+- **prototype-scan**：扫描原型时识别按钮操作 → 写入 `reports/SYS_PERMISSION_INFO.md` 基线
+
+---
+
+## 8. 报告输出（reports/PERMISSION_SYNC_<日期>.md）
+
+```md
+# 权限同步报告 2026-04-29
+
+## role-manage
+- ✅ 新增角色：测试角色（QA）/ test_qa
+
+## role-assign
+- ✅ 角色 default_role 已分配 5 个菜单：[id1, id2, ...]
+- ⚠️ 替换原有 7 个菜单（已确认）
+
+## action-attach
+- ✅ customer 页面新增 4 个动作：add/edit/remove/export
+- ✅ 代码已加 v-permission（src/views/customer/list/index.vue 第 32-45 行）
+
+## 回滚提示
+- 角色分配可通过重新调用 saveRoleMenus 传旧 menuIds 恢复
+- 新增的角色/动作建议通过后端管理界面手动删除（防止误删生产数据）
+```

package/files/.github/skills/sync/permission-sync/USAGE.md

@@ -0,0 +1,107 @@
+# permission-sync · 使用示例
+
+> 给团队成员看的快速上手文档。AI 触发协议见 `SKILL.md`。
+
+---
+
+## 一句话理解
+
+**permission-sync = 角色管理 + 角色授权 + 挂动作 + 加 v-permission**
+
+整条链路覆盖"页面建好后，怎么让指定角色的人能看见、能点按钮"的全过程。
+
+---
+
+## 三种典型对话
+
+### 1. 创建角色
+
+```
+用户：创建一个测试角色，code 是 test_qa
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = role-manage
+     调用 wls_role_query 检查 → code=test_qa 不存在
+     调用 wls_role_upsert
+     ✅ 创建成功
+```
+
+### 2. 给角色分配菜单
+
+```
+用户：给『档案普通人员』分配『客户档案』和『客户申请』两个菜单
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = role-assign
+     ⚠️ 注意：saveRoleMenus 是全量覆盖，原有菜单会被替换
+     是否继续？(yes/no)
+用户：yes
+AI ： 调用 wls_role_assign_menus
+     ✅ 角色授权成功
+```
+
+### 3. 给页面挂动作 + 加权限字段（数据驱动，无需改模板）
+
+```
+用户：给『客户档案』页面加上 新增/编辑/删除 三个按钮
+AI ： [触发 permission-sync]
+     [Pre-flight] 模式 = action-attach
+     1. wls_action_query 查询已有动作 → 无
+     2. wls_action_upsert 注册到后端：customer_add / customer_edit / customer_remove
+     3. 在 src/views/customer/list/data.ts 找到工具栏按钮配置，
+        给每个对应按钮的 ActionButtonDesc 添加 permission 字段：
+        { name: 'add', label: '新增', permission: ['customer_add'], ... }
+     ✅ 完成（已写报告 reports/PERMISSION_SYNC_20260429.md）
+```
+
+> **为什么不用 v-permission 指令？**  
+> 本项目 `BaseToolbar` 内部读取 `ActionButtonDesc.permission` 字段做权限控制，  
+> 只需在 `data.ts` 的按钮配置对象里加字段，不需要改 `.vue` 模板，也不依赖全局指令注册。
+
+---
+
+## 常见问题
+
+### Q1：角色授权时，为什么 menuIds 要传完整列表？
+
+后端 `saveRoleMenus` 是**全量覆盖**接口。你传 `[A, B]`，原先 `[A, B, C]` 就会变成 `[A, B]`，C 丢失。
+
+**正确做法**：先查角色现有菜单 → 合并新菜单 → 一起传。
+
+### Q2：权限码写在 `data.ts` 哪里？不需要改模板吗？
+
+对，**不需要改模板（`.vue` 文件）**。`BaseToolbar` 从 `ActionButtonDesc` 的 `permission` 字段读取权限码，在渲染时内部做拦截，标准结构如下：
+
+```ts
+// data.ts
+{
+  name: 'edit',
+  label: '编辑',
+  permission: ['qmmcProcessCodeMain_update'],  // ← 就加这一行
+  onClick: (row: any) => modalRef.value?.edit(row.id)
+}
+```
+
+`permission` 是数组，支持多权限码 OR 逻辑（有其中任意一个权限码即显示按钮）。
+
+### Q3：权限码用短形式还是长形式？
+
+参照项目既有用法。新项目建议短形式（`customer_add`），与平台示例数据一致。
+
+### Q4：能批量删除角色/动作吗？
+
+**不能**。permission-sync 仅新增不删除（防误删）。删除请走后端管理界面手动操作。
+
+---
+
+## 配置要点
+
+只需 `.github/skills/sync/env.local.json` 的根字段：
+
+```json
+{
+  "gatewayPath": "http://你的网关:端口",
+  "sysAppNo": "应用编码",
+  "token": "Bearer Token"
+}
+```
+
+不需要额外配置 `parentRoleId` / `parentPermissionId` 之类——所有父级 id 由 AI 在执行流程中通过查询接口动态获取。

package/mcp/api/roleApi.js

@@ -0,0 +1,60 @@
+'use strict'
+
+const { wlsFetch } = require('./client')
+
+/**
+ * 查询角色列表（分页）
+ * GET /system/role/list?current=1&size=10
+ */
+function queryRoleList(params, config) {
+  const current = (params && params.current) || 1
+  const size = (params && params.size) || 100
+  return wlsFetch(
+    `/system/role/list?current=${current}&size=${size}`,
+    {},
+    config
+  )
+}
+
+/**
+ * 新增角色
+ * POST /system/role/save
+ * body: { roleName, code, configDesc }
+ */
+function saveRole(body, config) {
+  return wlsFetch('/system/role/save', { method: 'POST', body }, config)
+}
+
+/**
+ * 查询全量可授权菜单（用于角色分配菜单）
+ * GET /system/menu/get/subMenu?size=999
+ */
+function queryAssignableMenus(config) {
+  return wlsFetch('/system/menu/get/subMenu?size=999', {}, config)
+}
+
+/**
+ * 给角色批量分配菜单权限
+ * POST /system/role/saveRoleMenus
+ * body: { roleId, menuIds: "id1,id2,id3" }  // 注意 menuIds 是逗号分隔字符串
+ */
+function saveRoleMenus(body, config) {
+  return wlsFetch('/system/role/saveRoleMenus', { method: 'POST', body }, config)
+}
+
+/**
+ * 查询父菜单下的子菜单/动作列表
+ * GET /system/menu/children?current=1&size=10&menuId=xxx
+ */
+function queryMenuChildren(menuId, config) {
+  const params = `current=1&size=999&menuId=${encodeURIComponent(menuId)}`
+  return wlsFetch(`/system/menu/children?${params}`, {}, config)
+}
+
+module.exports = {
+  queryRoleList,
+  saveRole,
+  queryAssignableMenus,
+  saveRoleMenus,
+  queryMenuChildren,
+}

package/mcp/server.js

@@ -5,11 +5,17 @@
  * wl-skills MCP Server
  *
  * 实现 MCP 协议（stdio transport，JSON-RPC 2.0）
- * 暴露 4 个工具：
- *   wls_menu_query   查询菜单树
- *   wls_menu_upsert  批量新增/更新菜单
- *   wls_dict_query   查询字典模块
- *   wls_dict_upsert  新增/更新字典模块及字典项
+ * 暴露工具：
+ *   wls_menu_query                查询菜单树
+ *   wls_menu_upsert               批量新增/更新菜单
+ *   wls_dict_query                查询字典模块
+ *   wls_dict_upsert               新增/更新字典模块及字典项
+ *   wls_role_query                查询角色列表
+ *   wls_role_upsert               批量新增角色（按 code 去重）
+ *   wls_assignable_menus_query    查询全量可授权菜单（用于角色授权）
+ *   wls_role_assign_menus         给角色批量分配菜单权限
+ *   wls_action_query              查询页面菜单下的动作（type=A）
+ *   wls_action_upsert             批量新增动作（按 permission 去重）
  *
  * 启动方式（由 .cursor/mcp.json 自动注入）：
  *   node node_modules/@agile-team/wl-skills-kit/mcp/server.js
@@ -19,6 +25,14 @@ const readline = require('readline')
 const { loadConfig } = require('./config')
 const { handleMenuQuery, handleMenuUpsert } = require('./tools/menuSync')
 const { handleDictQuery, handleDictUpsert } = require('./tools/dictSync')
+const {
+  handleRoleQuery,
+  handleRoleUpsert,
+  handleRoleAssignMenus,
+  handleAssignableMenusQuery,
+  handleActionQuery,
+  handleActionUpsert,
+} = require('./tools/permissionSync')
 
 const PKG = require('../package.json')
 
@@ -102,6 +116,94 @@ const TOOLS = [
       required: ['module'],
     },
   },
+  {
+    name: 'wls_role_query',
+    description:
+      '查询角色列表。可选参数 current/size 翻页，默认 size=100。返回精简字段：id, roleName, code, sysAppNo, roleDesc。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        current: { type: 'number', description: '页码，默认 1' },
+        size: { type: 'number', description: '每页数量，默认 100' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'wls_role_upsert',
+    description:
+      '批量新增角色（按 code 字段自动去重；已存在则跳过）。每项必填 roleName 和 code，可选 configDesc。' +
+      '注意：角色仅新增不更新，因角色变更通常需要业务确认。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        items: {
+          type: 'array',
+          description:
+            '角色数组。字段：roleName(必填，显示名), code(必填，唯一标识), configDesc(可选，描述)',
+          items: { type: 'object' },
+        },
+      },
+      required: ['items'],
+    },
+  },
+  {
+    name: 'wls_assignable_menus_query',
+    description:
+      '查询全量可授权菜单列表（扁平结构，含菜单 id/menuName/permission）。' +
+      '在 wls_role_assign_menus 前调用，AI 据此选出要分配给角色的 menuIds。',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'wls_role_assign_menus',
+    description:
+      '给指定角色批量分配菜单权限。menuIds 传字符串数组，内部自动拼成逗号分隔字符串提交后端。' +
+      '该接口为全量覆盖式，应包含该角色所有菜单（含已有的，否则会被移除）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        roleId: { type: 'string', description: '角色 id（来自 wls_role_query）' },
+        menuIds: {
+          type: 'array',
+          description: '该角色应拥有的全部菜单 id 数组',
+          items: { type: 'string' },
+        },
+      },
+      required: ['roleId', 'menuIds'],
+    },
+  },
+  {
+    name: 'wls_action_query',
+    description:
+      '查询指定页面菜单（type=C）下的动作按钮列表（type=A）。返回 id/menuName/permission/orderNum/icon。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        menuId: { type: 'string', description: '父菜单 id（页面菜单）' },
+      },
+      required: ['menuId'],
+    },
+  },
+  {
+    name: 'wls_action_upsert',
+    description:
+      '在指定页面菜单下批量新增动作按钮（type=A），按 permission 字段自动去重。' +
+      '权限码命名规范：{资源camelCase}_{动作} 或 {模块}:{资源}:{动作}（与项目既有约定保持一致）。' +
+      '常见动作：add/edit/remove/export/import/approve。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        parentId: { type: 'string', description: '页面菜单 id（动作挂在它下面）' },
+        items: {
+          type: 'array',
+          description:
+            '动作数组。字段：menuName(必填，显示名), permission(必填，权限码), icon(可选，默认list), orderNum(可选，默认1), useCache(可选，默认1)',
+          items: { type: 'object' },
+        },
+      },
+      required: ['parentId', 'items'],
+    },
+  },
 ]
 
 // ─── JSON-RPC 协议层 ────────────────────────────────────────────────────
@@ -145,6 +247,24 @@ async function dispatchTool(id, toolName, toolArgs) {
       case 'wls_dict_upsert':
         text = await handleDictUpsert(toolArgs, config)
         break
+      case 'wls_role_query':
+        text = await handleRoleQuery(toolArgs, config)
+        break
+      case 'wls_role_upsert':
+        text = await handleRoleUpsert(toolArgs, config)
+        break
+      case 'wls_assignable_menus_query':
+        text = await handleAssignableMenusQuery(toolArgs, config)
+        break
+      case 'wls_role_assign_menus':
+        text = await handleRoleAssignMenus(toolArgs, config)
+        break
+      case 'wls_action_query':
+        text = await handleActionQuery(toolArgs, config)
+        break
+      case 'wls_action_upsert':
+        text = await handleActionUpsert(toolArgs, config)
+        break
       default:
         sendError(id, -32601, `未知工具: ${toolName}`)
         return

package/mcp/tools/permissionSync.js

@@ -0,0 +1,321 @@
+'use strict'
+
+const {
+  queryRoleList,
+  saveRole,
+  queryAssignableMenus,
+  saveRoleMenus,
+  queryMenuChildren,
+} = require('../api/roleApi')
+const { saveMenu } = require('../api/menuApi')
+
+/* ──────────────────────────────────────────────────────────────────────
+ * 角色管理
+ * ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * wls_role_query 工具处理器
+ * 查询角色列表（仅返回字段精简后的角色摘要）
+ */
+async function handleRoleQuery(args, config) {
+  const result = await queryRoleList(args || {}, config)
+
+  if (!result.ok) {
+    return `❌ 查询角色失败: ${result.error} (code: ${result.code})`
+  }
+
+  const page = result.data && result.data.page
+  const records = (page && page.records) || []
+
+  if (records.length === 0) {
+    return '✅ 角色查询成功，当前应用暂无角色数据'
+  }
+
+  // 仅保留关键字段，减少 token 浪费
+  const slim = records.map((r) => ({
+    id: r.id,
+    roleName: r.roleName,
+    code: r.code,
+    sysAppNo: r.sysAppNo,
+    roleDesc: r.roleDesc,
+  }))
+
+  return [
+    `✅ 角色查询成功，当前页 ${records.length} 条 / 共 ${page.total} 条（current=${page.current}, pages=${page.pages}）`,
+    '',
+    JSON.stringify(slim, null, 2),
+  ].join('\n')
+}
+
+/**
+ * wls_role_upsert 工具处理器
+ * 批量新增角色（仅新增，不更新；以 code 字段去重）
+ *
+ * @param {{ items: Array<{ roleName: string, code: string, configDesc?: string }> }} args
+ */
+async function handleRoleUpsert(args, config) {
+  const { items } = args || {}
+
+  if (!Array.isArray(items) || items.length === 0) {
+    return '❌ 参数错误：items 必须是非空数组'
+  }
+
+  // 先查全量角色，按 code 去重
+  const queryResult = await queryRoleList({ size: 999 }, config)
+  if (!queryResult.ok) {
+    return `❌ 查询现有角色失败: ${queryResult.error}`
+  }
+  const existingCodes = new Set(
+    ((queryResult.data && queryResult.data.page && queryResult.data.page.records) || [])
+      .map((r) => r.code)
+  )
+
+  const results = []
+
+  for (const item of items) {
+    if (!item.roleName || !item.code) {
+      results.push({
+        roleName: item.roleName || '(未命名)',
+        code: item.code || '(无)',
+        status: '❌ roleName 与 code 必填',
+      })
+      continue
+    }
+
+    if (existingCodes.has(item.code)) {
+      results.push({
+        roleName: item.roleName,
+        code: item.code,
+        status: '⏭ 已存在（跳过）',
+      })
+      continue
+    }
+
+    const body = {
+      roleName: item.roleName,
+      code: item.code,
+      configDesc: item.configDesc || '',
+    }
+
+    const r = await saveRole(body, config)
+    results.push({
+      roleName: item.roleName,
+      code: item.code,
+      status: r.ok ? '✅ 创建成功' : `❌ 失败: ${r.error}`,
+    })
+  }
+
+  return formatTable(
+    results,
+    ['roleName', 'code', 'status'],
+    ['角色名', 'code', '状态']
+  )
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ * 角色授权（给角色挂菜单）
+ * ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * wls_role_assign_menus 工具处理器
+ * 给指定角色批量分配菜单权限
+ *
+ * @param {{ roleId: string, menuIds: string[] }} args - menuIds 用数组传入，内部拼成逗号字符串
+ */
+async function handleRoleAssignMenus(args, config) {
+  const { roleId, menuIds } = args || {}
+
+  if (!roleId) {
+    return '❌ 参数错误：roleId 必填'
+  }
+  if (!Array.isArray(menuIds) || menuIds.length === 0) {
+    return '❌ 参数错误：menuIds 必须是非空字符串数组'
+  }
+
+  const body = {
+    roleId,
+    menuIds: menuIds.join(','),
+  }
+
+  const r = await saveRoleMenus(body, config)
+  if (!r.ok) {
+    return `❌ 角色授权失败: ${r.error} (code: ${r.code})`
+  }
+
+  return `✅ 角色授权成功（roleId=${roleId}，已分配 ${menuIds.length} 个菜单/动作）`
+}
+
+/**
+ * wls_assignable_menus_query 工具处理器
+ * 查询全量可授权菜单（扁平/树形由后端决定）
+ */
+async function handleAssignableMenusQuery(_args, config) {
+  const r = await queryAssignableMenus(config)
+  if (!r.ok) {
+    return `❌ 查询可授权菜单失败: ${r.error} (code: ${r.code})`
+  }
+  // data 可能是 { records: [...] } 或数组
+  const records = (r.data && r.data.records) || (Array.isArray(r.data) ? r.data : [])
+  if (records.length === 0) {
+    return '✅ 查询成功，当前无可授权菜单'
+  }
+  return [
+    `✅ 可授权菜单查询成功，共 ${records.length} 条`,
+    '',
+    JSON.stringify(records, null, 2),
+  ].join('\n')
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ * 挂动作（给页面菜单加 type=A 的动作按钮）
+ * ──────────────────────────────────────────────────────────────────── */
+
+/**
+ * wls_action_query 工具处理器
+ * 查询指定页面菜单下的动作子项（type=A）
+ *
+ * @param {{ menuId: string }} args
+ */
+async function handleActionQuery(args, config) {
+  const { menuId } = args || {}
+  if (!menuId) {
+    return '❌ 参数错误：menuId 必填（页面菜单 id）'
+  }
+
+  const r = await queryMenuChildren(menuId, config)
+  if (!r.ok) {
+    return `❌ 查询子菜单失败: ${r.error} (code: ${r.code})`
+  }
+
+  const records = (r.data && r.data.records) || []
+  // 仅保留 type=A（动作）
+  const actions = records.filter((m) => m.type === 'A')
+
+  if (actions.length === 0) {
+    return `✅ 查询成功，菜单 ${menuId} 下暂无动作（type=A）`
+  }
+
+  const slim = actions.map((a) => ({
+    id: a.id,
+    menuName: a.menuName,
+    permission: a.permission,
+    orderNum: a.orderNum,
+    icon: a.icon,
+  }))
+
+  return [
+    `✅ 动作查询成功，共 ${actions.length} 条`,
+    '',
+    JSON.stringify(slim, null, 2),
+  ].join('\n')
+}
+
+/**
+ * wls_action_upsert 工具处理器
+ * 在指定页面菜单下批量新增动作（type=A），按 permission 去重
+ *
+ * @param {{ parentId: string, items: Array<object> }} args
+ *   items 元素：{ menuName, permission, icon?, orderNum?, useCache? }
+ */
+async function handleActionUpsert(args, config) {
+  const { parentId, items } = args || {}
+
+  if (!parentId) {
+    return '❌ 参数错误：parentId 必填（页面菜单 id）'
+  }
+  if (!Array.isArray(items) || items.length === 0) {
+    return '❌ 参数错误：items 必须是非空数组'
+  }
+
+  // 先查父菜单下已有动作，按 permission 去重
+  const queryResult = await queryMenuChildren(parentId, config)
+  if (!queryResult.ok) {
+    return `❌ 查询现有动作失败: ${queryResult.error}`
+  }
+  const existing = ((queryResult.data && queryResult.data.records) || [])
+    .filter((m) => m.type === 'A')
+  const existingPerms = new Set(existing.map((m) => m.permission))
+
+  const results = []
+
+  for (const item of items) {
+    if (!item.menuName || !item.permission) {
+      results.push({
+        menuName: item.menuName || '(未命名)',
+        permission: item.permission || '(无)',
+        status: '❌ menuName 与 permission 必填',
+      })
+      continue
+    }
+
+    if (existingPerms.has(item.permission)) {
+      results.push({
+        menuName: item.menuName,
+        permission: item.permission,
+        status: '⏭ 已存在（跳过）',
+      })
+      continue
+    }
+
+    const body = {
+      parentId,
+      type: 'A',
+      menuName: item.menuName,
+      permission: item.permission,
+      icon: item.icon || 'list',
+      orderNum: item.orderNum != null ? item.orderNum : 1,
+      useCache: item.useCache != null ? item.useCache : 1,
+      sysAppNo: config.sysAppNo,
+      intIsActive: 1,
+    }
+
+    const r = await saveMenu(body, config)
+    if (r.ok) {
+      const saved = r.data
+      results.push({
+        menuName: item.menuName,
+        permission: item.permission,
+        status: `✅ 创建成功 (id=${saved ? saved.id : '?'})`,
+      })
+    } else {
+      results.push({
+        menuName: item.menuName,
+        permission: item.permission,
+        status: `❌ 失败: ${r.error}`,
+      })
+    }
+  }
+
+  return formatTable(
+    results,
+    ['menuName', 'permission', 'status'],
+    ['动作名', '权限码', '状态']
+  )
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ * 工具函数
+ * ──────────────────────────────────────────────────────────────────── */
+
+function formatTable(rows, keys, headers) {
+  const successCount = rows.filter((r) => r.status.startsWith('✅')).length
+  const skipCount = rows.filter((r) => r.status.startsWith('⏭')).length
+  const failCount = rows.length - successCount - skipCount
+
+  let out = `操作完成：成功 ${successCount} 条，跳过 ${skipCount} 条，失败 ${failCount} 条\n\n`
+  out += '| ' + headers.join(' | ') + ' |\n'
+  out += '|' + headers.map(() => '---').join('|') + '|\n'
+  for (const r of rows) {
+    out += '| ' + keys.map((k) => r[k]).join(' | ') + ' |\n'
+  }
+  return out
+}
+
+module.exports = {
+  handleRoleQuery,
+  handleRoleUpsert,
+  handleRoleAssignMenus,
+  handleAssignableMenusQuery,
+  handleActionQuery,
+  handleActionUpsert,
+}

package/package.json

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

package/files/.github/skills/sync/permission-sync/SKILL.draft.md

@@ -1,91 +0,0 @@
----
-name: permission-sync
-description: "[PLANNED — DRAFT, not yet active] 权限同步 Skill 设计草稿。基于 reports/SYS_PERMISSION_INFO.md 基线，将页面级/按钮级权限码注册到系统权限表，并按角色分配。"
-status: planned
----
-
-# Skill: 权限同步（permission-sync）— 草稿
-
-> ⚠️ **本文件为设计草稿（SKILL.draft.md），未启用，不参与 AI 调度。**
-
----
-
-## 1. 设计目标
-
-新增页面后，除菜单外还需注册：
-
-- **页面访问权限**（`mmwr:customer:list`）
-- **按钮级权限**（`mmwr:customer:add` / `:edit` / `:remove` / `:approve` / `:export` ...）
-- **数据权限**（可选：客户经理只看自己的客户等）
-- **角色绑定**（哪些角色获得这些权限）
-
----
-
-## 2. 数据流
-
-```
-本地基线                                  后端接口                              Skill 触发
-────────────────────────────────────────  ──────────────────────────────────  ────────────────
-reports/SYS_PERMISSION_INFO.md  ─fetch─→  GET  /sys/permission/listAll
-                                ←compare── POST /sys/permission/batchSave
-                                ─upload─→ POST /sys/role/assignPermissions  ─→  "同步权限"
-```
-
----
-
-## 3. 权限码命名规范
-
-```
-{服务缩写}:{资源camelCase}:{操作}
-```
-
-| 操作     | 含义           | 示例                            |
-| -------- | -------------- | ------------------------------- |
-| list     | 查看列表       | `mmwr:customer:list`            |
-| detail   | 查看详情       | `mmwr:customer:detail`          |
-| add      | 新增           | `mmwr:customer:add`             |
-| edit     | 编辑           | `mmwr:customer:edit`            |
-| remove   | 删除           | `mmwr:customer:remove`          |
-| export   | 导出           | `mmwr:customer:export`          |
-| import   | 导入           | `mmwr:customer:import`          |
-| submit   | 提交审批       | `mmwr:customer:submit`          |
-| approve  | 审批通过       | `mmwr:customer:approve`         |
-| reject   | 审批驳回       | `mmwr:customer:reject`          |
-| {custom} | 自定义业务操作 | `mmwr:customer:convertToFormal` |
-
----
-
-## 4. 三种工作模式
-
-| 模式       | 触发                    | 动作                                                   |
-| ---------- | ----------------------- | ------------------------------------------------------ |
-| `scan`     | "扫描权限码"            | 从 src/views/ 扫 v-permission / hasPerm 调用，输出清单 |
-| `register` | "注册权限码 / 同步权限" | 对比基线 → 创建缺失 + 更新描述                         |
-| `assign`   | "给 XX 角色分配权限"    | 选定角色 + 选定权限码 → 调 /sys/role/assignPermissions |
-
----
-
-## 5. 安全约束
-
-- **生产环境拒绝直接 push**：检测 gatewayPath 含 prod/.com 时强制走"导出 SQL"模式
-- **角色分配二次确认**：每次 assign 必须在 Pre-flight 中列出"角色 → 新增/移除的权限"，得到用户 yes 才执行
-- **不删除权限**：永远只新增/更新，删除走人工 SQL（防误删导致大面积失权）
-- **审计**：每次 register/assign 输出 `reports/PERMISSION_SYNC_<YYYYMMDD>.md`，含完整调用日志和回滚 SQL
-
----
-
-## 6. 与其他 Skill 联动
-
-- **page-codegen**：生成 toolbar 时根据 api.md 操作集自动加 `v-permission` 指令
-- **menu-sync**：菜单注册后提示"是否同步注册访问权限"
-- **convention-audit**：审计按钮是否都有 v-permission
-
----
-
-## 7. 转正前的开发任务
-
-- [ ] 确认后端权限模型（RBAC / ABAC？是否分页面权限和按钮权限？）
-- [ ] 数据权限是否纳入本 Skill（建议：暂不，单独 data-permission-sync）
-- [ ] 设计 v-permission 指令的项目内实现（如 @jhlc/common-core 提供则复用）
-- [ ] 多租户场景下的权限继承策略
-- [ ] 与 SSO（嘉为蓝鲸）权限同步策略