BattleMonAgent/README.md

# 多功能 Mastra Agent

这是一个使用 Mastra 框架构建的多功能 AI Agent，具备以下基础功能：

- **天气查询**：获取任意城市的当前天气信息
- **时间查询**：返回当前时间和时区
- **计算器**：执行基本算术运算（加、减、乘、除）
- **文件列表**：列出指定目录的文件
- **笑话生成**：随机讲述笑话

## 项目结构

```
src/mastra/
├── agents/
│   ├── multi-function-agent.ts    # 多功能 agent
│   └── index.ts                   # agent 导出
├── tools/
│   ├── weather-tool.ts            # 天气工具
│   ├── time-tool.ts               # 时间工具
│   ├── calculator-tool.ts         # 计算器工具
│   ├── filelist-tool.ts           # 文件列表工具
│   ├── joke-tool.ts               # 笑话工具
│   └── index.ts                   # 工具导出
├── workflows/                     # （可选）工作流目录
└── index.ts                       # Mastra 入口点
```

## 快速开始

### 1. 安装依赖

```bash
pnpm install
```

### 2. 配置 API 密钥

复制 `.env.example` 为 `.env`，并填入你的 OpenAI API 密钥：

```bash
cp .env.example .env
```

编辑 `.env` 文件：
```
OPENAI_API_KEY=sk-your-openai-api-key-here
```

### 3. 启动开发服务器

```bash
pnpm dev
```

服务器将在 http://localhost:4111 启动。

### 4. 使用 Agent

#### 通过 Studio UI 交互

打开浏览器访问 http://localhost:4111，在 Studio 界面中与你的 agent 对话。

#### 通过 HTTP API 调用

```bash
# 获取当前时间
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What time is it?"
      }
    ]
  }'

# 计算 15 + 27
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is 15 + 27?"
      }
    ]
  }'

# 查询东京天气
curl -X POST http://localhost:4111/api/agents/multiFunctionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What'\''s the weather in Tokyo?"
      }
    ]
  }'
```

#### 通过 TypeScript 代码调用

```typescript
import { mastra } from "./src/mastra/index.js";

async function callAgent() {
  const agent = mastra.getAgent("multiFunctionAgent");

  // 查询时间
  const timeResponse = await agent.generate("What time is it?");
  console.log(timeResponse.text);

  // 计算
  const calcResponse = await agent.generate("What is 15 + 27?");
  console.log(calcResponse.text);

  // 查询天气
  const weatherResponse = await agent.generate("What's the weather in Tokyo?");
  console.log(weatherResponse.text);

  // 列出文件
  const fileResponse = await agent.generate("List files in current directory");
  console.log(fileResponse.text);

  // 讲笑话
  const jokeResponse = await agent.generate("Tell me a joke");
  console.log(jokeResponse.text);
}

callAgent();
```

## 工具详情

### 1. 天气工具 (`weatherTool`)
- **功能**：通过 Open-Meteo API 获取实时天气数据
- **输入**：城市名称
- **输出**：温度、体感温度、湿度、风速、天气状况

### 2. 时间工具 (`timeTool`)
- **功能**：返回当前 ISO 时间和时区
- **输入**：无
- **输出**：当前时间、时区

### 3. 计算器工具 (`calculatorTool`)
- **功能**：执行基本算术运算
- **输入**：操作类型（add/subtract/multiply/divide）、两个数字
- **输出**：计算结果、操作描述

### 4. 文件列表工具 (`filelistTool`)
- **功能**：列出指定目录的文件
- **输入**：（可选）目录路径
- **输出**：文件数组、目录路径

### 5. 笑话工具 (`jokeTool`)
- **功能**：随机返回一个预设笑话
- **输入**：无
- **输出**：笑话文本

## 扩展功能

### 添加新工具

1. 在 `src/mastra/tools/` 目录下创建新的工具文件
2. 实现工具逻辑，使用 `createTool` 函数
3. 在 `tools/index.ts` 中导出新工具
4. 在 agent 配置中添加该工具

### 添加记忆功能

安装 memory 包并配置：

```bash
pnpm add @mastra/memory @mastra/libsql
```

然后在 agent 配置中添加：

```typescript
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/libsql";

export const agent = new Agent({
  // ... 其他配置
  memory: new Memory({
    storage: new LibSQLStore({
      url: "file:./mastra.db",
    }),
  }),
});
```

### 添加语音功能

安装语音包并配置：

```bash
pnpm add @mastra/voice-openai
```

```typescript
import { OpenAIVoice } from "@mastra/voice-openai";

export const agent = new Agent({
  // ... 其他配置
  voice: new OpenAIVoice(),
});
```

## 故障排除

### 常见问题

1. **API 密钥错误**
   - 检查 `.env` 文件中的 `OPENAI_API_KEY` 是否正确
   - 确保密钥有足够的额度

2. **服务器启动失败**
   - 检查端口 4111 是否被占用
   - 尝试 `pnpm build` 检查构建错误

3. **工具调用失败**
   - 检查网络连接（天气工具需要网络）
   - 确认工具输入格式正确

### 获取帮助

- [Mastra 官方文档](https://mastra.ai/docs)
- [Mastra Discord 社区](https://discord.gg/BTYqqHKUrf)

## 许可证

MIT