OpenInterpreter DeepSeek TUI 的 Cycle Handoff Briefing：上下文周期切换时如何写好 3,000 Token 的「交接简报」

本篇技术指南以本仓库中 DeepSeek TUI（代号 CodeWhale）harness 的周期交接提示词 cycle_handoff_briefing.md 为核心，讲解当会话跨越单周期 Token 预算边界、整段转录被归档到磁盘后，Agent 如何用一段 <carry_forward> 结构化简报把「不可还原的状态」无损地交给下一个周期的自己。读完本文，你将掌握这份简报应写什么、不应写什么、格式约束如何落地，并能对照 deepseek_tui.rs 与 deepseek_tui_tools.json 看清该提示词在请求构建、压缩触发、归档检索工具等环节的实际调用链。

1. 触发场景：什么是「上下文周期边界」

cycle_handoff_briefing.md 开篇即定义了它的适用场景：

You are about to cross a context cycle boundary. The conversation so far has crossed the per-cycle token budget, so this entire transcript is going to be archived to disk and the next turn will start with a fresh context.

也就是说，当本周期对话累计 Token 超过单周期预算时，运行时不会做「截断式续写」，而是执行一次硬切换：

1. 完整转录（transcript）被归档落盘；
2. 下一轮对话以全新上下文重启，其中包含：
   • 原始系统提示词（system prompt）；
   • 结构化状态：todos、plan、working set、存活的子代理（sub-agents）；
   • 用户尚未处理的消息（pending message）；
   • 以及当前周期模型亲笔撰写的自由格式简报——这就是 <carry_forward> 块。

这份简报不是事后摘要，而是在跨界之前由「当下的自己」写给「下一个周期的自己」的一份工作交接，目标是让接手方「continue without redoing work」（继续工作而不必重做）。原文档给出的任务约束非常明确：在单条消息内产出一个至多 3,000 token 的 <carry_forward> 块，承载下一周期不可再生的全部状态。

2. <carry_forward> 应包含的五类内容

原文档以「Write concrete prose, not bullet-point summaries of the transcript.（写具体叙述，而不是对转录的要点式罗列）」定下基调，随后列出五个必写维度：

2.1 已做决策及其理由（Decisions made and why）

要写出「你选了什么」以及「是什么约束让它成为正确选择」。原文档明确反对含糊表述：

Not "we discussed options" — name the choice and the constraint that made it the right one.

即：不许写「我们讨论了一些方案」，必须点名具体选择，并说明使其成立的那条约束。

2.2 发现的约束（Constraints discovered）

关于代码库、运行环境、用户偏好或外部系统的具体事实——如果下一周期不知道它们就会踩坑。原文档给出三个典型示例：

• 「audit log 是 JSONL 格式而不是 JSON」；
• 「用户坚持非测试代码中禁止 unwrap()」；
• 「macOS 沙箱会阻止 tools/exec.rs 中的原始 socket」。

这类信息的特征是：单条看微不足道，缺失后却会导致下一周期重复踩坑或做出错误假设。

2.3 正在验证的假设（Hypotheses being tested）

当前正在主动调查的开放问题：你在试图证伪什么、什么证据会改变你的判断。这让下一周期能接续推理，而不是把假设当事实处理。

2.4 失败的路线（Approaches that failed）

需要「足以让下一周期不重走回头路」的细节：必须点名方案本身以及它具体为什么没成，而不是一句「tried X, didn't work」。

2.5 留给用户的开放问题（Open questions for the user）

当前被阻塞、需要用户裁决的事项——若用户没有主动提及，下一周期应主动提出这些问题。

3. 明确不要写入 <carry_forward> 的内容

原文档专设一节「What NOT to put in <carry_forward>」，四条排除规则每一条都对应一条 Token 经济学考量：

排除项	理由
工具输出的原始字节（Tool output bytes）	它们已经随转录归档到磁盘
读过的文件内容（File contents）	下一周期可以重读——「比简报 token 贵，但比基于陈旧转述的错误假设便宜」
操作过程的逐步复盘（Step-by-step recap）	下一周期不需要操作顺序，只需要当前状态
寒暄、铺垫、框架性语言（Pleasantries, throat-clearing）	「Every token matters.（每个 token 都有价值）」

其中「文件内容不写入简报」一条值得特别展开：原文档给出的取舍逻辑是重读文件 > 基于过时转述做假设。这与提示词第 4 节对 recall_archive 工具的定位互为呼应——宁可花成本重新取回事实，也不要在简报里塞可能过时的二手转述。

4. 格式约束

原文档对输出格式做了五条硬性规定：

• <carry_forward> 独占一行开始；
• </carry_forward> 独占一行结束；
• 标签之外不许有任何正文（No prose outside the tags）；
• 不许嵌套标签（No nested tags）;
• 块本身外面不许包代码围栏（code fence）——但块内部可以用代码围栏引用具体代码片段。

5. 与 recall_archive 工具的关系：简报是「承重墙」，归档是「备查库」

原文档最后一段交代了归档检索机制：下一周期会开放 recall_archive 工具，它基于 BM25 对归档转录的消息文本做检索并返回 top-N 命中；当简报遗漏了下一周期需要的信息时，用它兜底。但原文档同时给出了明确的使用纪律：

Use it sparingly — frequent recalls mean your briefing was too sparse, so refine your next briefing rather than leaning on the archive. Don't try to be exhaustive here: be precise about the load-bearing state and trust the archive for the rest.

即：频繁的 recall 是对「上一份简报写得太稀」的负面信号，正确反应是改进下一份简报，而不是依赖归档。设计哲学可以概括为一句话——对「承重状态」（load-bearing state）保持精确，其余交给归档。

5.1 仓库中的工具定义印证

该提示词描述的工具在仓库中有真实定义。deepseek_tui_tools.json 中 recall_archive 的 schema 为：

• 描述：Search prior context cycles for content not in your briefing. Use sparingly — frequent recalls mean your briefing was too sparse; refine your next briefing.——与提示词中的措辞逐字一致；
• 参数 query（必填）：Tokenized and BM25-scored against archived messages；
• 参数 cycle（可选）：限定到某个特定历史周期；
• 参数 max_results（可选）：默认 3 条命中，硬上限 10 条。

工具描述与提示词文本的一致性，说明「简报-归档」双通道策略是贯穿 prompt 层与工具层的整体设计，而非孤立文案。

6. 原文档给出的示例形态

原文档末尾附了一段示例，并特别注明「do not copy verbatim — write your own」（不要逐字照抄，写你自己的）：

<carry_forward>
Working on issue #124 (cycle-restart). Key decisions: (1) trigger at 110K
tokens not 128K — need ~8.5K headroom for the briefing turn itself plus
next-turn growth before the next boundary; (2) archive to JSONL with a
header line so future tools can stream-read without parsing the whole
file. Constraint discovered: DeepSeek V4 thinking-mode requires
reasoning_content replay on assistant messages with tool calls — so seed
messages can't include orphan tool calls from the archived cycle. The
approach of "summarize then keep recent messages" (the old compaction
path) was failing because the model couldn't tell which fragments were
verbatim vs. paraphrased; replacing it entirely. Open question for user:
do they want per-model briefing token caps, or one global cap?
</carry_forward>

这段示例恰好完整演练了第 2 节的五个维度：以连续叙述（而非列表）呈现；决策带上了量化理由（110K 触发点留出约 8.5K 余量给简报轮本身和下一轮增长）；约束具体到协议细节（thinking 模式要求 assistant 工具调用消息携带 reasoning_content，因此种子消息不能含归档周期遗留的孤儿工具调用）；失败路线点明了机制层面的原因（旧压缩路径中模型无法分辨哪些片段是逐字引用、哪些是转述）；结尾是一个留给用户的开放问题（按模型分设简报 Token 上限，还是全局统一上限）。值得注意的是，示例中「种子消息不能含孤儿工具调用」这一点与本仓库源码存在直接呼应：deepseek_tui.rs 中的 add_omitted_reasoning_to_assistant_tool_calls 会为缺少 reasoning_content 的 assistant 工具调用消息补占位值 "(reasoning omitted)"，这正是示例所述约束在请求组装层的落地。

7. 源码视角：这份提示词如何被触发和组装

以下结合 deepseek_tui.rs 的源码说明该提示词的实际调用链。

7.1 提示词以 include_str! 编译进二进制

deepseek_tui.rs 中：

const CYCLE_HANDOFF_BRIEFING_PROMPT: &str =
    include_str!("deepseek_tui_prompts/cycle_handoff_briefing.md");

提示词文件在编译期被内联，与其他 harness 提示词（base.md、calm 人格、YOLO 模式、compact 模板）并列加载。

7.2 触发条件：识别 CONTEXT CHECKPOINT COMPACTION 标记

build_request 首先调用 is_deepseek_tui_compaction_prompt 判断当前是否为周期切换场景（见 deepseek_tui.rs）：

fn is_deepseek_tui_compaction_prompt(prompt: &Prompt) -> bool {
    prompt.tools.is_empty()
        && prompt
            .input
            .iter()
            .rev()
            .find_map(response_item_text)
            .is_some_and(|text| text.contains("CONTEXT CHECKPOINT COMPACTION"))
}

从源码结构看，判定条件是双重的：本次请求不携带任何工具，且最近的 user 消息文本包含 CONTEXT CHECKPOINT COMPACTION 标记。该标记与通用压缩模板 prompt.md 首句「You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.」相互对应——即运行时注入这条压缩指令后，harness 便切换到「交接简报」分支。

7.3 压缩分支的请求参数

一旦命中压缩分支，请求被构造为一个极简形态（见 deepseek_tui.rs）：

let request = json!({
    "model": DEEPSEEK_TUI_COMPACTION_MODEL,   // "deepseek-v4-flash"
    "messages": [
        { "role": "system", "content": CYCLE_HANDOFF_BRIEFING_PROMPT },
        { "role": "user",
          "content": deepseek_tui_cycle_handoff_user_prompt(prompt.cwd.as_deref()) }
    ],
    "max_tokens": 4096,
    "temperature": 0.20000000298023224_f64,
});

关键参数与原文档的对应关系：

参数	取值	说明
model	deepseek-v4-flash	压缩任务用轻量模型承担，常量定义于 deepseek_tui.rs
系统提示词	本文档全文	<carry_forward> 规则整体作为 system prompt 下发
max_tokens	4096	略大于简报 3,000 token 的上限，为标签与少量外围输出留出余量
temperature	0.2	低温采样，保证交接文本稳定可预期
tools	无	返回的 ToolKinds::new() 为空——写简报这一轮不需要任何工具

对比常规对话分支（默认模型 deepseek-chat、max_tokens 64,000、开启流式与 usage 统计、挂载完整工具集，见 deepseek_tui.rs），可以推断该 harness 有意把「交接」建模为一个独立的、工具隔离的推理任务，而非主对话的一种特殊消息。

7.4 user 消息侧：结构化状态的注入

系统提示词定规则，user 消息则携带「当下能自动保有的状态」。deepseek_tui_cycle_handoff_user_prompt（见 deepseek_tui.rs）组装的内容包括：

• Briefing Request：复述简报的五个必写维度与排除项，与 system 提示词形成双保险；
• Cycle State (Auto-Preserved)：模式（YOLO）、工作区与 Cwd 路径；
• Work 清单：由 deepseek_tui_checklist_markdown() 生成的策略清单，含三项固定策略元数据——- [~] Initialize tracking and inspect workspace、- [ ] Search, git, and diagnostics、- [ ] Create, edit, verify, and finalize；
• Repo Working Set：从 cwd 实际扫描前 8 个条目（active_path_lines，目录深度 2，排除 .codewhale/.git/target，且不跟随符号链接目录），标注 (dir)/(file) 类型，并附一句「When in doubt, use tools to verify and keep changes focused on the working set.」；
• 结尾声明 No prior context summaries available. Produce a brief carry-forward from the structured state alone.——即首轮压缩时没有历史简报可继承，只能基于结构化状态冷启动。

这样设计的原因正契合原文档的边界：结构化状态（模式、工作集、清单）是运行时可自动保全的，写进 user 消息即可；而决策、约束、假设、失败路线、开放问题这五类「不可再生状态」才是模型简报的专属职责，两者不重叠。

7.5 测试用例对行为的固化

deepseek_tui.rs 中的测试 deepseek_tui_compaction_request_uses_structured_state 验证了上述行为：构造一个包含 CONTEXT CHECKPOINT COMPACTION 文本、指向含 module.py、generated_file.txt、shell_proof.txt 的临时工作区的 Prompt 后，断言请求满足：

• model 为 deepseek-v4-flash，max_tokens 为 4096，temperature 为 0.2；
• 工具集为空（tool_kinds.is_empty()）；
• messages 恰有 2 条（system + user）；
• user 内容包含策略元数据三行与三个真实文件条目（如 - generated_file.txt (file)），且不包含工具名类条目。

该测试把「压缩请求的顶层形状」固化为回归基线，意味着调整提示词或参数时会立刻被 CI 捕获。

8. 与同目录压缩中继模板的分工

同目录下还有一份 compact.md（「Compaction Relay — Tier 9 (Precedent)」模板），二者容易混淆，但从源码结构看职责互补：

• 本文档（cycle_handoff_briefing.md）：写给正在跨界的模型，约束它如何产出 <carry_forward>——面向「交接的写端」；
• compact.md：写入新周期的系统提示词（build_system_prompt 将其作为独立段落拼接，见 deepseek_tui.rs），告诉接手方如何消费既有摘要——面向「交接的读端」。它规定摘要包含 Goal / Constraints / Progress（Done、In Progress、Blocked）/ Key Decisions / Next step 五段，并明确其权威等级：Tier 9 先例，「是方向参考而非法律」（use this summary as orientation, not as law）——声明阻塞不约束说「继续」的用户，声称完成也不推翻「工作未完成」的证据。

两者再叠加 base.md 中的宪法条款，就构成完整的设计闭环：第六条（The Legacy of Coordination）要求「Leave the handoff truthful. The next intelligence — human or machine — should not have to re-discover what you already learned.」（留下诚实的交接，让下一个智能体不必重新发现你已经学会的东西）；第七条（The Hierarchy of Law）则将 handoff 置于低于用户当前指令、证据与记忆的层级。可以说，<carry_forward> 的「精确写承重状态、其余信任归档」策略，正是宪法第六条在周期边界上的工程化落地。

9. 小结：一份可复用的交接简报检查清单

把原文档规则与仓库实现合并，跨上下文边界的交接可以沉淀为如下检查清单：

1. 决策：点名选择 + 使其成立的约束（可带量化依据，如示例中的 110K/128K 余量计算）；
2. 约束：代码库/环境/用户偏好中会让接手方踩坑的具体事实；
3. 假设：正在证伪什么，什么证据会改变判断；
4. 失败路线：方案名 + 具体失效原因，禁止「tried X, didn't work」；
5. 开放问题：需要用户裁决的阻塞项；
6. 排除：工具输出字节、已读文件内容、操作顺序复盘、一切铺垫性语言；
7. 格式：标签独占行、标签外零正文、无嵌套、外层不加代码围栏；
8. 预算：本仓库实现中简报上限 3,000 token、请求 max_tokens 4096、由 deepseek-v4-flash 以 temperature 0.2 在无工具隔离环境中生成；
9. 兜底纪律：recall_archive（BM25 检索归档，默认 3 条、上限 10 条）仅用于补漏；recall 频率高应触发对下一份简报的改进，而非依赖归档。

对构建长时程编码 Agent 的开发者而言，这份提示词的价值在于它把「上下文压缩」从单纯的 Token 裁剪问题，重新表述为一个有明确写端规范、读端权威等级、检索兜底与回归测试保障的交接协议——这正是本仓库 DeepSeek TUI harness 在周期化上下文管理上的核心设计。