init

AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+本指南为在此仓库中工作的 AI 编码代理提供关键信息。
+
+## 项目结构
+
+```
+src/
+├── components/ui/    # shadcn/ui 组件（Base UI 基础组件）
+├── lib/              # 工具函数（cn() 函数用于 className 合并）
+├── modules/          # 应用模块（query client、basename）
+├── pages/            # 页面组件（默认导出）
+├── routes/           # TanStack Router 基于文件的路由
+├── styles/           # 全局样式、主题 CSS
+└── main.tsx          # 应用入口
+```
+
+
+## 代码风格指南
+
+### 模块目录结构
+
+每个新模块（如 `page-app`）应遵循以下结构：
+
+```
+pages/page-app/
+├── components/    # 模块专属组件
+├── hooks/         # 模块 React Query hooks（API 查询封装）
+├── modules/       # 模块功能函数（UI 组件、工具函数等）
+└── store/         # 模块状态管理（Zustand）
+```
+
+### hooks/ 文件夹说明
+
+每个模块的 `hooks/` 文件夹用于封装与该模块相关的 React Query hooks：
+
+- **use-api-query.ts**: 使用 `@tanstack/react-query` 的 `useQuery` 封装 API 调用
+  - 定义 `queryKeys` 常量用于缓存标识
+  - 封装 `useQuery` hooks 用于数据获取（GET 请求）
+  - 封装 `useMutation` hooks 用于数据修改（POST/PUT/DELETE 请求）
+  - 支持预取（prefetch）和无限滚动（infinite query）
+- **index.ts**: 导出模块所有 hooks，便于统一导入使用
+
+### 状态和数据获取
+
+- **@tanstack/react-query** 用于数据获取、缓存和状态管理
+  - 在模块的 `hooks/` 文件夹中封装 API 调用
+  - QueryClient 实例位于 `src/modules/query.ts`
+  - 在 `src/routes/__root.tsx` 中通过 `QueryClientProvider` 提供
+- **Zustand** 用于全局状态管理
+- **@kevisual/query** 用于底层 API 请求封装
+- **React Hook Form** 用于表单管理
+
+## 核心依赖
+
+- **@base-ui/react**: Headless UI 基础组件
+- **@tanstack/react-query**: 数据获取、缓存和状态管理（配合 hooks/ 使用）
+- **@tanstack/react-router**: 基于 TanStack Router 插件的文件路由
+- **class-variance-authority**: 基于变体的样式系统
+- **clsx + tailwind-merge**: 通过 `cn()` 提供 className 工具函数
+- **lucide-react**: 图标库
+- **react-hook-form**: 表单处理
+- **sonner**: Toast 通知
+- **zustand**: 状态管理
+- **tailwindcss v4**: 使用 @tailwindcss/vite 插件进行样式处理
+
+## 主题系统
+
+- **主题配色**: 采用黑白配色方案，提供简洁优雅的视觉体验
+- **主题模式**: 支持 light（浅色）和 dark（深色）模式切换
+- **主题实现**: 使用 `next-themes` 进行主题管理
+- **CSS 变量**: 主题相关的 CSS 变量定义在 `src/styles/theme.css` 中