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

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.10.1
+ * 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,10 +123,11 @@ 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        预览模式，不实际写入/删除任何文件
-    --keep-reports   clean 命令保留 .github/reports/（默认一起删除）
+    --keep-reports   clean 命令保留 .wl-skills/reports/（默认一起删除）
     --force          强制执行，跳过同版本检测（忽略已安装状态）
     --domain <name>  mock-clean 指定要清理的业务域（如 sale、mdata）
     --all            mock-clean 清理全部 mock（保留 _utils.ts）
@@ -128,24 +136,24 @@ 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 不覆盖已存在的）:
-    .github/reports/   AI 生成报告（团队累积数据，存在则跳过）
+    .wl-skills/reports/   AI 生成报告（团队累积数据，存在则跳过）
 
   清理保护路径（clean 不删除）:
     src/components/    通用组件（被业务页面 import，构建必需）
@@ -246,20 +254,20 @@ function writeManifest(data) {
 }
 
 // 受保护路径（clean 不删除）
-const PROTECTED_PREFIXES = ["src/components/", "src/types/"];
+const PROTECTED_PREFIXES = ["src/components/", "src/types/", ".wl-skills/src/components/", ".wl-skills/src/types/"];
 function isProtected(relPath) {
   return PROTECTED_PREFIXES.some((p) => relPath.startsWith(p));
 }
 
 // reports/ 中的 AI 生成报告：init/update 遇到已存在不覆盖（团队累积数据）
 function isReportFile(relPath) {
-  return relPath.startsWith(".github/reports/") && relPath.endsWith(".md");
+  return (relPath.startsWith(".wl-skills/reports/") || relPath.startsWith(".github/reports/")) && relPath.endsWith(".md");
 }
 
 // ─── 旧版遗留路径（v1.x/v2.0 → v2.1 迁移清理）───────────────────────────
 // update 时自动检测并移除，避免旧结构与新结构并存产生歧义。
 const LEGACY_PATHS = [
-  // Skill 目录重组：flat → core/sync/ops 分级（v2.1）
+  // v2.1: Skill 目录重组 flat → core/sync/ops
   ".github/skills/prototype-scan/SKILL.md",
   ".github/skills/api-contract/SKILL.md",
   ".github/skills/page-codegen/SKILL.md",
@@ -275,34 +283,42 @@ const LEGACY_PATHS = [
   ".github/skills/menu-sync/SKILL.md",
   ".github/skills/menu-sync/env/env.local.json",
   ".github/skills/menu-sync/env/guide.md",
-  ".github/skills/convention-extract/SKILL.md", // 已更名为 convention-audit
-  // docs/ 废弃文件：内容已迁移至 guides/ 或 reports/（v2.0）
+  ".github/skills/convention-extract/SKILL.md",
   ".github/docs/menu-sync-design.md",
   ".github/docs/use-skill.md",
   ".github/docs/wl-skills-kit.md",
-  ".github/docs/SYS_MENU_INFO.md", // 已迁移至 reports/
-  // _compat/ 旧说明文件（v2.0 → v2.1 重构为可执行配置层）
+  ".github/docs/SYS_MENU_INFO.md",
   ".github/skills/_compat/ai-model-matrix.md",
   ".github/skills/_compat/editor-setup.md",
 ];
 
+// ─── v2.11 迁移：.github/ → .wl-skills/ 目录重构 ────────────────────────────
+// update 时自动检测旧目录结构并清理
+const LEGACY_DIR_PREFIXES = [
+  ".github/skills/",
+  ".github/standards/",
+  ".github/guides/",
+  ".github/reports/",
+];
+
 // ─── 编辑器配置生成（从 _compat/editors.json 读取，特化 frontmatter 注入）─────
 
 const AUTO_HEADER_NOTE =
-  "<!-- 由 @agile-team/wl-skills-kit 自动生成。源文件：.github/copilot-instructions.md -->\n" +
-  "<!-- 请勿手动编辑本文件，更新时重新执行：npx @agile-team/wl-skills-kit@latest update -->\n\n";
+  "<!-- 由 @agile-team/wl-skills-kit 自动生成。薄壳入口 → .wl-skills/copilot-instructions-full.md -->\n" +
+  "<!-- 请勿手动编辑本文件，更新时重新执行：pnpm dlx @agile-team/wl-skills-kit@latest update -->\n\n";
 
 function getEditorConfigs(raw) {
+  // v2.11+: _compat 目录已迁移到 .wl-skills/skills/_compat/
   const editorsJsonPath = path.join(
     FILES_DIR,
-    ".github",
+    ".wl-skills",
     "skills",
     "_compat",
     "editors.json",
   );
   const headersDir = path.join(
     FILES_DIR,
-    ".github",
+    ".wl-skills",
     "skills",
     "_compat",
     "headers",
@@ -367,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",
       );
@@ -477,6 +493,8 @@ function runInstall(incremental) {
   if (incremental) {
     let migrated = 0;
     if (dryRun) console.log("\n  [Step 3] 旧版遗留文件检查（迁移清理）:\n");
+
+    // v2.1 旧版单文件清理
     for (const legacyRel of LEGACY_PATHS) {
       const legacyFull = path.join(TARGET_DIR, legacyRel);
       if (fs.existsSync(legacyFull)) {
@@ -488,6 +506,28 @@ function runInstall(incremental) {
         migrated++;
       }
     }
+
+    // v2.11 目录重构迁移：.github/skills|standards|guides|reports/ → .wl-skills/
+    for (const prefix of LEGACY_DIR_PREFIXES) {
+      const legacyDir = path.join(TARGET_DIR, prefix);
+      if (fs.existsSync(legacyDir)) {
+        const legacyFiles = walkDir(legacyDir, legacyDir);
+        for (const f of legacyFiles) {
+          const legacyFile = path.join(legacyDir, f);
+          if (dryRun) {
+            console.log("  迁移清理  " + prefix + f + "  (v2.11 目录重构)");
+          } else {
+            removeFileAndEmptyParents(legacyFile);
+          }
+          migrated++;
+        }
+        // 删除空目录
+        if (!dryRun && fs.existsSync(legacyDir)) {
+          try { fs.rmSync(legacyDir, { recursive: true, force: true }); } catch {}
+        }
+      }
+    }
+
     if (!dryRun && migrated > 0) {
       console.log(
         "    迁移: " +
@@ -572,7 +612,7 @@ function runInstall(incremental) {
     );
   }
   console.log(
-    "  ℹ 规范插件：建议执行 npx @robot-admin/git-standards init 接入代码质量与提交规范。",
+    "  ℹ 规范插件：建议执行 pnpm dlx @robot-admin/git-standards init 接入代码质量与提交规范。",
   );
   console.log("");
 
@@ -590,7 +630,7 @@ function runInstall(incremental) {
  * 3. 如果存在且已含但格式过旧 → 刷新为最新格式
  * 4. 如果存在且格式最新 → 跳过
  *
- * hook 使用 npx 动态解析，避免硬编码 node_modules 路径在 pnpm 下失效。
+ * hook 使用包管理器动态解析，避免硬编码 node_modules 路径在 pnpm 下失效。
  * 包含存在性守卫：kit 未安装时优雅跳过，不阻断提交。
  */
 function ensurePreCommitHook(targetDir) {
@@ -705,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);
   }
@@ -713,12 +753,12 @@ function runClean() {
   const allFiles = Object.keys(manifest.files);
   const toRemove = allFiles.filter((f) => {
     if (isProtected(f)) return false;
-    if (keepReports && f.startsWith(".github/reports/")) return false;
+    if (keepReports && (f.startsWith(".wl-skills/reports/") || f.startsWith(".github/reports/"))) return false;
     return true;
   });
   const toKeep = allFiles.filter((f) => {
     if (isProtected(f)) return true;
-    if (keepReports && f.startsWith(".github/reports/")) return true;
+    if (keepReports && (f.startsWith(".wl-skills/reports/") || f.startsWith(".github/reports/"))) return true;
     return false;
   });
 
@@ -754,7 +794,7 @@ function runClean() {
       console.log(
         "    保留: " +
           toKeep.length +
-          " 个文件（src/components/ + src/types/ + .github/reports/）",
+          " 个文件（src/components/ + src/types/ + .wl-skills/reports/）",
       );
     } else {
       console.log(
@@ -773,6 +813,7 @@ function expectedManifestFiles() {
   for (const relPath of files) {
     expected[relPath] = fileMd5(path.join(FILES_DIR, relPath));
   }
+  // v2.11+: copilot-instructions.md 是薄壳入口，完整地图在 .wl-skills/
   const instructionsSrc = path.join(
     FILES_DIR,
     ".github",
@@ -1220,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;
@@ -1327,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) {
@@ -1562,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"],
@@ -1603,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);
   }
@@ -1709,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);
@@ -1733,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 验证：