145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 [Mastra 框架](https://mastra.ai) 构建的多功能 AI Agent 项目。项目采用模块化架构，包含天气查询、时间查询、计算器、文件列表和笑话生成等基础功能。
|
||
|
||
## 常用命令
|
||
|
||
### 开发环境
|
||
```bash
|
||
pnpm install # 安装依赖
|
||
pnpm dev # 启动开发服务器（http://localhost:4111）
|
||
pnpm build # 构建项目用于部署
|
||
```
|
||
|
||
### Express API 服务器
|
||
```bash
|
||
pnpm server:dev # 启动Express开发服务器（http://localhost:3000）
|
||
pnpm server:start # 启动Express生产服务器
|
||
```
|
||
|
||
### 脚本工具
|
||
```bash
|
||
pnpm generate # 运行生成脚本
|
||
```
|
||
|
||
## 项目架构
|
||
|
||
### 核心组件
|
||
|
||
#### 1. Mastra 配置 (`src/mastra/index.ts`)
|
||
- 初始化 Mastra 框架实例
|
||
- 注册所有 Agent
|
||
- 全局配置入口
|
||
|
||
#### 2. Express API 服务器 (`src/server/`)
|
||
- `index.ts`: Express应用主文件
|
||
- `routes/`: API路由定义
|
||
- `middleware/`: Express中间件
|
||
- `schemas/`: 请求验证模式
|
||
- 提供 RESTful HTTP 接口访问 Agent
|
||
|
||
#### 3. Agent 系统 (`src/mastra/agents/`)
|
||
- `multi-function-agent.ts`: 主代理，集成所有工具功能
|
||
- Agent 配置包含：名称、系统指令、模型配置、可用工具
|
||
|
||
#### 3. Tool 系统 (`src/mastra/tools/`)
|
||
- 每个工具使用 `createTool` 工厂函数
|
||
- 遵循统一结构：id、描述、输入/输出 Schema、执行逻辑
|
||
- 工具通过 `tools/index.ts` 统一导出
|
||
|
||
### 工具清单
|
||
- `weatherTool`: 天气查询（使用 Open-Meteo API）
|
||
- `timeTool`: 时间查询
|
||
- `calculatorTool`: 基本算术运算
|
||
- `filelistTool`: 目录文件列表
|
||
- `jokeTool`: 随机笑话生成
|
||
- `goodsTool`: 商品信息查询（支持分页查询列表和单个商品详情）
|
||
|
||
### 配置系统
|
||
- **环境变量**: `.env` 文件存储 API 密钥和配置
|
||
- **TypeScript**: `tsconfig.json` 配置为 ES2022 模块系统
|
||
- **依赖管理**: 使用 pnpm 和 `package.json`
|
||
|
||
## 开发流程
|
||
|
||
### 1. 环境设置
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，配置必要的 API 密钥
|
||
```
|
||
|
||
### 2. 运行开发服务器
|
||
启动后可通过以下方式访问：
|
||
- **Studio UI**: http://localhost:4111（交互式测试）
|
||
- **REST API**: http://localhost:4111/api/agents/multiFunctionAgent/generate
|
||
- **Swagger UI**: http://localhost:4111/swagger-ui（API 文档）
|
||
|
||
### 3. 运行 Express API 服务器
|
||
启动 Express 服务器提供 HTTP API：
|
||
```bash
|
||
pnpm server:dev
|
||
```
|
||
启动后可通过以下方式访问：
|
||
- **健康检查**: http://localhost:3000/health
|
||
- **Agent API**: http://localhost:3000/api/agent
|
||
- **生成响应**: POST http://localhost:3000/api/agent/generate
|
||
- **流式响应**: POST http://localhost:3000/api/agent/stream
|
||
|
||
### 4. 扩展项目
|
||
|
||
#### 添加新工具
|
||
1. 在 `src/mastra/tools/` 下创建新工具文件
|
||
2. 使用 Zod 定义输入/输出 Schema
|
||
3. 实现 `execute` 函数逻辑
|
||
4. 在 `tools/index.ts` 中导出
|
||
5. 在 Agent 配置中添加新工具
|
||
|
||
#### 添加记忆功能
|
||
```bash
|
||
pnpm add @mastra/memory @mastra/libsql
|
||
```
|
||
然后在 Agent 配置中添加 Memory 配置。
|
||
|
||
#### 添加语音功能
|
||
```bash
|
||
pnpm add @mastra/voice-openai
|
||
```
|
||
|
||
## 关键设计模式
|
||
|
||
### 1. 模块化工具设计
|
||
- 每个工具独立实现，通过统一接口接入
|
||
- 工具间无依赖，便于测试和替换
|
||
|
||
### 2. 配置驱动
|
||
- Agent 能力通过配置组合
|
||
- 扩展无需修改核心代码
|
||
|
||
### 3. 类型安全
|
||
- 使用 Zod 进行运行时验证
|
||
- TypeScript 提供编译时类型检查
|
||
|
||
## 注意事项
|
||
|
||
1. **模型配置**: Agent 当前使用 DeepSeek 模型，在 `multi-function-agent.ts` 中配置
|
||
2. **API 调用**: 天气工具依赖外部 API，需要网络连接
|
||
3. **构建要求**: 项目使用 ES2022 模块系统，需确保兼容性
|
||
4. **环境变量**: 开发和生产环境都依赖 `.env` 配置
|
||
|
||
## 调试和测试
|
||
|
||
### 通过 Studio UI
|
||
访问 http://localhost:4111 进行交互式测试，可以：
|
||
- 查看工具调用过程
|
||
- 调试 Agent 推理链
|
||
- 测试不同输入场景
|
||
|
||
### 通过 REST API
|
||
使用 curl 或 HTTP 客户端测试特定功能。
|
||
|
||
### 查看构建输出
|
||
构建后在 `.mastra/output/` 目录中可查看编译结果。 |