@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/skills/fec-react-project-standard/references/react-quality-patterns.md

@@ -0,0 +1,131 @@
+# React 质量模式
+
+## 样式接入
+
+本 skill 不强制具体样式方案，默认遵循仓库现状。
+
+适配时注意：
+
+- Tailwind 项目继续使用 Tailwind
+- CSS Modules 项目保持命名与文件组织一致
+- styled-components 项目继续沿用其模式
+- 主题、颜色、字号、间距等优先复用仓库 token / CSS 变量
+- 避免在组件内硬编码大量视觉常量
+- 禁止内联样式（除动态值外）
+- 响应式处理需与项目断点约定一致
+
+---
+
+## 注释规范
+
+- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。
+- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。
+- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。
+- **公开 API**：模块或 hooks 的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。
+
+---
+
+## TypeScript 规范
+
+通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+
+React 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+
+### React 项目补充约定
+
+- Props interface 命名: `ComponentNameProps`
+- 事件处理函数: `handle` 前缀（如 `handleClick`）
+- 回调 Props: `on` 前缀（如 `onChange`、`onSubmit`）
+- 组件优先写显式 props 与返回值类型（`JSX.Element` / `React.ReactElement`），避免依赖 `React.FC` 的隐式 `children` 等行为差异
+- 泛型组件使用 `<T>` 约束，保持调用处类型推导；回调与事件类型优先使用 DOM / React 自带类型（如 `React.ChangeEvent<HTMLInputElement>`）
+
+```tsx
+interface TableProps<T extends Record<string, unknown>> {
+  data: T[];
+  columns: ColumnDef<T>[];
+  onRowClick?: (row: T) => void;
+}
+```
+
+---
+
+## 测试规范
+
+### 应优先覆盖的内容
+
+- 核心交互行为（点击、输入、提交）
+- 条件渲染（loading / error / empty / data）
+- 关键 hooks 的返回值和副作用
+- API 调用 mock 与模块级集成测试
+
+### 推荐风格
+
+- 测试用户行为，而不是实现细节
+- 优先使用 `screen.getByRole`、`getByLabelText`
+- 避免围绕内部 state 写脆弱测试
+- 只测关键行为，不机械追求覆盖率数字
+
+### 示例
+
+```tsx
+describe("UserForm", () => {
+  it("should submit with valid data", async () => {
+    const onSubmit = vi.fn();
+    render(<UserForm onSubmit={onSubmit} />);
+
+    await userEvent.type(screen.getByLabelText("用户名"), "test");
+    await userEvent.click(screen.getByRole("button", { name: "提交" }));
+
+    expect(onSubmit).toHaveBeenCalledWith({ username: "test" });
+  });
+
+  it("should show error on invalid input", async () => {
+    render(<UserForm onSubmit={vi.fn()} />);
+    await userEvent.click(screen.getByRole("button", { name: "提交" }));
+    expect(screen.getByText("用户名不能为空")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+
+## 常见反模式
+
+避免：
+
+- prop drilling 过深却不考虑组合或局部封装
+- 对局部问题过度使用 context
+- 把数据请求、视图渲染、命令式 DOM 操作全塞进一个文件
+- 在 useEffect 中做可以在事件处理函数中完成的事
+- 用 `useEffect + setState` 模拟本可直接计算的派生值
+- 将所有状态都推进全局 store
+- 在 `components/` 中放业务耦合组件
+- 直接绕过模块出口，从 feature 深层路径导入
+- 没有明显收益却提前做复杂优化
+- **新增类组件**或手写类式 Error Boundary（应函数组件 + `react-error-boundary` 等）
+
+---
+
+## 输出检查清单
+
+输出 React 代码或方案时，至少检查：
+
+- [ ] 是否先对齐了仓库现有约定
+- [ ] 页面 / feature / 通用组件边界是否清晰
+- [ ] 目录结构是否与模块复杂度匹配
+- [ ] Props 类型完整且明确
+- [ ] 解释性注释是否优先使用中文且点到要害
+- [ ] 可复用逻辑是否已提取为 hooks
+- [ ] loading / error / empty / data 状态是否齐全
+- [ ] API 层是否具备类型约束和统一错误处理
+- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `fec-typescript-project-standard`
+- [ ] 状态管理是否符合就近原则
+- [ ] 路由级或重型模块是否考虑懒加载
+- [ ] 样式方案是否与仓库保持一致
+- [ ] 关键行为是否有测试覆盖
+- [ ] 关键模块已用 **`react-error-boundary`**（等）包裹，且未手写类组件式 Boundary
+- [ ] 超长列表是否评估虚拟化；弹窗/复合组件是否具备键盘与焦点约定
+- [ ] 是否引入了不必要的新依赖或新范式
+
+---

package/localized/zh-CN/skills/fec-react-project-standard/references/react-runtime-patterns.md

@@ -0,0 +1,293 @@
+# React 运行时模式
+
+## 常用 UI 与状态模式
+
+以下模式可与本 skill 其他章节（Hooks、状态管理、性能优化、错误处理）对照使用；**按业务复杂度与团队熟悉度选用**，避免为模式而模式。思路参考业界常见的 React 前端模式实践（如组件组合、复合组件、性能与无障碍等）。
+
+### 组合优于继承
+
+- 用**小颗粒子组件** + `children` / 显式 props 拼装界面，而不是在 React 中搭建类继承层次。
+- 示例：`Card` + `CardHeader` + `CardBody`，由使用方组合，而不是一个巨型 `Card` 用大量布尔 props 分支。
+
+### 复合组件（Compound Components）
+
+- 根组件通过 **Context** 向子组件提供内部状态（如当前 Tab、打开/关闭）。
+- 子组件在 `useContext` 为空时**抛错或断言**，明确「必须在 Provider 树内使用」。
+- API 表面保持可读：`<Tabs><TabList><Tab /></TabList></Tabs>`。
+
+### Render Props / 函数子
+
+- 适用：封装**数据获取与三态**（loading / error / data），把**渲染决策**交给父级。
+- 与 **自定义 Hook** 二选一即可：多数场景 `useXxx()` + 普通组件更直观；仅在需要强约束「同层渲染逻辑」时保留 Render Props。
+
+### Context + useReducer
+
+- 适合**中等复杂度、多子树共享**的客户端状态，且更新可归约为明确 `action`。
+- 避免把高频变化的大对象塞进顶层 Context；服务端数据仍优先 **React Query / SWR**。
+- 大型全局业务状态继续用仓库已选的 **Zustand / Redux Toolkit / Jotai**。
+
+### 表单
+
+- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `fec-typescript-project-standard`。
+- 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。
+
+### Error Boundary
+
+- **不要**在业务代码中手写 React **类组件**形式的 Error Boundary；统一使用 **`react-error-boundary`**（或团队认可的同类库）在**模块边界**兜底渲染失败（与本章「错误处理」、`error-handling.md` 一致）。
+- 用 `FallbackComponent` 与 `resetErrorBoundary` 提供「重试」；**日志上报**放在库的 **`onError`**（等回调）中，生产代码避免长期依赖 `console.log`（见 TypeScript 规则）。
+
+
+### 动画与过渡
+
+- 列表进出场可用 **Framer Motion** 的 `AnimatePresence` + `key`，或 CSS `transition`；注意减少布局抖动与 `prefers-reduced-motion`（与无障碍策略一致时）。
+
+### 无障碍与焦点
+
+- 自定义下拉、标签页等：**`role` / `aria-*`**、**方向键 / Enter / Escape** 行为与焦点环可见。
+- 弹窗：打开时将焦点移入对话框，关闭时**恢复**触发元素焦点；可用 **`focus-trap-react`** 或类似方案，与 `fec-accessibility-check` skill 互补。
+
+### Next.js 与服务端组件
+
+- **App Router、Server Components、服务端数据获取与缓存**见 **`fec-nextjs-project-standard`**；客户端交互模式仍以本章与 Hooks 规范为准。
+
+---
+
+
+## Hooks 设计模式
+
+### 适合抽为自定义 Hook 的场景
+
+- 数据获取与三态管理
+- 表单状态逻辑
+- 分页、筛选、排序编排
+- 事件监听与副作用清理
+- 可在多个组件复用的交互逻辑
+
+### 推荐原则
+
+- 统一使用 `use` 前缀命名
+- 返回对象而非数组，方便按需解构，增强可读性和扩展性
+- 状态和行为封装在一起
+- Hook 内部处理 `loading / error / data`
+- 对外暴露清晰的最小接口，不泄漏无关内部细节
+
+### 示例
+
+```tsx
+function useUserList(params: QueryParams) {
+  const [data, setData] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetch = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await getUserList(params);
+      setData(res.list);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [params]);
+
+  useEffect(() => {
+    fetch();
+  }, [fetch]);
+
+  return { data, loading, error, refetch: fetch };
+}
+```
+
+### Hook 使用原则
+
+- `useEffect` 必须有正确依赖和清理逻辑
+- `useMemo` / `useCallback` 不要滥用，只有在稳定引用确实重要时再加
+- 不在条件分支或循环中调用 hooks
+- 已引入 React Query / SWR 时，数据请求优先走这些库，而不是自己重复造一套缓存层
+
+---
+
+## 路由组织
+
+### 推荐方式
+
+- 路由配置集中管理
+- 路径常量化
+- 页面组件按需懒加载
+- 权限控制放在 guard 层，而不是散落在页面组件内
+- 分页、筛选、排序等 URL 驱动状态优先与地址栏同步
+
+### 示例
+
+```tsx
+const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <MainLayout />,
+    children: [
+      { index: true, element: <DashboardPage /> },
+      { path: "users", element: <UserListPage /> },
+      { path: "users/:id", element: <UserDetailPage /> },
+      { path: "settings", element: <SettingsPage /> },
+    ],
+  },
+  { path: "/login", element: <LoginPage /> },
+  { path: "*", element: <NotFoundPage /> },
+];
+```
+
+```tsx
+const UserListPage = lazy(() => import("@/pages/UserList/UserListPage"));
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated } = useAuth();
+  if (!isAuthenticated) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+```
+
+---
+
+## 状态管理选型
+
+| 状态类型           | 推荐方案                                          |
+| ------------------ | ------------------------------------------------- |
+| 组件内临时 UI 状态 | `useState` / `useReducer`                         |
+| 跨组件共享业务状态 | Zustand / Redux Toolkit / Jotai（按仓库实际选择） |
+| 服务端数据缓存     | React Query / SWR                                 |
+| URL 驱动状态       | 路由参数 / `useSearchParams`                      |
+| 表单状态           | React Hook Form / Formik                          |
+
+### 核心原则
+
+- 就近管理：状态尽量放在最近的公共祖先
+- 单一数据源：同一份数据不要维护多份
+- 派生优于同步：可计算值优先在渲染期计算
+- 服务端数据优先交给请求库管理，不手动塞进全局 store
+- 不要因为“以后可能会用到”就把局部状态提前升级为全局状态
+
+---
+
+## API 层规范
+
+### 设计原则
+
+- 请求基础设施集中在 `services/`
+- 业务 API 按 feature 拆分，而不是全部堆在一个文件
+- 请求参数和响应结果都应有明确类型
+- 认证、错误格式化、通用拦截放在请求层统一处理
+- 页面和组件不要直接散落拼接请求细节
+
+### 示例
+
+```ts
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      redirectToLogin();
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+```ts
+// features/user/api.ts
+export function getUserList(
+  params: UserQueryParams,
+): Promise<PageResult<User>> {
+  return request.get("/users", { params });
+}
+
+export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return request.put(`/users/${id}`, data);
+}
+```
+
+---
+
+## 错误处理
+
+### 必须覆盖的状态
+
+- Loading
+- Error
+- Empty
+- Data
+
+### 推荐做法
+
+- 关键功能模块使用 Error Boundary 包裹，避免局部异常导致全页白屏
+- 异步请求失败时必须给用户可见反馈
+- 重要操作提供重试能力
+- 不要吞错，不写空 `catch`
+
+### 示例（`react-error-boundary`，函数式 Fallback）
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+function ModuleErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
+  return (
+    <div>
+      模块加载失败
+      <button type="button" onClick={resetErrorBoundary}>
+        重试
+      </button>
+    </div>
+  );
+}
+
+export function UserDashboardSection() {
+  return (
+    <ErrorBoundary FallbackComponent={ModuleErrorFallback}>
+      <UserDashboard />
+    </ErrorBoundary>
+  );
+}
+```
+
+---
+
+## Suspense 与懒加载
+
+适用场景：
+
+- 路由级页面
+- 图表、富文本编辑器、地图、重型表格等大体积组件
+- 初始化成本较高的模块
+
+示例：
+
+```tsx
+const HeavyChart = lazy(() => import("./components/HeavyChart"));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<ChartSkeleton />}>
+      <HeavyChart data={chartData} />
+    </Suspense>
+  );
+}
+```
+
+建议：
+
+- 路由级优先 `lazy + Suspense`
+- `fallback` 优先使用 Skeleton 或更贴近内容的占位态，而不是纯 spinner
+
+---
+

package/localized/zh-CN/skills/fec-refactor-clean/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: fec-refactor-clean
+description: 用于安全移除前端死代码、未使用导出、陈旧组件、废弃路由、未使用依赖，或由 knip、depcheck、ts-prune、TypeScript、ESLint、人工审查发现的清理目标。不要用于会改变行为的功能重写；中文触发词包括 死代码、清理未使用、refactor clean、依赖清理、删除无用代码。
+---
+
+# 重构清理
+
+## 用途
+
+在验证保护下识别并清理无用前端代码，减少技术债，同时避免误删动态引用、路由入口、配置文件和运行时约定。
+
+## 流程
+
+1. 先建立基线：运行或确认当前 lint、type-check、test、build 的状态。
+2. 收集候选项：
+   - 优先使用仓库已有工具，如 knip、depcheck、ts-prune、eslint、TypeScript。
+   - 没有工具时，用 `rg` 检查引用、导出、路由、注册点和文档入口。
+3. 按风险分类：
+   - SAFE：测试夹具、未引用工具函数、明确未导出的私有组件。
+   - CAUTION：共享组件、feature 入口、样式文件、Storybook stories。
+   - DANGER：路由、配置、package scripts、运行时模板、动态 import、插件元数据。
+   - UPGRADE：过期依赖、重复依赖、未使用依赖和安全告警先进入依赖升级或依赖清理评估，不与死代码删除混做。
+4. 只自动处理 SAFE 项；CAUTION 和 DANGER 需输出建议和证据，不直接删除。
+5. 每批清理后运行受影响验证命令。
+6. 若验证失败，停止扩大清理范围，先定位该批次。
+7. 清理结束后做行为等价复核：公开 API、路由、命令、模板、metadata、文档示例和报告输出仍可被引用。
+8. 对技术债排序：优先清理有验证保护、影响开发效率或阻塞升级的项目；低证据的大范围重写只输出建议。
+
+## 前端专项检查
+
+- 检查 JSX/模板字符串、路由配置、barrel export、Storybook、测试、文档示例和动态组件注册。
+- 样式文件需检查 className、CSS Modules、Tailwind safelist、全局选择器和主题变量。
+- 依赖清理需检查构建插件、运行时模板、CLI scripts、monorepo 子包和 peer dependency。
+
+## 约束
+
+- 不改变用户可见行为。
+- 不删除无法证明无引用的公开 API、路由、模板或配置。
+- 不用“一次大删除”替代可验证的小批次清理。
+- 不把格式化、重命名或架构重写混入死代码清理。
+- 不用“看起来没人用”作为证据；必须有搜索、工具输出、类型错误消失或测试保护。
+- 不把依赖大版本升级伪装成清理；升级风险、release notes 和 lockfile 变更应分流到依赖升级工作流。
+
+## 详细参考
+
+撰写清理报告时，加载 [references/report-template.md](references/report-template.md)。
+
+## 预期输出
+
+- 清理报告保存为 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`。
+- 代码清理后相关验证命令通过，或明确说明阻塞原因。
+## 结构重构边界
+
+本工作流只负责已经证明无用/未使用的内容。如果代码仍在运行，问题属于过长函数、职责所有权、可变/派生数据、条件逻辑、API 形态或继承设计等结构重构，应分流到保持行为的结构重构，而不是以“清理”名义删除或重写。

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

@@ -0,0 +1,83 @@
+---
+name: fec-refactoring
+description: 用于在不改变可观察行为的前提下重组既有前端代码，包括职责提炼、模块搬移、条件逻辑简化、API 整理和数据组织。不要用于新增功能、改变行为的缺陷修复、依赖或框架迁移，以及已经证实的死代码清理。
+---
+
+# 技能：保持行为的重构
+
+## 用途
+
+以小步、可验证、可回滚的方式重组仍在使用的前端代码，同时保持用户、调用方、测试、路由和集成能够观察到的行为不变。
+
+## 核心契约
+
+每次执行都遵守以下规则：
+
+1. **行为保持**：纯重构只改变内部结构，不主动改变可观察行为。
+2. **修改前基线**：编辑前先记录当前可用验证结果。
+3. **一次只做一个主要重构**：每一步只有一个主要结构意图。
+4. **每一步都验证**：完成一步后立即运行最小但有效的验证。
+5. **先回滚当前步骤，再讨论修复**：若当前步骤引入回归，先恢复到上一步，再缩小或重排方案。
+6. **重构与功能修改分离**：新增行为或改变行为的缺陷修复不属于纯重构。
+7. **优先最小安全重构**：有局部、可逆方案时，不直接扩大为架构重写。
+8. **遵守差异预算**：实际修改范围明显超出计划时必须停止并重新评估。
+
+纯重构采用 **GREEN → REFACTOR → GREEN**，不为了形式上的 TDD 人为制造失败行为测试。
+
+## 流程
+
+1. 分类请求，确认目标是结构调整且要求行为保持。
+2. 读取项目配置、受影响模块、公开导出、路由、状态边界、测试和当前 diff。
+3. 记录相关可观察契约：输入、输出、异常、副作用、UI 状态、事件、网络请求、状态迁移、路由和公开 API。
+4. 建立修改前基线；既有失败要单独记录，不能算到后续重构头上。
+5. 基于证据诊断结构问题，并检查可能的误判。
+6. 建立安全网：优先复用已有测试，风险较高且覆盖不足时再补当前行为的特征测试。
+7. 把方案拆成有顺序的小步，每步记录手法、原因、前置条件、风险、差异预算、验证和回滚边界。
+8. 每次只执行一个主要结构变换，不夹带无关清理、格式化和重新设计。
+9. 立即验证，并比较实际修改范围与差异预算。
+10. 若出现新回归，先回滚当前步骤，确认基线恢复，再缩小或调整顺序。
+11. 最后按需要运行类型检查、测试、构建、E2E、无障碍或其他专项门禁。
+12. 根据证据给出 PASS、PARTIAL 或 NOT PROVEN，不夸大验证强度。
+
+## 风险分级
+
+| 风险 | 常见范围 | 默认动作 |
+| --- | --- | --- |
+| `SAFE` | 局部私有代码、契约稳定、容易回滚 | 可执行，并逐步验证 |
+| `CAUTION` | 跨模块、共享状态、导入、Hook/Composable、生命周期 | 安全证据充分时执行，否则先规划 |
+| `DANGER` | 公开 API、路由、持久化、网络契约、认证、SSR/水合、大范围状态或继承改造 | 默认先规划并停止等待明确授权 |
+
+风险由上下文决定，不能只凭手法名称判定安全级别。
+
+## 差异预算
+
+每个可执行步骤先写清：
+
+```text
+预期文件数：N
+预期函数/组件数：N
+预期公开 API 变化：0
+预期行为变化：0
+```
+
+如果实际 diff 明显超出预算，停止并重新评估，不能静默扩大成重新设计。
+
+## 参考资料
+
+- 安全规则、证据模型和风险语言见 [principles.md](references/principles.md)。
+- 状态机、基线、回滚和报告契约见 [workflow.md](references/workflow.md)。
+- 判断何时重构或何时延后见 [when-to-refactor.md](references/when-to-refactor.md)。
+- 区分重构、功能、缺陷、清理、迁移和评审见 [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md)。
+
+## 约束
+
+- 不修改测试来接受被重构意外改变的业务行为。
+- 未有充分证据时，不把认证、权限、路由、持久化、协议或公开包契约变化标为 `SAFE`。
+- 当前步骤出现新失败后，不继续叠加结构修改。
+- 项目没有测试框架时，不自动安装新框架。
+- 行数、复杂度、注释、一个 switch 或链式调用都不能单独证明存在坏味道。
+- 默认不执行远程 Git 写入。
+
+## 预期输出
+
+输出带证据、风险、差异预算、逐步验证和必要回滚记录的重构方案或实现，并给出 PASS、PARTIAL 或 NOT PROVEN 的行为保持结论。

package/localized/zh-CN/skills/fec-refactoring/references/principles.md

@@ -0,0 +1,43 @@
+# 重构原则
+
+## 定义
+
+重构是在不主动改变可观察行为的前提下调整既有代码内部结构，目标是让后续修改更容易理解、定位、验证和回滚，而不是把新功能偷偷塞进结构修改。
+
+## 八条硬规则
+
+1. **行为保持**：开始重要修改前先明确相关可观察契约。
+2. **修改前基线**：把既有失败与当前步骤新引入的回归区分开。
+3. **一次一个主要重构**：每一步只承担一个结构意图。
+4. **每一步都验证**：完成一步立即运行最小有效反馈。
+5. **先回滚再修复**：当前步骤导致新回归时，先恢复，再缩小或重排。
+6. **功能修改分离**：新增结果、改变规则、改变错误行为都不属于纯重构。
+7. **最小安全重构优先**：优先局部、可逆、证据充分的变换。
+8. **遵守差异预算**：修改范围膨胀是停止信号，不是继续扩张的理由。
+
+## 可观察行为
+
+按实际范围检查：
+
+- 返回值、异常和错误映射；
+- 副作用及有业务意义的顺序；
+- 请求、载荷、重试、取消和认证行为；
+- 状态迁移、持久化、缓存身份和 memoization 依赖的对象身份；
+- DOM、加载/错误/空状态、焦点、键盘和事件；
+- props、emits、slots、Hook/Composable 契约、包导出、路由和 URL。
+
+## 证据模型
+
+优先使用调用点、依赖方向、数据所有权、变更位置、已有测试、公开契约、动态注册点、路由、i18n、Storybook、样式动态引用以及框架生命周期语义。度量值只负责提示“去哪里看”，不能单独下诊断结论。
+
+## 风险模型
+
+- **SAFE**：局部私有范围、契约稳定、容易回滚并有对应验证。
+- **CAUTION**：跨文件/组件、共享辅助模块、状态所有权、生命周期或动态引用，或者行为覆盖不完整。
+- **DANGER**：公开 API、路由、存储结构、后端契约、认证权限、SSR/水合、关键计算、大范围继承或状态架构替换。
+
+同一手法在不同上下文风险可能完全不同，例如局部变量改名可以很安全，而序列化字段改名可能影响外部契约。
+
+## 风险修改前的特征测试
+
+重要行为覆盖不足时，可以先补描述当前实际行为的特征测试。它第一次运行可以直接为绿，因为目的只是锁定既有行为，不是创造新需求。

package/localized/zh-CN/skills/fec-refactoring/references/refactoring-vs-feature-change.md

@@ -0,0 +1,25 @@
+# 重构与相邻工作的边界
+
+## 纯重构
+
+目标是改善职责、命名、封装、位置、条件逻辑、API 形状或数据组织，并明确要求不改变调用方/用户可观察行为时，属于纯重构。验证模型是 **GREEN → REFACTOR → GREEN**。
+
+## 功能或改变行为的缺陷修复
+
+新增能力、改变业务规则、改变接受输入、改变可见输出、改变错误结果或主动改变副作用，都不是纯重构。应先用失败行为测试表达新期望，再实现。
+
+## 调试
+
+故障原因未知时，应先找到根因。后续修复可能包含重构，但不能用“重构一下”代替故障证据。
+
+## 死代码清理
+
+已证实未使用的代码、导出、依赖、路由等需要专门检查动态 import、配置、模板、Storybook、CSS、i18n 和生成内容，不能与活代码的大范围结构改写混做。
+
+## 迁移
+
+框架、依赖、路由、构建系统、状态库或整体架构迁移会主动跨越兼容边界，即使设计因此更好，也应按迁移规划处理。
+
+## 普通评审
+
+合并前评审可以指出结构问题，但默认先输出报告；若要诊断或执行重构，应作为明确的后续动作，而不是评审过程中静默改写源码。