# 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:7328）
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:7328/health
- **Agent API**: http://localhost:7328/api/agent
- **生成响应**: POST http://localhost:7328/api/agent/generate
- **流式响应**: POST http://localhost:7328/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/` 目录中可查看编译结果。