学习笔记nanobot 源码分析

1. 项目简介

nanobot 是一个开源的超轻量级个人 AI Agent 框架，使用 Python 3.11+ 编写，配套 React/TypeScript WebUI。它的设计哲学是保持 Agent 核心小巧可读，同时提供实际长期运行所需的完整功能：WebUI、多渠道接入、工具系统、记忆管理、MCP 协议支持、模型路由、自动化任务和多种部署方式。

1.1 核心特性

  • 轻量级 Agent 循环：核心处理引擎（AgentLoop）代码简洁，通过状态机驱动消息处理流程
  • 多渠道支持：Telegram、Discord、Slack、微信、飞书、钉钉、WhatsApp、QQ、Matrix 等 15+ 聊天平台
  • 多 LLM 提供商：Anthropic、OpenAI、Azure、AWS Bedrock、GitHub Copilot、OpenAI Codex 及任意 OpenAI 兼容 API
  • 丰富的工具系统：文件读写、Shell 执行、Web 搜索、MCP 服务器、子 Agent 生成、Cron 定时任务
  • 记忆与巩固：Dream 两阶段记忆巩固，自动摘要历史对话
  • 会话管理：JSONL 持久化、自动压缩、上下文窗口管理
  • 模型预设：运行时热切换模型，支持 fallback 回退链

1.2 技术栈

层面 技术
语言 Python 3.11+
异步 asyncio 全异步架构
配置 Pydantic v2
WebUI React + TypeScript + Vite
日志 Loguru
包管理 Hatchling
代码规范 Ruff (E, F, I, N, W)

2. 核心概念速览

2.1 消息总线（MessageBus）

MessageBus 是整个系统的通信中枢。它通过两个 asyncio.Queue 解耦了聊天渠道和 Agent 核心：

  • Inbound Queue：渠道将用户消息发布到入站队列
  • Outbound Queue：Agent 将回复发布到出站队列
graph LR
    A[Telegram] -->|InboundMessage| B[MessageBus
Inbound Queue]
    C[Discord] -->|InboundMessage| B
    D[WebUI] -->|InboundMessage| B
    B -->|consume| E[AgentLoop]
    E -->|OutboundMessage| F[MessageBus
Outbound Queue]
    F -->|dispatch| A
    F -->|dispatch| C
    F -->|dispatch| D

2.2 Agent 循环（AgentLoop）

AgentLoop 是核心处理引擎，通过 状态机 驱动每个消息的处理流程：

stateDiagram-v2
    [*] --> RESTORE
    RESTORE --> COMPACT: ok
    COMPACT --> COMMAND: ok
    COMMAND --> BUILD: dispatch
    COMMAND --> DONE: shortcut
    BUILD --> RUN: ok
    RUN --> SAVE: ok
    SAVE --> RESPOND: ok
    RESPOND --> DONE: ok

8 个状态覆盖了从消息恢复到最终响应的完整生命周期。

2.3 LLM 提供商（Provider）

Provider 系统 基于抽象基类 LLMProvider，统一了不同 AI 服务商的调用接口：

  • 支持流式和非流式两种调用模式
  • 内置重试机制（标准模式 3 次重试 / 持久模式无限重试）
  • 自动区分瞬时错误（可重试）和配额/计费错误（不可重试）
  • 支持 Retry-After 头部解析

2.4 工具系统（Tools）

工具系统 是 Agent 能力的核心。每个工具继承 Tool 基类，通过 ToolRegistry 统一管理。工具通过 pkgutil 扫描自动发现，也支持 entry-point 插件扩展。

2.5 记忆与巩固（Memory & Consolidation）

记忆系统 包含两层：

  • MemoryStore：纯文件 I/O 层，管理 MEMORY.md、history.jsonl、SOUL.md、USER.md
  • Consolidator：基于 Token 预算的对话历史自动摘要，将旧消息压缩后写入 history.jsonl

3. 典型场景剖析

场景一：用户通过 Telegram 发送消息

sequenceDiagram
    participant U as 用户
    participant TG as Telegram Channel
    participant B as MessageBus
    participant AL as AgentLoop
    participant AR as AgentRunner
    participant P as LLM Provider
    participant T as Tools

    U->>TG: "帮我写一个Python脚本"
    TG->>B: publish_inbound(InboundMessage)
    B->>AL: consume_inbound()
    AL->>AL: _dispatch(msg)
    Note over AL: 状态机: RESTORE→COMPACT→COMMAND→BUILD→RUN
    AL->>AR: run(spec)
    AR->>P: chat_stream(messages, tools)
    P-->>AR: tool_calls: [write_file]
    AR->>T: execute("write_file", params)
    T-->>AR: "文件已写入"
    AR->>P: chat_stream(含工具结果)
    P-->>AR: "已为你创建脚本..."
    AR-->>AL: AgentRunResult
    Note over AL: SAVE→RESPOND→DONE
    AL->>B: publish_outbound(OutboundMessage)
    B->>TG: dispatch
    TG->>U: "已为你创建脚本..."

场景二：Dream 记忆巩固

sequenceDiagram
    participant Cron as CronService
    participant AL as AgentLoop
    participant MS as MemoryStore
    participant C as Consolidator
    participant P as LLM Provider

    Cron->>AL: submit_cron_turn(dream job)
    AL->>MS: build_dream_prompt()
    MS-->>AL: 未处理的历史条目
    AL->>AL: process_direct(ephemeral=True)
    Note over AL: 使用受限工具集 (read/edit/write)
    AL->>P: chat(memory prompt)
    P-->>AL: 更新 MEMORY.md / SOUL.md
    AL->>MS: set_last_dream_cursor()
    MS->>MS: git commit (auto)

4. 架构全景图

graph TB
    subgraph "入口层"
        CLI[CLI / Python SDK]
        API[OpenAI API Server]
    end

    subgraph "渠道层"
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WX[WeChat]
        FS[Feishu]
        WA[WhatsApp]
        WS[WebSocket/WebUI]
    end

    subgraph "核心层"
        MB[MessageBus]
        AL[AgentLoop]
        AR[AgentRunner]
        CB[ContextBuilder]
        CR[CommandRouter]
    end

    subgraph "能力层"
        TR[ToolRegistry]
        FS2[FileSystem Tools]
        SH[Shell Tools]
        WEB[Web Tools]
        MCP[MCP Tools]
        SP[Spawn/Subagent]
    end

    subgraph "基础设施层"
        PR[LLM Providers]
        SM[SessionManager]
        MS[MemoryStore]
        CS[Consolidator]
        CF[Config/Schema]
    end

    CLI --> AL
    API --> AL
    TG --> MB
    DC --> MB
    SL --> MB
    WX --> MB
    FS --> MB
    WA --> MB
    WS --> MB
    MB --> AL
    AL --> AR
    AL --> CB
    AL --> CR
    AL --> SM
    AL --> MS
    AL --> CS
    AR --> PR
    AR --> TR
    TR --> FS2
    TR --> SH
    TR --> WEB
    TR --> MCP
    TR --> SP

5. 学习路线图

建议按以下顺序阅读各模块章节：

顺序 章节 内容 预计时间
1 00-overview（本文） 建立全局认知 30min
2 01-module-agent-loop AgentLoop + AgentRunner 核心引擎 2h
3 02-module-message-bus MessageBus 异步通信中枢 30min
4 03-module-providers LLM Provider 抽象与重试机制 1.5h
5 04-module-channels 聊天渠道集成架构 1h
6 05-module-tools 工具系统与注册机制 1.5h
7 06-module-memory 记忆存储与 Dream 巩固 1.5h
8 07-module-session 会话管理与历史回放 1h
9 08-module-context 上下文构建与技能加载 1h
10 09-module-config-security 配置系统与安全边界 45min
11 appendix-references 参考资料索引 15min

学习建议：

  • 第 1-3 章是理解核心数据流的基础，务必先读
  • 第 4-5 章可以并行阅读（Provider 和 Tool 相对独立）
  • 第 6-8 章涉及持久化和上下文管理，建议按顺序阅读
  • 第 9 章是配置和安全的收尾

📝 本章小结

  1. nanobot 是一个异步 Python AI Agent 框架，核心理念是”小核心 + 丰富能力”
  2. MessageBus 通过两个 asyncio.Queue 实现渠道与 Agent 的解耦
  3. AgentLoop 使用 8 状态状态机驱动消息处理的完整生命周期
  4. Provider 系统通过抽象基类统一多 LLM 提供商接口，内置智能重试
  5. 记忆系统采用 Dream 两阶段巩固，自动管理上下文窗口