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

package/files/.github/guides/mcp-setup.md

@@ -0,0 +1,109 @@
+# MCP Server 配置指南
+
+`wl-skills init` 已自动为以下编辑器生成项目级 MCP 配置：
+
+| 编辑器 | 自动生成的配置文件 |
+| ---- | --------------- |
+| Cursor | `.cursor/mcp.json` |
+| Claude Code | `.mcp.json` |
+| VS Code / GitHub Copilot | `.vscode/mcp.json` |
+| Kiro | `.kiro/settings/mcp.json` |
+
+以下编辑器仅支持全局配置，需手动添加一次（添加后对所有项目生效，无需重复操作）：
+
+---
+
+## Windsurf
+
+编辑全局文件 `~/.codeium/windsurf/mcp_config.json`，在 `mcpServers` 中追加：
+
+```json
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["/你的项目绝对路径/node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}
+```
+
+> 提示：Windsurf 不支持 `${workspaceFolder}` 变量，需填写绝对路径；或使用相对路径 `node_modules/...`（Windsurf 会从工作区根目录解析）。
+
+---
+
+## Cline（VS Code 插件）
+
+打开 VS Code 设置（`Ctrl+,`），搜索 `cline mcpServers`，或直接编辑 `settings.json` 追加：
+
+```json
+{
+  "cline.mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["${workspaceFolder}/node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}
+```
+
+也可通过 Cline 侧边栏 → **MCP Servers** → **Edit Config** 进行图形化配置。
+
+---
+
+## Trae IDE
+
+1. 打开 **Trae 设置**（`Ctrl+Shift+,`）→ **MCP**
+2. 点击 **+** 新增服务器
+3. 在弹出的 JSON 中填入：
+
+```json
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}
+```
+
+4. 保存后重启 Trae，MCP 工具即可使用。
+
+---
+
+## Qoder IDE
+
+1. 打开 **Qoder 设置**（`Ctrl+Shift+,`）→ **MCP**
+2. 切换到 **我的服务器** 标签 → 点击右上角 **+** 新增
+3. 在弹出的 JSON 中填入：
+
+```json
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}
+```
+
+4. 关闭并保存，链接图标变绿表示连接成功。
+
+---
+
+## 配置完成后
+
+确保已在 `.github/skills/sync/env.local.json` 中填写：
+
+```json
+{
+  "gatewayPath": "https://你的网关域名/api",
+  "token": "Bearer 你的Token",
+  "menu": { "domainId": 1 },
+  "dict": {}
+}
+```
+
+配置完成后重启编辑器，对 AI 说「扩展菜单」或「加字典」，AI 会自动调用 MCP 工具完成同步。

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

@@ -1,176 +1,184 @@
-# wl-skills-kit 使用指南
-
-> **目标读者**：使用 `@agile-team/wl-skills-kit` 的 Vue 3 业务项目团队成员。
-> **适用版本**：v2.0+
-> **维护者**：CHENY（工号 409322）
-
----
-
-## 5 分钟上手
-
-### 第 1 步：安装工具链
-
-```bash
-# 进入你的 Vue 3 项目根目录
-cd your-vue3-project
-
-# 安装工程化规范（强制前置）
-npx @robot-admin/git-standards init
-
-# 安装 AI Skill 体系
-npx @agile-team/wl-skills-kit
-```
-
-### 第 2 步：确认编辑器
-
-推荐使用以下任一 AI 编辑器：
-
-- VS Code + GitHub Copilot
-- Cursor
-- Windsurf
-- Claude Code
-
-打开项目后，AI 会自动加载 `.github/copilot-instructions.md`，你不用做任何配置。
-
-### 第 3 步：开始使用
-
-在 AI 对话中直接说出需求即可：
-
-```
-"帮我生成一个客户管理列表页"
-"扫描这份原型 HTML"
-"审计 src/views/sale 这个目录的代码规范"
-"提取 mmwr-rolling-management 这个页面作为模板"
-"同步菜单到后端"
-```
-
-AI 会自动识别意图，触发对应的 Skill。
-
----
-
-## 8 个 Skill 速览
-
-| Skill              | 触发关键词                     | 用途                         |
-| ------------------ | ------------------------------ | ---------------------------- |
-| `prototype-scan`   | 扫描原型 / 解析原型 / 口述需求 | 原型 / 详设 → page-spec JSON |
-| `api-contract`     | 接口约定 / api.md / 字段定义   | 生成接口约定文档             |
-| `page-codegen`     | 生成页面 / 帮我生成            | 生成 4 文件 + 菜单注册       |
-| `menu-sync`        | 创建菜单 / 同步菜单            | 菜单数据同步到后端（MCP 自动 / prompt 手动两种模式） |
-| `dict-sync`        | 同步字典 / 创建字典 / 字典审计   | 字典基线同步到后端（MCP 自动 / prompt 手动两种模式） |
-| `convention-audit` | 规范审计 / 代码审计            | 13 条规范扫描 + 偏差报告     |
-| `template-extract` | 提取模板 / 抄取模板            | 从现有页面沉淠领域专属模板   |
-| `code-fix`         | 自动修复 / 整改偏差 / 规范整改   | 受控自动修复审计报告中的偏差 |
-
-完整调度规则见 `.github/skills/_registry.md`。
-
----
-
-## 项目目录结构
-
-安装后业务项目得到的关键目录：
-
-```
-你的项目/
-├── .github/
-│   ├── copilot-instructions.md      AI 主入口
-│   ├── standards/                   13 条模块化规范
-│   ├── skills/                      8 个 Skill + 1 个 PLANNED 草稿
-│   ├── guides/                      使用指南 + 架构设计
-│   └── reports/                     AI 生成报告（SYS_MENU_INFO 等）
-├── docs/                            12 个组件 API 文档（jh-* / request 等）
-├── demo/                            13 个领域样例（生产 + 销售）
-└── src/
-    ├── components/                  全局/局部/远程组件
-    └── types/
-```
-
----
-
-## 完整流水线（从原型到上线）
-
-```
-1. 原型/详设 → prototype-scan          → page-spec JSON
-2. page-spec → api-contract            → api.md
-3. api.md    → page-codegen            → 4 文件 + reports/SYS_MENU_INFO.md
-4. SYS_MENU_INFO → menu-sync           → 后端菜单表
-5. 代码完成  → dict-sync               → 字典基线同步到后端字典表
-6. 完成      → convention-audit        → 偏差报告（reports/规范审查报告.md）
-7. 报告      → code-fix                → 受控自动修复 🟡/🟢 偏差，逐条 diff 确认
-8. 沉淀      → template-extract        → 从标杆页面提取领域专属模板
-```
-
-> **说明**：每一步都可以单独触发，也可以按用户意图自动接续。
-> - `dict-sync`：首次使用先跑 **pull 模式**（「刷新字典基线」）建立本地基线，再跑 push 模式同步差异。
-> - `code-fix`：只修复 🟡/🟢 偏差；🔴 严重偏差必须人工或 page-codegen 处理。每条修复前强制 diff 预览确认。
-
----
-
-## 常见问题
-
-**Q: AI 生成的代码不符合规范怎么办？**
-A: 触发 `convention-audit`，输出偏差报告到 `reports/规范审查报告.md`，按 🔴 严重 → 🟡 轻微的优先级修复。
-
-**Q: 工具链检测一直失败？**
-A: 检查 `.prettierrc.js` / `eslint.config.ts` / `.husky/` 是否齐全。重新执行 `npx @robot-admin/git-standards init`，或联系 CHENY（工号 409322）。
-
-**Q: 本团队有特殊的页面模式，通用模板不适用？**
-A: 触发 `template-extract`，从现有标杆页面提取为领域专属模板，沉淀到 `templates/domains/{你的领域}/`。
-
-**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/`。
-
----
-
-## 升级与维护
-
-### 增量更新
-
-```bash
-npx @agile-team/wl-skills-kit@latest update
-# 仅覆盖有变化的文件，未变文件不动
-```
-
-### 预览模式
-
-任何命令都可加 `--dry-run` 预览变更：
-
-```bash
-npx @agile-team/wl-skills-kit update --dry-run
-npx @agile-team/wl-skills-kit clean --dry-run
-```
-
----
-
-## Pre-flight 声明阅读指南
-
-每次 AI 触发 Skill 时会输出"Pre-flight 声明"，告诉你它读取了哪些文件、做了哪些前置检查：
-
-```
-🚀 已触发技能 page-codegen/SKILL.md   → 页面代码生成
-✅ 已读取 standards/13-platform-components.md → 平台组件对照表
-✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓
-✅ cid 已生成：cl-745831
-```
-
-如果 AI 没输出此声明，说明它跳过了前置检查，**请提示它"补 Pre-flight 声明"**，或重新触发。
-
----
-
-## 反馈与贡献
-
-- 使用问题 / Bug：联系 CHENY（工号 409322）
-- 模板贡献：使用 `template-extract` Skill 自动提取并 PR
-- 规范修改：在 `standards/` 编辑后，团队评审通过后合入
-
----
-
-## 进一步阅读
-
-- 架构与决策记录：[architecture.md](architecture.md)
-- 编辑器适配说明：`.github/skills/_compat/README.md`
+# wl-skills-kit 使用指南
+
+> **目标读者**：使用 `@agile-team/wl-skills-kit` 的 Vue 3 业务项目团队成员。
+> **适用版本**：v2.0+
+> **维护者**：CHENY（工号 409322）
+
+---
+
+## 5 分钟上手
+
+### 第 1 步：安装工具链
+
+```bash
+# 进入你的 Vue 3 项目根目录
+cd your-vue3-project
+
+# 安装工程化规范（强制前置）
+npx @robot-admin/git-standards init
+
+# 安装 AI Skill 体系
+npx @agile-team/wl-skills-kit
+```
+
+### 第 2 步：确认编辑器
+
+推荐使用以下任一 AI 编辑器：
+
+- VS Code + GitHub Copilot
+- Cursor
+- Windsurf
+- Claude Code
+- Cline
+- Kiro
+- Trae
+- Qoder
+
+打开项目后，AI 会自动加载 `.github/copilot-instructions.md`，你不用做任何配置。
+
+### 第 3 步：开始使用
+
+在 AI 对话中直接说出需求即可：
+
+```
+"帮我生成一个客户管理列表页"
+"扫描这份原型 HTML"
+"审计 src/views/sale 这个目录的代码规范"
+"提取 mmwr-rolling-management 这个页面作为模板"
+"同步菜单到后端"
+```
+
+AI 会自动识别意图，触发对应的 Skill。
+
+---
+
+## 8 个 Skill 速览
+
+| Skill              | 触发关键词                     | 用途                         |
+| ------------------ | ------------------------------ | ---------------------------- |
+| `prototype-scan`   | 扫描原型 / 解析原型 / 口述需求 | 原型 / 详设 → page-spec JSON |
+| `api-contract`     | 接口约定 / api.md / 字段定义   | 生成接口约定文档             |
+| `page-codegen`     | 生成页面 / 帮我生成            | 生成 4 文件 + 菜单注册       |
+| `menu-sync`        | 创建菜单 / 同步菜单            | 菜单数据同步到后端（MCP 自动 / prompt 手动两种模式） |
+| `dict-sync`        | 同步字典 / 创建字典 / 字典审计   | 字典基线同步到后端（MCP 自动 / prompt 手动两种模式） |
+| `convention-audit` | 规范审计 / 代码审计            | 13 条规范扫描 + 偏差报告     |
+| `template-extract` | 提取模板 / 抄取模板            | 从现有页面沉淠领域专属模板   |
+| `code-fix`         | 自动修复 / 整改偏差 / 规范整改   | 受控自动修复审计报告中的偏差 |
+
+完整调度规则见 `.github/skills/_registry.md`。
+
+---
+
+## 项目目录结构
+
+安装后业务项目得到的关键目录：
+
+```
+你的项目/
+├── .github/
+│   ├── copilot-instructions.md      AI 主入口
+│   ├── standards/                   13 条模块化规范
+│   ├── skills/                      8 个 Skill + 1 个 PLANNED 草稿
+│   ├── guides/                      使用指南 + 架构设计
+│   └── reports/                     AI 生成报告（SYS_MENU_INFO 等）
+├── docs/                            12 个组件 API 文档（jh-* / request 等）
+├── demo/                            13 个领域样例（生产 + 销售）
+└── src/
+    ├── components/                  全局/局部/远程组件
+    └── types/
+```
+
+---
+
+## 完整流水线（从原型到上线）
+
+```
+1. 原型/详设 → prototype-scan          → page-spec JSON
+2. page-spec → api-contract            → api.md
+3. api.md    → page-codegen            → 4 文件 + reports/SYS_MENU_INFO.md
+4. SYS_MENU_INFO → menu-sync           → 后端菜单表
+5. 代码完成  → dict-sync               → 字典基线同步到后端字典表
+6. 完成      → convention-audit        → 偏差报告（reports/规范审查报告.md）
+7. 报告      → code-fix                → 受控自动修复 🟡/🟢 偏差，逐条 diff 确认
+8. 沉淀      → template-extract        → 从标杆页面提取领域专属模板
+```
+
+> **说明**：每一步都可以单独触发，也可以按用户意图自动接续。
+> - `dict-sync`：首次使用先跑 **pull 模式**（「刷新字典基线」）建立本地基线，再跑 push 模式同步差异。
+> - `code-fix`：只修复 🟡/🟢 偏差；🔴 严重偏差必须人工或 page-codegen 处理。每条修复前强制 diff 预览确认。
+
+---
+
+## 常见问题
+
+**Q: AI 生成的代码不符合规范怎么办？**
+A: 触发 `convention-audit`，输出偏差报告到 `reports/规范审查报告.md`，按 🔴 严重 → 🟡 轻微的优先级修复。
+
+**Q: 工具链检测一直失败？**
+A: 检查 `.prettierrc.js` / `eslint.config.ts` / `.husky/` 是否齐全。重新执行 `npx @robot-admin/git-standards init`，或联系 CHENY（工号 409322）。
+
+**Q: 本团队有特殊的页面模式，通用模板不适用？**
+A: 触发 `template-extract`，从现有标杆页面提取为领域专属模板，沉淀到 `templates/domains/{你的领域}/`。
+
+**Q: 多个 AI 编辑器之间会冲突吗？**
+A: 不会。`bin/wl-skills.js` 已自动生成 9 种主流 AI 编辑器配置文件（含 Qoder），所有内容来自同一份 `copilot-instructions.md`，保持一致。
+
+**Q: MCP Server 是什么？需要额外配置吗？**
+A: `wl-skills init` 会自动为 **Cursor**（`.cursor/mcp.json`）、**Claude Code**（`.mcp.json`）、**VS Code / GitHub Copilot**（`.vscode/mcp.json`）、**Kiro**（`.kiro/settings/mcp.json`）生成项目级 MCP 配置文件。
+
+Windsurf、Cline、Trae、Qoder 仅支持全局配置，需手动操作一次，详见 `.github/guides/mcp-setup.md`。
+
+配置完成后在 `.github/skills/sync/env.local.json` 中填好 `token`、`gatewayPath`、`menu.domainId`，重启编辑器，对 AI 说「扩展菜单」或「加字典」，AI 会自动调用 MCP 工具完成同步，无需手动粘贴接口响应。
+
+**Q: 部署到生产环境前如何清理 AI 文件？**
+A: 执行 `npx @agile-team/wl-skills-kit clean`。会移除所有 AI 辅助文件，保留 `src/components/` 和 `src/types/`。
+
+---
+
+## 升级与维护
+
+### 增量更新
+
+```bash
+npx @agile-team/wl-skills-kit@latest update
+# 仅覆盖有变化的文件，未变文件不动
+```
+
+### 预览模式
+
+任何命令都可加 `--dry-run` 预览变更：
+
+```bash
+npx @agile-team/wl-skills-kit update --dry-run
+npx @agile-team/wl-skills-kit clean --dry-run
+```
+
+---
+
+## Pre-flight 声明阅读指南
+
+每次 AI 触发 Skill 时会输出"Pre-flight 声明"，告诉你它读取了哪些文件、做了哪些前置检查：
+
+```
+🚀 已触发技能 page-codegen/SKILL.md   → 页面代码生成
+✅ 已读取 standards/13-platform-components.md → 平台组件对照表
+✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓
+✅ cid 已生成：cl-745831
+```
+
+如果 AI 没输出此声明，说明它跳过了前置检查，**请提示它"补 Pre-flight 声明"**，或重新触发。
+
+---
+
+## 反馈与贡献
+
+- 使用问题 / Bug：联系 CHENY（工号 409322）
+- 模板贡献：使用 `template-extract` Skill 自动提取并 PR
+- 规范修改：在 `standards/` 编辑后，团队评审通过后合入
+
+---
+
+## 进一步阅读
+
+- 架构与决策记录：[architecture.md](architecture.md)
+- 编辑器适配说明：`.github/skills/_compat/README.md`

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

@@ -1,65 +1,65 @@
-# Reports 目录
-
-本目录存放 AI 生成的报告类文件。**所有写入均为追加模式，不覆盖历史。**
-
----
-
-## 文件分类
-
-### A. 系统数据文件
-
-由生成类 Skill 写入，由同步类 Skill 读取。
-
-| 文件                               | 写入方             | 读取方          | 说明                   |
-| ---------------------------------- | ------------------ | --------------- | ---------------------- |
-| `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 | 权限数据汇总           |
-
-**写入规则**：每条数据带生成时间戳；新条目追加到末尾；不删除历史。
-
-### B. 审计偏差报告
-
-| 文件              | 写入方           | 读取方                 | 说明                    |
-| ----------------- | ---------------- | ---------------------- | ----------------------- |
-| `规范审查报告.md` | convention-audit | 人工 review → code-fix | 不合规项清单 + 整改建议 |
-
-**写入规则**：每次审计追加**新章节在顶部**（最新在最上），时间戳分节，历史自然下沉。
-
-### C. 提取建议报告
-
-| 文件              | 写入方           | 读取方                         | 说明                         |
-| ----------------- | ---------------- | ------------------------------ | ---------------------------- |
-| `组件提取建议.md` | convention-audit | 人工 review → template-extract | 跨页面复用但未封装的模式清单 |
-
-**写入规则**：同 B。
-
----
-
-## 为什么追加不覆盖
-
-1. **历史可追溯**：通过 git diff 可看到团队每次审计的变化趋势
-2. **多次执行幂等**：开发者可重复触发，不丢失数据
-3. **多人并行**：多人协作时不会互相覆盖
-4. **数据闭环**：菜单/字典/权限同步类 Skill 依赖累积数据
-
----
-
-## 安装与升级行为
-
-`bin/wl-skills.js` 对本目录的特殊处理：
-
-| 命令     | 行为                                                             |
-| -------- | ---------------------------------------------------------------- |
-| `init`   | 文件不存在时创建空模板；**已存在则跳过**（避免覆盖团队累积数据） |
-| `update` | 同 `init`：已存在的文件**不覆盖**                                |
-| `clean`  | 默认删除（视为 AI 辅助文件）；可加 `--keep-reports` 保留         |
-
----
-
-## Git 管理建议
-
-- ✅ `SYS_MENU_INFO.md`、`SYS_DICT_INFO.md`、`SYS_PERMISSION_INFO.md` 提交到仓库（团队共享数据）
-- ⚠️ `规范审查报告.md`、`组件提取建议.md` 视团队偏好选择：
-  - 提交：可见整改进度，PR review 时直观
-  - 不提交：避免污染 git 历史，加入 `.gitignore`
+# Reports 目录
+
+本目录存放 AI 生成的报告类文件。**所有写入均为追加模式，不覆盖历史。**
+
+---
+
+## 文件分类
+
+### A. 系统数据文件
+
+由生成类 Skill 写入，由同步类 Skill 读取。
+
+| 文件                               | 写入方             | 读取方          | 说明                   |
+| ---------------------------------- | ------------------ | --------------- | ---------------------- |
+| `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 | 权限数据汇总           |
+
+**写入规则**：每条数据带生成时间戳；新条目追加到末尾；不删除历史。
+
+### B. 审计偏差报告
+
+| 文件              | 写入方           | 读取方                 | 说明                    |
+| ----------------- | ---------------- | ---------------------- | ----------------------- |
+| `规范审查报告.md` | convention-audit | 人工 review → code-fix | 不合规项清单 + 整改建议 |
+
+**写入规则**：每次审计追加**新章节在顶部**（最新在最上），时间戳分节，历史自然下沉。
+
+### C. 提取建议报告
+
+| 文件              | 写入方           | 读取方                         | 说明                         |
+| ----------------- | ---------------- | ------------------------------ | ---------------------------- |
+| `组件提取建议.md` | convention-audit | 人工 review → template-extract | 跨页面复用但未封装的模式清单 |
+
+**写入规则**：同 B。
+
+---
+
+## 为什么追加不覆盖
+
+1. **历史可追溯**：通过 git diff 可看到团队每次审计的变化趋势
+2. **多次执行幂等**：开发者可重复触发，不丢失数据
+3. **多人并行**：多人协作时不会互相覆盖
+4. **数据闭环**：菜单/字典/权限同步类 Skill 依赖累积数据
+
+---
+
+## 安装与升级行为
+
+`bin/wl-skills.js` 对本目录的特殊处理：
+
+| 命令     | 行为                                                             |
+| -------- | ---------------------------------------------------------------- |
+| `init`   | 文件不存在时创建空模板；**已存在则跳过**（避免覆盖团队累积数据） |
+| `update` | 同 `init`：已存在的文件**不覆盖**                                |
+| `clean`  | 默认删除（视为 AI 辅助文件）；可加 `--keep-reports` 保留         |
+
+---
+
+## Git 管理建议
+
+- ✅ `SYS_MENU_INFO.md`、`SYS_DICT_INFO.md`、`SYS_PERMISSION_INFO.md` 提交到仓库（团队共享数据）
+- ⚠️ `规范审查报告.md`、`组件提取建议.md` 视团队偏好选择：
+  - 提交：可见整改进度，PR review 时直观
+  - 不提交：避免污染 git 历史，加入 `.gitignore`