@qilitt-mickey/vue3-temp-skill 1.2.5 → 1.2.6

package/bin/cli.js

@@ -31,11 +31,18 @@ const SKILL_DIR = path.resolve(__dirname, "..");
 const SKILL_NAME = "vue3-temp-skill";
 const TRACK_FILE = path.join(HOME, ".vue3-temp-skill.json");
 // 只复制 AI 运行时真正需要的文件；validate/cli 属作者侧词典维护工具，不随技能分发。
-// design-audit.mjs / check.mjs / apply-final-gate.mjs 必须随包分发：E11 交付完整性 / E12 设计层
-// 累积性（ledger 台账）/ 终态机读凭证（四闸串联，FINAL-GATE: PASS）是落地会话的运行时闸——
-// 缺了它们「只挑主题令牌落地 + 覆盖历史成果 + 以自述结束会话」无法被静态拦截
-// （失效模式：运行时副本缺审计闸时，残缺口变更集会一路绿灯）。
-const RUNTIME_SCRIPT_FILES = ["match.py", "modules.json", "check-landing.mjs"];
+// 施工脚本必须随包分发：generate-css.mjs（契约→CSS 确定性编译）、generate-page.mjs
+// （契约 structure→页面脚手架）、verify-render.mjs（Playwright 渲染验收）、
+// check-landing.mjs（落地八项自检）。缺了它们，弱模型被指示跑脚本时文件不存在，
+// 只能手抄 CSS 或直接跳过（失效模式：内容区空白、主题布局未落地）。
+const RUNTIME_SCRIPT_FILES = [
+  "match.py",
+  "modules.json",
+  "check-landing.mjs",
+  "generate-css.mjs",
+  "generate-page.mjs",
+  "verify-render.mjs",
+];
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(SKILL_DIR, "package.json"), "utf-8")).version;
 
 // ============================================================
@@ -80,6 +87,11 @@ const TARGETS = {
     dir: (p) => (p ? path.join(p, ".trae/rules") : path.join(HOME, ".trae/rules")),
     type: "rules",
   },
+  codebuddy: {
+    name: "CodeBuddy",
+    dir: (p) => (p ? path.join(p, ".codebuddy/rules") : path.join(HOME, ".codebuddy/rules")),
+    type: "rules",
+  },
   claude: {
     name: "Claude Code",
     dir: (p) => (p ? path.join(p, ".claude/skills") : path.join(HOME, ".claude/skills")),
@@ -222,32 +234,15 @@ function recordUninstall(targetKey, projectDir) {
 // ============================================================
 
 /**
- * rules 类型：Windsurf / Trae
- */
-function installRules(targetKey, projectDir) {
-  const cfg = TARGETS[targetKey];
-  const targetDir = cfg.dir(projectDir);
-  ensureDir(targetDir);
-
-  const content = readFullSkill();
-  const file = path.join(targetDir, `${SKILL_NAME}.md`);
-  fs.writeFileSync(file, content, "utf-8");
-}
-
-/**
- * skills 类型：Cursor / Qoder / Claude / Universal
+ * 复制技能运行时本体（SKILL.md / README.md / references / scripts / adapters / mapping）
+ * 供 skills 与 rules 两种形态共用——rules 形态也必须落盘本体，
+ * 否则规则文件指示的施工脚本不存在。
  */
-function installSkills(targetKey, projectDir) {
-  const cfg = TARGETS[targetKey];
-  const targetDir = cfg.dir(projectDir);
-  const dest = path.join(targetDir, SKILL_NAME);
-
+function copySkillBody(dest) {
   // 先清理旧版本
   if (fs.existsSync(dest)) {
     removeDir(dest);
   }
-
-  // 只复制必要文件，不复制整个包目录（避免缓存目录中的无关文件导致递归）
   ensureDir(dest);
   copyFile(path.join(SKILL_DIR, "SKILL.md"), path.join(dest, "SKILL.md"));
   copyFile(path.join(SKILL_DIR, "README.md"), path.join(dest, "README.md"));
@@ -266,11 +261,57 @@ function installSkills(targetKey, projectDir) {
     }
   }
 
-  // 视觉契约落地依赖：mapping/ 三列变量映射表（区域名 ↔ 项目现状对照）
+  // 契约→框架等价转换 adapter（generate-css / verify-render 的运行时依赖）
+  const adaptersSrc = path.join(SKILL_DIR, "adapters");
+  if (fs.existsSync(adaptersSrc)) {
+    copyDir(adaptersSrc, path.join(dest, "adapters"));
+  } else {
+    console.log(
+      yellow(
+        `  ! 技能包缺少 adapters/（generate-css / verify-render 的运行时依赖），装出的技能无法确定性施工，请检查发布包完整性`
+      )
+    );
+  }
+
+  // mapping/ 三列变量映射表（区域名 ↔ 项目现状对照）
   const mappingSrc = path.join(SKILL_DIR, "mapping");
   if (fs.existsSync(mappingSrc)) {
     copyDir(mappingSrc, path.join(dest, "mapping"));
   }
+}
+
+/**
+ * rules 类型：Windsurf / Trae / CodeBuddy
+ * 规则文件承载文本规范；施工脚本与 adapters/mapping 以技能本体随附落盘，
+ * 规则文件头部注明本体路径，模型按该路径运行脚本。
+ */
+function installRules(targetKey, projectDir) {
+  const cfg = TARGETS[targetKey];
+  const targetDir = cfg.dir(projectDir);
+  ensureDir(targetDir);
+
+  // 技能本体：<rules 上一级>/skills/<名>/（与 skills 形态同构）
+  const bodyDest = path.join(path.dirname(targetDir), "skills", SKILL_NAME);
+  copySkillBody(bodyDest);
+
+  const content = readFullSkill();
+  const file = path.join(targetDir, `${SKILL_NAME}.md`);
+  const header =
+    `> 技能本体（scripts/adapters/mapping/references）已随附安装至: ${bodyDest}\n` +
+    `> 运行施工脚本时一律使用该路径，例如:\n` +
+    `>   node ${bodyDest}/scripts/generate-css.mjs --project <项目根>\n` +
+    `>   node ${bodyDest}/scripts/check-landing.mjs --project <项目根>\n\n`;
+  fs.writeFileSync(file, header + content, "utf-8");
+}
+
+/**
+ * skills 类型：Cursor / Qoder / Claude / Universal
+ */
+function installSkills(targetKey, projectDir) {
+  const cfg = TARGETS[targetKey];
+  const targetDir = cfg.dir(projectDir);
+  const dest = path.join(targetDir, SKILL_NAME);
+  copySkillBody(dest);
 
   // Cursor：清理旧版 rules/*.mdc，避免与 skills 重复
   if (cfg.legacyRulesFile) {
@@ -318,6 +359,9 @@ function uninstallTarget(targetKey, projectDir) {
     const targetDir = cfg.dir(projectDir);
     const file = path.join(targetDir, `${SKILL_NAME}.md`);
     if (fs.existsSync(file)) fs.unlinkSync(file);
+    // 同步清理随附的技能本体
+    const body = path.join(path.dirname(targetDir), "skills", SKILL_NAME);
+    if (fs.existsSync(body)) removeDir(body);
   } else if (cfg.type === "skills") {
     const targetDir = cfg.dir(projectDir);
     const dest = path.join(targetDir, SKILL_NAME);
@@ -366,6 +410,7 @@ ${bold("目标 (target):")}
   windsurf     → Windsurf        ~/.windsurf/rules/
   gemini       → Gemini CLI      <项目>/GEMINI.md（项目级）
   trae         → Trae            ~/.trae/rules/
+  codebuddy    → CodeBuddy       ~/.codebuddy/rules/
   claude       → Claude Code     ~/.claude/skills/
   universal    → 通用标准        ~/.agents/skills/
   all          → 安装到所有支持的工具

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "type": "module",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块、视觉契约落地",
   "bin": {
@@ -12,6 +12,7 @@
   },
   "files": [
     "bin/",
+    "adapters/",
     "references/",
     "scripts/",
     "mapping/",

package/references/design-apply.md

@@ -230,8 +230,14 @@ node <技能>/scripts/generate-css.mjs --project <项目根>
 1. 在样式入口引入三份文件（**入口位置按 `adapter.output.entryImport`——通常是 main.ts 在组件库全量 CSS 之后**）
 2. 页面根节点挂 `.ui-page`，各区域挂 `.ui-region-<名>`
 3. 按 adapter 的「角色类挂载方式」给组件挂 `.role-*`（**表格走插槽，不是在 `<el-table>` 上加类**）
-4. **按契约 `structure` 重建页面骨架**——区块数量/顺序、列数与列宽档位、控件类型、图标 path、折叠/吸附结构，**照骨架对齐**。
-   **⚠️ 形态/内容分离（红线）**：`structure` 里标了 `sampleOnly` 的业务内容（列名文字、筛选项 label、数据行、菜单文字、状态文案）**一律不烧进项目**——项目侧保持自身业务字段（列名/prop/API/mock/权限/字典），只把「形态」对齐骨架。设计稿的演示占位不是目标项目的业务事实；覆盖业务逻辑 = 交付失败。
+4. **内容区页面骨架由 `generate-page.mjs` 确定性生成，不手写**：
+
+   ```bash
+   node <技能>/scripts/generate-page.mjs --project <项目根> --out src/views/design-restore
+   ```
+
+   生成器把契约 `structure` + `pages` 逐条翻译成列表页脚手架 SFC——页头/筛选/工具栏/表格/分页的区块结构与顺序、列数与列宽档位、控件类型、图标、状态变体类、SAMPLE 行。**角色类全部以字面量挂载**（`check-landing.mjs` 用正则扫源文件文本，回调拼接出来的类名扫不到 = 自检必挂）。生成后在路由注册该页。
+   **⚠️ 形态/内容分离（红线）**：`structure` 里标了 `sampleOnly` 的业务内容（列名文字、筛选项 label、数据行、状态文案）在生成物里一律是 SAMPLE 占位——项目侧接入真实业务时替换为自身字段（列名/prop/API/mock/权限/字典），**只换内容、不动形态**（角色类、区块结构、列宽档位保持原样）。设计稿的演示占位不是目标项目的业务事实；覆盖业务逻辑 = 交付失败。
 5. **重跑第 0 步的落地自检，八项全过才算挂载完成**
 6. 进入第 7 步视觉验收（computed style 逐点比对契约 + visualSanity 通用断言，目视截图只作最后留档）
 

package/scripts/check-landing.mjs

@@ -19,6 +19,10 @@ import { fileURLToPath } from "node:url";
 const IGNORE_DIRS = new Set([
   "node_modules", "dist", ".git", ".vite", "coverage",
   "__pycache__", ".idea", ".vscode", ".workbuddy", "unpackage",
+  // AI 工具配置 / 技能分发目录：技能脚本文本含 CSS 文件名与角色类名，
+  // 不排除会被 checkImported / checkMounting 自匹配成假 PASS
+  ".agents", ".codebuddy", ".cursor", ".qoder", ".windsurf", ".gemini",
+  ".trae", ".claude", ".github",
 ]);
 
 const CSS_FILES = ["ui-tokens.css", "ui-roles.css", "ui-layout.css"];
@@ -222,7 +226,24 @@ function expectedClassName(roleName) {
   );
 }
 
-function checkMounting(projectRoot, roleNames) {
+/** 页面绑定引用的角色集合（pages.*.nodes 的 role + pages.*.regions 的 role）—— 挂载检查的「必需集」。
+ *  契约角色库可能大于单页实际用量（可选复用角色如 card.base），未被任何页面引用的角色缺失不应阻塞落地。 */
+function boundRoles(contract) {
+  const pages = (contract && contract.pages) || {};
+  const set = new Set();
+  for (const page of Object.values(pages)) {
+    if (!page || typeof page !== "object") continue;
+    for (const n of Array.isArray(page.nodes) ? page.nodes : []) {
+      if (n && n.role) set.add(String(n.role));
+    }
+    for (const b of Array.isArray(page.regions) ? page.regions : []) {
+      if (b && b.role) set.add(String(b.role));
+    }
+  }
+  return set;
+}
+
+function checkMounting(projectRoot, roleNames, requiredSet) {
   const vueFiles = walk(projectRoot, SOURCE_EXT, []);
   const roleClassRe = /\brole-[a-z0-9]+(?:-[a-z0-9]+)*/g;
   const usedClasses = new Map();
@@ -239,9 +260,19 @@ function checkMounting(projectRoot, roleNames) {
   const expected = roleNames.map(expectedClassName);
   const mounted = [];
   const missing = [];
+  const optionalMissing = [];
+  let optionalMounted = 0;
   for (let i = 0; i < roleNames.length; i++) {
-    if (usedClasses.has(expected[i])) mounted.push(expected[i]);
-    else missing.push(`${roleNames[i]} → .${expected[i]}`);
+    // 必需集为空时回退旧语义（全部必需）—— 兼容无 pages 绑定的契约
+    const required = !requiredSet || requiredSet.size === 0 || requiredSet.has(roleNames[i]);
+    if (usedClasses.has(expected[i])) {
+      mounted.push(expected[i]);
+      if (!required) optionalMounted++;
+    } else if (required) {
+      missing.push(`${roleNames[i]} → .${expected[i]}`);
+    } else {
+      optionalMissing.push(`${roleNames[i]} → .${expected[i]}`);
+    }
   }
 
   const layoutClassRe = /\bui-(?:page|region-[a-z0-9]+(?:-[a-z0-9]+)*)\b/g;
@@ -256,6 +287,8 @@ function checkMounting(projectRoot, roleNames) {
     scannedFileCount: vueFiles.length,
     mounted,
     missing,
+    optionalMissing,
+    optionalMounted,
     layoutClasses: [...layoutClasses],
     hasLayout: layoutClasses.has("ui-page"),
   };
@@ -263,14 +296,35 @@ function checkMounting(projectRoot, roleNames) {
 
 // ────────────────────────────── 结构校验（契约 §7）
 
-const LIBRARY_DIR = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "../../project-ui-design/references/library"
-);
+/**
+ * 角色库目录多级探测（project-ui-design/references/library）：
+ * 1. 环境变量 UI_DESIGN_LIBRARY_DIR（显式指定，最高优先）
+ * 2. 双包同级（源码仓 skills/ 下、universal/rules 分发后的同级安装目录）
+ * 3. 上两层兜底
+ * 均不可达时返回 { dir: null, tried } —— 白名单校验降级为 WARN（预期降级，非故障）。
+ */
+function resolveLibraryDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [];
+  if (process.env.UI_DESIGN_LIBRARY_DIR) {
+    candidates.push(path.resolve(process.env.UI_DESIGN_LIBRARY_DIR));
+  }
+  candidates.push(
+    path.resolve(here, "../../project-ui-design/references/library"),
+    path.resolve(here, "../../../project-ui-design/references/library"),
+  );
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) return { dir, tried: candidates };
+  }
+  return { dir: null, tried: candidates };
+}
+
+const { dir: LIBRARY_DIR } = resolveLibraryDir();
 
 /** 加载角色库名集合：<场景>.json + components.json；目录不可达返回 null（降级 WARN） */
 function loadRoleLibrary(scene) {
   const merged = new Set();
+  if (!LIBRARY_DIR) return null;
   for (const f of [`${scene}.json`, "components.json"]) {
     const p = path.join(LIBRARY_DIR, f);
     if (!exists(p)) continue;
@@ -435,12 +489,12 @@ function run(projectRoot) {
     structStatus === "PASS"
       ? `${parsed.roleNames.length} 个角色全部在角色库；regions 与 areas 一致（${parsed.info.areaCount} 个区域）；页面绑定无悬空引用`
       : structStatus === "WARN"
-        ? "角色库目录不可达，跳过「角色名在库」校验（regions↔areas 与页面绑定校验已通过）"
+        ? "角色库目录不可达，跳过「角色名在库」校验（regions↔areas 与页面绑定校验已通过）—— 分发形态下 project-ui-design 未与本项目技能同装属预期降级"
         : struct.problems.join("；"),
     structStatus === "FAIL"
       ? "设计侧结构违规 —— 回设计侧修正契约（角色名须在库、layout.regions 与 layout.areas 一致、绑定的区域名必须存在），重新出契约。"
       : structStatus === "WARN"
-        ? "确认技能包完整（project-ui-design/references/library 存在）后重跑。"
+        ? "预期降级，不阻断落地。如需启用角色白名单校验：将 project-ui-design 与 vue3-temp-skill 同级安装，或设置环境变量 UI_DESIGN_LIBRARY_DIR 指向 project-ui-design/references/library 后重跑。"
         : null
   );
   if (structStatus === "FAIL") {
@@ -481,21 +535,26 @@ function run(projectRoot) {
     );
   }
 
-  // 6. 角色类挂载
-  const mount = checkMounting(projectRoot, parsed.roleNames);
-  const mountRatio = parsed.roleNames.length
-    ? mount.mounted.length / parsed.roleNames.length
-    : 0;
+  // 6. 角色类挂载 —— 必需集 = 页面绑定（nodes/regions）引用的角色；
+  //    契约角色库大于单页用量时（可选复用角色），未引用角色的缺失只提示不计入告警
+  const requiredRoleSet = boundRoles(contract);
+  const mount = checkMounting(projectRoot, parsed.roleNames, requiredRoleSet);
+  const optionalCount = mount.optionalMounted + mount.optionalMissing.length;
+  const requiredTotal = parsed.roleNames.length - optionalCount;
+  const requiredMounted = mount.mounted.length - mount.optionalMounted;
   add(
     "roles-mounted",
     "角色类挂到模板上",
-    mount.mounted.length === parsed.roleNames.length ? "PASS"
+    mount.missing.length === 0 ? "PASS"
       : mount.mounted.length === 0 ? "FAIL" : "WARN",
-    `契约 ${parsed.roleNames.length} 个角色，模板挂载 ${mount.mounted.length} 个（覆盖率 ${(mountRatio * 100).toFixed(0)}%）；扫描 ${mount.scannedFileCount} 个源文件`,
+    `契约 ${parsed.roleNames.length} 个角色（页面绑定引用 ${requiredTotal} 个为必需，已挂载 ${requiredMounted} 个）；扫描 ${mount.scannedFileCount} 个源文件` +
+      (mount.optionalMissing.length
+        ? `；未引用可选角色缺失 ${mount.optionalMissing.length} 个（${mount.optionalMissing.slice(0, 4).map((s) => s.split(" ")[0]).join("、")}${mount.optionalMissing.length > 4 ? "…" : ""}），不影响落地`
+        : ""),
     mount.mounted.length === 0
       ? "没有任何 .vue 文件出现 role-* 类名 —— 三份 CSS 全是死样式（写了规则但没元素承载）。按 adapter 的挂载映射给组件加 class。"
       : mount.missing.length
-        ? `未挂载 ${mount.missing.length} 个角色（CSS 已生成但页面上没有对应 class，视觉不会变）: ${mount.missing.slice(0, 6).join(" | ")}${mount.missing.length > 6 ? " …" : ""}`
+        ? `必需角色未挂载 ${mount.missing.length} 个（CSS 已生成但页面上没有对应 class，视觉不会变）: ${mount.missing.slice(0, 6).join(" | ")}${mount.missing.length > 6 ? " …" : ""}`
         : null
   );