学习笔记nanobot 源码分析

1. 模块概述

ContextBuilder（nanobot/agent/context.py）负责为每次 LLM 调用构建完整的消息列表——包括系统提示（身份、记忆、技能）和用户消息（含运行时上下文、媒体附件）。

📍 源码：nanobot/nanobot/agent/context.py#L1-L281

1.1 系统提示的组成部分

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
┌──────────────────────────────────────┐
│ 1. Identity (身份 + 运行时环境)       │
├──────────────────────────────────────┤
│ 2. Bootstrap Files                   │
│    AGENTS.md / SOUL.md / USER.md     │
├──────────────────────────────────────┤
│ 3. Tool Contract (工具使用规范)       │
├──────────────────────────────────────┤
│ 4. Memory (MEMORY.md 长期记忆)        │
├──────────────────────────────────────┤
│ 5. Always Skills (始终激活的技能)      │
├──────────────────────────────────────┤
│ 6. Skills Summary (可用技能摘要)       │
├──────────────────────────────────────┤
│ 7. Recent History (最近历史注入)       │
├──────────────────────────────────────┤
│ 8. Session Summary (归档摘要)          │
└──────────────────────────────────────┘

1.2 用户消息的组成部分

1
2
3
4
5
6
7
8
9
10
11
12
┌──────────────────────────────────────┐
│ 用户文本内容                          │
│ + 媒体附件 (base64 图片)              │
├──────────────────────────────────────┤
│ Runtime Context (追加在文本末尾)       │
│   Current Time: 2026-06-19 10:30    │
│   Channel: telegram                  │
│   Chat ID: 12345                     │
│   Sender ID: user_abc                │
│   Goal State Lines (如有)            │
│   CLI App / MCP Runtime Lines        │
└──────────────────────────────────────┘

2. 命名体系与易混淆函数对比

2.1 命名规律拆解

前缀 操作对象 操作 含义
build_ system_prompt — 构建系统提示
build_ messages — 构建完整消息列表
_build_ user_content — 构建用户消息内容（含图片）
_build_ runtime_context — 构建运行时上下文元数据块
_get_ identity — 获取身份部分
_load_ bootstrap_files — 加载引导文件
_is_ template_content — 检查是否仍是模板内容
_merge_ message_content — 合并消息内容

2.2 易混淆函数对比表

对比维度 build_system_prompt build_messages
返回值 单一字符串（系统提示） 消息列表 [{role, content}]
包含历史 ❌ ✅ 包含 history 参数
包含运行时上下文 ❌ ✅ 追加 Runtime Context
调用频率 每次 build_messages 内部调用 每个 turn 一次
一句话区分 build_system_prompt 构建 system 角色的提示 build_messages 构建完整的消息列表

3. API Signatures

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class ContextBuilder:
    BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md"]

    def __init__(self, workspace, timezone=None, disabled_skills=None):
        # 初始化 MemoryStore 和 SkillsLoader
        # 场景：AgentLoop.__init__

    def build_system_prompt(
        self, skill_names=None, channel=None,
        session_summary=None, workspace=None,
        include_memory_recent_history=True,
        session_key=None, unified_session=False,
    ) -> str:
        # 构建系统提示（8 个部分）
        # 场景：build_messages() 内部调用

    def build_messages(
        self, history, current_message, *,
        skill_names=None, media=None,
        channel=None, chat_id=None,
        current_role="user", sender_id=None,
        session_summary=None, session_metadata=None,
        current_runtime_lines=None, workspace=None,
        runtime_state=None, inbound_message=None,
        skip_runtime_lines=False,
        include_memory_recent_history=True,
        session_key=None, unified_session=False,
    ) -> list[dict[str, Any]]:
        # 构建完整的 LLM 消息列表
        # 场景：AgentLoop._build_initial_messages() 和 _process_system_message()

4. 数据结构深度解析

4.1 ContextBuilder

4.a 结构体存在的理由

ContextBuilder 将提示构建的所有关注点集中在一起：身份定义、引导文件加载、记忆注入、技能注入和历史注入。如果没有这个类，这些逻辑将分散在 AgentLoop 的各个方法中，导致提示构建逻辑难以理解和维护。

4.b 字段三层分析表

字段 设计动机 反事实 替代方案
BOOTSTRAP_FILES 定义需要加载的引导文件列表 硬编码在 _load_bootstrap_files 中 可以配置化，但引导文件是框架约定
memory 持有 MemoryStore 实例，复用文件 I/O 每次构建提示时重新创建 MemoryStore 可以用单例，但参数注入更清晰
skills 持有 SkillsLoader 实例，管理技能发现和加载 每次构建提示时重新扫描技能 可以缓存技能内容，但 SkillsLoader 已内置缓存
_RUNTIME_CONTEXT_TAG 标记运行时上下文的起止边界 无法在持久化时剥离运行时上下文 可以用特殊分隔符，但明确的标记更易解析

5. 函数逐行精讲

5.1 build_system_prompt() — 系统提示构建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def build_system_prompt(self, skill_names=None, channel=None, ...):
    # → 构建完整的系统提示字符串
    root = workspace or self.workspace
    parts = [self._get_identity(channel=channel, workspace=root)]
    # → 第 1 部分：身份 + 运行时环境 + 平台策略

    bootstrap = self._load_bootstrap_files(root)
    if bootstrap:
        parts.append(bootstrap)
    # → 第 2 部分：AGENTS.md / SOUL.md / USER.md

    parts.append(render_template("agent/tool_contract.md"))
    # → 第 3 部分：工具使用规范（固定模板）

    memory = self.memory.get_memory_context()
    if memory and not self._is_template_content(...):
        parts.append(f"# Memory\n\n{memory}")
    # → 第 4 部分：长期记忆（如果用户已自定义）

    always_skills = self.skills.get_always_skills()
    if always_skills:
        always_content = self.skills.load_skills_for_context(always_skills)
        if always_content:
            parts.append(f"# Active Skills\n\n{always_content}")
    # → 第 5 部分：始终激活的技能（如 cron、memory）

    skills_summary = self.skills.build_skills_summary(exclude=set(always_skills))
    if skills_summary:
        parts.append(render_template("agent/skills_section.md", skills_summary=skills_summary))
    # → 第 6 部分：可用技能摘要

    if include_memory_recent_history:
        entries = self.memory.read_recent_history_for_prompt(...)
        if entries:
            capped = entries[-self._MAX_RECENT_HISTORY:]  # → 最多 50 条
            history_text = truncate_text_to_tokens(history_text, self._MAX_HISTORY_TOKENS)
            # → 限制 8000 Token
            parts.append("# Recent History\n\n" + history_text)
    # → 第 7 部分：最近历史（Dream 已处理但未注入的）

    if session_summary:
        parts.append(f"[Archived Context Summary]\n\n{session_summary}")
    # → 第 8 部分：归档上下文摘要

    return "\n\n---\n\n".join(parts)
    # → 用分隔符连接所有部分

5.2 build_messages() — 完整消息组装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def build_messages(self, history, current_message, ...):
    # → 构建发送给 LLM 的完整消息列表

    # 1. 收集运行时上下文行
    extra = [
        *goal_state_runtime_lines(session_metadata),
        # → 持续目标状态行
    ]
    if runtime_state is not None and inbound_message is not None:
        extra.extend(runtime_lines(runtime_state, inbound_message, root, skip=skip_runtime_lines))
        # → CLI Apps + MCP 运行时行

    # 2. 构建运行时上下文块
    runtime_ctx = self._build_runtime_context(channel, chat_id, self.timezone, ...)
    # → 格式：[Runtime Context — metadata only, not instructions]
    # →       Current Time: ... / Channel: ... / Chat ID: ...

    # 3. 构建用户消息内容（文本 + 图片）
    user_content = self._build_user_content(current_message, media)
    # → 如果有图片附件，生成 image_url 块

    # 4. 合并用户内容和运行时上下文
    if isinstance(user_content, str):
        merged = f"{user_content}\n\n{runtime_ctx}"
    else:
        merged = user_content + [{"type": "text", "text": runtime_ctx}]
    # → 合并为一个 user 消息，避免连续同角色消息

    # 5. 组装最终消息列表
    messages = [
        {"role": "system", "content": self.build_system_prompt(...)},
        *history,
    ]
    # 如果最后一条消息角色与 current_role 相同，合并内容
    if messages[-1].get("role") == current_role:
        last = dict(messages[-1])
        last["content"] = self._merge_message_content(last.get("content"), merged)
        messages[-1] = last
    else:
        messages.append({"role": current_role, "content": merged})

    return messages

6. 关键算法剖析

6.1 运行时上下文注入

运行时上下文（Runtime Context）是一个关键的架构设计。它被追加在用户消息末尾，用明确的 [Runtime Context] 标记包裹：

1
2
3
4
5
6
[Runtime Context — metadata only, not instructions]
Current Time: 2026-06-19 10:30:00 +0800
Channel: telegram
Chat ID: 12345
Sender ID: user_abc
[/Runtime Context]

设计要点：

  • 标记为”metadata only, not instructions”以防止 LLM 将其视为用户指令
  • 在持久化时被剥离（_RUNTIME_CONTEXT_TAG 用于识别起止边界）
  • 与用户内容合并为一个 user 消息，避免角色交替问题

7. 设计决策分析

7.1 为什么运行时上下文追加在用户消息末尾而不是作为独立的 system 消息？

决策：运行时上下文（时间、渠道、发送者）与用户内容合并为同一个 user 消息。

权衡：

  • ✅ 避免 system 消息在对话中途出现（许多 Provider 不支持或行为不一致）
  • ✅ 保持消息列表简洁（减少消息数）
  • ❌ 运行时上下文在持久化时需要特殊处理来剥离
  • ❌ 可能影响 prompt cache 命中（时间每次不同）

7.2 为什么模板内容检测（_is_template_content）很重要？

决策：如果 MEMORY.md 内容与模板完全相同（用户未自定义），则不注入到系统提示。

权衡：

  • ✅ 减少无效 Token 消耗
  • ✅ 防止 LLM 将模板指令误认为用户的真实记忆
  • ❌ 如果用户恰好写了与模板相同的内容，会被忽略

8. 学习检查点

📝 本章小结

  1. 系统提示由 8 个部分组成：身份、引导文件、工具规范、记忆、技能、技能摘要、最近历史、归档摘要
  2. 运行时上下文包含时间、渠道、发送者等元数据，追加在用户消息末尾
  3. 模板内容检测避免将未自定义的模板注入系统提示
  4. 消息合并确保不产生连续同角色消息（Provider 兼容性）

🤔 思考题

  1. 为什么 build_messages 要将运行时上下文和用户内容合并为一个消息，而不是分开发送？

    参考答案

    合并（nanobot/nanobot/agent/context.py#L226-L232）是为了避免两个连续的 user 消息。许多 Provider 拒绝或行为异常当遇到连续的同角色消息。同时，合并确保运行时上下文紧跟在用户文本之后，LLM 将它们视为同一轮输入，更自然地将”在 Telegram 频道中，用户 X 在 10:30 说：…”作为整体理解。

  2. 为什么最近历史注入（Recent History）限制为 50 条和 8000 Token？

    参考答案

    50 条（nanobot/nanobot/agent/context.py#L57）和 8000 Token（nanobot/nanobot/agent/context.py#L58）是经验性平衡：太少则 Dream 处理后的历史信息不足，太多则挤占对话历史的上下文空间。最近历史是从 history.jsonl 注入的已处理摘要，不是原始对话——它提供的是”过去发生过什么”的背景信息，不需要像当前对话那样完整保留。