上下文与历史:模型这一次到底看见什么
你打开昨天的任务继续提问,界面里能翻到很长的历史。模型这一次真的看见全部原文了吗?这一站把 Thread 档案、运行历史、Prompt 和上下文压缩分开。
精读 Prompt 结构、历史快照整理和压缩替换边界;不把本课扩展成完整记忆系统或 RAG 课程,也不假设所有模型的窗口大小相同。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。
本站必背 · 走路复习
第 9 站:历史档案,不等于本次模型输入
先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。
核心背诵段 · 点击展开或遮住
第九站位于 Core,关注模型这一次实际收到什么。用户能翻看的任务历史,不等于每次请求都会发送全部原文。ContextManager 管理运行历史;run_turn 取得历史快照,经 for_prompt 整理工具调用与结果的配对,并适配模型支持的输入模态,再由 build_prompt 加上基础指令、工具定义和输出约束,交给模型客户端。因此 Prompt 是结构化上下文包,不只是输入框里的那句话。压缩会替换模型正在使用的历史视图,不应直接理解成删除整个对话,也不会自动扩大授权。记住:模型依据收到的材料工作,摘要不保证保留所有细节,重要事实和权限仍需可信来源与运行边界保障。
复述顺序:区分档案与工作历史 → 取得快照 → 规范化 → 组成 Prompt → 压缩边界。
背诵用于抓牢主线。理解自测:为什么界面里还能翻到某条旧消息,模型却未必在本次请求中看到它的原文? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
核对依据:Prompt 的组成 · 历史快照整理 · 压缩后替换历史 · 构造上下文包。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。先问“模型能看见什么”,再问“为什么必须取舍”。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。
先定位:这一站到底在讲哪一层?
这一站仍在 Core。run_turn 准备本次采样输入,ContextManager 管理运行历史,build_prompt 将历史、基础指令、工具定义和输出约束组成 Prompt。
课程中的 Prompt 不是仅指输入框里一句“提示词”。这里讨论的是代码里的结构体。它也还不是所有 HTTP 请求字节的最终形态,模型客户端会进一步适配发送。
- 1用户输入与工具结果被记录
- 2取得运行历史快照
- 3整理调用配对与输入模态
- 4加入基础指令和工具说明
- 5模型客户端组织并发送请求
- 6必要时压缩模型工作历史后再继续
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| 用户看到的任务历史 | 用于继续和回看任务的档案/展示 | 不代表每次请求都发送全部原文 |
| ContextManager | Core 维护的运行历史与相关元数据 | 不是数据库里所有内容的同义词 |
| Prompt | 一次模型请求所需的结构化上下文包 | 不只是用户输入的一个字符串 |
| Compaction | 替换或压缩模型正在使用的历史视图 | 不自动创建新 Thread,也不应改变用户授权 |
“上下文”是什么,为什么会有限制?
在本课里,上下文指模型做这一次判断时可用的输入材料:相关消息、工具调用与结果、指令、工具定义等。模型不能仅凭界面上有一个文件,就知道文件的所有内容;材料需要通过具体路径进入模型请求。
内容越多并不保证回答越准确。无关大日志会挤占容量,过期状态可能误导判断,工具输出还需要保留调用配对与来源。上文可见、这次被选入、内容足够新,是三个不同条件。
Token 是模型计量输入输出长度的单位,不等于汉字数,也不是按固定字节数精确换算。具体模型的容量和计费规则会变,本课不背一个固定数字;先学系统在哪里做计量和取舍。
| 材料 | 进入模型前应问的问题 |
|---|---|
| 旧消息 | 是否相关?是否已被压缩为新的工作历史? |
| 工具输出 | 是否完整、能否与调用关联、有没有截断? |
| 工程状态 | 来源是谁,读到的是哪个版本,是否需要重新查询? |
| 操作许可 | 由可信运行边界保存,不能仅凭摘要里的自然语言扩大范围。 |
Prompt 结构体:不是只有一段 text
1. 逐字段读模型请求的上下文包
真实源码 · codex-rs/core/src/client_common.rs:17–38
代码较长时可左右滑动;下方按语句和术语拆解。
/// API request payload for a single model turn
#[derive(Debug, Clone)]
pub struct Prompt {
/// Conversation context input items.
pub input: Vec<ResponseItem>,
/// Tools available to the model, including additional tools sourced from
/// external MCP servers.
pub(crate) tools: Arc<[ToolSpec]>,
/// Whether parallel tool calls are permitted for this prompt.
pub(crate) parallel_tool_calls: bool,
pub base_instructions: BaseInstructions,
/// Optional the output schema for the model's response.
pub output_schema: Option<Value>,
/// Whether the Responses API should strictly validate `output_schema`.
pub output_schema_strict: bool,
pub(crate) cyber_access_program: Option<codex_protocol::turn_input::CyberAccessProgram>,| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| input: Vec<ResponseItem> | 对话上下文项目;可以包含消息、工具调用和工具结果,不只用户文字。 |
| tools: Arc<[ToolSpec]> | 这一请求向模型提供的工具定义集合,与实际执行实现需要匹配。 |
| parallel_tool_calls: bool | 模型请求层是否允许并行工具调用;不替代第 7 站的执行协调与业务事务。 |
| base_instructions: BaseInstructions | 基础指令单独存放,不等于用户这次输入。 |
| output_schema: Option<Value> | 可选的输出结构约束;没有这个设置时是 None,而不是必须输出空 JSON。 |
| output_schema_strict: bool | 控制相关结构化输出约束的严格方式;仍不替代业务事实校验。 |
| cyber_access_program | 此快照的可选专项配置字段,不是普通学习主线的核心,不把它泛化成所有用户权限。 |
具体输入,逐层拆开
结构示意,字段内容经过简化,不是完整可执行请求。
Prompt
├─ input
│ ├─ 用户:检查当前算例为什么不能运行
│ ├─ 工具调用 C1:读取校验状态
│ └─ 工具结果 C1:缺少某项设置(示意)
├─ tools:当前允许模型使用的能力说明
├─ base_instructions:基础行为规则
└─ output_schema:如有,约束最终输出形状工程数据不会因为存在于电脑里就自动出现在 input。你需要真实读取工具或其他可信输入来源;模型不能拿未查询到的数据当事实。
for_prompt:名字叫整理,具体整理什么?
2. 门面函数与真实处理位置
真实源码 · codex-rs/core/src/context_manager/history.rs:379–393
代码较长时可左右滑动;下方按语句和术语拆解。
pub(crate) fn for_prompt(self, input_modalities: &[InputModality]) -> Vec<ResponseItem> {
self.for_prompt_annotated(input_modalities)
.into_iter()
.map(ResponseItemEnvelope::into_item)
.collect()
}
/// Returns normalized history envelopes for internal consumers that must retain metadata.
pub(crate) fn for_prompt_annotated(
mut self,
input_modalities: &[InputModality],
) -> Vec<ResponseItemEnvelope> {
self.normalize_history(input_modalities);
Arc::unwrap_or_clone(self.items)
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| for_prompt(self, input_modalities: &[InputModality]) | 消费这一份历史快照,并借用模型输入模态列表;不是传入一个新用户问题。 |
| .for_prompt_annotated(...) | 实际规范化委托到下一个函数。这个粒度与第 3 站的门面/真实判断区别一样。 |
| .into_iter().map(...).collect() | 遍历带元数据的项目封装,取出 ResponseItem,再收集成列表。 |
| mut self / self.normalize_history(...) | 在该快照上整理历史。mutable 是当前这份值可变,不代表随意改写整个 Thread 的档案。 |
| Arc::unwrap_or_clone(self.items) | 能取得内部所有权时取出,否则克隆共享内容;不是每次都无条件深拷贝所有历史。 |
3. 真实规范化逻辑
真实源码 · codex-rs/core/src/context_manager/history.rs:694–708
代码较长时可左右滑动;下方按语句和术语拆解。
fn normalize_history(&mut self, input_modalities: &[InputModality]) {
let items = Arc::make_mut(&mut self.items);
// all function/tool calls must have a corresponding output
normalize::ensure_call_outputs_present(items);
// Paired outputs must have a corresponding call; named external outputs stand alone.
normalize::remove_orphan_outputs(items);
// strip images when model does not support them
normalize::strip_images_when_unsupported(input_modalities, items);
// strip audio when model does not support it
normalize::strip_audio_when_unsupported(input_modalities, items);
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| Arc::make_mut(&mut self.items) | 取得可修改的向量;共享情况下按需分离,保护其他快照。 |
| ensure_call_outputs_present(items) | 规范化工具调用与对应输出关系;完整性处理不是证明某个缺失工具真的执行成功。 |
| remove_orphan_outputs(items) | 处理没有相应调用的配对输出;源码注释也说明具名外部输出有独立规则,不能一概删除所有独立输出。 |
| strip_images_when_unsupported(...) | 模型不支持图片时,整理掉不支持的图片内容。 |
| strip_audio_when_unsupported(...) | 同理处理音频模态。模型可接收格式由实际模型能力决定。 |
build_prompt:把材料和运行能力装成同一包
4. 基础指令、工具与输出约束在这里会合
真实源码 · codex-rs/core/src/session/turn.rs:1382–1398
代码较长时可左右滑动;下方按语句和术语拆解。
pub(crate) fn build_prompt(
input: Vec<ResponseItem>,
step_context: &StepContext,
base_instructions: BaseInstructions,
) -> Prompt {
let turn_context = &step_context.turn;
Prompt {
input,
tools: step_context.tool_router.model_visible_specs(),
parallel_tool_calls: true,
base_instructions,
output_schema: turn_context.final_output_json_schema.clone(),
output_schema_strict: !crate::guardian::is_basic_session_source(
&turn_context.session_source,
),
cyber_access_program: turn_context.cyber_access_program,
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| input / step_context / base_instructions | 三个输入分别提供历史项目、步骤快照和基础指令,不能都叫用户 params。 |
| let turn_context = &step_context.turn | 从同一步骤借用其 Turn 上下文。 |
| tools: step_context.tool_router.model_visible_specs() | 用同一步骤的工具路由器提供模型可见定义,让请求和随后调用保持一致视图。 |
| parallel_tool_calls: true | 该路径允许模型提出并行调用;真正执行仍受工具能力和运行时控制。 |
| output_schema: ...clone() | 带上本轮可选结构约束;数据形状符合要求不等于事实正确。 |
5. 压缩替换模型历史,不更改用户授权
真实源码 · codex-rs/core/src/context_manager/history.rs:487–502
代码较长时可左右滑动;下方按语句和术语拆解。
/// Compaction changes the model's history without changing the user's authorization.
pub(crate) fn replace_compacted(&mut self, items: Vec<ResponseItemEnvelope>) {
if self.review_history.is_none() {
let mut retained = TranscriptHistory::new(self.history_version.saturating_add(1));
for item in self.raw_items().filter(|item| {
!matches!(item, ResponseItem::Message { role, content, .. }
if role == "user" && is_contextual_user_message_content(content))
}) {
retained.record(item);
}
self.review_history = Some(retained);
}
self.items = Arc::new(items);
self.history_version = self.history_version.saturating_add(1);
self.world_state_baseline = None;
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| replace_compacted(&mut self, items: Vec<ResponseItemEnvelope>) | 接收已经准备好的替换历史。它自己不是“调用模型生成摘要”的函数。 |
| review_history.is_none() / TranscriptHistory | 首次需要时保留供审查的历史材料;不是把审批依据只押在压缩后的模型文本上。 |
| self.items = Arc::new(items) | 安装新的模型工作历史。与“删除整段用户对话”不能划等号。 |
| history_version.saturating_add(1) | 更新历史版本号;饱和加法避免整数溢出时回绕。 |
| world_state_baseline = None | 清除旧世界状态基线,使后续按新的历史边界组织上下文。 |
边界提醒:压缩算法与持久化另有代码;Session::replace_compacted_history 还会组织 CompactedItem 与持久化项。这里仅安装工作历史,不保证未来任意旧细节都能被模型原样回忆。
把同一个场景换一种条件
同一任务档案不变,模型这次得到的工作上下文仍可能变化。
仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
下一次请求多了一份事实
- 调用和结果被记录到运行历史。
- clone_history 取得快照,for_prompt 整理。
- build_prompt 组合工具定义和基础指令后继续请求。
不用新开一个 Thread,也可以给模型补充新证据。
可接收模态影响实际输入
- 准备本次历史快照。
- 规范化时按 input_modalities 处理图片和音频。
- 对模型没收到的内容,不能声称它已经看过。
界面还显示图片,不能证明当前模型请求包含图片。
更换模型工作历史
- 执行相应压缩/新窗口路径。
- 用准备好的 items 安装新的工作历史,推进版本。
- 继续当前工作;授权不能由摘要扩大。
压缩不是自动新建 Turn,更不是允许遗忘权限边界。
以可信当前状态重新核实
- 发现旧描述与当前工程证据可能冲突。
- 通过正式只读路径查询对象和版本。
- 使用新事实解释或规划,关键写入前再校验。
摘要帮助理解;领域系统才是实际工程状态的权威来源。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| Prompt 就是用户输入框里的话 | 代码里的 Prompt 还包含历史、工具定义、基础指令和输出约束。 |
| 历史能翻到,模型每次就一定看到全部原文 | 界面档案与本次模型工作视图不是同一个东西。 |
| 压缩等于删除旧对话并新开 Turn | 压缩更换模型工作历史;Thread/Turn 身份和保存策略需要分别看。 |
| 压缩后摘要说可以写,就获得了权限 | 授权要由可信运行边界保留与检查,不能由生成摘要扩大。 |
迁移到你的 GEODYNA 智能体
以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。
给 GEODYNA 模型提供的材料应适量、带来源且足够新。候选方式是返回工程摘要、目标对象 ID、版本和关键校验问题;需要更细的数据时再按需查询,而不是一次塞入全部节点、网格和所有日志。
自然语言摘要适合解释,但关键工程事实与操作权限必须来自可信系统。尤其在读取摘要到提交写操作之间,目标可能已变;不能只相信几分钟前的聊天内容。
| 你要设计的点 | 可验证的证据 |
|---|---|
| 信息取舍 | 针对用户问题选择必要状态,记录大结果是否截断或只返回摘要。 |
| 可追溯性 | 关键数字能追到对象、版本和工具输出来源。 |
| 状态新鲜度 | 写入前校验对象身份与版本;摘要不承担并发控制。 |
| 权限不靠记忆 | 即使压缩或更换模型,禁止写入等约束仍由执行层明确检查。 |
产品经理练习:设计一个“当前算例摘要”,限制在 8 个字段内,并说明哪些事实需要提交前重读。
先答小测,再看解析
每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。
1. Prompt 结构体是否只有 input 一个字段?
2. for_prompt 的规范化判断主要写在哪里?
3. 模型不支持图片时,界面有图能证明模型这次看到了吗?
4. replace_compacted 自己负责调用模型生成摘要吗?
5. 压缩后模型建议扩大工程写范围,可以直接执行吗?
最后一句话交作业
请从一条新的工具结果出发,说清它如何进入下一次模型请求;再解释“模型工作历史压缩”和“任务档案”为什么不是一回事。
展开参考答案(先自己说一遍)
工具结果进入运行历史,run_turn 取得快照,经 for_prompt 的模态和配对整理,再由 build_prompt 加上工具定义、基础指令和输出约束交给客户端。压缩替换的是模型工作视图,不能直接等同于删除用户档案,也不能更改授权或保证所有旧细节仍原样进入后续请求。
下一轮再回来时:第二轮逐项追踪历史的真实数据形态;第四轮再研究压缩触发、持久化恢复、预算与异常处理。