tako 文档 GitHub

对话只存路径:媒体字节为什么不进落库面

模块:运行引擎 · 多模态(doc/32 半边一)|状态:已落地(2026-10-18 A1–A7、2026-10-20 A6/A8 收口)|证据:doc/32-media-offload.md §1–§3、internal/runengine/media.go

1. 场景与病灶

用户在会话里发了一张 2MB 的截图,说「帮我看看配色」。如果按最自然的做法——把图片转成 data URI 塞进对话文本——接下来会发生这些事:

  1. 2MB 的 PNG base64 之后约 2.7MB,这一行文本进了 runlog_entries 的 text 列。
  2. 同一个 run 的 tool_result 行还要再存一份 payload JSON({name, output}),于是这 2.7MB 在库里出现两次。
  3. run_model_messages 再存第三份,因为下一枪要从这里重建模型输入。
  4. 下一枪把 2.7MB 原样重新发给模型。模型说「再仔细看看」,又调一次工具,对话里再多一整行。
  5. 十几轮之后,这个会话的每一行都在背几十 MB 的 base64;备份、主从复制、每轮读侧都跟着背。

更要命的是,在当时的文本管道下模型根本看不见图——data URI 被当作无意义的长文本。这些字节纯粹在烧窗口、烧钱、烧磁盘。

病根不在「把图发给模型」这个意图,而在抄这个动作:字节本来就在盘上(工作区里的那张 png),对话却把它再抄一份进自己怀里,从此每一轮都背着。

2. 核心裁定与候选对比

裁定(2026-10-18 用户拍):对话里面只保存 path。

纪律原话:媒体字节永远不进对话的三个落库面(runlog_entries、run_model_messages、runlive 帧),这三面里与媒体有关的内容只有一行占位文本。字节只允许活在两个地方:盘上的文件、当枪发给模型的请求体。

为什么不沿用旧线的「发送时再换掉」——这是在错误的层补救。

旧线 doc/18(internal/mediaoffload) v6(本篇)
正本在哪 进程内存 PG,且目标多副本
字节进不进正本 进,无所谓(内存) 进了就是行体永久膨胀,备份/复制/读侧每轮都背
补救位置 发送前把 data URI 换成占位 存储入口就不让字节进来
发送侧的自由度 只能救火 还原与否变成按需决定
现状 2026-10-03 仓体翻篇时删除,doc/18 降级为存档 本篇

一句话:把纪律从发送面移到存储面,发送面反而获得了自由。

占位行长什么样(图/音视频用同一条格式,PDF 只换句尾):

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

字段各自解决一个问题:

字段 谁读 解决什么
path 模型 → read_media_file 相对租户根,与工具现有入参同一形状、同一牢笼,不需要新放行规则
seq 模型的嘴(「第二张」) 全会话按上传先后累计,恒在
name 模型的嘴(「photo.png 的新版本」) 用户原始文件名,可省;sanitize 成单行(去控制字符/换行/引号,≤120 字符),清空则整个字段省略
mime/size/sha 模型的判断 不读文件也能知道值不值得重看;sha 同时是内容寻址键

sha 是内容寻址:同一张图在对话里出现多少次,盘上只有一份、占位里的 path 也相同。同名两版是两个内容、两个 sha 名——区分靠 name + seq 这对字段,不靠改盘名。

3. 同族小裁定

小问题 裁定 代价 / 备注
入口契约长什么样 POST /api/runs 加 images: [{mime, dataBase64, name?}],多图一次投 一笔写里完成校验 → 落盘 → user 行 = 正文 + 每图一行占位
图要不要折算进 413 准入线 不折算(2026-10-18 翻案);门槛退回硬上限 ≤5MB/张、≤4 张、mime 白名单 初版把 base64 喂 cl100k:300KB 实测 39s,3MB 截图分钟级;而 deepseek-flash 实际按张平价 ~384 token,cl100k 数字节差三个数量级。翻案后 3MB POST 43ms。AdmitText 签名去掉 blobs,「不折算」在编译层钉死
图进窗口的 token 怎么算 按 DeepSeek v41 另计,只加这一枪实际会发的图 见 图片只发一次;AdmitText 仍只数正文
字节落在哪 <tenantRoot>/workspaces/<wid>/.media/<sha 前 16 位>.<扩展名> 2026-10-20 按 doc/35 把锚点从 sessions/<sid>/.media/ 迁到工作区;旧路径由启动清理,不做两套并存
为什么不另设媒体缓存目录 字节进工作区后,read_media_file 的 VisibleWorkspace + resolveInWorkspace 天然覆盖读回路径 旧线要另建 .media-cache 是因为字节来源是消息内联、无处安放;v6 入口字节从第一刻就在工作区里
read_media_file 返回什么 占位行(不是 data URI),句尾「已按路径读取。媒体字节不会写入对话记录,请勿重复调用」 当前文本管道下模型本来就把 data URI 当无意义长文本,换占位是零损失;留着则第 1 节的失败每调一次重演一次。这一拍没有落盘动作,只有回执换字
工具回执带不带 name/seq 不带 读盘时无从知道会话序号;模型靠 path/sha 与入口占位对上(同一文件这两字段两边一致)
seq 在多副本下怎么数 postRuns 准入时数本会话 runlog user 行里既有的 [media 个数 +1 起编 同会话同时只有一个 run 在写(409 忙闸),计数无并发竞争;闸在 PG 不在进程,多副本照成立
前端怎么取图 GET /api/media?path=…,与 read_media_file 共用同一把牢笼 A4 拍;跨租户取同一张图回 404
存量行没有 name/seq 怎么办 前端解析按「缺字段省略」处理,不做迁移 历史行本来就是只读事实

4. 证据

方案:doc/32-media-offload.md §1(失败推演)§2(纪律与两个半边)§3(占位行真身、通信字段)§4 A1/A2/A4/A6/A7。

台账:tmp/32-media-offload/(A1–A7 的 planning + todos + 验收实录)、tmp/32-media-offload/a8-pdf/(A8)。A3 五拍没另起台账,实录只在 doc/32 §4。

代码符号:

位置 是什么
internal/runengine/media.go:24 mediaDirName / mediaMaxBytes(5MB) / mediaMaxPerMsg(4) / mediaNameMaxRunes(120)
internal/runengine/media.go:40 canonicalMediaExt:入口白名单 + mime→扩展名
internal/runengine/media.go:62 ingestImagesAt:校验 → 内容寻址写盘 → 拼占位
internal/runengine/media.go:167 mediaDisplayName:name sanitize
internal/runengine/media.go:212 mediaPlaceholder:占位行拼装
internal/runengine/media_send.go:31 mediaLinePattern:入口/回执两种占位同一把正则

复核命令:

cd yk-tako-eino
grep -n "mediaDirName\|mediaMaxBytes\|mediaMaxPerMsg" internal/runengine/media.go
grep -rn "data:image" internal/runengine/*.go | grep -v _test        # 应为空

活体验收(2026-10-21 抽验,引擎 8942、独立库、Redis db 8):带图投消息拿到 sessionId;user 行是占位(path 锚在工作区目录);runlog 零 base64;GET /api/media?path=… 取到字节且与上传同长;跨租户取同一张图回 404;删默认工作区回 409 114005。

5. 现状