background-agents 媒体流与附件处理实现解析图片如何一步步进入 AI 提示词【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents在开源后台智能体编码系统background-agentsOpen-Inspect中媒体流与附件处理解决了一个关键问题你在聊天框里拖进去的一张截图如何安全、可控地变成多模态大模型真正看得见的图像数据。本文完整解析这条链路——从图片上传、魔数校验、对象存储到提示词只携带引用 ID再到沙箱按需拉取并以 data URI 形式注入模型提示词的全过程帮你彻底看懂附件处理的设计精髓。整体链路一张图片的 4 站旅程先看全局。一张图片从用户电脑到模型上下文要经过四个站点阶段发生位置核心动作① 上传控制平面 HTTP 路由校验 → 魔数嗅探 → 存入媒体桶② 入队控制平面提示词路由提示词里只带attachmentId引用③ 拉取沙箱内的 bridge 进程用沙箱令牌下载图片Base64 编码④ 注入OpenCode 代理层组装成 file part 进入模型提示词这个引用与实体分离的设计是整篇文章最值得学习的部分。第一步上传校验——为什么不信任浏览器说的 MIME 类型用户点发送后前端先把图片上传到POST /sessions/:id/attachments处理逻辑在 session-attachments.ts 中。这个端点做了几层防御每一层都有明确动机请求级体积闸门在真正解析 multipart 之前先读Content-Length头超过SESSION_ATTACHMENT_MAX_REQUEST_BYTES10MB 图片上限 128KB 头部开销直接返回 413避免超大请求被整体缓冲进内存见 media.ts 中的sessionAttachmentRequestExceedsLimit。格式白名单只接受 PNG / JPEG / WebP / GIF 四种图片 MIME 类型定义在共享包 session-attachments.ts单个文件 ≤ 10MB。魔数嗅探magic bytes这是最精彩的一处。服务端不看客户端声称的Content-Type而是直接检查文件开头的字节——PNG 以0x89 0x50 0x4E 0x47开头、JPEG 以0xFF 0xD8 0xFF开头、GIF 以GIF87a/89a开头detectSessionAttachmentFileType函数。声称类型与魔数不符的文件会被当场拒绝。文件扩展名也是按嗅探结果决定的而不是照搬上传时的名字。校验通过后图片以不可猜测的随机 ID作为对象键sessions/{sessionId}/attachments/{attachmentId}存入媒体桶接口只回传{ attachmentId, mimeType }两个字段。配额与自动清理防止存储无限膨胀每张图还会在会话的 Durable Object 里登记一条附件记录从而执行三重约束每个会话最多100 个附件、总计不超过500MB超过 24 小时仍没有被任何提示词引用的孤儿图会在下一次附件操作时被自动清理对象 记录一起删除。这些常量集中定义在 media.ts 顶部方便审计。第二步提示词只带小纸条不带图片本体真正的巧思在提示词入队环节。当用户发送带图消息时POST /sessions/:id/prompt请求体session-prompt.ts中的attachments字段只有这样的引用{ attachmentId: aB3x9..., name: screenshot.png }没有 Base64没有图片字节。为什么session-attachments.ts 顶部的注释说得很直白Durable Object 的 SQLite 行上限是 2MB如果把 Base64 图片塞进消息行或消息队列稍大一点的图就会撑爆存储行。所以消息行里只留一张小纸条ID 文件名图片实体安心待在媒体桶里等模型真正需要时再去取。这带来一个直接好处消息历史、事件流、队列回放全都保持轻量附件不会污染消息层的性能。第三步沙箱里的 AttachmentProcessor 按需补水会话运行在隔离沙箱中桥接进程 bridge 收到提示词命令后才会开始把引用补水hydrate成真实图像逻辑在 attachment_processor.py 中。入口在 bridge.py再校验一遍parse_session_image_attachments在 WebSocket 边界重新验证每条附件——ID 必须匹配^[A-Za-z0-9-]{1,128}$MIME 必须在白名单内每条消息最多6 张图。非法项被跳过并且会通过_send_media_warning向用户明示N 个无效附件已被跳过而不是静默丢失。有界并发下载AttachmentProcessor用一个信号量把并发压到2逐个向控制平面请求/sessions/{id}/attachments/{attachmentId}携带会话级沙箱 Bearer 令牌。流式体积保护下载用流式读取逐块累计字节数一旦超过 10MB 立即中止整体超时 120 秒HTTP 非 200、网络异常都会记录结构化日志attachments.fetch_failed、attachments.too_large等并跳过该图。Base64 编码成功拉取后图片字节被编码为 ASCII Base64连同文件名和 MIME 一起封装为HydratedSessionAttachment。失败容忍很讲究单张图拉不下来只跳过它并提示用户整条提示词依然继续处理不会因为一张坏图卡死整个会话。第四步生成 file part图片正式进入提示词最后一步由AttachmentProcessor.build_file_parts完成——把每张水合后的图片转成 OpenCode 协议里的file part{ type: file, mime: image/png, filename: screenshot.png, url: data:image/png;base64,iVBORw0KGgo... }注意url字段用的是data URIdata:{mime};base64,{内容}而不是网络地址——这意味着图像数据被内联进提示词消息本身OpenCode 代理层拿到后即可直接把 file part 交给多模态模型模型在推理时看到的就是你上传的那张截图。至此闭环完成实体存桶 → 引用入队 → 令牌鉴权拉取 → data URI 注入提示词。设计亮点清单这套实现值得抄作业的地方实体与引用分离媒体桶存字节消息队列只存 ID绕开了 2MB 存储行上限消息历史永远轻量。魔数嗅探优先于客户端声明文件名和 MIME 都可伪造字节头不会说谎。处处设限请求级 Content-Length 预检、单图 10MB、每消息 6 张、每会话 100 个 / 500MB、下载并发 2——每一层限制都有独立存在的理由。失败优雅降级坏附件跳过 显式警告用户绝不阻塞主流程。TTL 自动清理无人引用的图片 24 小时后自动回收存储成本可控。延伸阅读相关源码导航模块路径附件上传/下载 HTTP 路由session-attachments.ts魔数嗅探与媒体常量media.ts共享类型与消息级上限session-attachments.ts提示词入队与附件校验session-prompt.ts沙箱端附件处理器attachment_processor.py桥接进程注入点bridge.py系统工作原理总览docs/HOW_IT_WORKS.md【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考