DeepSeek Harness（DSH）的附件机制目前默认使用本地存储。当会话中包含图片时，这些图片会直接保存在运行 DSH 的机器磁盘上。dsh-attachment-s3 插件为这个机制提供了一个 S3 存储后端，允许将会话图片持久化存储在云端对象存储中。
实现原理¶
该插件实现了 DSH 附件机制中的 AttachmentStore 接口，与内置的 @deepseek-ai/dsh-attachment-local 后端使用相同的抽象层。DSH 的附件机制一次只能配置一个提供者，因此该插件通过配置替换（而非叠加）的方式取代本地后端，将附件的生命周期从宿主机转移到了 S3 存储桶中。
核心功能¶
- S3 存储后端：利用 S3 兼容服务存储附件对象。
- 内容寻址：使用 SHA-256 哈希作为对象的唯一标识，确保数据的唯一性和完整性。
- 写入一次，验证读取：上传使用条件写入（
If-None-Match: *），读取时重新校验哈希和头部，防止数据损坏或篡改。 - 兼容 S3 服务：支持标准 AWS S3 及其他 S3 兼容服务（如 MinIO、Ceph 等）。
安装¶
通过 DSH 的插件命令安装。安装后，插件会通过一个补丁文件（cordis.patch.yml）禁用内置的 attachment-local 行，并添加 attachment-s3 行。
dsh plugin --profile <name> add @guaguasong/dsh-attachment-s3
安装完成后，需要配置环境变量以启用 S3 后端。
配置与使用¶
插件在启动时读取环境变量。以下变量是必需的或与配置直接相关的：
| 环境变量 | 配置字段 | 说明 |
|---|---|---|
DSH_ATTACHMENT_S3_BUCKET |
bucket |
必填。存储附件的对象桶。未设置会导致启动失败。 |
DSH_ATTACHMENT_S3_REGION |
region |
桶所在的区域。 |
DSH_ATTACHMENT_S3_ENDPOINT |
endpoint |
S3 兼容服务的端点（默认为 AWS S3）。 |
DSH_ATTACHMENT_S3_FORCE_PATH_STYLE |
forcePathStyle |
是否强制使用路径样式访问。 |
DSH_ATTACHMENT_S3_PREFIX |
prefix |
存储对象的键前缀，默认为 attachments/v1。 |
DSH_ATTACHMENT_S3_ACCESS_KEY_ID_REF |
accessKeyIdRef |
持有 Access Key 的环境变量名称（引用，非值）。 |
DSH_ATTACHMENT_S3_SECRET_ACCESS_KEY_REF |
secretAccessKeyRef |
持有 Secret Key 的环境变量名称。 |
DSH_ATTACHMENT_S3_SESSION_TOKEN_REF |
sessionTokenRef |
持有会话令牌的环境变量名称。 |
验证配置¶
安装并设置环境变量后，可以通过以下命令验证插件是否正确生效，确认 attachment-local 已被移除，attachment-s3 已被添加：
dsh --profile <name> --dump-config | grep -A2 id: attachment
配置凭证¶
凭证配置遵循 DSH 的凭证机制：配置项中存储的是环境变量名称，而非实际的密钥值。插件在运行时通过这些名称从环境变量中读取凭证。这种设计允许在不重启进程的情况下轮换密钥。必须同时声明 Access Key 和 Secret Key 的引用，或者两者都不声明，以避免静默的签名错误。
属性限制¶
为了保持与本地后端行为的一致性，插件继承并实现了以下图片属性限制：
maxImageBytes：单张图片最大编码字节数（默认 5 MiB）。maxImagesPerMessage：单条消息最大图片数量（默认 20）。maxMessageImageBytes：单条消息最大总编码字节数（默认 100 MiB）。maxImagePixels：单张图片最大像素总数（默认 40,000,000）。maxImageDimension：单张图片最大单边尺寸（默认 2000）。
对象在 S3 上的策略（如加密、存储类、生命周期规则）由存储桶本身管理，插件不覆盖这些策略。
系统要求¶
该插件依赖 Node.js 运行时。安装前请确保环境满足以下版本要求：
Node.js ^22.19 || >=24
卸载¶
如需恢复使用本地附件存储，执行以下命令移除插件：
dsh plugin --profile <name> remove @guaguasong/dsh-attachment-s3
总结¶
dsh-attachment-s3 为 DSH 提供了标准化的 S3 附件存储方案，通过内容寻址和写入一次读取验证机制保障数据安全。它适合需要将会话记录和附件长期保留在云端、或希望在不同机器间共享会话上下文（通过挂载同一个 S3 桶）的场景。
