nanobot 代码学习指南总览

项目概述

nanobot 是一个超轻量级的个人 AI 助手框架，受 Clawdbot 启发，用约 4,700 行代码实现了核心智能体（Agent）功能——比 Clawdbot 的 43 万行代码小 99%。

核心特性

  • 🪶 超轻量级：仅约 4,700 行代码
  • 🔬 研究友好：代码清晰易读，便于修改和扩展
  • ⚡️ 高效快速：启动快、资源占用低、迭代迅速
  • 💎 易于使用：一键部署即可使用

技术栈

  • 语言：Python 3.11+
  • 核心依赖：
    • LiteLLM：多 LLM 提供商支持
    • Typer：CLI 框架
    • Pydantic：数据验证
    • asyncio：异步处理
    • WebSockets：实时通信

学习路线图

本学习指南分为七个层次，从浅入深：

第一层：项目结构与入口（新手）

第二层：核心概念（初级）

第三层：Agent 核心（中级）

第四层：工具系统（中级）

第五层：高级特性（高级）

第六层：多渠道集成（高级）

第七层：扩展开发（专家）

推荐学习路径

路径 A：快速上手（2-3 小时）

适合想快速了解项目的开发者：

  1. 项目结构与架构（文档 01）
  2. CLI 命令入口（文档 02）
  3. Agent 核心循环（文档 05）
  4. 工具系统架构（文档 08）

路径 B：深入理解（1-2 天）

适合想深入理解所有机制的研究者：

  1. 按顺序阅读文档 01-15
  2. 结合源码进行验证
  3. 尝试修改和扩展功能

路径 C：扩展开发（3-5 天）

适合想基于 nanobot 开发的开发者：

  1. 先快速阅读文档 01-08
  2. 深入学习文档 16-18
  3. 实践开发自己的工具和技能

代码统计

总代码行数：约 4,700 行 Python
核心模块分布：
  - agent/          ~1,500 行（核心智能体逻辑）
  - tools/          ~800 行（工具实现）
  - providers/      ~500 行（LLM 提供商）
  - channels/       ~600 行（多渠道集成）
  - cli/            ~650 行（命令行接口）
  - 其他模块        ~650 行（配置、会话、定时等）

与 Clawdbot 的核心差异

维度 nanobot Clawdbot
代码量 ~4,700 行 ~430,000 行
复杂度 简洁、直接 功能丰富、复杂
学习曲线 平缓（1-2 天） 陡峭（1-2 周）
可读性 高 中等
扩展性 易于修改 需要深入理解架构
适用场景 研究、个人项目 生产环境、企业应用

如何使用本指南

  1. 从总览开始：阅读本文档了解整体结构
  2. 选择路径：根据你的目标选择合适的学习路径
  3. 边读边实践：在阅读文档的同时查看对应源码
  4. 动手修改：尝试修改代码以加深理解
  5. 创建扩展：开发自己的工具和技能

学习建议

前置知识

  • Python 基础（必须）
  • 异步编程概念（推荐）
  • LLM 基础知识（推荐）
  • 命令行使用（必须）

学习工具

  • IDE：推荐 VS Code 或 PyCharm
  • Python 版本：3.11 或更高
  • 终端：熟悉 bash/zsh
  • Git：用于代码版本管理

调试技巧

  1. 使用 --verbose 参数查看详细日志
  2. 在关键位置添加 logger.debug() 输出
  3. 使用 Python 调试器 (pdb) 单步执行
  4. 查看 ~/.nanobot/ 目录下的配置和会话文件

贡献与反馈

如果你在学习过程中发现：

  • 文档错误或不清晰的地方
  • 代码中的 bug 或改进建议
  • 想要贡献新的工具或技能

欢迎通过以下方式参与：

  • GitHub Issues
  • Pull Requests
  • 社区讨论（Discord、微信群、飞书群）

准备好了吗？让我们从第一层开始吧！ 👉 01-项目结构与架构.md