📚 编程进阶教程站

第 7 章 · Workflow 基础与 .then() ​

本章目标：理解 Workflow 与 Agent 的分工边界，掌握 createStep / createWorkflow / .then() 构建串行流水线。

7.1 Agent vs Workflow：何时用哪个 ​

AgentWorkflow
执行路径模型自主决策，不可预知显式定义，图结构确定
适用任务开放式问题（"帮我写个方案"）确定性流程（"抓取→清洗→入库"）
可靠性依赖提示词与模型能力步骤 schema 强约束，结果可预测
调试看完整 Trace 推理过程图形化查看每步输入输出

经验法则：路径可预测的流程用 Workflow，需要模型判断的环节才嵌入 Agent。两者常常组合使用。

7.2 createStep：定义步骤 ​

步骤是 Workflow 的积木。每个步骤用 Zod 声明输入/输出 schema，形成类型安全的管道接口：

typescript
// src/mastra/workflows/article-workflow.ts
import { createStep } from '@mastra/core/workflows';
import { z } from 'zod';

// 步骤一：接收主题，产出提纲
const outlineStep = createStep({
  id: 'outline',
  inputSchema: z.object({
    topic: z.string().describe('文章主题'),
  }),
  outputSchema: z.object({
    outline: z.string(),
    topic: z.string(), // 透传给下游
  }),
  // execute 的入参 inputData 类型由 inputSchema 自动推导
  execute: async ({ inputData }) => {
    const { topic } = inputData;
    // 实际项目中这里可调用 LLM、API 或任意函数
    return {
      outline: `${topic} 的三段式提纲：背景 → 分析 → 结论`,
      topic,
    };
  },
});

7.3 createWorkflow + .then()：串联执行 ​

typescript
// 同文件：第二个步骤消费上游输出
const draftStep = createStep({
  id: 'draft',
  inputSchema: z.object({
    outline: z.string(),
    topic: z.string(),
  }),
  outputSchema: z.object({
    article: z.string(),
  }),
  execute: async ({ inputData }) => ({
    article: `《${inputData.topic}》\n\n根据提纲撰写正文：${inputData.outline}`,
  }),
});

// 组装工作流：声明整体输入输出 → 链接步骤 → commit 收尾
export const articleWorkflow = createWorkflow({
  id: 'article-workflow',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ article: z.string() }),
})
  .then(outlineStep) // 先执行 outlineStep
  .then(draftStep)   // 其输出自动作为下一步输入
  .commit();         // 必须调用，锁定流程图

关键机制：.then() 会把上一步的 outputSchema 作为下一步的校验入参——如果两个步骤的 schema 不匹配，在组装期就会报错，这正是"schema 即契约"的价值。

7.4 注册与触发 ​

typescript
// src/mastra/index.ts —— 注册 workflow
import { Mastra } from '@mastra/core';
import { articleWorkflow } from './workflows/article-workflow';

export const mastra = new Mastra({
  workflows: { articleWorkflow },
});
typescript
// 触发方式一：代码中直接创建运行实例
const run = await mastra.getWorkflow('articleWorkflow').createRun();
const result = await run.start({ inputData: { topic: '大语言模型' } });
console.log(result.results); // 各步骤输出

也可以在 Studio 的 Workflows 页签中手动填入触发参数、图形化观察每步流转。

本章小结 ​

  • 开放式任务交给 Agent，确定性流程交给 Workflow，复杂系统二者组合；
  • createStep 用 Zod 双向声明输入/输出，execute 只写业务逻辑；
  • .then() 串行链接并自动做 schema 匹配检查，.commit() 锁定流程；
  • workflow 同样要在 Mastra 实例注册，支持代码 createRun 与 Studio 手动触发。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 下列哪种任务最适合用 Workflow 而不是 Agent 实现？

2. .then() 链接步骤时，框架如何保证步骤间兼容？

3. createWorkflow 定义完成后，收尾必须调用的方法是？

4. workflow 步骤的 execute 函数中获取上游数据的正确方式是？

🛠️ 动手实践 ​

  1. 给 articleWorkflow 追加第三个步骤 reviewStep：输入草稿，输出带评分的结构体。
  2. 故意让 draftStep 的 outputSchema 与 reviewStep 的 inputSchema 字段不匹配，观察组装期报错信息。
  3. 在 Studio 中打开你的 workflow，截图 Graph 视图并与代码中的 .then() 顺序对照。

下一章：第 8 章 · 分支与并行执行