@bovinphang/frontend-craft 2.5.0

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

@@ -0,0 +1,135 @@
+---
+name: fec-code-review
+description: Use when the user asks for general frontend code review, PR review, merge-readiness assessment, architecture maintainability, type-safety, rendering/state risks, style consistency, testability gaps, or a cross-cutting review summary. Delegate deep security, accessibility, E2E, or performance investigations to their specialized skills; Chinese triggers include 代码审查, 代码评审, review.
+---
+
+# 前端代码评审
+
+## Purpose
+
+从架构、类型安全、可访问性、样式一致性、性能和可测试性等 8 个维度审查前端代码质量，输出分级评审报告。
+
+## Review Process
+
+1. 先读项目事实：package scripts、框架、目录约定、最近 diff、现有测试和相关规则。
+2. 按风险找问题，而不是按个人偏好挑风格；每个发现都要能指向具体文件、行号和用户影响。
+3. 用五轴收敛结论：正确性、可维护性、类型/接口、用户体验、验证覆盖。
+4. 对安全、无障碍、E2E、性能等深水区只做初筛；需要专项调查时明确分流。
+5. 多维评审时先按职责拆分，再合并同类发现；同一文件同一根因只保留一条主发现，避免重复噪声。
+6. 报告先列阻塞问题，再列建议项；没有证据的问题不要写成确定结论。
+
+## 多维评审编排
+
+当改动跨越多个质量维度时，按“主评审 + 专项分流”组织，而不是让所有维度重复检查同一处代码。
+
+| 维度                | 触发条件                                             | 分流边界                             |
+| ------------------- | ---------------------------------------------------- | ------------------------------------ |
+| TypeScript 类型安全 | DTO、泛型、公共类型、类型守卫、`any`、断言           | 深入类型建模交给类型安全专项流程     |
+| 状态管理            | 状态归属、全局 store、URL 状态、派生状态、跨页面同步 | 状态选型与迁移交给状态管理专项流程   |
+| 安全                | 用户输入、HTML 渲染、token、上传、第三方脚本         | 漏洞级分析交给安全专项流程           |
+| 无障碍              | 弹窗、菜单、表单、键盘操作、焦点管理                 | WCAG 细查交给无障碍专项流程          |
+| 性能                | 大列表、重依赖、重复请求、长任务、包体积             | 性能证据与预算交给性能专项流程       |
+| E2E                 | 关键用户路径、登录态、支付、跨页面流程               | 浏览器用例与 trace 交给 E2E 专项流程 |
+
+发现合并规则：
+
+- 同一根因出现在多个维度时，只保留最高严重级别，并在 `Dimension` 中列出相关维度。
+- 同一文件多处重复模式，合并为一条模式级发现，列出代表性位置。
+- 置信度不足的问题放入 Open Questions，不升级为阻塞项。
+- 自动化可稳定捕获的格式问题交给 lint/format，不作为人工评审主发现。
+
+## 评审维度
+
+1. 架构
+
+- 组件边界是否清晰
+- 展示逻辑与业务逻辑是否分离
+- 是否有可复用抽象
+- 是否存在上帝组件
+
+2. 类型安全
+
+- 是否存在不必要的 `any`
+- props 类型是否明确
+- hooks/composables 返回值是否稳定
+- 在可行情况下 API 契约是否有类型约束
+
+3. 渲染与状态
+
+- 是否存在不必要的重复渲染
+- key 的使用是否稳定
+- 可推导状态是否被重复存储
+- 本地状态是否耦合过深
+- 全局 store 是否只保存真正跨边界共享的客户端状态
+- URL 状态、服务端状态、表单状态和浏览器持久化是否边界清晰
+
+4. 样式
+
+- 已有 Token 时是否还在使用 magic number
+- 类名是否与仓库约定一致
+- 响应式处理是否明确
+- 是否无必要地混用了多套样式体系
+
+5. 可访问性
+
+- 语义结构是否合理
+- 是否在需要时正确使用 label 和 aria
+- 是否支持键盘操作
+- 浮层和菜单的焦点管理是否正确
+
+6. 可维护性
+
+- 组件/页面文件规模是否合理（宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分，见共享 React / Vue 规则中的「组件文件规模」）
+- 命名质量是否良好
+- 是否有应该提取的重复逻辑
+- 是否存在死代码、过期注释或临时性 hack
+- 业务状态、类型、标识是否用裸数字/裸字符串（应对齐 `templates/shared/rules/fec-typescript.md`「禁止 Magic Number / Magic String」）
+
+7. 测试
+
+- 是否缺少关键测试覆盖
+- 是否存在脆弱的选择器或不稳定的测试模式
+
+8. 安全
+
+- 无明显 XSS 风险（dangerouslySetInnerHTML / v-html 必须审查）
+- 无敏感信息硬编码
+- 无未校验的用户输入直接渲染
+
+9. 性能与体验证据
+
+- 是否引入首屏重依赖、重复请求、大列表渲染或长任务
+- loading、empty、error、disabled、focus 等状态是否完整
+- 响应式布局是否有可验证断点和文本溢出保护
+
+10. 必检项（阻塞合并）
+
+- [ ] TypeScript 类型完整，无 `any`
+- [ ] 外部输入、DTO、公共类型边界无无守卫断言
+- [ ] 无 XSS 风险
+- [ ] 无敏感信息硬编码
+- [ ] 核心逻辑有单元测试
+
+11. 质量项（建议修改）
+
+- [ ] 组件文件规模符合约定（约 300 行内为佳；逾 500 行或高复杂度已拆子组件 / Hooks / Composables / utils）
+- [ ] 无重复代码（DRY 原则）
+- [ ] 无未使用的 import
+
+12. 规范项（风格建议）
+
+- [ ] 命名语义清晰
+- [ ] 注释覆盖复杂逻辑
+
+## Detailed References
+
+撰写代码评审报告时，加载 [references/report-template.md](references/report-template.md)。发现必须具体且可操作；不要写"优化性能"等空泛建议而不指出具体代码模式。
+
+## Expected Output
+
+- 分级评审报告（CRITICAL / HIGH / MEDIUM / LOW）
+- 每个问题关联具体文件和行号，附修复建议
+- 阻塞项（CRITICAL）修复前不建议合并
+- 评审报告保存为 `reports/code-review-YYYY-MM-DD-HHmmss.md`
+- 多维评审要合并重复发现，并说明已分流到哪些专项能力
+- 对不确定项标注需要的验证命令或补充上下文，不把猜测写成事实

package/skills/fec-code-review/references/report-template.md

@@ -0,0 +1,29 @@
+# 代码审查报告模板
+
+```markdown
+# 代码审查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## CRITICAL / 必须修改 (N项)
+- **[文件:行号]** 问题描述 -> 建议修改
+
+## HIGH / 建议优化 (N项)
+- ...
+
+## MEDIUM / 可选优化项 (N项)
+- ...
+
+## LOW / 观察项 (N项)
+- ...
+
+## 做得好的地方
+- ...
+
+## 风险等级：低 / 中 / 高
+
+**总体评价**: 可合并 / 待修改后合并 / 需要重构
+```
+
+评审完成后，将报告保存到 `reports/code-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-component-testing/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: fec-component-testing
+description: Use when authoring or reviewing frontend unit, component, or light integration tests close to UI code, including React Testing Library, Vue Test Utils, hooks/composables, props/emits, callbacks, accessible queries, user-event interactions, mocks, loading/error/empty states, and regression coverage. For layer planning, real-browser journeys, or existing validation failures, choose the matching testing or validation workflow first; Chinese triggers include 组件测试, 组件单测, 单元测试, 轻量集成测试.
+---
+
+# 组件测试
+
+## Purpose
+
+用贴近代码和用户行为的测试验证纯逻辑、组件契约与轻量模块协作，减少重构和 UI 交互回归。
+
+## Procedure
+
+### 1. 先确定测试层级
+
+- 单元测试：纯函数、hooks/composables、utils、状态逻辑、schema。
+- 组件测试：props/emits、回调、用户交互、loading/error/empty、mock 边界。
+- 轻量集成测试：表单 + API mock + Router/Store/Provider 上下文。
+
+跨页面真实浏览器流程分流到 E2E workflow；测试层选择不清楚时先做测试分层规划。
+
+### 2. 优先按用户可感知行为测试
+
+每个测试保持 Arrange / Act / Assert 清晰分段：准备数据和渲染、执行用户动作、断言用户可见结果或公开契约。
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SearchBox } from "./SearchBox";
+
+test("submits the entered keyword", async () => {
+  const user = userEvent.setup();
+  const onSearch = vi.fn();
+
+  render(<SearchBox onSearch={onSearch} />);
+
+  await user.type(screen.getByRole("searchbox", { name: /keyword/i }), "orders");
+  await user.click(screen.getByRole("button", { name: /search/i }));
+
+  expect(onSearch).toHaveBeenCalledWith("orders");
+});
+```
+
+### 3. Vue 组件使用可访问查询或明确文本断言
+
+```ts
+import { mount } from "@vue/test-utils";
+import UserMenu from "./UserMenu.vue";
+
+test("emits logout when the logout item is clicked", async () => {
+  const wrapper = mount(UserMenu, {
+    props: { userName: "Ada" },
+  });
+
+  await wrapper.get('[data-testid="logout-button"]').trigger("click");
+
+  expect(wrapper.emitted("logout")).toHaveLength(1);
+});
+```
+
+优先使用角色、标签和可见文本；仅在没有稳定语义时使用 `data-testid`。
+
+### 4. 控制 mock 边界
+
+```ts
+vi.mock("../api/users", () => ({
+  fetchUsers: vi.fn(async () => [{ id: "1", name: "Ada" }]),
+}));
+```
+
+- mock 网络、时间、路由和浏览器 API。
+- 不 mock 被测组件的内部函数。
+- 对设计系统基础组件只做轻量 mock，保留可访问行为。
+- mock 数据应表达业务场景，不使用只有测试作者能理解的随意字符串。
+- 共享 fixture 应保持可读，复杂对象用 builder 补默认值；每个测试只覆盖与场景相关的字段。
+- mock 网络时优先模拟用户可见结果和错误形状，不复制后端实现细节。
+
+### 5. 覆盖关键状态
+
+每个复杂组件至少覆盖：
+
+- 默认渲染。
+- 用户交互和回调。
+- loading / empty / error。
+- 权限或禁用态。
+- 键盘交互和焦点行为（适用时）。
+
+### 6. 保持测试可维护
+
+```ts
+function setup() {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<ProfileForm onSubmit={onSubmit} />);
+  return { user, onSubmit };
+}
+```
+
+将重复渲染逻辑放入 `setup`，但不要隐藏测试的核心操作和断言。
+
+### 7. 回归测试先证明问题
+
+- Bug 修复先写能复现失败的最小测试。
+- 失败原因应指向用户行为或公开契约，而不是导入错误、测试环境或等待方式。
+- 修复后保留回归测试，避免把验证只留在手工步骤里。
+
+## Constraints
+
+- 避免测试实现细节，例如内部 state 名称、私有函数调用、DOM 层级快照。
+- 不把 snapshot 作为交互组件的主要断言；它只能辅助检查稳定静态输出。
+- 异步断言使用 `findBy*` 或 `waitFor`，不要用固定延迟。
+- 测试名称应描述用户场景，而不是函数名。
+- 组件测试不能替代 E2E；路由、真实浏览器兼容和跨页流程仍需 E2E。
+- 不在测试里复制组件实现逻辑；否则测试会和错误实现一起通过。
+- 不在测试间共享可变 fixture、全局 store 或 fake timer 状态；每个用例独立 setup 和 cleanup。
+
+## Expected Output
+
+产出与组件同目录或项目约定目录下的测试文件，覆盖核心交互、状态和回归场景。验证时运行项目现有 test 命令，确认失败信息能定位到用户行为或组件契约。

package/skills/fec-data-fetching/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: fec-data-fetching
+description: Use when implementing or reviewing TanStack Query/React Query server-state flows: typed queries, query keys, caching, invalidation, mutations, optimistic updates, infinite queries, prefetch, SSR hydration, or API-layer integration. Do not use for local UI state or Service Worker caching; Chinese triggers include 数据获取, 缓存, 乐观更新.
+---
+
+# TanStack Query 数据获取
+
+## Purpose
+
+用声明式 server state 管理替代手写 `useEffect + loading`。
+
+## Procedure
+
+1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用 TanStack Query；纯本地 UI 状态用 `useState`/store。
+2. 建立 `QueryClientProvider`，按业务数据新鲜度设置 `staleTime`、`gcTime`、retry 和窗口聚焦刷新。
+3. 设计稳定 query key：数组结构包含实体、动作和所有影响结果的参数。
+4. API 函数保持纯请求函数，Query hook 负责缓存、select、loading/error/empty 状态。
+5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在 `onError` 回滚。
+
+## Quick Start
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+export function UserList({ keyword }: { keyword: string }) {
+  const query = useQuery({
+    queryKey: ["users", "list", { keyword }],
+    queryFn: () => getUserList({ keyword, page: 1, pageSize: 20 }),
+    select: (response) => response.list,
+  });
+
+  if (query.isLoading) return <Skeleton />;
+  if (query.isError) return <ErrorFallback onRetry={() => query.refetch()} />;
+  if (!query.data?.length) return <EmptyState />;
+
+  return query.data.map((user) => <UserRow key={user.id} user={user} />);
+}
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+  });
+}
+```
+
+## Detailed References
+
+涉及 QueryClient 默认配置、乐观更新、无限滚动查询、预取、SSR 水合和 API 层整合时，加载 [references/query-patterns.md](references/query-patterns.md)。
+
+## Constraints
+
+- 相同数据必须复用相同 query key；参数缺失会造成缓存串读。
+- `staleTime` 过长会显示旧数据，过短会造成频繁请求。
+- TanStack Query 不管理本地 UI 状态；不要把 modal、输入框值放进 query cache。
+- 乐观更新必须保存快照并在 `onError` 回滚。
+- Next.js App Router SSR 需要 `dehydrate` / `HydrationBoundary`。
+
+## Expected Output
+
+数据获取层具备 loading/error/empty/data 状态，重复请求自动去重，mutation 后缓存正确失效或回滚，API 层与 UI 层边界清晰。

package/skills/fec-data-fetching/references/query-patterns.md

@@ -0,0 +1,77 @@
+# TanStack Query 进阶模式
+
+## QueryClient 默认配置
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000,
+      gcTime: 30 * 60 * 1000,
+      retry: 2,
+      refetchOnWindowFocus: true,
+    },
+  },
+});
+```
+
+## Query Key
+
+- 推荐：`["users", "list", { page, status }]`
+- 详情：`["users", "detail", userId]`
+- 所有影响请求结果的参数都必须进入 key。
+
+## 乐观更新
+
+```tsx
+const mutation = useMutation({
+  mutationFn: () => api.likePost(postId),
+  onMutate: async () => {
+    await queryClient.cancelQueries({ queryKey: ["post", postId] });
+    const previousPost = queryClient.getQueryData(["post", postId]);
+    queryClient.setQueryData(["post", postId], (old: Post) => ({
+      ...old,
+      likes: old.likes + 1,
+      liked: true,
+    }));
+    return { previousPost };
+  },
+  onError: (_error, _variables, context) => {
+    queryClient.setQueryData(["post", postId], context?.previousPost);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["post", postId] });
+  },
+});
+```
+
+## Infinite Query
+
+```tsx
+const feed = useInfiniteQuery({
+  queryKey: ["feed"],
+  queryFn: ({ pageParam = 1 }) => api.fetchFeed({ page: pageParam, limit: 20 }),
+  getNextPageParam: (lastPage, pages) => (lastPage.hasMore ? pages.length + 1 : undefined),
+  initialPageParam: 1,
+});
+```
+
+虚拟列表场景将数据分页与 DOM 虚拟化分开设计。
+
+## API 层整合
+
+```ts
+export async function getUserList(params: GetUserListParams): Promise<GetUserListResponse> {
+  return request.get("/api/users", { params });
+}
+
+export function useUsers(params: GetUserListParams) {
+  return useQuery({
+    queryKey: ["users", "list", params],
+    queryFn: () => getUserList(params),
+    select: (response) => response.list,
+  });
+}
+```
+
+API 函数不包含 UI toast、loading 或缓存逻辑。

package/skills/fec-debug-framework/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: fec-debug-framework
+description: Use when diagnosing frontend build failures, runtime errors, UI anomalies, API/data problems, white screens, request failures, or unexplained production exceptions; Chinese triggers include 调试, debug, 排查, 定位, 报错, 异常, 白屏, 请求失败.
+---
+
+# 前端诊断框架
+
+## 核心方法论（5 步法）
+
+所有前端问题诊断遵循统一流程：
+
+### Step 1: 分类（Classify）
+
+识别问题类型和影响范围：
+
+| 类型    | 判断依据                     | 诊断入口       |
+| ------- | ---------------------------- | -------------- |
+| build   | 命令退出非零、stderr 有错误  | → Build 模块   |
+| runtime | 控制台异常、白屏、功能不可用 | → Runtime 模块 |
+| ui      | 视觉偏差、交互不符预期       | → UI 模块      |
+| api     | 请求状态码异常、数据不一致   | → API 模块     |
+
+跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。
+
+### Step 2: 收集（Collect）
+
+按类型收集证据（各模块有具体策略，见下方）。
+
+### Step 3: 假设（Hypothesize）
+
+基于证据提出可能根因，按可能性排序：
+
+- 每个假设必须可测试（有明确的验证方法）
+- 最多保留 3 个假设，避免发散
+- 格式：「因为 X，导致 Y，可通过 Z 验证」
+
+### Step 4: 验证（Verify）
+
+逐一测试假设：
+
+- 从最可能的假设开始
+- 每次只改一个变量
+- 验证结果记录：证实 / 证伪 / 待定
+- 假设全部证伪时回到 Step 2 重新收集
+
+### Step 5: 修复与确认（Fix & Validate）
+
+- 应用最小修复
+- 运行受影响验证命令
+- 确认无回归
+- 输出修复报告
+
+---
+
+## 诊断模块
+
+### Build 模块
+
+**收集**：运行最小失败命令，捕获完整 stderr/stdout
+**假设**：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式
+**验证**：修一类根因 → 重跑命令 → 确认错误减少
+**特殊处理**：
+
+- 依赖版本、peer dependency、ESM/CJS、lockfile 相关失败先作为 build 兼容性问题收集证据
+- 记录 package manager、Node 版本、lockfile diff、相关包版本和完整错误日志
+- 不在缺少证据时升级依赖、手工编辑 lockfile，或把依赖迁移与普通调试修复混在同一批改动
+- 若任务目标本身是版本升级、CVE 修复或 lockfile 风险评审，应转入依赖升级工作流
+- CI 专属失败检查 Node 版本、包管理器、环境变量差异
+
+### Runtime 模块
+
+**收集**：
+
+- 复现路径（用户操作序列）
+- 控制台错误和堆栈
+- 组件渲染树状态（检查关键组件是否正确挂载）
+- 相关 store/state 快照
+
+**假设**：
+
+- 堆栈反向追踪：从异常位置回溯到触发源
+- 状态流分析：检查 state 变化是否符合预期
+- 生命周期分析：是否在错误的时机访问了未初始化的数据
+
+**验证**：
+
+- 添加临时日志确认状态值
+- 在可疑路径添加断言
+- 复现路径验证修复
+
+### UI 模块
+
+**收集**：
+
+- 当前截图 vs 期望效果
+- DOM 结构检查（元素是否存在、层级是否正确）
+- 计算样式检查（实际应用的 CSS 值）
+- 响应式断点测试
+
+**假设**：
+
+- CSS 特异性冲突（选择器权重不够被覆盖）
+- 组件状态不匹配（props/state 未正确传递）
+- 布局模型问题（flex/grid 配置错误）
+- 响应式断点遗漏
+
+**验证**：
+
+- 浏览器 DevTools 实时调整验证
+- 隔离组件测试（排除外部样式干扰）
+- 多断点逐一验证
+
+### API 模块
+
+**收集**：
+
+- 请求 URL、method、headers、body
+- 响应 status、headers、body
+- 网络瀑布时序
+- 相关 store/state 中的缓存数据
+
+**假设**：
+
+- 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
+- 数据转换检查（响应解析、类型映射）
+- 缓存策略检查（过期、失效、竞态）
+- 并发请求竞态（race condition）
+
+**验证**：
+
+- curl 独立复现（排除前端干扰）
+- 逐层 mock 定位问题层级
+- 端到端请求验证修复
+
+---
+
+## 报告格式
+
+保存至 `reports/debug-YYYY-MM-DD-HHmmss.md`：
+
+### 诊断报告
+
+| 项目       | 内容                       |
+| ---------- | -------------------------- |
+| 问题类型   | build / runtime / ui / api |
+| 问题描述   | 用户报告的现象             |
+| 收集的证据 | 关键日志、截图、请求记录   |
+| 假设与验证 | 每个假设的验证结果         |
+| 根因       | 最终确认的根本原因         |
+| 修复内容   | 修改的文件和具体改动       |
+| 验证结果   | 修复后的验证命令和结果     |
+| 剩余风险   | 未覆盖的边界或潜在回归     |
+
+---
+
+## 强约束
+
+- 不在缺少证据时猜测根因
+- 不通过关闭规则、删除测试或降低类型安全来「修复」
+- 每次只改一个变量来验证假设
+- 不在验证前扩大改动范围
+- 同一假设连续 3 次验证失败，停止并报告阻塞

package/skills/fec-dependency-upgrade/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-dependency-upgrade
+description: Use when planning, implementing, or reviewing frontend dependency upgrades, package migrations, lockfile changes, major framework version bumps, CVE remediation, peer dependency conflicts, ESM/CJS shifts, build-tool compatibility, or CI verification matrices; Chinese triggers include 依赖升级, 版本升级, lockfile, peer dependency, CVE 修复, 大版本迁移.
+---
+
+# 依赖升级
+
+适用于前端依赖升级、漏洞修复、大版本迁移和 lockfile 风险评审。需要具体流程和检查清单时加载 [references/dependency-upgrade-workflow.md](references/dependency-upgrade-workflow.md)。
+
+## Purpose
+
+用来源驱动和小批验证的方式升级依赖，降低破坏性变更、供应链风险和 CI 回归。
+
+## Procedure
+
+1. 建立事实基线：读取 package manager、lockfile、Node 版本、workspace 范围、CI 命令和当前验证状态。
+2. 分类升级目标：安全修复、补丁升级、小版本升级、大版本迁移、框架迁移、构建工具迁移或依赖清理。
+3. 查证来源：对版本敏感的库读取官方 release notes、migration guide、peer dependency、Node/browser 支持和弃用项。
+4. 拆小批次：安全补丁可集中处理；大版本、构建工具、框架和测试工具必须单独批次验证。
+5. 处理兼容边界：检查 ESM/CJS、TypeScript 类型、CSS 处理、SSR/RSC、插件 API、peer dependency 和 polyfill 变化。
+6. 运行验证矩阵：至少覆盖 install、typecheck、unit/component tests、build；关键应用补 E2E、Storybook 或手工冒烟。
+7. 同步文档：记录升级原因、版本、破坏性变更、迁移命令、回滚方式和仍需人工验证的路径。
+
+## Constraints
+
+- 不在缺少来源和验证的情况下进行大版本连跳。
+- 不为了消除 audit 警告盲目升级运行时关键包；先判断可利用路径和修复影响。
+- 不手工编辑 lockfile 规避依赖冲突。
+- 不把依赖升级和无关重构混在一个批次。
+- 不移除 peer dependency 或构建插件，除非有证据证明没有被运行时、子包或 CI 使用。
+
+## Expected Output
+
+输出升级清单、风险分类、来源依据、批次策略、修改范围、验证命令、失败处理和回滚建议。完成后 lockfile 与 package 清单一致，关键验证通过，破坏性变更有记录。

package/skills/fec-dependency-upgrade/references/dependency-upgrade-workflow.md

@@ -0,0 +1,56 @@
+# 依赖升级工作流
+
+## 升级类型
+
+| 类型 | 示例 | 验证 |
+| ---- | ---- | ---- |
+| 安全补丁 | 传递依赖 CVE、patch 版本 | 安装、audit、目标测试 |
+| 小版本升级 | 兼容性功能版本 | typecheck、测试、构建 |
+| 大版本迁移 | React/Vue/Next/Vite/Storybook 大版本 | 迁移指南、完整验证矩阵 |
+| 工具链切换 | ESLint、TypeScript、bundler、test runner | 配置 diff、CI 对齐、样例失败 |
+| 清理 | 移除未使用包 | 引用搜索、构建、测试 |
+
+## 来源检查清单
+
+- 官方 release notes 或 migration guide。
+- 包管理器兼容性和 lockfile 格式。
+- Node 版本和浏览器支持范围。
+- Peer dependency 版本范围。
+- ESM/CJS 导出变化。
+- TypeScript 最低版本和类型变化。
+- SSR、RSC、edge runtime 或 browser-only 约束。
+
+## 分批策略
+
+- 框架大版本升级与样式、测试、lint 升级分开处理。
+- 当 peer 版本范围要求时，adapter 与宿主工具放在同一批升级。
+- Monorepo 中要验证受影响包，并至少验证一个消费这些包的应用。
+- 每个成功批次都记录通过的命令，必要时单独提交或单独报告。
+
+## 失败分诊
+
+1. 复现最小失败命令。
+2. 判断失败属于配置、类型表面、运行时行为还是 peer dependency。
+3. 优先采用官方迁移步骤，而不是本地临时 hack。
+4. 如果某个包阻塞当前批次，先 pin 住并记录原因；只有剩余批次仍然自洽时才继续。
+
+## 报告模板
+
+```markdown
+## 依赖升级摘要
+
+| 包 | 从 | 到 | 原因 | 风险 | 依据 |
+| -- | -- | -- | ---- | ---- | ---- |
+
+## 验证
+
+- install:
+- typecheck:
+- test:
+- build:
+- e2e/storybook/manual:
+
+## 剩余风险
+
+- ...
+```