Nanobot源码解析(一):整体架构

概述

NanoBot 是一个模块化的 AI 代理框架，支持多种 LLM 后端、多渠道接入和丰富的工具生态。本文档整合了其架构设计和核心概念，帮助你理解系统的工作原理。

NanoBot 与 harness

核心架构

整体数据流

单次请求处理流程 (One Agent Turn)

这是系统中最核心、最频繁的执行路径。无论用户通过何种渠道（CLI、WebUI、Telegram等）发起交互，每一次完整的“用户提问 → Agent 回复”都严格遵循以下标准化流程：

流程步骤拆解

关键流程统一性说明

核心编排逻辑***\*AgentLoop\****和***\*AgentRunner\****对消息来源完全无感。无论是 CLI 输入的文本、WebUI 传来的 JSON 负载，还是 Telegram 的 CallbackQuery，最终都会被渠道适配器转换为统一的 InboundMessage 事件。这种设计保证了：

1. 1. *逻辑复用*：所有业务规则（如工具调用权限、记忆检索策略）只需在核心链路中实现一次。
2. 2. *可测试性*：可以绕过所有渠道，直接向 MessageBus 注入测试消息来验证 Agent 行为。
3. 3. *扩展性*：新增渠道只需要实现一套“外部协议 ↔ 内部事件”的双向转换适配器，无需改动核心代码。

这个流程是理解 NanoBot 运行时行为的关键路径，也是定位问题时（如工具执行超时、上下文截断等）的首选追踪路线。

核心模块与文件

代理循环 vs 代理执行器

代理循环 (AgentLoop) 负责面向渠道的回合：

• • 接收入站消息
• • 确定有效会话和工作区范围
• • 构建上下文
• • 连接钩子、进度和渠道元数据
• • 发布出站消息

代理执行器 (AgentRunner) 负责面向模型的循环：

• • 发送消息到选定的提供者
• • 处理流式增量和推理块
• • 执行工具调用
• • 将工具结果反馈给模型
• • 在产生最终答案或达到运行时限制时停止

调试指引：

• • 渠道路由、会话键、工作区选择、出站交付问题 → 检查 agent/loop.py
• • 提供者调用、工具调用、流式、迭代限制问题 → 检查 agent/runner.py

核心概念

运行时组成

配置与工作区

默认实例位于 ~/.nanobot/：

可通过命令行标志覆盖：

bash

nanobot onboard --config ./bot-a/config.json --workspace ./bot-a/workspacenanobot agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace

代理工作区 vs 项目工作区

• • 代理工作区：配置的工作区，包含代理身份、持久状态
• • 项目工作区：WebUI 聊天可选择不同的项目工作区进行仓库特定工作

提供者与模型选择

活动模型应来自 modelPresets 条目，由 agents.defaults.modelPreset 选择。解析顺序：

1. 1. 如果活动预设提供者或隐式默认提供者不是 "auto"，使用该提供者
2. 2. 如果提供者是 "auto"，尝试从模型名称、配置的 API 密钥、本地提供者基础 URL 或网关提供者推断
3. 3. OAuth 提供者（OpenAI Codex、GitHub Copilot）需要显式登录和在活动预设内显式选择

配置示例：

json

{  "modelPresets": {    "primary": {      "provider": "openrouter",      "model": "anthropic/claude-opus-4.5"    }  },  "agents": {    "defaults": {      "modelPreset": "primary"    }  }}

渠道与会话

每个渠道将入站消息映射到会话键，使独立对话保持单独历史。WebUI 还支持多聊天和工作区范围元数据。

• • agents.defaults.unifiedSession 可故意跨渠道共享一个会话（单用户多设备场景）
• • 对于多个独立用户、群组、渠道或项目，保持关闭以保持独立上下文

记忆、会话与 Dream

Dream 是定期合并任务：读取累积历史并更新工作区记忆，使有用上下文能在短期会话重放之外持久保存。

工具与安全

工具自动从内置模块和插件入口点发现：

• • 文件读写/编辑/打补丁
• • Shell 执行（可配置沙箱）
• • Web 搜索和获取（带 SSRF 检查）
• • MCP 服务器
• • 定时任务提醒、本地触发器、心跳任务
• • 图像生成
• • 子代理和运行时自检

安全敏感代码路径：

后台任务

nanobot gateway 启动时运行工作区范围的自动化：

• • dream：当 agents.defaults.dream.enabled 为 true
• • heartbeat：当 gateway.heartbeat.enabled 为 true

Heartbeat 读取 <workspace>/HEARTBEAT.md，如果文件在 ## Active Tasks 下有任务，执行它们并将结果发送到最近活跃的聊天目标。

用户创建的提醒使用相同的 cron 服务，但作为计划任务在其来源聊天/会话中运行，通常将结果传递回该渠道。

本地触发器：与会话绑定，无自己的计划。从目标聊天用 /trigger <name> 创建，然后调用 nanobot trigger <id> "<message>" 让 NanoBot 在该会话中响应。

入口点

默认端口：

• • 健康检查端点：http://127.0.0.1:18790/health
• • WebUI/WebSocket：http://127.0.0.1:8765

扩展点