# 选 Mastra，要看谁来维护代码，而不是看演示

> TypeScript 客户团队能在一个仓库里用上工作流、记忆、MCP 和评测；纯 Python 团队则基本无此优势。

原文: https://fdetimes.net/zh/tools/mastra-typescript-agent-framework-fde/

客户的后端跑在 Node 和 TypeScript 上。你一离场，他们的团队就要接手这套 Agent 系统。这时选框架不再是个人偏好问题：它决定了六个月后还有谁能改这些代码。

Mastra 正是这种场景下值得认真考虑的选项。官方文档将它定义为用于构建 Agent 和 AI 应用的 TypeScript 框架。官方仓库把 Agent、工作流、记忆、评测和 MCP 集中在一处。

它背后是打造 Gatsby 的团队，三位联合创始人 Sam Bhagwat（CEO）、Shane Thomas 和 Abhi Aiyer 于 2024 年创立了这家公司。对前线部署工程师（FDE）来说，有用的问题不是 Mastra 好不好，而是在客户现场什么时候该选它，以及要学会哪些东西才能从第一天起就用上它。

## 为维护者选型，而不是为演示选型

一次部署是否成功，要看你离开后客户团队还能不能改得动。如果他们的后端是 TypeScript，再引入一个 Python 服务来跑 Agent，就意味着多一个运行时、多一条部署流水线，还有一批人要学另一门语言。Mastra 省掉了这笔成本，因为 Agent 和其他代码使用同一种语言、放在同一个仓库里。

第二个原因是，Agent 项目通常要自己搭的四样东西，Mastra 已经内置：编排步骤、记住用户、通过 MCP 接入工具，以及给输出质量打分。

如果用四个库把这四样东西拼起来，现场的大部分时间都会花在对接上。反过来，如果客户团队只用 Python，这个优势基本就不存在了，你应该重新考虑。

**要点:** 按照将来维护系统的团队所用的语言选框架，而不是按最惊艳的演示选。

## 工作流还是 Agent：界线在哪里？

Mastra 的文档说得很明确：任务事先定义清楚、包含多个步骤、且必须按特定顺序执行时，用工作流。工作流运行在基于图的引擎上，每次运行都可以暂停、恢复并流式输出结果。只有仍然模糊、需要模型自己选择下一步的部分，才交给 Agent。

当客户想知道哪一步先执行、哪一步需要有人签字时，这条界线对 FDE 就很重要。暂停和恢复正是把人工审批人放进流程的位置，不必自己写状态机。

## 设想一个带人工审批的退款流程

假设客户是一家零售商，想把退款申请自动化。你搭了一个四步工作流：对申请分类、查询订单、做出决定、起草回复。在决定这一步，如果金额超过客户设定的阈值，工作流就暂停，等员工审批后再继续。

下面的示意代码只说明这一步及配套 scorer 的逻辑。它是伪代码，不是准确语法；真实的函数名请查阅 Mastra v1 文档。

```ts
// 伪代码：仅说明逻辑，并非准确的 Mastra v1 API
const decide = step(async ({ refund, suspend, resumeData }) => {
  if (refund.amount > APPROVAL_THRESHOLD && !resumeData) {
    // 运行在此停止，直到员工审批并恢复
    return suspend({ orderId: refund.orderId, reason: "needs_approval" });
  }
  return { approved: resumeData ? resumeData.approved : true };
});

// 基于规则的 scorer：回复中是否提到了正确的订单号？
const mentionsOrderId = (output, refund) =>
  output.includes(refund.orderId) ? 1 : 0;
```

常见的错误是把需要判断的部分塞进工作流固定的 if-else 链里，比如判断一个含糊的退款理由是否成立。按照文档划出的界线，这部分应该交给 Agent，工作流只保留顺序明确的步骤和审批暂停。

两者混在一起，客户每提一个例外，工作流就膨胀一圈。到现场第一件事，是和运营团队坐下来，在白板上画出各个步骤，标出哪些需要人工审批、哪些需要判断。这张图几乎就是工作流设计本身。

## Agent 记住什么，放在哪一层？

Mastra 的记忆分为几层，退款流程三层都用得上。消息历史保存对话中最近 N 条消息，足以让 Agent 不再追问刚拿到的订单号。

工作记忆存储关于用户的结构化持久数据，如姓名、偏好和目标。这样即使在之后的对话里，Agent 也能记得这位客户希望退款到银行卡而不是钱包。

语义召回按含义而非关键词检索旧消息。像“上次你们发错了颜色”这样的话，即使用户没有重复原来的措辞，也能找到上个月的投诉。

最容易犯的错误是把所有东西都塞进同一层。把客户偏好放进消息历史，对话一长就被挤出去；靠语义召回来取退款方式这类结构化数据，结果就取决于基于含义的检索能不能碰巧命中。

事先想清楚哪些信息是固定档案，哪些只是上下文。

## 赶在客户之前打分

Mastra 中的评测叫 scorer：对 Agent 输出自动打分的测试，有三种方式：模型打分、基于规则和统计方法。在退款流程中，像上面示意代码里那样基于规则的 scorer 负责检查订单号；模型打分的 scorer 则判断语气是否礼貌、回复是否符合政策。

scorer 可以在两个地方运行。在 CI/CD 中，它们是回归测试：每次修改提示词，就在一组样例对话上重新运行，分数下降则阻止合并。在生产环境中，它们以抽样方式在后台实时运行，不阻塞 Agent 的响应，也不影响工作流的执行。

当客户问 Agent 这周是不是比上周差了，实时模式能给出数据。第一周就和他们商定两三个 scorer，别等到有人投诉。

## 需要提前和客户讲清的限制

Mastra 的许可证分两层。核心采用 Apache 2.0，而 ee/ 目录中的代码适用 Mastra Enterprise License，属于源码可见（source-available）许可。客户的法务团队可能会问到这一点，所以要提前查清你打算使用的功能位于哪里。

版本节点也有实际影响。Mastra v1 于 2026 年 1 月发布；文档建议新项目直接从 v1 开始，并提供了专门的升级指南。在此之前写的教程和示例代码可能已经对不上，查资料时优先看官方 v1 文档。

## 按什么顺序学，如何自测

合理的顺序就按上面的示例流程走。先做一个带审批暂停的工作流，因为客户想保留签字权时，suspend/resume 的价值体现得最明显。然后给 Agent 加上工作记忆，最后把 scorer 接入 CI。

最终练习：重建退款流程，审批阈值可配置，把退款方式存入工作记忆，再写一个检查订单号的基于规则的 scorer。通过标准是：超过阈值的申请停在正确的位置，审批后能恢复，而你故意从回复中删掉订单号时，CI 中的 scorer 会变红。

从职业发展看，一个能展示这三点的小仓库，分量远超一个聊天机器人演示。简历上用结果来写，例如“设计了带人工审批步骤的 TypeScript Agent 工作流，并通过 CI scorer 阻止质量回退”。

框架会不断变化，但方法不变：把流程化的部分和需要模型推理的部分分开，把人工审批人放在正确的位置，在客户不得不替你衡量之前，先自己衡量好质量。

**本周动手试试:**

- 用 Mastra v1 搭建一个三步工作流，让第二步暂停等待人工审批，然后恢复
- 为一个示例 Agent 写两个 scorer，一个基于规则、一个由模型打分，并在 CI 中用 20 段样例对话运行
- 打开 mastra-ai/mastra 仓库，列出 ee/ 目录，与你打算使用的功能逐一核对

## 信源

- [Mastra Docs](https://mastra.ai/docs)

- [mastra-ai/mastra (GitHub)](https://github.com/mastra-ai/mastra)

- [Workflows | Mastra Docs](https://mastra.ai/docs/workflows/overview)

- [Memory | Mastra Docs](https://mastra.ai/docs/memory/overview)

- [Evals | Mastra Docs](https://mastra.ai/docs/evals/overview)

- [About | Mastra](https://mastra.ai/about)

- [Upgrade to Mastra v1](https://mastra.ai/reference/migrations/upgrade-to-v1/overview)
