写在前面：关于 Hermes Agent

Hermes Agent 是由知名 AI 研究机构 Nous Research 开发的一款具备高度自我进化能力的开源智能体系统。它旨在打破传统大模型“阅后即焚”的单一对话框限制，让 AI 真正“生活”在开发者的终端、团队的通讯软件以及自动化的流水线中。

核心亮点：

• 闭环学习与长期记忆：它不仅能执行任务，还能在跨会话中持久化记忆，甚至从经验中自主创建和优化专属技能。
• 全平台无缝接入：内置强大的消息网关，一套代码即可接入 CLI、Telegram、Discord、Slack 等平台，实现跨设备状态同步。
• 模型无关与热切换：不被单一厂商锁定，支持随时无缝切换底层大模型（如 OpenAI、Anthropic、本地大模型等）。
• 多智能体协作与沙盒隔离：支持生成隔离的子智能体（Subagents）并行处理复杂任务，并在 Docker、SSH 等多种安全沙盒中执行代码。

本教程将带你由浅入深，掌握如何将其作为 Python 库使用，打造你自己的强大 AI 应用。

1. 环境准备

在开始之前，请确保你已经激活了项目的虚拟环境。

对于配置模型，Hermes Agent 采用了全新的配置管理机制：

⚠️ 重要提示：
过去很多 AI 工具喜欢通过终端 export OPENAI_BASE_URL 或在 .env 中设置 LLM_MODEL 等环境变量来控制模型。但在 Hermes Agent 最新版本中，这些旧的环境变量已被完全废弃，即使在终端 export 也不会生效！
Hermes 的核心配置来源是统一的配置文件：~/.hermes/config.yaml（或者通过代码显式传参）。

配置第三方中转 API（Custom Provider）的正确姿势：

如果你希望全局使用第三方中转站（使得 CLI 和代码调用都默认生效），最推荐的做法是直接修改 ~/.hermes/config.yaml：

1
2
3
4
5
6

# 在 ~/.hermes/config.yaml 中配置：
model:
  default: gpt-5.4-mini                       # 你的模型名称
  provider: custom                            # 必须声明 provider 为 custom
  base_url: https://api.your-proxy.com/v1     # 中转站的 Base URL
  api_key: your-api-key-here                  # 中转站的 API Key

或者使用交互式命令自动配置：

1
2
3

hermes model
# 选择 "Custom endpoint (self-hosted / VLLM / etc.)"
# 按照提示输入 Base URL、API Key 和模型名称即可。

当然，你也可以完全在代码中动态覆盖这些配置（见下一节）。

2. 基础篇：最简单的单次对话 (Single-turn Chat)

使用 Hermes 最简单的方法是调用 chat() 方法 —— 传入一条消息，返回一段字符串文本。它会在内部自动处理完整的对话循环（包括工具调用、重试等）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

from run_agent import AIAgent

# 初始化 Agent
agent = AIAgent(
    model="gpt-5.4-mini",        # 指定模型
    provider="custom",           # 明确指定为自定义端点
    base_url="https://api.your-proxy.com/v1", # 代码中显式指定第三方中转站
    api_key="your-api-key-here", # 代码中显式指定 API Key
    quiet_mode=True,             # 开启静默模式，不在控制台打印 CLI 动画和终端输出
    skip_memory=True,            # 不持久化对话历史
    skip_context_files=True      # 不读取默认的 AGENTS.md 上下文文件
)

# 使用 chat 方法进行简单对话
response = agent.chat("用一句话解释一下什么是 Python 装饰器？")
print("AI 回复:", response)

⚠️ 注意： 将 Hermes 嵌入到你自己的代码中时，请务必设置 quiet_mode=True。否则，Agent 会打印 CLI 的加载动画和进度指示器，这会扰乱你的应用输出。

3. 进阶篇：完全对话控制与多轮对话 (Full Conversation Control)

如果需要对对话有更多的控制权，请直接使用 run_conversation()。它不仅返回最终的文本回复，还会返回完整的消息历史记录和元数据字典。

3.1 获取完整上下文与自定义 System Prompt

你可以通过 run_conversation() 传入临时的 system_message，覆盖该次调用的系统提示词：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

from run_agent import AIAgent

agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    quiet_mode=True,
)

result = agent.run_conversation(
    user_message="解释一下什么是快速排序",
    system_message="你是一个计算机科学导师。请使用生活中的简单比喻来解释。",
    task_id="my-task-1", # 用于环境隔离的任务 ID
)

print("最终回复:", result["final_response"])
print(f"总共交互的消息数: {len(result['messages'])}")

返回的字典包含：

• final_response — Agent 的最终文本回复
• messages — 完整的消息历史（包含 system, user, assistant, tool calls）
• task_id — 用于虚拟机隔离的任务标识符

3.2 保持多轮对话状态与持久化机制

Hermes 的对话历史状态保存有两种模式：

模式 A：纯内存传递（适合无状态 API）

要在多个回合之间在纯内存中保持对话状态，只需将上一次返回的 messages 历史记录重新传入 conversation_history 参数即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

from run_agent import AIAgent

agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    quiet_mode=True,
    skip_memory=True, # 关闭自动持久化
)

# 第一轮对话
result1 = agent.run_conversation("你好，我叫 Alice，我最喜欢的颜色是蓝色。")
history = result1["messages"]
print("第一轮回复:", result1["final_response"])

# 第二轮对话 —— Agent 能从 history 中回忆起上下文
result2 = agent.run_conversation(
    "你还记得我叫什么名字，喜欢什么颜色吗？",
    conversation_history=history,
)
print("第二轮回复:", result2["final_response"]) # "你叫 Alice，喜欢蓝色。"

模式 B：SQLite 自动持久化存储（适合 CLI/聊天机器人）

如果你想让对话记录持久化到本地硬盘，即使程序重启也能继续聊天，你只需要在初始化 AIAgent 时传入一个固定的 session_id。

Hermes 底层使用了 hermes_state.py 提供的 SessionDB。它会将所有的对话消息自动存入 ~/.hermes/state.db (SQLite 数据库) 中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

from run_agent import AIAgent

# 初始化时设定 session_id，并确保没有设置 skip_memory=True
agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    quiet_mode=True,
    session_id="my_tutorial_session",  # 关键：指定会话 ID
    # skip_memory=False, # 默认就是 False，允许读写 SQLite
)

# 只要指定了 session_id，AIAgent 会在每次对话后自动将历史追加到 SQLite 数据库中。
res1 = agent.run_conversation("我最喜欢的水果是苹果。")
print("回复:", res1["final_response"])

# --- 假设在这里程序崩溃重启 ---
# 下次运行同样的脚本，传入相同的 session_id，Hermes 会自动从 SQLite 中加载历史记录
res2 = agent.run_conversation("我最喜欢的水果是什么？")
print("回复:", res2["final_response"]) # "你最喜欢的水果是苹果。"

4. 配置篇：工具权限与运行轨迹

4.1 开启或禁用工具 (Configuring Tools)

你可以通过 enabled_toolsets（白名单）或 disabled_toolsets（黑名单）来控制 Agent 有权使用哪些工具集：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 仅启用网络工具（浏览、搜索），适合做纯粹的“研究助手”
agent_web_only = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# 启用所有工具，但禁用终端执行权限（适合在不安全的共享环境中运行）
agent_no_terminal = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

4.2 保存对话轨迹 (Saving Trajectories)与临时人设

如果你需要收集数据用于模型微调，可以开启轨迹保存。同时，使用 ephemeral_system_prompt 可以设定专属人设，且该设定不会污染保存的轨迹数据：

1
2
3
4
5
6
7
8
9
10
11

agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    ephemeral_system_prompt="你是一个 SQL 专家。只回答与数据库相关的问题。",
    save_trajectories=True, # 开启后，对话将以 ShareGPT 格式保存到 trajectory_samples.jsonl
    quiet_mode=True,
)

response = agent.chat("我该怎么写一个 JOIN 查询？")

5. 架构篇：并发场景下的多用户隔离机制

当你准备将 Hermes Agent 接入 FastAPI、Discord Bot 或 Telegram 机器人时，多用户隔离是绕不开的话题。

Hermes 提供了两个层级的多用户隔离方案：

5.1 代码层级的软隔离 (Session ID)

在同一个 Python 进程中，如果你只是希望让模型能够分别记住不同用户的对话，你只需要为不同的用户请求分配不同的 session_id。

⚠️ 核心规则： AIAgent 实例维护着自身的对话历史、工具会话和迭代计数器，它不是线程安全的。因此，必须为每个并发任务或每个用户请求创建一个新的 AIAgent 实例。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import concurrent.futures
from run_agent import AIAgent

def handle_user_message(user_id: str, message: str):
    # 为每个并发请求实例化独立的 AIAgent 以保证线程安全
    agent = AIAgent(
        model="gpt-5.4-mini",
        provider="custom",
        base_url="https://api.your-proxy.com/v1",
        api_key="your-api-key-here",
        session_id=f"user_session_{user_id}",  # 动态 session_id 隔离不同用户记忆
        quiet_mode=True
    )
    return agent.chat(message)

# 模拟多用户并发请求
users_requests = {
    "u1001": "你好，我是用户A",
    "u1002": "你好，我是用户B"
}

with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
    # 并发执行
    futures = {
        executor.submit(handle_user_message, uid, msg): uid 
        for uid, msg in users_requests.items()
    }
    
    for future in concurrent.futures.as_completed(futures):
        uid = futures[future]
        print(f"用户 {uid} 的专属回复: {future.result()}")

5.2 物理层级的硬隔离 (Profiles)

如果你不仅需要隔离对话历史，还需要为不同用户配置完全不同的 API Key、不同的模型、不同的系统提示词（人设）、甚至不同的可用工具集，你需要使用 Hermes 的 Profiles（配置文件） 功能。

每一个 Profile 都拥有独立的 ~/.hermes/profiles/<name>/ 目录。

你可以通过 CLI 预先创建 Profile：

1
2

hermes profile create alice
hermes profile create bob

然后在 Python 代码中，你可以在初始化 AIAgent 之前，通过修改环境变量 HERMES_HOME 来让当前进程或 Agent 绑定到特定的 Profile 目录下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import os
from pathlib import Path
from run_agent import AIAgent

def run_agent_for_profile(profile_name: str, message: str):
    # 动态切换当前执行上下文的 HERMES_HOME 到指定的 profile 目录
    profile_dir = Path.home() / ".hermes" / "profiles" / profile_name
    os.environ["HERMES_HOME"] = str(profile_dir)
    
    # 此时初始化的 Agent 会自动读取对应 profile 目录下的 config.yaml, .env 和 state.db
    agent = AIAgent(
        quiet_mode=True
        # 不需要再传 model 和 key，它会自动从该用户的专属配置中读取
    )
    return agent.chat(message)

6. 实战集成示例 (Integration Examples)

6.1 FastAPI 接口端点

将 Hermes 包装成一个 HTTP API 服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

from fastapi import FastAPI
from pydantic import BaseModel
from run_agent import AIAgent

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "gpt-5.4-mini"

@app.post("/chat")
async def chat(request: ChatRequest):
    # 每次请求实例化一个全新无状态的 Agent
    agent = AIAgent(
        model=request.model,
        provider="custom",
        base_url="https://api.your-proxy.com/v1",
        api_key="your-api-key-here",
        quiet_mode=True,
        skip_context_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

6.2 CI/CD 自动化代码审查流水线

利用 Agent 在 CI/CD 流程中自动进行 Code Review：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#!/usr/bin/env python3
"""CI step: auto-review a PR diff."""
import subprocess
from run_agent import AIAgent

# 获取最新的代码变更
diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()

agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    quiet_mode=True,
    skip_context_files=True,
    skip_memory=True,
    disabled_toolsets=["terminal", "browser"], # CI 环境下关闭敏感工具
)

review = agent.chat(
    f"请审查以下 PR 的代码变更，检查是否存在 bug、安全漏洞或代码风格问题：\n\n{diff}"
)
print(review)

6.3 从零开发自定义工具

开发自定义工具非常简单，只需调用 tools.registry.registry.register 将其注册到全局系统中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

import json
from tools.registry import registry, tool_result
from run_agent import AIAgent

# 1. 编写业务逻辑函数
def get_weather(location: str) -> str:
    data = {"location": location, "weather": "晴朗", "temp": "25°C"}
    # 工具必须返回 JSON 字符串（可以通过自带的 tool_result 辅助函数包裹）
    return json.dumps(tool_result(success=True, data=data), ensure_ascii=False)

# 2. 编写符合 OpenAI Function Calling 标准的 Schema
WEATHER_SCHEMA = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "城市名称，如：北京、上海"}
            },
            "required": ["location"],
        },
    }
}

# 3. 将工具注册到系统中
registry.register(
    name="get_weather",           # 工具名称
    toolset="weather_tools",      # 归属的工具集名称
    schema=WEATHER_SCHEMA,        # 描述文件
    handler=lambda args, **kw: get_weather(args.get("location")), 
    emoji="🌤️"
)

# 4. 在 AIAgent 中启用你的自定义工具集
agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    enabled_toolsets=["weather_tools"],
    quiet_mode=False
)

print(agent.chat("今天北京的天气怎么样？"))

7. 高阶篇：复杂任务编排与子智能体委托 (Agent-to-Agent 通信)

当面对超大型任务（例如“帮我从头开发一个贪吃蛇游戏并运行测试”）时，单线程执行往往容易遇到上下文瓶颈。Hermes 支持一种受控的 A2A (Agent-to-Agent) 协作模式——即子智能体委托机制 (Subagent Delegation)。

当开启 delegate 工具集时，主 Agent 可以化身为“项目经理”，它会为不同的子任务创建隔离的 Child AIAgent 进行并行或串行的任务攻坚。

A2A 机制的核心特性：

• 上下文隔离：子 Agent 会获得全新的对话会话和专属任务 ID，主 Agent 的庞大上下文不会拖慢子 Agent 的执行速度。
• 防止递归失控：系统硬编码了最大委派深度（MAX_DEPTH = 2），即子 Agent 无法再创建孙 Agent，且被禁止向人类提问（clarify 工具被禁用），确保它们默默打工不打扰用户。
• 并行处理：主 Agent 可以一次性派发多个任务，系统会自动利用线程池并发运行多个子 Agent。

1
2
3
4
5
6
7
8
9
10
11

agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    enabled_toolsets=["delegate", "terminal", "file_tools"], 
    quiet_mode=False
)

# 主 Agent 发现任务复杂后，会自主调用 delegate 工具，通过 A2A 协议派生子 Agent 完成代码编写和测试
agent.chat("请帮我写一个 Python 贪吃蛇游戏，保存到 snake.py 中，然后运行并修复可能存在的 bug。")

此外，Hermes Agent 还可以接入 auxiliary_client.py 辅助客户端来支持视觉多模态识别，以及通过 cron/ 目录下的调度器实现自动化定时任务，这些都是其作为生产级 AI 框架的核心优势。

8. 前沿探索：支持标准 A2A Protocol (Agent2Agent)

最近，由 Linux 基金会主导的 A2A Protocol (Agent-to-Agent) 成为了跨框架智能体协作的开放标准。与前文提到的 Hermes 内部的 delegate（父子智能体委派）不同，标准的 A2A 协议允许 Hermes Agent 与完全不同的框架（如 LangGraph, CrewAI 等）构建的外部智能体进行去中心化的通信。

虽然目前 Hermes 官方暂未原生内置 A2A 协议，但得益于其高度可扩展的工具注册表（Tool Registry）和网关（Gateway）架构，将其作为一个插件接入是非常容易的！

概念验证 1：作为 A2A 发起方 (Caller)

如果你想让 Hermes 能够调用外部支持 A2A 协议的 Agent（例如一个专门用于金融分析的 LangGraph 智能体），你可以轻松地为其编写一个自定义工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

import json
from tools.registry import registry, tool_result
from run_agent import AIAgent

# 假设你已经安装了官方的 A2A Python SDK (pip install a2a-python)
# import a2a

def call_external_a2a_agent(agent_address: str, task_query: str) -> str:
    """通过 A2A 协议向外部智能体发送任务并等待结果"""
    print(f"正在通过 A2A 协议联系外部智能体 [{agent_address}]...")
    
    # --- 以下为伪代码，展示与 A2A SDK 的集成逻辑 ---
    # client = a2a.Client()
    # response = client.send_message(
    #     to=agent_address,
    #     content={"task": task_query}
    # )
    # result = response.get_result()
    # ---------------------------------------------
    
    # 模拟外部 Agent 的返回
    result = f"来自 {agent_address} 的分析结果：已完成关于 '{task_query}' 的任务。"
    return json.dumps(tool_result(success=True, data={"result": result}), ensure_ascii=False)

# 注册 A2A 通信工具
registry.register(
    name="call_a2a_agent",
    toolset="a2a_tools",
    schema={
        "type": "function",
        "function": {
            "name": "call_a2a_agent",
            "description": "通过标准 A2A 协议将特定领域的任务委派给外部智能体",
            "parameters": {
                "type": "object",
                "properties": {
                    "agent_address": {"type": "string", "description": "外部智能体的 A2A 寻址地址"},
                    "task_query": {"type": "string", "description": "需要外部智能体完成的任务详情"}
                },
                "required": ["agent_address", "task_query"],
            },
        }
    },
    handler=lambda args, **kw: call_external_a2a_agent(args.get("agent_address"), args.get("task_query")),
    emoji="📡"
)

# 启动支持 A2A 协议的 Hermes 主控 Agent
agent = AIAgent(
    model="gpt-5.4-mini",
    provider="custom",
    base_url="https://api.your-proxy.com/v1",
    api_key="your-api-key-here",
    enabled_toolsets=["a2a_tools", "web_search"],
    quiet_mode=False
)

agent.chat("我需要一份专业的市场分析报告。请通过 A2A 协议联系地址为 'a2a://finance-expert-agent' 的智能体，让它帮你生成报告，然后你再结合最新的网络搜索结果发给我。")

概念验证 2：作为 A2A 接收方 (Server)

除了主动调用其他 Agent，你也可以将 Hermes 包装成一个 A2A 协议的服务端，监听并处理来自外部框架（如 CrewAI 或 AutoGen）发送的 A2A 请求。这在 Hermes 的架构中相当于构建一个自定义的 Gateway Platform 适配器。

以下是最简单的伪代码实现思路，展示了如何监听 A2A 请求、将请求内容交给 Hermes AIAgent 处理，再将结果通过 A2A 协议返回：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

from run_agent import AIAgent

# 假设安装了官方的 A2A Python SDK (pip install a2a-python)
# import a2a

def handle_incoming_a2a_task(request):
    """处理外部 Agent 发送来的 A2A 请求"""
    print(f"收到来自 {request.sender} 的任务：{request.content['task']}")
    
    # 实例化一个 Hermes Agent 来处理该任务
    agent = AIAgent(
        model="gpt-5.4-mini",
        provider="custom",
        base_url="https://api.your-proxy.com/v1",
        api_key="your-api-key-here",
        quiet_mode=True,
        # 可以根据 request.sender 动态设置 session_id 以隔离不同 Agent 的记忆
        session_id=f"a2a_session_{request.sender}"
    )
    
    # 核心：将 A2A 请求转换为 Hermes 的内部聊天指令
    result = agent.chat(request.content["task"])
    
    # 将 Hermes 的回复通过 A2A 协议返回给发送方
    # return request.reply(content={"result": result})
    print(f"任务完成，回复给 {request.sender}：{result}")

def start_a2a_server():
    """启动 A2A 监听服务"""
    # client = a2a.Client(address="a2a://hermes-research-agent")
    # client.on_message(handle_incoming_a2a_task)
    # print("Hermes A2A 节点已启动，监听地址: a2a://hermes-research-agent")
    # client.start()
    pass

if __name__ == "__main__":
    start_a2a_server()

正如你所见，A2A 协议（用于 Agent 间通信）与 MCP 协议（用于 Agent 访问工具资源）是完美的互补组合。随着生态的成熟，你完全可以通过上述方式将 Hermes 接入到由无数异构 AI 智能体组成的“互联网”中！

结语

通过本教程，你已经掌握了如何使用 Python 库的方式调用 hermes-agent，从单次/多轮对话控制，到安全地进行并发处理和工具定制。它既可以作为你的本地终端 Copilot，也能轻易集成到 FastAPI 后端、Discord Bot 甚至自动化 CI/CD 流水线中！

引言

在 AI Agent 的长期交互中，记忆管理一直是个痛点。nanobot 的记忆机制建立在一个非常优雅的理念之上：记忆应该是鲜活的，但不应该是混乱的（Memory should feel alive, but it should not feel chaotic）。

好的记忆不应该是一堆笔记的无序堆砌，而是一个安静的注意力系统。它能敏锐地注意到什么值得保留，优雅地放弃不再需要的内容，并将经历转化为平静、持久和有用的知识。本文将结合 nanobot 的实际代码（主要集中在 nanobot/agent/memory.py），深入拆解这套记忆系统的设计与实现。

记忆的分层架构：各司其职的存储介质

nanobot 并没有把所有记忆都塞进一个巨大的文件里，而是根据不同类型记忆的生命周期和用途，将其拆分到了不同的层级和文件中：

1. 短期记忆 (Short-term)：
   • 存在于内存中的 session.messages。
   • 保存当前正在进行的、鲜活的对话上下文。
2. 中期记忆 (Mid-term)：
   • 存储于 memory/history.jsonl。
   • 这是一个只追加（Append-only）的运行日志，用于记录被压缩后的前期对话流。
3. 长期记忆 (Long-term)：
   • 持久化的 Markdown 知识文件，分为三个维度：
     • SOUL.md：定义 Bot 的人格、行为模式和沟通语气。
     • USER.md：记录用户的身份、偏好和习惯。
     • memory/MEMORY.md：记录项目上下文、长期事实和重要事件。

这种分层设计使得系统在当前对话中保持轻量级和高响应速度，同时在长期使用中具备反思和知识积累的能力。值得一提的是，长期记忆文件由底层的 GitStore 自动进行版本控制，确保记忆的演变可追溯、可回滚。

核心组件与大模型 Prompt 深度解析：从流转到沉淀

整个记忆系统的核心代码位于 nanobot/agent/memory.py 中，主要由三个类构成：MemoryStore（底层存储）、Consolidator（会话压缩）和 Dream（知识提炼）。大模型在其中扮演了关键的“记忆提炼器”角色，其行为由几个精心设计的 Prompt 控制。

1. MemoryStore：纯文件 I/O 与数据结构

MemoryStore 负责底层的文件读写、游标管理和 JSONL 格式化。

关于 history.jsonl 的设计哲学：
在早期的版本中，历史记录存储在 HISTORY.md 中，这虽然适合人类阅读，但作为系统的操作基底（operational substrate）却过于脆弱。nanobot 将其迁移到了 history.jsonl，带来了以下优势：

• 稳定的增量游标（cursor-based）。
• 更安全的机器解析和批量处理（easier batching）。
• 清晰的边界：将“原始历史”与“提炼后的知识”彻底分开。

代码中通过 append_history(entry) 每次生成一个自增的 cursor，并写入带有时间戳的 JSON 记录：

1
2
3
4
5
6
7
8
9

def append_history(self, entry: str) -> int:
    cursor = self._next_cursor()
    ts = datetime.now().strftime("%Y-%m-%d %H:%M")
    record = {"cursor": cursor, "timestamp": ts, "content": strip_think(entry.rstrip()) or entry.rstrip()}
    with open(self.history_file, "a", encoding="utf-8") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")
    # 更新游标状态
    self._cursor_file.write_text(str(cursor), encoding="utf-8")
    return cursor

2. Consolidator：防止上下文爆炸的“压缩器”

随着对话的进行，session.messages 会越来越长，最终对大模型的 Context Window 造成压力。Consolidator 是一个轻量级的、基于 Token 预算触发的合并器。

• 触发机制：maybe_consolidate_by_tokens 方法会实时估算当前会话的 Token 数。如果超过了安全预算（Context Window - 最大生成 Token - 安全缓冲区），就会触发合并逻辑。
• 安全切分：它不会生硬地截断对话，而是通过 pick_consolidation_boundary 寻找一个合适的用户发言（User Turn）作为切分边界。
• 大模型摘要 (Archive Prompt)：将切分出的旧对话通过大模型进行摘要提取，并调用 archive() 将摘要追加到 history.jsonl 中。这里使用的 Prompt (consolidator_archive.md) 非常强调实用性和高优排序：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  Extract key facts from this conversation. Only output items matching these categories, skip everything else: - User facts: personal info, preferences, stated opinions, habits - Decisions: choices made, conclusions reached - Solutions: working approaches discovered through trial and error, especially non-obvious methods that succeeded after failed attempts - Events: plans, deadlines, notable occurrences - Preferences: communication style, tool preferences Priority: user corrections and preferences > solutions > decisions > events > environment facts. The most valuable memory prevents the user from having to repeat themselves. Skip: code patterns derivable from source, git history, or anything already captured in existing memory. Output as concise bullet points, one fact per line. No preamble, no commentary. If nothing noteworthy happened, output: (nothing)

  解析：
  • 严格过滤：明确指出了需要保留的 5 种事实，其余全部丢弃。
  • 优先级定义：用户的纠正与偏好 > 解决方案 > 决策 > 事件 > 环境事实。核心理念是：“最有价值的记忆是防止用户重复自己的话”。
  • 降噪机制：明确要求跳过可以通过源码或 Git 历史推导的代码模式。
• 优雅降级：如果 LLM 调用失败，系统会触发 raw_archive 机制，直接将原始消息以 [RAW] 标签 Dump 进历史文件，保证数据不丢失。

3. Dream：从历史中提炼知识的“盗梦空间”

如果说 Consolidator 是为了应对当下的生存压力（Context Window），那么 Dream 就是为了长远的知识沉淀。这是一个重型的、可通过定时任务或手动命令（/dream）触发的记忆处理器。

Dream 类采用了非常工程化的两阶段（Two-phase）处理模式，这反映在它的两个不同的 Prompt 设计上：

阶段一：分析提炼 (Phase 1)

• 读取自上次 .dream_cursor 以来的 history.jsonl 未处理条目。
• 将这段历史记录，连同当前的 SOUL.md、USER.md、MEMORY.md 内容一起发给大模型。
• 分析 Prompt (dream_phase1.md)：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  Compare conversation history against current memory files. Output one line per finding: [FILE] atomic fact or change description Files: USER (identity, preferences, habits), SOUL (bot behavior, tone), MEMORY (knowledge, project context, tool patterns) Rules: - Only new or conflicting information — skip duplicates and ephemera - Prefer atomic facts: "has a cat named Luna" not "discussed pet care" - Corrections: [USER] location is Tokyo, not Osaka - Also capture confirmed approaches: if the user validated a non-obvious choice, note it If nothing needs updating: [SKIP] no new information

  解析：
  • 原子化原则：强制要求模型输出具体的事实（如 “has a cat named Luna”），而不是宽泛的总结（如 “discussed pet care”）。
  • 变更发现：不仅提取新信息，还要求识别与现有记忆冲突的信息并进行纠正。
  • 固定输出格式：要求以 [FILE] 事实描述 的格式输出，为阶段二的精准编辑提供清晰的指令。

阶段二：增量编辑 (Phase 2)

• 将阶段一的分析结果交由一个专用的 AgentRunner 处理。
• 这个 Agent 被赋予了两个核心工具：ReadFileTool 和 EditFileTool。
• 编辑 Prompt (dream_phase2.md)：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  Update memory files based on the analysis below. ## Quality standards - Every line must carry standalone value — no filler - Concise bullet points under clear headers - Remove outdated or contradicted information ## Editing - File contents provided below — edit directly, no read_file needed - Batch changes to the same file into one edit_file call - Surgical edits only — never rewrite entire files - Do NOT overwrite correct entries — only add, update, or remove - If nothing to update, stop without calling tools

  解析：
  • 外科手术式编辑 (Surgical edits only)：这是最核心的指导原则。它明确禁止 LLM 覆写整个文件，而是要求进行局部增删改。这极大地降低了破坏现有知识结构的风险。
  • 优化工具调用：提示词中告知 LLM 文件内容已经提供，不需要调用 read_file，并且要求将对同一个文件的修改合并到一次 edit_file 调用中，提升了处理效率。

Git 自动版本控制

当 Dream 完成编辑后，不仅会推进 .dream_cursor 游标，还会通过 GitStore.auto_commit() 自动生成一次 Git 提交：

1
2
3

if changelog and self.store.git.is_initialized():
    ts = batch[-1]["timestamp"]
    sha = self.store.git.auto_commit(f"dream: {ts}, {len(changelog)} change(s)")

总结与启示

nanobot 的记忆机制完美诠释了“结构与意义的分离”：

• history.jsonl 负责结构（记录发生了什么）。
• SOUL.md, USER.md, MEMORY.md 负责意义（沉淀留下了什么）。

通过 Consolidator 实现对话流的实时无损压缩，通过 Dream 机制实现异步的、增量的知识提炼，并结合 Git 工具链提供强大的版本控制与容错能力。这套机制避免了传统记忆管理中“上下文臃肿”和“信息被过度覆盖”的顽疾，为构建长期陪伴型 AI Agent 提供了一个极其优秀的工程参考范式。

在多智能体（Multi-Agent）架构中，主智能体如何理解用户意图并动态派发任务给子智能体，是一个非常核心的设计。本文将以 Nanobot Agent 为例，详细拆解当用户在终端输入交互指令：“请使用子智能体调研一下hermes agent” 时，系统在底层是如何一步步流转的。

1. 接收输入：构造 InboundMessage

一切的起点始于用户在交互界面（例如 CLI 终端）输入文本。Nanobot 使用统一的事件总线（Message Bus）来解耦各个渠道和核心 Agent 逻辑。

当用户敲下回车后，CLI 渠道会捕获这段文本，并将其封装为一个标准化的 InboundMessage 对象。这个数据类定义在 events.py 中：

1
2
3
4
5
6
7

@dataclass
class InboundMessage:
    channel: str  # 例如 "cli"
    sender_id: str  # 用户标识，例如 "user"
    chat_id: str  # 会话标识，例如 "direct"
    content: str  # 消息文本内容
    # ...

在 CLI 交互模式下，具体的构造逻辑位于 commands.py 中：

1
2
3
4
5
6
7

await bus.publish_inbound(InboundMessage(
    channel=cli_channel,
    sender_id="user",
    chat_id=cli_chat_id,
    content=user_input,  # 即 "请使用子智能体调研一下hermes agent"
    metadata={"_wants_stream": True},
))

随后，该消息被推入消息总线，等待主 Agent 循环消费。

2. 消息路由：主循环与会话加锁

主 Agent 在后台运行着一个监听循环，即 loop.py 中的 run() 方法。这个方法是整个机器人响应系统的心脏，它采用了异步和非阻塞的设计模式。我们一步步解析 run() 到底做了什么：

run() 方法的执行拆解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

async def run(self) -> None:
    self._running = True
    await self._connect_mcp()  # 1. 启动前初始化 MCP (Model Context Protocol) 插件连接
    logger.info("Agent loop started")

    while self._running:
        try:
            # 2. 带超时的消息轮询
            msg = await asyncio.wait_for(self.bus.consume_inbound(), timeout=1.0)
        except asyncio.TimeoutError:
            continue
        # ... 省略异常处理 ...

        raw = msg.content.strip()
        # 3. 优先级命令拦截
        if self.commands.is_priority(raw):
            ctx = CommandContext(msg=msg, session=None, key=msg.session_key, raw=raw, loop=self)
            result = await self.commands.dispatch_priority(ctx)
            if result:
                await self.bus.publish_outbound(result)
            continue
        
        # 4. 普通消息的异步派发
        task = asyncio.create_task(self._dispatch(msg))
        self._active_tasks.setdefault(msg.session_key, []).append(task)
        task.add_done_callback(...)

1. MCP 插件初始化：在进入死循环之前，先通过 _connect_mcp() 建立与配置的外部插件（如本地开发工具链、数据库查询接口等）的连接。
2. 带超时的非阻塞拉取：通过 asyncio.wait_for(..., timeout=1.0) 从总线 consume_inbound() 获取消息。设置 1 秒超时是为了让循环能周期性“醒来”检查 self._running 的状态，从而支持优雅的平滑退出（Graceful Shutdown）。
3. 优先指令拦截（Priority Commands）：如果收到像 /stop 这样紧急干预指令，self.commands.is_priority(raw) 会返回 True。此时直接 await self.commands.dispatch_priority(ctx) 并在当前协程同步执行完毕，它能立即终止对应会话下的所有活跃任务和子智能体。这正是为什么即便机器人还在长篇大论地生成或执行耗时任务，你依然可以随时用 /stop 叫停它。
4. 异步任务派发（Task Dispatch）：对于绝大多数普通对话消息（包括我们的“请使用子智能体…”），run() 方法不会在原地等待它执行完。而是通过 asyncio.create_task(self._dispatch(msg)) 创建一个后台任务，并将其注册到该会话的活跃任务字典 _active_tasks 中，以便后续可能被 /stop 取消。

通过异步派发，普通消息进入到 _dispatch(msg) 中。在这里，系统会根据 session_key 获取一把异步锁：

1
2
3
4

lock = self._session_locks.setdefault(msg.session_key, asyncio.Lock())
async with lock, gate:
    # ...
    response = await self._process_message(msg, ...)

这保证了同一个用户的同一个会话是串行处理的，而不同用户的会话可以并发处理。随后消息进入 _process_message 方法。

3. 意图解析与工具选择：LLM Function Calling

在 _process_message 中，Nanobot 并没有硬编码写死 if "子智能体" in text 的判断逻辑。相反，它构建了上下文后，直接将消息丢给了大语言模型（LLM）。

3.1 主智能体的 Prompt 构造

在每次请求大模型前，Nanobot 都会通过 ContextBuilder.build_messages()（位于 context.py）来组装发给 LLM 的上下文，其中包括：

1. System Prompt：由 build_system_prompt() 动态生成，包含机器人的人设（identity.md）、用户的自定义规则（AGENTS.md, SOUL.md 等）、以及当前已加载的 Skills 列表。
2. Runtime Context：通过 _build_runtime_context() 注入当前系统时间、渠道来源等元数据。
3. 对话历史：从数据库加载该 Session 的上下文记录。
4. 当前输入：即用户输入的“请使用子智能体调研一下hermes agent”。

3.2 发现工具：SpawnTool Schema

大模型之所以“知道”它可以使用子智能体，是因为主智能体在请求时携带了所有可用工具的 JSON Schema 定义。

主智能体在初始化时，将 SpawnTool 注册进了工具集（见 loop.py）。在与 LLM 交互时（runner.py 的 _request_model 方法），Nanobot 会通过 self.tools.get_definitions() 获取工具定义。

SpawnTool 的描述位于 spawn.py。最终转换为 OpenAI 标准的 Function Schema 发送给大模型，其结构大致如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "type": "function",
  "function": {
    "name": "spawn",
    "description": "Spawn a subagent to handle a task in the background. Use this for complex or time-consuming tasks that can run independently...",
    "parameters": {
      "type": "object",
      "properties": {
        "task": {"type": "string", "description": "The task for the subagent to complete"},
        "label": {"type": "string", "description": "Optional short label for the task (for display)"}
      },
      "required": ["task"]
    }
  }
}

由于用户的输入明确要求“请使用子智能体…”，LLM 读取到 spawn 工具的 description 匹配该意图，于是决定触发 Function Calling，输出类似 {"name": "spawn", "arguments": {"task": "调研一下hermes agent"}} 的指令。

4. 派发任务：SpawnTool 与 SubagentManager

当 AgentRunner 接收到 LLM 返回的 Tool Call 请求后，会执行对应的工具代码。对于 spawn 工具，其执行体 spawn.py 仅仅是一个简单的转发层：

1
2
3
4
5
6
7
8

async def execute(self, task: str, label: str | None = None, **kwargs: Any) -> str:
    return await self._manager.spawn(
        task=task,
        label=label,
        origin_channel=self._origin_channel,
        origin_chat_id=self._origin_chat_id,
        session_key=self._session_key,
    )

SubagentManager.spawn 方法（subagent.py）接管后，会做两件事：

1. 启动后台任务：通过 asyncio.create_task(self._run_subagent(...)) 将耗时的调研任务丢到后台执行。
2. 立即回复主模型：返回类似 "Subagent [...] started (id: ...). I'll notify you when it completes." 的字符串。这使得主智能体能立刻给用户一个响应，告知任务已在后台开启，而不必让用户在此处干等。

5. 子智能体执行：专用的运行沙盒

后台的 _run_subagent 任务（subagent.py）代表了子智能体的实际运行过程。它的设计有几个关键特点：

• 隔离的工具集：它创建了一个全新的 ToolRegistry，包含了文件读写、Grep/Glob 检索，甚至 Web 搜索工具。但刻意去掉了发消息给用户的工具和再次生成子智能体的 spawn 工具，以防无限递归。

• 独立的 System Prompt：在调用 LLM 之前，系统通过 self._build_subagent_prompt() 方法为子智能体构造了专属的人设。在 subagent_system.md 模板中，系统提示词明确规定：

  1 2 3 4 5 6 7 8 9

  # Subagent {{ time_ctx }} You are a subagent spawned by the main agent to complete a specific task. Stay focused on the assigned task. Your final response will be reported back to the main agent. ## Workspace {{ workspace }}

  这段提示词极大地压缩了主智能体复杂的闲聊属性，使得子智能体仅仅作为一个纯粹的“打工人”，去执行传入的 task 参数内容（即 {"role": "user", "content": "调研一下hermes agent"}）。

• 有限的迭代：它使用独立的 AgentRunner 跑一个上限为 15 轮的小迭代，防止子智能体在遇到死胡同时无限制地消耗 Tokens。

在这个环节，子智能体带着上述提示词，会在代码库里检索 hermes agent，收集到相关结论后生成内部的总结报告。

6. 结果回注：巧妙的 system 消息通道

子智能体执行完毕后，并不能直接调用 API 发消息给用户。为了将结果带回给主智能体，它调用了 _announce_result 方法（subagent.py）。

这里使用了非常巧妙的事件驱动设计：将结果伪装成一条来自 system 渠道的 InboundMessage 重新发布到消息总线上：

1
2
3
4
5
6
7

msg = InboundMessage(
    channel="system",
    sender_id="subagent",
    chat_id=f"{origin['channel']}:{origin['chat_id']}",
    content=announce_content,
)
await self.bus.publish_inbound(msg)

announce_content 的渲染模板 subagent_announce.md 中还包含了一条隐藏指令：“Summarize this naturally for the user. Keep it brief… Do not mention technical details like ‘subagent’ or task IDs.”。

7. 二次转述：主智能体的最终回应

这条带有系统通知的 InboundMessage 再次进入了主循环的 _process_message。

在 loop.py 的 system 消息专用分支中，系统会从 chat_id 中解析出原始的 CLI 会话。由于消息的发送者是 subagent，系统会将其标记为 current_role = "assistant"，代表这是助手自身完成的后台任务结果：

1
2
3

current_role = "assistant" if msg.sender_id == "subagent" else "user"
messages = self.context.build_messages(..., current_role=current_role)
final_content, _, all_msgs = await self._run_agent_loop(messages, ...)

带着之前历史上下文和这份子智能体的详细报告，主智能体（LLM）再次被唤醒。根据模板中的隐藏指令，LLM 会将繁杂的技术报告转化为对用户友好的自然语言摘要，最终封装为 OutboundMessage 返回给 CLI 渠道展示在屏幕上。

总结

Nanobot 对“使用子智能体”这一请求的处理，优雅地展示了现代 Agent 框架的解耦美学：

1. 渠道层：负责标准化 InboundMessage。
2. 意图层：不靠正则匹配，全权交由 LLM Function Calling 决策。
3. 执行层：后台异步调度，主从沙盒隔离。
4. 闭环层：利用事件总线回注系统消息，触发主智能体二次总结。

这种基于事件总线和工具抽象的机制，赋予了系统极高的扩展性。

导语：Nanobot 不仅仅是一个命令行聊天工具，它底层是一个具备“全网搜索、网页抓取、文件操作、Shell 执行”的强大智能体框架。通过 Python SDK，可以将这套强大的 Agent 能力嵌入到任何 Python 业务中。

本文将从最基础的单次对话开始，逐步解锁多轮记忆、工作区接管、内置工具链驱动，最终构建一个高并发的 Web API。

一、 初级篇：环境搭建与日志清理

在最基础的场景中，我们只需要让 Nanobot 跑起来并回答问题。为了避免框架内部冗长的 INFO/DEBUG 日志污染你的终端，我们可以通过 loguru 屏蔽底层日志。

实战代码 1：干净的单次问答

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import asyncio
from loguru import logger
from nanobot import Nanobot

# 关闭 nanobot 框架内部的日志输出，让终端保持清爽
logger.disable("nanobot")

async def main():
    bot = Nanobot.from_config()
    
    print("正在向 Nanobot 提问...")
    result = await bot.run("请用一句话介绍 Python。")
    
    print(f"🤖 回答: {result.content}")

if __name__ == "__main__":
    asyncio.run(main())

二、 中级篇 1：构建 CLI 交互式多轮对话

单个问题往往不够，我们需要一个可以持续对话的控制台程序。要让 Nanobot 记住上下文（即实现“多轮对话”），核心在于复用同一个 session_key。

实战代码 2：打造你自己的 ChatGPT 终端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

import asyncio
from loguru import logger
from nanobot import Nanobot

logger.disable("nanobot")

async def main():
    bot = Nanobot.from_config()
    
    print("========================================")
    print("🤖 Nanobot CLI 模式已启动！(输入 'exit' 退出)")
    print("========================================")
    
    # 设定一个固定的 session_key，这是保持多轮对话记忆的关键
    SESSION_ID = "my-cli-session"
    
    while True:
        try:
            user_input = input("\n🧑 你: ").strip()
        except (KeyboardInterrupt, EOFError):
            break
            
        if user_input.lower() in ['exit', 'quit']:
            break
        if not user_input:
            continue
            
        print("🤖 思考中...", end="\r")
        result = await bot.run(user_input, session_key=SESSION_ID)
        
        print(" " * 20, end="\r") 
        print(f"🤖 Nanobot: {result.content}")
        
        if result.tools_used:
            print(f"   [🔧 辅助操作: 使用了 {', '.join(result.tools_used)} 工具]")

if __name__ == "__main__":
    asyncio.run(main())

三、 中级篇 2：工作区接管与多用户隔离

在企业级开发中（例如构建一个面向多用户的微信机器人），所有用户不能共享同一个对话历史，同时 Agent 可能需要针对特定目录下的代码文件进行操作。

实战代码 3：多用户聊天模拟器

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import asyncio
from loguru import logger
from nanobot import Nanobot

logger.disable("nanobot")

async def main():
    # 强制指定 Agent 工作的根目录，文件读写等工具将被限制在此目录下
    bot = Nanobot.from_config(workspace="/var/www/my_project")
    
    print("--- 👱‍♀️ Alice 的会话 ---")
    await bot.run("你好，我是前端开发 Alice", session_key="user-alice")
    res_alice = await bot.run("你还记得我是做什么的吗？", session_key="user-alice")
    print(f"Alice 收到回答: {res_alice.content}") 
    
    print("\n--- 👨‍🦱 Bob 的会话 ---")
    # Bob 属于另一个 session_key，无法访问 Alice 的记忆
    res_bob = await bot.run("你还记得我是做什么的吗？", session_key="user-bob")
    print(f"Bob 收到回答: {res_bob.content}") 

if __name__ == "__main__":
    asyncio.run(main())

四、 高级篇 1：释放 Nanobot 的内置工具链

Nanobot 底层不仅是一个聊天模型，它还内置了强大的工具链：

1. 网络工具：web_search（全网搜索）、web_fetch（网页提取为 Markdown）。
2. 系统工具：exec（受限 Shell 执行）、read_file / write_file / edit_file / grep / glob 等。

你可以直接用自然语言向它下达复合指令，它会自动规划并调用这些工具。

实战代码 4：自动网页抓取与文件分析助手

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import asyncio
from loguru import logger
from nanobot import Nanobot

logger.disable("nanobot")

async def main():
    # 设定一个测试工作区
    bot = Nanobot.from_config(workspace="./research_workspace")
    
    task_prompt = """
    1. 请帮我搜索一下 '2024年诺贝尔物理学奖得主是谁'。
    2. 找到确切结果后，将他们的名字和主要贡献总结成一段话。
    3. 将这段话保存到当前工作区的 'nobel_2024.md' 文件中。
    """
    
    print("🤖 正在执行复杂的网络检索与文件写入任务，请稍候...")
    result = await bot.run(task_prompt, session_key="research-task")
    
    print("\n✅ 任务完成！")
    print(f"最终汇报:\n{result.content}")
    print(f"\n🛠️ 期间 Agent 自主调用的工具列表: {result.tools_used}")

if __name__ == "__main__":
    asyncio.run(main())

在这个例子中，Agent 会自动调用 web_search 查找新闻，然后调用 write_file 写入文件，你无需编写任何爬虫或文件 IO 代码！

五、 高级篇 2：利用 Hooks 实现流式输出与安全审计

SDK 最强大的特性是 Hooks（钩子）。它允许你在不修改 Nanobot 核心代码的情况下，监控、拦截 Agent 的行为。我们可以利用 on_stream 钩子，给前面的 CLI 对话加上流式打字机效果。

实战代码 5：支持流式输出与审计的高级终端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

import sys
import asyncio
from loguru import logger
from nanobot import Nanobot
from nanobot.agent import AgentHook, AgentHookContext

logger.disable("nanobot")

# 1. 流式输出 Hook：捕获每个 token 并实时打印
class StreamingHook(AgentHook):
    def on_stream(self, ctx: AgentHookContext, delta: str) -> None:
        sys.stdout.write(delta)
        sys.stdout.flush()

    def on_stream_end(self, ctx: AgentHookContext) -> None:
        sys.stdout.write("\n")

# 2. 审计 Hook：记录所有将要执行的工具操作
class AuditHook(AgentHook):
    async def before_execute_tools(self, ctx: AgentHookContext) -> None:
        for tc in ctx.tool_calls:
            print(f"\n⚠️ [安全审计] 拦截到 Agent 尝试调用工具: {tc.name} ({tc.arguments})")

async def main():
    bot = Nanobot.from_config()
    print("🤖 高级流式终端已启动！请提问：")
    
    # 组合传入多个 Hook
    hooks = [StreamingHook(), AuditHook()]
    
    while True:
        user_input = input("\n🧑 你: ").strip()
        if not user_input: continue
            
        print("🤖 Nanobot: ", end="")
        
        # 运行并传入 hooks，Bot 的回答将通过 StreamingHook 实时打印
        await bot.run(user_input, session_key="stream-session", hooks=hooks)

if __name__ == "__main__":
    asyncio.run(main())

六、 终极实战：构建一个基于 FastAPI 的智能 Agent API

将上述能力综合起来，我们可以将其封装成一个标准的 Web 后端 API。供前端、小程序或客户端调用。

实战代码 6：结合 FastAPI 构建高并发后端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# 依赖安装: pip install fastapi uvicorn pydantic
import time
from fastapi import FastAPI, Header
from pydantic import BaseModel
from loguru import logger
from nanobot import Nanobot
from nanobot.agent import AgentHook, AgentHookContext

logger.disable("nanobot")

app = FastAPI()

# 全局单例加载 Bot
bot = Nanobot.from_config(workspace="./api_workspace")

# 自定义性能监控 Hook
class TimingHook(AgentHook):
    async def before_iteration(self, ctx: AgentHookContext) -> None:
        ctx.metadata["_t0"] = time.time()

    async def after_iteration(self, ctx: AgentHookContext, response) -> None:
        elapsed = time.time() - ctx.metadata.get("_t0", 0)
        print(f"[监控] LLM 思考耗时: {elapsed:.2f}s")

class ChatRequest(BaseModel):
    message: str

@app.post("/api/v1/agent/chat")
async def chat_endpoint(request: ChatRequest, user_id: str = Header(..., alias="X-User-Id")):
    """
    处理对话请求，使用 X-User-Id 请求头进行会话隔离
    """
    session_key = f"web_session_{user_id}"
    
    result = await bot.run(
        request.message,
        session_key=session_key,
        hooks=[TimingHook()]
    )
    
    return {
        "status": "success",
        "user_id": user_id,
        "reply": result.content,
        "tools_used": result.tools_used
    }

# 启动命令: uvicorn main:app --host 0.0.0.0 --port 8000

七、 终极硬核篇：通过底层消息系统发送图片附件 (多模态)

在 Nanobot 的设计中，高层的 bot.run(message) 是为了纯文本对话设计的便捷接口。如果你在做深度的 SDK 集成（例如将 Nanobot 接入微信、企业内部 IM），当用户直接发来一张图片时，你需要构造底层的 InboundMessage 并通过底层的消息处理方法交由 Agent 分析。

Agent 在处理带有 media（附件）的消息时，会自动读取该路径的图片，将其转换为大模型支持的视觉输入块（Base64），从而让 Agent 具备“看图说话”的能力。

实战代码 7：模拟 IM 机器人接收并分析图片

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import asyncio
from loguru import logger
from nanobot import Nanobot
from nanobot.bus.events import InboundMessage

logger.disable("nanobot")

async def main():
    bot = Nanobot.from_config()
    
    # 1. 构造一条底层的 InboundMessage
    # 假设这是从微信或 Slack 接收到的消息和下载到本地的图片
    msg = InboundMessage(
        channel="wechat",          # 来源渠道
        sender_id="user_10086",    # 用户 ID
        chat_id="chat_001",        # 会话 ID
        content="请帮我分析一下这张架构图里有几个核心模块？",
        media=["/absolute/path/to/architecture_diagram.png"]  # 图片的绝对路径
    )
    
    print("📸 正在将图片和问题发送给 Nanobot...")
    
    # 2. 绕过 bot.run()，直接调用底层的 _process_message 处理多模态消息
    # 这样可以同步等待结果返回，而不必去处理复杂的异步总线队列 (bus)
    session_key = f"im_session_{msg.sender_id}"
    result = await bot._loop._process_message(msg, session_key=session_key)
    
    print("\n✅ 分析完成！")
    print(f"🤖 回答:\n{result.content}")

if __name__ == "__main__":
    asyncio.run(main())

🦞 龙虾问数 (DataClaw)

释放你的数据潜能，让分析像养龙虾一样简单爽快！ 🌊📊
龙虾问数 (DataClaw) 是一个智能的、AI 驱动的数据分析平台。通过自然语言与你的数据对话，瞬间生成可视化图表，轻松搭建仪表盘——从此告别繁琐的 SQL 语句！

✨ 为什么选择龙虾问数？

受够了为了画个简单的柱状图而写半天复杂的 SQL 语句吗？龙虾问数就是你的私人数据科学家。借助强大的大语言模型 (LLM) 和智能 Agent 工作流，它能将你的自然语言提问精准转化为数据库查询，提取数据，并即时渲染出美观的可视化图表。

无论你是要查询庞大的 Supabase/PostgreSQL 数据库，还是随手丢进一个 CSV 文件，龙虾问数都能轻松拿捏！🚀

🌟 核心特性

• 🗣️ 自然语言转 SQL: 用大白话提问！它能理解你的数据表结构，生成准确的 SQL，甚至在报错时进行自我纠正 (Self-correction)。
• 📈 即时数据可视化: 拒绝枯燥的生肉表格，根据数据特征自动生成交互式图表。
• 🗂️ 动态多数据源: 无缝连接 PostgreSQL、Supabase，以及本地 CSV/Excel 文件上传解析。
• 🧠 灵活的模型接入: 原生集成 LiteLLM，支持随插随用 OpenAI、DeepSeek、智谱、通义千问 (DashScope)、火山引擎或任何兼容的 LLM 提供商。
• 🛠️ 强大的 Agent 技能拓展: 基于核心 nanobot框架（OpenClaw的精简版）构建。支持通过斜杠命令 (/) 快速调用自定义工具 (Skills)，完美贴合特定业务逻辑。
• 📊 可定制仪表盘 (Dashboard): 一键将对话中生成的图表固定到看板，拖拽布局，随时查看核心指标。

🏗️ 项目架构

DataClaw 的架构主要分为三只“大钳子”：

1. frontend/ 🎨: 闪亮的外壳。基于 React 19、Vite、TailwindCSS 和 Zustand 构建。拥有类似微信/ChatGPT的对话界面、支持流式思考过程渲染以及交互式图表展示。
2. backend/ ⚙️: 强健的肌肉。一个 FastAPI 后端服务，负责管理项目、数据源连接、用户会话持久化以及作为 API 网关。
3. nanobot/ 🧠: 智慧的大脑。核心的 AI Agent 框架，负责处理意图路由、NL2SQL 转换、Schema 缓存管理以及与 LLM 的底层交互。

🚀 快速开始

准备好大显身手了吗？让我们把龙虾问数在你的本地跑起来！

1. 后端服务启动 🐍

请确保你已安装 Python 3.10 或以上版本。

1
2
3
4
5
6
7
8
9
10

cd backend
# 创建虚拟环境（可选但强烈建议）
python -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动 FastAPI 服务器
uvicorn app.main:app --reload --port 8000

提示：请确保 nanobot 核心库已根据项目工作区的要求正确链接或以可编辑模式 (editable mode) 安装。

2. 前端服务启动 ⚛️

请确保你已安装 Node.js 18 或以上版本。

1
2
3
4
5
6

cd frontend
# 安装依赖
npm install

# 启动 Vite 开发服务器
npm run dev

3. 初始账号配置 👤

系统首次注册的用户将自动成为管理员。您可以在登录页面直接点击“注册”按钮创建您的管理员账号（例如：用户名 admin，密码 admin），随后即可登录并管理项目、数据源和用户。

🔌 数据源配置说明

DataClaw 支持连接多种类型的数据源，以满足不同场景的分析需求。你可以在界面的 Data Sources 菜单中点击 + 新建并配置它们。以下是常见数据源的详细接入指南：

🤝 参与贡献

有个好点子？发现了一个 Bug？非常欢迎你的加入！随时可以提交 Issue 或 Pull Request。让我们一起让数据分析变得更加有趣！

💖 特别鸣谢

DataClaw 的开发深受以下优秀开源项目的启发，特此致谢：

• WrenAI: 强大的 Text-to-SQL 解决方案，其架构和思路给了我们很大的启发。
• Aix-DB: 在智能数据分析和交互式体验方面提供了极好的参考。

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

直到我遇到了 nanobot。

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

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

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

0在这里
1在这里
2在这里

一夫当关

前面是看了“怎样只聊一句”，现在看看“网关模式”做了啥。

具体流程

nanobot gateway 是 Nanobot 的核心后台服务进程。简单来说，它就像一个不知疲倦的“接线员”兼“大脑”，负责连接外部世界（如 Telegram/微信）、管理内部任务（如定时提醒），并指挥 AI（Agent）进行思考和回复。

以下是 nanobot gateway 启动和运行的详细步骤解析：

第一阶段：初始化 (Initialization)

当你运行 nanobot gateway 命令时，系统会按顺序完成以下准备工作：

1. 加载配置 (load_config)：读取你的 ~/.nanobot/config.json 配置文件，确定要启用哪些功能。
2. 创建消息总线 (MessageBus)：这是一个内部的通信管道，用于在“接收消息的渠道”和“处理消息的 Agent”之间传递数据。
3. 准备大脑 (AgentLoop)：初始化 AI 核心循环。它加载了 LLM 提供商（如 OpenAI/Claude）、工具集（搜索、文件操作等）以及记忆管理器。
4. 准备定时器 (CronService & HeartbeatService)：
   • Cron: 加载保存的定时任务（如“每天早上 8 点提醒我看新闻”）。
   • Heartbeat: 设置心跳机制（默认每 30 分钟），用于自我保活或周期性自检。
5. 准备渠道 (ChannelManager)：根据配置初始化外部通信渠道（如 Telegram, WhatsApp, Slack 等）。

这个地方与之前的“只聊一句”又有很大差别，引入了新概念。

SessionManager

SessionManager 类是 Nanobot 用来管理聊天会话（Conversation Sessions）的核心组件。它的主要职责是持久化存储和检索用户与机器人之间的聊天记录。

它通过管理 Session 对象来实现这一功能，每个 Session 代表一个独立的对话上下文（例如你和机器人在 Telegram 上的私聊，或者你在命令行里的即兴对话）。

核心功能

1. 会话存储 (Storage)

   • 位置: 所有会话都保存在 ~/.nanobot/sessions/ 目录下。
   • 格式: 采用 JSONL (JSON Lines) 格式。
     • 文件名通常是 channel_chatid.jsonl（例如 telegram_123456789.jsonl）。
     • 文件的第一行始终是元数据 (Metadata)，包含创建时间、更新时间等。
     • 后续每一行代表一条消息 (Message)，包含角色（user/assistant）、内容、时间戳等。
   • 优点: JSONL 格式允许追加写入（Append-only），性能好且易于阅读和修复。

2. 内存缓存 (Caching)

   • 为了减少磁盘 I/O，SessionManager 会在内存中维护一个 _cache 字典。
   • 当你频繁与机器人对话时，它会直接从内存中读取会话对象，只有在保存时才写入磁盘。

关键类与方法

1. Session (数据类)

代表单个会话的数据结构。

• 属性:
  • key: 唯一标识符，格式通常为 channel:chat_id（如 telegram:12345）。
  • messages: 消息列表。
  • created_at / updated_at: 时间戳。
• 方法:
  • add_message(role, content): 添加一条新消息。
  • get_history(max_messages): 获取最近的 N 条消息，并格式化为 LLM（大模型）可接受的格式（只保留 role 和 content）。
  • clear(): 清空当前会话的所有消息。

2. SessionManager (管理器类)

负责对 Session 进行增删改查。

• __init__(workspace): 初始化，确保 ~/.nanobot/sessions 目录存在。
• get_or_create(key): 最常用的方法。
  1. 先查内存缓存。
  2. 缓存没有，就去磁盘加载。
  3. 磁盘也没有，就创建一个新的空白会话。
• save(session): 将会话状态写回磁盘。它会重写整个文件，确保元数据和消息列表都是最新的。
• delete(key): 删除某个会话（从内存移除并删除对应的 .jsonl 文件）。
• list_sessions(): 扫描目录，读取所有 .jsonl 文件的第一行（元数据），返回所有会话的列表，按更新时间倒序排列。

代码结构图解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

classDiagram
    class SessionManager {
        - Path sessions_dir
        - dict _cache
        + get_or_create(key) Session
        + save(session)
        + delete(key)
        + list_sessions()
    }
    
    class Session {
        + str key
        + list messages
        + datetime created_at
        + add_message(role, content)
        + get_history(max_messages)
    }
    
    SessionManager "1" --> "*" Session : manages

实际工作流程示例

当你发一条消息 “Hello” 给机器人时：

1. 加载: gateway 调用 manager.get_or_create("telegram:123")。管理器发现内存里没有，于是去读 ~/.nanobot/sessions/telegram_123.jsonl，加载之前的聊天记录。
2. 更新: Agent 处理完消息后，调用 session.add_message("user", "Hello") 和 session.add_message("assistant", "Hi there!")。
3. 保存: Agent 调用 manager.save(session)。管理器将更新后的消息列表写回 jsonl 文件。

总结

SessionManager 是 Nanobot 的记忆中枢。它简单、高效地利用文件系统来保存对话上下文，确保机器人即使重启也能“记得”你们之前的聊天内容。

CronService

CronService 是 Nanobot 的定时任务调度器。它类似于 Linux 的 cron 或 Python 的 Celery，但更轻量且专为 Agent 设计。它的主要职责是管理和执行那些需要在未来某个时间点或周期性执行的任务。

核心功能

1. 任务调度 (Scheduling)

   • 支持三种调度方式：
     • 一次性 (at): 在指定时间点执行一次（例如“明天早上 8 点”）。
     • 间隔循环 (every): 每隔一段时间执行一次（例如“每 30 分钟”）。
     • Cron 表达式 (cron): 使用标准 crontab 语法（例如 0 8 * * * 每天早上 8 点）。
   • 使用 _compute_next_run 函数计算下一次执行时间。

2. 任务持久化 (Persistence)

   • 文件存储: 所有任务数据保存在 JSON 文件中（通常是 ~/.nanobot/data/cron/jobs.json）。
   • 结构: CronStore 包含一个任务列表，每个 CronJob 包含 ID、名称、调度规则、Payload（要做什么）以及运行状态。
   • 优点: 即使 Nanobot 重启，任务也不会丢失。重启后会重新计算下次运行时间。

3. 任务执行 (Execution)

   • Payload: 任务的核心是一个 message（例如 “check weather”）。
   • 执行: 当时间到了，CronService 不会自己执行业务逻辑，而是调用回调函数 on_job（通常绑定到 commands.py 里的 agent.process_direct），把这个 message 扔给 Agent 去处理。
   • 结果分发: 如果任务配置了 deliver=True 和目标 to（如 Telegram 用户 ID），执行结果会自动发送给该用户。

4. 定时器机制 (Timer Loop)

   • 它不使用“每秒轮询”这种低效方式。
   • 智能休眠: _arm_timer 方法会计算距离“最近一个待执行任务”还有多久（delay_s），然后 asyncio.sleep(delay_s)。这样在空闲时几乎不消耗 CPU。
   • 当有新任务添加或任务执行完毕时，会重新计算并重置定时器。

关键类与方法

CronService

• __init__(store_path, on_job): 初始化服务，指定存储路径和执行回调。
• start() / stop(): 启动/停止服务。启动时会加载任务并计算下次运行时间。
• add_job(...): 添加新任务。会自动保存到磁盘并更新定时器。
• remove_job(job_id): 删除任务。
• _execute_job(job): 执行单个任务。
  1. 调用 self.on_job(job) 触发 Agent。
  2. 更新任务状态（last_status, last_run_at）。
  3. 对于一次性任务，执行完后将其禁用或删除；对于循环任务，计算下次运行时间。
  4. 保存状态到磁盘。
• _arm_timer(): 核心调度逻辑。找到所有任务中 next_run_at_ms 最小的那个时间点，设置一个 asyncio 延时任务。

任务数据结构 (CronJob)

一个典型的任务数据如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "id": "a1b2c3d4",
  "name": "每日早报",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *"  // 每天 8:00
  },
  "payload": {
    "message": "总结今天的科技新闻",  // Agent 收到的指令
    "deliver": true,
    "channel": "telegram",
    "to": "123456789"  // 结果发给谁
  },
  "state": {
    "nextRunAtMs": 1700000000000
  }
}

实际工作流程示例

1. 用户指令: 你对机器人说“每天早上 8 点提醒我喝水”。
2. 创建任务: Agent 调用 CronService.add_job，创建一个 cron 任务，schedule 为 0 8 * * *，payload message 为 “提醒用户喝水”。
3. 等待: CronService 计算出下次 8 点的时间戳，进入休眠。
4. 触发: 第二天早上 8 点，定时器醒来，调用 _execute_job。
5. 回调: CronService 调用 gateway 中的 on_cron_job 回调。
6. Agent 执行: Agent 收到 “提醒用户喝水” 的指令，生成回复 “早上好，该喝水了！”。
7. 推送: 因为 deliver=True，回复会自动推送到你的 Telegram。

总结

CronService 是 Nanobot 的生物钟。它让 Agent 具备了时间观念，不再只是被动等待用户说话，而是能主动在特定时间执行任务。它设计得非常轻量且健壮，利用文件系统持久化和 asyncio 实现高效调度。

HeartbeatService

HeartbeatService 是 Nanobot 的心跳机制，也是一种“周期性自检”服务。它的作用是让 Agent 即使在没有用户发消息的时候，也能每隔一段时间“醒来”一次，检查是否有后台任务需要处理。

与 CronService（基于精确时间调度）不同，HeartbeatService 更加简单粗暴，它基于一个固定的文件 HEARTBEAT.md 来驱动。

核心逻辑

1. 心跳周期 (Interval)

   • 默认每 30 分钟（1800 秒）触发一次。
   • 这是一个死循环 (while self._running)，每次执行完 await asyncio.sleep(self.interval_s) 后就会“跳动”一次。

2. 驱动源 (HEARTBEAT.md)

   • 服务会检查工作区（Workspace）下是否存在 HEARTBEAT.md 文件。
   • 如果文件不存在或为空：Agent 继续睡觉，什么都不做。
   • 如果文件有内容：Agent 被唤醒。

3. 唤醒与执行

   • 当心跳触发且 HEARTBEAT.md 有内容时，服务会调用 on_heartbeat 回调函数。
   • 这个回调实际上是向 Agent 发送了一条特殊的 Prompt：

     1 2 3

     Read HEARTBEAT.md in your workspace (if it exists). Follow any instructions or tasks listed there. If nothing needs attention, reply with just: HEARTBEAT_OK

   • Agent 收到这条指令后，会读取 HEARTBEAT.md，执行里面列出的任务（例如“检查是否有新的待办事项”、“整理今天的日志”等）。

4. 反馈机制

   • 如果 Agent 执行完任务，或者发现其实没什么要做的，它应该回复 HEARTBEAT_OK。
   • HeartbeatService 收到这个回复后，会记录一条日志 “Heartbeat: OK”，表示本次心跳正常结束。

关键方法解析

• _is_heartbeat_empty(content):

  • 这是一个辅助函数，用来判断 HEARTBEAT.md 是否真的有“干货”。
  • 它会忽略空行、标题（# 开头）、HTML 注释（<!-- -->）以及空的复选框（- [ ]）。
  • 只有当文件里有真正的文本内容时，才会触发心跳。这避免了因为文件里只写了个标题而频繁唤醒 Agent 浪费 Token。

• _run_loop():

  • 后台常驻协程。
  • 只要 self._running 为 True，就无限循环：sleep -> _tick。

• _tick():

  • 单次心跳的逻辑。
  • 1. 读取 HEARTBEAT.md。
  • 1. 检查是否为空 (_is_heartbeat_empty)。为空则直接返回。
  • 1. 调用 self.on_heartbeat(HEARTBEAT_PROMPT) 唤醒 Agent。
  • 1. 检查 Agent 的回复是否包含 HEARTBEAT_OK，记录日志。

设计意图

HeartbeatService 的设计初衷是实现异步的长运行任务或状态维护，而不需要用户显式触发。

• 场景 1：长任务队列

  • 你可以往 HEARTBEAT.md 里写入：”处理 data/raw 目录下的所有 PDF 文件”。
  • 即使你下线了，Agent 也会每半小时醒来一次，处理一部分文件，直到处理完把 HEARTBEAT.md 清空。

• 场景 2：自我反思/整理

  • 可以在 HEARTBEAT.md 里写：”检查 MEMORY.md，如果太乱了就整理一下”。
  • Agent 会定期整理自己的记忆，保持“头脑清醒”。

总结

HeartbeatService 是一个基于文件的被动触发器。它通过检测 HEARTBEAT.md 文件的状态来决定是否唤醒 Agent。这是一种非常灵活的机制，允许用户通过简单地修改文件来控制 Agent 的后台行为，而无需编写复杂的 Cron 表达式。

ChannelManager

ChannelManager 是 Nanobot 的外交部长。它统一管理所有外部通信渠道（如 Telegram, WhatsApp, Slack 等），负责它们的生命周期（启动/停止）以及消息的分发。

核心职责

1. 渠道初始化 (_init_channels)

   • 在启动时，根据 nanobot.toml 配置文件，动态加载并实例化启用的渠道。
   • 目前支持的渠道包括：Telegram, WhatsApp, Discord, 飞书, Mochat, 钉钉, Email, Slack, QQ 等。
   • 每个渠道都继承自 BaseChannel，拥有统一的接口（start, stop, send）。

2. 生命周期管理

   • start_all(): 并发启动所有已启用的渠道。
     • 每个渠道的 start() 方法通常会启动一个轮询循环（Polling）或 Webhook 服务器来接收消息。
     • 同时启动一个 _dispatch_outbound 任务，负责处理发出去的消息。
   • stop_all(): 优雅关闭所有渠道，释放资源（如关闭 HTTP 连接）。

3. 消息路由 (Routing)

   • 输入路由（隐式）: 各个 Channel 实例内部会持有 bus（消息总线）的引用。当它们收到外部消息时，会直接调用 bus.publish_inbound(...) 将消息扔进总线，供 Agent 消费。ChannelManager 不直接干预这一步。
   • 输出路由（显式）:
     • ChannelManager 启动一个后台任务 _dispatch_outbound。
     • 这个任务不断从总线的输出队列 (consume_outbound) 中取出消息。
     • 它检查消息的 channel 属性（例如 “telegram”）。
     • 然后在自己的 self.channels 字典里找到对应的 Channel 实例，调用 channel.send(msg) 将消息发出去。

关键代码逻辑

• _dispatch_outbound:
  这是核心的消息分发循环。

  1 2 3 4 5 6 7 8 9 10

  while True: # 1. 从总线获取待发送消息 msg = await bus.consume_outbound() # 2. 查找目标渠道 channel = self.channels.get(msg.channel) # 3. 发送 if channel: await channel.send(msg)

  这个设计实现了 Agent 与具体通信协议的解耦。Agent 只需要产生一个通用的 OutboundMessage，不需要知道对方是用 HTTP 请求还是 WebSocket 发送，也不需要知道对方的 API Key 是什么。所有这些脏活累活都由 ChannelManager 委托给具体的 Channel 实现类去处理。

总结

ChannelManager 是连接 Nanobot 内核（Agent）与外部世界（用户）的桥梁。它通过统一的接口屏蔽了不同聊天平台的差异，让 Agent 可以专注于处理逻辑，而不用关心消息是如何传输的。

第二阶段：并发启动 (Startup)

初始化完成后，Gateway 会启动以下四个主要服务：

1
2
3
4
5
6
7

try:
    await cron.start()
    await heartbeat.start()
    await asyncio.gather(
        agent.run(),
        channels.start_all(),
    )

1. 启动定时任务调度器 (cron.start())：开始计时，等待任务触发。
2. 启动心跳服务 (heartbeat.start())：开始倒计时。
3. 启动 Agent 主循环 (agent.run())：Agent 进入“待机状态”，时刻监听消息总线上的输入消息。
4. 启动渠道管理 (channels.start_all())：
   • 启动所有启用的渠道（例如开始轮询 Telegram 消息，或监听 Webhook）。
   • 启动输出分发器 (_dispatch_outbound)，时刻监听消息总线上的输出消息。

这段代码是 nanobot gateway 启动的核心逻辑，它展示了从初始化后台服务到进入主运行循环的过程。

代码逻辑分步解析

1
2
3
4
5
6
7
8
9
10
11

# 1. 启动定时任务服务 (非阻塞)
await cron.start()

# 2. 启动心跳服务 (非阻塞)
await heartbeat.start()

# 3. 并发启动 Agent 和 Channels (阻塞/长运行)
await asyncio.gather(
    agent.run(),
    channels.start_all(),
)

为什么要按这个顺序？

这个顺序的设计主要基于任务的性质（是非阻塞初始化，还是长运行死循环）：

1. 为什么 cron 和 heartbeat 先行？

• 非阻塞初始化: cron.start() 和 heartbeat.start() 方法内部仅仅是设置状态标志（_running = True）并创建后台的 asyncio.Task（计时器）。它们执行非常快，瞬间就会返回，不会阻塞主程序的执行。
• 就绪原则: 按照依赖关系，最好先让内部的调度系统（定时器、心跳）准备就绪。这样一旦 Agent 开始工作，所有的定时触发机制都已经处于激活状态。

2. 为什么 agent 和 channels 要用 asyncio.gather？

• 阻塞运行:
  • agent.run() 是一个 while True 循环，它会一直卡在那里监听消息总线，直到程序退出。
  • channels.start_all() 也是一个阻塞操作，它会等待所有启用的渠道（Telegram, WhatsApp 等）运行，而这些渠道通常也是通过 while True 轮询或长连接挂起的。
• 并发必要性:
  • 如果写成顺序执行（例如先 await agent.run()），代码就会永远停在这一行，Agent 虽然跑起来了，但 channels.start_all() 永远不会被执行，导致机器人无法收发消息。
  • asyncio.gather 的作用就是让这两个“死循环”在同一个事件循环中同时跑。Agent 负责“思考”，Channels 负责“听和说”，两者并行不悖。

总结图解

可以将这个启动过程想象成一家餐厅开门：

1. cron.start(): 经理先打开闹钟，设置好提醒（比如“中午12点开启特价午餐”）。这一步只是拨个开关，马上就好。
2. heartbeat.start(): 经理开启打卡机，每半小时检查一次员工状态。这一步也只是通个电，马上就好。
3. asyncio.gather(...): 餐厅正式对外营业：
   • agent.run(): 厨师（Agent） 站到灶台前，开始死循环等待订单。
   • channels.start_all(): 服务员（Channels） 站到门口，开始死循环等待顾客。

厨师和服务员必须同时进入工作状态，餐厅才能正常运转。

第三阶段：消息处理循环 (The Loop)

这是 Gateway 运行时的核心逻辑，分为“接收”和“发送”两条路径：

1. 输入路径：从 用户 到 Agent

当你在 Telegram 给机器人发一条消息时：

1. 接收: TelegramChannel 收到消息。
2. 发布: 渠道将消息封装为 InboundMessage（包含内容、发送者ID、渠道名），扔进消息总线。
3. 获取: 正在待机的 AgentLoop 从总线中抓取到这条消息。
4. 思考与执行:
   • Agent 读取历史聊天记录。
   • Agent 将历史记录 + 新消息发送给 LLM（大模型）。
   • 工具调用: 如果 LLM 决定使用工具（如“搜索天气”），Agent 会执行工具代码，并将结果再次喂给 LLM。
   • 生成回复: LLM 生成最终的文本回复。
5. 存储: Agent 将对话记录保存到数据库（SessionManager）。
6. 输出: Agent 将回复封装为 OutboundMessage，扔回消息总线。

2. 输出路径：从 Agent 到 用户

当 Agent 产生回复（或定时任务触发）时：

1. 分发: ChannelManager 的输出分发器从总线中抓取到 OutboundMessage。
2. 路由: 分发器查看消息的标签（例如 channel="telegram"）。
3. 发送: 找到对应的 TelegramChannel 实例，调用其发送接口（如调用 Telegram API），将消息推送到你的手机上。

总结图解

1
2
3
4
5
6
7
8
9
10
11
12
13
14

graph TD
    User[用户] --发消息--> Channel[通信渠道 (Telegram/Slack)]
    Channel --InboundMessage--> Bus[消息总线]
    Bus --InboundMessage--> Agent[AgentLoop (大脑)]
    
    Agent --思考/查资料--> Tools[工具集]
    Tools --结果--> Agent
    
    Agent --OutboundMessage--> Bus
    Bus --OutboundMessage--> Dispatcher[渠道分发器]
    Dispatcher --找到对应渠道--> Channel
    Channel --回复--> User
    
    Cron[定时任务] --触发--> Agent

简而言之，nanobot gateway 就是一个死循环，不断地搬运消息、触发 AI 思考、并把结果送回给用户。

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

直到我遇到了 nanobot。

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

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

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

0在这里
1在这里

只聊一句

前面运行的nanobot gateway实际上启动了一个 全功能的AI服务端。你可以把它想象成一个繁忙的指挥中心，它同时处理着多条战线的工作。它是nanobot最典型的使用场景，但是这种模式有点复杂，不利于我们研究源码。
这里将先从nanobot agent -m这种模式入手，研究下“只与agent聊一句天，它背后干了啥”。

具体流程

nanobot agent -m 命令用于在 单次消息模式 (Single Message Mode) 下运行智能体。它允许你从命令行直接发送一条指令给智能体，智能体执行完毕并返回结果后程序即刻退出，而不会进入交互式聊天界面。

下面是该命令从输入到输出的详细执行流程：

CLI 入口与参数解析

文件: nanobot/cli/commands.py

当你运行 nanobot agent -m "你的指令" 时：

• Typer 解析: agent 函数被调用，-m 参数的值被赋给 message 变量。
• 环境准备:
  • load_config() 加载项目配置。
  • 初始化 MessageBus (消息总线) 和 LLMProvider (大模型提供商)。
  • 初始化核心控制器 AgentLoop。

这里非常关键，一下引出了3个关键概念，下面一一详细研究下。

消息总线

MessageBus 类是一个基于 asyncio.Queue 的异步消息总线，其核心目的是解耦消息的生产者（Chat Channels，如 CLI、Slack、Discord 等）和消费者（Agent Core 智能体核心）。

它实现了经典的 生产者-消费者模式，并通过双向队列分别处理“输入”和“输出”。

1. 核心结构

nanobot/bus/queue.py

MessageBus 内部维护了两个主要的异步队列：

• self.inbound: 用于存放发给智能体的消息（用户 -> 智能体）。
• self.outbound: 用于存放智能体发出的回复（智能体 -> 用户）。
• self._outbound_subscribers: 一个字典，用于管理不同渠道（Channel）的回调函数，确保消息能准确路由回来源渠道。

2. 主要功能模块

A. 输入流处理 (Inbound Flow)

当用户发送消息时（例如通过 CLI 输入或 Slack 发送）：

• publish_inbound(msg) (L25): 外部渠道调用此方法，将 InboundMessage 放入输入队列。
• consume_inbound() (L29): 智能体核心循环 (AgentLoop) 调用此方法，阻塞等待并获取下一条待处理的消息。

B. 输出流处理 (Outbound Flow)

当智能体处理完任务并生成回复时：

• publish_outbound(msg) (L33): 智能体调用此方法，将 OutboundMessage 放入输出队列。
• consume_outbound() (L37): 手动消费输出消息的方法（通常用于简单的同步场景）。

C. 订阅与分发机制 (Subscription & Dispatch)

为了支持多渠道并发（例如同时运行 CLI 和 Slack 机器人），MessageBus 提供了订阅机制：

• subscribe_outbound(channel, callback) (L41): 允许特定渠道注册回调函数。例如，Slack 适配器会订阅 channel="slack"，并提供一个将消息发送到 Slack API 的回调函数。
• dispatch_outbound() (L51): 这是一个后台任务循环。它不断从 outbound 队列中取出消息，根据消息的 channel 属性查找对应的订阅者，并执行回调函数。这确保了如果消息来自 Slack，回复也会发回 Slack，而不是发到 CLI。

3. 数据流向图解

1
2
3
4
5
6

graph LR
    User[用户 (CLI/Slack)] -->|publish_inbound| InQueue[(Inbound Queue)]
    InQueue -->|consume_inbound| Agent[智能体核心 (AgentLoop)]
    Agent -->|publish_outbound| OutQueue[(Outbound Queue)]
    OutQueue -->|dispatch_outbound| Dispatcher[分发器]
    Dispatcher -->|callback| User

4. 代码细节解析

• 非阻塞与并发: 使用 asyncio.Queue 保证了线程安全和协程并发能力。consume_inbound 和 consume_outbound 都是 await 操作，不会阻塞事件循环。
• 错误处理: 在 dispatch_outbound 循环中 (L58-67)，使用了 try-except 捕获回调执行中的异常，防止因为某个渠道的发送失败导致整个总线崩溃。同时使用了 asyncio.wait_for 来定期检查停止标志 _running。
• 生命周期管理: 提供了 stop() 方法 (L69) 来优雅地停止分发循环。

总结

MessageBus 是 Nanobot 架构中的中枢神经。它不仅实现了异步解耦，还通过订阅/分发机制支持了多渠道（Multi-channel）的扩展能力，使得核心智能体逻辑不需要关心消息是从哪里来的，也不需要知道如何发送回具体的平台，只需要关注处理 InboundMessage 并产生 OutboundMessage 即可。

LiteLLMProvider

LiteLLMProvider 类是 Nanobot 与各种大语言模型 (LLM) 进行交互的核心适配器。它利用 litellm 库的强大兼容性，实现了对 OpenAI、Anthropic、OpenRouter、Google Gemini 等数十种模型提供商的统一支持，而无需为每个提供商编写单独的代码。

代码位置：nanobot/providers/litellm_provider.py

1. 核心设计理念

该类采用 “配置驱动 + 统一接口” 的设计模式：

• 统一接口: 继承自 LLMProvider，对外暴露标准的 chat() 方法。无论底层是 GPT-4 还是 Claude 3，调用方式都一样。
• 配置驱动: 通过 providers/registry.py 中的注册表来管理不同模型的特性（如 API Key 环境变量名、模型前缀、参数覆盖等），避免了大量的 if-elif 硬编码。

2. 主要功能解析

A. 初始化与环境自动配置 (__init__ & _setup_env)

代码: L23-L71

当 LiteLLMProvider 实例化时：

1. 检测网关: 调用 find_gateway 判断是否使用了 API 网关（如 OpenRouter 或自定义代理）。
2. 设置环境变量: _setup_env 方法根据检测到的提供商（如 Anthropic 或 OpenAI），自动将传入的 api_key 设置到对应的环境变量中（如 ANTHROPIC_API_KEY）。这使得 litellm 库能自动找到凭证。
3. LiteLLM 调优: 禁用调试日志 (suppress_debug_info) 并开启自动丢弃不支持参数 (drop_params)，提高稳定性。

B. 智能模型路由 (_resolve_model)

代码: L73-L90

LiteLLM 要求模型名称带有前缀（如 anthropic/claude-3）。此方法自动处理这些细节：

• 网关模式: 如果配置了网关，它会根据网关规则添加或去除前缀。
• 标准模式: 自动为已知模型添加前缀。例如，如果用户配置 model: claude-3-opus，它会自动转换为 anthropic/claude-3-opus，用户无需操心前缀问题。

C. 模型参数微调 (_apply_model_overrides)

代码: L92-L100

不同的模型对参数有不同的偏好。例如，某些国产模型可能对 temperature 敏感。此方法允许通过注册表为特定模型注入特定的参数覆盖，确保最佳效果。

D. 对话请求与响应标准化 (chat & _parse_response)

代码: L102-L199

这是真正干活的地方：

1. 准备参数: 将消息历史、工具定义、Token 限制等封装成字典。
2. 调用 LiteLLM: 使用 acompletion 异步发送请求。
3. 结果解析:
   • 工具调用: 将原始 JSON 解析为标准的 ToolCallRequest 对象，处理 JSON 解析错误。
   • Token 统计: 提取 usage 信息。
   • 推理内容: 如果模型支持思维链（如 DeepSeek R1），提取 reasoning_content。
   • 统一返回: 打包成 LLMResponse 对象返回给 AgentLoop。

3. 为什么使用 LiteLLM？

• 多模型支持: 一套代码支持 100+ 种模型。
• 标准化: 屏蔽了不同 API（如 OpenAI 格式 vs Anthropic 格式）的差异，输入输出完全统一。
• 容错性: drop_params=True 自动处理参数不兼容问题（例如某些模型不支持 tool_choice）。

总结

LiteLLMProvider 是 Nanobot 的 “万能插头”。它让 Nanobot 能够轻松切换底层模型，无论是本地部署的 Ollama，还是云端的 GPT-4/Claude-3，只需更改配置，无需修改代码。

AgentLoop

AgentLoop 类是 Nanobot 的大脑和心脏。它负责协调所有的核心组件：接收消息、管理记忆、调用大模型 (LLM)、执行工具，并最终生成回复。

代码位置：nanobot/agent/loop.py

以下是 AgentLoop 的详细解构：

1. 核心职责

AgentLoop 是一个自主的智能体运行时环境。它的主要工作流程是：

1. 监听消息总线 (MessageBus)。
2. 构建上下文 (Context)，包括历史记录、长期记忆和可用工具。
3. 进入思考-执行循环 (ReAct Loop)：
   • 询问 LLM 下一步做什么。
   • 如果 LLM 决定调用工具，执行工具并将结果反馈给 LLM。
   • 重复上述步骤，直到 LLM 给出最终回复。
4. 将结果发送回消息总线。

2. 关键组件 (初始化)

在 __init__ (L38) 中，它组装了以下关键模块：

• MessageBus: 通信管道，用于收发消息。
• LLMProvider: 大模型接口 (如 OpenAI, Anthropic)，负责生成文本和工具调用。
• ContextBuilder: 上下文构建器，负责将杂乱的信息（历史、文件、记忆）组装成 LLM 能理解的 Prompt。
• ToolRegistry: 工具箱，管理所有可用工具 (读写文件、Web搜索、执行Shell等)。
• SessionManager: 会话管理器，负责保存和加载聊天记录。
• SubagentManager: 子智能体管理器，允许主智能体生成 (Spawn) 其他智能体来处理特定任务。

3. 运行模式

AgentLoop 支持两种运行模式：

A. 守护进程模式 (run)

代码: L113
这是智能体的主循环。它无限运行 (while self._running)，不断从 bus.consume_inbound() 获取消息。这种模式适用于长期运行的服务（如连接到 Slack 或后台任务）。

B. 直接调用模式 (process_direct)

代码: L427
用于 CLI 命令 (如 nanobot agent -m "...") 或 Cron 定时任务。它不经过队列等待，直接处理传入的字符串并返回结果。

4. 核心思考逻辑 (_process_message)

这是最复杂也是最核心的部分 (L147)，处理单条消息的完整流程如下：

第一阶段：上下文准备

1. 加载会话: 根据 Session ID 获取历史聊天记录。
2. 记忆压缩 (_consolidate_memory): 如果历史记录太长（超过 memory_window，默认 50 条），会触发后台压缩任务，将旧对话总结并存入 MEMORY.md，保持上下文窗口精简 (L366)。
3. 工具注入: 为 Message/Spawn 等工具注入当前频道信息，确保回复能发回正确的地方。
4. 构建 Prompt: self.context.build_messages(...) 将所有信息打包成 LLM 消息列表。

第二阶段：思考-执行循环 (The Loop)

代码位于 L200-L244。这是一个 while 循环，最大迭代次数由 max_iterations 控制（防止无限循环）。

• Step 1: 询问 LLM
  调用 self.provider.chat(messages, tools=...)。

• Step 2: 判断行动

  • 情况 A: LLM 想要调用工具 (response.has_tool_calls)
    1. 将 LLM 的“思考过程”和“工具调用请求”加入消息历史。
    2. 执行工具: 遍历 tool_calls，调用 self.tools.execute(...) 执行实际代码（如读取文件、搜索网页）。
    3. 反馈结果: 将工具的执行结果 (tool_result) 作为新消息追加到历史中。
    4. 继续循环: 带着工具的结果，进入下一次迭代，让 LLM 决定下一步。
  • 情况 B: LLM 返回最终回复
    1. 获取文本内容。
    2. 跳出循环 (break)。

第三阶段：收尾

1. 保存记录: 将用户的输入、LLM 的回复以及使用过的工具列表保存到 Session 文件中 (L253)。
2. 发送回复: 封装 OutboundMessage 并通过 Bus 发送出去。

5. 记忆系统 (_consolidate_memory)

代码: L366
这是一个非常关键的自我维护机制。当对话过长时，AgentLoop 不会简单地截断，而是：

1. 提取旧的消息。
2. 调用 LLM (作为 memory consolidation agent)。
3. 要求 LLM 生成两样东西：
   • History Entry: 一段摘要，存入 HISTORY.md。
   • Memory Update: 更新 MEMORY.md 中的长期事实（如用户偏好、项目背景）。
4. 这样，即使原始对话被丢弃，关键信息也留在了长期记忆中。

总结

AgentLoop 实现了一个标准的 ReAct (Reasoning + Acting) 架构。它不仅仅是一个聊天机器人，更是一个能通过工具与环境交互、并通过记忆系统维持长期连贯性的智能体运行时。

进入单次执行模式

文件: nanobot/cli/commands.py

代码检查 if message: 是否存在：

• 交互模式 (False): 如果没有 -m，代码会进入 else 分支启动交互式 Shell (run_interactive)。
• 单次模式 (True): 存在 -m 时，定义并运行 run_once 异步函数：
  • 启动 _thinking_ctx() 上下文管理器，在终端显示 “nanobot is thinking…” 加载动画（除非开启了 --logs）。
  • 调用核心处理函数 agent_loop.process_direct(message, session_id)。

核心处理循环 (AgentLoop)

文件: nanobot/agent/loop.py

process_direct 是从 CLI 到智能体逻辑的桥梁，它将你的字符串指令封装为 InboundMessage，然后调用内部的 _process_message 方法。这是智能体真正”思考”的地方：

A. 上下文构建

• 会话管理: 根据 session_id 获取或创建会话记录 (Session)，加载历史对话。
• 记忆整合: 如果历史消息超过 memory_window (默认 50 条)，触发 _consolidate_memory 将旧消息压缩为长期记忆 (L366)。
• 工具准备: 为 Message/Spawn/Cron 等工具注入当前上下文信息。
• 构建 Prompt: ContextBuilder 将系统提示词、历史记录、当前指令、长期记忆组合成发送给 LLM 的最终消息列表。

B. 思考与执行循环 (Loop)

文件: nanobot/agent/loop.py

智能体进入一个 while 循环 (最多 max_iterations 次，默认 20 次)：

1. 调用 LLM: 将消息列表和工具定义发送给模型 (self.provider.chat)。
2. 处理响应:
   • 情况 1：模型决定调用工具 (Has Tool Calls)
     • 解析工具调用请求 (如 read_file, web_search 等)。
     • 执行工具逻辑 (self.tools.execute)。
     • 将工具执行结果追加到消息列表中。
     • 继续循环，让模型根据工具结果进行下一步思考。
   • 情况 2：模型返回文本 (No Tool Calls)
     • 获取最终回复内容。
     • 跳出循环。

结果返回与展示

文件: nanobot/cli/commands.py

一旦 process_direct 返回最终文本：

• 保存会话: 你的指令和智能体的回复被保存到 Session 中，供下次调用使用。
• 打印输出: _print_agent_response 函数将结果渲染为 Markdown 格式打印到终端。
• 程序退出: asyncio.run(run_once()) 结束，Python 进程退出。

总结

nanobot agent -m 本质上是 “启动环境 -> 执行一次思考循环 -> 打印结果 -> 退出” 的快捷通道，非常适合用于脚本集成或快速的单次问答任务。

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

直到我遇到了 nanobot。

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

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

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

0在这里

一键装机

在运行nanobot之前，需要先初始化一下：

1

nanobot onboard

检查并创建配置文件

• 位置：~/.nanobot/config.json
• 动作：
  • 首先检查该文件是否存在。如果存在，会询问你是否覆盖。
  • 如果不存在（或确认覆盖），它会创建一个默认的 Config 对象并保存。
  • 这个文件是你后续配置 API Key（如 OpenAI、Anthropic）的地方。

创建工作区目录

• 位置：默认为 ~/.nanobot/workspace（具体路径由 get_workspace_path() 决定）。
• 动作：确保这个目录存在，如果不存在则创建它。这个目录是 nanobot 的“大脑”和“手脚”，它在这里读写文件、存储记忆。

生成模板文件 (Bootstrap)

它会在你的工作区里自动生成一些基础的 Markdown 文件，用来定义 nanobot 的行为和记忆：

• AGENTS.md:
  • 作用：Agent 的“员工手册”。定义了它作为一个 AI 助手的基本准则（比如要友善、准确、行动前要解释）。
  • 提示词是：

    1 2 3 4 5 6 7 8 9 10 11

    ""# Agent Instructions You are a helpful AI assistant. Be concise, accurate, and friendly. ## Guidelines - Always explain what you're doing before taking actions - Ask for clarification when the request is ambiguous - Use tools to help accomplish tasks - Remember important information in memory/MEMORY.md; past events are logged in memory/HISTORY.md """

• SOUL.md:
  • 作用：Agent 的“人设”。定义了它的性格（乐于助人、好奇）、价值观（隐私优先、透明）。
  • 提示词是：

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

    """# Soul I am nanobot, a lightweight AI assistant. ## Personality - Helpful and friendly - Concise and to the point - Curious and eager to learn ## Values - Accuracy over speed - User privacy and safety - Transparency in actions """

• USER.md:
  • 作用：Agent 对你的认知。这里记录了你的偏好（语言、时区、沟通风格）。
  • 提示词是：

    1 2 3 4 5 6 7 8 9 10

    """# User Information about the user goes here. ## Preferences - Communication style: (casual/formal) - Timezone: (your timezone) - Language: (your preferred language) """

• memory/MEMORY.md:
  • 作用：长期记忆。用来存储那些需要跨会话记住的重要信息。
  • 提示词是：

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

    """# Long-term Memory This file stores important information that should persist across sessions. ## User Information (Important facts about the user) ## Preferences (User preferences learned over time) ## Important Notes (Things to remember) """

• memory/HISTORY.md:
  • 作用：历史记录。用来记录过去的事件（初始化为空）。
  • 提示词默认为空。
• skills/:
  • 作用：技能目录。预留给未来存放自定义技能的地方。

打印后续指引

最后，它会在终端输出一个“下一步”指南，告诉你：

1. 去 ~/.nanobot/config.json 填入你的 API Key。
2. 如何开始第一次对话（nanobot agent -m "Hello!"）。

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   ✓ Created config at /root/.nanobot/config.json ✓ Created workspace at /root/.nanobot/workspace Created AGENTS.md Created SOUL.md Created USER.md Created memory/MEMORY.md 🐈 nanobot is ready! Next steps: 1. Add your API key to ~/.nanobot/config.json Get one at: https://openrouter.ai/keys 2. Chat: nanobot agent -m "Hello!" Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps

总结

nanobot onboard 就是一个一键装机命令。它帮你铺好了路，建好了房（目录结构），写好了家规（模板文件），你只需要拿着钥匙（API Key）住进去（配置一下）就可以开始了。

配置

完成 onboard 之后，你的环境已经准备好了，接下来只需要把“钥匙”交给 nanobot。你需要编辑配置文件 ~/.nanobot/config.json。

配置模型供应商

需要至少配置一个 AI 提供商，就两个参数：apiBase和apiKey：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxxxxxxx" 
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

注意：agents.defaults.model 决定了 nanobot 默认用哪个模型。你可以随时通过命令行参数 -m 覆盖它。

配置保存后，在终端运行以下命令来测试：

1
2
3
4
5

# 检查状态，看看 Key 是否被识别
nanobot status

# 试着聊一句
nanobot agent -m "你好，介绍一下你自己"

如果它回复了你，恭喜！你的 nanobot 已经正式上岗了。🎉

配置飞书频道

上面的运行方式只能“聊一句”，nanobot真正的交互方式是通过各种通讯工具与它进行对话，这里使用飞书作为案例搞一下。

配置飞书（Feishu）需要两个步骤：先在飞书开放平台创建一个机器人应用，然后把凭证填入 nanobot 的配置文件。

nanobot 使用飞书的WebSocket 长连接模式，这意味着你不需要公网 IP，也不需要内网穿透，直接在本地电脑运行即可。

第一步：创建飞书机器人

1. 登录 飞书开放平台。
2. 点击 创建企业自建应用，填写名称（比如 “Nanobot”）和描述。
3. 添加机器人能力：
   • 进入左侧菜单 添加应用能力 -> 机器人，点击添加。
4. 配置权限：
   • 进入 权限管理，搜索并添加以下权限：
     • im:message (获取与发送单聊、群组消息)
     • im:message.group_at_msg (获取群组中 @机器人的消息)
     • im:message.p2p_msg (获取用户发给机器人的单聊消息)
   • 注意：添加权限后，需要发布版本才能生效。
5. 配置事件订阅（注意！这一步先不要做，等到把ID和secret配置给nanob，然后启动gateway后再设置）：
   • 进入 事件订阅。
   • 订阅方式：选择 长连接模式（这一步很关键！）。
   • 添加事件：搜索并添加 im.message.receive_v1 (接收消息)。
6. 获取凭证：
   • 进入 凭证与基础信息。
   • 复制 App ID 和 App Secret。
7. 发布应用：
   • 进入 版本管理与发布，创建并发布一个版本（如果不发布，机器人无法被外部搜到）。

第二步：配置 nanobot

打开配置文件 ~/.nanobot/config.json，在 channels 下添加 feishu 配置：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxx", 
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "encryptKey": "",
      "verificationToken": "",
      "allowFrom": []
    }
  }
}

• appId: 填入你刚才复制的 App ID。
• appSecret: 填入你刚才复制的 App Secret。
• encryptKey 和 verificationToken: 在长连接模式下通常留空即可。
• allowFrom: 如果你想限制只有特定用户能跟机器人聊天，可以在这里填入用户的 open_id。留空 [] 表示允许所有人。

第三步：启动

配置完成后，启动网关模式：

1

nanobot gateway

现在，打开飞书 App，搜索你的机器人名字，给它发一条消息，它应该就会回复你了！🎉

如果它回复了你，恭喜！你的 nanobot 已经正式上岗了。🎉

后台运行

nanobot gateway 命令本身是一个前台进程，它没有内置 --daemon 参数来自动转入后台。

如果你想让它在后台长期运行，有几种标准的方法：

使用 nohup (最简单)

这是最传统的后台运行方式，即使你退出了 SSH 终端，它也会继续运行。

1
2

# 启动并把日志输出到 nanobot.log
nohup nanobot gateway > nanobot.log 2>&1 &

• 查看日志：tail -f nanobot.log
• 停止：你需要先找到进程 ID，然后 kill 掉。

  1 2	ps aux | grep nanobot kill <PID>

使用 Docker (生产环境推荐)

如果你想要更稳定的部署，用 Docker 跑是最省心的，它自带重启策略。

1
2
3
4
5
6

docker run -d \
  --name nanobot \
  --restart always \
  -v ~/.nanobot:/root/.nanobot \
  -p 18790:18790 \
  nanobot gateway

• -d: 后台运行 (Detach)
• --restart always: 如果挂了或者重启电脑，自动重新启动

使用 systemd (Linux 服务器推荐)

如果你是在 Linux 服务器上部署，可以把它注册成系统服务。

创建一个文件 /etc/systemd/system/nanobot.service：

1
2
3
4
5
6
7
8
9
10
11
12
13

[Unit]
Description=Nanobot AI Gateway
After=network.target

[Service]
Type=simple
User=your_username
ExecStart=/path/to/your/python/bin/nanobot gateway
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

然后启用：

1
2

sudo systemctl enable nanobot
sudo systemctl start nanobot

这一章先到这吧，未完待续。

最近在看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

1

pip install nanobot-ai

纳米机器人启动

安装好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 函数去执行。

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

最近OpenClaw（曾用名ClawdBot、MoltBot）大火，本文基于 OpenClaw 官方文档，结合 阿里云 ECS / 轻量应用服务器 的实际使用场景，给出一份 从零开始、可落地 的 OpenClaw 安装与部署指南，适用于测试与生产环境。

部署前准备

云服务器选择

推荐使用 阿里云 ECS 或 轻量应用服务器（SAS）。

推荐配置：

• 操作系统：Ubuntu 22.04 LTS（或 20.04）
• CPU：≥ 2 vCPU
• 内存：≥ 4 GB
• 磁盘：≥ 40 GB SSD
• 网络：分配公网 IP

OpenClaw 官方推荐运行在标准 Linux VPS 环境中，支持容器化部署。

安全组与网络

在阿里云控制台 安全组规则 中，至少放行以下端口：

环境安装

安装 Node.js（非 Docker 模式）

OpenClaw 需要 Node.js ≥ 22：

1
2
3
4

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

配置大模型

这里使用的kimi 2.5模型。
具体订阅和获取key的方法不再详述。

安装 OpenClaw

官方一键安装脚本（推荐，如果不行用下面的npm）

1

curl -fsSL https://openclaw.bot/install.sh | bash

安装完成后，确认命令是否可用：

1

openclaw --version

如命令不存在，请确认 npm global bin 已加入 $PATH。

使用npm

1

npm i -g openclaw

初始化与配置

1

openclaw onboard --install-daemon