第一章 认识 MetaGPT

1.1 什么是 MetaGPT

MetaGPT 是一个多 Agent 协作框架，由中国团队深度智慧（DeepWisdom）开发，GitHub 68k+ Stars，MIT 开源协议。它的核心理念是"Code = SOP(Team)"——将软件公司的标准作业流程（SOP）注入到多个 AI Agent 中，让它们像真实团队一样协作。

当你给 MetaGPT 一个产品需求，它会自动触发以下流程：产品经理写 PRD → 架构师设计技术方案 → 工程师编写代码 → 测试工程师编写测试。整个过程完全自动化，无需人工介入。

该项目已被 ICLR 2024 接收为口头报告论文（录取率仅 1.8%），学术和工程价值都得到了认可。

1.2 核心理念：Code = SOP(Team)

传统代码生成工具只关注"写代码"这一步，MetaGPT 关注的是完整的软件开发流程。它将软件工程中的角色分工和协作流程编码到 Agent 系统中：

• SOP 驱动：每个角色遵循标准作业流程，产出标准格式的文档
• 角色专业化：每个 Agent 专注自己的角色，不越界
• 信息传递：上游角色的输出自动成为下游角色的输入
• 质量控制：每个阶段都有明确的交付物和评审环节

1.3 能干什么

• 一句话生成完整项目：输入"创建一个 2048 游戏"，自动生成完整可运行的代码
• 多角色代码审查：PM 审查需求完整性，架构师审查技术方案，工程师审查代码质量
• 增量开发：在已有项目基础上添加新功能，自动理解上下文
• 数据分析：Data Interpreter 模块能自主进行数据分析和可视化
• 研究报告：Researcher 模块能多角度调研并输出结构化报告
• 多 Agent 辩论：多个 Agent 针对问题辩论，提高决策质量

1.4 系统要求

1.5 与其他框架对比

第二章 快速上手（5分钟）

本章带你用最少步骤体验 MetaGPT。你只需要一个终端和一枚 API Key。

2.1 安装 MetaGPT

打开终端，执行：

pip install --upgrade metagpt

验证安装：

metagpt --help

如果看到帮助信息，说明安装成功。

2.2 初始化配置

执行初始化命令，生成默认配置文件：

metagpt --init-config

这个命令会在 ~/.metagpt/config2.yaml 生成配置文件。接下来你需要编辑这个文件，填入你的 LLM API 信息。用任意文本编辑器打开：

vim ~/.metagpt/config2.yaml

2.3 配置 LLM API（最小配置）

将文件内容修改为以下内容（以 OpenAI 为例）：

llm:
  api_type: "openai"
  api_key: "sk-your-api-key-here"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4-turbo"

💡 提示: MetaGPT 对 LLM 质量要求较高。如果使用 GPT-3.5，生成效果会明显下降。推荐使用 GPT-4 或 Claude 3.5 Sonnet。中文用户也可以配置国产模型如 DeepSeek、GLM-4。

2.4 运行第一个项目

执行以下命令，让 MetaGPT 生成一个 2048 游戏：

metagpt "Create a 2048 game"

MetaGPT 会启动多 Agent 协作流程：

1. 产品经理（PM）分析需求，撰写 PRD 文档
2. 架构师（Architect）设计技术方案和代码结构
3. 项目经理（PM）拆分任务
4. 工程师（Engineer）编写代码
5. 测试工程师（QA Engineer）编写测试

2.5 查看输出

项目生成完成后，在 ./workspace 目录下可以找到完整的项目代码：

cd workspace
ls -la
ls -la 2048_game/  # 或类似名称

你会看到完整的项目结构，包括源代码、测试文件、README 等。

💡 提示: 第一次运行需要下载模型依赖和 Node.js 依赖（用于图表渲染），可能需要 2-5 分钟。确保网络畅通。

第三章 安装与 Python 环境

3.1 Python 版本要求

MetaGPT 要求 Python 3.9 或更高版本，但必须低于 Python 3.12。这是因为 MetaGPT 依赖的一些库（如某些 AST 解析工具）尚未完全支持 Python 3.12。推荐使用 Python 3.10 或 3.11。

检查当前 Python 版本：

python3 --version

3.2 使用虚拟环境（推荐）

强烈建议在虚拟环境中安装 MetaGPT，避免与系统 Python 包冲突。

使用 venv：

python3 -m venv metagpt-env
source metagpt-env/bin/activate  # macOS / Linux
或者 Windows: metagpt-env\Scripts\activate

使用 conda（如果你用 Anaconda）：

conda create -n metagpt python=3.11
conda activate metagpt

在虚拟环境中安装：

pip install --upgrade metagpt

3.3 Node.js 依赖

MetaGPT 使用 mermaid.js 生成架构图和流程图，这需要 Node.js 环境。如果你没有安装 Node.js：

macOS 使用 Homebrew：

brew install node
npm install -g pnpm

Ubuntu/Debian：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g pnpm

验证安装：

node --version
pnpm --version

3.4 解决依赖冲突

如果你遇到依赖冲突错误，可以尝试：

pip install --upgrade pip setuptools wheel
pip install metagpt --no-deps  # 仅安装核心包
pip install metagpt[all]  # 安装全部依赖（包括可选子模块）

或者使用低版本依赖模式：

pip install --upgrade metagpt==0.7.0  # 回退到稳定版本

💡 提示: 如果你只需要核心功能（不涉及 mermaid 图表），可以跳过 Node.js 安装。但推荐安装，因为图表能直观展示 Agent 的思维过程。

3.5 Windows 用户特别说明

Windows 用户强烈建议使用 WSL2（Windows Subsystem for Linux）：

# 在 PowerShell（管理员）中执行
wsl --install -d Ubuntu-22.04

然后在 WSL2 中按 Linux 方式安装。如果在原生 Windows 上安装，可能需要处理一些路径和权限问题。

第四章 配置 LLM API

LLM API 配置是 MetaGPT 使用中最关键也最容易出错的环节。本章详细介绍各种配置方案。

4.1 配置文件位置

MetaGPT 的配置文件位于 ~/.metagpt/config2.yaml。创建默认配置：

metagpt --init-config

4.2 OpenAI 配置

最直接的配置方式：

llm:
  api_type: "openai"
  api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4-turbo"
  temperature: 0.1
  max_tokens: 8192

参数说明：

• temperature: 越低越稳定（0.1-0.3 适合代码生成，0.7+ 适合创意任务）
• max_tokens: 限制每次生成的 token 数。代码生成建议 4096+

4.3 配置多个 LLM（用于不同角色）

高级用法：为不同角色配置不同的模型：

llm:
  api_type: "openai"
  api_key: "sk-xxx"
  base_url: "https://api.openai.com/v1"
  model: "gpt-4-turbo"

role_llm:
  ProductManager:
    api_type: "openai"
    api_key: "sk-xxx"
    model: "gpt-4-turbo"
  Architect:
    api_type: "openai"
    api_key: "sk-xxx"
    model: "gpt-4-turbo"
  Engineer:
    api_type: "openai"
    api_key: "sk-xxx"
    model: "claude-3-5-sonnet-20241022"
    base_url: "https://api.anthropic.com/v1"

这样 PM 和架构师用 GPT-4，工程师用 Claude 3.5 Sonnet，各取所长。

4.4 配置国产模型

国产模型（以 DeepSeek 为例）：

llm:
  api_type: "deepseek"
  api_key: "sk-your-deepseek-key"
  base_url: "https://api.deepseek.com/v1"
  model: "deepseek-chat"

通义千问（Qwen）：

llm:
  api_type: "openai"  # 兼容 OpenAI 格式
  api_key: "sk-your-dashscope-key"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  model: "qwen-turbo"

智谱 GLM-4：

llm:
  api_type: "zhipuai"
  api_key: "your-zhipu-api-key"
  model: "glm-4"

4.5 成本控制

MetaGPT 每次项目运行会消耗大量 token。以一个中型项目为例：

省钱技巧：

• 先用 GPT-4o mini 或 DeepSeek 快速迭代需求，最后用 GPT-4 生成正式代码
• 降低 max_tokens 和 temperature
• 减少多轮对话（在 prompt 中一次性给出完整需求）
• 使用本地模型（Ollama）处理非关键角色

💡 提示: 配置 LLM 是 MetaGPT 的 #1 痛点。如果遇到报错 "LLM API call failed"，先检查 API Key 是否有效、base_url 是否写对、模型名是否支持。

第五章 多角色协作详解

5.1 SOP 机制

MetaGPT 的核心是SOP（标准作业流程）机制。它将软件开发的完整流程编码为一系列结构化的步骤：

1. 需求分析：PM 分析用户需求，拆解为功能点
2. PRD 撰写：PM 编写产品需求文档，包含功能列表、用户故事、验收标准
3. 技术设计：Architect 设计系统架构、技术选型、接口定义
4. 任务拆分：PM 将需求拆分为具体开发任务
5. 编码实现：Engineer 按任务编码，自动化测试
6. 代码审查：QA Engineer 审查代码质量和测试覆盖

5.2 角色分工

5.3 对话流程示例

当你输入需求后，MetaGPT 内部会按以下顺序自动执行：

Step 1: PM 分析需求

"I need to analyze the user's requirements for a 2048 game. The key features are: game board, tile movement, scoring, win/lose detection."

Step 2: Architect 设计技术方案

"Based on the PRD, I recommend using HTML + CSS + JavaScript (vanilla) for this game. No external dependencies needed."

Step 3: Engineer 编码

"I'll implement the game board as a 4x4 grid, with keyboard event listeners for arrow keys..."

整个过程不需要你介入，MetaGPT 自动完成角色切换和信息传递。

5.4 自定义角色

你可以创建自定义角色来处理特殊场景。在 ~/.metagpt/config2.yaml 中添加：

custom_roles:
  - name: "DevOps Engineer"
    profile: "DevOps Engineer"
    goal: "Design and implement CI/CD pipelines, infrastructure as code"
    constraints: "Follow DevOps best practices, ensure security compliance"

然后在 Python 代码中使用：

from metagpt.roles import Role
from metagpt.environment import Environment

devops = Role(name="DevOps Engineer", profile="DevOps Engineer",
              goal="Design CI/CD pipelines",
              constraints="Follow best practices")
env = Environment()
env.add_role(devops)

5.5 增量开发模式

MetaGPT 支持在已有项目基础上进行增量开发。只需提供项目路径：

metagpt "Add a high score feature to the 2048 game" --project-path ./workspace/2048_game

MetaGPT 会分析现有代码结构，理解上下文，然后只生成新增功能的代码，不会覆盖已有逻辑。

第六章 实战项目

6.1 项目一：2048 游戏（入门）

这是 MetaGPT 的经典入门项目：

metagpt "Create a 2048 game using HTML, CSS, and JavaScript"

生成后进入项目目录：

cd workspace
ls -la
#找到生成的 2048 目录
cd 2048_game  # 具体目录名可能不同
#启动一个 HTTP 服务器查看效果
python3 -m http.server 8000

打开浏览器访问 http://localhost:8000 即可看到游戏。

6.2 项目二：待办事项应用（Web App）

metagpt "Create a todo list web application with Flask, SQLite backend, and Bootstrap frontend. Include user authentication, add/edit/delete tasks, and task categories."

这个项目会生成完整的 Flask 应用，包含数据库模型、路由、模板和静态文件。

6.3 项目三：RESTful API 服务

metagpt "Create a RESTful API service for a blog platform using FastAPI. Include CRUD for posts, comments, and users. Use SQLAlchemy for ORM and JWT for authentication."

生成后运行：

cd workspace/blog_api
pip install -r requirements.txt
uvicorn main:app --reload

6.4 项目四：数据分析任务

使用 Data Interpreter 模块：

# 从 Python 代码中使用 Data Interpreter
python3 -c "
from metagpt.roles.data_interpreter import DataInterpreter
di = DataInterpreter()
await di.run('Load the CSV file sales.csv, analyze monthly trends, and generate a visualization report')
"

💡 提示: Data Interpreter 是 MetaGPT 的独立子模块，专注于数据分析场景。它支持 pandas、matplotlib、plotly 等数据科学生态。

6.5 项目五：多 Agent 辩论

让多个 Agent 就某个问题进行辩论：

# 在 Python 脚本中使用
python3 -c "
from metagpt.team import Team
team = Team()
team.run('Debate: Should we use microservices or monolith for a startup?')
"

不同角色的 Agent 会从各自角度发表观点，最终汇总结论。

第七章 进阶技巧

7.1 省钱策略

• 使用便宜模型进行迭代：先用 GPT-4o mini 或 DeepSeek 验证需求，最后才用 GPT-4 生成最终代码
• 缓存机制：MetaGPT 支持缓存 LLM 调用结果，避免重复消耗：
  cache: enable: true type: "disk" path: "~/.metagpt/cache"
• 减少角色数量：使用最小角色配置，比如只用 PM + Engineer，跳过 Architect 和 QA
• 限制迭代轮次：设置最大对话轮次，避免无限循环

7.2 使用子模块

MetaGPT 包含多个可选子模块，按需安装：

# 安装特定子模块
pip install metagpt[rag]         # 检索增强生成
pip install metagpt[ocr]         # 光学字符识别
pip install metagpt[search-google]  # Google 搜索
pip install metagpt[selenium]    # 浏览器自动化
#安装全部
pip install metagpt[all]

7.3 自定义 Prompt 模板

在配置文件中自定义各个角色的 Prompt：

prompt_templates:
  ProductManager:
    write_prd: |
      You are a senior product manager. Write a detailed PRD for the following requirement.
      Include:
      - Product overview
      - User stories
      - Functional requirements
      - Non-functional requirements
      - Acceptance criteria

      Requirement: {requirement}
  Engineer:
    write_code: |
      You are a senior software engineer. Implement the following task.
      Follow these guidelines:
      - Write clean, well-documented code
      - Include error handling
      - Add unit tests
      - Follow {language} best practices

7.4 增量开发与迭代

在已有项目上添加功能：

metagpt "Add dark mode support" --project-path ./workspace/my_project --incremental

MetaGPT 会先分析现有代码，理解项目结构和风格，然后只生成变更部分。

7.5 批量生成和脚本化

用 Python 脚本批量执行：

from metagpt.software_company import SoftwareCompany

company = SoftwareCompany()
company.start_project("Create a calculator app")
company.run(n_rounds=10)
result = company.get_result()
print(f"Project generated at: {result.workspace}")

7.6 使用 Researcher 模块

进行多角度研究：

from metagpt.roles.researcher import Researcher

researcher = Researcher()
report = await researcher.run("Research the latest trends in AI Agent frameworks")
print(report)

第八章 常见问题与排错

8.1 安装问题

Q: pip install 报错 "No matching distribution found for metagpt"

A: 检查 Python 版本（需 3.9-3.11）。升级 pip：pip install --upgrade pip。尝试使用国内镜像：pip install metagpt -i https://pypi.tuna.tsinghua.edu.cn/simple

Q: 安装依赖冲突

A: 在干净的虚拟环境中安装：

python3 -m venv fresh-env
source fresh-env/bin/activate
pip install --upgrade pip
pip install metagpt

8.2 配置问题

Q: "LLM API call failed" 错误

A: MetaGPT 配置的 #1 痛点。检查以下三件事：

• API Key 是否正确且未过期：echo $OPENAI_API_KEY
• base_url 是否正确（特别是使用代理时，注意 /v1 后缀）
• 模型名是否被 API 支持：curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

Q: config2.yaml 文件在哪里？

A: 执行 metagpt --init-config 后，文件在 ~/.metagpt/config2.yaml。你也可以在当前项目目录下放一个 config2.yaml，优先级高于全局配置。

8.3 运行问题

Q: 运行后没有任何输出

A: 设置日志级别为 DEBUG：

export METAGPT_LOG_LEVEL=DEBUG
metagpt "Create a 2048 game"

Q: 生成的项目不完整或代码有错误

A: 这是常见情况。原因和对策：

• LLM 模型太弱：改用 GPT-4 或 Claude 3.5
• 需求不够具体：给出更详细的描述，包括技术栈、功能列表
• token 限制：增加 max_tokens 配置
• 多运行几次：LLM 有随机性，同一个需求生成多次选最好的

Q: Mermaid 图表无法渲染

A: 确保安装了 Node.js 和 pnpm：

node --version && pnpm --version
#如果没有，重新安装
npm install -g pnpm

8.4 网络问题

Q: 国内用户无法访问 OpenAI API

A: 三种解决方案：

• 使用国内模型（DeepSeek、GLM-4、Qwen）
• 配置 HTTP 代理：export HTTP_PROXY=http://127.0.0.1:7890 export HTTPS_PROXY=http://127.0.0.1:7890
• 使用 API 中转服务，在 base_url 中配置中转地址

Q: 超时错误

A: 在配置中增加超时时间：

llm:
  timeout: 300  # 5 分钟超时
  retry: 3      # 失败重试 3 次

8.5 其他常见问题

Q: 项目生成在哪个目录？

A: 默认在 ./workspace 目录。可以在配置中修改：workspace: "./my_projects"

Q: 如何中断运行？

A: 按 Ctrl+C 中断。如果进程不响应，用 kill -9 [PID]。

Q: 如何查看详细的运行日志？

A: 日志文件默认在 ~/.metagpt/logs/ 目录下。

Q: 支持哪些 Python 框架？

A: Flask、FastAPI、Django、纯 Python 等主流框架都支持。在需求中指定即可。

💡 提示: 遇到问题先检查三件事：(1) Python 版本是否 3.9-3.11 (2) LLM API 配置是否正确 (3) Node.js 环境是否可用。90% 的问题出在这三处。

附录：命令速查表

安装相关

配置相关

运行相关

环境验证

排错命令