tako 文档 GitHub

32 · media_offload(对话只存 path)

性质:已落地(2026-10-21 收口)。A1–A7 随 dcf3e6b 入库(2026-10-18);A3-1 至 A3-5 与 A8-1/A8-2 随 6e4de68 入库(2026-10-20)。 本篇覆盖两个半边:半边一(存储纪律,入口图与工具回执只落占位)= A1–A2; 半边二(模型可见,本轮图在发送份里还原成真图 part)= A3-1 至 A3-5,2026-10-20 已落地。 施工台账:tmp/32-media-offload/(A1–A7 的 planning + todos + 验收实录)与 tmp/32-media-offload/a8-pdf/(A8); A3 五拍当时没另起台账,施工与活体验收记录只在本篇 §4。 验收结论:A1–A7 与 A8 的逐拍实录见上述台账(2026-10-18 引擎 8947/8916、2026-10-20 引擎 8909/8910)。 2026-10-21 活体抽验(引擎 127.0.0.1:8942、独立库、Redis db 8,本篇 7 项断言全过):带图投消息拿到 sessionId; user 行是占位(path=workspaces/<wid>/.media/…,锚在工作区目录);runlog 零 base64; GET /api/media?path=… 取到字节且与上传同长;跨租户取同一张图回 404;删默认工作区回 409 114005(doc/35 A8a)。 这一批明确不做的:扫描件 OCR(2026-10-20 已拍)、音视频内容(2026-10-20 已拍)、 CJK 兼容字形归一化、复杂版式不承诺、「文本只进当枪发送副本」这一另拍的半边。 扫描件 OCR、音视频内容不在本篇范围内。 本篇是 doc/16 能力表 #4b「media_offload」在 v6 的方案真源。旧线实现(doc/18,internal/mediaoffload) 已随 2026-10-03 仓体翻篇删除,doc/18 降级为旧线实现存档,不作施工面;它踩过的坑在本篇第 6 节吸收。 关联:doc/35(附件锚点已迁到 workspaces/<wid>/.media/)、doc/19v6-08 第 3 节 (read_media_file 声明面、多模态消费)、doc/19-v6(存储真源划分)。

核心裁定(用户 2026-10-18 拍):对话里面只保存 path。字节从进系统那一刻起就只落盘; 对话的三份落库面里,媒体永远只是一行占位文本,占位里带 path。

结论先给一句:把「不背字节」从旧线的发送侧技巧升级成 v6 的存储纪律——盘上是唯一字节真源, 对话里抄的只有路径;需要模型看图的当枪发送份临时还原成 image part,落库面始终只有占位。


1. 先演一场失败

v6 今天的对话是纯文本的:用户发不了图(postRunsRequest 只有 Text,server.go:117)。 但模型自己能把大字节拉进对话——唯一的一条路是 read_media_file。按今天的代码逐步演:

  1. 用户说「看一下 assets/shot.png 帮我改配色」。模型调 read_media_file{"path":"assets/shot.png"}。
  2. 工具读盘,返回一行 data:image/png;base64,iVBORw0…——2MB 的截图 base64 后约 2.7MB, 全在这一行文本里(filetools.go:591)。
  3. 这行文本作为工具结果进 TurnEntry.Text,EndRun 把它落进三处: runlog_entries 的 tool_result 行 text 列、同一行的 payload JSON({name, output})、 run_model_messages 的 text 列(store.go:235-247、store.go:403-409)。
  4. 下一枪 prepareInput 从 model_history 重建输入,这 2.7MB 原样重发给模型。 模型按提示「再仔细看看」又调一次,对话里再多一整行。
  5. 十几轮之后,窗口和账单里可能背着几十 MB 的 base64——而模型在当前文本管道下 根本看不见图(19v6-08 第 3 节挂账:data URI 暂被当文本)。这些字节纯粹在烧窗口、烧钱。

病根一句话:字节已经在盘上了(workspace 里的 shot.png),对话却把它再抄一份进自己怀里, 从此每轮都背着。media_offload 要改的就是「抄」这一步:对话不抄字节,只抄路径。

2. 一条纪律,两个半边

纪律(用户拍):媒体字节永远不进对话的落库面。三份落库面——runlog_entries、 run_model_messages、帧(runlive)——里与媒体有关的内容只有一行占位文本。

字节只允许活在两个地方:盘上的文件、当枪发给模型的请求体。

这条纪律与旧线 doc/18 的设计是反的,翻案理由要讲清:旧线是「正本不动、只改发给模型的那一份」—— 因为旧线正本在进程内存里,字节留着无所谓。v6 的正本落 PG 且目标多副本:字节进了行就是 行体永久膨胀(备份、复制、读侧每轮都背着),「发送时再换掉」是在错误的层补救。 把纪律移到存储面之后,发送面反而获得自由:还原与否变成按需决定,不再是救火。

两个半边,各自独立成拍:

3. 占位行真身

所有占位(入口图、工具回执)用同一条格式:

[media seq=2 name="photo.png" path=workspaces/ws_01…/.media/ab12cd34….png mime=image/png size=182340B sha=ab12cd34ef56…;要看就调 read_media_file 读这个路径]

PDF 入口占位用同一套字段,句尾换成「要看就调 read_pdf_text 读这个路径(可分页)」。图片和音视频仍指向 read_media_file。

通信字段(2026-10-18 用户增补拍:name 与 seq):

4. 分步

A1 入口拍(契约)

POST /api/runs 请求体加图:images 数组(每项 {mime, dataBase64, name?})。 服务端在一笔写里完成:校验(mime 白名单、大小上限)→ 内容寻址写入 workspaces/<wid>/.media/(<sha 前 16 位>.<扩展名>)→ user 行 Text = 正文 + 每图一行占位。

A2 工具回执拍

read_media_file 的返回从 data URI 单行改成占位行(第 3 节同格式)。

A3 多模态拍(2026-10-20 分五拍;A3-1 至 A3-5 已落地)

发送侧包壳在新文件 internal/runengine/media_send.go,挂在 overflow guard 里面 (模型调用点最内层);它只改这一次模型调用的输入副本,存储面(runlog_entries、 run_model_messages、帧)零改动。guard 的折叠、计数与救援看到的仍是占位文本。

A3 的五拍:

拍 内容 状态
A3-1 用户图发送:最后一条 user 的占位 → image part;历史 user 占位改成元数据说明行 ✅ 2026-10-20
A3-2 工具回执发送:最后一条 user 之后的 tool 回执 → tool 角色 image part;按 ToolCallID 只发一次 ✅ 2026-10-20
A3-3 第一枪闸:当前 run 的 user 图只还原第一枪,后续枪不重复背 ✅ 2026-10-20
A3-4 目录 vision 标记 + TAKO_MEDIA_SEND 总开关 + deepseek-flash 目录条目修正 ✅ 2026-10-20
A3-5 图片 token 计数(按 DeepSeek v41 口径进窗口) ✅ 2026-10-20

发送份形状(A3-1/A3-2):

验收(2026-10-20 活体,dev 库):

A4 前端拍

占位行在页面渲染成图(气泡里直接看图),前端需要一个取文件的 GET 端点 (牢笼校验后按 path 回流)。端点形状随 A1 的契约拍一起定。

A6 通信把手拍(2026-10-18 增补,拍号沿 tmp/32 todos 编号)

请求体 images 每项加可选 name(用户上传文件名);占位行入口变体加 name=/seq= 两列(第 3 节通信字段小节)。落库列零改动(占位仍是 text)。

A7 前端名显拍(2026-10-18 增补)

web/ 的占位行解析正则扩 seq/name(三捕获组全可缺省容忍:新行、存量行、工具回执 变体三种形状同一把正则);气泡 <img> 的 alt/title 用 name,文件片显示 name, 刷新 reconcile 后附件真名仍显示(修掉「刷新后文件名丢失」的现存缺口)。

A8 PDF 文本读取(2026-10-20;A8-1 与 A8-2 已施工并活体验收)

用户把一份 40 页的报告 PDF 发进会话,问第 3 页的结论。字节已经落在 workspaces/<wid>/.media/<sha16>.pdf,user 行多了一行占位。模型若调 read_media_file,拿到的仍是一行元信息。PDF 也不在可还原成图片的四种格式里,发送侧不会把它变成 image part。模型只能说自己看不到内容。上传成功和可读之间断了一环。

A8-1 补文本层这一环。模型按占位 path 调 read_pdf_text,工具按页抽出文字,作为普通工具结果写入 runlog 和 run_model_messages。扫描件返回正常说明,run 继续。音视频不处理,也不做 OCR。

链路:用户 POST 带 PDF → postRuns 落盘并写占位 → 模型看到句尾,调用 read_pdf_text → resolveReadMediaPath 把 path 收进工作区 → pdftext.go 逐页抽文本 → 工具结果落库 → 下一枪模型读到页文本并回答。图片回执链在旁边:只有模型自己调了 read_media_file,下一枪才把图附上。引擎不因为历史里还有一张图就重发。

工具契约。 read_pdf_text 声明 read,父池排在 read_media_file 后面。path 必填,与 read_media_file 共用 resolveReadMediaPath。解析成功后还要是普通文件、扩展名 .pdf、不超过 5MB,否则返回工具错误。page_from 可省,默认 1。page_to 可省,默认从起点起共 3 页,并夹到总页数。单次最多 10 页;请求超过 10 页而且这个窗口后面还有没读的页时,页眉写「单次最多 10 页,已夹取」。

成功时先给一行 [pdf path=… pages=N;第 a-b 页;文本层抽取],再按页写 --- page N --- 和该页文本。空页写「本页无文本层」。单页解析失败写「本页无法抽取」,其他页继续。单次正文上限 16KB,超过时在 rune 边界截断,末尾写「(本页文本超过单次上限,已截断;请缩小页范围)」。page_from 超过总页数时返回 [pdf … pages=N;page_from 超出范围],这是正常结果。请求范围内每一页都没有文字时返回 [pdf … pages=N;未检测到文本层(可能是扫描件),无法抽取文本;可让用户上传页面截图],也是正常结果。加密、损坏、上下文已取消返回 Go error,wrapToolErrors 收成「错误:…」,run 继续。

抽字在 pdftext.go,库是 github.com/ledongthuc/pdf(pin v0.0.0-20260907135840-6c8c28e0e8a0,BSD-3,纯 Go)。字形按 Y 分行、按 X 从左到右排。相邻字形的空隙超过左侧字号的 0.2 倍,并且两侧都是 ASCII 字母或数字时,才补一个空格。中文两侧不补。不承诺版式还原,也不做 CJK 兼容字形归一,不另存派生文本。成功返回后引擎打一行 pdf read <sid>/<run>: pages=a-b chars=…,chars 是写进正文的页文本 rune 数。

占位与历史行按 mime 分流。 PDF 入口占位句尾是「要看就调 read_pdf_text 读这个路径(可分页)」。图片和音视频仍指向 read_media_file。历史 PDF 行不说「不再附带像素」。图片历史行点名 read_media_file,和「重看由模型自己调工具」对齐。read_media_file 的回执句尾仍是「已按路径读取」,不改成指向 read_pdf_text。

回执双闸。 PDF 正文可以逐字印出「已按路径读取」,再带上一行完整的 [media …]。发送侧若只按行匹配,就会去读那行里的 path,把用户没点名的图附进下一枪。restoreToolMedia 先收集最后一条 user 之后 assistant 消息里的 ToolCallID 和工具名。一条 tool 消息要还原,映射必须是 read_media_file,并且该行的 receipt 为真。两个条件缺一个就不还原,映射缺失也不读盘。入口 user 占位不查回执句,否则第一次发图的占位会被自己挡掉。伪造行放在 read_text_file 结果中间时不还原;同一行放在真正的 read_media_file 结果里才还原。

researcher 走排除路,排除清单仍只有 bash,所以它的有效名单多了 read_pdf_text。coder 的白名单不含这把。

不做。 扫描件 OCR、音视频内容、把抽出的文本改成只进当枪发送副本。扫描件只返回「未检测到文本层」,音视频仍走 read_media_file 的元信息回执。

A8-1 活体验收(2026-10-20)。 临时引擎 127.0.0.1:8909,workspace /tmp/a8-ws,dev Redis 6390、Postgres 5433。cupsfilter 把三页文本 apple / banana / orange 打成 /tmp/a8.pdf。新注册的租户配上 deepseek/deepseek-flash 后,POST /api/runs,正文是「读取这份 PDF 的第 2 页,只回答那页的水果」,附件 a8.pdf。HTTP 202,session s_01M5CF1DFP5EJJ3NRBD48QMKH3,run r_01M5CF1DFS9ZAD72GYQ5YXRYH8,随后 complete。assistant 写的是「第 2 页列出的水果是香蕉(banana)」。runlog 的 user 行仍是占位,句尾指向 read_pdf_text,行内没有 base64。唯一一条 tool_result 是第 2 页:--- page 2 --- 下面是 Page two: banana。引擎日志有一行 pdf read s_01M5CF1DFP5EJJ3NRBD48QMKH3/r_01M5CF1DFS9ZAD72GYQ5YXRYH8: pages=2-2 chars=16,没有 panic。模型自己指定了第 2 页,所以页窗是 2-2。同一 run 的 runlog_entries(text 与 payload)和 run_model_messages.text 里,base64 计数都是 0。台账里的核对 SQL 写了 run_model_messages.content,这列不存在,实际列是 text。验完停掉 8909,8901 上原来的进程还在。

A8-2 活体验收(2026-10-20)。 临时引擎 127.0.0.1:8909,workspace /tmp/a82-ws,同一套 Redis 6390 和 Postgres 5433。go test ./internal/runengine、go vet、gofmt -l 都干净。新用例 TestPDFEncrypted 确认加密 PDF 返回「无法读取 PDF」;TestPDFForgedReceipt 把一条 size 和 sha 都对得上的完整回执印进 PDF 文本层,经 read_pdf_text 抽出后不还原,图文件当时是可读的。

同一租户 t_01M5CH3GM9NZQVJ37J7CKMN65X 上五场 run 都是 complete,user 行仍是占位,两表零 base64:

另起 127.0.0.1:8910,TAKO_MEDIA_SEND=off,workspace /tmp/a82-off-ws。session s_01M5CH5KCT5TWATE05DHYMQ6VX,run r_01M5CH5KCY1RQA6T7Z1QY0YW7Y,complete,assistant 含 orange,日志只有 pdf read … pages=3-3 chars=18,没有 media send 行。这场 run 两表也是零 base64。验完停掉 8909 和 8910,8901 上原来的进程还在。

5. 拍板记录(2026-10-18 四项已拍)

  1. 入口形状 ✅:images 数组({mime, dataBase64} 多图一次投),契约一次定到位。
  2. A2 时机 ✅:现在就换占位,不等 translator(零损失、纪律先行)。
  3. 本 run 内多枪 ✅:只还原第一枪。A3-3 已落地。载体是 media_send.go 的 mediaSendModel 和 worker 把流排干之后的 commitMediaSend:foldBox.mediaSentUser 在 root 成功回复后置位,同一容器的后续枪不再还原 user 图。模型要重看,走 read_media_file, 回执按 ToolCallID 再附一次。接管或续跑新建 foldBox,标志自然为 false,保守再还原一次 (多发字节,不漏看)。
  4. 前端取文件端点 ✅:GET /api/media?path=…。2026-10-20 起 path 是 workspaces/<wid>/.media/<sha16>.<ext>,按 VisibleWorkspace 取图(doc/35)。 2026-10-22 起错误分支换信封(doc/40):越权路径回 404 {"code":114001,"message":"找不到这个项目","data":null}; path 格式不对是 114102「媒体路径不对」,文件不存在是 114101「找不到这个文件」,缺 path 是 400 111001。成功体不进信封——它是图片字节,不是 JSON。
  5. 清理契约(维持原推荐):.media/ 随 workspace 生命周期走,先不做回收,到点看占用再裁。
  6. 音频/视频/PDF:占位格式同一条、入口白名单含它们。发送份当前只还原 png/jpeg/gif/webp 四种栅格图。 PDF 的文本层走 read_pdf_text(A8-1),不把 PDF 字节当图片发送。音视频仍只有元信息占位。
  7. 能力标记 ✅:目录每条模型的 vision 缺省 false。它回答这个模型收不收图。 官方 deepseek-flash 标 true,deepseek-v4-pro 不标。
  8. 部署总闸 ✅:TAKO_MEDIA_SEND 默认开,字面 off 才关。它回答这次部署发不发图。 与第 7 条都真,包壳才把占位还原成图。

6. doc/18 的教训,哪些还有效

7. 所以这解决了什么

第 1 节那场失败里,用户损失的是窗口和账单:模型每看一眼图,对话就永久多背 2.7MB, 十轮下来光图就占掉半个窗口,而模型全程没真正看见过图。本方案把它换成三件确定性的事: 字节只存一份(工作区、内容寻址);对话只抄路径(三份落库面零字节, 历史和备份不再膨胀);看图变成明确的当枪发送副本——A3-1/A3-2 已让当前 user 图与 read_media_file 回执在下一枪带上 image part,模型真的看得见,而落库面仍只有占位。 多副本目标栈下,这条纪律同时把「PG 行体膨胀」和「每轮重发大字节」两个账一起结了。 A3-3 把同一张 user 图收成「本 run 成功回复之后不再重复发送」;模型要重看,走工具回执那一条。 A3-5 把这一枪还会发出去的图片按 DeepSeek v41 加进窗口压力:800×800 是 422,像素不足 544×544 的 100×100 先放大再投影,是 184。 发送前准备看见超限就折叠。活体用 -compact-window 940(limit 752),加图那一枪估算 814,其中 422 来自这张图,剩下 392 低于触发线。 更早的 user 图和已经发出去的图不加。AdmitText 仍只数正文。厂商 usage 仍是已经完成的请求的锚点,估算只补锚点之后还没发出去的图。 A8-1 让 PDF 的文本层按页进入工具结果,user 行仍只有占位;图片要再次进入请求,仍得模型自己调 read_media_file。