模块详解

agent.ts 9408 行是整个 core 最大单文件，但实际执行逻辑大量委托出去：prepare-stream workflow（agent/workflows/prepare-stream/）在每次调用时构造，加载 memory、解析 tools、跑 input processors；真正的 LLM 循环交给 llm/model/model.loop.ts 里的 MastraLLMVNext → loop()。读 Agent 时重点看 agent.ts 里的 #execute() 私有方法和 generate()/stream() 如何构造 prepare-stream。另外注意：Agent 没有顶层 approve()/decline()，人审接口在 agent-controller（session approval）和 approveNetworkToolCall/declineNetworkToolCall（network 场景）。

Mastra 类在 index.ts 里是个 5870 行的大类，但绝大多数方法是注册/查找（getAgent、addAgent、listAgents、getWorkflow...）。执行期 primitives 通过 request-context 反向拿到 Mastra 实例（di/RequestContext），所以运行时依赖是反的。它主要是注册期的大管家 + 后台服务（worker、scheduler、server）的宿主。顶层 @mastra/core 只 re-export Mastra 和 Config，其他都走子路径（@mastra/core/agent 等）。

Workflow 本身不内置 LLM 概念，但和 Agent/loop 的耦合极深：Agentic Loop 的每轮迭代就是一次 Workflow 执行。两套引擎并存：DefaultExecutionEngine（pull-based，传统 workflow 用）和 evented/（push-based，实时事件处理）。Step 可以是普通函数、LLM step、或另一个 Workflow，这是 agentic-loop > agentic-execution 嵌套的基础。读源码时 workflow.ts 4400 行是入口，但真正的执行流程在 handlers/ 和 evented/workflow-event-processor/ 里。

理解 Mastra 执行模型的关键模块。注意：createPrepareStreamWorkflow 不在 loop/ 下，而在 agent/workflows/prepare-stream/。loop.ts 本身只有 177 行，真正逻辑在 workflows/ 子目录。agentic-execution 单轮的 step 顺序是：llmExecutionStep → map-tool-calls → foreach(toolCallStep) → llmMappingStep → backgroundTaskCheckStep → signalDrainStep → isTaskCompleteStep → goalStep。loop() 只依赖 stream/processors/observability 等少数模块，不直接依赖 agent/——反向依赖由 llm/model.loop.ts（MastraLLMVNext）桥接。

Processor 接口定义在 index.ts 本身（不是单独的 types 文件），890 行。10+ 个 hooks 分阶段：processInput/processLLMRequest（请求侧）、processLLMResponse/processOutput/processOutputStream（响应侧）、processAPIError（错误处理）、computeStateSignal（状态信号）、processInputStep/processOutputStep（step 粒度）、processDataParts（流数据处理）。Processor 本身可以是类实例或 Workflow（复用 DAG 能力）。读源码时先从内置 processor 反向理解接口比直接看 interface 更直观——24 个内置 processor 都在 processors/processors/ 和 processors/memory/ 下。

关键理解点：MastraLLMVNext（model.loop.ts）虽然在 llm/ 下但不从 llm/index.ts 导出，agent/agent.ts 直接 import 它。这个类包装 AI SDK LanguageModel，但把 doStream 路由进 Mastra 自己的 loop()，而不是直接调 AI SDK——这是 agent.generate() 最终跑三层 workflow 的入口。router.ts 的 ModelRouterLanguageModel 做字符串解析和 provider 动态 import（冷启动成本来源）。gateway 认证、API key 轮换、fallback 链都在 router/gateway 层。注意 llm/ 还同时支持 AI SDK v4/v5/v6/v7（aisdk/ 子目录各版本 wrapper）。

Storage 是被依赖最多的底层模块，自己只依赖 base.ts（MastraBase），几乎零跨模块依赖。设计上每个子域（storage/domains/<name>/）独立提供 base/inmemory/filesystem 三套实现——你可以 workflow 状态用 Postgres（外部包）、blob 用 S3、memory 用 Redis、其他用 InMemory，混搭运行。types.ts 3086 行是整个 core 最大的类型文件。读源码时 base.ts 只有 614 行（主要是域访问器和 init/close），真正的域接口定义全在 types.ts 和 domains/ 下。

Tools 代码量不大（5712 行），但它和 loop/agent 的交互点很关键：工具可以声明 requireApproval（中断 loop 等人审）、suspend（SuspendOptions 类型来自 workflows/，把 agent 睡眠等外部事件唤醒）、background（由 tool-loop-agent 后台跑）。这些扩展点不是 if/else 加在 Tool 类里，而是通过 agentic-execution workflow 的 tool-call-step 分支实现——durable execution 天然支持中途停下来。tool-builder/builder.ts 1068 行负责把 Vercel AI SDK 工具和其他 provider 工具转成 Mastra Tool，是生态兼容层。