jeremymoo1. 项目概述：Nanobot源码架构解析
OpenClaw作为当前AI助手领域的重要开源项目，其完整代码库规模庞大（约40万行），直接学习成本较高。而Nanobot作为香港大学数据科学实验室（HKUDS）开源的超轻量级个人AI助手框架，定位为"Ultra-Lightweight OpenClaw"，其代码结构清晰、功能完整，是学习现代AI Agent架构的理想切入点。
Nanobot的核心价值在于：
- 模块化设计：各组件职责明确，接口定义清晰
- 轻量级实现：核心功能仅需3500行代码即可完整实现
- 完整Agent闭环：包含上下文管理、工具调用、记忆存储等关键子系统
- 可扩展架构：通过技能(Skill)机制支持功能扩展
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心架构解析
2.1 上下文构建系统（ContextBuilder）
ContextBuilder是Nanobot架构中最核心的组件之一，负责将分散的身份定义、记忆存储、技能系统和运行时信息整合为标准化的LLM对话上下文。其设计哲学体现了现代AI Agent系统的几个关键原则：
-
分层提示词工程：系统提示词按优先级分为多个层次：
- 身份核心（最高优先级）
- 引导文件（行为准则）
- 长期记忆
- 常驻技能
- 技能摘要
-
多源信息融合：整合了以下多种信息源：
python复制class ContextBuilder: BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md", "IDENTITY.md"] def build_system_prompt(self): parts = [ self._get_identity(), # 身份定义 self._load_bootstrap_files(), # 引导文件 self.memory.get_memory_context(), # 记忆系统 self.skills.get_always_skills(), # 常驻技能 self.skills.build_skills_summary() # 技能摘要 ] return "\n\n---\n\n".join(filter(None, parts)) -
运行时隔离设计：通过明确的标签区分指令性内容和元数据：
python复制_RUNTIME_CONTEXT_TAG = "[Runtime Context — metadata only, not instructions]"
2.2 关键设计亮点
2.2.1 模块化引导系统
Nanobot采用Markdown文件定义Agent的核心行为，这种设计既易于人类编辑，又保持了机器可读性：
AGENTS.md：操作手册（工具使用规则、安全策略）SOUL.md：性格定义（语气、沟通风格）USER.md：用户画像（称呼、偏好）TOOLS.md：本地工具说明IDENTITY.md：基础身份设定
示例SOUL.md内容：
markdown复制# Soul
I am nanobot 🐈, a personal AI assistant.
## Personality
- Helpful and friendly
- Concise and to the point
- Curious and eager to learn
2.2.2 技能管理系统
技能(Skill)是Nanobot的功能扩展单元，每个技能包含：
SKILL.md：技能描述和使用说明- 实现代码（Python或其他语言）
- 元数据（通过YAML frontmatter定义）
技能加载器(SkillsLoader)会扫描工作区中的技能目录，并提供两种使用模式：
- 常驻技能（always=true）：直接嵌入系统提示词
- 按需技能：通过摘要形式提供，需要时通过
read_file工具读取
2.2.3 记忆系统设计
MemoryStore实现了双层记忆存储：
- 长期记忆（MEMORY.md）：结构化Markdown格式
- 对话历史（HISTORY.md）：JSONL格式日志
记忆检索采用TF-IDF算法实现内容召回，确保相关记忆能自动注入当前对话上下文。
3. 核心流程实现
3.1 消息处理流程
完整的消息处理包含以下步骤：
- 上下文构建
- LLM交互
- 工具执行（可选）
- 结果处理
- 记忆更新
关键代码流程：
python复制async def _process_message(self, msg: InboundMessage):
# 构建完整对话上下文
messages = self.context.build_messages(
history=history,
current_message=msg.content
)
# 执行Agent循环
final_content, _, all_msgs = await self._run_agent_loop(messages)
# 保存对话回合
self._save_turn(session, all_msgs)
return OutboundMessage(content=final_content)
3.2 Agent执行循环
_run_agent_loop实现了Agent的核心推理-行动循环：
python复制async def _run_agent_loop(initial_messages):
messages = initial_messages
while iteration < max_iterations:
# 调用LLM获取响应
response = await self.provider.chat(messages)
if response.has_tool_calls:
# 添加助手消息（含工具调用）
messages = self.context.add_assistant_message(
messages, response.content, tool_call_dicts
)
# 执行每个工具调用
for tool_call in response.tool_calls:
result = await self._execute_tool(tool_call)
messages = self.context.add_tool_result(
messages, tool_call.id, tool_call.name, result
)
else:
# 添加普通助手回复
messages = self.context.add_assistant_message(
messages, response.content
)
return final_content, tools_used, messages
4. 高级特性与实现技巧
4.1 多模态支持
ContextBuilder内置了对图片等多媒体内容的支持，会自动将图片转为Base64编码：
python复制def _build_user_content(self, text: str, media: list[str] | None):
if not media:
return text
images = []
for path in media:
mime, _ = mimetypes.guess_type(path)
if not Path(path).is_file() or not mime.startswith("image/"):
continue
b64 = base64.b64encode(Path(path).read_bytes()).decode()
images.append({
"type": "image_url",
"image_url": {"url": f"data:{mime};base64,{b64}"}
})
return images + [{"type": "text", "text": text}]
4.2 工具调用管理
Nanobot的工具调用系统遵循以下设计原则：
- 声明式定义：通过工具描述文件定义接口
- 结果验证：自动检查工具执行结果
- 错误处理：提供标准的错误反馈机制
工具结果添加示例：
python复制def add_tool_result(self, messages, tool_call_id, tool_name, result):
messages.append({
"role": "tool",
"tool_call_id": tool_call_id,
"name": tool_name,
"content": result
})
return messages
5. 实践建议与优化方向
5.1 部署优化建议
-
工作区规划：
- 保持技能目录结构清晰
- 定期清理历史日志
- 对重要记忆进行版本控制
-
性能调优：
python复制# 限制引导文件大小 def _load_bootstrap_files(self): for filename in self.BOOTSTRAP_FILES: file_path = self.workspace / filename if file_path.exists(): content = file_path.read_text(encoding="utf-8")[:20000] # 限制单文件20k parts.append(f"## {filename}\n\n{content}")
5.2 扩展开发建议
-
自定义技能开发：
- 遵循SKILL.md规范
- 包含清晰的YAML frontmatter
- 提供使用示例
-
记忆系统增强：
- 实现基于向量的记忆检索
- 添加记忆重要性评分
- 支持记忆自动归档
-
上下文优化：
python复制# 动态上下文窗口管理 def build_system_prompt(self): parts = [...] # 标准部分 total_length = sum(len(p) for p in parts) if total_length > 150000: # 150k token限制 parts = self._truncate_parts(parts) return "\n\n---\n\n".join(parts)
6. 典型问题排查
6.1 常见问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 技能未加载 | SKILL.md格式错误 | 检查YAML frontmatter |
| 记忆未召回 | TF-IDF参数不当 | 调整相似度阈值 |
| 工具调用失败 | 权限问题 | 检查工具执行环境 |
| 响应速度慢 | 上下文过大 | 优化提示词分层 |
6.2 调试技巧
-
上下文检查：
python复制# 打印完整系统提示词 print(context.build_system_prompt()) -
消息跟踪：
python复制# 记录完整消息流 with open("message_flow.json", "w") as f: json.dump(messages, f, indent=2) -
记忆调试：
python复制# 检查记忆检索结果 recalled = memory.search("query") print(f"Recalled memories: {recalled}")
通过Nanobot源码学习，我们可以深入理解现代AI Agent系统的核心设计理念和实现细节。其模块化架构、清晰的接口定义和实用的工程实践，为开发者构建自己的AI助手提供了宝贵参考。