从零复刻 nanobot：手把手造一个 AI Agent
通过亲手构建一个完整的 AI Agent 框架，深入理解 nanobot 的架构设计。
这部分教程的定位是“教学版复刻”，重点是帮助你理解架构分层和演进过程，不等同于逐行复现当前仓库实现，也不是生产级脚手架。
为什么要从零造一个？
"听过不如看过，看过不如做过。"
用 nanobot 只需要 5 分钟，但理解 nanobot 需要自己造一个。这个教程会带你从一个 40 行的聊天脚本，逐步演进到一个完整的多平台 AI Agent——和 nanobot 走过的路一样。
教程目录
| 章节 | 代码量 | 你将构建 | 对应 nanobot 模块 |
|---|---|---|---|
| 第 1 章：最简 Agent | ~40 行 | 能对话的 LLM 客户端 | providers/ |
| 第 2 章：工具系统 | ~200 行 | 能执行命令、读写文件的 Agent | agent/tools/, agent/loop.py |
| 第 3 章：记忆与上下文 | ~300 行 | 有记忆、有人格的 Agent | agent/context.py, agent/memory.py, session/ |
| 第 4 章：消息总线 | ~400 行 | 能接入多平台的 Agent | bus/, channels/ |
| 第 5 章：技能与扩展 | ~500 行 | 可动态扩展的完整 Agent | agent/skills.py, cron/ |
| 第 6 章：从 Mini Agent 到真实项目 | 架构桥接 | 从教学版过渡到可维护项目 | 工程化边界、安全、并发、重试 |
怎么读这一部分
这部分最容易出现两种低效读法：
- 一口气通读所有代码，但没有真正跑过任何示例
- 只复制完整代码运行，却不知道这一章到底新增了什么
更推荐下面两种读法：
读法 A：只想先懂原理
每章优先看这 4 个位置：
- 开头的“问题 / 目标”
- 中间新增的核心抽象
- “本章你真正学到的抽象”
- “还缺什么？”
读法 B：边读边敲
每章固定按这个顺序：
- 先看“相对上一章，只新增了什么”
- 再读核心代码段，而不是一上来就看完整代码
- 最后再复制完整代码运行，并做最小验证
如果你不是程序员，建议把这一部分主要当作架构解释材料来读，不必强求自己完整敲完全部代码。
前置要求
- Python >= 3.11
- 一个 OpenAI 兼容的 API Key（推荐 OpenRouter）
- 基础 Python 知识（函数、类、async/await）
安装依赖
建议额外准备：
- 一个单独的虚拟环境，避免和现有项目依赖冲突
- 可访问的 OpenAI 兼容接口，以及一个已经验证可用的模型名
- 一个临时工作目录，方便测试读写文件和执行命令
后续章节会按需加入新依赖，每章开头会说明。
约定
- 每章末尾有完整的可运行代码，直接复制就能跑
nanobot/xxx.py表示 nanobot 源码中的对应模块；行号可能随版本变化- 每章的代码都在前一章基础上增量演进，不是推倒重来
如何使用这部分教程
推荐用下面的方式阅读，而不是一次性通读：
- 先跑通当前章节代码，确认最小示例可运行
- 再对照对应的 nanobot 模块，看真实实现多解决了哪些工程问题
- 如果示例代码和仓库实现不完全一致，优先把它理解成“教学简化版”
如果你的目标已经不是“理解原理”，而是“开始做自己的 bot 项目”，建议读完第 5 章后继续看第 6 章。第 6 章会专门说明教学版和真实项目之间还差哪些工程能力，以及应该先补什么、后补什么。
每章都建议做两类验证：
- 功能验证：代码是否真的能运行出本章目标效果
- 理解验证：你是否能说清这一章新增了哪一层抽象，以及为什么要加它
每章到底新增了什么
你可以把这 6 章理解成 6 次“只补一层”的递进：
- 第 1 章：新增
Provider和最小messages状态 - 第 2 章：新增
Tool、Registry、ReAct Loop - 第 3 章：新增
Session持久化、Context Builder、Memory - 第 4 章：新增
MessageBus和Channel，把 Agent 从终端解耦出来 - 第 5 章：新增
Skills，把“新知识”从底层代码里拆出去 - 第 6 章：不再加新机制，专门说明教学版和真实项目之间还差什么
配套示例文件
如果你更习惯“先打开代码文件，再对照文档阅读”，可以直接看：
这些示例是按章节整理的教学快照，目的是降低复制 Markdown 代码块的成本。它们依然是教学版，不是生产脚手架。