📚 编程进阶教程站

第 2 章 · 项目结构与 Mastra Studio ​

本章目标：读懂脚手架生成的目录结构，掌握 Mastra Studio 的四大功能面板，养成"改代码 → Studio 验证"的开发节奏。

2.1 脚手架目录解读 ​

用 npm create mastra@latest 生成的项目结构如下：

text
my-mastra-app/
├── src/
│   └── mastra/               # ★ 所有 Mastra 资源都放在这里
│       ├── index.ts          # 入口：new Mastra({...}) 注册全部资源
│       ├── agents/           # Agent 定义
│       │   └── weather-agent.ts
│       ├── tools/            # 工具定义
│       │   └── weather-tool.ts
│       └── workflows/        # Workflow 定义
│           └── test-workflow.ts
├── package.json
├── tsconfig.json
└── .env                      # API Key 等环境变量

约定优于配置：mastra dev 会扫描 src/mastra/ 目录自动发现并热加载资源，你不需要手动注册文件路径。

2.2 入口文件 index.ts ​

入口文件是整个应用的装配点：

typescript
// src/mastra/index.ts
import { Mastra } from '@mastra/core';
import { weatherAgent } from './agents/weather-agent';
// import { testWorkflow } from './workflows/test-workflow';

export const mastra = new Mastra({
  // 注册 agents，键名即后续 getAgent('xxx') 的 id 来源
  agents: { weatherAgent },
  // workflows: { testWorkflow },  // 有 workflow 时取消注释
  // storage、memory、logger 等也在这里统一配置（后面章节展开）
});
typescript
// 在任意脚本中验证资源是否被正确发现
import { mastra } from './mastra';

console.log(Object.keys(mastra.getAgents())); // 应输出 ['weatherAgent']

所有资源（agents / workflows / tools / storage）都在这一处集中注册，形成一张应用资源图。

2.3 Studio 四大面板 ​

启动 npm run dev 后打开 http://localhost:4111：

面板功能典型用途
Agents与任意已注册 Agent 对话测试调试 instructions、观察工具调用
Workflows图形化查看步骤流与执行路径检查 .then/.branch 连接是否符合预期
Traces查看每次调用的完整链路排查延迟、token 消耗
Logs运行日志流开发期快速定位报错

2.4 用 Studio 调试第一个 Agent ​

在 Agents 面板选择 weatherAgent，输入"上海明天适合跑步吗"，右侧会展开完整的执行过程：

text
User: 上海明天适合跑步吗
 ├─ tool-call: weatherTool({ city: "Shanghai" })
 │   └─ tool-result: { temp: "22°C", condition: "多云" }
 └─ Assistant: 明天上海多云，气温约 22°C，湿度适中，非常适合户外跑步。

工具调用参数与返回值全程可见——这是排查"模型为什么没调用我的工具"类问题最快的方式。

2.5 环境变量与密钥管理 ​

脚手架按所选提供商生成 .env 模板：

bash
# .env —— 千万不要提交到 git
OPENAI_API_KEY=sk-...
# 若使用 anthropic 提供商则改为：
# ANTHROPIC_API_KEY=sk-ant-...
typescript
// mastra dev 会自动加载 .env；代码中无需手动 process.env 传参
// 但自定义部署时可用 dotenv 显式加载：
import 'dotenv/config'; // 必须放在最顶部，先于其他 import 执行
typescript
// 生产部署时的显式加载示例：确保密钥在任何运行方式下都可用
import 'dotenv/config';
import { mastra } from './mastra';

if (!process.env.OPENAI_API_KEY) {
  throw new Error('缺少 OPENAI_API_KEY，请检查 .env 或平台环境变量');
}
console.log('资源加载正常:', Object.keys(mastra.getAgents()));

安全提示

.env 已被脚手架加入 .gitignore。若不小心泄露了 Key，应立即到提供商控制台吊销重置。

2.6 本章小结 ​

  • src/mastra/ 是唯一需要关心的源码目录，index.ts 是资源装配入口；
  • Studio 四大面板：Agents 对话测试、Workflows 图形视图、Traces 链路追踪、Logs 日志；
  • Studio 会展示完整的工具调用链路，是调试 Agent 行为的第一现场；
  • API Key 放 .env 并确认已被 gitignore。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Mastra 项目中，Agent / Tool / Workflow 等资源的默认存放目录是？

2. 想在可视化界面里查看某次 Agent 回复调用了哪些工具及参数，应该使用哪个面板？

3. 关于 Mastra 的环境变量加载，正确的说法是？

4. src/mastra/index.ts 中 new Mastra({ agents: { weatherAgent } }) 的作用是？

🛠️ 动手实践 ​

  1. 在 Studio 的 Agents 面板中修改 instructions（如要求"始终用中文回答"），观察回复风格变化，体会提示词的作用。
  2. 故意把 .env 中的 API Key 改错，观察 Studio 中报错信息长什么样，然后恢复。
  3. 在 Traces 面板找到一次对话记录，数一数一次 generate 调用包含几个 span。

下一章：第 3 章 · Model Routing 模型路由