CrewAI 多智能体 Unity 自动开发项目的三轮迭代复盘

这是一篇技术讨论文章不是产品宣传。我把 MyCrew 项目从 v1一个 CrewAI 模板 demo到 v2弃用的桌面应用再到 v3当前 188 commits、约 6 万行代码的 Tauri FastAPI 工程的全部弯路、踩坑、反思摆开来谈希望能对正在用 CrewAI / LangGraph 做AI 全链路代码生成的同行有参考价值。一、项目目标与最终面对的现实项目立项的口号用 CrewAI 多智能体编排 Unity MCP让 AI 从一句话需求自动产出可玩的 Unity 游戏。两个月后能给出的真话能做到单个 C# 脚本生成、确定性的资源处理图片/音频脚本化、半自主的多步骤流水线 人审 checkpoint做不到按一个按钮、不干预、产出一个 Unity 可玩项目关键事实在最近一次 N5 × 5 LLM provider 组合的实测里CrewAI 的核心交接工具emit_output0/25 次被 agent 自然触发——所有成功的运行都依赖 4 层 rescue 兜底这不是悲观是 2026 年这个时间点用现有大模型 CrewAI 生态做这类工程真实的能力边界。文章后半段会把这个数据展开。二、v1 → v2 → v3 的三段路v1Claude-CrewAIWorkflow2026-04-22 起步形态一个 Python CLI纯 CrewAI 模板演示research → summarize两步流。8 个 commits目录里没有 UI没有数据库只有一份pyproject.toml和几个 agent yaml。目的验证 CrewAI 框架本身能不能跑、agent tools sequential process 的范式直觉是否成立。结论能跑。基础 demo 在 OpenAI / Anthropic 上都通。但仅是验证。任何真实业务场景都不够。v2MyCrew_v22026-04 末到 5 月初形态在 v1 基础上加桌面壳Tauri 数据层 YAML 驱动配置。Description.md 自评生产就绪 (0.2.0)14 个专业 Agent、6 个 Crew、2 种 Flowsimple/complex、8 个 MCP 集成。为什么弃用v3 的 Description.md 直白写明v2 已实现完整桌面应用但因整体用户体验不佳、核心功能不稳定被弃用。v3 在空目录从零重构参考 v2 的 IMPLEMENTATION_GUIDE.md 但不复用 v2 代码。真正的 v2 失败点事后总结YAML 驱动配置听上去灵活实际上每次改 agent 都要手工编辑配置文件、重启、测试。重新加载循环 30 秒导致迭代极慢。没有 PMProject Manager这一层用户输入直接喂给 Crew意味着任务拆解的责任丢给 user 自己。CrewAI dynamic MCP integration 参数报错频发——v2 用crewai-tools自带的 MCP wrapper命中各种 schema 兼容性问题。没有 task 输出契约agent 自由发挥的产物没法被下游可靠消费。v2 的核心教训堆功能不解决稳定性问题。先有能正确做完一件事的基底再做 UI不要倒过来。v3MyCrew_v32026-05-09 起步至今重写决定v3 在空目录从零起步。Tauri 2.x React 19 (frontend) Python FastAPI sidecar (backend) SQLite 持久化。截至本文撰写时 188 个 commit、47 个 backend service 文件、约 6 万行代码。下面把 v3 自身的几个大版本展开。三、v3 内部的 PM v1 → v5 五次迭代v3 的核心是PMProject Manager层——把用户的自然语言需求拆解成可执行的 Task DAG。这一层经历了 5 次大改写每次都有明确的换思路理由。PM v1隐含Phase 17 之前inception_svc 直接用 raw-LLM JSON-block prompting 让模型输出任务列表。失败模式模型经常输出形似 JSON 但有微小错误的文本validation_failed 率很高。PM v2Phase 17commit2be53635-13引入 CrewAI Plan Maker agent create_workflow工具。这是第一次用agent tool替代raw prompt parse。改进通过 tool 的args_schema让模型必须按结构出参数。遗留问题Plan Maker 是单个庞大 agent1800-token backstory处理 5 种意图每轮 5 个 LLM iter。Token 消耗极重慢。PM v3commitfffe1c8系列5-15渐进富集progressive enrichment的 Pydantic 链ConceptDoc ← Phase 1 主策划 AtomicTask ← Phase 2 系统策划 ReviewedTask ← Phase 3 审核策划加 acceptance schema PathedTask ← Phase 4 项管加 file_paths Assignment ← Phase 5 指挥员每个 phase 一个 LLM 调用 一个对应的submit_*工具验证 Pydantic 模型。思想从一句话需求到完整任务规格分 5 步走每步只关心一件事下游 phase 继承上游模型schema 严格扩展不破。为什么这个范式有效commit message 直说——v2 emit_output(payload: dict) 的范式 schema 在散文里v3 LLMs 看到的是 function-calling signature 里的 strict args_schema一次过率上去了。PM v4commit393bf59系列5-16核心是 Crew 池架构14 个单一职责 agentArt Director / System Designer / QA Engineer 等8 个 CrewSystem Implementation / UI Implementation / Audio / VFX / Scene Assembly / 等每个 Crew 是 head→executor→QA 三步骤序列Tasks 表加performer_kindperformer_id一个 task 可以分配给单 agent 或整个 Crew为什么需要 Crew 池v3 早期一个 agent 干所有事prompt 极长 max_iter 不够 工具集过大 → agent 经常想多步但只走一步就停。Crew 把工作切碎到不同角色每个角色拿到的 prompt 工具集都聚焦。Plan Maker v2同期 commit75b3c44的 Dify 风格意图路由把单 Plan Maker 替换成前置过滤 → 合规闸 → 意图分类器 → 5 子 agent 分派。Token 经济性从 25k/轮降到 1k-6k视意图。PM v5commite3d0d84/c2c6d8a5-17Code ContractPM Phase 5 designer 给每个代码任务输出一份必须实现的公共符号清单。Executor 写 .cs 时被注入这份契约QA 走 regex 校验第一版。两天后commit35cdd675-18regex 校验被升级为tree-sitter AST 语义匹配。为什么因为 regex 对 property body 风格过敏契约写public int Score { get; set; }模型写{ get _x; set { OnX?.Invoke(); } }——同一个 API 不同 bodyregex 假阴性。AST 走(kind, name)语义键匹配body 风格无关true positive 率显著上升。再一天commit243ceff5-19加Debugger 通道契约缺签名时不直接 validation_failed而是启 Debugger agent 跑一次精准补丁只补缺的签名不动业务逻辑。这是用针对性修复代替整 task 重跑节约 token。当前5-21本会话发生了一次架构级试错详见第五节尝试用Task(output_pydanticSpec)让 CrewAI 框架接管 schema 强制——实测推翻。回退原方案。四、累积下来的防御层到 5-21 为止v3 在 Crew 执行链路上累积了至少 7 个防御机制每个都是某次事故后加上去的#防御层来源事故commit1emit_output schema 校验v2 散文 schema 不可靠PM v32emit_output 路径存在性检查agent 说写了但其实没写漏洞心之回廊 audit5-133code_contract regex 校验Sonnet 漏 4-5 个签名PM v55-174code_contract AST 语义校验regex 假阴性5-185_rescue_react_emit_outputagent 把 Action/JSON 写在 text 没调 emit_output5-206_rescue_by_file_existenceagent 用 create_script 写了文件但忘 emit_output5-207workflow_svc server-side disk truth checkagent 编 file_paths 但磁盘没文件本会话发现5-21这个清单本身是一个信号底层 framework 不给硬保证所以每个失败模式都要在外面再补一道墙。五、本会话的关键试错output_pydantic 翻车值得单独讲因为是最近也是最戏剧化的一次。假设CrewAI 1.14 的Task(output_pydanticSpec)让框架接管 schema → 干净取代 emit_output 工具调用。Probe 1孤立环境用 Qwen-plus ExecutorSpec 跑 N1010/10 pydantic OK9/10 一次成功平均 1.1 LLM call/trial。看起来非常好。Probe 2tool_choice{type:function,function:{name:verify_outputs}}在 Qwen 5/5 强制成功。架构看起来全绿。部署到生产fruit-ninja 项目7 个代码 task4 个 statusdone但磁盘上文件不存在3 个被新 server-side check 抓到失败真成功0Phase 4 受控变量实验Variantreal_successbaseline (output_pydantic 普通 prompt)0/5strong_prompt0/5high_iter (max_iter8)0/5simple_tool0/5no_pydantic (无 output_pydantic verify_outputs)5/5根因Task(output_pydanticSpec)让 Qwen agent 把目标从做事再产 JSON扭曲成直接产 JSON工具循环被框架短路。prompt 强化、提高 iter、换工具都无效——只有不用 output_pydantic 才能恢复 agent 的工具调用行为。这是 CrewAI 1.14 一个未文档化的架构特性社区 GitHub issue 里有类似抱怨#1338、#2895。反思Probe 1 测的是能不能产出合法 Spec没测是否同时做了工具工作——两个本应正交的指标实际是负相关。孤立单元测试的盲区。后续任何涉及 output_pydantic 类设计probe 必须同时观察预期工具是否被触发。六、方法 / 结果总表把这两个月试过的关键方法摊开方法状态结果数据备注YAML 驱动 agent 配置v2❌ 弃用UX 反馈难用改 SQLite 后端 API单庞大 Plan Maker agentv3 早期❌ 弃用25k tokens/轮改 Dify 风格意图路由意图路由 5 子 agentPM v2✅ 沿用1k-6k tokens/轮按意图-75% to -96%Pydantic progressive enrichmentPM v3✅ 沿用schema 失败大幅下降仍是主架构Crew 池 performer_idPM v4✅ 沿用agent 职责单一化仍是主架构code_contract regex 校验PM v5❌ 替换property body 风格假阴性改 ASTcode_contract tree-sitter AST✅ 沿用21 test case 全过真根因解Stage D Debugger 补丁✅ 沿用缺签名时只补不重跑节约 tokenCrewAI native deepseek path❌ 已知坏DSML token 5/5 泄漏强制 is_litellmTrueLiteLLM 路径 emit_output⚠️ 不可靠emit_output 0/5 自调需 rescue 兜底_rescue_react_emit_output等 4 个 rescue 分支✅ 沿用补救率提升治标Task(output_pydanticSpec)本会话试❌ 推翻生产 0/7 真成功agent 跳工具verify_outputs 工具 tool_choice specific✅ 沿用Qwen 5/5 强制成功但 prompt 模式下 0/5 自调workflow_svc server-side disk truth check✅ 沿用抓 100% agent 作弊最后一道防线Qwen / GLM 替代 DeepSeekstructural 步骤✅ 沿用Qwen response_format json_schema 支持DeepSeek reasoner 不支持七、走过的弯路 / 误判的根因弯路 1v1→v2 把 UI 做在不稳定核心之上v2 是产品化优先思路的典型失败——还没解决AI 能不能可靠完成一件事就着急做 UI 让用户操作它。结果是用户看见一个看起来完整的 app但每次跑都失败。正确顺序先磨稳核心 1-2 个场景的端到端再做 UI。弯路 2迷信agent 会按 prompt 守规矩v3 早期 emit_output 的整个设计假设 agent 会主动调它。实测 0/5 真触发——agent 把 payload 写在 final answer text 里。每次失败就加一个 rescue 分支。4 个 rescue 累积下来反思这不是 4 个独立 bug是同一个架构假设工具会被调的 4 次破绽。应该早早承认这个假设站不住把校验前置到 server-side。弯路 3把 schema 严谨等同于framework 接管Task(output_pydanticSpec)看起来比 agent 必须主动调 emit_output 优雅——让框架做约束。Probe 1 数据漂亮10/10就贸然推进。没意识到框架接管 schema 的代价是 agent 跳过 tool 循环。教训评估架构改动时必须同时测理想路径和副作用路径——10/10 schema 成功 0/5 工具调用 净负回归。弯路 4code_contract 第一版选 regex写 regex 校验比写 AST 容易但 regex 对代码风格过敏。这种先用脆的、坏了再换的选择加上中间还把它当真理跑了几天的项目事后看直接上 AST 是对的。弯路 5用 git log 做诊断、不用日志/产物会话中段我有一次基于 commit history 模式匹配 → 给方案——被用户直接打断不要用 commit history 脑补根因。教训诊断永远是 evidence-first——读out.json、读 LLM raw response、加 instrumentation不是读 commit 揣测。八、行业横向对比2026-05 时点CrewAI 自身现状来自 DigitalbyDefault.ai 2026 report47.8K GitHub stars2B agent runs150 enterprise customers1.9.x 版本加了 CheckpointConfig 的状态持久化与 LangGraph 对比代码生成成功率CrewAI 54% vs LangGraph 62%Devin号称首个 AI 软件工程师来自 OpenAIToolsHub 2026 review2024 launch 自报 SWE-bench 13.86%Cognition没有更新过 2025 / 2026 的 benchmark公认局限模糊需求难处理、复杂任务容易钻牛角尖、关键操作必须人审LLM Agent 失败率研究来自 Augment Code 2026 report 与 arxiv 2601.16280生产环境多 agent 系统失败率41-86.7%Context 保留每步丢 2%5 步循环后只剩 60% 原始上下文可访问12 类工具调用错误分类法小模型工具初始化是主瓶颈Unity AI 生态来自 andrew.ooo Unity MCP guide 与 GitHub IvanMurzak/Unity-MCPUnity MCP独立项目5800 stars把 Unity Editor 当成可寻址工具表面Unity 官方 AI Gateway 2026 年开始 roll outCoplay.dev 提供 Unity AI 助手定位是AI for Unity dev而非全自主搭建没有公开的AI 一键搭 Unity 项目产品CrewAI Pydantic Tool Calling 已知问题来自 CrewAI GitHub issuesPydantic schema 不被加入 system prompt 是已知 bugGemini LLM tool calling 在 1.14 LiteLLM 1.70 下 tools 参数被传 nullLiteLLM 缺失依赖在 1.0.0 升级时大面积失败九、技术局限性的诚实评估把模型层、框架层、目标层分开评估。模型层模型工具调用可靠性本项目实测DeepSeek v4-flash (reasoner)不支持 tool_choice requiredDSML token 5/5 泄漏nativeReAct 文本模式偶错格式Qwen-plus工具调用最稳response_format json_schema 支持tool_choice specific 模式 5/5 强制成功GLM-4-plus同 Qwen文档稍弱MiMo v2.5-pro不稳定2/5 trial 报 None/empty结论模型在单步骤工具调用这件事上其实有解Qwen 正确配置问题是多步骤工具编排 严格输出的复合场景所有模型都不可靠。这是当前 LLM 的真实能力边界不是哪家模型不行。框架层CrewAI 1.14 的几个未公开缺陷本项目实测Task(output_pydanticSpec)与 tool-using agent 不兼容LiteLLM Instructor / Converter 不继承 LLM 实例上的 api_keyruntime 不自动从 llm_models 读 max_tokensReAct 文本协议默认开启没有强制走 native tool_calls开关per-call tool_choice 不在 Agent 公开 API 里对比 LangGraph基于公开资料LangGraph 的图编排更显式节点之间状态传递可控失败模式不同但同样需要 workaround代码生成基准上 LangGraph 62% vs CrewAI 54%但都不到 70%结论CrewAI 在快速搭多 agent demo很顺手但生产级严谨输出需要自己加 server-side enforcement 层。这部分工作量本项目证明可控~7 层防御机制没有任何一层是不可工程化的。目标层最难的部分AI 一键产出 Unity 游戏 这个产品目标在 2026 年是 stretch 目标需要全局一致性namespace、事件订阅链、prefab 引用—— agent 在 max_iter 内维持不住需要跨文件依赖管理 —— 当前 LLM context 衰减 5 步后只剩 60%MemU 2026 数据需要 Unity Editor 交互验证 —— 即使 Unity MCP 暴露了 Editoragent 没法看见运行结果再调整需要美术资源生产 —— 这部分本项目走脚本化路径script_comfy_generate成功了因为它本质上是确定性步骤对比 Devin / Cursor agent 模式 / 各家AI 工程师没有任何一家做到全程自主 高成功率主流姿态全部收敛回AI 协助 人审 checkpointSWE-bench 13.86% 是 Devin 自报上限十、未来方向与可能性基于以上数据给四个方向的判断方向 1降低自主度加人审 checkpoint推荐短期每个 Crew 完成后弹待审核用户瞄一眼放行/驳回。驳回带反馈词触发 re-run。这是今天能落地的产品形态——半小时 demo 一个游戏用户操作的不是按钮而是审核者角色。方向 2脚本化更多确定性步骤推荐中期本项目已有script_comfy_generate路径图片生成100% 可靠因为它绕开 agent 直接 HTTP 调用 ComfyUI。类似可以延伸文件创建 / 目录结构 / .meta 生成 → 脚本Unity prefab 装配的常见 pattern → 脚本Asset import 配置 → 脚本让 LLM 只做决定写什么不直接怎么写。方向 3等下一代模型自然变好推荐 1-2 年视野GPT-5 / Claude Opus 5 / Qwen3.7 / GLM-5 已经在路上工具调用可靠性、长上下文一致性、Unity 领域知识都在指数提升。今天硬卷的 workaround 在下一代模型上可能全不需要。ROI 计算投 3 个月做 100% 自主 vs 等 1 年模型自然到位 做半自主——后者通常更划算。方向 4换 stack高投入长期价值不确定可选项Anthropic API 自研编排Computer Use / Code Execution tool 原生支持更好LangGraph图式编排更显式自研 minimal agent loop最大控制权最大维护成本没有明显赢家——CrewAI 的痛点在别的框架里以不同形式存在主要的 trade-off 是上手快 vs 极致控制。十一、结语技术尝试值不值得做如果你看完前面 1 万字觉得这项目踩了一堆坑、目标也没完全达到到底值不值我的回答是值但不是从产品意义上。从工程产出角度188 个 commits 188 次失败/微调 一份对CrewAI 在生产严谨场景的真实表现的高保真观察7 层防御机制 5 个 rescue 分支 一份如何在不可靠 framework 上加 enforcement 层的工程参考5 次 PM 大改写 渐进富集 Pydantic 链 Crew 池 代码契约这个范式的实测数据本会话的 N5 × 5 provider 实验 一份可复用的 LLM 工具调用基准从产品意义角度今天还做不出一键 Unity 游戏。等下一代模型 持续打磨架构可能 12-18 个月有机会。这是一篇失败学的文章——失败学的价值在于让下一个走同样路的人少踩几个坑。如果你也在做LLM 自主代码生成类项目希望本文里的 7 个防御机制清单、4 条弯路标记、Probe 数据能省你几周时间。参考资料行业现状与对比CrewAI Hit 47.8K Stars and 2 Billion Agent Runs (DigitalbyDefault 2026)Best Multi-Agent Frameworks 2026 (Gurusup)Devin AI Review 2026 (OpenAIToolsHub)Devin 1: Specs, Benchmarks Why Its Obsolete (UC Strategies 2026)LLM Agent 失败模式研究When Agents Fail to Act: Diagnostic Framework (arxiv 2601.16280)Beyond pass1: Reliability Science for Long-Horizon Agents (arxiv 2603.29231)Multi-Agent AI Systems: Why They Fail (Augment Code 2026)LLM Agentic Failure Modes (Ceaksan)AI Agent Harness Failures: 13 Anti-Patterns (Atlan)Unity AI / MCP 生态Unity MCP - AI Game Development Bridge (andrew.ooo)Unity-MCP GitHub (IvanMurzak)Advanced Agentic Game Development in Unity (Medium)Coplay - AI Assistant for Unity Game DevelopmentUnity AI: AI Game Development Tools (Unity Official)CrewAI Pydantic / LiteLLM 已知问题CrewAI Issue #1338: Pydantic schema not in system promptCrewAI Issue #2895: Gemini Tool Calling Fails with null toolsCrewAI Discussion #1436: How to get structured output using pydantic作者注本文数据基于 MyCrew 项目自 2026-04-22 至 2026-05-21 的实测硬件环境 Windows 11 Python 3.13 CrewAI 1.14.4 LiteLLM 1.85。Git库https://github.com/Joe-Hank/MyCrew_Desktop欢迎技术交流。*