前言¶

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 未出现在已核实资料中。