nanobot 🐈 项目文档库

超轻量级个人 AI 助手框架
~4,000 行核心代码 | Python 3.11+ | 全异步设计

执行摘要

项目基本信息

项目属性	值
项目名称	nanobot
项目描述	超轻量级个人 AI 助手框架
核心代码量	~4,000 行
主要语言	Python 3.11+
核心特性	LLM 工具调用、多渠道支持、子代理、技能系统

分析方法论

本项目采用 并行分析 + 价值驱动深挖 的分析方法论：

并行启动：6 个一级分析任务同时进行，覆盖架构的完整维度
价值驱动：基于一级分析识别的技术亮点，动态生成深挖任务
整合输出：最终整合报告提供全局视角和设计洞察

完成统计

总任务数: 9 (6 个一级 + 3 个深挖)
├── 已完成: 9 ✅
├── 进行中: 0
└── 待开始: 0

核心优势

维度	评估
架构复杂度	低 - 清晰的分层设计
扩展性	高 - 支持渠道、工具、技能、LLM 提供商扩展
性能	优秀 - 全异步设计，高效资源利用
可维护性	优秀 - 代码简洁，模块化清晰
创新点	渐进式技能加载、上下文注入、子代理工具隔离

核心架构报告

任务关系图

一级分析任务（6个）
    ├── task_001: Agent 核心机制
    ├── task_002: 消息总线与渠道架构
    ├── task_003: 工具系统设计
    ├── task_004: 会话与记忆系统
    ├── task_005: 子代理架构
    └── task_006: 扩展机制

一级分析任务

任务	名称	简要说明	覆盖维度
task_001	Agent 核心机制	主处理引擎、消息循环、上下文构建	核心执行流程、迭代机制
task_002	消息总线与渠道架构	队列设计、渠道实现、系统消息路由	多渠道支持、事件驱动架构
task_003	工具系统设计	工具抽象、内置工具、执行流程	工具调用能力、扩展接口
task_004	会话与记忆系统	JSONL 存储、双模式记忆、会话隔离	持久化、跨渠道数据管理
task_005	子代理架构	后台并行、工具隔离、结果公告	任务并行化、异步处理
task_006	扩展机制	技能系统、Cron 任务、心跳服务	系统扩展性、定时任务

深挖技术专题

任务依赖关系

task_007 ── task_003 (工具系统)
task_008 ── task_003 (工具系统)
task_009 ── task_003, task_006 (工具系统 + 扩展机制)

深挖任务详情

任务	名称	父任务	简要说明	技术亮点
task_007	异步化工具执行	task_003	全异步接口设计、Shell/HTTP 非阻塞执行	三层错误处理、超时控制
task_008	工具上下文注入机制	task_003	运行时动态注入、多渠道支持、子代理路由	上下文优先级、路由机制
task_009	渐进式技能加载	task_003, task_006	Always vs Available 分离、按需加载	节省 81% token 开销

最终整合报告

报告内容：

执行摘要与核心结论
6 个核心架构维度的详细分析
3 个深挖技术专题的深度解读
设计亮点与创新总结
关键指标统计与性能数据
适用场景与最佳实践

核心洞察：

nanobot 证明了：简洁的设计也能实现强大的功能。通过约 4,000 行核心代码，实现了完整的 AI 助手功能，包括多渠道聊天、工具调用、子代理并行、持久化记忆、定时任务、心跳服务等。

使用指南

📚 如何使用文档库

快速入门：从最终整合报告开始，了解全局架构
深入细节：根据兴趣选择对应的核心架构报告（task_001 ~ task_006）
技术深挖：研究深挖专题（task_007 ~ task_009）了解核心技术细节

🗂️ 目录导航说明

nanobot/
├── index.md          # 本文档 - 文档库入口
├── tasks/            # 一级分析和深挖任务报告
│   ├── task_001_*.md
│   ├── task_002_*.md
│   ├── ...
│   └── task_009_*.md
└── final/            # 最终整合报告
    └── summary.md

🔍 按角色阅读推荐

角色	推荐阅读顺序
架构师	最终整合报告 → task_001 → task_002 → task_005
开发者	task_001 → task_003 → task_007 → task_008
产品经理	最终整合报告 → task_002 → task_006
运维工程师	task_002 → task_004 → task_006

🎯 快速查找

想了解...	查看文档
nanobot 如何处理消息？	task_001
如何支持 Telegram/WhatsApp？	task_002
工具系统如何工作？	task_003
会话和历史如何存储？	task_004
子代理如何并行执行？	task_005
如何添加新技能？	task_006
异步执行如何实现？	task_007
上下文如何传递？	task_008
如何节省 token 开销？	task_009

项目特色

🎨 设计哲学

极简主义：仅约 4,000 行核心代码实现完整功能集
异步优先：全异步设计，高效资源利用
零配置：工具注册无需额外配置代码
错误即对话：将错误信息作为对话的一部分，让 LLM 理解并处理

⚡ 技术亮点

亮点	说明
渐进式技能加载	Always Skills + Available Skills，节省 81% token
工具上下文注入	运行时动态注入，支持多渠道和子代理
子代理工具隔离	防止递归创建，确保结果路由一致性
JSONL 存储	流式处理、易于追加、版本控制友好

📊 关键指标

指标	值
核心代码行数	~4,000 行
内置工具数量	9 个
聊天渠道支持	3+ (Telegram, WhatsApp, 可扩展)
LLM 提供商	7+ (支持 100+ 模型)
Token 节省	81% (20 技能场景)
最大工具迭代	20 (主代理) / 15 (子代理)