@agile-team/wl-skills-kit 2.7.1 → 2.7.3

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [2.7.3] - 2026-05-13
+
+### Added
+
+- **`tests/mcp-tools.test.js`**（30 个测试）：覆盖 `menuSync` 8 个纯函数（cleanCell / splitMarkdownRow / isDividerRow / parseBoolean / normalizeTree / flattenMenus / findExisting / parseReport）、`dictSync.extractModules`、`handleDictUpsert` 参数校验、`handleRoleUpsert` / `handleRoleAssignMenus` 参数校验，填补最易出 Bug 的 MCP 工具层零覆盖空白。
+- **`.gitattributes`**：统一 `eol=lf`，消除 Windows 开发者打开文件后 CRLF 行尾符变更噪音。
+
+### Changed
+
+- **`scripts/lint-skills.js`** 扩展 core/ops Skill 校验：有写操作的 5 个 Skill（page-codegen / convention-audit / business-doc-extract / template-extract / code-fix）必须包含 Pre-flight 声明 + standards 引用，防止关键约束被遗漏；同时清理旧版 AI-bypass 警告规则（误报率高，作用有限）。输出信息更新为"公共文件 N 个、sync Skill N 个、write Skill N 个全部合规"。
+- **`mcp/tools/menuSync.js` / `dictSync.js`**：新增 `_internal` 导出，暴露纯工具函数供单测调用，不影响运行时行为。
+- **`files/.github/skills/sync/permission-sync/SKILL.md`**：275 → 240 行（-13%），命名规范表从 9 行精简为 1 行覆盖范例、后端接口参考表删去冗余 Body 示例列、报告输出改为一句话描述。
+
+### Notes
+
+- 纯工程质量提升，无 Skill 行为变更、无 MCP API 变更，业务项目无需操作。
+
+## [2.7.2] - 2026-05-13
+
+### Added
+
+- **`skills/_best-practices.md`**（新文档）：场景级最佳实践索引。AI 每轮对话默认读取，按场景（新建模块 / 补菜单 / 补字典 / 角色授权 / 项目体检等）路由 Skill，弱化"靠关键词猜触发"。人也可当 Runbook 查阅。
+- **`skills/sync/_mcp-guardrail.md`**（新文档）：sync 类 Skill 通用护栏。明确 MCP 调用纪律 + 错误分层（L0~L4）+ **自愈闭环剧本**：MCP 调用失败时引导用户完善 `env.local.json`（token/domainId/gatewayPath 等）后重试，**禁止** AI 用 curl/PowerShell/fetch 绕开 MCP 自拼 HTTP。
+- **`scripts/lint-skills.js`**（新脚本）+ **`tests/lint-skills.test.js`**：静态校验 sync SKILL.md 引用 guardrail、列出"严禁 curl"纪律、无残留 `TODO_CONFIRM`，`_registry.md` 引用的 Skill 路径必须存在。`prepublishOnly` 已串联。
+- **`mcp/server.js` 启动 banner**：写入 stderr（不污染 stdio JSON-RPC），列出版本、`WL_PROJECT_ROOT`、已注册的 17 个工具，方便快速判断"MCP 是否真连上"。
+- **`mcp/api/client.js` 友好错误提示**：401 / 4004 自动附排查指引（"token 仅填纯 JWT 不含 bearer 前缀" / "gatewayPath 可能缺前缀，不要让 AI 绕开 MCP 拼 HTTP"）。
+- **`_registry.md` 增加「MCP 工具依赖」列**：明确每个 Skill 用到的 `wls_*` 工具，AI 加载 Skill 时一并核验工具可用性。
+
+### Fixed
+
+- **`dict-sync/SKILL.md`** 完全重写（451 → 215 行）：删除文件被错误拼接的旧版残留段、`TODO_CONFIRM` 错路径（`/system/dict/list` 等）、错字段名；改为 MCP 优先，明确 `wls_dict_query` / `wls_dict_upsert` 入参模板。
+- **`menu-sync/SKILL.md`**：执行流程改为 `wls_menu_sync_from_report` 一步到位优先；HTTP body 显式标注「仅为 MCP 入参参考」，杜绝 AI 据此自行 fetch。
+- **`menu-sync/USAGE.md`**：修正旧字段（`tenantId` / `rootMenuId` / 旧路径示例）→ 统一为 `sysAppNo` / `menu.parentMenuId` / `sync/env.local.json`。
+- **`permission-sync/SKILL.md` §6**：标题从"无 MCP 时的兜底"改为"MCP 内部实现，AI 不得调用"，杜绝 AI 把它当 fallback 路径自己跑 HTTP。
+
+### Changed
+
+- **`copilot-instructions.md`** AI Skills 自动调度段：新增"首选场景索引（best-practices）"流程，三件套（best-practices + registry + pipeline）联合路由替代单纯关键词命中。
+- **三个 sync SKILL.md 顶部纪律段统一**：均改为引用 `_mcp-guardrail.md`，错误处理走自愈闭环（不再"立即停止"）。
+
+### Notes
+
+- 纯文档 + MCP 运行时增强，无 SDK 行为破坏性变更，业务项目 `npx @agile-team/wl-skills-kit update` 即可同步。
+
 ## [2.7.1] - 2026-05-13
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.7.1** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.7.3** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -23,6 +23,21 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 ## 版本亮点
 
+**v2.7.3**：工程质量提升 — MCP tools 单测覆盖、lint-skills 扩展到 core Skill、.gitattributes 消除行尾符噪音、permission-sync SKILL.md 精简。
+
+- 新增 `tests/mcp-tools.test.js`（30 个测试）覆盖 menuSync/dictSync/permissionSync 核心纯函数与参数校验
+- `lint-skills` 新增 core/ops SKILL.md 规则：有写操作 Skill 必须含 Pre-flight + standards 引用
+- 新增 `.gitattributes` 统一 LF 行尾，消除 Windows 开发者提交噪音
+- `permission-sync/SKILL.md` 压缩 275 → 240 行，命名规范表与报告示例精简
+
+**v2.7.2**：sync 类 Skill 自愈闭环 + 场景索引路由。
+
+- 新增 `skills/_best-practices.md` 场景索引（AI 每轮默认加载，弱化关键词命中）
+- 新增 `skills/sync/_mcp-guardrail.md` 公共护栏（含 L0~L4 错误自愈剧本，MCP 失败时引导用户完善 `env.local.json` 而不是绕开自拼 HTTP）
+- 修复 `dict-sync/SKILL.md` 旧版残留与错路径；统一 `menu-sync/USAGE.md` 字段命名
+- MCP server 启动 banner（stderr，不污染 JSON-RPC）；client.js 401/4004 友好提示
+- 新增 `npm run lint:skills` 静态护栏，已串入 `prepublishOnly`
+
 **v2.7.1**：JH 组件文档全面修正，基于 `@jhlc/common-core` 源码校准 Props/API/映射规则。
 
 - 修正 `jh-drag-row` 6 个缺失 Props、`jh-date`/`jh-date-range` format 命名

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.7.1
+ * wl-skills-kit CLI v2.7.3
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）

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

@@ -234,6 +234,18 @@ onMounted(() => select());
 
 完整触发词与 Skill 路径见 `skills/_registry.md`（**单一数据源**，不在此处重复）。
 
+> 🔖 **首选「场景索引」**：`skills/_best-practices.md`
+>
+> 进入项目对话或开启新任务时，AI 必须先 `read_file` 加载：
+>
+> 1. `skills/_best-practices.md`（按场景的最佳实践索引，**首选路由依据**）
+> 2. `skills/_registry.md`（触发词 → Skill 路径映射）
+> 3. `skills/_pipeline.md`（Skill I/O 契约 + 推荐链式顺序）
+>
+> 三者联合判定后再决定调用哪个 Skill / MCP 工具。**禁止仅凭关键词命中就跳过 best-practices 的语义判断**。
+>
+> sync 类（菜单/字典/权限）任务必须额外加载 `skills/sync/_mcp-guardrail.md`，调用失败按 §2 自愈剧本引导用户完善配置后重试，不绕开 MCP。
+
 ### Intent Router（自然语言智能识别）
 
 用户不需要记住 Skill 名。只要消息包含以下任一语义，AI 必须自动路由到对应 Skill：

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

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.7.1（2026-05-13）
+> **当前版本**：v2.7.3（2026-05-13）
 
 ---
 

package/files/.github/skills/_best-practices.md

@@ -0,0 +1,220 @@
+# 最佳实践索引（Best Practices Playbook）
+
+> **本文件是 AI 与团队成员共享的"按场景查手册"**。
+>
+> - 对 AI：**每次进入项目对话时默认读取一次**，用于把用户的自然表达精准映射到推荐流程，减少"靠关键词猜触发"
+> - 对人：当成 Runbook 用，按场景找最佳实践、触发话术、避坑要点
+>
+> 维护策略：场景由实战沉淀，每次踩坑都回写到对应条目；新增 Skill / MCP 工具必须在此登记典型用法。
+
+---
+
+## 0. 通用前置规则（任一场景共用）
+
+| # | 规则 |
+|---|---|
+| 1 | 用户的"自然表达"优先于"关键词命中"。先理解意图再决定是否触发 Skill |
+| 2 | 涉及 **sync 类**（菜单/字典/权限）操作时，**必读** `skills/sync/_mcp-guardrail.md`，调用失败不绕开 MCP，按 guardrail §2 自愈剧本引导用户 |
+| 3 | 每个场景都允许「单步执行」或「流水线执行」两种方式，由用户决定 |
+| 4 | 写文件 / 调写接口 / 修改代码前，输出 Pre-flight 声明并等待用户确认 |
+| 5 | 报告类产物统一写入 `.github/reports/`，**追加不覆盖** |
+
+---
+
+## 1. 场景：新建模块完整闭环（最常用）
+
+> 从原型/详设 → 页面 → 菜单注册 → 字典/权限补齐 → 审计通过
+
+**用户典型话术**：
+- "帮我做一个新模块"
+- "根据原型/详设生成 XX 模块"
+- "我要新建客户管理模块"
+
+**推荐流程**：
+
+```
+prototype-scan
+  → business-doc-extract（资料完整时）
+  → api-contract
+  → page-codegen           ← 产物：src/views/.../{index.vue,data.ts,api.md,SYS_MENU_INFO.md}
+  → menu-sync              ← 推荐工具：wls_menu_sync_from_report
+  → dict-sync（页面用到字典时）
+  → permission-sync（需角色授权 / 动作按钮时）
+  → convention-audit
+```
+
+**关键检查点**：
+- pages.ts 是否注册了新页面（否则路由不存在）
+- `.github/reports/SYS_MENU_INFO.md` 是否包含本次新增页面
+- 同步菜单后端 4004 / 401 → 走 guardrail 引导用户改 env.local.json
+
+---
+
+## 2. 场景：补菜单 / 注册菜单
+
+**用户典型话术**：
+- "帮我创建菜单"
+- "同步菜单"
+- "页面写完了点不进去"
+- "补菜单"
+
+**推荐流程**（默认一步到位）：
+
+```
+wls_menu_sync_from_report  ← MCP 工具，自动读报告 + 查菜单树 + 一二级有序创建
+  └─ 首次先传 dryRun: true 预览，确认无误再正式执行
+```
+
+**前置**：
+- `.github/reports/SYS_MENU_INFO.md` 已生成（由 page-codegen 产出，或手工维护）
+- `env.local.json` 配齐：gatewayPath / token（纯 JWT）/ sysAppNo / menu.parentMenuId / menu.domainId
+
+**典型故障 → 处理**：
+- 工具列表里没有 `wls_menu_sync_from_report` → guardrail §2.2
+- 报错"请填写真实的 domainId" → guardrail §2.3
+- 返回 401 → guardrail §2.4
+- 返回 4004（路径不存在）→ guardrail §2.5
+
+---
+
+## 3. 场景：补字典 / 同步字典
+
+**用户典型话术**：
+- "同步字典"
+- "data.ts 里 logicValue 缺字典"
+- "字典对比 / 字典审计"
+
+**推荐流程**：
+
+```
+1. 用 wls_dict_query 查线上已有
+2. 扫 data.ts 收集所有 logicValue（DICT_CODE）
+3. 差集 = 待新建 → 用户确认
+4. 逐个调 wls_dict_upsert（含 module + items）
+5. 更新 .github/reports/SYS_DICT_INFO.md
+```
+
+**配置依赖**：env.local.json → `dict.moduleId`
+
+---
+
+## 4. 场景：角色授权 / 加动作按钮
+
+**用户典型话术**：
+- "给 XX 角色分配菜单"
+- "给页面挂动作按钮"
+- "注册权限码"
+
+**推荐流程**：
+
+| 子场景 | MCP 工具序列 |
+|---|---|
+| 创建角色 | `wls_role_query`（查重）→ `wls_role_upsert` |
+| 角色授权 | `wls_role_query` → `wls_assignable_menus_query` → `wls_role_assign_menus`（⚠️ **全量覆盖**，AI 需自动合并旧 menuIds + 新增）|
+| 挂动作 | `wls_menu_query` 找页面 id → `wls_action_query` 查重 → `wls_action_upsert` 批量新增 → 修改 `data.ts` 给按钮加 `permission: [xxx]` 字段 |
+
+**避坑**：
+- 角色分配是**全量覆盖**，传 `[A,B]` 会把原有 C 移除，必须先查再合并
+- 权限码命名遵循项目既有风格（`资源_动作` 或 `模块:资源:动作`）
+
+---
+
+## 5. 场景：存量项目体检 / 接手新项目
+
+**用户典型话术**：
+- "接手新项目"
+- "项目体检"
+- "规范审计"
+
+**推荐流程**：
+
+```
+wls_code_scan          ← 概览：页面目录、API_CONFIG、文件完整性
+  → convention-audit   ← 13 条规范全量扫描，产出 AUDIT_*.md
+  → code-fix（可选）   ← 自动修复可整改项
+```
+
+---
+
+## 6. 场景：仅 mock 跑通 / 后端没好先能跑
+
+**用户典型话术**："先 mock 一下"、"假数据"、"后端没好先能跑"
+
+**推荐**：`page-codegen` 的 mock-first 规则，生成假数据 + 注释好真实接口对接位置。
+
+---
+
+## 7. 场景：模板沉淀
+
+**用户典型话术**："这页面成熟了，沉淀成模板"
+
+**推荐**：`template-extract` Skill → 产出 `templates/domains/**/TPL-*.md` → 下次 `page-codegen` 复用。
+
+---
+
+## 8. 场景：业务文档/字段字典维护
+
+**用户典型话术**：用户提供完整原型/详设/字段或字典资料，意图为业务沉淀
+
+**推荐**：`business-doc-extract`（**语义级触发**，碎片需求默认跳过）
+
+---
+
+## 9. 场景：Git 提交 / 分支管理
+
+**用户典型话术**："提交"、"发布"、"打 tag"
+
+**推荐**：遵循 `standards/08-*.md` Git 规范，使用 `pnpm cz` / `pnpm release:*` 命令。
+
+---
+
+## 10. 索引：Skill / MCP 工具速查
+
+### Skills（详见 `_registry.md`）
+
+| Skill | 一句话 |
+|---|---|
+| prototype-scan | 原型/详设 → 页面清单 |
+| business-doc-extract | 模块级资料 → 业务文档沉淀 |
+| api-contract | 生成 `api.md` 接口约定 |
+| page-codegen | 生成 Vue 页面三件套 + api.md + SYS_MENU_INFO.md |
+| convention-audit | 13 条规范审计 |
+| code-fix | 按审计报告自动修复 |
+| menu-sync | 后端菜单同步（MCP）|
+| dict-sync | 后端字典同步（MCP）|
+| permission-sync | 角色 / 授权 / 动作（MCP）|
+| template-extract | 成熟页面沉淀为模板 |
+
+### MCP 工具（详见 `mcp/registry.js`）
+
+| 工具 | 用途 |
+|---|---|
+| `wls_menu_query` / `wls_menu_upsert` / `wls_menu_sync_from_report` | 菜单 |
+| `wls_dict_query` / `wls_dict_upsert` | 字典 |
+| `wls_role_query` / `wls_role_upsert` / `wls_assignable_menus_query` / `wls_role_assign_menus` / `wls_action_query` / `wls_action_upsert` | 角色 / 授权 / 动作 |
+| `wls_code_scan` / `wls_validate_page` / `wls_doctor_ui` / `wls_route_check` / `wls_git_log_extract` / `wls_audit_report_push` | 辅助 |
+
+---
+
+## 11. 如何扩展本文件
+
+新增场景请按此模板：
+
+```markdown
+## N. 场景：{一句话描述}
+
+**用户典型话术**：
+- "..."
+
+**推荐流程**：
+- 用什么 Skill / MCP 工具
+- 关键顺序
+- 配置依赖
+
+**避坑**：
+- ...
+```
+
+---
+
+> ✅ AI 在每轮对话开始时（首次进入项目或长时间未刷新上下文时），优先 `read_file` 加载本文件 + `_registry.md` + `_pipeline.md`，三者联合作为路由依据。

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

@@ -39,30 +39,34 @@ skills/
 
 ## 启用 Skill 路由表
 
-| Skill 名         | 状态    | 路径                                    | 触发关键词                                                                                                                              |
-| ---------------- | ------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| prototype-scan   | ✅ 启用 | `skills/core/prototype-scan/SKILL.md`   | 扫描原型 / 解析原型 / 页面清单 / 详设文档 / 口述需求 / 建个页面 / 写个页面 / 根据截图 / 根据原型                                        |
-| api-contract     | ✅ 启用 | `skills/core/api-contract/SKILL.md`     | 接口约定 / api.md / 字段定义 / 前后端对齐 / 接口设计                                                                                    |
-| page-codegen     | ✅ 启用 | `skills/core/page-codegen/SKILL.md`     | 生成页面 / 创建页面 / 代码生成 / vue页面 / 按原型生成 / 帮我生成 / 列表页 / 管理页 / 台账 / mock / 假数据 / 先能跑 / AGGrid / skills-ui |
-| convention-audit | ✅ 启用 | `skills/core/convention-audit/SKILL.md` | 规范审计 / 代码审计 / 规范检查 / 对齐规范 / 规范偏差 / 接手新项目 / 存量代码分析 / 项目体检                                             |
-| business-doc-extract | ✅ 启用 | `skills/core/business-doc-extract/SKILL.md` | **语义级触发，不依赖固定关键词**：用户提供原型 / 详设 / 字段或字典资料 / 现有页面 + api.md，且意图为业务梳理 / 模块沉淀 / 字段字典维护 / 待确认事项整理时触发；碎片化问答、单截图、小修小改默认不触发 |
-| 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  | ✅ 启用 | `skills/sync/permission-sync/SKILL.md`  | 创建角色 / 角色管理 / 角色授权 / 给角色分配菜单 / 挂动作 / 添加动作按钮 / 同步权限 / 权限码注册                                         |
-| code-fix         | ✅ 启用 | `skills/ops/code-fix/SKILL.md`          | 自动修复 / 整改偏差 / 修复报告 / 规范整改 / 修复偏差 / code fix                                                                         |
+| Skill 名         | 状态    | 路径                                    | MCP 工具依赖                                                                                                              | 触发关键词                                                                                                                              |
+| ---------------- | ------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| prototype-scan   | ✅ 启用 | `skills/core/prototype-scan/SKILL.md`   | —                                                                                                                          | 扫描原型 / 解析原型 / 页面清单 / 详设文档 / 口述需求 / 建个页面 / 写个页面 / 根据截图 / 根据原型                                        |
+| api-contract     | ✅ 启用 | `skills/core/api-contract/SKILL.md`     | —                                                                                                                          | 接口约定 / api.md / 字段定义 / 前后端对齐 / 接口设计                                                                                    |
+| page-codegen     | ✅ 启用 | `skills/core/page-codegen/SKILL.md`     | `wls_validate_page` / `wls_doctor_ui`                                                                                      | 生成页面 / 创建页面 / 代码生成 / vue页面 / 按原型生成 / 帮我生成 / 列表页 / 管理页 / 台账 / mock / 假数据 / 先能跑 / AGGrid / skills-ui |
+| convention-audit | ✅ 启用 | `skills/core/convention-audit/SKILL.md` | `wls_code_scan` / `wls_audit_report_push`                                                                                  | 规范审计 / 代码审计 / 规范检查 / 对齐规范 / 规范偏差 / 接手新项目 / 存量代码分析 / 项目体检                                             |
+| business-doc-extract | ✅ 启用 | `skills/core/business-doc-extract/SKILL.md` | —                                                                                                                          | **语义级触发，不依赖固定关键词**：用户提供原型 / 详设 / 字段或字典资料 / 现有页面 + api.md，且意图为业务梳理 / 模块沉淀 / 字段字典维护 / 待确认事项整理时触发；碎片化问答、单截图、小修小改默认不触发 |
+| template-extract | ✅ 启用 | `skills/core/template-extract/SKILL.md` | —                                                                                                                          | 提取模板 / 抽取模板 / 沉淀模板 / 模板贡献                                                                                               |
+| menu-sync        | ✅ 启用 | `skills/sync/menu-sync/SKILL.md`        | `wls_menu_sync_from_report` / `wls_menu_query` / `wls_menu_upsert`                                                         | 创建菜单 / 注册菜单 / 同步菜单 / 补菜单 / 页面点击进不来 / 菜单打不开                                                                   |
+| dict-sync        | ✅ 启用 | `skills/sync/dict-sync/SKILL.md`        | `wls_dict_query` / `wls_dict_upsert`                                                                                       | 同步字典 / 创建字典 / 刷新字典基线 / 字典对比 / 字典审计                                                                                |
+| permission-sync  | ✅ 启用 | `skills/sync/permission-sync/SKILL.md`  | `wls_role_query` / `wls_role_upsert` / `wls_assignable_menus_query` / `wls_role_assign_menus` / `wls_action_query` / `wls_action_upsert` | 创建角色 / 角色管理 / 角色授权 / 给角色分配菜单 / 挂动作 / 添加动作按钮 / 同步权限 / 权限码注册                                         |
+| code-fix         | ✅ 启用 | `skills/ops/code-fix/SKILL.md`          | —                                                                                                                          | 自动修复 / 整改偏差 / 修复报告 / 规范整改 / 修复偏差 / code fix                                                                         |
+
+> **MCP 工具依赖说明**：sync 类 Skill 必须通过列出的 MCP 工具执行。工具不可用或返回错误时，遵循 `skills/sync/_mcp-guardrail.md` §2 自愈剧本（引导用户完善 `env.local.json` 后重试），**不允许** AI 用 curl/PowerShell/fetch 等绕开 MCP。
 
 ---
 
 ## 调度规则
 
-1. AI 收到用户消息 → 匹配上表 `触发关键词` → `read_file` 加载 `路径` 列对应的 SKILL.md
-2. SKILL.md 中标注的 `必读 standards` 按 `standards/index.md` 任务类型映射加载
-3. 如用户表达连续交付/智能体/全流程意图，同时读取 `_pipeline.md` 获取 Skill I/O 与 `next_suggest`
-4. 在 SKILL.md 指示下输出 **Pre-flight 声明**（强制约定式输出）
-5. 页面生成任务必须额外读取 `standards/12-base-table.md`，并执行 `BaseTable + render-type="agGrid" + cid + defineColumns + renderOps` 硬约束
-6. 若消息包含“风格 / skills-ui / 状态标签 / 操作列 / AGGrid”，同时建议运行 `wl-skills doctor-ui`
-7. `business-doc-extract` 不依赖关键词匹配，AI 必须按 `资料源 + 意图 + 范围` 三因素自行判断；缺资料时先询问用户提供原型/详设/字段资料路径，不要凭推断写入 `docs/business`
+1. **首先加载** `_best-practices.md`（场景索引，语义级路由依据），结合用户意图判断属于哪个场景
+2. 按场景指向的 Skill，`read_file` 加载对应 SKILL.md
+3. SKILL.md 中标注的 `必读 standards` 按 `standards/index.md` 任务类型映射加载
+4. sync 类（菜单/字典/权限）任务必须额外加载 `skills/sync/_mcp-guardrail.md`
+5. 如用户表达连续交付/智能体/全流程意图，同时读取 `_pipeline.md` 获取 Skill I/O 与 `next_suggest`
+6. 在 SKILL.md 指示下输出 **Pre-flight 声明**（强制约定式输出）
+7. 页面生成任务必须额外读取 `standards/12-base-table.md`，并执行 `BaseTable + render-type="agGrid" + cid + defineColumns + renderOps` 硬约束
+8. 若消息包含"风格 / skills-ui / 状态标签 / 操作列 / AGGrid"，同时建议运行 `wl-skills doctor-ui`
+9. `business-doc-extract` 不依赖关键词匹配，AI 必须按 `资料源 + 意图 + 范围` 三因素自行判断；缺资料时先询问用户提供原型/详设/字段资料路径，不要凭推断写入 `docs/business`
 
 ---
 

package/files/.github/skills/sync/_mcp-guardrail.md

@@ -0,0 +1,109 @@
+# Sync Skill 通用护栏（MCP 调用纪律 + 自愈闭环）
+
+> 所有 sync 类 Skill（menu-sync / dict-sync / permission-sync）共用本规则。
+> SKILL.md 顶部需引用本文件，确保 AI 行为一致。
+
+---
+
+## 1. 调用纪律（AI 必读）
+
+- ✅ **首选**：通过本 Skill 在「MCP 工具调用规范」中列出的工具调用（`wls_*`）
+- ❌ **严禁**：使用 `curl` / `Invoke-RestMethod` / `Invoke-WebRequest` / `fetch` / `axios` / `Send-WebRequest` 等任何 shell 命令或代码直接发起 HTTP 请求
+- ❌ **严禁**：自行推测、拼接、或从历史对话沿用接口路径
+- ❌ **严禁**：在 SKILL.md 中看到 `POST /system/xxx/save` 字样后据此手动调用——HTTP 路径仅为 MCP **内部实现说明**
+
+---
+
+## 2. 自愈闭环（MCP 异常时 AI 该怎么做）
+
+> 不是"立即停止"，而是"按层级引导用户完善配置，让它能跑通"。原则：**优先帮用户闭环，最后才放弃**。
+
+### 2.1 错误分层判定
+
+AI 调用 MCP 工具后，按返回内容判定属于哪一类，并按对应剧本处理：
+
+| 错误特征 | 归类 | 处理剧本 |
+|---|---|---|
+| 工具不在 `tools/list` 中（编辑器根本没识别到 wls_*）| L0 MCP 未连接 | 走 §2.2 |
+| 工具返回"❌ 配置加载失败"/"配置文件不存在"/"请填写真实的 xxx" | L1 配置缺失 | 走 §2.3 |
+| 工具返回 `code === 401` 或包含 "token"/"鉴权"/"未登录" 字样 | L2 Token 失效 | 走 §2.4 |
+| 工具返回 `code === 4004` / "url:GET; ..." / 接口不存在 | L3 接口路径不匹配 | 走 §2.5 |
+| 工具返回业务错误（参数错误、唯一键冲突等） | L4 业务层 | 按工具返回的提示给用户看，不需要 fallback |
+
+### 2.2 L0 — MCP 未连接
+
+引导（不要默认放弃）：
+
+```
+🔧 当前编辑器似乎未识别到 wls_* 工具，请按顺序检查：
+1. 编辑器的 MCP 配置文件存在吗？（Cursor/Kiro/Trae: 见各自 mcp.json）
+2. 配置里 WL_PROJECT_ROOT 指向当前项目根了吗？
+3. 重启编辑器后再看 MCP 面板的工具列表
+
+请告诉我以上哪一步通不过，我帮你定位。
+```
+
+仅在用户明确表示**无法启用 MCP** 时，才退化为「手工去后台维护」的人肉方案，且**不再尝试**让 AI 拼 HTTP。
+
+### 2.3 L1 — 配置缺失 / 占位值未替换
+
+如果工具返回类似：
+- `请在 env.local.json 中填写真实的 gatewayPath（当前为占位值）`
+- `请在 .github/skills/sync/env.local.json 填写 menu.domainId`
+- `配置文件不存在: .../env.local.json`
+
+AI **立即转入引导模式**：
+
+1. `read_file` 加载 `.github/skills/sync/menu-sync/env/guide.md`（统一配置说明）
+2. 告诉用户具体哪个字段缺失、获取方式（如 token 抓包、domainId Network 查询）
+3. 等待用户填好 `env.local.json` 后**自动重试同一个 MCP 工具调用**
+4. 直到配置完整、调用成功为止 → 完成闭环
+
+### 2.4 L2 — Token 失效
+
+```
+🔑 Token 似乎已过期。请：
+1. 浏览器登录系统
+2. F12 → Network → 任意接口 → 复制 authorization 头的值
+3. 去掉开头的 `bearer ` 前缀，把纯 JWT 部分粘到 env.local.json 的 token 字段
+4. 告诉我"token 已更新"，我会重新尝试同步
+```
+
+更新后**自动重跑**之前失败的 MCP 调用。
+
+### 2.5 L3 — 接口路径不匹配（如 4004）
+
+后端环境差异可能导致内置接口路径与实际不符。AI 应：
+
+1. 提示用户："当前 MCP 内置的接口路径在你的后端未注册（返回 4004）。可能是该环境网关前缀不同。"
+2. 引导用户：
+   - 检查 `env.local.json.gatewayPath` 是否需要补一段前缀（如 `/uac`）
+   - 或者联系后端确认该 sync 工具对应的真实路径
+3. **不要**让 AI 自行去猜路径再 curl，否则就是绕开 MCP 的回旋
+4. 路径前缀这类配置类问题可以由用户更新后**重试 MCP 工具**完成闭环
+
+> 长期方案：将变化的接口前缀做成 `env.local.json` 中的可配置项，由 kit 维护者在 mcp/api/*.js 中支持读取覆盖。该改动属于 MCP 内部实现，AI 不需要也不应该自行 patch。
+
+### 2.6 L4 — 业务错误
+
+工具返回的业务层提示（如 "menuName 已存在"、"参数缺失"）属正常反馈，AI 直接展示给用户即可，不需要 fallback。
+
+---
+
+## 3. Pre-flight 自检模板（执行前必须输出）
+
+```
+🚀 已触发技能 {skill-name}/SKILL.md → {一句话用途}
+✅ MCP 工具检查：{要用到的 wls_* 全部列出，✓/✗}
+✅ 已读取 .github/skills/sync/env.local.json → gatewayPath/token/sysAppNo/{其他必填}
+✅ 已读取 {本 Skill 的 SYS_*_INFO.md 基线}
+✅ 操作模式：{pull / push / audit / ...}
+```
+
+任一项 ✗ → 进入 §2 自愈剧本，**不要直接放弃**。
+
+---
+
+## 4. 一句话总则
+
+> **MCP 是默认通路，配置是参数化的；调不通时帮用户改配置，而不是绕开 MCP 自己拼 HTTP。**