docs: 将 AGENTS.md 全部翻译为简体中文

2026-05-15 11:49:33 +08:00
parent 5ab18fc612
commit edc367898f
1 changed files with 55 additions and 44 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,52 +1,52 @@
 # AGENTS.md

-You are an expert in JavaScript, Rsbuild, and web application development. You write maintainable, performant, and accessible code.
+你是 JavaScript、Rsbuild 和 Web 应用开发方面的专家，编写可维护、高性能且无障碍的代码。

-## Tech Stack
+## 技术栈

- **React 19** + **TypeScript** — frontend framework and type system
- **Rsbuild 2** — build tool (wraps Rspack), configured in `rsbuild.config.ts`
- **React Router v7** (`react-router`) — client-side routing
- **antd 6** + **@ant-design/icons 6** — UI component library and icon set
- **pnpm** — package manager
+- **React 19** + **TypeScript** — 前端框架和类型系统
+- **Rsbuild 2** — 构建工具（基于 Rspack），配置文件为 `rsbuild.config.ts`
+- **React Router v7**（`react-router`）— 客户端路由
+- **antd 6** + **@ant-design/icons 6** — UI 组件库和图标集
+- **pnpm** — 包管理器

-## Commands
+## 常用命令

- `pnpm run dev` - Start the dev server (auto-opens http://localhost:3000)
- `pnpm run build` - Build the app for production (output: `dist/`)
- `pnpm run preview` - Preview the production build locally
- `pnpm run lint` - Lint TypeScript/TSX files with ESLint
- `pnpm run format` - Format all files with Prettier
+- `pnpm run dev` — 启动开发服务器（自动打开 http://localhost:3000）
+- `pnpm run build` — 构建生产版本（输出至 `dist/`）
+- `pnpm run preview` — 本地预览生产构建
+- `pnpm run lint` — 使用 ESLint 检查 TypeScript/TSX 文件
+- `pnpm run format` — 使用 Prettier 格式化所有文件

-## Project Structure
+## 项目结构

 ```
 src/
-  index.tsx          # App entry point — mounts React root to #root
-  App.tsx            # Root component — renders <RouterProvider>
-  App.css            # Root component styles
-  router.tsx         # createBrowserRouter，由 routes 树自动生成
-  env.d.ts           # Rsbuild environment type declarations
+  index.tsx          # 应用入口，将 React 根节点挂载到 #root
+  App.tsx            # 根组件，渲染 <RouterProvider>
+  App.css            # 根组件样式
+  router.tsx         # createBrowserRouter，由路由树自动生成
+  env.d.ts           # Rsbuild 环境类型声明
  routes/
    types.ts         # RouteItem 类型定义
    index.tsx        # 路由树数据（唯一数据源），导出 routes / RouteItem
    utils.tsx        # toRouteObjects()：将路由树转为 React Router RouteObject[]
  layouts/
-    RootLayout.tsx   # Root layout with nav links and <Outlet />
+    RootLayout.tsx   # 根布局，包含导航链接和 <Outlet />
  pages/
-    Home.tsx         # "/" index page
-    About.tsx        # "/about" page
-    NotFound.tsx     # "*" catch-all 404 page
+    Home.tsx         # "/" 首页
+    About.tsx        # "/about" 关于页
+    NotFound.tsx     # "*" 兜底 404 页
 public/
  favicon.png
-rsbuild.config.ts  # Build configuration
-eslint.config.mjs  # ESLint flat config (TS/TSX only, dist/ ignored)
+rsbuild.config.ts  # 构建配置
+eslint.config.mjs  # ESLint 扁平配置（仅作用于 TS/TSX，忽略 dist/）
 tsconfig.json
 ```

-## Routing
+## 路由

-Uses **React Router v7** (`react-router`) with `createBrowserRouter`.
+使用 **React Router v7**（`react-router`）的 `createBrowserRouter`。

 - **唯一数据源**：`src/routes/index.tsx` 维护 `routes: RouteItem[]` 路由树
 - `RouteItem` 字段：`path` / `label` / `icon?` / `component?` / `hideInMenu?` / `redirect?` / `children?`
@@ -54,29 +54,40 @@ Uses **React Router v7** (`react-router`) with `createBrowserRouter`.
 - 菜单、面包屑等模块直接消费 `routes` 数组，无需重复维护路由信息
 - 添加新页面：在 `src/pages/` 创建组件，在 `src/routes/index.tsx` 追加节点即可

-## TypeScript Configuration
+## TypeScript 配置

- `noUnusedLocals` and `noUnusedParameters` are enabled — unused variables/parameters are errors
- `verbatimModuleSyntax` is enabled — type-only imports must use `import type`
- `moduleResolution: "bundler"` — use bundler-style module resolution
+- 已启用 `noUnusedLocals` 和 `noUnusedParameters`，未使用的变量/参数会报错
+- 已启用 `verbatimModuleSyntax`，纯类型导入必须使用 `import type`
+- `moduleResolution: "bundler"`，使用打包器风格的模块解析

-## Code Style
+## 代码风格

- **Single quotes** (`singleQuote: true` in `.prettierrc`)
- ESLint applies to `**/*.{ts,tsx}` only, with `react-hooks` and `react-refresh` plugins enabled
+- **单引号**（`.prettierrc` 中 `singleQuote: true`）
+- ESLint 仅作用于 `**/*.{ts,tsx}`，启用了 `react-hooks` 和 `react-refresh` 插件

-## UI Components (antd)
+## UI 组件规范（antd）

- Import components directly from `antd`, icons from `@ant-design/icons` — tree-shaking is automatic
- To customize the theme, wrap the app with `ConfigProvider` in `App.tsx`:
-  ```tsx
-  import { ConfigProvider } from 'antd';
-  <ConfigProvider theme={{ token: { colorPrimary: '#00b96b' } }}>
+**页面 UI 优先使用 antd 组件，不自行实现已有组件的功能。**
+
+- 从 `antd` 直接导入组件，从 `@ant-design/icons` 导入图标，自动 tree-shaking
+- 布局使用 `Layout`（`Header` / `Sider` / `Content` / `Footer`）
+- 导航使用 `Menu`，面包屑使用 `Breadcrumb`
+- 表单使用 `Form` + `Form.Item`，不使用原生 `<form>`
+- 按钮使用 `Button`，不使用原生 `<button>`
+- 弹窗使用 `Modal`，消息提示使用 `message` / `notification`
+- 数据展示使用 `Table` / `List` / `Descriptions` / `Card`
+- 空状态使用 `Empty`，加载状态使用 `Spin` / `Skeleton`
+- 404 页面使用 `Result status="404"`
+
+自定义主题通过 `ConfigProvider` 在 `App.tsx` 统一配置：
+```tsx
+import { ConfigProvider } from 'antd';
+<ConfigProvider theme={{ token: { colorPrimary: '#00b96b' } }}>
  <RouterProvider router={router} />
-  </ConfigProvider>
-  ```
+</ConfigProvider>
+```

-## Docs
+## 参考文档

 - Rsbuild: https://rsbuild.rs/llms.txt
 - Rspack: https://rspack.rs/llms.txt