Nanobot源码解析(二):系统提示词与Message构建

1. 总体流程图

图有点大左右滑动一下

┌──────────────────────────────────────────────────────────────────────┐
│  Channel (Telegram/Discord/CLI/...)                                  │
│  └─→ publish_inbound(InboundMessage) → MessageBus                   │
└──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  AgentLoop.run (loop.py:1154)                                        │
│   consume_inbound() → _process_message(msg) → TurnContext           │
└──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  AgentLoop._build_initial_messages (loop.py:721)                     │
│   └─→ ContextBuilder.build_messages(history, current_message, …)     │
└──────────────────────────────────────────────────────────────────────┘
                                  │
        ┌─────────────────────────┴─────────────────────────┐
        ▼                                                   ▼
┌────────────────────────────┐                ┌──────────────────────────┐
│  build_system_prompt       │                │  history (Session)       │
│  (context.py:82)           │                │  + current_message       │
│                            │                │  (build_current_message) │
│  ┌──────────────────────┐  │                └──────────────────────────┘
│  │ 1. identity.md       │  │
│  │    + platform_policy │  │
│  │ 2. AGENTS.md/SOUL.md │  │
│  │    /USER.md          │  │
│  │ 3. tool_contract.md  │  │
│  │ 4. memory/MEMORY.md  │  │
│  │ 5. Active Skills     │  │
│  │ 6. Skills summary    │  │
│  │ 7. Recent History    │  │
│  │ 8. Archived Summary  │  │
│  └──────────────────────┘  │
│  joined with "\n\n---\n\n" │
└────────────────────────────┘
        │                                                   │
        └─────────────────────────┬─────────────────────────┘
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  messages = [                                                        │
│    {role:"system", content: <long system prompt>},                   │
│    *history,                                                         │
│    {role:"user", content: <current + media + runtime context>},      │
│  ]                                                                   │
└──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  AgentRunner._request_model (runner.py:919)                          │
│   _build_request_kwargs: { messages, tools, model, … }               │
│   tools = ToolRegistry.get_definitions()                             │
│     (built-in tools sorted, then MCP tools sorted)                   │
└──────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  LLMProvider.chat_with_retry / chat_stream_with_retry                │
│   (base.py:854-958)                                                  │
└──────────────────────────────────────────────────────────────────────┘
                                  │
        ┌─────────────────────────┴─────────────────────────┐
        ▼                                                   ▼
┌────────────────────────────┐                ┌──────────────────────────┐
│  Anthropic                 │                │  OpenAI-Compatible        │
│  _convert_messages:        │                │  messages 透传            │
│    抽 system → 顶级 system  │                │  + _sanitize_messages    │
│  + _apply_cache_control    │                │  (may use /responses API) │
│  + _convert_tools          │                └──────────────────────────┘
└────────────────────────────┘
        │                                                   │
        └─────────────────────────┬─────────────────────────┘
                                  ▼
                          ┌──────────────┐
                          │   LLM API    │
                          └──────────────┘

2. system prompt

nanobot 的 system prompt 是 由 ContextBuilder 统一管理、按 markdown 段落拼接的模块化系统：

• • 入口在 nanobot/agent/context.py:82 的 ContextBuilder.build_system_prompt()；
• • 8 个 section 按固定顺序拼装，段间用 "\n\n---\n\n" 连接；
• • 最终与 session 历史、当前 user 消息 一起被 ContextBuilder.build_messages()
  打包成 OpenAI 风格的 messages: list[dict]；
• • 在 AgentRunner._request_model() 中与 tools: list[dict] 合并，调用
  LLMProvider.chat_with_retry()；
• • 各 provider 在自己内部把 system 消息 翻译 成各 LLM 协议（Anthropic 拆为
  顶级 system 参数，Responses API 拆为 instructions 等）；
• • Tools 不进入 system prompt 文本，而是以独立的 tools=[...] 字段发给 LLM；
• • Runtime context（持续目标、CLI app 附件等）也 不进入 system prompt，
  而是拼到当前 user 消息末尾并用特殊 tag 包裹，方便持久化时剥离。

3. 模板目录（所有 system prompt 文本来源）

4. system prompt

最终拼接："\n\n---\n\n".join(parts)（nanobot/agent/context.py:141）

5. Messages 完整组装流程

ContextBuilder.build_messages()（nanobot/agent/context.py:220-279）的产物：

messages = [
    { "role": "system", "content": build_system_prompt(...) },   # 一条超长 system
    *history,                                                     # 当前 session 的历史
    { "role": "user", "content": build_current_message(...) }    # 当前 user（含图片、runtime context）
]

关键调用栈：

1. 1. AgentLoop._build_initial_messages()（loop.py:721-737）— 调用
   self.context.build_messages(...) 拿到 initial_messages；
2. 2. ContextBuilder.build_messages()（context.py:220-279）— 装配 system + history，
   然后调 build_current_message()；
3. 3. ContextBuilder.build_current_message()（context.py:281-298）— 拼出当前 user
   消息，若 messages[-1].role == current_role，则合并到最后一条（context.py:265-277）；
4. 4. AgentRunner._run_core()（runner.py:419-861）— 拿到 initial_messages 后调
   context_governor.prepare_for_model() 治理；
5. 5. AgentRunner._request_model()（runner.py:919+）— 进入循环调
   _build_request_kwargs()；
6. 6. AgentRunner._build_request_kwargs()（runner.py:875-893）— 打包
   messages + tools + model + temperature + max_tokens + reasoning_effort + tool_choice；
7. 7. LLMProvider.chat_with_retry() / chat_stream_with_retry()（base.py:854-958）— 调 _run_with_retry；
8. 8. 各 provider 的 _build_kwargs()：
• • Anthropic（anthropic_provider.py:574-649）：_convert_messages()把
  system 消息从 messages 列表中抽出，变成顶级 system 参数；tools 通过
  _convert_tools() 转 Anthropic schema；可选加 cache_control: ephemeral；
• • OpenAI-compatible（openai_compat_provider.py:807-940）：messages
  透传，可能分流到 /responses API；
• • Bedrock（bedrock_provider.py:287-432）：类似 Anthropic 路径。