前言¶

DSH 的插件安裝是面向 profile 的。對於需要把 SessionPersistence 放到 S3 或 S3-compatible endpoint 的場景，dsh-session-s3 提供一個可安裝的 DSH 插件。它採用 wal3-Lite：immutable JSONL fragments 加 CAS manifest，通過 If-None-Match / If-Match 協調寫入方，而不是直接修改已有 fragment。下面介紹它的定位、安裝、配置和驗證方式。

這是什麼¶

dsh-session-s3 是 gengmao 維護的社區 DSH 插件，許可證爲 MIT。它爲 DeepSeek Harness 提供 S3-backed SessionPersistence provider，註冊爲 ctx.sessionPersistence，並通過 Cordis bundle patch 替換 profile 的 sessions row。

核心功能¶

• 提供 S3-backed SessionPersistence provider for DeepSeek Harness。
• 使用 wal3-Lite 設計：immutable JSONL fragments + CAS manifest，並依賴 If-None-Match / If-Match。
• 每個 fragment 有 SHA-256；Phase 1 不使用 setsum。
• 通過單個 compare-and-swap object 協調併發寫入方，不修改 fragment。
• 註冊爲 ctx.sessionPersistence，並通過 Cordis bundle patch 替換 profile sessions row。
• 支持 AWS SDK credential chain，以及 R2、Tigris、MinIO、SeaweedFS、GCS interop 等 S3-compatible endpoint。
• 提供庫助手 createProvider()，包含 append、read、compact、close 方法。

安裝與啓用¶

插件安裝到 profile，不安裝到全局。運行環境要求 Node >= 22。

從 GitHub 安裝¶

先執行下面命令，把插件添加到 web profile：

dsh plugin --profile web add github:gengmao/dsh-session-s3

如果沒有全局 dsh，可以使用 npx：

npx -y @deepseek-ai/dsh plugin --profile web add github:gengmao/dsh-session-s3

在 pnpm >= 10 環境中，git-hosted prepare scripts 可能被阻斷。如果 add 失敗，允許 dsh-session-s3 構建後重新執行安裝命令。

本地 checkout 安裝¶

如果已經在本地目錄中，可以使用：

dsh plugin --profile web add ./dsh-session-s3

重啓與移除¶

添加完成後，重啓：

dsh web

或使用 profile：

dsh --profile web

移除插件：

dsh plugin --profile web remove dsh-session-s3

npm 安裝（未確認發佈）¶

已覈實資料中列有 dsh plugin --profile web add dsh-session-s3，但 npm 包是否已發佈未確認。優先使用前面的 GitHub 安裝方式。

配置¶

在 profile overlay 中設置 bucket 和可選 endpoint。路徑爲：

$DSH_HOME/profiles/web/cordis.patch.yml

需要關注的配置項如下：

• bucket：必填。
• endpoint：可選；如果設置，必須爲 http 或 https。
• accessKeyId / secretAccessKey：如果設置，兩者必須同時設置；它們是 static keys，不包含 session token。

不要在 Cordis patch 中放 access keys。優先使用 AWS SDK default credential chain。

配置非法時，加載階段會列出所有問題。

典型用法與驗證¶

在 DSH seam 中，插件註冊爲 ctx.sessionPersistence，替換 profile sessions row。庫助手 createProvider() 提供 append、read、compact、close 方法。

要檢查目標 bucket 的 CAS 行爲，可以使用：

aws s3api put-object --bucket my-sessions --key dsh/_probe --body /dev/null --if-none-match '*'

list() 和 listSnapshots() 會調用 ListObjectsV2，因此需要 s3:ListBucket 權限。

適用場景與注意¶

適合以下情況：

• DSH profile 需要 S3-backed SessionPersistence。
• 使用 R2、Tigris、MinIO、SeaweedFS 或 GCS interop。
• 使用 AWS SDK credential chain。
• 需要 immutable JSONL fragments 和 CAS 協調寫入。

注意事項：

• 許可證爲 MIT。插件以當前 dsh 進程權限運行；安裝前應檢查源碼與許可證。
• 要求 Node >= 22。
• 插件安裝到 profile，不安裝到全局。
• bucket 必填。
• endpoint 如果設置，必須爲 http 或 https。
• 不要在 Cordis patch 中保存 access keys。
• list() / listSnapshots() 需要 s3:ListBucket。
• 獨立 npm install 使用 legacy-peer-deps=true，原因是 @deepseek-ai/dsh-type-meta 未在 npmjs 發佈。
• npm 包是否已發佈未確認。

鏈接¶

GitHub：

https://github.com/gengmao/dsh-session-s3

目錄頁 URL 未出現在已覈實資料中。