@agile-team/wl-skills-kit 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [2.3.0] - 2026-04-27
+
+### 🤖 MCP Server 内置（菜单 & 字典自动同步）
+
+#### MCP Server
+- 新增 `mcp/` 目录（随包发布），内置 MCP stdio server（纯 Node.js，无三方依赖，兼容 Node 16+）
+- 暴露 4 个 Tools：`wls_menu_query` / `wls_menu_upsert` / `wls_dict_query` / `wls_dict_upsert`
+- `wls_dict_upsert` 内部自动处理 dict module `data=null` 问题（创建后自动 re-query 拿 id，再创建字典项）
+- `mcp/config.js` 从 `.github/skills/sync/env.local.json` 读取配置，占位值校验友好提示
+
+#### CLI 更新
+- `wl-skills init` / `update` 新增 Step 2.5：自动生成 `.cursor/mcp.json` 和 `.claude/settings.json`（已存在则跳过）
+- `package.json` 的 `files` 字段加入 `mcp/`，确保随包发布
+- `--help` 保护路径说明补充 MCP 配置文件条目
+
+#### 配置扩展
+- `files/.github/skills/sync/env.local.json` 模板新增 `menu.domainId` 字段（MCP wls_menu_query 使用）
+
+#### 文档同步
+- `files/.github/guides/architecture.md`：第 8 节新增 MCP 模式说明；第 4.2 节 dict-sync 状态改为 ✅；bin 工作流补 Step 5；版本表更新至 v2.3.0
+- `files/.github/guides/usage.md`：Skill 速览表 menu-sync / dict-sync 行补充"MCP 自动模式"说明；FAQ 新增 MCP 配置问题
+- `README.md`：新增"MCP Server"章节（工具清单 + 配置说明 + 效率对比表）
+- `docs/mcp建议.md`：新增第七节（已确认接口清单），更新阶段一目录结构为实际 .js 文件
+
+---
+
+## [2.2.0] - 2026-04-27
+
+### 🔄 sync-version.js 扩展 + 文档修复
+
+#### sync-version.js 扩展
+- 新增 `SKILL_COUNT` 常量（值 8），改一处自动同步到所有编辑器适配文件中的 Skill 数量描述
+- 新增同步目标：`package.json description`、`files/.github/skills/_compat/headers/cursor-mdc.txt`、`kiro.txt`、`trae.txt`
+
+#### 流程文档更新
+- `files/.github/guides/usage.md`：完整流水线补充 step 5（dict-sync）和 step 7（code-fix）
+- `files/.github/standards/12-base-table.md`：新增批量 cid 碰撞预防代码块
+- `files/.github/skills/core/convention-audit/SKILL.md`：Rule 12 旧格式 cid 降级为 🟡 偏差（迁移豁免）
+
+---
+
 ## [2.1.5] - 2026-04-27
 
 ### 🔄 版本自动同步 + 发布流程优化

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@agile-team/wl-skills-kit?label=wl-skills-kit&color=brightgreen)](https://www.npmjs.com/package/@agile-team/wl-skills-kit)
 
-**AI Skill 模板包 v2.2.0** — 一条命令尗13 条编码规范、8 个 AI Skill、组件文档、领域样例导入 Vue 3 项目。
+**AI Skill 模板包 v2.3.0** — 一条命令导入 13 条编码规范、8 个 AI Skill、组件文档、领域样例到 Vue 3 项目。
 
-让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
+让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。内置 MCP Server 实现菜单和字典自动同步（对话轮数 ≤ 2）。
 
 ---
 
@@ -12,10 +12,11 @@
 
 ```bash
 npx @robot-admin/git-standards init      # 工程化前置（必须）
-npx @agile-team/wl-skills-kit            # 安装 AI 体系
+npx @agile-team/wl-skills-kit            # 安装 AI 体系（自动生成 MCP 配置）
+# 填写 .github/skills/sync/env.local.json（token / domainId）
 # 在 AI 对话中：
-"扫描 docs/prototypes/ 下的原型生成页面清单"
-"基于上一步生成所有 api.md，再 codegen 出页面"
+"扩展菜单"
+"加字典"
 ```
 
 ---
@@ -187,6 +188,46 @@ npx @agile-team/wl-skills-kit update
 
 ---
 
+## MCP Server（菜单 & 字典自动同步）
+
+`init` 安装时会自动生成 `.cursor/mcp.json` 和 `.claude/settings.json`，将 wl-skills MCP server 注册到 AI 编辑器。**无需手动配置**，启动 Cursor / Claude Code 后自动启用。
+
+### 提供的工具
+
+| 工具 | 用途 |
+|---|---|
+| `wls_menu_query` | 查询当前应用完整菜单树（用于决策新增/更新） |
+| `wls_menu_upsert` | 批量新增或更新菜单（有 id=更新，无 id=新增，自动返回服务端 id） |
+| `wls_dict_query` | 查询所有字典模块及字典项 |
+| `wls_dict_upsert` | 新增/更新字典模块+字典项（内部自动 re-query 获取 id） |
+
+### 配置（安装后填写一次）
+
+在 `.github/skills/sync/env.local.json` 中填写：
+
+```json
+{
+  "gatewayPath": "http://你的网关地址:端口",
+  "token": "Bearer Token（不含 Bearer 前缀）",
+  "sysAppNo": "应用编码",
+  "menu": {
+    "domainId": "从 Network 面板 getMenuTreeByDomainId?domainId=xxx 中获取",
+    "parentMenuId": "新建菜单的父节点 ID"
+  }
+}
+```
+
+> `env.local.json` 已自动加入 `.gitignore`，不会入库。
+
+### 效率对比
+
+| 方式 | 同步 10 条菜单 | 手动操作 | 耗时 |
+|---|---|---|---|
+| SKILL.md（prompt-based） | ~4000 token | 10 次 | ~20 分钟 |
+| **MCP tools** | ~500 token | **0 次** | **~1 分钟** |
+
+---
+
 ## Skill 概览
 
 | Skill              | 状态      | 路径                                     | 核心用途                      |

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.2.0
+ * wl-skills-kit CLI v2.3.0
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -52,7 +52,9 @@ if (showHelp) {
 
   保护路径（init / update 不覆盖已存在的）:
     .github/reports/                               AI 生成报告（团队累积数据，存在则跳过）
-    .github/skills/sync/menu-sync/env/env.local.json  用户本地配置（token 等，已存在则跳过）
+    .github/skills/sync/env.local.json             用户本地配置（token 等，已存在则跳过）
+    .cursor/mcp.json                               MCP 配置（已存在则跳过，避免覆盖其他 server）
+    .claude/settings.json                          MCP 配置（已存在则跳过）
 
   清理保护路径（clean 不删除）:
     src/components/    通用组件（被业务页面 import，构建必需）
@@ -381,6 +383,62 @@ function runInstall(incremental) {
     }
   }
 
+  // ── Step 2.5: MCP 配置文件（.cursor/mcp.json + .claude/settings.json）──────
+
+  const MCP_SERVER_ARGS = ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"];
+  const MCP_CONFIGS = [
+    {
+      relPath: ".cursor/mcp.json",
+      content: JSON.stringify(
+        {
+          mcpServers: {
+            "wl-skills": {
+              command: "node",
+              args: MCP_SERVER_ARGS,
+              env: { WL_PROJECT_ROOT: "${workspaceFolder}" },
+            },
+          },
+        },
+        null,
+        2
+      ),
+    },
+    {
+      relPath: ".claude/settings.json",
+      content: JSON.stringify(
+        {
+          mcpServers: {
+            "wl-skills": {
+              command: "node",
+              args: MCP_SERVER_ARGS,
+              env: { WL_PROJECT_ROOT: "." },
+            },
+          },
+        },
+        null,
+        2
+      ),
+    },
+  ];
+
+  if (dryRun) console.log("\n  [Step 2.5] MCP 配置文件:\n");
+
+  for (const mc of MCP_CONFIGS) {
+    const mcDest = path.join(TARGET_DIR, mc.relPath);
+    if (fs.existsSync(mcDest)) {
+      preserved++;
+      if (dryRun) console.log("  保留  " + mc.relPath + "  (已存在，不覆盖)");
+    } else {
+      if (dryRun) {
+        console.log("  新增  " + mc.relPath);
+        created++;
+      } else {
+        writeFile(mcDest, mc.content);
+        created++;
+      }
+    }
+  }
+
   // ── Step 3: 迁移清理（仅 update，清理旧版遗留文件）──────────────────
 
   if (incremental) {

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

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员  
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）  
-> **当前版本**：v2.2.0（2026-04-27）
+> **当前版本**：v2.3.0（2026-04-27）
 
 ---
 
@@ -102,7 +102,10 @@ wl-skills.js init/update
     │      - reports/*.md 已存在则跳过（保护团队累积数据）
     │      - 其他文件：覆盖写入
     │
-    └─ 5. 写入/更新 .wl-skills-manifest.json（文件哈希快照）
+    ├─ 5. 生成 MCP 配置文件（.cursor/mcp.json + .claude/settings.json）
+    │      - 已存在则跳过（不覆盖用户已有配置）
+    │
+    └─ 6. 写入/更新 .wl-skills-manifest.json（文件哈希快照）
 ```
 
 ---
@@ -213,7 +216,7 @@ skills/
 │
 ├── sync/                数据同步类（与后端系统联动）
 │   ├── menu-sync/           ✅ 启用：菜单基线 ↔ 后端菜单接口
-│   ├── dict-sync/           ⏳ PLANNED
+│   ├── dict-sync/           ✅ 启用：字典基线 ↔ 后端字典接口
 │   └── permission-sync/     ⏳ PLANNED
 │
 ├── ops/                 运维/质量类
@@ -424,7 +427,24 @@ AI "假执行"——声称读了规范，实际按惯性输出。没有强制约
 
 ## 8. 菜单/字典/权限同步机制
 
-三类 sync Skill 共用同一模式，以 `menu-sync` 为基准（已启用）：
+三类 sync Skill 共用同一基线模式。**v2.3.0 起，menu-sync 和 dict-sync 同时提供 SKILL.md prompt 模式（手动中转）和 MCP Server 自动模式（零手动）**：
+
+### MCP 自动模式（推荐，v2.3.0+）
+
+```
+开发者说："扩展菜单" / "加字典"
+    ↓
+AI 自动 call MCP Tools（无需手动粘贴接口响应）：
+    wls_menu_query  → 拉取现有菜单树
+    wls_menu_upsert → 批量新增/更新
+    wls_dict_query  → 拉取现有字典模块
+    wls_dict_upsert → 创建模块 + 字典项（内部自动 re-query 拿 id）
+```
+
+`init` 时自动生成 `.cursor/mcp.json` + `.claude/settings.json`（已存在则跳过）。
+MCP server 从 `.github/skills/sync/env.local.json` 读取 `gatewayPath / token / menu.domainId`。
+
+### SKILL.md Prompt 模式（兼容，无 MCP 环境可用）
 
 ```
 本地基线文件（reports/SYS_MENU_INFO.md）
@@ -437,7 +457,7 @@ AI "假执行"——声称读了规范，实际按惯性输出。没有强制约
            ③ 对比：基线 vs 线上 → 找出缺失条目
            ④ Pre-flight 输出操作预览（必须用户确认）
            ⑤ 调用后端接口写入
-           ⑥ 输出操作日志（含回滚 SQL）到 reports/MENU_SYNC_*.md
+           ⑥ 输出操作日志到 reports/MENU_SYNC_*.md
 ```
 
 **关键设计约束**：
@@ -475,9 +495,10 @@ AI "假执行"——声称读了规范，实际按惯性输出。没有强制约
 | ---- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------- |
 | v1.x | 5 个 Skill 平铺 + 9 个 TPL 平铺 + 单一超长 copilot-instructions                                                                           | ✅ 已发布 |
 | v2.0 | 规范模块化（13 条）+ 模板分层（universal/domains）+ 报告分类 + Pre-flight + 工具链门控                                                    | ✅ 已发布 |
-| v2.1 | Skill 分级目录（core/sync/ops/domain）+ 多 AI 适配解耦（editors.json）+ 各 Skill USAGE.md + api-contract 真实响应 + 3 个 PLANNED 草稿补全 | ✅ 当前   |
-| v2.2 | dict-sync / permission-sync / code-fix 从 PLANNED → 转正（视后端接口稳定情况）                                                            | ⏳ 规划中 |
-| v2.3 | CI 流水线接入（convention-audit 报告注入 PR 评论）+ Skill 版本感知                                                                        | ⏳ 规划中 |
+| v2.1 | Skill 分级目录（core/sync/ops/domain）+ 多 AI 适配解耦（editors.json）+ 各 Skill USAGE.md + api-contract 真实响应 + 3 个 PLANNED 草稿补全 | ✅ 已发布 |
+| v2.2 | sync-version.js（版本号自动同步）+ dict-sync / code-fix 正式激活 + 8 个 Skill 全部就绪                                                    | ✅ 已发布 |
+| v2.3 | MCP Server 内置（wls_menu_query/upsert + wls_dict_query/upsert）+ init 自动写 MCP 配置 + env.local.json 新增 menu.domainId                | ✅ 当前   |
+| v2.4 | permission-sync MCP 化（待后端接口确认）                                                                                                   | ⏳ 规划中 |
 
 ---
 

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

@@ -55,8 +55,8 @@ AI 会自动识别意图，触发对应的 Skill。
 | `prototype-scan`   | 扫描原型 / 解析原型 / 口述需求 | 原型 / 详设 → page-spec JSON |
 | `api-contract`     | 接口约定 / api.md / 字段定义   | 生成接口约定文档             |
 | `page-codegen`     | 生成页面 / 帮我生成            | 生成 4 文件 + 菜单注册       |
-| `menu-sync`        | 创建菜单 / 同步菜单            | 菜单数据同步到后端           |
-| `dict-sync`        | 同步字典 / 创建字典 / 字典审计   | 字典基线同步到后端           |
+| `menu-sync`        | 创建菜单 / 同步菜单            | 菜单数据同步到后端（MCP 自动 / prompt 手动两种模式） |
+| `dict-sync`        | 同步字典 / 创建字典 / 字典审计   | 字典基线同步到后端（MCP 自动 / prompt 手动两种模式） |
 | `convention-audit` | 规范审计 / 代码审计            | 13 条规范扫描 + 偏差报告     |
 | `template-extract` | 提取模板 / 抄取模板            | 从现有页面沉淠领域专属模板   |
 | `code-fix`         | 自动修复 / 整改偏差 / 规范整改   | 受控自动修复审计报告中的偏差 |
@@ -119,6 +119,9 @@ A: 触发 `template-extract`，从现有标杆页面提取为领域专属模板
 **Q: 多个 AI 编辑器之间会冲突吗？**
 A: 不会。`bin/wl-skills.js` 已自动生成 8 种主流 AI 编辑器配置文件，所有内容来自同一份 `copilot-instructions.md`，保持一致。
 
+**Q: MCP Server 是什么？需要额外配置吗？**
+A: `wl-skills init` 会自动生成 `.cursor/mcp.json`（Cursor 用）和 `.claude/settings.json`（Claude Code 用）。只需在 `.github/skills/sync/env.local.json` 里填好 `token`、`gatewayPath`、`menu.domainId` 即可。填写后重启编辑器，对 AI 说「扩展菜单」或「加字典」，AI 会自动调用接口完成同步，无需手动粘贴接口响应。
+
 **Q: 部署到生产环境前如何清理 AI 文件？**
 A: 执行 `npx @agile-team/wl-skills-kit clean`。会移除所有 AI 辅助文件，保留 `src/components/` 和 `src/types/`。
 

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

@@ -7,7 +7,8 @@
 
   "menu": {
     "_comment": "menu-sync 专属配置",
-    "parentMenuId": "父级菜单ID（从菜单管理后台获取）"
+    "parentMenuId": "父级菜单ID（从菜单管理后台获取，新建菜单时的父节点）",
+    "domainId": "应用域ID（从 Network 面板 getMenuTreeByDomainId?domainId=xxx 中获取，MCP wls_menu_query 使用）"
   },
 
   "dict": {

package/mcp/api/client.js

@@ -0,0 +1,76 @@
+'use strict'
+
+const https = require('https')
+const http = require('http')
+
+/**
+ * 带鉴权的 HTTP 客户端（兼容 Node 16+，无额外依赖）
+ *
+ * @param {string} urlPath - 接口路径（以 / 开头），拼接到 config.gatewayPath 后
+ * @param {{ method?: string, body?: unknown }} options
+ * @param {{ gatewayPath: string, token: string }} config
+ * @returns {Promise<{ ok: boolean, data: any, error?: string, code?: number }>}
+ */
+function wlsFetch(urlPath, options, config) {
+  const fullUrl = config.gatewayPath + urlPath
+  const isHttps = fullUrl.startsWith('https')
+  const lib = isHttps ? https : http
+  const bodyStr = options.body ? JSON.stringify(options.body) : null
+
+  let urlObj
+  try {
+    urlObj = new URL(fullUrl)
+  } catch (e) {
+    return Promise.reject(new Error(`无效的 URL: ${fullUrl}`))
+  }
+
+  const reqOptions = {
+    hostname: urlObj.hostname,
+    port: urlObj.port || (isHttps ? 443 : 80),
+    path: urlObj.pathname + urlObj.search,
+    method: options.method || 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${config.token}`,
+    },
+  }
+
+  if (bodyStr) {
+    reqOptions.headers['Content-Length'] = Buffer.byteLength(bodyStr)
+  }
+
+  return new Promise((resolve, reject) => {
+    const req = lib.request(reqOptions, (res) => {
+      let data = ''
+      res.on('data', (chunk) => { data += chunk })
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data)
+          if (json.code === 2000) {
+            resolve({ ok: true, data: json.data, code: json.code })
+          } else {
+            resolve({
+              ok: false,
+              data: null,
+              error: json.message || `服务端返回 code=${json.code}`,
+              code: json.code,
+            })
+          }
+        } catch (e) {
+          reject(new Error(`响应解析失败: ${e.message}，原始内容: ${data.slice(0, 200)}`))
+        }
+      })
+    })
+
+    req.on('error', (e) => reject(new Error(`请求失败: ${e.message}`)))
+    req.setTimeout(15000, () => {
+      req.destroy()
+      reject(new Error('请求超时（15s）'))
+    })
+
+    if (bodyStr) req.write(bodyStr)
+    req.end()
+  })
+}
+
+module.exports = { wlsFetch }

package/mcp/api/dictApi.js

@@ -0,0 +1,40 @@
+'use strict'
+
+const { wlsFetch } = require('./client')
+
+/**
+ * 查询字典树（全量，含所有模块和字典项）
+ * GET /system/business/dict/getDictionaryTreeData
+ * 响应结构: { data: { dictionary: { children: DictModule[] } } }
+ *
+ * @param {{ gatewayPath: string, token: string }} config
+ */
+function queryDictModules(config) {
+  return wlsFetch('/system/business/dict/getDictionaryTreeData', {}, config)
+}
+
+/**
+ * 新增或更新字典模块
+ * POST /system/dictModule/save
+ * ⚠️ 响应 data 为 null，创建后必须通过 queryDictModules + strSn 匹配才能拿到 id
+ *
+ * @param {object} body - DictModuleSaveBody
+ * @param {{ gatewayPath: string, token: string }} config
+ */
+function saveDictModule(body, config) {
+  return wlsFetch('/system/dictModule/save', { method: 'POST', body }, config)
+}
+
+/**
+ * 新增字典值（词典项）
+ * POST /system/business/dict/save
+ * 响应 data 为 null（只需确认 code=2000 成功即可）
+ *
+ * @param {object} body - DictItemSaveBody
+ * @param {{ gatewayPath: string, token: string }} config
+ */
+function saveDictItem(body, config) {
+  return wlsFetch('/system/business/dict/save', { method: 'POST', body }, config)
+}
+
+module.exports = { queryDictModules, saveDictModule, saveDictItem }

package/mcp/api/menuApi.js

@@ -0,0 +1,32 @@
+'use strict'
+
+const { wlsFetch } = require('./client')
+
+/**
+ * 查询指定应用域的菜单树
+ * GET /system/menu/getMenuTreeByDomainId?domainId={domainId}
+ *
+ * @param {string} domainId
+ * @param {{ gatewayPath: string, token: string }} config
+ */
+function queryMenuTree(domainId, config) {
+  return wlsFetch(
+    `/system/menu/getMenuTreeByDomainId?domainId=${encodeURIComponent(domainId)}`,
+    {},
+    config
+  )
+}
+
+/**
+ * 新增或更新菜单
+ * POST /system/menu/save
+ * 有 id → 更新；无 id → 新增（响应 data 含服务端生成的完整对象包括 id）
+ *
+ * @param {object} body - MenuSaveBody
+ * @param {{ gatewayPath: string, token: string }} config
+ */
+function saveMenu(body, config) {
+  return wlsFetch('/system/menu/save', { method: 'POST', body }, config)
+}
+
+module.exports = { queryMenuTree, saveMenu }

package/mcp/config.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * 从项目的 .github/skills/sync/env.local.json 加载 MCP 运行配置
+ * 项目根目录通过环境变量 WL_PROJECT_ROOT 传入（由 .cursor/mcp.json 注入）
+ */
+function loadConfig() {
+  const projectRoot = process.env.WL_PROJECT_ROOT
+    ? path.resolve(process.env.WL_PROJECT_ROOT)
+    : process.cwd()
+
+  const configPath = path.join(projectRoot, '.github', 'skills', 'sync', 'env.local.json')
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      `配置文件不存在: ${configPath}\n` +
+      `请先执行 npx @agile-team/wl-skills-kit init，然后填写 .github/skills/sync/env.local.json`
+    )
+  }
+
+  let raw
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  } catch (e) {
+    throw new Error(`配置文件解析失败: ${e.message}`)
+  }
+
+  if (!raw.gatewayPath || raw.gatewayPath.includes('你的网关')) {
+    throw new Error('请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）')
+  }
+  if (!raw.token || raw.token.includes('Bearer Token')) {
+    throw new Error('请在 env.local.json 中填写真实的 token（当前为占位值）')
+  }
+
+  return {
+    gatewayPath: raw.gatewayPath.replace(/\/$/, ''), // 去掉尾部斜杠
+    token: raw.token,
+    sysAppNo: raw.sysAppNo || '',
+    menu: raw.menu || {},
+    dict: raw.dict || {},
+  }
+}
+
+module.exports = { loadConfig }

package/mcp/server.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * wl-skills MCP Server
+ *
+ * 实现 MCP 协议（stdio transport，JSON-RPC 2.0）
+ * 暴露 4 个工具：
+ *   wls_menu_query   查询菜单树
+ *   wls_menu_upsert  批量新增/更新菜单
+ *   wls_dict_query   查询字典模块
+ *   wls_dict_upsert  新增/更新字典模块及字典项
+ *
+ * 启动方式（由 .cursor/mcp.json 自动注入）：
+ *   node node_modules/@agile-team/wl-skills-kit/mcp/server.js
+ */
+
+const readline = require('readline')
+const { loadConfig } = require('./config')
+const { handleMenuQuery, handleMenuUpsert } = require('./tools/menuSync')
+const { handleDictQuery, handleDictUpsert } = require('./tools/dictSync')
+
+const PKG = require('../package.json')
+
+// ─── Tool 注册表 ────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'wls_menu_query',
+    description:
+      '查询当前应用的完整菜单树。自动从 .github/skills/sync/env.local.json 读取 domainId，' +
+      '无需传参。在 wls_menu_upsert 前调用，用于判断哪些菜单需要新增、哪些需要更新。',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'wls_menu_upsert',
+    description:
+      '批量新增或更新菜单项。有 id 字段 → 更新；无 id 字段 → 新增。' +
+      '新增时响应自动包含服务端生成的 id，可链式用于创建子菜单。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        items: {
+          type: 'array',
+          description:
+            'MenuSaveBody 数组。每项字段：' +
+            'id(更新时传), sysAppNo, menuName, menuNameCode, parentId, ' +
+            'type("M"=目录/"C"=菜单), path, icon, orderNum, ' +
+            'useCache(1), common(2), hidden(false), editMode(false), ' +
+            'component(type=C时传), permission(type=C时传)',
+          items: { type: 'object' },
+        },
+      },
+      required: ['items'],
+    },
+  },
+  {
+    name: 'wls_dict_query',
+    description:
+      '查询当前应用的所有字典模块及字典项。在 wls_dict_upsert 前调用，' +
+      '用于判断哪些模块/字典项已存在。',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'wls_dict_upsert',
+    description:
+      '新增或更新字典模块及其字典项。内部自动处理：' +
+      '若模块不存在则创建（data=null 后自动 re-query 获取 id），' +
+      '若已存在则直接取 id；字典项自动跳过已存在的 strSn。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        module: {
+          type: 'object',
+          description: 'DictModuleSaveBody: strSn(必填), strName(必填), sortPriority("1"), strLevel(2)',
+          properties: {
+            strSn: { type: 'string', description: '模块标识符，如 "gender"' },
+            strName: { type: 'string', description: '模块显示名，如 "性别"' },
+            sortPriority: { type: 'string', description: '排序，字符串类型，如 "1"' },
+            strLevel: { type: 'number', description: '固定传 2' },
+          },
+          required: ['strSn', 'strName'],
+        },
+        items: {
+          type: 'array',
+          description:
+            'DictItemSaveBody 数组（可选）。每项字段：' +
+            'strSn(必填), strName(必填), strLevel(2), ' +
+            'dtlValue(""), dtlValueRequired(false), dtlValue2Required(false), ' +
+            'dtlValue3Required(false), dtlValue4Required(false)',
+          items: { type: 'object' },
+        },
+      },
+      required: ['module'],
+    },
+  },
+]
+
+// ─── JSON-RPC 协议层 ────────────────────────────────────────────────────
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: '2.0', id, result })
+}
+
+function sendError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } })
+}
+
+// ─── Tool 调度 ───────────────────────────────────────────────────────────
+
+async function dispatchTool(id, toolName, toolArgs) {
+  let config
+  try {
+    config = loadConfig()
+  } catch (e) {
+    // 配置加载失败：以文本形式返回给 AI（不是 JSON-RPC error，AI 能读）
+    sendResult(id, { content: [{ type: 'text', text: `❌ 配置加载失败: ${e.message}` }], isError: true })
+    return
+  }
+
+  try {
+    let text
+    switch (toolName) {
+      case 'wls_menu_query':
+        text = await handleMenuQuery(config)
+        break
+      case 'wls_menu_upsert':
+        text = await handleMenuUpsert(toolArgs, config)
+        break
+      case 'wls_dict_query':
+        text = await handleDictQuery(config)
+        break
+      case 'wls_dict_upsert':
+        text = await handleDictUpsert(toolArgs, config)
+        break
+      default:
+        sendError(id, -32601, `未知工具: ${toolName}`)
+        return
+    }
+    sendResult(id, { content: [{ type: 'text', text }] })
+  } catch (e) {
+    sendResult(id, {
+      content: [{ type: 'text', text: `❌ 工具执行异常: ${e.message}` }],
+      isError: true,
+    })
+  }
+}
+
+// ─── 消息循环 ────────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false })
+
+rl.on('line', async (line) => {
+  const raw = line.trim()
+  if (!raw) return
+
+  let msg
+  try {
+    msg = JSON.parse(raw)
+  } catch (e) {
+    send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })
+    return
+  }
+
+  const { id, method, params = {} } = msg
+
+  // Notifications（无 id）不需要响应
+  if (id === undefined || id === null) return
+
+  switch (method) {
+    case 'initialize':
+      sendResult(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'wl-skills', version: PKG.version },
+      })
+      break
+
+    case 'tools/list':
+      sendResult(id, { tools: TOOLS })
+      break
+
+    case 'tools/call':
+      await dispatchTool(id, params.name, params.arguments || {})
+      break
+
+    case 'ping':
+      sendResult(id, {})
+      break
+
+    default:
+      sendError(id, -32601, `Method not found: ${method}`)
+  }
+})
+
+rl.on('close', () => {
+  process.exit(0)
+})

package/mcp/tools/dictSync.js

@@ -0,0 +1,173 @@
+'use strict'
+
+const { queryDictModules, saveDictModule, saveDictItem } = require('../api/dictApi')
+
+/**
+ * 从字典树查询响应中提取模块列表
+ * 响应结构: { dictionary: { children: DictModule[] } }
+ *
+ * @param {any} data - queryDictModules 返回的 result.data
+ * @returns {object[]}
+ */
+function extractModules(data) {
+  if (!data) return []
+  if (data.dictionary && Array.isArray(data.dictionary.children)) {
+    return data.dictionary.children
+  }
+  if (Array.isArray(data)) return data
+  return []
+}
+
+/**
+ * wls_dict_query 工具处理器
+ * 查询当前应用的所有字典模块及字典项
+ *
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function handleDictQuery(config) {
+  const result = await queryDictModules(config)
+
+  if (!result.ok) {
+    return `❌ 查询字典失败: ${result.error} (code: ${result.code})`
+  }
+
+  const modules = extractModules(result.data)
+
+  if (modules.length === 0) {
+    return '✅ 字典查询成功，当前应用暂无字典数据'
+  }
+
+  return `✅ 字典查询成功，共 ${modules.length} 个模块\n\n${JSON.stringify(modules, null, 2)}`
+}
+
+/**
+ * wls_dict_upsert 工具处理器
+ * 新增或更新字典模块及字典项（完整幂等流程）
+ *
+ * 流程：
+ * ① 查询现有模块，检查 strSn 是否已存在
+ * ② 若不存在：创建模块（data=null）→ 重新查询 → 用 strSn 定位拿 id
+ * ③ 若已存在：跳过模块创建，直接取已有 id
+ * ④ 遍历 items，跳过 strSn 已存在的，其余逐条创建
+ *
+ * @param {{ module: object, items?: object[] }} args
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function handleDictUpsert(args, config) {
+  const { module: moduleBody, items = [] } = args
+
+  if (!moduleBody || !moduleBody.strSn) {
+    return '❌ 参数错误：module.strSn 必填'
+  }
+  if (!moduleBody.strName) {
+    return '❌ 参数错误：module.strName 必填'
+  }
+
+  // ① 查询现有模块
+  const queryResult = await queryDictModules(config)
+  if (!queryResult.ok) {
+    return `❌ 查询字典失败: ${queryResult.error}`
+  }
+
+  const existingModules = extractModules(queryResult.data)
+  let targetModule = existingModules.find((m) => m.strSn === moduleBody.strSn)
+  let moduleAction
+
+  // ② 模块不存在时创建
+  if (!targetModule) {
+    const saveBody = {
+      strSn: moduleBody.strSn,
+      strName: moduleBody.strName,
+      sortPriority: moduleBody.sortPriority != null ? String(moduleBody.sortPriority) : '1',
+      strLevel: 2,
+    }
+
+    const createResult = await saveDictModule(saveBody, config)
+    if (!createResult.ok) {
+      return `❌ 创建字典模块失败: ${createResult.error}`
+    }
+
+    // ③ 重新查询（data=null，只能靠 re-query 拿 id）
+    const reQueryResult = await queryDictModules(config)
+    if (!reQueryResult.ok) {
+      return `❌ 重新查询字典失败: ${reQueryResult.error}`
+    }
+
+    const freshModules = extractModules(reQueryResult.data)
+    targetModule = freshModules.find((m) => m.strSn === moduleBody.strSn)
+
+    if (!targetModule) {
+      return `❌ 字典模块创建后未能找到（strSn="${moduleBody.strSn}"），请在字典管理后台确认`
+    }
+
+    moduleAction = '✅ 已创建'
+  } else {
+    moduleAction = '⏭ 已存在（跳过创建）'
+  }
+
+  const moduleId = targetModule.id
+
+  // ④ 处理字典项
+  const existingItems = Array.isArray(targetModule.dictionaries)
+    ? targetModule.dictionaries
+    : []
+  const existingSns = new Set(existingItems.map((i) => i.strSn))
+
+  const itemResults = []
+
+  for (const item of items) {
+    if (existingSns.has(item.strSn)) {
+      itemResults.push({
+        strSn: item.strSn,
+        strName: item.strName || '',
+        status: '⏭ 已存在（跳过）',
+      })
+      continue
+    }
+
+    const itemBody = {
+      moduleId,
+      strSn: item.strSn,
+      strName: item.strName,
+      strLevel: 2,
+      dtlValue: item.dtlValue != null ? item.dtlValue : '',
+      dtlValueRequired: item.dtlValueRequired || false,
+      dtlValue2Required: item.dtlValue2Required || false,
+      dtlValue3Required: item.dtlValue3Required || false,
+      dtlValue4Required: item.dtlValue4Required || false,
+    }
+
+    const createResult = await saveDictItem(itemBody, config)
+    if (createResult.ok) {
+      itemResults.push({ strSn: item.strSn, strName: item.strName || '', status: '✅ 已创建' })
+    } else {
+      itemResults.push({
+        strSn: item.strSn,
+        strName: item.strName || '',
+        status: `❌ 失败: ${createResult.error}`,
+      })
+    }
+  }
+
+  const createdCount = itemResults.filter((r) => r.status.startsWith('✅')).length
+  const skippedCount = itemResults.filter((r) => r.status.startsWith('⏭')).length
+  const failedCount = itemResults.filter((r) => r.status.startsWith('❌')).length
+
+  let output = `字典模块 "${moduleBody.strSn}" (${moduleBody.strName})：${moduleAction}\n`
+  output += `模块 ID：${moduleId}\n`
+
+  if (items.length > 0) {
+    output += `字典项：创建 ${createdCount}，跳过 ${skippedCount}，失败 ${failedCount}\n\n`
+    output += '| strSn | strName | 状态 |\n'
+    output += '|---|---|---|\n'
+    for (const r of itemResults) {
+      output += `| ${r.strSn} | ${r.strName} | ${r.status} |\n`
+    }
+  }
+
+  return output
+}
+
+module.exports = { handleDictQuery, handleDictUpsert }

package/mcp/tools/menuSync.js

@@ -0,0 +1,96 @@
+'use strict'
+
+const { queryMenuTree, saveMenu } = require('../api/menuApi')
+
+/**
+ * wls_menu_query 工具处理器
+ * 自动从 config.menu.domainId 读取应用域 ID，查询完整菜单树
+ *
+ * @param {{ menu: { domainId?: string } }} config
+ * @returns {Promise<string>} 返回给 AI 的文本内容
+ */
+async function handleMenuQuery(config) {
+  const domainId = config.menu && config.menu.domainId
+
+  if (!domainId || domainId.toString().includes('domainId')) {
+    return [
+      '❌ 请在 env.local.json 的 menu.domainId 字段填写真实的应用域 ID',
+      '',
+      '获取方式：打开菜单管理后台，在 Network 面板找到类似',
+      '  getMenuTreeByDomainId?domainId=1777597797627056130',
+      '中的数字即为 domainId，填入 env.local.json：',
+      '  "menu": { "domainId": "1777597797627056130", ... }',
+    ].join('\n')
+  }
+
+  const result = await queryMenuTree(domainId, config)
+
+  if (!result.ok) {
+    return `❌ 查询菜单树失败: ${result.error} (code: ${result.code})`
+  }
+
+  const tree = result.data
+  const isEmpty = !tree || (Array.isArray(tree) && tree.length === 0)
+  if (isEmpty) {
+    return `✅ 菜单树查询成功，当前应用域（domainId=${domainId}）暂无菜单数据`
+  }
+
+  return `✅ 菜单树查询成功（domainId=${domainId}）\n\n${JSON.stringify(tree, null, 2)}`
+}
+
+/**
+ * wls_menu_upsert 工具处理器
+ * 批量新增（无 id）或更新（有 id）菜单项
+ * 新增时从响应 data 取服务端生成的 id，可用于链式创建子菜单
+ *
+ * @param {{ items: object[] }} args
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function handleMenuUpsert(args, config) {
+  const { items } = args
+
+  if (!Array.isArray(items) || items.length === 0) {
+    return '❌ 参数错误：items 必须是非空数组'
+  }
+
+  const results = []
+
+  for (const item of items) {
+    const isUpdate = Boolean(item.id)
+    const action = isUpdate ? '更新' : '新增'
+
+    const result = await saveMenu(item, config)
+
+    if (result.ok) {
+      const saved = result.data
+      results.push({
+        action,
+        menuName: item.menuName || '(未命名)',
+        id: saved ? saved.id : item.id,
+        status: '✅ 成功',
+      })
+    } else {
+      results.push({
+        action,
+        menuName: item.menuName || '(未命名)',
+        id: item.id || '(新增)',
+        status: `❌ 失败: ${result.error}`,
+      })
+    }
+  }
+
+  const successCount = results.filter((r) => r.status.startsWith('✅')).length
+  const failCount = results.length - successCount
+
+  let output = `菜单操作完成：成功 ${successCount} 条，失败 ${failCount} 条\n\n`
+  output += '| 操作 | 菜单名 | ID | 状态 |\n'
+  output += '|---|---|---|---|\n'
+  for (const r of results) {
+    output += `| ${r.action} | ${r.menuName} | ${r.id} | ${r.status} |\n`
+  }
+
+  return output
+}
+
+module.exports = { handleMenuQuery, handleMenuUpsert }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.2.0",
-  "description": "AI Skill 模板包 v2.2.0 — 13 条编码规范 + 8 个 AI Skill，一条命令导入 Vue 3 项目",
+  "version": "2.3.0",
+  "description": "AI Skill 模板包 v2.3.0 — 13 条编码规范 + 8 个 AI Skill，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
     "wl-skills": "bin/wl-skills.js"
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "files/",
+    "mcp/",
     "README.md",
     "CHANGELOG.md"
   ],