Mastra Workflow 步骤实战用 createStep 创建你的第一个工作流步骤【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南基于 Mastra 官方课程中的 “Creating Your First Step” 章节带你动手创建第一个工作流步骤Step。你将学会如何使用createStep配合 Zod 定义一个带输入/输出 Schema 的文本校验步骤理解步骤中id、inputSchema、outputSchema、execute四个核心要素的作用并结合mastra/core的源码看清这些参数在底层是如何被处理和执行的从而能够独立编写可校验、可复用、可测试的 Mastra 工作流步骤。准备工作放置工作流文件按照课程约定首先在工作区的src/mastra/workflows目录下新建一个文件用于存放工作流代码。课程示例将其命名为content-workflow.ts。Mastra 项目通常约定将工作流定义集中放在src/mastra/workflows或workflows目录中便于后续注册到Mastra实例并在 Playground 中可视化调试。完整示例创建一个内容校验步骤下面是课程给出的完整步骤定义代码功能是校验传入的文本内容要求内容非空且至少包含 5 个单词否则步骤执行失败。import { createStep } from mastra/core/workflows import { z } from zod const validateContentStep createStep({ id: validate-content, description: Validates incoming text content, inputSchema: z.object({ content: z.string().min(1, Content cannot be empty), type: z.enum([article, blog, social]).default(article), }), outputSchema: z.object({ content: z.string(), type: z.string(), wordCount: z.number(), isValid: z.boolean(), }), execute: async ({ inputData }) { const { content, type } inputData const wordCount content.trim().split(/\s/).length const isValid wordCount 5 // Minimum 5 words if (!isValid) { throw new Error(Content too short: ${wordCount} words) } return { content: content.trim(), type, wordCount, isValid, } }, })这个示例覆盖了 Mastra 步骤最典型的形态纯数据变换 Schema 契约 失败即抛错。逐字段解读一个步骤由什么构成课程对示例代码的说明可以归纳为四个要点IDid步骤在整条工作流中的唯一标识符这里是validate-content。后续在.then()链式编排、Playground 查看执行轨迹时都依赖这个 id 来定位步骤。输入 SchemainputSchema声明该步骤期望接收的数据。示例要求content必填字符串且非空否则触发 Zod 错误信息Content cannot be empty和可选的type枚举值article/blog/social缺省值为article。输出 SchemaoutputSchema声明该步骤产出的数据结构——content、type、wordCount和校验状态isValid。execute的返回值必须能通过这些 Schema 的校验。执行函数execute承载实际业务逻辑的异步函数。它从执行上下文中解构出inputData统计单词数content.trim().split(/\s/).length当单词数少于 5 时抛出Error使步骤失败成功时返回一个符合outputSchema的对象。校验逻辑的三个细节输入校验发生在 execute 之前。content为空字符串时z.string().min(1, ...)会在运行时校验阶段直接给出错误信息不会进入execute函数体。.default(article)让type成为可选字段。调用方不传type时自动补为article这让步骤对上游更宽容。用抛错表达业务失败。内容过短时throw new Error(...)工作流引擎会捕获该异常并将步骤标记为失败错误信息Content too short: N words会随执行记录一起可查而不是静默返回一个“看起来成功”的结果。底层实现createStep 在源码中做了什么createStep的导出位于核心包 workflow.ts它是一个带多重签名overloads的函数既可以传入以StepParams为核心的步骤配置对象本教程的用法也可以直接传入 Agent 或 Tool 来生成 agent 步骤 / tool 步骤还能把 Processor 包装成步骤。当传入普通配置对象时实现在 createStepFromParams 中完成从源码可以看到几个关键行为Schema 统一转换为 Standard SchemainputSchema、outputSchema以及可选的stateSchema、resumeSchema、suspendSchema、requestContextSchema都会经过toStandardSchema(...)转换见 workflow.ts。这意味着 Mastra 并不只支持 Zod——任何符合 Standard Schema 规范的库都可以作为步骤的输入/输出契约Zod 只是其中最常用的选择。execute 会绑定到步骤参数对象上execute: params.execute.bind(params)保证执行函数内部的this指向稳定。返回的是一个可编排的 Step 对象类型层面通过泛型推断把inputSchema/outputSchema解析为具体的 TS 类型InferPublicSchema因此上游步骤的输出类型必须与下游步骤的输入类型匹配类型不匹配会在编译期报错。步骤参数本身的完整结构定义在 StepParams 类型中。除了课程示例用到的id、description、inputSchema、outputSchema、execute源码还揭示了若干可用但示例未涉及的可选项参数说明description步骤描述文本用于文档与调试展示retries步骤失败时的重试次数metadata附加到步骤的自定义元数据scorers步骤级的评估器scorers配置stateSchema声明跨步骤共享状态的 SchemasuspendSchema/resumeSchema支持步骤挂起/恢复human-in-the-loop场景的 SchemarequestContextSchema用于在执行前校验请求上下文request context的 Schema从StepParams的类型签名与execute的执行上下文设计可以推断execute接收的上下文对象除inputData外还携带挂起/恢复数据、请求上下文等运行时信息以便在更复杂的场景如人工审批后恢复执行中使用。本教程的示例只用到inputData已足够覆盖最常见的数据变换步骤。为什么步骤要用 Schema 声明契约示例中每个字段都有 Zod 定义这带来几个实际好处类型安全TypeScript 能从 Schema 推断出步骤输入/输出的具体类型inputData在execute内自带类型提示步骤之间串联时类型不匹配会在编译期暴露。运行时校验无论数据来自哪里API、数据库、上游 LLM 输出进入步骤前都会先过 Schema非法数据会带着明确的错误信息如Content cannot be empty被拦截。活文档Schema 本身就是对步骤输入/输出契约最精确的说明配合description字段新接手代码的人能快速理解数据流。可调试清晰的契约让“数据在哪个环节变坏”变得可定位——每个步骤的输入输出都有 Schema 背书排查问题时只需对比失败步骤的输入与预期。同时步骤是天然可复用、可测试、可组合的单元validateContentStep不依赖任何外部服务可以直接在测试中单独执行验证其逻辑也可以被不同工作流复用。下一步把这个步骤用起来完成本课后validate-content步骤已经可以独立运行。按照 Mastra 官方课程的后续章节继续推进在 创建第二个步骤 中为工作流增加转换类步骤体验步骤间的数据流在 串联步骤 中用.then()把校验步骤和后续步骤编排成链在 注册到 Mastra 实例 中把整条工作流挂到Mastra实例上并通过 Playground 做可视化调试在 以编程方式运行工作流 中学习workflow.create()与start()的调用方式。也可以直接查阅课程中 理解工作流 与 理解步骤 两篇回顾概念基础或在核心包测试 workflow.test.ts 中查看createStep与步骤编排在真实测试用例里的用法。小结通过本教程你已经掌握了 Mastra 工作流的最小可行单元在src/mastra/workflows下创建content-workflow.ts用createStep定义一个带id、description、inputSchema、outputSchema和execute的校验步骤理解 Schema 契约带来的类型安全与运行时校验以及“业务失败即抛错”的约定了解源码层面createStep如何把 Schema 转换为 Standard Schema、如何推断类型并绑定执行函数以及StepParams提供的重试、挂起/恢复等进阶能力。第一个步骤就绪后接下来就可以着手把它与更多步骤组合成一条完整的可执行工作流。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考