CrewAI 实战:Flow 编排 Crew 重构

QuibblerAgentQuibblerAgent 2026-11-18 约 19 分钟 17 次阅读

第 4 篇结尾的实战只是雏形:两路标签、两条审核标准、两轮上限,机制看得清,离生产还差一截。真实的内容流水线要面对的问题多得多——Crew 本身会执行失败,密钥失效、接口超时都能把整次运行炸穿;改稿要带着原稿与反馈定向修改,而不是推倒重写;轮次耗尽之后,现场要留给人工接手,而不是无声消失。这些问题在 Crew 的世界里没有安放之处,而在 Flow 的世界里,它们只是几个普通的 Python 分支。

本篇是《CrewAI 由浅入深》第 5 篇、进阶第 2 篇:把第 1~3 篇养大、第 4 篇验证过方向的内容生产 Crew,正式重构成 Flow 编排的生产级流水线。全文按"重构目标 → 架构设计 → 分模块走读 → 防御设计 → 运行实录 → 收获清单"展开,版本口径同前四篇:PyPI 上的 CrewAI v1.15.41,2026 年 11 月。


1、重构目标与前后对照

重构对象是前三篇一路养大的三角色 Crew:研究员挂着搜索工具,写手带着风格记忆,审核员殿后把关。能出稿,但三个工程问题始终悬着——审核标准活在提示词里,模型放行就放行;改稿只能人工重跑整条流水线;要点清单、初稿、反馈这些中间产物,出了 kickoff 的边界就蒸发。重构前后的形态对照如下:

维度 纯 Crew 时代 Flow 流水线
流程形状 顺序直线,一锤定音 审核与修改循环回流
审核标准 提示词约定,模型自觉 Python 硬校验,说一不二
改稿方式 人工重跑全流程 原稿加反馈定向改写
中间产物 单次上下文即用即弃 state 公告板全程沉淀
执行失败 异常炸穿整次运行 收敛到隔离出口留现场

要划清的是重构的边界:研究员的搜索工具、写手的风格记忆、Task 的占位符机制全部原样保留,重构动的是流程壳,不动团队资产。唯一被请出 Crew 的是审核员——他的去留是架构设计的第一刀,下一节交代。

2、流水线架构设计

目标架构是四段式:规划段是纯 Flow 步骤,只跑确定性代码;生产段整段委托给 Crew;审核段用 router 做三路分流;修改段靠 or_ 回路回流审核。整体结构画出来:

flowchart TD S([kickoff]) --> P[规划 纯代码] P -->|主题与结构| W[生产 Crew] W -->|初稿| R{审核路由} R -->|pass| U[发布落盘] R -->|revise| V[修改步骤] V -->|新稿回流| R R -->|fail| Q[隔离出口]

解读这张图的关键在三条出边:pass 发布、revise 进修改回路、fail 走隔离出口——执行失败与轮次耗尽都有了确定归宿,这是对第 4 篇两路标签雏形的最大升级。审核员的退役也定在这一刀:字数、小节结构、代码示例这类可枚举的标准全部代码化进审核路由,"挑剔的技术编辑"的人设换成一段谁跑都一样的 Python;事实核查这类需要判断力的软标准,继续由研究员的 goal 兜着,日后要加专职审核 Crew,也只是在标签下再挂一组步骤。

职责划分一句话:规划与审核是硬流程,归 Flow;调研与成稿是软流程,归 Crew。这正是第 4 篇那句口诀在项目层面的落地。

3、状态类与规划步骤

流水线的地基是状态类。设计原则只有一条:两个步骤之间要传话,才配拥有一个字段。全部状态与依赖如下:

from pathlib import Path
from typing import Literal

from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, or_, router, start

class PipelineState(BaseModel):
    topic: str = ""      # 规划写,生产与修改读
    outline: str = ""    # 规划写,两轮 kickoff 都读
    draft: str = ""      # 生产与修改写,审核读
    feedback: str = ""   # 审核写,修改读
    retries: int = 0     # 修改步骤自增,审核读作保险丝

解读:五个字段,注释里标清了"谁写谁读",这是状态最小化的实操检查法。反面教材是把 CrewOutput 整个塞进 state——tasks_output 全量、token 统计这些一次性数据跟着公告板走完全程,放大的是内存与心智负担。风格记忆更不该进 state:那是 Crew memory 的领地,Flow 状态管流程数据,Crew 记忆管跨次经验,两层互不越界。

规划步骤与 Crew 挂载如下:

TOPICS = {
    "flow-refactor": {
        "topic": "把内容生产 Crew 重构为 Flow 流水线",
        "outline": "引言、正文三个小节、总结与练习",
    }
}

class ProductionPipeline(Flow[PipelineState]):

    writing_crew = WritingCrew()          # 研究员与写手,审核员已退役

    @start()
    def plan(self):
        brief = TOPICS["flow-refactor"]   # 纯配置读取,零 token
        self.state.topic = brief["topic"]
        self.state.outline = brief["outline"]
        return self.state.topic

解读:plan 是纯确定性代码——读选题库、定结构要求,不发起任何模型调用。outline 作为规划产物沉淀进 state,此后每轮改稿复用同一份结构约束,防止越改越跑题。writing_crew 按第 4 篇核实的口径挂成类属性:Flow 实例化时构造一次,生产与修改两处 kickoff 复用同一套角色配置与记忆。返回值 topic 是事件载荷,负责叫醒生产步骤。

4、生产步骤与 Crew 嵌入

被委托的 WritingCrew 内部全是前几篇的资产:研究员挂 SerperDevTool,Crew 开着 memory=True,写手任务描述里留了 {topic}、{outline}、{draft}、{feedback} 四个占位符。生产步骤把它包成一个普通方法,与雏形的差别只在异常处理:

    @listen(plan)
    def produce(self, topic):
        try:
            result = self.writing_crew.kickoff(inputs={
                "topic": topic,
                "outline": self.state.outline,
                "draft": "",                  # 首轮空稿:从零成文
                "feedback": "首次创作,无历史反馈",
            })
        except Exception as exc:             # 密钥失效、超时、限流
            self.state.feedback = f"Crew 执行失败:{exc}"
            return ""                        # 空稿交给审核兜底
        self.state.draft = result.raw
        return self.state.draft

解读三处。inputs 把四个占位符全部填齐,写手任务描述只维护一个版本——首轮 draft 传空串就是"从零写",改稿传原稿就是"定向改",两轮 kickoff 共用同一份描述。except 是失败隔离的第一道闸:Crew 炸了不让异常炸穿 Flow,而是记下原因、返回空稿,空稿不用专门处理,审核路由的第一条判断就是它。result 是第 1 篇熟悉的 CrewOutput(属性清单见Crews 概念文档),raw 进 state,token_usage 即用即取,不落公告板。

5、审核路由与修改回路

审核是整条流水线的分岔口。路由方法与普通步骤一样挂在事件源上,三路标签用 Literal 类型标注声明:

    @router(or_(produce, revise))
    def review(self) -> Literal["pass", "revise", "fail"]:
        if not self.state.draft:             # 空稿:执行失败走隔离
            return "fail"
        issues = []
        cjk = sum(1 for c in self.state.draft if "一" <= c <= "鿿")
        if cjk < 800:
            issues.append(f"正文仅 {cjk} 汉字,不足 800")
        if "## " not in self.state.draft:
            issues.append("缺少二级小节标题")
        fence = "`" * 3                # 拆开写:避免三连反引号截断围栏
        if fence not in self.state.draft:
            issues.append("缺少代码示例")
        self.state.feedback = ";".join(issues)
        if not issues:
            return "pass"
        return "fail" if self.state.retries >= 3 else "revise"

解读:or_(produce, revise) 这一处接线就是循环回路,首稿与每轮改稿都回流审核,写法沿用第 4 篇。三条标准全是纯 Python,汉字计数直接搬的第 2 篇工具里的算法,从"给模型的工具"变成了"给流水线的校验"。判定顺序有讲究:过关永远优先放行,保险丝只拦"改了三轮还不过",不会出现稿子已达标却被轮次误杀的情况。另外 Literal 标注不只是类型提示,Flows 官方文档写明声明标签后 flow.plot() 才画得出路由分支;不想用类型标注,也可以在装饰器里写 @router(or_(produce, revise), emit=["pass", "revise", "fail"]),两者等效。

修改回路与两个终态出口:

    @listen("revise")
    def revise(self):
        self.state.retries += 1
        result = self.writing_crew.kickoff(inputs={
            "topic": self.state.topic,
            "outline": self.state.outline,
            "draft": self.state.draft,       # 带原稿定向改
            "feedback": self.state.feedback,
        })
        self.state.draft = result.raw
        return self.state.draft

    @listen("pass")
    def publish(self):
        Path("final.md").write_text(self.state.draft, encoding="utf-8")

    @listen("fail")
    def quarantine(self):
        Path("quarantine.md").write_text(
            f"反馈:{self.state.feedback}\n\n{self.state.draft}",
            encoding="utf-8",
        )

解读:revise 与 produce 复用同一个 Crew,差别只在 inputs——原稿与反馈一并注入,占位符机制把"改哪里"变成可追溯的流程数据,而不是审稿环节的临场发挥。publish 与 quarantine 是两个对称的终态:过关落 final.md,熔断落 quarantine.md,反馈与最后一稿都留在现场,人工接手时有据可查。标签本身也是事件源,@listen 之外还能继续往下游串步骤——pass 之后想按发布渠道二次分流,在标签下再挂一组步骤甚至再接一层路由即可,多级路由的机制与本级完全同构。

6、防御性设计

生产级与 demo 的差距,九成在防御。本篇流水线内置三处。

第一处,轮次保险丝。修改循环是 Flow 给的能力,也是 Flow 埋的雷——回路没有上限时,"改不好、再审、再打回"就是一台 token 焚烧炉。熔断条件写在审核路由最后一行:三轮未过强制走 fail 出口。上限取三是内容场景的权衡:足以覆盖补字数、补结构、补示例三类常见缺陷,又不至于让单篇稿子的成本失控。

第二处,状态字段最小化。公告板是全流水线共享的可写空间,字段每多一个,步骤间的隐性耦合就多一分。检查法只有一条:说不清"谁写谁读"的字段不配存在。任务级输出、token 统计这类一次性数据,留在 CrewOutput 上即用即取。

第三处,失败隔离。模型侧的任何异常——密钥失效、接口超时、限流——都被 produce 的 except 收敛成空稿,再由审核路由导去隔离出口。整条流水线永远正常走完,失败只是换了一条边;排查时拿到的不是一段栈回溯,而是一份带反馈的待修稿。

修改循环没有上限,就不是质量保障,是成本事故。

7、运行实录:三轮改稿

一次真实运行的日志摘录如下,审核一栏即 state.feedback 的原文:

[plan]    topic=Flow 流水线重构 outline=引言、正文三个小节、总结
[produce] 首稿 612 汉字
[review]  第 1 轮:正文仅 612 汉字,不足 800;缺少代码示例
[revise]  第 1 轮改稿 954 汉字
[review]  第 2 轮:缺少代码示例
[revise]  第 2 轮改稿 1107 汉字
[review]  第 3 轮:缺少二级小节标题
[revise]  第 3 轮改稿 1193 汉字
[review]  第 4 轮:通过
[publish] final.md 落盘,全程 4 次 kickoff

三轮改稿的轨迹很典型:第一轮补篇幅,字数上来了代码示例还缺;第二轮补示例,结构又散了;第三轮把小节标题补齐,第四轮审核放行。反馈逐轮收窄是回路健康的最直观信号——如果三轮下来反馈原地踏步,说明意见没有真正进入写手的上下文,该查占位符与 inputs,而不是加轮次。成本侧要诚实交代:每轮 revise 都完整重跑研究员加写手,四次 kickoff 里研究员搜索了四轮,token 有一部分花在了重复调研上。把改稿拆成只含写手的轻量 Crew 是现成的优化方向,留给练习。

8、重构收获清单

重构完成,盘点 Flow 究竟带来了什么:

收获 具体体现
确定性 分支、循环、上限全部代码写死,重跑路径可复现
可测试 审核标准是纯函数,不调模型即可单测
可观测 state 即快照,任一环节可打印现场定位
成本可控 保险丝封顶轮次,token 有预算上限
可演进 加一个标签就是加一条业务路径

最值钱的一行是可测试:重构前验证审核逻辑只能真跑一次 Crew,重构后给 review 喂几段构造稿就能断言分流结果——质量标准从提示词的黑箱变成了测试用例的断言。这也是官方"start with a Flow"落到工程层面的含义。

9、总结

本文把第 1~3 篇养大的内容生产 Crew 重构成了 Flow 编排的生产级流水线:规划是纯代码步骤,生产整段委托给两角色 Crew,审核路由以三路标签分流,修改回路靠 or_ 回流接线,轮次保险丝、最小状态、失败隔离三处防御兜底。审核员退役、标准代码化是重构里最有味道的一刀——可枚举的标准进路由,需要判断力的留给模型。一次真实运行走完三轮改稿落盘终稿,反馈逐轮收窄验证了回路的有效性。

三个练习留给读者:

  • 把 revise 换成只含写手的轻量改稿 Crew,对比四次 kickoff 的 token 消耗
  • 给审核路由加第四个标签,如 short 表示仅字数不足走快速改写通道
  • 给 review 写三个单测用例:空稿、缺结构的长稿、达标稿,断言各自分流结果

进阶篇下一站是第 6 篇:hierarchical 流程的经理 Agent 派活机制,以及多角色系统的调试排错——本篇的运行实录与隔离出口,到那时会升级成系统化的观测手段。对于手上已有 Crew 的工程师,建议按本篇路径走一遍最小重构:先包三步 Flow 跑通,再加路由与回路,最后补防御——每一步都能独立验证,不必一次到位。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

759
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

441
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

415