---

关于作者

• 深耕领域：大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调
• 技术栈：Python | RAG (LangChain / Dify + Milvus) | FastAPI + Docker
• 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让 AI 交互更智能，让技术落地更高效」
欢迎技术探讨与项目合作，解锁大模型与智能交互的无限可能！

---

nanobot：极简 AI Agent 框架的设计哲学

用 ~4,000 行代码实现核心 Agent 功能，比 Clawdbot 小 99%，却拥有完整的多渠道通信、工具调用、记忆系统。

概述

nanobot 是一个超轻量级的个人 AI 助手框架，其核心设计理念是"极简但完整"。通过精心的架构设计，它仅用约 4,000 行 Python 代码就实现了完整的 Agent 功能，包括 LLM 交互、工具调用、多渠道通信、记忆系统和定时任务。本文将深入剖析 nanobot 的设计哲学与核心架构。

问题背景

AI Agent 框架的复杂性困境

当前主流的 AI Agent 框架往往存在以下问题：

问题	表现	影响
代码膨胀	Clawdbot 超过 430k 行代码	难以理解、难以定制
过度抽象	多层继承、复杂依赖	学习曲线陡峭
功能冗余	大量不常用功能	资源占用高、启动慢
黑盒设计	核心逻辑深埋	调试困难、信任成本高

nanobot 的设计目标

nanobot 的诞生正是为了解决这些问题：

核心设计理念

1. Less is More

nanobot 的核心代码量仅为 3,578 行（可通过 bash core_agent_lines.sh 验证），这背后是"少即是多"的设计哲学：

• 只做一件事: 专注于 Agent 核心功能
• 拒绝过度工程: 每一行代码都有存在的理由
• 依赖最小化: 只依赖必要的第三方库

2. 可读性优先

代码是写给人看的，其次才是给机器执行的：

class AgentLoop:
    """
    The agent loop is the core processing engine.
    
    It:
    1. Receives messages from the bus
    2. Builds context with history, memory, skills
    3. Calls the LLM
    4. Executes tool calls
    5. Sends responses back
    """

每个核心类都有清晰的文档字符串，说明其职责和工作流程。

3. 组合优于继承

nanobot 大量使用组合模式而非继承：

架构总览

整体架构图

核心模块职责

模块	职责	关键文件
agent	Agent 核心逻辑	[loop.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/agent/loop.py)
channels	多渠道通信适配	[base.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/channels/base.py)
bus	消息路由与传递	[events.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/bus/events.py)
tools	工具定义与执行	[registry.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/agent/tools/registry.py)
providers	LLM 提供者抽象	[base.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/providers/base.py)
cron	定时任务调度	[service.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/cron/service.py)
session	会话历史管理	[manager.py](file:///d:/CodeProject/nanobot-main/nanobot-main/nanobot/session/manager.py)

数据流分析

消息处理流程

核心数据结构

nanobot 使用 dataclass 定义核心数据结构，简洁且类型安全：

@dataclass
class InboundMessage:
    """Message received from a chat channel."""
    
    channel: str          # telegram, discord, slack, whatsapp
    sender_id: str        # User identifier
    chat_id: str          # Chat/channel identifier
    content: str          # Message text
    timestamp: datetime = field(default_factory=datetime.now)
    media: list[str] = field(default_factory=list)
    metadata: dict[str, Any] = field(default_factory=dict)
    
    @property
    def session_key(self) -> str:
        """Unique key for session identification."""
        return f"{self.channel}:{self.chat_id}"

扩展机制

工具扩展

添加新工具只需实现 Tool 抽象类：

class Tool(ABC):
    """Abstract base class for agent tools."""
    
    @property
    @abstractmethod
    def name(self) -> str:
        """Tool name used in function calls."""
        pass
    
    @property
    @abstractmethod
    def description(self) -> str:
        """Description of what the tool does."""
        pass
    
    @property
    @abstractmethod
    def parameters(self) -> dict[str, Any]:
        """JSON Schema for tool parameters."""
        pass
    
    @abstractmethod
    async def execute(self, **kwargs: Any) -> str:
        """Execute the tool with given parameters."""
        pass

渠道扩展

添加新通信渠道只需实现 BaseChannel 抽象类：

class BaseChannel(ABC):
    """Abstract base class for chat channel implementations."""
    
    name: str = "base"
    
    @abstractmethod
    async def start(self) -> None:
        """Start the channel and begin listening for messages."""
        pass
    
    @abstractmethod
    async def stop(self) -> None:
        """Stop the channel and clean up resources."""
        pass
    
    @abstractmethod
    async def send(self, msg: OutboundMessage) -> None:
        """Send a message through this channel."""
        pass

LLM 提供者扩展

添加新 LLM 提供者只需实现 LLMProvider 抽象类：

class LLMProvider(ABC):
    """Abstract base class for LLM providers."""
    
    @abstractmethod
    async def chat(
        self,
        messages: list[dict[str, Any]],
        tools: list[dict[str, Any]] | None = None,
        model: str | None = None,
    ) -> LLMResponse:
        """Send a chat completion request."""
        pass

实践案例

快速启动

# 安装
pip install nanobot-ai

# 初始化配置
nanobot onboard

# 配置 API Key
# 编辑 ~/.nanobot/config.json

# 开始对话
nanobot agent -m "Hello, nanobot!"

多渠道部署

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    },
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

# 启动网关
nanobot gateway

设计权衡

设计决策	优势	劣势
极简代码	易读、易维护、快速启动	功能相对有限
组合模式	灵活、可测试	需要手动组装
单进程架构	部署简单、资源占用低	不适合高并发场景
文件存储	无需数据库依赖	大规模数据性能受限

总结

nanobot 通过"极简但完整"的设计理念，证明了 AI Agent 框架不需要复杂的架构和庞大的代码量。其核心设计思想可以总结为：

设计原则	实现方式
极简主义	~4,000 行核心代码，最小依赖
可读优先	清晰命名、充分注释、文档字符串
组合设计	避免深层继承，使用依赖注入
抽象统一	Tool、Channel、Provider 统一接口
渐进加载	Skills 按需加载，减少上下文膨胀

在后续文章中，我们将深入剖析 nanobot 的各个核心模块，包括 Agent Loop、工具系统、多渠道通信和记忆系统。

---

下一篇: Agent Loop：AI Agent 的核心引擎