@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/localized/zh-CN/skills/fec-implement-from-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: fec-implement-from-design
+description: 用于根据 Figma、Sketch、MasterGo、Pixso、墨刀、摹客、截图、设计选区、设计 Token 或设计转代码任务实现生产级前端组件/页面；中文触发词包括 设计稿、按设计实现。
+---
+
+# 按设计稿实现
+
+## 用途
+
+基于设计工具（Figma、Sketch、MasterGo、Pixso、墨刀、摹客）的设计上下文，高保真实现页面或组件，强调组件复用、设计 Token 映射、可访问性和面向生产的前端实现。
+
+## 支持的设计工具
+
+| 工具     | MCP 集成                  | 获取设计数据方式                          |
+| -------- | ------------------------- | ----------------------------------------- |
+| Figma    | `figma` / `figma-desktop` | API 获取设计结构、变量定义                |
+| Sketch   | `sketch`                  | MCP 获取设计选区截图                      |
+| MasterGo | `mastergo`                | API 获取 DSL 结构数据                     |
+| Pixso    | `pixso`                   | 本地 MCP 获取帧数据和代码                 |
+| 墨刀     | `modao`                   | MCP 获取原型数据、生成设计描述            |
+| 摹客     | 无 MCP                    | 通过用户提供的截图、标注或导出的 CSS 获取 |
+
+## 目标
+
+- 尽量高还原地实现设计稿
+- 在创建新组件前优先复用现有项目组件
+- 尽可能把设计变量映射到现有 Token
+- 保持实现结果可维护、类型明确、可测试且具备可访问性
+- 避免引入重复的基础组件或并行设计系统
+
+## 流程
+
+### 1. 识别设计来源
+
+按优先级选择设计数据获取方式：
+
+- `figma` — Figma API 集成
+- `figma-desktop` — Figma 桌面端集成
+- `mastergo` — MasterGo DSL 数据
+- `pixso` — Pixso 本地 MCP
+- `modao` — 墨刀原型数据
+- `sketch` — Sketch 选区截图
+- 如以上 MCP 均不可用，请求用户提供设计截图或标注（适用于摹客等无 MCP 工具）
+- 如果没有权威设计稿，但任务明确要求视觉型网站、品牌页、作品集或高审美重设计，可把用户提供或本地生成的分区级参考图作为临时视觉事实来源；这种来源必须先分析后实现，并在计划中标明不是权威设计系统。
+
+### 2. 读取设计上下文
+
+通过 MCP 或用户提供的设计数据读取设计上下文：
+
+- 检查布局结构
+- 检查间距、字体、颜色、变量、状态、图标和组件层级
+- 如果 MCP 提供了资源文件或 SVG / 图片源，直接使用
+- 如果 MCP 已提供真实资源，不要自行造占位资源
+- 如果用户提供截图而非 MCP 数据，从截图中推断布局、颜色、字体等视觉信息
+- 如果使用图像/截图参考，先提取区块结构、视觉层级、主色和功能色、字体气质、间距节奏、媒体位置、交互状态暗示和响应式风险，再写代码。
+- 对多区块页面优先使用清晰的分区级参考图或局部细节图；不要从压缩长图里猜测按钮、字号、间距和组件状态。
+- 视觉参考中的不可读文字、假截图、不可检查素材或冲突状态不能直接照搬；需要转译成项目真实内容、真实状态或明确占位说明。
+
+### 3. 搜索可复用组件
+
+在创建新组件前先搜索代码库中的可复用组件，重点检查：
+
+- 按钮（Button）
+- 输入框 / 选择器 / 复选框 / 单选框 / 开关（Input / Select / Checkbox / Radio / Switch）
+- 模态框 / 抽屉 / 对话框（Modal / Drawer / Dialog）
+- 表格 / 列表 / 卡片（Table / List / Card）
+- 标签页 / 面包屑 / 分页（Tabs / Breadcrumb / Pagination）
+- 页面容器 / 区块容器 / 空状态 / Loading 状态
+
+### 4. 产出实现计划
+
+在改文件前先产出一份简短实现计划，计划必须包含：
+
+- 需要改动的文件列表
+- 组件拆分方案
+- 状态 / 数据流
+- 响应式行为
+- 复用还是新建的决策
+- 设计缺口或歧义点
+- 图像/截图来源的可靠性，以及哪些视觉细节会被项目 token、组件约定或可访问性要求覆盖
+
+### 5. 按框架实现
+
+按仓库当前使用的前端框架进行实现：
+
+- 严格遵循仓库现有约定
+- 优先使用明确类型的 props 和 interfaces/types
+- 保持组件小而可组合
+- 将重复逻辑提取为 hooks / composables / utilities
+
+### 6. 设计 Token 映射
+
+- 优先使用现有 design token、CSS 变量、主题变量或工具类
+- 除非确实没有对应 Token，否则不要硬编码颜色、圆角和间距
+- 如果设计使用了新 Token，要明确指出，不要悄悄到处硬编码
+
+### 7. 可访问性保障
+
+- 优先使用语义化 HTML
+- 确保交互控件具有可访问名称
+- 保留可见的焦点样式
+- 检查对话框、菜单、标签页、表单控件的键盘可操作性
+
+### 8. 编码后验证
+
+- 如有 lint，执行 lint
+- 如有测试，执行测试
+- 如果缺少测试，说明建议补充的最小测试范围
+
+## 详细参考
+
+撰写实现计划报告时，加载 [references/design-plan-template.md](references/design-plan-template.md)。
+
+## 约束
+
+- 如果已有设计上下文（MCP 或截图），不要靠猜来实现 UI
+- 如果项目已有 UI 体系，不要再引入一套新的 UI Kit
+- 除非有合理理由，不要用硬编码替代已 Token 化的样式
+- 不要忽略 hover、active、disabled、loading、empty、error 等状态
+- 摹客等无 MCP 工具场景下，主动向用户索要关键截图和标注信息，不要凭空编造视觉数据
+- 不把生成图像当作可直接复制的代码规范；它只提供视觉证据，最终实现必须服从当前项目组件、token、可访问性和性能边界
+- 不用一张不可读整页图替代分区分析；关键区块、CTA、表单、导航和状态必须可检查
+
+## 预期输出
+
+- 设计实现计划报告保存为 `reports/design-plan-YYYY-MM-DD-HHmmss.md`，包含实现概要、组件拆分方案、状态/数据流、变更文件清单
+- 代码实现高保真还原设计稿，组件复用率最大化
+- 设计变量映射到现有 Token，无硬编码颜色/间距/圆角
+- 交互元素具备可访问名称和键盘支持，焦点样式可见

package/localized/zh-CN/skills/fec-implement-from-design/references/design-plan-template.md

@@ -0,0 +1,36 @@
+# 设计实现计划模板
+
+```markdown
+# 设计实现计划
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+> 设计工具: Figma / Sketch / MasterGo / Pixso / 墨刀 / 摹客
+
+## 实现概要
+- 设计稿来源: ...
+- 目标页面/组件: ...
+
+## 复用的组件
+- ...
+
+## 新建的组件
+- ...
+
+## 组件拆分方案
+- ...
+
+## 状态/数据流
+- ...
+
+## 与设计稿的偏差
+- ...
+
+## 缺失的资源 / Token / 交互细节
+- ...
+
+## 变更文件清单
+- ...
+```
+
+实现计划确定后，将报告保存到 `reports/design-plan-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

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

@@ -0,0 +1,46 @@
+---
+name: fec-legacy-to-modern-migration
+description: 用于规划或实施从 JavaScript、jQuery、HTML/CSS、服务端渲染模板、MPA 遗留前端代码或旧框架代码迁移到现代前端技术栈，同时保持行为一致。不要用于仍留在旧技术栈内的日常遗留 bug 修复；中文触发词包括 遗留项目、技术栈升级、jQuery 迁移。
+---
+
+# 传统前端到现代框架迁移
+
+适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）、服务端模板渲染项目或旧框架代码，渐进迁移到 React、Vue、Next.js、Nuxt、TypeScript，或保留 MPA 形态但现代化模块、构建、类型和测试的场景。
+
+## 用途
+
+指导传统前端项目渐进迁移到目标现代栈，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。
+
+## 流程
+
+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、资源和样式边界。
+
+## 约束
+
+- 迁移前必须先输出迁移分析报告，明确策略、优先级和风险。
+- 不要在一次迁移中同时改架构、改 UI、改接口。
+- 优先保证功能等价，再考虑优化和现代化。
+- 迁移过程中保持旧系统可运行，避免大爆炸式上线。
+- 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换。
+- 目标栈先识别 React/Vue/Next/Nuxt、现代 MPA 或局部现代化目标，不默认强制改成 SPA。
+- 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范；内联 SVG 例外需有可访问性、组件化或维护理由。
+- 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系；内联样式例外需局部、可解释。
+- 目标是视觉与交互一致、代码更简洁易维护，业务功能不得缺失。
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须建立重构前后的行为清单，并使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
+- 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。
+
+## 预期输出
+
+- 迁移分析报告保存为 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案。
+- 迁移后的业务功能与原项目完全等价，无功能缺失。
+- 视觉与交互与原项目一致，用户无感知差异。
+- 类型定义完整，无 `any` 滥用，API 调用统一且类型安全。
+- 图片使用原项目资源，样式进入目标项目样式体系，图标和内联样式例外有明确理由。
+- 新代码文案已 i18n，关键路径有测试覆盖。

package/localized/zh-CN/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/localized/zh-CN/skills/fec-legacy-to-modern-migration/references/migration-report-template.md

@@ -0,0 +1,41 @@
+# 迁移分析报告模板
+
+```markdown
+# 迁移分析报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## 策略选择
+- 渐进式 / 一次性重写:
+- 理由:
+
+## 存量盘点
+- 页面数量:
+- 功能模块:
+- jQuery 插件:
+- 服务端模板:
+- API 调用方式:
+
+## 依赖关系
+- 共享 JS/CSS:
+- 跨页面逻辑:
+- 后端接口契约:
+
+## 迁移优先级
+- 第一批:
+- 第二批:
+- 暂缓:
+
+## 分阶段步骤
+- 阶段 0:
+- 阶段 1:
+- 阶段 2:
+- 阶段 3:
+
+## 风险与回滚
+- 风险:
+- 回滚方案:
+```
+
+迁移分析或计划完成后，将报告保存到 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/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/localized/zh-CN/skills/fec-legacy-web-standard/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: fec-legacy-web-standard
+description: 用于维护或安全修改既有非框架前端代码：原生 JavaScript、jQuery、HTML/CSS、MPA 页面、服务端渲染模板、遗留插件或需要长期保持当前技术栈的代码。若是规划迁移到 React/Vue/TypeScript，请使用迁移 skill；中文触发词包括 传统前端、原生 JS、jQuery。
+---
+
+# 传统前端项目规范（JS + jQuery + HTML）
+
+## 用途
+
+在不重写技术栈的前提下安全维护 vanilla JS、jQuery、HTML/CSS 和服务端模板项目。
+
+## 流程
+
+1. 先确认本次改动是维护旧栈还是迁移；迁移到 React/Vue/TypeScript 时切换到现代化迁移 workflow。
+2. 沿用现有架构和代码风格，优先修复问题，不在一次改动中引入多项现代化。
+3. JavaScript 用 IIFE/命名空间减少全局污染，事件绑定优先委托到合理容器。
+4. DOM 更新缓存选择器、批量操作、转义用户输入；Ajax 必须处理 loading、error、空状态和防重复提交。
+5. HTML/CSS 保持语义、label、alt、BEM/既有命名和低选择器深度。
+6. 安全重点检查 `.html()`、`innerHTML`、URL 参数渲染、CSRF token 和文件上传。
+
+## 详细参考
+
+涉及 jQuery 命名空间、事件绑定、Ajax、XSS 转义、文件组织和维护清单示例时，加载 [references/legacy-patterns.md](references/legacy-patterns.md)。
+
+## 约束
+
+- 在现有架构内改进，不要引入与项目格格不入的现代框架。
+- 渐进增强优于推倒重来。
+- 禁止用 `innerHTML` / `.html()` 直接插入用户输入。
+- 避免全局变量污染。
+- 每次聚焦一个维护点，避免顺手重构整个模块。
+
+## 预期输出
+
+改动与旧项目风格一致，无全局变量泄漏，事件和 DOM 操作可维护，Ajax 状态完整，用户输入已转义，渐进改进不破坏现有功能。

package/localized/zh-CN/skills/fec-legacy-web-standard/references/legacy-patterns.md

@@ -0,0 +1,85 @@
+# 传统前端维护模式
+
+## 命名空间
+
+```javascript
+var App = App || {};
+App.UserModule = (function ($) {
+  "use strict";
+
+  function init() {
+    bindEvents();
+    loadData();
+  }
+
+  function bindEvents() {
+    $(document).on("click", ".js-submit-btn", handleSubmit);
+  }
+
+  return { init: init };
+})(jQuery);
+```
+
+## 事件与 DOM
+
+- 事件触发元素用 `.js-*` class，与样式 class 分离。
+- 缓存频繁使用的选择器。
+- 批量 DOM 操作用 `DocumentFragment` 或一次性插入。
+- 页面卸载或模块销毁时解绑事件或调用插件 destroy。
+
+## Ajax
+
+```javascript
+function fetchUserList(params) {
+  return $.ajax({
+    url: "/api/v1/users",
+    method: "GET",
+    data: params,
+    dataType: "json",
+  })
+    .done(function (res) {
+      if (res.code === 0) renderList(res.data);
+      else showError(res.message);
+    })
+    .fail(function () {
+      showError("网络错误，请稍后重试");
+    })
+    .always(function () {
+      hideLoading();
+    });
+}
+```
+
+## XSS 转义
+
+```javascript
+$(".username").text(userData.name);
+
+function escapeHtml(str) {
+  var div = document.createElement("div");
+  div.appendChild(document.createTextNode(str));
+  return div.innerHTML;
+}
+```
+
+## 文件组织
+
+```text
+project/
+├── css/
+│   ├── common.css
+│   └── pages/user-list.css
+├── js/
+│   ├── lib/jquery.min.js
+│   ├── common/utils.js
+│   └── pages/user-list.js
+└── pages/
+```
+
+## 检查清单
+
+- 没有全局变量泄漏。
+- 事件绑定在合理容器上。
+- Ajax 处理 loading/error/empty。
+- 用户输入已转义。
+- 未扩大第三方库或框架依赖。

package/localized/zh-CN/skills/fec-list-virtualization/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-list-virtualization
+description: 用于优化或审查大列表、虚拟滚动、windowing、react-window、TanStack Virtual、可变高度行、动态测量、无限滚动、网格虚拟化或滚动性能；中文触发词包括 虚拟列表、大列表优化、滚动性能。
+---
+
+# 列表虚拟化优化
+
+## 用途
+
+通过窗口化只渲染可视区域，解决大列表 DOM 过多和滚动卡顿。
+
+## 流程
+
+1. 先确认列表规模和瓶颈：500+ 项、滚动掉帧、DOM 节点过多或内存飙升才引入虚拟化。
+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 限制。
+
+## 详细参考
+
+涉及是否需要虚拟化、库选型、固定高度、可变/动态高度、无限滚动、网格虚拟化和性能注意事项时，加载 [references/virtualization-patterns.md](references/virtualization-patterns.md)。
+
+## 约束
+
+- SEO 关键内容不要只存在于虚拟项中。
+- 浏览器原生 Ctrl+F 无法搜索未挂载项目。
+- Row 根元素必须透传虚拟库提供的 style/measure ref。
+- overscan 过大会浪费内存，过小会白屏。
+- 动态高度测量要处理 ResizeObserver 和布局抖动。
+
+## 预期输出
+
+10000+ 项列表滚动接近 60fps，DOM 节点数稳定在可视区域及缓冲区范围，内存从 O(n) 降至 O(visible)。

package/localized/zh-CN/skills/fec-list-virtualization/references/virtualization-patterns.md

@@ -0,0 +1,80 @@
+# 虚拟列表模式
+
+## 先判断是否需要虚拟化
+
+- 只有列表规模、渲染成本或滚动性能已经形成瓶颈时才引入虚拟化；小列表、轻量静态列表和分页后可控的列表不需要。
+- 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";
+
+const Row = ({ index, style, data }: { index: number; style: React.CSSProperties; data: User[] }) => (
+  <div style={style}>{data[index].name}</div>
+);
+
+export const UserList = ({ users }: { users: User[] }) => (
+  <List height={500} itemCount={users.length} itemSize={48} width="100%" itemData={users}>
+    {Row}
+  </List>
+);
+```
+
+## React 可变高度示例
+
+```tsx
+import { VariableSizeList as List } from "react-window";
+
+const getItemSize = (index: number) => (items[index].hasSummary ? 120 : 60);
+
+<List height={600} itemCount={items.length} itemSize={getItemSize} width="100%">
+  {CardRow}
+</List>;
+```
+
+## TanStack Virtual 动态高度示例
+
+```tsx
+const virtualizer = useVirtualizer({
+  count: messages.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 60,
+  overscan: 5,
+});
+```
+
+动态内容需要测量元素并处理 ResizeObserver；Vue/Solid/Svelte 项目使用 TanStack Virtual 对应框架 adapter，核心选项保持一致。
+
+## 无限滚动
+
+- `count` 包含 loader 占位项。
+- 最后一个虚拟项进入视口时调用 `fetchNextPage()`。
+- 不要在 render 中无条件触发请求，使用 effect 或明确状态保护。
+
+## 网格虚拟化
+
+二维网格使用 `FixedSizeGrid` 或 TanStack Virtual 的 row/column 双轴方案，确保单元格 style 透传。