|
1 | 1 | # CLAUDE.md |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## Project Overview |
6 | | - |
7 | | -FastGPT is an AI Agent construction platform providing out-of-the-box data processing, model invocation capabilities, and visual workflow orchestration through Flow. This is a full-stack TypeScript application built on NextJS with MongoDB/PostgreSQL backends. |
8 | | - |
9 | | -**Tech Stack**: NextJS + TypeScript + ChakraUI + MongoDB + PostgreSQL (PG Vector)/Milvus |
10 | | - |
11 | | -## Architecture |
12 | | - |
13 | | -This is a monorepo using pnpm workspaces with the following key structure: |
14 | | - |
15 | | -### Packages (Library Code) |
16 | | -- `packages/global/` - Shared types, constants, utilities used across all projects |
17 | | -- `packages/service/` - Backend services, database schemas, API controllers, workflow engine |
18 | | -- `packages/web/` - Shared frontend components, hooks, styles, i18n |
19 | | -- `packages/templates/` - Application templates for the template market |
20 | | - |
21 | | -### Projects (Applications) |
22 | | -- `projects/app/` - Main NextJS web application (frontend + API routes) |
23 | | -- `projects/sandbox/` - NestJS code execution sandbox service |
24 | | -- `projects/mcp_server/` - Model Context Protocol server implementation |
25 | | - |
26 | | -### Key Directories |
27 | | -- `document/` - Documentation site (NextJS app with content) |
28 | | -- `plugins/` - External plugins (models, crawlers, etc.) |
29 | | -- `deploy/` - Docker and Helm deployment configurations |
30 | | -- `test/` - Centralized test files and utilities |
31 | | - |
32 | | -## Development Commands |
33 | | - |
34 | | -### Main Commands (run from project root) |
35 | | -- `pnpm dev` - Start development for all projects (uses package.json workspace scripts) |
36 | | -- `pnpm build` - Build all projects |
37 | | -- `pnpm test` - Run tests using Vitest |
38 | | -- `pnpm test:workflow` - Run workflow-specific tests |
39 | | -- `pnpm lint` - Run ESLint across all TypeScript files with auto-fix |
40 | | -- `pnpm format-code` - Format code using Prettier |
41 | | - |
42 | | -### Project-Specific Commands |
43 | | -**Main App (projects/app/)**: |
44 | | -- `cd projects/app && pnpm dev` - Start NextJS dev server |
45 | | -- `cd projects/app && pnpm build` - Build NextJS app |
46 | | -- `cd projects/app && pnpm start` - Start production server |
47 | | - |
48 | | -**Sandbox (projects/sandbox/)**: |
49 | | -- `cd projects/sandbox && pnpm dev` - Start NestJS dev server with watch mode |
50 | | -- `cd projects/sandbox && pnpm build` - Build NestJS app |
51 | | -- `cd projects/sandbox && pnpm test` - Run Jest tests |
52 | | - |
53 | | -**MCP Server (projects/mcp_server/)**: |
54 | | -- `cd projects/mcp_server && bun dev` - Start with Bun in watch mode |
55 | | -- `cd projects/mcp_server && bun build` - Build MCP server |
56 | | -- `cd projects/mcp_server && bun start` - Start MCP server |
57 | | - |
58 | | -### Utility Commands |
59 | | -- `pnpm create:i18n` - Generate i18n translation files |
60 | | -- `pnpm api:gen` - Generate OpenAPI documentation |
61 | | -- `pnpm initIcon` - Initialize icon assets |
62 | | -- `pnpm gen:theme-typings` - Generate Chakra UI theme typings |
63 | | - |
64 | | -## Testing |
65 | | - |
66 | | -The project uses Vitest for testing with coverage reporting. Key test commands: |
67 | | -- `pnpm test` - Run all tests |
68 | | -- `pnpm test:workflow` - Run workflow tests specifically |
69 | | -- Test files are located in `test/` directory and `projects/app/test/` |
70 | | -- Coverage reports are generated in `coverage/` directory |
71 | | - |
72 | | -## Code Organization Patterns |
73 | | - |
74 | | -### Monorepo Structure |
75 | | -- Shared code lives in `packages/` and is imported using workspace references |
76 | | -- Each project in `projects/` is a standalone application |
77 | | -- Use `@fastgpt/global`, `@fastgpt/service`, `@fastgpt/web` imports for shared packages |
78 | | - |
79 | | -### API Structure |
80 | | -- NextJS API routes in `projects/app/src/pages/api/` |
81 | | -- Core business logic in `packages/service/core/` |
82 | | -- Database schemas in `packages/service/` with MongoDB/Mongoose |
83 | | - |
84 | | -### Frontend Architecture |
85 | | -- React components in `projects/app/src/components/` and `packages/web/components/` |
86 | | -- Chakra UI for styling with custom theme in `packages/web/styles/theme.ts` |
87 | | -- i18n support with files in `packages/web/i18n/` |
88 | | -- State management using React Context and Zustand |
89 | | - |
90 | | -### Workflow System |
91 | | -- Visual workflow editor using ReactFlow |
92 | | -- Workflow engine in `packages/service/core/workflow/` |
93 | | -- Node definitions in `packages/global/core/workflow/template/` |
94 | | -- Dispatch system for executing workflow nodes |
95 | | - |
96 | | -## Development Notes |
97 | | - |
98 | | -- **Package Manager**: Uses pnpm with workspace configuration |
99 | | -- **Node Version**: Requires Node.js >=18.16.0, pnpm >=9.0.0 |
100 | | -- **Database**: Supports MongoDB, PostgreSQL with pgvector, or Milvus for vector storage |
101 | | -- **AI Integration**: Supports multiple AI providers through unified interface |
102 | | -- **Internationalization**: Full i18n support for Chinese, English, and Japanese |
103 | | - |
104 | | -## Key File Patterns |
105 | | - |
106 | | -- `.ts` and `.tsx` files use TypeScript throughout |
107 | | -- Database schemas use Mongoose with TypeScript |
108 | | -- API routes follow NextJS conventions |
109 | | -- Component files use React functional components with hooks |
110 | | -- Shared types defined in `packages/global/` with `.d.ts` files |
111 | | - |
112 | | -## Environment Configuration |
113 | | - |
114 | | -- Configuration files in `projects/app/data/config.json` |
115 | | -- Environment-specific configs supported |
116 | | -- Model configurations in `packages/service/core/ai/config/` |
| 3 | +本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指导说明。 |
| 4 | + |
| 5 | +## 语言 |
| 6 | + |
| 7 | +中文 |
| 8 | + |
| 9 | +## 项目概述 |
| 10 | + |
| 11 | +FastGPT 是一个 AI Agent 构建平台,通过 Flow 提供开箱即用的数据处理、模型调用能力和可视化工作流编排。这是一个基于 NextJS 构建的全栈 TypeScript 应用,后端使用 MongoDB/PostgreSQL。 |
| 12 | + |
| 13 | +**技术栈**: NextJS + TypeScript + ChakraUI + MongoDB + PostgreSQL (PG Vector)/Milvus |
| 14 | + |
| 15 | +## 架构 |
| 16 | + |
| 17 | +这是一个使用 pnpm workspaces 的 monorepo,主要结构如下: |
| 18 | + |
| 19 | +### Packages (库代码) |
| 20 | +- `packages/global/` - 所有项目共享的类型、常量、工具函数 |
| 21 | +- `packages/service/` - 后端服务、数据库模型、API 控制器、工作流引擎 |
| 22 | +- `packages/web/` - 共享的前端组件、hooks、样式、国际化 |
| 23 | +- `packages/templates/` - 模板市场的应用模板 |
| 24 | + |
| 25 | +### Projects (应用程序) |
| 26 | +- `projects/app/` - 主 NextJS Web 应用(前端 + API 路由) |
| 27 | +- `projects/sandbox/` - NestJS 代码执行沙箱服务 |
| 28 | +- `projects/mcp_server/` - Model Context Protocol 服务器实现 |
| 29 | + |
| 30 | +### 关键目录 |
| 31 | +- `document/` - 文档站点(NextJS 应用及内容) |
| 32 | +- `plugins/` - 外部插件(模型、爬虫等) |
| 33 | +- `deploy/` - Docker 和 Helm 部署配置 |
| 34 | +- `test/` - 集中的测试文件和工具 |
| 35 | + |
| 36 | +## 开发命令 |
| 37 | + |
| 38 | +### 主要命令(从项目根目录运行) |
| 39 | +- `pnpm dev` - 启动所有项目的开发环境(使用 package.json 的 workspace 脚本) |
| 40 | +- `pnpm build` - 构建所有项目 |
| 41 | +- `pnpm test` - 使用 Vitest 运行测试 |
| 42 | +- `pnpm test:workflow` - 运行工作流相关测试 |
| 43 | +- `pnpm lint` - 对所有 TypeScript 文件运行 ESLint 并自动修复 |
| 44 | +- `pnpm format-code` - 使用 Prettier 格式化代码 |
| 45 | + |
| 46 | +### 项目专用命令 |
| 47 | +**主应用 (projects/app/)**: |
| 48 | +- `cd projects/app && pnpm dev` - 启动 NextJS 开发服务器 |
| 49 | +- `cd projects/app && pnpm build` - 构建 NextJS 应用 |
| 50 | +- `cd projects/app && pnpm start` - 启动生产服务器 |
| 51 | + |
| 52 | +**沙箱 (projects/sandbox/)**: |
| 53 | +- `cd projects/sandbox && pnpm dev` - 以监视模式启动 NestJS 开发服务器 |
| 54 | +- `cd projects/sandbox && pnpm build` - 构建 NestJS 应用 |
| 55 | +- `cd projects/sandbox && pnpm test` - 运行 Jest 测试 |
| 56 | + |
| 57 | +**MCP 服务器 (projects/mcp_server/)**: |
| 58 | +- `cd projects/mcp_server && bun dev` - 使用 Bun 以监视模式启动 |
| 59 | +- `cd projects/mcp_server && bun build` - 构建 MCP 服务器 |
| 60 | +- `cd projects/mcp_server && bun start` - 启动 MCP 服务器 |
| 61 | + |
| 62 | +### 工具命令 |
| 63 | +- `pnpm create:i18n` - 生成国际化翻译文件 |
| 64 | +- `pnpm api:gen` - 生成 OpenAPI 文档 |
| 65 | +- `pnpm initIcon` - 初始化图标资源 |
| 66 | +- `pnpm gen:theme-typings` - 生成 Chakra UI 主题类型定义 |
| 67 | + |
| 68 | +## 测试 |
| 69 | + |
| 70 | +项目使用 Vitest 进行测试并生成覆盖率报告。主要测试命令: |
| 71 | +- `pnpm test` - 运行所有测试 |
| 72 | +- `pnpm test:workflow` - 专门运行工作流测试 |
| 73 | +- 测试文件位于 `test/` 目录和 `projects/app/test/` |
| 74 | +- 覆盖率报告生成在 `coverage/` 目录 |
| 75 | + |
| 76 | +## 代码组织模式 |
| 77 | + |
| 78 | +### Monorepo 结构 |
| 79 | +- 共享代码存放在 `packages/` 中,通过 workspace 引用导入 |
| 80 | +- `projects/` 中的每个项目都是独立的应用程序 |
| 81 | +- 使用 `@fastgpt/global`、`@fastgpt/service`、`@fastgpt/web` 导入共享包 |
| 82 | + |
| 83 | +### API 结构 |
| 84 | +- NextJS API 路由在 `projects/app/src/pages/api/` |
| 85 | +- 核心业务逻辑在 `packages/service/core/` |
| 86 | +- 数据库模型在 `packages/service/` 中,使用 MongoDB/Mongoose |
| 87 | + |
| 88 | +### 前端架构 |
| 89 | +- React 组件在 `projects/app/src/components/` 和 `packages/web/components/` |
| 90 | +- 使用 Chakra UI 进行样式设计,自定义主题在 `packages/web/styles/theme.ts` |
| 91 | +- 国际化支持文件在 `packages/web/i18n/` |
| 92 | +- 使用 React Context 和 Zustand 进行状态管理 |
| 93 | + |
| 94 | +### 工作流系统 |
| 95 | +- 使用 ReactFlow 的可视化工作流编辑器 |
| 96 | +- 工作流引擎在 `packages/service/core/workflow/` |
| 97 | +- 节点定义在 `packages/global/core/workflow/template/` |
| 98 | +- 用于执行工作流节点的调度系统 |
| 99 | + |
| 100 | +## 开发注意事项 |
| 101 | + |
| 102 | +- **包管理器**: 使用 pnpm 及 workspace 配置 |
| 103 | +- **Node 版本**: 需要 Node.js >=18.16.0, pnpm >=9.0.0 |
| 104 | +- **数据库**: 支持 MongoDB、带 pgvector 的 PostgreSQL 或 Milvus 向量存储 |
| 105 | +- **AI 集成**: 通过统一接口支持多个 AI 提供商 |
| 106 | +- **国际化**: 完整支持中文、英文和日文 |
| 107 | + |
| 108 | +## 关键文件模式 |
| 109 | + |
| 110 | +- `.ts` 和 `.tsx` 文件全部使用 TypeScript |
| 111 | +- 数据库模型使用 Mongoose 配合 TypeScript |
| 112 | +- API 路由遵循 NextJS 约定 |
| 113 | +- 组件文件使用 React 函数式组件和 hooks |
| 114 | +- 共享类型定义在 `packages/global/` 的 `.d.ts` 文件中 |
| 115 | + |
| 116 | +## 环境配置 |
| 117 | + |
| 118 | +- 配置文件在 `projects/app/data/config.json` |
| 119 | +- 支持特定环境配置 |
| 120 | +- 模型配置在 `packages/service/core/ai/config/` |
0 commit comments