nanobot 速通

# Nanobot 项目学习指南

## 1. 项目概述

**Nanobot** 是一个超轻量级的个人AI助手框架，以 **99%更少的代码量**（相比OpenClaw）实现核心智能体功能。

### 核心特点
- **超轻量级**: ~20,000行Python代码（相比传统系统的200万+行）
- **研究友好**: 清晰可读的代码，易于理解和修改
- **生产就绪**: 支持15+聊天平台和25+ LLM提供商
- **易于部署**: 通过`nanobot onboard`一键设置

**当前版本**: 0.1.4.post5 (2026年3月)

**关键数据**:
- 纯Python实现，依赖最小化
- 异步优先架构
- 基于插件的频道和提供商系统
- 总计约20,140行代码

---

## 2. 架构概览

系统采用**解耦的事件驱动架构**，包含以下核心层：

```
┌─────────────────────────────────────────────────────────────┐
│                    聊天频道层                                 │
│    (Telegram, Discord, Feishu, Slack, WhatsApp, etc.)      │
└──────────────────────┬──────────────────────────────────────┘
                       │
           ┌───────────▼────────────┐
           │   消息总线 (异步队列)   │
           │                        │
           └───────────┬────────────┘
                       │
        ┌──────────────▼──────────────┐
        │      Agent循环               │
        │  (LLM ↔ 工具执行)           │
        │                              │
        │  - 上下文构建器              │
        │  - 工具注册表                │
        │  - 记忆系统                  │
        │  - 会话管理器                │
        └──────────────┬───────────────┘
                       │
    ┌──────────────────┼──────────────────┐
    │                  │                  │
    ▼                  ▼                  ▼
  工具              提供商              外部系统
  (Exec,        (OpenAI, Claude,    (MCP服务器,
   Web,         DeepSeek, etc.)      Web API)
   File,
   Spawn)
```

---

## 3. 主要目录结构

| 目录 | 用途 | 关键组件 |
|------|------|----------|
| **`nanobot/agent/`** | 核心agent循环与执行 | `loop.py`, `runner.py`, `context.py`, `memory.py`, `skills.py`, `subagent.py` |
| **`nanobot/channels/`** | 聊天平台集成 | `telegram.py`, `discord.py`, `slack.py`, `feishu.py`, `whatsapp.py`, `matrix.py`等 |
| **`nanobot/providers/`** | LLM提供商实现 | `openai_compat_provider.py`, `anthropic_provider.py`, `azure_openai_provider.py`, `registry.py` |
| **`nanobot/bus/`** | 异步消息路由 | `queue.py` (MessageBus), `events.py` (消息类型) |
| **`nanobot/session/`** | 对话历史 | `manager.py` (Session & SessionManager) |
| **`nanobot/config/`** | 配置与模式 | `schema.py` (Pydantic模型), `paths.py` (文件路径) |
| **`nanobot/cli/`** | 命令行接口 | `commands.py` (Typer应用), `stream.py` (输出渲染) |
| **`nanobot/skills/`** | 内置技能 | `github/`, `weather/`, `cron/`, `memory/`, `tmux/`, `clawhub/` |
| **`nanobot/agent/tools/`** | 内置工具 | `shell.py`, `filesystem.py`, `web.py`, `spawn.py`, `cron.py`, `mcp.py` |
| **`nanobot/cron/`** | 计划任务管理 | Cron表达式解析与执行 |
| **`nanobot/heartbeat/`** | 周期性唤醒服务 | 通过`HEARTBEAT.md`管理任务 |
| **`nanobot/command/`** | 内置命令系统 | 特殊命令路由 |

---

## 4. 核心技术栈

### 核心依赖:
- **CLI**: `typer` (0.20+) — 类型安全的CLI框架
- **配置**: `pydantic` (2.12+) + `pydantic-settings` — 验证与序列化
- **异步**: `asyncio`, `websockets`, `websocket-client` — 事件驱动架构
- **LLM SDK**:
  - `anthropic>=0.45.0` — Claude API
  - `openai>=2.8.0` — OpenAI API
  - 直接集成（自2026年3月起移除了`litellm`依赖）
- **HTTP**: `httpx>=0.28.0` — 异步HTTP客户端
- **日志**: `loguru>=0.7.3` — 结构化日志
- **UI**: `rich>=14.0.0` — 终端格式化
- **提示**: `prompt-toolkit>=3.0.50` — 交互式CLI

### 聊天平台集成（内置）:
- **Telegram**: `python-telegram-bot[socks]>=22.6`
- **Discord**: 通过`discord.py`模式
- **Slack**: `slack-sdk>=3.39.0`
- **Feishu**: `lark-oapi>=1.5.0`
- **QQ**: `qq-botpy>=1.2.0`
- **DingTalk**: `dingtalk-stream>=0.24.0`
- **WhatsApp**: Node.js桥接（TypeScript在`/bridge`目录）
- **Matrix**: `matrix-nio[e2e]>=0.25.2` (可选)
- **WeChat**: 自定义集成
- **WeCom**: `wecom-aibot-sdk-python>=0.1.5` (可选)

### 可选集成:
- **MCP**: `mcp>=1.26.0` — 模型上下文协议支持
- **LangSmith**: `langsmith>=0.1.0` — LLM可观测性
- **本地LLM**: 支持`ollama`, `vllm`, OpenVINO

---

## 5. 重要入口点与核心模块

### CLI入口点
```python
# pyproject.toml
[project.scripts]
nanobot = "nanobot.cli.commands:app"
```

**主要命令组** (`nanobot/cli/commands.py`):
- `nanobot onboard` — 初始化配置与工作区
- `nanobot agent` — 与agent聊天（CLI模式）
- `nanobot gateway` — 启动网关（常驻bot）
- `nanobot status` — 显示系统状态
- `nanobot provider login` — 提供商OAuth
- `nanobot channels login` — 聊天平台认证
- `nanobot channels status` — 显示频道连接状态

### 核心Agent循环 (`nanobot/agent/loop.py`)

`AgentLoop`类是执行的核心:

```
1. 从MessageBus接收消息
2. 通过ContextBuilder构建上下文
   - 系统提示词来自identity + bootstrap文件
   - 用户记忆来自MEMORY.md
   - 活跃技能列表
3. 调用LLMProvider获取响应
4. 通过ToolRegistry执行工具调用（如有）
5. 将响应发送回MessageBus
6. 重复直到完成或达到max_iterations
```

**关键方法**:
- `async process_message()` — 主入口点
- `_build_context()` — 组装系统提示词 + 历史
- `_execute_tool()` — 运行单个工具
- `_consolidate_memory()` — 执行后保存记忆

### 消息总线 (`nanobot/bus/queue.py`)

解耦频道与agent处理:

```python
class MessageBus:
    inbound: asyncio.Queue[InboundMessage]   # 频道 → Agent
    outbound: asyncio.Queue[OutboundMessage] # Agent → 频道
```

**事件** (`nanobot/bus/events.py`):
- `InboundMessage` — 来自频道的用户消息
- `OutboundMessage` — 要发送回的agent响应

### 配置系统 (`nanobot/config/schema.py`)

基于Pydantic的配置，包含两部分:

1. **ProvidersConfig** — LLM提供商凭证
   - `anthropic`, `openai`, `openrouter`, `deepseek`, `groq`等
   - 支持25+提供商

2. **ChannelsConfig** — 聊天平台凭证
   - 全局: `send_progress`, `send_tool_hints`, `send_max_retries`
   - 每个频道: `enabled`, `token`, `allowFrom`等

3. **ToolsConfig** — 工具启用
   - `exec` — Shell执行
   - `web` — Web搜索配置
   - `mcp_servers` — MCP服务器定义
   - `restrict_to_workspace` — 安全沙箱

4. **AgentsConfig** — Agent默认设置
   - 模型选择、温度、令牌限制
   - 工作区路径、时区

---

## 6. 核心模块详解

### A. Agent执行流程

**文件**: `nanobot/agent/loop.py`

```python
class AgentLoop:
    async def process_message(self, message: InboundMessage):
        # 1. 为此频道/聊天获取或创建会话
        session = self.sessions.get_or_create(message.session_key)

# 2. 使用记忆和技能构建系统提示词
        system = self.context.build_system_prompt()

# 3. 将用户消息添加到历史
        session.add_message("user", message.content)

# 4. 通过runner运行agent
        result = await self.runner.run(AgentRunSpec(...))

# 5. 保存会话并整合记忆
        session.messages.extend(result.messages)
        await self.memory.consolidate(session)

# 6. 发送响应
        await self.bus.publish_outbound(OutboundMessage(...))
```

### B. 工具系统

**文件**: `nanobot/agent/tools/registry.py`

Agent可用的内置工具:

| 工具 | 文件 | 用途 |
|------|------|------|
| `exec` | `shell.py` | 执行Shell命令 |
| `read_file` | `filesystem.py` | 读取文件 |
| `write_file` | `filesystem.py` | 写入文件 |
| `edit_file` | `filesystem.py` | 用补丁编辑文件 |
| `list_dir` | `filesystem.py` | 列出目录 |
| `web_search` | `web.py` | Web搜索 |
| `web_fetch` | `web.py` | 获取网页内容 |
| `message` | `message.py` | 发送通知 |
| `spawn` | `spawn.py` | 启动后台子agent |
| `cron` | `cron.py` | 管理计划任务 |
| MCP工具 | `mcp.py` | 来自MCP服务器的自定义工具 |

### C. 提供商系统

**文件**: `nanobot/providers/registry.py`

所有LLM提供商的单一事实来源注册表:

```python
@dataclass(frozen=True)
class ProviderSpec:
    name: str                    # "openrouter", "anthropic"等
    keywords: tuple[str, ...]    # 模型名称关键词（用于自动检测）
    env_key: str                 # 环境变量名
    display_name: str            # 用户友好的显示名
    backend: str                 # "openai_compat", "anthropic", "azure_openai"
    is_gateway: bool             # 路由任何模型
    is_local: bool               # 本地部署
    default_api_base: str        # OpenAI兼容端点URL
```

**实现**:
- `openai_compat_provider.py` — 通用OpenAI兼容（处理20+提供商）
- `anthropic_provider.py` — Claude直接API
- `azure_openai_provider.py` — Azure OpenAI
- `openai_codex_provider.py` — OpenAI Codex (OAuth)

### D. 频道系统

**文件**: `nanobot/channels/manager.py` + 各个频道实现

```python
class BaseChannel:
    async def start(self):
        """开始监听来自平台的消息"""

async def send(self, message: OutboundMessage):
        """将消息发送回用户"""
```

**频道插件可通过以下方式发现**:
1. `nanobot/channels/`中的内置频道
2. 外部插件的Python入口点
3. 基于配置的自动实例化

### E. 会话与记忆系统

**文件**:
- `nanobot/session/manager.py` — 对话历史
- `nanobot/agent/memory.py` — 长期记忆整合

**双层记忆**:
1. **MEMORY.md** — 长期事实（持久知识）
2. **HISTORY.md** — 可grep的事件日志

**记忆整合**: 每次对话后运行；使用LLM总结关键事件和事实。

### F. 技能系统

**文件**: `nanobot/agent/skills.py`

技能是扩展agent能力的markdown文件:

```
nanobot/skills/
├── github/           # GitHub集成
├── weather/          # 天气API技能
├── cron/             # 计划任务技能
├── memory/           # 记忆管理
├── tmux/             # 终端复用器集成
└── clawhub/          # ClawHub集成
```

技能从工作区和系统目录加载。

---

## 7. 数据与配置文件

### 工作区结构
```
~/.nanobot/
├── config.json          # 主配置
├── workspace/           # 默认工作区
│   ├── sessions/        # 对话历史（JSONL）
│   ├── MEMORY.md        # 长期记忆
│   ├── HISTORY.md       # 事件日志
│   ├── HEARTBEAT.md     # 周期性任务
│   ├── AGENTS.md        # 身份自定义
│   ├── SOUL.md          # 个性特征
│   ├── USER.md          # 用户上下文
│   └── TOOLS.md         # 工具描述
├── cron/                # Cron作业定义
├── media/               # 下载的媒体
└── bridge/              # WhatsApp Node.js桥接
```

### Config.json结构
```json
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter",
      "workspace": "~/.nanobot/workspace"
    }
  },
  "providers": {
    "openrouter": {"apiKey": "sk-or-..."},
    "anthropic": {"apiKey": "sk-ant-..."}
  },
  "channels": {
    "sendProgress": true,
    "telegram": {"enabled": true, "token": "..."}
  },
  "tools": {
    "web": {"search": {"provider": "brave"}},
    "exec": {"enable": true}
  }
}
```

---

## 8. 测试基础设施

**测试结构** (`tests/`):
- `tests/agent/` — Agent循环、记忆、上下文测试
- `tests/config/` — 配置验证
- `tests/providers/` — 提供商集成测试
- `tests/tools/` — 单个工具测试
- `tests/channels/` — 频道集成测试
- `tests/security/` — 安全加固测试

**测试框架**: pytest with asyncio支持

---

## 9. 关键特性与能力

### Agent能力
- **工具使用** — 执行10+内置工具（shell、文件、web、spawn）
- **记忆** — 带整合的持久长期记忆
- **计划任务** — 基于Cron的任务调度
- **后台执行** — 通过`spawn`工具生成子agent
- **流式传输** — 实时响应流式传输到频道
- **MCP支持** — 来自模型上下文协议服务器的自定义工具
- **推理** — Claude思考模式支持（低/中/高）

### 多平台支持
- **频道**: 15+聊天平台（Telegram、Discord、Slack、WhatsApp等）
- **提供商**: 25+ LLM提供商（OpenRouter、Claude、GPT、DeepSeek、本地模型）
- **部署**: CLI、Docker、systemd服务、多实例

### 安全特性
- **访问控制** — 每个频道的`allowFrom`白名单
- **工作区沙箱** — `restrictToWorkspace`选项
- **Shell安全** — 工具执行沙箱
- **配置验证** — 基于Pydantic的验证

---

## 10. 开发与扩展点

### 添加新提供商（2步）

1. 在`nanobot/providers/registry.py`的`PROVIDERS`中添加`ProviderSpec`
2. 在`nanobot/config/schema.py`的`ProvidersConfig`中添加字段

其他所有内容（环境变量、自动检测、CLI）自动处理。

### 添加新频道

1. 在`nanobot/channels/`中创建继承`BaseChannel`的类
2. 实现`async start()`和`async send()`
3. 通过入口点或pkgutil发现注册

详见`docs/CHANNEL_PLUGIN_GUIDE.md`。

### 添加新工具

1. 创建继承`BaseTool`的工具类
2. 向`ToolRegistry`注册
3. 实现`async execute()`方法

---

## 11. 性能与可扩展性

- **轻量级**: ~20K行 vs 2M+行（替代方案）
- **异步优先**: 所有I/O都是非阻塞的
- **多实例**: 每个平台/租户运行独立实例
- **最小依赖**: 纯Python，只有必要的包
- **内存高效**: 会话整合防止无限增长

---

## 12. 最近变更与路线图

**最近（2026年3月）**:
- 移除`litellm`依赖（供应链安全）
- 原生`openai` + `anthropic` SDK
- 交互式设置向导
- Telegram流式传输改进
- Step Fun（中国大陆）提供商

**路线图**:
- 多模态（图像、语音、视频）
- 长期记忆改进
- 更好的推理（多步骤规划）
- 更多集成（日历等）
- 从反馈中自我改进

---

## 13. 学习路径建议

### 理解架构:
1. 从README.md和项目结构开始
2. 阅读`nanobot/agent/loop.py`（核心agent循环）
3. 研究`nanobot/bus/queue.py`（消息路由）
4. 探索`nanobot/config/schema.py`（配置模型）

### 添加功能:
1. 查看现有频道实现（如`nanobot/channels/telegram.py`）
2. 研究`ToolRegistry`系统
3. 按照模式添加新提供商或工具

### 理解集成:
1. 查看`nanobot/providers/registry.py`（提供商系统）
2. 查看`nanobot/channels/manager.py`（频道加载）
3. 研究单个频道实现

---

## 14. 快速参考: 主要文件

| 文件 | 行数 | 用途 |
|------|------|------|
| `agent/loop.py` | ~400 | 核心agent循环 |
| `agent/runner.py` | ~200 | 共享LLM执行 |
| `channels/manager.py` | ~150 | 频道协调 |
| `config/schema.py` | ~300 | Pydantic配置模型 |
| `cli/commands.py` | ~800 | CLI命令（agent、gateway、onboard） |
| `providers/registry.py` | ~400 | 提供商元数据注册表 |
| `agent/memory.py` | ~350 | 记忆整合 |
| `session/manager.py` | ~250 | 会话管理 |

---

## 15. 代码示例

### 示例1: 创建自定义工具

```python
# nanobot/agent/tools/my_tool.py
from nanobot.agent.tools.base import BaseTool

class MyCustomTool(BaseTool):
    name = "my_tool"
    description = "我的自定义工具描述"

async def execute(self, **kwargs):
        # 工具逻辑
        result = do_something(kwargs)
        return {"result": result}
```

### 示例2: 使用消息总线

```python
from nanobot.bus.queue import MessageBus
from nanobot.bus.events import InboundMessage, OutboundMessage

# 发布入站消息
await bus.publish_inbound(InboundMessage(
    session_key="telegram:123456",
    content="你好，助手！",
    user_id="123456"
))

# 订阅出站消息
async for message in bus.subscribe_outbound():
    print(f"发送给 {message.session_key}: {message.content}")
```

### 示例3: 扩展配置

```python
# nanobot/config/schema.py
class MyToolConfig(BaseModel):
    enabled: bool = False
    api_key: Optional[str] = None

class ToolsConfig(BaseModel):
    # ... 现有工具 ...
    my_tool: MyToolConfig = Field(default_factory=MyToolConfig)
```

---

## 16. 常见问题

### Q: 如何添加新的LLM提供商？
A: 在`providers/registry.py`中添加`ProviderSpec`，在`config/schema.py`中添加配置字段。

### Q: 如何启用工具沙箱？
A: 在`config.json`中设置`tools.restrictToWorkspace: true`。

### Q: 如何自定义agent身份？
A: 编辑工作区中的`AGENTS.md`文件。

### Q: 如何查看日志？
A: 使用`loguru`，日志在`~/.nanobot/logs/`目录。

### Q: 如何部署为服务？
A: 使用`nanobot gateway`命令或创建systemd服务。

---

## 17. 资源链接

- **文档**: `docs/`目录
- **示例**: `examples/`目录
- **测试**: `tests/`目录
- **GitHub**: 项目仓库
- **社区**: 问题跟踪器

---

这份学习指南提供了理解nanobot架构、扩展它以及为项目做贡献的全面基础。代码库有意保持清晰和可读，使其成为研究和学习的理想选择。

其他