oh-my-pi Snapcompact 上下文占位符注入将 AGENTS.md 指令压缩为 PNG 帧的提示词工程机制【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pioh-my-pi 的 Snapcompact inline imaging 机制会在请求发出前把系统提示中的 context 文件指令如 AGENTS.md、repo-rules、## Context段落以及冗长的历史工具结果渲染为高密度 PNG 帧以压缩在途 token。snapcompact-context-stub.md正是这一机制的关键一环当原文本被替换成图片后它作为占位符提示留在原位指导模型把图片当作被移走的原文来读取。读完本文你将理解该占位符的注入时机、与其余四个 prompt 文件的配合关系、背后SnapcompactInlineTransformer的完整调用链以及如何通过snapcompact.*配置项启用和调优这套机制。占位符文件本身一行指令承载的职责snapcompact-context-stub.md 全文只有一行Loaded context-file instructions: PNG image(s) attached below at the first user message start. At this marker, read every frame in order; apply as if original context-file text remained here.它被编译进 snapcompact-inline.ts与contextFramesNote、systemFramesNote、systemStub、toolResultNote一起通过with { type: text }导入。它回答模型三个问题发生了什么——你本来加载的 context-file 指令被移走了去哪找——图片附加在第一条用户消息的开头按顺序读取怎么用——把每一帧当作被移走的原文等价物apply as if original context-file text remained here而不是普通配图。这正是一份指令占位符instruction stub图片只承载文本密度语义权威性仍来自这行文字对模型阅读行为的约束。占位符的注入点replaceContextSections的文本替换逻辑占位符并非随便贴在系统提示里而是精确替换掉被图片化的原文段落。核心逻辑在 selectSystemPromptImageTarget 和 replaceContextSectionsconst CONTEXT_SECTION_PATTERNS [ /repo-rules\n[\s\S]*?\n\/repo-rules/g, /## Context\ninstructions\n[\s\S]*?\n\/instructions/g, ] as const; function replaceContextSections(block: string, extracted: string[]): string { let replaced block; for (const pattern of CONTEXT_SECTION_PATTERNS) { replaced replaced.replace(pattern, match { extracted.push(match.trim()); return contextStub.trim(); }); } return replaced; }也就是说当snapcompact.systemPrompt设为agents-md时系统提示中两类结构——repo-rules…/repo-rules标签块以及## Context标题下instructions…/instructions包裹的段落——会整体被提取出来存入extracted原位替换为contextStub.trim()。这正是 AGENTS.md 等 context 文件指令被加载进系统提示后的典型形态因此该模式又被称为仅搬走 context 文件指令。被提取的原文随后拼接为一段文本经snapcompact.frames(text, { shape })估算帧数最终在第一条用户消息前插入渲染出的 PNG 帧同时把contextFramesNote作为该帧前的文字说明。三种模式与兄弟占位符一套完整的图片化替换家族SnapcompactSystemPromptMode定义了系统提示图片化的三种模式snapcompact-inline.ts模式行为none系统提示保持纯文本不做任何替换agents-md仅替换repo-rules与## Context instructions段落占位符为 context-stuball整个系统提示被替换为systemStub说明文本改用systemFramesNote五种 prompt 文件按场景各司其职全部位于 packages/coding-agent/src/prompts/system/snapcompact-context-stub.md——context 文件指令段的原位占位符本文主角snapcompact-context-frames-note.md——附加在第一条用户消息前的说明读下面的图片把它们当作被替换的 context 文件snapcompact-system-stub.md——all模式下整份系统提示的原位占位符图片是权威的操作指令优先读取并按权威执行snapcompact-system-frames-note.md——all模式下用户消息前的说明文字snapcompact-toolresult-note.md——历史工具结果被图片化后随帧附带的说明其中特别注明这是刻意的上下文节省行为不是故障不要重跑工具或上报问题并解释源图片位置标记的对应关系。注意到 snapcompact-inline.ts 中系统提示被替换后用户消息的content被重组为[{ type: text, text: userNote }, ...frames, ...originalContent]——即说明文字 帧 原用户消息内容依次排列与 stub 中image(s) attached below at the first user message start的描述完全对应。触发链路transformProviderContext中的执行顺序占位符替换不是独立的文本处理而是 agent 循环里每次请求前的一段转换管线。在 sdk.ts 中SnapcompactInlineTransformer在transformProviderContext钩子里按固定顺序执行obfuscateProviderContext——可选的混淆器先行snapcompactInline.transform——本机制核心计划交换planInlineSwaps、渲染帧、把 stub 写回系统提示、把帧挂到第一条用户消息clampProviderContextImages——按提供商的图片预算裁剪超出的图片块normalizeProviderContextImagesForModel——按模型归一化图片格式dropUnreadableContextImages——剔除无法解码的图片块降级为文字占位blobBroker.decorateContext——将内联字节换成可服务的远程 URL若配置了 blob brokerdateCwdReminder.transform——把日期/工作目录提醒注入首条用户消息。关键约束在文件头注释中写得很明确transform 只构造新的 message 对象绝不修改输入的content数组引用因为输入共享了持久化SessionMessageEntry的引用直接改动会把渲染出的图片泄漏进session.jsonl。因此帧是每次请求瞬态生成的历史文件里永远只有文本。交换策略与门控什么时候才值得图片化planInlineSwapssnapcompact-inline.ts是唯一决策入口实时请求与/context节省估算共用同一份规则保证二者永不打架工具结果门控MIN_TOOL_RESULT_TOKENS 3000——低于 3000 token 的工具结果绝不栅格化文本足够便宜isError的工具结果必须保持纯文本提供商 API 校验需要节省裕度SAVINGS_MARGIN 0.9——只有帧数 × frameTokenEstimate textTokens × 0.9才渲染保证图片 token 至少比原文本便宜 10%系统提示帧上限MAX_SYSTEM_PROMPT_FRAMES 6预算约束先扣掉上下文中已存在的图片数得到剩余预算系统提示交换放在工具结果之后只用剩下的预算跳过而非停止单个候选超出剩余预算时跳过它继续看后面的更小候选且最新一条工具结果永远保持文本保证最新输出清晰可读、利于缓存稳定性。预算来自 snapcompact.ts 的PROVIDER_IMAGE_BUDGETS与providerImageBudget各提供商有独立预算表未知名提供商回退到DEFAULT_PROVIDER_IMAGE_BUDGET 5。estimateInlineSavingssnapcompact-inline.ts据此输出visionCapable、systemPrompt、toolResults三组估算/context面板可预览下一请求将省多少 token。缓存与懒渲染避免重复栅格化SnapcompactInlineTransformer内部维护两个渲染缓存snapcompact-inline.ts#toolCache以toolCallId为键、Bun.hash(text)为内容指纹每次 transform 后用当前上下文中存活的toolCallId清掉失效条目缓存大小受实时历史约束#systemCache以整个待图片化系统提示文本的 hash 为指纹命中即复用。#framesFor优先调用构造时注入的frameSinkblob broker 的懒渲染服务帧在缓存里只是小占位符{ data: , url }真正的 PNG 只在提供商实际抓取 URL 时才栅格化内存里从不囤积像素。这也是 provider-image-budget.ts 注释里提到的形态transform 先于图片裁剪执行因此它见到的占位符已经是引用形状不会误判为待解码的内联字节。配置项与实操参数在 settings-schema.ts 中本机制暴露为三个实验性配置UI 位于 context 标签页的 Experimental 分组配置项类型默认值说明snapcompact.systemPromptenumnone/agents-md/allnone是否将系统提示或其 context 文件段图片化仅视觉模型生效节省 token 但会失去被图片化文本的提示缓存snapcompact.toolResultsbooleanfalse是否将大体积历史工具结果渲染为 PNG省下累积的 read/search 输出snapcompact.shapeenumauto 各形状变体auto帧的排版形状auto按当前模型自动挑选回退到其提供商家族兼容性细节settings.ts 会把旧版布尔值snapcompact.systemPrompt自动迁移为枚举——true→allfalse→none。snapcompact.shape的主要变体详见 schema 描述变体特征8x8r-bw/8x8r-sentunscii 方块字格每行重复两遍后者按句子换色6x6u-bw/6x6u-sent6x6 最密可读格帧数最少5x8-bw/5x8-sent最初的 snapcompact 形状X.org 5x8 字形8on22-bw8x13 字形配 8x22 行距OpenAI/Google 默认11on16-bw8x13 字形配 11x16 字距Anthropic 默认silver16-bw内嵌 Silver TrueType 字体 16px 网格面向 CJK 等非拉丁文本doc-8on16-bw/doc-8on16-sent/doc-8on16-sent-dim双栏报纸式排版可选句子换色与虚词压暗建议启用顺序先snapcompact.toolResults true观察长会话中累积工具输出的节省再试snapcompact.systemPrompt agents-md仅图片化 AGENTS.md 等 context 指令风险面最小最后才考虑all。由于图片化会破坏对应文本的提示缓存schema 描述已明确提示 loses prompt caching for imaged text对依赖前缀缓存的开源权重模型需权衡每次请求的 in-flight 节省与缓存命中的长期收益。局限性与兜底设计仅视觉模型生效model.input不含image时 transform 直接原样返回上下文snapcompact-inline.ts因为纯文本提供商会静默丢弃图片栅格化等于丢内容预算耗尽回退一旦预算被已附带的归档图片或系统提示帧花光工具结果原样以文本发送损坏图片兜底若帧或历史图片无法解码provider-image-budget.ts 的dropUnreadableContextImages会把不可读块降级为[image omitted: undecodable …]文字而不是让整个请求被提供商拒绝不出现在历史帧只存在于出站Context的瞬时副本session.jsonl中永远只有被 stub 替换前的文本形态onToolResultSavings追加式账本sdk.ts是帧 token 节省的唯一痕迹。从源码结构看这套文本 → 密集 PNG 帧 原位占位符指令的模式是 oh-my-pi 应对长上下文预算的核心实验路径占位符文件虽短却负责在语义上把图片即原文的阅读契约固定下来缺了它模型将无法区分附带截图与被替换的指令整个压缩机制就会失去保真度。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-pi Snapcompact 上下文占位符注入：将 AGENTS.md 指令压缩为 PNG 帧的提示词工程机制
oh-my-pi Snapcompact 上下文占位符注入将 AGENTS.md 指令压缩为 PNG 帧的提示词工程机制【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pioh-my-pi 的 Snapcompact inline imaging 机制会在请求发出前把系统提示中的 context 文件指令如 AGENTS.md、repo-rules、## Context段落以及冗长的历史工具结果渲染为高密度 PNG 帧以压缩在途 token。snapcompact-context-stub.md正是这一机制的关键一环当原文本被替换成图片后它作为占位符提示留在原位指导模型把图片当作被移走的原文来读取。读完本文你将理解该占位符的注入时机、与其余四个 prompt 文件的配合关系、背后SnapcompactInlineTransformer的完整调用链以及如何通过snapcompact.*配置项启用和调优这套机制。占位符文件本身一行指令承载的职责snapcompact-context-stub.md 全文只有一行Loaded context-file instructions: PNG image(s) attached below at the first user message start. At this marker, read every frame in order; apply as if original context-file text remained here.它被编译进 snapcompact-inline.ts与contextFramesNote、systemFramesNote、systemStub、toolResultNote一起通过with { type: text }导入。它回答模型三个问题发生了什么——你本来加载的 context-file 指令被移走了去哪找——图片附加在第一条用户消息的开头按顺序读取怎么用——把每一帧当作被移走的原文等价物apply as if original context-file text remained here而不是普通配图。这正是一份指令占位符instruction stub图片只承载文本密度语义权威性仍来自这行文字对模型阅读行为的约束。占位符的注入点replaceContextSections的文本替换逻辑占位符并非随便贴在系统提示里而是精确替换掉被图片化的原文段落。核心逻辑在 selectSystemPromptImageTarget 和 replaceContextSectionsconst CONTEXT_SECTION_PATTERNS [ /repo-rules\n[\s\S]*?\n\/repo-rules/g, /## Context\ninstructions\n[\s\S]*?\n\/instructions/g, ] as const; function replaceContextSections(block: string, extracted: string[]): string { let replaced block; for (const pattern of CONTEXT_SECTION_PATTERNS) { replaced replaced.replace(pattern, match { extracted.push(match.trim()); return contextStub.trim(); }); } return replaced; }也就是说当snapcompact.systemPrompt设为agents-md时系统提示中两类结构——repo-rules…/repo-rules标签块以及## Context标题下instructions…/instructions包裹的段落——会整体被提取出来存入extracted原位替换为contextStub.trim()。这正是 AGENTS.md 等 context 文件指令被加载进系统提示后的典型形态因此该模式又被称为仅搬走 context 文件指令。被提取的原文随后拼接为一段文本经snapcompact.frames(text, { shape })估算帧数最终在第一条用户消息前插入渲染出的 PNG 帧同时把contextFramesNote作为该帧前的文字说明。三种模式与兄弟占位符一套完整的图片化替换家族SnapcompactSystemPromptMode定义了系统提示图片化的三种模式snapcompact-inline.ts模式行为none系统提示保持纯文本不做任何替换agents-md仅替换repo-rules与## Context instructions段落占位符为 context-stuball整个系统提示被替换为systemStub说明文本改用systemFramesNote五种 prompt 文件按场景各司其职全部位于 packages/coding-agent/src/prompts/system/snapcompact-context-stub.md——context 文件指令段的原位占位符本文主角snapcompact-context-frames-note.md——附加在第一条用户消息前的说明读下面的图片把它们当作被替换的 context 文件snapcompact-system-stub.md——all模式下整份系统提示的原位占位符图片是权威的操作指令优先读取并按权威执行snapcompact-system-frames-note.md——all模式下用户消息前的说明文字snapcompact-toolresult-note.md——历史工具结果被图片化后随帧附带的说明其中特别注明这是刻意的上下文节省行为不是故障不要重跑工具或上报问题并解释源图片位置标记的对应关系。注意到 snapcompact-inline.ts 中系统提示被替换后用户消息的content被重组为[{ type: text, text: userNote }, ...frames, ...originalContent]——即说明文字 帧 原用户消息内容依次排列与 stub 中image(s) attached below at the first user message start的描述完全对应。触发链路transformProviderContext中的执行顺序占位符替换不是独立的文本处理而是 agent 循环里每次请求前的一段转换管线。在 sdk.ts 中SnapcompactInlineTransformer在transformProviderContext钩子里按固定顺序执行obfuscateProviderContext——可选的混淆器先行snapcompactInline.transform——本机制核心计划交换planInlineSwaps、渲染帧、把 stub 写回系统提示、把帧挂到第一条用户消息clampProviderContextImages——按提供商的图片预算裁剪超出的图片块normalizeProviderContextImagesForModel——按模型归一化图片格式dropUnreadableContextImages——剔除无法解码的图片块降级为文字占位blobBroker.decorateContext——将内联字节换成可服务的远程 URL若配置了 blob brokerdateCwdReminder.transform——把日期/工作目录提醒注入首条用户消息。关键约束在文件头注释中写得很明确transform 只构造新的 message 对象绝不修改输入的content数组引用因为输入共享了持久化SessionMessageEntry的引用直接改动会把渲染出的图片泄漏进session.jsonl。因此帧是每次请求瞬态生成的历史文件里永远只有文本。交换策略与门控什么时候才值得图片化planInlineSwapssnapcompact-inline.ts是唯一决策入口实时请求与/context节省估算共用同一份规则保证二者永不打架工具结果门控MIN_TOOL_RESULT_TOKENS 3000——低于 3000 token 的工具结果绝不栅格化文本足够便宜isError的工具结果必须保持纯文本提供商 API 校验需要节省裕度SAVINGS_MARGIN 0.9——只有帧数 × frameTokenEstimate textTokens × 0.9才渲染保证图片 token 至少比原文本便宜 10%系统提示帧上限MAX_SYSTEM_PROMPT_FRAMES 6预算约束先扣掉上下文中已存在的图片数得到剩余预算系统提示交换放在工具结果之后只用剩下的预算跳过而非停止单个候选超出剩余预算时跳过它继续看后面的更小候选且最新一条工具结果永远保持文本保证最新输出清晰可读、利于缓存稳定性。预算来自 snapcompact.ts 的PROVIDER_IMAGE_BUDGETS与providerImageBudget各提供商有独立预算表未知名提供商回退到DEFAULT_PROVIDER_IMAGE_BUDGET 5。estimateInlineSavingssnapcompact-inline.ts据此输出visionCapable、systemPrompt、toolResults三组估算/context面板可预览下一请求将省多少 token。缓存与懒渲染避免重复栅格化SnapcompactInlineTransformer内部维护两个渲染缓存snapcompact-inline.ts#toolCache以toolCallId为键、Bun.hash(text)为内容指纹每次 transform 后用当前上下文中存活的toolCallId清掉失效条目缓存大小受实时历史约束#systemCache以整个待图片化系统提示文本的 hash 为指纹命中即复用。#framesFor优先调用构造时注入的frameSinkblob broker 的懒渲染服务帧在缓存里只是小占位符{ data: , url }真正的 PNG 只在提供商实际抓取 URL 时才栅格化内存里从不囤积像素。这也是 provider-image-budget.ts 注释里提到的形态transform 先于图片裁剪执行因此它见到的占位符已经是引用形状不会误判为待解码的内联字节。配置项与实操参数在 settings-schema.ts 中本机制暴露为三个实验性配置UI 位于 context 标签页的 Experimental 分组配置项类型默认值说明snapcompact.systemPromptenumnone/agents-md/allnone是否将系统提示或其 context 文件段图片化仅视觉模型生效节省 token 但会失去被图片化文本的提示缓存snapcompact.toolResultsbooleanfalse是否将大体积历史工具结果渲染为 PNG省下累积的 read/search 输出snapcompact.shapeenumauto 各形状变体auto帧的排版形状auto按当前模型自动挑选回退到其提供商家族兼容性细节settings.ts 会把旧版布尔值snapcompact.systemPrompt自动迁移为枚举——true→allfalse→none。snapcompact.shape的主要变体详见 schema 描述变体特征8x8r-bw/8x8r-sentunscii 方块字格每行重复两遍后者按句子换色6x6u-bw/6x6u-sent6x6 最密可读格帧数最少5x8-bw/5x8-sent最初的 snapcompact 形状X.org 5x8 字形8on22-bw8x13 字形配 8x22 行距OpenAI/Google 默认11on16-bw8x13 字形配 11x16 字距Anthropic 默认silver16-bw内嵌 Silver TrueType 字体 16px 网格面向 CJK 等非拉丁文本doc-8on16-bw/doc-8on16-sent/doc-8on16-sent-dim双栏报纸式排版可选句子换色与虚词压暗建议启用顺序先snapcompact.toolResults true观察长会话中累积工具输出的节省再试snapcompact.systemPrompt agents-md仅图片化 AGENTS.md 等 context 指令风险面最小最后才考虑all。由于图片化会破坏对应文本的提示缓存schema 描述已明确提示 loses prompt caching for imaged text对依赖前缀缓存的开源权重模型需权衡每次请求的 in-flight 节省与缓存命中的长期收益。局限性与兜底设计仅视觉模型生效model.input不含image时 transform 直接原样返回上下文snapcompact-inline.ts因为纯文本提供商会静默丢弃图片栅格化等于丢内容预算耗尽回退一旦预算被已附带的归档图片或系统提示帧花光工具结果原样以文本发送损坏图片兜底若帧或历史图片无法解码provider-image-budget.ts 的dropUnreadableContextImages会把不可读块降级为[image omitted: undecodable …]文字而不是让整个请求被提供商拒绝不出现在历史帧只存在于出站Context的瞬时副本session.jsonl中永远只有被 stub 替换前的文本形态onToolResultSavings追加式账本sdk.ts是帧 token 节省的唯一痕迹。从源码结构看这套文本 → 密集 PNG 帧 原位占位符指令的模式是 oh-my-pi 应对长上下文预算的核心实验路径占位符文件虽短却负责在语义上把图片即原文的阅读契约固定下来缺了它模型将无法区分附带截图与被替换的指令整个压缩机制就会失去保真度。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考