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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.1** — 一键将 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` 覆盖安装、升级、对比、清理、体检、页面完整性检查和基线导出
 - 页面模板升级为 `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 规则文件

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,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "AI Skill 模板包 v2.5.0 — 13 条编码规范 + 9 个 AI Skill + 17 个 MCP Tool，一条命令导入 Vue 3 项目",
   "main": "./bin/wl-skills.js",
   "bin": {
@@ -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"