跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt

Use this file to discover all available pages before exploring further.

​
以上下文为中心

SimpleLLMFunc 不把 provider messages 当作一个任由各组件直接编辑的列表。每次 LLM 调用都会从三类输入编译出发送给提供商的消息列表：
  1. Invocation 配置 —— docstring 提示词、模板参数、工具指导、输出契约、SelfRef 快照。
  2. 基础对话记录 —— 本次调用的 history / 当前消息。
  3. 运行时对话记录补丁 —— LLM 调用、工具执行、SelfRef 原语、中断处理和压缩产生的内部类型化编辑。
更准确地说： 
provider messages = render(invocation config, patch(base transcript, runtime patches))

​
问题

在很多 Agent 系统中，“上下文”就是一个被到处修改的消息列表：
  • 工具直接追加结果；
  • 编排循环直接塞入助手消息；
  • 记忆系统在任意位置注入内容；
  • 摘要器就地覆盖历史；
  • 中断/取消处理留下半合法的消息结构。
结果是上下文不可预测：很难回答“下一次模型到底会看到什么”。

​
运行时补丁模型

SimpleLLMFunc 使用 ContextMutation 作为内部对话记录补丁协议。 Mutation 不是完整上下文，也不是主要用户 API。它只是 runtime 副作用对基础对话记录产生的类型化增量编辑，并且只在编译边界统一应用。 
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 请求。
┌─────────────────────────────────────────────┐
│  输入                                        │
│                                             │
│  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[]                │
└─────────────────────────────────────────────┘
参见编译管道了解完整技术细节。

​
实际影响

对于大多数用户，mutation 是不可见的。你写函数、传 history、挂载工具、消费事件，并按需使用 SelfRef 原语。 如果你在调试框架内部，mutation 能解释 runtime 副作用如何变成对话记录编辑。如果你在写应用代码，主要入口仍然是：
  • @llm_function / @llm_chat 的签名和 docstring；
  • history / chat_history；
  • 工具和事件流；
  • remember(...)、compact(...) 等 SelfRef 原语。

深入：运行时补丁

查看内部 mutation 类型以及 runtime 何时产生这些对话记录补丁。