@agile-team/wl-skills-ui 1.6.6 → 1.6.8

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.6.8] - 2026-05-11
+
+### Changed
+
+- 修正架构边界文档中 L1/L2 的表述：L1 负责 Element Plus 原生组件族，L2 Project Vendors 是当前项目集群的必需覆盖层。
+- README 和架构文档明确 `Base*`、`jh-*`、`C_*`、AG Grid、自研封装和 custom wrappers 都必须按统一 tokens 与 Element Plus 基础视觉对齐，不应被理解为可选补丁。
+
+## [1.6.7] - 2026-05-11
+
+### Added
+
+- 新增 `standards/architecture/01-layer-boundaries.md`，明确 tokens、Element Plus、vendors、layouts、runtime、scanner、skills 的职责边界和扩展规则。
+- 新增 `npm run docs:check`，校验旧命名、旧命令、README 版本文案、CHANGELOG 版本记录和编辑器配置完整性。
+
+### Changed
+
+- CLI 编辑器安装配置改为读取 `skills/_meta/_compat/editors.json`，消除代码内第二份 `EDITOR_TARGETS` 路径映射。
+- `editors.json` 补齐 `ext`、`singleFile`、`headerFile` 等安装行为字段，使 AI 编辑器配置成为单一事实源。
+
 ## [1.6.6] - 2026-05-11
 
 ### Changed

package/README.md

@@ -193,10 +193,13 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.6.5 版本重点强化“统一规则源 + 多编辑器分发 + UI 细节精准修复”的闭环：
+当前 v1.6.8 版本重点强化“统一规则源 + 多编辑器分发 + 项目集群封装必覆盖 + UI 细节精准修复”的闭环：
 
 - `skills/**/*.md` 作为唯一规则源，`wl-ui init/update` 会按编辑器格式转换并覆盖写入目标 rules
+- `skills/_meta/_compat/editors.json` 作为 AI 编辑器安装配置唯一来源，CLI 不再维护第二份编辑器路径映射
 - `wl-ui update --editor all --force` 可一次性刷新全部支持编辑器；未指定编辑器时会刷新 manifest 与项目中已存在的编辑器规则目录
+- `standards/architecture/01-layer-boundaries.md` 固化 tokens、Element Plus、Project Vendors、layouts、runtime、scanner、skills 的扩展边界，明确 `Base*` / `jh-*` / `C_*` / AG Grid 是当前项目集群必覆盖层
+- `npm run docs:check` 校验旧命名、旧命令、版本文案和编辑器配置，防止规则文档回退
 - 表格空状态改为对应表格区域内自适应居中，避免嵌套表格靠固定高度猜效果
 - 查询区/工具栏按钮补齐 token fallback，禁用按钮独立保留清晰禁用态
 - 表单控件圆角统一使用 `--wk-form-control-radius`，覆盖 input/select/date/textarea/upload 等控件家族
@@ -393,11 +396,11 @@ AI 按 _flows/legacy-skin-align.md 严格 6 phase 执行：
 ### Skin 模式优先级（团队约定）
 
 ```
-Base* > jh-* > C_*/c_* > custom wrappers
+Base* > jh-* > C_*/c_* > AG Grid > custom wrappers
        (高)            (低)
 ```
 
-样式文件加载顺序在 `styles/vendors/index.scss` 中固化，确保高优先级覆盖低优先级。
+样式文件加载顺序在 `styles/vendors/index.scss` 中固化，确保高优先级覆盖低优先级。vendor 层不是可选补丁层，而是当前项目集群统一风格的必需适配层。
 
 ---
 
@@ -454,7 +457,7 @@ export const myRules = [
 
 ## Element Plus 组件族样式管控
 
-`wl-skills-ui` 的核心是样式绝对管控。加载 `styles`、`styles/presets/skin` 或 `styles/presets/element-only` 后，会统一覆盖首批 B 端高频 Element Plus 组件族：
+`wl-skills-ui` 的核心是样式绝对管控。加载 `styles`、`styles/presets/skin` 或 `styles/presets/element-only` 后，会先统一覆盖首批 B 端高频 Element Plus 组件族；基于 Element Plus 的 `Base*`、`jh-*`、`C_*`、AG Grid 等封装/组合组件由 `styles/vendors` 继续承接，确保当前项目集群不管怎么封装组装，都收敛到同一套视觉体系：
 
 | 组件族       | 覆盖标签                                                   | 典型场景                         |
 | ------------ | ---------------------------------------------------------- | -------------------------------- |

package/bin/wl-ui.js

@@ -3,7 +3,7 @@
  * wl-ui — wl-skills-ui 统一 CLI
  *
  * 子命令：
- *   wl-ui init   [--project <path>] [--editor copilot|cursor|windsurf|kiro|trae] [--dry-run]
+ *   wl-ui init   [--project <path>] [--editor <editor|all>] [--dry-run]
  *                把 skills/ 写入目标项目的 AI 编辑器规则目录
  *   wl-ui scan   → 委托给 scanner/index.mjs
  *   wl-ui check  → 委托给 scanner/index.mjs
@@ -40,21 +40,7 @@ const MANIFEST_NAME = ".wl-skills-ui-manifest.json";
 // 常量
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/** 编辑器 → 安装目录映射 */
-const EDITOR_TARGETS = {
-  "github-copilot": {
-    dir: ".github/instructions/wk-skills",
-    ext: ".instructions.md",
-  },
-  cursor: { dir: ".cursor/rules", ext: ".mdc" },
-  windsurf: { dir: ".windsurf/rules", ext: ".md" },
-  kiro: { dir: ".kiro/steering", ext: ".md" },
-  trae: { dir: ".trae/rules", ext: ".md" },
-  "claude-code": { dir: ".", ext: ".md", singleFile: "CLAUDE.md" },
-  cline: { dir: ".", ext: ".md", singleFile: ".clinerules" },
-  "agents-generic": { dir: ".", ext: ".md", singleFile: "AGENTS.md" },
-  qoder: { dir: ".qoder/rules", ext: ".md" },
-};
+const EDITOR_TARGETS = loadEditorTargets();
 const EDITOR_IDS = Object.keys(EDITOR_TARGETS);
 
 // ── 参数解析 ─────────────────────────────────────────────────────────────────
@@ -265,6 +251,33 @@ function detectEditor(projectRoot) {
   return "github-copilot";
 }
 
+function loadEditorTargets() {
+  const configPath = join(
+    PKG_ROOT,
+    "skills",
+    "_meta",
+    "_compat",
+    "editors.json",
+  );
+  const config = JSON.parse(readFileSync(configPath, "utf8"));
+  return Object.fromEntries(
+    config.editors.map((editor) => [
+      editor.id,
+      {
+        dir: normalizeInstallDir(editor.installPath),
+        ext: editor.ext || ".md",
+        singleFile: editor.singleFile,
+        headerFile: editor.headerFile,
+      },
+    ]),
+  );
+}
+
+function normalizeInstallDir(installPath) {
+  const normalized = installPath.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized === "." || normalized === "" ? "." : normalized;
+}
+
 function detectInstalledEditors(projectRoot) {
   return EDITOR_IDS.filter((editor) => {
     const target = EDITOR_TARGETS[editor];
@@ -338,13 +351,14 @@ function collectSkills(skillsDir) {
 
 /** 读取编辑器 frontmatter 模板 */
 function getHeaderTemplate(editor) {
+  const target = EDITOR_TARGETS[editor];
+  const headerFile = target?.headerFile;
   const headerPath = join(
     PKG_ROOT,
     "skills",
     "_meta",
     "_compat",
-    "headers",
-    `${editorHeaderName(editor)}.txt`,
+    headerFile || join("headers", `${editor}.txt`),
   );
   if (existsSync(headerPath)) return readFileSync(headerPath, "utf8");
   return "";
@@ -543,22 +557,6 @@ function capitalize(s) {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
-function editorHeaderName(editor) {
-  return (
-    {
-      cursor: "cursor-mdc",
-      "github-copilot": "github-copilot",
-      windsurf: "windsurf",
-      kiro: "kiro",
-      trae: "trae",
-      "claude-code": "claude-code",
-      cline: "cline",
-      "agents-generic": "agents",
-      qoder: "qoder",
-    }[editor] || editor
-  );
-}
-
 function installSupportFiles({ projectRoot, dryRun }) {
   const files = [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.6.6",
+  "version": "1.6.8",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",
@@ -40,6 +40,7 @@
     "build": "tsup && npm run sync:tokens",
     "prepare": "npm run build",
     "sync:tokens": "node -e \"import('fs').then(fs=>fs.copyFileSync('design/tokens/base.css','dist/tokens.css'))\"",
+    "docs:check": "node scripts/check-docs.mjs",
     "scan": "node scanner/index.mjs scan",
     "check": "node scanner/index.mjs check",
     "fix": "node scanner/index.mjs fix",
@@ -58,6 +59,7 @@
     "skills",
     "templates",
     "bin",
+    "scripts",
     "mcp",
     "reference",
     "examples",

package/scripts/check-docs.mjs

@@ -0,0 +1,83 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const root = join(__dirname, "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const readme = readFileSync(join(root, "README.md"), "utf8");
+const changelog = readFileSync(join(root, "CHANGELOG.md"), "utf8");
+const editorConfig = JSON.parse(
+  readFileSync(
+    join(root, "skills", "_meta", "_compat", "editors.json"),
+    "utf8",
+  ),
+);
+
+const errors = [];
+const forbiddenPatterns = [
+  { pattern: /\bwk-ui\b/, message: "旧 CLI 名称 wk-ui" },
+  { pattern: /\bwk-skills-ui\b/, message: "旧包名 wk-skills-ui" },
+  {
+    pattern: /@agile-team\/wk-skills-ui/,
+    message: "旧 npm 包名 @agile-team/wk-skills-ui",
+  },
+  { pattern: /--editor auto/, message: "无效编辑器参数 --editor auto" },
+  { pattern: /当前 v1\.6\.2/, message: "过期 README 当前版本文案" },
+];
+
+function walk(dir) {
+  const files = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (["node_modules", ".git", "dist", "es"].includes(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(full));
+    if (entry.isFile() && entry.name.endsWith(".md")) files.push(full);
+  }
+  return files;
+}
+
+for (const file of walk(root)) {
+  const rel = relative(root, file).replace(/\\/g, "/");
+  const content = readFileSync(file, "utf8");
+  for (const { pattern, message } of forbiddenPatterns) {
+    if (rel === "CHANGELOG.md") continue;
+    if (pattern.test(content)) errors.push(`${rel}: ${message}`);
+  }
+}
+
+if (!readme.includes(`当前 v${pkg.version}`)) {
+  errors.push(
+    `README.md: 当前版本文案未同步 package.json version ${pkg.version}`,
+  );
+}
+
+if (!changelog.includes(`## [${pkg.version}]`)) {
+  errors.push(`CHANGELOG.md: 缺少 ${pkg.version} 版本记录`);
+}
+
+for (const editor of editorConfig.editors) {
+  if (!editor.id) errors.push("editors.json: editor 缺少 id");
+  if (!editor.installPath)
+    errors.push(`editors.json: ${editor.id} 缺少 installPath`);
+  if (!editor.ext) errors.push(`editors.json: ${editor.id} 缺少 ext`);
+  if (!editor.headerFile)
+    errors.push(`editors.json: ${editor.id} 缺少 headerFile`);
+  if (
+    !existsSync(join(root, "skills", "_meta", "_compat", editor.headerFile))
+  ) {
+    errors.push(
+      `editors.json: ${editor.id} headerFile 不存在：${editor.headerFile}`,
+    );
+  }
+}
+
+if (errors.length > 0) {
+  console.error(
+    "docs:check failed:\n" + errors.map((error) => `- ${error}`).join("\n"),
+  );
+  process.exit(1);
+}
+
+console.log("docs:check passed");

package/skills/_meta/_compat/editors.json

@@ -6,6 +6,7 @@
       "description": "VS Code GitHub Copilot Chat Agent 模式",
       "skillFormat": "SKILL.md with YAML frontmatter (applyTo: glob)",
       "installPath": ".github/instructions/wk-skills/",
+      "ext": ".instructions.md",
       "headerFile": "headers/github-copilot.txt"
     },
     {
@@ -14,6 +15,7 @@
       "description": "Cursor AI 编辑器 .mdc 规则文件",
       "skillFormat": ".mdc files with YAML frontmatter (globs:)",
       "installPath": ".cursor/rules/",
+      "ext": ".mdc",
       "headerFile": "headers/cursor-mdc.txt"
     },
     {
@@ -22,6 +24,7 @@
       "description": "Windsurf AI 编辑器规则文件",
       "skillFormat": "Plain markdown, no frontmatter",
       "installPath": ".windsurf/rules/",
+      "ext": ".md",
       "headerFile": "headers/windsurf.txt"
     },
     {
@@ -30,6 +33,7 @@
       "description": "Kiro AI 编辑器 steering 文档",
       "skillFormat": "Markdown with YAML frontmatter (inclusion: manual)",
       "installPath": ".kiro/steering/",
+      "ext": ".md",
       "headerFile": "headers/kiro.txt"
     },
     {
@@ -38,6 +42,7 @@
       "description": "Trae AI 编辑器规则文件",
       "skillFormat": "Markdown with description frontmatter",
       "installPath": ".trae/rules/",
+      "ext": ".md",
       "headerFile": "headers/trae.txt"
     },
     {
@@ -46,6 +51,8 @@
       "description": "Claude Code 项目规则文件",
       "skillFormat": "Plain markdown",
       "installPath": "./",
+      "ext": ".md",
+      "singleFile": "CLAUDE.md",
       "headerFile": "headers/claude-code.txt"
     },
     {
@@ -54,6 +61,8 @@
       "description": "Cline 规则文件",
       "skillFormat": "Plain markdown",
       "installPath": "./",
+      "ext": ".md",
+      "singleFile": ".clinerules",
       "headerFile": "headers/cline.txt"
     },
     {
@@ -62,6 +71,8 @@
       "description": "AGENTS.md 通用代理协议",
       "skillFormat": "Plain markdown",
       "installPath": "./",
+      "ext": ".md",
+      "singleFile": "AGENTS.md",
       "headerFile": "headers/agents.txt"
     },
     {
@@ -70,6 +81,7 @@
       "description": "Qoder IDE 规则文件",
       "skillFormat": "Markdown with description frontmatter",
       "installPath": ".qoder/rules/",
+      "ext": ".md",
       "headerFile": "headers/qoder.txt"
     }
   ]

package/standards/architecture/01-layer-boundaries.md

@@ -0,0 +1,126 @@
+# wl-skills-ui 架构分层与扩展边界
+
+## 核心原则
+
+`wl-skills-ui` 当前服务于既定项目集群，因此默认 tokens、配色、圆角、密度、组件视觉和工程接入方式是固化体系；但这些固化内容必须保持为可替换的独立变量层，不能散落到组件覆盖、vendor 化妆或 AI rules 中形成补丁污染。
+
+任何新增能力都必须遵守：
+
+- 单一事实源：同一类配置只能有一个权威来源。
+- 分层隔离：tokens、Element Plus 原子覆盖、项目集群封装覆盖、layouts、runtime、scanner、skills 各自负责自己的边界。
+- 向下依赖：上层可以使用下层 token 和规范，下层不能反向依赖上层实现。
+- 覆盖有序：后写入和高优先级覆盖必须有明确目录和加载顺序，不能靠零散 `!important` 补丁堆叠。
+- 项目集群优先：当前风格先服务当前项目集群；未来多项目集群主题替换应通过 theme/tokens/preset 入口扩展，而不是修改组件规则本身。
+
+## 分层边界
+
+| 层级 | 目录 | 职责 | 不允许做的事 |
+| --- | --- | --- | --- |
+| L0 Design Tokens | `design/tokens`、`styles/tokens` | 定义颜色、圆角、间距、字号、阴影等基础变量 | 不写具体组件选择器，不绑定业务组件名 |
+| L1 Element Plus | `styles/element`、`skills/element` | 统一 Element Plus 原生组件视觉，作为全部封装层的基础视觉规则 | 不把 `Base*`、`jh-*`、`C_*`、AG Grid 的私有选择器混入原子层 |
+| L2 Project Vendors | `styles/vendors`、`skills/vendors` | 必须覆盖当前项目集群里的 `Base*`、`jh-*`、`C_*`、自研封装、AG Grid 等封装/组合组件，使其继承同一套风格 | 不重新定义品牌色体系，不脱离 L0/L1 另起一套视觉规则，不覆盖 layout 骨架语义 |
+| L3 Layouts | `styles/layouts`、`skills/layouts`、`templates` | 约束列表页、树表页、表单弹窗等页面骨架 | 不改 token，不写 vendor 私有修复 |
+| L4 Runtime | `runtime`、`reference` | 提供 `defineColumns`、`renderOps`、preset 等业务渲染能力 | 不直接承担老项目 skin 化妆职责 |
+| Automation | `scanner`、`mcp` | 扫描、检查、dry-run 修复和 AI 工具入口 | 不绕过 skills/standards 私自定义新规则语义 |
+| AI Rules | `skills`、`standards` | AI 可读规范、流程和修复策略 | 不和代码实现产生第二套事实源 |
+
+## Tokens 与主题替换边界
+
+当前默认主题位于：
+
+```text
+design/tokens/base.css
+styles/tokens/index.scss
+```
+
+这些文件是当前项目集群的默认主题源。组件样式只能引用 token，不应硬编码品牌色、表单圆角、按钮颜色、空状态颜色等可主题化变量。
+
+推荐写法：
+
+```scss
+color: var(--el-text-color-secondary, #909399);
+border-radius: var(--wk-form-control-radius, 6px);
+```
+
+不推荐写法：
+
+```scss
+color: #909399;
+border-radius: 6px;
+```
+
+未来如果不同项目集群需要切换主题，应优先增加新的 token/preset 入口，例如：
+
+```text
+design/tokens/<cluster>.css
+styles/presets/<cluster>.scss
+```
+
+而不是在 `styles/element` 或 `styles/vendors` 中追加按项目名区分的补丁选择器。
+
+## Element Plus 覆盖边界
+
+Element Plus 原生组件覆盖必须保持组件族独立：
+
+```text
+styles/element/_button.scss
+styles/element/_form.scss
+styles/element/_table.scss
+styles/element/_feedback.scss
+styles/element/_upload.scss
+```
+
+每个文件只处理对应组件族或强相关子组件。跨组件一致性通过 token 解决，例如表单圆角统一使用 `--wk-form-control-radius`，不能在 input、select、upload 中分别写不同硬编码。
+
+L1 的“不处理封装私有结构”不是“不覆盖封装组件”，而是要求封装组件进入 L2，由 L2 按当前项目集群真实封装形态做统一风格适配。
+
+## Project Vendors 覆盖边界
+
+Project Vendors 层是当前项目集群的必需覆盖层，不是可选补丁层。它用于承接所有基于 Element Plus 或与 Element Plus 共同组成页面的封装/组合组件，包括：
+
+```text
+Base* > jh-* > C_*/c_* > AG Grid > custom wrappers
+```
+
+这些组件虽然不是 Element Plus 原生选择器，但在当前项目集群中同样属于统一 UI 风格体系的一部分，必须使用 L0 tokens 和 L1 组件视觉原则进行对齐。
+
+新增 vendor 覆盖时应同时补齐：
+
+1. `styles/vendors/_xxx.scss`
+2. `styles/vendors/index.scss` 加载顺序
+3. `skills/vendors/xxx/SKILL.md`
+4. `skills/_meta/_detection.md`
+5. 如需自动检查，补 `scanner/rules/*`
+
+不能只在某个页面局部追加样式补丁。
+
+## AI Rules 单一源原则
+
+AI 编辑器规则由 `skills/**/*.md` 统一生成。不同编辑器只允许通过 `skills/_meta/_compat/editors.json` 和 `headers/*.txt` 做格式转换。
+
+禁止在以下目录手写与 `skills` 不一致的规则语义：
+
+```text
+.github/instructions/wk-skills
+.cursor/rules
+.windsurf/rules
+.kiro/steering
+.trae/rules
+.qoder/rules
+CLAUDE.md
+.clinerules
+AGENTS.md
+```
+
+这些目录是安装产物，应由 `wl-ui init/update` 覆盖生成。
+
+## 新增能力检查清单
+
+新增任何 UI 规则或样式覆盖前，先确认：
+
+- 是否能通过 token 解决，而不是新增组件补丁。
+- 是否属于 Element Plus 原子层，还是 vendor 封装层。
+- 是否需要同步 Skill、Standard、Scanner 和 Template。
+- 是否会影响 skin 模式老项目布局。
+- 是否会污染未来主题替换能力。
+- 是否可以通过 `wl-ui update --editor all --force` 分发给全部 AI 编辑器。