NanoBot 深度解析:港大开源极简智能体框架的架构与实现
NanoBot 深度解析:港大开源极简智能体框架的架构与实现
本文基于对港大数据科学实验室(HKUDS)开源的 NanoBot 项目的系统梳理,从框架选型、核心架构、工具系统、消息处理到可观测性,完整呈现一个约 4000 行代码的极简 Agent 框架是如何做到"麻雀虽小,五脏俱全"的。
一、NanoBot 是什么:定位与背景
在 LangChain、AutoGen、CrewAI 等框架逐渐走向"重抽象"的当下,NanoBot 选择了一条截然相反的路:用最少的代码和最简单的抽象,把"Agent 循环"这一件事做到极致可控。它的核心代码仅约 4000 行,却实现了 OpenClaw 90% 以上的能力,同时保持了极高的可读性和可修改性。
理解 NanoBot 的定位,需要先厘清一个常见误解:它不基于任何外部编排框架。原版 NanoBot 并非构建在 LangChain 或 AutoGen 之上,它本身就是一个小型框架。它的底层依赖停留在协议与库层面——通过 LiteLLM 实现模型无关性(支持 OpenAI、Claude、Gemini、DeepSeek、vLLM 等),通过 MCP(Model Context Protocol) 接入外部工具生态,用纯 Python 实现,pip 安装即可运行。
需要注意区分:社区中另有一个名为 NanoBot.Net 的 C#/.NET 移植版,那个版本确实基于微软的 Microsoft.Agents.AI 框架构建。本文讨论的始终是港大原版。
从学习路径的角度看,NanoBot 恰好处于"读完最小 Agent 原理之后、深入真实项目源码"的理想位置:体量可控、核心循环短到可以在脑中执行,同时又保留了工具插件、MCP、多通道接入、子 Agent、上下文治理等一个真实 Agent 系统该有的骨架。
二、整体架构:四层解耦,控制面高度集中
NanoBot 在物理上分为四层,但逻辑上的"大脑"高度集中:
层级 核心职责 关键设计

这种分层的最大价值在于调试路径清晰:通道路由、会话管理、出站问题去 agent/loop.py;provider 调用、工具执行、迭代上限问题去 agent/runner.py。两个类的边界,就是两类问题的边界,不需要额外的编排抽象层来"解耦"。
三、核心引擎:AgentLoop 与 AgentRunner 的职责分离
这是 NanoBot 实现上最关键的一个拆分。
AgentLoop 面向"通道与回合",它不做具体的模型调用,只负责:
从 MessageBus 接收入站消息;
确定会话(session)和工作区(workspace)边界;
构建初始上下文(历史消息、系统提示词、记忆内容、技能索引);
装配 hooks、进度回调和通道元数据;
将 Runner 的最终结果封装为出站消息发布。
AgentRunner 才是真正面对 LLM 的循环,逻辑极其朴素:
while iteration < max_iterations:
response = await provider.chat(messages, tools)
if response.has_tool_calls:
for tool_call in response.tool_calls:
result = await tools.execute(tool_call.name, tool_call.arguments)
messages = add_tool_result(messages, tool_call.id, result)
else:
return response.content # 无 tool_calls,即为最终答案,跳出
几个值得注意的设计细节:
迭代上限作为安全阀,默认值为 40,核心作用是防止无限循环。被触及时的行为是返回已有结果并记录 warning,而不是抛出异常中断。
所有决策路径穿过同一个循环,没有旁路、没有隐藏的状态机分支。读完这一个函数,就理解了 Agent 的"思考-行动"全貌。
错误恢复全部委托给 LLM:系统只追加一句引导提示,让模型自行判断如何从工具错误中恢复,而非在代码中硬编码恢复策略。
四、记忆系统:主动放弃向量数据库
NanoBot 在记忆上的取舍非常果断:不用向量库,只用两个 Markdown 文件。
MEMORY.md 记录长期事实——用户是谁、偏好、项目上下文等稳定信息,始终被加载到系统提示词中,无需检索。
HISTORY.md 是仅追加(append-only) 的事件日志,记录带时间戳的对话摘要。它不主动加载,而是在需要时通过 grep 按需搜索。
这个选择的逻辑是:对于个人助手场景,记忆的确定性和可审计性比"语义相似度"更重要。grep 的结果完全可预测、零额外基础设施成本;而向量检索需要嵌入模型、向量库、相似度阈值调参,且存在"近似匹配"带来的不可控性。代价是当 HISTORY.md 极大时,grep 效率会下降,且无法做跨语义的模糊关联——但对于"个人助手"这一定位,这是被主动接受的取舍。
还有一个容易被忽略的细节:错误响应不会被持久化到 session history,目的是防止"400 中毒循环"——一旦某条错误格式的消息进入历史,后续每次上下文构建都会把它重新带给模型,导致持续报错。
五、上下文治理:ContextGovernor 的"节流"机制
Agent 循环跑得越久,上下文膨胀的风险越大。NanoBot 的 ContextGovernor 负责在模型调用前确保消息不超出上下文窗口,而不是等撞墙后再处理。
它的核心策略是 H/delta compaction:保留最近正在进行的 delta(增量) 消息,将较老的已接受历史 H(History) 压缩为一个检查点(checkpoint),同时保持 compaction 过程中产生的 tool call ID 稳定不变,避免后续模型调用因 ID 漂移而出错。
此外,AutoCompact 会在会话空闲时主动压缩较老的上下文,为下一次交互腾出空间,而不是被动等待溢出。工具执行结果在存入会话历史时会被截断为 500 字符,以控制上下文增长速率,但在当前回合内 LLM 仍能看到完整结果。
六、工具系统:极简接口与插件化架构
6.1 内置工具全览
NanoBot 的内置工具涵盖以下几个类别:
文件系统工具:ReadFileTool、WriteFileTool、EditFileTool 负责读写与编辑;ListDirTool、FindFilesTool、GrepTool 负责目录列举、文件查找与文本搜索。
执行与网络工具:ExecTool 执行 Shell 命令;WebSearchTool 与 WebFetchTool 负责网络搜索与网页抓取。
消息与系统管理:MessageTool 向用户发送消息;SpawnTool 派生子代理;CronTool 管理定时任务;MyTool(运行时自省工具)允许 Agent 检查和修改自身的运行时状态(模型、迭代次数、上下文窗口等)。
此外,NanoBot 通过 MCP 支持动态加载外部工具,这些工具会被包装为带命名空间前缀的原生 Tool 对象,与内置工具走完全相同的注册和执行路径,不引入第二套调用协议。
6.2 接口约束:返回值强制为 str
NanoBot 对工具接口的约束是极致的:execute 的返回值强制为 str。无论工具内部返回的是 JSON、列表还是结构化对象,必须在工具内部序列化为字符串。
这个看似"退化"的设计,换来的是 Runner 循环中绝对统一的处理逻辑——不需要对不同类型的返回值做分支判断。代价是 JSON Schema 需要手写,结构化数据要在工具侧序列化;而 LangChain 的 @tool 装饰器可以从类型注解自动生成 schema。这是一种典型的"用约束换简单"的工程取舍。
七、工具膨胀治理:如何避免 LLM 派遣混乱
工具越多,模型越容易用错工具或陷入循环。NanoBot 在多个层面采取了措施,其中最核心的是子代理的工具裁剪。
策略一:子代理的工具裁剪(动态隔离)
当主 Agent 通过 SpawnTool 派生子代理时,并非简单复制所有工具,而是执行一次严格的"工具裁剪":子代理在创建时克隆主 Agent 的工具注册表,但强制移除 SpawnTool 和 MessageTool。
移除 SpawnTool:防止子代理再次派生子代理,彻底杜绝无限递归派遣。
移除 MessageTool:限制子代理的直接通信能力,让它专注执行具体子任务,结果统一通过 MessageBus 回注给主 Agent。
通过这种裁剪,每个子代理获得的都是恰好够用的工具集,有效避免了工具间互相干扰,也降低了模型的选择难度。
策略二:工具排序的稳定前缀(静态优化与缓存友好)
ToolRegistry 每次向 LLM 提供工具定义时,内置工具会作为稳定前缀排在前面,并进行稳定排序(如按 schema 名称),结果被缓存直到注册表变更才失效。这不仅让模型输入更加稳定可预测,也最大化了对 Prompt Caching 的利用效率,避免因工具顺序频繁变动而击穿缓存。
策略三:技能(Skill)的渐进式加载
技能并非工具,但同样占用给模型的指令空间。NanoBot 采用渐进式加载:系统只注入一个轻量的 XML 索引(技能名称与简要描述),只有当模型根据索引判断某个技能相关并决定"使用"它时,完整的技能文档才会被加载。这是一种按需的懒加载,从源头控制了上下文膨胀。
八、Coding 能力:能做什么,不能做什么
NanoBot 可以支持 Coding 任务,且具备相应工具链,但它的设计定位与 Claude Code 这类专用编程 Agent 有本质区别——将编码作为通用工具集能覆盖的众多场景之一,而非围绕代码编辑器构建一切。
它依赖内置工具实现编码:ReadFileTool / WriteFileTool / EditFileTool 直接读写修改代码文件;ExecTool 执行 Shell 命令,是运行测试、构建项目、执行脚本的基础;官方指南明确提到 NanoBot 可以管理 Git 仓库,执行提交、分支、回滚等操作。v0.1.5 版本还引入了 “programming Agent SDK”,为开发者提供了更便利的编程接口。
但需要正视一个核心局限:缺乏原生的代码 Diff 展示。社区中有用户明确询问编码能力,核心开发者的回应很坦诚——“nanobot 没有直接的渠道可以用来给你展示它修改了什么,你可以通过独立编辑器看 diff,也可以通过 github 的 pr 界面看 diff”。这意味着你无法在对话流中直接"看到"它改了哪几行代码,必须切换到外部工具审查变更。不过开发者补充道:“只要你配置了适合用来编程的模型,并设置正确的 context window,nanobot 不会比任何 coding agent 表现差”——其代码质量上限更多取决于底层 LLM 的能力和配置。
适用场景判断:通过 IM(Telegram/飞书等)远程触发编码、自动化脚本编写与系统管理,非常适合;需要即时 Diff 反馈的交互式开发,不太适合;大型项目的深度重构,需谨慎评估约 4000 行极简架构在超大型代码库上的上下文管理健壮性。
九、消息处理全链路:从外部消息到 Agent 响应
NanoBot 对外部消息的响应构建在一条清晰的异步管道之上,核心设计思想是"三层解耦":将平台差异(Channel)、消息流转(MessageBus)与 Agent 决策(AgentLoop)彻底分开,使核心逻辑不关心消息来自 Telegram 还是 CLI,只处理统一的 InboundMessage。
第一站:Channel 层——平台消息的统一化
每个支持的平台都有一个继承自 BaseChannel 的适配器,职责单一且明确:协议转换。以 Telegram 为例,Channel 从平台事件中提取发送者 ID、聊天 ID 和文本内容,封装成标准的 InboundMessage 推送到 MessageBus 入站队列。这种适配器模式使得新增一个平台无需触及 Agent 核心的任何一行代码。
第二站:MessageBus——异步解耦的枢纽
MessageBus 通过双队列设计将消息的"接收"与"处理"彻底解耦:

InboundMessage 携带路由所需的关键元数据:channel(平台标识)、sender_id、chat_id,以及一个计算属性 session_key(格式为 {channel}:{chat_id})。这个 session_key 是会话隔离的基石——确保来自不同平台或不同对话的消息被路由到各自独立的会话上下文中。MessageBus 基于 asyncio.Queue 实现,实现了并发排队、顺序处理的非阻塞模型。
第三站:AgentLoop——面向通道的"回合"编排器
AgentLoop 从 Inbound Queue 持续拉取消息,依次完成:根据 session_key 加载会话历史、通过 ContextBuilder 组装上下文(历史 + 当前消息 + 系统提示词 + 记忆 + 技能索引)、将上下文交给 AgentRunner 执行、将结果封装为 OutboundMessage 发布到出站队列。它通过 asyncio.create_task 并发派发任务,同时保留任务跟踪能力以支持取消。一个值得注意的细节是:如果用户在一个任务仍在执行时发送新消息,这条消息会被注入到当前活跃的回合中,而非阻塞等待。
第四站:AgentRunner——面向模型的迭代循环
执行标准的 ReAct 循环:调用模型 → 检查工具调用 → 执行工具 → 回填结果 → 再次调用模型,直至模型产出不含工具调用的最终文本。
外部平台消息
↓
Channel 适配器 (协议转换)
↓
InboundMessage → MessageBus (入站队列)
↓
AgentLoop (会话识别 + 上下文构建)
↓
AgentRunner (LLM ↔ 工具 迭代循环)
↓
OutboundMessage → MessageBus (出站队列)
↓
ChannelManager (路由到对应通道)
↓
回复发送回原平台
链路的每一站都遵循单一职责原则,调试时因此有清晰路径——通道路由或会话问题从 agent/loop.py 入手,provider 调用或工具循环问题从 agent/runner.py 入手。
十、Gateway 服务:Channel 层的运行时管理
Channel 层并非独立运行,它的启动和管理依赖于一个核心的 Gateway 服务。运行 nanobot gateway 命令时,启动的是一个长期运行的后台服务,这就是 NanoBot 的"生产环境"。Gateway 通过 asyncio.gather 同时拉起多个核心组件:MessageBus(异步消息总线)、AgentLoop(Agent 大脑)、ChannelManager(管理所有渠道)、CronService(定时任务)、HeartbeatService(主动监控与通知)。
因此,Channel 层是 Gateway 服务管理的子组件,由 Gateway 统一启动和编排。Gateway 启动后,ChannelManager 遍历配置,实例化并启动所有启用的 Channel。每个 Channel 的 start() 方法被设计为一个阻塞的长期异步任务,但"监听"的具体实现因平台而异,主要有三种形态:

所以,"是否需要启动类似 Gateway 的监听服务"的准确答案是:必须有一个 Gateway 服务作为长期运行的总入口,统一启动和管理所有核心组件;而"监听服务"是它在管理具体渠道时可能采用的一种实现方式(Webhook 模式),并非唯一形态。
十一、飞书集成:WebSocket 长连接模式
NanoBot 的 Gateway 与飞书之间,通过 WebSocket 长连接建立通信。这是一种"反向连接"模式,由 NanoBot 主动向飞书服务器发起并维持一条持久化通道,飞书在有新消息时通过这条通道实时推送,因此不需要公网 IP,也无需配置 Webhook 或 SSL 证书,非常适合在个人电脑或内网环境运行。
连接建立流程
第一步,飞书开放平台侧准备:创建"自建应用"并启用机器人能力;添加 im:message(发送消息)和 im:message.p2p_msg:readonly(接收私聊消息)权限;在事件订阅中添加 im.message.receive_v1 事件,并务必选择"长连接模式";获取 App ID 与 App Secret;发布应用。
第二步,NanoBot 侧配置:可以执行 nanobot channels login feishu 通过二维码自动配置,也可以手动编辑 ~/.nanobot/config.json:
json
{
“channels”: {
“feishu”: {
“enabled”: true,
“appId”: “cli_xxx”,
“appSecret”: “xxx”,
“allowFrom”: [“ou_YOUR_OPEN_ID”],
“groupPolicy”: “mention”
}
}
}
其中 allowFrom 指定允许交互的用户 Open ID([“*”] 允许所有用户,生产环境不推荐);groupPolicy 控制群聊响应策略(“mention” 仅被 @ 时回复,“open” 回复所有群消息);encryptKey / verificationToken 在长连接模式下可选,通常留空。
第三步,启动 Gateway:nanobot gateway 启动后,飞书 Channel 主动向飞书服务器发起 WebSocket 长连接,日志中出现 Feishu channel connected via WebSocket 即表示连接建立。
关键澄清:长连接不暴露任何公网地址
这是与 Webhook 模式的根本区别。飞书官方文档明确说明:长连接模式下只需保证运行环境具备访问公网的能力,无需提供公网 IP 或域名,也无需内网穿透工具。因为连接由 NanoBot 主动拨出,事件数据通过这条已建立的通道"原路返回":
长连接模式(NanoBot 使用):
NanoBot (你的电脑/服务器) ──主动拨出──▶ 飞书服务器
(无需公网地址) ◀──推送事件──
Webhook 模式(需要暴露地址):
飞书服务器 ──主动POST──▶ NanoBot 的公网地址/端口
需要暴露公网地址的是传统 Webhook 模式,而 NanoBot 的飞书集成默认且推荐使用长连接模式,正是为了避开整套公网暴露和证书配置工作。
十二、可观测性:思考过程与工具执行如何呈现
NanoBot 内部完整地产生并传递了 LLM 的思考过程与工具执行事件,但并非所有渠道都能将它们渲染出来。WebSocket(WebUI)通道是唯一能完整、结构化呈现这两类信息的客户端。
思考过程(Reasoning / Chain-of-Thought)
AgentRunner 会捕获并发出模型的推理内容,这是一个内建的一等公民能力。它处理流式响应时,会解析并发出专门的推理事件(如 reasoning_delta 或通过 hook.emit_reasoning 触发),支持解析原生推理字段以及内联的 标签。
在呈现上:WebUI 能实时渲染一个可自动折叠的"Thinking…“气泡,展示模型的内部思考流(v0.2.1 版本引入了清晰的"Thought/response timelines”);IM 渠道(飞书、Telegram)通常不会显示——相关 PR 讨论明确指出,reasoning_content 作为流式跟进内容发送时只有 WebSocket 通道真正理解其专用路径,CLI 和其他大多数渠道会直接丢弃它。
工具执行过程
Agent 的钩子上下文(AgentHookContext)中包含了 tool_calls、tool_results 以及 tool_events(执行状态等元数据)。WebUI 会实时更新并展示工具执行的跟踪轨迹,让你看到正在调用什么工具、参数是什么、执行状态如何;部分 IM 渠道(如飞书) 在特定条件下(如流式卡片)可能以流式卡片形式展示工具调用轮次,但并非所有渠道的通用行为;CLI 通过"智能工具提示"和"推理缓冲区"提供视觉反馈,重复调用相同工具时会折叠为单行显示。

因此,若想完整观察 NanoBot 的"思考"与"行动"全貌,目前最佳且几乎是唯一的途径是使用其内置 WebUI。对于飞书等 IM 客户端,NanoBot 的设计重心在于将 Agent 作为"对话伙伴"给出最终结论,而非暴露其内部的推理和工具调用链条。
十三、总结:NanoBot 的可迁移架构模式
NanoBot 给个人学习者最有价值的启发,不在于某个具体函数怎么写,而在于它示范了几种可迁移的极简架构模式:
模式一:把 ReAct 循环写成一个函数。 20 行左右的 while 循环,tool_calls 有无决定继续还是跳出。理解成本几乎为零,定制时直接在这个函数里加逻辑即可。
模式二:用"职责拆分"代替"抽象分层"。 AgentLoop 管回合、AgentRunner 管模型循环——两个类的边界就是两类问题的边界,不需要额外的编排抽象层来"解耦"。
模式三:在存储上做减法,在确定性上做加法。 文件 + grep 替代向量库,用可预测性换取零基础设施成本。适用于数据量可控、确定性优先的个人场景;不适用于大规模、语义模糊检索需求。
模式四:接口约束最小化。 工具返回值强制 str,换来 Runner 循环中零分支判断。约束越少,核心逻辑越简单。
模式五:用工具裁剪治理复杂度。 子代理强制移除 SpawnTool 和 MessageTool,从架构层面杜绝递归派遣和通信混乱,让每个子代理获得恰好够用的工具集。
模式六:出站连接替代公网暴露。 飞书集成采用 WebSocket 长连接主动拨出,无需公网 IP、无需证书、无需内网穿透,把部署复杂度降到最低。
对于正在学习 Agent 开发的个人而言,NanoBot 是一个难得的样本:约 4000 行体量,一个下午可以通读;核心循环短到可以在脑中执行;同时保留了工具插件、MCP、多通道、子 Agent、上下文治理等一个真实 Agent 系统该有的骨架。读完它,你对"一个 Agent 在代码层面到底长什么样"会有一个不会被框架抽象遮蔽的清晰认知——这正是它在"手写最小循环"与"使用重量级框架"之间,最有价值的位置。
更多推荐

所有评论(0)