AI Agent Engineer

AI Agent Engineer

nanobot 源码学习路线总览

11 min read

nanobot 源码学习路线总览

这套文档的目标不是教你记住 nanobot 里有哪些类，而是帮助你逐步获得三种能力：

  1. 能从一个入口追踪一条消息，解释它如何变成最终回复；
  2. 能观察 session、上下文、工具调用和运行状态，定位常见问题；
  3. 能判断新能力应该放在 Tool、Skill、MCP、Provider、Channel 还是外围服务中，并完成最小扩展。

源码基线

所有 nanobot 实现事实均以当前工作区 example/nanobot/code-EN 的 v0.2.2 快照为准。公开网站不复制该源码；正文中的实现引用指向上游 v0.2.2 固定版本。仓库内官方文档用于核对公开用法，源码和测试用于核对实际行为。

中文优先

learning-CN 是权威版本；learning-EN 只按中文已经确认的结构、事实、图表和练习制作对应译文，不独立发展另一套课程。

文档与源码对照约定

除前置知识、纯导航和学习方法外，每篇涉及 nanobot 实现的文档都会在靠前位置列出“对应源码”：

  • nanobot 实现路径都相对于当前源码基线 example/nanobot/code-EN；学习练习和可修改示例若位于 example/nanobot/learning-CN/examples/，则按 vault 根目录路径标注；
  • 文件.py::Class.method 表示建议直接定位到的类或函数；
  • 目录表示该主题横跨一组遵循共同契约的实现；
  • 正文节选的代码是用于讲解的当前源码片段，理解完整分支时仍应回到原文件；
  • “对应测试”用于验证实现事实，不代表源码行为只能由这些测试覆盖。

代码节选不是可复制的新实现

节选会省略与当前概念无关的分支、类型或日志。省略处会明确说明，不能用节选替代原文件做修改依据。

这套文档不是什么

它不会重复完整的安装手册、Provider 配置表、Channel 接入清单、SDK/API 参数表或部署手册。遇到这些内容时，正文只解释理解源码所需的部分，并链接 nanobot 自带文档：

推荐学习路径

flowchart TD
    A["前置知识：Python、asyncio、LLM 消息与 Tool Calling"] --> B["最小运行：接入 DeepSeek，完成一次请求"]
    B --> C["项目全貌：入口、核心模块和源码地图"]
    C --> D["一次 Turn：AgentLoop 状态机"]
    D --> E["模型—工具循环：AgentRunner"]
    E --> F["状态与持久化：Session、Context、Memory"]
    F --> G["不同运行表面：CLI、Gateway、API、SDK、WebUI"]
    G --> H["工程与安全：并发、取消、重试、Workspace、SSRF"]
    H --> I["扩展开发：Tool、Skill、MCP、Provider、Channel"]
    I --> J["分级源码实践与复盘"]

文档库导航

阶段入口解决的核心问题
1前置知识需要会多少 Python、asyncio、LLM 消息与调试？
2运行与源码地图如何用隔离配置完成第一次请求，项目从哪里进入？
3一次 Turn（主要 Agent 架构）消息如何经过 Loop、Runner、Provider、Tool、保存和响应？
4状态与长期运行Session、压缩、Memory、Dream、Goal、Cron 和 Subagent 如何协作？
5运行表面Channel、Gateway、API、SDK、WebSocket 与 WebUI 如何复用核心？
6工程与安全并发、取消、错误、数据一致性、可观测性与安全边界在哪里？
7扩展开发新能力应做成 Tool、Skill、MCP、Provider、Channel 还是运行表面功能？
8源码实践如何通过观察、断点、测试和独立示例把理解变成能力？
随用随查速查参考怎样快速找到术语、源码、测试、配置、事件和排障入口？

可修改示例位于 example/nanobot/learning-CN/examples/。它与核心阅读任务分离，避免学习过程直接改动 code-EN 源码。

双语边界

中文始终先完成和确认，英文随后逐篇镜像；网站发布会校验一一对应关系与中文源哈希，任一英文页缺失或过期时停止构建。

第一阶段：先能运行和观察

从 前置知识地图 开始，然后进入“运行与源码地图”。这一阶段只要求：

  • 能运行 Python 命令；
  • 能看懂基本类、函数和 async def；
  • 知道 LLM 接口中的 messages、stream 和 tool call；
  • 能使用 DeepSeek key 完成一次真实请求。

不要求你掌握 React、MCP、复杂并发或生产部署。

第二阶段：吃透一次 Turn（主要 Agent 架构）

核心问题只有一个：

一条用户消息进入 nanobot 后，究竟经历了哪些状态、对象和异步边界？

这一阶段围绕以下源码展开：

职责主要源码
入站和出站消息nanobot/bus/events.py
消息队列nanobot/bus/queue.py
Turn 生命周期nanobot/agent/loop.py
模型—工具循环nanobot/agent/runner.py
上下文构建nanobot/agent/context.py
Provider 契约nanobot/providers/base.py
工具注册与执行nanobot/agent/tools/registry.py
Session 持久化nanobot/session/manager.py

第三阶段：理解状态与运行表面

掌握核心 Turn 后，再学习：

  • Session、Memory 和上下文不是同一个概念；
  • MessageBus 与 RuntimeEventBus 解决不同问题；
  • CLI、API、SDK、Channel 和 WebUI 复用核心 runtime 的方式不同；
  • Cron、Goal、Continuation 和 Subagent 分别处于什么边界。

第四阶段：调试和扩展

最后进入并发、取消、错误恢复、安全边界和扩展开发。建议顺序是：

  1. Tool；
  2. Skill；
  3. MCP；
  4. Provider；
  5. Channel；
  6. API、SDK 或 WebUI。

三条可选路线

路线 A：Agent 开发入门

适合还没有独立实现过 Agent 的读者。

阅读顺序：

  1. 前置知识；
  2. 最小运行；
  3. 项目全貌；
  4. 一次 Turn；
  5. Session 与上下文；
  6. Tool 扩展；
  7. 前四个实践任务。

路线 B：源码调试

适合已经会调用 LLM API，希望学会定位 nanobot 问题的读者。

阅读顺序：

  1. 入口与源码地图；
  2. AgentLoop 状态机；
  3. AgentRunner；
  4. Runtime Event；
  5. 异常、超时、取消与重试；
  6. Session 持久化；
  7. 测试和故障定位。

路线 C：扩展开发

适合已经理解核心 Turn，希望新增能力的读者。

阅读顺序：

  1. AgentLoop 与 AgentRunner 的职责边界；
  2. Tool、Skill、MCP 的区别；
  3. 工程和安全边界；
  4. 对应扩展文档；
  5. 对应实践任务。

如何阅读每篇文档

每篇核心文档都尽量回答以下问题：

  • 学习目标：学完后能够解释或完成什么；
  • 前置知识：需要掌握到什么程度；
  • 对应源码：阅读正文时应该同时打开哪些文件、类和函数；
  • 先建立的直觉：先用简单模型理解问题；
  • 源码事实：当前代码实际做了什么；
  • 调用链和状态变化：数据经过哪些步骤；
  • 源码与测试位置：从哪里继续核对；
  • 观察或验证方法：如何亲自看到这些行为；
  • 边界和误区：哪些结论不能过度推广。

证据规则

文档中的陈述分为五类：

标记含义
源码事实可以直接从当前 code-EN 源码或测试证明
官方文档事实由当前仓库内官方文档明确说明
Agent 通用知识不依赖 nanobot 的通用概念
设计解读根据实现作出的解释，不冒充维护者原意
待确认当前材料不足，不能给出确定结论

不从名称猜行为

类名、配置字段或文档标题只能提供线索。写入结论前，还要核对实际调用方、状态变化和测试。

学习完成标准

完成核心路线后，你应当能够：

  • 画出一次普通 Turn 和一次 Tool Call Turn 的时序图；
  • 解释 AgentLoop 与 AgentRunner 的职责区别；
  • 区分消息队列、运行事件、Session、Memory 和模型上下文；
  • 从 CLI、API 或 SDK 入口追踪到 process_direct() 或消息总线；
  • 找到模型选择、Provider 创建和 fallback 的代码；
  • 找到 Tool 的 schema 校验、执行和结果回填位置；
  • 解释同 session 串行、跨 session 并发的原因和实现位置；
  • 使用最小测试或断点验证自己的判断；
  • 判断一个扩展应该进入核心、Tool、Skill、MCP、Provider 还是 Channel。

下一步

进入 前置知识地图，先确认自己需要补哪些基础。

9 items under this folder.