MetaGPT — 多智能体软件公司框架:架构与原理

30 秒导读: MetaGPT 把「一家软件公司怎么运作」这套标准作业流程(SOP,Standard Operating Procedure)写进一队 LLM 角色里。你丢进一句话需求(「做个 2048 游戏」),产品经理写 PRD、 架构师出设计、工程师写代码——角色之间不直接互相调用函数,而是把产物当消息发到一个共享 环境里,谁「订阅」了这类产物就自动被触发接力。一句话哲学:Code = SOP(Team)。

---

1. 这是什么(零基础也能懂)

• 一句话定义: MetaGPT 是一个多智能体(multi-agent)框架——让多个各有分工的 LLM 角色, 按一套模拟真实软件公司的流程协作,把一句话需求变成需求文档、架构设计、可运行的代码仓库。

• 解决什么问题 / 给谁用: 单个 LLM 一口气写完整个项目容易「想哪写哪」、丢三落四。MetaGPT 的思路是:把复杂任务拆成公司里的岗位与交接流程,每个岗位只干一件擅长的事、只在拿到上游 产物时才动手。给谁用?想让 AI 端到端产出软件的开发者、研究多智能体协作的人。

• 它能做什么:

  • 从一行需求生成用户故事、竞品分析、需求文档(PRD)、数据结构、API 设计、代码。
  • 提供一整套「软件公司」角色:产品经理 / 架构师 / 项目经理 / 工程师 / 数据分析师。
  • 既支持固定流水线(经典 SOP),也支持由 TeamLeader 动态调度的自由智能体团队(MGX)。

• 用起来什么样: 命令行一句话即可启动一整支团队跑起来。

  # 安装后,一句需求启动整个「软件公司」
  metagpt "Create a 2048 game"

  它对应的 Python 入口是把一队角色「雇」进一个 Team,再投点「预算」跑几轮:

  # 示意,非源码:generate_repo 的核心骨架(见 software_company.py)
  company = Team(context=ctx)
  company.hire([TeamLeader(), ProductManager(), Architect(), Engineer2(), DataAnalyst()])
  company.invest(investment=3.0)          # 预算上限,超支就停
  asyncio.run(company.run(n_round=5, idea="Create a 2048 game"))

• 一句话直觉 / 类比: 把它想成一家会自己运转的微型软件公司:需求是老板拍下来的一句话, 员工各就各位;唯一的沟通方式是往公司公告栏(环境)贴东西,别人看到与自己相关的就接着干。

本节不谈底层代码。目标:完全不懂的人读完知道「这是干嘛的」。

---

2. 顶层全景(它大概怎么转)

2.1 核心哲学:Code = SOP(Team)

MetaGPT 的全部设计都从一句话展开:把标准作业流程(SOP)当成一个函数,作用在一支团队上。

• Team(团队) = 一群角色 + 一个共享环境。
• SOP(流程) = 「谁看到什么产物就该接着做什么」的规则。
• 把 SOP 施加到 Team 上,就「跑」出了软件——所以叫 Code = SOP(Team)。

2.2 四层结构

整个框架自底向上是四层积木,上层由下层拼成:

                 ┌─────────────────────────────────────────────┐
   一句话需求 ──▶ │  Team（团队）  ── 投预算、跑 N 轮、最后归档     │
                 │     └── Environment（共享环境 = 消息总线）      │
                 └───────────────────┬─────────────────────────┘
                                     │ 广播 / 订阅 Message
              ┌──────────────┬───────┴───────┬──────────────┐
              ▼              ▼               ▼              ▼
         ┌─────────┐   ┌─────────┐     ┌─────────┐    ┌─────────┐
         │ Role A  │   │ Role B  │     │ Role C  │    │  ...    │   ← 角色 = 智能体原子
         │ 观察-思考-行动 每个角色内部是一个 观察→思考→行动 循环        │
         └────┬────┘   └────┬────┘     └────┬────┘    └─────────┘
              │ 执行          │               │
              ▼              ▼               ▼
           Action ─────▶ ActionNode（把 LLM 的自由文本压成结构化产物）  ← 工作单元

怎么读这张图: 从上往下是「谁包含谁」。需求进入 Team,Team 持有一个 Environment(消息 总线);角色都挂在环境上,各自跑「观察-思考-行动」循环;角色行动时执行 Action,Action 常借 ActionNode 把 LLM 输出变成结构化数据(PRD、设计、代码)。

2.3 部件一句话职责

部件	干什么	在哪个文件
Team	雇角色、管预算、驱动 N 轮运行、结束归档	metagpt/team.py:32
Environment	共享消息总线:按订阅地址把消息投递给角色	metagpt/environment/base_env.py:124
Role	智能体原子:观察消息→思考选动作→行动产出	metagpt/roles/role.py:125
Action	一个工作单元(写 PRD、写代码…),封装一次 LLM 调用	metagpt/actions/action.py:29
ActionNode	把 LLM 自由文本按 schema 解析成结构化对象	metagpt/actions/action_node.py:135
Message	角色之间流转的产物,带 cause_by/send_to 路由信息	metagpt/schema.py:232
MGXEnv	让 TeamLeader 接管消息发布的动态团队环境	metagpt/environment/mgx/mgx_env.py:11
RoleZero	能动态思考、每轮自选工具命令的通用智能体基类	metagpt/roles/di/role_zero.py:55

2.4 主线走一遍(高层,不进代码)

一次运行从需求到产物,大致这样流动:

需求 ──▶ Team.run_project 把 Message 发到 Environment
         │
         ▼  每一轮(round),Environment 让所有「不空闲」的角色并发跑一次
    Role.run: _observe（挑出我订阅的新消息）
                 └─▶ _think（决定这轮做哪个 Action）
                        └─▶ _act（跑 Action,产出新 Message）
                               └─▶ publish_message（发回 Environment）
         │
         ▼  新消息又触发下游角色…… 如此接力,直到没有新活(全部 idle)或轮数用尽
    产物汇聚成一个代码仓库

关键点:角色之间零直接调用。 产品经理写完 PRD 不会「call 架构师」;它只是把 PRD 消息发到 环境,而架构师订阅了 PRD 这类产物(_watch({WritePRD})),于是下一轮自然被唤醒。这种 「谁产出什么就触发谁」的发布-订阅关系,就是 SOP 被编码进代码的地方。

---

3. 阅读地图(建议顺序)

本子库分五章,由浅入深。先建立「角色循环 + 消息总线」这两块地基,再看两种上层玩法 (固定流水线 vs 动态团队)。

顺序	章节	讲什么	读完你会
0	MetaGPT 是什么 · 全景 · 阅读地图	本页:全景与导航	知道整体怎么拼
1	Role:观察-思考-行动的智能体原子	Role 的 _observe/_think/_act 循环、三种 react 模式	看懂单个智能体怎么动
2	Action 与 ActionNode:工作单元 + 结构化输出引擎	Action 封装 LLM 调用,ActionNode 把自由文本压成结构化产物	看懂「一次思考如何落成可用数据」
3	Environment 消息总线、Message 路由与 Team	发布-订阅、cause_by/send_to 路由、Team 如何驱动多轮	看懂角色如何在不直接调用下协作
4	经典 SOP 流水线:一行需求跑成一个软件仓库	产品→架构→工程 的固定订阅链,端到端追一遍	看懂固定流水线怎么把需求变成代码
5	MGX 与 RoleZero:TeamLeader 调度的动态命令智能体	MGXEnv 让 TeamLeader 接管路由,RoleZero 每轮自选工具命令	看懂「自由团队」这套新范式

两条主线的分岔(先建立心智模型): MetaGPT 里同时活着两代设计。

• 经典 SOP(固定流水线): 角色用 by_order / 固定 _watch 订阅,像装配线一样按预定顺序 接力。代表:ProductManager(use_fixed_sop=True)、Architect、经典 Engineer。见第 4 章。
• MGX / RoleZero(动态团队): 由 TeamLeader(名叫 Mike)接管消息发布,像真人领导一样 决定「这条消息该派给谁」;每个角色是 RoleZero,用 react 模式每轮让 LLM 自选下一条 工具命令。默认 Team(use_mgx=True) 走这条路。见第 5 章。

---

4. 巧妙之处(可带走的技术)

这几处是 MetaGPT 值得借鉴的设计,先说妙在哪,再给引用。

• 把「协作」降维成「发布-订阅」。 角色不持有彼此引用,只往环境发消息、只从自己的私有 buffer 读订阅到的消息。加一个角色 = 声明它 _watch 什么、发什么,零改动已有角色。 订阅过滤见 Role._observe(metagpt/roles/role.py:399),按 cause_by ∈ watch 或点名 send_to 命中;发布见 Environment.publish_message(metagpt/environment/base_env.py:175)。

• cause_by 让消息自带「我是谁产的」标签。 每条 Message 记录它由哪个 Action 产生 (cause_by,metagpt/schema.py:239),下游订阅就是匹配这个标签——SOP 的「交接规则」 因此变成一行声明,而不是硬编码的调用图。

• ActionNode:让 LLM 的自由文本变成可靠的结构化对象。 它用 Pydantic 的 create_model 按 schema 动态造类再校验(ActionNode.create_model_class,metagpt/actions/action_node.py:248), 把「模型说的一段话」精确落成 PRD/设计/代码字段。这是把不可靠 LLM 输出工程化的关键一招。

• TeamLeader 作为「消息路由的人」。 经典环境是广播;MGX 里几乎所有消息都先过 TeamLeader (MGXEnv.publish_message,metagpt/environment/mgx/mgx_env.py:24),由它决定派给谁 (publish_team_message,metagpt/roles/di/team_leader.py)。把「调度」显式建成一个角色, 比写死流程更灵活。

• 一个 react 循环,统一「思考」与「工具调用」。 RoleZero 每轮 _think 让 LLM 输出一串 命令、_act 解析并执行(metagpt/roles/di/role_zero.py:198 / :280),最多 50 轮 (max_react_loop)。同一套循环既能规划、又能调工具,不必为每种角色写专用逻辑。

• 预算即熔断。 Team 每轮先 _check_balance,累计成本超过投资额就抛 NoMoneyException 停机(metagpt/team.py:98),给「让 LLM 自由跑」加了一道硬性成本闸。

---

5. 代码地图(导航索引)

下表是给人和 agent 的跳转表:用符号名 grep 比行号更抗上游漂移。所有引用锚定 sourceCommit: 11cdf466。

主题	文件路径	关键符号
CLI 入口 / 组队	metagpt/software_company.py	generate_repo、app(typer)
团队驱动多轮	metagpt/team.py	Team、Team.run、run_project、invest、_check_balance
共享环境 / 消息总线	metagpt/environment/base_env.py	Environment、publish_message、Environment.run、member_addrs
角色循环	metagpt/roles/role.py	Role、_observe、_think、_act、_react、publish_message、RoleReactMode
工作单元	metagpt/actions/action.py	Action、Action.run、_run_action_node
结构化输出引擎	metagpt/actions/action_node.py	ActionNode、fill、create_model_class、compile、SIMPLE_TEMPLATE
消息与路由字段	metagpt/schema.py	Message(cause_by/send_to/instruct_content)、AIMessage、MessageQueue.pop_all
动态团队环境	metagpt/environment/mgx/mgx_env.py	MGXEnv、publish_message、_publish_message、move_message_info_to_content
动态智能体基类	metagpt/roles/di/role_zero.py	RoleZero、_think、_act、_run_commands、max_react_loop
团队领导 / 调度	metagpt/roles/di/team_leader.py	TeamLeader(name=Mike)、publish_team_message、publish_message
经典 SOP 角色	metagpt/roles/product_manager.py、architect.py	ProductManager(use_fixed_sop)、Architect(_watch({WritePRD}))
工程实现角色	metagpt/roles/engineer.py、metagpt/roles/di/engineer2.py	Engineer(n_borg)、Engineer2(Terminal/Editor 工具)
关键常量	metagpt/const.py	TEAMLEADER_NAME="Mike"、MESSAGE_ROUTE_TO_ALL="<all>"、MESSAGE_ROUTE_TO_SELF="<self>"

深入各机制请沿「阅读地图」进对应章节。 本页只负责让你(或 agent)低成本判断相关性、 决定下钻哪一章;真正的代码走读在 01–05 各章。