@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/skills/fec-legacy-to-modern-migration/references/migration-report-template.md

@@ -1,41 +1,41 @@
-# 迁移分析报告模板
+# Migration analysis report template
 
 ```markdown
-# 迁移分析报告
-
-> 生成时间: YYYY-MM-DD HH:mm
-> 评审工具: frontend-craft
-
-## 策略选择
-- 渐进式 / 一次性重写:
-- 理由:
-
-## 存量盘点
-- 页面数量:
-- 功能模块:
-- jQuery 插件:
-- 服务端模板:
-- API 调用方式:
-
-## 依赖关系
-- 共享 JS/CSS:
-- 跨页面逻辑:
-- 后端接口契约:
-
-## 迁移优先级
-- 第一批:
-- 第二批:
-- 暂缓:
-
-## 分阶段步骤
-- 阶段 0:
-- 阶段 1:
-- 阶段 2:
-- 阶段 3:
-
-## 风险与回滚
-- 风险:
-- 回滚方案:
+# Migration analysis report
+
+> Generation time: YYYY-MM-DD HH:mm
+> Review tool: frontend-craft
+
+## Strategy selection
+- Progressive/one-time rewrite:
+- Reason:
+
+## Inventory inventory
+- Number of pages:
+- Function modules:
+- jQuery plugin:
+- Server template:
+- API calling method:
+
+## Dependencies
+- Share JS/CSS:
+- Cross-page logic:
+- Backend interface contract:
+
+## Migration priority
+- First batch:
+- Second batch:
+- Suspension:
+
+## Phased steps
+- Stage 0:
+- Stage 1:
+- Stage 2:
+- Stage 3:
+
+## Risk and rollback
+- Risk:
+- Rollback plan:
 ```
 
-迁移分析或计划完成后，将报告保存到 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。
+After migration analysis or planning is completed, save the report to `reports/migration-plan-YYYY-MM-DD-HHmmss.md` and inform the user of the report path.

package/skills/fec-legacy-to-modern-migration/references/migration-strategy-and-mapping.md

@@ -0,0 +1,48 @@
+# Migration strategy and concept mapping
+
+## Migration strategy selection
+
+| Strategy | Applicability | Advantages | Risks |
+| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
+| **Progressive (Strangler Fig)** | Large-scale projects, requiring continuous delivery, and insufficient team familiarity | Risks are controllable, can be launched in batches, and can be rolled back | Old and new coexist for a long time, and two sets of codes need to be maintained |
+| **One-time rewrite** | Small and medium-sized projects, stable business, sufficient time window | Clear target architecture, no historical baggage | Long cycle, high pressure to go online, difficult rollback |
+
+**Recommendation**: Prioritize the incremental approach unless the project is small and the business is simple.
+
+## Concept mapping
+
+### jQuery → React
+
+| Legacy Patterns | React Correspondence |
+| ------------------------------------------ | -------------------------------------- |
+| `$(selector).html(content)` | Declarative JSX + state-driven rendering |
+| `$(document).on('click', '.btn', handler)` | `onClick` + event delegation is handled by React |
+| `$.ajax()` / `$.get()` | Project request layer, `fetch` / `axios`, can be connected to TanStack Query or SWR on demand |
+| Global variables/namespace storage state | Local state, Context or the existing store of the project can be used as needed Zustand/Redux |
+| `$(el).show()` / `$(el).hide()` | Conditional rendering `{visible && <Component />}` |
+| Manual DOM operations `append` / `remove` | Data-driven, triggering re-rendering through setState |
+| Template string concatenation HTML | JSX component + props |
+| Multiple pages + server-side routing | React Router client-side routing |
+
+### jQuery → Vue 3
+
+| Legacy Mode | Vue 3 Compatibility |
+| ------------------------------------------ | -------------------------------------------------- |
+| `$(selector).html(content)` | Template + `ref` / `reactive` driven rendering |
+| `$(document).on('click', '.btn', handler)` | `@click` + event modifier |
+| `$.ajax()` / `$.get()` | Project request layer, `fetch` / `axios`, can be connected to VueUse, Nuxt `useFetch` or TanStack Query Vue adapter as needed |
+| Global variables / Namespace storage state | `ref` / `reactive` / Pinia |
+| `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
+| Manual DOM manipulation | Data-driven, with responsive view updates |
+| Template string concatenation HTML | Single file component `<template>` + props |
+| Multiple pages + server-side routing | Vue Router client-side routing |
+
+### Universal mapping
+
+| Legacy Concepts | Modern Correspondence |
+| --------------------------------- | ------------------------------------------ |
+| Page-level JS entry (one script per page) | Routing/page entry + lazy loading module, or retain MPA entry and modernize packaging |
+| Public JS modules (utils, ajax packaging) | `services/`, `utils/`, typed API layer |
+| Inline styles / page-level CSS | Target project style system, such as CSS Modules, Tailwind, global style layering or component library styles |
+| Server-side template variables | Obtain via API, SSR/loader injection, or preserve server-side template boundaries and typed data |
+| Form submission + full page refresh | Form library + client verification + API call |

package/skills/fec-legacy-web-standard/SKILL.md

@@ -1,35 +1,35 @@
 ---
 name: fec-legacy-web-standard
-description: Use when maintaining or safely modifying existing non-framework frontend code: vanilla JavaScript, jQuery, HTML/CSS, MPA pages, server-rendered templates, legacy plugins, or long-lived code that should stay in its current stack. Use migration skill when planning a move to React/Vue/TypeScript; Chinese triggers include 传统前端, 原生 JS, jQuery.
+description: Use when maintaining or safely modifying existing non-framework frontend code: vanilla JavaScript, jQuery, HTML/CSS, MPA pages, server-rendered templates, legacy plugins, or long-lived code that should stay in its current stack. Use migration skill when planning a move to React/Vue/TypeScript; Chinese triggers include traditional frontend, native JS, jQuery.
 ---
 
-# 传统前端项目规范（JS + jQuery + HTML）
+# Traditional front-end project specifications (JS + jQuery + HTML)
 
 ## Purpose
 
-在不重写技术栈的前提下安全维护 vanilla JS、jQuery、HTML/CSS 和服务端模板项目。
+Safely maintain vanilla JS, jQuery, HTML/CSS and server-side template projects without rewriting the technology stack.
 
 ## Procedure
 
-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 和文件上传。
+1. First confirm whether this change is to maintain the old stack or migrate; switch to the modern migration workflow when migrating to React/Vue/TypeScript.
+2. Use the existing architecture and coding style, prioritize fixing problems, and do not introduce multiple modernizations in one change.
+3. JavaScript uses IIFE/namespace to reduce global pollution, and event binding is delegated to reasonable containers first.
+4. DOM updates cache selectors, batch operations, and escapes user input; Ajax must handle loading, error, empty status, and prevention of repeated submissions.
+5. HTML/CSS maintains semantics, label, alt, BEM/existing naming and low selector depth.
+6. Key security checks: `.html()`, `innerHTML`, URL parameter rendering, CSRF token and file upload.
 
-## 详细参考
+## Detailed reference
 
-涉及 jQuery 命名空间、事件绑定、Ajax、XSS 转义、文件组织和维护清单示例时，加载 [references/legacy-patterns.md](references/legacy-patterns.md)。
+Load [references/legacy-patterns.md](references/legacy-patterns.md) when it comes to jQuery namespaces, event binding, Ajax, XSS escaping, file organization, and maintenance checklist examples.
 
 ## Constraints
 
-- 在现有架构内改进，不要引入与项目格格不入的现代框架。
-- 渐进增强优于推倒重来。
-- 禁止用 `innerHTML` / `.html()` 直接插入用户输入。
-- 避免全局变量污染。
-- 每次聚焦一个维护点，避免顺手重构整个模块。
+- Improve within the existing architecture and do not introduce modern frameworks that are incompatible with the project.
+- Progressive enhancement is better than reinventing the wheel.
+- Disable using `innerHTML` / `.html()` to directly insert user input.
+- Avoid global variable pollution.
+- Focus on one maintenance point at a time to avoid rebuilding the entire module.
 
 ## Expected Output
 
-改动与旧项目风格一致，无全局变量泄漏，事件和 DOM 操作可维护，Ajax 状态完整，用户输入已转义，渐进改进不破坏现有功能。
+The changes are consistent with the style of the old project, no global variables are leaked, events and DOM operations are maintainable, Ajax state is intact, user input has been escaped, and incremental improvements do not destroy existing functionality.

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

@@ -1,6 +1,6 @@
-# 传统前端维护模式
+# Traditional front-end maintenance mode
 
-## 命名空间
+## Namespace
 
 ```javascript
 var App = App || {};
@@ -20,12 +20,12 @@ App.UserModule = (function ($) {
 })(jQuery);
 ```
 
-## 事件与 DOM
+## Events and DOM
 
-- 事件触发元素用 `.js-*` class，与样式 class 分离。
-- 缓存频繁使用的选择器。
-- 批量 DOM 操作用 `DocumentFragment` 或一次性插入。
-- 页面卸载或模块销毁时解绑事件或调用插件 destroy。
+- Event triggering elements use `.js-*` classes, separated from style classes.
+- Cache frequently used selectors.
+- Batch DOM manipulation with `DocumentFragment` or one-time insertion.
+- Unbind the event or call the plug-in destroy when the page is unloaded or the module is destroyed.
 
 ## Ajax
 
@@ -42,7 +42,7 @@ function fetchUserList(params) {
       else showError(res.message);
     })
     .fail(function () {
-      showError("网络错误，请稍后重试");
+      showError("Network error, please try again later");
     })
     .always(function () {
       hideLoading();
@@ -50,7 +50,7 @@ function fetchUserList(params) {
 }
 ```
 
-## XSS 转义
+## XSS escaping
 
 ```javascript
 $(".username").text(userData.name);
@@ -62,7 +62,7 @@ function escapeHtml(str) {
 }
 ```
 
-## 文件组织
+## File organization
 
 ```text
 project/
@@ -76,10 +76,10 @@ project/
 └── pages/
 ```
 
-## 检查清单
+## Checklist
 
-- 没有全局变量泄漏。
-- 事件绑定在合理容器上。
-- Ajax 处理 loading/error/empty。
-- 用户输入已转义。
-- 未扩大第三方库或框架依赖。
+- No global variables leaked.
+- Events are bound to reasonable containers.
+- Ajax handling loading/error/empty.
+- User input is escaped.
+- No third-party library or framework dependencies have been expanded.

package/skills/fec-list-virtualization/SKILL.md

@@ -1,34 +1,34 @@
 ---
 name: fec-list-virtualization
-description: Use when optimizing or reviewing large lists, virtual scrolling, windowing, react-window, TanStack Virtual, variable-height rows, dynamic measurement, infinite scroll, grid virtualization, or scroll performance; Chinese triggers include 虚拟列表, 大列表优化, 滚动性能.
+description: Use when optimizing or reviewing large lists, virtual scrolling, windowing, react-window, TanStack Virtual, variable-height rows, dynamic measurement, infinite scroll, grid virtualization, or scroll performance; Chinese triggers include virtual lists, large list optimization, scroll performance.
 ---
 
-# 列表虚拟化优化
+# List virtualization optimization
 
 ## Purpose
 
-通过窗口化只渲染可视区域，解决大列表 DOM 过多和滚动卡顿。
+Only the visible area is rendered through windowing, which solves the problem of excessive DOM and stuck scrolling in large lists.
 
 ## Procedure
 
-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 限制。
+1. First confirm the list size and bottleneck: 500+ items, scrolling frame drops, too many DOM nodes, or memory surge before introducing virtualization.
+2. First follow the existing framework, dependencies and design system constraints of the project, and then select the library according to the scenario: React can consider `react-window` or TanStack Virtual; Vue/Solid/Svelte, dynamic measurement, grid or cross-framework scenarios give priority to TanStack Virtual; the legacy `react-virtualized` is only maintained and not added.
+3. Clarify item size, overscan, container height, key, rolling container and resize behavior.
+4. Separate data paging and DOM virtualization during infinite scrolling; data acquisition can be combined with the data acquisition workflow.
+5. Verify DOM node count, scrolling FPS, keyboard/screen reader experience, and Ctrl+F/SEO limitations.
 
-## 详细参考
+## Detailed reference
 
-涉及是否需要虚拟化、库选型、固定高度、可变/动态高度、无限滚动、网格虚拟化和性能注意事项时，加载 [references/virtualization-patterns.md](references/virtualization-patterns.md)。
+Load [references/virtualization-patterns.md](references/virtualization-patterns.md) when it comes to the need for virtualization, library selection, fixed height, variable/dynamic height, infinite scrolling, grid virtualization, and performance considerations.
 
 ## Constraints
 
-- SEO 关键内容不要只存在于虚拟项中。
-- 浏览器原生 Ctrl+F 无法搜索未挂载项目。
-- Row 根元素必须透传虚拟库提供的 style/measure ref。
-- overscan 过大会浪费内存，过小会白屏。
-- 动态高度测量要处理 ResizeObserver 和布局抖动。
+- SEO key content doesn’t exist only in dummy items.
+- Browser native Ctrl+F cannot search for unmounted items.
+- The Row root element must transparently transmit the style/measure ref provided by the virtual library.
+- If overscan is too high, memory will be wasted; if overscan is too low, the screen will be white.
+- Dynamic height measurement to handle ResizeObserver and layout jitter.
 
 ## Expected Output
 
-10000+ 项列表滚动接近 60fps，DOM 节点数稳定在可视区域及缓冲区范围，内存从 O(n) 降至 O(visible)。
+The scrolling of the 10,000+ item list is close to 60fps, the number of DOM nodes is stable within the visible area and buffer range, and the memory is reduced from O(n) to O(visible).

package/skills/fec-list-virtualization/references/virtualization-patterns.md

@@ -1,34 +1,34 @@
-# 虚拟列表模式
+# Virtual list mode
 
-## 先判断是否需要虚拟化
+## First determine whether virtualization is required
 
-- 只有列表规模、渲染成本或滚动性能已经形成瓶颈时才引入虚拟化；小列表、轻量静态列表和分页后可控的列表不需要。
-- SEO 关键内容、依赖浏览器原生 Ctrl+F 的全文内容、需要一次性打印/导出的内容，不要只存在于虚拟项中。
-- 虚拟化只减少 DOM 渲染成本，不替代数据分页、接口缓存、图片懒加载或复杂行组件的渲染优化。
+- Introduce virtualization only when list size, rendering cost, or scrolling performance have become a bottleneck; not required for small lists, lightweight static lists, and controllable lists after paging.
+- SEO-critical content, full-text content that relies on the browser's native Ctrl+F, and content that needs to be printed/exported once, do not exist only in virtual items.
+- Virtualization only reduces DOM rendering costs and does not replace data paging, interface caching, lazy loading of images, or rendering optimization of complex row components.
 
-## 选型参考
+## Selection reference
 
-先沿用项目已有虚拟列表库和框架约定；新增依赖时再按场景选择。
+First, use the existing virtual list library and framework conventions of the project; when adding new dependencies, select them according to the scenario.
 
-| 场景 | 候选方案 | 注意点 |
+| Scenarios | Alternative solutions | Notes |
 | --- | --- | --- |
-| 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` 项目 | 维护现有实现 | 不建议新功能继续扩散；大改时评估迁移成本。 |
+| React fixed-height list | `react-window` or TanStack Virtual | `react-window` is lightweight and stable; TanStack Virtual is more suitable for unifying complex scenes. |
+| React Variable Height List | `VariableSizeList` of `react-window` or TanStack Virtual | Both are available when the height can be calculated; measurement and reset are required when the real height of the content changes. |
+| Dynamic measurement, chat flow, expanded rows | TanStack Virtual | Works with `measureElement` / ResizeObserver to handle layout jitter and scroll anchor points. |
+| Vue / Solid / Svelte / Cross-framework | TanStack Virtual or the project's existing ecological library | Do not introduce React-only virtual list libraries for non-React projects. |
+| Two-dimensional grid, table, column virtualization | TanStack Virtual row/column Dual-axis solution or existing table library virtualization capability | Fixed columns, sticky headers and keyboard navigation need to be verified separately. |
+| Legacy `react-virtualized` project | Maintain existing implementation | It is not recommended that new features continue to spread; evaluate migration costs when making major changes. |
 
-## 通用实现原则
+## General implementation principles
 
-- 容器高度必须稳定，滚动容器必须明确，item key 必须来自稳定业务标识。
-- 行根元素必须透传虚拟库提供的 `style`、定位属性和测量 ref。
-- `overscan` 按设备和行渲染成本调节：过小会白屏，过大会接近全量渲染。
-- 动态高度需要估算高度、真实测量、resize 更新和滚动锚点策略。
-- 无限滚动要分离“数据分页”和“DOM 虚拟化”；不要在 render 阶段无条件触发请求。
-- 验证键盘导航、屏幕阅读器语义、焦点保持、滚动恢复、空态/加载态和错误态。
+- The container height must be stable, the rolling container must be clear, and the item key must come from a stable business identity.
+- The row root element must transparently pass the `style`, positioning attributes and measurement ref provided by the virtual library.
+- `overscan` adjusts the rendering cost by device and row: if it is too small, the screen will be white, if it is too large, it will be close to full rendering.
+- Dynamic height requires estimated height, real measurements, resize updates and scroll anchor strategy.
+- Infinite scrolling must separate "data paging" and "DOM virtualization"; do not trigger requests unconditionally in the render phase.
+- Validate keyboard navigation, screen reader semantics, focus maintenance, scroll recovery, empty/loading states, and error states.
 
-## React 固定高度示例
+## React fixed height example
 
 ```tsx
 import { FixedSizeList as List } from "react-window";
@@ -44,7 +44,7 @@ export const UserList = ({ users }: { users: User[] }) => (
 );
 ```
 
-## React 可变高度示例
+## React variable height example
 
 ```tsx
 import { VariableSizeList as List } from "react-window";
@@ -56,7 +56,7 @@ const getItemSize = (index: number) => (items[index].hasSummary ? 120 : 60);
 </List>;
 ```
 
-## TanStack Virtual 动态高度示例
+## TanStack Virtual dynamic height example
 
 ```tsx
 const virtualizer = useVirtualizer({
@@ -67,14 +67,14 @@ const virtualizer = useVirtualizer({
 });
 ```
 
-动态内容需要测量元素并处理 ResizeObserver；Vue/Solid/Svelte 项目使用 TanStack Virtual 对应框架 adapter，核心选项保持一致。
+Dynamic content requires measuring elements and processing ResizeObserver; Vue/Solid/Svelte projects use the TanStack Virtual corresponding framework adapter, and the core options remain the same.
 
-## 无限滚动
+## infinite scroll
 
-- `count` 包含 loader 占位项。
-- 最后一个虚拟项进入视口时调用 `fetchNextPage()`。
-- 不要在 render 中无条件触发请求，使用 effect 或明确状态保护。
+- `count` contains loader placeholders.
+- `fetchNextPage()` is called when the last virtual item enters the viewport.
+- Do not trigger requests unconditionally in render, use effects or explicit state protection.
 
-## 网格虚拟化
+## Grid virtualization
 
-二维网格使用 `FixedSizeGrid` 或 TanStack Virtual 的 row/column 双轴方案，确保单元格 style 透传。
+The two-dimensional grid uses `FixedSizeGrid` or TanStack Virtual's row/column dual-axis solution to ensure that the cell style is transparently transmitted.

package/skills/fec-monorepo-project-standard/SKILL.md

@@ -1,58 +1,58 @@
 ---
 name: fec-monorepo-project-standard
-description: Use when creating, reviewing, or restructuring frontend monorepos with pnpm workspace, Turborepo, Nx, multi-package dependency boundaries, task orchestration, package naming, or package publishing; Chinese triggers include monorepo, workspace, 多包.
+description: Use when creating, reviewing, or restructuring frontend monorepos with pnpm workspace, Turborepo, Nx, multi-package dependency boundaries, task orchestration, package naming, or package publishing; Chinese triggers include monorepo, workspace, multi-package.
 ---
 
-# Monorepo 项目规范
+# Monorepo Project Specifications
 
-适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。
+For multi-package front-end repositories using pnpm workspace, Turborepo or Nx.
 
 ## Purpose
 
-规范 Monorepo 项目的目录结构、依赖管理、任务编排和包发布流程，确保多包协作的构建效率和版本一致性。
+Standardize the directory structure, dependency management, task orchestration and package release process of the Monorepo project to ensure the build efficiency and version consistency of multi-package collaboration.
 
 ## Procedure
 
-1. 先确认仓库是否已使用 pnpm workspace、Turborepo 或 Nx，并沿用现有包命名与任务约定。
-2. 将应用放在 `apps/`，共享库、配置和工具放在 `packages/` 或既有等价目录。
-3. 内部依赖使用 `workspace:*`，通过依赖图驱动构建顺序。
-4. 为 build、lint、test 配置可缓存、可并行、可增量的根任务，并明确输入、输出和环境变量。
-5. 在 Turborepo/Nx 中配置 affected/changed 范围命令，CI 优先跑受影响包，同时保留主干全量验证入口。
-6. 发布包前检查包边界、循环依赖、exports、peer dependencies 和版本策略。
+1. First confirm whether the repository has used pnpm workspace, Turborepo or Nx, and continue to use the existing package naming and task conventions.
+2. Place applications in `apps/` and shared libraries, configuration and tools in `packages/` or existing equivalent directories.
+3. Internal dependencies use `workspace:*` to drive the build sequence through the dependency graph.
+4. Configure cacheable, parallelizable, and incremental root tasks for build, lint, and test, and specify input, output, and environment variables.
+5. Configure the affected/changed range command in Turborepo/Nx. CI will run the affected packages first while retaining the backbone full verification entry.
+6. Check package boundaries, circular dependencies, exports, peer dependencies and version policies before publishing the package.
 
-## 工具选择
+## Tool selection
 
-| 工具               | 适用 | 特点                       |
+| Tools | Applicability | Features |
 | ------------------ | ---- | -------------------------- |
-| **pnpm workspace** | 基础 | 依赖提升、链接、脚本聚合   |
-| **Turborepo**      | 推荐 | 缓存、并行、依赖图         |
-| **Nx**             | 大型 | 增量构建、云缓存、插件生态 |
+| **pnpm workspace** | Basics | Dependency promotion, linking, script aggregation |
+| **Turborepo** | Recommended | Caching, parallelism, dependency graph |
+| **Nx** | Large | Incremental build, cloud cache, plug-in ecology |
 
-## 目录结构
+## Directory structure
 
 ### pnpm + Turborepo
 
 ```
-├── package.json                # 根 package，workspace 配置
-├── pnpm-workspace.yaml         # workspace 包列表
-├── turbo.json                  # Turborepo 配置
+├── package.json # Root package, workspace configuration
+├── pnpm-workspace.yaml # workspace package list
+├── turbo.json # Turborepo configuration
 │
 ├── apps/
-│   ├── web/                    # 主应用
+│ ├── web/ # Main application
 │   │   ├── package.json
 │   │   └── ...
-│   ├── admin/                  # 管理后台
-│   └── docs/                   # 文档站
+│ ├── admin/ # Management background
+│ └── docs/ # Documentation site
 │
 ├── packages/
-│   ├── ui/                     # 共享 UI 组件
+│ ├── ui/ # Shared UI components
 │   │   ├── package.json
 │   │   └── src/
-│   ├── utils/                  # 工具函数
-│   ├── config-eslint/         # 共享 ESLint 配置
-│   └── config-typescript/     # 共享 TS 配置
+│ ├── utils/ # Utility function
+│ ├── config-eslint/ # Shared ESLint configuration
+│ └── config-typescript/ # Shared TS configuration
 │
-└── tooling/                    # 构建/测试工具（可选）
+└── tooling/ # Build/test tools (optional)
     └── scripts/
 ```
 
@@ -64,11 +64,11 @@ packages:
   - "packages/*"
 ```
 
-## 依赖管理
+## Dependency management
 
-- 内部包使用 `workspace:*` 协议
-- 根 `package.json` 统一部分依赖版本，子包可覆盖
-- 禁止循环依赖，通过 `pnpm why` 检查
+- Internal packages use the `workspace:*` protocol
+- The root `package.json` unifies some dependency versions and can be overridden by sub-packages
+- Disable circular dependencies, check via `pnpm why`
 
 ```json
 {
@@ -79,7 +79,7 @@ packages:
 }
 ```
 
-## Turborepo 任务编排
+## Turborepo task orchestration
 
 ```json
 {
@@ -99,12 +99,12 @@ packages:
 }
 ```
 
-- `^build` 表示先执行依赖包的 build
-- `outputs` 用于缓存命中判断
-- `inputs` 应包含源码、配置、锁文件和环境相关文件；不要把 `.env` secret 值写入缓存 key
-- 远程缓存要区分可信 CI 与本地开发，避免把含敏感信息的产物上传
+- `^build` means executing the build of dependent packages first
+- `outputs` is used for cache hit judgment
+- `inputs` should include source code, configuration, lock files and environment-related files; do not write the `.env` secret value into the cache key
+- Remote caching should distinguish between trusted CI and local development to avoid uploading products containing sensitive information.
 
-## Nx 任务编排
+## Nx task orchestration
 
 ```json
 {
@@ -118,25 +118,25 @@ packages:
 }
 ```
 
-## 包命名
+## Package naming
 
-- 内部包：`@org/package-name` 或 `@repo/package-name`
-- 发布到 npm：遵循 `@scope/name` 规范
+- Internal package: `@org/package-name` or `@repo/package-name`
+- Publish to npm: follow the `@scope/name` specification
 
 ## Constraints
 
-- 子包之间通过 `workspace:*` 引用，不发布到 npm 再安装
-- 共享配置（ESLint、TS）放在 `packages/config-*`，子包 extends
-- 构建顺序由依赖图决定，不手动指定无关依赖
-- 根目录执行 `pnpm -r build` 或 `turbo run build` 时，所有包按序构建
-- 禁止循环依赖，新增包时通过 `pnpm why` 检查依赖链
-- CI cache 只缓存依赖安装目录和任务产物，不缓存未验证的构建状态
-- affected 构建不能替代发布前全量验证；主干或 release 分支仍需完整质量门禁
+- Sub-packages are referenced through `workspace:*` and are not published to npm and then installed.
+- Shared configurations (ESLint, TS) are placed in `packages/config-*`, and sub-packages extend
+- The build order is determined by the dependency graph, without manually specifying irrelevant dependencies
+- When executing `pnpm -r build` or `turbo run build` in the root directory, all packages will be built in order
+- Disable circular dependencies, use `pnpm why` to check the dependency chain when adding a new package
+- CI cache only caches dependent installation directories and task products, and does not cache unverified build status
+- Affected builds cannot replace full verification before release; the trunk or release branch still requires complete quality control
 
 ## Expected Output
 
-- Monorepo 目录结构清晰（`apps/` 应用、`packages/` 共享包、`tooling/` 工具）
-- `pnpm-workspace.yaml` 和 `turbo.json` / `nx.json` 配置正确
-- 内部包使用 `workspace:*` 协议，无循环依赖
-- 构建、lint、test 任务可通过根命令一键执行，缓存命中率高
-- CI 能区分 affected 快速反馈和 release 全量验证，缓存配置不会泄露密钥或隐藏依赖边界问题
+- Monorepo directory structure is clear (`apps/` applications, `packages/` shared packages, `tooling/` tools)
+- `pnpm-workspace.yaml` and `turbo.json` / `nx.json` are configured correctly
+- Internal packages use `workspace:*` protocol, no circular dependencies
+- Build, lint, and test tasks can be executed with one click through the root command, and the cache hit rate is high
+- CI can distinguish between affected quick feedback and release full verification, and the cache configuration will not leak keys or hide dependency boundary issues