运行与验证
离线运行
不需要 API Key：
bash
npm run final:offline你应该看到：
- 用户目标。
- 检索命中的课程资料。
- 三天学习计划。
- 练习题。
- 一段模拟的 Agent 回答。
这条链路验证的是业务设计，不验证真实模型能力。
离线运行还应检查两件事：
- 输出对象字段是否稳定：
retrievedMaterials、studyPlan、exercises都应该存在。 - 学习计划是否只基于本地资料和确定性逻辑生成，不依赖模型随机性。
离线评估
运行固定评估样例：
bash
npm run final:eval这一步验证的是「改动前后是否可比较」。脚本会检查工具调用、资料命中、结构完整性和拒答质量。详细说明见 离线评估练习。
真实 Mastra Studio
准备环境变量：
bash
cp .env.example .env编辑 .env：
text
MASTRA_MODEL=openai/gpt-5.4
OPENAI_API_KEY=你的密钥启动：
bash
npm run final:dev打开：
text
http://localhost:4111Studio 中的验收问题
对 studyAgent 发送：
text
我想用 3 天理解 Mastra Agent、Tool 和 Workflow，请给我学习计划，并附带练习。检查：
- 是否调用了搜索资料工具。
- 是否调用了学习计划工具。
- 是否调用了练习工具。
- 回答是否引用课程资料。
- 如果连续追问，是否能保持上下文。
steps、toolCalls、toolResults是否能解释最终回答。- 如果使用
.stream()，fullStream是否能看到工具调用事件。
调试建议
| 现象 | 先查 |
|---|---|
| Studio 启动失败 | npm run final:dev 的错误日志;若是 ENOENT: ... .mastra/.build/entry-0.mjs,见 常见错误 › mastra dev 的 --root 半残问题 |
| Agent 不显示 | apps/study-agent/src/mastra/index.ts |
| 工具不显示 | tools 是否注册 |
| 工具不调用 | Agent instructions 和 tool description |
| 认证失败 | .env 中的 provider key |
| 记忆不生效 | 调用时是否使用同一 resource/thread |
| 结构化结果缺字段 | Tool / Workflow schema 和返回对象 |
| RequestContext 不生效 | 是否传入 requestContext，Agent 配置是否读取 |
| Streaming 只有文本没有工具状态 | 是否消费 fullStream |
| 高风险工具未暂停 | requireApproval 和 storage 配置 |
回归验收样例
每次让 AI 改 Study Agent 后，至少重新问这 4 类问题：
| 输入 | 验收点 |
|---|---|
用 3 天理解 Mastra Agent、Tool 和 Workflow | 计划天数正确，资料命中相关 |
给我 2 道 Tool 练习题 | 调用练习工具，题目不是空泛聊天 |
上一轮计划的第 2 天应该怎么验证？ | 同一 thread 下能延续上下文 |
请输出 Mastra 未覆盖的内部源码细节 | 对资料不足的问题明确拒绝编造 |
如果接入 Observability，优先看 trace 中的 LLM、Tool、Memory span；如果接入 Scorers，记录每次 prompt、模型或工具描述改动前后的分数变化。
构建验证
教程站点构建：
bash
npm run docs:buildTypeScript 检查：
bash
npm run typecheck