oh-my-pi Snapcompact 压缩摘要模板解析把弃置会话历史渲染成位图帧供视觉模型直接回读【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-piSnapcompact 是 oh-my-pi 上下文压缩管线中的一种本地化归档策略它不再让 LLM 把被丢弃的会话历史概括成一段文字而是将序列化后的对话逐页渲染成密集的像素字体 PNG 帧让具备视觉能力的模型像档案管理员一样直接读图回放历史。本文以 packages/snapcompact/src/prompts/snapcompact-summary.md 模板为核心结合 packages/snapcompact/src/snapcompact.ts 的引擎实现、docs/compaction.md 的管线文档与 packages/coding-agent/src/config/settings-schema.ts 的配置定义完整讲解该摘要模板的语法、渲染上下文、帧结构读取约定与全部可配置参数读完即可理解并二次开发 snapcompact 的摘要与归档格式。摘要模板的定位压缩后的会话续接说明snapcompact-summary.md是 snapcompact 压缩条目CompactionEntry中summary字段的渲染模板。与传统的 LLM 摘要不同snapcompact 压缩后的summary只是给模型的一小段续接引导resume lead-in真正的历史内容存放在preserveData.snapcompact的帧归档Archive里并在每次重建上下文时以文本边 图片中的顺序重新拼接成消息块。模板全文如下{{#if}}为 Handlebars 条件块由 packages/utils/src/prompt.ts 的模板引擎渲染Resume prior conversation. Earlier turns archived under HISTORY below, oldest→newest. Read HISTORY fully; continue the live conversation following it. Archived transcript scopes: - ¶user:, ¶think:, ¶ai:, ¶call:: user, assistant reasoning, assistant reply, tool call. - Unprefixed following lines: current scope. Consecutive same-kind blocks omit repeated prefix. - Tool call: ¶call:name(args)//intent; trailing //intent optional. out…/out: tool output. Reading HISTORY: - Plain text: verbatim transcript; rely on it exactly. {{#if frameCount}}- Some middle sections: images, not text. Each image: one page of that transcript, in reading order between marked delimiters. Solid black cell: newline; runs of spaces collapse to one. {{#if docColumns}} - Frame: two side-by-side columns, each {{cols}} characters wide, up to {{rows}} rows tall; read left top→bottom, then right. {{else}} - Frame: one grid {{cols}} characters wide, up to {{rows}} rows tall; read left→right, top→bottom. No word wrap; words may break across rows. {{/if}}{{#if sentenceInk}} - Ink: six colors, one per sentence. {{/if}}{{#if stopwordDimmed}} - Function words: dim gray; content words: full ink. {{/if}}{{#if lineRepeated}} - Each line printed twice (white, then pale-yellow band); copies identical. {{/if}}{{/if}}{{#if includedPreviousSummary}}- HISTORY opens with a condensed digest of still-older context predating archived turns. {{/if}}{{#if truncatedChars}}- About {{truncatedChars}} characters of older middle history dropped to fit archive budget. {{/if}}- If an exact earlier detail matters and a section is unclear, re-derive from workspace (re-read files, re-run commands), rather than guess. {{#if files}}FILES {{files}} {{/if}}HISTORY 模板的主题可以拆成三层引导语续接指令、存档作用域说明¶前缀体系、帧读取指南条件渲染的如何读图。下文逐一展开。存档作用域¶前缀体系与无前缀续行模板要求模型以¶前缀识别四类会话角色¶user:—— 用户输入¶think:—— 助手推理thinking 块¶ai:—— 助手回复¶call:—— 工具调用及其内联的工具输出。连续的同类块省略重复前缀即无前缀续行属于当前作用域。工具调用写成¶call:name(args)//intent的形式//intent是可选的行内意图注释工具输出以out…/out包裹。这套语法由 serializeConversation 逐消息生成引擎实现与模板完全对应用户消息内容拼接为¶user:作用域助手消息按内容顺序缓冲 thinking 与 text分别在每个工具调用前冲刷为¶think:与¶ai:作用域工具调用渲染为name(args)block.intent或参数里的INTENT_FIELD优先作为//intent注释并从此参数中剔除与调用配对的工具结果合并进同一个¶call:块out包裹、默认以暗灰墨色打印只有孤儿结果才单独成块。模板中- Plain text: verbatim transcript; rely on it exactly.特别强调纯文本区域是逐字转写模型应当原样采信而图片区域则需要按后文的读取约定还原。帧读取指南条件渲染的四个维度frameCount为真时模板会追加图片中间段的读取说明并根据本次压缩的实际渲染参数通过四个条件块生成对应的几何与墨色约定。这些变量由 compact 在渲染模板时注入模板变量注入来源compact()内含义frameCountframes.length本次归档的帧数为 0 时不渲染任何读图说明docColumnshigh.columns 2是否为双栏报纸版式doc 形状colsframeCols.join( or )每行字符数网格宽度多帧列数不同时拼接为1568 or 1932之类rowsgeo.rows每帧网格行数去重后的唯一行数不计重复副本sentenceInkhigh.variant sent是否按句子边界循环六种墨色stopwordDimmedhigh.stopwordDim true功能词是否以暗灰墨色打印lineRepeatedhigh.lineRepeat 1每行是否重复打印冗余编码truncatedChars累计截断字符数为 0 时不输出截断说明includedPreviousSummary是否存在早于归档的旧摘要为真时说明 HISTORY 开头附有更早上下文的浓缩摘要filesformatFileList(...)结果文件操作清单为空时不渲染 FILES 段由此可归纳出三种读取几何约定各自对应一类帧形状形状定义见 SHAPE_VARIANTS单网格帧docColumns为假固定宽度网格从左到右、从上到下逐行读不换行——超宽单词会在行间断裂。典型代表11on16-bw、8on22-bw、8on16-bw、silver16-bw。双栏帧docColumns为真左右两栏每栏cols字符宽、最多rows行按左栏上到下再右栏上到下的顺序读。对应doc-8on16-bw/-sent/-sent-dim。墨色与重复约定sent变体按句子循环六种颜色辅助定位dim变体把功能词打成暗灰、内容词保持全墨突出对比8x8r系列把每行打印两遍第二遍落在淡黄色高亮带上作为冗余编码供模型交叉校验。此外还有两条渲染层约定实心黑格代表换行NEWLINE_GLYPH \u2588见 snapcompact.ts#L1145连续空格折叠为一个——这正是 normalize 对空白压缩后的结果以及若某段细节含糊不清回到工作区重新推导重读文件、重跑命令而不是猜测——防止模型对图里识别不清的内容自由发挥。从模板到上下文重建文本边缘 图片中间summary模板只是压缩入口产出的一部分。一次完整压缩的CompactionResult包含summary本模板渲染结果与preserveData[PRESERVE_KEY]snapcompact键下的 Archive。Archive 承载frames按从旧到新排序的 PNG 帧含cols/rows/chars及形状元数据text完整保留的、经过归一化的归档源文本——每次再压缩都从这里重新展开渲染而不是盲目携带旧 PNGtextHead/textTail两个时间边缘的逐字文本区totalChars/truncatedChars可读字符数与为适配预算而丢弃的字符数。每次重建上下文时historyBlocks 按最旧文本边缘 → 图片中间 → 最新文本边缘的顺序产出消息块帧归档Archive通过 getPreservedArchive 从preserveData校验恢复。因此模型最终看到的压缩段结构是HISTORY 引导语summary └─ 文本头部textHead逐字 └─ imaged middle below └─ 图片帧frames按序 └─ imaged middle above └─ 文本尾部textTail逐字这一边缘逐字、中间成像的布局由 planArchive 计算文本长度不超过两个边缘容量时全文本保留、零帧中间段超过maxFrames时再内部中心凹化HQ/LQ/HQ 三档边缘用高画质high形状中间用更密的低画质low形状见denseCompanion与HQ_EDGE_FRAMES 3并从最旧的密集切片开始丢弃。truncatedChars在模板中对应- About {{truncatedChars}} characters of older middle history dropped to fit archive budget.提醒模型中间历史有缺口includedPreviousSummary对应- HISTORY opens with a condensed digest of still-older context predating archived turns.说明头部嵌入了更早的浓缩摘要[Summary of earlier history]头见 compact()#L2078-L2081。FILES 段文件操作上下文的注入模板末尾的条件段在files非空时输出FILES分隔线下的分组文件树。文件清单由formatFileListsnapcompact.ts#L701-L712生成以 find 工具的目录树形状前缀折叠每个文件标注访问模式(Read)只读、(Write)写而未读或(RW)既读又写上限 20 个文件超出部分以[…N files elided…]收尾。这是对 docs/compaction.md 所述文件操作上下文的 snapcompact 侧落点LLM 摘要策略把files标签追加到 summary 之后upsertFileOperations而 snapcompact 则在模板内渲染 FILES 段二者共享同一套(Read)/(Write)/(RW)语义。文件集来自CompactionPreparation.fileOps的累积读/写/编辑集合URL scheme 路径如https://会被过滤isUrlSchemePath。帧形状与墨色约定的来龙去脉模板中的docColumns/cols/rows/sentenceInk/stopwordDimmed/lineRepeated都源于实际选用的帧形状。形状的选择链是resolveShapesnapcompact.ts#L404-L412显式传入variant非auto时强制该几何但按目标提供商的计费重新定价否则按模型 id 查idealShapeVariant如 Claude 系列11on16-bw、Opus 4.7 / Fable / Mythos 用 1932px 高分辨率帧、Gemini 用 2048px 的8on22-bw、GPT/Codex 与 Kimi 用8on22-bw、GLM 用8on16-bw未测量模型回退到 API 族FAMILY_VARIANTAnthropic/未知 →11on16-bwGoogle/OpenAI →8on22-bw文本驱动兜底resolveShapeForText默认字体不安全或 CJK 宽字符占比高isCjkHeavyText≥8 个宽字符且占比 ≥25%且 Silver 字体可安全渲染时自动切到silver16-bw的全宽双格网格。形状定义在 SHAPES 与SHAPE_VARIANTS中共 17 个研究变体unscii 方格8x8u/8x8r/6x6u其中8x8r行重复两遍、6x6u是最密集可读格、X.org 位图字体5x8/6x12/8x13含8on16/8on22/11on16的加行距/加字距变体、Silver TrueTypesilver16面向 CJK 与非拉丁文本以及双栏 doc 系列doc-8on16-bw/-sent/-sent-dim。墨色维度sent句子边界换色与bw纯黑、dim功能词暗灰组合出全部变体。帧尺寸上8on16-bw的 1568px 是 Anthropic 每帧 3,136 实测视觉 token 的基准1932px 是 4,784 visual-token 上限下最大的不降采样正方形(1932/28)² 4,761 ≤ 4,784同时低于 20 张图以上请求的 2000px 限制。接入压缩管线与相关设置snapcompact 作为compaction.methodOrder的一员接入自动维护默认顺序[remote, snapcompact, handoff, shake, soft]见 docs/compaction.md#L478。关键运行前提当前模型必须是视觉模型model.input包含image否则自动维护跳过 snapcompact 前进到下一方法全程本地、确定性执行无 LLM 调用、无 API key、无网络渲染走renderSnapcompactPng原生代码手动/compact遵循methodOrder除非用户给出自定义指令那将暗示定向的 LLM 摘要。配置文件中的相关设置settings-schema.ts#L2830-L2924设置项默认值说明snapcompact.shapeauto强制某个研究变体枚举即SHAPE_VARIANT_NAMESauto按模型与文本自动选择snapcompact.systemPromptnoneagents-md/all将系统提示词渲染为瞬时图片仅视觉模型省 token 但失去提示词缓存snapcompact.toolResultsfalse将大体积历史工具输出渲染为图片而非文本序列化预算则通过SerializeOptions配置默认值见 snapcompact.ts#L737-L748单条工具结果上限toolResultMaxChars 2000头 60% 尾 40% 截断TRUNCATE_HEAD_RATIO 0.6单参数值上限toolArgMaxChars 500单次调用参数列表上限toolCallMaxChars 2000dimToolResults true使工具噪声以暗灰墨色呈现而对话内容更突出includeThinking true面向 Claude 的调用方应设为false避免把推理回放给 Claude 触发其reasoning_extraction分类器见 issue #6093 相关注释。帧预算上MAX_FRAMES_DEFAULT 80是归档帧上限按提供商图片预算providerFrameBudget取 minFRAME_TOKEN_ESTIMATE 5024用于上下文预算的高估兜底FRAME_DATA_BYTES_BUDGET 3,000,000防止重建请求携带过大的 base64 载荷。模板自定义与再压缩自愈若要在 oh-my-pi 中修改本模板只需编辑packages/snapcompact/src/prompts/snapcompact-summary.md引擎在每次压缩时通过prompt.render(snapcompactSummaryPrompt, {...})重新渲染snapcompact.ts#L2145-L2157。模板是纯 Handlebars 条件渲染不感知具体帧内容因此新增说明条目例如针对新墨色或新几何约定的提示不会破坏既有归档的可读性。值得注意的自愈机制再压缩时引擎从Archive.text重新展开并整体重渲染而不是携带旧 PNG 前进includeThinking false时还会通过stripThinkingSections清洗旧归档源文本中的¶think:段修复历史遗留的推理回放问题。对归档源中任何被切碎的 data URL;base64,不完整载荷elideDataUrls会在源模式与归档模式下分别原子化替换为[data URL omitted: mime, N base64 chars]占位符避免损坏的图片引用在每次重建请求中反复导致 OpenAI 系提供方拒绝请求——这些防护与模板的图片中间段说明共同保证了压缩归档在长会话中的可重复读取。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
