caveman 中的 TOON 与 Pixel：两种可选上下文编码的选型、配置与源码剖析

caveman 中的 TOON 与 Pixel两种可选上下文编码的选型、配置与源码剖析【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/cavemanTOONToken-Oriented Object Notation和 Pixel 是 caveman 提供的两种可选上下文编码前者把结构化 JSON 重编码为紧凑文本后者把文本渲染成 PNG 交给视觉模型阅读。本文基于 docs/technical/toon-and-pixel.md 的原始约定结合engine/compressors/与engine/pixel/下的实现源码完整讲清两者的启用条件、配置参数、CLI 用法、适配的输入形态与失效fail-closed行为帮助你在代理会话中判断何时该开、何时绝不该开。一、两者的共同前提改变的是模型可见输入在展开细节之前先明确原文档给出的总纲TOON 和 pixel 都会改变模型可见的输入字节因此两者都不是 byte-safe字节安全的。它们只在输入形态和目标模型都匹配时才应使用。这一点在源码层面被明确落实TOON 被实现为无损重编码器重编码后语义不变但文本字节变了其安全等级为S4见 toon.go 中的ContentType()与SafetyClass()Pixel 包的文件头注释直接声明它是「S4 lossy transform」——把文本搬进图片块改变了模型可见字节因此转发前必须保证原始字节可通过 CCR上下文恢复存储找回任何解析、渲染或存储错误都必须 fail closed 回退为直通pass-through见 doc.go。这一「改字节前先留后路」的原则是理解后文所有启用规则的关键。二、TOON面向均匀表格 JSON 的紧凑重编码2.1 工作原理与示例TOON 把结构化数据重编码为紧凑的文本形式它对字段名一致的均匀对象数组收益最大。原文档给出的示例[ {name:Ada,role:engineer}, {name:Lin,role:designer} ]这类数组会被 TOON 把重复的键提升到共享表头、行内只保留单元格值。编码器 toon_encode.go 中的writeTOONArray正是这样做的对表格数组输出形如[2]{name,role}:的表头行行数 字段名列表随后每行输出以分隔符连接的标量值。原文档也明确提醒确切语法由实现及其测试夹具定义调用方应当使用编码器/解码器而不是手工拼写 TOON——因为解码器是严格校验的见 2.4 节。2.2 选择规则Selection rules原文档规定了三条硬性选择规则源码逐一印证只能显式请求或经特性开关启用Detect通用探测函数不会选中它。这是最强的一条约束。toon.go 中NewTOON的注释写明该编码器「只能通过强制Options.Type toon到达Detect 永远不会路由到它」。结果必须比原表示更小。若重编码后不省调用方应原样透传。编码器encodeTOON的返回契约是okfalse时调用方保持原始字节不变toon_encode.go 的注释。绝不用于 tool-call 参数。即使数据看起来结构相似改写工具参数也可能改变程序行为因此 TOON 只用于「作为上下文消费的数据」而非可执行参数。在 caveman 的配置体系中TOON 的持久开关是think.toon默认true「当更小且受支持时允许 TOON」对应环境变量CAVEMAN_TOON项目级 overlay 可以设置think.toon。这些参数见 configuration.md。2.3 CLI 用法TOON 的命令行入口caveman tools toon encode data.json caveman tools toon decode data.toonCLI 层的实现细节值得注意packages/cli/src/index.ts 中toonConvert通过 shell 调用caveman-engine toon encode|decode子命令它是无状态的。这意味着encode依赖caveman-engine二进制存在通过caveman setup安装、设置CAVEMAN_ENGINE_BIN或自行构建decode在引擎二进制缺失时会直接拒绝工作refusing to emit unconverted TOON as JSON即宁可报错也不产出「看起来像 JSON」的错误输出——这延续了 TOON 全链路「拒绝而非猜测」的基调。2.4 解码器的严格性原文档一句话「解码器拒绝畸形输入而不是发明缺失的结构」在 toon_decode.go 中可以找到完整的实现证据缩进必须为偶数TOON 以 2 个空格为一层缩进奇数缩进直接判非法scanTOONLines行数声明必须兑现表头[N]{...}:声明了 N 行解码器要求恰好有 N 个物理行跟随且每行的单元格数必须等于字段数否则拒绝容量防滥用解码器在分配数组容量之前先校验n 剩余行数即拒绝——注释说明这是防止「一个极小的不可信输入要求分配 GB 级内存」字段名必须是安全键字段名需匹配^[A-Za-z_][A-Za-z0-9_.-]*$safeTOONKey解码时对重复字段、未知结构一律返回失败。2.5 适配与不适配的输入原文档的适用性清单可对照源码中的判定逻辑适合 TOON 的输入对应tabularRows的判定条件toon_encode.go对象组成的均匀数组重复的字段名每行字段名与顺序必须完全一致标量单元格值null / bool / number / string单元格内含对象或数组即不合格数据是作为上下文消费而非可执行参数。应避免 TOON 的场景不规则的嵌套对象任一行结构偏离即整体回退为原样透传本来就紧凑的数据「必须更小」的硬规则会挡住它键顺序或字节表示重要的输入注意asTOONValue对对象键会做排序toon_encode.gotool-call 参数行为安全的硬禁区。工程上还有一个可观测点toon_eligible.go 中的tabularEligibility会递归统计「数组元素落在均匀扁平对象数组中的比例」用于量化一段数据有多「表格化」供上层决策与评测使用。三、Pixel把文本渲染成 PNG 交给视觉模型3.1 机制与风险Pixel 把文本转换为视觉模型可阅读的 PNG 图片能降低稠密源码类素材的文本 token 输入但引入光学识别与视觉排版风险——这正是它被定为 S4 有损变换的原因。渲染产物样例见文首配图 pixel-sample.png一整页密集文本被排布进固定几何的像素网格。Pixel 包是从 pxpipe 移植而来doc.go 注明移植来源与 MIT 许可并有意做了三处本地化PNG 字节来自 Go 标准库编码器测试比较解码后的像素而非 PNG 字节流、token 估算改用 caveman 离线的engine/tokens计数器、且不做实时的count_tokens探测。3.2 启用方式单会话与持久配置原文档给出的单会话启用命令caveman wrap --pixel agentCLI 的--pixel标志在 index.ts 的合法标志集中注册cli-reference.md 中进一步说明--pixel为「列入模型清单的模型」启用有损的文本转图像上下文传输。Pixel 还有一个关键约束要求显式模型允许清单。原文档给出的配置示例{ think: { pixel: { models: [model-name], density: balanced } } }对照 configuration.md 的完整参数表配置项默认值取值说明think.pixel.models[]模型名数组允许接收 pixel 上下文的模型think.pixel.densitybalancedconservative,balanced,maxpixel 打包密度注意think.pixel.models默认是空数组即默认任何模型都不接收 pixel 上下文——与「不允许从模型名推断支持」的原则一致。同时原文档提示项目 overlay 不能修改 pixel 设置configuration.md防止被检入的项目文件悄悄启用这种更具侵入性的变换。环境覆盖方面CAVE_PIXEL_MODELS与CAVE_PIXEL_DENSITY分别对应上述两项适合临时会话使用。3.3 密度档位conservative / balanced / max原文档说明density 支持conservative、balanced、max三档密度越高塞进单张图的文本越多小字号对模型越难读。density.go 中给出了每档的具体几何参数可以直接读出「密度」的工程含义档位单元格水平推进行距墨色层数conservative5px8px单色1balanced默认4px6px三色斑马纹1max4px6px三色斑马纹2叠加层两个 fail-closed 细节值得注意未知或非法的密度值一律落到 conservativenormalizeLevel环境变量CAVE_PIXEL_DENSITY未设置时默认balanced假值0/false/off等映射为conservative解析出的渲染参数还要经过「地板值」钳制applyDensityFloors斑马纹行距不低于 5px、单色不低于 6px确保任何配置都不会把字号压到模型无法识别的程度。3.4 模型兼容性为什么「能看图片」不够原文档的核心论断仅有视觉能力是不够的因为图片尺寸、细节设置、供应商 token 计费和文本识别质量各不相同所以 caveman 不会从模型名推断支持。源码层面这体现为显式的前缀匹配白名单而非能力推断applicability.go 中AllowedModelBases读取CAVE_PIXEL_MODELS或配置项未设置时使用内置默认基底列表Allowed对模型名先剥掉[...]变体标签再做精确匹配或base-前缀匹配——没有命中清单的模型一律不进入 pixel 路径密度解析ResolveDensity也执行 fail-closed未被识别为「密度可用」的模型无论请求哪一档都回落到 conservative 几何参数density.go并且 hi-res 画布只授予被显式识别的高分辨率模型族。3.5 恢复机制CCR 兜底 收益闸门原文档 Recovery 一节的三句话对应源码中的三道保障「原始文本在发出 pixel 输出之前先存入 CCR」——这是engine/pixel/doc.go的硬性要求调用方必须在转发变换后的字节前保证原始字节可经 CCR 找回任何存储失败都要 fail closed 回退到原始文本留在请求中「图片上下文应带清晰的恢复引用以便工具在需要字符级细节时取回精确源」——这保证模型在图片里看不清某个字时仍可通过工具链取回逐字符原文此外还有原文档未展开、但源码明确存在的收益闸门gate.go 的EvalCompressionProfitability会把「渲染成图后的预估 token 数含 10% 安全边际」与「原文本 token 数」对比并计入 prompt 缓存的创建/读取费率差1.25 / 0.10只有图片侧总成本低于文本侧时才判定为「盈利」——也就是说即使模型在白名单里不划算的短文本也不会走 pixel 路径。四、证据边界更小的本地表示 ≠ 更低的供应商成本原文档最后的 Evidence boundary 一节是对任何「省 token」宣传的清醒约束值得原样保留更小的本地表示不能推出更低的供应商成本因为供应商对图片输入和结构化文本输入的计费方式不同一个成立的「更便宜」声明需要针对确切模型的供应商 usage 数据或有文档记录的 benchmark「质量等价」同样需要超出「可恢复性」之外的任务级评测。Pixel 源码中的 token 数字也自我标注为本地估算doc.go 写明「The token reductions from this package are local estimates only」gate.go 的ImageCostSafetyMargin 1.10就是给本地估算留出的保守边际。评估这两项编码是否划算时请以你所在供应商对目标模型的实计 usage 为准而不是仓库内的估算值。五、小结一张启用决策表维度TOONPixel变换性质无损重编码字节变化S4 有损变换文本→图片默认是否启用不经过Detect必须显式/开关启用think.toon模型白名单默认空默认完全关闭启用方式caveman toon encode\|decode、think.toon/CAVEMAN_TOONcaveman wrap --pixel、think.pixel.models/CAVE_PIXEL_MODELS硬前提结果必须更小禁用于 tool-call 参数模型显式白名单 原始文本先入 CCR 收益闸门盈利参数调节无分隔符固定,编码失败即透传density:conservative/balanced/max非法值落conservative失败行为拒绝畸形输入不猜测结构解析/渲染/存储任一失败都回退直通原文两者共同的工程哲学是能力可以更强但启用必须显式任何一步不确定就回退到原始文本。理解这一点后你在自己的代理会话中配置这两个开关时就已经掌握了 caveman 上下文编码的核心决策框架。更多参数上下文可继续查阅 cli-reference.md、configuration.md 与 agent-wrapping.md。【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考