第 7 周 · Mastra Agent/Tool/Workspace + Workflow/Durable
用 Mastra 构建产品级 Agent 与可暂停恢复的业务流程，并与 Native 实现做对照
本周产出：mastra-adapter、商品运营 Agent、可 Suspend / Resume 的上架 Workflow · 预计投入：15 到 20 小时 · 对应原 24 周编号：第 13、14 周
学前自测
1. 第 4 周你手写了 Agent Loop，现在引入框架，你期望它帮你省掉哪部分？
框架通常帮你省掉循环骨架、事件流、状态持久化和一部分工具编排。它通常不帮你做的是预算策略、错误分类、审批集成和跨租户隔离，这些还是要自己写。想清楚这个边界，才能判断引入框架是净收益还是净负债。
2. 什么是 Durable Execution？和普通的重试有什么区别？
普通重试是失败后从头再来。Durable Execution 是把每一步的结果持久化，服务重启后能从上次成功的那一步继续。区别在于前者会重复执行已成功的副作用（重复发邮件），后者不会。这是长流程业务的硬需求。
3. Workflow 在什么点上应该 Suspend？
需要外部输入才能继续的点：人工审批、等待第三方回调、等待定时触发。Suspend 的本质是把一个长时间的等待从占用进程变成持久化状态，这样服务重启不影响，也不会有一个进程干等几个小时。
4. 为什么核心业务包不能 import Mastra 的私有类型？
因为那样就绑死了。第 9 周要做 Runtime 平台化，需要 Native 和 Mastra 两套实现跑同一批契约测试；如果业务包已经依赖了 Mastra 的类型，Native 那条路根本跑不起来。这条约束从第 1 周立下，这一周是第一次真正被检验。
学习目标
使用 Mastra 构建产品级 Agent，接入统一 Tool Runtime、Workspace 与平台契约，并实现强类型、可暂停恢复的业务流程。
这一周有个隐藏目标：验证你前六周的抽象是不是真的抽象。如果 Adapter 写得很痛苦，说明前面的契约设计有问题，现在改还来得及。
课程内容
Mastra Agent、Tool、Workspace
- Mastra 项目结构与 Instance
- Agent、Instructions 与 Model
- Tool 与结构化输出
- generate / stream 与事件
- Request Context
- Agent Registration 与版本
- Workspace Root 与 Artifact
- Workspace Tool 和 Sandbox 边界
- ToolSet、动态工具与权限映射
- Runtime Adapter 与依赖注入
- Server、Client SDK 与 API 边界
- Mastra Beta 能力隔离原则
Mastra Workflow、Durable
- Workflow、Step 与 State
- Input / Output Schema
- branch、parallel、loop 与 composition
- Agent Step 与 Tool Step
- Snapshot、Suspend / Resume
- Human-in-the-loop 与修改后恢复
- Durable Execution 与服务重启
- 幂等、副作用与补偿
- Timeout、Retry 与 Dead Letter
- Workflow 版本和状态迁移
实施任务
将第 4 周的商品运营 Agent 用 Mastra 实现：
- Agent 和 Tool 定义通过
mastra-adapter接入统一契约 - Tool 最终仍由第 3 周 Tool Runtime、Sandbox 与 Permission Gate 执行
- Workspace 只暴露受控 Artifact 与测试目录
- Mastra stream 转换为统一
AgentEvent
用 Mastra 重写商品上架 Workflow：
执行服务重启、重复 signal、审批超时、节点失败故障注入。Beta 能力必须位于 Adapter 和 feature flag 后，关闭后主流程仍可运行。
对照任务
比较 Native 与 Mastra 的 Agent Definition、Tool 调用、stream、取消、事件完整性、类型安全、代码量、延迟与成本。程序员进阶版补齐 Pi / LangChain / LangGraph 后做多方对照。
动手挑战
在 Workflow 跑到审批节点时，把整个服务 kill 掉，然后重启。
检查五件事：
- Workflow 状态恢复到了哪一步？
- 审批之前已经执行过的步骤有没有被重复执行？
- 如果有一个步骤是发送通知，重启后用户收到了几条？
- 重启后批准，后续步骤能不能正常走完？
- 在服务停机期间，如果审批请求被重复提交了三次，恢复后会怎样？
第 3 条和第 5 条是大多数人第一版会翻车的地方。修好它们，你就真正理解了幂等性为什么是长流程系统的地基。
Agent OS 里程碑
完成 mastra-adapter，Agent Registry 可选择 Native 或 Mastra Runtime。完成 Workflow Designer 与 Background Job / Signal Demo。
验收标准
核心档（程序员基础版毕业线）
- Native 与 Mastra 双实现通过同一 Tool、Policy、Dataset 和事件契约测试
- 核心业务 packages 不导入 Mastra 私有类型
- Workspace 越权与高风险 Tool 必须被平台层阻断
- 服务重启、审批暂停和恢复不重复产生副作用
- Signal 重复投递具备幂等语义
- Beta 能力关闭后仍可退回稳定 Workflow 实现
进阶档验收见程序员进阶版附录 B。
学后自测
1. 同一个业务逻辑，Native 版和 Mastra 版的代码量差多少？多出来的时间省在哪，成本花在哪？
要能报具体行数和具体收益。典型结论是 Mastra 省掉了循环、事件和持久化的样板代码，代价是多了一层抽象要理解，以及升级时的兼容风险。有数字的对比在面试里是硬通货。
2. Mastra 的 stream 事件和你第 4 周定义的 AgentEvent，映射时哪些字段对不上？
对不上的地方正是 Adapter 存在的价值。常见缺口是成本字段、审批状态、自定义 Stop 原因。把这些缺口列出来，就是一份很有说服力的框架能力评估。
3. 如果明天要把 Mastra 换成别的框架，你要改多少个文件？
理想答案是只改 packages/adapter-mastra/ 一个包。如果答案是十几个文件散落在业务里，说明抽象漏了，现在补比第 9 周做平台化时补便宜得多。
本周作业
packages/adapter-mastra/：Agent、Tool、事件三方面的完整适配- 商品上架 Workflow 完整实现，含 Suspend / Resume
- 故障注入测试：服务重启、重复 signal、审批超时、节点失败四类
docs/native-vs-mastra.md：对照任务的完整报告，九个维度的实测数据加结论
这份对照报告是程序员基础版最有面试价值的文档之一，因为它证明你能做技术选型而不只是执行。
面试考点
这一周对应面试里的框架能力与选型判断考察。
- 「你为什么选 Mastra 不选 LangChain？」：拿出对照报告答，讲具体维度。切忌答生态好或者流行。中立提到 LangChain 的优势（生态组件多）再说明你的场景为什么更看重类型安全和 Workflow 持久化。
- 「长流程业务怎么保证不重复执行？」：答 Durable Execution 加幂等键加 Snapshot。最好讲你 kill 服务那次实验发现了什么问题、怎么修的。真实踩坑经历的说服力远高于理论。
- 「Human-in-the-loop 怎么实现？」：答 Workflow Suspend 加状态持久化加 signal 恢复。展开讲审批超时怎么处理，这是大多数人没想到的边界。
- 「框架升级把你的代码搞挂了怎么办？」：答 Adapter 隔离加 feature flag 加 Beta 能力单独关。能说出你的业务包一行框架私有类型都没有，这个回答就完整了。
- 反向陷阱：面试官可能说「用框架不就是省事吗，你搞这么多抽象是不是过度设计」。答要看框架在哪一层，模型和工具层的抽象是必要的因为要换 Provider，业务层过度抽象确实是浪费。承认边界比一味坚持更显成熟。
复习与延伸
官方文档
注意用 @mastra/core，不是 CLI 包 mastra。
本仓库对应源码
packages/adapter-mastra/src/agent.ts：Agent 适配参考实现packages/adapter-mastra/src/tool.ts：工具适配，注意执行最终仍走@agent-os/tool-runtimepackages/harness-native/src/agent-loop.ts：拿来和 Mastra 版逐行对照