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

package/CHANGELOG.md

@@ -1,36 +1,28 @@
 # Changelog
 
-## [2.3.3] - 2026-04-28
+## [2.3.4] - 2026-04-28
 
-### 📝 README 大幅重写 + Skill 状态校正
+### 🔌 全编辑器 MCP 支持 + Qoder 新增
 
-#### README 新增核心章节
-- **文档地图 & 架构导读**：按角色（设计师/业务分析师/后端/前端/维护者）列出各自入口；各目录职责一览；“读哪个 README”导航表
-- **设计理念**：三层分工结构（SKILL.md 语义层 / MCP tools 执行层 / HTTP API 数据层）
-- **当前能力全景**：完整的从输入到输出的流程图，包括 MCP 工具层在链路中的位置
-- **Roadmap**：按优先级列出 permission-sync 等待做事项
-- **未来设想**：完整自动化链路展望
+#### MCP 配置自动生成（补全实现）
+- `wl-skills init` 现在自动生成 4 个项目级 MCP 配置文件：
+  - `.cursor/mcp.json` — Cursor
+  - `.mcp.json` — Claude Code（project scope，随 VCS 共享）
+  - `.vscode/mcp.json` — VS Code / GitHub Copilot（使用 `"servers"` 键，符合 VS Code MCP 规范）
+  - `.kiro/settings/mcp.json` — Kiro（AWS）
+- 修复 `usage.md` 中错误的配置路径描述（原来写的 `.claude/settings.json` 实际不存在）
 
-#### Skill 状态校正
-- `dict-sync`：已有完整 SKILL.md，从 ⏳ PLANNED 改为 ✅ 启用
-- `code-fix`：已有完整 SKILL.md，从 ⏳ PLANNED 改为 ✅ 启用
-- `permission-sync`：仍是 SKILL.draft.md，保持 ⏳ PLANNED
-- Skills 总数更新：6 → 8 个已启用，1 个 PLANNED（两处描述同步更新）
+#### 手动配置指南
+- 新增 `.github/guides/mcp-setup.md`：Windsurf / Cline / Trae / Qoder 的手动 MCP 配置步骤
 
----
-
-## [2.3.2] - 2026-04-28
-
-### 📝 输入规范文档体系 + README/目录结构优化
-
-#### 新增 docs/ 输入规范文档（仅仓库可见，不随包分发）
-- **`docs/input-spec-prototype.md`**: 原型输入规范——面向设计师/产品，含合格原型自检清单、按鈕颜色规范、Tab/视角切换标注要求、精度对比表
-- **`docs/input-spec-detailed-design.md`**: 详设文档输入规范——面向业务分析师，含可直接复制的 Markdown 表格模板、字段英文名+字典 code 对精度的量化影响说明
-- **`docs/input-spec-api.md`**: API 契约确认规范——面向后端开发者，含接口 URL 命名规范、api.md 两步确认工作流、常见问题答疑
-- **`docs/input-spec-page-spec.md`**: page-spec JSON 参考手册——面向前端开发者，含每个字段详细注释、自检清单、手写 spec 场景指南
+#### Qoder 编辑器支持（新增第 10 个编辑器）
+- `editors.json` 新增 `qoder` 条目，自动生成 `.qoder/rules/conventions.md`
+- Qoder 同时通过现有 `AGENTS.md` 天然兼容（无需额外操作）
+- 新增 `_compat/headers/qoder.txt` 规则头部
 
-#### 结构和文档优化
-- `README.md`: 版本读数更新为 v2.3，仓库结构图补充 `docs/` 目录说明，“进一步阅读”章节补充输入规范入口
+#### 文档更新
+- `usage.md` 推荐编辑器列表补全（Cline / Kiro / Trae / Qoder）
+- `usage.md` 编辑器数量 8 → 9
 
 ---
 

package/README.md

@@ -1,8 +1,8 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.3** — 一条命令将 13 条编码规范、8 个 AI Skill、MCP 工具层、组件文档、领域样例导入 Vue 3 项目。
+**AI Skill 模板包 v2.3** — 一条命令将 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 / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
 ---
 
@@ -41,135 +41,6 @@ reports/AUDIT_AI_*.md + AUDIT_HUMAN_*.md
 
 ---
 
-## 文档地图 — 谁该读什么
-
-> 这个项目覆盖了多个角色和多层目录，先花 30 秒定位自己，再按需深入。
-
-### 按角色找入口
-
-| 你的身份 | 你要做的事 | 从这里开始 |
-|---|---|---|
-| **业务团队（首次接入）** | 安装、跑通 AI 代码生成流程 | 本文档 → CLI 命令 → 业务项目内 `.github/guides/usage.md` |
-| **设计师 / 产品经理** | 了解如何制作让 AI 精确识别的原型 | [docs/input-spec-prototype.md](docs/input-spec-prototype.md) |
-| **业务分析师** | 了解详设文档需要提供哪些结构化内容 | [docs/input-spec-detailed-design.md](docs/input-spec-detailed-design.md) |
-| **后端开发者** | 了解接口命名/响应格式规范，如何确认 api.md | [docs/input-spec-api.md](docs/input-spec-api.md) |
-| **前端开发者** | 理解 page-spec JSON 结构，手写或校验 | [docs/input-spec-page-spec.md](docs/input-spec-page-spec.md) |
-| **wl-skills-kit 维护者** | 修改规范、Skill、模板、CLI | [kit-internal/README.md](kit-internal/README.md) |
-
-### 各目录职责一览
-
-```
-wl-skills-kit/
-│
-├── files/            ← ★ 打包分发给业务项目的全部内容
-│   ├── .github/         AI 指令体系（规范+Skill+适配层+报告模板）
-│   ├── docs/            随包分发的组件 API 文档（12 个组件）
-│   └── demo/            领域样例代码（供 AI 参考学习）
-│
-├── mcp/              ← ★ MCP Server（随包分发，Cursor 自动注册）
-│                        4 个工具：菜单查询/写入 + 字典查询/写入
-│
-├── bin/              ← CLI 实现（init / update / clean）
-│
-├── docs/             ← 仅本仓库可见（不分发）
-│                        输入规范文档系列（面向团队各角色）
-│
-└── kit-internal/     ← 仅本仓库可见（不分发）
-                         维护者文档（架构 ADR、贡献流程、踩坑记录）
-```
-
-### 读哪个 README
-
-| README 文件 | 内容 | 读者 |
-|---|---|---|
-| 本文件（根 README.md） | 包概述、安装使用、Skill 全景 | 所有人 |
-| `kit-internal/README.md` | 维护者工作空间总览 | 维护者 |
-| `files/.github/guides/usage.md` | 业务项目安装后的完整使用流程 | 业务团队 |
-| `files/.github/guides/architecture.md` | AI 体系架构与设计决策 | 想深入了解的技术同学 |
-| `files/.github/skills/*/USAGE.md` | 每个 Skill 的触发方式和效果说明 | 业务团队按需查阅 |
-| `docs/input-spec-*.md` | 各角色的输入规范最佳实践 | 设计/分析/后端/前端 |
-
----
-
-## 设计理念 & 演进路线
-
-### 核心设计理念
-
-**"一次写好 Skill，人人获益"** — wl-skills-kit 不是项目脚手架，而是一套 **AI 行为规范体系**。
-
-通过将团队的编码规范、业务模式、设计决策编码到 SKILL.md 中，让每一个 AI 编辑器在每一次对话里都能遵守相同的规范——无论是 Copilot、Cursor 还是 Claude Code，无论是老成员还是新同学，AI 的行为都是可预期的、一致的。
-
-**三层分工**：
-
-```
-SKILL.md（语义层）     AI 编辑器理解"该怎么做"
-      │
-      ▼
-MCP tools / CLI（执行层）  跨越 AI 上下文边界，调用真实系统
-      │
-      ▼
-mcp/api/ / 后端 HTTP API  实际的数据读写
-```
-
-- **SKILL.md** — 静态知识，放在 AI 编辑器的上下文里，零运行时开销
-- **MCP 工具** — 当 Skill 需要读写真实系统（菜单树/字典表）时，通过 MCP 调用，跨越 AI 上下文边界
-- **纯查询/生成类 Skill**（如 page-codegen / convention-audit）不需要 MCP，SKILL.md 直接驱动
-
-### 当前能力全景（v2.3）
-
-```
-输入层                  AI 推理层                   输出层
-─────────              ─────────────────────       ─────────────────
-Axure HTML 原型    →   prototype-scan          →   page-spec JSON
-详设 Markdown 表   →   prototype-scan          →   page-spec JSON
-口述需求           →   prototype-scan (推断)   →   page-spec JSON
-                        │
-                        ▼
-                   api-contract            →   api.md（逐页面）
-                        │
-                        ▼
-                   page-codegen            →   data.ts + index.vue
-                   （8 种内置模板）              + index.scss + pages.ts
-                        │
-                        ▼
-                   convention-audit        →   AUDIT_AI.md（AI 自查）
-                                               AUDIT_HUMAN.md（人工检查）
-                        │
-                        ▼
-                   code-fix                →   受控自动整改偏差
-                        │
-                        ▼
-                   menu-sync (MCP)         →   线上菜单注册完毕
-                   dict-sync (MCP)         →   线上字典同步完毕
-                        │
-                        ▼
-                   template-extract        →   领域模板沉淀复用
-```
-
-### 下一步计划（Roadmap）
-
-| 优先级 | 功能 | 状态 |
-|---|---|---|
-| 🔴 高 | `permission-sync` — 页面级/按钮级权限批量注册 | ⏳ SKILL.draft.md 已有设计 |
-| 🟡 中 | `domain/` 领域模板扩展 — 补充 sale / hrms 等领域样例 | ⏳ 规划中 |
-| 🟡 中 | `page-codegen` 支持更多 Template 组件（cx-ui-produce 的配置驱动页面）| ⏳ 持续补充 |
-| 🟢 低 | MCP 增加 permission 工具（`wls_permission_query/upsert`）| ⏳ 依赖 permission-sync Skill |
-| 🟢 低 | `code-fix` 完善 — 覆盖更多自动修复场景 | ⏳ 持续完善 |
-
-### 未来设想
-
-当 permission-sync 完成后，一个新页面从 0 到线上可访问的完整链路将全自动化：
-
-```
-原型 → AI 生成代码 → convention-audit 验收 → menu-sync 注册菜单
-                                             → dict-sync 同步字典
-                                             → permission-sync 注册权限
-                                                     ↓
-                                              UI 可访问，权限可分配
-```
-
----
-
 ## ⚠️ 仓库结构 vs 业务项目安装结构（**必看**）
 
 `wl-skills-kit` 是一个 **npm 模板包**：仓库本身的结构 ≠ 你 `npx` 之后业务项目里看到的结构。两者**严格区分**：
@@ -195,13 +66,6 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   ├── docs/                             组件 API 文档
 │   └── demo/                             领域样例
 │
-├── docs/                                 ★★ 仅仓库可见，不会安装到业务项目 ★★
-│   ├── mcp建议.md                        MCP 进化路线与三层架构建议
-│   ├── input-spec-prototype.md           原型输入规范（面向设计师/产品）
-│   ├── input-spec-detailed-design.md     详设文档输入规范（面向业务分析师）
-│   ├── input-spec-api.md                 API 契约确认规范（面向后端开发者）
-│   └── input-spec-page-spec.md           page-spec JSON 参考手册（面向前端开发者）
-│
 ├── kit-internal/                         ★★ 仅仓库可见，不会安装到业务项目 ★★
 │   ├── README.md                         维护者首页
 │   ├── architecture.md                   架构总览
@@ -330,10 +194,10 @@ npx @agile-team/wl-skills-kit update
 | `page-codegen`     | ✅ 启用    | `skills/core/page-codegen/`              | 4 文件骨架生成 + 模板调度    |
 | `convention-audit` | ✅ 启用    | `skills/core/convention-audit/`          | 13 条规范扫描 + 双报告        |
 | `template-extract` | ✅ 启用    | `skills/core/template-extract/`          | 现有页面 → 领域模板           |
-| `menu-sync`        | ✅ 启用    | `skills/sync/menu-sync/`                 | 菜单基线 ↔ 后端接口（MCP）  |
-| `dict-sync`        | ✅ 启用    | `skills/sync/dict-sync/`                 | 字典基线 ↔ 后端接口（MCP）  |
-| `code-fix`         | ✅ 启用    | `skills/ops/code-fix/`                   | 受控自动修复偏差              |
-| `permission-sync`  | ⏳ PLANNED | `skills/sync/permission-sync/`           | 权限基线 ↔ 后端接口（设计中） |
+| `menu-sync`        | ✅ 启用    | `skills/sync/menu-sync/`                 | 菜单基线 ↔ 后端接口          |
+| `dict-sync`        | ⏳ PLANNED | `skills/sync/dict-sync/`                 | 字典基线 ↔ 后端接口          |
+| `permission-sync`  | ⏳ PLANNED | `skills/sync/permission-sync/`           | 权限基线 ↔ 后端接口          |
+| `code-fix`         | ⏳ PLANNED | `skills/ops/code-fix/`                   | 受控自动修复偏差              |
 
 每个启用 Skill 同目录都有 **`SKILL.md`（AI 触发用）+ `USAGE.md`（团队成员阅读）**。
 
@@ -376,7 +240,6 @@ npx @agile-team/wl-skills-kit update
 - 🔧 维护者文档：[kit-internal/README.md](kit-internal/README.md)（仅本仓库）
 - 🤖 多编辑器适配机制：[files/.github/skills/_compat/README.md](files/.github/skills/_compat/README.md)
 - 🛠️ Jenkins 流水线参考：[kit-internal/jenkins-pipeline.md](kit-internal/jenkins-pipeline.md)
-- 📝 输入规范（如何提供高精度输入）：[docs/](docs/)
 
 ---
 

package/files/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}

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

@@ -29,6 +29,10 @@ npx @agile-team/wl-skills-kit
 - Cursor
 - Windsurf
 - Claude Code
+- Cline
+- Kiro
+- Trae
+- Qoder
 
 打开项目后，AI 会自动加载 `.github/copilot-instructions.md`，你不用做任何配置。
 
@@ -117,10 +121,14 @@ A: 检查 `.prettierrc.js` / `eslint.config.ts` / `.husky/` 是否齐全。重
 A: 触发 `template-extract`，从现有标杆页面提取为领域专属模板，沉淀到 `templates/domains/{你的领域}/`。
 
 **Q: 多个 AI 编辑器之间会冲突吗？**
-A: 不会。`bin/wl-skills.js` 已自动生成 8 种主流 AI 编辑器配置文件，所有内容来自同一份 `copilot-instructions.md`，保持一致。
+A: 不会。`bin/wl-skills.js` 已自动生成 9 种主流 AI 编辑器配置文件（含 Qoder），所有内容来自同一份 `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 会自动调用接口完成同步，无需手动粘贴接口响应。
+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/`。

package/files/.github/skills/_compat/editors.json

@@ -56,6 +56,13 @@
       "headerFile": "agents.txt",
       "outputPath": "AGENTS.md",
       "enabled": true
+    },
+    {
+      "name": "qoder",
+      "headerFile": "qoder.txt",
+      "outputPath": ".qoder/rules/conventions.md",
+      "enabled": true,
+      "_note": "Qoder IDE 规则文件（Always Apply 类型）。Qoder 也原生兼容 AGENTS.md，两者均可被识别。"
     }
   ]
 }

package/files/.github/skills/_compat/headers/qoder.txt

@@ -0,0 +1,8 @@
+# Qoder Rules — 项目编码规范
+
+> 此文件为 Qoder IDE 规则文件（Always Apply），由 @agile-team/wl-skills-kit 自动生成。
+> 源文件：`.github/copilot-instructions.md`
+> 更新方式：`npx @agile-team/wl-skills-kit@latest update`
+
+---
+

package/files/.kiro/settings/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}

package/files/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wl-skills": {
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}

package/files/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "wl-skills": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["node_modules/@agile-team/wl-skills-kit/mcp/server.js"]
+    }
+  }
+}

package/package.json

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