dsh-attachment-s3

English | 中文

DeepSeek Harness 附件 seam 的 S3 存储。它实现 AttachmentStore —— 与内置的 @deepseek-ai/dsh-attachment-local（存在 DSH_HOME 下）是同一个抽象服务 —— 于是会话图片存进 bucket，而不是绑在录入它的那台机器上。该 seam 只接受一个 provider，所以本插件是替换本地后端，不与之并存。

bucket 对模型完全不可见：写进会话日志的仍是那个不透明的 sha256: 引用，因此在两个后端之间迁移不改变一份 transcript 的含义。

安装

dsh plugin --profile <name> add dsh-attachment-s3
export DSH_ATTACHMENT_S3_BUCKET=my-attachments
export DSH_ATTACHMENT_S3_REGION=us-east-1
dsh --profile <name>

本包声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，dsh plugin 会把它追加到该 profile 的 bundle 层栈。它的 patch 会禁用 dsh-base 插入的 attachment-local 行，并加入 attachment-s3 行。启动前确认这两件事：

dsh --profile <name> --dump-config | grep -A2 'id: attachment'

dsh plugin --profile <name> remove dsh-attachment-s3 会撤销安装并恢复本地后端。

环境变量

bundle patch 在挂载时从环境读取配置。DSH_ 前缀的名字必须来自启动环境——export 出来或写在拉起 dsh 的服务单元里；launcher 拒绝 .env 文件里的该前缀。凭据值的变量名由你自己定，可以放进 $DSH_HOME/.env。

变量	配置字段
DSH_ATTACHMENT_S3_BUCKET	bucket —— 必填；未设置时启动即在该行失败，而不是把附件存到别处
DSH_ATTACHMENT_S3_REGION	region
DSH_ATTACHMENT_S3_ENDPOINT	endpoint —— S3 兼容服务
DSH_ATTACHMENT_S3_FORCE_PATH_STYLE	forcePathStyle —— 设为 true 启用
DSH_ATTACHMENT_S3_PREFIX	prefix
DSH_ATTACHMENT_S3_ACCESS_KEY_ID_REF	accessKeyIdRef —— 持有密钥的变量名字，不是密钥本身
DSH_ATTACHMENT_S3_SECRET_ACCESS_KEY_REF	secretAccessKeyRef
DSH_ATTACHMENT_S3_SESSION_TOKEN_REF	sessionTokenRef
DSH_ATTACHMENT_S3_VARIANT_CACHE_DIR	variantCacheDir

不想依赖环境变量，就把该行固定写进 $DSH_HOME/profiles/<name>/cordis.patch.yml——它在所有 bundle 层之后应用。按 id 定位的 patch 会替换整个 config，要保留的字段需一并重述：

- id: attachment-s3
  name: 'dsh-attachment-s3'
  config:
    bucket: my-attachments
    region: us-east-1

配置

字段	默认值	含义
bucket	—（必填）	存放全部附件对象的 bucket。
region	由 SDK 解析	bucket 所在区域。
endpoint	AWS S3	S3 兼容服务的 endpoint。
forcePathStyle	false	path-style 寻址，多数 S3 兼容服务需要。
prefix	attachments/v1	本部署拥有的对象键前缀。
accessKeyIdRef	—	持有 access key id 的环境变量名。
secretAccessKeyRef	—	持有 secret access key 的环境变量名。
sessionTokenRef	—	持有 session token 的环境变量名。
maxImageBytes	20 MiB	提交的单张图片最大编码字节数。
maxImagesPerMessage	20	单条消息最大图片数。
maxMessageImageBytes	200 MiB	单条消息图片编码字节总量上限。
maxImagePixels	64,000,000	提交的单张图片固有宽 × 高上限。
maxImageDimension	8192	单张图片固有宽、高各自的上限（按边）。
normalizedImageMaxDimension	2048	入库图片的长边；超过的会被缩到这个尺寸。
normalizedImageMaxBytes	4 MiB	入库图片的字节预算。
variantCacheDir	Harness home 下	派生请求图片的本地缓存目录。

准入、归一化、请求图片派生都委托给内置的 @deepseek-ai/dsh-attachment-local——它把这些能力导出为普通函数；上表的默认值也是从它再导出而非另抄一份。这样两个后端共用同一套编码策略：同一张图被接受、入库、送到模型面前的结果都一致，本包只负责 bucket 那一半。bucket 本就管辖的对象策略——默认加密、存储类别、生命周期——交给 bucket。

配置里携带的是凭据引用而非值，与 harness 的凭据 seam 一致。每次请求重新解析：加载了凭据 provider 就走 ctx.credentials，否则走进程环境，因此轮换后的密钥下一次请求即生效。两个 key 引用要么都写要么都不写：只写一半会在加载时失败，而不是悄悄用 SDK 环境里的默认身份签名。都不写正是实例角色部署的常规做法。

存储方式

<prefix>/objects/<哈希前两位>/<sha256 十六进制>

每张不同的图片一个不可变对象：Content-Type 为校验过的媒体类型，SHA-256 作为对象校验和发送，固有 width/height 记入对象元数据。会话日志里记的是 sha256:<hex>——不透明 id，既不是键也不是 URL。前缀里的 v1 段把未来不兼容的布局隔开。

进 bucket 的是归一化之后的图片，而不是提交的原始字节：准入会把过大的源缩到入库长边并按字节预算重编码，引用里记下原始尺寸。送进模型请求的那一版则按需从入库对象派生、缓存在本地——它可复现，不该占 bucket。

• 去重靠内容寻址。 键就是待写字节的 SHA-256，所以撞键时重写进去的正是已经在那里的字节，而发布出去的引用描述的正是这次调用自己写入的内容。两个写者写同一张图收敛到同一个对象，重复的只是上传。每次上传都带 x-amz-checksum-sha256，会校验它的服务能拒收传输中损坏的字节。
• 读取即校验。 读取只请求引用声明的字节范围，回来后重算摘要并重解析图片头，因此 bucket 侧的替换以 ATTACHMENT_CORRUPT 暴露，不会进入模型请求。
• 失败码。 准入保留 seam 中调用方可纠正的码（IMAGE_TOO_LARGE、IMAGE_TYPE_MISMATCH、IMAGE_TOO_MANY_PIXELS、IMAGE_DIMENSION_TOO_LARGE、INVALID_IMAGE）；存储失败为 ATTACHMENT_WRITE_FAILED、ATTACHMENT_READ_FAILED、ATTACHMENT_NOT_FOUND、ATTACHMENT_CORRUPT，各自带上底层 cause。

S3 兼容服务

本后端对 bucket 有三项要求：接受 SHA-256 校验和头的上传、range 读取、可区分的「键不存在」。接入前先探测：

PROBE_ENDPOINT=https://s3.example.com PROBE_REGION=us-east-1 PROBE_BUCKET=<bucket> \
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... pnpm run probe

它写入并删除两个小对象，报告该服务在每项行为上的表现，包括错误的校验和到底是被拒绝还是被照单全收。拒绝校验和头的服务，本后端按现状跑不了。

开发

pnpm install       # 会跑 `prepare`，构建出 lib/
pnpm run test      # 单元测试，包含用真实 AWS SDK 打本地回环 S3 兼容服务
pnpm run typecheck
pnpm run build
pnpm run test:e2e  # 真实 bucket；没有 DSH_S3_E2E_BUCKET 时自动跳过

pnpm run test 不需要 bucket 也不需要联网：tests/support/fake-s3.ts 直接应答 SDK 真正发出的 S3 请求，签名、校验和头、range 读取和状态码分类都是真实走过的。e2e 读取 DSH_S3_E2E_BUCKET，可选 DSH_S3_E2E_REGION、DSH_S3_E2E_ENDPOINT、DSH_S3_E2E_FORCE_PATH_STYLE、DSH_S3_E2E_PREFIX；它写在每次运行随机生成的前缀下，并删除自己写入的对象。

发布时 prepublishOnly 会先跑：clean、typecheck、全套测试、build。

已知限制与未尽事项

• 没有保留期与删除。 对象只写不删；两个后端的 seam 都没有保留策略。只能靠 bucket 生命周期规则回收，而过期掉某个会话仍在引用的对象会让该附件变成 ATTACHMENT_NOT_FOUND。
• 只支持图片。 seam 的第一版面只承载 PNG、JPEG、WebP、GIF。
• 一个部署一个 bucket。 把会话或工作区路由到不同 bucket 需要一层本包没有的路由。
• 整对象传输。 读取会把整张图片缓冲进内存，受 maxImageBytes 约束。
• 共享不只需要附件。 会话日志仍在该 profile 的持久化后端所在之处——默认是 $DSH_HOME/sessions，机器本地。bucket 让附件持久且集中受管，但它本身并不能让另一台机器读到某个会话。