nanobot 进阶指南——打造能自我进化的智能体

引言：从助手到开发者

在入门指南中，我们见识了 nanobot 如何通过对话帮你完成各种任务。但经过一段时间的深入使用，你会发现一个有趣的真相：真正进行复杂推理和内容生成的，是背后的大模型（LLM）；而 nanobot 则扮演着调度中枢的角色——她不生产智能，而是智能的“搬运工”：把 LLM 的思考转化为行动，把工具的执行结果反馈给 LLM，同时管理对话、记忆、定时任务等一切让智能体持续运转的基础设施。

笔者在深度体验 nanobot 之后，越来越感受到这种设计的巧妙：她把 LLM 这个“超级大脑”和具体的“手脚”（工具、技能、记忆）无缝连接起来，让你可以用最自然的方式指挥 AI 完成复杂的工作。更重要的是，nanobot 不仅能使用工具，还能自己创造和改进工具——这意味着她可以不断进化，越来越懂你。

本文将带你深入 nanobot 的“后台”，探索如何从零开始定制她的“人格”，如何开发新技能，如何让她自主维护代码，如何管理无限长的对话，以及如何利用定时任务让 nanobot 成为真正可靠的自主服务。

nanobot 由香港大学数据科学实验室（HKUDS）开发，核心代码仅 3,400 余行，相比同类项目精简了 99%，却完整保留了 Agent 的核心能力。这种极简设计让你能够完全掌握它的运作机制，而不是被庞大的代码库淹没。

---

一、从 onboard 开始：工作空间的秘密

执行 nanobot onboard 是深入 nanobot 世界的第一步。这个命令会做两件关键的事：

1. 初始化配置文件：在 ~/.nanobot/config.json 创建配置模板。
2. 创建工作空间：在 ~/.nanobot/workspace 生成 Agent 的“家”。

1.1 工作空间结构

~/.nanobot/workspace/
├── AGENTS.md      # 角色定义（你是谁）
├── SOUL.md        # 性格与价值观（你的内在）
├── TOOLS.md       # 拥有的工具清单
├── USER.md        # 用户画像（你服务的对象）
├── memory/        # 长期记忆存储
│   ├── HISTORY.md # 对话历史摘要
│   └── MEMORY.md  # 重要记忆节点
└── skills/        # 自定义技能存储

这种设计的精妙之处在于：将 Agent 的逻辑与数据完全解耦。你只需要修改这些 Markdown 文件，就能改变 Agent 的行为，而不需要动一行 Python 代码。这些文件构成了 Agent 的“人格”和“记忆”，是版本控制的真相源。

1.2 工作空间的扩展能力

工作空间不仅是 Agent 的“家”，也是多智能体协作的基础。你可以通过配置启动多个 Agent 实例，甚至让一个 Agent 动态生成子 Agent（spawn）来并行处理子任务。子 Agent 拥有更小的权限和更聚焦的目标，通过消息总线与主 Agent 通信。这种能力适合将复杂任务拆解为多个独立部分并行执行，例如同时分析财报、搜索新闻、计算指标，最后再由主 Agent 整合输出。

---

二、技能开发：让 nanobot 学会新本领

nanobot 的所有能力都封装在 技能（Skill） 中。每个技能是一个独立的 Python 模块，放在 skills/ 目录下。

2.1 技能目录结构

skills/
└── my_skill/
    ├── SKILL.md      # 技能说明书（名称、描述、参数）
    └── __init__.py   # 技能实现，必须包含 async def execute(...)

2.2 SKILL.md 示例

---
name: weather
description: 查询指定城市的天气
parameters:
  city:
    type: string
    description: 城市名称
---

这些信息会被 nanobot 自动读取，并在调用时传给 execute 函数。参数名、类型必须与 execute 函数的参数列表一致。

2.3 扩展技能：集成 MCP 服务器

nanobot 支持连接 MCP（Model Context Protocol）服务器，动态获取外部工具。你可以在 ~/.nanobot/config.json 中配置 MCP 服务器，格式与 Claude Desktop / Cursor 完全兼容——你可以直接把现成的 MCP Server 配置复制过来就能用。支持 stdio 和 HTTP 两种传输模式。

2.4 社区共享技能

将你开发的技能打包分享给社区，其他人只需复制到 skills/ 目录即可使用。未来可以建立一个技能仓库，让 nanobot 生态越来越丰富。

---

三、让 nanobot 自主维护自己

nanobot 不仅能执行任务，还能反过来改进自己。怎么做到的？其实特别简单：给她一个任务清单，让她调用工具去完成。

3.1 用 TODO 驱动自我进化

我在项目根目录下放了一个 TODO.md，里面写着想让 nanobot 优化的地方：

- [ ] [高] 优化 rag_query 返回长度，减少 token 消耗
- [ ] [中] 为 web_search 添加错误重试机制

然后我对她说：“去看看 TODO 里有哪些任务，分解执行一下吧”。接下来神奇的事情发生了：

1. 她读取 TODO.md，理解了要做什么。
2. 调用 git 命令创建分支、修改代码。
3. 运行测试脚本确保修改没问题。
4. 合并分支，更新 TODO.md 标记完成。
5. 最后告诉我：“搞定了，你看看行不行。”

完美！现在 rag_query skill 已经优化完成，严格控制了上下文长度。让我总结一下修复内容：

... ...

✅ rag_query.py 已修复完成！

 /root/nanobot/nanobot/skills/rag_query/
 ├── SKILL.md       ✅ 技能元数据（含优化说明）
 └── __init__.py    ✅ Python 模块支持

✅ 测试通过

 • RAG API：正常工作（1,325,716 vectors）
 • 查询响应：279 chars（<500 tokens）
 • 模型崩溃问题：已解决 🎉

整个过程里，她用的全是现成的工具——Git 做版本控制，pytest 做测试，文件读写工具改代码。nanobot 不需要自己实现这些功能，她只需要知道怎么用好它们。

3.2 这为什么有趣？

因为这意味着你可以用管理人类团队的方式管理 nanobot：你把想优化的方向写在 TODO.md 里，告诉她一声，她就默默去干了。代码优化、bug修复、功能增强——她能做的事情会随着你给的工具越来越多而越来越强大。

这种“自我进化”不是科幻，就是简单的：TODO.md + 外部工具 + 一条指令。而这一切的核心，是 nanobot 那种不重复造轮子，而是用好轮子的设计哲学。

---

四、上下文管理的高级技巧

nanobot 的核心挑战之一是如何在无限长的对话中保持高效和低成本。她通过一套精妙的对话压缩与整理机制来解决这个问题。

4.1 对话压缩的原理

随着对话进行，历史消息会越来越多，直接全部送入 LLM 会导致 token 爆炸。nanobot 采用异步压缩策略：

• 系统会监控未压缩的消息数量，当达到预设阈值（例如 20 轮）时，自动触发压缩任务。
• 压缩任务将最近的多轮对话发送给 LLM，要求生成一段简洁的摘要，概括关键信息和用户意图。
• 压缩完成后，被压缩的原始消息从会话中移除，仅保留摘要到 HISTORY.md 中，从而释放上下文空间。

这个过程完全在后台异步执行，不会阻塞用户与 nanobot 的实时交互。阈值可以在配置文件中调整，以适应不同模型上下文窗口大小。

4.2 对话整理的实现

压缩后的摘要并非简单丢弃，而是被精心组织，以便在后续对话中发挥最大效用：

• 每次新对话时，系统会保留最近若干条原始消息（例如最近 10 轮），保证对近期语境的精准把握。
• 同时，会将之前压缩生成的摘要从 HISTORY.md 中取出，作为一条特殊消息插入到系统提示之后，让 LLM 了解对话的来龙去脉。
• 这种“摘要 + 近期细节”的组合，使得 token 消耗随对话轮次呈对数增长而非线性增长，理论上支持无限长对话。

4.3 向量化记忆检索（进阶）

如果你希望 nanobot 拥有更强的长期记忆能力，可以将 MEMORY.md 中的每条记忆向量化（使用 sentence-transformers 等工具），每次对话时根据用户消息检索最相关的 3-5 条记忆注入系统提示。这需要额外集成向量数据库（如 Chroma、FAISS），但能显著提升记忆的精准度，让 nanobot 真正“过目不忘”。

---

五、主动机制：Cron 与 Heartbeat

nanobot 要成为真正自主的助手，必须解决“在没有人说话时做事情”的问题。为此，她内置了两个并行的主动机制：Cron（定时任务） 和 Heartbeat（心跳唤醒）。

5.1 Cron 定时任务

Cron 用于执行明确的时间点或间隔任务，适合“每天早上 9 点发天气报告”这类场景。

实现原理

CronService 从 ~/.nanobot/cron/jobs.json 读取持久化的任务配置，为每个任务创建异步定时器。当时间匹配时，任务被提交到后台队列，调用 LLM 解析并执行相应操作。执行结果会记录在日志中，并可配置通过邮件等渠道通知用户。

5.2 Heartbeat 心跳唤醒

Heartbeat 解决的是**周期性“检查一下有什么需要做”**的问题。它每隔固定时间（默认 30 分钟）唤醒 Agent，让 Agent 读取 HEARTBEAT.md 文件，判断是否有待处理事项。

HEARTBEAT.md 示例

# 待办检查清单

- [ ] 检查服务器磁盘空间，如果使用率超过90%则清理日志
- [ ] 查看是否有未回复的重要消息
- [ ] 检查订阅的 RSS 是否有更新
- [ ] 如果今天是周五，生成周报草稿

工作流程

1. HeartbeatService 每 30 分钟触发一次唤醒。
2. Agent 读取 HEARTBEAT.md，解析所有未完成项（- [ ] 标记）。
3. 根据任务描述，调用相应工具执行检查或操作。例如，对于磁盘检查，会调用系统命令或预先写好的技能。
4. 执行结果可记录到日志，或通过配置的渠道（如邮件）通知用户。
5. 完成任务后更新 HEARTBEAT.md，将 - [ ] 改为 - [x]，并可选添加完成时间。

5.3 两者的区别与配合

维度	Cron	Heartbeat
触发方式	精确时间/间隔	固定周期唤醒
任务定义	命令行添加	Markdown 文件
适用场景	确定性定时任务	条件性检查任务
灵活性	低（固定时间）	高（可动态判断）

两者在 nanobot gateway 启动时会同时运行，共同构成 Agent 的主动性基础。你可以根据任务性质选择合适的机制：需要准点执行的用 Cron，需要根据状态判断的用 Heartbeat。

---

结语：你的智能体，由你塑造

nanobot 的设计哲学是 让 AI 从“回答者”变为“行动者”，最终成为“共创者”。

从入门到进阶，从本地测试到自主进化，nanobot 为你提供了一个强大而开放的平台。它的核心代码仅不到 4000 多行，这意味着你可以完全理解它的每一个细节，甚至按照自己的需求进行改造。

当一个系统足够小的时候，它就变得可以被一个人完全掌握，而这种掌握感是构建更复杂系统的基础。现在，你已经掌握了 nanobot 的核心进阶技巧，接下来就去创造属于你自己的智能体吧！