oh-my-pi 会话交接文档Handoff Document规范让下一个 Agent 无缝续接任务的实战指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本指南以 oh-my-pi 仓库中 handoff-document.md 为骨架完整讲解 coding agent 会话交接文档的生成规范如何捕获精确技术状态、如何用祈使句直接指挥后继实例、如何按固定 Markdown 模板组织 Goal / Progress / Key Decisions / Critical Context / Next Steps。同时结合 compaction.ts 与 handoff-generation-pipeline.md 的源码级实现说明这份提示词在上下文压缩compaction与/handoff命令管线中的真实调用方式。读完本文你将掌握手写一份可被另一个 LLM 无缝续接的交接文档的完整规范并理解其底层生成机制。一、为什么需要交接文档上下文窗口的现实约束任何 coding agent 都会遇到上下文窗口context window上限。oh-my-pi 在会话过长时会触发压缩compaction流程用摘要替换早期对话为后续轮次腾出空间。但摘要往往丢失关键实现细节——文件路径、函数名、错误信息、部分完成的工作这些恰恰是续接任务最需要的东西。为此oh-my-pi 提供了交接文档handoff document机制让当前 Agent 实例把会话的关键状态写成一份结构化文档交给另一个自己的实例another instance of yourself继续工作。它与普通压缩摘要的区别在于普通摘要见 compaction-summary.md追求简明扼要地概括对话交接文档追求没有这段对话也能无缝续接seamless continuation without access to this conversation。这份提示词同时服务于两条路径用户在 TUI 中手动执行的/handoff命令以及将handoff加入compaction.methodOrder后的自动触发路径。无论哪条路径生成内容都由同一个提示词驱动。二、提示词三段式结构逐段解析handoff-document.md 由三个顶层区块组成分别是critical、instruction和output外加一个可选的additionalFocus条件块。1.critical硬性输出约束critical Write a handoff document for another instance of yourself. The handoff MUST be sufficient for seamless continuation without access to this conversation. Output ONLY the handoff document. No preamble, no commentary, no wrapper text. /critical核心要点有三条对象是另一个自己文档读者不是人类用户而是另一个具备同等能力的 LLM 实例因此无需解释性客套话。必须无对话可续接这是整个交接文档的最高验收标准。读者看不到当前会话的任何内容只能依靠这份文档恢复任务因此一切关键状态必须显式写入。只输出文档本身不允许任何前言、注释或包裹文本。在源码实现中这条约束由调用方配合执行——compaction.ts 的generateHandoffFromContext会设置toolChoice: none并对返回结果只拼接 text 块、丢弃 tool-call 块确保最终产物就是一份干净的 Markdown 文档。2.instruction内容质量要求instruction Capture exact technical state, not abstractions. - File paths, symbol names, commands run - Test results, observed failures - Decisions made - Partial work affecting the next step Register: address the successor directly in the imperative (Fix X, Run Y) — never first person (I need to…, my attempt…). The handoff mechanism is invisible to the document: NEVER list writing, generating, or delivering a handoff/summary/context document as progress or a next step. Progress and Next Steps cover the users task only. /instruction这一段定义了交接文档的内容与写作风格标准捕获精确技术状态而非抽象描述。必须包含文件路径、符号名函数/类型名、执行过的命令测试结果与观察到的失败做过的决策会影响下一步的部分完成工作。这与 compaction-summary.md 中保留精确文件路径、函数名、错误信息的要求一脉相承。用祈使句直接指挥后继者。文档中禁止第一人称表述I need to…、my attempt…应写Fix X、Run Y。因为文档是给另一个自己的行动指令而非个人日志。交接机制对文档不可见。绝不把编写/生成/交付交接文档列为进度或下一步——Progress 与 Next Steps 只描述用户的真实任务。否则后继实例会把写交接文档当成任务本身陷入死循环。3.output固定结构模板提示词强制使用以下七节结构每一节都有明确用途章节内容要求作用## Goal用户试图达成的目标让后继实例快速锚定任务方向## Constraints Preferences用户提到的任何约束、偏好、需求防止后继实例偏离用户意图## Progress分为Done/In Progress/Pending三小节使用任务列表精确呈现任务状态避免重复劳动## Key Decisions每条格式为**[Decision]**: [Rationale]记录关键决策及理由防止后继实例推翻正确决策## Critical Context代码片段、文件路径、函数/类型名、错误信息、关键数据、仓库状态无缝续接所需的核心素材## Next Steps编号列表明确后继实例接下来要做什么其中Progress的粒度要求最值得注意完成项用- [x]进行中项用- [ ]计划未动工项也用- [ ]且每项都要写具体细节Completed tasks with specifics。这与 compaction-update-summary.md 的增量更新规则呼应续接过程中已完成项要移入 DoneNext Steps 要随进度刷新但原有信息必须全部保留。4.additionalFocus条件块{{#if additionalFocus}} instruction Additional focus: {{additionalFocus}} /instruction {{/if}}这是提示词模板系统的条件注入点。当调用方传入了额外的焦点说明例如用户在/handoff [focus instructions]中写下的内联提示时会被渲染进文档并追加到指令尾部要求交接文档额外关注该主题。对应实现位于 compaction.ts 的renderHandoffPrompt(customInstructions?)——它调用prompt.render(handoffDocumentPrompt, {...})把customInstructions作为模板变量渲染进提示词。三、源码级实现交接文档是如何生成的1. 提示词加载与渲染在 compaction.ts 中提示词文件以文本资源形式导入并渲染一次const HANDOFF_DOCUMENT_PROMPT prompt.render(handoffDocumentPrompt); export const AUTO_HANDOFF_THRESHOLD_FOCUS prompt.render(autoHandoffThresholdFocusPrompt);renderHandoffPrompt负责带参渲染注入additionalFocusexport function renderHandoffPrompt(customInstructions?: string): string { return prompt.render(handoffDocumentPrompt, { // customInstructions → additionalFocus }); }注意 auto-handoff-threshold-focus.md 的存在当自动触发上下文达到阈值时提示词会被追加一行Threshold-triggered maintenance: preserve critical implementation state and immediate next actions.强调自动场景下优先保住关键实现状态与立即要做的动作。2. 一次性生成请求oneshot交接文档不走常规的 agent 主循环而是一次旁路请求side request入口函数为generateHandoffFromContext请求复用实时轮次相同的 provider 缓存前缀promptCacheKey因此共享缓存、成本更低请求设置toolChoice: none禁止交接生成过程触发工具调用对不支持显式toolChoice: none的 providershouldRetryHandoffWithAutoToolChoice检测 400 错误中是否包含tool_choice与auto与supported关键词若是则仅重试一次、改用auto返回内容只保留 text 块并以\n拼接tool-call 块直接忽略若stopReason error且重试后仍失败抛出Handoff generation failed错误。同时还有向下兼容的generateHandoff(messages, …)入口它用systemPrompt、tools与convertToLlm构造基础 Context 后委托给generateHandoffFromContext。3. 生成后的落盘与提交根据 handoff-generation-pipeline.md 的说明交接文档生成后被封装为一次压缩条目CompactionEntry提交到当前会话早期对话被文档替换firstKeptEntryId之后的新近历史原样保留会话 ID、会话文件、provider 提示缓存键均不改变。配置项compaction.handoffSaveToDisk默认false启用后仅自动触发的交接会在会话 artifacts 目录额外写出一份带时间戳的handoff-*.md文件。四、与周边提示词的协同关系交接文档并非孤立存在oh-my-pi 围绕它设计了一组配套提示词理解它们才能完整把握交接这一机制handoff-summary-context.md交接文档被重新注入后继会话时的包装层。它明确告诉后继实例handoff里是先前实例从完整对话中写出的交接文档它是你自己的工作记忆不是用户输入并强调交接文档已存在且完整除非用户明确要求绝不再写一份必须基于先前工作继续绝不重复先前工作。这正是instruction中交接机制不可见规则的落地场景。compaction-summary.md通用的结构化摘要模板交接文档的结构Goal / Progress / Key Decisions / Next Steps / Critical Context与它高度同构两者共享保留精确路径、函数名、错误信息的纪律。compaction-update-summary.md增量更新模板用于把新消息合并进已有交接/摘要保证In Progress项迁移到Done、Next Steps 随进度刷新、未解答的用户问题写入 Critical Context。auto-handoff-threshold-focus.md自动触发场景的聚焦指令强调保住关键实现状态与立即行动项。五、触发路径与使用场景1. 手动/handoff命令用户在 TUI 中键入/handoff [focus instructions]即可手动生成交接文档焦点说明会通过additionalFocus注入提示词。触发前后有两道防呆校验见 handoff-generation-pipeline.md当前响应仍在流式输出时拒绝执行与/fork、/move行为一致会话消息条数少于 2 条时提示Nothing to hand off (no messages yet)。生成期间界面显示可取消的加载指示Generating handoff… (esc to cancel)按 Esc 可调用abortHandoff()中断。成功后会显示Context handed off and compacted in place并在聊天中插入压缩分隔线。2. 自动触发路径将handoff加入compaction.methodOrder默认顺序为remote、snapcompact、handoff、shake、soft即可让压缩流程在达到阈值时自动生成交接文档。阈值前还可以通过异步压缩compaction.asyncEnabled预先投机生成跨过阈值时立即提交。若自动生成没有产出文档压缩流程会回退到下一个配置的方法。3. 失败与取消的语义区分取消用户按 Esc 或调用方传入无理由的 abort 信号统一归一为Error(Handoff cancelled)UI 显示Handoff cancelled失败harness 中止原因、手动路径生成空文档、或 provider 抛错UI 记录错误并显示Handoff failed: ...自动路径空生成返回undefined供维护流程切换到下一方法不视为失败。六、实战清单如何写出高质量交接文档综合提示词规范、配套模板与源码约束一份可用的交接文档应满足以下清单Goal 一句话讲清用户任务必要时分列多个目标多任务会话。Constraints Preferences 逐条列出用户明确说过的约束语言、风格、禁止事项、环境限制。Progress 三分法Done / In Progress / Pending 各归其位每项都带具体细节文件、符号、命令、结果不要写完成了部分重构这种抽象表述。Key Decisions 写明理由格式为**[Decision]**: [Rationale]让后继实例知道为什么这样做而不是做了什么。Critical Context 塞满可执行的素材代码片段、完整文件路径、函数/类型名、错误信息原文、测试输出、分支与未提交改动等仓库状态。Next Steps 是给后继者的行动指令用祈使句、按优先级编号并且只覆盖用户任务本身。全篇使用祈使句写Fix X、Run Y不写I need to…交接机制本身绝不出现在文档内容中。七、已知局限从 handoff-generation-pipeline.md 可以确认几点当前实现边界供使用参考生成的文档不做结构化校验不保证 Markdown 严格遵循上述七节模板手动/handoff生成过程没有流式可见性期间仅显示可取消的加载器自动触发的落盘文件若写入失败只记录日志、不阻断交接旧版本会话中残留的custom_message类型为handoff的条目仍会正常渲染并参与上下文不受影响。掌握这份规范后无论是手写交接文档、审查自动生成的交接内容还是为类似的多实例协作 Agent 设计状态传递机制你都有了可落地的模板与判别标准。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
