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

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.4.0
+ * wl-skills-kit CLI v2.5.0
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -9,7 +9,9 @@
  *   clean     构建清理（移除 AI 指令/文档/样例，保留组件和类型）
  *   check     环境预检（工具链 / MCP 配置 / manifest）
  *   diff      对比已安装文件与当前 kit 版本
- *   validate  静态检查 src/views 页面文件完整性
+ *   validate  静态检查 src/views 页面文件完整性、AGGrid、skills-ui runtime、mock
+ *   validate-page validate 的别名，适用于单页/目录检查
+ *   doctor-ui 检查 @agile-team/wk-skills-ui 接入完整性
  *   export    导出 SYS_MENU / SYS_DICT / SYS_PERMISSION 为 xlsx
  *   --help    帮助
  *   --dry-run 预览模式（所有命令均支持）
@@ -44,7 +46,9 @@ if (showHelp) {
     clean      构建清理（移除开发期 AI 文件，保留 src/components + src/types）
     check      环境预检（Node / 工具链 / MCP 配置 / manifest）
     diff       对比已安装文件与当前 kit 版本的差异
-    validate   静态检查 src/views 页面文件完整性
+    validate   静态检查 src/views 页面文件、AGGrid、skills-ui runtime、mock
+    validate-page validate 的别名，适用于单页/目录检查
+    doctor-ui  检查 @agile-team/wk-skills-ui 接入完整性
     export     导出 reports/SYS_* 数据为 xlsx
 
   选项:
@@ -60,6 +64,8 @@ if (showHelp) {
     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/中的菜单/字典数据
@@ -143,7 +149,7 @@ function removeFileAndEmptyParents(filePath) {
       } else {
         break;
       }
-    } catch (e) {
+    } catch {
       break;
     }
   }
@@ -154,7 +160,7 @@ function readManifest() {
   if (fs.existsSync(MANIFEST_PATH)) {
     try {
       return JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
-    } catch (e) {
+    } catch {
       return null;
     }
   }
@@ -332,9 +338,11 @@ function runInstall(incremental) {
     if (dryRun) {
       const exists = fs.existsSync(dest);
       console.log("  " + (exists ? "覆盖" : "新增") + "  " + relPath);
-      exists ? updated++ : created++;
+      if (exists) updated++;
+      else created++;
     } else {
-      copyFileSafe(src, dest) === "created" ? created++ : updated++;
+      if (copyFileSafe(src, dest) === "created") created++;
+      else updated++;
     }
   }
 
@@ -372,9 +380,11 @@ function runInstall(incremental) {
         console.log(
           "  " + (ecExists ? "覆盖" : "新增") + "  [编辑器] " + ecPath,
         );
-        ecExists ? updated++ : created++;
+        if (ecExists) updated++;
+        else created++;
       } else {
-        writeFile(ecDest, ecContent) === "created" ? created++ : updated++;
+        if (writeFile(ecDest, ecContent) === "created") created++;
+        else updated++;
       }
     }
   }
@@ -411,6 +421,20 @@ function runInstall(incremental) {
 
   if (!dryRun) writeManifest(newManifest);
 
+  // ── Step 5: 非耦合桥接提醒（不自动安装 wk-skills-ui）───────────────────────
+
+  const targetPkgPath = path.join(TARGET_DIR, "package.json");
+  let hasUiPackage = false;
+  if (fs.existsSync(targetPkgPath)) {
+    try {
+      const targetPkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf8"));
+      const deps = { ...targetPkg.dependencies, ...targetPkg.devDependencies };
+      hasUiPackage = Boolean(deps["@agile-team/wk-skills-ui"]);
+    } catch {
+      hasUiPackage = false;
+    }
+  }
+
   // ── 输出统计 ──────────────────────────────────────────────────────
 
   const total = created + updated + unchanged;
@@ -455,6 +479,19 @@ function runInstall(incremental) {
     }
   }
   console.log("");
+  if (hasUiPackage) {
+    console.log(
+      "  ℹ 检测到 @agile-team/wk-skills-ui：两包独立分工，可组合触发 UI 风格对齐流程。",
+    );
+  } else {
+    console.log(
+      "  ℹ 可选桥接：如需统一 UI 风格/老项目化妆层，可安装 @agile-team/wk-skills-ui。",
+    );
+  }
+  console.log(
+    "  ℹ 规范插件：建议执行 npx @robot-admin/git-standards init 接入代码质量与提交规范。",
+  );
+  console.log("");
 }
 
 // ─── 命令: clean ────────────────────────────────────────────────────────
@@ -537,7 +574,11 @@ function expectedManifestFiles() {
   for (const relPath of files) {
     expected[relPath] = fileMd5(path.join(FILES_DIR, relPath));
   }
-  const instructionsSrc = path.join(FILES_DIR, ".github", "copilot-instructions.md");
+  const instructionsSrc = path.join(
+    FILES_DIR,
+    ".github",
+    "copilot-instructions.md",
+  );
   if (fs.existsSync(instructionsSrc)) {
     const raw = fs.readFileSync(instructionsSrc, "utf8");
     for (const [ecPath, ecContent] of getEditorConfigs(raw)) {
@@ -567,19 +608,34 @@ function runCheck() {
 
   const toolFiles = [".prettierrc.js", "eslint.config.ts", ".husky"];
   for (const rel of toolFiles) {
-    add(rel, fs.existsSync(path.join(TARGET_DIR, rel)), fs.existsSync(path.join(TARGET_DIR, rel)) ? "存在" : "缺失");
+    add(
+      rel,
+      fs.existsSync(path.join(TARGET_DIR, rel)),
+      fs.existsSync(path.join(TARGET_DIR, rel)) ? "存在" : "缺失",
+    );
   }
 
   const manifest = readManifest();
-  add(MANIFEST_NAME, Boolean(manifest), manifest ? "已安装 v" + manifest.version : "未安装");
+  add(
+    MANIFEST_NAME,
+    Boolean(manifest),
+    manifest ? "已安装 v" + manifest.version : "未安装",
+  );
 
-  const envPath = path.join(TARGET_DIR, ".github", "skills", "sync", "env.local.json");
+  const envPath = path.join(
+    TARGET_DIR,
+    ".github",
+    "skills",
+    "sync",
+    "env.local.json",
+  );
   let envOk = false;
   let envDetail = "缺失";
   if (fs.existsSync(envPath)) {
     try {
       const env = JSON.parse(fs.readFileSync(envPath, "utf8"));
-      const gatewayOk = env.gatewayPath && !String(env.gatewayPath).includes("你的网关");
+      const gatewayOk =
+        env.gatewayPath && !String(env.gatewayPath).includes("你的网关");
       const tokenOk = env.token && !String(env.token).includes("Bearer Token");
       envOk = Boolean(gatewayOk && tokenOk);
       envDetail = envOk ? "已填写 gatewayPath/token" : "存在但仍含占位值";
@@ -589,15 +645,33 @@ function runCheck() {
   }
   add("MCP env.local.json", envOk, envDetail);
 
-  const mcpServer = path.join(TARGET_DIR, "node_modules", "@agile-team", "wl-skills-kit", "mcp", "server.js");
-  add("MCP server", fs.existsSync(mcpServer) || fs.existsSync(path.join(__dirname, "..", "mcp", "server.js")), "server.js 可发现");
+  const mcpServer = path.join(
+    TARGET_DIR,
+    "node_modules",
+    "@agile-team",
+    "wl-skills-kit",
+    "mcp",
+    "server.js",
+  );
+  add(
+    "MCP server",
+    fs.existsSync(mcpServer) ||
+      fs.existsSync(path.join(__dirname, "..", "mcp", "server.js")),
+    "server.js 可发现",
+  );
 
   for (const item of checks) {
-    console.log("  " + statusIcon(item.ok) + " " + item.name + " — " + item.detail);
+    console.log(
+      "  " + statusIcon(item.ok) + " " + item.name + " — " + item.detail,
+    );
   }
   const failed = checks.filter((item) => !item.ok).length;
   console.log("");
-  console.log(failed === 0 ? "  ✔ 环境预检通过" : "  ⚠ 环境预检完成，发现 " + failed + " 项需处理");
+  console.log(
+    failed === 0
+      ? "  ✔ 环境预检通过"
+      : "  ⚠ 环境预检完成，发现 " + failed + " 项需处理",
+  );
   console.log("");
   if (failed > 0) process.exitCode = 1;
 }
@@ -633,7 +707,9 @@ function runDiff() {
     }
   }
 
-  console.log("  当前 manifest: " + (manifest ? "v" + manifest.version : "未找到"));
+  console.log(
+    "  当前 manifest: " + (manifest ? "v" + manifest.version : "未找到"),
+  );
   console.log("  最新 kit: v" + PKG.version);
   console.log("  新增/缺失: " + added.length);
   console.log("  内容不同: " + changed.length);
@@ -645,7 +721,8 @@ function runDiff() {
     if (list.length === 0) return;
     console.log("  " + title + "：");
     for (const relPath of list.slice(0, 80)) console.log("    - " + relPath);
-    if (list.length > 80) console.log("    ... 还有 " + (list.length - 80) + " 项");
+    if (list.length > 80)
+      console.log("    ... 还有 " + (list.length - 80) + " 项");
     console.log("");
   }
 
@@ -668,27 +745,53 @@ function scanPageDirs(scanRel) {
   const pages = [];
   for (const [dir, names] of dirs.entries()) {
     if (!names.has("index.vue")) continue;
-    let apiConfigCount = 0;
+    const indexPath = path.join(TARGET_DIR, dir, "index.vue");
+    const indexContent = fs.existsSync(indexPath)
+      ? fs.readFileSync(indexPath, "utf8")
+      : "";
     const dataPath = path.join(TARGET_DIR, dir, "data.ts");
-    if (fs.existsSync(dataPath)) {
-      apiConfigCount = (fs.readFileSync(dataPath, "utf8").match(/API_CONFIG/g) || []).length;
-    }
+    const dataContent = fs.existsSync(dataPath)
+      ? fs.readFileSync(dataPath, "utf8")
+      : "";
+    let apiConfigCount = 0;
+    if (dataContent)
+      apiConfigCount = (dataContent.match(/API_CONFIG/g) || []).length;
     pages.push({
       dir,
       hasDataTs: names.has("data.ts"),
       hasIndexScss: names.has("index.scss"),
       hasApiMd: names.has("api.md"),
       apiConfigCount,
+      baseTableCount: (indexContent.match(/<BaseTable\b/g) || []).length,
+      agGridCount: (indexContent.match(/render-type=["']agGrid["']/g) || [])
+        .length,
+      cidBindCount: (indexContent.match(/\bcid=|:cid=/g) || []).length,
+      hasDefineColumns: /defineColumns\s*\(/.test(dataContent),
+      hasRenderOps: /renderOps\s*\(/.test(dataContent),
+      hasOperationsArray: /operations\s*:/.test(dataContent),
+      hasEmptyOnClick: /onClick\s*:\s*\(\s*[^)]*\s*\)\s*=>\s*\{\s*\}/.test(
+        dataContent,
+      ),
+      apiUrls: Array.from(
+        dataContent.matchAll(/:\s*["']([^"']+\/[^"']+)["']/g),
+      ).map((m) => m[1]),
     });
   }
   return pages.sort((a, b) => a.dir.localeCompare(b.dir));
 }
 
+function findMockFiles() {
+  const mockDir = path.join(TARGET_DIR, "mock");
+  if (!fs.existsSync(mockDir)) return [];
+  return walkDir(mockDir, TARGET_DIR).filter((rel) => /\.(ts|js)$/.test(rel));
+}
+
 function runValidate() {
-  const scanPath = args.find((a) => !a.startsWith("-") && a !== command) || "src/views";
+  const scanPath =
+    args.find((a) => !a.startsWith("-") && a !== command) || "src/views";
   const pages = scanPageDirs(scanPath);
   console.log("");
-  console.log("  wl-skills-kit v" + PKG.version + "  [validate]");
+  console.log("  wl-skills-kit v" + PKG.version + "  [" + command + "]");
   console.log("  扫描目录: " + scanPath);
   console.log("");
 
@@ -700,28 +803,195 @@ function runValidate() {
   }
 
   const issues = [];
+  const mockFiles = findMockFiles();
+  const mockContent = mockFiles
+    .map((rel) => fs.readFileSync(path.join(TARGET_DIR, rel), "utf8"))
+    .join("\n");
   for (const page of pages) {
-    if (!page.hasDataTs) issues.push({ level: "warn", dir: page.dir, text: "缺 data.ts（需结合页面复杂度判断）" });
-    if (!page.hasIndexScss) issues.push({ level: "warn", dir: page.dir, text: "缺 index.scss" });
-    if (page.apiConfigCount > 0 && !page.hasApiMd) issues.push({ level: "warn", dir: page.dir, text: "检测到 API_CONFIG 但缺 api.md" });
+    if (!page.hasDataTs)
+      issues.push({
+        level: "warn",
+        dir: page.dir,
+        text: "缺 data.ts（需结合页面复杂度判断）",
+      });
+    if (!page.hasIndexScss)
+      issues.push({ level: "warn", dir: page.dir, text: "缺 index.scss" });
+    if (page.apiConfigCount > 0 && !page.hasApiMd)
+      issues.push({
+        level: "warn",
+        dir: page.dir,
+        text: "检测到 API_CONFIG 但缺 api.md",
+      });
+    if (page.baseTableCount > 0 && page.agGridCount < page.baseTableCount)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: 'BaseTable 必须显式 render-type="agGrid"',
+      });
+    if (page.baseTableCount > 0 && page.cidBindCount < page.baseTableCount)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "BaseTable 必须配置全局唯一 cid / :cid",
+      });
+    if (page.hasDataTs && page.baseTableCount > 0 && !page.hasDefineColumns)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "表格列必须使用 wk-skills-ui defineColumns()",
+      });
+    if (page.hasOperationsArray)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "操作列禁止 operations 数组，必须使用 defaultSlot + renderOps()",
+      });
+    if (
+      page.hasDataTs &&
+      page.baseTableCount > 0 &&
+      !page.hasRenderOps &&
+      /操作|_action/.test(
+        fs.readFileSync(path.join(TARGET_DIR, page.dir, "data.ts"), "utf8"),
+      )
+    )
+      issues.push({
+        level: "warn",
+        dir: page.dir,
+        text: "疑似存在操作列但未使用 renderOps()",
+      });
+    if (page.hasEmptyOnClick)
+      issues.push({
+        level: "error",
+        dir: page.dir,
+        text: "存在空 onClick: () => {}",
+      });
+    if (page.apiConfigCount > 0 && mockFiles.length === 0)
+      issues.push({
+        level: "warn",
+        dir: page.dir,
+        text: "检测到 API_CONFIG 但项目 mock/ 目录无 mock 文件",
+      });
+    for (const url of page.apiUrls.filter((item) => item.startsWith("/"))) {
+      const mockUrl = `/dev-api${url}`;
+      if (mockContent && !mockContent.includes(mockUrl))
+        issues.push({
+          level: "warn",
+          dir: page.dir,
+          text: "mock 中未发现端点 " + mockUrl,
+        });
+    }
   }
 
   console.log("  页面目录: " + pages.length);
   console.log("  提示项: " + issues.length);
   console.log("");
+  const errors = issues.filter((issue) => issue.level === "error").length;
   for (const issue of issues) {
-    console.log("  ⚠ " + issue.dir + " — " + issue.text);
+    const icon = issue.level === "error" ? "✖" : "⚠";
+    console.log("  " + icon + " " + issue.dir + " — " + issue.text);
   }
   if (issues.length === 0) console.log("  ✔ 页面文件完整性检查通过");
   console.log("");
-  if (issues.length > 0) process.exitCode = 1;
+  if (errors > 0 || issues.length > 0) process.exitCode = 1;
+}
+
+function readJsonSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function runDoctorUi() {
+  console.log("");
+  console.log("  wl-skills-kit v" + PKG.version + "  [doctor-ui]");
+  console.log("  目标目录: " + TARGET_DIR);
+  console.log("");
+
+  const checks = [];
+  function add(name, ok, detail) {
+    checks.push({ name, ok, detail });
+  }
+
+  const pkg = readJsonSafe(path.join(TARGET_DIR, "package.json"));
+  const deps = pkg ? { ...pkg.dependencies, ...pkg.devDependencies } : {};
+  add(
+    "@agile-team/wk-skills-ui",
+    Boolean(deps["@agile-team/wk-skills-ui"]),
+    deps["@agile-team/wk-skills-ui"] || "未安装",
+  );
+  add(
+    "@element-plus/icons-vue",
+    Boolean(deps["@element-plus/icons-vue"]),
+    deps["@element-plus/icons-vue"] || "未安装",
+  );
+
+  const files = fs.existsSync(TARGET_DIR)
+    ? walkDir(TARGET_DIR, TARGET_DIR)
+    : [];
+  const sourceFiles = files.filter(
+    (rel) =>
+      /\.(ts|vue|scss|html)$/.test(rel) && !rel.startsWith("node_modules/"),
+  );
+  const readAll = (pattern) =>
+    sourceFiles
+      .filter((rel) => pattern.test(rel))
+      .map((rel) => fs.readFileSync(path.join(TARGET_DIR, rel), "utf8"))
+      .join("\n");
+  const allSource = readAll(/.*/);
+
+  add(
+    "design tokens",
+    /@agile-team\/wk-skills-ui\/design\/tokens|dist\/tokens\.css/.test(
+      allSource,
+    ),
+    "需引入 design tokens",
+  );
+  add(
+    "styles preset",
+    /@agile-team\/wk-skills-ui\/styles/.test(allSource),
+    "需引入 styles 或 skin preset",
+  );
+  add(
+    "installCommonPreset",
+    /installCommonPreset\s*\(/.test(allSource),
+    "需在入口或业务 preset 中调用",
+  );
+  add(
+    "defineColumns",
+    /defineColumns\s*\(/.test(allSource),
+    "页面列定义需使用 defineColumns",
+  );
+  add("renderOps", /renderOps\s*\(/.test(allSource), "操作列需使用 renderOps");
+
+  for (const item of checks) {
+    console.log(
+      "  " + statusIcon(item.ok) + " " + item.name + " — " + item.detail,
+    );
+  }
+  const failed = checks.filter((item) => !item.ok).length;
+  console.log("");
+  console.log(
+    failed === 0
+      ? "  ✔ wk-skills-ui 接入检查通过"
+      : "  ⚠ wk-skills-ui 接入仍有 " + failed + " 项需处理",
+  );
+  console.log("");
+  if (failed > 0) process.exitCode = 1;
 }
 
 function parseMarkdownTable(content) {
   return content
     .split(/\r?\n/)
     .filter((line) => /^\|.*\|$/.test(line) && !/^\|\s*-+/.test(line))
-    .map((line) => line.split("|").slice(1, -1).map((cell) => cell.trim()));
+    .map((line) =>
+      line
+        .split("|")
+        .slice(1, -1)
+        .map((cell) => cell.trim()),
+    );
 }
 
 function runExport() {
@@ -743,7 +1013,11 @@ function runExport() {
     if (!fs.existsSync(full)) continue;
     const content = fs.readFileSync(full, "utf8");
     let rows = parseMarkdownTable(content);
-    if (rows.length === 0) rows = content.split(/\r?\n/).filter(Boolean).map((line) => [line]);
+    if (rows.length === 0)
+      rows = content
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => [line]);
     sheets.push([sheetName, rows]);
     addedSheets++;
   }
@@ -764,13 +1038,19 @@ function runExport() {
     let XLSX;
     try {
       XLSX = require("xlsx");
-    } catch (e) {
-      console.error("  ✖ 未找到 xlsx 依赖，请重新安装最新 @agile-team/wl-skills-kit");
+    } catch {
+      console.error(
+        "  ✖ 未找到 xlsx 依赖，请重新安装最新 @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);
+      XLSX.utils.book_append_sheet(
+        wb,
+        XLSX.utils.aoa_to_sheet(rows),
+        sheetName,
+      );
     }
     fs.mkdirSync(outDir, { recursive: true });
     XLSX.writeFile(wb, outFile);
@@ -783,14 +1063,34 @@ function runExport() {
 // ─── 主路由 ─────────────────────────────────────────────────────────────
 
 switch (command) {
-  case "init":     runInstall(false); break;
-  case "update":   runInstall(true);  break;
-  case "clean":    runClean();        break;
-  case "check":    runCheck();        break;
-  case "diff":     runDiff();         break;
-  case "validate": runValidate();     break;
-  case "export":   runExport();       break;
+  case "init":
+    runInstall(false);
+    break;
+  case "update":
+    runInstall(true);
+    break;
+  case "clean":
+    runClean();
+    break;
+  case "check":
+    runCheck();
+    break;
+  case "diff":
+    runDiff();
+    break;
+  case "validate":
+  case "validate-page":
+    runValidate();
+    break;
+  case "doctor-ui":
+    runDoctorUi();
+    break;
+  case "export":
+    runExport();
+    break;
   default:
-    console.error('  ✖ 未知命令: "' + command + '"，请使用 --help 查看可用命令');
+    console.error(
+      '  ✖ 未知命令: "' + command + '"，请使用 --help 查看可用命令',
+    );
     process.exit(1);
 }

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.4.0 架构**
+> **基于 wl-skills-kit v2.4.x 架构**
 > **日期**：2026-05-02
 > **目标**：企业级通用 · 质量精度高 · 速度快 · 节省 token · 还原度高 · 开箱即用 · 支持 Agent Pipeline
 
@@ -33,7 +33,7 @@ L7 自演化体系         🔭 需要足够审计报告与模板样本后再规
 
 ---
 
-## 3. v2.4.0 关键新增
+## 3. v2.4.x 关键能力
 
 ### 3.1 Agent Pipeline
 
@@ -134,7 +134,7 @@ wls_code_scan
 
 ## 6. 结论
 
-v2.4.0 后，wl-skills-kit 已具备搭建通用智能体的基础条件：
+v2.4.x 后，wl-skills-kit 已具备搭建通用智能体的基础条件：
 
 - 有 Skills 作为结构化能力单元
 - 有 MCP 作为实时项目感知与副作用执行工具