@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/localized/zh-CN/skills/fec-route-protection/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: fec-route-protection
+description: 用于实现或审查前端路由保护、auth guard、RBAC、权限路由、登录态处理、重定向、middleware、React Router、Next.js、Vue Router 或 Nuxt route middleware；中文触发词包括 路由保护、权限路由、登录态。
+---
+
+# 路由保护
+
+## 用途
+
+为前端应用建立清晰的认证、授权和重定向边界，避免越权访问与闪烁渲染。
+
+## 适用场景
+
+- 页面需要登录后访问，或不同角色看到不同路由。
+- 需要实现 React Router、Next.js、Nuxt 或 Vue Router 的路由守卫。
+- 登录过期、权限不足、组织/租户切换需要统一处理。
+- 不用于替代服务端授权；前端路由保护只能改善体验，不能作为唯一安全边界。
+
+## 流程
+
+### 1. 定义认证与授权状态
+
+```ts
+export type AuthStatus = "loading" | "anonymous" | "authenticated";
+
+export interface CurrentUser {
+  id: string;
+  roles: string[];
+  permissions: string[];
+}
+
+export function canAccess(user: CurrentUser, required: string[]) {
+  return required.every((permission) => user.permissions.includes(permission));
+}
+```
+
+### 2. React Router 使用布局守卫
+
+```tsx
+import { Navigate, Outlet, useLocation } from "react-router-dom";
+
+interface ProtectedRouteProps {
+  requiredPermissions?: string[];
+}
+
+export function ProtectedRoute({ requiredPermissions = [] }: ProtectedRouteProps) {
+  const location = useLocation();
+  const { status, user } = useAuth();
+
+  if (status === "loading") return <RouteLoading />;
+  if (status === "anonymous") {
+    return <Navigate to="/login" replace state={{ from: location }} />;
+  }
+  if (requiredPermissions.length > 0 && !canAccess(user, requiredPermissions)) {
+    return <Navigate to="/403" replace />;
+  }
+
+  return <Outlet />;
+}
+```
+
+```tsx
+const router = createBrowserRouter([
+  {
+    element: <ProtectedRoute requiredPermissions={["orders:read"]} />,
+    children: [{ path: "/orders", element: <OrdersPage /> }],
+  },
+]);
+```
+
+### 3. Next.js 优先在服务端边界处理
+
+```ts
+// middleware.ts
+import { NextResponse, type NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get("session")?.value;
+  const isPrivateRoute = request.nextUrl.pathname.startsWith("/dashboard");
+
+  if (isPrivateRoute && !token) {
+    const loginUrl = new URL("/login", request.url);
+    loginUrl.searchParams.set("redirect", request.nextUrl.pathname);
+    return NextResponse.redirect(loginUrl);
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*"],
+};
+```
+
+对需要精细权限的 App Router 页面，在 server component 或 server action 中重新校验权限，不依赖客户端状态。
+
+### 4. Vue Router / Nuxt 使用导航守卫
+
+```ts
+router.beforeEach(async (to) => {
+  const auth = useAuthStore();
+  if (auth.status === "unknown") await auth.fetchCurrentUser();
+
+  if (to.meta.requiresAuth && !auth.user) {
+    return { path: "/login", query: { redirect: to.fullPath } };
+  }
+
+  const required = to.meta.permissions as string[] | undefined;
+  if (required?.length && !auth.canAccess(required)) {
+    return { path: "/403" };
+  }
+});
+```
+
+### 5. 统一失败与跳转体验
+
+- `401`：清理过期会话，跳转登录页并保留 `redirect`。
+- `403`：进入无权限页，不反复重试。
+- `loading`：渲染稳定骨架屏，避免先显示私有内容再跳转。
+- 登录成功：只跳转到同源且允许的路径，防止 open redirect。
+- RBAC：权限矩阵来自可信会话或后端返回；前端只用于路由体验和 UI 裁剪，不能替代接口授权。
+- 会话刷新：401 刷新失败后统一清理状态；避免多个并发请求各自触发跳转或刷新风暴。
+
+## 约束
+
+- 前端路由保护不是安全边界；API、SSR loader、server action 必须重复做授权校验。
+- 不要在组件渲染后用 `useEffect` 才跳转私有页面，否则会出现敏感内容闪烁。
+- redirect 参数必须限制为站内路径，不能直接信任 URL 输入。
+- 权限信息应来自可信会话或后端响应，不要只依赖 localStorage 中的角色字段。
+- 多租户应用必须把 tenant/org 上下文纳入权限判断。
+- 不把菜单隐藏视为授权完成；用户直接访问 URL、刷新页面、篡改 localStorage 和替换 tenant 都必须验证。
+
+## 预期输出
+
+产出一套路由守卫实现，覆盖 loading、未登录、权限不足、登录后回跳和会话过期。验证时直接访问私有 URL、刷新页面、切换角色、篡改 redirect 参数，确认行为稳定且 API 仍有服务端授权。

package/localized/zh-CN/skills/fec-security-review/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fec-security-review
+description: 用于审查前端安全风险，如 XSS、CSRF、敏感数据暴露、不安全 DOM API、不可信用户输入、认证/token 处理、支付流程、文件上传、CSP、依赖风险或第三方脚本；中文触发词包括 安全审查、安全检查。
+---
+
+# 前端安全审查
+
+## 用途
+
+识别前端代码中的客户端安全风险，并给出可执行修复建议。
+
+## 流程
+
+1. 先确认审查面：用户输入、动态 HTML、URL 跳转、认证态、RBAC、文件上传、支付/删除等敏感操作、第三方脚本和依赖。
+2. 搜索高危模式：`dangerouslySetInnerHTML`、`v-html`、`innerHTML`、`document.write`、动态 script、未校验 redirect、明文 token。
+3. 按风险类型审查：XSS、CSP、敏感数据、CSRF、依赖、输入校验、文件上传、开放重定向、认证授权和第三方脚本。
+4. 用边界模型判断责任：客户端只能改善体验和减少误用，鉴权、授权、上传信任和敏感操作必须由服务端最终裁决。
+5. 高危问题标记为阻塞合并；前端校验只能改善体验，不能作为唯一安全边界。
+6. 输出分级安全报告；报告格式见 [references/report-template.md](references/report-template.md)。
+
+## 详细参考
+
+- 需要 XSS、CSP、敏感数据、CSRF、依赖和输入校验细节时，加载 [references/security-checklist.md](references/security-checklist.md)。
+- 撰写安全审查报告时，加载 [references/report-template.md](references/report-template.md)。
+
+## 约束
+
+- 不要为了方便开发而绕过安全机制。
+- 不要依赖前端校验作为唯一安全防线。
+- 不要信任任何来自客户端的数据。
+- 发现高危问题时必须标记为阻塞合并。
+- 与通用代码质量 review 分工：本 skill 关注威胁、攻击面和数据泄露。
+- 不把依赖审计结果机械等同为可利用漏洞；需要结合运行路径、暴露面和修复成本判断。
+- 不把隐藏按钮、前端路由守卫或本地角色字段当作授权边界；API、SSR loader、server action 和敏感操作必须有服务端裁决。
+
+## 预期输出
+
+输出 CRITICAL/HIGH/MEDIUM/LOW 分级安全审查报告，每个问题关联具体文件和行号，给出修复建议；报告保存为 `reports/security-review-YYYY-MM-DD-HHmmss.md`。

package/localized/zh-CN/skills/fec-security-review/references/report-template.md

@@ -0,0 +1,27 @@
+# 安全审查报告模板
+
+```markdown
+# 安全审查报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## CRITICAL / 高危 (N项)
+- **[文件:行号]** 风险描述 -> 修复建议
+
+## HIGH / 中高危 (N项)
+- ...
+
+## MEDIUM / 中危 (N项)
+- ...
+
+## LOW / 低危或建议 (N项)
+- ...
+
+## 已通过的安全检查
+- ...
+
+**整体安全等级**: 安全 / 存在风险 / 高危需修复
+```
+
+审查完成后，将报告保存到 `reports/security-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/skills/fec-security-review/references/security-checklist.md

@@ -0,0 +1,64 @@
+# 前端安全审查清单
+
+## XSS
+
+- `dangerouslySetInnerHTML` 和 `v-html` 必须有明确理由和输入净化。
+- 用户输入不得直接插入 DOM、`innerHTML`、`document.write`。
+- URL 参数不得直接用于页面渲染。
+- 动态生成的 `<script>` 标签必须审查来源。
+- 富文本使用 DOMPurify 等库，并配置标签、属性、协议白名单。
+
+```ts
+import DOMPurify from "dompurify";
+
+const clean = DOMPurify.sanitize(dirtyHtml, {
+  ALLOWED_TAGS: ["b", "i", "em", "strong", "a", "ul", "ol", "li", "p", "br"],
+  ALLOWED_ATTR: ["href", "title"],
+  ALLOWED_URI_REGEXP: /^(https?|mailto):/i,
+});
+```
+
+## 安全重定向
+
+```ts
+function safeRedirect(url: string): string {
+  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  return "/dashboard";
+}
+```
+
+## CSP
+
+- 推荐先用 `Content-Security-Policy-Report-Only` 验证。
+- `default-src 'self'`、`object-src 'none'`、`frame-ancestors 'none'`、`base-uri 'self'` 是常见底线。
+- 避免 `'unsafe-eval'`；内联脚本优先 nonce。
+
+```http
+Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';
+```
+
+## 敏感数据
+
+- 禁止前端硬编码 API Key、Secret、密码。
+- 禁止 localStorage/sessionStorage/IndexedDB 存明文 token、密码、信用卡信息。
+- 禁止 URL query 参数传 token 或密码。
+- 禁止 console.log 或错误上报携带隐私数据。
+- Token 优先 httpOnly + Secure + SameSite cookie。
+
+## CSRF
+
+- 变更操作必须携带 CSRF token 或使用同等后端防护。
+- 关键操作不要使用 GET。
+- 检查后端是否校验 `Origin` / `Referer`。
+
+## 依赖与第三方脚本
+
+- 定期审查依赖安全公告。
+- 禁止从非官方 CDN 加载脚本，除非有 SRI 和来源审查。
+- 动态加载第三方脚本必须有业务必要性和降级策略。
+
+## 输入校验与文件上传
+
+- 前端校验不是安全边界，后端必须二次校验。
+- 文件上传校验 MIME、大小、扩展名和内容；不能只看扩展名。
+- 正则校验注意 ReDoS 风险。

package/localized/zh-CN/skills/fec-source-driven-development/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: fec-source-driven-development
+description: 用于前端决策依赖可能变化的框架、库、浏览器、运行时、包、API 或平台行为时，包括官方文档核验、版本敏感模式、迁移选择或公共接口假设；中文触发词包括 查官方文档、以源码为准、source-driven、版本差异。
+---
+
+# 来源驱动开发
+
+## 用途
+
+在前端实现、评审和架构决策中优先依据项目内事实、官方文档和当前版本行为，避免沿用过时经验或未经验证的假设。
+
+## 流程
+
+1. 判断是否需要查源
+   - 涉及框架新版本、路由、渲染模式、缓存、构建工具、浏览器 API、包发布格式、鉴权协议或公共接口时必须查源。
+   - 涉及项目约定时先读本仓库 README、配置、模板、已有实现、测试和迁移记录。
+   - 只是稳定语言语法或明显局部重构时，可使用项目现有模式作为事实来源。
+
+2. 收集权威材料
+   - 首选官方文档、规范、源码、release notes、migration guide、类型定义和项目内测试。
+   - 第三方文章只能作为线索，不能作为最终依据。
+   - 对快速变化的库记录包名、版本、文档日期或页面标题。
+   - 当用户要求从本地知识库、项目资料库或 `knowledge/` 目录回答问题时，先走本地知识检索，不使用网络搜索补事实。
+
+3. 提炼决策
+   - 写清当前版本推荐做法、弃用做法、限制条件和迁移注意事项。
+   - 对多个可行方案说明选择理由、兼容性、维护成本和回退方式。
+   - 若文档和项目现状冲突，优先解释冲突并给出渐进调整，不直接推翻已运行系统。
+   - 对依赖升级、框架迁移和公共 API 变化，记录 release notes、migration guide、版本范围、破坏性变更和回滚方案。
+
+4. 落到实现
+   - 将外部行为隔离在适配层、配置层或小型工具函数中，避免在组件里散落版本假设。
+   - 公共接口变化要保持命名、错误形状、默认值和兼容策略清晰。
+   - 代码注释只记录非显而易见的来源约束，不粘贴大段文档。
+
+5. 验证假设
+   - 用类型检查、最小复现、单元测试、组件测试、E2E、构建或浏览器验证证明关键假设。
+   - 如果无法验证，报告不确定性、风险范围和需要用户或团队确认的信息。
+6. 留下轻量决策记录
+   - 当结论会影响公共接口、依赖版本、目录规范或团队工作流时，补充 ADR/变更记录或交给文档同步流程。
+
+## 本地知识检索
+
+当用户指定本地知识库路径，或默认 `knowledge/` 目录存在时，可用本流程回答资料库问题、抽取证据或辅助决策。
+
+1. 定位根目录
+   - 用户明确指定路径时使用该路径。
+   - 否则检查当前项目下 `knowledge/` 是否存在；不存在时说明未找到默认知识库并请求路径。
+   - 不用文件 glob 判断目录是否存在。
+
+2. 分层导航
+   - 优先读取根目录和子目录中的 `data_structure.md`。
+   - 根据目录说明选择最相关的少量分支，不一次性遍历整个知识库。
+   - 记录候选文件、主题、时间/版本范围和为什么相关。
+
+3. 渐进检索
+   - Markdown、文本、日志：先用关键词搜索，再局部读取命中上下文。
+   - PDF：处理前先确认可用工具和提取路线，优先提取到临时文本后再检索，避免把整份 PDF 打进上下文。
+   - Excel：处理前先确认读取/分析路线，先看工作表、列名和少量样例，再按字段过滤或聚合。
+   - 默认最多 5 轮关键词迭代；每轮根据已找到证据调整同义词、缩写和范围。
+
+4. 回答与溯源
+   - 先给结论，再列文件路径、章节、页码、工作表或行号附近作为依据。
+   - 证据不足时说明查过哪些路径、缺什么信息，以及用户如何缩小范围。
+   - 不把知识库外的网络信息混入答案，除非用户另行要求查外部来源。
+
+## 事实源优先级
+
+| 优先级 | 来源 | 用途 |
+| ------ | ---- | ---- |
+| 1 | 项目内配置、测试、已有实现 | 判断本仓库真实约定 |
+| 2 | 官方文档、源码、类型定义 | 判断当前推荐行为 |
+| 3 | 标准规范、浏览器兼容数据 | 判断平台能力和兼容边界 |
+| 4 | Issue、讨论、第三方文章 | 辅助排查，不能单独定案 |
+
+## 约束
+
+- 不凭记忆给版本敏感结论。
+- 不把过时教程当作当前最佳实践。
+- 不引用无法复核的来源作为关键依据。
+- 不为追新而改动稳定项目约定；必须说明收益和迁移成本。
+- 不在交付中复制长篇外部文档；只保留必要结论和链接或文件路径。
+- 不把“查过文档”停留在口头；版本敏感决策需要能追溯到具体版本、路径或官方页面。
+
+## 预期输出
+
+输出来源清单、版本或项目事实、决策结论、实现影响、验证命令和未决风险。若修改代码，关键行为应有测试或构建验证支撑。

package/localized/zh-CN/skills/fec-state-management/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: fec-state-management
+description: 用于选择、实现、审查或重构 React、Vue、Next.js、Nuxt、URL 状态、服务端状态、表单状态、浏览器持久化或全局 store 的前端状态归属。TanStack Query 缓存细节、浏览器存储持久化或表单校验内部问题优先使用更窄的 skill；中文触发词包括 状态管理、状态归属、store 选型。
+---
+
+# 前端状态管理
+
+## 用途
+
+为前端状态确定清晰归属，避免全局 store 膨胀、重复缓存和派生状态同步错误。
+
+## 流程
+
+### 1. 先分类状态来源
+
+不要先选 Redux、Zustand、Pinia 或 Context。先把每个状态标到唯一归属，再决定工具。
+
+| 状态类型         | 典型例子                             | 默认归属                 |
+| ---------------- | ------------------------------------ | ------------------------ |
+| 本地 UI 状态     | 弹窗开关、tab、展开行、hover 编辑态  | 组件内 state / ref       |
+| 表单状态         | 输入值、脏字段、校验错误、提交中     | 表单库或表单组件         |
+| 服务端状态       | 列表、详情、分页结果、远程错误       | 请求缓存库               |
+| URL 状态         | 搜索词、筛选、排序、页码、选中 tab   | 路由参数 / search params |
+| 全局客户端状态   | 登录用户、主题、权限快照、购物车草稿 | 全局 store               |
+| 浏览器持久化状态 | 跨刷新保留的草稿、偏好、离线队列     | 存储层 + 状态适配器      |
+
+```tsx
+type ReportsStateMap = {
+  search: "url";
+  selectedReportId: "url";
+  reports: "server-state-cache";
+  isFilterPanelOpen: "local-ui";
+  draftColumns: "browser-persistence";
+};
+```
+
+### 2. 保持最小状态
+
+可从 props、server state、URL 或已有 state 推导出来的值，不要另存一份。
+
+```tsx
+interface Invoice {
+  id: string;
+  status: "draft" | "sent" | "paid";
+}
+
+function InvoiceList({ invoices }: { invoices: Invoice[] }) {
+  const paidInvoices = invoices.filter((invoice) => invoice.status === "paid");
+
+  return <span>{paidInvoices.length}</span>;
+}
+```
+
+### 3. 选择 React 全局状态方案
+
+React 中优先本地化和组合；只有跨页面、跨 feature 或需要统一动作时才引入全局 store。
+
+```tsx
+import { create } from "zustand";
+
+interface WorkspaceState {
+  activeWorkspaceId: string | null;
+  setActiveWorkspaceId: (workspaceId: string) => void;
+}
+
+export const useWorkspaceStore = create<WorkspaceState>((set) => ({
+  activeWorkspaceId: null,
+  setActiveWorkspaceId: (activeWorkspaceId) => set({ activeWorkspaceId }),
+}));
+```
+
+决策顺序：
+
+1. 只在一个组件或一个小子树使用：`useState` / `useReducer`。
+2. 低频全局配置或依赖注入：Context。
+3. 中等复杂业务状态：Zustand 或 Jotai，按仓库现有选型优先。
+4. 大型应用、严格动作流、审计或时间旅行调试：Redux Toolkit。
+5. 远程数据：使用数据获取 skill 管理 query key、缓存和失效策略。
+
+### 4. 选择 Vue 全局状态方案
+
+Vue 3 中，局部跨层级传递使用 `provide/inject`；全局业务状态使用 Pinia 或项目既有 store。
+
+```ts
+import { computed, readonly, ref } from "vue";
+import { defineStore } from "pinia";
+
+export const useSessionStore = defineStore("session", () => {
+  const userId = ref<string | null>(null);
+  const isSignedIn = computed(() => userId.value !== null);
+
+  function signIn(nextUserId: string) {
+    userId.value = nextUserId;
+  }
+
+  return {
+    userId: readonly(userId),
+    isSignedIn,
+    signIn,
+  };
+});
+```
+
+### 5. 明确状态边界和迁移步骤
+
+重构状态时先做状态清单，再逐步移动读写入口。每一步都应保持行为可验证。
+
+```ts
+interface StateMigrationItem {
+  name: string;
+  currentOwner: "component" | "context" | "store" | "query-cache" | "url";
+  targetOwner: "component" | "context" | "store" | "query-cache" | "url";
+  verification: string;
+}
+
+const migrationPlan: StateMigrationItem[] = [
+  {
+    name: "dashboard filters",
+    currentOwner: "store",
+    targetOwner: "url",
+    verification: "refreshing the page preserves filters through search params",
+  },
+];
+```
+
+## 详细参考
+
+需要 Store 形状示例、选择器模式、URL 状态同步、持久化适配器、SSR 边界或审查清单时，加载 [references/state-patterns.md](references/state-patterns.md)。
+
+## 约束
+
+- 不把服务端响应复制到全局 store；缓存、失效和重试归数据获取层。
+- 不把表单每个字段提升到全局 store；跨步骤共享也优先由表单上下文或提交草稿适配器处理。
+- 不用 Context 承载高频变化的大对象；会扩大重渲染范围。
+- 持久化状态必须明确字段白名单、版本号、过期策略和敏感数据排除。
+- SSR 场景不要在模块顶层创建带用户数据的单例 store。
+
+## 预期输出
+
+产出状态归属清单、选型理由、store/API 边界和验证步骤。实现时应保留 loading/error/empty、刷新、回退、跨路由和权限变化等关键行为。

package/localized/zh-CN/skills/fec-state-management/references/state-patterns.md

@@ -0,0 +1,109 @@
+# 状态管理模式
+
+## 所有权审查清单
+
+- 每个状态字段有唯一归属：本地状态、表单状态、服务端缓存、URL 状态、全局 Store 或浏览器持久化。
+- 派生值由源状态计算得出，而不是通过 effect 或 watcher 手动同步。
+- URL 状态用于可分享、刷新后需保留的视图状态，如筛选、搜索、排序和分页。
+- 服务端数据保留在请求缓存中；全局 Store 仅存放选中的 ID、本地偏好或乐观更新提示。
+- 持久化的客户端状态需有白名单、schema 版本号、迁移路径和敏感字段排除规则。
+- Store 的 action 以领域事件命名，而非组件处理器命名。
+
+## React Store 形状示例
+
+```tsx
+import { create } from "zustand";
+import { subscribeWithSelector } from "zustand/middleware";
+
+interface CartLine {
+  sku: string;
+  quantity: number;
+}
+
+interface CartState {
+  lines: CartLine[];
+  addLine: (line: CartLine) => void;
+  removeLine: (sku: string) => void;
+}
+
+export const useCartStore = create<CartState>()(
+  subscribeWithSelector((set) => ({
+    lines: [],
+    addLine: (line) =>
+      set((state) => ({
+        lines: [...state.lines.filter((item) => item.sku !== line.sku), line],
+      })),
+    removeLine: (sku) =>
+      set((state) => ({
+        lines: state.lines.filter((line) => line.sku !== sku),
+      })),
+  })),
+);
+```
+
+选择器应尽可能返回稳定的原始值或经过 memo 的切片：
+
+```tsx
+const itemCount = useCartStore((state) =>
+  state.lines.reduce((total, line) => total + line.quantity, 0),
+);
+```
+
+## URL 状态边界
+
+当另一个用户应能打开相同视图，或刷新后需要保留视图时，使用 URL 状态。
+
+```tsx
+import { useSearchParams } from "react-router-dom";
+
+export function useReportFilters() {
+  const [params, setParams] = useSearchParams();
+  const status = params.get("status") ?? "open";
+
+  function setStatus(nextStatus: string) {
+    setParams((next) => {
+      next.set("status", nextStatus);
+      next.set("page", "1");
+      return next;
+    });
+  }
+
+  return { status, setStatus };
+}
+```
+
+## 持久化适配器边界
+
+仅持久化稳定的客户端偏好设置或非敏感草稿。序列化逻辑放在组件外部。
+
+```ts
+interface PersistedGridState {
+  version: 1;
+  visibleColumns: string[];
+}
+
+const storageKey = "reports:grid";
+
+export function readGridState(): PersistedGridState | null {
+  const raw = window.localStorage.getItem(storageKey);
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as PersistedGridState;
+    return parsed.version === 1 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeGridState(state: PersistedGridState): void {
+  window.localStorage.setItem(storageKey, JSON.stringify(state));
+}
+```
+
+## SSR 与请求隔离
+
+- 当状态可能包含用户数据时，每次请求需创建独立的 Store。
+- 服务端渲染期间不要读取 `window`、`localStorage` 或 `document`。
+- 水合后再加载持久化偏好，并在水合前提供确定性默认值。
+- 服务端缓存脱水与纯客户端全局 Store 分开处理。

package/localized/zh-CN/skills/fec-storybook-component-doc/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fec-storybook-component-doc
+description: 用于设置或审查 Storybook 组件文档、设计系统展示、隔离组件状态预览、stories、addons、decorators、MDX 文档、组件状态交互检查、视觉基线或 Chromatic。真实浏览器跨页面旅程或更广覆盖规划优先选择对应测试工作流；中文触发词包括 Storybook、组件文档、Design System、视觉回归。
+---
+
+# Storybook 组件文档化
+
+## 用途
+
+为 UI 组件建立文档化、设计系统展示和隔离状态预览环境；交互与视觉测试只覆盖 Storybook 场景内的组件状态。
+
+## 流程
+
+1. 初始化或识别现有 Storybook 配置，沿用项目框架适配器、stories glob、主题和构建命令。
+2. 每个组件的 Story 覆盖默认态、主要变体、尺寸、语义 tone、disabled、loading、error、empty、selected、invalid 和关键边缘状态。
+3. 依赖 Router、Store、i18n、ThemeProvider 的组件用 decorators 包裹，不在 Story 中复制应用入口。
+4. 复杂组件用 MDX 补充使用说明、Props、slots/children、variant 矩阵、状态示例、可访问性要求和源码展示。
+5. 需要自动化时接入 interaction tests、addon-a11y、Chromatic 或 Storybook Test Runner；这些能力服务于组件文档和设计系统展示，不承接跨页业务旅程。
+6. 设计系统组件应记录 token 来源、Tailwind/class 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。
+
+## 详细参考
+
+- 需要 `main.ts`、`preview.ts`、stories、decorators、MDX、交互测试和视觉回归示例时，加载 [references/story-patterns.md](references/story-patterns.md)。
+
+## 约束
+
+- Story 需随组件 prop 变更同步更新。
+- Provider 依赖必须通过 decorator 补齐。
+- Storybook 构建产物 `storybook-static/` 不应提交到 Git。
+- Storybook 用于开发和组件文档，不替代生产页面 SEO。
+- Storybook 视觉基线用于组件状态；跨页面截图和真实路由流程分流到 E2E workflow。
+- 大型组件库需控制 stories glob 和 addon 开销。
+- 不用 Storybook 隐藏组件 API 问题；若变体组合爆炸，应先收敛组件职责或拆分组件。
+
+## 预期输出
+
+可交互的组件文档和设计系统展示站点，每个组件状态都有隔离预览，Props 表格可生成，关键 Storybook 场景有可选 play 测试或视觉回归基线。