@agile-team/wl-skills-kit 2.7.0 → 2.7.2

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

@@ -7,14 +7,21 @@ description: "Use when: syncing data dictionary entries to the backend, pulling
 
 将 `data.ts` 中引用的数据字典（`logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"`）同步到后端字典表，保持本地基线与线上一致。
 
-> **与 menu-sync 的关系**：机制完全对称——同样读取本地基线报告 → 与线上对比 → 补齐差异。  
-> 配置直接复用 `skills/sync/env.local.json` 统一配置文件，无需重复填写。
+> **与 menu-sync / permission-sync 对称**：同样读取本地基线 → 与线上对比 → 补齐差异。配置共用 `skills/sync/env.local.json`。
 
 ---
 
-## 配置（统一配置文件，无需重复填写）
+## 📖 必读公共护栏
 
-读取 `.github/skills/sync/env.local.json`（已在 .gitignore，不入 git）：
+本 Skill 遵守 `../_mcp-guardrail.md`（MCP 调用纪律与自愈闭环）。AI 首次执行 sync 类任务时先 `read_file` 加载它。
+
+本 Skill 使用的 MCP 工具：`wls_dict_query` / `wls_dict_upsert`。调用失败时按 guardrail §2 剧本引导用户完善 `env.local.json` 后重试，**不得用 curl/手拼 HTTP 绕开 MCP**。
+
+---
+
+## 配置（统一配置文件）
+
+读取 `.github/skills/sync/env.local.json`（已在 `.gitignore`，不入 git）：
 
 ```json
 {
@@ -27,9 +34,14 @@ description: "Use when: syncing data dictionary entries to the backend, pulling
 }
 ```
 
-`moduleId` 获取方式：进入低代码平台「数据字典」模块 → 新增一条字典 → DevTools Network → 查找 `moduleId` 字段值。
+| 字段 | 说明 |
+|---|---|
+| `gatewayPath` | 后端网关，末尾不加斜杠 |
+| `sysAppNo` | 应用编码（非明文） |
+| `token` | 纯 JWT，**不含 `bearer ` 前缀**（MCP 内部自动拼接） |
+| `dict.moduleId` | 字典所属模块 ID（字典管理后台 Network 抓取） |
 
-**向下兼容**：如上述文件不存在，回落到 `skills/sync/menu-sync/env/env.local.json`（老版本路径）。
+> 字段获取方式见同目录 `../menu-sync/env/guide.md`。
 
 ---
 
@@ -37,26 +49,14 @@ description: "Use when: syncing data dictionary entries to the backend, pulling
 
 ```
 🚀 已触发技能 dict-sync/SKILL.md → 字典同步
-✅ 已读取 skills/sync/env.local.json   → 网关地址、token、sysAppNo、dict.moduleId
-✅ 已读取 reports/SYS_DICT_INFO.md     → 本地字典基线
+✅ MCP 工具检查：wls_dict_query / wls_dict_upsert 均可用
+✅ 已读取 .github/skills/sync/env.local.json → 网关 + token + sysAppNo + dict.moduleId
+✅ 已读取 .github/reports/SYS_DICT_INFO.md   → 本地字典基线
 ✅ 操作模式：{pull / push / audit}
-✅ 目标字典码：{用户指定 / 从 data.ts 扫描到的字典码列表}
-```
-
----
-
-## API 调用规范
-
-所有接口使用以下 Headers：
-
-```
-Authorization: Bearer {token}
-Sysappno: {sysAppNo}
-Content-Type: application/json
+✅ 目标字典码：{用户指定 / data.ts 扫描结果}
 ```
 
-**成功判断**：`response.code === 2000`  
-**Token 失效**：`code === 401` 或 `code` 不在 `[200, 2000]` 且 message 含 "token" → 停止执行，提示用户更新 token。
+> Pre-flight 任一项失败（特别是 MCP 工具检查），立即停止并向用户报告，**不得**降级为手动调接口。
 
 ---
 
@@ -66,40 +66,13 @@ Content-Type: application/json
 
 **触发词**：`刷新字典基线` / `拉字典`
 
-```
-调用 GET {gatewayPath}/system/business/dict/getDictionaryTreeData
-→ 解析 data.data.dictionary.children（递归，无 children 的节点为字典叶节点）
-→ 整理为 SYS_DICT_INFO.md 格式覆盖写入
-→ 输出：共拉取 N 个字典码，M 个字典项
-```
-
-**接口**：
-```
-GET {gatewayPath}/system/business/dict/getDictionaryTreeData
-Headers:
-  Authorization: Bearer {token}
-  Sysappno: {sysAppNo}
-```
+**执行**：
+1. 调用 MCP 工具 `wls_dict_query`（无参）
+2. 工具返回当前应用域全部字典模块 + 字典项树
+3. AI 解析返回结果，整理为 SYS_DICT_INFO.md 格式覆盖写入
+4. 输出："共拉取 N 个字典码，M 个字典项"
 
-**响应结构**：
-```json
-{
-  "code": 2000,
-  "data": {
-    "dictionary": {
-      "children": [
-        {
-          "id": "节点ID",
-          "strSn": "字典编码或模块编码",
-          "strName": "字典名称",
-          "children": [...]
-        }
-      ]
-    }
-  }
-}
-```
-叶节点（无 `children`）= 实际字典，取其 `id`（用于后续创建字典项）和 `strSn`。
+> MCP 内部对应 `GET /system/business/dict/getDictionaryTreeData`，AI **无需关心**。
 
 ---
 
@@ -110,93 +83,82 @@ Headers:
 #### Step 1：扫描 data.ts 中的字典引用
 
 从用户指定范围扫描所有：
+
 ```typescript
 logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"
 ```
-收集所有 `logicValue` 值去重，得到「当前用到的字典码集合」。
+
+去重得到「当前用到的字典码集合」。
 
 #### Step 2：与本地基线 + 线上对比（去重双保险）
 
 ```
-① 读取 reports/SYS_DICT_INFO.md → 已知字典码（本地已记录，大概率线上有）
-② 调用 getDictionaryTreeData → 当前线上实际存在的字典码（strSn 列表）
+① 读取 reports/SYS_DICT_INFO.md → 本地已知字典码
+② 调用 wls_dict_query           → 线上当前字典码（strSn 列表）
 ③ 待创建 = 用到的字典码 - 线上已有字典码
 ```
 
-> **多人协同说明**：每人各自的 env.local.json 不入 git，各人用自己的 token。  
-> 去重通过 Step ② 线上实时查询保证：A 创建了，B 运行时线上已有，自动跳过，**不会重复创建**。  
-> 即使极端并发（两人同一秒执行），后端 `strSn` 字段有唯一约束，第二次创建会返回"已存在"，Skill 将其视为成功跳过。
+> **多人协同**：每人 env.local.json 不入 git。去重通过 ② 线上实时查询保证；后端 `strSn` 字段有唯一约束，并发场景下第二次创建会被服务端跳过，Skill 视为成功。
 
-#### Step 3：Pre-flight 输出清单，等待确认
+#### Step 3：Pre-flight 输出待新建清单，等待确认
 
 ```
 📋 待同步字典清单：
   新建：ORDER_STATUS（订单状态）— 含 4 项
   新建：SALES_COMPANY（销售公司）— 含 3 项
   跳过（线上已有）：PRODUCT_SEGMENT
-
 确认执行？(yes/no)
 ```
 
-#### Step 4：创建字典码
+#### Step 4：批量创建字典码 + 字典项
 
-```
-POST {gatewayPath}/system/business/dict/save
-Headers: Authorization / Sysappno / Content-Type
+调用 MCP 工具 `wls_dict_upsert`（**逐个字典模块**调一次）：
 
-Body:
+```jsonc
+// MCP 工具入参
 {
-  "strSn": "ORDER_STATUS",
-  "strName": "订单状态",
-  "intIsVisible": 1,
-  "intSort": 0,
-  "moduleId": "{dict.moduleId}"
+  "module": {
+    "strSn": "ORDER_STATUS",
+    "strName": "订单状态",
+    "sortPriority": "1",
+    "strLevel": 2
+  },
+  "items": [
+    { "strSn": "0", "strName": "草稿",   "strLevel": 2 },
+    { "strSn": "1", "strName": "待审核", "strLevel": 2 },
+    { "strSn": "2", "strName": "已通过", "strLevel": 2 },
+    { "strSn": "3", "strName": "已驳回", "strLevel": 2 }
+  ]
 }
 ```
 
-成功后再次调用 `getDictionaryTreeData` 获取新创建字典的 `id`（用于下一步）。
-
-#### Step 5：创建字典项
-
-**逐条**调用（服务端会跳过重复的 strKey）：
-
-```
-POST {gatewayPath}/system/dictDtl/save
-Headers: Authorization / Sysappno / Content-Type
-
-Body:
-{
-  "strKey": "1",
-  "strValue": "待审核",
-  "strSn": "ORDER_STATUS",
-  "dictId": "{上一步获取的字典 id}"
-}
-```
+> 工具内部：模块不存在则创建并自动 re-query 取 id；字典项按 strSn 自动跳过已存在项。AI 无需手动管理 id。
 
-#### Step 6：输出结果表 + 更新基线
+#### Step 5：输出结果表 + 更新基线
 
 | 字典码 | 字典名称 | 字典项数 | 状态 |
-|--------|---------|---------|------|
+|---|---|---|---|
 | ORDER_STATUS | 订单状态 | 4 | ✅ created |
 | SALES_COMPANY | 销售公司 | 3 | ✅ created |
 | PRODUCT_SEGMENT | 产品板块 | - | ⏭️ skipped（线上已有） |
 
-执行完成后，将新建字典追加写入 `reports/SYS_DICT_INFO.md`。
+执行完成后，将新建字典追加写入 `.github/reports/SYS_DICT_INFO.md`。
 
 ---
 
-### audit — 仅检查，不调接口
+### audit — 仅检查，不调写接口
 
 **触发词**：`字典审计` / `检查字典`
 
 ```
 1. 扫描指定范围的 data.ts，收集所有 logicValue 字典码
-2. 对比 SYS_DICT_INFO.md 本地基线
-3. 输出三类：
-   ✅ 已在基线中（无需操作）
-   ⚠️ data.ts 中用到但不在基线中（建议执行 push）
-   💤 在基线中但未被任何 data.ts 使用（可能已废弃）
-4. 不调用任何接口
+2. 调用 wls_dict_query 获取线上现状
+3. 对比 SYS_DICT_INFO.md 本地基线
+4. 输出三类清单：
+   ✅ 已在基线 + 线上（健康）
+   ⚠️ data.ts 用到但缺失（建议执行 push）
+   💤 在基线但未被任何 data.ts 引用（可能已废弃）
+5. 不调用任何写接口
 ```
 
 ---
@@ -208,244 +170,39 @@ Body:
 ```markdown
 ## ORDER_STATUS（订单状态）
 
-| 值（strKey） | 显示名称（strValue） | 备注 |
-| ----------- | ------------------- | ---- |
-| 0           | 草稿                |      |
-| 1           | 待审核              |      |
-| 2           | 审核通过            |      |
-```
-
-**字典码命名规范**：全大写 + 下划线，如 `ORDER_STATUS` / `SALES_COMPANY`（来自项目实际 data.ts 用法）。
-
----
-
-## 与其他 Skill 联动
-
-| Skill | 联动方式 |
-|-------|---------|
-| **page-codegen** | 生成 data.ts 时，如 `logicValue` 不在基线中，报告末尾提示"建议运行 dict-sync 补齐" |
-| **convention-audit** | 可调用 audit 模式，"字典码未在基线"列为 🟡 偏差 |
-| **menu-sync** | 共享 `skills/sync/env.local.json`，gatewayPath / token / sysAppNo 同一份配置 |
-
-
-# Skill: 字典同步（dict-sync）
-
-将 `data.ts` 中引用的数据字典（`logicType: BusLogicDataType.dict`）同步到后端字典表，保持本地基线与线上一致。
-
-> **与 menu-sync 的关系**：机制完全对称——同样读取本地基线报告 → 与线上对比 → 补齐差异。
-> 配置直接复用 `menu-sync/env/env.local.json`，无需重复填写。
-
----
-
-## ⚠️ 激活前请确认 3 个 API 端点
-
-在开始使用本 Skill 前，请与后端团队核实以下 3 个接口路径，并将正确路径填入本文件对应位置（搜索 `TODO_CONFIRM`）：
-
-| # | 用途 | 草稿路径（待确认） | 确认方式 |
-|---|------|--------------------|---------|
-| 1 | 查询全量字典列表（去重用） | `GET /system/dict/list` | DevTools → 进入"数据字典"列表页 → 查看 Network |
-| 2 | 创建/更新单个字典码 | `POST /system/dict/save` | DevTools → 新增一条字典 → 查看 Request URL + Body |
-| 3 | 批量保存字典项（value/label） | `POST /system/dictItem/save` | DevTools → 为字典添加项 → 查看 Request URL + Body |
-
-确认完成后，删除此区块即可正式使用。
-
----
-
-## 配置（复用 menu-sync，无需重复填写）
-
-本 Skill 读取顺序：
-
-1. 优先读取 `skills/sync/dict-sync/env/env.local.json`（如存在）
-2. 回落到 `skills/sync/menu-sync/env/env.local.json`（_inherit 机制）
-
-**绝大多数情况下无需单独创建字典配置**——menu-sync 配置的 `gatewayPath`、`token`、`sysAppNo` 完全共用。
-
-仅当字典接口需要独立 token 或不同网关时，才在 `dict-sync/env/env.local.json` 单独配置：
-
-```json
-{
-  "gatewayPath": "http://网关地址:端口",
-  "sysAppNo": "应用编码",
-  "token": "Bearer Token（不含 bearer 前缀）"
-}
+| 值（strSn） | 显示名称（strName） | 备注 |
+| ---------- | ------------------ | ---- |
+| 0          | 草稿               |      |
+| 1          | 待审核             |      |
+| 2          | 已通过             |      |
+| 3          | 已驳回             |      |
 ```
 
----
-
-## Pre-flight 声明（执行前必须输出）
-
-```
-🚀 已触发技能 dict-sync/SKILL.md → 字典同步
-✅ 已读取 menu-sync/env/env.local.json  → 网关地址、token、sysAppNo
-✅ 已读取 reports/SYS_DICT_INFO.md       → 本地字典基线
-✅ 操作模式：{pull / push / audit}
-✅ 目标字典码：{用户指定 / 从 data.ts 扫描到的字典码列表}
-```
-
----
-
-## SYS_DICT_INFO.md — 本地基线格式
-
-路径：`.github/reports/SYS_DICT_INFO.md`
-
-写入规范（每次 pull 后覆盖更新，push 后追加）：
-
-```markdown
-## {DICT_CODE}（{字典中文名}）
-
-| 值（value） | 显示名称（label） | 排序 | 备注 |
-| ---------- | ---------------- | ---- | ---- |
-| 0          | 草稿             | 1    |      |
-| 1          | 待审核           | 2    |      |
-| 2          | 审核通过         | 3    |      |
-| 3          | 已驳回           | 4    |      |
-```
-
-**字典码命名规范**（来自项目 data.ts 分析）：
-
-| 风格 | 正确 ✅ | 错误 ❌ |
-|------|---------|---------|
-| 全大写+下划线 | `ORDER_STATUS` / `SALES_COMPANY` | `orderStatus` / `salesCompany` |
-
----
-
-## 三种工作模式
-
-### pull — 刷新本地基线
-
-**触发词**：`刷新字典基线` / `拉字典`
-
-```
-1. 调用 GET {TODO_CONFIRM: /system/dict/list?size=500} → 获取全量字典
-2. 整理为 SYS_DICT_INFO.md 格式
-3. 覆盖写入 reports/SYS_DICT_INFO.md
-4. 输出：共拉取 N 个字典码，M 个字典项
-```
-
-**接口调用**：
-```
-GET {gatewayPath}/system/dict/list?current=1&size=500       ← TODO_CONFIRM 路径
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-```
-
-**响应处理**：取 `data.records`（或 `data.list`，以实际为准），`code === 2000` 为成功。
-
----
-
-### push — 推送新增字典（核心模式）
-
-**触发词**：`同步字典` / `创建字典` / `补字典`
-
-#### Step 1：扫描当前 data.ts 中的字典引用
-
-从用户指定范围（单文件 / 整个 src/views/）扫描所有：
-```typescript
-logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"
-```
-收集所有 `logicValue` 值，去重后得到「当前用到的字典码集合」。
-
-#### Step 2：与本地基线对比
-
-读取 `reports/SYS_DICT_INFO.md`，找出「未在基线中的字典码」（即需要新建的字典）。
-
-> 若本地基线为空或过期，提示用户先执行 `pull` 模式拉取基线。
-
-#### Step 3：Pre-flight 输出待新建清单
-
-在执行任何 API 调用前，输出：
-
-```
-📋 待同步字典清单：
-  新建字典码：ORDER_STATUS（订单状态）— 含 4 个字典项
-  新建字典码：SALES_COMPANY（销售公司）— 含 3 个字典项
-  跳过（已在基线中）：PRODUCT_SEGMENT
-
-确认执行？(yes/no)
-```
-
-等待用户确认后再执行。
-
-#### Step 4：逐条创建字典码
-
-```
-POST {gatewayPath}/system/dict/save      ← TODO_CONFIRM 路径
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-  Content-Type: application/json
-
-Body（待确认字段名）:
-{
-  "dictCode": "ORDER_STATUS",
-  "dictName": "订单状态",
-  "remark": ""
-}
-```
-
-#### Step 5：批量写入字典项
-
-```
-POST {gatewayPath}/system/dictItem/save  ← TODO_CONFIRM 路径
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-  Content-Type: application/json
-
-Body（待确认字段名，按实际接口响应调整）:
-{
-  "dictCode": "ORDER_STATUS",
-  "items": [
-    { "dictItemValue": "0", "dictItemLabel": "草稿",   "sortNo": 1 },
-    { "dictItemValue": "1", "dictItemLabel": "待审核", "sortNo": 2 }
-  ]
-}
-```
-
-#### Step 6：输出结果表
-
-| 字典码 | 字典名称 | 字典项数 | 状态 |
-|--------|---------|---------|------|
-| ORDER_STATUS | 订单状态 | 4 | ✅ created |
-| SALES_COMPANY | 销售公司 | 3 | ✅ created |
-| PRODUCT_SEGMENT | 产品板块 | 5 | ⏭️ skipped（已存在） |
-
-执行完成后，将新建字典追加写入 `reports/SYS_DICT_INFO.md`。
-
----
-
-### audit — 仅检查，不调接口
-
-**触发词**：`字典审计` / `检查字典`
-
-```
-1. 扫描指定范围的 data.ts，收集所有 logicValue 字典码
-2. 与 SYS_DICT_INFO.md 基线对比
-3. 输出三个清单：
-   ✅ 已在基线中（无需操作）
-   ⚠️ 在 data.ts 中使用但不在基线中（建议执行 push）
-   💤 在基线中但未被任何 data.ts 使用（可能已废弃）
-4. 不调用任何接口
-```
+**字典码命名规范**：全大写 + 下划线，如 `ORDER_STATUS` / `SALES_COMPANY`。
 
 ---
 
 ## 冲突处理原则
 
 | 场景 | 策略 |
-|------|------|
-| 本地新增字典，线上不存在 | 调接口创建 |
-| 字典码已存在，字典名不同 | 询问用户：以本地为准（更新）/ 保留线上 / 跳过 |
-| 字典项 value 相同，label 不同 | 询问用户：以本地为准 / 以线上为准 / 跳过 |
-| 线上存在，本地无记录 | 仅在 audit 中报告，**绝不主动删除** |
+|---|---|
+| 本地新增、线上不存在 | 调 `wls_dict_upsert` 创建 |
+| 字典码已存在、字典名不同 | 询问用户：以本地为准 / 保留线上 / 跳过 |
+| 字典项 strSn 相同、strName 不同 | 询问用户决定（Skill 默认跳过，不覆盖） |
+| 线上存在、本地无记录 | 仅在 audit 中报告，**绝不主动删除** |
 
 ---
 
 ## 与其他 Skill 联动
 
 | Skill | 联动方式 |
-|-------|---------|
-| **page-codegen** | 生成 data.ts 时，如发现 `logicValue` 字典码不在基线中，报告末尾追加"⚠️ 建议运行 dict-sync 补齐以下字典" |
-| **convention-audit** | 审计 12 号规范时，可调用 dict-sync audit 模式，将"字典码未在基线中"列为 🟡 偏差 |
-| **menu-sync** | 共享 env.local.json 配置，无需重复填写 |
+|---|---|
+| **page-codegen** | 生成 data.ts 时如 `logicValue` 不在基线中，报告末尾提示"建议运行 dict-sync 补齐" |
+| **convention-audit** | 调用 audit 模式，"字典码未在基线"列为 🟡 偏差 |
+| **menu-sync / permission-sync** | 共享 `skills/sync/env.local.json`，gatewayPath / token / sysAppNo 同一份 |
+
+---
+
+## MCP 不可用或调用失败时怎么办
+
+见 `../_mcp-guardrail.md` §2 自愈闭环剧本。**原则**：先帮用户完善 `env.local.json` 里的 token / dict.moduleId，重试 MCP 工具。**绝不允许** AI 用 curl/PowerShell/fetch 绕开 MCP 手拼 HTTP。

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

@@ -69,16 +69,19 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 
 ---
 
-## Phase 1：AI 调用 API 创建菜单（当前方案）
+## Phase 1：MCP 驱动创建菜单（当前方案）
 
-> 此方案参考平台伙伴的 jh4j-cloud skill，适配 cx-ui-produce 项目。
-> 本质是 **menu-sync-design.md 的方案 C（只增不删）**，由 AI 自动执行。
+> 本质是 **menu-sync-design.md 的方案 C（只增不删）**，由 AI 调 MCP 工具自动执行。
+
+> 📖 **必读公共护栏**：`../_mcp-guardrail.md`
+> 该文件定义了 MCP 调用纪律、错误分层判定、自愈闭环剧本。AI 首次执行 sync 类任务时必须先 `read_file` 加载它。
+>
+> 本 Skill 使用的 MCP 工具：`wls_menu_sync_from_report` / `wls_menu_query` / `wls_menu_upsert`。工具不可用或调用失败时，按 guardrail §2 剧本引导用户完善 `env.local.json` 后重试，**不得用 curl/手拼 HTTP 绕开 MCP**。
 
 ### 前置条件
 
-1. 用户提供后端系统管理地址（如 `http://localhost:9000` 或实际网关地址）
-2. 用户提供有效的 Bearer Token（从浏览器开发者工具 Network 面板复制）
-3. 用户提供父级菜单 ID（`menuId`），可通过查询接口获取
+1. MCP 已连接（工具列表中可见 `wls_menu_sync_from_report`）
+2. `.github/skills/sync/env.local.json` 已填写 `token`（纯 JWT，不含 `bearer ` 前缀）、`gatewayPath`、`sysAppNo`、`menu.parentMenuId`、`menu.domainId`
 
 ### 输入
 
@@ -96,45 +99,47 @@ SYS_MENU_INFO.md 是 menu-sync Skill 的输入数据源：
 | `C`  | 菜单（页面） | `menuName`, `path`, `permission`, `component` |
 | `A`  | 动作按钮     | `menuName`, `path`                            |
 
-### 执行流程
+### 执行流程（首选：一步到位）
 
-#### Step 1: 查询当前 domain 菜单树（防重复 + 取父级信息）
+**默认走 `wls_menu_sync_from_report`**——它内部完成「读报告 → 查菜单树 → 一级目录 upsert → 二级菜单 upsert」全流程：
 
 ```
-工具：wls_menu_query
-读取：env.local.json → menu.domainId
-返回：当前应用域完整菜单树
+工具：wls_menu_sync_from_report
+入参：{ dryRun?: boolean, reportPath?: string }   // 不传 reportPath 自动用最新 SYS_MENU_INFO*.md
+第一次执行：先传 dryRun: true 预览，确认无误后再正式执行（去掉 dryRun）
 ```
 
-> 推荐：具备 MCP 时优先调用 `wls_menu_sync_from_report`，它会自动读取最新 `SYS_MENU_INFO*.md`、查询菜单树、复用/更新目录，再把二级菜单挂到对应目录下。可先传 `dryRun: true` 做预览。
+### 手动拆分流程（仅当一步式不满足时）
 
-#### Step 2: 先创建一级目录（type=M）
-
-对于 `SYS_MENU_INFO` 中的一级目录，按 `menuName/path` 在父级 `parentMenuId` 下去重；不存在则创建，存在则复用 id。
+#### Step 1: 查询当前 domain 菜单树（防重复 + 取父级信息）
 
-#### Step 3: 再创建二级页面菜单（type=C）
+```
+工具：wls_menu_query   （无参，自动读 env.local.json → menu.domainId）
+返回：当前应用域完整菜单树
+```
 
-对于每条页面菜单，`parentId` 必须使用上一步对应目录的 id，禁止全部挂到根 `parentMenuId`。
+#### Step 2: 先创建一级目录（type=M），再创建二级页面菜单（type=C）
 
-> **响应码说明**：后端成功响应为 `code: 2000`（非标准 HTTP 200），判断成功应检查 `response.body.code === 2000` 或 `message` 包含"成功"。
+- 一级目录按 `menuName/path` 在父级 `parentMenuId` 下去重；不存在则创建，存在则复用 id
+- 二级页面菜单的 `parentId` 必须是上一步对应目录的 id，**禁止**全部挂到根 `parentMenuId`
 
 ```
-POST {gatewayPath}/system/menu/save
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-  Content-Type: application/json
+工具：wls_menu_upsert
+入参：{ items: [<下面的对象>...] }
+```
 
-Body:
+**`items[]` 单条对象模板（仅作为 MCP 入参参考，禁止 AI 自行 fetch）**：
+
+```jsonc
 {
   "useCache": 1,
   "icon": "list",
   "common": 2,
   "hidden": false,
-  "type": "C",
-  "parentId": "{parentMenuId}",
+  "type": "C",                      // "M"=目录, "C"=菜单, "A"=动作
+  "parentId": "{父级目录的 id}",
   "sysAppNo": "{sysAppNo}",
-  "orderNum": {nextOrder},
+  "orderNum": 1,
   "menuName": "客户档案",
   "menuNameCode": "{parentMenuNameCode}:{pinyinName}",
   "path": "mmwrCustomerArchive",
@@ -143,6 +148,8 @@ Body:
 }
 ```
 
+> **MCP 内部说明**（AI 不可据此自行调接口）：底层走 `POST /system/menu/save`，成功码 `code: 2000`。
+
 #### Step 3: 记录结果
 
 创建完成后输出结果表格：

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

@@ -31,18 +31,22 @@
 
 ## 前置条件
 
-`.github/skills/sync/menu-sync/env/env.local.json`（首次使用先填写）：
+`.github/skills/sync/env.local.json`（首次使用先填写，已加入 `.gitignore`）：
 
 ```json
 {
-  "gatewayPath": "https://uat-api.example.com",
-  "token": "Bearer xxx",
-  "tenantId": "10001",
-  "rootMenuId": "1234567890"
+  "gatewayPath": "http://192.168.10.50:9000",
+  "sysAppNo": "应用编码（非明文，从已有菜单接口响应获取）",
+  "token": "eyJhbGci...（纯 JWT，不含 bearer 前缀）",
+  "menu": {
+    "parentMenuId": "父级菜单 ID（菜单管理后台获取）",
+    "domainId": "应用域 ID（Network 面板 getMenuTreeByDomainId?domainId=xxx 获取）"
+  }
 }
 ```
 
-> **`env.local.json` 不入 git**（已加 .gitignore）。每个开发者本地填自己的 token。
+> **`env.local.json` 不入 git**。每个开发者本地填自己的 token（更新 token 时只换 token 字段，其他不动）。
+> 字段获取详见 `env/guide.md`。
 
 ---
 
@@ -54,11 +58,11 @@ AI：[Pre-flight]
     步骤 1：读取线上菜单基线 reports/SYS_MENU_INFO.md（最新更新：2025-04-20）
     步骤 2：扫描 src/views/produce/aiflow/ 共 7 个页面
     步骤 3：对比缺失：5 项缺失，2 项已存在
-    步骤 4：将调用 /sys/menu/save 创建 5 项
+    步骤 4：将调用 wls_menu_sync_from_report 创建 5 项
     [需你确认]：
-    - 父菜单：精整作业 → 客户管理（rootMenuId: xxx）
-    - 排序：sortNo 自动递增
-    - 权限标识：mmwr:customer:list 等
+    - 父菜单：精整作业 → 客户管理（menu.parentMenuId: xxx）
+    - 排序：orderNum 自动递增
+    - 权限标识：mmwrCustomerArchive 等
     确认 yes/no？
 ```
 
@@ -78,8 +82,10 @@ AI：[Pre-flight]
 | -------------------- | ---------------------------- | ---------------------------------------------- |
 | 同步成功但 UI 看不到 | 用户角色没分配新菜单         | 跑 permission-sync（PLANNED）或后台手工分配    |
 | 401/403 报错         | env.local.json 的 token 过期 | 重新登录系统，从 Network 抓 Authorization 替换 |
+| AI 用 curl/Invoke-RestMethod 调接口，返回 4004 | AI 没走 MCP，自行拼接了错误的接口路径 | 确认 MCP 已连接（Cursor/Kiro 设置里可见 wls_menu_sync_from_report），然后重新说「帮我同步菜单」|
+| token 填了 `Bearer eyJ...` 整串，接口 401 | Authorization Header 变成 `Bearer Bearer eyJ...` | token 字段只填 `eyJ...` 纯 JWT 部分，去掉 `bearer ` 前缀 |
 | 同名菜单重复创建     | 没读 SYS_MENU_INFO.md 基线   | 先跑一遍"刷新基线"再 sync                      |
-| 父菜单 ID 不对       | rootMenuId 配错              | 从浏览器开发者工具看父菜单的 dom data-id       |
+| 父菜单 ID 不对       | menu.parentMenuId 配错     | 从菜单后台编辑页复制菜单 ID，填入 env.local.json |
 
 ---