Mastra Workflows 核心概念：深入理解 Step（步骤）的架构、Schema 契约与执行机制

Mastra Workflows 核心概念深入理解 Step步骤的架构、Schema 契约与执行机制【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读Step步骤是 Mastra Workflows 中最基本的构建单元每一个步骤都是一个自包含的、接收输入、处理逻辑并产生输出的独立模块。本文以 Mastra 官方课程《Understanding Steps》为主线结合mastra/core的真实源码实现系统讲解 Step 的三大组成部分输入 Schema、输出 Schema、Execute 函数、Schema 契约带来的类型安全与运行时校验能力以及 Step 可复用、可测试、可组合、可追踪的设计优势帮助你从会用createStep进阶到理解 Mastra Workflow 引擎如何驱动每一个步骤。读完本文你将掌握 Step 的定义规范、execute 上下文的完整能力面以及它与 Agent、Tool 的底层关系。什么是 Step在 Mastra 的 Workflow 体系中Step 是工作流的基本构建块。从源码层面看Step 被建模为一个强类型的接口定义在 packages/core/src/workflows/step.tsexport interface Step TStepId extends string string, TState unknown, TInput unknown, TOutput unknown, TResume unknown, TSuspend unknown, ... { id: TStepId; description?: string; inputSchema: StandardSchemaWithJSONTInput; outputSchema: StandardSchemaWithJSONTOutput; resumeSchema?: StandardSchemaWithJSONTResume; suspendSchema?: StandardSchemaWithJSONTSuspend; stateSchema?: StandardSchemaWithJSONTState; execute: ExecuteFunctionTState, TInput, TOutput, TResume, TSuspend, ...; scorers?: DynamicArgumentMastraScorers; retries?: number; component?: string; metadata?: StepMetadata; }一个 Step 有三个主要部分Input Schema—— 它期望接收什么样的数据Output Schema—— 它将产生什么样的数据Execute Function—— 把输入转换为输出的核心逻辑。官方课程对这三者的定义在 Mastra 的Step接口源码中得到了完整印证inputSchema、outputSchema是必填的契约属性execute则是唯一负责干活的执行函数。此外源码还暴露了课程中未展开的进阶字段如resumeSchema、suspendSchema、stateSchema、retries等我们将在后文逐一说明。Step 的标准结构createStep每个 Step 都遵循统一的创建模式通过createStep工厂函数定义const myStep createStep({ id: unique-step-name, description: What this step does, inputSchema: z.object({ // Define expected input structure }), outputSchema: z.object({ // Define output structure }), execute: async ({ inputData }) { // Your logic here return { // Return data matching output schema } }, })从源码看createStep并不是一个简单的对象打包器而是一个多重载的分发工厂。在 packages/core/src/workflows/evented/workflow.ts 中它的实现按参数类型做了运行时判别export function createStep(params: any, agentOrToolOptions?: any): Stepany, any, any, any, any, any, any { if (isAgentCompatible(params)) { return createStepFromAgent(params, agentOrToolOptions); } if (isToolStep(params)) { return createStepFromTool(params, agentOrToolOptions); } if (isProcessor(params)) { return createStepFromProcessor(params); } if (isStepParams(params)) { return createStepFromParams(params); } throw new Error(Invalid input: expected StepParams, Agent, ToolStep, or Processor); }这意味着createStep除了接收上文展示的标准StepParams{ id, description, inputSchema, outputSchema, execute }之外还支持三种快捷包装重载从 Agent 创建 Step直接传入一个Agent或SubAgent输入自动约定为{ prompt: string }输出默认为{ text: string }也可通过structuredOutput: { schema }指定结构化输出见 step-factories.ts从 Tool 创建 Step传入一个已定义inputSchema与outputSchema的 Tool即变成一个可编排的步骤若 Tool 缺少任一 Schema工厂会直接抛出Tool must have input and output schemas defined错误见 step-factories.ts从 Processor 创建 Step将具备processInput/processOutput等方法的 Processor 包装为processor:id形式的步骤。因此课程中的标准createStep({ ... })写法实际走的是最后一个分支createStepFromParams它会把inputSchema、outputSchema等通过toStandardSchema统一转换为标准 Schema 格式并将execute绑定为 Step 的执行函数见 evented/workflow.ts。认识 execute 的完整上下文官方课程的示例只使用了execute: async ({ inputData }) { ... }。但在 Mastra 的真实执行环境中execute接收的是一个内容丰富的上下文对象其类型ExecuteFunctionParams定义于 packages/core/src/workflows/step.ts。核心字段包括字段类型说明inputDataTStepInput当前步骤的输入由上游步骤输出或工作流初始输入提供runIdstring本次工作流运行的唯一 ID可用于追踪workflowIdstring当前所属工作流的 IDmastraMastraMastra 运行时实例可访问注册的 Agent、Tool 等state/setStateTState/(state) Promisevoid步骤级共享状态的读写retryCountnumber当前已重试次数配合retries使用getStepResult(step)函数按步骤 id 或 Step 对象获取某一步的成功输出仅当该步骤status success时返回见 step.tsgetInitData()函数获取工作流初始输入数据suspend/resume函数 / 对象挂起步骤并等待外部恢复配合suspendSchema/resumeSchemabail(result)函数提前终止步骤并返回结果abort()函数中止步骤执行abortSignalAbortSignal标准 Abort 信号便于实现可取消逻辑engineEngineType当前工作流引擎类型默认为DefaultEngineTyperequestContextRequestContext请求级上下文writer/outputWriterToolStream/OutputWriter流式输出相关能力这意味着一个标准 Step 的execute不仅能做纯函数式的输入输出转换还能在必要时读取其他步骤的结果、读写共享状态、访问 Mastra 实例、支持挂起/恢复和取消——这些都是在设计复杂工作流时可以调用的底层能力。为什么使用 Schema在 Step 中强制声明inputSchema与outputSchema并非形式主义而是为工作流带来四重收益类型安全Type SafetyTypeScript 能够精确推断在步骤之间流动的数据类型。当你编写.then(stepA).then(stepB)时编译器会依据stepA的outputSchema与stepB的inputSchema校验数据流是否匹配。从源码看createStepFromParams会把泛型参数TInputSchema、TOutputSchema映射为InferPublicSchemaTInputSchema等推断类型从而把运行时 Schema 直接翻译成编译期类型。运行时校验Runtime Validation非法数据会在进入步骤的瞬间被拦截并给出可读的错误信息。Mastra 内部将所有 Schema 统一转换为标准 SchemaStandardSchemaWithJSON通过toStandardSchema转换工作流在运行时会对输入数据、步骤输出与最终输出做自动校验。文档化DocumentationSchema 本身就是工作流的活文档。一个z.object({ content: z.string().min(1) })比任何注释都更精确地描述了数据契约。可调试Debugging清晰的输入/输出契约让数据流中的问题可以被快速定位——错误要么出在生产方的返回值要么出在消费方的期望值边界一目了然。Step 的核心设计优势官方课程总结了 Step 的五项关键优势它们共同构成了为什么用 Step 而非直接写函数的理由可复用ReusableStep 是自包含单元可以按需组合进多个不同的工作流。因为一个 Step 只通过 Schema 与外部交互不绑定某个具体工作流实例天然具备跨工作流复用的能力。可测试Testable每个 Step 都能脱离工作流独立测试——给它一份符合inputSchema的数据断言其输出是否符合outputSchema即可。这正是课程后续章节Creating Your First Step中先独立写好 Step 再链入工作流的实践基础。可组合ComposableStep 可以通过.then()等方式以不同顺序、不同拓扑组合成完整工作流。课程 Chaining Steps Together 展示了标准的链式写法createWorkflow({ ... }).then(validateContentStep).then(enhanceContentStep).commit()数据按声明顺序依次流动。可靠ReliableSchema 在数据进入每个环节前就拦截问题。结合retries字段源码中 Step 支持声明重试次数和retryCount上下文可在一定程度上对抗瞬时失败。可追踪Traceable每个 Step 都被纳入工作流运行追踪。Mastra 的运行机制会为每次执行生成runId步骤执行会发布对应的事件流例如workflow.events.v2.runId通道上的运行事件见 evented/workflow.ts从而可以在运行时观察数据在步骤之间的流动路径。Step 在工作流中的运行方式要真正理解 Step还需要知道它被放进 Workflow 后是如何被驱动的。课程 Understanding Workflows 入门篇 与 Chaining Steps Together 说明了数据流的基本规则工作流接收符合其inputSchema的初始输入第一个 Step 处理输入并输出符合其outputSchema的数据第二个 Step 接收第一个 Step 的输出作为自己的输入工作流返回最后一个 Step 的输出并校验其是否符合工作流的outputSchema。在链条的每个节点运行时都会自动完成三类校验工作流输入是否符合工作流的 inputSchema、上游步骤输出是否符合下游步骤的 inputSchema、最终输出是否符合工作流的 outputSchema。从源码角度步骤输出会以StepResult的形式被记录在运行结果中见 step.ts 中getStepResult对stepResults的读取逻辑只有当某一步的状态为success时其结果才对后续步骤可见——这保证了步骤间数据传递的确定性与可审计性。从理解到实践下一步做什么理解了 Step 的定义、Schema 契约和执行上下文之后就可以进入实战环节。官方课程为你规划了一条循序渐进的实践路径创建你的第一个 Step在src/mastra/workflows/content-workflow.ts中用createStep实现一个内容校验步骤输入content字符串与type枚举输出带wordCount、isValid的校验结果创建第二个 Step新增enhanceContentStep为已校验内容补充阅读时长、难度等元数据将 Step 链成工作流用createWorkflow({ ... }).then(...).then(...).commit()将两个 Step 串成完整的contentWorkflow并验证 Schema 校验在输入、步骤间、输出三个层面的生效情况后续课程还会带你逐步学习注册到 Mastra、使用 Playground 调试、以编程方式运行工作流以及并行执行、条件分支等进阶编排能力。小结Step 是 Mastra Workflow 的最小执行单元也是整个编排体系的基石。它通过inputSchema、outputSchema、execute三要素把数据契约与执行逻辑清晰分离Schema 提供编译期类型安全、运行时校验、活文档与调试依据execute则在丰富的上下文中完成实际业务逻辑并借助retries、state、suspend/resume、getStepResult等能力支持复杂场景。而createStep的多重载设计让 Agent、Tool 与普通函数逻辑都能被统一封装为 Step这正是 Mastra Workflow 灵活编排能力的底层来源。相关源码路径速查Step 接口与执行上下文类型packages/core/src/workflows/step.tscreateStep多重载与分发实现packages/core/src/workflows/evented/workflow.tsAgent / Tool / Mapping 步骤工厂packages/core/src/workflows/step-factories.ts工作流定义与编排入口packages/core/src/workflows/workflow.ts官方课程下一篇Creating Your First Step【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考