Nanobot —— 项目概述与整体架构

#Nanobot, Agent

本文档是 Nanobot 框架的综述，帮助开发者快速了解其设计哲学、整体架构与各模块职责。

1. 项目定位

Nanobot 是一个开源、轻量级 AI Agent 框架，核心目标是保持极简可读的 Agent Loop 内核，同时通过插件化扩展支持多渠道部署、持久记忆、MCP 集成和生产级运维。

定位对比
─────────────────────────────────────────────────────
框架           特点                       适用场景
─────────────────────────────────────────────────────
Nanobot        极简核心 + 插件扩展         个人助手 / 研究 / 生产
LangGraph      状态机编排                  复杂工作流
CrewAI         角色分工多 Agent            任务协作团队
Hermes         自学习 + 企业级             大规模生产部署
─────────────────────────────────────────────────────

核心理念：Agency 来自模型训练，不是代码编排。框架只提供工具环境（Harness），不设计智能逻辑。

2. 设计哲学

2.1 极简核心

Agent Loop 核心不超过 500 行代码，逻辑一目了然：

1
2
3

用户消息 → 加载上下文 → 调用 LLM → 执行工具 → 回复消息
                              ↑              ↓
                         继续迭代 ← 工具结果注回

添加新能力不修改核心，只增加 Hook / Plugin / Tool。

2.2 关注点分离

┌─────────────────────────────────────────────┐
│               渠道层（Channels）              │
│  Telegram  Discord  Slack  Email  WebSocket  │
└────────────────────┬────────────────────────┘
                     │ InboundMessage
┌────────────────────▼────────────────────────┐
│              消息总线（MessageBus）           │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│           Agent 核心层（Agent Core）          │
│   Loop  ▶  Runner  ▶  ToolRegistry          │
│              ↕                               │
│           Hook System                        │
└────┬───────────────────┬────────────────────┘
     │                   │
┌────▼────┐         ┌────▼─────────────────┐
│ Memory  │         │   Provider Layer      │
│ SOUL.md │         │  Anthropic / OpenAI   │
│ USER.md │         │  Azure / Copilot      │
│ MEM.md  │         └──────────────────────┘
└─────────┘

2.3 文件原生记忆

长期记忆以 Markdown 文件存储，受 Git 版本控制，人类可读可编辑：

workspace/
├── SOUL.md       # Agent 个性与沟通风格
├── USER.md       # 用户信息与偏好
├── MEMORY.md     # 项目事实与决策记录
└── memory/
    ├── history.jsonl   # 压缩后的历史消息
    └── sessions/       # 原始会话存储

3. 整体架构

3.1 模块全景

nanobot/
├── agent/                  # Agent 核心层
│   ├── loop.py             # 主处理循环
│   ├── runner.py           # LLM 迭代引擎
│   ├── hook.py             # Hook 系统
│   ├── memory.py           # 记忆管理
│   ├── context.py          # 上下文构建
│   ├── autocompact.py      # 自动上下文压缩
│   ├── skills.py           # 技能加载器
│   ├── subagent.py         # 子 Agent
│   └── tools/              # 工具系统
│       ├── registry.py
│       ├── filesystem.py
│       ├── shell.py
│       ├── web.py
│       ├── mcp.py
│       └── ...
├── channels/               # 渠道适配层
│   ├── base.py
│   ├── telegram.py
│   ├── discord.py
│   ├── slack.py
│   └── ...（15+ 渠道）
├── providers/              # LLM Provider 层
│   ├── base.py
│   ├── anthropic_provider.py
│   ├── openai_compat_provider.py
│   └── ...（30+ 提供商）
├── session/                # 会话管理
├── bus/                    # 消息总线
├── cron/                   # 定时调度
├── config/                 # 配置系统
├── templates/              # Jinja2 模板
└── api/                    # OpenAI 兼容 API

3.2 模块职责

模块	核心类	职责
`agent/loop.py`	`AgentLoop`	消息接收、上下文组装、迭代调度
`agent/runner.py`	`AgentRunner`	LLM 调用、工具执行、结果注回
`agent/hook.py`	`AgentHook`	生命周期扩展点
`agent/memory.py`	`MemoryStore` / `Dream`	文件层读写、压缩、学习
`agent/tools/registry.py`	`ToolRegistry`	工具注册、查找、执行分发
`channels/`	`BaseChannel`	渠道消息收发
`bus/queue.py`	`MessageBus`	渠道与 Agent 解耦队列
`providers/`	`LLMProvider`	统一 LLM 接口
`session/manager.py`	`SessionManager`	会话历史存取
`cron/service.py`	`CronService`	定时任务调度

4. 技术栈

4.1 核心依赖

分类	依赖	版本	用途
LLM SDK	anthropic	≥0.45.0	Claude 系列模型
LLM SDK	openai	≥2.8.0	OpenAI 及兼容 API
数据验证	pydantic	≥2.12.0	配置与数据模型
CLI	typer	≥0.20.0	命令行入口
终端	rich	—	美化输出
模板	jinja2	—	系统提示渲染
HTTP	httpx	≥0.28.0	异步 HTTP 客户端
WebSocket	websockets	≥16.0	WebSocket 支持
搜索	ddgs	—	DuckDuckGo 搜索
Git	dulwich	—	文件版本控制记忆
Token 计数	tiktoken	—	上下文预算管理
MCP	mcp	≥1.26.0	Model Context Protocol
定时	croniter	≥6.0.0	Cron 表达式解析

4.2 可选渠道依赖

渠道	依赖包
Telegram	`python-telegram-bot`
Discord	`discord.py`
Slack	`slack-sdk`
飞书	`lark-oapi`
钉钉	`dingtalk-stream`
企业微信	`wecom`
QQ	`qq-botpy`
Matrix	`matrix-nio`

4.3 运行时要求

Python ≥ 3.11
支持 asyncio（全面 async/await）

5. 部署方式

5.1 CLI 模式

# 单 Agent 交互
nanobot agent

# 多渠道网关
nanobot gateway

# 初始化配置向导
nanobot onboard

5.2 Docker 模式

docker build -t nanobot .
docker run -d \
  -e ANTHROPIC_API_KEY=sk-... \
  -v $(pwd)/workspace:/workspace \
  nanobot gateway

5.3 OpenAI 兼容 API

# 启动 API 服务器（供第三方集成）
nanobot api --port 8080

# 兼容 OpenAI Chat Completions 接口
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "nanobot", "messages": [...]}'

5.4 部署对比

方式	适用场景	优势
CLI 直接运行	本地开发调试	快速启动
Docker	服务器长期运行	环境隔离
docker-compose	多渠道同时部署	编排管理
systemd 服务	Linux 生产环境	自动重启
API 服务器	第三方集成	标准接口

6. 配置系统

// ~/.nanobot/config.json 示例结构
{
  "agent": {
    "model": "claude-sonnet-4-6",
    "workspace": "~/workspace",
    "max_iterations": 50,
    "max_tokens": 8000
  },
  "providers": {
    "anthropic": {"api_key": "sk-ant-..."},
    "openai": {"api_key": "sk-..."}
  },
  "channels": {
    "telegram": {"token": "...", "allowed_users": [123456]},
    "discord": {"token": "..."}
  },
  "dream": {
    "enabled": true,
    "interval_hours": 24
  },
  "tools": {
    "mcp_servers": [
      {"name": "filesystem", "command": "npx", "args": [...]}
    ]
  }
}

配置通过 Pydantic Settings 加载，支持环境变量覆盖，优先级：环境变量 > 配置文件 > 默认值。

#Nanobot, Agent