120 lines
3.3 KiB
Markdown
120 lines
3.3 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 # 构建项目用于部署
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 脚本工具
|
|||
|
|
```bash
|
|||
|
|
pnpm generate # 运行生成脚本
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 项目架构
|
|||
|
|
|
|||
|
|
### 核心组件
|
|||
|
|
|
|||
|
|
#### 1. Mastra 配置 (`src/mastra/index.ts`)
|
|||
|
|
- 初始化 Mastra 框架实例
|
|||
|
|
- 注册所有 Agent
|
|||
|
|
- 全局配置入口
|
|||
|
|
|
|||
|
|
#### 2. 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`: 随机笑话生成
|
|||
|
|
|
|||
|
|
### 配置系统
|
|||
|
|
- **环境变量**: `.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. 扩展项目
|
|||
|
|
|
|||
|
|
#### 添加新工具
|
|||
|
|
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/` 目录中可查看编译结果。
|