@agile-team/wl-skills-ui 1.7.1 → 1.8.1

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.8.1] - 2026-05-13
+
+### Added
+
+- 新增 **`scanner/drift.mjs`** 漂移检测模块：对比基线与当前扫描 JSON，输出 gained / fixed / regressed 结构化报告。
+- 新增 CLI `wl-scan drift --baseline <f> --current <f>` 子命令，支持 `--output json` 和 `--fail-on-error` 门槛。
+- 新增 MCP 工具 **`wl_ui_drift`**：AI 可直接传入两份扫描 JSON 拿漂移报告。
+
+## [1.8.0] - 2026-05-12
+
+### Added
+
+- 新增 **`standards/rules.json`** R-rule 单一事实源：29 条规则按 `id / category / severity / appliesTo / autoFixable / scanner / skills` 结构化注册，所有 standards 文档、SKILL.md、scanner、MCP、未来 ESLint 插件均从此派生。
+- 新增 **`standards/rules-loader.mjs`** 共享加载器：暴露 `loadRules / listRules / getRule / groupByCategory / buildRuleSummary`，scanner / MCP / check-docs / Vite 插件统一读取。
+- 新增 MCP 工具 **`wl_ui_list_rules`**：按 `category / severity / autoFixable` 过滤返回规则摘要。
+- 新增 MCP 工具 **`wl_ui_describe_rule`**：按 ID 返回单条 R-rule 完整定义（含 aliases 兼容旧 ID）。
+- 新增 **`docs/governance-long-term.md`**：业务项目长效治理方案（基线 / 豁免 / 漂移看板 / 版本钉死 / 写作期 AI 守护五机制）。
+- `scripts/check-docs.mjs` 扩展：校验 `scanner/rules/*.mjs` 中所有 `id` 必须在 `rules.json` 注册、SKILL.md 引用的 R-id 必须存在、`_registry.md` 引用的 skill 目录必须真实存在。
+
+### Changed (Breaking-ish)
+
+- **修复 R011 逻辑反转 bug**：之前 scanner 检测分页"不在 #footer 报错"，与 `standards/ui/05` "分页必须放内容区，不得放 #footer" 相互矛盾。v1.8.0 反转 scanner 检测语义，与 standards 对齐。
+- **`scanner/rules/tag.mjs` R017/R018 重号为 R019/R020**：原 ID 与 `color.mjs` 的 R017/R018 冲突。`rules.json` 通过 `aliases: [R017_TAG_LEGACY/R018_TAG_LEGACY]` 兼容历史引用；scanner 输出 `rule` 字段改为新 ID。
+- **`skills/_meta/_registry.md` 清理 12 条幽灵条目**：删除 9 个不存在的 `element/*` SKILL 引用（el-card/el-tabs/el-descriptions/el-tree/el-drawer/el-upload/el-steps/el-overlay/el-navigation/el-feedback），声明已统一归入 `element/component-family`；删除 2 个 `ops/*` 引用（route-intent / recommend-flow），声明为 MCP 工具而非独立 SKILL。
+- **`skills/runtime/style-align/SKILL.md` 改为指针式引用**：不再复述 17 条 R-rule 内容，仅保留分类→编号→SKILL 映射表，规则细节统一查 `standards/rules.json` 或 `wl_ui_describe_rule`。
+- `tsup.config.ts` `clean: true`：每次构建清空 `es/` 目录，避免 hash 残留。
+
+### Notes
+
+- R013（Upload 嵌入 operations[]）由文档约束晋升为 `rules.json` 正式条目（`severity: review`，无 scanner 实现）。
+- 推荐业务项目跟进：跑一次 `npx wl-ui audit --target src --outFile .wl-baseline.json` 建立基线，配合 `--baseline` 增量门槛使用（详见 `docs/governance-long-term.md`）。
+
 ## [1.7.1] - 2026-05-12
 
 ### Added

package/README.md

@@ -213,7 +213,16 @@ yarn add @agile-team/wl-skills-ui
 
 ## 版本亮点
 
-当前 v1.7.1 版本在 v1.7.0「单一事实源」基础上，把"识别"升级为"启动期自动 + 一键修复"：
+当前 v1.8.1 版本完成 R-rule 治理体系单一事实源化，并落地业务项目长效治理方案：
+
+- 新增 **`standards/rules.json`** 作为 29 条 R-rule 的单一事实源；所有 standards 文档、SKILL.md、scanner、MCP、未来 ESLint 插件均从此派生
+- 新增 **`standards/rules-loader.mjs`** 共享加载器；新增 MCP 工具 **`wl_ui_list_rules`** / **`wl_ui_describe_rule`**，AI 写代码前一键查规则
+- 修复历史 ID 冲突与逻辑反转 bug：scanner `tag.mjs` 原 R017/R018 重号为 R019/R020（与 `color.mjs` 解耦，旧 ID 通过 `aliases` 兼容）；R011 由"必须放 #footer"反转为"不得放 #footer"，与 standards/ui/05 对齐
+- 清理 `_registry.md` 12 条幽灵 skill 引用；`runtime/style-align/SKILL.md` 改为指针式引用 rules.json，不再复述规则细节
+- `scripts/check-docs.mjs` 扩展为 R-rule / scanner / SKILL / registry 四向一致性守卫，CI 不一致直接红灯
+- 新增 **`docs/governance-long-term.md`**：业务项目长效治理方案（基线 / 豁免 / 漂移看板 / 版本钉死 / 写作期 AI 守护五机制），杜绝遗留累积与升级回归
+
+历史亮点（v1.7.1）：
 
 - 新增 Vite 插件 `@agile-team/wl-skills-ui/vite`：消费方一行配置即可在每次启动 dev/build 时自动跑版本配对校验，偏离时彩色提示 + 修复片段
 - 新增 `npx wl-ui doctor --print-overrides`：检测到偏离直接输出 pnpm/npm/yarn overrides JSON，复制粘贴即可修复

package/docs/governance-long-term.md

@@ -0,0 +1,191 @@
+# 长效治理：业务项目如何避免遗留与漂移污染
+
+> 适用：使用 `@agile-team/wl-skills-ui` 的业务项目，长期迭代过程中**不让历史违规无限累积**、**不让新代码反向污染**、**不让升级回归打穿主干**。
+> 事实源：本文档结合 `standards/rules.json` 单一事实源 + `scanner/snapshot.mjs` + `scanner/exempt.mjs` 共同提供。
+
+## 一、问题画像
+
+业务项目随时间会出现三种"污染"：
+
+| 类型 | 表现 | 根因 |
+| --- | --- | --- |
+| **历史遗留**（legacy） | 旧页面违规但没人修，scanner 报错被忽略 | 一次性扫描门槛太高，团队选择 mute |
+| **风格漂移**（drift） | 同一种场景不同写法，hex 颜色又冒出来 | 没有 PR 级别的增量校验 |
+| **升级回归**（regression） | wl-skills-ui 升版后老页面视觉错乱 | vendor 版本配对没钉死、scoped 样式覆盖底层 |
+
+下面三条机制对应三个根因。
+
+---
+
+## 二、机制 1 · 基线快照（Baseline）
+
+**目标**：把"历史欠债"冻结，新代码只对增量负责。
+
+```bash
+# 在主干分支建立基线（团队第一次接入时执行一次）
+npx wl-ui audit --target src --output json --outFile .wl-baseline.json
+git add .wl-baseline.json && git commit -m "chore: wl-ui baseline snapshot"
+```
+
+`.wl-baseline.json` 记录当前所有违规条目的 `(file, line, ruleId)` 指纹。后续：
+
+```bash
+# PR 检查（仅报新增违规）
+npx wl-ui scan --target src --baseline .wl-baseline.json --fail-on=new-issues
+```
+
+- **历史条目不再阻塞构建**（团队按计划逐步消化）
+- **新代码引入新违规 → 立即红灯**
+- 团队修复历史条目后跑 `npx wl-ui audit --refresh-baseline` 收敛基线
+
+> 实现入口：`scanner/snapshot.mjs` 已具备文件级快照能力，issue 级 baseline 在 v1.8.0 起以 `audit --output json` 输出为契约，业务项目可自行 diff。
+
+---
+
+## 三、机制 2 · 豁免与隔离（Quarantine）
+
+**目标**：大屏、地图、流程设计器等强个性化页面 + 不再迭代的旧模块，明确隔离，**不参与统一风格扫描**。
+
+`.wl-exempt.json`：
+
+```json
+{
+  "exemptPaths": [
+    "src/views/**/big-screen/**",
+    "src/views/**/dashboard/**",
+    "src/views/legacy/**"
+  ],
+  "exemptRules": {
+    "R016": ["src/views/**/chart/**"]
+  },
+  "exemptCategories": ["dashboard", "big-screen", "report-designer"],
+  "description": "大屏与遗留模块豁免风格统一扫描；新功能不得新增豁免路径"
+}
+```
+
+约束（团队规约）：
+
+1. 豁免清单**只能减少**，不能增加（新增需架构组评审 PR）
+2. 豁免路径**禁止承载新业务**；新业务必须落到非豁免目录
+3. 每季度团队负责人审视豁免清单：能解开就解开
+
+> 实现入口：`scanner/exempt.mjs::loadExemptConfig` 已支持 glob + 规则级豁免；CLI/MCP/Vite 插件统一读取。
+
+---
+
+## 四、机制 3 · 漂移看板（Drift Dashboard）
+
+**目标**：让"逐渐变烂"可见，每次升级都能量化。
+
+```bash
+# 每次 wl-skills-ui 升版后跑一次
+npx wl-ui audit --target src --output json --outFile .wl-drift-after.json
+node -e "console.log(require('@agile-team/wl-skills-ui/scanner/drift.mjs').report('.wl-baseline.json','.wl-drift-after.json'))"
+```
+
+输出（示意）：
+
+```
+变化（基线 → 当前）
+  gained   +12  新增违规（红灯）
+  fixed    -45  消化历史（绿灯）
+  regressed +3  曾修过又破的（黄灯，最高优先级追查）
+  exempt    +0  豁免清单未扩张
+按规则 Top3：R017(+8) R001(+3) R009(+1)
+按目录 Top3：src/views/quote(+9) src/views/cost(+3)
+```
+
+> 实现入口：v1.8.0 起 `scanner/index.mjs` 已暴露 `--output json` 完整结构（含 `file/line/rule`），业务项目可基于该结构自实现 drift 报告；包内 `scanner/drift.mjs` 在 1.8.x 后续小版本提供。
+
+---
+
+## 五、机制 4 · 版本钉死（Lock & Detect）
+
+**目标**：vendor（Element Plus / @jhlc/jh-ui）版本飘移导致老页面 DOM 不匹配的问题，**在启动期就发现**，而不是页面坏了才查。
+
+```ts
+// vite.config.ts
+import { wlSkillsCheck } from '@agile-team/wl-skills-ui/runtime/vite/check.mjs'
+
+export default defineConfig({
+  plugins: [
+    wlSkillsCheck({
+      enforce: 'warn',          // 'warn' | 'error'
+      verbose: false,
+    }),
+  ],
+})
+```
+
+启动时输出（不匹配示意）：
+
+```
+[wl-skills-ui] 版本偏离推荐组合：
+  element-plus@2.6.3 ≠ 推荐 2.2.6-prod.3（jh 集群）
+  @jhlc/jh-ui@3.1.0 ✓
+  修复片段：
+    "pnpm": { "overrides": { "element-plus": "2.2.6-prod.3" } }
+```
+
+> 推荐组合 = `skills/_meta/_compat/vendors.json`（事实源）。CLI: `npx wl-ui doctor --print-overrides`。MCP: `wl_ui_detect_skin`。
+
+---
+
+## 六、机制 5 · 写作期 AI 守护（Editor Skill）
+
+**目标**：在 AI 写出新代码的那一刻就让它**对齐 rules.json**，而不是事后扫描。
+
+- 编辑器接入：`npx wl-ui init` 会把 `.cursor/rules` / `.windsurf/rules` 等指向 `skills/` 目录
+- AI 强约束（写入 SKILL 头部）：
+  - 任何样式相关结论必须先通过 MCP `wl_ui_describe_rule` 查 `standards/rules.json`
+  - **禁止**在业务 SFC 的 `<style scoped>` 中覆盖 `.el-*` / `.jh-*` 全局选择器；样式补丁全部归 wl-skills-ui 升级
+  - 新增组件族适配优先升级到 wl-skills-ui，而不是在业务侧封 `Base*` 二代
+
+效果：AI 写出的代码 day-1 即合规，不再产生历史欠债。
+
+---
+
+## 七、典型业务项目接入清单
+
+```bash
+# 1. 安装
+pnpm add -D @agile-team/wl-skills-ui
+
+# 2. 编辑器规则 + MCP + 启动期插件
+npx wl-ui init --project . --mode skin
+
+# 3. 基线
+npx wl-ui audit --target src --outFile .wl-baseline.json --output json
+git add .wl-baseline.json
+
+# 4. 豁免（如有）
+cp node_modules/@agile-team/wl-skills-ui/.wl-exempt.example.json .wl-exempt.json
+# 编辑为本项目实际豁免路径
+
+# 5. CI 加 PR gate
+#   npx wl-ui scan --target src --baseline .wl-baseline.json --fail-on=new-issues
+
+# 6. 每季度 / 每次升级
+npx wl-ui doctor --print-overrides     # 版本对齐
+npx wl-ui audit --refresh-baseline      # 基线收敛
+```
+
+---
+
+## 八、wl-skills-ui 自身的承诺
+
+为了让业务项目"敢于"长期跟随：
+
+1. **R-rule 不删只迁**：v1.8.0 起 `tag.mjs` 的旧 R017/R018 → R019/R020，旧 ID 在 `rules.json.aliases` 保留，scanner 输出兼容
+2. **CSS Token 不破坏**：`design/tokens/base.css` 的变量名为长期契约，重命名走 deprecate → alias → remove 三段式
+3. **vendor 适配可选**：业务项目偏离推荐组合时插件**只警告不阻塞**，由项目方决策升级节奏
+4. **每个 minor 版本附带 compat-matrix 更新**：`docs/compat-matrix.md` 是版本与 vendor 的双向契约
+5. **`docs:check` 守护文档/规则/scanner 一致性**：包级 CI 不通过则不发版
+
+---
+
+## 九、不做的事
+
+- ❌ 不强行重写业务 SFC 结构（除非走 ops/migrate 显式确认）
+- ❌ 不在业务项目里塞自动 commit hook（团队自行选 husky/lefthook）
+- ❌ 不收集业务项目数据（所有扫描结果留在本地或 CI artifact）

package/mcp/server.js

@@ -98,6 +98,60 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "wl_ui_list_rules",
+    description:
+      "列出 wl-skills-ui R-rule 全集（事实源：standards/rules.json）。可按 category / severity / autoFixable 过滤。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description:
+            "可选：table / button / form / dialog / tag / style / base / family / layout",
+        },
+        severity: {
+          type: "string",
+          description: "可选：error / warning / info / suggestion / review",
+        },
+        autoFixable: {
+          type: "boolean",
+          description: "可选：仅返回可自动修复的规则",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "wl_ui_describe_rule",
+    description: "返回单条 R-rule 的完整定义（事实源：standards/rules.json）。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "规则 ID，例如 R001、R019" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "wl_ui_drift",
+    description:
+      "对比基线与当前扫描 JSON，输出漂移报告（gained / fixed / regressed）。用于 PR 级增量门槛。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        baselineJson: {
+          type: "string",
+          description: "基线扫描 JSON 字符串（.wl-baseline.json 的内容）",
+        },
+        currentJson: {
+          type: "string",
+          description: "当前扫描 JSON 字符串",
+        },
+      },
+      required: ["baselineJson", "currentJson"],
+    },
+  },
   {
     name: "wl_ui_recommend_flow",
     description:
@@ -409,6 +463,82 @@ async function dispatchTool(id, name, args) {
       });
       return;
     }
+    if (name === "wl_ui_list_rules") {
+      const loader = await import("../standards/rules-loader.mjs");
+      const rules = loader.listRules({
+        category: args.category,
+        severity: args.severity,
+        autoFixable: args.autoFixable,
+      });
+      const summary = rules.map((r) => ({
+        id: r.id,
+        severity: r.severity,
+        category: r.category,
+        title: r.title,
+        autoFixable: !!r.autoFixable,
+      }));
+      sendResult(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { total: summary.length, rules: summary },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+      return;
+    }
+    if (name === "wl_ui_describe_rule") {
+      const loader = await import("../standards/rules-loader.mjs");
+      const rule = loader.getRule(args.id);
+      if (!rule) {
+        sendResult(id, {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ok: false, reason: `规则 ${args.id} 未注册` },
+                null,
+                2,
+              ),
+            },
+          ],
+        });
+        return;
+      }
+      sendResult(id, {
+        content: [{ type: "text", text: JSON.stringify(rule, null, 2) }],
+      });
+      return;
+    }
+    if (name === "wl_ui_drift") {
+      const { drift, formatDriftJson } = await import("../scanner/drift.mjs");
+      try {
+        const baseline = JSON.parse(args.baselineJson);
+        const current = JSON.parse(args.currentJson);
+        const result = drift(baseline, current);
+        sendResult(id, {
+          content: [{ type: "text", text: formatDriftJson(result) }],
+        });
+      } catch (e) {
+        sendResult(id, {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ok: false, reason: String(e.message) },
+                null,
+                2,
+              ),
+            },
+          ],
+        });
+      }
+      return;
+    }
     if (name === "wl_ui_recommend_flow") {
       sendResult(id, {
         content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 项目通用化妆/原生双模式（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/scanner/drift.mjs

@@ -0,0 +1,179 @@
+/**
+ * scanner/drift.mjs — 漂移检测
+ *
+ * 对比 baseline（基线 JSON）与 current（当前扫描 JSON），输出结构化漂移报告。
+ * 指纹策略：file + rule（行号不稳定，不参与指纹）。同一 file+rule 多条则按数量 diff。
+ *
+ * 用法：
+ *   import { drift, formatDriftText } from '@agile-team/wl-skills-ui/scanner/drift.mjs'
+ *   const result = drift(baselineJson, currentJson)
+ *   console.log(formatDriftText(result))
+ *
+ * CLI（由 scanner/index.mjs 调用）：
+ *   npx wl-ui drift --baseline .wl-baseline.json --current .wl-current.json
+ *
+ * 事实源：standards/rules.json
+ */
+import { readFileSync, existsSync } from "node:fs";
+
+// ── 指纹 ────────────────────────────────────────────────────────────────────
+
+function fingerprint(issue) {
+  return `${issue.file}\x00${issue.rule}`;
+}
+
+function buildCountMap(issues) {
+  const map = new Map();
+  for (const iss of issues) {
+    const key = fingerprint(iss);
+    map.set(key, (map.get(key) || 0) + 1);
+  }
+  return map;
+}
+
+// ── 核心 diff ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} baseline  JSON 扫描结果（含 issues 数组）
+ * @param {object} current   JSON 扫描结果（含 issues 数组）
+ * @returns {DriftResult}
+ */
+export function drift(baseline, current) {
+  const baseIssues = baseline.issues || [];
+  const curIssues = current.issues || [];
+  const baseMap = buildCountMap(baseIssues);
+  const curMap = buildCountMap(curIssues);
+
+  const allKeys = new Set([...baseMap.keys(), ...curMap.keys()]);
+
+  const gained = []; // 新增（当前有、基线无 或 当前 > 基线）
+  const fixed = []; // 消化（基线有、当前无 或 当前 < 基线）
+  const regressed = []; // 回归预留（后续可扩展 fix-then-break 检测）
+
+  for (const key of allKeys) {
+    const [file, rule] = key.split("\x00");
+    const baseCount = baseMap.get(key) || 0;
+    const curCount = curMap.get(key) || 0;
+    const delta = curCount - baseCount;
+    if (delta > 0) {
+      gained.push({ file, rule, delta, baseCount, curCount });
+    } else if (delta < 0) {
+      fixed.push({ file, rule, delta, baseCount, curCount });
+    }
+    // delta === 0 → 无变化，跳过
+  }
+
+  // 按规则 & 目录 聚合
+  const byRule = aggregate(gained, "rule");
+  const byDir = aggregateDir(gained);
+  const fixedByRule = aggregate(fixed, "rule");
+
+  return {
+    baselineTotal: baseIssues.length,
+    currentTotal: curIssues.length,
+    netDelta: curIssues.length - baseIssues.length,
+    gained: { count: sumDelta(gained), items: gained },
+    fixed: { count: Math.abs(sumDelta(fixed)), items: fixed },
+    regressed: { count: 0, items: regressed },
+    topGainedByRule: sortDesc(byRule).slice(0, 5),
+    topGainedByDir: sortDesc(byDir).slice(0, 5),
+    topFixedByRule: sortDesc(fixedByRule).slice(0, 5),
+  };
+}
+
+function sumDelta(arr) {
+  return arr.reduce((s, i) => s + Math.abs(i.delta), 0);
+}
+
+function aggregate(items, field) {
+  const map = new Map();
+  for (const it of items) {
+    const key = it[field];
+    map.set(key, (map.get(key) || 0) + Math.abs(it.delta));
+  }
+  return [...map.entries()].map(([key, count]) => ({ key, count }));
+}
+
+function aggregateDir(items) {
+  const map = new Map();
+  for (const it of items) {
+    const parts = it.file.split("/");
+    const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : ".";
+    map.set(dir, (map.get(dir) || 0) + Math.abs(it.delta));
+  }
+  return [...map.entries()].map(([key, count]) => ({ key, count }));
+}
+
+function sortDesc(arr) {
+  return arr.sort((a, b) => b.count - a.count);
+}
+
+// ── 文本格式化 ──────────────────────────────────────────────────────────────
+
+export function formatDriftText(result) {
+  const lines = [];
+  lines.push("╭──────────────────────────────────────╮");
+  lines.push("│        wl-skills-ui 漂移报告         │");
+  lines.push("╰──────────────────────────────────────╯");
+  lines.push("");
+  lines.push(`基线违规: ${result.baselineTotal}  →  当前违规: ${result.currentTotal}  (${result.netDelta >= 0 ? "+" : ""}${result.netDelta})`);
+  lines.push("");
+  lines.push(`  🔴 gained   +${result.gained.count}  新增违规`);
+  lines.push(`  🟢 fixed    -${result.fixed.count}  消化历史`);
+  if (result.regressed.count > 0) {
+    lines.push(`  🟡 regressed +${result.regressed.count}  回归`);
+  }
+  lines.push("");
+
+  if (result.topGainedByRule.length > 0) {
+    lines.push("新增 Top 规则:");
+    for (const { key, count } of result.topGainedByRule) {
+      lines.push(`  ${key}  +${count}`);
+    }
+    lines.push("");
+  }
+
+  if (result.topGainedByDir.length > 0) {
+    lines.push("新增 Top 目录:");
+    for (const { key, count } of result.topGainedByDir) {
+      lines.push(`  ${key}  +${count}`);
+    }
+    lines.push("");
+  }
+
+  if (result.topFixedByRule.length > 0) {
+    lines.push("消化 Top 规则:");
+    for (const { key, count } of result.topFixedByRule) {
+      lines.push(`  ${key}  -${count}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// ── JSON 格式化 ─────────────────────────────────────────────────────────────
+
+export function formatDriftJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+// ── 文件级便捷 API ──────────────────────────────────────────────────────────
+
+/**
+ * 从两个 JSON 文件路径生成漂移报告
+ * @param {string} baselinePath
+ * @param {string} currentPath
+ * @returns {DriftResult}
+ */
+export function driftFromFiles(baselinePath, currentPath) {
+  if (!existsSync(baselinePath)) {
+    throw new Error(`基线文件不存在: ${baselinePath}`);
+  }
+  if (!existsSync(currentPath)) {
+    throw new Error(`当前扫描结果不存在: ${currentPath}`);
+  }
+  const baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+  const current = JSON.parse(readFileSync(currentPath, "utf8"));
+  return drift(baseline, current);
+}

package/scanner/index.mjs

@@ -11,6 +11,7 @@
  *   wl-scan fix --target <path> --dry-run
  *   wl-scan all --project <path>          # 接入检查 + 风格扫描 + 报告
  *   wl-scan init                          # 打印接入指引
+ *   wl-scan drift --baseline <f> --current <f>  # 漂移检测
  *   wl-scan snapshot list                  # 列出快照
  *   wl-scan snapshot rollback [--id <id>]  # 回退到快照（默认最新）
  *   wl-scan snapshot diff [--id <id>]      # 查看快照与当前差异
@@ -43,6 +44,7 @@ const SUBCOMMANDS = new Set([
   "fix",
   "all",
   "init",
+  "drift",
   "snapshot",
 ]);
 let subcommand = "scan";
@@ -67,6 +69,8 @@ const { values } = parseArgs({
     keep: { type: "string", default: "5" },
     "no-snapshot": { type: "boolean", default: false },
     exempt: { type: "string", default: "" },
+    baseline: { type: "string", default: "" },
+    current: { type: "string", default: "" },
   },
   strict: false,
 });
@@ -263,6 +267,27 @@ if (subcommand === "check") {
   process.exit(values["fail-on-error"] && hasError ? 1 : 0);
 }
 
+if (subcommand === "drift") {
+  const { driftFromFiles, formatDriftText, formatDriftJson } =
+    await import("./drift.mjs");
+  const baselinePath = resolve(values.baseline || ".wl-baseline.json");
+  const currentPath = resolve(values.current);
+  if (!values.current) {
+    console.error(
+      "用法: wl-scan drift --baseline .wl-baseline.json --current .wl-current.json",
+    );
+    process.exit(1);
+  }
+  const result = driftFromFiles(baselinePath, currentPath);
+  if (values.output === "json") {
+    console.log(formatDriftJson(result));
+  } else {
+    console.log(formatDriftText(result));
+  }
+  const hasNew = result.gained.count > 0;
+  process.exit(values["fail-on-error"] && hasNew ? 1 : 0);
+}
+
 if (subcommand === "snapshot") {
   const projectRoot = resolve(values.project);
   const sub = args[0] || "list";