tako 文档 GitHub

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 那样在消息块上打标记,而是按「这条消息在本轮的什么位置」判:

「本轮」的边界是最后一条 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. 落在哪里

在 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. 还没做的