DeepSeek Harness 持久图片附件子系统解析

DeepSeek Harness（简称 dsh）是 DeepSeek AI 开源的 agent harness，基于 Cordis 插件框架构建，主张一切皆插件。在它公开的子系统文档里，附件（attachment）这一篇篇幅不长，却把一个容易被忽视的问题讲得很透：图片这类二进制数据，怎样才能在 agent 会话流水线里安全流转。本文带你拆解它的核心设计。

把图片所有权从会话日志里剥离

dsh 引入了一条附件接缝（attachment seam），把二进制图片的所有权与会话日志分开。生产方把经过校验的编码字节交给 ctx.attachments 服务，只有对象完成持久化之后，该服务才会发布一个不可变的内容寻址引用。会话事件和模型可见的 ImageBlock 里携带的是这个引用及其元数据，而不是字节本身。

哪些东西不允许进会话日志，文档列得非常明确：浏览器对象 URL、宿主临时路径、提供方 URL、base64 数据，一律不放行。这样做的好处是，会话日志变得可复放、可迁移，不依赖任何一台机器的本地状态，审计与回放也不会被悬空的引用卡住。

未发送的浏览器草稿可以留在内存里，原生客户端也可以把草稿暂存在操作系统的临时存储中。宿主接受用户消息后，会先把消息中的图片移到 DSH_HOME 环境变量指向目录下的 attachments/v1 里，然后才追加用户事件。模型的结构化图片输出遵循同一条规则：先持久化，后追加事件。

引用与元数据：不透明字符串加一副尺寸牌

附件的唯一标识 AttachmentId 是带类型标记的不透明字符串。本地后端目前生成形如 sha256 加摘要的字符串，但文档明确要求消费方既不能解析这种表示，也不能据此推导文件系统路径。存储布局是实现的私事，接缝只承诺引用本身稳定可用。

随引用一起发布的元数据叫 ImageAttachmentRef，包含四个关键字段：mediaType 是从存储字节实际验证出来的媒体类型；bytes 是精确的编码字节长度；width 与 height 是图片固有的编码宽高；还有一个可选的 name 显示名，它会被剥离本地路径信息，永远不会被当作路径解释。

把这副尺寸牌交给客户端是刻意安排：渲染历史记录时，客户端不用解码图片就能完成排版；而每次权威读取仍会根据对象重新校验摘要、媒体签名、尺寸和元数据，引用与字节想脱节并不容易。

三个方法：先校验，再提交，读取必验证

ctx.attachments 接缝只暴露三个抽象方法，语义边界划得很干净。

validateImage 只校验不落盘。它接收编码字节、调用方声明的媒体类型和可选显示名，返回的前提是这批栅格图已被完整解码并通过检查。批量调用方会先用它校验全部成员，再保存任何成员，因此某一次校验被拒，不会留下只保存了一半的对象。

saveImage 校验字节并以原子方式提交一个对象，之后才返回引用。它的契约是在所属会话事件被追加之前完成持久化，这保证了日志里出现的每一张图片都真实存在于存储中。

readImage 接受来自已授权会话路径的引用，只在完整性校验通过后返回字节；读取或验证被中断时按信号原因终止，校验失败则抛出存储错误。

这些类型集中在仓库的 packages/attachment/attachment/src/types.ts，文档里的 API 目录由脚本从源码生成并做一致性校验，接口与实现不容易悄悄漂移。

准入限制：把拒绝提前到入口

附件接缝还定义了一组部署侧解析的准入限制 ImageAttachmentLimits：接受的媒体类型固定为 image/png、image/jpeg、image/webp、image/gif 四种，另有单图字节上限、单消息图片张数、单消息图片总字节与像素总量四项限制。上传准入与请求缓冲共用这一份配置，超限的图片在入口就被拒绝，而不是持久化之后才发现装不下。

垃圾回收为什么被延期

一个值得玩味的决定是：附件服务刻意不规定保留策略。恢复出来的会话、fork 出来的会话可能共享同一批对象，如果垃圾回收绑定在某个会话的删除动作上，就会误伤仍在引用这些对象的其他会话。因此 dsh 选择把基于引用的垃圾回收延期实现，而不是仓促上线一个可能删错东西的回收器。这种宁可暂时不做也不做错的取舍，在急着交付的工程环境里并不多见。

小结

附件子系统的设计可以压缩成三句话：先持久化，后追加事件；引用不透明，字节必校验；限制前置于入口，回收宁可延期。对于任何要处理多模态输入的 agent 项目，这套把二进制所有权从日志里剥离的思路都值得直接借鉴。项目采用 MIT 协议在 GitHub 上开源（仓库 deepseek-ai/deepseek-harness），附件子系统文档提供中英双语版本，感兴趣可以阅读原文。