第一轮 · 第 9 站 · CORE · 请求输入与上下文管理

上下文与历史:模型这一次到底看见什么

你打开昨天的任务继续提问,界面里能翻到很长的历史。模型这一次真的看见全部原文了吗?这一站把 Thread 档案、运行历史、Prompt 和上下文压缩分开。

本站必背:走路时复述这一段

把 Prompt 理解成结构化请求输入
追 clone_history → for_prompt → build_prompt
分清上下文压缩、历史回看与权限保留

精读 Prompt 结构、历史快照整理和压缩替换边界;不把本课扩展成完整记忆系统或 RAG 课程,也不假设所有模型的窗口大小相同。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。

本站必背 · 走路复习

第 9 站:历史档案,不等于本次模型输入

先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。

核心背诵段 · 点击展开或遮住

第九站位于 Core,关注模型这一次实际收到什么。用户能翻看的任务历史,不等于每次请求都会发送全部原文。ContextManager 管理运行历史;run_turn 取得历史快照,经 for_prompt 整理工具调用与结果的配对,并适配模型支持的输入模态,再由 build_prompt 加上基础指令、工具定义和输出约束,交给模型客户端。因此 Prompt 是结构化上下文包,不只是输入框里的那句话。压缩会替换模型正在使用的历史视图,不应直接理解成删除整个对话,也不会自动扩大授权。记住:模型依据收到的材料工作,摘要不保证保留所有细节,重要事实和权限仍需可信来源与运行边界保障。

复述顺序:区分档案与工作历史 → 取得快照 → 规范化 → 组成 Prompt → 压缩边界。

背诵用于抓牢主线。理解自测:为什么界面里还能翻到某条旧消息,模型却未必在本次请求中看到它的原文? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。

核对依据:Prompt 的组成 · 历史快照整理 · 压缩后替换历史 · 构造上下文包。

配套音频 · AI 合成语音

先听一遍,再对照源码

普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。先问“模型能看见什么”,再问“为什么必须取舍”。

全长 6:23 · 6 章MP3 · 2.9 MB普通话女声 · 稍慢语速
下载 MP3

点击开始;页面不会自动播放,也不会自动标记课程通关。

点击任一章,从对应位置开始。

    展开音频文字稿 · 听不清时对照看
    声音中的术语,对应代码里的哪个词?

    AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。

    先定位:这一站到底在讲哪一层?

    这一站仍在 Core。run_turn 准备本次采样输入,ContextManager 管理运行历史,build_prompt 将历史、基础指令、工具定义和输出约束组成 Prompt。

    课程中的 Prompt 不是仅指输入框里一句“提示词”。这里讨论的是代码里的结构体。它也还不是所有 HTTP 请求字节的最终形态,模型客户端会进一步适配发送。

    1. 1用户输入与工具结果被记录
    2. 2取得运行历史快照
    3. 3整理调用配对与输入模态
    4. 4加入基础指令和工具说明
    5. 5模型客户端组织并发送请求
    6. 6必要时压缩模型工作历史后再继续
    粒度负责什么不要误认为
    用户看到的任务历史用于继续和回看任务的档案/展示不代表每次请求都发送全部原文
    ContextManagerCore 维护的运行历史与相关元数据不是数据库里所有内容的同义词
    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,不执行任何真实操作。

    先预测会走哪条分支,再点击按钮查看。

    最容易说错的边界

    常见说法准确表述
    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 加上工具定义、基础指令和输出约束交给客户端。压缩替换的是模型工作视图,不能直接等同于删除用户档案,也不能更改授权或保证所有旧细节仍原样进入后续请求。

    下一轮再回来时:第二轮逐项追踪历史的真实数据形态;第四轮再研究压缩触发、持久化恢复、预算与异常处理。