@bovinphang/frontend-craft 2.7.0 → 2.9.0

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

@@ -1,43 +1,43 @@
 # React quality patterns
 
-## 样式接入
+## Style access
 
-本 skill 不强制具体样式方案，默认遵循仓库现状。
+This skill does not enforce a specific style scheme and follows the current status of the warehouse by default.
 
-适配时注意：
+Please note when adapting:
 
-- Tailwind 项目继续使用 Tailwind
-- CSS Modules 项目保持命名与文件组织一致
-- styled-components 项目继续沿用其模式
-- 主题、颜色、字号、间距等优先复用仓库 token / CSS 变量
-- 避免在组件内硬编码大量视觉常量
-- 禁止内联样式（除动态值外）
-- 响应式处理需与项目断点约定一致
+- Tailwind project continues to use Tailwind
+- CSS Modules projects keep naming consistent with file organization
+- The styled-components project continues to follow its pattern
+- Theme, color, font size, spacing, etc. give priority to reusing warehouse token / CSS variables
+- Avoid hardcoding a large number of visual constants within the component
+- Disable inline styles (except dynamic values)
+- Responsive processing must be consistent with the project breakpoint agreement
 
 ---
 
-## 注释规范
+## Comment specifications
 
-- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。
-- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。
-- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。
-- **公开 API**：模块或 hooks 的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。
+- **Prefer using Chinese**: When explaining "why this is done", business constraints, boundary conditions, and non-obvious trade-offs, give priority to writing comments in Chinese to make it easier for the team and business parties to read.
+- **Exception when consistent with the code language**: When connecting third-party protocol field names, HTTP headers, and English terms in specifications, English proper nouns can be retained in the comments, and Chinese and English descriptions can be given when necessary.
+- **Less but more precise**: Can express clear logic through clear naming and types without writing nonsense comments; complex branches, temporary compatibility, and performance trade-offs must be clearly stated.
+- **Public API**: The external contract of modules or hooks can use JSDoc (`@param` / `@returns` / `@example`). The instructions can be in Chinese, unless the warehouse requires English.
 
 ---
 
-## TypeScript 规范
+## TypeScript Specification
 
-通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+Common TypeScript project rules are taken care of by `fec-typescript-project-standard`, including `tsconfig`, strictness, DTO / view model boundaries, `unknown` narrowing, public API types, declared artifacts, and type tests.
 
-React 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+The React specification only supplements components, Props, events and TSX generic writing; complex type modeling or cross-framework type contracts are first offloaded to `fec-typescript-project-standard`.
 
-### React 项目补充约定
+### React project supplementary conventions
 
-- Props interface 命名: `ComponentNameProps`
-- 事件处理函数: `handle` 前缀（如 `handleClick`）
-- 回调 Props: `on` 前缀（如 `onChange`、`onSubmit`）
-- 组件优先写显式 props 与返回值类型（`JSX.Element` / `React.ReactElement`），避免依赖 `React.FC` 的隐式 `children` 等行为差异
-- 泛型组件使用 `<T>` 约束，保持调用处类型推导；回调与事件类型优先使用 DOM / React 自带类型（如 `React.ChangeEvent<HTMLInputElement>`）
+- Props interface naming: `ComponentNameProps`
+- Event handling function: `handle` prefix (such as `handleClick`)
+- Callback Props: `on` prefix (such as `onChange`, `onSubmit`)
+- Components give priority to writing explicit props and return value types (`JSX.Element` / `React.ReactElement`) to avoid behavioral differences such as relying on the implicit `children` of `React.FC`
+- Generic components use `<T>` constraints to maintain call-site type derivation; callback and event types preferentially use DOM/React’s own types (such as `React.ChangeEvent<HTMLInputElement>`)
 
 ```tsx
 interface TableProps<T extends Record<string, unknown>> {
@@ -49,23 +49,23 @@ interface TableProps<T extends Record<string, unknown>> {
 
 ---
 
-## 测试规范
+## Test specifications
 
-### 应优先覆盖的内容
+### Content that should be covered first
 
-- 核心交互行为（点击、输入、提交）
-- 条件渲染（loading / error / empty / data）
-- 关键 hooks 的返回值和副作用
-- API 调用 mock 与模块级集成测试
+- Core interaction behaviors (click, input, submit)
+- Conditional rendering (loading/error/empty/data)
+- Return values and side effects of key hooks
+- API call mock and module-level integration testing
 
-### 推荐风格
+### Recommended style
 
-- 测试用户行为，而不是实现细节
-- 优先使用 `screen.getByRole`、`getByLabelText`
-- 避免围绕内部 state 写脆弱测试
-- 只测关键行为，不机械追求覆盖率数字
+- Test user behavior, not implementation details
+- Prioritize using `screen.getByRole`, `getByLabelText`
+- Avoid writing brittle tests around internal state
+- Only measure key behaviors and do not mechanically pursue coverage figures
 
-### 示例
+### Example
 
 ```tsx
 describe("UserForm", () => {
@@ -73,16 +73,16 @@ describe("UserForm", () => {
     const onSubmit = vi.fn();
     render(<UserForm onSubmit={onSubmit} />);
 
-    await userEvent.type(screen.getByLabelText("用户名"), "test");
-    await userEvent.click(screen.getByRole("button", { name: "提交" }));
+    await userEvent.type(screen.getByLabelText("username"), "test");
+    await userEvent.click(screen.getByRole("button", { name: "Submit" }));
 
     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();
+    await userEvent.click(screen.getByRole("button", { name: "Submit" }));
+    expect(screen.getByText("Username cannot be empty")).toBeInTheDocument();
   });
 });
 ```
@@ -90,42 +90,42 @@ describe("UserForm", () => {
 ---
 
 
-## 常见反模式
+## Common anti-patterns
 
-避免：
+Avoid:
 
-- prop drilling 过深却不考虑组合或局部封装
-- 对局部问题过度使用 context
-- 把数据请求、视图渲染、命令式 DOM 操作全塞进一个文件
-- 在 useEffect 中做可以在事件处理函数中完成的事
-- 用 `useEffect + setState` 模拟本可直接计算的派生值
-- 将所有状态都推进全局 store
-- 在 `components/` 中放业务耦合组件
-- 直接绕过模块出口，从 feature 深层路径导入
-- 没有明显收益却提前做复杂优化
-- **新增类组件**或手写类式 Error Boundary（应函数组件 + `react-error-boundary` 等）
+- prop drilling is too deep without considering combination or partial encapsulation
+- Excessive use of context for local issues
+- Stuff data requests, view rendering, and imperative DOM operations into one file
+- Do things in useEffect that can be done in event handlers
+- Use `useEffect + setState` to simulate derived values that could be calculated directly
+- Push all states to the global store
+- Put business coupling components in `components/`
+- Directly bypass the module export and import from the feature deep path
+- There is no obvious benefit but complex optimization is done in advance
+- **New class component** or handwritten class Error Boundary (should function component + `react-error-boundary`, etc.)
 
 ---
 
-## 输出检查清单
-
-输出 React 代码或方案时，至少检查：
-
-- [ ] 是否先对齐了仓库现有约定
-- [ ] 页面 / feature / 通用组件边界是否清晰
-- [ ] 目录结构是否与模块复杂度匹配
-- [ ] Props 类型完整且明确
-- [ ] 解释性注释是否优先使用中文且点到要害
-- [ ] 可复用逻辑是否已提取为 hooks
-- [ ] loading / error / empty / data 状态是否齐全
-- [ ] API 层是否具备类型约束和统一错误处理
-- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `fec-typescript-project-standard`
-- [ ] 状态管理是否符合就近原则
-- [ ] 路由级或重型模块是否考虑懒加载
-- [ ] 样式方案是否与仓库保持一致
-- [ ] 关键行为是否有测试覆盖
-- [ ] 关键模块已用 **`react-error-boundary`**（等）包裹，且未手写类组件式 Boundary
-- [ ] 超长列表是否评估虚拟化；弹窗/复合组件是否具备键盘与焦点约定
-- [ ] 是否引入了不必要的新依赖或新范式
+## Output checklist
+
+When outputting React code or solutions, at least check:
+
+- [ ] Whether to align the existing contracts of the warehouse first
+- [ ] Page / feature / Is the boundary of common components clear?
+- [ ] Whether the directory structure matches the module complexity
+- [ ] Props type is complete and clear
+- [ ] Whether explanatory comments should be given priority in Chinese and to the point
+- [ ] Whether reusable logic has been extracted into hooks
+- [ ] loading / error / empty / data status is complete
+- [ ] Whether the API layer has type constraints and unified error handling
+- [ ] Whether complex DTO, external data narrowing, public types or `tsconfig` issues have been offloaded to `fec-typescript-project-standard`
+- [ ] Whether status management complies with the proximity principle
+- [ ] Whether lazy loading is considered for routing-level or heavy-duty modules
+- [ ] Whether the style scheme is consistent with the warehouse
+- [ ] Whether key behaviors are covered by tests
+- [ ] Key modules have been wrapped with **`react-error-boundary`** (etc.), and no hand-written class component Boundary
+- [ ] Whether the long list evaluates virtualization; whether the pop-up window/composite component has keyboard and focus conventions
+- [ ] Whether unnecessary new dependencies or new paradigms are introduced
 
 ---

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

@@ -1,77 +1,77 @@
 # React runtime patterns
 
-## 常用 UI 与状态模式
+## Common UI and status mode
 
-以下模式可与本 skill 其他章节（Hooks、状态管理、性能优化、错误处理）对照使用；**按业务复杂度与团队熟悉度选用**，避免为模式而模式。思路参考业界常见的 React 前端模式实践（如组件组合、复合组件、性能与无障碍等）。
+The following patterns can be used in comparison with other chapters of this skill (Hooks, state management, performance optimization, error handling); **Select based on business complexity and team familiarity** to avoid patterns for pattern's sake. The ideas refer to common React front-end pattern practices in the industry (such as component combination, composite components, performance and accessibility, etc.).
 
-### 组合优于继承
+### Composition is better than inheritance
 
-- 用**小颗粒子组件** + `children` / 显式 props 拼装界面，而不是在 React 中搭建类继承层次。
-- 示例：`Card` + `CardHeader` + `CardBody`，由使用方组合，而不是一个巨型 `Card` 用大量布尔 props 分支。
+- Use **small subcomponents** + `children` / explicit props to assemble the interface instead of building a class inheritance hierarchy in React.
+- Example: `Card` + `CardHeader` + `CardBody`, composed by the consumer, rather than one giant `Card` branched with a lot of boolean props.
 
-### 复合组件（Compound Components）
+### Compound Components
 
-- 根组件通过 **Context** 向子组件提供内部状态（如当前 Tab、打开/关闭）。
-- 子组件在 `useContext` 为空时**抛错或断言**，明确「必须在 Provider 树内使用」。
-- API 表面保持可读：`<Tabs><TabList><Tab /></TabList></Tabs>`。
+- The root component provides internal state (such as current Tab, open/closed) to child components through **Context**.
+- The subcomponent **throws an error or asserts** when `useContext` is empty, making it clear that it "must be used within the Provider tree".
+- API surfaces remain readable: `<Tabs><TabList><Tab /></TabList></Tabs>`.
 
-### Render Props / 函数子
+### Render Props/Functionator
 
-- 适用：封装**数据获取与三态**（loading / error / data），把**渲染决策**交给父级。
-- 与 **自定义 Hook** 二选一即可：多数场景 `useXxx()` + 普通组件更直观；仅在需要强约束「同层渲染逻辑」时保留 Render Props。
+- Applicable: Encapsulate **data acquisition and three-state** (loading / error / data), and hand over **rendering decision** to the parent.
+- Choose one of the two with **Custom Hook**: `useXxx()` + ordinary components are more intuitive in most scenarios; only keep Render Props when strong constraints on "same-layer rendering logic" are required.
 
 ### Context + useReducer
 
-- 适合**中等复杂度、多子树共享**的客户端状态，且更新可归约为明确 `action`。
-- 避免把高频变化的大对象塞进顶层 Context；服务端数据仍优先 **React Query / SWR**。
-- 大型全局业务状态继续用仓库已选的 **Zustand / Redux Toolkit / Jotai**。
+- Suitable for **moderate complexity, multi-subtree sharing** client state, and updates can be reduced to explicit `action`.
+- Avoid stuffing large objects that change frequently into the top-level Context; server-side data still takes priority **React Query / SWR**.
+- Large global business status continues to use the **Zusand / Redux Toolkit / Jotai** selected by the warehouse.
 
-### 表单
+### Form
 
-- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `fec-typescript-project-standard`。
-- 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。
+- Controlled fields + validation error objects are a feasible implementation; medium and large forms are given priority **React Hook Form** (or Formik) + **Zod**, and complex form values, DTO and validation type contracts are offloaded to `fec-typescript-project-standard`.
+- Avoid huge `useState` form objects and repeated validation logic in a single component, detachable field subcomponents or extract `useFormSchema`.
 
 ### Error Boundary
 
-- **不要**在业务代码中手写 React **类组件**形式的 Error Boundary；统一使用 **`react-error-boundary`**（或团队认可的同类库）在**模块边界**兜底渲染失败（与本章「错误处理」、`error-handling.md` 一致）。
-- 用 `FallbackComponent` 与 `resetErrorBoundary` 提供「重试」；**日志上报**放在库的 **`onError`**（等回调）中，生产代码避免长期依赖 `console.log`（见 TypeScript 规则）。
+- **Don't** handwrite Error Boundary in the form of React **class component** in business code; uniformly use **`react-error-boundary`** (or a similar library recognized by the team) to render failure at the **module boundary** (consistent with "Error Handling" and `error-handling.md` in this chapter).
+- Use `FallbackComponent` and `resetErrorBoundary` to provide "retry"; **log reporting** is placed in the library's **`onError`** (waiting for callbacks), and production code avoids long-term dependence on `console.log` (see TypeScript rules).
 
 
-### 动画与过渡
+### Animation and Transition
 
-- 列表进出场可用 **Framer Motion** 的 `AnimatePresence` + `key`，或 CSS `transition`；注意减少布局抖动与 `prefers-reduced-motion`（与无障碍策略一致时）。
+- List entry and exit can be done using **Framer Motion**'s `AnimatePresence` + `key`, or CSS `transition`; note that reduced layout jitter and `prefers-reduced-motion` (when consistent with accessibility policies).
 
-### 无障碍与焦点
+### Accessibility and Focus
 
-- 自定义下拉、标签页等：**`role` / `aria-*`**、**方向键 / Enter / Escape** 行为与焦点环可见。
-- 弹窗：打开时将焦点移入对话框，关闭时**恢复**触发元素焦点；可用 **`focus-trap-react`** 或类似方案，与 `fec-accessibility-check` skill 互补。
+- Customized drop-downs, tabs, etc.: **`role` / `aria-*`**, **Direction keys / Enter / Escape** Behavior and focus rings are visible.
+- Pop-up window: Move the focus into the dialog box when it is opened, and **restore** when it is closed to trigger the element focus; **`focus-trap-react`** or similar solutions can be used to complement the `fec-accessibility-check` skill.
 
-### Next.js 与服务端组件
+### Next.js and server-side components
 
-- **App Router、Server Components、服务端数据获取与缓存**见 **`fec-nextjs-project-standard`**；客户端交互模式仍以本章与 Hooks 规范为准。
+- **App Router, Server Components, server-side data acquisition and caching** see **`fec-nextjs-project-standard`**; the client interaction mode is still subject to this chapter and the Hooks specification.
 
 ---
 
 
-## Hooks 设计模式
+## Hooks design pattern
 
-### 适合抽为自定义 Hook 的场景
+### Suitable for scenarios where custom Hooks are drawn
 
-- 数据获取与三态管理
-- 表单状态逻辑
-- 分页、筛选、排序编排
-- 事件监听与副作用清理
-- 可在多个组件复用的交互逻辑
+- Data acquisition and three-state management
+- Form status logic
+- Paging, filtering, sorting and arrangement
+- Event monitoring and side effect cleanup
+- Interaction logic that can be reused in multiple components
 
-### 推荐原则
+### Recommended principles
 
-- 统一使用 `use` 前缀命名
-- 返回对象而非数组，方便按需解构，增强可读性和扩展性
-- 状态和行为封装在一起
-- Hook 内部处理 `loading / error / data`
-- 对外暴露清晰的最小接口，不泄漏无关内部细节
+- Uniformly use `use` prefix naming
+- Return objects instead of arrays to facilitate on-demand destructuring and enhance readability and scalability
+- State and behavior are encapsulated together
+- Hook internal processing `loading/error/data`
+- Expose a clear minimal interface to the outside world without leaking irrelevant internal details
 
-### 示例
+### Example
 
 ```tsx
 function useUserList(params: QueryParams) {
@@ -100,26 +100,26 @@ function useUserList(params: QueryParams) {
 }
 ```
 
-### Hook 使用原则
+### Hook usage principles
 
-- `useEffect` 必须有正确依赖和清理逻辑
-- `useMemo` / `useCallback` 不要滥用，只有在稳定引用确实重要时再加
-- 不在条件分支或循环中调用 hooks
-- 已引入 React Query / SWR 时，数据请求优先走这些库，而不是自己重复造一套缓存层
+- `useEffect` must have correct dependencies and cleanup logic
+- `useMemo` / `useCallback` Don’t overuse it, add it only when stable references are really important
+- Don't call hooks in conditional branches or loops
+- When React Query / SWR has been introduced, data requests go through these libraries first instead of recreating a cache layer yourself.
 
 ---
 
-## 路由组织
+## Routing organization
 
-### 推荐方式
+### Recommended method
 
-- 路由配置集中管理
-- 路径常量化
-- 页面组件按需懒加载
-- 权限控制放在 guard 层，而不是散落在页面组件内
-- 分页、筛选、排序等 URL 驱动状态优先与地址栏同步
+- Centralized management of routing configuration
+- Path constantization
+- Lazy loading of page components on demand
+- Permission control is placed in the guard layer instead of scattered within the page components
+- Paging, filtering, sorting, etc. URL driver status is synchronized with the address bar first
 
-### 示例
+### Example
 
 ```tsx
 const routes: RouteObject[] = [
@@ -150,37 +150,37 @@ function ProtectedRoute({ children }: { children: React.ReactNode }) {
 
 ---
 
-## 状态管理选型
+## Status management selection
 
-| 状态类型           | 推荐方案                                          |
+| Status type | Recommended solution |
 | ------------------ | ------------------------------------------------- |
-| 组件内临时 UI 状态 | `useState` / `useReducer`                         |
-| 跨组件共享业务状态 | Zustand / Redux Toolkit / Jotai（按仓库实际选择） |
-| 服务端数据缓存     | React Query / SWR                                 |
-| URL 驱动状态       | 路由参数 / `useSearchParams`                      |
-| 表单状态           | React Hook Form / Formik                          |
+| Temporary UI state within the component | `useState` / `useReducer` |
+| Sharing business status across components | Zustand / Redux Toolkit / Jotai (actual selection by warehouse) |
+| Server-side data caching | React Query / SWR |
+| URL driver status | Route parameters / `useSearchParams` |
+| Form State | React Hook Form / Formik |
 
-### 核心原则
+### Core Principles
 
-- 就近管理：状态尽量放在最近的公共祖先
-- 单一数据源：同一份数据不要维护多份
-- 派生优于同步：可计算值优先在渲染期计算
-- 服务端数据优先交给请求库管理，不手动塞进全局 store
-- 不要因为“以后可能会用到”就把局部状态提前升级为全局状态
+- Proximity management: try to place the state on the nearest common ancestor
+-Single data source: Do not maintain multiple copies of the same data
+- Derived over synchronized: computable values are calculated first at render time
+- The server-side data is given priority to the request library management and is not manually inserted into the global store.
+- Don’t upgrade local state to global state in advance just because it “may be used in the future”
 
 ---
 
-## API 层规范
+## API layer specification
 
-### 设计原则
+### Design principles
 
-- 请求基础设施集中在 `services/`
-- 业务 API 按 feature 拆分，而不是全部堆在一个文件
-- 请求参数和响应结果都应有明确类型
-- 认证、错误格式化、通用拦截放在请求层统一处理
-- 页面和组件不要直接散落拼接请求细节
+- Request infrastructure is centralized in `services/`
+-Business APIs are split by feature instead of stacking them all in one file
+- Both request parameters and response results should have clear types
+- Authentication, error formatting, and universal interception are handled uniformly at the request layer
+- Do not directly scatter splicing request details on pages and components
 
-### 示例
+### Example
 
 ```ts
 // services/request.ts
@@ -215,23 +215,23 @@ export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
 
 ---
 
-## 错误处理
+## Error handling
 
-### 必须覆盖的状态
+### Status that must be overridden
 
 - Loading
 - Error
 - Empty
 - Data
 
-### 推荐做法
+### Recommended practices
 
-- 关键功能模块使用 Error Boundary 包裹，避免局部异常导致全页白屏
-- 异步请求失败时必须给用户可见反馈
-- 重要操作提供重试能力
-- 不要吞错，不写空 `catch`
+- Use Error Boundary to wrap key functional modules to avoid local exceptions causing a full-page white screen
+- Visible feedback must be given to the user when an asynchronous request fails
+- Provide retry capability for important operations
+- Don’t catch mistakes, don’t write empty `catch`
 
-### 示例（`react-error-boundary`，函数式 Fallback）
+### Example (`react-error-boundary`, functional Fallback)
 
 ```tsx
 import { ErrorBoundary } from "react-error-boundary";
@@ -243,9 +243,9 @@ function ModuleErrorFallback({
 }) {
   return (
     <div>
-      模块加载失败
+      Module loading failed
       <button type="button" onClick={resetErrorBoundary}>
-        重试
+        Try again
       </button>
     </div>
   );
@@ -262,15 +262,15 @@ export function UserDashboardSection() {
 
 ---
 
-## Suspense 与懒加载
+## Suspense and lazy loading
 
-适用场景：
+Applicable scenarios:
 
-- 路由级页面
-- 图表、富文本编辑器、地图、重型表格等大体积组件
-- 初始化成本较高的模块
+- Routing level page
+- Large components such as charts, rich text editors, maps, heavy tables, etc.
+- Modules with higher initialization costs
 
-示例：
+Example:
 
 ```tsx
 const HeavyChart = lazy(() => import("./components/HeavyChart"));
@@ -284,10 +284,10 @@ function Dashboard() {
 }
 ```
 
-建议：
+Suggestions:
 
-- 路由级优先 `lazy + Suspense`
-- `fallback` 优先使用 Skeleton 或更贴近内容的占位态，而不是纯 spinner
+- Route level priority `lazy + Suspense`
+- `fallback` gives priority to using Skeleton or a placeholder state closer to the content instead of a pure spinner
 
 ---
 

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

@@ -1,51 +1,54 @@
 ---
 name: fec-refactor-clean
-description: Use when safely removing dead frontend code, unused exports, stale components, obsolete routes, unused dependencies, or cleanup targets found by tools such as knip, depcheck, ts-prune, TypeScript, ESLint, or manual review. Do not use for feature rewrites that change behavior; Chinese triggers include 死代码, 清理未使用, refactor clean, 依赖清理, 删除无用代码.
+description: Use when safely removing dead frontend code, unused exports, stale components, obsolete routes, unused dependencies, or cleanup targets found by tools such as knip, depcheck, ts-prune, TypeScript, ESLint, or manual review. Do not use for feature rewrites that change behavior; Chinese triggers include dead code, clean up unused, refactor clean, dependency cleanup, delete useless code.
 ---
 
-# 重构清理
+# Refactoring and cleaning
 
 ## Purpose
 
-在验证保护下识别并清理无用前端代码，减少技术债，同时避免误删动态引用、路由入口、配置文件和运行时约定。
+Identify and clean up unused front-end code under validation protection, reducing technical debt while avoiding accidentally deleting dynamic references, routing entries, configuration files, and runtime conventions.
 
 ## Procedure
 
-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. 对技术债排序：优先清理有验证保护、影响开发效率或阻塞升级的项目；低证据的大范围重写只输出建议。
+1. Establish a baseline first: run or confirm the current status of lint, type-check, test, and build.
+2. Collect candidates:
+   - Prioritize the use of existing tools in the warehouse, such as knip, depcheck, ts-prune, eslint, and TypeScript.
+   - When tools are not available, use `rg` to check references, exports, routes, registration points and document entries.
+3. Classification by risk:
+   - SAFE: test fixtures, unreferenced tool functions, explicitly unexported private components.
+   - CAUTION: Shared components, feature entries, style files, Storybook stories.
+   - DANGER: routing, configuration, package scripts, runtime templates, dynamic import, plug-in metadata.
+   - UPGRADE: Expired dependencies, duplicate dependencies, unused dependencies and security alarms will be evaluated first for dependency upgrade or dependency cleanup, and will not be mixed with dead code deletion.
+4. Only SAFE items are automatically processed; CAUTION and DANGER need to output suggestions and evidence and are not deleted directly.
+5. Run the affected verification command after each batch cleanup.
+6. If the verification fails, stop expanding the cleaning scope and locate the batch first.
+7. Conduct behavioral equivalence review after cleaning: public APIs, routes, commands, templates, metadata, documentation examples, and report outputs can still be referenced.
+8. Sort technical debt: Prioritize projects that have verification protection, affect development efficiency, or block upgrades; only output suggestions for large-scale rewrites with low evidence.
 
 ## Frontend-Specific Checks
 
-- 检查 JSX/模板字符串、路由配置、barrel export、Storybook、测试、文档示例和动态组件注册。
-- 样式文件需检查 className、CSS Modules、Tailwind safelist、全局选择器和主题变量。
-- 依赖清理需检查构建插件、运行时模板、CLI scripts、monorepo 子包和 peer dependency。
+- Check JSX/template strings, route configuration, barrel export, Storybook, tests, documentation examples and dynamic component registration.
+- Style files need to check className, CSS Modules, Tailwind safelist, global selectors and theme variables.
+- Dependency cleanup checks build plugins, runtime templates, CLI scripts, monorepo subpackages, and peer dependencies.
 
 ## Constraints
 
-- 不改变用户可见行为。
-- 不删除无法证明无引用的公开 API、路由、模板或配置。
-- 不用“一次大删除”替代可验证的小批次清理。
-- 不把格式化、重命名或架构重写混入死代码清理。
-- 不用“看起来没人用”作为证据；必须有搜索、工具输出、类型错误消失或测试保护。
-- 不把依赖大版本升级伪装成清理；升级风险、release notes 和 lockfile 变更应分流到依赖升级工作流。
+- Does not change user-visible behavior.
+- Do not remove public APIs, routes, templates, or configurations that cannot be proven referenceless.
+- No "one big delete" replacement for verifiable small batch cleanups.
+- Don't mix formatting, renaming or schema rewriting into dead code cleanup.
+- No evidence that "no one seems to be using it" is needed; there must be search, tool output, type error disappearance, or test protection.
+- Don’t disguise major dependency version upgrades as cleanup; upgrade risks, release notes, and lockfile changes should be offloaded to the dependency upgrade workflow.
 
-## 详细参考
+## Detailed reference
 
-撰写清理报告时，加载 [references/report-template.md](references/report-template.md)。
+When writing a cleanup report, load [references/report-template.md](references/report-template.md).
 
 ## Expected Output
 
-- 清理报告保存为 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`。
-- 代码清理后相关验证命令通过，或明确说明阻塞原因。
+- Clean reports are saved as `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`.
+- After the code is cleaned, the relevant verification commands pass, or the cause of the blocking is clearly stated.
+## Structural Refactoring Boundary
+
+This workflow owns proven dead/unused code. When code is live but structurally difficult—long functions, ownership problems, mutable/derived data, conditionals, API shape, or hierarchy design—route it to structural refactoring instead of deleting or rewriting it under cleanup.