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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [2.7.0] - 2026-05-12
+
+### Added
+
+- **CLI 未知 flag/命令防护**：`bin/wl-skills.js` 引入 `KNOWN_COMMANDS` / `KNOWN_FLAGS` 白名单。`node bin/wl-skills.js --version` 等未识别参数不再默认走 `init`，而是**退出非零并提示**，彻底消除 v2.6.x 时段被验证过的"误装风险"。
+- **MCP Tool auto-discovery**：新增 `mcp/registry.js` 集中维护 17 个工具描述符（含 `handle` / `needsBackendConfig`）。`mcp/server.js` 大幅瘦身（496 行 → 130 行），不再硬编码 17 项 switch case；新增 / 修改 Tool 仅改 `mcp/registry.js`。
+- **版本一致性自检脚本**：新增 `scripts/verify-version.js`（`npm run version:verify`），跨文件校验 `package.json#version` 与 CLI header / README / `guides/architecture.md` / headers 中描述行的一致性，并交叉校验 `_registry.md` 的 ✅ 启用 行数与 README / `package.json#description` 中的 "N 个 AI Skill" 数字一致。
+- **prepublishOnly 守门**：`npm publish` 前自动运行 `version:verify` + `vitest run`，不一致或测试失败则阻断发版。
+- **vitest 单元测试**：`tests/registry.test.js`（17 项 Tool 描述符 / Skill 计数 / package.json 一致性，9 测试）+ `tests/cli.test.js`（A1 防护黑盒测试 + dry-run 隔离验证，6 测试）+ `tests/version-tools.test.js`（version 工具脚本，3 测试）。共 **18 测试**全绿。
+- 新增 `dict-sync` / `code-fix` 的 `USAGE.md`，与其他 8 个启用 Skill 文档结构一致。
+
+### Changed
+
+- **`scripts/sync-version.js` 改为 registry-driven**：`SKILL_COUNT` 不再是手动维护常量，自动从 `files/.github/skills/_registry.md` 解析 ✅ 启用 行数得到；`MCP_TOOL_COUNT` 自动从 `mcp/registry.js` 取。
+- `files/.github/copilot-instructions.md` 删除内嵌的 Skill 状态表，改为单行指针 → `_registry.md`，消除三处独立维护。
+- `kit-internal/architecture.md` 重写为 **ADR 索引 + 当前架构指针**，不再复制能力清单；当前能力盘点统一指向 `docs/全盘分析与智能体搭建指南.md` 等单一数据源。
+- `package.json` 新增 `test` / `version:verify` / `prepublishOnly` 脚本与 `vitest` devDependency。
+
+### Notes
+
+- 业务项目升级 `npx @agile-team/wl-skills-kit update` 即可，无破坏性变更。
+- 维护者新增 Skill：仅改 `_registry.md` 与 `_pipeline.md` + 写 SKILL.md/USAGE.md，**不再需要手改 sync-version 常量与 copilot Skill 表**。
+- 维护者新增 MCP Tool：仅改 `mcp/registry.js` 加一条描述符，**不再需要改 server.js**。
+- 验证：`npm run version:verify && npm test` 应全绿，CI 可直接接入。
+
 ## [2.6.0] - 2026-05-12
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.6.0** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.7.0** — 一键将 13 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -23,6 +23,14 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 ## 版本亮点
 
+**v2.7.0**：一致性治理与可测性升级，安全防护加固。
+
+- **CLI 未知 flag / 命令防护**：`npx @agile-team/wl-skills-kit --version` 等未识别参数不再默认走 `init` 误装，而是退出非零并提示
+- **MCP Tool auto-discovery**：新增 `mcp/registry.js`，17 个 Tool 描述符集中维护；`mcp/server.js` 从 496 行瘦身到 130 行，新增 Tool 仅改 registry
+- **版本一致性自检**：`npm run version:verify` 跨文件校验版本 + Skill 计数；`prepublishOnly` 在 `npm publish` 前自动运行它与 `vitest`，不一致则阻断发版
+- **单元测试**：registry / CLI / version-tools 共 18 项覆盖，上面三项防护都有连动验证
+- **单一数据源加固**：`SKILL_COUNT` 从常量改为从 `_registry.md` 动态计算；copilot-instructions 删除内嵌 Skill 表改为指针；dict-sync / code-fix 补 USAGE.md
+
 当前 2.6.x 重点补齐业务理解闭环：原型/详设 → 业务文档 → 接口契约 → 页面代码 → 复扫。
 
 - **新增 `business-doc-extract` Skill**：语义级智能触发（不依赖固定关键词），在资料达模块/项目级完整度时建议生成业务文档：

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.6.0
+ * wl-skills-kit CLI v2.7.0
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -27,11 +27,57 @@ const MANIFEST_NAME = ".wl-skills-manifest.json";
 const MANIFEST_PATH = path.join(TARGET_DIR, MANIFEST_NAME);
 const PKG = require("../package.json");
 const args = process.argv.slice(2);
+
+// ─── 已知命令 / 选项白名单（A1: 防止未知 flag 默认走 init 误装）──────────
+const KNOWN_COMMANDS = new Set([
+  "init",
+  "update",
+  "clean",
+  "check",
+  "diff",
+  "validate",
+  "validate-page",
+  "doctor-ui",
+  "export",
+]);
+const KNOWN_FLAGS = new Set([
+  "--dry-run",
+  "--keep-reports",
+  "--force",
+  "--help",
+  "-h",
+]);
+
 const dryRun = args.includes("--dry-run");
 const showHelp = args.includes("--help") || args.includes("-h");
 const keepReports = args.includes("--keep-reports");
 const force = args.includes("--force");
-const command = args.find((a) => !a.startsWith("-")) || "init";
+
+// 校验所有 flag 是否已知（--help 优先，跳过校验直接显示帮助）
+if (!showHelp) {
+  const unknownFlags = args.filter(
+    (a) => a.startsWith("-") && !KNOWN_FLAGS.has(a),
+  );
+  if (unknownFlags.length > 0) {
+    console.error("");
+    console.error("  ✖ 未知选项: " + unknownFlags.join(", "));
+    console.error("  请使用 --help 查看可用选项");
+    console.error("");
+    process.exit(1);
+  }
+}
+
+const positional = args.filter((a) => !a.startsWith("-"));
+const command = positional[0] || "init";
+
+// 校验主命令是否已知（--help 时跳过；空命令默认 init）
+if (!showHelp && !KNOWN_COMMANDS.has(command)) {
+  console.error("");
+  console.error('  ✖ 未知命令: "' + command + '"');
+  console.error("  请使用 --help 查看可用命令");
+  console.error("");
+  process.exit(1);
+}
 
 if (showHelp) {
   console.log(`

package/docs/agent-pipeline-runbook.md

@@ -1,6 +1,6 @@
 # Agent Pipeline 运行手册
 
-> **版本基线**：wl-skills-kit v2.6.0  
+> **版本基线**：wl-skills-kit v2.7.0  
 > **定位**：给 AI 编辑器、团队成员和 CI 统一一套可追踪、可回退、可复扫的 Agent Pipeline 执行方法。
 
 ---

package/docs/ai/345/205/250/346/231/257/345/210/206/346/236/220.md

@@ -1,6 +1,6 @@
 # AI 辅助开发全景分析 & 架构演进蓝图
 
-> **基于 wl-skills-kit v2.6.0 架构**
+> **基于 wl-skills-kit v2.7.0 架构**
 > **日期**：2026-05-12
 > **目标**：企业级通用 · 质量精度高 · 速度快 · 节省 token · 还原度高 · 开箱即用 · 支持 Agent Pipeline
 

package/docs/mcp-tool-risk-matrix.md

@@ -1,6 +1,7 @@
 # MCP Tool 风险矩阵
 
-> **版本基线**：wl-skills-kit v2.6.0  
+> **版本基线**：wl-skills-kit v2.7.0  
+> **数据源**：`mcp/registry.js`（v2.7.0+ 引入 auto-discovery，新增 Tool 仅改 registry）  
 > **定位**：统一说明 17 个 MCP Tool 的风险等级、自动化边界、人工确认点和适用场景，避免 Agent 在企业项目中越权执行有副作用动作。
 
 ---

package/docs//345/205/250/347/233/230/345/210/206/346/236/220/344/270/216/346/231/272/350/203/275/344/275/223/346/220/255/345/273/272/346/214/207/345/215/227.md

@@ -1,6 +1,6 @@
 # wl-skills-kit 全盘分析与智能体搭建指南
 
-> **版本基线**：wl-skills-kit v2.6.0
+> **版本基线**：wl-skills-kit v2.7.0
 > **日期**：2026-05-12
 > **定位**：统一盘点当前能力、Agent Pipeline 搭建步骤、MCP 风险边界和后续迭代方向。
 

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

@@ -267,18 +267,7 @@ onMounted(() => select());
 - 保留 `common-core` 平台骨架，不得生搬硬套 `wk-skills-ui` 通用模板里的 `usePageHook/el-form/el-pagination`
 - 生成后建议运行 `wl-skills validate-page <页面目录>` 和 `wl-skills doctor-ui`
 
-| Skill 名             | 状态     | 一句话说明                              |
-| -------------------- | -------- | --------------------------------------- |
-| prototype-scan       | ✅ 启用  | 原型/详设 → page-spec JSON              |
-| api-contract         | ✅ 启用  | 生成 api.md 接口约定                    |
-| page-codegen         | ✅ 启用  | 页面骨架 + 模板调度 + 菜单追加            |
-| business-doc-extract | ✅ 启用  | 原型/详设/字段/字典/现有页面 → docs/business 业务文档 |
-| menu-sync            | ✅ 启用  | reports/SYS_MENU_INFO → 后端菜单接口    |
-| convention-audit     | ✅ 启用  | 13 条规范扫描 + 偏差报告 + 提取建议     |
-| template-extract     | ✅ 启用  | 现有页面 → 领域模板沉淀                 |
-| dict-sync            | ✅ 启用   | 字典数据同步                            |
-| permission-sync      | ✅ 启用   | 角色+授权+动作权限同步（MCP）           |
-| code-fix             | ✅ 启用   | 自动整改 🟢🟡 等级偏差                  |
+**Skill 状态总览 / 路径 / 完整触发词**：见 `skills/_registry.md`（**单一数据源**，新增或激活 Skill 只改这一处）。
 
 **执行规则**：
 

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

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

package/files/.github/skills/ops/code-fix/USAGE.md

@@ -0,0 +1,131 @@
+# 使用指南：code-fix（受控自动修复）
+
+> **谁读这个文档**：团队成员（前端 / 接手老项目时）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+`convention-audit` 跑完会生成 `reports/规范审查报告.md`，里面列出 N 条偏差，按 🔴/🟡/🟢 分级。如果手动一条一条改，效率很低；但**全量交给 AI 自动改**又会引入隐性破坏。
+
+`code-fix` 的定位是：**只修 🟡 / 🟢 级偏差，且每条都要 diff 预览 + 用户确认**。
+
+---
+
+## 何时使用
+
+- `convention-audit` 报告里堆积了大量 🟡 / 🟢 偏差（如缺 `:scoped` / 缺 `cid` / 缺导入顺序等）
+- 接手老项目，想批量整改 ESLint 之外的项目内规范
+- PR 评审前快速把"低风险偏差"清干净，让 reviewer 只看业务逻辑
+
+**不适用场景**：
+
+- 🔴 严重偏差（结构错误 / 用错组件 / 接口契约不符等）→ 用 `page-codegen` 重新生成或人工重写
+- 业务逻辑变更 → code-fix 不参与；这是 PR 的活
+- 没跑过 `convention-audit` → 必须先有报告，code-fix 不会自己扫代码
+
+---
+
+## 触发关键词
+
+`自动修复` / `整改偏差` / `修复报告` / `规范整改` / `code fix`
+
+---
+
+## 前置条件
+
+1. 项目根有 `reports/规范审查报告.md`（来自 `convention-audit` 的最新一次输出）
+2. 报告里 issue 项明确（含 issueId / 文件路径 / 行号 / 偏差类型）
+
+---
+
+## 标准对话示例
+
+```
+你：把规范审查报告里 🟡 级的偏差都修一下
+AI：[Pre-flight]
+    步骤 1：读取 reports/规范审查报告.md，识别到：
+       - 🔴 严重 3 项（不修）
+       - 🟡 中 12 项（可修）
+       - 🟢 低 8 项（可修）
+    步骤 2：本次修复目标：12 + 8 = 20 项
+    步骤 3：分组展示前 5 项 diff：
+
+       [issue-001] src/views/sale/order/index.vue:24
+       - <style lang="scss">
+       + <style lang="scss" scoped>
+
+       [issue-002] src/views/sale/order/index.vue:80
+       - <BaseTable :columns="columns" />
+       + <BaseTable :cid="ORDER_CID" :columns="columns" />
+
+       ... (再展示 3 项)
+
+    [需你确认] 这 5 项 yes 后继续看后续 15 项？逐组 yes/no？
+你：yes，全部一起改了吧
+AI：执行第 1 组（5 项）写入 → 标记报告条目为 ✅ 已修复 → 显示下一组
+    ...
+```
+
+---
+
+## 输出物
+
+1. **修改后的源文件**（每条 issue 命中的文件被精准 patch）
+2. **报告条目状态更新**：`reports/规范审查报告.md` 中对应 issueId 标记为 ✅ 已修复 + 时间戳
+3. **修复摘要**（可选）：`reports/CODE_FIX_<YYYYMMDD>.md` —— 本次共修复 N 项，按文件聚合
+
+---
+
+## 受控原则（严格执行）
+
+| 原则 | 说明 |
+|---|---|
+| **不修 🔴** | 严重偏差必须人工或 page-codegen 处理，code-fix 不介入 |
+| **不破坏功能** | 只改报告点名的行，不顺手"重构"周边代码 |
+| **不批量盲改** | 每个文件都先 diff 预览，禁止跳过用户确认 |
+| **不生成新逻辑** | 只修偏差，不做功能补全（那是 page-codegen 的职责） |
+| **范围明确** | 若用户引导修改业务逻辑，必须拒绝并说明原因 |
+
+---
+
+## 常见踩坑
+
+| 现象 | 原因 | 解法 |
+|---|---|---|
+| diff 看着对，但 lint 又报新错 | 修复策略与项目 ESLint 配置不一致 | 先跑 `npm run lint` 看新报错；调整 SKILL 里的 rule-based 策略 |
+| 报告里 issueId 被改回去了 | code-fix 修完后又有人手工改回旧写法 | PR 评审环节加"不要逆向修改"约束 |
+| AI 想"顺手优化"周边逻辑 | 模型主动性过强 | 在指令里加"严格按 issueId 修复，不做其他改动" |
+| 两次 code-fix 的 diff 不一致 | 中间 convention-audit 没重跑 | code-fix 之前必须先 audit，保证报告是最新快照 |
+
+---
+
+## 团队协作流程
+
+```
+[每次 PR 之前]
+1. wl-skills validate-page <修改过的页面>      # 单页快速校验
+2. convention-audit                             # 生成最新偏差报告
+3. code-fix                                      # 修 🟡/🟢
+4. 再跑一次 convention-audit                     # 复扫确认 🟡/🟢 → 0
+5. PR 提交（reviewer 只看 🔴 处理 + 业务逻辑）
+```
+
+> 复扫这一步**必做**：避免 code-fix 改完之后又引入新偏差。
+
+---
+
+## FAQ
+
+**Q：能跳过用户确认直接全部改吗？**
+A：**不允许**。code-fix 的核心定位就是"受控"，跳过确认会变成黑盒整改。要全自动请用 ESLint --fix。
+
+**Q：和 ESLint --fix 有什么区别？**
+A：ESLint 修语法/格式（自动化没风险），code-fix 修**项目内规范**（如 cid/operations/`:scoped`/导入顺序/AGGrid 写法 等 ESLint 不覆盖的规则）。两者互补，建议先 ESLint 再 code-fix。
+
+**Q：code-fix 改完会不会破坏 mock-first？**
+A：不会。code-fix 只动报告点名的行，mock-first 相关字段（`API_CONFIG.useMock` 等）不在受控修复范围。
+
+**Q：和 page-codegen 重新生成有什么区别？**
+A：`page-codegen` 是"重写整个页面骨架"，适合 🔴 级整页结构错误；`code-fix` 是"按 issue 精准修",  适合 🟡/🟢 级零碎偏差。两者互补，混用即可。

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

@@ -0,0 +1,122 @@
+# 使用指南：dict-sync（字典同步）
+
+> **谁读这个文档**：团队成员（前端 + 后端联调时）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+业务页面里 `data.ts` 引用的字典（`logicType: BusLogicDataType.dict, logicValue: "DICT_CODE"`）需要在低代码平台 **数据字典模块** 中真实存在，否则下拉项为空、表头标签为空。
+
+`dict-sync` 负责：
+
+1. 拉取**线上字典模块及字典项**到 `reports/SYS_DICT_INFO.md`（团队基线）
+2. 对比 `data.ts` 引用的字典码 vs 线上字典，**列出缺失字典码**
+3. 调用字典模块/字典项保存接口（或生成对照报告供后端建数据）
+
+---
+
+## 何时使用
+
+- 业务页面下拉/状态列空白，怀疑字典码没建
+- 一次性从原型/详设里抽取出 N 个新字典，需批量同步
+- 同步线上字典基线（DEV / UAT / PROD 拉齐）
+- `convention-audit` 报告里出现 "字典码不存在" 类偏差
+
+---
+
+## 触发关键词
+
+`同步字典` / `创建字典` / `刷新字典基线` / `字典对比` / `字典审计`
+
+---
+
+## 前置条件
+
+`.github/skills/sync/env.local.json`（已 gitignore，每个开发者本地填自己的 token）：
+
+```json
+{
+  "gatewayPath": "http://192.168.10.50:9000",
+  "sysAppNo": "QjQuXy1kbKxZyjhS5N2",
+  "token": "eyJhbGci...",
+  "dict": {
+    "moduleId": "7C909G0U2F8HI7E305LV0135LSJ3UBIO"
+  }
+}
+```
+
+`dict.moduleId` 获取方式：低代码平台 → 数据字典 → 新增一条 → DevTools Network → 抓 `moduleId` 字段。
+
+> **向下兼容**：`env.local.json` 不存在时回落到旧路径 `skills/sync/menu-sync/env/env.local.json`。
+
+---
+
+## 标准对话示例
+
+```
+你：把 src/views/produce/aiflow/ 里所有页面用到的字典同步一下
+AI：[Pre-flight]
+    步骤 1：扫描 data.ts，提取 logicValue 形成字典码集合（共 12 个）
+    步骤 2：调用 wls_dict_query 拉线上字典模块（已有 8 个，缺 4 个）
+    步骤 3：建议新增字典模块 + 字典项：
+       - APPLY_STATUS（申请状态：待审核/审核中/已通过/已驳回）
+       - CUSTOMER_TYPE（客户类型：临时/正式/合作/战略）
+       - ...
+    [需你确认]
+    - 排序 sortPriority 自动从 1 递增？yes/no
+    - 字典名 strName 我直接用截图里的中文，对吗？yes/no
+```
+
+---
+
+## 输出物
+
+1. **基线文件**：`reports/SYS_DICT_INFO.md` —— 当前所有线上字典模块 + 字典项的本地基线
+2. **同步报告**（可选）：`reports/DICT_SYNC_<YYYYMMDD>.md` —— 本次新增了哪些字典/字典项
+3. **缺失对照**：报告附 "未在线上找到的字典码" 列表，便于后端预先建数据
+
+---
+
+## 与 business-doc-extract 的关系
+
+| 维度 | `business-doc-extract` | `dict-sync` |
+|---|---|---|
+| 职责 | 业务理解 / 设计意图 | 线上事实 / 数据落地 |
+| 输出 | `docs/business/0X-xx/dictionary.md`（人读） | 后端字典表（系统读） |
+| 时机 | 项目/模块沉淀阶段 | 联调前 / 上线前 |
+
+两者**互不替代**：业务文档说的是"应该有什么字典"，dict-sync 解决"线上有没有"。建议顺序：`business-doc-extract` 整理出 dictionary.md 草案 → 评审 → `dict-sync` 落地。
+
+---
+
+## 常见踩坑
+
+| 现象 | 原因 | 解法 |
+|---|---|---|
+| 下拉空白但接口返回正常 | 字典码大小写不一致 | 字典码全部 UPPER_SNAKE_CASE，data.ts 与后端对齐 |
+| 401/403 报错 | env.local.json 的 token 过期 | 重新登录系统，从 Network 抓 Authorization 替换 |
+| 模块新增成功但取不到 id | 接口异步延迟 | dict-sync 已自动 re-query，无需手动处理 |
+| 字典项重复创建 | 没读基线就 push | 先跑 `wls_dict_query` 取线上数据 → 对比 → 增量 push |
+
+---
+
+## 团队协作流程
+
+1. **每周一**由 lead 跑一次 `刷新字典基线`，更新 `reports/SYS_DICT_INFO.md`
+2. 业务页面 PR 提交前自查 "我加的字典码是否进了基线"
+3. 上线前再 sync 一次到生产环境（切换 env 文件中的 gatewayPath）
+
+---
+
+## FAQ
+
+**Q：业务字典 vs 系统字典 vs 状态枚举怎么区分？**
+A：状态枚举（如 `APPLY_STATUS`）走系统字典；业务高频可枚举字段（如 `CUSTOMER_TYPE`）走系统字典；纯文本备注、复杂联动数据不走字典。
+
+**Q：能不能让 AI 直接根据 data.ts 自动建字典？**
+A：可以，但 **建议人工确认 strName**。AI 从字段中文猜出来的字典名往往不够标准，PR 评审难。先生成对照报告，人工 review 后再 push。
+
+**Q：和 menu-sync / permission-sync 关系？**
+A：菜单是入口，字典是值域，权限是访问控制。三者独立但配合。建议顺序：`menu-sync` → `permission-sync` → `dict-sync`。