Research: Codex Plan mode behavior and prompt architecture

调研范围

基于 openai/codex 提交 363427b5e3fe1b6d7499e6bc47651f62a5a3b1d2（2026-08-13）进行源码审阅，聚焦 Plan 模式的状态、提示词、工具约束、流式协议和实施切换流程。

结论

Plan 模式是独立的协作模式，不是 update_plan 待办工具。它主要依赖 developer 提示词约束模型行为，并结合少量运行时硬约束、<proposed_plan> 协议及 TUI 的“批准后实施”交互实现闭环。

运行链路

1. 用户在 TUI 选择/切换到 Plan。内置预设默认设置 Medium 推理强度，且可由 plan_mode_reasoning_effort 覆盖。
2. 每轮 world state 将 Plan 提示词包装在 <collaboration_mode> developer 消息中并注入模型上下文，状态随会话持久化。
3. 模型先进行只读探索、澄清意图、补齐实施决策，然后以独占行的 <proposed_plan>...</proposed_plan> 输出完整计划。
4. 运行时把该块从普通 assistant 文本中剥离，流式发送 PlanDelta，最终生成 TurnItem::Plan。
5. TUI 收到 PlanItem 后提供三项操作：保留上下文切换 Default 并实施、新开上下文携带计划实施、或继续 Plan 模式。

Plan 提示词要点

完整原文：plan.md

• 严格分为环境事实探索、意图澄清、实施细节澄清三阶段。
• 用户的“直接实现”不能结束 Plan 模式，只能理解成“规划如何实施”；仅 developer 指令能切换模式。
• 允许阅读、搜索、静态分析、无副作用命令和只写缓存的构建/测试。
• 禁止编辑仓库、应用补丁、迁移、改写型 formatter/codegen，以及所有实际执行计划的副作用操作。
• 优先使用 request_user_input 询问无法从环境发现、且会实质影响方案的偏好或取舍。
• 只有当方案“实现者不需要再做决策”时才能生成最终计划；每轮至多一个 <proposed_plan>。
• 最终计划默认应简洁，并包含标题、摘要、公共接口变化、测试和明确的默认假设。

硬约束与软约束

重要边界：Core 中对 Plan 的通用工具执行没有发现针对 exec、apply_patch 等变更工具的统一后端拒绝。因此“不得写入”主要是高优先级提示词约束，而非完整的强制沙箱隔离；update_plan 是已确认的特例硬拦截。

关键实现位置

• 模式与 mask 定义
• 内置 Plan / Default 预设
• world-state developer 提示注入
• Plan 流式分流与 PlanItem 生命周期
• <proposed_plan> 解析器
• update_plan 在 Plan 中的拒绝
• 实施确认弹窗与上下文转交

额外注意

实际运行的提示词可能不同于仓库模板：若模型目录返回 collaboration_mode_messages.plan，该内容会优先覆盖本地预设；若 include_collaboration_mode_instructions = false，则不会注入该 developer 提示块。

Start with codex-rs/collaboration-mode-templates/templates/plan.md and trace the listed Rust locations: collaboration_mode_presets.rs, world_state/collaboration_mode.rs, session/turn.rs, stream-parser/src/proposed_plan.rs, tools/handlers/plan.rs, and tui/chatwidget/plan_implementation.rs. Compare them with commit 363427b5e3fe1b6d7499e6bc47651f62a5a3b1d2; done means documenting the Plan lifecycle, constraints, streaming protocol, implementation handoff, and noted prompt overrides.