migrating-mastra-to-pydantic-ai

将 Mastra 迁移到 Pydantic AI

保留可观察到的行为，而不是 TypeScript 或 Mastra 的对象模型。迁移最小的完整调用路径，并保留现有应用基础设施。

先追踪源实现，再选择目标

1. 阅读仓库说明、依赖、测试和运行时入口。记录已安装的 Mastra、Pydantic AI 和 Harness 版本。
2. 从公开入口追踪一个真实请求：无论是 Agent.generate() / Agent.stream() 调用，还是工作流运行，都要追踪其使用的工具、处理器、记忆、事件、结果、状态和副作用。建立聚焦的基线或特征测试。
3. 分别梳理以下源契约（如存在）：
   • 请求上下文、由模型选择的工具输入、工作流输入/输出以及共享工作流状态；
   • 对话消息、语义回忆、工作或观察记忆、工作流快照以及由模型管理的计划；
   • 最终文本或对象、Token 增量、生命周期事件、跳闸保护以及工作流终止状态；
   • 工具审批、经身份验证的授权以及进程或沙箱隔离；
   • 确定性工作流、由 Agent 选择的委派、队列、计划任务以及持久化执行。
4. 记录每项观察到的契约、其所属方、语义差异和可执行的证明。未使用的 Mastra 功能不属于迁移范围。

对于检测到的源功能，请阅读 研究与概念映射。实现前请阅读 验证与切换。

选择最小目标

• 核心： 使用 pydantic_ai.Agent 实现 Agent 循环、类型化依赖、工具、输出、规范化消息、通用钩子、流式处理、MCP 客户端、审批、使用量限制、检测、实时功能和持久化运行时集成。
• 图： 仅在显式类型化节点、分支和合并仍有用时使用 pydantic_graph；简单的固定控制流使用普通异步 Python。
• Harness： 仅当观察到可复用策略时才添加 pydantic-ai-harness，例如记忆笔记本、规划、由模型指挥的子 Agent、Agent Skills、编码工具、护栏、与模型无关的压缩策略或步骤持久化。Harness 功能通过核心 Agent 循环进行组合；Harness 不是工作流引擎，也不是第二个运行时。
• 评测： 对于观察到的数据集、用例和评估器，添加独立的 pydantic-evals 包。
• 应用： 保留身份验证、数据库、向量搜索、队列、计划任务、部署、产品状态、API/UI 传输、会话查询和租户策略，除非请求的切片明确包含这些内容。
• 差距： 指明没有受支持的公开接口能够保留的行为，说明其影响，并测试范围明确的适配器。不要仅为掩盖差异而复刻 Mastra 注册表、服务器、存储架构或事件分类体系。

常规迁移方式是使用一个可复用的 Agent，通过类型化依赖提供应用服务，使用常规 Pydantic AI 工具，在调用方需要结构化数据时使用类型化输出，并由应用负责存储 result.all_messages() 以供后续轮次使用。通过小型适配器保留现有 HTTP、作业或 UI 边界及其当前字段名称。如果 Mastra 调用仅在进程内发生，则在同一切片中迁移其最近的调用方，或明确商定新的、由应用负责的服务边界；默认不要添加传输层。

应用高风险门槛

• Mastra RequestContext 是可信运行上下文，而不是模型输入。将经过身份验证的身份和服务映射为类型化依赖项；仅将模型选择的值作为工具参数公开。
• Mastra 内存包含不同的行为。将线程消息映射为序列化的 Pydantic AI 消息历史记录，将语义检索保留在应用服务或工具之后；仅当 Harness Memory 的模型自主笔记本语义能够保留已观察到的工作内存契约时才使用它。对于现有 Mastra 记录，应明确选择并测试一次性转换、只读适配器，或将从头开始作为一项已接受的变更。不要将消息历史、笔记本或 Harness StepPersistence 视为工作流快照。
• Mastra 工作流是确定性的应用控制流。使用纯 Python 或 pydantic_graph；不要将 .branch()、.parallel()、.foreach()、循环或挂起条件移入 Agent 提示词。明确保留并发、聚合、故障和取消语义。
• Mastra 工作流挂起时会持久化可恢复的快照。将分支和工作流状态的持久化保留在应用或底层持久化引擎中，并验证能否从承诺的步骤重新启动。Pydantic AI 持久化集成可使工作流中的 Agent 模型、工具和 MCP 操作持久化；但它们不负责工作流外围的控制流。延迟工具保留 Agent 工具调用，而非任意工作流状态。
• 根据触发时机、输入／输出变更、熔断行为、执行顺序、流式可见性和持久化映射处理器。选择范围最窄的方案：核心历史处理器、输出验证器、钩子、Harness 输入／输出／工具防护栏、自定义能力或应用适配器；并对调用方可见的事件或错误进行黄金测试。
• 审批会暂停已验证的操作；它不会验证审批者的身份。在应用中保留身份、授权、审计、关联和幂等性，并验证审批前不会执行操作。
• 映射流式处理的使用方意图。Pydantic AI 输出流式处理、运行事件流式处理、UI 适配器和图迭代是不同的接口；它们都不保证采用 Mastra 的 fullStream 分块分类。
• 仅将 Harness SubAgents 用于模型指导的委派。将确定性扇出、聚合、重试和评分器驱动的验证循环保留在应用或图代码中。
• Mastra Agent Skills 可能包含引用并支持动态解析。Harness Skills 仅按需加载 SKILL.md 指令，不会自动扫描 .agents 或 .claude；对于必需引用，请使用 Harness FileSystem 或应用工具，并单独测试每次请求的选择行为。
• Mastra Studio、服务端适配器、存储提供程序、部署目标、日志、跟踪存储和实时评估调度都属于产品基础设施。应有意保留或替换它们，而不要将 Agent 迁移视为与之等同。
• Mastra 持久化 Agent、工作流时间旅行、精确快照兼容性、观察式内存压缩和精确原始事件标识，除非已证明存在适用于已观察调用方的受支持目标扩展点，否则都属于能力缺口。

实现并验证一个垂直切片

1. 保留受支持的调用方边界，只替换由 Agent 管理的内部实现。
2. 从核心功能开始。只有在源契约要求时，才添加 pydantic_graph、Harness、Pydantic Evals 或持久化运行时。
3. 在该边界测试输入、类型化输出、错误、事件顺序、工具参数/结果、处理器决策、跨轮次状态和副作用。离线时使用确定性模型和模拟应用服务；只有当提供方行为属于契约内容时，才添加有针对性的录制测试或实时测试。
4. 对于持久化、审批、并发工作流或外部副作用，应在 Mastra 承诺的确切边界测试中断与重启、谱系、授权、故障聚合和幂等性。
5. 只有在不再有任何保留路径依赖它们后，才移除 @mastra/*、Mastra 服务端设置以及 Mastra 存储或事件适配器。

实现前，解释任何影响重大的语义变更：说明源行为、目标行为、对调用方的影响、建议的选择以及剩余风险。

完成

按照验证与切换中的完成标准执行。准确标注来自模拟、录制和实时提供方的证据。