图片只发一次:发送份还原与两把闸
模块:运行引擎 · 多模态(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 上的两组标记做账:
mediaSentUser/mediaPendingUser:user 图是否已确认发过 / 本枪已附待确认。mediaSentTools/mediaPendingTools:同上,按 ToolCallID。
流程:每次模型调用把可还原回执记进 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 消息要还原,必须同时满足:
- 映射存在且等于
read_media_file; - 该行确实是回执行(句尾是「已按路径读取」)。
缺一个就不还原,映射缺失也不读盘。入口 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 口径计价,只算这一枪实际会发送的图:
- 本 run 还没成功发过 user 图时,给最后一条 user 计价;
- 这条 user 之后、ToolCallID 还没提交的工具回执也计价;
- 更早的 user 图和已经发出去的图不加。
计算器读文件头上的原始宽高,发送前不先缩小。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):
- A3-1 首轮红图 → complete;同会话纯文本问「刚才那张图什么颜色」→ assistant 答出颜色,本 run 零
media send;PG 两条LIKE '%base64%'均为 0。 - A3-2 模型按占位 path 调
read_media_file→ assistant 答「红色」,日志media send … user=0 tool=1;再调get_time后不再出现同一 ToolCallID 的tool=1;帧里 tool_result output 仍是占位。 - A3-3 同一 run 首回复同时调两个工具,日志顺序
user=1 tool=0→user=0 tool=1;两个落库面的 user/tool 行都无 base64。 - A3-4 SVG 入口 run complete,首枪
skipped=1+reason=mime_not_restorable,模型仍读回占位;TAKO_MEDIA_SEND=off重启后红图 run complete,assistant 答「看不到」,日志只有启动行media: send=false。 - A3-5 800×800 红图
img=422tok、100×100img=184tok;-compact-window 940(limit 752)下加图那枪「输入 814 tok > limit 752,进入折叠」,814 − 422 = 392,过线的正是这张图。 - A8-1 三页 PDF 问第 2 页 → assistant「香蕉(banana)」;日志
pdf read … pages=2-2 chars=16;两表零 base64。 - A8-2 第 99 页 →
page_from 超出范围,不编造;扫描件 → 「未检测到文本层」,不按文件名编造内容;伪造回执 run 的media send仍是tool=0 skipped=1 img=0tok。