跳转到主要内容

​
上下文概览

本页介绍 SimpleLLMFunc 如何编译上下文——即 LLM 在每个推理步骤中所看到的信息。最终发送给提供商的消息列表来自 invocation 配置、基础对话记录和内部运行时补丁。

​
核心数据结构

​
ContextState

对话当前状态的运行时表示： 
@dataclass
class ContextState:
    messages: NormalizedMessageList           # The conversation transcript
    data_from_selfref: Optional[DataFromSelfRef]  # Durable self-reference state
    pending_mutations: List[ContextMutation]  # Changes waiting to be applied
  • messages 是当前运行状态的基础对话记录——包含助手消息、工具结果、用户消息
  • data_from_selfref 承载来自 SelfReference 后端的持久状态（经验、摘要）
  • pending_mutations 在 ReAct 迭代期间积累内部运行时补丁，在下一个编译边界统一应用到对话记录

​
CompileSource

输入边界——生成 LLM 请求所需的全部信息： 
@dataclass(frozen=True)
class CompileSource:
    data_from_agent_config: DataFromAgentConfig  # Static: system prompt, tool specs
    data_from_selfref: Optional[DataFromSelfRef] # Durable: experiences, summaries
    input_messages: NormalizedMessageList         # Dynamic: conversation messages

​
DataFromAgentConfig

来自装饰器的静态配置： 
@dataclass(frozen=True)
class DataFromAgentConfig:
    base_system_prompt: str                    # From docstring (possibly templated)
    template_params: Optional[Dict[str, Any]]  # Runtime template values
    tool_prompt_specs: List[Dict[str, Any]]    # Tool best-practice injections
    include_must_principles: bool              # Whether to add structured-call rules

​
DataFromSelfRef

来自 SelfReference 后端的持久状态： 
@dataclass(frozen=True)
class DataFromSelfRef:
    base_system_prompt: str                    # System prompt with selfref markers
    experiences: List[Dict[str, str]]          # Durable remembered experiences
    summary: Optional[Dict[str, Any]]          # Compaction summary metadata
    summary_message: Optional[Dict[str, Any]]  # The summary as a message
    working_messages: NormalizedMessageList     # Post-compaction working transcript

​
上下文输入

SimpleLLMFunc 并不是只从 mutation 构建 LLM 上下文。每次 LLM 请求都从三类输入编译而来：
  1. Invocation 配置 —— 由装饰器函数、docstring、模板参数、工具指导、返回模式和 SelfRef 快照构成的 InvocationSpec / prompt contract。
  2. 基础对话记录 —— 从 history / chat_history、当前用户输入以及之前最终消息构建出的 message list。
  3. 运行时补丁 —— LLM 调用、工具、SelfRef 原语、压缩以及中断/取消处理在内部产生的 ContextMutation 对象。
provider messages = render(invocation config, patch(base transcript, runtime patches))

​
数据流：从你的代码到 LLM

┌─ 你的代码 ────────────────────────────────────────────────┐
│                                                           │
│  @llm_chat(llm_interface=llm, toolkit=[...])             │
│  async def agent(message: str, history: list):            │
│      """System prompt here."""                            │
│      pass                                                 │
│                                                           │
│  async for output in agent("hello", history):             │
│      ...                                                  │
│                                                           │
└───────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ 装饰器层 ──────────────────────────────────────────────┐
│                                                           │
│  构建 InvocationSpec：                                    │
│    - 解析 docstring → base_system_prompt                  │
│    - 收集工具规格 → tool_prompt_specs                      │
│    - 解析 template_params                                 │
│    - 根据 history + 用户消息构建初始对话记录                  │
│                                                           │
└───────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ ReAct 循环 ─────────────────────────────────────────────┐
│                                                           │
│  while has_more_work:                                     │
│                                                           │
│    1. 收集 hook mutation（selfref 等）                     │
│    2. compile_context(state, pending_mutations)           │
│         → apply_mutations → CompiledContext               │
│    3. compile_invocation_turn(spec, messages, [], selfref)│
│         → reduce + convert → CompiledTurnContext          │
│    4. execute_single_llm_phase(compiled.llm_messages)     │
│         → 产出事件 + 生成 mutation                         │
│    5. 如有工具调用：schedule_tool_batch(...)                │
│         → 执行工具 → 生成 mutation                         │
│    6. 合并所有 mutation → 回到步骤 1                       │
│                                                           │
└───────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─ 接口层 ─────────────────────────────────────────────────┐
│                                                           │
│  OpenAICompatible.chat_stream(messages=[...])             │
│  → 向提供商发送 HTTP 请求                                  │
│  → 流式返回响应                                           │
│                                                           │
└───────────────────────────────────────────────────────────┘

​
关键不变量

  1. Runtime 副作用不直接编辑 live transcript — LLM 调用、工具、SelfRef 原语和中断处理会产生 ContextMutation 补丁，而不是原地修改 ContextState.messages。
  2. Mutation 是对话记录补丁，不是完整上下文 — docstring、模板参数、工具指导、SelfRef 快照和初始 history 来自 invocation 配置和基础对话记录。
  3. Mutation 先积累，再原子化应用 — 在一次 ReAct 迭代中，运行时补丁积累在 pending_mutations 中，在编译边界统一应用。
  4. 编译产生快照 — 编译输出是一份克隆。原始状态永远不会被原地修改。
  5. SelfRef 状态持续传播 — DataFromSelfRef 在编译过程中向前传递。如果 mutation 应用后的对话记录中检测到 selfref 标记，快照会被刷新。
  6. 系统提示词的解析优先级：
    • SelfRef 快照（如果存在）→ 渲染基础提示词 + 经验
    • PromptContract.system_prompt（如果显式设置）
    • 对话记录中最新的系统消息
    • PromptContract.base_instruction（docstring 兜底）

​
下一步

运行时补丁

内部 mutation 类型——runtime 何时产生对话记录补丁。

编译管道

invocation 配置、对话记录和补丁如何变成最终的 LLM 请求。