@agile-team/wl-skills-kit 2.5.0 → 2.5.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [2.5.2] - 2026-05-12
+
+### Added
+
+- 新增 `docs/mcp-tool-risk-matrix.md`，按只读、本地检查、后端写入、外部通知分级说明 MCP Tool 风险、确认要求和自动化边界。
+- 新增 `docs/agent-pipeline-runbook.md`，定义 Agent Pipeline 执行顺序、人工确认点、运行报告字段和闭环验证建议。
+
+### Changed
+
+- 同步 `package.json`、`package-lock.json`、CLI header、README 的版本文案到 `2.5.2`，修复 2.5.x 发布后残留的旧版本描述。
+- 升级 `docs/全盘分析与智能体搭建指南.md` 与 `docs/ai全景分析.md` 到 2.5.x 当前能力，补齐 17 个 MCP Tool、`validate-page`、`doctor-ui`、`wk-skills-ui` 桥接和 `navigateHidden` 隐藏页导航实践。
+
+## [2.5.1] - 2026-05-09
+
+### Changed
+
+- `prototype-scan` Skill 补齐 Axure 原型文件访问前置说明：`index.html` 永久不可用（VS Code 内嵌 Chromium 不加载用户 Chrome 扩展）；只能用 `open_browser_page(具体页.html)` 或 `read_file`；`(not visible)` 不等于不可访问。
+- `page-codegen` Skill 将隐藏页导航方案统一为 `navigateHidden` 主路（`src/util/navigate-hidden.ts`）：懒注册 + `router.push` 无整页刷新，内部自动 `location.href` 兜底防白屏；禁止外部调用侧直接使用 `location.href`；生成摘要后续步骤新增"维护 `HIDDEN_ROUTE_MAP`"强提醒。
+
 ## [2.5.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.5.0** — 一键将 13 条规范、9 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.5.2** — 一键将 13 条规范、9 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -23,11 +23,13 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 ## 版本亮点
 
-当前 2.4.x 版本重点完善生命周期、规范插件和跨包协作体验：
+当前 2.5.x 版本重点完善 Skill 规范精度和隐藏页导航体系：
 
-- `init/update/diff/clean/check/validate/export` 覆盖安装、升级、对比、清理、体检、页面完整性检查和基线导出
+- `init/update/diff/clean/check/validate/validate-page/doctor-ui/export` 覆盖安装、升级、对比、清理、体检、页面完整性检查、UI 接入诊断和基线导出
 - 页面模板升级为 `BaseTable + render-type="agGrid" + cid + defineColumns + renderOps` 最终标准，融合 `wk-skills-ui` runtime，但保留 `common-core` 平台骨架
 - 新增 `doctor-ui` / `validate-page`：检查 `wk-skills-ui` 接入、AGGrid/cid、操作列、mock-first、api.md 等关键偏差
+- **`prototype-scan` Skill 补齐 Axure 访问前置说明**：明确 `index.html` 永久不可用（VS Code 内嵌 Chromium 不加载用户 Chrome 扩展），只能用 `open_browser_page(具体页.html)` 或 `read_file`；`(not visible)` 不等于不可访问
+- **`page-codegen` Skill 统一隐藏页导航为 `navigateHidden` 主路**：懒注册 + router.push 无整页刷新，内部自动兜底防白屏；外部调用禁止直接 `location.href`，新增页面生成摘要步骤强提醒维护 `HIDDEN_ROUTE_MAP`
 - 增强 Intent Router：用户只需说“做个页面 / 先 mock / 菜单同步 / 风格不生效”，AI 自动识别触发 Skill/MCP
 - manifest 记录安装文件哈希，`reports/`、`src/components/`、`src/types/` 等关键资产受到保护
 - 自动生成 Copilot、Claude Code、Cursor、Windsurf、Cline、Kiro、Trae、Qoder、通用 Agents 规则文件
@@ -78,7 +80,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ├── package.json                          name: @agile-team/wl-skills-kit
 │
 ├── bin/
-│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / export）
+│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / validate-page / doctor-ui / export）
 │
 ├── files/                                ★★★ 真正会被打包并复制到业务项目的内容 ★★★
 │   └── .github/

package/bin/wl-skills.js

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

package/docs/agent-pipeline-runbook.md

@@ -0,0 +1,199 @@
+# Agent Pipeline 运行手册
+
+> **版本基线**：wl-skills-kit v2.5.2  
+> **定位**：给 AI 编辑器、团队成员和 CI 统一一套可追踪、可回退、可复扫的 Agent Pipeline 执行方法。
+
+---
+
+## 1. 核心目标
+
+Agent Pipeline 不是让 AI 一次性自动做完所有事，而是把复杂任务拆成可验证步骤：
+
+```text
+项目感知 → Skill 调度 → 生成/同步/修复 → 本地校验 → 人工确认 → 复扫闭环
+```
+
+每一步都必须有：
+
+- **输入**：用户需求、原型、详设、报告或文件路径
+- **动作**：触发的 Skill、CLI 或 MCP Tool
+- **输出**：文件、报告、后端数据或检查结果
+- **确认点**：是否涉及写文件、写后端或外部推送
+- **下一步**：`next_suggest`
+
+---
+
+## 2. 标准链路
+
+### 2.1 原型到页面
+
+```text
+prototype-scan
+→ api-contract
+→ page-codegen
+→ validate-page
+→ convention-audit
+→ code-fix（可选）
+→ convention-audit 复扫
+```
+
+适用场景：有 Axure、截图、详设、page-spec 或较完整口述需求。
+
+### 2.2 口述需求到可运行页面
+
+```text
+page-codegen
+→ validate-page
+→ doctor-ui（如接入 wk-skills-ui）
+→ convention-audit
+```
+
+适用场景：用户只描述“做个页面”“先 mock 能跑”。
+
+### 2.3 存量项目体检
+
+```text
+wls_code_scan
+→ wls_git_log_extract
+→ convention-audit
+→ code-fix（仅修明确可自动修复项）
+→ validate / validate-page
+→ convention-audit 复扫
+```
+
+适用场景：接手存量模块、评估规范偏差、准备重构。
+
+### 2.4 菜单/字典/权限闭环
+
+```text
+page-codegen 产出 SYS_* 报告
+→ query 类 MCP Tool 获取现状
+→ 展示差异和写入计划
+→ 用户确认
+→ upsert / sync 类 MCP Tool
+→ route_check / validate_page / convention-audit 复扫
+```
+
+适用场景：页面已生成，需要同步后台菜单、字典、角色授权或动作权限。
+
+---
+
+## 3. Pipeline 运行报告
+
+建议每次复杂任务生成：
+
+```text
+.github/reports/PIPELINE_RUN_YYYYMMDD_HHmm.md
+```
+
+报告字段：
+
+| 字段 | 说明 |
+|---|---|
+| 用户目标 | 原始需求摘要 |
+| 触发 Skill | 实际执行的 Skill 列表 |
+| 必读规范 | 已加载的 standards 文件 |
+| 调用工具 | CLI/MCP Tool 调用清单 |
+| 输入产物 | 原型、详设、api.md、审计报告等 |
+| 输出产物 | 新增/修改文件、报告、后端同步摘要 |
+| 风险项 | 需要人工 review 或后续治理的问题 |
+| 人工确认点 | 写文件、调接口、授权覆盖、外部推送等 |
+| 复扫结果 | validate、doctor-ui、route_check、convention-audit 结果 |
+| next_suggest | 下一步建议 |
+
+---
+
+## 4. Agent 输出规范
+
+每个阶段完成后，Agent 必须输出：
+
+```text
+## 完成摘要
+- 产物：{output_file}
+- 关键数据：{counts / changed files / backend ids}
+- 风险：{manual review items}
+
+## 建议下一步
+- next_suggest：{skill-name / cli / mcp tool}
+- 原因：{why}
+- 是否需要用户确认：是/否
+```
+
+涉及以下动作时，`是否需要用户确认` 必须为“是”：
+
+- 写源码文件
+- 修改 `.github/reports/` 基线
+- 调用后端写接口
+- 覆盖角色授权
+- 推送飞书/外部通知
+- 发版、提交、推送远端
+
+---
+
+## 5. 推荐验证组合
+
+### 本地页面质量
+
+```bash
+npx @agile-team/wl-skills-kit validate
+npx @agile-team/wl-skills-kit validate-page src/views/xxx/yyy
+npx @agile-team/wl-skills-kit doctor-ui
+```
+
+### MCP 项目感知
+
+```text
+wls_code_scan({ path: "src/views" })
+wls_route_check({ path: "src/views" })
+wls_git_log_extract({ n: 20 })
+```
+
+### 发布前自检
+
+```bash
+node --check bin/wl-skills.js
+node --check mcp/server.js
+node --check mcp/tools/projectTools.js
+npm pack --dry-run
+git diff --check
+```
+
+---
+
+## 6. 回退策略
+
+- **单步失败**：只重跑当前 Skill 和后续步骤，不从头重跑。
+- **页面生成不满意**：保留 `api.md`，重跑 `page-codegen`。
+- **审计修复不满意**：回退源码 diff，保留审计报告。
+- **菜单/字典同步异常**：基于报告和后台查询结果人工校正，再重跑 query 类工具验证。
+- **权限授权异常**：优先重新确认全量 `menuIds`，再执行覆盖式授权。
+
+---
+
+## 7. 与 wk-skills-ui 的协作
+
+当业务项目接入 `@agile-team/wk-skills-ui` 时，Pipeline 需要额外检查：
+
+- design tokens 是否引入
+- styles preset 是否引入
+- `installCommonPreset()` 是否调用
+- 页面列定义是否使用 `defineColumns()`
+- 操作列是否使用 `renderOps()`
+
+推荐步骤：
+
+```text
+page-codegen
+→ doctor-ui
+→ validate-page
+→ convention-audit
+```
+
+---
+
+## 8. 当前不建议自动化的事项
+
+- 不建议让 Agent 自动执行 R3/R4 MCP Tool。
+- 不建议自动合并规范自演化结论。
+- 不建议直接启动 Multi-Agent 编排框架。
+- 不建议把 sale/produce 等领域专属流程塞入主包，成熟后应拆为独立领域包。

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

@@ -1,7 +1,7 @@
 # AI 辅助开发全景分析 & 架构演进蓝图
 
-> **基于 wl-skills-kit v2.4.x 架构**
-> **日期**：2026-05-02
+> **基于 wl-skills-kit v2.5.2 架构**
+> **日期**：2026-05-12
 > **目标**：企业级通用 · 质量精度高 · 速度快 · 节省 token · 还原度高 · 开箱即用 · 支持 Agent Pipeline
 
 ---
@@ -11,9 +11,9 @@
 ```text
 L1 提示词工程         ✅ copilot-instructions + 多编辑器适配 + standards 懒加载
 L2 Skills             ✅ 9 个启用 Skill + registry + pre-flight
-L3 MCP                ✅ 14 个 Tool（菜单/字典/权限/项目感知/通知）
-L4 CLI                ✅ init/update/clean/check/diff/validate/export
-L5 Agent Pipeline     🟡 已落地协议，可进入试运行
+L3 MCP                ✅ 17 个 Tool（菜单/字典/权限/项目感知/页面校验/UI 体检/通知）
+L4 CLI                ✅ init/update/clean/check/diff/validate/validate-page/doctor-ui/export
+L5 Agent Pipeline     🟡 已落地协议与运行手册，可进入试运行
 L6 Multi-Agent        🔭 L5 稳定后再评估
 L7 自演化体系         🔭 需要足够审计报告与模板样本后再规划
 ```
@@ -26,14 +26,14 @@ L7 自演化体系         🔭 需要足够审计报告与模板样本后再规
 |---|---:|---|
 | Standards | 13 条 | 场景化 code-structure、Git 审计、AGGrid 判定均已纳入 |
 | Skills | 9 个 | core/sync/ops 全部启用，domain 暂不扩展 |
-| MCP Tools | 14 个 | 新增 code_scan / route_check / git_log_extract / audit_report_push |
-| CLI 命令 | 7 个 | init / update / clean / check / diff / validate / export |
+| MCP Tools | 17 个 | 覆盖 code_scan / route_check / validate_page / doctor_ui / git_log_extract / audit_report_push 等 |
+| CLI 命令 | 9 个 | init / update / clean / check / diff / validate / validate-page / doctor-ui / export |
 | Pipeline 协议 | 1 份 | `.github/skills/_pipeline.md` |
 | 全盘分析文档 | 1 份 | `docs/全盘分析与智能体搭建指南.md` |
 
 ---
 
-## 3. v2.4.x 关键能力
+## 3. v2.5.x 关键能力
 
 ### 3.1 Agent Pipeline
 
@@ -57,6 +57,8 @@ files/.github/skills/_pipeline.md
 |---|---|
 | `wls_code_scan` | 扫描页面目录、文件完整性、API_CONFIG 分布 |
 | `wls_route_check` | 检查页面是否可被路由发现 |
+| `wls_validate_page` | 校验 AGGrid/cid/api.md/mock/操作列等页面规范 |
+| `wls_doctor_ui` | 检查 wk-skills-ui tokens、styles、preset 和 runtime 接入 |
 | `wls_git_log_extract` | 提取最近提交，支撑 Git 审计/变更日志 |
 | `wls_audit_report_push` | 可选推送审计报告到飞书 webhook |
 
@@ -66,7 +68,9 @@ files/.github/skills/_pipeline.md
 |---|---|
 | `wl-skills check` | 新成员接入和环境排查 |
 | `wl-skills diff` | update 前评估文件变化 |
-| `wl-skills validate` | 无 AI 静态检查页面文件完整性 |
+| `wl-skills validate` | 无 AI 静态检查页面完整性、AGGrid、cid、mock、api.md |
+| `wl-skills validate-page` | 针对单页/目录做即时校验 |
+| `wl-skills doctor-ui` | 检查 wk-skills-ui 是否真实接入 |
 | `wl-skills export` | 导出菜单/字典/权限基线为 xlsx |
 
 ---
@@ -80,6 +84,7 @@ files/.github/skills/_pipeline.md
   → 读取 _registry.md 匹配 Skill
   → 读取 _pipeline.md 判断上下游
   → wls_code_scan 感知项目结构
+  → validate-page / doctor-ui 做本地校验
   → 执行 Skill
   → 输出完成摘要 + next_suggest
   → 用户确认后继续下一步
@@ -91,6 +96,7 @@ files/.github/skills/_pipeline.md
 prototype-scan
   → api-contract
   → page-codegen
+  → validate-page
   → convention-audit
   → code-fix（可选）
   → convention-audit 复扫
@@ -104,7 +110,7 @@ wls_code_scan
   → convention-audit
   → code-fix
   → convention-audit 复扫
-  → wl-skills validate
+  → wl-skills validate / doctor-ui
 ```
 
 ---
@@ -114,8 +120,9 @@ wls_code_scan
 ### 短期
 
 - 在真实项目中试跑 Agent Pipeline
-- 将 `wl-skills validate` 接入 CI 非阻断阶段
+- 将 `wl-skills validate` / `doctor-ui` 接入 CI 非阻断阶段
 - 持续收集 convention-audit 报告样本
+- 为复杂任务生成 `PIPELINE_RUN_YYYYMMDD_HHmm.md` 运行报告
 
 ### 中期
 
@@ -134,11 +141,12 @@ wls_code_scan
 
 ## 6. 结论
 
-v2.4.x 后，wl-skills-kit 已具备搭建通用智能体的基础条件：
+v2.5.x 后，wl-skills-kit 已具备搭建通用智能体的基础条件：
 
 - 有 Skills 作为结构化能力单元
 - 有 MCP 作为实时项目感知与副作用执行工具
 - 有 CLI 作为无 AI 的质量兜底
 - 有 `_pipeline.md` 作为 Agent 串联协议
+- 有 `wk-skills-ui` 可选桥接作为 UI Runtime 治理边界
 
 下一步应先在真实业务项目中稳定跑通通用 Pipeline，再考虑领域 Skill 或 Multi-Agent。

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

@@ -0,0 +1,130 @@
+# MCP Tool 风险矩阵
+
+> **版本基线**：wl-skills-kit v2.5.2  
+> **定位**：统一说明 17 个 MCP Tool 的风险等级、自动化边界、人工确认点和适用场景，避免 Agent 在企业项目中越权执行有副作用动作。
+
+---
+
+## 1. 分级原则
+
+| 风险级别 | 定义 | 自动化建议 |
+|---|---|---|
+| R0 只读感知 | 只读取本地文件、Git 信息或后端数据，不产生写入 | 可由 Agent 自动调用 |
+| R1 本地检查 | 只做本地扫描和诊断，不修改文件、不调用后端写接口 | 可由 Agent 自动调用，结果需展示 |
+| R2 本地产物 | 读取本地报告并生成导出文件或摘要 | 建议先 dry-run 或展示输出路径 |
+| R3 后端写入 | 会新增/更新菜单、字典、角色、授权或动作权限 | 必须人工确认，建议先 query/dry-run/报告预览 |
+| R4 外部通知 | 会向飞书等外部协作系统推送消息 | 必须人工确认，可配置缺失时静默跳过 |
+
+---
+
+## 2. Tool 风险矩阵
+
+| Tool | 分类 | 风险级别 | 是否依赖 token | 是否可自动调用 | 人工确认要求 |
+|---|---|---:|---|---|---|
+| `wls_code_scan` | 项目感知 | R0 | 否 | 是 | 无 |
+| `wls_route_check` | 项目感知 | R0 | 否 | 是 | 无 |
+| `wls_git_log_extract` | 项目感知 | R0 | 否 | 是 | 无 |
+| `wls_validate_page` | 本地检查 | R1 | 否 | 是 | 无 |
+| `wls_doctor_ui` | 本地检查 | R1 | 否 | 是 | 无 |
+| `wls_menu_query` | 菜单查询 | R0 | 是 | 是 | 无 |
+| `wls_dict_query` | 字典查询 | R0 | 是 | 是 | 无 |
+| `wls_role_query` | 权限查询 | R0 | 是 | 是 | 无 |
+| `wls_assignable_menus_query` | 权限查询 | R0 | 是 | 是 | 无 |
+| `wls_action_query` | 权限查询 | R0 | 是 | 是 | 无 |
+| `wls_menu_sync_from_report` | 菜单同步 | R3 | 是 | 否 | 必须确认报告路径、同步范围和 dry-run 结果 |
+| `wls_menu_upsert` | 菜单写入 | R3 | 是 | 否 | 必须确认新增/更新项 |
+| `wls_dict_upsert` | 字典写入 | R3 | 是 | 否 | 必须确认模块和字典项 |
+| `wls_role_upsert` | 角色写入 | R3 | 是 | 否 | 必须确认角色 code 和名称 |
+| `wls_role_assign_menus` | 授权写入 | R3 | 是 | 否 | 必须确认全量 menuIds，避免覆盖已有授权 |
+| `wls_action_upsert` | 动作写入 | R3 | 是 | 否 | 必须确认 parentId 和 permission 命名 |
+| `wls_audit_report_push` | 外部通知 | R4 | 可选 | 否 | 必须确认推送报告和目标 webhook |
+
+---
+
+## 3. Agent 调用约束
+
+### 3.1 可自动调用
+
+以下 Tool 不产生副作用，可作为 Agent Pipeline 的前置感知或复扫能力：
+
+```text
+wls_code_scan
+wls_route_check
+wls_git_log_extract
+wls_validate_page
+wls_doctor_ui
+wls_menu_query
+wls_dict_query
+wls_role_query
+wls_assignable_menus_query
+wls_action_query
+```
+
+### 3.2 必须人工确认
+
+以下 Tool 会写后端或推送外部消息，Agent 必须先输出计划并等待用户确认：
+
+```text
+wls_menu_sync_from_report
+wls_menu_upsert
+wls_dict_upsert
+wls_role_upsert
+wls_role_assign_menus
+wls_action_upsert
+wls_audit_report_push
+```
+
+确认信息至少包含：
+
+- **目标环境**：`gatewayPath` / `sysAppNo` / `domainId`
+- **数据来源**：报告路径、用户输入或上一步产物
+- **影响范围**：新增、更新、覆盖、推送对象
+- **回滚方式**：是否可通过后台手工删除或重新同步恢复
+
+---
+
+## 4. 推荐执行顺序
+
+### 菜单同步
+
+```text
+wls_menu_query
+→ 读取/生成 SYS_MENU_INFO.md
+→ wls_menu_sync_from_report(dryRun: true)
+→ 用户确认
+→ wls_menu_sync_from_report(dryRun: false)
+→ wls_route_check
+```
+
+### 字典同步
+
+```text
+wls_dict_query
+→ 读取/生成 SYS_DICT_INFO.md
+→ 展示将新增/跳过项
+→ 用户确认
+→ wls_dict_upsert
+→ convention-audit 或页面复扫
+```
+
+### 权限同步
+
+```text
+wls_role_query
+→ wls_assignable_menus_query
+→ wls_action_query
+→ 生成 SYS_PERMISSION_INFO.md
+→ 用户确认
+→ wls_role_upsert / wls_action_upsert / wls_role_assign_menus
+→ 权限码使用复扫
+```
+
+---
+
+## 5. 安全边界
+
+- `env.local.json` 只放本地环境配置，不应提交真实 token。
+- R3/R4 Tool 不允许在用户无明确确认时自动执行。
+- 角色授权是全量覆盖式操作，必须展示最终 `menuIds` 集合。
+- 飞书 webhook 缺失时应跳过，不阻断主流程。
+- CI 中默认只运行 R0/R1 能力；如需 R3/R4，必须使用受控环境变量和审批流程。

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,8 +1,8 @@
 # wl-skills-kit 全盘分析与智能体搭建指南
 
-> **版本基线**：wl-skills-kit v2.4 规划基线
-> **日期**：2026-05-02
-> **定位**：对当前能力、扩展方向、智能体搭建步骤进行统一盘点，作为后续迭代和团队评审依据。
+> **版本基线**：wl-skills-kit v2.5.2
+> **日期**：2026-05-12
+> **定位**：统一盘点当前能力、Agent Pipeline 搭建步骤、MCP 风险边界和后续迭代方向。
 
 ---
 
@@ -12,8 +12,8 @@
 |---|---|---|
 | L1 提示词工程 | ✅ 稳定 | `copilot-instructions.md` + 多编辑器适配 + standards 懒加载 |
 | L2 Skills | ✅ 稳定 | 9 个启用 Skill，覆盖原型扫描、接口契约、页面生成、审计、模板提取、菜单/字典/权限同步、受控修复 |
-| L3 MCP | ✅ 增强 | 14 个 Tool，覆盖菜单/字典/权限/项目结构扫描/路由检查/Git 摘要/审计报告推送 |
-| L4 CLI | ✅ 增强 | `init` / `update` / `clean` / `check` / `diff` / `validate` / `export` |
+| L3 MCP | ✅ 增强 | 17 个 Tool，覆盖菜单、字典、权限、项目感知、页面校验、UI 体检、Git 摘要和审计报告推送 |
+| L4 CLI | ✅ 增强 | `init` / `update` / `clean` / `check` / `diff` / `validate` / `validate-page` / `doctor-ui` / `export` |
 | L5 Agent Pipeline | 🟡 已具备基础 | 已新增 `_pipeline.md` 协议，可开始按 Skill I/O 串联 |
 | L6 Multi-Agent | 🔭 远期 | 暂不建议启动，需 L5 稳定后再评估 |
 | L7 自演化体系 | 🔭 远期 | 需积累审计报告与模板提取样本后再规划 |
@@ -24,9 +24,9 @@
 
 | 分类 | Skill | 状态 | 核心价值 |
 |---|---|---|---|
-| core | `prototype-scan` | ✅ | 原型/详设/口述需求 → 页面清单 |
+| core | `prototype-scan` | ✅ | 原型/详设/口述需求 → 页面清单；已补齐 Axure 具体页访问约束 |
 | core | `api-contract` | ✅ | 生成页面级 `api.md` 前后端契约 |
-| core | `page-codegen` | ✅ | 生成符合 13 条规范的页面骨架 |
+| core | `page-codegen` | ✅ | 生成符合 13 条规范的页面骨架；统一 AGGrid、cid、`defineColumns()`、`renderOps()` 和 `navigateHidden` |
 | core | `convention-audit` | ✅ | 13 条规范扫描 + 结构化审计报告 |
 | core | `template-extract` | ✅ | 从成熟页面沉淀模板 |
 | sync | `menu-sync` | ✅ | 菜单基线 ↔ 后端菜单接口 |
@@ -44,6 +44,7 @@
 |---|---|---|
 | 菜单 | `wls_menu_query` | 查询完整菜单树 |
 | 菜单 | `wls_menu_upsert` | 批量新增/更新菜单 |
+| 菜单 | `wls_menu_sync_from_report` | 从 `SYS_MENU_INFO*.md` 确定性同步菜单 |
 | 字典 | `wls_dict_query` | 查询字典模块与字典项 |
 | 字典 | `wls_dict_upsert` | 新增/更新字典模块与字典项 |
 | 权限 | `wls_role_query` | 查询角色列表 |
@@ -54,13 +55,19 @@
 | 权限 | `wls_action_upsert` | 批量新增动作按钮 |
 | 项目感知 | `wls_code_scan` | 扫描页面目录和文件完整性 |
 | 项目感知 | `wls_route_check` | 检查页面目录是否在路由文件中可发现 |
+| 项目感知 | `wls_validate_page` | 校验页面 AGGrid/cid/`api.md`/mock/操作列等规范 |
+| 项目感知 | `wls_doctor_ui` | 检查 `wk-skills-ui` tokens、styles、preset 和 runtime 接入 |
 | 项目感知 | `wls_git_log_extract` | 提取近期 Git 提交摘要 |
 | 通知 | `wls_audit_report_push` | 推送最新审计报告到飞书 webhook（可选） |
 
+MCP 风险边界详见 `docs/mcp-tool-risk-matrix.md`。
+
 ### 3.1 MCP 扩展价值
 
 - **`wls_code_scan`**：解决 AI 只能猜目录结构的问题，是 convention-audit 和 Pipeline 的关键前置能力。
 - **`wls_route_check`**：让 page-codegen/menu-sync 后有闭环验证，不再只看文件是否生成。
+- **`wls_validate_page`**：把页面规范检查沉淀为可重复 MCP 能力，便于 Agent 复扫单页。
+- **`wls_doctor_ui`**：检查 `wk-skills-ui` 是否真实接入，避免只安装依赖但样式/runtime 未生效。
 - **`wls_git_log_extract`**：支撑 Git 规范审计与后续 changelog-gen。
 - **`wls_audit_report_push`**：把审计结果从本地报告推进到团队协作渠道。
 
@@ -75,14 +82,17 @@
 | `clean` | 清理开发期 AI 文件 | 构建前/交付前 |
 | `check` | 环境预检 | 新成员接入、问题排查 |
 | `diff` | 对比已安装文件与当前 kit | update 前评估影响 |
-| `validate` | 静态扫描页面文件完整性 | CI 或审计前快速检查 |
+| `validate` | 静态扫描页面完整性、AGGrid、cid、mock、`api.md` | CI 或审计前快速检查 |
+| `validate-page` | `validate` 的别名，支持单页/目录路径 | 单页生成后即时检查 |
+| `doctor-ui` | 检查 `wk-skills-ui` 接入完整性 | UI 风格治理、老项目化妆层接入后 |
 | `export` | 导出菜单/字典/权限基线 xlsx | 给产品/后端/测试查看 |
 
 ### 4.1 CLI 扩展价值
 
 - `check` 降低新成员配置成本。
 - `diff` 降低团队升级时的不确定性。
-- `validate` 提供无 AI 的最低限度质量门禁。
+- `validate` / `validate-page` 提供无 AI 的最低限度质量门禁。
+- `doctor-ui` 让 `wk-skills-ui` 桥接从“已安装”变成“真实生效可检查”。
 - `export` 让 reports 数据更容易被非研发角色使用。
 
 ---

package/files/.github/skills/core/page-codegen/SKILL.md

@@ -46,8 +46,9 @@ description: "Use when: generating complete Vue 3 page code (index.vue + data.ts
 ────────────────────────────────────────────────
 📌 后续步骤：
    1. 在 router/pages.ts 注册路由
-   2. 提交：git cz（禁止直接 git commit）
-   3. 可选：触发 convention-audit 扫描本次生成文件
+   2. 若本页 hiddenMenu=true → 在 src/util/navigate-hidden.ts 的 HIDDEN_ROUTE_MAP 追加一行
+   3. 提交：git cz（禁止直接 git commit）
+   4. 可选：触发 convention-audit 扫描本次生成文件
 ────────────────────────────────────────────────
 ```
 
@@ -259,9 +260,10 @@ function handleCodeClick(row: any) {
 >
 > | 场景 | 方式 | 原因 |
 > |---|---|---|
-> | **菜单页 → 隐藏页**（如列表→表单） | `envConfig()?.router` + `location.href` | 需要父壳刷新菜单高亮 |
-> | **隐藏页 → 隐藏页**（如表单→变更历史） | `envConfig()?.router` + `location.href` | `router.push()` 跳过 shell 的 `generateCurrentRoute`，导致 "Invalid route component" 报错 |
+> | **菜单页 → 隐藏页 / 隐藏页 → 隐藏页** | `navigateHidden(path, query?)` from `src/util/navigate-hidden.ts` | 懒注册 + router.push，无整页刷新；内部自动兜底 location.href 防白屏 |
 > | **返回上一页** | `useRouter().back()` | 任何页面均可用 |
+>
+> ⚠️ `navigateHidden` 依赖 `src/util/navigate-hidden.ts` 的 `HIDDEN_ROUTE_MAP`。**每新增一个隐藏页，必须在该 Map 里追加一行**，否则兜底会退化为整页刷新。
 
 #### 路由路径命名规则
 
@@ -274,36 +276,60 @@ function handleCodeClick(row: any) {
 - 子模块名取 pages.ts 的 key，如 `aiflow`
 - 页面目录名整体转 PascalCase（含 `mmwr` 前缀），如 `mmwr-customer-apply-add-form` → `mmwrCustomerApplyAddForm`
 
-#### 标准实现（data.ts）
+#### navigate-hidden.ts 标准实现（首次使用时创建，后续只追加 Map 条目）
 
 ```typescript
-// ✅ 正确：用 envConfig
+// src/util/navigate-hidden.ts
 import envConfig from "@jhlc/common-core/src/store/env-config";
+import { ElMessage } from "element-plus";
+
+/**
+ * 隐藏页路由懒注册表
+ * 每新增一个 hiddenMenu=true 的页面，在此追加一行
+ */
+const HIDDEN_ROUTE_MAP: Record<string, () => Promise<any>> = {
+  // "/aiflow/mmwrCustomerApplyAddForm": () => import("@/views/produce/aiflow/mmwr-customer-apply-add-form/index.vue"),
+};
+
+export async function navigateHidden(path: string, query?: Record<string, string>) {
+  const router = envConfig()?.router;
+  if (!router) { ElMessage.error("路由未初始化，请刷新页面重试"); return; }
+
+  const matched = router.resolve({ path }).matched;
+  if (!matched.length || matched[0].path === "/:pathMatch(.*)*") {
+    const loader = HIDDEN_ROUTE_MAP[path];
+    if (!loader) {
+      // 降级兜底：路由 Map 未配置时整页跳转，不白屏
+      location.href = router.resolve({ path, query } as any).href;
+      return;
+    }
+    router.addRoute({ path, component: loader });
+  }
+  await router.push({ path, query } as any);
+}
+```
+
+#### 调用侧标准实现（data.ts）
+
+```typescript
+// ✅ 正确：用 navigateHidden
+import { navigateHidden } from "@/util/navigate-hidden";
 
 // 在 createPage() 外部定义，避免每次调用都重新创建
 const FORM_ROUTE = "/aiflow/mmwrCustomerApplyAddForm";
 
 function navigateToForm(query?: Record<string, string>) {
-  const router = envConfig()?.router;
-  if (!router) {
-    ElMessage.error("路由未初始化，请刷新页面重试");
-    return;
-  }
-  const target: any = { path: FORM_ROUTE };
-  if (query) target.query = query;
-  location.href = router.resolve(target).href;
+  navigateHidden(FORM_ROUTE, query);
 }
 
 export function createPage() {
-  // ... 不在 createPage 内部声明 router
   const Page = new (class extends AbstractPageQueryHook {
-    // ...
     toolbarDef(): ActionButtonDesc[] {
       return [
         {
           name: "primary",
           label: "新增申请",
-          onClick: () => navigateToForm()   // 无参：新增
+          onClick: () => navigateToForm()        // 无参：新增
         }
       ];
     }
@@ -328,14 +354,16 @@ export function createPage() {
 }
 ```
 
-> **❌ 禁止**：
-> - `router.push({ path: "/mmwr-xxx-form" })`（kebab-case 路径错误）
-> - 在**菜单可见页面**（如列表页 data.ts 的 `navigateToForm`）中使用 `router.push()`（父壳无法刷新菜单高亮）
+> **✅ 正确做法**：
+> - 跳转隐藏页 → `navigateHidden(path, query?)`（懒注册 + router.push，无刷新，内部兜底防白屏）
+> - 返回上一页 → `useRouter().back()`
 >
-> **✅ 允许**：
-> - `useRouter().back()`（表单页"取消"按钮返回上一页时可用）
+> **❌ 禁止**：
+> - 直接 `router.push({ path: "..." })` — 主应用过滤了 hidden 路由，路由未注册直接 push 会白屏或报 "Invalid route component"
+> - 直接 `location.href = router.resolve(...).href` — 触发整页重载，有加载动画刷新感；`navigateHidden` 内部已兜底，**外部调用侧禁止直接使用**
+> - kebab-case 路径（`/mmwr-xxx-form`）— 路由路径必须是 camelCase
 >
-> ⚠️ **所有前进导航（包括隐藏页→隐藏页）必须用 `location.href`**。`router.push()` 会跳过 shell 的 `generateCurrentRoute`，在 dev 模式下触发 "Invalid route component" 错误（已在 `mmwrCustomerApplyChangeHistory` 实测验证）。
+> ⚠️ **新增隐藏页时必须同步维护 `src/util/navigate-hidden.ts` 的 `HIDDEN_ROUTE_MAP`**，否则 `navigateHidden` 降级为整页刷新，失去无刷新优势。
 
 ---
 

package/files/.github/skills/core/prototype-scan/SKILL.md

@@ -108,6 +108,22 @@ AI 根据提取的信息，内部构建 page-spec JSON（**不输出给用户**
 
 ## 步骤
 
+> ### ⚠️ Axure 原型文件访问前置说明
+>
+> Axure 导出的 HTML 包含一个 `index.html` 入口，但**不能直接用 `open_browser_page(index.html)` 访问**：
+>
+> | 访问方式 | 结果 | 推荐 |
+> |---------|------|------|
+> | `open_browser_page(index.html)` | 被重定向到 `resources/chrome/chrome.html`（扩展安装引导页），侧边栏不渲染 | ❌ 永久不可用 |
+> | `open_browser_page(具体功能页.html)` | 页面内容正常，`read_page` 可读完整 DOM 快照 | ✅ **首选** |
+> | `read_file(xxx.html)` | 直接读 HTML 源码，用正则提取文本/label | ✅ 推荐（补细节用）|
+>
+> **根本原因**：VS Code 集成浏览器是独立 Playwright/Chromium 进程，**不加载用户 Chrome 的任何扩展**，即使用户本地已安装 Axure RP 扩展也无效。此行为不随环境变化。
+>
+> **补充**：浏览器面板显示 `(not visible)` 仅表示该标签不在前台，不代表无法访问，`screenshot_page`/`read_page` 照样可用。
+>
+> **菜单树**应从 `系统整体框架.html`（或类似全局框架页）的 DOM 文本节点提取，不依赖侧边栏渲染。
+
 ### 1. 全量扫描 HTML
 
 遍历所有 `.html` 文件，提取：

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.5.0",
-  "description": "AI Skill 模板包 v2.5.0 — 13 条编码规范 + 9 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
+  "version": "2.5.2",
+  "description": "AI Skill 模板包 v2.5.2 — 13 条编码规范 + 9 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
     "wl-skills": "bin/wl-skills.js"
@@ -28,6 +28,9 @@
   ],
   "author": "JHLC Frontend Team",
   "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ChenyCHENYU/wl-skills-kit.git"
@@ -67,4 +70,4 @@
       "eslint --fix --no-cache"
     ]
   }
-}
+}