@agile-team/wl-skills-kit 1.2.1 → 2.1.1

package/bin/wl-skills.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * wl-skills-kit CLI v2.0
+ * wl-skills-kit CLI v2.1
  *
  * 命令:
  *   init      全量安装（默认，向后兼容）
@@ -23,6 +23,7 @@ const PKG = require("../package.json");
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
 const showHelp = args.includes("--help") || args.includes("-h");
+const keepReports = args.includes("--keep-reports");
 const command = args.find((a) => !a.startsWith("-")) || "init";
 
 if (showHelp) {
@@ -38,14 +39,19 @@ if (showHelp) {
     clean      构建清理（移除开发期 AI 文件，保留 src/components + src/types）
 
   选项:
-    --dry-run  预览模式，不实际写入/删除任何文件
-    --help     显示帮助
+    --dry-run        预览模式，不实际写入/删除任何文件
+    --keep-reports   clean 命令保留 .github/reports/（默认一起删除）
+    --help           显示帮助
 
   示例:
-    npx @agile-team/wl-skills-kit                安装全量文件
-    npx @agile-team/wl-skills-kit update         仅更新有变化的文件
-    npx @agile-team/wl-skills-kit clean          清理开发期文件
-    npx @agile-team/wl-skills-kit clean --dry-run 预览将要清理哪些文件
+    npx @agile-team/wl-skills-kit                       安装全量文件
+    npx @agile-team/wl-skills-kit update                仅更新有变化的文件
+    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       预览将要清理哪些文件
+
+  保护路径（init / update 不覆盖已存在的）:
+    .github/reports/   AI 生成报告（团队累积数据，存在则跳过）
 
   清理保护路径（clean 不删除）:
     src/components/    通用组件（被业务页面 import，构建必需）
@@ -119,16 +125,23 @@ function removeFileAndEmptyParents(filePath) {
       if (fs.readdirSync(dir).length === 0) {
         fs.rmdirSync(dir);
         dir = path.dirname(dir);
-      } else { break; }
-    } catch (e) { break; }
+      } else {
+        break;
+      }
+    } catch (e) {
+      break;
+    }
   }
 }
 
 /** 读取 manifest */
 function readManifest() {
   if (fs.existsSync(MANIFEST_PATH)) {
-    try { return JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8")); }
-    catch (e) { return null; }
+    try {
+      return JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
+    } catch (e) {
+      return null;
+    }
   }
   return null;
 }
@@ -144,30 +157,90 @@ 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");
+}
 
-const AUTO_HEADER =
+// ─── 旧版遗留路径（v1.x/v2.0 → v2.1 迁移清理）───────────────────────────
+// update 时自动检测并移除，避免旧结构与新结构并存产生歧义。
+const LEGACY_PATHS = [
+  // Skill 目录重组：flat → core/sync/ops 分级（v2.1）
+  ".github/skills/prototype-scan/SKILL.md",
+  ".github/skills/api-contract/SKILL.md",
+  ".github/skills/page-codegen/SKILL.md",
+  ".github/skills/page-codegen/TPL-LIST.md",
+  ".github/skills/page-codegen/TPL-MASTER-DETAIL.md",
+  ".github/skills/page-codegen/TPL-TREE-LIST.md",
+  ".github/skills/page-codegen/TPL-DETAIL-TABS.md",
+  ".github/skills/page-codegen/TPL-FORM-ROUTE.md",
+  ".github/skills/page-codegen/TPL-CHANGE-HISTORY.md",
+  ".github/skills/page-codegen/TPL-RECORD-FORM.md",
+  ".github/skills/page-codegen/TPL-DRIVEN.md",
+  ".github/skills/page-codegen/TPL-OPERATION-STATION.md",
+  ".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/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/skills/_compat/ai-model-matrix.md",
+  ".github/skills/_compat/editor-setup.md",
+];
+
+// ─── 编辑器配置生成（从 _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 -->\n\n";
-
-const CURSOR_MDC_HEADER =
-  "---\n" +
-  'description: "项目编码规范（由 wl-skills-kit 自动生成）"\n' +
-  "alwaysApply: true\n" +
-  "---\n\n" +
-  AUTO_HEADER;
+  "<!-- 请勿手动编辑本文件，更新时重新执行：npx @agile-team/wl-skills-kit@latest update -->\n\n";
 
 function getEditorConfigs(raw) {
-  return [
-    ["AGENTS.md", AUTO_HEADER + raw],
-    ["CLAUDE.md", AUTO_HEADER + raw],
-    [".clinerules", AUTO_HEADER + raw],
-    [".cursorrules", AUTO_HEADER + raw],
-    [".cursor/rules/conventions.mdc", CURSOR_MDC_HEADER + raw],
-    [".windsurfrules", AUTO_HEADER + raw],
-    [".kiro/steering/conventions.md", AUTO_HEADER + raw],
-    [".trae/rules/conventions.md", AUTO_HEADER + raw],
-  ];
+  const editorsJsonPath = path.join(
+    FILES_DIR,
+    ".github",
+    "skills",
+    "_compat",
+    "editors.json",
+  );
+  const headersDir = path.join(
+    FILES_DIR,
+    ".github",
+    "skills",
+    "_compat",
+    "headers",
+  );
+
+  if (!fs.existsSync(editorsJsonPath)) {
+    console.warn("  ⚠ _compat/editors.json 不存在，跳过多 AI 编辑器配置生成");
+    return [];
+  }
+
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(editorsJsonPath, "utf8"));
+  } catch (e) {
+    console.warn("  ⚠ _compat/editors.json 解析失败：" + e.message);
+    return [];
+  }
+
+  const configs = [];
+  for (const editor of registry.editors || []) {
+    if (editor.enabled === false) continue;
+    // GitHub Copilot 直接使用 .github/copilot-instructions.md，不重复生成
+    if (editor.outputPath === ".github/copilot-instructions.md") continue;
+
+    const headerPath = path.join(headersDir, editor.headerFile);
+    let header = "";
+    if (fs.existsSync(headerPath)) {
+      header = fs.readFileSync(headerPath, "utf8");
+    }
+    configs.push([editor.outputPath, header + AUTO_HEADER_NOTE + raw]);
+  }
+  return configs;
 }
 
 // ─── 命令: init / update ────────────────────────────────────────────────
@@ -187,9 +260,12 @@ function runInstall(incremental) {
 
   const oldManifest = readManifest();
   const newManifest = { version: PKG.version, files: {} };
-  let created = 0, updated = 0, unchanged = 0;
+  let created = 0,
+    updated = 0,
+    unchanged = 0,
+    preserved = 0;
 
-  // ── Step 1: 复制 files/ 静态文件 ───────────────────────────────────
+  // ── Step 1: 复制 files/ 静态文件 ───────────────────
 
   const files = walkDir(FILES_DIR, FILES_DIR);
   if (dryRun) console.log("  [Step 1] files/ 静态文件:\n");
@@ -200,9 +276,19 @@ function runInstall(incremental) {
     const srcHash = fileMd5(src);
     newManifest.files[relPath] = srcHash;
 
+    // reports/ 下的报告文件：已存在则跳过（保护团队累积数据）
+    if (isReportFile(relPath) && fs.existsSync(dest)) {
+      preserved++;
+      if (dryRun) console.log("  保留  " + relPath + "  (reports/ 已存在)");
+      continue;
+    }
+
     // update 模式: 跳过内容相同的文件
     if (incremental && fs.existsSync(dest)) {
-      if (srcHash === fileMd5(dest)) { unchanged++; continue; }
+      if (srcHash === fileMd5(dest)) {
+        unchanged++;
+        continue;
+      }
     }
 
     if (dryRun) {
@@ -216,13 +302,19 @@ function runInstall(incremental) {
 
   // ── Step 2: 动态生成编辑器配置文件 ────────────────────────────────
 
-  const INSTRUCTIONS_SRC = path.join(FILES_DIR, ".github", "copilot-instructions.md");
+  const INSTRUCTIONS_SRC = path.join(
+    FILES_DIR,
+    ".github",
+    "copilot-instructions.md",
+  );
   if (fs.existsSync(INSTRUCTIONS_SRC)) {
     const raw = fs.readFileSync(INSTRUCTIONS_SRC, "utf8");
     const editorConfigs = getEditorConfigs(raw);
 
     if (dryRun) {
-      console.log("\n  [Step 2] 编辑器配置文件（从 copilot-instructions.md 生成）:\n");
+      console.log(
+        "\n  [Step 2] 编辑器配置文件（从 copilot-instructions.md 生成）:\n",
+      );
     }
 
     for (const [ecPath, ecContent] of editorConfigs) {
@@ -231,12 +323,17 @@ function runInstall(incremental) {
       newManifest.files[ecPath] = ecHash;
 
       if (incremental && fs.existsSync(ecDest)) {
-        if (ecHash === fileMd5(ecDest)) { unchanged++; continue; }
+        if (ecHash === fileMd5(ecDest)) {
+          unchanged++;
+          continue;
+        }
       }
 
       if (dryRun) {
         const ecExists = fs.existsSync(ecDest);
-        console.log("  " + (ecExists ? "覆盖" : "新增") + "  [编辑器] " + ecPath);
+        console.log(
+          "  " + (ecExists ? "覆盖" : "新增") + "  [编辑器] " + ecPath,
+        );
         ecExists ? updated++ : created++;
       } else {
         writeFile(ecDest, ecContent) === "created" ? created++ : updated++;
@@ -244,7 +341,33 @@ function runInstall(incremental) {
     }
   }
 
-  // ── Step 3: 写 manifest ────────────────────────────────────────────
+  // ── Step 3: 迁移清理（仅 update，清理旧版遗留文件）──────────────────
+
+  if (incremental) {
+    let migrated = 0;
+    if (dryRun) console.log("\n  [Step 3] 旧版遗留文件检查（迁移清理）:\n");
+    for (const legacyRel of LEGACY_PATHS) {
+      const legacyFull = path.join(TARGET_DIR, legacyRel);
+      if (fs.existsSync(legacyFull)) {
+        if (dryRun) {
+          console.log("  迁移清理  " + legacyRel + "  (旧版遗留，将被移除)");
+        } else {
+          removeFileAndEmptyParents(legacyFull);
+        }
+        migrated++;
+      }
+    }
+    if (!dryRun && migrated > 0) {
+      console.log(
+        "    迁移: " + migrated + " 个旧版文件已移除（路径已变更，见 CHANGELOG.md）",
+      );
+    }
+    if (dryRun && migrated === 0) {
+      console.log("  （无旧版遗留文件）");
+    }
+  }
+
+  // ── Step 4: 写 manifest ────────────────────────────────────────────
 
   if (!dryRun) writeManifest(newManifest);
 
@@ -254,7 +377,17 @@ function runInstall(incremental) {
   if (dryRun) {
     console.log("");
     if (incremental) {
-      console.log("  共 " + total + " 个文件（新增 " + created + "，变更 " + updated + "，未变 " + unchanged + "）（未实际写入）");
+      console.log(
+        "  共 " +
+          total +
+          " 个文件（新增 " +
+          created +
+          "，变更 " +
+          updated +
+          "，未变 " +
+          unchanged +
+          "）（未实际写入）",
+      );
     } else {
       console.log("  共 " + total + " 个文件（未实际写入）");
     }
@@ -264,12 +397,20 @@ function runInstall(incremental) {
       console.log("    新增: " + created + " 个文件");
       console.log("    更新: " + updated + " 个文件");
       console.log("    未变: " + unchanged + " 个文件");
+      if (preserved > 0)
+        console.log(
+          "    保留: " + preserved + " 个 reports/ 文件（团队累积数据不覆盖）",
+        );
       if (oldManifest && oldManifest.version !== PKG.version) {
         console.log("    版本: " + oldManifest.version + " → " + PKG.version);
       }
     } else {
       console.log("    新增: " + created + " 个文件");
       console.log("    覆盖: " + updated + " 个文件");
+      if (preserved > 0)
+        console.log(
+          "    保留: " + preserved + " 个 reports/ 文件（团队累积数据不覆盖）",
+        );
       console.log("    总计: " + (created + updated) + " 个文件");
     }
   }
@@ -294,8 +435,16 @@ function runClean() {
   }
 
   const allFiles = Object.keys(manifest.files);
-  const toRemove = allFiles.filter((f) => !isProtected(f));
-  const toKeep = allFiles.filter((f) => isProtected(f));
+  const toRemove = allFiles.filter((f) => {
+    if (isProtected(f)) return false;
+    if (keepReports && 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;
+    return false;
+  });
 
   if (dryRun) {
     console.log("  将要删除（" + toRemove.length + " 个文件）:\n");
@@ -308,7 +457,8 @@ function runClean() {
       console.log("  保留  " + f);
     }
   } else {
-    let removed = 0, skipped = 0;
+    let removed = 0,
+      skipped = 0;
     for (const f of toRemove) {
       const fullPath = path.join(TARGET_DIR, f);
       if (fs.existsSync(fullPath)) {
@@ -324,7 +474,19 @@ function runClean() {
     console.log("  ✔ 清理完成!");
     console.log("    删除: " + removed + " 个文件");
     if (skipped > 0) console.log("    跳过: " + skipped + " 个（已不存在）");
-    console.log("    保留: " + toKeep.length + " 个文件（src/components/ + src/types/）");
+    if (keepReports) {
+      console.log(
+        "    保留: " +
+          toKeep.length +
+          " 个文件（src/components/ + src/types/ + .github/reports/）",
+      );
+    } else {
+      console.log(
+        "    保留: " +
+          toKeep.length +
+          " 个文件（src/components/ + src/types/）",
+      );
+    }
   }
   console.log("");
 }

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

@@ -11,7 +11,7 @@
 - 样式：Windi CSS + SCSS
 - 状态：Pinia
 - 页面注册：`vite/plugins/shared/pages.ts` 通过 `gProd()` / `gSale()` 声明
-- 菜单路由配置：后端菜单表是唯一数据源。pages.ts 注册组件后，需在系统管理后台 → 菜单管理 → 新增菜单。批量新增页面时可用后端 batchImport 接口，详见 `.github/docs/menu-sync-design.md`
+- 菜单路由配置：后端菜单表是唯一数据源。pages.ts 注册组件后，需在系统管理后台 → 菜单管理 → 新增菜单。批量新增页面时可用后端 batchImport 接口，详见 `.github/skills/sync/menu-sync/SKILL.md`
 
 ## 页面标准结构（4 文件）
 
@@ -198,64 +198,125 @@ onMounted(() => select());
 - ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
 - ❌ 每个页面重复写弹窗组件（优先用 `c_modal` 等局部公共组件）
 
-## AI Skills 自动调度（强制执行 — 所有 AI 编辑器/模型通用）
 
-本项目内置 5 个 Skill 文件，覆盖「原型/详设 → 可运行页面 → 菜单注册」完整流程。
-**执行以下任何任务前，必须先用工具读取（read_file）对应的 SKILL.md，读取完成前禁止生成任何代码或输出。**
+---
 
-### Skill 注册表
+## 规范门控（standards/index.md 懒加载）
 
-| 触发场景（用户意图关键词） | 必须读取的文件 | Skill 名称 |
-|---|---|---|
-| 扫描原型、解析原型、页面清单、原型分析、详设文档、口述需求、建个页面、写个页面 | `.github/skills/prototype-scan/SKILL.md` | prototype-scan |
-| 接口约定、api.md、字段定义、前后端对齐、接口设计 | `.github/skills/api-contract/SKILL.md` | api-contract |
-| 生成页面、创建页面、代码生成、vue页面、按原型生成、口述生成页面、帮我生成 | `.github/skills/page-codegen/SKILL.md`（主文件会指示继续读取对应的 `TPL-*.md` 模板） | page-codegen |
-| 创建菜单、注册菜单、同步菜单、补菜单 | `.github/skills/menu-sync/SKILL.md` | menu-sync |
-| 规范审计、代码审计、规范检查、对齐规范、规范偏差 | `.github/skills/convention-extract/SKILL.md` | convention-audit |
+> ⚠️ 本节为**强制约定**，所有 AI 编辑器/模型都必须遵守。
 
-### 完整流水线（原型/详设 → 页面 → 菜单）
+完整 13 条编码规范拆分在 `.github/standards/01 ~ 13.md`，由 `standards/index.md` 提供任务类型 → 规范子集映射，**按需加载，不全量读取**。
 
-当用户提供原型文件或详设文档并要求批量生成页面时，按以下顺序依次执行：
+| 任务类型              | 必读规范                                          |
+| --------------------- | ------------------------------------------------- |
+| A. 生成新页面         | 01, 02, 03, 04, 05, 06, 07, 09, 10, 11, 12, 13   |
+| B. 修改/重构现有代码  | 02, 04, 05, 06, 09, 10, 12, 13                    |
+| C. 规范审计           | 全部 01 ~ 13                                       |
+| D. 模板提取           | 02, 03, 09, 12, 13                                |
+| E. 数据同步（菜单等） | 04, 05, 07                                        |
+| F. Git/分支/提交      | 08                                                |
+
+**执行任何代码生成或改动前**：
+1. 先 `read_file` 加载 `standards/index.md` 确认任务类型
+2. 按映射读取对应 `standards/0X-*.md`
+3. 在 Pre-flight 声明中列出已加载文件
+
+---
+
+## AI Skills 自动调度
+
+完整触发词与 Skill 路径见 `skills/_registry.md`（**单一数据源**，不在此处重复）。
+
+| Skill 名             | 状态     | 一句话说明                              |
+| -------------------- | -------- | --------------------------------------- |
+| prototype-scan       | ✅ 启用  | 原型/详设 → page-spec JSON              |
+| api-contract         | ✅ 启用  | 生成 api.md 接口约定                    |
+| page-codegen         | ✅ 启用  | 4 文件 + 模板调度 + 菜单追加            |
+| menu-sync            | ✅ 启用  | reports/SYS_MENU_INFO → 后端菜单接口    |
+| convention-audit     | ✅ 启用  | 13 条规范扫描 + 偏差报告 + 提取建议     |
+| template-extract     | ✅ 启用  | 现有页面 → 领域模板沉淀                 |
+| dict-sync            | ⏳ PLANNED | 字典数据同步                            |
+| permission-sync      | ⏳ PLANNED | 权限数据同步                            |
+| code-fix             | ⏳ PLANNED | 自动整改 🟢🟡 等级偏差                  |
+
+**执行规则**：
+
+1. 用户消息匹配 `_registry.md` 触发词 → 用 `read_file` 加载对应 SKILL.md
+2. SKILL.md 中标注的"必读 standards"按 standards/index.md 映射加载
+3. 在 SKILL.md 指示下输出 **Pre-flight 声明**（强制）
+
+---
+
+## Pre-flight 声明（强制约定式输出）
+
+每次 Skill 触发时，**必须先输出**以下结构的 Pre-flight 声明，再开始执行：
 
 ```
-Step 1 → 读取 prototype-scan/SKILL.md → 执行原型扫描 → 输出 page-spec
-Step 2 → 读取 api-contract/SKILL.md   → 生成 api.md 接口约定（先于代码生成，确保 API_CONFIG 与接口一致）
-Step 3 → 读取 page-codegen/SKILL.md   → 逐页生成代码 + 追加/覆盖 SYS_MENU_INFO.md（询问用户选择写入模式）
-Step 4 → 读取 menu-sync/SKILL.md      → 读取 SYS_MENU_INFO.md → 注册菜单到后端
+🚀 已触发技能 {skill-name}/SKILL.md  → {一句话用途}
+✅ 已读取 standards/index.md         → 规范门控
+✅ 已读取 standards/{相关条目}        → {一句话说明}
+✅ 已读取 {其他必要文档}              → {说明}
+✅ 工具链检测：{各项 ✓ / ✗}
+✅ {其他前置检查项，如 cid 生成等}
 ```
 
-> **模式 0 快捷路径**：当用户口述需求（如"帮我生成一个客户管理页面"）而未提供原型/文档时，AI 内部调用 prototype-scan 模式 0 自动构建 page-spec JSON，然后从 Step 2 继续执行，无需用户提供任何文件。
+**工具链检测失败必须暂停**：
+
+```
+❌ 工具链检测失败：未找到 {缺失文件}
+   → 请执行：npx @robot-admin/git-standards init
+   → 或联系 CHENY（工号 409322）解决
+   → ⛔ 任务已暂停，修复后重新触发
+```
+
+---
+
+## 报告类文件（reports/）
+
+AI 生成的所有报告类文件统一写入 `.github/reports/`，**全部追加不覆盖**。
+
+| 文件                              | 写入方             | 读取方                |
+| --------------------------------- | ------------------ | --------------------- |
+| `reports/SYS_MENU_INFO.md`        | page-codegen       | menu-sync             |
+| `reports/SYS_DICT_INFO.md` [PLANNED]   | dict-collect  | dict-sync             |
+| `reports/SYS_PERMISSION_INFO.md` [PLANNED] | permission-collect | permission-sync |
+| `reports/规范审查报告.md`          | convention-audit   | 人工 → code-fix       |
+| `reports/组件提取建议.md`          | convention-audit   | 人工 → template-extract |
+
+详见 `reports/README.md`。
+
+---
 
-每个 Step 开始前读取对应 SKILL.md，**前一个 Step 完成后再进入下一个**。
-上一步的输出（如 page-spec）直接作为下一步的输入，无需用户中间干预。
+## 组件文档按需查阅
 
-> **数据闭环**：page-codegen 生成的 `SYS_MENU_INFO.md` 是 menu-sync 的唯一输入。
-> 菜单通过 `组件路径` 字段与 pages.ts 注册的文件路径关联，无论自动（menu-sync API）还是手动（系统管理后台）创建菜单，效果等价。
+生成代码时如需了解组件用法，按需读取以下文档（不要全量加载）：
 
-### 单独使用
+| 主题                                | 文档路径                                              |
+| ----------------------------------- | ----------------------------------------------------- |
+| BaseQuery / BaseTable / BaseToolbar | `src/components/remote/{BaseXxx}/README.md`           |
+| jh-* 平台组件                       | `docs/jh-{name}.md`                                   |
+| c_formModal / c_listModal 等        | `src/components/local/{c_xxx}/README.md`              |
+| AbstractPageQueryHook 最佳实践      | `docs/page-query-hook-best-practices.md`              |
+| HTTP 请求工具                       | `docs/request.md`                                     |
 
-用户也可以只执行单个 Skill（如只说"帮我生成客户档案页面"），此时只需读取对应的 SKILL.md，不必执行完整流水线。
+> 详细对照表与"何时必读哪个文档"见 `standards/13-platform-components.md`。
 
-### 组件文档按需查阅
+---
 
-生成代码过程中如需了解组件用法，读取 `docs/` 下对应文档：
+## 领域样例参考
 
-| 组件 | 文档路径 |
-|------|---------|
-| BaseQuery / BaseTable / BaseToolbar | `src/components/remote/BaseQuery/README.md` 等 |
-| jh-select / jh-date / jh-pagination 等 | `docs/jh-select.md` / `docs/jh-date.md` 等 |
-| c_formModal / c_formSections / c_listModal | `src/components/local/c_formModal/README.md` 等 |
-| AbstractPageQueryHook 最佳实践 | `docs/page-query-hook-best-practices.md` |
-| HTTP 请求工具 | `docs/request.md` |
+首次生成某类页面时，可读取 `demo/` 下对应样例：
 
-### 领域样例参考
+| 模板类型              | 样例路径                                                |
+| --------------------- | ------------------------------------------------------- |
+| LIST                  | `demo/produce/aiflow/mmwr-customer-archive/`            |
+| FORM_ROUTE            | `demo/produce/aiflow/mmwr-customer-apply-add-form/`     |
+| CHANGE_HISTORY        | `demo/produce/aiflow/mmwr-customer-apply-change-history/` |
+| DETAIL_TABS           | `demo/produce/aiflow/mmwr-customer-detail/`             |
+| MASTER_DETAIL         | `demo/sale/demo/metallurgical-spec/`                    |
 
-首次生成某类页面时，可读取 `demo/` 下的对应样例学习实际写法：
+---
 
-| 模板类型 | 样例路径 |
-|---------|---------|
-| LIST（标准列表） | `demo/produce/aiflow/mmwr-customer-archive/` |
-| FORM_ROUTE（复杂表单） | `demo/produce/aiflow/mmwr-customer-apply-add-form/` |
-| CHANGE_HISTORY（变更历史） | `demo/produce/aiflow/mmwr-customer-apply-change-history/` |
-| DETAIL_TABS（详情Tab） | `demo/produce/aiflow/mmwr-customer-detail/` |
-| MASTER_DETAIL（上下分栏） | `demo/sale/demo/metallurgical-spec/` |
+> 📚 完整指南：`.github/guides/usage.md`
+> 🏗️ 架构设计：`.github/guides/architecture.md`
+> 🔧 维护者文档：`kit-internal/`（仓库内，不安装到业务项目）

package/files/.github/guides/README.md

@@ -0,0 +1,13 @@
+# Guides 指南目录
+
+本目录下文档由 `wl-skills-kit` 安装到业务项目的 `.github/guides/`，作为团队成员人工维护的指南类文档。
+
+| 文件              | 内容                                           |
+| ----------------- | ---------------------------------------------- |
+| `usage.md`        | 全套 Skill 使用说明（团队成员上手必读）        |
+| `architecture.md` | 整体架构设计与决策记录（含菜单同步等设计内容） |
+
+> 与 `kit-internal/`（仅 wl-skills-kit 仓库可见的维护文档）严格区分：
+>
+> - `guides/` → 业务项目使用方阅读
+> - `kit-internal/` → wl-skills-kit 仓库维护者阅读，**不安装到业务项目**