@bovinphang/frontend-craft 2.5.0 → 2.7.0

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

@@ -1,180 +1,46 @@
 ---
 name: fec-legacy-to-modern-migration
-description: Use when planning or implementing an intentional migration from JavaScript, jQuery, HTML/CSS, server-rendered templates, or MPA legacy frontend code to React + TypeScript or Vue 3 + TypeScript while preserving behavior. Do not use for routine legacy bug fixes that stay in the old stack; Chinese triggers include 遗留项目, 技术栈升级, jQuery 迁移.
+description: Use when planning or implementing an intentional migration from JavaScript, jQuery, HTML/CSS, server-rendered templates, MPA legacy frontend code, or older framework code toward a modern frontend stack while preserving behavior. Do not use for routine legacy bug fixes that stay in the old stack; Chinese triggers include 遗留项目, 技术栈升级, jQuery 迁移.
 ---
 
 # 传统前端到现代框架迁移
 
-适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）或服务端模板渲染项目，迁移至 React + TypeScript 或 Vue 3 + TypeScript 单页面应用（SPA）的场景。
+适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）、服务端模板渲染项目或旧框架代码，渐进迁移到 React、Vue、Next.js、Nuxt、TypeScript，或保留 MPA 形态但现代化模块、构建、类型和测试的场景。
 
 ## Purpose
 
-指导将 jQuery/MPA 传统前端项目渐进迁移至 React + TypeScript 或 Vue 3 + TypeScript，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。
+指导传统前端项目渐进迁移到目标现代栈，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。
 
-## 迁移策略选择
+## Procedure
 
-| 策略                        | 适用情况                             | 优点                         | 风险                         |
-| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
-| **渐进式（Strangler Fig）** | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
-| **一次性重写**              | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱     | 周期长、上线压力大、回滚困难 |
-
-**推荐**：优先考虑渐进式，除非项目规模小且业务简单。
-
-## 概念映射
-
-### jQuery → React
-
-| 遗留模式                                   | React 对应                             |
-| ------------------------------------------ | -------------------------------------- |
-| `$(selector).html(content)`                | 声明式 JSX + state 驱动渲染            |
-| `$(document).on('click', '.btn', handler)` | `onClick` + 事件委托由 React 处理      |
-| `$.ajax()` / `$.get()`                     | `fetch` / `axios` + React Query 或 SWR |
-| 全局变量 / 命名空间存储状态                | `useState` / `useContext` / Zustand    |
-| `$(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 `useFetch` 或 Vue Query |
-| 全局变量 / 命名空间存储状态                | `ref` / `reactive` / Pinia                         |
-| `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
-| 手动 DOM 操作                              | 数据驱动，通过响应式更新视图                       |
-| 模板字符串拼接 HTML                        | 单文件组件 `<template>` + props                    |
-| 多页面 + 服务端路由                        | Vue Router 客户端路由                              |
-
-### 通用映射
-
-| 遗留概念                          | 现代对应                                   |
-| --------------------------------- | ------------------------------------------ |
-| 页面级 JS 入口（每页一个 script） | 路由 + 懒加载页面组件                      |
-| 公共 JS 模块（utils、ajax 封装）  | `services/`、`utils/`、类型化 API 层       |
-| 内联样式 / 页面级 CSS             | CSS Modules / Tailwind / styled-components |
-| 服务端模板变量                    | 通过 API 获取 + 前端状态管理               |
-| 表单提交 + 整页刷新               | 表单库 + 客户端校验 + API 调用             |
-
-## 迁移前分析
-
-在动手迁移前，必须完成以下分析并输出**迁移分析报告**：
-
-1. **存量盘点**
-   - 页面数量、功能模块数量
-   - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
-   - 现有 API 调用方式、是否有统一封装
-   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需改为纯前端渲染
-
-2. **依赖关系**
-   - 页面间共享的 JS/CSS 模块
-   - 跨页面复用的业务逻辑
-   - 与后端的接口契约（是否需调整）
-
-3. **迁移优先级**
-   - 按业务价值、复杂度、耦合度排序
-   - 优先迁移独立模块、低耦合页面
-   - 识别可复用的工具函数、常量、类型定义
-
-## 分阶段迁移流程
-
-### 阶段 0：准备
-
-- 搭建新项目脚手架（Vite + React/Vue + TypeScript）
-- 配置 ESLint、Prettier、测试框架
-- 建立 `services/request.ts` 统一请求层，与现有 API 兼容
-- 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型
-
-### 阶段 1：基础层
-
-- 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
-- 迁移工具函数（日期、格式化、校验等）
-- 迁移常量、枚举、类型定义
-- 建立路由骨架，占位未迁移页面（重定向或 iframe 嵌入旧页面）
-
-### 阶段 2：按模块/页面迁移
-
-- 每次迁移一个完整功能或页面
-- 从简单到复杂：静态页 → 列表页 → 表单页 → 复杂交互页
-- 迁移时提取可复用组件，遵循目标 React 或 Vue 项目的目录结构
-- 每完成一个模块，补充单元测试和 E2E 关键路径
-
-### 阶段 3：收尾
-
-- 移除旧代码入口，全面切换至 SPA
-- 配置 404、错误边界、全局错误处理
-- 性能优化（懒加载、代码分割、缓存策略）
-- 文档更新、部署流程调整
-
-## 重构实施要求
-
-迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。
-
-### 图片与图标
-
-- 直接使用原项目的图片资源路径，不重新托管或替换
-- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`），**禁止使用内联 SVG**（`<svg>...</svg>` 直接写在组件中）
-- **若原项目使用了 iconfont 或 IcoMoon 图标，重构时继续使用**，保持图标体系一致；不替换为其他图标方案（如独立 SVG、其他图标库）
-- 图标优先使用原项目已有的图标文件（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="..."`），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护
-
-### 目标
-
-- **视觉和交互**：与原项目一致，用户无感知差异
-- **代码质量**：更简洁、易维护，符合目标框架规范
-- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价
-
-## 迁移检查清单
-
-每个迁移单元完成后，确认：
-
-- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
-- [ ] 类型定义完整，无 `any` 滥用
-- [ ] API 调用使用统一 request 层，错误处理完整
-- [ ] 表单校验、loading、空状态、错误状态已实现
-- [ ] 可访问性：表单有 label、交互可键盘操作
-- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
-- [ ] 关键路径有测试覆盖
-- [ ] 符合目标框架的项目规范（参考目标 React / Vue 项目约定）
-- [ ] 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
-- [ ] 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
-- [ ] 视觉与交互与原项目一致，代码更简洁易维护
-- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）
+1. 先识别目标栈、迁移边界和是否保留 MPA/服务端模板形态。
+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 或微前端方式嵌入，待后续替换
-- **图片与图标**：使用原项目图片资源，可用 SVG 文件，禁止内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
-- **样式**：参考原项目效果不照搬 CSS，优先 flex 布局，组件禁止内联样式
-- **目标**：视觉与交互一致、代码更简洁易维护，业务功能不得缺失
-
-## Detailed References
-
-撰写迁移分析或迁移计划报告时，加载 [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 调用统一且类型安全
-- 图片使用原项目资源，样式使用 flex 布局，无内联样式
-- 新代码文案已 i18n，关键路径有测试覆盖
+- 迁移分析报告保存为 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案。
+- 迁移后的业务功能与原项目完全等价，无功能缺失。
+- 视觉与交互与原项目一致，用户无感知差异。
+- 类型定义完整，无 `any` 滥用，API 调用统一且类型安全。
+- 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由。
+- 新代码文案已 i18n，关键路径有测试覆盖。

package/skills/fec-legacy-to-modern-migration/references/migration-execution-checklist.md

@@ -0,0 +1,110 @@
+# 迁移执行与检查清单
+
+## 迁移前分析
+
+在动手迁移前，必须完成以下分析并输出**迁移分析报告**：
+
+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 变量桥接时，应保持局部、可解释，并优先放入目标项目样式体系。
+
+### 目标
+
+- **视觉和交互**：与原项目一致，用户无感知差异
+- **代码质量**：更简洁、易维护，符合目标框架规范
+- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价
+
+### 验证分层
+
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，先建立重构前后的行为清单，再使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
+- 对视觉敏感页面，补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。
+
+## 迁移检查清单
+
+每个迁移单元完成后，确认：
+
+- [ ] 已建立重构前后的行为清单，覆盖公共 API、路由、表单、权限、错误状态、缓存、埋点和关键交互
+- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
+- [ ] 涉及 UI、交互或关键流程的迁移已使用 Playwright 或同等真实浏览器验证方式完成关键路径对比
+- [ ] 视觉敏感页面已完成截图对比或人工截图验收，并说明动态内容、动画、字体和环境差异处理方式
+- [ ] 纯逻辑、类型、构建或无 UI 迁移已选择更贴近风险的验证层，不强制套用 Playwright
+- [ ] 类型定义完整，无 `any` 滥用
+- [ ] API 调用使用统一 request 层，错误处理完整
+- [ ] 表单校验、loading、空状态、错误状态已实现
+- [ ] 可访问性：表单有 label、交互可键盘操作
+- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
+- [ ] 关键路径有测试覆盖
+- [ ] 符合目标栈的项目规范（React / Vue / Next / Nuxt / MPA 现代化等）
+- [ ] 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范，例外已说明
+- [ ] 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系，内联样式例外已说明
+- [ ] 视觉与交互与原项目一致，代码更简洁易维护
+- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）

package/skills/fec-legacy-to-modern-migration/references/migration-strategy-and-mapping.md

@@ -0,0 +1,48 @@
+# 迁移策略与概念映射
+
+## 迁移策略选择
+
+| 策略                        | 适用情况                             | 优点                         | 风险                         |
+| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
+| **渐进式（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 调用             |

package/skills/fec-legacy-web-standard/SKILL.md

@@ -18,7 +18,7 @@ description: Use when maintaining or safely modifying existing non-framework fro
 5. HTML/CSS 保持语义、label、alt、BEM/既有命名和低选择器深度。
 6. 安全重点检查 `.html()`、`innerHTML`、URL 参数渲染、CSRF token 和文件上传。
 
-## Detailed References
+## 详细参考
 
 涉及 jQuery 命名空间、事件绑定、Ajax、XSS 转义、文件组织和维护清单示例时，加载 [references/legacy-patterns.md](references/legacy-patterns.md)。
 

package/skills/fec-list-virtualization/SKILL.md

@@ -12,14 +12,14 @@ description: Use when optimizing or reviewing large lists, virtual scrolling, wi
 ## Procedure
 
 1. 先确认列表规模和瓶颈：500+ 项、滚动掉帧、DOM 节点过多或内存飙升才引入虚拟化。
-2. 固定高度列表用 `react-window`；动态高度、跨框架或高级场景用 TanStack Virtual；遗留项目可维护 `react-virtualized`。
+2. 先遵循项目现有框架、依赖和设计系统约束，再按场景选库：React 可考虑 `react-window` 或 TanStack Virtual；Vue/Solid/Svelte、动态测量、网格或跨框架场景优先考虑 TanStack Virtual；遗留 `react-virtualized` 只维护不新增。
 3. 明确 item size、overscan、容器高度、key、滚动容器和 resize 行为。
 4. 无限滚动时分离数据分页和 DOM 虚拟化；数据获取可联用数据获取 workflow。
 5. 验证 DOM 节点数、滚动 FPS、键盘/屏幕阅读器体验和 Ctrl+F/SEO 限制。
 
-## Detailed References
+## 详细参考
 
-涉及固定高度列表、可变/动态高度、无限滚动、网格虚拟化和性能注意事项时，加载 [references/virtualization-patterns.md](references/virtualization-patterns.md)。
+涉及是否需要虚拟化、库选型、固定高度、可变/动态高度、无限滚动、网格虚拟化和性能注意事项时，加载 [references/virtualization-patterns.md](references/virtualization-patterns.md)。
 
 ## Constraints
 

package/skills/fec-list-virtualization/references/virtualization-patterns.md

@@ -1,6 +1,34 @@
 # 虚拟列表模式
 
-## 固定高度列表
+## 先判断是否需要虚拟化
+
+- 只有列表规模、渲染成本或滚动性能已经形成瓶颈时才引入虚拟化；小列表、轻量静态列表和分页后可控的列表不需要。
+- SEO 关键内容、依赖浏览器原生 Ctrl+F 的全文内容、需要一次性打印/导出的内容，不要只存在于虚拟项中。
+- 虚拟化只减少 DOM 渲染成本，不替代数据分页、接口缓存、图片懒加载或复杂行组件的渲染优化。
+
+## 选型参考
+
+先沿用项目已有虚拟列表库和框架约定；新增依赖时再按场景选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React 固定高度列表 | `react-window` 或 TanStack Virtual | `react-window` 轻量稳定；TanStack Virtual 更适合统一复杂场景。 |
+| React 可变高度列表 | `react-window` 的 `VariableSizeList` 或 TanStack Virtual | 高度可计算时两者都可用；内容真实高度会变化时需要测量和重置。 |
+| 动态测量、聊天流、展开行 | TanStack Virtual | 配合 `measureElement` / ResizeObserver，处理布局抖动和滚动锚点。 |
+| Vue / Solid / Svelte / 跨框架 | TanStack Virtual 或项目既有生态库 | 不要为非 React 项目引入 React-only 虚拟列表库。 |
+| 二维网格、表格、列虚拟化 | TanStack Virtual row/column 双轴方案或现有表格库虚拟化能力 | 固定列、粘性表头和键盘导航需要单独验证。 |
+| 遗留 `react-virtualized` 项目 | 维护现有实现 | 不建议新功能继续扩散；大改时评估迁移成本。 |
+
+## 通用实现原则
+
+- 容器高度必须稳定，滚动容器必须明确，item key 必须来自稳定业务标识。
+- 行根元素必须透传虚拟库提供的 `style`、定位属性和测量 ref。
+- `overscan` 按设备和行渲染成本调节：过小会白屏，过大会接近全量渲染。
+- 动态高度需要估算高度、真实测量、resize 更新和滚动锚点策略。
+- 无限滚动要分离“数据分页”和“DOM 虚拟化”；不要在 render 阶段无条件触发请求。
+- 验证键盘导航、屏幕阅读器语义、焦点保持、滚动恢复、空态/加载态和错误态。
+
+## React 固定高度示例
 
 ```tsx
 import { FixedSizeList as List } from "react-window";
@@ -16,7 +44,7 @@ export const UserList = ({ users }: { users: User[] }) => (
 );
 ```
 
-## 可变高度
+## React 可变高度示例
 
 ```tsx
 import { VariableSizeList as List } from "react-window";
@@ -28,7 +56,7 @@ const getItemSize = (index: number) => (items[index].hasSummary ? 120 : 60);
 </List>;
 ```
 
-## 动态高度
+## TanStack Virtual 动态高度示例
 
 ```tsx
 const virtualizer = useVirtualizer({
@@ -39,7 +67,7 @@ const virtualizer = useVirtualizer({
 });
 ```
 
-动态内容需要测量元素并处理 ResizeObserver。
+动态内容需要测量元素并处理 ResizeObserver；Vue/Solid/Svelte 项目使用 TanStack Virtual 对应框架 adapter，核心选项保持一致。
 
 ## 无限滚动
 

package/skills/fec-motion-interaction/SKILL.md

@@ -31,12 +31,16 @@ description: Use when designing, implementing, or reviewing frontend interaction
    - Level 3-4：加入短 stagger、局部 spring 和轻量 reveal，适合仪表盘、设置页和管理台。
    - Level 5-6：加入视差、布局 morph、指针响应，适合产品展示和交互式首页。
    - Level 7+：使用滚动叙事、固定段落或 3D/WebGL 配合，必须单独做移动端和 reduced-motion 降级。
+   - 场景默认值：公共服务、医疗、金融和强可访问性产品从 Level 1-2 起步；SaaS 工具和数据后台从 Level 2-3 起步；营销页、品牌页和作品集可从 Level 4-6 起步；实验性活动页或沉浸式叙事才考虑 Level 7+。
+   - 如果 UI 设计流程已经设定了动效强度拨盘，沿用该拨盘；不要因为引入了某个动效库就自动提高强度。
 
 4. 建立性能边界
    - 只高频动画 `transform`、`opacity`，谨慎使用 `filter` 和 `clip-path`。
    - GSAP、Lottie、Three.js、重型动画组件必须动态导入或隔离在叶子组件。
    - 持续动画需要暂停条件：不可见、标签页隐藏、用户关闭、低电量或 reduced motion。
    - 不在滚动事件中同步读写布局；使用 IntersectionObserver、ScrollTimeline 或节流后的 rAF。
+   - 滚动叙事、stagger、spring、磁吸指针和视差效果必须各自有明确职责；同一屏不要同时堆叠多种高强度运动语言。
+   - 长页面中重复 reveal 动画要控制节奏，避免每个区块都以同一种延迟、方向和 easing 进入，造成模板感和滚动疲劳。
 
 5. 设计可访问降级
    - 所有非必要动效读取 `prefers-reduced-motion`，降级为静态、淡入或即时状态。
@@ -50,12 +54,15 @@ description: Use when designing, implementing, or reviewing frontend interaction
    - 检查首次加载 bundle 是否因动效库显著膨胀。
    - 手动开启 reduced motion，确认动画被禁用或弱化。
    - 用性能面板或实际设备确认滚动和关键交互没有明显掉帧。
+   - 检查动效强度是否匹配页面类型：工作台不应出现营销式滚动剧场，作品集也不应只有默认 hover 淡入。
+   - 对滚动触发序列确认用户可以快速到达内容，不因 pinned 区块、过长时间轴或不可中断过渡丢失上下文。
 
 ## Constraints
 
 - 不在同一个组件内混用 Framer Motion 和 GSAP 控制同一元素。
 - 不用动效掩盖 loading、empty、error、disabled 等状态缺失。
 - 不为普通后台表格、配置页和高频工作台默认加入大幅视差或滚动劫持。
+- 不让所有区块使用相同 reveal 模板；动效节奏应随信息层级和用户任务变化。
 - 不动画 `width`、`height`、`top`、`left`、`margin`、`padding` 等会频繁触发布局的属性。
 - 不把大型 Lottie JSON、GSAP 插件或 3D 场景放入首屏同步包。
 - 不让动画改变阅读顺序、焦点顺序或键盘可达性。

package/skills/fec-nextjs-project-standard/SKILL.md

@@ -18,7 +18,8 @@ description: Use when creating or reviewing Next.js 14+ App Router projects, fil
 3. 明确 SSR / SSG / ISR / CSR 渲染模式和 Next fetch/cache 策略。
 4. 为路由补齐 `loading.tsx`、`error.tsx`、`not-found.tsx`、metadata 和敏感逻辑的服务端边界。
 5. 引入第三方库前检查是否支持 Server Component；浏览器专属、动效、图表、编辑器和 WebGL 库必须放进客户端叶子组件并按需加载。
-6. 客户端组件架构问题分流到 React 项目 workflow。
+6. 对动态渲染、缓存失效、RSC 序列化、route handler、middleware 和首屏 bundle 做证据优先审查；不确定时先收集构建、trace、headers 或路由行为证据。
+7. 客户端组件架构问题分流到 React 项目 workflow。
 
 ## 项目结构
 
@@ -73,6 +74,8 @@ src/
 - 客户端组件：`useEffect` + `useState`，或 SWR / React Query
 - 优先在服务端获取数据，减少客户端水合
 - 使用 `loading.tsx` 和 Suspense 包裹异步区块，提供流式体验
+- 缓存策略要写清 `force-cache`、`no-store`、`revalidate`、tag/path revalidation 或用户私有数据约束
+- 任何会让路由从静态变动态的读取（cookies、headers、searchParams、未缓存 fetch）都要说明原因和验证方式
 
 ## 路由与布局
 
@@ -102,6 +105,8 @@ src/
 - 不把密钥、内部 API 地址或服务端 token 放入 `NEXT_PUBLIC_` 环境变量。
 - 不让大型动效库、3D 场景、富文本编辑器或地图 SDK 进入根布局同步 bundle。
 - 首屏媒体必须有确定尺寸、真实资源和合理 priority；不要用远程占位图撑布局。
+- 不在没有指标、响应头、构建输出或路由行为证据时断言某路由“已缓存”或“必须动态”。
+- Middleware 只处理路由级轻量决策，不承载重型鉴权查询、日志批处理或可放到 route handler 的业务逻辑。
 
 ## 与客户端 UI 模式的分工
 
@@ -115,3 +120,4 @@ src/
 - 渲染模式选择正确（SSR/SSG/ISR/CSR），数据获取路径清晰
 - 元数据和 SEO 配置完整（title、description、openGraph）
 - 敏感逻辑在服务端，客户端组件仅处理交互
+- 缓存、动态渲染和首屏 bundle 决策有可复查证据，性能风险可分流到专项性能 workflow

package/skills/fec-performance-optimization/SKILL.md

@@ -21,6 +21,7 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
    - 对页面体验优先使用 Lighthouse、Performance trace、React Profiler、Vue Devtools、Memory snapshot 或 RUM 数据。
    - 对包体优先看构建产物、source map、依赖重复、首屏 chunk 和动态 import 边界。
    - 对运行时卡顿优先看长任务、重复渲染、昂贵计算、同步循环、布局抖动和大列表。
+   - 如果已有线上监控、平台指标或 CI 产物，先用它们确认受影响路由、设备、时间窗和用户主路径，再决定读哪些源码。
 
 3. 分层定位
    - 加载层：关键 CSS、字体、图片、脚本阻塞、预加载和缓存。
@@ -34,6 +35,7 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
    - 优先处理高频主路径和 P95 体验；低频后台任务不抢占首屏预算。
    - 先做低风险高收益改动，如懒加载、去重、缓存、尺寸预留、虚拟列表、稳定引用和释放资源。
    - 对会牺牲可维护性的技巧，必须说明收益证据和替代方案。
+   - 建议进入实现前先过候选门禁：是否有指标支撑、能否定位到路由/组件/chunk/请求、是否可由前端验证、是否存在更小改动。
 
 5. 验证回归
    - 重新运行受影响构建、测试和性能采集命令。
@@ -66,7 +68,13 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
 - 不为一次 Lighthouse 分数牺牲真实用户主路径。
 - 不引入大型新依赖解决小问题；先利用项目已有工具和浏览器能力。
 - 不把后端、网络和浏览器侧问题混为一谈；前端能验证的部分要单独列证据。
+- 不从 repo-wide grep 直接跳到优化结论；先用指标或复现路径收窄候选，再读相关源码。
+
+## 详细参考
+
+撰写性能分析报告时，加载 [references/report-template.md](references/report-template.md)。
+需要按 React、Vue、Next.js 或 Nuxt 分类定位框架专项性能风险时，加载 [references/framework-performance-patterns.md](references/framework-performance-patterns.md)。
 
 ## Expected Output
 
-输出性能分析报告，包含基线、指标或观察证据、瓶颈位置、优先级、改法、验证命令和剩余风险。报告保存为 `reports/performance-review-YYYY-MM-DD-HHmmss.md`。
+输出有证据链的性能分析报告，说明基线、候选门禁、瓶颈、优化建议、验证方式和剩余风险。报告保存为 `reports/performance-review-YYYY-MM-DD-HHmmss.md`。

package/skills/fec-performance-optimization/references/framework-performance-patterns.md

@@ -0,0 +1,38 @@
+# 框架专项性能诊断模式
+
+本参考用于已经进入性能优化流程后的专项定位。先建立目标、基线和候选门禁，再按框架读取对应分类；不要从这些清单直接跳到结论。
+
+## React / Client React
+
+- **Waterfall**：独立请求、权限检查、feature flag 或子组件数据是否被串行等待。用 Network waterfall、React Profiler 或用户路径日志确认依赖关系。
+- **Bundle**：首屏是否同步引入图表、编辑器、地图、3D、全量图标、重型日期库或 barrel export。用构建产物、source map 或 bundle analyzer 定位 chunk。
+- **Rerender**：Context 是否过宽，selector 是否过粗，默认对象/数组 props 是否每次新建，昂贵派生是否在热路径重复执行。用 React Profiler 或可复现交互证明。
+- **Effect**：是否用 effect 保存可直接推导的数据，是否把交互逻辑放进 effect，是否缺少取消、清理或稳定依赖。用渲染次数、请求次数或内存/订阅证据确认。
+- **Lazy boundary**：Suspense、动态 import、错误 fallback、loading/empty/error 状态是否成对出现，懒加载是否破坏焦点或首屏布局稳定性。
+
+## Vue 3 / Nuxt Client
+
+- **Reactive payload size**：大型对象、表格数据或第三方实例是否被深层响应式代理。用组件更新、内存快照或长任务证据判断是否需要浅响应式或不可变边界。
+- **Computed/watch**：本该 computed 的派生值是否用大范围 watcher 手动同步，watch 是否监听过宽对象，异步 watch 是否缺少取消和竞态处理。
+- **Template hot path**：`v-for` 中是否混用 `v-if`、内联重计算、缺少稳定 `:key`，或在大列表中渲染非视区节点。
+- **Async component boundary**：重型组件是否使用异步组件或路由级动态导入，加载状态是否稳定，错误态是否可恢复。
+- **Store fan-out**：Pinia store 是否把高频 UI 临时状态扩散到大范围订阅者，或把服务端缓存复制到全局 store。
+
+## Next.js
+
+- **Dynamic route drift**：cookies、headers、searchParams 或未缓存 fetch 是否让静态路由变动态。用构建输出、响应头或路由行为确认。
+- **RSC serialization**：Server Component 是否向 Client Component 传递过大 props、重复数据或不可序列化结构。
+- **Fetch/cache policy**：`force-cache`、`no-store`、`revalidate`、tag/path revalidation 是否与数据私有性和更新频率匹配。
+- **Client boundary leakage**：根布局或高层客户端边界是否同步带入重型浏览器库、Provider 或不必要状态。
+- **Middleware cost**：middleware 是否承载重型查询、日志批处理或可放到 route handler 的业务逻辑。
+
+## Nuxt 3
+
+- **Rendering mode mismatch**：页面是否应为 SSR、SSG、ISR/route rules 或 SPA，实际行为是否和部署目标一致。
+- **Data duplication**：`useFetch` / `useAsyncData` 是否重复请求，key 是否稳定，客户端 hydration 是否重复拉取同一数据。
+- **Route middleware cost**：路由中间件是否做重型异步工作、重复鉴权请求或不可缓存的全局阻塞逻辑。
+- **Client-only islands**：只在浏览器运行的图表、编辑器、地图或 WebGL 是否被隔离到 client-only 或异步边界。
+
+## 输出要求
+
+每个框架专项建议都要写清楚：证据来源、受影响路由/组件/chunk/请求、建议改法、验证命令和可能影响的 loading、error、empty、offline、reduced-motion 或移动端状态。