18 · 媒体落盘与图片读取
性质:旧线实现存档(2026-10-18 降级)。描述的是旧线
internal/mediaoffload的实现, 该代码已随 2026-10-03 仓体翻篇删除;本文不再作施工面。v6 的 media_offload 方案真源在 doc/32(核心裁定:对话只存 path——与本文 §2「正本不动、只改发送份」是反的,翻案理由见 doc/32 §2); 本文遗留问题(同图重读、seen 重置、缓存清理契约)的处理见 doc/32 §6。 对应《16》能力表第 4b 项(media_offload)。 这一层同时补上了 tako 一直缺的另一半:图片怎么进模型。两半要一起看,见第 4 节。
1. 要解决的问题
模型每看一眼历史,历史里的图片就要重发一次。一张截图动辄几百 KB,base64 之后更大,几轮下来光图片就能占掉半个窗口,而且这些字节模型早就看过了、这一轮根本用不上。
Octop 的做法(middleware/media_offload.py)是:媒体字节只在第一次给模型看的时候留在消息里,之后落盘到工作区,历史里只留一行占位文字,写上路径。模型真要再看,自己用 read_file 读回来。
2. 规则
tako 的历史正本是自己的 Memory(internal/compact 的 ReplMemory / webui 的会话内存),每一轮都把整份历史重新喂给 agent。所以规则不按 Octop 那样在消息块上打标记,而是按「这条消息在本轮的什么位置」判:
- 上一轮及更早的消息里的内联媒体 → 换占位符。模型这一轮不需要重看历史里的图。
- 本轮第一次看到的媒体(按内容 SHA-256 认「同一条」)→ 留字节,同时落盘。
- 本轮已经看过的,包括同一次请求里重复出现的同一张图 → 换占位符。
「本轮」的边界是最后一条 user 消息:它之前算历史,它之后算本轮。user 消息条数一变就重置「看过」的记录,所以下一轮重新 read_file 同一张图,模型还是能看到字节。
改写只发生在发给模型的那一份上。会话内存里的正本不动,event_log 里的原文也不动——占位符是给模型省窗口的,不是给人看的,页面上仍然显示原始内容。
小于 4 KB 的媒体不处理:换占位符省不下几个 token,反而让模型多绕一次工具调用。
占位文字长这样:
[image 已落盘: sha=ab12cd34ef56 path=/…/.media-cache/ab12….png size=182340B mime=image/png;要重新看就用 read_file 读这个路径]
3. 落在哪里
internal/mediaoffload/store.go:内容寻址缓存。文件名是字节的 SHA-256,目录默认.media-cache,放在工作区根下(和文件守卫同一个根,模型读回来不需要额外放行)。单文件上限 32 MB,超了就不收。internal/mediaoffload/offload.go:Session.Rewrite是改写主体。copy-on-write——只有真要改的时候才复制消息对象,没动的还是原来那个指针。internal/mediaoffload/handler.go:Handler实现adk.ChatModelAgentMiddleware的BeforeModelRewriteState,每场会话一份(它记着本轮哪些媒体看过,共用会串台)。
在 cmd/yktako 的 Handlers 链里,mediaoffload 排在 taskboard 之后、compact 之前。这个顺序是有意的:图先换成占位符,compact 再数 token,数到的才是真要发出去的那一份。
任何失败(base64 解不开、落盘写不进去)都只记一行日志、保留原样,不返回错误。这一层的职责是省窗口,不该因为磁盘满了把一轮对话打断。
4. 图片怎么进来:read_file 变成多模态工具
落盘之后模型要能读回来,可 tako 原来根本没有「把图片给模型看」的通道——read_file 只返回字符串。所以这一层顺带补上了:
internal/tools/files.go 里的 read_file 改用 utils.InferEnhancedTool,返回 *schema.ToolResult。内容是 image/* 时(用 http.DetectContentType 认,不看扩展名),回执带一个 ToolOutputImage 片段,图本身以 base64 给模型;超过 5 MB 的图片不读,回一句文字说明。文本文件的行为没变,4000 字节截断,且截断退到 UTF-8 字符边界,不劈汉字。
write_file 没动。
5. 两个连带改动
guard 必须覆盖 enhanced 工具调用。 eino 的 ToolsNode 优先用 EnhancedInvokableTool 接口,而 guard 三件套原来只实现了 WrapInvokableToolCall。read_file 一改成 enhanced,路径守卫、命令守卫、审批中断、PII 打码就全被绕过了——能读工作区外的文件,能读 .env。现在三个 handler 都加了 WrapEnhancedInvokableToolCall,判定逻辑抽成共用的 decide,两条路径行为一致。PII 那层只打码文本片段,图片字节不动(打码后的 base64 是坏图)。
enhanced 回执的 Content 是空的。 工具结果在 UserInputMultiContent 里,Content 字段没东西。原来靠 msg.Content 取文本的两个地方会直接变空白:webui 的 tool_result 事件、compact 的摘要与归档。新增 internal/msgtext,Of(msg) 先看 Content,空了再拼片段里的文本,非文字片段写成 [图片] 这样的标签。
6. 还没做的
- 只处理内联的 base64 媒体。远端 URL 原样留着——省不了本地窗口,真要落盘得先下载,是另一件事。
- 缓存只写不清。SHA 命名天然去重,但跑久了目录会一直长,没有回收策略。
- 音频、视频、PDF 走同一条路径(
schema.MessageInputPart的四种都覆盖),但只有图片这条真的验过。