// Resolve base instructions for the session. Priority order: // 注释直接声明三级优先级// 1. config.base_instructions override // 第一级：用户显式配置，最高权威// 2. conversation history => session_meta.base_instructions // 第二级：从历史会话继承（resume/fork）// 3. rendered instructions_template for current model // 第三级兜底：渲染当前模型的模板let base_instructions = config // 从配置层开始找    .base_instructions // 用户显式覆盖项（config.toml / API 参数传入）    .clone() // clone 出来，避免长期借用 Arc<Config>    .or_else(|| conversation_history.get_base_instructions().map(|s| s.text)) // 没配置 → 查历史 session_meta：resume/fork 时继承父线程的指令    .unwrap_or_else(|| model_info.get_model_instructions(config.personality)); // 都没有 → 渲染当前模型模板（personality 参与渲染）

pub fn get_model_instructions(&self, personality: Option<Personality>) -> String { // 渲染模型指令的入口；personality 可选    if let Some(model_messages) = &self.model_messages // 先看该模型有没有服务端下发的 messages 配置        && let Some(template) = &model_messages.instructions_template // 再取其中的指令模板（let-chains 短路）    {        if model_messages.instructions_variables.is_none() { // 没声明变量 → 模板就是纯文本，原样返回            return template.clone();        }        let personality_message = model_messages // 有变量 → 按当前 personality 查对应文案            .get_personality_message(personality)            .unwrap_or_default(); // 查不到就用空串（宁可少说，不报错）        template.replace(PERSONALITY_PLACEHOLDER, personality_message.as_str()) // 把 {{ personality }} 占位符替换成人格化文本    } else {        warn!(model = %self.slug, "Model has no instruction template; returning empty instructions."); // fail loud：打警告日志而不是静默塞错内容            String::new() // 返回空指令，让上层决定怎么办    }}

You are a coding agent running in the Codex CLI, a terminal-based coding assistant. // 第一句定身份：Codex CLI 里的编码智能体Your capabilities: // 能力清单开头- Receive user prompts and other context provided by the harness, such as files in the workspace. // 输入侧：用户提示 + harness 提供的上下文（如工作区文件）- Communicate with the user by streaming thinking & responses, and by making & updating plans. // 输出侧：流式思考/回复 + 制定和更新计划- Emit function calls to run terminal commands and apply patches. // 行动侧：发函数调用跑命令、打补丁

/// Render the request copy without changing instructions persisted or inherited by forks. // 关键设计：只改"本次请求的副本"，不动持久化状态pub(crate) async fn get_prompt_base_instructions(&self) -> BaseInstructions {    let config = self.get_config().await; // 取当前配置    let instructions = self.get_base_instructions().await; // 读会话级 base instructions（含 provenance 来源标记）    if !config.update_plan_enabled && config.model_catalog.is_none() && matches!(instructions.provenance, Some(BaseInstructionsProvenance::Model { .. })) { // 三个条件同时满足才动刀：计划工具关闭 + 无自定义目录 + 指令确实来自模型模板        BaseInstructions { text: crate::context::without_update_plan_instructions(&instructions.text), ..instructions } // 切除 update_plan 段落，其余字段原样保留    } else { instructions } // 用户自定义的指令绝不修改——尊重用户意图}

pub trait ContextualUserFragment { // 统一注入协议：任何"上下文片段"实现它就能进入模型输入    fn role(&self) -> &'static str; // 以哪个角色说话（developer/user）——决定消息归属    /// Returns a stable `<feature>.<name>` classification, using `generic` for shared fragments. // content_kind：稳定分类标识，用于去重/审计/遥测    fn content_kind(&self) -> ContentItemKind;    /// Whether this fragment must be recorded as its own response item. // 是否必须独占一条消息（默认否 → 可合并）    fn requires_separate_message(&self) -> bool { false }    fn markers(&self) -> (&'static str, &'static str); // 起止标记：之后能在历史里"认出"这个片段（去重/压缩时识别）    fn body(&self) -> String; // 模型可见的正文内容    fn render(&self) -> String { // 渲染 = 标记 + 正文，不额外加分隔符（空白由实现方自己控制）        let (start_marker, end_marker) = self.markers();        let body = self.body();        if start_marker.is_empty() && end_marker.is_empty() { return body; } // 无标记 → 纯文本直出        format!("{start_marker}{body}{end_marker}") // 有标记 → 包一层，如 <permissions instructions>...</permissions instructions>    }    fn into(self) -> ResponseItem where Self: Sized { // 一行转成 API 消息项：fragment 与请求体之间的桥        ResponseItem::from(self.render_fragment())    }}

#[derive(Clone, Debug, PartialEq, Eq)] // 派生比较能力：差量判断需要"两个片段是否相等"pub(crate) struct BaseInstructionsFragment(pub(crate) String); // base instructions 片段：包一层最终指令文本impl ContextualUserFragment for BaseInstructionsFragment { // 实现统一注入协议    fn content_kind(&self) -> ContentItemKind { // 稳定标识 model.base_instructions——历史里去重/审计的钥匙        ContentItemKind("model.base_instructions".to_string())    }    fn role(&self) -> &'static str { "developer" } // developer 角色：系统级指令，不是用户说的话    fn requires_separate_message(&self) -> bool { true } // 必须独占一条消息——绝不和其他上下文混排    fn markers(&self) -> (&'static str, &'static str) { Self::type_markers() } // 标记取类型级默认值    fn type_markers() -> (&'static str, &'static str) { ("", "") } // 空标记 → render 出纯文本，matches_text 永不命中（它靠 content_kind 识别）    fn body(&self) -> String { self.0.clone() } // 正文就是指令文本本身}

pub(crate) trait WorldStateSection: Send + Sync + 'static { // 一个"世界状态节"：自管快照、自管差量渲染    const ID: &'static str; // 稳定 ID（持久化进 rollout，跨版本不能变）——section 的身份    type Snapshot: DeserializeOwned + Serialize; // 快照类型：只存"判断变化所需的最小数据"    fn snapshot(&self) -> Self::Snapshot; // 当前状态 → 可序列化快照（每轮持久化，供下轮对比）    /// Whether the section contributes comparison state to persisted rollouts. // 是否参与持久化（默认是；纯展示型节可以关掉）    fn should_persist(&self) -> bool { true }    /// Recognizes legacy fragments whose identity depends on this section's current value. // 识别旧版本片段文本——兼容升级前的历史    fn matches_current_legacy_fragment(&self, role: &str, text: &str) -> bool { Self::matches_legacy_fragment(role, text) }    /// Whether retained model history must still contain this section's rendered fragment. // 是否要检查"片段还在历史里吗"（防压缩后重复注入）    fn has_retained_fragment_matcher() -> bool { false }    fn render_diff( // 核心方法：对比上一份快照，决定本轮告诉模型什么        &self,        previous: PreviousSectionState<'_, Self::Snapshot>, // 三态：Absent（没有）/ Unknown（有但读不出类型）/ Known（精确快照）    ) -> Option<Box<dyn ContextualUserFragment>>; // None = 没变化，零注入；Some(fragment) = 变了，输出差量文本}impl WorldState {    /// Renders every section as new, without any known previous state. // 首轮：所有节都当"新"处理 → 全量注入    pub(crate) fn render_full(&self) -> Vec<Box<dyn ContextualUserFragment>> {        self.render_with(|_, _| PreviousSectionState::Absent) // 统一走 render_with，previous 恒为 Absent    }    /// Renders each section against the exact persisted snapshot when available. // 后续轮：逐节对比持久化快照 → 只输出差量    pub(crate) fn render_diff(&self, previous: &WorldStateSnapshot) -> Vec<Box<dyn ContextualUserFragment>> {        self.render_with(|id, _| match previous.sections.get(id) { // 按 section ID 查上一份快照            Some(previous) => PreviousSectionState::Known(previous), // 有快照 → 精确差量            None => PreviousSectionState::Absent, // 没有（新增的节）→ 当新内容全量注入        })    }}

fn render_diff( // permissions 节：所有 section 里差量策略最精细的一个    &self,    previous: PreviousSectionState<'_, Self::Snapshot>,) -> Option<Box<dyn ContextualUserFragment>> {    match (previous, &self.snapshot) { // 同时对比"上一状态"和"当前状态"两个快照        (PreviousSectionState::Known(PermissionsSnapshot::Current { instructions: previous_instructions, approved_command_prefixes: previous_prefixes }), PermissionsSnapshot::Current { instructions, approved_command_prefixes }) if previous_instructions == instructions => { // 指令体哈希没变 → 只剩前缀集合可能变了            if previous_prefixes == approved_command_prefixes { return None; } // 前缀也没变 → 本轮零注入（最省路径）            if previous_prefixes.is_subset(approved_command_prefixes) { // 新集合 ⊇ 旧集合 = 纯新增，没有撤销                let added_prefixes = approved_command_prefixes.difference(previous_prefixes).cloned().collect(); // 求差集：本轮新批准的命令前缀                if let Some(prefixes) = format_allow_prefixes(added_prefixes) {                    return Some(Box::new(ApprovedCommandPrefixSaved::new(prefixes))); // 只发一条"这些前缀现在可用了"的短通知，不重发整份策略                }            }        }        (PreviousSectionState::Known(PermissionsSnapshot::Legacy(previous)), PermissionsSnapshot::Current { .. }) if previous == &WorldStateHash::from_fragment(&self.instructions) => return None, // 旧版快照（只有哈希）与当前一致 → 视为没变，兼容升级        _ => {} // 其余情况（策略真变了 / 状态未知）落到下面全量重发    }    Some(Box::new(self.instructions.clone())) // 兜底：重新注入完整 permissions instructions}

fn render_diff( // model 节：快照就是模型名本身（String）    &self,    previous: PreviousSectionState<'_, Self::Snapshot>,) -> Option<Box<dyn ContextualUserFragment>> {    let model_changed = match previous { // 判断"模型是否换了"        PreviousSectionState::Known(previous) => previous != &self.model, // 有精确快照 → 直接比名字        PreviousSectionState::Unknown | PreviousSectionState::Absent => self.previous_model.as_deref().is_some_and(|previous| previous != self.model), // 没快照 → 用运行时记录的"上一轮模型名"兜底判断    };    (model_changed && !self.instructions.is_empty()).then(|| { // 换了且有指令文本才注入（空指令不废话）        Box::new(ModelSwitchInstructions::new(self.instructions.clone())) as Box<dyn ContextualUserFragment> // 包成"换模型通知"片段    })}impl ContextualUserFragment for ModelSwitchInstructions { // 换模型通知：告诉模型"你被换了，按新规则来"    fn content_kind(&self) -> ContentItemKind { ContentItemKind("model_switch.instructions".to_string()) } // 稳定标识    fn role(&self) -> &'static str { "developer" } // developer 角色    fn requires_separate_message(&self) -> bool { true } // 独占一条消息——换模型是大事件，不混排    fn type_markers() -> (&'static str, &'static str) { ("<model_switch>", "</model_switch>") } // XML 式标记：历史里能认出它（防重复注入）    fn body(&self) -> String {        format!("The user was previously using a different model. Please continue the conversation according to the following instructions:\n\n{}\n", self.model_instructions) // 先解释"之前是别的模型"，再附完整新指令——给模型一个行为切换的台阶    }}

impl PermissionsInstructions {    /// Builds permissions instructions from the effective permission profile and approval policy. // 入口：把"策略对象"翻译成"提示词文本"    pub fn from_permission_profile(        permission_profile: &PermissionProfile, // 文件系统 + 网络沙箱策略（真正执行的那份）        approval_policy: AskForApproval, // 审批策略四选一：Never / UnlessTrusted / OnRequest / Granular        approval_context: ApprovalPromptContext<'_>, // reviewer（user/auto_review）+ 模型侧自定义文案覆盖        exec_policy: &Policy, // execpolicy 命令策略引擎：已批准前缀等        cwd: &Path, // 当前工作目录：解析相对可写根用        exec_permission_approvals_enabled: bool, // shell 权限审批流是否开启（影响文案分支）        request_permissions_tool_enabled: bool, // request_permissions 工具是否可用（决定要不要教模型用它）    ) -> Self {        let file_system_sandbox_policy = permission_profile.file_system_sandbox_policy(); // 拆出文件系统策略        let (sandbox_mode, writable_roots) = sandbox_prompt_from_policy(&file_system_sandbox_policy, cwd); // 映射成三档：full access / workspace write / read-only + 可写根列表        Self::from_permissions_with_network_and_denied_reads(            sandbox_mode, // 沙箱档位决定选哪套模板文案            network_access_from_policy(permission_profile.network_sandbox_policy()), // 网络策略 → Enabled/Restricted（填进 {{ network_access }}）            PermissionsPromptConfig { approval_policy, approvals_reviewer: approval_context.reviewer, .. }, // 审批相关配置打包            writable_roots, // 可写根列表（渲染成 "The writable root is `...`."）            denied_reads_text(&file_system_sandbox_policy, cwd), // 被禁读的路径/glob → "不要请求升级权限去读它们"的明确警告        )    }}impl ContextualUserFragment for PermissionsInstructions {    fn role(&self) -> &'static str { "developer" } // developer 消息：策略说明属于系统层    fn content_kind(&self) -> ContentItemKind { ContentItemKind("permissions.instructions".to_string()) } // 稳定标识 permissions.instructions    fn type_markers() -> (&'static str, &'static str) { ("<permissions instructions>", "</permissions instructions>") } // 标记：WorldState 靠它认出"这条还在历史里"（has_retained_fragment_matcher=true）}

pub(crate) fn build_plugin_injections( // 插件提及注入入口：用户显式 @ 了插件 → 生成 developer hint    mentioned_plugins: &[PluginCapabilitySummary], // 本轮被显式提到的插件列表（从用户输入里解析）    mcp_tools: &[ToolInfo], // 全部 MCP 工具（用来反查"哪些 server 属于这个插件"）    available_connectors: &[connectors::AppInfo], // 可用 App connectors（同样按插件名反查）) -> Vec<ResponseItem> {    if mentioned_plugins.is_empty() { return Vec::new(); } // 没提及 → 零注入：不污染上下文，这是默认路径    mentioned_plugins.iter().filter_map(|plugin| { // 逐个处理被提到的插件        let available_mcp_servers = mcp_tools.iter() // 找出属于该插件的 MCP server（排除内置 apps server）            .filter(|tool| tool.server_name != CODEX_APPS_MCP_SERVER_NAME && tool.plugin_display_names.iter().any(|name| name == &plugin.display_name))            .map(|tool| tool.server_name.clone()).collect::<BTreeSet<String>>() // BTreeSet 去重 + 排序 → 输出顺序稳定（提示词可复现）            .into_iter().collect::<Vec<_>>();        let available_apps = available_connectors.iter() // 找出属于该插件且已启用的 App            .filter(|connector| connector.is_enabled && connector.plugin_display_names.iter().any(|name| name == &plugin.display_name))            .map(connector_display_label).collect::<BTreeSet<String>>()            .into_iter().collect::<Vec<_>>();        render_explicit_plugin_instructions(plugin, &available_mcp_servers, &available_apps) // 渲染 hint 文本（内部带 4KB 硬预算）            .map(PluginInstructions::new).map(ContextualUserFragment::into) // 包成 fragment → ResponseItem，走统一协议    }).collect()}fn bound_explicit_plugin_instructions(rendered: String) -> String { // 硬预算：插件 hint 最多 4KB（MAX_EXPLICIT_PLUGIN_INSTRUCTIONS_BYTES）    if rendered.len() <= MAX_EXPLICIT_PLUGIN_INSTRUCTIONS_BYTES { return rendered; } // 没超 → 原样通过    let max_prefix_bytes = MAX_EXPLICIT_PLUGIN_INSTRUCTIONS_BYTES.saturating_sub(TRUNCATED_PLUGIN_INSTRUCTIONS_SUFFIX.len()); // 先给截断提示语留出空间（saturating 防下溢）    let prefix = take_bytes_at_char_boundary(&rendered, max_prefix_bytes); // 按字符边界截断——绝不把 UTF-8 多字节切半    format!("{prefix}{TRUNCATED_PLUGIN_INSTRUCTIONS_SUFFIX}") // 追加 "Additional plugin capabilities omitted to fit the context limit."}

for fragment in world_state.render_full() { // 首轮全量渲染 → 按角色 + 标记路由进三个桶    match fragment.role() {        "developer" if fragment.markers().0 == ModelSwitchInstructions::type_markers().0 => { developer_sections.insert(0, fragment.render_fragment()); } // 换模型通知必须插到 developer 上下文最前面（新规则优先于旧约定）        "developer" if fragment.requires_separate_message() && fragment.markers().0.is_empty() => { separate_developer_sections.push(fragment.render_fragment()); } // 要求独占消息的片段 → 各自一条 ResponseItem        "developer" => developer_sections.push(fragment.render_fragment()), // 普通 developer 片段 → 攒进合并桶（最终合成一条大消息）        "user" => contextual_user_sections.push(fragment.render_fragment()), // user 角色片段（如推荐插件）→ 单独的 user 消息        _ => {} // 其他角色忽略    }}let mut items = Vec::with_capacity(4);if let Some(developer_message) = crate::context_manager::updates::build_rendered_message(developer_sections) { items.push(developer_message); } // 合并桶 → 一条 developer 消息（多个 content item）for section in separate_developer_sections { if let Some(m) = build_rendered_message(vec![section]) { items.push(m); } } // 独占片段 → 逐条成消息// ……multi-agent mode / contextual user / guardian policy / managed instructions 依次追加……if separate_guardian_developer_message && let Some(developer_instructions) = turn_context.developer_instructions.as_deref() { /* GuardianPolicy::new(...).render_fragment() → 独立消息 */ } // guardian 子代理的策略提示单独成条——便于审计"审查者当时看到什么"

pub(crate) fn build_prompt( // 最终打包：历史 + 工具 + base instructions → 一个 Prompt    input: Vec<ResponseItem>, // 对话历史（含所有已注入的上下文片段）    step_context: &StepContext, // 本步冻结快照（工具路由/权限/模型信息都从这里取）    base_instructions: BaseInstructions, // 解析好的 base instructions（带 provenance，调用方刚用 get_prompt_base_instructions 取的请求副本）) -> Prompt {    let turn_context = &step_context.turn;    Prompt {        input, // 历史原样进 input 数组        tools: step_context.tool_router.model_visible_specs(), // 模型可见的工具 spec（ToolRouter 统一出口）        parallel_tool_calls: true, // 默认允许并行工具调用        base_instructions, // base instructions 单独携带——它最终落在请求的哪个字段，由下游按 provider 能力决定        output_schema: turn_context.final_output_json_schema.clone(), // 可选的结构化输出 schema        output_schema_strict: !crate::guardian::is_basic_session_source(&turn_context.session_source), // guardian 子会话放宽 strict（它的输出是内部审查用，格式容错）        cyber_access_program: turn_context.cyber_access_program, // access program 元数据（如有）    }}

let mut input = prompt.get_formatted_input_for_request(model_info); // 历史先做模型适配（如图片 detail 归一化）let (instructions, tools) = if model_info.use_responses_lite { // 双路径分叉：Responses Lite vs 标准 Responses API    let prefix_namespace = Uuid::new_v5(&Uuid::NAMESPACE_OID, self.state.thread_id.to_string().as_bytes()); // 从 thread ID 派生稳定命名空间——同一线程里相同内容永远得到相同 UUID    let tools = if self.state.provider.capabilities().namespace_tools { create_tools_json_for_responses_lite(&prompt.tools)? } else { create_tools_json_for_responses_api(&prompt.tools)? }; // 按 provider 能力选两种工具 JSON 格式之一    let mut prefix = vec![ResponseItem::AdditionalTools { id: Some(ResponseItemId::with_suffix("at", Uuid::new_v5(&prefix_namespace, &serde_json::to_vec(&tools)?))), role: "developer".to_string(), tools }]; // 工具声明作为第一条 input item（ID 由内容哈希派生 → 稳定）    if !prompt.base_instructions.text.is_empty() { // base instructions 非空 → 也拼进前缀        let mut instructions = ContextualUserFragment::into(BaseInstructionsFragment(prompt.base_instructions.text.clone())); // 走统一 fragment 协议包成 developer 消息（和注入的上下文同一条流水线）        instructions.set_id(Some(ResponseItemId::with_suffix("msg", Uuid::new_v5(&prefix_namespace, prompt.base_instructions.text.as_bytes())))); // ID = f(内容)：重试/resume 时身份不变 → prompt cache 友好、增量请求可复用        prefix.push(instructions);    }    input.splice(0..0, prefix); // 前缀拼到 input 头部——Lite API 没有独立 instructions 字段，一切皆消息    (String::new(), None) // 标准字段留空（instructions/tools 都不走顶层）} else {    (prompt.base_instructions.text.clone(), Some(create_tools_raw_json_for_responses_api(&prompt.tools)?.into())) // 标准路径：base instructions 进顶层 instructions 字段，tools 用 raw JSON};

提示词组装管线（会话启动 + 每轮 turn）

▼

▼

▼

▼

▼