@agile-team/wl-skills-kit 2.11.0 → 2.11.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [2.11.1] - 2026-06-15
+
+### Added
+
+- **page-spec 落盘 + spec-align 确定性比对（S1~S5）**：新增 `lib/page-spec.js` 引擎，把"按原型精准实现"从 AI 自觉升级为代码卡控。page-codegen 生成时落盘 `page-spec.json`（单一真值），`validate` 自动比对 `data.ts` 实际实现：
+  - S1 查询字段顺序（warn）/ S2 表格列顺序与集合（error）/ S3 工具栏按钮顺序·集合·颜色（error）/ S4 操作列按钮严格对应（error）/ S5 按钮·列 label 文字保真（warn）
+  - 同步接入 MCP `wls_validate_page`，CLI 与 MCP 双通道一致
+  - 新增 `.wl-skills/docs/page-spec-schema.md` 字段规范
+- **`wl-skills fix` 确定性机械修复（F1~F5）**：新增 `lib/safe-fix.js`，对幂等零语义偏差自动修复——BaseTable 补 `render-type="agGrid"`、`::v-deep`/`/deep/` → `:deep()`、行尾空白、文件末尾换行；支持 `--dry-run` 预览。语义级偏差仍交 AI/人工
+- **规则覆盖矩阵治理**：新增 `kit-internal/rule-coverage.md`，登记每条约定的执行器（R*/S*/regex/AI）；`lint-skills.js` 校验标记「阻断」的规则必须有确定性执行器，防止"文档约定"退化
+
+### Changed
+
+- **C_Splitter 彻底删除**：从 kit 移除 `C_Splitter` 组件（`onMounted` 冻结 vnode 导致响应式失效的 bug 写法），`lint-skills` 全量禁止 `<C_Splitter>` / `import C_Splitter`（无任何例外），standards/14 更新为"已删除"
+- page-codegen SKILL.md 新增"生成时落盘 page-spec.json + 自检跑 spec-align"硬约束
+- **维护链路统一 pnpm-first**：新增 `packageManager: pnpm@11.5.3`、`pnpm-lock.yaml`、`pnpm verify` / `pnpm ci`，删除 `package-lock.json`；npm 仅保留在 `npm pack` / `npm publish` 发版环节
+- **导出依赖安全替换**：`wl-skills export` 从存在高危漏洞的 `xlsx@0.18.5` 迁移到 `write-excel-file`，并将运行时 Node 基线提升到 `>=18`
+
+### Fixed
+
+- 修复 `scripts/verify-version.js` / `scripts/sync-version.js` / `scripts/lint-skills.js` 仍指向旧版 `.github/` 路径导致 v2.11 后完全失效的问题（统一迁移到 `.wl-skills/`）
+- 清理仓库根残留的旧版 `.wl-skills-manifest.json`（v2.6.0）
+- 移除仓库 `.npmrc` 中误提交的 npm token，仅保留 registry 配置；本地私密 npmrc 已加入 ignore
+- 修复 `export` 仍读取旧 `.github/reports` 的迁移漏点，现优先读取 `.wl-skills/reports` 并兼容旧目录
+
 ## [2.11.0] - 2026-06-14
 
 ### Changed
@@ -14,7 +39,7 @@
 
 ### Migration
 
-- 已安装 v2.10.x 的项目执行 `npx @agile-team/wl-skills-kit@latest update` 即可自动迁移
+- 已安装 v2.10.x 的项目执行 `pnpm dlx @agile-team/wl-skills-kit@latest update` 即可自动迁移
 - 旧版 `.github/skills/`、`.github/standards/`、`.github/guides/`、`.github/reports/` 目录将被自动清理
 - `.github/copilot-instructions.md` 自动替换为薄壳入口
 
@@ -89,7 +114,7 @@
 ### Notes
 
 - 测试矩阵：cli + lint-skills + doctor-ui + registry + version-tools 合计 **53 测试通过**
-- 升级路径：`npx @agile-team/wl-skills-kit@latest update` 同步 standards/14；CI 增挂 `wl-skills doctor-ui` 即可
+- 升级路径：`pnpm dlx @agile-team/wl-skills-kit@latest update` 同步 standards/14；CI 增挂 `wl-skills doctor-ui` 即可
 
 ## [2.9.1] - 2026-05-17
 
@@ -191,7 +216,7 @@
 
 ### Notes
 
-- 纯文档 + MCP 运行时增强，无 SDK 行为破坏性变更，业务项目 `npx @agile-team/wl-skills-kit update` 即可同步。
+- 纯文档 + MCP 运行时增强，无 SDK 行为破坏性变更，业务项目 `pnpm dlx @agile-team/wl-skills-kit update` 即可同步。
 
 ## [2.7.1] - 2026-05-13
 
@@ -212,7 +237,7 @@
 
 ### Notes
 
-- 纯文档修正，无功能变更，业务项目 `npx @agile-team/wl-skills-kit update` 即可同步最新文档
+- 纯文档修正，无功能变更，业务项目 `pnpm dlx @agile-team/wl-skills-kit update` 即可同步最新文档
 
 ## [2.7.0] - 2026-05-12
 
@@ -220,7 +245,7 @@
 
 - **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" 数字一致。
+- **版本一致性自检脚本**：新增 `scripts/verify-version.js`（`pnpm 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 文档结构一致。
@@ -234,10 +259,10 @@
 
 ### Notes
 
-- 业务项目升级 `npx @agile-team/wl-skills-kit update` 即可，无破坏性变更。
+- 业务项目升级 `pnpm dlx @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 可直接接入。
+- 验证：`pnpm version:verify && pnpm test` 应全绿，CI 可直接接入。
 
 ## [2.6.0] - 2026-05-12
 
@@ -303,7 +328,7 @@
 ### Added
 
 - CLI 安装完成后新增 `@agile-team/wk-skills-ui` 可选桥接提醒，保持两包独立分工、不强耦合
-- 新增 `standards:init` 脚本，统一指向 `npx @robot-admin/git-standards init`
+- 新增 `standards:init` 脚本，统一指向 `pnpm dlx @robot-admin/git-standards init`
 - README 补充 wk-skills-ui 可选桥接说明与规范插件入口
 
 ## [2.4.0] - 2026-05-02
@@ -689,7 +714,7 @@
 
 ### 迁移指南（从 v1.x 升级）
 
-执行 `npx @agile-team/wl-skills-kit@latest update` 即可。注意：
+执行 `pnpm dlx @agile-team/wl-skills-kit@latest update` 即可。注意：
 
 1. 老的 `docs/SYS_MENU_INFO.md` 需手动迁移到 `reports/SYS_MENU_INFO.md`
 2. 老的 `docs/menu-sync-design.md` / `docs/wl-skills-kit.md` 已删除，相关内容见 `guides/architecture.md`

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.11.0** — 一键将 14 条规范、11 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.11.1** — 一键将 14 条规范、11 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -9,9 +9,9 @@
 ## TL;DR
 
 ```bash
-npx @robot-admin/git-standards init      # 工程化前置（必须）
-npx @agile-team/wl-skills-kit            # 安装 AI 体系
-npm run standards:init                   # 本包维护/业务项目均可复用的规范插件入口
+pnpm dlx @robot-admin/git-standards init      # 工程化前置（必须）
+pnpm dlx @agile-team/wl-skills-kit            # 安装 AI 体系
+pnpm standards:init                           # 本包维护/业务项目均可复用的规范插件入口
 # 在 AI 对话中：
 "扫描 docs/prototypes/ 下的原型生成页面清单"
 "基于上一步生成所有 api.md，再 codegen 出页面"
@@ -19,10 +19,20 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 > 可选桥接：如业务项目也需要统一 UI 风格、老系统化妆层和 UI 扫描修复，可单独安装 `@agile-team/wk-skills-ui`。两包职责独立，不互相强依赖：`wl-skills-kit` 负责编码规范/页面生成/菜单字典权限，`wk-skills-ui` 负责视觉一致性/设计令牌/化妆层/Runtime 渲染。
 
+> 包管理策略：本仓库维护链路 **pnpm-first**，使用 `pnpm-lock.yaml`、`pnpm verify`、`pnpm ci`；npm 只用于 `npm pack` / `npm publish` 发版环节，不提交 `package-lock.json` 和 npm token。
+
 ---
 
 ## 版本亮点
 
+**v2.11.1**：精准卡控闭环 —— 把"约定"接线到确定性执行器，生成即精确。
+
+- **新增 page-spec 落盘 + spec-align 确定性比对（S1~S5）**：`page-codegen` 生成页面时同步写出 `page-spec.json`（原型约定真值），`validate` 用 AST 解析 `data.ts` 的 `queryDef/columnsDef/toolbarDef` 与之逐项比对——查询字段顺序、表格列顺序、工具栏按钮顺序与颜色、操作列按钮集合、label 文字保真。过去只靠 AI 自觉的 6 条"精准实现"约定，现在变成可阻断的硬卡控
+- **新增 `wl-skills fix` 确定性机械修复**：对幂等、零语义判断的偏差（BaseTable 补 `render-type`、`::v-deep`→`:deep()`、行尾空白、文件末尾换行）做确定性自动修复，AI 只处理需语义判断的部分；`--dry-run` 预览
+- **新增「规则 → 执行器」覆盖矩阵治理**：`kit-internal/rule-coverage.md` 登记每条约定由谁兜底（R*/S*/regex/AI），`lint:skills` 校验标记「阻断」的规则必须有真实执行器，杜绝"文档约定"退化为纯文档
+- **C_Splitter 彻底删除**：废弃组件（onMounted 冻 vnode 致响应式失效）从包内移除，`lint:skills` 全量禁止任何引用，无例外
+- **修复 v2.11 目录迁移遗留**：`lint-skills.js` / `verify-version.js` / `sync-version.js` 的 `.github/` 路径全部修正为 `.wl-skills/`，CI 自检链路恢复可用
+
 **v2.8.0**：Mock 架构体系固化 + `mock-clean` CLI 命令。
 
 - 新增 `docs/mock-architecture.md` — Mock 目录约定、开关机制、模块化规范、一键清理流程
@@ -45,7 +55,7 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 - 新增 `skills/sync/_mcp-guardrail.md` 公共护栏（含 L0~L4 错误自愈剧本，MCP 失败时引导用户完善 `env.local.json` 而不是绕开自拼 HTTP）
 - 修复 `dict-sync/SKILL.md` 旧版残留与错路径；统一 `menu-sync/USAGE.md` 字段命名
 - MCP server 启动 banner（stderr，不污染 JSON-RPC）；client.js 401/4004 友好提示
-- 新增 `npm run lint:skills` 静态护栏，已串入 `prepublishOnly`
+- 新增 `pnpm lint:skills` 静态护栏，已串入 `prepublishOnly`
 
 **v2.7.1**：JH 组件文档全面修正，基于 `@jhlc/common-core` 源码校准 Props/API/映射规则。
 
@@ -56,9 +66,9 @@ npm run standards:init                   # 本包维护/业务项目均可复用
 
 **v2.7.0**：一致性治理与可测性升级，安全防护加固。
 
-- **CLI 未知 flag / 命令防护**：`npx @agile-team/wl-skills-kit --version` 等未识别参数不再默认走 `init` 误装，而是退出非零并提示
+- **CLI 未知 flag / 命令防护**：`pnpm dlx @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`，不一致则阻断发版
+- **版本一致性自检**：`pnpm 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
 
@@ -134,7 +144,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 ├── package.json                          name: @agile-team/wl-skills-kit
 │
 ├── bin/
-│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / validate-page / doctor-ui / export / mock-clean）
+│   └── wl-skills.js                      CLI 实现（init / update / clean / check / diff / validate / validate-page / fix / doctor-ui / export / mock-clean）
 │
 ├── files/                                ★★★ 真正会被打包并复制到业务项目的内容 ★★★
 │   ├── .github/
@@ -167,7 +177,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 > - 多 AI 编辑器适配要改 → 改 `files/.wl-skills/skills/_compat/`（**不是**改业务项目里的根配置文件）
 > - 维护文档要写 → 进 `kit-internal/`（不会污染业务项目）
 
-### B. 业务项目结构（执行 `npx @agile-team/wl-skills-kit` 之后）
+### B. 业务项目结构（执行 `pnpm dlx @agile-team/wl-skills-kit` 之后）
 
 ```
 你的业务项目/
@@ -240,43 +250,51 @@ wl-skills-kit/                            ← 你正看的这个仓库
 
 ```bash
 # 全量安装（默认）
-npx @agile-team/wl-skills-kit
+pnpm dlx @agile-team/wl-skills-kit
 
 # 增量更新（仅覆盖有变化的文件，自动保护 reports/）
-npx @agile-team/wl-skills-kit update
+pnpm dlx @agile-team/wl-skills-kit update
 
 # 环境预检（Node / 工具链 / MCP 配置 / manifest）
-npx @agile-team/wl-skills-kit check
+pnpm dlx @agile-team/wl-skills-kit check
 
 # 对比已安装文件与当前 kit 版本差异
-npx @agile-team/wl-skills-kit diff
+pnpm dlx @agile-team/wl-skills-kit diff
 
 # 静态检查 src/views 页面文件完整性 + AGGrid/cid/skills-ui/mock
-npx @agile-team/wl-skills-kit validate
+pnpm dlx @agile-team/wl-skills-kit validate
 
 # 单页/指定目录校验
-npx @agile-team/wl-skills-kit validate-page src/views/mdata/model/mdata-model-config
+pnpm dlx @agile-team/wl-skills-kit validate-page src/views/mdata/model/mdata-model-config
+
+# spec-align：页面目录存在 page-spec.json 时，确定性比对"约定 vs 代码"
+# （查询字段/表格列顺序、工具栏按钮顺序与颜色、操作列严格对应、label 保真）
+# 已内置于 validate，无需额外参数
+
+# 确定性机械修复（缺 render-type、::v-deep→:deep、行尾空白等，幂等安全）
+pnpm dlx @agile-team/wl-skills-kit fix
+pnpm dlx @agile-team/wl-skills-kit fix --dry-run
 
 # 检查 wk-skills-ui 是否真正接入
-npx @agile-team/wl-skills-kit doctor-ui
+pnpm dlx @agile-team/wl-skills-kit doctor-ui
 
 # 导出菜单/字典/权限基线为 xlsx
-npx @agile-team/wl-skills-kit export
+pnpm dlx @agile-team/wl-skills-kit export
 
 # 构建前清理（保留 src/components + src/types）
-npx @agile-team/wl-skills-kit clean
+pnpm dlx @agile-team/wl-skills-kit clean
 
 # 清理但保留 reports/（菜单/字典/权限累积数据）
-npx @agile-team/wl-skills-kit clean --keep-reports
+pnpm dlx @agile-team/wl-skills-kit clean --keep-reports
 
 # 清理指定业务域的 mock 文件（保留 _utils.ts）
-npx @agile-team/wl-skills-kit mock-clean --domain mdata
+pnpm dlx @agile-team/wl-skills-kit mock-clean --domain mdata
 
 # 清理全部 mock（保留 _utils.ts）
-npx @agile-team/wl-skills-kit mock-clean --all
+pnpm dlx @agile-team/wl-skills-kit mock-clean --all
 
 # 任何命令都可加 --dry-run 预览
-npx @agile-team/wl-skills-kit update --dry-run
+pnpm dlx @agile-team/wl-skills-kit update --dry-run
 ```
 
 > 全局安装后也可直接用 `wl-skills` 命令（如 `wl-skills update`）。
@@ -313,7 +331,7 @@ npx @agile-team/wl-skills-kit update --dry-run
 
 ```bash
 # 执行增量更新即可
-npx @agile-team/wl-skills-kit update
+pnpm dlx @agile-team/wl-skills-kit update
 ```
 
 `update` 命令会自动完成：

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.11.0
+ * wl-skills-kit CLI v2.11.1
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -29,6 +29,12 @@ const {
   hasAstAvailable,
 } = require("../lib/ast-rules");
 
+// ─── page-spec 比对引擎（v2.11.1+，"约定 vs 代码"确定性核对）────────────
+const { alignPage } = require("../lib/page-spec");
+
+// ─── 安全修复引擎（v2.11.1+，确定性机械修复 F1~F5）────────────────────────
+const { runSafeFix } = require("../lib/safe-fix");
+
 const FILES_DIR = path.resolve(__dirname, "..", "files");
 const TARGET_DIR = process.cwd();
 const MANIFEST_NAME = ".wl-skills-manifest.json";
@@ -48,6 +54,7 @@ const KNOWN_COMMANDS = new Set([
   "doctor-ui",
   "export",
   "mock-clean",
+  "fix",
 ]);
 const KNOWN_FLAGS = new Set([
   "--dry-run",
@@ -102,7 +109,7 @@ if (showHelp) {
   wl-skills-kit v${PKG.version} — AI Skill 模板包
 
   用法:
-    npx @agile-team/wl-skills-kit [命令] [选项]
+    pnpm dlx @agile-team/wl-skills-kit [命令] [选项]
 
   命令:
     init       全量安装模板文件到当前项目（默认）
@@ -116,6 +123,7 @@ if (showHelp) {
     doctor-ui  检查 @agile-team/wk-skills-ui 接入完整性
     export     导出 reports/SYS_* 数据为 xlsx
     mock-clean 清理 mock 文件（按域或全部），保留 _utils.ts
+    fix        确定性机械修复（agGrid/:deep/未用 import 等），AI 无关
 
   选项:
     --dry-run        预览模式，不实际写入/删除任何文件
@@ -128,21 +136,21 @@ if (showHelp) {
     --help           显示帮助
 
   示例:
-    npx @agile-team/wl-skills-kit                       安装全量文件
-    npx @agile-team/wl-skills-kit update                仅更新有变化的文件
-    npx @agile-team/wl-skills-kit update --force        强制更新（忽略同版本检测）
-    npx @agile-team/wl-skills-kit check                 检查本地环境
-    npx @agile-team/wl-skills-kit diff                  查看当前项目与最新 kit 差异
-    npx @agile-team/wl-skills-kit validate              检查 src/views 页面文件
-    npx @agile-team/wl-skills-kit validate-page src/views/mdata/model/demo
-    npx @agile-team/wl-skills-kit doctor-ui             检查 wk-skills-ui 接入
-    npx @agile-team/wl-skills-kit export                导出菜单/字典/权限 xlsx
-    npx @agile-team/wl-skills-kit clean                 清理开发期文件
-    npx @agile-team/wl-skills-kit clean --keep-reports  保留 reports/中的菜单/字典数据
-    npx @agile-team/wl-skills-kit clean --dry-run       预览将要清理哪些文件
-    npx @agile-team/wl-skills-kit mock-clean --domain mdata  清理 mdata 域 mock
-    npx @agile-team/wl-skills-kit mock-clean --all           清理全部 mock
-    npx @agile-team/wl-skills-kit mock-clean --all --dry-run 预览将要清理的 mock 文件
+    pnpm dlx @agile-team/wl-skills-kit                       安装全量文件
+    pnpm dlx @agile-team/wl-skills-kit update                仅更新有变化的文件
+    pnpm dlx @agile-team/wl-skills-kit update --force        强制更新（忽略同版本检测）
+    pnpm dlx @agile-team/wl-skills-kit check                 检查本地环境
+    pnpm dlx @agile-team/wl-skills-kit diff                  查看当前项目与最新 kit 差异
+    pnpm dlx @agile-team/wl-skills-kit validate              检查 src/views 页面文件
+    pnpm dlx @agile-team/wl-skills-kit validate-page src/views/mdata/model/demo
+    pnpm dlx @agile-team/wl-skills-kit doctor-ui             检查 wk-skills-ui 接入
+    pnpm dlx @agile-team/wl-skills-kit export                导出菜单/字典/权限 xlsx
+    pnpm dlx @agile-team/wl-skills-kit clean                 清理开发期文件
+    pnpm dlx @agile-team/wl-skills-kit clean --keep-reports  保留 reports/中的菜单/字典数据
+    pnpm dlx @agile-team/wl-skills-kit clean --dry-run       预览将要清理哪些文件
+    pnpm dlx @agile-team/wl-skills-kit mock-clean --domain mdata  清理 mdata 域 mock
+    pnpm dlx @agile-team/wl-skills-kit mock-clean --all           清理全部 mock
+    pnpm dlx @agile-team/wl-skills-kit mock-clean --all --dry-run 预览将要清理的 mock 文件
 
   保护路径（init / update 不覆盖已存在的）:
     .wl-skills/reports/   AI 生成报告（团队累积数据，存在则跳过）
@@ -297,7 +305,7 @@ const LEGACY_DIR_PREFIXES = [
 
 const AUTO_HEADER_NOTE =
   "<!-- 由 @agile-team/wl-skills-kit 自动生成。薄壳入口 → .wl-skills/copilot-instructions-full.md -->\n" +
-  "<!-- 请勿手动编辑本文件，更新时重新执行：npx @agile-team/wl-skills-kit@latest update -->\n\n";
+  "<!-- 请勿手动编辑本文件，更新时重新执行：pnpm dlx @agile-team/wl-skills-kit@latest update -->\n\n";
 
 function getEditorConfigs(raw) {
   // v2.11+: _compat 目录已迁移到 .wl-skills/skills/_compat/
@@ -375,7 +383,7 @@ function runInstall(incremental) {
     if (oldManifest.version === PKG.version) {
       console.log("  ✔ 当前项目已安装 v" + PKG.version + "，无需重复操作");
       console.log(
-        "    如需强制重装：npx @agile-team/wl-skills-kit@latest " +
+        "    如需强制重装：pnpm dlx @agile-team/wl-skills-kit@latest " +
           label +
           " --force",
       );
@@ -604,7 +612,7 @@ function runInstall(incremental) {
     );
   }
   console.log(
-    "  ℹ 规范插件：建议执行 npx @robot-admin/git-standards init 接入代码质量与提交规范。",
+    "  ℹ 规范插件：建议执行 pnpm dlx @robot-admin/git-standards init 接入代码质量与提交规范。",
   );
   console.log("");
 
@@ -622,7 +630,7 @@ function runInstall(incremental) {
  * 3. 如果存在且已含但格式过旧 → 刷新为最新格式
  * 4. 如果存在且格式最新 → 跳过
  *
- * hook 使用 npx 动态解析，避免硬编码 node_modules 路径在 pnpm 下失效。
+ * hook 使用包管理器动态解析，避免硬编码 node_modules 路径在 pnpm 下失效。
  * 包含存在性守卫：kit 未安装时优雅跳过，不阻断提交。
  */
 function ensurePreCommitHook(targetDir) {
@@ -737,7 +745,7 @@ function runClean() {
   const manifest = readManifest();
   if (!manifest) {
     console.log("  ⚠ 未找到 " + MANIFEST_NAME);
-    console.log("  请先执行 npx @agile-team/wl-skills-kit init 安装一次。");
+    console.log("  请先执行 pnpm dlx @agile-team/wl-skills-kit init 安装一次。");
     console.log("");
     process.exit(1);
   }
@@ -1253,8 +1261,24 @@ function runValidate() {
   // 合并 AST 结果（降级和正常都 push）
   issues.push(...astResult.issues);
 
+  // ── page-spec 比对（v2.11.1+，"约定 vs 代码"确定性核对 S1~S5）───────
+  // 页面目录存在 page-spec.json 时，比对 data.ts 实际实现与原型约定真值。
+  // 无 page-spec.json 的页面静默跳过，不影响其他检查。
+  let specAlignedPages = 0;
+  for (const page of pages) {
+    const absDir = path.join(TARGET_DIR, page.dir);
+    const { issues: specIssues, hasSpec } = alignPage(absDir, page.dir);
+    if (hasSpec) specAlignedPages++;
+    issues.push(...specIssues);
+  }
+
   // ── 输出 ───────────────────────────────────────────────────────────
-  console.log("  页面目录: " + pages.length + (astResult.pages ? "（AST 扫描 " + astResult.pages + "）" : ""));
+  console.log(
+    "  页面目录: " +
+      pages.length +
+      (astResult.pages ? "（AST 扫描 " + astResult.pages + "）" : "") +
+      (specAlignedPages ? "（spec-align " + specAlignedPages + "）" : ""),
+  );
   console.log("  提示项: " + issues.length);
   console.log("");
   const errors = issues.filter((issue) => issue.level === "error").length;
@@ -1360,6 +1384,12 @@ const AST_FIX_SUGGESTIONS = {
   R10: { fix: '\u66ff\u6362\u539f\u751f el-* \u7ec4\u4ef6\u4e3a\u5e73\u53f0\u5c01\u88c5\uff08jh-select/jh-date/jh-pagination \u7b49\uff09', ref: 'standards/13-platform-components.md', auto: true },
   R11: { fix: '\u4ece data.ts \u4e2d\u79fb\u9664 Pinia Store import\uff0cStore \u5e94\u5728\u7ec4\u4ef6\u5c42\u4f7f\u7528', ref: 'standards/10-pinia.md', auto: true },
   R12: { fix: '\u5c06\u786c\u7f16\u7801 IP/URL \u79fb\u81f3 .env.* \u73af\u5883\u53d8\u91cf', ref: 'standards/07-config.md', auto: true },
+  // S 系列：page-spec 约定 vs 代码确定性核对（v2.11.1+）
+  S0: { fix: '\u4fee\u6b63 page-spec.json \u7ed3\u6784\uff08page/query/columns/toolbar/operations\uff09', ref: '.wl-skills/skills/core/page-codegen/SKILL.md', auto: false },
+  S1: { fix: '\u8c03\u6574 queryDef() \u67e5\u8be2\u5b57\u6bb5\u987a\u5e8f\u4e0e page-spec.json query \u4e25\u683c\u4e00\u81f4', ref: '.wl-skills/skills/core/page-codegen/SKILL.md', auto: true },
+  S2: { fix: '\u8c03\u6574 columnsDef() \u8868\u683c\u5217\u987a\u5e8f/\u96c6\u5408\u4e0e page-spec.json columns \u4e25\u683c\u4e00\u81f4', ref: '.wl-skills/skills/core/page-codegen/SKILL.md', auto: true },
+  S3: { fix: '\u8c03\u6574 toolbarDef() \u6309\u94ae\u987a\u5e8f/\u989c\u8272\u4e0e page-spec.json toolbar \u4e25\u683c\u4e00\u81f4', ref: '.wl-skills/skills/core/page-codegen/SKILL.md', auto: true },
+  S4: { fix: '\u64cd\u4f5c\u5217\u6309\u94ae\u4e0e page-spec.json operations \u4e25\u683c\u5bf9\u5e94\uff0c\u4e0d\u591a\u4e0d\u5c11', ref: '.wl-skills/skills/core/page-codegen/SKILL.md', auto: true },
 };
 
 function printFixSuggestions(blockingIssues) {
@@ -1595,13 +1625,18 @@ function parseMarkdownTable(content) {
     );
 }
 
-function runExport() {
+async function runExport() {
   console.log("");
   console.log("  wl-skills-kit v" + PKG.version + "  [export]");
   console.log("  目标目录: " + TARGET_DIR);
   console.log("");
 
-  const reportDir = path.join(TARGET_DIR, ".github", "reports");
+  const reportDir =
+    [
+      path.join(TARGET_DIR, ".wl-skills", "reports"),
+      path.join(TARGET_DIR, ".github", "reports"),
+    ].find((dir) => fs.existsSync(dir)) ||
+    path.join(TARGET_DIR, ".wl-skills", "reports");
   const files = [
     ["菜单", "SYS_MENU_INFO.md"],
     ["字典", "SYS_DICT_INFO.md"],
@@ -1636,25 +1671,22 @@ function runExport() {
     console.log("  将导出: " + outFile);
     console.log("  sheet 数: " + addedSheets);
   } else {
-    let XLSX;
+    let writeXlsxFile;
     try {
-      XLSX = require("xlsx");
+      writeXlsxFile = require("write-excel-file/node");
     } catch {
       console.error(
-        "  ✖ 未找到 xlsx 依赖，请重新安装最新 @agile-team/wl-skills-kit",
+        "  ✖ 未找到 write-excel-file 依赖，请重新安装最新 @agile-team/wl-skills-kit",
       );
       process.exit(1);
     }
-    const wb = XLSX.utils.book_new();
-    for (const [sheetName, rows] of sheets) {
-      XLSX.utils.book_append_sheet(
-        wb,
-        XLSX.utils.aoa_to_sheet(rows),
-        sheetName,
-      );
-    }
     fs.mkdirSync(outDir, { recursive: true });
-    XLSX.writeFile(wb, outFile);
+    await writeXlsxFile(
+      sheets.map(([sheetName, rows]) => ({
+        sheet: sheetName,
+        data: rows,
+      })),
+    ).toFile(outFile);
     console.log("  ✔ 已导出: " + outFile);
     console.log("  sheet 数: " + addedSheets);
   }
@@ -1742,6 +1774,38 @@ function runMockClean() {
 
 // ─── 主路由 ─────────────────────────────────────────────────────────────
 
+// ─── 命令: fix（确定性机械修复）──────────────────────────────────────────
+
+function runFix() {
+  const scanPath =
+    args.find((a) => !a.startsWith("-") && a !== command) || "src/views";
+  console.log("");
+  console.log("  wl-skills-kit v" + PKG.version + "  [fix]" + (dryRun ? "  [dry-run]" : ""));
+  console.log("  扫描目录: " + scanPath);
+  console.log("");
+
+  const result = runSafeFix(TARGET_DIR, scanPath, { dryRun });
+  if (result.files.length === 0) {
+    console.log("  ✔ 未发现可自动修复的机械偏差");
+    console.log("");
+    return;
+  }
+  for (const f of result.files) {
+    for (const change of f.changes) {
+      console.log("  " + (dryRun ? "将修复" : "已修复") + "  " + f.rel + " — " + change);
+    }
+  }
+  console.log("");
+  console.log(
+    "  " + (dryRun ? "预览" : "完成") + "：" + result.fixedCount + " 处机械修复，涉及 " + result.files.length + " 个文件",
+  );
+  if (!dryRun) {
+    console.log("");
+    console.log("  → 建议执行 wl-skills validate 复扫确认；语义级偏差仍需 AI 或人工处理");
+  }
+  console.log("");
+}
+
 switch (command) {
   case "init":
     runInstall(false);
@@ -1766,11 +1830,17 @@ switch (command) {
     runDoctorUi();
     break;
   case "export":
-    runExport();
+    runExport().catch((e) => {
+      console.error("  ✖ 导出失败: " + (e && e.message ? e.message : e));
+      process.exit(1);
+    });
     break;
   case "mock-clean":
     runMockClean();
     break;
+  case "fix":
+    runFix();
+    break;
   default:
     console.error(
       '  ✖ 未知命令: "' + command + '"，请使用 --help 查看可用命令',

package/docs/agent-pipeline-runbook.md

@@ -136,9 +136,9 @@ page-codegen 产出 SYS_* 报告
 ### 本地页面质量
 
 ```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
+pnpm dlx @agile-team/wl-skills-kit validate
+pnpm dlx @agile-team/wl-skills-kit validate-page src/views/xxx/yyy
+pnpm dlx @agile-team/wl-skills-kit doctor-ui
 ```
 
 ### MCP 项目感知

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

@@ -132,9 +132,9 @@ prototype-scan
 ### Step 1：安装与环境预检
 
 ```bash
-npx @robot-admin/git-standards init
-npx @agile-team/wl-skills-kit@latest
-npx @agile-team/wl-skills-kit@latest check
+pnpm dlx @robot-admin/git-standards init
+pnpm dlx @agile-team/wl-skills-kit@latest
+pnpm dlx @agile-team/wl-skills-kit@latest check
 ```
 
 检查点：
@@ -224,7 +224,7 @@ Agent 完成任一 Skill 后，必须输出：
 建议组合：
 
 ```bash
-npx @agile-team/wl-skills-kit@latest validate
+pnpm dlx @agile-team/wl-skills-kit@latest validate
 ```
 
 MCP 验证：