nanobot 核心概念详解:从 Agent Loop 到 Dream 记忆系统的运行机制
nanobot 核心概念详解:从 Agent Loop 到 Dream 记忆系统的运行机制
本文基于 nanobot 官方的 Concepts 文档,系统讲解这个超轻量自托管 AI Agent 框架的运行形态、配置与工作区划分、单次 Agent 回合的完整流程,以及 Provider 选择、会话隔离、记忆/Dream 整合、插件与后台任务的底层机制。读完后,你无需先通读源码,就能准确理解 nanobot 各组件的边界与协作方式,为后续修改高级配置、部署多实例或接入聊天应用打下坚实的概念基础。
运行时形态:一个核心循环,多种入口
nanobot 的运行时由"一个小而完整的核心循环 + 多种进入它的方式"构成。官方将各组成部分的职责归纳如下:
| 组件 | 职责 |
|---|---|
| Agent loop(Agent 循环) | 构建上下文、选择会话、调用 Provider、执行工具、发布回复 |
| Providers | LLM 后端,如 OpenRouter、Anthropic、OpenAI、Bedrock、Ollama、vLLM 及其他 OpenAI 兼容 API |
| Channels | 面向用户的传输通道,如 CLI、WebUI/WebSocket、Telegram、Discord、Slack、飞书、微信、Email、Mattermost 等 |
| Tools | 模型可调用的能力,包括文件操作、shell、网络搜索/抓取、MCP、cron、图像生成、子 Agent |
| Memory | 工作区文件与会话历史,用于在多轮之间保留有用上下文 |
| Gateway | 常驻进程,连接已启用的各 Channel 并对外提供健康检查端点 |
从源码结构看,这套分工与仓库目录一一对应:核心循环位于 agent/loop.py,其中 run()、_dispatch()、_process_message() 等方法串起了消息分发与会话处理;工具集集中在 agent/tools 目录,能看到 filesystem.py(文件读写编辑)、shell.py(shell 执行)、web.py(网络搜索/抓取)、mcp.py(MCP 服务器)、cron.py(定时任务)、image_generation.py(图像生成)、spawn.py(子 Agent)等模块,与上表 Tools 行完全吻合;各聊天通道则位于 channels 目录下。
两条最简单的使用路径:
# 一次性路径:一条入站消息经过 agent 循环,直接在终端打印回复
nanobot agent -m "Hello!"
# 常驻路径:channels 从聊天应用或 WebUI 接收消息,
# 发布到同一个 agent 循环,并把回复送回来源 channel
nanobot gateway
Config 与 Workspace 的分离
默认实例的所有状态都位于 ~/.nanobot/ 下,三者职责分明:
| 路径 | 含义 |
|---|---|
~/.nanobot/config.json |
实例配置:providers、模型默认值、channels、tools、gateway、API 与运行时选项 |
~/.nanobot/workspace/ |
Agent 工作区:memory、heartbeat 任务、cron 任务、skills 与生成的产物 |
~/.nanobot/sessions/<workspace-id>/ |
会话历史,存放在 Agent 可访问工作区之外;不透明 ID 会跟随工作区移动 |
这一设计在 config/paths.py 中得到印证:get_workspace_path() 在传入 None 时回退到 Path.home() / ".nanobot" / "workspace",get_data_dir() 返回实例级运行时数据目录,媒体、cron、日志等运行时子目录都从配置目录派生。
两个参数可用命令行标志覆盖,这也是多实例部署的基础:
nanobot onboard --config ./bot-a/config.json --workspace ./bot-a/workspace
nanobot agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"
nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace
一句话概括:配置文件决定 nanobot 可以用什么,工作区存放该实例的状态。
Agent 工作区与项目工作区
配置中声明的 workspace 是 agent workspace(Agent 工作区)。WebUI 聊天还可以额外选择一个 project workspace(项目工作区),用于针对某个仓库的工作,而无需搬动 Agent 的身份或持久状态。选中项目后,各类资源的所有权划分如下:
| 资源 | 归属(选中项目时) |
|---|---|
| 项目指令 | 来自所选项目的 AGENTS.md,不会回退到 agent 工作区的 AGENTS.md |
| Agent 档案 | 来自 agent 工作区的 SOUL.md 与 USER.md;项目中同名文件会被忽略 |
| Memory 与自定义 skills | 来自 agent 工作区的 memory/ 与 skills/ |
| 相对文件路径与 shell 工作目录 | 所选项目工作区 |
未单独选择项目时,通常一个目录同时承担两个角色。选择项目只改变该聊天的工作上下文,不会创建第二个 Agent,也不会迁移已配置的 agent 工作区。
配置格式:camelCase 与 snake_case 双兼容
config.json 同时接受 camelCase 和 snake_case 键。官方文档示例统一使用 camelCase,因为 nanobot 回写配置时使用的是 camelCase 别名,例如 apiKey、modelPresets、intervalS、maxToolResultChars。
一个重要的实操提醒:文档中的配置示例大多为局部片段,应合并进 nanobot onboard 生成的现有配置文件,除非想重置整个实例,否则不要整体替换文件。
一次完整的 Agent 回合
普通回合的标准流程如下:
- Channel 收到用户消息,发布到消息总线(message bus);
- Agent 循环选定 session key,并基于有效项目工作区、agent 专属的 profile/skills/memory、近期消息、channel 元数据与运行时设置构建上下文;
- Provider 接收模型请求;
- 若模型请求调用工具,runner 执行工具并把结果回喂给模型;
- 最终回复保存进 session,并经由 channel 发送回去。
无论消息来自 CLI、WebUI、Telegram、Discord 还是其他 channel,走的都是这条流程。从源码结构看,agent/loop.py 中的 _build_turn()、_run_turn()、_persist_turn()、_prepare_outbound() 等方法链,正好对应"构建上下文 → 执行模型/工具 → 持久化 → 出站投递"的阶段划分;消息总线则位于 bus/queue.py,负责在 channel 与 agent 循环之间解耦。
CLI、Gateway、API 与 WebUI 四种入口
| 入口 | 命令 | 适用场景 |
|---|---|---|
| CLI 一次性 | nanobot agent -m "..." |
首次运行检查、脚本、快速本地提问 |
| CLI 交互式 | nanobot agent |
带持久会话历史的终端聊天 |
| Gateway | nanobot gateway |
聊天应用、WebUI、heartbeat、Dream 与长驻服务模式 |
| OpenAI 兼容 API | nanobot serve |
通过 /v1/chat/completions 做程序化访问 |
| WebUI | nanobot webui |
准备本地 WebUI、启动 gateway 并打开浏览器工作台 |
WebUI 启动器是浏览器入口的常规方式;底层仍由 gateway 维持 WebSocket channel 和其他长驻服务。两个端口的分工需要注意:
- gateway 健康检查端点在
gateway.port上,默认 18790(见 config/schema.py 中port: int = 18790); - 浏览器 WebUI 默认由 8765 端口提供,而不是健康检查端点(见 cli/webui_support.py 中的端口回退逻辑)。
Provider 与模型选择
活动模型通常应来自由 agents.defaults.modelPreset 选中的某个命名 modelPresets 条目;而 agents.defaults.provider 与 agents.defaults.model 的直接组合,仍然为旧版或极简配置形成隐式的 default preset。agent/model_presets.py 中可以看到这一机制的实现:configured_model_presets() 在用户配置的 preset 之上自动并入一个 "default" 条目。
活动 provider 的解析顺序:
- 若活动 preset 的 provider(或隐式默认 provider)不是
"auto",nanobot 直接使用它; - 若 provider 为
"auto",nanobot 依次尝试从模型名、已配置的 API key、本地 provider 的 base URL 或 gateway providers 推断; - 如 OpenAI Codex、GitHub Copilot 等 OAuth provider,要求显式登录,并在活动 preset 中显式选择 provider/model。
官方建议:首次配置时在 preset 内固定 provider,调试更容易:
{
"modelPresets": {
"primary": {
"provider": "openrouter",
"model": "anthropic/claude-opus-4.5"
}
},
"agents": {
"defaults": {
"modelPreset": "primary"
}
}
}
更完整的 provider 示例见 providers.md,完整参考见 configuration.md。
Channel 与 Session 的映射
每个 channel 会把入站消息映射到一个 session key,从而让相互独立的对话各自保有独立历史;WebUI 还支持多聊天以及项目工作区级别的元数据。
agents.defaults.unifiedSession 可以在单用户多设备场景下刻意共享同一 session;如果你预期不同的人、群、channel 或项目应保持独立上下文,应保持该选项关闭。
Memory、Sessions 与 Dream
nanobot 使用两个相互关联的存储:
| 存储 | 位置 | 用途 |
|---|---|---|
| Sessions | <config-dir>/sessions/<workspace-id>/*.jsonl |
重放进上下文的近期对话回合 |
| Memory | <workspace>/memory/MEMORY.md 与 <workspace>/memory/history.jsonl |
长期事实与整合后的历史 |
Dream 是一个周期性的整合任务:它读取积累的历史并更新工作区 memory,让有用的上下文能超越短期会话回放而存活下来。详细设计见 memory.md。
workspace-id:会话命名空间的锚点
配置的工作区内含一个 .nanobot/workspace-id 文件,只包含一个不透明随机标识符——绝不含对话内容或凭据。从 session/manager.py 的实现看,该标识符格式为 32 位十六进制字符串(正则 ^[0-9a-f]{32}$),并且被严格禁止为符号链接(读取时若发现 symlink 会直接抛出 RuntimeError),这是防止身份标记被篡改的安全设计。它的实际作用:
- 工作区被重命名、移动或恢复后,nanobot 仍能凭同一标识符找到对应的外部 session 命名空间,因此备份工作区时必须一并保留它;
- 若在同一位置打开一份工作区副本,副本会获得新 ID,避免两个工作区意外共享对话;
- 若清理操作意外删除了该标记,
_find_workspace_namespace()会尝试从既有 sessions 目录名中恢复同一工作区路径下的身份标记。
Apps 与 Agent Plugins
Agent Plugins 是 nanobot 对可安装能力的统一打包与激活边界——它组织已有的扩展类型,而不是替代它们:
| 部分 | 角色 |
|---|---|
| Agent Plugin | 可安装包,可打包 skills、MCP server 或两者兼有 |
| Skill | 渐进式加载或经 $skill-name 调用的工作流指引 |
| MCP server | 暴露给 agent 的运行时工具 |
| CLI App | 本地管理的可执行文件,其 adapter 像插件一样打包与激活 |
| Apps | WebUI 中审阅和管理这些能力的界面 |
需要强调:原生 provider、channel、内置工具、独立的 workspace skills、直接配置的 MCP server,均保持各自的既有扩展路径不受影响。用户侧流程见 webui.md,包契约见 configuration.md。
工具与安全性
工具从内置模块和插件入口自动发现,常见工具组包括:
- 文件读/写/编辑与补丁(对应 agent/tools/filesystem.py、agent/tools/apply_patch.py);
- 带可配置沙箱的 shell 执行(agent/tools/shell.py、agent/tools/sandbox.py);
- 带 SSRF 检查的网络搜索与抓取(agent/tools/web.py);
- MCP 服务器(agent/tools/mcp.py);
- cron 提醒、本地触发器与 heartbeat 任务(agent/tools/cron.py);
- 图像生成(agent/tools/image_generation.py);
- 子 Agent 与运行时自省(agent/tools/spawn.py、agent/tools/self.py)。
涉及安全的控制项集中在 configuration.md。生产环境或共享聊天应用还应配置 channel 访问控制,如 allowFrom、pairing 或 WebSocket token。
后台任务:Dream、Heartbeat、Cron 与本地 Trigger
nanobot gateway 启动时会运行工作区范围的自动化任务并注册系统作业:
dream,当agents.defaults.dream.enabled为 true 时;heartbeat,当gateway.heartbeat.enabled为 true 时。
Heartbeat 读取 <workspace>/HEARTBEAT.md。从 cli/gateway_runtime.py 的实现看,它会检查该文件 ## Active Tasks 下的任务行(忽略标题、空行与注释):有任务则执行,且只把有用/可操作的结果发送到最近活跃的聊天目标,"没有变化"的例行结果会被抑制。
用户创建的提醒走的是同一个 cron 服务,但与受保护的 heartbeat 系统作业不同:提醒作为计划回合(scheduled turn)在其来源聊天/会话中运行,并把结果正常投递回该 channel。
本地触发器(local triggers)同样绑定会话,但没有自己的时间表:
- 从目标聊天用
/trigger <name>创建一个触发器; - 当本地脚本或外部服务希望 nanobot 在该会话中响应时,调用
nanobot trigger <id> "<message>"; - Webhook 服务器、第三方认证、事件到消息的格式化,都留在 nanobot 之外。
投递语义(从 triggers/local_runner.py 所在模块可印证其按会话投递的设计):
- 触发投递在关联 agent 回合成功结束前一直存留在工作区;
- 若目标会话正忙,触发器会等待其空闲,而不是注入正在进行的回合;
- 消息作为 automation turn 记录进该会话;
- 投递为 at-least-once:外部系统应容忍重复的触发消息;到达 agent 但执行失败的投递会被标记为 failed,而非无限重试。
延伸阅读
| 需求 | 参考文档 |
|---|---|
| 首个可运行安装 | quick-start.md |
| Provider/模型配置 | providers.md |
| 聊天应用接入 | chat-apps.md |
| 完整配置参考 | configuration.md |
| 运行时排障 | troubleshooting.md |
| 源码级职责划分与扩展点 | architecture.md |
