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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [2.10.1] - 2026-06-14
+
+### Added
+
+- **pre-commit 阻断修复建议输出**：`wl-skills validate` 阻断时自动输出格式化修复建议框，含 AST R1~R12 规则映射和正则检查建议，标注可自动修复项，引导触发 `规范审计 → 自动修复 → 复扫验证` 流程
+- **code-fix 强制复扫验证**：新增步骤[6]闭环关键步骤，修复完成后必须自动执行 `wl-skills validate` 复扫，用户不可跳过
+- **convention-audit --quick 复扫模式**：仅复查上次报告中的 🔴🟡 项，token 消耗约全量 10%，适用于 code-fix 后轻量级闭环验证
+- **_pipeline.md 闭环强化**：code-fix→validate 从"建议"升级为"强制"约定，新增强制执行 vs 建议执行对照表
+- **_registry.md 加固调度规则 10-12**：闭环强制约定、高风险 Skill 确认机制（page-codegen/sync 类/code-fix）、误触发防护
+- **_best-practices.md 场景 5 闭环补全**：完整闭环流程含强制复扫步骤和触发话术
+- **copilot-instructions.md AI 执行护栏**：新增 5 条强制约定（闭环强制、确认机制、误触发防护、Pre-flight 声明、修复建议输出规范）
+
+### Fixed
+
+- 修复 `printFixSuggestions` 对未知规则静默跳过的问题，新增兜底输出
+- 修复 copilot-instructions.md 高风险 Skill 列表与 _registry.md 不一致的问题
+
+## [2.10.0] - 2026-05-31
+
+### Added
+
+- **新增 `spec-doc-parse` Skill（规范线）**：专门解构 wl-skills-design 产出的标准《需求设计说明书》（IPO 表 / 功能编码 / 流程五要素），输出与 `prototype-scan` 完全相同格式的 page-spec JSON，自带 Pre-flight 校验 + Parse Validation 五项检查 + 自动修复纠偏 + 解析报告（`SPEC_PARSE_*.md`）
+- **`convention-audit` 新增 `--mode spec-align`（GAP 报告）**：比对 spec 定义字段 vs 代码实际字段，输出 `SPEC_GAP_*.md`，完成「说明书 → 代码」零损耗闭环验证
+
+### Changed
+
+- **双线隔离（原型线 / 规范线）**：`_registry.md` 调度规则新增「优先级 0」——输入命中 `docs/spec/` / 功能编码 `/[A-Z]{2,6}[0-9]{3}/` / IPO 表特征时强制路由 `spec-doc-parse`，禁止 `prototype-scan` 接管；两线最终汇聚同一份 page-spec JSON，下游无感知
+- **`prototype-scan` 模式 B 收敛**：由「详设文档」收敛为「非规范零散详设」，加入排除声明，避免与标准说明书混淆
+- 同步更新 `_pipeline.md`（规范线分支 + I/O 契约）、`copilot-instructions.md`（Intent Router）、`kit-internal/architecture.md`（ADR-009）、`lint-skills.js`（spec-doc-parse 纳入写操作 Skill 校验）
+- 启用 Skill 数 10 → 11
+
 ## [2.9.4] - 2026-05-18
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.9.4** — 一键将 14 条规范、10 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
+**AI Skill 模板包 v2.10.1** — 一键将 14 条规范、11 个 AI Skill、17 个 MCP Tool、编辑器 MCP 配置、文档导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / Qoder / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -184,6 +184,7 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   │   ├── _compat/                      多 AI 编辑器适配（配置 + headers）
 │   │   ├── core/                         核心通用 Skill
 │   │   │   ├── prototype-scan/   { SKILL.md, USAGE.md }
+│   │   │   ├── spec-doc-parse/   { SKILL.md, USAGE.md }
 │   │   │   ├── api-contract/     { SKILL.md, USAGE.md }
 │   │   │   ├── page-codegen/     { SKILL.md, USAGE.md, templates/ }
 │   │   │   ├── convention-audit/ { SKILL.md, USAGE.md }
@@ -329,7 +330,8 @@ npx @agile-team/wl-skills-kit update
 
 | Skill              | 状态    | 路径                            | 核心用途                                    |
 | ------------------ | ------- | ------------------------------- | ------------------------------------------- |
-| `prototype-scan`   | ✅ 启用 | `skills/core/prototype-scan/`   | 原型/详设/口述 → 页面清单                   |
+| `prototype-scan`   | ✅ 启用 | `skills/core/prototype-scan/`   | 原型线：Axure/截图/口述/非规范详设 → 页面清单 |
+| `spec-doc-parse`   | ✅ 启用 | `skills/core/spec-doc-parse/`   | 规范线：wl-skills-design 标准说明书 → 页面清单 |
 | `api-contract`     | ✅ 启用 | `skills/core/api-contract/`     | 生成 api.md 前后端契约                      |
 | `page-codegen`     | ✅ 启用 | `skills/core/page-codegen/`     | 页面骨架生成 + 模板调度                     |
 | `convention-audit` | ✅ 启用 | `skills/core/convention-audit/` | 13 条规范扫描 + 双报告                      |

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.9.4
+ * wl-skills-kit CLI v2.10.1
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -22,6 +22,13 @@ const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
 
+// ─── AST 规则引擎（v2.10.1+，语义级约束检测）──────────────────────────
+const {
+  runAstRules,
+  getStagedFiles,
+  hasAstAvailable,
+} = require("../lib/ast-rules");
+
 const FILES_DIR = path.resolve(__dirname, "..", "files");
 const TARGET_DIR = process.cwd();
 const MANIFEST_NAME = ".wl-skills-manifest.json";
@@ -50,12 +57,16 @@ const KNOWN_FLAGS = new Set([
   "-h",
   "--domain",
   "--all",
+  "--pre-commit",
+  "--strict",
 ]);
 
 const dryRun = args.includes("--dry-run");
 const showHelp = args.includes("--help") || args.includes("-h");
 const keepReports = args.includes("--keep-reports");
 const force = args.includes("--force");
+const preCommit = args.includes("--pre-commit");
+const strict = args.includes("--strict");
 
 // 校验所有 flag 是否已知（--help 优先，跳过校验直接显示帮助）
 if (!showHelp) {
@@ -100,6 +111,7 @@ if (showHelp) {
     check      环境预检（Node / 工具链 / MCP 配置 / manifest）
     diff       对比已安装文件与当前 kit 版本的差异
     validate   静态检查 src/views 页面文件、AGGrid、skills-ui runtime、mock
+               v2.10.1+ 集成 AST 语义级检测（R1~R7），覆盖正则无法检测的规则
     validate-page validate 的别名，适用于单页/目录检查
     doctor-ui  检查 @agile-team/wk-skills-ui 接入完整性
     export     导出 reports/SYS_* 数据为 xlsx
@@ -111,6 +123,8 @@ if (showHelp) {
     --force          强制执行，跳过同版本检测（忽略已安装状态）
     --domain <name>  mock-clean 指定要清理的业务域（如 sale、mdata）
     --all            mock-clean 清理全部 mock（保留 _utils.ts）
+    --pre-commit     validate 仅检测 git staged 文件，error 阻断提交，warn 仅提示
+    --strict         validate 的 error 和 warn 都导致退出码 1（CI 用）
     --help           显示帮助
 
   示例:
@@ -341,6 +355,13 @@ function runInstall(incremental) {
 
   const oldManifest = readManifest();
 
+  // ── 约束基础设施：无论版本是否相同，都确保 pre-commit hook 和 eslint 配置就绪 ──
+  // 这样即使 early-return（同版本跳过文件复制），hook 也会被创建/更新
+  if (!dryRun) {
+    ensurePreCommitHook(TARGET_DIR);
+    ensureEslintConfig(TARGET_DIR);
+  }
+
   // ── 版本去重：同版本跳过，不同版本自动增量更新 ──────────────────────
   if (oldManifest && !force) {
     if (oldManifest.version === PKG.version) {
@@ -374,6 +395,9 @@ function runInstall(incremental) {
   if (dryRun) console.log("  [Step 1] files/ 静态文件:\n");
 
   for (const relPath of files) {
+    // eslint 模板由 ensureEslintConfig 单独处理，不通过 Step 1 复制
+    if (relPath === "eslint.config.wl-skills.cjs") continue;
+
     const src = path.join(FILES_DIR, relPath);
     const dest = path.join(TARGET_DIR, relPath);
     const srcHash = fileMd5(src);
@@ -551,10 +575,126 @@ function runInstall(incremental) {
     "  ℹ 规范插件：建议执行 npx @robot-admin/git-standards init 接入代码质量与提交规范。",
   );
   console.log("");
+
 }
 
 // ─── 命令: clean ────────────────────────────────────────────────────────
 
+/**
+ * 确保 .husky/pre-commit 包含 wl-skills validate --pre-commit
+ * — 这是让 AI 生成的代码"绕不开"规范的核心拦截点
+ *
+ * 策略：
+ * 1. 如果 .husky/pre-commit 不存在 → 创建（包含 validate 调用）
+ * 2. 如果存在但不含 wl-skills → 追加（不破坏用户已有的 hook 内容）
+ * 3. 如果存在且已含但格式过旧 → 刷新为最新格式
+ * 4. 如果存在且格式最新 → 跳过
+ *
+ * hook 使用 npx 动态解析，避免硬编码 node_modules 路径在 pnpm 下失效。
+ * 包含存在性守卫：kit 未安装时优雅跳过，不阻断提交。
+ */
+function ensurePreCommitHook(targetDir) {
+  const huskyDir = path.join(targetDir, ".husky");
+  const preCommitPath = path.join(huskyDir, ".husky/pre-commit");
+
+  // 只有 git 仓库才创建 husky hook
+  if (!fs.existsSync(path.join(targetDir, ".git"))) return;
+  if (!fs.existsSync(huskyDir)) return;
+
+  const VALIDATE_MARKER = "wl-skills validate --pre-commit";
+  // 最新 hook 版本标记，用于检测旧格式并刷新
+  const HOOK_VERSION_TAG = "# wl-skills-hook-v2";
+
+  const hookContent =
+    "#!/usr/bin/env sh\n" +
+    HOOK_VERSION_TAG + "\n" +
+    "# wl-skills-kit 自动管理：提交前规范检测（error 阻断提交）\n" +
+    "# 如果 node_modules 不存在或 kit 未安装，优雅跳过，不阻断提交\n" +
+    'if [ -f "node_modules/@agile-team/wl-skills-kit/bin/wl-skills.js" ]; then\n' +
+    '  node node_modules/@agile-team/wl-skills-kit/bin/wl-skills.js validate --pre-commit\n' +
+    "  if [ $? -ne 0 ]; then\n" +
+    '    echo ""\n' +
+    '    echo "  ✖ 规范检测未通过，提交已阻断。修复后重新 git add + git commit"\n' +
+    "    exit 1\n" +
+    "  fi\n" +
+    "else\n" +
+    '  echo "  ⚠ wl-skills-kit 未安装（node_modules 中未找到），跳过提交前检测"\n' +
+    "fi\n";
+
+  const preCommitFile = path.join(huskyDir, "pre-commit");
+
+  if (!fs.existsSync(preCommitFile)) {
+    fs.writeFileSync(preCommitFile, hookContent, "utf8");
+    try { fs.chmodSync(preCommitFile, 0o755); } catch {}
+    console.log("  ✔ 已创建 .husky/pre-commit（提交前自动运行 wl-skills validate）");
+    console.log("    → 每次 git commit 时自动检测页面规范，error 级别阻断提交");
+    console.log("    → kit 未安装时自动跳过，不阻断提交");
+    console.log("");
+  } else {
+    const existing = fs.readFileSync(preCommitFile, "utf8");
+
+    // 已有最新版本标记 → 跳过
+    if (existing.includes(HOOK_VERSION_TAG)) return;
+
+    // 有旧 marker 但格式过旧 → 替换整段 wl-skills 块为最新格式
+    if (existing.includes(VALIDATE_MARKER)) {
+      // 删除旧的 wl-skills 块（从 VALIDATE_MARKER 前的注释行到对应的 fi）
+      const lines = existing.split("\n");
+      const filtered = [];
+      let skipMode = false;
+      for (const line of lines) {
+        if (line.includes(VALIDATE_MARKER) || line.includes("wl-skills-kit 自动")) {
+          skipMode = true;
+          continue;
+        }
+        if (skipMode && (line.includes("exit 1") || line.trim() === "fi")) {
+          skipMode = false;
+          continue;
+        }
+        if (!skipMode) filtered.push(line);
+      }
+      // 去尾部空行
+      while (filtered.length > 0 && filtered[filtered.length - 1].trim() === "") {
+        filtered.pop();
+      }
+      // 追加最新格式
+      const updated = filtered.join("\n").trimEnd() + "\n\n" + hookContent.replace("#!/usr/bin/env sh\n", "");
+      fs.writeFileSync(preCommitFile, updated, "utf8");
+      try { fs.chmodSync(preCommitFile, 0o755); } catch {}
+      console.log("  ✔ 已刷新 .husky/pre-commit 为最新格式（v2，含存在性守卫）");
+      console.log("");
+      return;
+    }
+
+    // 无 marker → 追加
+    const addition = "\n" + hookContent.replace("#!/usr/bin/env sh\n", "");
+    fs.writeFileSync(preCommitFile, existing.trimEnd() + "\n" + addition, "utf8");
+    try { fs.chmodSync(preCommitFile, 0o755); } catch {}
+    console.log("  ✔ 已在 .husky/pre-commit 追加 wl-skills validate（提交前规范检测）");
+    console.log("    → kit 未安装时自动跳过，不阻断提交");
+    console.log("");
+  }
+}
+
+/**
+ * 确保业务项目有 ESLint 配置
+ * 策略：如果项目根目录没有 eslint.config.cjs，从 kit 复制模板
+ *       如果已有，不覆盖（尊重用户自定义配置）
+ */
+function ensureEslintConfig(targetDir) {
+  const targetEslint = path.join(targetDir, "eslint.config.cjs");
+  if (fs.existsSync(targetEslint)) return; // 用户已有自定义配置
+
+  const templatePath = path.join(FILES_DIR, "eslint.config.wl-skills.cjs");
+  if (!fs.existsSync(templatePath)) return;
+
+  const content = fs.readFileSync(templatePath, "utf8");
+  fs.writeFileSync(targetEslint, content, "utf8");
+  console.log("  ✔ 已创建 eslint.config.cjs（wl-skills-kit 模板）");
+  console.log("    → 安装依赖后生效：pnpm add -D eslint eslint-plugin-vue vue-eslint-parser @typescript-eslint/parser @typescript-eslint/eslint-plugin");
+  console.log("");
+}
+
 function runClean() {
   console.log("");
   console.log("  wl-skills-kit v" + PKG.version + "  [clean]");
@@ -665,14 +805,36 @@ function runCheck() {
   const nodeMajor = Number(process.versions.node.split(".")[0]);
   add("Node 版本", nodeMajor >= 16, process.versions.node + "（要求 >=16）");
 
-  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)) ? "存在" : "缺失",
-    );
+  // 工具链检测：支持多种可能的文件名
+  const prettierExists =
+    fs.existsSync(path.join(TARGET_DIR, ".prettierrc.js")) ||
+    fs.existsSync(path.join(TARGET_DIR, ".prettierrc")) ||
+    fs.existsSync(path.join(TARGET_DIR, ".prettierrc.cjs"));
+  add(".prettierrc", prettierExists, prettierExists ? "存在" : "缺失");
+
+  const eslintExists =
+    fs.existsSync(path.join(TARGET_DIR, "eslint.config.ts")) ||
+    fs.existsSync(path.join(TARGET_DIR, "eslint.config.mjs")) ||
+    fs.existsSync(path.join(TARGET_DIR, "eslint.config.cjs")) ||
+    fs.existsSync(path.join(TARGET_DIR, "eslint.config.js"));
+  add("eslint.config", eslintExists, eslintExists ? "存在" : "缺失");
+
+  // husky 目录检测
+  const huskyExists = fs.existsSync(path.join(TARGET_DIR, ".husky"));
+  add(".husky", huskyExists, huskyExists ? "存在" : "缺失");
+
+  // pre-commit hook 内容检测（不只检查目录存在）
+  const preCommitPath = path.join(TARGET_DIR, ".husky", "pre-commit");
+  let preCommitHasValidate = false;
+  if (fs.existsSync(preCommitPath)) {
+    const hookContent = fs.readFileSync(preCommitPath, "utf8");
+    preCommitHasValidate = hookContent.includes("wl-skills validate --pre-commit");
   }
+  add(
+    ".husky/pre-commit (wl-skills validate)",
+    preCommitHasValidate,
+    preCommitHasValidate ? "已配置规范检测" : huskyExists ? "存在但未配置 wl-skills validate" : "不存在",
+  );
 
   const manifest = readManifest();
   add(
@@ -859,10 +1021,37 @@ function findMockFiles() {
 function runValidate() {
   const scanPath =
     args.find((a) => !a.startsWith("-") && a !== command) || "src/views";
-  const pages = scanPageDirs(scanPath);
+
+  // --pre-commit 模式：获取 staged 文件列表，用于过滤
+  let stagedSet = null;
+  if (preCommit) {
+    const staged = getStagedFiles(TARGET_DIR);
+    if (staged.length === 0) {
+      console.log("");
+      console.log("  wl-skills-kit v" + PKG.version + "  [validate --pre-commit]");
+      console.log("  ⚠ 无 staged 的 .vue/.ts 文件，跳过检测");
+      console.log("");
+      return;
+    }
+    stagedSet = new Set(staged.map((f) => f.replace(/\\/g, "/")));
+  }
+
+  const allPages = scanPageDirs(scanPath);
+  // 在 pre-commit 模式下，只保留包含 staged 文件的页面目录
+  const pages = preCommit
+    ? allPages.filter((page) =>
+        Array.from(stagedSet).some(
+          (f) =>
+            f.startsWith(page.dir + "/") ||
+            f === page.dir + "/index.vue" ||
+            f === page.dir + "/data.ts",
+        ),
+      )
+    : allPages;
+
   console.log("");
-  console.log("  wl-skills-kit v" + PKG.version + "  [" + command + "]");
-  console.log("  扫描目录: " + scanPath);
+  console.log("  wl-skills-kit v" + PKG.version + "  [" + command + "]" + (preCommit ? "  [pre-commit]" : ""));
+  console.log("  扫描目录: " + scanPath + (preCommit ? "（仅 staged 文件）" : ""));
   console.log("");
 
   if (pages.length === 0) {
@@ -1021,18 +1210,185 @@ function runValidate() {
     }
   }
 
-  console.log("  页面目录: " + pages.length);
+  // ── AST 语义级规则检测（v2.10.1+）─────────────────────────────────
+  // 补充正则无法覆盖的 7 条语义规则（R1~R7），与正则规则合并输出
+  // 在 pre-commit 模式下复用上面已计算的 stagedSet
+  const astStagedFiles = preCommit && stagedSet ? Array.from(stagedSet) : undefined;
+  const astResult = runAstRules(TARGET_DIR, scanPath, {
+    stagedFiles: astStagedFiles,
+  });
+  // 合并 AST 结果（降级和正常都 push）
+  issues.push(...astResult.issues);
+
+  // ── 输出 ───────────────────────────────────────────────────────────
+  console.log("  页面目录: " + pages.length + (astResult.pages ? "（AST 扫描 " + astResult.pages + "）" : ""));
   console.log("  提示项: " + issues.length);
   console.log("");
   const errors = issues.filter((issue) => issue.level === "error").length;
+  const warns = issues.filter(
+    (issue) => issue.level === "warn" || issue.level === undefined,
+  ).length;
   for (const issue of issues) {
     const icon =
       issue.level === "error" ? "✖" : issue.level === "info" ? "ℹ" : "⚠";
     console.log("  " + icon + " " + issue.dir + " — " + issue.text);
   }
-  if (issues.length === 0) console.log("  ✔ 页面文件完整性检查通过");
+  if (issues.length === 0) console.log("  \u2714 \u9875\u9762\u6587\u4ef6\u5b8c\u6574\u6027\u68c0\u67e5\u901a\u8fc7");
   console.log("");
-  if (errors > 0 || issues.length > 0) process.exitCode = 1;
+
+  // ── \u4fee\u590d\u5efa\u8bae\u8f93\u51fa\uff08P0 \u6539\u8fdb\uff1a\u963b\u65ad\u65f6\u544a\u8bc9\u5f00\u53d1\u8005\u600e\u4e48\u4fee\uff09─────────────────────
+  const blockingIssues = issues.filter((i) => i.level === "error" || (strict && i.level === "warn"));
+  if (blockingIssues.length > 0) {
+    printFixSuggestions(blockingIssues);
+  }
+
+  if (preCommit) {
+    // pre-commit \u6a21\u5f0f\uff1aerror \u963b\u65ad\u63d0\u4ea4
+    // --pre-commit --strict \u7ec4\u5408\uff1aerror + warn \u90fd\u963b\u65ad
+    const failCount = strict ? errors + warns : errors;
+    if (failCount > 0) {
+      console.log(
+        "  \u2716 pre-commit \u68c0\u67e5\u53d1\u73b0 " +
+        errors + " \u4e2a error" +
+        (strict && warns > 0 ? " + " + warns + " \u4e2a warn\uff08strict \u6a21\u5f0f\uff09" : "") +
+        "\uff0c\u63d0\u4ea4\u5df2\u963b\u65ad",
+      );
+      console.log("  \u2192 \u8bf7\u4fee\u590d\u540e\u91cd\u65b0 git add + git commit");
+      console.log("  \u2192 \u5982\u9700 AI \u8f85\u52a9\u4fee\u590d\uff0c\u8bf7\u89e6\u53d1\uff1a\u89c4\u8303\u5ba1\u8ba1 \u2192 \u81ea\u52a8\u4fee\u590d \u2192 \u590d\u626b\u9a8c\u8bc1");
+      console.log("");
+      process.exitCode = 1;
+    } else {
+      console.log("  \u2714 pre-commit \u68c0\u67e5\u901a\u8fc7\uff08" + issues.length + " \u4e2a\u63d0\u793a\u9879\u4e0d\u963b\u65ad\u63d0\u4ea4\uff09");
+      console.log("");
+    }
+  } else if (strict) {
+    // --strict \u6a21\u5f0f\uff08CI \u7528\uff09\uff1aerror \u548c warn \u5bfc\u81f4\u5931\u8d25\uff0cinfo \u4e0d\u8ba1\u5165
+    if (errors > 0 || warns > 0) {
+      console.log(
+        "  \u2716 strict \u6a21\u5f0f\u68c0\u67e5\u53d1\u73b0 " + errors + " error / " + warns + " warn\uff0cCI \u5df2\u963b\u65ad",
+      );
+      console.log("  \u2192 --strict \u6a21\u5f0f\u4e0b warn \u4e5f\u4f1a\u5931\u8d25\uff0c\u8bf7\u4fee\u590d");
+      process.exitCode = 1;
+    } else {
+      console.log("  \u2714 strict \u6a21\u5f0f\u68c0\u67e5\u5168\u90e8\u901a\u8fc7");
+    }
+    console.log("");
+  } else {
+    // \u666e\u901a\u6a21\u5f0f\uff1a\u53ea\u6709 error \u6216 warn \u624d exit 1\uff0cinfo \u4ec5\u63d0\u793a
+    if (errors > 0 || warns > 0) process.exitCode = 1;
+  }
+}
+
+// ── \u4fee\u590d\u5efa\u8bae\u6620\u5c04\u8868\uff08P0\uff1a\u8ba9\u5f00\u53d1\u8005\u77e5\u9053\u600e\u4e48\u4fee\uff09──────────────────────────────
+const FIX_SUGGESTIONS = {
+  // \u6b63\u5219\u7ea7\u68c0\u67e5
+  'render-type="agGrid"': {
+    fix: '<BaseTable render-type="agGrid" ...>',
+    ref: 'standards/12-base-table.md',
+    auto: true,
+  },
+  'cid / :cid': {
+    fix: '\u7ed9 BaseTable \u52a0 cid="{\u6a21\u5757\u7f29\u5199}-{\u529f\u80fd}"\uff0c\u5168\u5c40\u552f\u4e00',
+    ref: 'standards/12-base-table.md',
+    auto: true,
+  },
+  'defineColumns()': {
+    fix: 'import { defineColumns } from "@agile-team/wk-skills-ui/runtime" \u5e76\u7528\u4e8e\u5217\u5b9a\u4e49',
+    ref: 'standards/12-base-table.md',
+    auto: true,
+  },
+  'renderOps()': {
+    fix: '\u64cd\u4f5c\u5217\u4f7f\u7528 defaultSlot + renderOps()\uff0c\u7981\u6b62 operations \u6570\u7ec4',
+    ref: 'standards/12-base-table.md',
+    auto: true,
+  },
+  'C_Splitter': {
+    fix: '\u66ff\u6362\u4e3a jh-drag-col\uff08\u5de6\u53f3\uff09/ jh-drag-row\uff08\u4e0a\u4e0b\uff09',
+    ref: 'standards/14-layout-containers.md',
+    auto: true,
+  },
+  'onClick: () => {}': {
+    fix: '\u586b\u5145\u5b9e\u9645\u4e8b\u4ef6\u5904\u7406\u903b\u8f91\uff0c\u6216\u8054\u52a8 code-fix \u81ea\u52a8\u4fee\u590d',
+    ref: 'standards/04-coding-basics.md',
+    auto: true,
+  },
+};
+
+const AST_FIX_SUGGESTIONS = {
+  R1: { fix: '\u5c06\u4e1a\u52a1\u903b\u8f91\u8fc1\u79fb\u5230 data.ts\uff0cindex.vue \u53ea\u4fdd\u7559\u6a21\u677f+\u89e3\u6784', ref: 'standards/02-code-structure.md', auto: false },
+  R2: { fix: '\u5c06 getAction/postAction/sessionStorage \u79fb\u5230 data.ts \u4e2d\u8c03\u7528', ref: 'standards/02-code-structure.md', auto: true },
+  R3: { fix: '\u66ff\u6362 <el-table> \u4e3a <BaseTable render-type="agGrid" :cid="xxx">', ref: 'standards/12-base-table.md', auto: true },
+  R4: { fix: '\u4fee\u6539\u91cd\u590d cid \u4e3a\u5168\u5c40\u552f\u4e00\u503c\uff08\u683c\u5f0f: {\u6a21\u5757\u7f29\u5199}-{\u529f\u80fd}\uff09', ref: 'standards/12-base-table.md', auto: true },
+  R5: { fix: 'data.ts \u4e2d class extends AbstractPageQueryHook\uff0c\u5b9e\u73b0 queryDef/columnsDef', ref: 'standards/02-code-structure.md', auto: false },
+  R6: { fix: '\u5220\u9664 import axios\uff0c\u6539\u7528 getAction/postAction', ref: 'standards/06-security.md', auto: true },
+  R7: { fix: '\u5220\u9664 eval/new Function\uff0c\u7528\u5b89\u5168\u7684\u66ff\u4ee3\u65b9\u6848', ref: 'standards/06-security.md', auto: false },
+  R8: { fix: '\u521b\u5efa data.ts\uff0c\u5c06\u63a5\u53e3\u8c03\u7528\u548c\u4e1a\u52a1\u903b\u8f91\u79fb\u5165\uff1b\u786e\u4fdd index.vue \u65e0 API \u8c03\u7528', ref: 'standards/02-code-structure.md', auto: true },
+  R9: { fix: '\u66f4\u65b0 api.md\uff0c\u786e\u4fdd URL \u4e0e data.ts API_CONFIG \u4e00\u81f4', ref: 'standards/02-code-structure.md', auto: true },
+  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 },
+};
+
+function printFixSuggestions(blockingIssues) {
+  // \u6309\u89c4\u5219\u5206\u7ec4\u53bb\u91cd
+  const ruleGroups = new Map();
+  for (const issue of blockingIssues) {
+    const key = issue.rule || guessRuleFromText(issue.text);
+    if (!key) continue;
+    if (!ruleGroups.has(key)) ruleGroups.set(key, []);
+    ruleGroups.get(key).push(issue);
+  }
+
+  if (ruleGroups.size === 0) return;
+
+  console.log("  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  console.log("  \u2502 \ud83d\udd27 \u4fee\u590d\u5efa\u8bae                                              \u2502");
+  console.log("  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+
+  let hasAutoFix = false;
+  let hasUnknownIssue = false;
+  for (const [rule, ruleIssues] of ruleGroups.entries()) {
+    const suggestion = AST_FIX_SUGGESTIONS[rule] || findRegexSuggestion(ruleIssues[0].text);
+    const count = ruleIssues.length;
+    if (!suggestion) {
+      // 免底：未知规则的阻断项也要展示，避免用户看不到任何提示
+      hasUnknownIssue = true;
+      console.log("  \u2502  " + rule + "\uff08" + count + " \u5904\uff09 [\u2753\u672a\u77e5\u89c4\u5219]");
+      console.log("  \u2502    \u2192 \u8bf7\u67e5\u770b .github/standards/ \u76f8\u5173\u89c4\u8303\u6216\u89e6\u53d1\u89c4\u8303\u5ba1\u8ba1");
+      console.log("  \u2502");
+      continue;
+    }
+    const autoTag = suggestion.auto ? " [\u2705\u53ef\u81ea\u52a8\u4fee]" : " [\u270b\u9700\u4eba\u5de5]";
+    if (suggestion.auto) hasAutoFix = true;
+    console.log("  \u2502  " + rule + "\uff08" + count + " \u5904\uff09" + autoTag);
+    console.log("  \u2502    \u2192 " + suggestion.fix);
+    console.log("  \u2502    \u53c2\u8003: .github/" + suggestion.ref);
+    console.log("  \u2502");
+  }
+
+  console.log("  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  if (hasAutoFix) {
+    console.log("  \u2502 \ud83d\ude80 \u5feb\u901f\u4fee\u590d\uff1a\u5728 AI \u7f16\u8f91\u5668\u4e2d\u8f93\u5165\uff1a                       \u2502");
+    console.log("  \u2502    \"\u89c4\u8303\u5ba1\u8ba1\" \u2192 \"\u81ea\u52a8\u4fee\u590d\" \u2192 \"\u590d\u626b\u9a8c\u8bc1\"              \u2502");
+  } else {
+    console.log("  \u2502 \ud83d\udcdd \u8bf7\u53c2\u7167\u4e0a\u8ff0\u89c4\u8303\u6587\u6863\u624b\u52a8\u4fee\u590d                       \u2502");
+  }
+  console.log("  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+  console.log("");
+}
+
+function guessRuleFromText(text) {
+  for (const key of Object.keys(FIX_SUGGESTIONS)) {
+    if (text.includes(key)) return key;
+  }
+  return null;
+}
+
+function findRegexSuggestion(text) {
+  for (const [key, suggestion] of Object.entries(FIX_SUGGESTIONS)) {
+    if (text.includes(key)) return suggestion;
+  }
+  return null;
 }
 
 function readJsonSafe(filePath) {

package/files/.github/copilot-instructions.md

@@ -266,6 +266,7 @@ onMounted(() => select());
 | 用户自然表达 | 自动触发 |
 | ------------ | -------- |
 | 生成页面 / 做个页面 / 列表页 / 管理页 / 台账 / 根据原型 / 根据截图 / 补页面 | `page-codegen`，必要时先 `prototype-scan` + `api-contract` |
+| 解析说明书 / 规范文档转页面 / 根据说明书生成 / IPO 转页面 / docs/spec 路径 / 功能编码（PMMB001） | `spec-doc-parse`（**规范线**，wl-skills-design 标准说明书专属，禁止 prototype-scan 接管） |
 | mock / 假数据 / 后端没好 / 先能跑 / 联调前 | `page-codegen` 的 mock-first 规则 |
 | 菜单 / 注册页面 / 点击进不来 / 同步菜单 / 补菜单 | `menu-sync` + `route-check` |
 | 风格 / 样式不生效 / skills-ui / 操作列 / 状态标签 / AGGrid | `page-codegen` + `wk-skills-ui runtime` + `doctor-ui` |
@@ -372,6 +373,103 @@ AI 生成的所有报告类文件统一写入 `.github/reports/`，**全部追
 
 ---
 
+## 小修改 / 零散变更的约束（同样不可绕过）
+
+> 即使不是"生成新页面"，仅做小修改（加字段、改样式、修 bug、加按钮）也必须遵守：
+
+| 规则 | 说明 |
+|------|------|
+| ❌ 不在 index.vue 写业务逻辑 | 新加的方法/状态必须放在 data.ts |
+| ❌ 不直接用 axios / getAction / sessionStorage | 这些只能出现在 data.ts |
+| ❌ 不用 el-table / el-form 替代平台组件 | 用 BaseTable / BaseForm |
+| ❌ 不引入新依赖不经团队确认 | 需在 PR 中说明理由 |
+| ✅ 改完即验证 | 触发 `wls_validate_page` 或 `wl-skills validate` |
+| ✅ git cz 提交 | pre-commit 会自动检测规范，error 级别阻断提交 |
+
+> **提交即验证**：`.husky/pre-commit` 会自动运行 `wl-skills validate --pre-commit`，检测 staged 文件中的规范偏差。error 阻断提交，warn 仅提示。这是**机器强制**，不是建议。
+>
+> **CI 兜底**：即使 `git commit --no-verify` 绕过 pre-commit，CI 流水线中的 `wl-skills validate --strict`（正则 + AST 全量检测）会再次拦截，error 和 warn 都导致 CI 失败、阻断 PR 合并。这是不可绕开的最后一道防线。
+
+### 豁免标记（特殊场景）
+
+极少数场景下确实需要绕过某条规则（如弹窗内确实需要原生 `<el-table>`）时，在文件中添加精确豁免标记：
+
+```vue
+<!-- wl-skills:ignore R3 -->
+<el-table :data="dialogData">...</el-table>
+```
+
+或在 `<script>` 中：
+
+```typescript
+// wl-skills:ignore R2
+const data = sessionStorage.getItem("key");
+```
+
+**规则**：
+- 必须带规则编号（R1~R9），精确豁免，不支持全局豁免
+- 标记放在被豁免的代码附近，便于 review
+- CI `--strict` 模式下豁免标记仍然生效（豁免不是违规）
+
+---
+
+## AI 执行护栏（强制约定）
+
+以下规则对所有 AI 助手（Copilot / Claude / GPT 等）在本项目中执行任务时**强制生效**，不可被用户口头覆盖。
+
+### 1. 闭环强制约定
+
+| 触发场景 | 强制动作 | 不可跳过原因 |
+|----------|----------|-------------|
+| code-fix 执行完毕 | 自动执行 `wl-skills validate` 复扫 | 确保修复未引入新偏差 |
+| 复扫发现新问题 | 继续修复 → 再次复扫，直到通过 | 闭环不允许断开 |
+| 用户说“不用验证了” | **仍然执行**复扫，只是不再追问 | 规范高于口头指令 |
+
+### 2. 高风险 Skill 确认机制
+
+以下 Skill 触发前必须向用户**二次确认**，不可静默执行：
+
+- `page-codegen`（生成整页代码，不可逆）
+- `menu-sync` / `dict-sync` / `permission-sync`（跨系统同步，影响后端数据）
+- `code-fix`（批量修改源码文件，需确认范围）
+
+确认话术模板：
+
+```
+即将执行 [Skill名称]，影响范围：[文件列表 / 后端数据类型]
+是否继续？(Y/n)
+```
+
+### 3. 误触发防护
+
+| 情况 | 处理方式 |
+|------|----------|
+| 用户意图匹配 2+ 个 Skill | 必须列出候选并询问用户意图 |
+| 用户意图模糊无法映射到 Skill | 询问澄清，不猜测执行 |
+| 仅匹配 1 个 Skill 且置信度高 | 直接执行，无需确认 |
+
+### 4. Pre-flight 声明完整性
+
+AI 在执行任何 Skill 前必须输出 Pre-flight 声明：
+
+```
+📋 Pre-flight:
+- Skill: [skill-name]
+- 触发依据: [用户原话 / 管道上游输出]
+- 影响文件: [文件列表]
+- 预期结果: [一句话描述]
+```
+
+### 5. 修复建议输出规范
+
+当 `wl-skills validate` 阻断时，AI 必须：
+1. 完整展示阻断项（error + strict 模式下的 warn）
+2. 对每项给出**具体修复建议**（而非泛泛的“请修复”）
+3. 标注是否可自动修复（auto: true/false）
+4. 引导用户触发修复流程：`规范审计 → 自动修复 → 复扫验证`
+
+---
+
 > 📚 完整指南：`.github/guides/usage.md`
 > 🏗️ 架构设计：`.github/guides/architecture.md`
 > 🔧 维护者文档：`kit-internal/`（仓库内，不安装到业务项目）

package/files/.github/guides/architecture.md

@@ -2,7 +2,7 @@
 
 > **读者**：团队技术负责人 / wl-skills-kit 维护者 / 对体系设计感兴趣的团队成员
 > **更新方式**：重大架构变更后追加对应章节，旧章节原文保留（历史可溯）
-> **当前版本**：v2.9.4（2026-05-18）
+> **当前版本**：v2.10.1（2026-06-14）
 
 ---