数字旗手

数字化、智能化、智能体化

0%

跟着🐈NanoBot学AI个人助理设计和开发0：纳米机器人启动！

Posted on Edited on In Disqus:

前言

最近在看OpenClaw这个当今最火的AI个人助理，想通过OpenClaw来研究下这种个人智能助理的设计和开发原理。但是发现OpenClaw太“重”了，动不动就是几十万行代码，层层封装，想从源码层面理解它的运行逻辑（它还是typescript语言），或者想自己魔改加个小功能，往往要翻半天文档。

直到我遇到了 nanobot。

它给我的第一感觉就是“干净”。核心代码只有 4000 行左右（大概只有OpenClaw 的 1%），但麻雀虽小，五脏俱全。它去掉了很多复杂的抽象，保留了 Agent 最核心的能力。

nanobot 内置了非常丰富的渠道支持。你可以把它接入 Telegram、Discord、Slack，甚至是国内的飞书、钉钉、QQ 和微信（通过 Mochat）。我现在把它挂在飞书上，平时想查个资料、翻译段文本，或者只是单纯想找个“人”聊聊代码思路，随时掏出手机就能发消息，它会像一个真正的助理一样回复你。

那么就从nanobot源码开始学习AI个人助理吧。

这次的源码学习我想换个方式，就是由原来的“先考虑顶层架构，然后再看细节实现”，变为“直接深入细节，按图索骥，窥一斑见全貌”这种方式，因为我发现NanoBot的架构跟之前的OpenCode的架构类似，都是由“智能体循环+消息总线+记忆系统+工具/Skill系统”等核心系统构成，如果按原先方式进行梳理的话，跟OpenCode之前的解析是重复了。

安装

使用UV：

1
uv tool install nanobot-ai

或者使用pip：
1
pip install nanobot-ai

因为我们主要是研究源码，所以需要把源码下载下来，项目地址在这里：GitHub - HKUDS/nanobot

纳米机器人启动

安装好nanobot后，如果我们输入：

1
nanobot

会出现：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
root@iZ0jlfb93iky3umeol0f22Z:~# nanobot
                                                                                                                                      
 Usage: nanobot [OPTIONS] COMMAND [ARGS]...                                                                                           
                                                                                                                                      
 🐈 nanobot - Personal AI Assistant                                                                                                   
                                                                                                                                      
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version             -v                                                                                                           │
│ --install-completion            Install completion for the current shell.                                                          │
│ --show-completion               Show completion for the current shell, to copy it or customize the installation.                   │
│ --help                          Show this message and exit.                                                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ onboard   Initialize nanobot configuration and workspace.                                                                          │
│ gateway   Start the nanobot gateway.                                                                                               │
│ agent     Interact with the agent directly.                                                                                        │
│ status    Show nanobot status.                                                                                                     │
│ channels  Manage channels                                                                                                          │
│ cron      Manage scheduled tasks                                                                                                   │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

入口探究

当你输入 nanobot 命令时，后台的执行流程其实是一个标准的 Python 命令行工具启动过程。我们可以把它分为 三个阶段 来理解：

寻找入口 (Shell -> Python)

当在终端敲下 nanobot 并回车时：

  1. Shell 查找：Shell 会在你的系统路径（PATH）中寻找名为 nanobot 的可执行文件。
  2. Entry Point：这个可执行文件实际上是由 Python 的包管理器（如 pip/uv）在安装时自动生成的。它会指向 pyproject.toml 中定义的位置：
    1
    2
    [project.scripts]
    nanobot = "nanobot.cli.commands:app"
    这意味着：“请去加载 nanobot.cli.commands 模块，并运行里面的 app 对象。”

加载与解析 (Typer 框架)

Python 解释器启动后，会加载 nanobot/cli/commands.py 文件。这里面的核心主角是 app 对象：

1
2
3
4
5
6
7
# nanobot/cli/commands.py

app = typer.Typer(
    name="nanobot",
    help=f"{__logo__} nanobot - Personal AI Assistant",
    no_args_is_help=True,  # 重点：如果没有子命令，就显示帮助
)

Typer 是一个基于 Python 类型提示的现代 CLI 库。此时，app() 被调用，它会做两件事：

  1. 解析参数：检查你有没有输入子命令（比如 agent, gateway, onboard）。
  2. 分发任务：
    • 如果你只输入了 nanobot（没带参数），因为设置了 no_args_is_help=True，它会直接打印帮助菜单，列出所有可用命令。
    • 如果你输入了 nanobot agent，它就会去执行被 @app.command() 装饰的 agent 函数。

执行具体功能 (Function Execution)

根据你输入的子命令，Typer 会路由到对应的 Python 函数执行。例如：

  • nanobot agent -> 执行 def agent(...):

    • 初始化 AgentLoop（核心逻辑循环）。
    • 连接 LLM 提供商（OpenRouter/OpenAI 等）。
    • 进入一个 while True 循环，等待你的输入，发送给 AI，处理工具调用，然后返回结果。

  • nanobot gateway -> 执行 def gateway(...):

    • 启动一个长期运行的服务进程。
    • 初始化 MessageBus（消息总线）。
    • 启动各个渠道（Telegram, Discord 等）的监听器。
    • 挂载 CronService（定时任务）和 HeartbeatService（心跳保活）。

总结

简单来说，nanobot 命令就是一个 路由器。它负责解析你的意图，然后把任务分发给后台具体的 Python 函数去执行。

这一节就到这里吧，后面继续。