Codex 长会话上下文管理：会话拆分与状态交接的工程化实践

用好 Codex 之类的编程智能体，决定上限的往往不是"会不会写提示词"，而是上下文管理能力。我们团队用 Codex 快半年，从最初"一个会话干到底"的蛮荒阶段，进化到现在有一整套会话拆分与状态交接的规范。这篇把踩过的坑和沉淀出的做法完整讲一遍，内容比较长，适合正在被"越聊越笨"折磨的同学。

一、先承认一个事实：长会话必然退化

很多新手的用法是：早上开一个会话，从需求分析聊到代码实现再到测试修复，晚上下班前会话里已经堆了几百条消息。然后开始抱怨"它越来越笨""前面说好的约定它又忘了"。

这不是错觉，也不是玄学。原因有两个层面：

**第一，注意力稀释。**模型的上下文窗口虽大，但对整段上下文的"注意力"不是均匀分布的。会话中后段堆满了几十轮文件内容、报错日志和改来改去的方案讨论，真正关键的约束------比如"禁止修改公共模块""必须走参数校验"------被淹没在噪音里，遵循度肉眼可见地下降。我们做过对比：同一个重构任务，在 20 条消息的会话里规范违反率约 8%，拉到 150 条消息后超过 35%。

**第二，历史包袱污染。**长会话里往往有过多次"试错---推翻---重来"。比如先让它用方案 A 写了半截，发现不对推翻，又转方案 B。这半截方案 A 的代码讨论就永远留在上下文里，模型在后续生成时会不自觉地被旧方案"拽回去"------变量名突然切回旧命名、结构突然冒出废弃风格的写法，都是这个机制在作祟。

所以核心原则先立住：**长会话不是资源，是负债。**会话的价值密度随长度递减，到某个临界点就该果断开新会话，而不是继续聊。

二、什么时候该拆会话：三个明确信号

我们总结出三个信号，出现任何一个就该考虑拆分：

**信号一：任务边界切换。**做完一个功能、准备开下一个功能，就是天然的拆分点。哪怕当前会话还很"干净"，也建议切------新任务带上干净上下文，比在旧任务的背景里做新任务，输出质量稳定得多。

**信号二：试错超过两轮。**同一个问题让它修了两轮还没修对，第三轮大概率还是在错误的方向上打转。这时候正确动作不是继续追问"再试试"，而是：总结前两轮的失败信息，开新会话，把"已排除的路径"作为输入重新出发。

**信号三：它开始重复犯错或重复提问。**问过的文件结构又问一遍、改掉的写法又冒出来------这是上下文已经"装不下"的直接证据，说明有效信息密度已经被稀释到危险水平。别犹豫，立刻拆。

我们的经验值：一般业务任务的会话控制在 40~60 条消息以内，复杂重构可以放宽到 80 条，超过就该拆了。

三、状态交接：拆分的关键不在"拆"，在"接"

会话拆分最大的损失是状态------当前做到哪了、做过什么决定、还剩什么没做。如果只是关掉旧会话开新的，新会话两眼一抹黑，所有上下文要重新建立，效率暴跌。

所以我们的规范里，每次拆会话必须做状态交接。做法分两种：

轻量交接（任务还在收尾阶段）：在旧会话结束前，让 Codex 自己输出一份交接摘要。提示词是固定的：

会话即将结束。请输出交接摘要，包含：
1. 当前任务目标（一句话）
2. 已完成的改动清单（文件路径 + 改了什么）
3. 已验证的结论（哪些假设被证实/排除）
4. 未完成事项与下一步建议
5. 新会话必须知道的约束（禁止事项、关键决策）

这份摘要保存下来，作为新会话的第一条输入。因为摘要是由"当事人"自己写的，信息保真度比人工事后回忆高得多。

重量交接（跨天的复杂任务） ：除了会话内摘要，还要把关键状态落盘到项目文件里。我们的惯例是维护一个 handoff.md（放在项目根目录，加入 .gitignore），记录三类内容：当前进行中的任务状态、重要的架构决策及其原因、已知的坑和规避方法。新会话开场第一句就是"读取 handoff.md 了解当前进度"。

落盘比纯会话内交接多一个巨大好处：跨天、跨人、跨模型都通用。第二天你换了台机器、或者同事接手，甚至你换了另一个智能体工具，交接状态都还在。

四、新会话的开场三件套

拿到交接摘要后，新会话的开场直接影响后面的效率。我们的开场固定三件套：

**第一件：注入交接状态。**贴上摘要或指明 handoff.md 位置，并明确说"以下是上一个会话的状态，以此为基线继续，不要重复已完成的工作"。

第二件：重申关键约束。AGENTS.md 会自动加载项目级规范，但那些临时的、任务级的约束必须重申。比如"这次只动 service 层，controller 一律不碰"。别假设新会话能从交接摘要里自动提炼出这些------显式说出来，遵循率高一个档次。

**第三件：要求先复述再动手。**开场后先让它输出："我理解当前状态是 X，接下来的第一步是 Y，涉及文件 A/B/C，约束是 Z。确认后开始。"这一步花 30 秒，能拦住 90% 的"理解偏差跑偏"------偏差在复述阶段纠正成本几乎为零，等它改了三个文件再发现，就要回滚了。

五、两个实战案例

**案例一：300 个文件的国际化改造。**这是我们的极限测试。任务是把项目里所有中文文案抽到 i18n 资源文件，涉及 300 多个文件。显然一个会话做不完，我们按模块拆了 7 个会话：第一个会话先做基础设施（i18n 框架接入 + 工具函数 + 一个示范模块的完整改造），它的产出包括代码和一份"改造模式说明"；后续 6 个会话，每个开场贴"模式说明 + 上个会话的完成进度"，并行开了两个会话分头跑。全程规范违反 3 次，都在评审阶段拦下。这个规模以前人工做至少两周，实际两天收工。

案例二：一次失败的交接。也有翻车的时候。一次跨天任务，第二天偷懒没让 Codex 复述，直接让它继续干------结果它把交接摘要里"未完成事项"里的一条已被排除的方案 当成待办做了，写了半天才被发现，回滚浪费了一上午。教训写进了团队规范：交接后不复述，等于没交接。

六、几个容易忽略的细节

最后补几个细节，都是实际踩出来的：

1. **摘要别超 500 字。**交接摘要过长本身就稀释上下文。控制在一屏内，只留"新会话无法自行推断"的信息------代码里能看到的（文件结构、改动 diff）不用写，写决策和约束。

2. **失败会话的尸体也要利用。**修不好的 bug 在放弃前，让 Codex 输出"已尝试方案与失败现象清单"，这份清单在新会话里价值极高------它不用再走一遍弯路。

3. **并行会话要错开文件域。**开两个会话并行时，任务分配必须按文件/模块切干净，两个会话改同一个文件几乎必然产生冲突------它们互相看不见对方的改动。

4. **用检查点工具兜底。**Codex 自带的会话恢复/检查点功能，适合崩溃恢复场景，但它恢复的是完整历史，不会帮你做"信息蒸馏"。该手动拆还得拆，检查点只是保险丝。

小结

长会话上下文管理，说到底是一个"信息工程"问题：让模型在任何时刻看到的上下文，都是高密度、无污染、恰好够用的。会话拆分控制信息总量，状态交接保证决策延续，开场三件套确保理解对齐。这三层做下来，你会发现同一个模型，输出质量完全是另一个水平。

这套会话交接模板（摘要提示词 + handoff.md 结构）整理好放在了 gptupcn.com，需要可以直接取用。