nanobot 源码深度解析与问题诊断

前言

近期在飞书平台部署了两个 nanobot 实例，经过三天的深度使用与源码研读（配合 AI 辅助），针对运行中遇到的实际问题进行了逻辑梳理。本文旨在记录核心架构理解及发现的潜在问题。

---

1. 建议阅读区域

Agent 核心与提示词注入

Agent 模块结构	提示词模板目录

---

2. 运行期间 API 调用上下文

通过抓包观察不同业务场景下的 Prompt 组装过程：

普通用户对话	Channel 渠道消息处理

Heartbeat 心跳检测	Dream 梦境记忆整理 (Phase 1 & 2)

---

核心一：System Prompt 组装工厂

身份定义与引导文件

identity.md (基础人设)	AGENTS.md (工作区规范)

Active Skills（常驻技能加载）

技能加载逻辑	技能内容示例

---

核心二: 上下文治理（Context Governance）流水线

流程概览	详细执行步骤

文件读取去重（Deduplication）与安全隔离

文件去重标记逻辑	防 Prompt 注入 “免责声明”

核心三： Dream（记忆整理服务）

两个处理阶段	游标（Cursor）追踪机制
游标存储位置

---

5. 总结与发现的问题

架构总结

nanobot 将会话分为定时任务会话和用户交互会话，统一存储在 workspace\sessions 目录下。

数据处理闭环：

1. 历史归档：自动检测并压缩工具调用的冗余输出，将长对话摘要后存入 workspace\memory\history.jsonl。
2. 记忆提炼：Dream 进程定期扫描 history.jsonl，提取关键事实转化为长期记忆（MEMORY.md）或自动化技能（skills/）。
3. 安全与优化：内置了文件读取去重、Prompt 注入隔离等机制以保障稳定性。

待解决的 Bug / 疑点

在双实例并行运行的环境下，观察到以下 4 个异常现象：

1. Token 预算判断失效：上下文压缩逻辑（Consolidation）未能按预期触发，疑似 context_window_tokens 的估算或边界检查存在逻辑漏洞。
2. 文件去重状态不一致：file_state 缓存标记文件已读，但实际发送给 LLM 的上下文中该文件内容已被裁剪（Snipping）丢失，导致 AI 无法获取必要信息却仍被阻止重新读取。
3. 路径解析兼容性：偶发读取错误文件地址的情况，可能与 Windows 环境下的路径分隔符处理或模型对相对路径的理解偏差有关。
4. 心跳文件职能重叠：HEARTBEAT.md 似乎已失去独立存在的意义，其记录的周期性任务状态正逐渐被 MEMORY.md 的记忆提取功能所覆盖。