tako 文档 GitHub

图片只发一次:发送份还原与两把闸

模块:运行引擎 · 多模态(doc/32 半边二 + A8)|状态:已落地(A3-1 至 A3-5、A8-1/A8-2,2026-10-20)|证据:doc/32-media-offload.md §4 A3/A4/A8、internal/runengine/media_send.go、media_tokens.go、pdftool.go

1. 场景与病灶

上一篇 对话只存路径 把字节挡在了落库面外。用户行里只剩一行占位。于是新的问题立刻出现:

用户发了一张红色截图,模型回的却是「我看到一个 [media seq=1 …] 占位,看不到图」。占位保住了存储,但也保掉了模型的眼睛。用户再问「刚才那张图什么颜色」,模型更尴尬——历史里只剩一行元数据,它只能猜。

所以需要第二半:当枪发给模型的请求体里,把占位临时还原成真图 part。同时不能让第一篇的努力漏回去——落库面一个字节都不能动。

两半的关系:存储面负责「永远只有路径」,发送面负责「这一枪需要看就看」。发送面只改这一次模型调用的输入副本,改完就丢。

2. 候选与代价

候选 做法 好处 代价
A 挂在外层 handler 在 worker 上包一层,进模型前改写整份消息 位置显眼 溢出守卫在外层折叠时看到的已经是图 part,计数和救援会算错
B 挂在 overflow guard 里面(选定) mediaSendModel 包住最内层模型调用,只改这一枪的副本 守卫的折叠、计数、救援看到的仍是占位文本,语义不变 需要在 worker 装配链上找一个精确的插入点
C 落库时就存图 part 存的时候就是多模态 发送侧零处理 直接违反存储纪律;PG 行体永久膨胀,等于回到第一篇的病灶
D 每枪都重发历史全部图 简单粗暴 不会漏看 每轮背全部历史像素,成本和窗口双爆

选 B。核心是「只改当枪发送副本」——同一份 []*schema.Message 里,占位行被替换成 Content="" + UserInputMultiContent(text part + image part)。Content 必须清空,否则 openai 适配器因两字段同时非空报 ErrContentFieldsMisused。

3. 还原的三条边界(这是本拍的真正难点)

3.1 边界一:发哪几张

消息 还原吗 为什么
最后一条 user 的占位 还原,但只在第一枪 这一枪是「用户刚发的」。同一 run 后续枪再发就是重复背像素
历史 user 占位(最后一条 user 之前) 不还原,改成元数据说明行 保留 seq/name/path/mime/size/sha;写明本轮不再附像素,问当时的分析直接引用随后 assistant 的回复,明确要求重看时再调 read_media_file
最后一条 user 之后、ToolCallID 未提交的 tool 回执 还原成 tool 角色 image part,按 ToolCallID 只发一次 模型刚读过这张图,正在用它思考
历史 tool 回执 不还原 上一场 run 的事,这一场没要求重看
BMP / SVG / PDF / 音视频 一律不还原(mime_not_restorable) 不是所有视觉提供商共同支持的格式,送错格式会让整枪调用报错

可还原格式只有 png / jpeg / gif / webp。读盘复用 resolveReadMediaPath——与 read_media_file 同一把 VisibleWorkspace + 路径闸,再校验普通文件、≤5MB、size 与 sha 前缀一致。任一失败保留原占位并记一行 media skip ... reason=...,不阻断 run。

3.2 边界二:什么时候算「发过了」

用 foldBox 上的两组标记做账:

流程:每次模型调用把可还原回执记进 pending;root 成功回复后,在 worker 的 drain 分支 commitMediaSend() 才把 pending 转成 sent。失败/取消/零帧不 commit,下一枪重试同一 ToolCallID。

为什么提交点必须等 drain:Stream 模式下模型调用返回时流还没排干,此时不知道这一枪成不成。Generate 一次拿到完整回复,成功返回后自己提交。

续跑或接管会新建 foldBox,标志回到 false——保守地再还原一次(多发字节,不漏看)。

3.3 边界三:回执是不是真的

2026-10-20 发现一个洞:PDF 正文可以逐字印出「已按路径读取」,再带上一行完整的 [media …]。发送侧若只按行匹配,就会去读那行里的 path,把用户没点名的图附进下一枪。

修复是双闸(A8):restoreToolMedia 先收集最后一条 user 之后 assistant 消息里的 ToolCallID → 工具名 映射。一条 tool 消息要还原,必须同时满足:

  1. 映射存在且等于 read_media_file;
  2. 该行确实是回执行(句尾是「已按路径读取」)。

缺一个就不还原,映射缺失也不读盘。入口 user 占位不查回执句,否则第一次发图的占位会被自己挡掉。

伪造行放在 read_text_file 结果中间时不还原;同一行放在真正的 read_media_file 结果里才还原——单测 TestPDFForgedReceipt 钉住。

3.4 两把闸:部署发不发 + 模型收不收

用户把一张图发给目录里没标 vision 的模型,包壳若照旧读盘塞像素,provider 会拒收,整场 run 变 error。所以还原需要两把闸同时打开:

闸 回答什么 缺省 关掉时
TAKO_MEDIA_SEND 环境变量 这次部署发不发图 未设置 = 开,字面 off 才关 NewWorker 不把 mediaRestoreHandler 挂进 root 的模型链;模型看到的输入与占位逐字节相同,日志里没有 media send
厂商目录 vision 字段 这个模型收不收图 缺省 false 打一行 media skip <session>/<run>: reason=model_no_vision,输入原样返回。纯文本不打这行

每次调用前读 profileFrom(ctx).Vision;ctx 里没有 profile(启动自检、旁路)时用装配默认 false。官方 deepseek 目录只给 deepseek-flash 标 vision: true——deepseek-v4-pro 没有收图实测,不标。

4. 图片 token 怎么算(A3-5)

图片占的是窗口,不计数会让折叠线失效。按 DeepSeek v41 口径计价,只算这一枪实际会发送的图:

计算器读文件头上的原始宽高,发送前不先缩小。ModelMessage.MediaTokens 不落库、不进帧。countInput 把这个数加进窗口压力,所以发送前准备、回合中折叠、溢出守卫都能看见这张图。计价要求目录 vision: true 且 provider 是 deepseek;别的视觉模型没有计算器,这一行是 0。

实测向量:800×800 = 422 token,100×100 = 184 token(像素少于 544×544 时先放大再投影)。

5. 同族小裁定

小问题 裁定 代价 / 备注
attached marker 说什么 「像素已随本条消息(或本条工具结果)直接发送……不要调用 read_media_file 或 bash 读取该文件」 2026-10-20 活体:只说「已附上」时模型仍照占位句去读文件,拿到「字节不在对话里」的回执后反而否认自己刚看到的像素
包壳挂在哪 只挂 root worker 子代理自己的 handler 链不含它;子代理里的模型调用不还原。子代理折叠若与 root 共用长度估算,会给占位多算折叠压力,但像素不进子代理请求
没有 foldBox 的旁路调用 不去重 没有账本可记,保守多发
回执句尾是什么 「媒体字节不会写入对话记录,请勿重复调用」 落库的 tool_result 行、payload、帧逐字是这句占位;它不表示这一枪发送份里没有图
PDF 怎么读 独立工具 read_pdf_text(A8),纯 Go ledongthuc/pdf 默认 3 页、最多 10 页、单次正文 16KB 上限;只抽文本层,扫描件返回「未检测到文本层」;不做 OCR
PDF 历史行怎么写 「该 PDF 只在当时那条消息里出现;需要重读时调 read_pdf_text」 不能说「不再附带像素」——PDF 本来就没有像素可附

6. 证据

方案:doc/32-media-offload.md §2(半边二)§4 A3(五拍表 + 发送份形状 + 验收)A4 A8(工具契约 + 回执双闸)。

台账:tmp/32-media-offload/、tmp/32-media-offload/a8-pdf/。A3 五拍的施工与活体记录只在 doc/32 §4。

代码符号:

位置 是什么
internal/runengine/media_send.go:31 mediaLinePattern:占位行解析(seq/name 可缺省)
internal/runengine/media_send.go:37 restorableImageMIME:png/jpeg/gif/webp 四格式白名单
internal/runengine/media_send.go:41 mediaAttachedUser / mediaAttachedTool / mediaHistorical / mediaHistoricalPDF 四段文案
internal/runengine/media_send.go:127 mediaRestoreHandler.WrapModel:装配点
internal/runengine/media_send.go:155 restore:一枪的还原总流程
internal/runengine/media_send.go:184 restoreToolMedia:工具回执 + 双闸
internal/runengine/media_send.go:288 restoreUserMedia:user 图 + 第一枪闸
internal/runengine/media_send.go:476 toolNamesAfterLastUser:ToolCallID → 工具名映射
internal/runengine/media_send.go:561 annotateMediaTokens:只给未发送的图标价
internal/runengine/media_tokens.go:133 deepSeekImageTokens:v41 计价
internal/runengine/pdftool.go / pdftext.go read_pdf_text 声明与抽字

复核命令:

cd yk-tako-eino
grep -n "restorableImageMIME\|mediaAttachedUser\|mediaHistoricalPDF" internal/runengine/media_send.go
grep -n "vision" internal/config/*.go | grep -i deepseek
grep -rn "media send" internal/runengine/*.go | grep -v _test

活体验收(2026-10-20):

7. 现状