nanobot 核心概念详解:从 Agent Loop 到 Dream 记忆系统的运行机制

原创2026-09-17 11:01:402,238 阅读
文章标签:人工智能AI 应用AI AgentAgent 框架工具调用MCP ClientsAgent 记忆多智能体交互助手任务调度本地部署CLI前端插件系统即时通讯

nanobot 核心概念详解:从 Agent Loop 到 Dream 记忆系统的运行机制

本文基于 nanobot 官方的 Concepts 文档,系统讲解这个超轻量自托管 AI Agent 框架的运行形态、配置与工作区划分、单次 Agent 回合的完整流程,以及 Provider 选择、会话隔离、记忆/Dream 整合、插件与后台任务的底层机制。读完后,你无需先通读源码,就能准确理解 nanobot 各组件的边界与协作方式,为后续修改高级配置、部署多实例或接入聊天应用打下坚实的概念基础。

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 回合

普通回合的标准流程如下:

  1. Channel 收到用户消息,发布到消息总线(message bus);
  2. Agent 循环选定 session key,并基于有效项目工作区、agent 专属的 profile/skills/memory、近期消息、channel 元数据与运行时设置构建上下文;
  3. Provider 接收模型请求;
  4. 若模型请求调用工具,runner 执行工具并把结果回喂给模型;
  5. 最终回复保存进 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 的解析顺序:

  1. 若活动 preset 的 provider(或隐式默认 provider)不是 "auto",nanobot 直接使用它;
  2. 若 provider 为 "auto",nanobot 依次尝试从模型名、已配置的 API key、本地 provider 的 base URL 或 gateway providers 推断;
  3. 如 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。

工具与安全性

工具从内置模块和插件入口自动发现,常见工具组包括:

涉及安全的控制项集中在 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)同样绑定会话,但没有自己的时间表:

  1. 从目标聊天用 /trigger <name> 创建一个触发器;
  2. 当本地脚本或外部服务希望 nanobot 在该会话中响应时,调用 nanobot trigger <id> "<message>";
  3. 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
登录后查看全文
nanobot