Manus：从泄露物还原架构
一句话：Manus 没有源码，但它的 29 个工具定义、agent loop 和四个外置模块都在公开流传，加上官方两篇技术材料，足够还原出一个可信的架构图。
一、先把材料硬度说清楚
这一篇和 02 Kimi CLI 性质不同。Kimi 那篇每一行都是官方仓库里的代码，这篇是拼图。所以先标清楚每块材料的来源和可信度：
| 材料 | 内容 | 来源 | 硬度 |
|---|---|---|---|
Agent loop.txt 2.1KB | 六步循环 | 社区泄露仓库 | ⚠️ 非官方 |
Modules.txt 12KB | 20 个 XML 标签的完整 system prompt | 社区泄露仓库 | ⚠️ 非官方 |
Prompt.txt 10KB | 另一份 prompt | 社区泄露仓库 | ⚠️ 非官方 |
tools.json 18.5KB | 29 个工具的完整 JSON Schema | 社区泄露仓库 | ⚠️ 非官方 |
| Context Engineering for AI Agents | 六条上下文工程原则 | manus.im 官方博客 | ✅ 官方一手 |
| Wide Research 产品页 | 多 Agent 架构说明 | manus.im 官方 | ✅ 官方一手 |
泄露物来自 x1xhlol/system-prompts-and-models-of-ai-tools（142,905★，最后更新 2026-08-11）里的 Manus Agent Tools & Prompt/ 目录。
本文的处理原则：泄露物用来还原「有哪些零件」，官方材料用来验证「为什么这么设计」。凡是两边能对上的，可信度高；只有泄露物支持的，会明确标注。
复现方式：
curl -sL "https://raw.githubusercontent.com/x1xhlol/system-prompts-and-models-of-ai-tools/main/Manus%20Agent%20Tools%20%26%20Prompt/tools.json" -o manus-tools.json
二、29 个工具：一台电脑的完整切面
tools.json 里正好 29 个工具，按前缀分成七组：
| 组 | 工具 | 数量 |
|---|---|---|
| message | message_notify_user、message_ask_user | 2 |
| file | file_read、file_write、file_str_replace、file_find_in_content、file_find_by_name | 5 |
| shell | shell_exec、shell_view、shell_wait、shell_write_to_process、shell_kill_process | 5 |
| browser | browser_view、browser_navigate、browser_restart、browser_click、browser_input、browser_move_mouse、browser_press_key、browser_select_option、browser_scroll_up、browser_scroll_down、browser_console_exec、browser_console_view | 12 |
| info | info_search_web | 1 |
| deploy | deploy_expose_port、deploy_apply_deployment | 2 |
| 其他 | make_manus_page、idle | 2 |
三个观察：
① 浏览器占了 12 个，接近一半。 这就是 Manus「像个真人在用电脑」体感的来源。而且注意它不是「给我一个网页的文本」这种粗粒度工具，而是 click / input / scroll / press_key / select_option 这种逐个动作拆开的细粒度工具。粗粒度工具好写但模型控制不了细节，细粒度工具让模型真的在操作 UI。
② browser_console_exec 和 browser_console_view 是个大杀器。 直接在页面里执行 JS 并读取控制台——意味着它可以绕过所有 DOM 解析的麻烦，直接跑脚本抓数据。
③ shell_write_to_process 和 shell_wait 说明 shell 不是「跑一条命令拿输出」。 有 wait、有 write_to_process、有 kill_process，说明 shell 是长期存活的会话，Agent 可以启动一个进程、往它 stdin 里写东西、等它、再杀掉。这是「真的在用一台电脑」和「调用一个函数」的分水岭。
④ 有 idle 这个工具。 「什么都不做，进入待机」被做成了一个显式的工具。这解决了 Agent 工程里一个很实际的问题：怎么知道模型认为自己干完了。让它显式调用 idle 比解析文本判断可靠得多。
三、Agent Loop：一次只调一个工具
泄露的 Agent loop.txt（⚠️ 非官方）里的六步：
- Analyze Events: Understand user needs and current state through event stream
- Select Tools: Choose next tool call based on current state, task planning, relevant knowledge and available data APIs
- Wait for Execution: Selected tool action will be executed by sandbox environment with new observations added to event stream
- Iterate: Choose only one tool call per iteration, patiently repeat above steps until task completion
- Submit Results: Send results to user via message tools
- Enter Standby: Enter idle state when all tasks are completed
第 4 步「一次迭代只选一个工具」是个重要的架构信号。
对比一下：Kimi CLI 的 explore 子 Agent 的 prompt 里明确鼓励「spawn multiple parallel tool calls for grepping and reading files to maximize speed」。两家取向完全相反。
Manus 选串行的代价是慢，收益是事件流严格线性——这直接支撑了它整个上下文工程策略（见第五节）。并行工具调用会让事件流变成偏序，KV-cache 前缀的稳定性就难保证了。
四、四个外置模块：Manus 架构里最容易被忽略的部分
泄露的 Modules.txt（⚠️ 非官方）里，事件流被定义为七种事件类型：
- Message: Messages input by actual users
- Action: Tool use (function calling) actions
- Observation: Results generated from corresponding action execution
- Plan: Task step planning and status updates provided by the Planner module
- Knowledge: Task-related knowledge and best practices provided by the Knowledge module
- Datasource: Data API documentation provided by the Datasource module
- Other miscellaneous events
注意 4、5、6 这三种事件：它们不是 Agent 调工具产生的，是系统「推」进事件流的。
这是 Manus 架构里最关键、也最容易被忽略的一点。大部分人复刻 Manus 只复刻了工具循环，漏掉了这三个外置模块：
4.1 Planner Module —— 规划器在循环外面
- System is equipped with planner module for overall task planning
- Task planning will be provided as events in the event stream
- Task plans use numbered pseudocode to represent execution steps
- Each planning update includes the current step number, status, and reflection
- Must complete all planned steps and reach the final step number by completion
规划不是主 Agent 自己做的，是一个独立模块做完之后当事件塞进来的。 而且规划以「带编号的伪代码」形式表达，主 Agent 必须走完所有编号步骤。
这跟绝大多数框架的做法相反——LangGraph、CrewAI 那些都是让 Agent 自己调一个 plan 工具。Manus 把规划提到了循环外面，主 Agent 只负责执行。
对照 Kimi CLI：Kimi 的 plan 是一个子 Agent 工种，仍然在 Agent 体系内。Manus 的 Planner 是系统组件，在 Agent 体系外。
4.2 Knowledge Module —— 带作用域的最佳实践注入
- Task-relevant knowledge will be provided as events in the event stream
- Each knowledge item has its scope and should only be adopted when conditions are met
「每条知识有自己的作用域，只在条件满足时采纳」——这是个 RAG 变体，但检索出来的不是文档，是行为规范。
4.3 Datasource Module —— 数据 API 必须用 Python 调，不能当工具
这条规则很特别：
- Data APIs must be called through Python code and cannot be used as tools
- Save retrieved data to files instead of outputting intermediate results
泄露物里甚至带了代码样例：
import sys
sys.path.append('/opt/.manus/.sandbox-runtime')
from data_api import ApiClient
client = ApiClient()
weather = client.call_api('WeatherBank/get_weather', query={'location': 'Singapore'})
print(weather)
为什么数据 API 不做成工具？ 因为工具定义会常驻在每一轮的 prompt 里。几百个数据源做成几百个工具，光工具描述就能吃掉几万 token，而且 KV-cache 前缀会随着可用工具变化而失效。改成「写 Python 调库」，工具数永远只有 shell_exec 那一个，API 文档按需以 Datasource 事件注入。
这一条是整篇里最值得抄的设计。 它跟官方博客里的「Mask, Don't Remove」是同一个思路的两种落地。
⚠️ 注意：
/opt/.manus/.sandbox-runtime这个路径来自泄露物，官方从未确认。
4.4 todo.md —— 规划的落地副本
- Create todo.md file as checklist based on task planning from the Planner module
- Task planning takes precedence over todo.md, while todo.md contains more details
- Update markers in todo.md via text replacement tool immediately after completing each item
- Rebuild todo.md when task planning changes significantly
层次关系是：Planner 的伪代码是权威，todo.md 是它的细化副本，两者不一致时以 Planner 为准。
这个 todo.md 的作用在官方博客里有正面解释，见下一节第 4 条。
五、官方博客的六条：和泄露物严丝合缝
Context Engineering for AI Agents: Lessons from Building Manus 是官方一手材料。开篇就说他们把 Agent 框架重写了四遍。
六条原则，每一条都能在泄露的 prompt 里找到对应：
1️⃣ Design Around the KV-Cache
- Manus 的平均输入输出 token 比约 100:1
- Claude Sonnet 上缓存命中 3/MTok，10 倍差价
- 核心原则：prompt 前缀必须稳定，一个 token 的变化就会让后面全部失效
100:1 这个比例是理解整个设计的钥匙。一个 Agent 绝大部分开销在输入侧，所以 KV-cache 命中率几乎等价于成本本身。
所以别在 system prompt 里放时间戳。这是最经典的自杀方式——每一轮前缀都不一样，缓存 0 命中。
2️ ⃣ Mask, Don't Remove
用「上下文感知的状态机」来管工具可用性，而不是动态增删工具。
原因有两个：删工具会让 KV-cache 失效；而且历史里已经出现过的工具调用会引用到已删除的工具，造成 schema 违规。
做法是在解码时 mask 掉 logits，工具定义留在上下文里不动。这跟 4.3 节 Datasource 不做成工具是配套的：能不进工具列表的就不进，进了的就别再拿出来。
3️⃣ Use the File System as Context
把文件系统当成「无限大、天然持久、Agent 自己就能直接操作」的上下文。
关键概念是可恢复的压缩：网页正文可以从上下文里丢掉，但 URL 必须留着；文档内容可以丢，但路径要留。丢掉的东西随时能读回来，所以丢得起。
对照泄露的 file_rules 和 5 个 file 工具，这一条完全对得上。
4️⃣ Manipulate Attention Through Recitation
Manus 维护一个持续更新的
todo.md。平均一个任务约 50 次工具调用。
目的是把任务目标反复推进「最近注意力窗口」，对抗 lost-in-the-middle。
这条和泄露的 todo_rules 严丝合缝。 泄露物里说「每完成一项立刻用文本替换工具更新标记」——现在知道为什么了：不是为了给人看进度，是为了每隔几步就把目标重新写到上下文末尾。
50 次工具调用这个数字也值得对比：Kimi CLI 的 max_steps_per_turn 默认 1000。一个是实测均值，一个是上限，量级上是自洽的。
5️⃣ Keep the Wrong Stuff In
把失败的动作留在上下文里，模型会隐式地调整行为。错误恢复能力是「真 Agent」的核心指标。
这是反直觉的一条。大部分人的第一反应是把报错清掉免得污染上下文，但那样模型会在同一个坑里反复踩，因为它看不到自己踩过。
对照 Kimi CLI 的失败处理：Kimi 把子 Agent 的异常转成消息回传给父 Agent，本质上是同一个思路。
6️⃣ Don't Get Few-Shotted
上下文里重复出现同一种模式，模型会一直跟着那个模式走，哪怕已经不是最优解了。
解法是在序列化格 式和措辞上故意引入结构化的变化。
六、Wide Research：Manus 的多 Agent 部分
前面五节讲的都是单 Agent。Manus 的多 Agent 是 Wide Research 这个功能，官方页面说得很直接：
| 问题 | 官方说法 |
|---|---|
| 多少个子 Agent | 主 Agent 把请求拆成上百个独立子任务，规模可扩展到「hundreds」 |
| 一个子 Agent 是什么 | 自己的 VM、自己的工具、自己的联网，全新的上下文 |
| 子 Agent 之间 | "Sub-agents never talk to each other." 理由：防止上下文污染、减少幻觉 |
| 结果怎么收 | 主 Agent 收集所有结果并综合成最终报告 |
| 子 Agent 是什么角色 | 不预设角色，每个都是完整能力的 Manus 实例 |
最值得注意的是「不预设角色」。
CrewAI、MetaGPT 那一派的核心卖点是「给 Agent 分配角色」——产品经理、架构师、工程师、测试。Manus 反着来：每个子 Agent 都是完整的通用 Manus，区别只在于分到的任务不同。
这背后的判断是：角色分工的收益来自 prompt 特化，而 prompt 特化的收益，在模型足够强之后会趋近于零；但角色分工的成本——角色之间的交接损耗、职责边界的争议——不会消失。
隔离粒度是「一台 VM」，这是 本专题里最粗的一档。 代价是启动开销和账单，收益是彻底的故障隔离：一个子 Agent 把自己的机器搞死了，其他 99 个照跑。
七、五维打分
对照 01 的五个维度：
| 维度 | Manus 的答案 |
|---|---|
| D1 隔离单位 | 一台独立虚拟机（本专题最粗粒度） |
| D2 通信拓扑 | 严格星型，官方明确「子 Agent 之间从不交谈」 |
| D3 结果回收 | 主 Agent 收集全部结果后综合，具体裁剪策略未公开 |
| D4 递归深度 | 官方未公开；从「上百个子任务由主 Agent 拆分」的表述推测为单层 |
| D5 生命周期 | 一次性（未见 resume 机制的公开说明） |
一句话总结：Manus 的多 Agent 是用虚拟机换隔离的极端做法，而它真正的技术护城河其实在单 Agent 那一侧——KV-cache 优化、文件系统即上下文、todo.md 复述这套上下文工程。
八、和 Kimi CLI 横着比
| Manus | Kimi CLI | |
|---|---|---|
| 一轮几个工具调用 | 只能 1 个 | 鼓励并行 |
| 规划在哪 | 循环外的 Planner 模块，以事件注入 | 循环内的 plan 子 Agent 工种 |
| 子 Agent 有角色吗 | 没有，都是完整 Manus 实例 | 有，coder / explore / plan 三个工种 |
| 隔离单位 | 一台 VM | 一个 context.jsonl |
| 大量数据源怎么接 | 写 Python 调库，不进工具列表 | MCP（但子 Agent 拿不到） |
| 子 Agent 能否复活 | 未公开 | 可以，resume=agent_id |
两条路线的分歧点很清楚：Manus 相信「模型够强就别搞结构」，所以子 Agent 不分角色、规划外置、工具尽量少；Kimi CLI 相信「结构能省钱」，所以分工种、绑不同模型、剥离工具权限。
考虑到 Manus 底座用的是别家模型而 Kimi 用自家模型，这个分歧其实也有商业逻辑：能控制模型的人倾向于把复杂度往模型里推，不能控制模型的人倾向于把复杂度留在工程层。 这条线在 08 里还会再出现。