OpenManus — 架构与原理

30 秒导读： OpenManus 是开源版的「Manus」——一个能自己调用工具（写代码、开浏览器、改文件、搜网页）来完成你交给它的任意任务的通用 AI agent。它的骨架是一条清晰的继承链和一个反复「想一步 → 做一步」的循环；复杂任务再套一层「先做计划、再逐步执行」的调度层。

本项目较大（多个子系统：agent 继承链、工具系统、MCP 远程工具、计划流），所以拆成多篇。先读本页建立全景，再按下方阅读地图下钻。

1. 这是什么（零基础也能懂）

一句话定义： OpenManus 是一个通用型 AI agent 框架——你给它一句话（"帮我分析这个 CSV 并画张图"），它会自己决定该用哪个工具、一步步执行，直到把事办完。
解决什么问题 / 给谁用： 商业产品 Manus 很强但要邀请码。OpenManus 想做一个人人可跑、可魔改的替代品。给两类人用：
- 想要一个"能动手"的 AI 助手的普通用户（跑 main.py 输入任务即可）。
- 想研究 / 二次开发 agent 的工程师（继承 ToolCallAgent 就能造自己的专用 agent）。
它能做什么（功能）：
- 执行 Python 代码（PythonExecute）
- 操作浏览器：导航、点击、填表、抓内容（BrowserUseTool）
- 读写 / 编辑文件（StrReplaceEditor）
- 联网搜索（WebSearch）
- 通过 MCP（Model Context Protocol，模型上下文协议） 接入任意外部工具服务器
- 对复杂任务：先生成一份计划，再逐步执行（PlanningFlow）
用起来什么样： 一条命令行交互——

$ python main.py
Enter your prompt: 帮我在 workspace 里建一个 hello.py 并运行它
# agent 开始一步步：想 → 调 StrReplaceEditor 建文件 → 调 PythonExecute 运行 → terminate

入口极薄（main.py）：创建一个 Manus agent，把用户输入喂给 agent.run(prompt)，剩下全交给循环。

一句话直觉 / 类比： 把它想成一个装了工具箱的实习生。你交代任务，他脑子里反复念叨"现在该干嘛？"（think），然后伸手从工具箱里拿一件工具用一下（act），看看结果，再想下一步——直到他喊"我干完了"（terminate）。

2. 顶层全景（它大概怎么转）

2.1 两种运行模式

OpenManus 有两个入口，对应两种复杂度：

入口	模式	适合	核心对象
`main.py`	单 agent 直跑	简单/中等任务	`Manus`
`run_flow.py`	计划流调度	需要拆步骤的复杂任务	`PlanningFlow` + 若干 agent

本页和 §01–03 讲单 agent 直跑这条主线（最核心）；§04 单独讲计划流。

2.2 结构总图

怎么读这张图：竖着是「继承链」（下层复用上层能力），右边挂的是每个 agent 手里的「工具箱」。

         用户 prompt
             │
             ▼
   ┌─────────────────────┐
   │  BaseAgent          │  运行循环 run()：while 步数没超 且 没结束 { step() }
   │  （抽象）            │  + 状态机 IDLE/RUNNING/FINISHED/ERROR + 记忆 Memory + 卡死检测
   └─────────┬───────────┘
             │ 继承，补上 step() = think() + act()
   ┌─────────▼───────────┐
   │  ReActAgent（抽象）  │  step() 拆成两个抽象方法：think()「想」/ act()「做」
   └─────────┬───────────┘
             │ 继承，实现 think/act = 一次工具调用
   ┌─────────▼───────────┐        ┌──────────────────────────┐
   │  ToolCallAgent      │───────▶│ ToolCollection（工具箱）  │
   │  think(): 问 LLM 要 │        │  CreateChatCompletion    │
   │          tool_calls │        │  Terminate               │
   │  act():  执行工具    │        └──────────────────────────┘
   └─────────┬───────────┘
             │ 继承，换成更全的工具箱 + MCP
   ┌─────────▼───────────┐        ┌──────────────────────────┐
   │  Manus（成品）       │───────▶│ PythonExecute            │
   │                     │        │ BrowserUseTool           │
   │                     │        │ StrReplaceEditor         │
   │                     │        │ AskHuman / Terminate     │
   │                     │        │ + MCP 远程工具（动态挂）  │
   └─────────────────────┘        └──────────────────────────┘

2.3 部件一句话职责

部件	干什么	在哪个文件
`BaseAgent`	定义运行循环、状态机、记忆、卡死检测；`step()` 留空给子类	`app/agent/base.py`
`ReActAgent`	把 `step()` 拆成抽象的 `think()` / `act()`（想-做范式）	`app/agent/react.py`
`ToolCallAgent`	实现 think=向 LLM 要工具调用、act=执行工具，是所有实用 agent 的父类	`app/agent/toolcall.py`
`Manus`	成品通用 agent，配齐工具箱 + 接 MCP	`app/agent/manus.py`
`LLM`	包装 OpenAI/Azure/Bedrock，管 token 计数、重试、`ask_tool`	`app/llm.py`
`BaseTool` / `ToolResult`	所有工具的基类 + 统一结果结构	`app/tool/base.py`
`ToolCollection`	工具箱：注册、按名执行、转成 LLM 的 function 定义	`app/tool/tool_collection.py`
`MCPClients` / `MCPClientTool`	连接外部 MCP 服务器，把远程工具伪装成本地工具	`app/tool/mcp.py`
`PlanningFlow` / `PlanningTool`	先生成计划、再逐步派 agent 执行	`app/flow/planning.py`, `app/tool/planning.py`

2.4 主线走一遍（高层，不进代码）

以 main.py 跑 Manus 为例，一次任务的生命周期：

1. Manus.create() ─ 建 agent，连好配置里的 MCP 服务器
2. agent.run(prompt)
     ├─ 把 prompt 存进 memory（user 消息）
     └─ 进入循环 while 步数<max 且 状态≠FINISHED：
           step() = think() + act()
             think(): 把 memory + 工具清单发给 LLM，拿回「要调哪些工具」
             act():   逐个执行工具，结果写回 memory
           （每步后查一次「是否卡死」，卡了就注入换策略的提示）
3. 某次 act 执行了 terminate 工具 ⇒ 状态置 FINISHED ⇒ 跳出循环
4. cleanup()：关浏览器、断开 MCP

这条 「think → act → 写回记忆 → 再 think」 的循环，就是整个项目的心脏。它叫 ReAct（Reasoning + Acting，推理与行动交替）。

3. 阅读地图（建议顺序）

按下面顺序读，就是一条由浅入深的路径：

01-agent-core.md — 智能体核心。 BaseAgent 的 run() 循环、四态状态机、Memory、卡死检测。理解这层，就懂了"agent 到底在循环什么"。
02-react-toolcall.md — 想-做循环与工具调用。 ReActAgent 的 think/act 拆分，ToolCallAgent 如何把 LLM 返回的 tool_calls 变成真实执行、特殊工具 terminate 如何结束循环。这是最核心的一章。
03-tools-and-mcp.md — 工具系统与 MCP。 BaseTool/ToolResult/ToolCollection 的设计，以及 MCPClientTool 如何把远程工具伪装成本地工具。
04-planning-flow.md — 计划流。 PlanningFlow 如何用 LLM 生成计划、逐步标记状态、把每一步派给合适的 agent 执行。

4. 横向对比（同 shelf 的取舍）

OpenManus 在 ai-agent-reference 里属于"从零手写 ReAct 循环 + 工具调用"这一派——不依赖 LangChain 之类的编排框架，整套循环、状态机、工具协议都是自己实现的几百行代码，非常适合当"教科书级" agent 骨架来读。

与依赖大型编排框架的 agent 相比：OpenManus 的循环是显式的、可读的（BaseAgent.run 一眼看完），代价是并发/流式/分支等高级编排要自己加。
与"单一巨型 prompt"式 agent 相比：OpenManus 用继承链把"循环 / 想-做 / 工具执行 / 成品"分了四层，扩展点清晰。
MCP 支持让它能即插即用接第三方工具服务器，这点和现代 agent（Claude/Cursor 等走 MCP 的生态）对齐。

5. 代码地图（导航索引）

主题	文件路径	符号名
入口（单 agent）	`main.py`	`main`
入口（计划流）	`run_flow.py`	`run_flow`
运行循环 / 状态机	`app/agent/base.py`	`BaseAgent.run`, `BaseAgent.state_context`, `AgentState`
想-做范式	`app/agent/react.py`	`ReActAgent.think`, `ReActAgent.act`, `ReActAgent.step`
工具调用实现	`app/agent/toolcall.py`	`ToolCallAgent.think`, `ToolCallAgent.act`, `ToolCallAgent.execute_tool`
成品 agent	`app/agent/manus.py`	`Manus`, `Manus.create`
LLM 封装	`app/llm.py`	`LLM.ask_tool`, `LLM.ask`
工具基类	`app/tool/base.py`	`BaseTool`, `ToolResult`
工具箱	`app/tool/tool_collection.py`	`ToolCollection.execute`, `ToolCollection.to_params`
MCP 远程工具	`app/tool/mcp.py`	`MCPClientTool`, `MCPClients.connect_stdio`
计划流	`app/flow/planning.py`	`PlanningFlow.execute`, `PlanningFlow._create_initial_plan`
计划工具	`app/tool/planning.py`	`PlanningTool.execute`

1. 这是什么（零基础也能懂）​

2. 顶层全景（它大概怎么转）​

2.1 两种运行模式​

2.2 结构总图​

2.3 部件一句话职责​

2.4 主线走一遍（高层，不进代码）​

3. 阅读地图（建议顺序）​

4. 横向对比（同 shelf 的取舍）​

5. 代码地图（导航索引）​