Mystery/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个基于 Mastra 框架 构建的多功能 AI Agent 项目。项目采用模块化架构，包含天气查询、时间查询、计算器、文件列表和笑话生成等基础功能。

常用命令

开发环境

pnpm install      # 安装依赖
pnpm dev          # 启动开发服务器（http://localhost:4111）
pnpm build        # 构建项目用于部署

Express API 服务器

pnpm server:dev   # 启动Express开发服务器（http://localhost:7328）
pnpm server:start # 启动Express生产服务器

脚本工具

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. 环境设置

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：

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 配置中添加新工具

添加记忆功能

pnpm add @mastra/memory @mastra/libsql

然后在 Agent 配置中添加 Memory 配置。

添加语音功能

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/ 目录中可查看编译结果。