nanobot

一句话定位

一个超轻量、可自托管的 Python single-agent 运行时：围绕一个小而可读的 agent loop（消息进入→LLM 决定是否调工具→拉取记忆/技能作为上下文→回写渠道），把长时运行 agent 真正需要的”实战零件”——WebUI、9+ 聊天渠道、工具、记忆、MCP、模型路由与部署——都内置进来，让你”拥有自己的 AI agent 技术栈”而不依赖大平台。

设计理念 / 顶层架构

nanobot 的核心范式是 single-agent 的工具循环（tool-using loop），刻意保持”薄内核 + 异步消息总线解耦”的取舍：

• 消息总线解耦：渠道与 agent 核心通过异步 MessageBus（nanobot/bus/queue.py）通信。渠道发布 InboundMessage，AgentLoop 消费、构建上下文、协调一个 turn，结果作为 OutboundMessage 发回对应渠道。这让”加一个聊天平台”与”改 agent 逻辑”互不耦合。
• AgentLoop / AgentRunner 双层：AgentLoop（nanobot/agent/loop.py）是产品层引擎，负责 session key、hook、上下文构建、压缩、命令路由、mid-turn 注入；它把一个 turn 建模成一张显式状态机（TurnState: RESTORE→COMPACT→COMMAND→BUILD→RUN→SAVE→RESPOND→DONE，loop.py:76,167）。AgentRunner（nanobot/agent/runner.py）是纯粹的”工具型 LLM 循环”，不含产品层关切，可被主 loop、subagent、Dream 复用。
• 插件式自动发现：工具（Tool 子类）和渠道都用 pkgutil 扫描包 + entry_points 第三方插件自动注册（agent/tools/loader.py:37,68）。新增内置工具=丢一个文件进 agent/tools/；新增 provider≈2 步。
• 电池内置但内核小：记忆（含 Dream 两阶段巩固）、MCP 客户端、cron、sandbox、subagent、长任务/持续目标、图像生成、self-modify 全部内置，但都以”工具/上下文”形态挂在小内核外围，而非重型编排层。
• 入口形态：CLI nanobot/cli/commands.py（nanobot onboard / agent / gateway）；Python SDK 门面 Nanobot（nanobot/nanobot.py:23，Nanobot.from_config().run(...)）；OpenAI 兼容 HTTP API（nanobot/api/server.py）。配置走 Pydantic + ~/.nanobot/config.json。

最小示例（取自 README，零代码——配置驱动）：

# 1) 初始化向导
nanobot onboard

# 2) 在 ~/.nanobot/config.json 配 key 与模型
#   { "providers": { "openrouter": { "apiKey": "sk-or-v1-xxx" } },
#     "agents": { "defaults": { "provider": "openrouter",
#                               "model": "anthropic/claude-opus-4-6" } } }

# 3) 开聊（CLI）；或开 WebUI/网关
nanobot agent
# 启用 websocket 渠道后： nanobot gateway  →  http://127.0.0.1:8765

# Python SDK 形态（nanobot/nanobot.py）
import asyncio
from nanobot import Nanobot

async def main():
    bot = Nanobot.from_config()                 # 读 ~/.nanobot/config.json
    result = await bot.run("Summarize this repo")
    print(result.content)

asyncio.run(main())

组件实现（横向逐项，无则标 N/A）

设计权衡与特性

• “小核心 + 实战电池” vs 极简内核：与去框架化的 Swarm 不同，nanobot 把 9+ 聊天渠道、记忆巩固、MCP、cron、subagent、sandbox、WebUI 全部内置——目标是”个人就能拥有并自托管一个 24/7 长跑 agent”。代价是依赖很重（telegram/lark/slack/qq/discord SDK、mcp、tiktoken、boto3、pypdf/docx/pptx/openpyxl 文档解析、dulwich 等几十个）。
• turn 显式状态机 + mid-turn 注入：把一个对话回合建成 TurnState 状态机并记录每态耗时 trace，是较少见的工程化做法；配合 per-session 串行 / 跨 session 并发 + pending queue，可在 agent 仍在跑工具时把用户后续消息”注入”当前 turn（runner._try_drain_injections），而非排队新 turn——对长任务体验关键。
• Dream 两阶段记忆：历史用 append-only history.jsonl（cursor 增量、原子写 + fsync + 目录 fsync），Consolidator 按 token 预算把溢出消息 LLM 摘要、降级时 raw-archive 兜底；MemoryStore 还做了 legacy HISTORY.md→JSONL 一次性迁移。可靠性细节（去孤儿 tool 结果、backfill、microcompact、token snip）非常密集。
• provider 抽象成熟：原生 openai+anthropic SDK（2026-03 移除 litellm），统一 OpenAI message 格式 + ToolCallRequest，覆盖 OpenAI-compat / Anthropic / Azure / Bedrock / GitHub Copilot / OpenAI Codex / Responses API，并有 FallbackProvider 多模型 failover 与 model presets 热切换（_apply_provider_snapshot 不打断进行中的 turn）。
• single-agent 边界清晰：多智能体仅限进程内 subagent（隔离工具/工作区，结果经 bus 回灌父会话），没有跨网络 agent-to-agent 协议或信任系统——与 ConnectOnion 的 host/relay/trust 路线形成对照。
• 安全是硬边界：SSRF（私网 URL）为”不可绕过”边界、shell sandbox + allow-list、workspace 路径限制、DM pairing 审批、默认拒绝未知渠道；CLI 入口启用 PTH 文件守卫（nanobot/security/）。
• 待确认/坑：①向量检索缺失，长期记忆是文件 + LLM 摘要而非语义检索；②依赖面极大，按需用 optional-extras（discord/matrix/wecom/weixin/msteams/pdf 等）裁剪；③仍标 Development Status :: 3 - Alpha、版本 0.2.1，News 显示迭代极快（near-daily），API 可能漂移；④Windows 下 MCP stdio 启动器需特殊包装（mcp.py:101），且部分目录 fsync 在 Windows 跳过。

关联

• component-taxonomy · single-vs-multi-agent · multi-agent-orchestration
• 同范式(single+电池/自托管平台)：connectonion · swarm · 源码：agents-example/nanobot/