> ## Documentation Index
> Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 以上下文为中心

> LLM 上下文如何由 invocation 配置、对话记录和运行时补丁编译而来

# 以上下文为中心

SimpleLLMFunc 不把 provider messages 当作一个任由各组件直接编辑的列表。每次 LLM 调用都会从三类输入编译出发送给提供商的消息列表：

1. **Invocation 配置** —— docstring 提示词、模板参数、工具指导、输出契约、SelfRef 快照。
2. **基础对话记录** —— 本次调用的 history / 当前消息。
3. **运行时对话记录补丁** —— LLM 调用、工具执行、SelfRef 原语、中断处理和压缩产生的内部类型化编辑。

更准确地说：

```text theme={null}
provider messages = render(invocation config, patch(base transcript, runtime patches))
```

## 问题

在很多 Agent 系统中，"上下文"就是一个被到处修改的消息列表：

* 工具直接追加结果；
* 编排循环直接塞入助手消息；
* 记忆系统在任意位置注入内容；
* 摘要器就地覆盖历史；
* 中断/取消处理留下半合法的消息结构。

结果是上下文不可预测：很难回答“下一次模型到底会看到什么”。

## 运行时补丁模型

SimpleLLMFunc 使用 `ContextMutation` 作为**内部对话记录补丁协议**。

Mutation 不是完整上下文，也不是主要用户 API。它只是 runtime 副作用对基础对话记录产生的类型化增量编辑，并且只在编译边界统一应用。

```text theme={null}
runtime 副作用 → ContextMutation → [累积] → 应用到 transcript → 渲染 LLM 请求
```

例子：

| 运行时事实           | 内部补丁                           |
| --------------- | ------------------------------ |
| LLM 产生最终助手消息    | `AssistantMessageMutation`     |
| 工具返回文本          | `ToolResultMutation`           |
| 工具返回多模态内容       | `MultimodalToolResultMutation` |
| SelfRef 压缩工作上下文 | `ContextSummaryMutation`       |
| 用户中断 LLM 流式输出   | `AssistantTruncatedMutation`   |
| 工具执行被取消         | `ToolCancelledMutation`        |

核心规则是：

> Runtime 副作用不能直接修改 live transcript。它们只能产生类型化补丁，并由编译边界按顺序应用。

## Mutation 不是什么

Mutation 的范围是有意收窄的。

它不是：

* docstring / 系统提示词的来源；
* 模板参数的来源；
* 工具 schema 或工具最佳实践提示的来源；
* `@llm_chat` 初始 `history` 的来源；
* UI 消费的 public event stream；
* 用户自定义 Agent 的主要入口。

这些分别属于 invocation 配置、基础对话记录、工具、SelfRef 原语或事件消费者。

## 为什么仍然重要

### 安全并发

多个工具可以并行完成。工具不直接写共享消息列表，而是产生结果补丁；运行时在下一个编译边界统一应用。

### 可控压缩

上下文压缩是一个对话记录补丁。它可以用摘要替换过期工作消息，同时保留系统提示词和持久经验。

### 合法的中断 / 取消状态

中断处理必须留下结构合法的对话记录。`AssistantTruncatedMutation` 和 `ToolCancelledMutation` 把这些修复逻辑集中到一个地方。

### 可测试的内部边界

补丁应用可以和提示词渲染、provider transport 分开测试。

## 编译边界

编译边界有两个职责：

1. 用待处理 runtime mutation 修补基础对话记录。
2. 根据修补后的对话记录 + invocation 配置渲染 provider 请求。

```text theme={null}
┌─────────────────────────────────────────────┐
│  输入                                        │
│                                             │
│  Invocation 配置                             │
│    - docstring / prompt contract             │
│    - template params                         │
│    - tool guidance                           │
│    - SelfRef snapshot                        │
│                                             │
│  基础对话记录 / history                       │
│  运行时补丁 (ContextMutation[])               │
├──────────── 编译边界 ────────────────────────┤
│                                             │
│  apply_mutations(transcript, patches)        │
│  → patched transcript                        │
│                                             │
│  convert_to_llm_request(...)                 │
│  → provider-facing messages[]                │
└─────────────────────────────────────────────┘
```

参见[编译管道](/zh/context/compile-pipeline)了解完整技术细节。

## 实际影响

对于大多数用户，mutation 是不可见的。你写函数、传 history、挂载工具、消费事件，并按需使用 SelfRef 原语。

如果你在调试框架内部，mutation 能解释 runtime 副作用如何变成对话记录编辑。如果你在写应用代码，主要入口仍然是：

* `@llm_function` / `@llm_chat` 的签名和 docstring；
* `history` / `chat_history`；
* 工具和事件流；
* `remember(...)`、`compact(...)` 等 SelfRef 原语。

<Card title="深入：运行时补丁" icon="list" href="/zh/context/mutations">
  查看内部 mutation 类型以及 runtime 何时产生这些对话记录补丁。
</Card>