Nanobot 项目分析

执行摘要

nanobot 是一个超轻量级个人 AI 助手框架，用约 6,595 行 Python 代码实现了核心代理功能。该项目旨在为学术研究和实验用途提供清晰、易读的代码库，易于理解和扩展。它提供了完整的 AI 助手生态系统，包括多聊天平台集成、LLM 提供商支持和模块化架构。

版本： 0.1.3.post5
许可证： MIT
Python 要求： >=3.11
核心代码行数： ~3,448（不包括 channels、cli、providers）

项目概述

目标和愿景

nanobot 旨在提供一个极简但功能齐全的 AI 助手框架，具有以下特点：

超轻量级： 比类似框架（如 Clawdbot 的 430k+ 行）小 99%
研究就绪： 清晰、可读的代码库，适合学术和实验用途
快速： 最小的占用空间，快速启动和低资源使用
易于使用： 一键部署，配置简单

核心特性

多通道支持： Telegram、Discord、WhatsApp、飞书、钉钉
多 LLM 提供商支持： OpenRouter、Anthropic、OpenAI、DeepSeek、Groq、Gemini、DashScope（通义千问）、Moonshot（Kimi）、Zhipu（GLM）、vLLM（本地）
内置工具： 文件操作、shell 执行、web 搜索/获取、cron 调度、消息处理
后台任务执行： 子代理系统用于并发任务处理
会话管理： 持久化对话历史
技能系统： 模块化技能包（GitHub、天气、tmux、摘要、cron）
Docker 支持： 容器化部署
安全特性： 工作区限制、访问控制列表、命令过滤

架构

高层架构

┌─────────────────────────────────────────────────────────────────┐
│                           CLI 层                                │
│  (命令: agent, gateway, cron, channels, status, onboard)        │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────────┐
│                      消息总线 (MQ)                              │
│    InboundMessage → Queue → OutboundMessage                    │
└───────┬───────────────────────────┬─────────────────────────────┘
        │                           │
┌───────▼──────────────┐    ┌──────▼─────────────────────────────┐
│   通道管理器         │    │       Agent 循环 (核心)             │
│  - Telegram          │    │  - 上下文构建器                    │
│  - Discord           │    │  - 工具注册表                      │
│  - WhatsApp          │    │  - 会话管理器                      │
│  - Feishu            │    │  - 子代理管理器                    │
│  - DingTalk          │    │  - 记忆系统                        │
└──────────────────────┘    └──────┬──────────────────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
            ┌───────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
            │   提供商     │ │  工具    │ │   技能      │
            │  - LiteLLM   │ │ - 文件   │ │ - GitHub    │
            │  - 注册表    │ │ - Shell  │ │ - 天气     │
            │              │ │ - Web    │ │ - Tmux      │
            └──────────────┘ └──────────┘ └─────────────┘

核心组件

1. Agent 循环 (`nanobot/agent/loop.py`)

中央处理引擎，负责：

从消息总线接收消息
使用历史记录、记忆和技能构建上下文
通过提供商调用 LLM
执行工具调用
发送响应

主要职责：

消息处理管道
工具编排
会话管理
错误处理

2. 上下文构建器 (`nanobot/agent/context.py`)

通过组合以下内容构建 LLM 提示：

系统提示
对话历史
可用工具
技能文档
当前消息上下文

3. 工具注册表 (`nanobot/agent/tools/registry.py`)

管理所有可用工具，包括：

工具注册和发现
参数验证
执行编排
结果格式化

内置工具：

filesystem：读取、写入、编辑、列出文件
shell：执行 shell 命令（带安全检查）
web：搜索和获取 web 内容
message：向通道发送消息
spawn：创建后台子代理
cron：调度任务

4. 提供商系统 (`nanobot/providers/`)

多个 LLM 提供商的统一接口，使用：

提供商注册表 (registry.py)：提供商元数据的单一真实来源
LiteLLM 集成：跨提供商的标准化 API 调用
自动检测：通过 API 密钥前缀或基础 URL 检测网关提供商
模型前缀：自动模型名称转换

支持的提供商：

提供商	用途	关键特性
OpenRouter	全局网关	访问所有模型，通过 `sk-or-` 前缀检测
Anthropic	Claude 直接	原生 Claude 集成
OpenAI	GPT 直接	原生 OpenAI 集成
DeepSeek	DeepSeek 模型	高性价比中文模型
Groq	LLM + Whisper	免费语音转录
Gemini	Google 模型	Google AI 集成
DashScope	通义千问（阿里）	中文语言模型
Moonshot	Kimi	中文 AI 助手
Zhipu	GLM	智谱 AI 模型
vLLM	本地部署	OpenAI 兼容服务器

5. 消息总线 (`nanobot/bus/`)

异步消息路由系统：

队列：FIFO 消息处理
事件：InboundMessage 和 OutboundMessage 类型
Async/Await：非阻塞消息处理

6. 通道管理器 (`nanobot/channels/`)

多平台消息适配器：

通道	实现	关键特性
Telegram	Bot API	基于 Token，支持代理
Discord	WebSocket	基于 Intents，功能丰富
WhatsApp	Node.js 桥接	QR 认证，本地 WebSocket
Feishu	WebSocket 长连接	无需公网 IP
DingTalk	Stream 模式	无需公网 IP

7. 会话管理器 (`nanobot/session/`)

持久化对话存储：

基于通道和聊天 ID 的会话键
历史记录跟踪
JSON 文件持久化
跨重启的上下文保留

8. 子代理系统 (`nanobot/agent/subagent.py`)

后台任务执行：

生成隔离的代理实例
并发任务处理
向原始通道宣布结果
任务生命周期管理

9. Cron 服务 (`nanobot/cron/`)

定时任务管理：

Cron 表达式解析
任务存储和检索
基于时间的执行
与代理循环集成

10. 技能系统 (`nanobot/skills/`)

模块化技能包：

GitHub：仓库操作
Weather：天气信息
Tmux：终端会话管理
Summarize：文本摘要
Cron：任务调度
Skill-Creator：创建新技能

代码组织

目录结构

nanobot/
├── agent/              # 核心代理逻辑（2,162 行）
│   ├── loop.py         # 代理处理循环
│   ├── context.py      # 提示/上下文构建器
│   ├── memory.py       # 持久化记忆
│   ├── skills.py       # 技能加载器
│   ├── subagent.py     # 后台任务执行
│   └── tools/          # 内置工具
│       ├── base.py     # 工具基类
│       ├── registry.py # 工具注册表
│       ├── filesystem.py
│       ├── shell.py
│       ├── web.py
│       ├── message.py
│       ├── spawn.py
│       └── cron.py
├── providers/          # LLM 提供商实现
│   ├── registry.py     # 提供商注册表（单一真实来源）
│   └── base.py         # 提供商基类
├── channels/           # 聊天通道集成
│   ├── base.py         # 通道基类
│   ├── manager.py      # 通道管理器
│   ├── telegram.py
│   ├── discord.py
│   ├── whatsapp.py
│   ├── feishu.py
│   └── dingtalk.py
├── bus/                # 消息路由
│   ├── events.py       # 事件类型
│   └── queue.py        # 消息队列
├── session/            # 会话管理
│   └── manager.py
├── cron/               # 定时任务
│   └── service.py
├── heartbeat/          # 主动唤醒
├── config/             # 配置
│   ├── schema.py       # Pydantic 模式
│   └── loader.py
├── cli/                # 命令行界面
│   └── commands.py
├── utils/              # 工具函数
└── skills/             # 打包的技能
    ├── github/
    ├── weather/
    ├── tmux/
    ├── summarize/
    ├── cron/
    └── skill-creator/

代码统计

组件	行数	百分比
Agent（核心）	2,162	32.8%
Channels	~1,500	22.7%
CLI	~800	12.1%
Providers	~400	6.1%
Bus/Session/Config	~800	12.1%
Skills	~500	7.6%
其他	~433	6.6%
总计	6,595	100%

核心代理行数（不包括 channels、cli、providers）： ~3,448

技术栈

核心依赖

包	版本	用途
`typer`	>=0.9.0	CLI 框架
`litellm`	>=1.0.0	统一 LLM API
`pydantic`	>=2.0.0	数据验证
`pydantic-settings`	>=2.0.0	配置管理
`websockets`	>=12.0	WebSocket 支持
`websocket-client`	>=1.6.0	WebSocket 客户端
`httpx`	>=0.25.0	异步 HTTP 客户端
`loguru`	>=0.7.0	日志记录
`readability-lxml`	>=0.8.0	Web 内容提取
`rich`	>=13.0.0	终端格式化
`croniter`	>=2.0.0	Cron 表达式解析
`dingtalk-stream`	>=0.4.0	钉钉集成
`python-telegram-bot`	>=21.0	Telegram bot API
`lark-oapi`	>=1.0.0	飞书/Lark API

开发依赖

pytest：测试框架
pytest-asyncio：异步测试支持
ruff：代码检查和格式化

其他技术

Node.js 20：WhatsApp 桥接所需
Docker：容器化支持
vLLM：本地 LLM 服务器（可选）

关键设计模式

1. 提供商注册表模式

位置： nanobot/providers/registry.py

提供商注册表作为所有 LLM 提供商元数据的单一真实来源。该模式实现：

轻松添加提供商：只需 2 步（添加规范，添加配置字段）
自动行为：环境变量、模型前缀和检测都从注册表派生
无 if-elif 链：消除了散布在代码库中的条件逻辑

PROVIDERS: tuple[ProviderSpec, ...] = (
    ProviderSpec(
        name="openrouter",
        keywords=("openrouter",),
        env_key="OPENROUTER_API_KEY",
        display_name="OpenRouter",
        litellm_prefix="openrouter",
        is_gateway=True,
        detect_by_key_prefix="sk-or-",
    ),
    # ... 更多提供商
)

2. 工具注册表模式

位置： nanobot/agent/tools/registry.py

工具在运行时动态注册，实现：

模块化工具系统：易于添加/删除工具
参数验证：自动模式验证
执行编排：统一的工具执行接口

3. 消息总线模式

位置： nanobot/bus/queue.py

将消息生产者（通道）与消费者（代理循环）解耦：

异步队列：非阻塞消息传递
事件类型：强类型消息结构
可扩展性：易于添加新通道或消费者

4. 会话管理

位置： nanobot/session/manager.py

持久化对话状态：

会话键：每个通道/聊天的唯一标识符
历史跟踪：完整的对话历史
JSON 持久化：跨重启存活

5. 子代理模式

位置： nanobot/agent/subagent.py

后台任务执行：

隔离执行：独立的代理实例
并发处理：多个任务并行
结果路由：向原始通道宣布

配置系统

配置文件

位置： ~/.nanobot/config.json

配置模式

位置： nanobot/config/schema.py

关键配置部分

1. 提供商

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx",
      "apiBase": "https://openrouter.ai/api/v1"
    },
    "deepseek": {
      "apiKey": "sk-xxx"
    }
  }
}

2. 代理

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 20,
      "workspace": "~/.nanobot/workspace"
    }
  }
}

3. 通道

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789"],
      "proxy": "socks5://127.0.0.1:1080"
    },
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789"]
    }
  }
}

4. 工具（安全）

{
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "timeout": 60,
      "allowedCommands": ["ls", "cat", "grep"]
    }
  }
}

环境变量

nanobot 支持所有提供商的环境变量：

OPENROUTER_API_KEY
ANTHROPIC_API_KEY
OPENAI_API_KEY
DEEPSEEK_API_KEY
GROQ_API_KEY
GEMINI_API_KEY
DASHSCOPE_API_KEY
MOONSHOT_API_KEY
ZHIPUAI_API_KEY
BRAVE_API_KEY（用于 web 搜索）

CLI 命令

可用命令

命令	描述
`nanobot onboard`	初始化配置和工作区
`nanobot agent -m "..."`	发送单条消息
`nanobot agent`	交互式聊天模式
`nanobot gateway`	启动消息网关
`nanobot status`	显示系统状态
`nanobot cron add`	添加定时任务
`nanobot cron list`	列出定时任务
`nanobot cron remove <id>`	删除任务
`nanobot channels login`	链接 WhatsApp（QR 扫描）
`nanobot channels status`	显示通道状态

交互功能

Readline 支持：方向键、历史导航
持久化历史：保存到 ~/.nanobot/history/cli_history
终端状态管理：退出时正确清理
TTY 输入刷新：清除待处理的按键

安全考虑

安全特性

工作区限制
- restrictToWorkspace 选项限制文件操作
- 防止路径遍历攻击
- 将代理沙箱化到特定目录
访问控制列表
- 每个通道的 allowFrom 列表
- 基于白名单的用户授权
- 空列表 = 允许所有（个人使用默认）
命令过滤
- 阻止危险模式（如 rm -rf /）
- 防止 fork 炸弹
- 阻止文件系统格式化
输入验证
- 所有工具的参数验证
- 类型检查
- 范围和枚举验证
资源保护
- 命令执行超时（默认 60 秒）
- 输出截断（10KB 限制）
- HTTP 请求超时（10-30 秒）

安全最佳实践

API 密钥管理
- 以 0600 权限存储在 ~/.nanobot/config.json
- 永远不要提交到版本控制
- 生产环境使用环境变量
- 定期轮换密钥
通道安全
- 生产环境始终配置 allowFrom
- 开发/生产使用不同的 bot
- 监控访问日志
Shell 执行
- 以非 root 用户运行
- 在日志中查看工具使用情况
- 使用专用用户帐户
依赖安全
- 保持依赖项更新
- 定期运行 pip-audit
- 订阅安全公告

已知限制

无速率限制：用户可以发送无限消息
纯文本配置：API 密钥以纯文本存储
无会话过期：会话无限期持久化
有限的命令过滤：仅阻止明显的模式
无审计跟踪：有限的安全事件日志记录

测试

测试覆盖率

位置： tests/

目前测试覆盖率有限：

test_tool_validation.py：工具参数验证测试
test_docker.sh：Docker 集成测试

测试类型

单元测试：工具验证
集成测试：Docker 部署
手动测试：case/ 目录中的 GIF 演示

测试建议

扩展单元测试：覆盖核心代理逻辑
添加集成测试：测试通道集成
添加端到端测试：完整工作流测试
添加安全测试：输入验证、访问控制
添加性能测试：并发消息处理

部署选项

1. 本地开发

# 克隆并安装
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

# 初始化
nanobot onboard

# 配置
vim ~/.nanobot/config.json

# 运行
nanobot gateway

2. Docker 部署

# 构建镜像
docker build -t nanobot .

# 初始化配置
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# 运行网关
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

3. 生产部署

建议：

使用专用用户帐户
设置适当的文件权限
配置 allowFrom 列表
启用工作区限制
设置监控和日志记录
在 API 提供商上使用速率限制
定期安全更新

优势

超轻量级：仅约 3,448 行核心代码
清晰的架构：组织良好、模块化设计
易于扩展：提供商注册表和工具系统使添加功能变得简单
多平台：支持 5+ 个聊天平台
多提供商：支持 10+ 个 LLM 提供商
研究就绪：代码清晰，适合学术研究
Docker 支持：易于容器化
积极开发：定期更新和改进
良好的文档：全面的 README 和内联注释
安全特性：工作区限制、访问控制、命令过滤

劣势

有限的测试覆盖率：最少的自动化测试
无速率限制：容易受到消息洪水攻击
纯文本配置：API 密钥以纯文本存储
无会话管理：无自动过期
有限的文档：无扩展的 API 文档
无指标/监控：无内置性能监控
无分布式支持：仅单实例
有限的错误处理：某些边缘情况未覆盖
无插件系统：技能手动加载
无多租户：专注于单用户

改进机会

高优先级

扩展测试覆盖率
- 为核心代理逻辑添加单元测试
- 为通道添加集成测试
- 为工作流添加端到端测试
- 目标：80%+ 代码覆盖率
增强安全性
- 添加速率限制
- 实现密钥环集成
- 添加会话过期
- 增强命令过滤
- 添加审计日志
改进文档
- 添加 API 文档
- 添加贡献指南
- 添加架构图
- 添加故障排除指南

中优先级

添加监控
- 性能指标
- 错误跟踪
- 使用情况分析
- 健康检查
增强工具系统
- 工具权限模型
- 工具使用限制
- 工具依赖解析
- 工具沙箱化
改进会话管理
- 会话过期
- 会话上下文限制
- 会话导出/导入
- 多会话支持

低优先级

添加插件系统
- 动态技能加载
- 插件市场
- 插件版本控制
- 插件依赖
多租户支持
- 用户隔离
- 资源配额
- 每用户配置
- 管理面板
分布式支持
- 水平扩展
- 负载均衡
- 共享状态
- 消息队列集群
高级功能
- 长期记忆
- 多模态支持
- 语音输入/输出
- 视频处理

使用场景

1. 个人助手

日常日程管理
任务自动化
信息检索
快速计算

2. 开发者助手

代码生成
调试辅助
文档查找
项目管理

3. 研究助手

文献搜索
数据分析
实验跟踪
报告生成

4. 客服机器人

FAQ 回答
问题分类
升级路由
知识库查询

5. 团队协作

会议记录
任务协调
文档摘要
决策支持

与替代方案的比较

vs. Clawdbot

特性	nanobot	Clawdbot
代码行数	~3,448	430,000+
大小比例	1x	125x
设置复杂度	2 分钟	复杂
研究友好	是	有限
多平台	5+	有限
提供商支持	10+	有限

vs. LangChain

特性	nanobot	LangChain
专注点	完整 AI 助手	LLM 框架
代码大小	~3,448 行	100,000+ 行
学习曲线	低	高
内置通道	是	否
内置工具	是	有限
生产就绪	是	需要设置

vs. AutoGPT

特性	nanobot	AutoGPT
专注点	聊天助手	自主代理
复杂度	低	高
资源使用	最小	高
用户控制	高	低
多平台	是	否

结论

nanobot 是一个设计良好、超轻量级的 AI 助手框架，在最小的代码库中成功实现了核心代理功能。其清晰的架构、模块化设计和全面的功能集使其成为以下用途的绝佳选择：

研究人员：用于实验的清晰代码库
开发人员：易于理解和扩展
用户：简单的设置和部署
组织：内部工具的轻量级解决方案

该项目的优势在于其简单性以及对核心功能的关注。虽然它缺乏大型框架中的一些高级功能，但这正是设计使然，有助于其可维护性和易用性。

随着持续的开发和社区贡献，nanobot 有潜力成为研究和生产用途的领先轻量级 AI 助手框架。

建议

对于用户

从以下开始：Telegram 或 Discord 通道（最简单的设置）
使用：OpenRouter 访问所有模型
启用：restrictToWorkspace 以提高安全性
配置：生产环境的 allowFrom 列表
监控：定期检查日志以发现安全事件

对于开发人员

阅读：nanobot/agent/loop.py 了解核心逻辑
研究：nanobot/providers/registry.py 了解提供商模式
扩展：通过工具注册表添加新工具
贡献：测试、文档和错误修复
遵循：既定的代码风格和模式

对于研究人员

分析：代理循环架构
实验：使用不同的 LLM 提供商
研究：工具编排模式
实现：特定任务的自定义技能
发布：研究发现和贡献

分析生成于 2026-02-09