读懂 Codex（4.27）：PromptCompiler 到 Responses Request 的字段映射

Core 内部 Prompt 保留五组核心字段；ModelClient 再结合 ModelInfo、Provider、Turn 推理设置和 Responses metadata 编译成 ResponsesApiRequest。标准 Responses 与 Responses Lite 的最大差别，是后者把 Base Instructions 和工具目录作为 input 前缀发送。

标准 Responses 映射

Prompt/Context	Responses 字段
`base_instructions.text`	`instructions`
`input`	`input`
`ToolSpec[]`	raw JSON `tools`
`parallel_tool_calls`	`parallel_tool_calls`
output schema/strict	`text` controls
ModelInfo + Turn	model、reasoning、service tier
Responses metadata	cache key、client metadata、headers

Prompt 与 Turn、Model、Provider 元数据共同编译为 Responses 请求 — 图 4.27-1：Prompt 不是完整网络请求。模型方言、推理设置、缓存键和传输元数据在 Client 编译层加入。

def compile_responses_request(prompt, model, provider, turn, metadata):
    return ResponsesRequest(
        model=model.slug,
        instructions=prompt.base_instructions.text,
        input=format_input(prompt.input, model),
        tools=encode_tools(prompt.tools),
        parallel_tool_calls=prompt.parallel_tool_calls,
        reasoning=build_reasoning(model, turn),
        text=build_text_controls(model, prompt.output_schema, prompt.strict),
        prompt_cache_key=metadata.session_id,
        stream=True,
    )

非 OpenAI provider 会清除内部 chat metadata 和 encrypted function args。请求发送前，还会移除不符合客户端前缀约定的 item ID，避免把本地/上游不兼容 ID 交给 API。

Responses Lite 改写通道

Lite 先把 ToolSpec 编码为 ResponseItem::AdditionalTools(role=developer)，再把非空 Base Instructions 包成 developer Message，一起插到 input 开头；顶层 instructions 变空，tools=None，parallel tool calls 被关闭，图片 detail 也被移除。

标准 Responses 与 Responses Lite 的字段映射差异 — 图 4.27-2：语义相同但 wire shape 不同。调试器若只看顶层 instructions，会错误判断 Lite 请求没有基础指令。

def compile_lite(prompt):
    prefix = [AdditionalTools(role="developer", tools=encode_tools(prompt.tools))]
    if prompt.base_instructions.text:
        prefix.append(Message.developer(prompt.base_instructions.text))
    return {
        "instructions": "",
        "tools": None,
        "input": prefix + strip_image_detail(prompt.input),
        "parallel_tool_calls": False,
    }

源码与测试锚点

codex-rs/core/src/session/turn.rs::build_prompt。
codex-rs/core/src/client.rs::build_responses_request。
codex-rs/core/src/client_common.rs::get_formatted_input_for_request。
codex-rs/codex-api/src/common.rs::ResponsesApiRequest。

标准 Responses 映射

Responses Lite 改写通道

源码与测试锚点

评论