@bovinphang/frontend-craft 2.5.0 → 2.6.0

package/skills/fec-form-handling/references/advanced-form-patterns.md

@@ -1,6 +1,35 @@
 # 高级表单模式
 
-## Controller
+## 先判断是否需要表单库
+
+- 1-3 个字段、无复杂校验、无动态字段、无组件库适配压力的表单，可用框架原生状态、浏览器约束校验和轻量提交状态。
+- 需要动态字段、跨字段校验、多步流程、文件上传、异步校验、服务端错误回填或明显输入卡顿时，再引入专门表单方案。
+- 表单库只管理字段状态和校验流程，不替代 API 错误映射、权限判断、可访问性标注或服务端最终校验。
+
+## 选型参考
+
+先沿用项目已有表单库、schema 库和组件库适配方式；新增依赖时再按场景选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React 复杂表单 | React Hook Form + Zod | 非受控优先，第三方受控组件用 `Controller`。 |
+| Vue 复杂表单 | vee-validate / FormKit + Zod、Yup 或 Valibot | 不要为 Vue 项目引入 React-only 表单 API；优先沿用项目既有 Vue 表单库。 |
+| 简单表单 | 框架原生状态 + 基础校验 | 避免为了 1-3 个字段引入重型表单体系。 |
+| 多步表单 | 分步 schema + 最终提交 schema | 明确跨步数据保存、返回上一步和最终校验策略。 |
+| 文件上传 | 表单库字段状态 + `FormData` | 校验文件数量、大小、类型；不要把 `File` JSON 序列化。 |
+| 异步校验 | 提交边界校验或 debounce 字段校验 | 避免每次键入请求；处理竞态和旧响应覆盖。 |
+
+## 通用实现原则
+
+- 运行时 schema 或校验函数负责外部输入边界；TypeScript 类型不能替代运行时校验。
+- 默认值、reset 数据和服务端回填数据要形状一致，避免字段在受控/非受控之间切换。
+- 字段错误要能映射到具体字段；全局错误用于提交失败、权限或服务不可用等非字段问题。
+- 组件库适配层要透传 value、onChange、onBlur、name/ref 或等价字段注册能力。
+- 提交时保护 loading、重复提交、取消/过期请求、服务端错误回填和成功后 reset。
+- 文件上传使用 `FormData` 或直传流程，前端校验只做体验保护，服务端仍需最终校验。
+- 性能优化优先使用字段级订阅、局部组件拆分和延迟校验，不要全表单 watch 后驱动整页重渲染。
+
+## React Hook Form Controller
 
 ```tsx
 <Controller
@@ -18,7 +47,7 @@
 
 用于不暴露原生 `ref` 的 Select、DatePicker、RichEditor 等组件。
 
-## 动态字段
+## React Hook Form 动态字段
 
 ```tsx
 const { fields, append, remove } = useFieldArray({
@@ -36,7 +65,7 @@ const { fields, append, remove } = useFieldArray({
 
 `key` 必须使用 `field.id`，不要使用数组 index。
 
-## 联动校验
+## Zod 联动校验
 
 ```ts
 const schema = z
@@ -50,7 +79,7 @@ const schema = z
   });
 ```
 
-## 文件上传
+## Zod 文件上传校验
 
 ```ts
 const schema = z.object({
@@ -67,6 +96,6 @@ const schema = z.object({
 ## 性能
 
 - 用 `useWatch` 或字段级订阅替代全表单 watch。
-- 大表单拆成 memoized 子组件。
+- 大表单拆成 memoized 子组件或框架等价的局部更新单元。
 - 高频输入不要每次键入触发网络校验。
 - 多步表单要明确每步 schema 和跨步最终 schema。

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

@@ -28,7 +28,7 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - 保持实现结果可维护、类型明确、可测试且具备可访问性
 - 避免引入重复的基础组件或并行设计系统
 
-## 必需工作流
+## Procedure
 
 ### 1. 识别设计来源
 
@@ -102,7 +102,7 @@ description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao
 - 如有测试，执行测试
 - 如果缺少测试，说明建议补充的最小测试范围
 
-## Detailed References
+## 详细参考
 
 撰写实现计划报告时，加载 [references/design-plan-template.md](references/design-plan-template.md)。
 

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

@@ -1,15 +1,23 @@
 ---
 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
+
+1. 先识别目标栈、迁移边界和是否保留 MPA/服务端模板形态。
+2. 选择渐进式或一次性重写策略，并输出迁移分析报告。
+3. 做存量盘点、依赖关系分析和迁移优先级排序。
+4. 按准备、基础层、模块/页面迁移、收尾的顺序推进，每次迁移一个可验证单元。
+5. 每个迁移单元按检查清单验证功能等价、视觉一致、类型安全、可访问性、i18n、资源和样式边界。
 
 ## 迁移策略选择
 
@@ -28,8 +36,8 @@ description: Use when planning or implementing an intentional migration from Jav
 | ------------------------------------------ | -------------------------------------- |
 | `$(selector).html(content)`                | 声明式 JSX + state 驱动渲染            |
 | `$(document).on('click', '.btn', handler)` | `onClick` + 事件委托由 React 处理      |
-| `$.ajax()` / `$.get()`                     | `fetch` / `axios` + React Query 或 SWR |
-| 全局变量 / 命名空间存储状态                | `useState` / `useContext` / Zustand    |
+| `$.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                       |
@@ -41,7 +49,7 @@ description: Use when planning or implementing an intentional migration from Jav
 | ------------------------------------------ | -------------------------------------------------- |
 | `$(selector).html(content)`                | 模板 + `ref` / `reactive` 驱动渲染                 |
 | `$(document).on('click', '.btn', handler)` | `@click` + 事件修饰符                              |
-| `$.ajax()` / `$.get()`                     | `fetch` / `axios` + VueUse `useFetch` 或 Vue Query |
+| `$.ajax()` / `$.get()`                     | 项目请求层、`fetch` / `axios`，可按需接 VueUse、Nuxt `useFetch` 或 TanStack Query Vue adapter |
 | 全局变量 / 命名空间存储状态                | `ref` / `reactive` / Pinia                         |
 | `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
 | 手动 DOM 操作                              | 数据驱动，通过响应式更新视图                       |
@@ -52,10 +60,10 @@ description: Use when planning or implementing an intentional migration from Jav
 
 | 遗留概念                          | 现代对应                                   |
 | --------------------------------- | ------------------------------------------ |
-| 页面级 JS 入口（每页一个 script） | 路由 + 懒加载页面组件                      |
+| 页面级 JS 入口（每页一个 script） | 路由/页面入口 + 懒加载模块，或保留 MPA 入口并现代化打包 |
 | 公共 JS 模块（utils、ajax 封装）  | `services/`、`utils/`、类型化 API 层       |
-| 内联样式 / 页面级 CSS             | CSS Modules / Tailwind / styled-components |
-| 服务端模板变量                    | 通过 API 获取 + 前端状态管理               |
+| 内联样式 / 页面级 CSS             | 目标项目样式体系，如 CSS Modules、Tailwind、全局样式分层或组件库样式 |
+| 服务端模板变量                    | 通过 API 获取、SSR/loader 注入，或保留服务端模板边界并类型化数据 |
 | 表单提交 + 整页刷新               | 表单库 + 客户端校验 + API 调用             |
 
 ## 迁移前分析
@@ -66,7 +74,8 @@ description: Use when planning or implementing an intentional migration from Jav
    - 页面数量、功能模块数量
    - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
    - 现有 API 调用方式、是否有统一封装
-   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需改为纯前端渲染
+   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需要保留、局部替换或改为纯前端渲染
+   - 目标栈是 React/Vue/Next/Nuxt、现代 MPA，还是只做局部 TypeScript/构建/测试现代化
 
 2. **依赖关系**
    - 页面间共享的 JS/CSS 模块
@@ -82,7 +91,7 @@ description: Use when planning or implementing an intentional migration from Jav
 
 ### 阶段 0：准备
 
-- 搭建新项目脚手架（Vite + React/Vue + TypeScript）
+- 搭建或识别目标项目骨架：React/Vue/Next/Nuxt、现代 MPA，或现有项目内的渐进式 TypeScript/构建入口
 - 配置 ESLint、Prettier、测试框架
 - 建立 `services/request.ts` 统一请求层，与现有 API 兼容
 - 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型
@@ -92,7 +101,7 @@ description: Use when planning or implementing an intentional migration from Jav
 - 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
 - 迁移工具函数（日期、格式化、校验等）
 - 迁移常量、枚举、类型定义
-- 建立路由骨架，占位未迁移页面（重定向或 iframe 嵌入旧页面）
+- 建立目标导航/页面入口骨架；未迁移页面可继续走旧路由、重定向、iframe 或微前端嵌入
 
 ### 阶段 2：按模块/页面迁移
 
@@ -103,7 +112,7 @@ description: Use when planning or implementing an intentional migration from Jav
 
 ### 阶段 3：收尾
 
-- 移除旧代码入口，全面切换至 SPA
+- 按迁移策略移除或冻结旧代码入口；若保留 MPA，则收敛旧入口并完成现代化边界
 - 配置 404、错误边界、全局错误处理
 - 性能优化（懒加载、代码分割、缓存策略）
 - 文档更新、部署流程调整
@@ -115,8 +124,8 @@ description: Use when planning or implementing an intentional migration from Jav
 ### 图片与图标
 
 - 直接使用原项目的图片资源路径，不重新托管或替换
-- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`），**禁止使用内联 SVG**（`<svg>...</svg>` 直接写在组件中）
-- **若原项目使用了 iconfont 或 IcoMoon 图标，重构时继续使用**，保持图标体系一致；不替换为其他图标方案（如独立 SVG、其他图标库）
+- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`）；图标组件或可访问交互确需内联 SVG 时，应遵循目标项目图标规范并说明理由。
+- 若原项目使用了 iconfont 或 IcoMoon 图标，重构时优先继续使用，保持图标体系一致；替换为其他图标方案前需评估视觉一致性、包体和维护成本。
 - 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
 
 ### 国际化（i18n）
@@ -130,7 +139,7 @@ description: Use when planning or implementing an intentional migration from Jav
 - 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
 - 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
 - 避免不合理写法：如 `!important` 滥用、过深选择器、重复定义
-- **组件中禁止使用内联样式**（`style={{ ... }}` / `style="..."`），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护
+- 组件中优先避免内联样式（`style={{ ... }}` / `style="..."`）；确需使用运行时动态值、第三方组件 API 或 CSS 变量桥接时，应保持局部、可解释，并优先放入目标项目样式体系。
 
 ### 目标
 
@@ -149,9 +158,9 @@ description: Use when planning or implementing an intentional migration from Jav
 - [ ] 可访问性：表单有 label、交互可键盘操作
 - [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
 - [ ] 关键路径有测试覆盖
-- [ ] 符合目标框架的项目规范（参考目标 React / Vue 项目约定）
-- [ ] 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
-- [ ] 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
+- [ ] 符合目标栈的项目规范（React / Vue / Next / Nuxt / MPA 现代化等）
+- [ ] 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范，例外已说明
+- [ ] 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系，内联样式例外已说明
 - [ ] 视觉与交互与原项目一致，代码更简洁易维护
 - [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）
 
@@ -162,11 +171,12 @@ description: Use when planning or implementing an intentional migration from Jav
 - 优先保证功能等价，再考虑优化和现代化
 - 迁移过程中保持旧系统可运行，避免大爆炸式上线
 - 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换
-- **图片与图标**：使用原项目图片资源，可用 SVG 文件，禁止内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
-- **样式**：参考原项目效果不照搬 CSS，优先 flex 布局，组件禁止内联样式
+- **目标栈**：先识别 React/Vue/Next/Nuxt、现代 MPA 或局部现代化目标，不默认强制改成 SPA。
+- **图片与图标**：使用原项目图片资源，图标体系优先沿用原项目或目标项目规范；内联 SVG 例外需有可访问性、组件化或维护理由。
+- **样式**：参考原项目效果不照搬 CSS，优先使用目标项目样式体系；内联样式例外需局部、可解释。
 - **目标**：视觉与交互一致、代码更简洁易维护，业务功能不得缺失
 
-## Detailed References
+## 详细参考
 
 撰写迁移分析或迁移计划报告时，加载 [references/migration-report-template.md](references/migration-report-template.md)。
 
@@ -176,5 +186,5 @@ description: Use when planning or implementing an intentional migration from Jav
 - 迁移后的业务功能与原项目完全等价，无功能缺失
 - 视觉与交互与原项目一致，用户无感知差异
 - 类型定义完整，无 `any` 滥用，API 调用统一且类型安全
-- 图片使用原项目资源，样式使用 flex 布局，无内联样式
+- 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由
 - 新代码文案已 i18n，关键路径有测试覆盖

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-performance-optimization/SKILL.md

@@ -67,6 +67,10 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
 - 不引入大型新依赖解决小问题；先利用项目已有工具和浏览器能力。
 - 不把后端、网络和浏览器侧问题混为一谈；前端能验证的部分要单独列证据。
 
+## 详细参考
+
+撰写性能分析报告时，加载 [references/report-template.md](references/report-template.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/report-template.md

@@ -0,0 +1,53 @@
+# 性能分析报告模板
+
+```markdown
+# 前端性能分析报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 目标页面/流程: ...
+> 环境: 设备、浏览器、网络、分支或版本
+
+## 性能目标
+
+- 关注指标: LCP / CLS / INP / TBT / bundle size / memory / FPS
+- 项目预算或目标阈值
+- 用户主路径和 P95 场景
+
+## 基线数据
+
+| 指标 | 当前值 | 采集方式 | 备注 |
+| --- | --- | --- | --- |
+| LCP | ... | Lighthouse / RUM / trace | ... |
+
+## 瓶颈定位
+
+- 加载层、渲染层、数据层、主线程或资源层问题
+- 关联文件、路由、chunk、组件或请求
+- 支持该判断的 trace、bundle、日志或截图证据
+
+## 优先级
+
+| 优先级 | 问题 | 用户影响 | 风险 |
+| --- | --- | --- | --- |
+| P0 / P1 / P2 | ... | ... | ... |
+
+## 优化方案
+
+- 具体改法
+- 替代方案
+- 可维护性、可访问性和产品行为影响
+
+## 验证对比
+
+| 指标 | 优化前 | 优化后 | 采集方式 |
+| --- | --- | --- | --- |
+| ... | ... | ... | ... |
+
+## 剩余风险
+
+- 未覆盖设备、网络或浏览器
+- 需要后端、设计、产品或基础设施协作的部分
+- 建议监控或后续任务
+```
+
+分析完成后，将报告保存到 `reports/performance-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-pwa-implementation/SKILL.md

@@ -17,10 +17,10 @@ description: Use when adding or reviewing Progressive Web App capabilities such
 4. 用 Workbox 或框架插件管理 precache/runtime cache；登录、支付、权限变更等敏感请求必须走网络。
 5. 提供 offline fallback 页面和安装提示 UI，并验证首次加载、离线访问、更新激活、卸载重装。
 
-## Detailed References
+## 详细参考
 
-- Load [references/manifest-and-icons.md](references/manifest-and-icons.md) for manifest fields, HTML links, icon requirements, screenshots, and iOS notes.
-- Load [references/service-worker-workbox.md](references/service-worker-workbox.md) for Service Worker registration, Workbox strategies, Vite integration, offline fallback, and update flow.
+- 需要 manifest 字段、HTML 引用、图标要求、截图和 iOS 注意事项时，加载 [references/manifest-and-icons.md](references/manifest-and-icons.md)。
+- 需要 Service Worker 注册、Workbox 策略、Vite 集成、离线兜底和更新流程时，加载 [references/service-worker-workbox.md](references/service-worker-workbox.md)。
 
 ## Constraints
 
@@ -33,4 +33,3 @@ description: Use when adding or reviewing Progressive Web App capabilities such
 ## Expected Output
 
 产出可安装的 Web 应用、离线 fallback、可见更新提示和明确缓存策略。验证 Lighthouse PWA、DevTools Application 面板、离线模式、更新发布和移动端安装流程。
-

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

@@ -50,7 +50,7 @@ description: Use when designing or reviewing React + TypeScript project structur
    - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致
    - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill
 
-## Detailed References
+## 详细参考
 
 需要具体 React 项目结构、组件模式、Hooks、路由、状态归属、API 层形状、错误处理、样式默认值、TypeScript 约定或审查清单时，加载 [references/react-project-details.md](references/react-project-details.md)。
 

package/skills/fec-refactor-clean/SKILL.md

@@ -41,8 +41,11 @@ description: Use when safely removing dead frontend code, unused exports, stale
 - 不用“看起来没人用”作为证据；必须有搜索、工具输出、类型错误消失或测试保护。
 - 不把依赖大版本升级伪装成清理；升级风险、release notes 和 lockfile 变更应分流到依赖升级工作流。
 
+## 详细参考
+
+撰写清理报告时，加载 [references/report-template.md](references/report-template.md)。
+
 ## Expected Output
 
 - 清理报告保存为 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`。
-- 报告包含候选项、风险分类、已清理项、跳过原因、运行命令和剩余风险。
 - 代码清理后相关验证命令通过，或明确说明阻塞原因。

package/skills/fec-refactor-clean/references/report-template.md

@@ -0,0 +1,42 @@
+# 重构清理报告模板
+
+```markdown
+# 重构清理报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 清理范围: 文件 / 模块 / 依赖 / 路由 / 样式
+
+## 基线验证
+
+| 命令 | 清理前状态 | 清理后状态 | 备注 |
+| --- | --- | --- | --- |
+| `npm run lint` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+
+## 候选项与证据
+
+| 候选项 | 证据 | 风险分类 |
+| --- | --- | --- |
+| `path/to/file.ts` | 工具输出 / rg 搜索 / 类型检查 | SAFE / CAUTION / DANGER / UPGRADE |
+
+## 已清理项
+
+- 删除或修改的文件、导出、样式、依赖或配置
+- 每项清理对应的证据
+
+## 跳过原因
+
+- CAUTION / DANGER 项为什么没有自动处理
+- 需要人工确认、运行时验证或专项流程的内容
+
+## 验证命令
+
+- 执行的 lint、type-check、test、build 或手工验证
+- 关键输出摘要
+
+## 剩余风险
+
+- 动态引用、运行时模板、插件元数据或外部入口风险
+- 建议后续清理或依赖升级项
+```
+
+清理完成后，将报告保存到 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-security-review/SKILL.md

@@ -18,10 +18,10 @@ description: Use when reviewing frontend security risks such as XSS, CSRF, sensi
 5. 高危问题标记为阻塞合并；前端校验只能改善体验，不能作为唯一安全边界。
 6. 输出分级安全报告；报告格式见 [references/report-template.md](references/report-template.md)。
 
-## Detailed References
+## 详细参考
 
-- Load [references/security-checklist.md](references/security-checklist.md) for XSS, CSP, sensitive data, CSRF, dependency, and input validation details.
-- Load [references/report-template.md](references/report-template.md) when writing the security review report.
+- 需要 XSS、CSP、敏感数据、CSRF、依赖和输入校验细节时，加载 [references/security-checklist.md](references/security-checklist.md)。
+- 撰写安全审查报告时，加载 [references/report-template.md](references/report-template.md)。
 
 ## Constraints
 

package/skills/fec-state-management/SKILL.md

@@ -123,7 +123,7 @@ const migrationPlan: StateMigrationItem[] = [
 ];
 ```
 
-## Detailed References
+## 详细参考
 
 需要 Store 形状示例、选择器模式、URL 状态同步、持久化适配器、SSR 边界或审查清单时，加载 [references/state-patterns.md](references/state-patterns.md)。
 

package/skills/fec-storybook-component-doc/SKILL.md

@@ -18,9 +18,9 @@ description: Use when setting up or reviewing Storybook component documentation,
 5. 需要自动化时接入 interaction tests、addon-a11y、Chromatic 或 Storybook Test Runner；这些能力服务于组件文档和设计系统展示，不承接跨页业务旅程。
 6. 设计系统组件应记录 token 来源、Tailwind/class 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。
 
-## Detailed References
+## 详细参考
 
-- Load [references/story-patterns.md](references/story-patterns.md) for `main.ts`, `preview.ts`, stories, decorators, MDX, interaction tests, and visual regression examples.
+- 需要 `main.ts`、`preview.ts`、stories、decorators、MDX、交互测试和视觉回归示例时，加载 [references/story-patterns.md](references/story-patterns.md)。
 
 ## Constraints
 

package/skills/fec-typescript-type-safety/SKILL.md

@@ -140,7 +140,7 @@ type UserStatus = UserViewModel["status"];
 type _UserStatusTest = Expect<Equal<UserStatus, "active" | "disabled">>;
 ```
 
-## Detailed References
+## 详细参考
 
 涉及高级泛型约束、映射类型、模板字面量类型、类型测试、DTO 映射或类型审查清单时，加载 [references/type-safety-patterns.md](references/type-safety-patterns.md)。
 

package/skills/fec-validation-fix/SKILL.md

@@ -31,7 +31,7 @@ description: Use when running existing project validation commands and fixing fa
 - 对 CI 专属失败记录 Node 版本、包管理器、环境变量、路径大小写和工作目录差异。
 - 修复测试时优先修产品代码或测试等待方式，不用删除断言掩盖真实回归。
 
-## 强约束
+## Constraints
 
 - 不要盲目关闭规则来消除报错
 - 除非有明确理由，不要为了通过检查而降低类型安全
@@ -40,9 +40,12 @@ description: Use when running existing project validation commands and fixing fa
 - 不要删除失败测试来让验证通过
 - 不要只运行失败命令的片段就声称整体验证通过
 
+## 详细参考
+
+撰写验证修复报告时，加载 [references/report-template.md](references/report-template.md)。
+
 ## Expected Output
 
 - lint / type-check / test / build 等验证命令全部通过
 - 失败项已修复或给出明确原因和后续行动
 - 修复报告保存为 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`
-- 报告包含命令状态表、问题根因、修复说明、变更文件和剩余风险

package/skills/fec-validation-fix/references/report-template.md

@@ -0,0 +1,43 @@
+# 验证修复报告模板
+
+```markdown
+# 验证修复报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 验证范围: lint / type-check / test / build / CI
+
+## 命令状态表
+
+| 命令 | 初始状态 | 修复后状态 | 备注 |
+| --- | --- | --- | --- |
+| `npm run type-check` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+
+## 失败摘要
+
+- 最早出现且会级联的错误
+- 受影响文件、错误类型和关键日志
+- 是否属于 CI 专属、测试环境、依赖版本或 flaky 问题
+
+## 根因
+
+- 确认的根本原因
+- 支持该结论的输出、日志或复现证据
+
+## 修复内容
+
+- 修改的文件和行为
+- 为什么没有通过关闭规则、删除断言或降低类型安全来规避失败
+
+## 验证结果
+
+- 重新执行的命令
+- 命令输出摘要
+- 是否仍有失败项
+
+## 剩余风险
+
+- 未覆盖的验证命令
+- 仍需用户决策或外部环境确认的问题
+```
+
+验证修复完成后，将报告保存到 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

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

@@ -21,7 +21,7 @@ description: Use when designing or reviewing Vue 3 + TypeScript project structur
 6. Tailwind token/variant 或响应式布局需求应分流到对应专项 skill，避免把样式系统规则塞进 Vue 组件规范。
 5. 状态归属复杂时先做状态清单；DTO、公共 props 或泛型 composable 复杂时先收敛 TypeScript 类型契约。
 
-## Detailed References
+## 详细参考
 
 需要具体 Vue 3 项目结构、组件模式、Composables、slots、Provide/Inject、路由、Pinia、API 层、错误处理、指令、样式、TypeScript、测试、性能或审查清单时，加载 [references/vue3-project-details.md](references/vue3-project-details.md)。
 

package/skills/fec-web-workers/SKILL.md

@@ -17,10 +17,10 @@ description: Use when moving expensive browser work off the main thread with Web
 4. 传大对象时优先 Transferable Objects；不要让结构化克隆吞掉 Worker 带来的收益。
 5. 在组件或页面卸载时 `terminate()`，并通过 Profiler、Performance 面板或 FPS 指标验证主线程改善。
 
-## Detailed References
+## 详细参考
 
-- Load [references/basic-worker.md](references/basic-worker.md) for plain Worker files, bundler imports, React lifecycle wrapping, and cleanup.
-- Load [references/advanced-workers.md](references/advanced-workers.md) for Transferable Objects, Comlink, Worker pools, SharedWorker, CSP, and SharedArrayBuffer notes.
+- 需要原生 Worker 文件、构建工具导入、React 生命周期封装和清理示例时，加载 [references/basic-worker.md](references/basic-worker.md)。
+- 需要 Transferable Objects、Comlink、Worker pool、SharedWorker、CSP 和 SharedArrayBuffer 注意事项时，加载 [references/advanced-workers.md](references/advanced-workers.md)。
 
 ## Constraints
 
@@ -33,4 +33,3 @@ description: Use when moving expensive browser work off the main thread with Web
 ## Expected Output
 
 计算密集型操作在后台线程执行，主线程输入和滚动恢复流畅，错误与取消路径明确，Worker 在卸载时被终止且无内存泄漏。
-