Appearance
🐣 小a的困惑
小a在 pi 工坊干了半年,自以为摸透了 Agent 的样子:一个跑在终端里的 CLI,帮人写代码。
某天它上网冲浪,撞见一个叫 Mastra 的家伙,瞬间懵了——人家也自称 "TypeScript Agent 框架",但长得完全不一样:不是 CLI,是库;不是 Loop,是 Graph 工作流;不跑在你电脑上,而是部署到 Vercel、Cloudflare。
"同样是 Agent,差别怎么这么大?"小a跑去问老z。
🧙 老z笑了:"因为你看到的是 Agent 世界的两个极端。一个替人干活(本地工具),一个替人造应用(云框架)。理解它们的对立,你就懂了 Agent 的全貌。"
F.1 两种 Agent 是两种生物
先把话说清楚:pi 和 Mastra 根本不是同一类东西。这不是"哪个更好",而是"解决完全不同的问题"。
| 维度 | pi-mono(本地 Agent) | Mastra(云端框架) |
|---|---|---|
| 本质 | 一个可执行产品(pi 命令) | 一个 npm 库,你写代码调用它 |
| 用户 | 想让 AI 帮自己写代码的开发者 | 想造"会做事的应用"的开发者 |
| 产物 | 终端里的编码助手 | 后端服务/API/网页应用 |
| 谁定义行为 | pi 的作者(你装来用) | 你(你用它造自己的 agent) |
| 部署位置 | 你的本地电脑 | Vercel / Cloudflare / 自建服务器 / Mastra Cloud |
| 运行方式 | 你敲一行命令,它跑给你看 | 跑在服务器上,响应 HTTP 请求 |
| 数据在哪 | 你本地磁盘(你的代码、你的 key) | 云端(你的用户数据) |
| 典型场景 | "帮我改这个仓库的 bug" | "造一个客服 bot 部署给一千个用户用" |
🧙 老z打比方:"pi 是电饭煲——买来就能煮饭,你自己吃。Mastra 是厨房设备厂——给你灶台、烤箱、流水线,你组装成餐厅,做给顾客吃。"
F.2 七个核心维度的正面对撞
这是本附录的重点。逐个看"它们在每个设计点上,为什么选了相反的路"。
维度 1:编排范式 —— Loop vs Graph ★
这是最根本的分野,呼应 Part I 第 14 章。
pi:纯 Loop
- pi 的全部编排就是一个
agent-loop.ts(Part II 第 18 章) - 模型自主决定下一步:看现状 → 想 → 动手 → 循环
- 没有 graph、没有节点边、没有
.then()/.branch() - 核实证据:在 pi 源码里 grep
graph/dag/workflow/orchestrat—— 业务代码零命中
Mastra:Graph 工作流引擎
- 内置 graph-based workflow,用
.then()/.branch()/.parallel()编排 - 步骤是预先定义的,模型在节点里执行,但路线由开发者画好
- 适合:多步骤业务流程(审批、ETL、订单处理),路径需要确定可控
pi 的 Loop Mastra 的 Graph
┌─────────────────┐ ┌──────────────────────┐
│ 看现状 │ │ start │
│ ↓ │ │ ↓ .then() │
│ 模型想下一步 │ ←循环→ │ [节点A] ──.branch()─┐│
│ ↓ │ │ ↓ ↓│
│ 执行工具 │ │ [节点B] [节点C]│
│ ↓ │ │ ↓ .parallel() ↓│
│ (直到模型说停) │ │ [合并] ←──────────┘ │
└─────────────────┘ │ ↓ │
│ end │
路径:模型现场决定 └──────────────────────┘
路径:开发者预先画好🐣 小a问:"那哪个好?" 🧙 "看任务。写代码这种创造性、不可预测的活,Loop 更合适——你不知道要改几个文件、查几次。但业务流程(请假要经理批、财务复核、HR 备案)路径是固定的,Graph 更可控。pi 选 Loop 是因为它做的是前者,Mastra 提供 Graph 是因为它做的是后者。"
维度 2:RAG —— 不做 vs 核心特性
pi:不做 RAG
- 源码里
embedding/vector/retrieval业务代码零命中 - pi 帮你写代码,靠的是工具读文件(read/grep/glob),精确操作,不需要向量检索
- 核实:见 Part I 第 13 章的源码核查
Mastra:RAG 是一等公民
- "combine message history with retrieval from external databases, files, and APIs"
- 内置向量存储、语义召回
- 适合:知识库问答、客服 bot 回答产品文档、长文档检索
🧙 "pi 不需要 RAG,因为代码仓库就是它的知识库——它直接
read文件比向量召回还准。但 Mastra 服务的场景(回答海量用户的各种问题)必须靠检索。RAG 不是银弹,是特定场景的解药。"
维度 3:记忆 —— compaction vs 语义记忆
pi:截断 + 分支总结
compaction/branch-summarization.ts(Part II 第 18 章)- 上下文超了 → 把旧对话总结成摘要,腾出空间
- 记忆是"会话内的",关了就存 JSONL,下次能恢复
Mastra:语义召回 + 线程化存储
- "durable context with observational memory, semantic recall, and thread-aware storage"
- 不只是截断,还能跨会话语义召回("用户上周说过喜欢简洁风格"这种)
- 适合:长期服务的 bot,需要"记住用户"
🐣 小a嘀咕:"那 pi 是不是记性差?" 🧙 "pi 记的是'这次任务聊了啥',够用——你改完 bug 就关了。Mastra 记的是'这个用户的长期偏好',因为它要长期服务。记忆的深度,取决于服务周期。"
维度 4:MCP —— 消费方 vs 双向
pi:MCP 消费方
- pi 能调用 MCP server 提供的工具(见 Part I 第 10 章)
- 但 pi 自己不发布 MCP server
Mastra:MCP 双向
- 既消费 MCP,也能把自己的 agent/tool/resource 发布成 MCP server
- "allowing agents, tools, and structured resources to be exposed to any platform"
🧙 "Mastra 让你造的 agent 能被别的 agent 调用——它是生态节点。pi 是生态消费者。这是产品定位决定的:pi 是终端工具,不是平台。"
维度 5:可观测性 —— 基础 vs 内置
pi:基础遥测
telemetry.ts+usage-totals.ts+timings.ts(pi-ai 包内的遥测三件套)- 偏向"给用户看这次花了多少 token"
Mastra:生产级可观测
- 内置 latency / cost / token 监控
- model-graded + rule-based evals "before changes reach production"
- 面向"上线后持续监控"的生产场景
🧙 "pi 的遥测是给你个人看的(省点钱)。Mastra 的可观测是给团队/生产用的(保证服务不挂)。深度不同,因为受众不同。"
维度 6:部署 —— 本地 vs 全平台
pi:本地运行
pi命令在你电脑上跑,读你的文件、用你的 key- 容器化是可选沙箱(
containerization.md三种模式:Gondolin/Docker/OpenShell),为了隔离,不是为了部署到云
Mastra:全平台部署
- 框架可嵌入 React/Next.js/Node/Express/Hono
- 内置 Vercel/Netlify/Cloudflare 部署器
- 有 Mastra Cloud 托管(staging/preview/prod)
维度 7:多 Agent —— 单兵 vs Harness
pi:单 Agent
- 一个主 agent,不上 teams/ACP/A2A(见 Part I 第 12 章)
- 哲学:单兵作战 + 好工具,够了
Mastra:Harness 多模式
- 有 "Harness" 组件,"coordinates multi-mode agents with shared state and storage"
- 支持多 agent 协作、共享状态
🐣 小a警觉:"等等,Mastra 也有个叫 Harness 的东西?pi 里
agent/harness/不也是 harness?" 🧙 "名字一样,含义不同。pi 的 harness 是给单个 Agent 穿衣服(装上 system prompt、tools、session)——见 Part II 第 18 章。Mastra 的 Harness 是协调多个 Agent。前者是'穿衣',后者是'管团队'。别被同名骗了。"
F.3 一张总图:Agent 的两个极端
Agent 的设计光谱
本地 / 个人 / 工具 云端 / 平台 / 服务
←─────────────────────────────────────────────────────────────→
【pi-mono】 【Mastra】
┌──────────────┐ ┌──────────────┐
│ 终端 CLI 产品 │ │ TS 后端框架 │
│ 帮你写代码 │ │ 帮你造应用 │
│ │ │ │
│ • 纯 Loop │ │ • Graph 工作流│
│ • 无 RAG │ │ • RAG 核心 │
│ • 单 Agent │ │ • 多 Agent │
│ • 本地运行 │ │ • 云端部署 │
│ • MCP 消费 │ │ • MCP 双向 │
└──────┬───────┘ └───────┬──────┘
│ │
└────────── 中间地带(都可做但不擅长)──────────┘
pi 也能加 RPC 模式远程化 Mastra 也能本地跑🧙 老z总结:"这不是谁对谁错。pi 把'单兵作战'做到极致,Mastra 把'平台服务'做到极致。 它们各自牺牲了对方的强项。"
F.4 选型决策树:你该选哪个?
这是本附录最实用的部分。回答几个问题,你就知道自己该走哪条路。
决策一:你造的是"工具"还是"应用"?
你的目标是什么?
│
├─ 帮自己/团队写代码、操作本地文件
│ → 选 pi 这条路(本地 Agent)
│ → 或参考 Part III 自己造一个
│
├─ 造一个给最终用户用的服务(bot/API/网页)
→ 选 Mastra 这条路(云端框架)决策二:任务路径是"自由探索"还是"固定流程"?
任务的下一步由谁决定?
│
├─ 模型自己看着办(写代码、查资料、debug)
│ → Loop(pi 的路)
│
├─ 开发者预先画好(审批流、ETL、订单处理)
→ Graph / Workflow(Mastra 的路)决策三:需要长期记忆 / 知识检索吗?
agent 要不要"记住"海量信息?
│
├─ 不用,当前任务够用就行
│ → 截断/总结(pi 的 compaction 够了)
│
├─ 要,要回答知识库、记住用户长期偏好
→ RAG + 语义记忆(Mastra 的强项)决策四:部署给多少人?
谁在用?
│
├─ 就我自己 / 团队几个人,本地跑
│ → pi(本地,数据不出门)
│
├─ 上千用户,要稳定服务、要扩容
→ Mastra(云端,生产级)决策五:数据敏感度?
数据能上云吗?
│
├─ 不能(公司机密代码、私有 key)
│ → 本地 Agent(pi),数据留在本机
│
├─ 能(公开知识库、用户授权数据)
→ 云端框架(Mastra)更合适F.5 给本书读者的特别建议
既然你在读这本"学 pi"的书,老z有几句掏心窝的话:
🧙 "别因为 Mastra 功能多就觉得 pi 简陋。"
pi 的"简单"(纯 Loop、无 RAG、单 Agent)是刻意的设计,不是能力不足。它牺牲了 Graph 的可控性、RAG 的检索力、多 Agent 的并行,换来的是:
- 极低的认知负担(一个 loop 就懂了,见 Part III 第 26 章你只要 80 行就能写出来)
- 极高的单兵战斗力(给写代码这个场景,Loop + 好工具 > Graph + 复杂编排)
- 本地数据的掌控感(你的代码不上云)
Mastra 的"丰富"对应的是另一组代价:框架学习成本、部署运维负担、云端数据合规。功能多不等于适合你。
🧙 "学完 pi 再看 Mastra,你会秒懂它为什么长这样。"
这本书 Part I 讲的概念(Loop/Graph/RAG/多 Agent),正是 pi 和 Mastra 分道扬镳的岔路口。读懂 pi 的 Loop,你就理解了 Mastra 为什么要加 Graph——因为它的场景需要。没有对比,就没有理解。
🧙 "真要造,先从 pi 这条路起步。"
Part III 我们用 ~500 行造一个本地 Agent,是因为 Loop 路线入门最快、反馈最直接。等你能驾驭单 Agent 了,再考虑要不要上 Graph/RAG/多 Agent。YAGNI(你暂时不需要)是这本书的反复主题。
F.6 一句话总结
pi 是"独善其身"的本地利器,Mastra 是"兼济天下"的云上工厂。它们不是对手,是 Agent 设计光谱的两个端点。你的任务站在光谱的哪个位置,决定了你该往哪边走。
参考
- pi-mono 源码:本地克隆
pi-mono/packages/,本文所有 pi 论断均经源码核实 - Mastra:官网 mastra.ai(本文 Mastra 信息取自官网,2026-08 核实)
- 相关章节:Part I 第 12 章(多 Agent)、第 14 章(Loop vs Graph);Part III 第 24 章(范式选择)