用 ChatDev ChatChain 搭建角色分工的多智能体协作流程

ChatDev 是一个开源的多智能体框架，它把软件开发流程当作研究协作式 AI 的实验场：每个智能体由大语言模型驱动，被赋予 CEO、CTO、设计师、程序员、测试等角色，从一句简短的需求描述出发，迭代完成设计、编码与测试。真正把这些角色串起来的是框架内部的协调逻辑 ChatChain——它决定谁在什么阶段发言、消息如何传递、上下文如何累积。如果你想理解多智能体系统里「角色分工 + 结构化通信」是怎么落地的，ChatDev 是一个比较直观的样本。本文按「准备环境 → 配置模型后端 → 运行 → 查看协作过程」的顺序，讲清一次完整跑通需要做的每一步。站内同类工具的索引可以看 ChatDev 这一条目。

需要先说明这篇教程的定位：它面向的是想动手跑一遍、观察智能体之间如何通信的读者，而不是要交付生产系统的人。生成结果在多次运行之间会有差异，产出的应用通常还需要人工调整才能完全可用。这一点在后面的注意事项里会展开。

准备工作

运行环境

ChatDev 本身设计为跨平台，但不同操作系统、Python 版本和 CPU 架构会影响安装与运行表现。准备阶段需要确认以下几件事：

• Python 版本：需要 Python 3.11。可以用 python3 --version 检查当前版本，版本不符时先切换解释器再继续。
• Git：需要克隆项目仓库，本地要有可用的 Git 客户端。
• Shell 差异：在 Windows 上使用 PowerShell 时，一些为 Unix 系系统编写的 shell 命令需要做相应调整，例如路径分隔符、环境变量写法、命令串联方式等。遇到命令报错时，先排查是不是这类平台差异。
• 模型后端：需要一个可调用的大语言模型 API。本文的示例使用 IBM watsonx.ai 作为模型后端，通过它与 Hugging Face 的集成调用 Llama-4-Maverick 生成软件方案。

项目结构

克隆仓库后，先确认目录结构符合预期，再往下走。教程对应的项目目录大致如下：

tutorials/projects/chatdev_watsonx/
├── camel/
│   ├── model_backend.py   # 与多种 AI 模型交互的统一接口
│   ├── typing.py          # 类型定义，包括支持的 AI 模型
│   ├── configs.py         # 基于模型接口定义的模型参数
│   ├── utils.py           # 工具函数，包括模型 token 上限配置
│   └── ...
├── Visualizer/
│   └── app.py             # 本地 Flask 应用，用于查看日志与 ChatChain
├── WareHouse              # 生成的软件保存在这里
├── run.py                 # 应用入口
└── chatdev_watsonx.md     # 项目说明文档

几个目录的作用值得先记住：camel/ 下是与模型交互的适配层，model_backend.py 提供统一接口，configs.py 和 utils.py 负责模型参数与 token 上限；WareHouse 是产物落盘的位置；run.py 是唯一的运行入口；Visualizer/app.py 是事后分析与实时监控用的本地 Web 界面。

模型后端的适配说明

这个示例使用的是一份针对 watsonx.ai API 做过适配的 ChatDev 版本。核心 ChatDev 支持多种模型提供方，但这份适配版主要做了三处改动：

• 把 watsonx.ai 的 API 包装成 ChatDev 期望的 LLM 接口；
• 调整提示词模板，以适配 watsonx.ai API 对 token 与格式的要求；
• 修改模型选择逻辑，使 watsonx.ai 成为一个可选的后端。

这意味着它演示的是「如何把 ChatDev 扩展到其他模型提供方」这件事本身。其他提供方（例如 OpenAI、Ollama）并没有在这份适配版上验证过，若要切换，需要在代码层面做相应调整，而不是改一个配置项就能完成。

操作步骤

第一步：确认 Python 版本

先确认解释器版本，避免后续依赖安装出现难以定位的问题：

python3 --version

输出应为 Python 3.11.x。如果系统里同时存在多个 Python，注意后续安装依赖与运行脚本时使用的是同一个解释器。

第二步：克隆仓库

把项目仓库克隆到本地，然后进入教程对应的项目目录：

git clone <仓库地址>
cd <仓库目录>/tutorials/projects/chatdev_watsonx

克隆完成后，对照上一节给出的目录结构检查一遍，确认 camel/、Visualizer/、WareHouse、run.py 都在位。如果目录层级对不上，说明克隆的分支或路径有误，先解决这个问题再继续。

第三步：配置模型后端

模型后端的配置集中在 camel/ 目录下。model_backend.py 是与模型交互的统一入口，configs.py 定义模型参数，utils.py 里包含 token 上限相关的设置。使用 watsonx.ai 时，需要准备好对应的 API 凭据，并让适配层能够读到这些凭据。

配置时重点确认三件事：

1. 后端选择：模型选择逻辑中要指向 watsonx.ai，而不是默认的其他提供方。
2. 模型标识：示例使用的是 Llama-4-Maverick，模型名称要与后端实际提供的标识一致。
3. token 上限：utils.py 中的 token 限制配置要与所选模型的上下文能力匹配，设置过小会导致长对话被截断，影响后续阶段的上下文传递。

具体的凭据字段名、环境变量名与参数键名以项目内 chatdev_watsonx.md 的说明和官网当前信息为准，不同版本之间可能有差异。

第四步：运行入口脚本

配置完成后，从项目目录运行入口脚本：

python3 run.py

运行时需要提供一句描述需求的输入，例如「Build a to-do list app」。这句输入是整个流程的起点，后续所有阶段都围绕它展开。输入越具体，各角色拿到的任务边界越清晰；输入过于笼统时，生成结果往往需要更多人工修正。

第五步：观察 ChatChain 的协作过程

运行过程中，智能体之间通过多轮对话、也就是消息传递机制交换结构化 JSON 消息。这些消息既承载各阶段的输出，也充当共享记忆缓冲区，让后一阶段能够在前一阶段的产出上继续推进。整个流程大致是这样一条链路：

用户输入「Build a to-do list app」→ CEO 分派给 CTO → CTO 指派给开发者 → 开发者编写代码 → 测试者验证

每个智能体都是一个 Python 类，按顺序通过结构化的自然语言提示词通信。提示词遵循预定义模板，模板里包含角色身份、任务指令以及此前交互的相关上下文。这种模板化策略的作用是把角色身份与共享记忆嵌进提示词本身，从而保证跨阶段的连续性与一致性。

第六步：用 Visualizer 查看日志

ChatDev 提供 Visualizer 工具，这是一个基于 Flask 的本地 Web 界面，既支持运行后分析，也支持实时监控。启动后通过本地浏览器访问，可以切换几种视图：

• Log Viewer：查看实时的智能体交互日志；
• Replay Viewer：回放已保存的多智能体对话记录；
• ChatChain Viewer：检查任务协调流程，看清各阶段之间的衔接关系。

对于学习目的而言，ChatChain Viewer 是最值得反复看的部分——它把「谁在什么时候把什么交给了谁」显式呈现出来，比读代码更容易建立直觉。Visualizer 的启动方式与端口配置以项目内说明为准。

一个完整示例

下面把前面的步骤串成一个从零到看到结果的最小流程。假设目标是生成一个待办事项应用。

1. 环境检查

python3 --version

确认输出为 Python 3.11.x。

2. 获取项目并进入目录

git clone <仓库地址>
cd <仓库目录>/tutorials/projects/chatdev_watsonx

3. 核对结构

确认 camel/model_backend.py、camel/configs.py、camel/utils.py、Visualizer/app.py、run.py 均存在，WareHouse 目录为空或仅有历史产物。

4. 配置 watsonx.ai 后端

在 camel/ 下完成 API 凭据与模型标识的配置，模型选择指向 watsonx.ai，模型使用 Llama-4-Maverick，并检查 utils.py 中的 token 上限设置。

5. 运行

python3 run.py

输入需求描述：

Build a to-do list app

6. 观察阶段推进

CEO 接收需求并分派给 CTO，CTO 拆解任务并指派给开发者，开发者产出代码，测试者进行验证。每个阶段的输出以结构化消息形式进入共享上下文，供下一阶段使用。

7. 查看产物

生成的软件保存在 WareHouse 目录下。打开该目录即可看到本次运行产出的代码与文档。

8. 用 Visualizer 复盘

启动 Visualizer/app.py 对应的 Flask 应用，在本地浏览器中打开，先用 Log Viewer 看实时交互，再用 ChatChain Viewer 检查任务协调流程，最后用 Replay Viewer 回放保存下来的对话记录。

到这里，一次完整的「一句话需求 → 多角色协作 → 代码产物 → 过程复盘」就完成了。这个流程的价值不在于产出的应用有多完善，而在于你能亲眼看到角色分工、消息传递与上下文累积是如何共同驱动一次多智能体协作的。

注意事项

输出存在不确定性

和多数生成式 AI 工作流一样，ChatDev 的输出在多次运行之间会有差异。智能体通常能产出连贯、结构合理的代码与文档，但生成的应用可能需要人工调整才能完全可用。影响结果的因素包括提示词设计、任务复杂度，以及大语言模型响应本身的波动性。不要把它当作一次运行就能交付成品的工具。

适配版并非全场景验证

本文使用的 watsonx.ai 适配版是以较为务实的方式改造出来的，功能可用，但并没有在所有场景下做过充分测试。其他模型提供方（如 OpenAI、Ollama）没有在这份适配版上验证过，切换时需要改代码，而不是改配置。如果你打算换后端，先评估需要改动的位置：接口包装、提示词模板、模型选择逻辑这三处是已知的适配点。

平台差异可能导致命令失败

跨平台支持不等于零差异。Windows PowerShell 下为 Unix 编写的命令可能需要调整；不同操作系统、Python 版本与 CPU 架构也会影响性能与行为。遇到安装或运行问题时，优先排查平台差异，再考虑代码问题。

token 上限会影响长对话

多轮对话会持续累积上下文，token 上限设置不当会导致早期阶段的上下文在后续阶段被截断，进而影响协作的连贯性。调整 utils.py 中的相关配置时，要与所选模型的实际上下文能力匹配。

定位是学习与实验

ChatDev 的这套流程适合用来学习、实验和观察 LLM 驱动的智能体协作，不是面向生产的解决方案。把它当作理解 ChatChain 与智能体通信机制的起点，而不是直接部署的基础设施。涉及模型可用性、配额与计费的信息，请以官网当前信息为准。