DeepSeek Harness 插件：dsh-attachment-s3

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 桶）的場景。

插件目錄 | 源碼倉庫