4000行代码打造个人AI助手,比Claude轻99%,却一样好用!

大家好，我是何三，独立开发者。

今天我们来聊聊整个轻量级的"openBot"的项目架构到底是如何实现的。

github：Commits · HKUDS/nanobot

nanobot 是一个超轻量级（约4000行代码）的个人AI助手，灵感来自 Clawdbot，但体积小了99%。它是一个基于 ReAct (Reasoning + Acting) 模式的智能代理系统。

🏗️ 核心架构图

┌─────────────────────────────────────────────────────────────────┐│                        用户交互层 (Channels)                      ││  ┌──────────┐  ┌──────────┐  ┌──────────┐                       ││  │  CLI     │  │ Telegram │  │ WhatsApp │  (可扩展更多渠道)       ││  └────┬─────┘  └────┬─────┘  └────┬─────┘                       │└───────┼─────────────┼─────────────┼───────────────────────────────┘        │             │             │        └─────────────┴─────────────┘                      │                      ▼┌─────────────────────────────────────────────────────────────────┐│                    消息总线 (Message Bus)                         ││     解耦渠道和核心代理，实现异步消息传递                            ││     - Inbound Queue:  用户消息 → Agent                          ││     - Outbound Queue: Agent响应 → 用户                          │└─────────────────────────────────────────────────────────────────┘                      │                      ▼┌─────────────────────────────────────────────────────────────────┐│                    核心代理引擎 (Agent Loop)                      ││                                                                  ││  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      ││  │ ContextBuilder│◄───│  MemoryStore │    │ SkillsLoader │      ││  │  (上下文构建) │    │  (记忆系统)   │    │  (技能系统)  │      ││  └──────┬───────┘    └──────────────┘    └──────────────┘      ││         │                                                        ││         ▼                                                        ││  ┌─────────────────────────────────────────────────────────┐    ││  │                    LLM Provider                          │    ││  │         (OpenRouter/Anthropic/OpenAI/Gemini等)           │    ││  └─────────────────────────────────────────────────────────┘    ││         │                                                        ││         ▼                                                        ││  ┌─────────────────────────────────────────────────────────┐    ││  │                    Tool Registry                         │    ││  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │    ││  │  │read_file│ │write_file│ │edit_file│ │ list_dir│       │    ││  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │    ││  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │    ││  │  │  exec   │ │web_search│ │web_fetch│ │ message │       │    ││  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │    ││  │  ┌─────────────────────────────────────────────────┐   │    ││  │  │              spawn (子代理工具)                   │   │    ││  │  │         SubagentManager (后台任务管理)            │   │    ││  │  └─────────────────────────────────────────────────┘   │    ││  └─────────────────────────────────────────────────────────┘    │└─────────────────────────────────────────────────────────────────┘                      │                      ▼┌─────────────────────────────────────────────────────────────────┐│                    支撑服务层                                      ││  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           ││  │ CronService  │  │HeartbeatSvc  │  │SessionManager│           ││  │  (定时任务)   │  │  (心跳服务)   │  │  (会话管理)  │           ││  └──────────────┘  └──────────────┘  └──────────────┘           │└─────────────────────────────────────────────────────────────────┘

🔑 核心组件详解

1. 消息总线 (Message Bus) - bus/queue.py

• 作用
  : 解耦消息渠道和代理核心
• 机制
  : 使用 asyncio.Queue 实现异步消息传递
• 特点
  :
• 入队 (inbound): 各渠道将用户消息放入队列
• 出队 (outbound): Agent处理后将响应发回给用户
• 支持订阅模式，不同渠道订阅自己的消息

2. Agent 循环 (Agent Loop) - agent/loop.py

这是整个系统的核心引擎，采用 ReAct 模式:

用户消息 → 构建上下文 → 调用LLM → 解析响应                              ↓                    ┌─────────────────┐                    │  需要工具调用?    │                    └────────┬────────┘                             │           ┌─────────────────┼─────────────────┐           ▼                 ▼                 ▼        是(有工具调用)      否(直接回复)       达到最大迭代           │                 │                 │           ▼                 ▼                 ▼    执行工具调用 ──→ 将结果返回LLM ──→ 继续循环   返回最终结果

核心流程:

1. 接收消息 → 获取/创建会话
2. 构建上下文（历史记录 + 系统提示 + 记忆 + 技能）
3. 调用 LLM，获取响应
4. 如果响应包含工具调用 → 执行工具 → 将结果返回LLM → 继续循环
5. 如果没有工具调用 → 返回最终结果给用户

3. 上下文构建器 (ContextBuilder) - agent/context.py

构建发送给LLM的完整上下文，包括：

• Bootstrap 文件
  : AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md
• 记忆系统
  : 长期记忆 + 近期记忆
• 技能系统
  : 已加载的技能说明

4. 工具系统 (Tools) - agent/tools/

5. 子代理系统 (Subagent) - agent/subagent.py

• 作用
  : 执行耗时的后台任务，不阻塞主代理
• 机制
  : 创建独立的 asyncio.Task 运行子代理
• 特点
  :
• 子代理有独立的工具集（没有 message 和 spawn 工具）
• 完成后通过系统消息通知主代理
• 主代理收到通知后决定如何告知用户

6. 记忆系统 (Memory) - agent/memory.py

• 长期记忆
  : MEMORY.md - 持久化的重要信息
• 每日笔记
  : YYYY-MM-DD.md - 按日期组织的短期记忆
• 自动加载
  : 最近7天的记忆会自动加载到上下文中

7. 技能系统 (Skills) - agent/skills.py

• 位置
  : ~/.nanobot/workspace/skills/ 或内置 nanobot/skills/
• 格式
  : 每个技能是一个目录，包含 SKILL.md
• 加载策略
  :
• 始终加载的技能：完整内容放入上下文
• 可选技能：只显示摘要，需要时通过 read_file 读取

8. 定时任务 (Cron) - cron/service.py

• 支持类型
  :
• at
  : 指定时间执行一次
• every
  : 每隔一段时间执行
• cron
  : Cron表达式
• 持久化
  : 任务存储在JSON文件中

🔄 消息处理完整流程

┌─────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐│  用户   │────►│   Channel   │────►│  MessageBus │────►│  AgentLoop  ││  输入   │     │ (Telegram等)│     │  (inbound)  │     │  _process_  │└─────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘                                                               │                    ┌──────────────────────────────────────────┘                    ▼         ┌─────────────────────┐         │   SessionManager    │         │  获取/创建会话历史   │         └─────────────────────┘                    │                    ▼         ┌─────────────────────┐         │   ContextBuilder    │         │  构建完整系统提示   │         │  (bootstrap+记忆+技能)│         └─────────────────────┘                    │                    ▼         ┌─────────────────────┐         │    LLM Provider     │         │   调用大语言模型     │         └─────────────────────┘                    │         ┌─────────┴──────────┐         ▼                    ▼    ┌─────────┐          ┌─────────┐    │ 工具调用 │          │ 直接回复 │    └────┬────┘          └────┬────┘         │                    │         ▼                    ▼    ┌─────────┐          ┌─────────────┐    │ToolRegistry│        │ 保存到会话   │    │执行工具   │        │ 返回给用户   │    └────┬────┘          └──────┬──────┘         │                      │         └──────────┬───────────┘                    ▼         ┌─────────────────────┐         │  工具结果返回LLM    │         │  继续下一轮推理     │         └─────────────────────┘

💡 设计亮点

1. 超轻量级
   : 核心功能仅约4000行代码，易于理解和修改
2. 模块化设计
   : 渠道、代理、工具完全解耦，易于扩展
3. ReAct 模式
   : 推理-行动循环让Agent能够处理复杂任务
4. 子代理系统
   : 后台任务不阻塞主交互
5. 渐进式技能加载
   : 按需加载技能，控制上下文长度
6. 多记忆层级
   : 长期记忆 + 短期记忆，让Agent有"记忆"
7. 多LLM支持
   : 通过 LiteLLM 支持多种模型提供商

这个项目非常适合作为个人AI助手，也可以作为学习Agent架构的优秀范例！

如果你对这个项目感兴趣完全可以clone下来封装到自己的项目中

我是何三，一个致力于让 AI 开发更简单的独立开发者。如果这篇文章对你有帮助，欢迎分享给你的朋友。我们下期再见！