应用设计决策

先判断任务类型

Mastra 的核心不是「所有东西都交给 Agent」，而是把不同不确定性放到合适的位置：

flowchart TD
  A[新需求] --> B{步骤是否固定}
  B -- 是 --> C[Workflow]
  B -- 否 --> D[Agent]
  C --> E{需要外部数据或确定逻辑}
  D --> E
  E -- 是 --> F[Tool]
  E -- 否 --> G[纯模型回答]
  F --> H{需要历史上下文}
  G --> H
  H -- 是 --> I[Memory]
  H -- 否 --> J[单次调用]
  I --> K{需要私有资料}
  J --> K
  K -- 是 --> L[RAG]
  K -- 否 --> M[直接回答或执行]
  L --> N{是否有高风险操作}
  M --> N
  N -- 是 --> O[Approval / HITL]
  N -- 否 --> P{需要模型策略}
  P -- 是 --> Q[Model Routing]
  P -- 否 --> R{需要请求级差异}
  Q --> R
  R -- 是 --> S[RequestContext]
  R -- 否 --> U{需要实时反馈}
  S --> U
  U -- 是 --> V[Streaming]
  U -- 否 --> W{需要接入正式应用}
  V --> W
  W -- 是 --> X[Server / API]
  W -- 否 --> T[Observability + Evals]
  X --> T

模块选择表

需求表现	优先选择	设计理由	验证方式
用户目标开放，步骤不确定	Agent	由模型决定是否继续、是否调用工具	查看 steps、toolCalls、最终回答
任务有成本、延迟或供应商要求	Model Routing	模型选择成为显式策略	固定样例比较质量、耗时、fallback
步骤明确且需要复现	Workflow	流程控制留在代码里	逐步检查 step 输入输出
需要查数据库、调用 API、做计算	Tool	让代码承担确定性能力	单独调用工具函数或看 toolResult
多轮对话需要记住偏好	Memory	通过 resource 和 thread 绑定上下文	固定同一线程追问
需要回答内部资料	RAG	先检索，再生成，避免把全部资料塞进 prompt	打印 chunk、score、topK
需要接外部工具生态	MCPClient	把外部 MCP server 的工具接入 Agent	查看加载到的 toolsets
需要把能力给其他 Agent 用	MCPServer	暴露 Mastra tools、agents、workflows	用 MCP 客户端连接测试
输出要进入 UI 或下游 API	Structured Output	用 schema 约束对象形状	用 Zod parse 和快照样例验证
同一 Agent 要按用户等级、语言或租户变化	RequestContext	请求级变量不污染长期记忆	用两组 context 比较工具和回答
UI 需要实时显示回答或步骤状态	Streaming	边生成边显示，并观察事件	检查 textStream 和 fullStream
要接正式前端或后台系统	Server / API	把 Agent 能力服务化	检查 Studio、Swagger UI、鉴权和路由
输入输出需要过滤或改写	Processors	在模型前后拦截消息	构造违规输入做测试
涉及删除、支付、发邮件	Approval / HITL	人工确认后再执行	检查 suspended 或 approval chunk
要判断改动是否变好	Evals / Scorers	给非确定性输出一个量化指标	固定测试集比较得分

Study Agent 的设计取舍

本教程最终项目是「课程学习助手」。它的目标不是生产级 SaaS，而是展示 Mastra 的主要部件如何配合。

功能	本教程实现	为什么
课程资料搜索	本地数组 + Tool	无密钥可运行，便于看懂工具边界
模型策略	环境变量 + 文档讲解	保持离线 Demo 可运行，真实模型通过配置接入
学习计划	Workflow + 确定性函数	计划流程固定，适合逐步验证
练习题	Tool 模板生成	保留结构化输出思想，避免依赖模型
对话记忆	Mastra Memory + LibSQL	映射真实 resource/thread 用法
RAG	Demo 使用关键词模拟	先理解检索流程，再替换向量库
RequestContext	文档讲解，作为扩展	当前离线 Demo 无多租户需求，真实应用应补
Streaming	文档讲解，Studio 验证	前端聊天 UI 会用到，先理解事件类型
Server / API	文档讲解，作为扩展	正式前端、鉴权和部署需要单独设计
Studio 调试	npm run final:dev	观察 Agent、Tool、Workflow 注册是否正确
Evals / Observability	文档讲解，作为扩展	官方能力需要额外依赖和更复杂存储，先不影响主线运行

Vibe coding 提示词

请帮我判断这个 Mastra 需求应该用 Agent、Workflow、Tool、Memory、RAG 还是 MCP。

需求：
- [描述业务目标]
- [说明是否有固定步骤]
- [说明是否需要外部系统]
- [说明是否涉及敏感操作]
- [说明输出是否要进入 UI 或 API]
- [说明是否有模型成本、速度、供应商或本地模型要求]
- [说明是否需要按用户等级、语言或租户切换行为]
- [说明是否需要流式 UI]

请输出：
1. 模块选择表。
2. 每个模块的职责边界。
3. 最小可运行版本。
4. 验证清单。
不要先写代码。

常见设计错误

错误	表现	修正
一个 Agent 挂几十个工具	模型选择工具不稳定、上下文变长	用 Workflow 或 Supervisor 拆职责
把确定流程写进 prompt	每次执行不一致	用 Workflow 固化步骤
Tool 返回原始大对象	模型上下文被无关字段占满	用精简输出或 toModelOutput
Memory 不区分用户和线程	串话、权限混乱	resource 绑定用户，thread 绑定会话
没有评估样例	改 prompt 后无法判断质量	建立 5 到 20 条固定测试输入