npm - @agile-team/wl-skills-ui - Versions diffs - 1.6.2 - Mend

@agile-team/wl-skills-ui 1.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (150) hide show

package/CHANGELOG.md +207 -0
package/README.md +623 -0
package/SKILL.md +632 -0
package/bin/wl-ui.js +794 -0
package/design/spec/color.md +41 -0
package/design/spec/spacing.md +28 -0
package/design/spec/typography.md +29 -0
package/design/tokens/base.css +144 -0
package/design/tokens/index.css +8 -0
package/dist/ag-grid-override.scss +1 -0
package/dist/element.scss +1 -0
package/dist/index.scss +1 -0
package/dist/portal.scss +1 -0
package/dist/style-override.scss +1 -0
package/dist/tokens.css +144 -0
package/es/chunk-GBB7LDKQ.js +261 -0
package/es/chunk-MDI2SCUP.js +281 -0
package/es/chunk-QDTNMM7W.js +286 -0
package/es/chunk-YLNAFAWE.js +233 -0
package/es/common-preset.d.ts +38 -0
package/es/common-preset.js +157 -0
package/es/index.d.ts +32 -0
package/es/index.js +1 -0
package/es/presets/security.d.ts +16 -0
package/es/presets/security.js +99 -0
package/es/renderers-BFRSp2BH.d.ts +51 -0
package/es/renderers-DMZbi_Gs.d.ts +51 -0
package/es/renderers-DWhUlI2y.d.ts +47 -0
package/es/types-04qLKHMt.d.ts +62 -0
package/es/types-BrCPjAH6.d.ts +62 -0
package/es/types-QZ1gy9KX.d.ts +63 -0
package/examples/migration-operations-to-renderOps.md +107 -0
package/examples/wk-exempt.example.json +30 -0
package/mcp/server.js +394 -0
package/package.json +130 -0
package/reference/SelectPopupCom.vue +634 -0
package/reference/ag-cell-renders.ts +644 -0
package/reference/define-columns.ts +185 -0
package/reference/jhlc.d.ts +1 -0
package/scanner/coverage.mjs +287 -0
package/scanner/exempt.mjs +127 -0
package/scanner/fix.mjs +216 -0
package/scanner/index.mjs +403 -0
package/scanner/integration.mjs +155 -0
package/scanner/report.mjs +459 -0
package/scanner/rules/_shared.mjs +134 -0
package/scanner/rules/button.mjs +97 -0
package/scanner/rules/color.mjs +118 -0
package/scanner/rules/componentFamily.mjs +184 -0
package/scanner/rules/dialog.mjs +42 -0
package/scanner/rules/form.mjs +86 -0
package/scanner/rules/index.mjs +58 -0
package/scanner/rules/table.mjs +170 -0
package/scanner/rules/tag.mjs +245 -0
package/scanner/snapshot.mjs +198 -0
package/skills/_flows/full-audit.md +65 -0
package/skills/_flows/legacy-skin-align.md +71 -0
package/skills/_flows/new-project-init.md +80 -0
package/skills/_flows/progressive-migrate.md +49 -0
package/skills/_meta/_compat/README.md +47 -0
package/skills/_meta/_compat/editors.json +76 -0
package/skills/_meta/_compat/headers/agents.txt +7 -0
package/skills/_meta/_compat/headers/claude-code.txt +7 -0
package/skills/_meta/_compat/headers/cline.txt +7 -0
package/skills/_meta/_compat/headers/cursor-mdc.txt +5 -0
package/skills/_meta/_compat/headers/github-copilot.txt +5 -0
package/skills/_meta/_compat/headers/kiro.txt +4 -0
package/skills/_meta/_compat/headers/qoder.txt +4 -0
package/skills/_meta/_compat/headers/trae.txt +3 -0
package/skills/_meta/_compat/headers/windsurf.txt +5 -0
package/skills/_meta/_detection.md +81 -0
package/skills/_meta/_registry.md +96 -0
package/skills/element/component-family/SKILL.md +71 -0
package/skills/element/el-dialog/SKILL.md +124 -0
package/skills/element/el-form/SKILL.md +84 -0
package/skills/element/el-table/SKILL.md +86 -0
package/skills/element/el-tag/SKILL.md +127 -0
package/skills/layouts/detail-page/SKILL.md +99 -0
package/skills/layouts/form-dialog/SKILL.md +128 -0
package/skills/layouts/list-page/SKILL.md +111 -0
package/skills/layouts/tree-list/SKILL.md +108 -0
package/skills/ops/audit/SKILL.md +109 -0
package/skills/ops/fix/SKILL.md +52 -0
package/skills/ops/fix/USAGE.md +24 -0
package/skills/ops/migrate/SKILL.md +157 -0
package/skills/ops/scan/SKILL.md +71 -0
package/skills/ops/scan/USAGE.md +16 -0
package/skills/runtime/design-tokens/SKILL.md +88 -0
package/skills/runtime/design-tokens/USAGE.md +19 -0
package/skills/runtime/migration/SKILL.md +106 -0
package/skills/runtime/migration/USAGE.md +34 -0
package/skills/runtime/style-align/SKILL.md +124 -0
package/skills/runtime/style-align/USAGE.md +52 -0
package/skills/vendors/ag-grid/SKILL.md +94 -0
package/skills/vendors/base-table/SKILL.md +57 -0
package/skills/vendors/c-components/SKILL.md +36 -0
package/skills/vendors/custom-wrappers/SKILL.md +45 -0
package/skills/vendors/jh-components/SKILL.md +42 -0
package/skills/vendors/unknown-wrapper/SKILL.md +44 -0
package/standards/engineering/01-import-order.md +46 -0
package/standards/engineering/02-naming.md +54 -0
package/standards/engineering/03-scss-structure.md +59 -0
package/standards/ui/01-table.md +111 -0
package/standards/ui/02-button.md +83 -0
package/standards/ui/03-form.md +118 -0
package/standards/ui/04-tag-status.md +110 -0
package/standards/ui/05-dialog-pagination.md +118 -0
package/styles/element/_card.scss +26 -0
package/styles/element/_descriptions.scss +22 -0
package/styles/element/_dialog.scss +43 -0
package/styles/element/_drawer.scss +22 -0
package/styles/element/_feedback.scss +52 -0
package/styles/element/_form.scss +22 -0
package/styles/element/_navigation.scss +36 -0
package/styles/element/_overlay.scss +32 -0
package/styles/element/_pagination.scss +16 -0
package/styles/element/_steps.scss +32 -0
package/styles/element/_table.scss +13 -0
package/styles/element/_tabs.scss +40 -0
package/styles/element/_tree.scss +27 -0
package/styles/element/_upload.scss +34 -0
package/styles/element/index.scss +17 -0
package/styles/index.scss +21 -0
package/styles/layouts/_detail-page.scss +27 -0
package/styles/layouts/_form-dialog.scss +19 -0
package/styles/layouts/_list-page.scss +47 -0
package/styles/layouts/_tree-list.scss +33 -0
package/styles/layouts/index.scss +6 -0
package/styles/presets/element-only.scss +6 -0
package/styles/presets/full.scss +12 -0
package/styles/presets/security.scss +37 -0
package/styles/presets/skin.scss +14 -0
package/styles/presets/tokens-only.scss +7 -0
package/styles/tokens/index.scss +79 -0
package/styles/vendors/_ag-grid.scss +273 -0
package/styles/vendors/_base-components.scss +480 -0
package/styles/vendors/_base-query-toolbar.scss +253 -0
package/styles/vendors/_base-table.scss +41 -0
package/styles/vendors/_c-components.scss +34 -0
package/styles/vendors/_custom-wrappers.scss +30 -0
package/styles/vendors/_jh-drag-col.scss +63 -0
package/styles/vendors/_jh-pagination.scss +81 -0
package/styles/vendors/_jh-tree.scss +196 -0
package/styles/vendors/_portal.scss +114 -0
package/styles/vendors/index.scss +17 -0
package/templates/ag-grid-page/TPL-AG-GRID.md +76 -0
package/templates/form-dialog/TPL-FORM-DIALOG.md +165 -0
package/templates/list-page/TPL-LIST.md +139 -0
package/templates/tree-list/TPL-TREE-LIST.md +176 -0
package/templates/ui-optimization-report/TPL-UI-OPTIM-REPORT.md +343 -0

package/scanner/integration.mjs ADDED Viewed

@@ -0,0 +1,155 @@
+/**
+ * 接入完整性检查
+ * 检查目标项目是否正确引入了 @agile-team/wk-skills-ui 的样式和 runtime
+ *
+ * 检查项：
+ *   I001 — index.html 是否引入 tokens.css（或同等 css-var-compile.css）
+ *   I002 — main.scss / 全局入口是否引入 @agile-team/wk-skills-ui/styles 或 shared/index.scss
+ *   I003 — src/util/ 是否有 ag-cell-renders.ts 或者 main.ts 中安装了 runtime
+ *   I004 — element-plus 是否在 dependencies 中（peer 兼容）
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+/**
+ * @param {string} projectRoot — 项目根目录（包含 index.html / src / package.json）
+ * @returns {Array<{id, severity, ok, description, suggestion}>}
+ */
+export function checkIntegration(projectRoot) {
+  const checks = [];
+  // ── I001: index.html 加载 tokens.css ─────────────────────────────────
+  const indexHtml = join(projectRoot, "index.html");
+  if (existsSync(indexHtml)) {
+    const html = readFileSync(indexHtml, "utf8");
+    const hasTokens =
+      /(css-var-compile|tokens)\.css/.test(html) ||
+      /wk-skills-ui\/(dist\/tokens|design\/tokens)/.test(html) ||
+      /@agile-team\/wk-skills-ui/.test(html);
+    checks.push({
+      id: "I001",
+      severity: hasTokens ? "info" : "error",
+      ok: hasTokens,
+      description: hasTokens
+        ? "tokens.css 已在 index.html 中引入"
+        : "index.html 缺少 tokens.css 引入",
+      suggestion: hasTokens
+        ? ""
+        : '在 <head> 最先加载：<link rel="stylesheet" href="/node_modules/@agile-team/wk-skills-ui/design/tokens/base.css" />',
+    });
+  } else {
+    checks.push({
+      id: "I001",
+      severity: "warning",
+      ok: false,
+      description: "未找到 index.html",
+      suggestion: "确认 --project 参数指向项目根目录",
+    });
+  }
+  // ── I002: 全局样式入口引入 @agile-team/wk-skills-ui ─────────────────────────
+  const styleEntries = [
+    "src/assets/style/main.scss",
+    "src/assets/style/index.scss",
+    "src/styles/main.scss",
+    "src/styles/index.scss",
+    "src/main.scss",
+    "src/style.scss",
+  ];
+  let styleHit = null;
+  for (const rel of styleEntries) {
+    const p = join(projectRoot, rel);
+    if (existsSync(p)) {
+      styleHit = { rel, content: readFileSync(p, "utf8") };
+      break;
+    }
+  }
+  if (styleHit) {
+    const referenced =
+      /@agile-team\/wk-skills-ui(\/styles)?/.test(styleHit.content) ||
+      /wk-skills-ui(\/dist)?/.test(styleHit.content) ||
+      /shared\/index/.test(styleHit.content);
+    checks.push({
+      id: "I002",
+      severity: referenced ? "info" : "warning",
+      ok: referenced,
+      description: referenced
+        ? `全局样式入口 ${styleHit.rel} 已引入 @agile-team/wk-skills-ui`
+        : `全局样式入口 ${styleHit.rel} 未引入 @agile-team/wk-skills-ui/styles`,
+      suggestion: referenced
+        ? ""
+        : `在 ${styleHit.rel} 末尾添加：@use '@agile-team/wk-skills-ui/styles' as *;`,
+    });
+  } else {
+    checks.push({
+      id: "I002",
+      severity: "warning",
+      ok: false,
+      description: "未找到全局 SCSS 入口（main.scss / index.scss）",
+      suggestion:
+        "在 src/assets/style/main.scss 中 @use '@agile-team/wk-skills-ui/styles' as *;",
+    });
+  }
+  // ── I003: runtime 是否被引入 ─────────────────────────────────────────
+  const utilDir = join(projectRoot, "src/util");
+  const utilHit =
+    existsSync(utilDir) &&
+    (existsSync(join(utilDir, "ag-cell-renders.ts")) ||
+      existsSync(join(utilDir, "define-columns.ts")));
+  let runtimeReferenced = false;
+  // 也检查 main.ts 是否 import runtime
+  for (const entry of ["src/main.ts", "src/main.js", "src/main-core.ts"]) {
+    const p = join(projectRoot, entry);
+    if (
+      existsSync(p) &&
+      /@agile-team\/wk-skills-ui\/runtime/.test(readFileSync(p, "utf8"))
+    ) {
+      runtimeReferenced = true;
+      break;
+    }
+  }
+  const runtimeOk = utilHit || runtimeReferenced;
+  checks.push({
+    id: "I003",
+    severity: runtimeOk ? "info" : "warning",
+    ok: runtimeOk,
+    description: runtimeOk
+      ? "runtime 已可用（util/ag-cell-renders.ts 存在或已 import 包）"
+      : "未发现 runtime 引入（无 src/util/ag-cell-renders.ts，main.ts 也未 import runtime）",
+    suggestion: runtimeOk
+      ? ""
+      : '推荐：在 main.ts 中 import { installCommonPreset } from "@agile-team/wk-skills-ui/runtime/common-preset"; installCommonPreset();',
+  });
+  // ── I004: element-plus 已安装 ────────────────────────────────────────
+  const pkgPath = join(projectRoot, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      const hasEp = !!deps["element-plus"];
+      const hasVue = !!deps["vue"];
+      checks.push({
+        id: "I004",
+        severity: hasEp && hasVue ? "info" : "warning",
+        ok: hasEp && hasVue,
+        description:
+          hasEp && hasVue
+            ? `peer 依赖满足（vue ${deps.vue}，element-plus ${deps["element-plus"]}）`
+            : `peer 依赖缺失：${!hasVue ? "vue " : ""}${!hasEp ? "element-plus" : ""}`,
+        suggestion: hasEp && hasVue ? "" : "pnpm add vue element-plus",
+      });
+    } catch {
+      checks.push({
+        id: "I004",
+        severity: "warning",
+        ok: false,
+        description: "package.json 解析失败",
+        suggestion: "",
+      });
+    }
+  }
+  return checks;
+}

package/scanner/report.mjs ADDED Viewed

@@ -0,0 +1,459 @@
+/**
+ * 报告生成器 v3 — 结构化全量报告模板
+ *
+ * 自动输出以下章节：
+ *   一、接入完整性仪表盘
+ *   二、扫描总览（目录/文件/分类/严重度）
+ *   三、豁免统计
+ *   四、按分类统计（token/表格/表单/按钮/弹窗/标签 …）
+ *   五、按规则统计
+ *   六、按目录 & 文件明细
+ *   七、问题明细（高/中/低）
+ *   八、残留问题与后续建议
+ *   附录：豁免配置 & 快照说明
+ */
+const SEVERITY_LABEL = {
+  error: "🔴 高危",
+  warning: "🟡 中危",
+  info: "🔵 低危",
+};
+const CATEGORY_LABEL = {
+  color: "色值 Token",
+  token: "色值 Token",
+  style: "样式规范",
+  table: "表格 (el-table)",
+  form: "表单 (el-form/input/select)",
+  input: "表单 (el-input)",
+  dialog: "弹窗 (el-dialog)",
+  button: "按钮 / 操作列",
+  tag: "标签 (el-tag)",
+  pagination: "分页 (pagination)",
+  card: "卡片 (el-card)",
+  tabs: "标签页 (el-tabs)",
+  descriptions: "描述列表 (el-descriptions)",
+  tree: "树 (el-tree)",
+  drawer: "抽屉 (el-drawer)",
+  upload: "上传 (el-upload)",
+  steps: "步骤条 (el-steps)",
+  overlay: "弹层 (popover/tooltip/dropdown)",
+  navigation: "导航 (menu/breadcrumb)",
+  feedback: "反馈 (empty/result/alert/badge)",
+};
+const RULE_NAME = {
+  R001: 'el-table-column 缺少 align="center"',
+  R002: "el-table 缺少 empty-text",
+  R003: "BaseTable 缺少 empty-text",
+  R004: "操作列使用文字 el-button",
+  R005: "工具栏 el-button 缺少 icon",
+  R006: 'el-input/el-select 缺少 size="small"',
+  R007: "el-date-picker 缺少 width:100%",
+  R008: "el-form labelWidth 偏小",
+  R009: "状态字段纯文本渲染（应使用 renderTagNode/ElTag）",
+  R010: '分类字段 ElTag 未使用 effect="plain"',
+  R011: "pagination 在 #footer 内（位置错误）",
+  R012: "弹窗内 el-table 缺少 empty-text",
+  R013: "columnsDef 旧格式 operations: []",
+  R014: "selection 列缺少 header-align",
+  R015: "弹窗嵌套表格用 el-button link",
+  R016: "<style> 块硬编码 hex 颜色",
+  R017: "<template> 内硬编码 hex 颜色",
+  R018: "<script> 块硬编码 hex 颜色",
+  R021: 'BaseTable 缺少 render-type="agGrid"',
+  R022: "BaseTable 缺少唯一 cid",
+  R031: "详情/统计卡片建议使用统一场景 class",
+  R032: "el-tabs 建议明确页面场景",
+  R033: "el-descriptions 建议使用 bordered 或统一容器",
+  R034: "el-drawer 建议明确 size",
+  R035: "el-upload 建议配置 tip/限制说明",
+  R036: "el-steps 审批/流程建议明确状态来源",
+  R037: "空/异常反馈建议统一操作入口",
+};
+/* ── helpers ─────────────────────────────────────────────────────────── */
+function buildSummary(issues, fileCount) {
+  const byRule = {};
+  const bySeverity = { error: 0, warning: 0, info: 0 };
+  const byCategory = {};
+  for (const i of issues) {
+    byRule[i.rule] = (byRule[i.rule] || 0) + 1;
+    bySeverity[i.severity] = (bySeverity[i.severity] || 0) + 1;
+    const cat = i.category || "other";
+    byCategory[cat] = (byCategory[cat] || 0) + 1;
+  }
+  return { fileCount, total: issues.length, bySeverity, byRule, byCategory };
+}
+/** 从文件路径提取目录（第一级 + 第二级） */
+function dirOf(filePath) {
+  const parts = filePath.replace(/\\/g, "/").split("/");
+  if (parts.length <= 1) return ".";
+  return parts.slice(0, -1).join("/");
+}
+/** 提取模块目录（取 views/xxx/yyy 级别） */
+function moduleOf(filePath) {
+  const parts = filePath.replace(/\\/g, "/").split("/");
+  // 找到 views 之后取两级
+  const vi = parts.indexOf("views");
+  if (vi >= 0 && parts.length > vi + 2)
+    return parts.slice(vi, vi + 3).join("/");
+  if (vi >= 0 && parts.length > vi + 1)
+    return parts.slice(vi, vi + 2).join("/");
+  // components
+  const ci = parts.indexOf("components");
+  if (ci >= 0 && parts.length > ci + 1)
+    return parts.slice(ci, ci + 2).join("/");
+  return parts.slice(0, 2).join("/");
+}
+/* ── section builders ────────────────────────────────────────────────── */
+function buildIntegrationSection(integration) {
+  if (!integration || integration.length === 0) return [];
+  const lines = ["## 一、接入完整性仪表盘", ""];
+  const okCount = integration.filter((c) => c.ok).length;
+  lines.push(`**通过：${okCount} / ${integration.length}**`);
+  lines.push("");
+  lines.push("| 编号 | 检查项 | 结果 | 说明 |");
+  lines.push("|------|--------|------|------|");
+  for (const c of integration) {
+    const icon = c.ok
+      ? "✅ 通过"
+      : c.severity === "error"
+        ? "❌ 未通过"
+        : "⚠️ 警告";
+    const note = c.ok ? "—" : c.suggestion || "";
+    lines.push(`| ${c.id} | ${c.description} | ${icon} | ${note} |`);
+  }
+  lines.push("");
+  return lines;
+}
+function buildOverviewSection(issues, fileCount, extras) {
+  const summary = buildSummary(issues, fileCount);
+  const scannedFiles = fileCount - (extras.exemptFileCount || 0);
+  const affectedFiles = new Set(issues.map((i) => i.file));
+  const affectedDirs = new Set(issues.map((i) => dirOf(i.file)));
+  const cleanFiles = scannedFiles - affectedFiles.size;
+  const coverageRate =
+    scannedFiles > 0 ? ((cleanFiles / scannedFiles) * 100).toFixed(1) : "100.0";
+  const lines = ["## 二、扫描总览", ""];
+  lines.push("| 维度 | 数量 |");
+  lines.push("|------|------|");
+  lines.push(`| 扫描 .vue 文件总数 | **${fileCount}** |`);
+  lines.push(
+    `| 实际检查文件数 | **${scannedFiles}**（豁免 ${extras.exemptFileCount || 0}） |`,
+  );
+  lines.push(`| 涉及问题的文件数 | **${affectedFiles.size}** |`);
+  lines.push(`| 涉及问题的目录数 | **${affectedDirs.size}** |`);
+  lines.push(
+    `| 发现问题总数 | **${summary.total}**（🔴 ${summary.bySeverity.error} / 🟡 ${summary.bySeverity.warning} / 🔵 ${summary.bySeverity.info}） |`,
+  );
+  lines.push(
+    `| 规范覆盖率（无问题文件占比） | **${coverageRate}%**（${cleanFiles} / ${scannedFiles}） |`,
+  );
+  lines.push(`| 分类数 | **${Object.keys(summary.byCategory).length}** |`);
+  lines.push("");
+  return { lines, summary };
+}
+function buildExemptSection(extras) {
+  const lines = [];
+  const exemptFileCount = extras.exemptFileCount || 0;
+  const exemptedIssueCount = extras.exemptedIssueCount || 0;
+  const exemptPaths = extras.exemptPaths || [];
+  if (
+    exemptFileCount === 0 &&
+    exemptedIssueCount === 0 &&
+    exemptPaths.length === 0
+  )
+    return lines;
+  lines.push("## 三、豁免统计");
+  lines.push("");
+  lines.push("| 维度 | 数量 |");
+  lines.push("|------|------|");
+  lines.push(`| 豁免文件数 | **${exemptFileCount}** |`);
+  lines.push(`| 豁免问题数 | **${exemptedIssueCount}** |`);
+  lines.push(`| 豁免路径规则数 | **${exemptPaths.length}** |`);
+  lines.push("");
+  if (exemptPaths.length > 0) {
+    lines.push("豁免路径：");
+    lines.push("");
+    for (const p of exemptPaths) lines.push(`- \`${p}\``);
+    lines.push("");
+  }
+  return lines;
+}
+function buildCategorySection(summary) {
+  const lines = ["## 四、按分类统计", ""];
+  lines.push("| 分类 | 说明 | 问题数 |");
+  lines.push("|------|------|--------|");
+  const sorted = Object.entries(summary.byCategory).sort((a, b) => b[1] - a[1]);
+  for (const [cat, count] of sorted) {
+    const label = CATEGORY_LABEL[cat] || cat;
+    lines.push(`| ${cat} | ${label} | **${count}** |`);
+  }
+  lines.push("");
+  return lines;
+}
+function buildRuleSection(summary) {
+  if (Object.keys(summary.byRule).length === 0) return [];
+  const lines = ["## 五、按规则统计", ""];
+  lines.push("| 规则 | 名称 | 严重度 | 数量 |");
+  lines.push("|------|------|--------|------|");
+  const sortedRules = Object.entries(summary.byRule).sort(
+    (a, b) => b[1] - a[1],
+  );
+  for (const [rule, count] of sortedRules) {
+    const name = RULE_NAME[rule] || "";
+    const sev =
+      rule.startsWith("R01") && parseInt(rule.slice(1)) <= 15
+        ? "🔴/🟡"
+        : "🟡/🔵";
+    lines.push(`| ${rule} | ${name} | ${sev} | **${count}** |`);
+  }
+  lines.push("");
+  return lines;
+}
+function buildDirFileSection(issues) {
+  const lines = ["## 六、按目录 & 文件明细", ""];
+  // 按模块分组
+  const byModule = {};
+  for (const i of issues) {
+    const mod = moduleOf(i.file);
+    if (!byModule[mod]) byModule[mod] = {};
+    if (!byModule[mod][i.file]) byModule[mod][i.file] = [];
+    byModule[mod][i.file].push(i);
+  }
+  const sortedModules = Object.keys(byModule).sort();
+  for (const mod of sortedModules) {
+    const files = byModule[mod];
+    const fileCount = Object.keys(files).length;
+    const issueCount = Object.values(files).reduce(
+      (s, arr) => s + arr.length,
+      0,
+    );
+    lines.push(`### 📁 ${mod}（${fileCount} 个文件，${issueCount} 个问题）`);
+    lines.push("");
+    lines.push("| 文件 | 问题数 | 高危 | 中危 | 低危 | 主要规则 |");
+    lines.push("|------|--------|------|------|------|----------|");
+    for (const [file, fileIssues] of Object.entries(files).sort()) {
+      const shortFile = file.split("/").pop();
+      const sevCounts = { error: 0, warning: 0, info: 0 };
+      const ruleSet = new Set();
+      for (const fi of fileIssues) {
+        sevCounts[fi.severity]++;
+        ruleSet.add(fi.rule);
+      }
+      const topRules = [...ruleSet].slice(0, 3).join(", ");
+      lines.push(
+        `| \`${shortFile}\` | ${fileIssues.length} | ${sevCounts.error} | ${sevCounts.warning} | ${sevCounts.info} | ${topRules} |`,
+      );
+    }
+    lines.push("");
+  }
+  return lines;
+}
+function buildDetailSection(issues) {
+  if (issues.length === 0) {
+    return [
+      "## 七、问题明细",
+      "",
+      "✅ **所有风格检查项均已通过，无需修复。**",
+      "",
+    ];
+  }
+  const lines = ["## 七、问题明细", ""];
+  for (const sev of ["error", "warning", "info"]) {
+    const group = issues.filter((i) => i.severity === sev);
+    if (group.length === 0) continue;
+    lines.push(`### ${SEVERITY_LABEL[sev]}（${group.length} 项）`);
+    lines.push("");
+    lines.push("| 规则 | 分类 | 文件 | 行号 | 问题描述 | 修复建议 |");
+    lines.push("|------|------|------|------|----------|----------|");
+    for (const i of group) {
+      const shortFile = i.file.length > 60 ? "..." + i.file.slice(-55) : i.file;
+      lines.push(
+        `| ${i.rule} | ${i.category || "-"} | \`${shortFile}\` | ${i.line} | ${i.description} | ${i.suggestion} |`,
+      );
+    }
+    lines.push("");
+  }
+  return lines;
+}
+function buildCoverageSection(extras) {
+  const coverage = extras.coverage;
+  const recommendations = extras.recommendations;
+  if (!coverage && !recommendations) return [];
+  const lines = ["## 八、组件覆盖与 AI 下一步建议", ""];
+  if (coverage) {
+    lines.push("### 组件覆盖");
+    lines.push("");
+    lines.push("| 类型 | 命中 |");
+    lines.push("|------|------|");
+    lines.push(
+      `| Element Plus | ${(coverage.element || []).map((v) => `\`${v}\``).join(", ") || "—"} |`,
+    );
+    lines.push(
+      `| Vendor 封装 | ${(coverage.vendors || []).map((v) => `\`${v}\``).join(", ") || "—"} |`,
+    );
+    lines.push(
+      `| Layout 场景 | ${(coverage.layouts || []).map((v) => `\`${v}\``).join(", ") || "—"} |`,
+    );
+    lines.push(
+      `| B 端业务场景 | ${(coverage.businessScenarios || []).map((v) => `\`${v}\``).join(", ") || "—"} |`,
+    );
+    lines.push(
+      `| 推荐 Skills | ${(coverage.recommendedSkills || []).map((v) => `\`${v}\``).join(", ") || "—"} |`,
+    );
+    lines.push("");
+  }
+  if (recommendations) {
+    lines.push("### 推荐流程");
+    lines.push("");
+    for (const flow of recommendations.recommendedFlows || []) {
+      lines.push(`- \`${flow}\``);
+    }
+    lines.push("");
+    lines.push("### 下一步");
+    lines.push("");
+    for (const action of recommendations.nextActions || []) {
+      lines.push(`- ${action}`);
+    }
+    lines.push("");
+    if (recommendations.kitBridge) {
+      lines.push("### wl-skills-kit 桥接判断");
+      lines.push("");
+      lines.push(
+        `- 是否建议桥接：**${recommendations.kitBridge.needed ? "是" : "否"}**`,
+      );
+      lines.push(`- 原因：${recommendations.kitBridge.reason}`);
+      if (recommendations.kitBridge.commands?.length) {
+        lines.push("- 建议命令：");
+        for (const command of recommendations.kitBridge.commands) {
+          lines.push(`  - \`${command}\``);
+        }
+      }
+      lines.push("");
+    }
+  }
+  return lines;
+}
+function buildFooter() {
+  const lines = [];
+  lines.push("## 九、快照与回滚说明");
+  lines.push("");
+  lines.push("`.wk-snapshot/` 是 `wk-skills-ui` 自动生成的修复前快照目录。");
+  lines.push("每次执行 `wk-ui fix` 前会自动备份即将修改的文件，支持一键回退。");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("wk-ui snapshot list              # 列出所有快照");
+  lines.push("wk-ui snapshot diff --id <id>    # 查看某次快照与当前差异");
+  lines.push("wk-ui snapshot rollback --id <id> # 回滚到指定快照");
+  lines.push("wk-ui snapshot clean --keep 3    # 仅保留最近 3 个快照");
+  lines.push("```");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("> 由 `wk-skills-ui` scanner 自动生成。修复前请经用户确认。");
+  lines.push("> 回退命令：`npx wk-scan snapshot rollback`");
+  return lines;
+}
+/* ── 主入口 ──────────────────────────────────────────────────────────── */
+export function generateReport(
+  issues,
+  fileCount,
+  format = "markdown",
+  extras = {},
+) {
+  if (format === "json") {
+    return JSON.stringify(
+      {
+        summary: buildSummary(issues, fileCount),
+        integration: extras.integration || null,
+        componentCoverage: extras.coverage || null,
+        recommendedSkills: extras.coverage?.recommendedSkills || [],
+        recommendations: extras.recommendations || null,
+        issues,
+      },
+      null,
+      2,
+    );
+  }
+  return buildMarkdown(issues, fileCount, extras);
+}
+function buildMarkdown(issues, fileCount, extras = {}) {
+  const lines = [];
+  const ts = new Date().toISOString().slice(0, 10);
+  lines.push("# UI 风格对齐扫描报告");
+  lines.push("");
+  lines.push(`> 生成时间：${ts}`);
+  lines.push("> 工具版本：@agile-team/wk-skills-ui");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  const hasInt = !!(extras.integration && extras.integration.length);
+  const hasExempt = !!(
+    extras.exemptFileCount ||
+    extras.exemptedIssueCount ||
+    (extras.exemptPaths && extras.exemptPaths.length)
+  );
+  // 一、接入完整性
+  if (hasInt) lines.push(...buildIntegrationSection(extras.integration));
+  // 二、扫描总览
+  const { lines: overviewLines, summary } = buildOverviewSection(
+    issues,
+    fileCount,
+    extras,
+  );
+  lines.push(...overviewLines);
+  // 三、豁免统计
+  if (hasExempt) lines.push(...buildExemptSection(extras));
+  // 四、按分类统计
+  if (Object.keys(summary.byCategory).length > 0)
+    lines.push(...buildCategorySection(summary));
+  // 五、按规则统计
+  lines.push(...buildRuleSection(summary));
+  // 六、按目录 & 文件明细
+  if (issues.length > 0) lines.push(...buildDirFileSection(issues));
+  // 七、问题明细
+  lines.push(...buildDetailSection(issues));
+  // 八、组件覆盖与推荐
+  lines.push(...buildCoverageSection(extras));
+  // 九、快照说明 & 页脚
+  lines.push(...buildFooter());
+  return lines.join("\n");
+}