@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/skills/fec-image-generation/scripts/png-qa.mjs

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.png || args.help) {
+  printHelp();
+  process.exit(args.help ? 0 : 1);
+}
+
+try {
+  const image = readPng(args.png);
+  const manifest = args.manifest ? readManifest(args.manifest) : undefined;
+  const report = analyze(image, manifest, Boolean(args.strict));
+  if ((args.format ?? "markdown") === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(renderMarkdown(report));
+  }
+  process.exit(report.ok ? 0 : 2);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+function parseArgs(values) {
+  const parsed = { format: "markdown", strict: false, help: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === "--help" || value === "-h") parsed.help = true;
+    else if (value === "--strict") parsed.strict = true;
+    else if (value === "--png") parsed.png = values[++index];
+    else if (value === "--manifest") parsed.manifest = values[++index];
+    else if (value === "--format") parsed.format = values[++index];
+    else throw new Error(`Unknown argument: ${value}`);
+  }
+  if (parsed.format !== "json" && parsed.format !== "markdown") {
+    throw new Error("--format must be json or markdown");
+  }
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage: node skills/fec-image-generation/scripts/png-qa.mjs --png <file> [--manifest <layout.json>] [--format json|markdown] [--strict]`);
+}
+
+function readManifest(filePath) {
+  const manifest = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return {
+    canvas: manifest.canvas,
+    boxes: Array.isArray(manifest.boxes) ? manifest.boxes : [],
+    connectors: Array.isArray(manifest.connectors) ? manifest.connectors : [],
+  };
+}
+
+function readPng(filePath) {
+  const buffer = fs.readFileSync(filePath);
+  const signature = "89504e470d0a1a0a";
+  if (buffer.subarray(0, 8).toString("hex") !== signature) {
+    throw new Error(`Not a PNG file: ${filePath}`);
+  }
+
+  let offset = 8;
+  let ihdr;
+  const idat = [];
+  while (offset < buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.subarray(offset + 4, offset + 8).toString("ascii");
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+    if (type === "IHDR") {
+      ihdr = {
+        width: data.readUInt32BE(0),
+        height: data.readUInt32BE(4),
+        bitDepth: data[8],
+        colorType: data[9],
+        compression: data[10],
+        filter: data[11],
+        interlace: data[12],
+      };
+    } else if (type === "IDAT") {
+      idat.push(data);
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!ihdr) throw new Error("PNG is missing IHDR");
+  if (ihdr.bitDepth !== 8) throw new Error(`Unsupported PNG bit depth: ${ihdr.bitDepth}`);
+  if (ihdr.compression !== 0 || ihdr.filter !== 0 || ihdr.interlace !== 0) {
+    throw new Error("Unsupported PNG compression/filter/interlace settings");
+  }
+
+  const channels = channelsForColorType(ihdr.colorType);
+  const inflated = zlib.inflateSync(Buffer.concat(idat));
+  const pixels = unfilter(inflated, ihdr.width, ihdr.height, channels);
+  return {
+    path: path.resolve(filePath),
+    width: ihdr.width,
+    height: ihdr.height,
+    colorType: ihdr.colorType,
+    channels,
+    pixels,
+  };
+}
+
+function channelsForColorType(colorType) {
+  if (colorType === 0) return 1;
+  if (colorType === 2) return 3;
+  if (colorType === 4) return 2;
+  if (colorType === 6) return 4;
+  throw new Error(`Unsupported PNG color type: ${colorType}`);
+}
+
+function unfilter(data, width, height, channels) {
+  const stride = width * channels;
+  const output = Buffer.alloc(stride * height);
+  let sourceOffset = 0;
+
+  for (let y = 0; y < height; y += 1) {
+    const filterType = data[sourceOffset];
+    sourceOffset += 1;
+    const rowOffset = y * stride;
+    const previousRowOffset = (y - 1) * stride;
+
+    for (let x = 0; x < stride; x += 1) {
+      const raw = data[sourceOffset + x];
+      const left = x >= channels ? output[rowOffset + x - channels] : 0;
+      const up = y > 0 ? output[previousRowOffset + x] : 0;
+      const upLeft = y > 0 && x >= channels ? output[previousRowOffset + x - channels] : 0;
+      let value;
+      if (filterType === 0) value = raw;
+      else if (filterType === 1) value = raw + left;
+      else if (filterType === 2) value = raw + up;
+      else if (filterType === 3) value = raw + Math.floor((left + up) / 2);
+      else if (filterType === 4) value = raw + paeth(left, up, upLeft);
+      else throw new Error(`Unsupported PNG filter type: ${filterType}`);
+      output[rowOffset + x] = value & 0xff;
+    }
+    sourceOffset += stride;
+  }
+
+  return output;
+}
+
+function paeth(left, up, upLeft) {
+  const estimate = left + up - upLeft;
+  const leftDistance = Math.abs(estimate - left);
+  const upDistance = Math.abs(estimate - up);
+  const upLeftDistance = Math.abs(estimate - upLeft);
+  if (leftDistance <= upDistance && leftDistance <= upLeftDistance) return left;
+  if (upDistance <= upLeftDistance) return up;
+  return upLeft;
+}
+
+function analyze(image, manifest, strict) {
+  const issues = [];
+  const nextActions = new Set();
+  const ink = measureInk(image, strict ? 10 : 18);
+
+  if (image.width < 64 || image.height < 64) {
+    addIssue(issues, nextActions, "image-too-small", "PNG is too small for reliable visual QA.", "Export a larger PNG before review.");
+  }
+
+  if (ink.coverage < (strict ? 0.001 : 0.0002)) {
+    addIssue(issues, nextActions, "blank-image", "PNG appears blank or nearly blank.", "Check the renderer/export target and regenerate the image.");
+  }
+
+  if (ink.bounds) {
+    const pad = strict ? 6 : 3;
+    if (ink.bounds.minX <= pad || ink.bounds.minY <= pad || image.width - ink.bounds.maxX <= pad || image.height - ink.bounds.maxY <= pad) {
+      addIssue(issues, nextActions, "edge-clipping", "Visible content is very close to the PNG edge.", "Increase canvas/viewBox padding or reduce subject scale.");
+    }
+  }
+
+  if (manifest) analyzeManifest(image, manifest, issues, nextActions, strict);
+
+  return {
+    ok: issues.length === 0,
+    image: {
+      path: image.path,
+      width: image.width,
+      height: image.height,
+      colorType: image.colorType,
+      inkCoverage: Number(ink.coverage.toFixed(6)),
+      inkBounds: ink.bounds,
+    },
+    issues,
+    nextActions: [...nextActions],
+  };
+}
+
+function measureInk(image, threshold) {
+  const first = samplePixel(image, 0, 0);
+  let inkPixels = 0;
+  let minX = image.width;
+  let minY = image.height;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const pixel = samplePixel(image, x, y);
+      const differs = colorDistance(pixel, first) > threshold && pixel.a > 8;
+      if (differs) {
+        inkPixels += 1;
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+
+  return {
+    coverage: inkPixels / (image.width * image.height),
+    bounds: inkPixels > 0 ? { minX, minY, maxX, maxY } : null,
+  };
+}
+
+function samplePixel(image, x, y) {
+  const offset = (y * image.width + x) * image.channels;
+  if (image.channels === 1) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: 255 };
+  }
+  if (image.channels === 2) {
+    const value = image.pixels[offset];
+    return { r: value, g: value, b: value, a: image.pixels[offset + 1] };
+  }
+  return {
+    r: image.pixels[offset],
+    g: image.pixels[offset + 1],
+    b: image.pixels[offset + 2],
+    a: image.channels === 4 ? image.pixels[offset + 3] : 255,
+  };
+}
+
+function colorDistance(left, right) {
+  return Math.abs(left.r - right.r) + Math.abs(left.g - right.g) + Math.abs(left.b - right.b) + Math.abs(left.a - right.a);
+}
+
+function analyzeManifest(image, manifest, issues, nextActions, strict) {
+  if (manifest.canvas && (manifest.canvas.width !== image.width || manifest.canvas.height !== image.height)) {
+    addIssue(
+      issues,
+      nextActions,
+      "manifest-canvas-mismatch",
+      `Manifest canvas ${manifest.canvas.width}x${manifest.canvas.height} does not match PNG ${image.width}x${image.height}.`,
+      "Regenerate the manifest from the final export dimensions.",
+    );
+  }
+
+  const boxes = manifest.boxes.map(normalizeBox).filter(Boolean);
+  for (const box of boxes) {
+    if (box.x < 0 || box.y < 0 || box.x + box.width > image.width || box.y + box.height > image.height) {
+      addIssue(issues, nextActions, "box-out-of-bounds", `Box "${box.id}" is outside the canvas.`, "Move out-of-bounds nodes inside the canvas or expand the canvas.");
+    }
+    if (box.label && estimateLabelOverflow(box, strict)) {
+      addIssue(issues, nextActions, "label-overflow", `Box "${box.id}" label is likely to overflow.`, "Wrap or shorten labels, widen boxes, or increase export scale.");
+    }
+  }
+
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const overlap = overlapArea(boxes[i], boxes[j]);
+      if (overlap > 0) {
+        addIssue(issues, nextActions, "box-overlap", `Boxes "${boxes[i].id}" and "${boxes[j].id}" overlap by ${Math.round(overlap)}px^2.`, "Increase node spacing or split dense groups.");
+      }
+    }
+  }
+
+  const boxById = new Map(boxes.map((box) => [box.id, box]));
+  const segments = [];
+  for (const connector of manifest.connectors) {
+    const points = normalizePoints(connector.points);
+    for (let index = 0; index < points.length - 1; index += 1) {
+      const segment = { connector, a: points[index], b: points[index + 1] };
+      segments.push(segment);
+      for (const box of boxes) {
+        if (box.id === connector.from || box.id === connector.to) continue;
+        if (segmentIntersectsBox(segment, box)) {
+          addIssue(issues, nextActions, "connector-through-label", `Connector "${connector.id ?? "unnamed"}" crosses box "${box.id}".`, "Add waypoints around labels or use orthogonal routing.");
+        }
+      }
+    }
+    if ((connector.from && !boxById.has(connector.from)) || (connector.to && !boxById.has(connector.to))) {
+      addIssue(issues, nextActions, "connector-endpoint-missing", `Connector "${connector.id ?? "unnamed"}" references a missing endpoint.`, "Update connector endpoints to match manifest box ids.");
+    }
+  }
+
+  for (let i = 0; i < segments.length; i += 1) {
+    for (let j = i + 1; j < segments.length; j += 1) {
+      if (segments[i].connector === segments[j].connector) continue;
+      if (segmentsStack(segments[i], segments[j], strict ? 4 : 2)) {
+        addIssue(issues, nextActions, "connector-stacking", "Two connector segments are stacked or nearly stacked.", "Offset parallel connectors or bundle them into a labeled shared route.");
+      }
+    }
+  }
+}
+
+function normalizeBox(box) {
+  if (!box || typeof box.id !== "string") return null;
+  const normalized = {
+    id: box.id,
+    x: Number(box.x),
+    y: Number(box.y),
+    width: Number(box.width),
+    height: Number(box.height),
+    label: typeof box.label === "string" ? box.label : "",
+  };
+  if ([normalized.x, normalized.y, normalized.width, normalized.height].some((value) => !Number.isFinite(value))) return null;
+  return normalized;
+}
+
+function normalizePoints(points) {
+  if (!Array.isArray(points)) return [];
+  return points
+    .map((point) => {
+      if (Array.isArray(point)) return { x: Number(point[0]), y: Number(point[1]) };
+      return { x: Number(point?.x), y: Number(point?.y) };
+    })
+    .filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y));
+}
+
+function estimateLabelOverflow(box, strict) {
+  const label = box.label.trim();
+  if (!label) return false;
+  const lines = label.split(/\r?\n/);
+  const maxLine = Math.max(...lines.map((line) => visualLength(line)));
+  const estimatedWidth = maxLine * (strict ? 7.5 : 7);
+  const estimatedHeight = lines.length * (strict ? 18 : 16);
+  return estimatedWidth > Math.max(0, box.width - 12) || estimatedHeight > Math.max(0, box.height - 8);
+}
+
+function visualLength(value) {
+  return [...value].reduce((total, char) => total + (/[\u4e00-\u9fff]/.test(char) ? 2 : 1), 0);
+}
+
+function overlapArea(left, right) {
+  const width = Math.max(0, Math.min(left.x + left.width, right.x + right.width) - Math.max(left.x, right.x));
+  const height = Math.max(0, Math.min(left.y + left.height, right.y + right.height) - Math.max(left.y, right.y));
+  return width * height;
+}
+
+function segmentIntersectsBox(segment, box) {
+  if (pointInsideBox(segment.a, box) || pointInsideBox(segment.b, box)) return true;
+  const edges = [
+    [{ x: box.x, y: box.y }, { x: box.x + box.width, y: box.y }],
+    [{ x: box.x + box.width, y: box.y }, { x: box.x + box.width, y: box.y + box.height }],
+    [{ x: box.x + box.width, y: box.y + box.height }, { x: box.x, y: box.y + box.height }],
+    [{ x: box.x, y: box.y + box.height }, { x: box.x, y: box.y }],
+  ];
+  return edges.some(([a, b]) => segmentsIntersect(segment.a, segment.b, a, b));
+}
+
+function pointInsideBox(point, box) {
+  return point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+}
+
+function segmentsIntersect(a, b, c, d) {
+  const o1 = orientation(a, b, c);
+  const o2 = orientation(a, b, d);
+  const o3 = orientation(c, d, a);
+  const o4 = orientation(c, d, b);
+  if (o1 !== o2 && o3 !== o4) return true;
+  return false;
+}
+
+function orientation(a, b, c) {
+  const value = (b.y - a.y) * (c.x - b.x) - (b.x - a.x) * (c.y - b.y);
+  if (Math.abs(value) < 0.0001) return 0;
+  return value > 0 ? 1 : 2;
+}
+
+function segmentsStack(left, right, tolerance) {
+  const leftHorizontal = Math.abs(left.a.y - left.b.y) <= tolerance;
+  const rightHorizontal = Math.abs(right.a.y - right.b.y) <= tolerance;
+  const leftVertical = Math.abs(left.a.x - left.b.x) <= tolerance;
+  const rightVertical = Math.abs(right.a.x - right.b.x) <= tolerance;
+
+  if (leftHorizontal && rightHorizontal && Math.abs(left.a.y - right.a.y) <= tolerance) {
+    return rangesOverlap([left.a.x, left.b.x], [right.a.x, right.b.x]) > tolerance;
+  }
+  if (leftVertical && rightVertical && Math.abs(left.a.x - right.a.x) <= tolerance) {
+    return rangesOverlap([left.a.y, left.b.y], [right.a.y, right.b.y]) > tolerance;
+  }
+  return false;
+}
+
+function rangesOverlap(left, right) {
+  const a = [Math.min(...left), Math.max(...left)];
+  const b = [Math.min(...right), Math.max(...right)];
+  return Math.max(0, Math.min(a[1], b[1]) - Math.max(a[0], b[0]));
+}
+
+function addIssue(issues, nextActions, code, message, action) {
+  issues.push({ code, message, action });
+  nextActions.add(action);
+}
+
+function renderMarkdown(report) {
+  const lines = [
+    "# PNG QA Report",
+    "",
+    `- Status: ${report.ok ? "ok" : "issues-found"}`,
+    `- Image: ${report.image.width}x${report.image.height}`,
+    `- Ink coverage: ${report.image.inkCoverage}`,
+  ];
+  if (report.image.inkBounds) {
+    lines.push(`- Ink bounds: ${JSON.stringify(report.image.inkBounds)}`);
+  }
+  lines.push("", "## Issues");
+  if (report.issues.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const issue of report.issues) {
+      lines.push(`- ${issue.code}: ${issue.message}`);
+    }
+  }
+  lines.push("", "## Next Actions");
+  if (report.nextActions.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const action of report.nextActions) lines.push(`- ${action}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/skills/fec-implement-from-design/SKILL.md

@@ -41,6 +41,7 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - `modao` — 墨刀原型数据
 - `sketch` — Sketch 选区截图
 - 如以上 MCP 均不可用，请求用户提供设计截图或标注（适用于摹客等无 MCP 工具）
+- 如果没有权威设计稿，但任务明确要求视觉型网站、品牌页、作品集或高审美重设计，可把用户提供或本地生成的分区级参考图作为临时视觉事实来源；这种来源必须先分析后实现，并在计划中标明不是权威设计系统。
 
 ### 2. 读取设计上下文
 
@@ -51,6 +52,9 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - 如果 MCP 提供了资源文件或 SVG / 图片源，直接使用
 - 如果 MCP 已提供真实资源，不要自行造占位资源
 - 如果用户提供截图而非 MCP 数据，从截图中推断布局、颜色、字体等视觉信息
+- 如果使用图像/截图参考，先提取区块结构、视觉层级、主色和功能色、字体气质、间距节奏、媒体位置、交互状态暗示和响应式风险，再写代码。
+- 对多区块页面优先使用清晰的分区级参考图或局部细节图；不要从压缩长图里猜测按钮、字号、间距和组件状态。
+- 视觉参考中的不可读文字、假截图、不可检查素材或冲突状态不能直接照搬；需要转译成项目真实内容、真实状态或明确占位说明。
 
 ### 3. 搜索可复用组件
 
@@ -73,6 +77,7 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - 响应式行为
 - 复用还是新建的决策
 - 设计缺口或歧义点
+- 图像/截图来源的可靠性，以及哪些视觉细节会被项目 token、组件约定或可访问性要求覆盖
 
 ### 5. 按框架实现
 
@@ -113,6 +118,8 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - 除非有合理理由，不要用硬编码替代已 Token 化的样式
 - 不要忽略 hover、active、disabled、loading、empty、error 等状态
 - 摹客等无 MCP 工具场景下，主动向用户索要关键截图和标注信息，不要凭空编造视觉数据
+- 不把生成图像当作可直接复制的代码规范；它只提供视觉证据，最终实现必须服从当前项目组件、token、可访问性和性能边界
+- 不用一张不可读整页图替代分区分析；关键区块、CTA、表单、导航和状态必须可检查
 
 ## Expected Output
 

package/skills/fec-legacy-to-modern-migration/SKILL.md

@@ -14,177 +14,33 @@ description: Use when planning or implementing an intentional migration from Jav
 ## Procedure
 
 1. 先识别目标栈、迁移边界和是否保留 MPA/服务端模板形态。
-2. 选择渐进式或一次性重写策略，并输出迁移分析报告。
-3. 做存量盘点、依赖关系分析和迁移优先级排序。
-4. 按准备、基础层、模块/页面迁移、收尾的顺序推进，每次迁移一个可验证单元。
-5. 每个迁移单元按检查清单验证功能等价、视觉一致、类型安全、可访问性、i18n、资源和样式边界。
-
-## 迁移策略选择
-
-| 策略                        | 适用情况                             | 优点                         | 风险                         |
-| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
-| **渐进式（Strangler Fig）** | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
-| **一次性重写**              | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱     | 周期长、上线压力大、回滚困难 |
-
-**推荐**：优先考虑渐进式，除非项目规模小且业务简单。
-
-## 概念映射
-
-### jQuery → React
-
-| 遗留模式                                   | React 对应                             |
-| ------------------------------------------ | -------------------------------------- |
-| `$(selector).html(content)`                | 声明式 JSX + state 驱动渲染            |
-| `$(document).on('click', '.btn', handler)` | `onClick` + 事件委托由 React 处理      |
-| `$.ajax()` / `$.get()`                     | 项目请求层、`fetch` / `axios`，可按需接 TanStack Query 或 SWR |
-| 全局变量 / 命名空间存储状态                | 局部 state、Context 或项目既有 store，可按需使用 Zustand/Redux |
-| `$(el).show()` / `$(el).hide()`            | 条件渲染 `{visible && <Component />}`  |
-| 手动 DOM 操作 `append` / `remove`          | 数据驱动，通过 setState 触发重渲染     |
-| 模板字符串拼接 HTML                        | JSX 组件 + props                       |
-| 多页面 + 服务端路由                        | React Router 客户端路由                |
-
-### jQuery → Vue 3
-
-| 遗留模式                                   | Vue 3 对应                                         |
-| ------------------------------------------ | -------------------------------------------------- |
-| `$(selector).html(content)`                | 模板 + `ref` / `reactive` 驱动渲染                 |
-| `$(document).on('click', '.btn', handler)` | `@click` + 事件修饰符                              |
-| `$.ajax()` / `$.get()`                     | 项目请求层、`fetch` / `axios`，可按需接 VueUse、Nuxt `useFetch` 或 TanStack Query Vue adapter |
-| 全局变量 / 命名空间存储状态                | `ref` / `reactive` / Pinia                         |
-| `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
-| 手动 DOM 操作                              | 数据驱动，通过响应式更新视图                       |
-| 模板字符串拼接 HTML                        | 单文件组件 `<template>` + props                    |
-| 多页面 + 服务端路由                        | Vue Router 客户端路由                              |
-
-### 通用映射
-
-| 遗留概念                          | 现代对应                                   |
-| --------------------------------- | ------------------------------------------ |
-| 页面级 JS 入口（每页一个 script） | 路由/页面入口 + 懒加载模块，或保留 MPA 入口并现代化打包 |
-| 公共 JS 模块（utils、ajax 封装）  | `services/`、`utils/`、类型化 API 层       |
-| 内联样式 / 页面级 CSS             | 目标项目样式体系，如 CSS Modules、Tailwind、全局样式分层或组件库样式 |
-| 服务端模板变量                    | 通过 API 获取、SSR/loader 注入，或保留服务端模板边界并类型化数据 |
-| 表单提交 + 整页刷新               | 表单库 + 客户端校验 + API 调用             |
-
-## 迁移前分析
-
-在动手迁移前，必须完成以下分析并输出**迁移分析报告**：
-
-1. **存量盘点**
-   - 页面数量、功能模块数量
-   - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
-   - 现有 API 调用方式、是否有统一封装
-   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需要保留、局部替换或改为纯前端渲染
-   - 目标栈是 React/Vue/Next/Nuxt、现代 MPA，还是只做局部 TypeScript/构建/测试现代化
-
-2. **依赖关系**
-   - 页面间共享的 JS/CSS 模块
-   - 跨页面复用的业务逻辑
-   - 与后端的接口契约（是否需调整）
-
-3. **迁移优先级**
-   - 按业务价值、复杂度、耦合度排序
-   - 优先迁移独立模块、低耦合页面
-   - 识别可复用的工具函数、常量、类型定义
-
-## 分阶段迁移流程
-
-### 阶段 0：准备
-
-- 搭建或识别目标项目骨架：React/Vue/Next/Nuxt、现代 MPA，或现有项目内的渐进式 TypeScript/构建入口
-- 配置 ESLint、Prettier、测试框架
-- 建立 `services/request.ts` 统一请求层，与现有 API 兼容
-- 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型
-
-### 阶段 1：基础层
-
-- 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
-- 迁移工具函数（日期、格式化、校验等）
-- 迁移常量、枚举、类型定义
-- 建立目标导航/页面入口骨架；未迁移页面可继续走旧路由、重定向、iframe 或微前端嵌入
-
-### 阶段 2：按模块/页面迁移
-
-- 每次迁移一个完整功能或页面
-- 从简单到复杂：静态页 → 列表页 → 表单页 → 复杂交互页
-- 迁移时提取可复用组件，遵循目标 React 或 Vue 项目的目录结构
-- 每完成一个模块，补充单元测试和 E2E 关键路径
-
-### 阶段 3：收尾
-
-- 按迁移策略移除或冻结旧代码入口；若保留 MPA，则收敛旧入口并完成现代化边界
-- 配置 404、错误边界、全局错误处理
-- 性能优化（懒加载、代码分割、缓存策略）
-- 文档更新、部署流程调整
-
-## 重构实施要求
-
-迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。
-
-### 图片与图标
-
-- 直接使用原项目的图片资源路径，不重新托管或替换
-- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`）；图标组件或可访问交互确需内联 SVG 时，应遵循目标项目图标规范并说明理由。
-- 若原项目使用了 iconfont 或 IcoMoon 图标，重构时优先继续使用，保持图标体系一致；替换为其他图标方案前需评估视觉一致性、包体和维护成本。
-- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
-
-### 国际化（i18n）
-
-- 新栈代码（React / Vue 等）中的用户可见文案须走项目 i18n，不在新代码里硬编码中/英文案
-- 遗留 HTML/JS 中**不要新增**用户可见硬编码文案，除非纯静态且仓库尚无可用 i18n 接入点；改动文案前先查 locales 是否已有条目，并同步主要语言文件
-- key 按页面/模块/语义组织，复用既有 key；仅当旧 key 为对外契约时才做映射过渡，详见项目规则中的 **国际化 (i18n)**（`templates/shared/rules/fec-i18n.md` 内「遗留代码与迁移场景」）
-
-### 样式
-
-- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
-- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
-- 避免不合理写法：如 `!important` 滥用、过深选择器、重复定义
-- 组件中优先避免内联样式（`style={{ ... }}` / `style="..."`）；确需使用运行时动态值、第三方组件 API 或 CSS 变量桥接时，应保持局部、可解释，并优先放入目标项目样式体系。
-
-### 目标
-
-- **视觉和交互**：与原项目一致，用户无感知差异
-- **代码质量**：更简洁、易维护，符合目标框架规范
-- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价
-
-## 迁移检查清单
-
-每个迁移单元完成后，确认：
-
-- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
-- [ ] 类型定义完整，无 `any` 滥用
-- [ ] API 调用使用统一 request 层，错误处理完整
-- [ ] 表单校验、loading、空状态、错误状态已实现
-- [ ] 可访问性：表单有 label、交互可键盘操作
-- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
-- [ ] 关键路径有测试覆盖
-- [ ] 符合目标栈的项目规范（React / Vue / Next / Nuxt / MPA 现代化等）
-- [ ] 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范，例外已说明
-- [ ] 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系，内联样式例外已说明
-- [ ] 视觉与交互与原项目一致，代码更简洁易维护
-- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）
+2. 加载 [references/migration-strategy-and-mapping.md](references/migration-strategy-and-mapping.md)，选择渐进式或一次性重写策略，并明确遗留模式到目标栈的映射。
+3. 加载 [references/migration-execution-checklist.md](references/migration-execution-checklist.md)，完成存量盘点、依赖分析、优先级排序和分阶段迁移计划。
+4. 撰写迁移分析或迁移计划报告时，加载 [references/migration-report-template.md](references/migration-report-template.md)。
+5. 按准备、基础层、模块/页面迁移、收尾的顺序推进，每次迁移一个可验证单元。
+6. 每个迁移单元验证功能等价、视觉一致、类型安全、可访问性、i18n、资源和样式边界。
 
 ## Constraints
 
-- 迁移前必须先输出迁移分析报告，明确策略、优先级和风险
-- 不要在一次迁移中同时改架构、改 UI、改接口
-- 优先保证功能等价，再考虑优化和现代化
-- 迁移过程中保持旧系统可运行，避免大爆炸式上线
-- 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换
-- **目标栈**：先识别 React/Vue/Next/Nuxt、现代 MPA 或局部现代化目标，不默认强制改成 SPA。
-- **图片与图标**：使用原项目图片资源，图标体系优先沿用原项目或目标项目规范；内联 SVG 例外需有可访问性、组件化或维护理由。
-- **样式**：参考原项目效果不照搬 CSS，优先使用目标项目样式体系；内联样式例外需局部、可解释。
-- **目标**：视觉与交互一致、代码更简洁易维护，业务功能不得缺失
-
-## 详细参考
-
-撰写迁移分析或迁移计划报告时，加载 [references/migration-report-template.md](references/migration-report-template.md)。
+- 迁移前必须先输出迁移分析报告，明确策略、优先级和风险。
+- 不要在一次迁移中同时改架构、改 UI、改接口。
+- 优先保证功能等价，再考虑优化和现代化。
+- 迁移过程中保持旧系统可运行，避免大爆炸式上线。
+- 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换。
+- 目标栈先识别 React/Vue/Next/Nuxt、现代 MPA 或局部现代化目标，不默认强制改成 SPA。
+- 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范；内联 SVG 例外需有可访问性、组件化或维护理由。
+- 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系；内联样式例外需局部、可解释。
+- 目标是视觉与交互一致、代码更简洁易维护，业务功能不得缺失。
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须建立重构前后的行为清单，并使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
+- 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。
 
 ## Expected Output
 
-- 迁移分析报告保存为 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案
-- 迁移后的业务功能与原项目完全等价，无功能缺失
-- 视觉与交互与原项目一致，用户无感知差异
-- 类型定义完整，无 `any` 滥用，API 调用统一且类型安全
-- 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由
-- 新代码文案已 i18n，关键路径有测试覆盖
+- 迁移分析报告保存为 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案。
+- 迁移后的业务功能与原项目完全等价，无功能缺失。
+- 视觉与交互与原项目一致，用户无感知差异。
+- 类型定义完整，无 `any` 滥用，API 调用统一且类型安全。
+- 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由。
+- 新代码文案已 i18n，关键路径有测试覆盖。