为什么写这本教程

Mastra 的官方文档覆盖面很广，但中文读者常遇到三个问题。

第一，概念太多。Agent、Tool、Workflow、Memory、RAG、MCP、Evals、Observability 都很重要，但新手最难的是判断顺序。你不需要第一天就懂全部，但需要知道这些能力分别解决什么问题。

第二，demo 和产品之间有距离。一个天气工具很容易跑通，但真实产品还要考虑多用户、记忆边界、权限、失败重试、人工审批、日志、评测和部署。

第三，AI agent 框架变化很快。很多网络教程会混用旧 API、新 API 和其他框架的概念，最后让读者在 TypeScript 类型错误和运行时错误里消耗时间。

这本教程的写法会更工程化：

• 不只介绍 API，还解释选择理由。
• 不只给片段，还给一个可运行示例项目。
• 不只讲“能用”，还讲“上线时怎么不失控”。
• 不把 Agent 当万能入口，而是把 Agent 和 Workflow 分清边界。

这本教程不做什么

它不会覆盖 Mastra 的每一个边角 API。官方 reference 更适合查完整参数。

它也不会替你选择唯一模型供应商。Mastra 的模型路由支持多供应商，本教程的示例会尽量把模型字符串集中配置，方便你替换。

它不会把 RAG、MCP、评测讲成“加一个库就完成”的功能。这些都是系统设计问题，代码只是入口。

最终你应该获得什么

读完后，你应该能独立回答：

• 一个需求应该用 Agent、Workflow，还是两者组合？
• Tool 的 schema、描述和返回值应该如何设计？
• 多用户记忆为什么要区分 resource 和 thread？
• 如何让 agent 访问 MCP 工具，又如何把自己的能力暴露成 MCP Server？
• 生产环境至少需要哪些观测、评测和安全策略？