oh-my-pi 上下文压缩摘要注入机制compaction-summary-context 模板如何让 Agent 基于先前工作继续【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇指南聚焦 oh-my-pi⌥ Coding agent with the IDE wired in长会话上下文压缩Context Compaction链路中的一个关键拼图——compaction-summary-context.md模板。它负责在压缩完成后把先前工作与工具状态以受控的方式重新注入后继 LLM 的上下文并约束模型必须基于先前工作继续、绝不重复先前工作。读完本文你将掌握该模板的逐行语义、它在消息转换层的真实组装方式以及它背后compact()全流程切割点选择、本地/远程摘要生成、摘要持久化与跨模型复用的源码级工作原理可直接用于理解或定制 oh-my-pi 类 Coding Agent 的长会话记忆机制。模板本体五行的语义密度关联文档 compaction-summary-context.md 全文仅 5 行属于典型的短而强的指令模板Prior model work/tool state available. MUST build on prior work; NEVER duplicate prior work. summary {{summary}} /summary逐行拆解其语义Prior model work/tool state available.——显式告知后继模型当前上下文并非空白起点此前已存在模型工作产物与工具状态历史工具调用结果、文件操作、决策记录等。这是为后续约束做的事实铺垫。MUST build on prior work; NEVER duplicate prior work.——核心指令全部大写强调。它把继续推进设为强约束把重复劳动设为禁区防止压缩后模型把已完成的步骤再执行一遍例如重复应用已打过的补丁、重复运行已跑过的命令。summary…/summary与{{summary}}占位符——XML 风格标签用于划定摘要的边界{{summary}}是模板渲染时被真实摘要文本替换的插槽。标签边界的存在让模型能够明确区分注入的历史摘要与当前实时对话。这种短指令 标签占位符的结构与同目录其他上下文模板一脉相承例如 handoff-summary-context.md 使用handoff{{summary}}/handoff包裹交接文档并强调这是你自己的工作记忆不是用户输入branch-summary-context.md 则以Branch-return summary:前缀加summary标签注入分支回归摘要。渲染与组装从模板到真实请求消息模板本身是纯文本资源真正把它变成请求消息的是消息转换层 messages.ts。模板的加载与渲染函数模板通过with { type: text }作为文本资源导入messages.tsimport compactionSummaryContextPrompt from ./prompts/compaction-summary-context.md with { type: text };随后定义渲染函数messages.tsexport function renderCompactionSummaryContext(summary: string): string { return prompt.render(COMPACTION_SUMMARY_TEMPLATE, { summary }); }prompt.render来自oh-my-pi/pi-utils作用是把模板中的{{summary}}占位符替换为实际的摘要文本——这正是上文模板第三部分起作用的环节。compactionSummary 消息的 LLM 形态转换convertMessageToLlmmessages.ts是核心域消息到 provider 请求消息的单一事实来源。对role compactionSummary的消息其转换逻辑为messages.tscase compactionSummary: return { role: user, content: message.blocks ! undefined ? [{ type: text as const, text: message.summary }, ...message.blocks] : [ { type: text as const, text: message.method handoff ? renderHandoffSummaryContext(message.summary) : renderCompactionSummaryContext(message.summary), }, ...(message.images ?? []), ], attribution: agent, historyRewriteAt: message.timestamp, providerPayload: message.providerPayload, timestamp: message.timestamp, };关键设计点以user角色注入摘要被包装为一条user消息但attribution: agent明确标记其来源是 Agent 自身而非真实用户避免模型把历史摘要误读为新指令。historyRewriteAt标记该消息是历史重写压缩的产物供上层做计费归属与语义区分。handoff 分支当method handoff时改用 handoff-summary-context.md 模板该模板显式声明交接文档已完整存在除非用户明确要求绝不再写一份交接文档可防止后继实例误把第一人称的 Next Steps 当作新用户指令。snapcompact 分支当存在blocks快照压缩产生的图像/文本块时直接以summary blocks拼装跳过旧式包装。图像透传images数组被原样附加保证远程压缩如 OpenAI remote compaction保留的多模态内容可以继续回放。此外findValidCutPointscompaction.ts把compactionSummary与user、assistant、branchSummary等一并列为合法切割点意味着压缩边界可以落在上一次压缩摘要处实现迭代式压缩。摘要从何而来compact() 全流程模板注入的{{summary}}文本由 compaction.ts 的compact()compaction.ts配合prepareCompaction()生成。流程分四步。第一步准备阶段 prepareCompactionprepareCompactioncompaction.ts在不动上下文的前提下规划压缩方案边界处理尊重/clear重置边界与上一次可复用的压缩边界若最近的压缩条目对当前模型不可读则视为不存在并向后展开原始消息见下文的findReadableCompactionIndex。切割点选择findCutPointcompaction.ts从最新消息往回累计 token直到达到keepRecentTokens预算切割点只能落在user/assistant/custom/branchSummary/compactionSummary等消息上绝不切割在toolResult上工具结果必须跟随其工具调用保证消息对完整。三类消息划分messagesToSummarize将被摘要并丢弃的历史、turnPrefixMessages若切割落在回合中间被切割的回合前半段、recentMessages压缩后完整保留的近段历史。第二步远程压缩优先compact()内部按优先级尝试 provider 原生远程压缩OpenAI V2 流式远程压缩当模型满足shouldUseCompactionV2Streaming时compaction.ts把消息转换为 OpenAI Responses/Codex 原生输入含上一轮远程压缩的replacementHistory拼接通过 compaction-v2-streaming.ts 发起远程请求并在preserveData中持久化 provider 回放载荷。V1 远程压缩回退V2 失败时信号中止除外回退到 openai.ts 的 V1 远程压缩。本地摘要兜底远程压缩不可用或全部失败时降级为本地 LLM 摘要。远程压缩成功后summary仅为占位文本如 compaction.ts 的formatRemoteCompactionSummaryRemote compaction preserved provider-native history for this session. Compaction processed N input tokens.真正历史存放在 provider 回放载荷中只有当下一次压缩无法复用该载荷时例如切换了 provider才会重新展开原始消息做本地摘要见remotePreserveReusablecompaction.ts。第三步本地摘要生成 generateSummary本地路径调用generateSummarycompaction.ts会话先被serializeConversationForSummary序列化为文本包裹进conversation…/conversation标签防止模型续写而非总结。若存在上一次摘要则以previous-summary…/previous-summary携带并改用增量更新模板 compaction-update-summary.md要求保留旧摘要全部信息、把完成的 In Progress 移到 Done、更新 Next Steps、保留精确文件路径/函数名/错误信息实现迭代式压缩。基础摘要模板 compaction-summary.md 规定输出为结构化的 handoff 摘要Goal、Constraints Preferences、ProgressDone / In Progress / Blocked、Key Decisions、Next Steps、Critical Context、Additional Notes并强制只输出结构化摘要、绝不输出额外文本。摘要 token 预算maxTokens min(floor(0.8 * reserveTokens), MAX_SUMMARY_TOKENS)其中DEFAULT_RESERVE_TOKENS 16384、MAX_SUMMARY_TOKENS与其相等compaction.ts保证压缩比随窗口增大而改善而不是退化。若单次窗口装不下整个会话planSummaryWindows会把消息切分为多个窗口折叠式依次摘要——每个窗口以上一个窗口产出的摘要为previousSummary继续增量更新。第四步短摘要与文件操作回填generateShortSummarycompaction.ts基于recentMessages与历史摘要生成 PR 风格的展示用短摘要预算被压到min(512, floor(0.2 * reserveTokens))。computeFileLists与upsertFileOperations把历史中被读取/修改的文件列表回填进摘要供后继实例快速恢复文件操作上下文。摘要的持久化与上下文恢复压缩结果被封装为CompactionSummaryMessagemessages.ts携带summary、shortSummary、tokensBefore压缩前 token 数、tokensAfter压缩后估算、method如remote/soft/handoff、blocks/imagessnapcompact 图像块、warning等元数据作为会话条目持久化。后继模型恢复上下文时若存在可读的压缩条目findReadableCompactionIndexcompaction.ts从最新往回找到第一个当前模型可读的压缩边界。关键约束是remotePreserveReusableprovider 原生的远程压缩回放载荷只在当前模型与压缩时 provider 相同且远程回放仍启用时可复用否则该压缩条目对当前模型等于不存在后续压缩会越过它重新展开原始消息做本地摘要避免跨模型后上下文永久性失忆。恢复时正是通过本文主角renderCompactionSummaryContext(summary)把摘要文本包进summary…/summary注入或当method handoff时走 handoff 模板完成基于先前工作继续的上下文重建。触发器与阈值压缩何时发生模板注入是压缩的出口而压缩的入口由配置与阈值决定shouldCompactcompaction.ts在contextTokens thresholdTokens时触发。resolveThresholdTokenscompaction.ts优先采用thresholdTokens固定值钳制在[1, contextWindow - 1]否则按thresholdPercent比例计算最后兜底为contextWindow - reserveTokens。默认配置compaction.ts为enabled: true、strategy: context-full、keepRecentTokens: 20000、midTurnEnabled: true、autoContinue: true、remoteEnabled: true、remoteStreamingV2Enabled: truereserveTokens缺省时生效DEFAULT_RESERVE_TOKENS且小窗口模型会自动以窗口 15% 的比例预留替代resolveBudgetReserveTokenscompaction.ts。compactionContextTokenscompaction.ts对 provider 上报值与本地存储会话估算值取较大者防止上线前请求载荷被压缩扩展如 Headroom、混淆器、内联 snapcompact导致 provider 上报的 token 被低估、真实历史无限膨胀。同目录模板的分工一览compaction-summary-context.md不是孤岛它与prompts/目录下其他模板构成完整协作链prompts 目录模板文件职责compaction-summary-context.md压缩后摘要注入上下文的包装指令本文主角compaction-summary.md首次摘要生成的结构化输出模板handoff 格式compaction-update-summary.md迭代压缩时增量更新旧摘要的模板compaction-short-summary.md展示用 PR 风格短摘要模板compaction-turn-prefix.md回合中间切割时被切割回合前半段的摘要模板handoff-summary-context.md/handoff-document.md显式交接handoff文档的生成与注入branch-summary-context.md/branch-summary.md分支回归摘要的生成与注入snapcompact-archive-context.md旧 snapcompact 档案文本合并进摘要的格式auto-handoff-threshold-focus.md自动交接阈值聚焦提示summarization-system.md摘要系统级提示词file-operations.md文件操作提取规则context-window-truncated-output.md上下文窗口截断输出说明小结短模板、长链路的工程启示compaction-summary-context.md用 5 行文本解决了长会话 Coding Agent 的一个核心矛盾压缩节省了上下文空间却不能丢失已完成工作的记忆。其工程化价值体现在边界清晰summary标签 attribution: agent让模型能区分历史记忆与用户新指令约束显式MUST build on prior work; NEVER duplicate prior work 直接压制压缩后最常见的重复劳动问题链路完整从prepareCompaction切割、compact远程/本地摘要、generateSummary窗口折叠到convertMessageToLlm注入、findReadableCompactionIndex恢复模板只是这条链路末端的最后一句话但正是这句话决定了后继实例以何种心智模型解读注入的摘要。理解这条链路后若要为 oh-my-pi 定制长会话行为例如调整摘要格式、改变注入措辞、或新增第三类上下文模板可分别从 prompts 目录的模板、messages.ts 的转换层、以及 compaction.ts 的流程层入手三者各司其职、互不越界。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考