Mastra（TypeScript 智能体框架）
| 分类 | 🧰 框架工具 |
| 阅读时间 | ⏱️ 15 分钟 |
| 更新时间 | 📅 2026-10-26 |
| 条目编号 | ENC-FRAMEWORK-23-mastra |
关键要点 ✦
- 定位：面向 TypeScript 技术栈的智能体与应用框架，核心包 @mastra/core，配套 @mastra/memory 等模块包；本地 Mastra Studio（默认 4111 端口）可视化调试智能体、工作流与工具，同一应用可部署到 Mastra Cloud。
- 运行外壳（harness）能力分层且可逐层采纳：持久化智能体（durable agents，@mastra/core 1.45.0 起）、后台任务、目标（goals，1.43.0 起，由 LLM 评审打分、默认 maxRuns 50）、定时任务（schedules，1.50.0 起）与信号及信号提供方（把 GitHub、Slack、CI 事件转入线程）。
- AgentController（前身名为 Harness，经 PR 18510 更名）于 2026-10-06 正式 GA：会话持久化、plan 与 build 双模式切换与计划审批流、子智能体派生、follow-up 排队与 steer() 中途转向、35 个信号的发布订阅事件流；团队自用的 TUI 编码智能体 Mastra Code 即构建其上。
- 持久化智能体把智能体循环包进工作流：流式分块随生成缓存到服务端缓存（如 Redis），客户端断线、刷新后可从原点重放，或以 runId 旁观进行中的流；事件化变体 createEventedAgent() 支持脱离 HTTP 请求的后台执行。
- 1.78.0（2026-10-15）加入 agent scopes（类型化身份字符串，冲突返回 HTTP 400 而非静默取舍）与 queueSignal() 排队信号；据第三方统计，@mastra/core 在约六周内发布了 15 个 minor 版本，API 演进快，部分新能力仍标注 beta。
- 与本站相邻条目的分工：Letta（ENC-FRAMEWORK-18）以记忆为核心本体，Google ADK 2.0（ENC-FRAMEWORK-22）走多语言矩阵路线，Mastra 代表 TypeScript 全家桶路线，把「跑得久、可恢复、可指挥」作为一等公民能力。
框架概览与组件
据 mastra.ai 官方站点，Mastra 的核心原语包括：Agent（在单一位置定义带类型指令、模型、工具与运行行为的智能体）、Workflow（类型化步骤、重试与分支组合成可审查可发布的生产工作流）、Memory（观察式记忆、语义召回与线程感知存储）、Server（把智能体与工作流注册到一个 Mastra 服务器上，本地运行或部署到 Mastra Cloud）与 Studio（本地界面，构建、测试与管理）。官方示例以 npm create mastra 起步，模型路由层可接入数千个模型。
框架同时强调评测内建：追踪、指标、日志、评分器与数据集等能力直接进入工作台，官方页面展示了带标注得分的评测运行示例。这使得「构建-观测-改进」的循环在同一个 TypeScript 代码库内完成，团队无需自行拼装观测栈。
运行外壳：让智能体活得比一次请求更久
Mastra 文档把 harness 定义为一组管理智能体「超出单次不间断运行」的能力集合：持久化智能体、后台任务、目标、定时、信号、信号提供方、AgentController 与 createCodingAgent()。重要的设计选择是粒度：一个带记忆的普通智能体照常工作，每一层外壳能力都可以单独采纳——想要持续跟进就加目标，想自主唤醒就加定时，想要外部事件就接信号提供方。
目标（1.43.0 引入）是线程范围内的持久目标：循环每迭代一次由 LLM 评审对已完成工作打分，目标未达成且预算未耗尽就继续，runsUsed 达到 maxRuns（默认 50）则标记暂停。定时（1.50.0 引入）以 cron 节奏唤醒智能体并持久化，跨重启与重部署存活。信号则把外部事件（GitHub、Slack、CI）作为类型化信号转入线程，1.78.0 又补上 queueSignal()，让外部事件排在当前运行之后而不是降级成普通消息。
AgentController 与长会话
据官方博客，AgentController 是包在智能体循环外的一层：提供可观看、可中断、可转向的会话，适配长运行的存储与记忆，控制工具调用，支持向子智能体派生任务，以及多模式切换（每个模式带独立指令与工具，如 plan 与 build 加计划审批流）。会话 Session 跨回合持久化状态，线程可创建、切换、重命名、删除与克隆；pub/sub 事件系统发出 35 个信号（agent_start、tool_input_delta、subagent_text_delta、usage_update 等），归约为可被网页、移动端或 TUI 消费的展示状态对象。
官方给出的使用信号包括：任务应当长运行或自主执行、需要与它进行长时间同事式对话、派发超过几分钟的任务、或在循环中大量编写并执行代码。团队自己每天驱动的 TUI 编码智能体 Mastra Code 就是该控制器的产物，随后把可用部分反哺成通用类库。
持久化智能体与版本节奏
持久化智能体（官方博客 Introducing Durable Agents）解决的问题是：智能体流原本绑定在发起它的 HTTP 连接上，连接断开就只能从头再来。新实现把智能体循环包进工作流，分块随生成写入服务端缓存（示例用 Redis），经由事件系统供任意客户端以 runId 订阅——换一个客户端也能从流的起点旁观进行中或已完成的运行；需要脱离 HTTP 请求的后台执行时改用 createEventedAgent()。据官方说明，该能力自 @mastra/core 1.45.0 起提供。
版本节奏需要纳入工程计划：据第三方开发者媒体统计，@mastra/core 从 2026-09-03 的 1.64.0 到 2026-10-15 的 1.78.0 发布了 15 个 minor 版本（1.79.0 已进入 alpha），目标、定时、信号、后台任务与 AgentController GA 都发生在这个窗口内；1.78.0 引入 agent scopes 并移除跨作用域凭据回退，升级 @mastra/server 与 core 必须同步进行，否则智能体会拒绝来自旧服务器的请求。部分新能力仍标 beta，选型时应对关键路径做版本锁定与降级预案。
🎯 应用场景
✅ 最佳实践
- 锁定关键依赖版本：core 与 @mastra/server 必须同步升级，升级前阅读破坏性变更清单。
- 按需渐进采纳外壳能力：从带记忆的普通智能体起步，逐层加入目标、定时与信号。
- 生产环境为线程、快照与目标选择可靠存储后端，LibSQL 适合本地与原型。
- 对标注 beta 的能力（如持久化智能体相关路径）准备降级方案，避免直接承压关键业务。
- 利用 Studio 与评测内建能力在本地闭环验证，再部署到 Mastra Cloud 或自有设施。
🔮 未来展望
TypeScript 智能体框架的竞争正集中在长时运行与平台化：目标、定时、信号等原语在走向标配，评测门禁与 MCP 2.x 集成继续深化。对采用者而言，框架快速迭代是长期现实，版本锁定策略与渐进采纳路径会决定维护成本；AgentController 一类的「可指挥运行外壳」预计会被更多框架效仿。