code-graph/AGENTS.md

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 中