交付卡片下载 hanbernate/dsh-save-button

dsh-save-button

在 DSH Web GUI 的交付卡片上，给「打开」按钮右边加一个「下载」按钮：模型用 present 交付的文件（打包好的 zip、报告、数据集、图片……）直接通过浏览器下载到本机，不用再开 SFTP/SCP 拉文件。

┌──────────────────────────────────────────────────────────────────┐
│ 📄 HexHowitzer-windows-x86_64.zip ┌────────┐ │
│ 在侧边栏预览 │ 打开 ▾ │ │ ← 官方卡片 │ └────────┘ │ └──────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────┐ │ 📄 HexHowitzer-windows-x86_64.zip ┌────────┐ ┌──────┐ │ │ 在侧边栏预览 │ 打开 ▾ │ │ ⬇ 下载│ │ ← 装上本插件 │ └────────┘ └──────┘ │ └──────────────────────────────────────────────────────────────────┘

远程/容器里跑 DSH（云主机、GPU 机器、WSL、内网服务器）时最有用：文件在 Host 上，浏览器在你手上，中间只差一个按钮。

功能

- 交付卡片一键下载：present 声明的每个文件右边都有「下载」，走 Content-Disposition: attachment，由浏览器自己的下载管理器流式落盘——几十上百 MB 的 zip 不会先塞进页面内存。
- 官方卡片能力保留：点卡片/「打开」在侧边栏预览；右侧 ▾ 仍是官方的「用默认应用打开」「打开所在文件夹 / 在 Finder 中显示 / 在文件资源管理器中显示」，主机没有桌面时按官方语义禁用并提示。
- 状态就地反馈：正在准备下载… / 已开始下载 / 下载失败，点击重试；打开、打开所在文件夹同样有状态与重试。
- 不干扰官方渲染：本轮文件改动 chips、多文件折叠（全部 N 个文件 / 收起）等官方行为照旧；插件的回合没有交付产物时，官方那一行完全不受影响。
- 零依赖、零构建：纯 ESM + 手写浏览器 bundle，装完即用；没有 postinstall、没有编译步骤。
- 中英双语：跟随 GUI 语言。
- 同时兼容 DSH 0.1.5-rc.\、0.1.7-rc.\ 与 0.2.0-rc.\*：见下方「支持的 DSH 版本」。

安装

从 npm 装进 web profile：

dsh plugin --profile web add dsh-save-button

也可以直接装 git 仓库——本包无构建步骤，lib/ 已提交：

dsh plugin --profile web add github:hanbernate/dsh-save-button

本地开发时改为链接本目录，改动后 Host 半区随 Loader 热重组合生效：

dsh plugin --profile web add /path/to/dsh-save-button

dsh 不在 PATH 上时，用你启动 Web GUI 的那份 CLI，例如：

node ~/.dsh/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js \
plugin --profile web add dsh-save-button

这条命令把 dsh-save-button 追加到 profile 的 dsh.profile.bundles，并由 Loader 插入本包 cordis.patch.yml 里的那条 entry。

生效方式：

- 装完 刷新浏览器页面（浏览器半区是页面加载的 bundle，刷新才会重新拉取）。
- 若刷新后没出现按钮，重启 Web GUI：dsh web（或你平时的启动命令）。

验证：随便让它 present 一个文件（例如先 ls 出你打包好的 zip），卡片右侧就会出现「下载」。

使用

按钮长在官方交付卡片的「打开」右侧，一文件一个：

| 操作 | 行为 |
| 下载 | 先 HEAD /api/download.button?sessionId=…&seq=…&index=… 探测可下载性，成功后用 把文件交给浏览器下载管理器；文件名由 Host 的 Content-Disposition 决定 |
| 打开 | 与官方一致：在侧边栏预览该文件 |
| ▾ 菜单 | 官方动作：用默认应用打开 / 打开所在文件夹（Finder / 资源管理器）；主机无桌面时禁用 |
| 失败 | 就地显示失败原因（如「该文件已不在会话中」），点击原按钮重试 |
| 多于 4 个文件 | 保留官方折叠：全部 N 个文件 / 收起 |

下载只接受 (sessionId, seq, index) 三元组寻址，没有 path 参数，因此只有该会话用 present 声明过的文件能被下载；解析、越界与类型校验、分块读取全在 Host 半区。详见 doc/architecture.md。

支持的 DSH 版本

| DSH RC | turnTail 契约 | 集成方式 | 状态 |
| 0.1.0-rc.2 … 0.1.2-rc.1 | —（无 present / workspaceFiles） | 不适用 | 不支持 |
| 0.1.5-rc.1 / rc.2 / rc.3 | chain | 按 priority: -1 认领整行并自绘卡片 | 支持（rc.3 实测 11/11） |
| 0.1.7-rc.1 / rc.2 | list | 官方卡片原样，注入 deliverables.file.actions 下载按钮 | 支持（rc.2 实测 12/12） |
| 0.2.0-rc.1 / rc.2 | list | 同 0.1.7：官方卡片原样，注入 deliverables.file.actions 下载按钮 | 支持（rc.2 实测 12/12） |

插件在初始化时按运行时实际声明选择适配器（客户端拿不到 DSH 版本号），所以同一份安装包在所有这些线上都工作。
契约清单、测试分层、逐项实测记录与换线手册见 doc/compatibility.md。

卸载

dsh plugin --profile web remove dsh-save-button

然后刷新页面。插件被移除后，官方交付卡片原样恢复——本插件不修改任何官方文件。

故障排查

| 现象 | 处理 |
| 卡片右侧没有「下载」 | 先刷新页面；再确认 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 里有 dsh-save-button；仍无效则重启 dsh web |
| 按钮出现，点了提示「下载失败，点击重试」 | 打开浏览器开发者工具看 /api/download.button?... 的响应：401/403 = 认证，404 = 该声明不在 Session 里（换了会话或事件被裁剪），422 = 不是常规文件/在工作区之外 |
| 点「打开」报「打开失败」 | Host 无桌面（纯服务器）时的正常结果；用「下载」或侧边栏预览 |
| 报 exports["./client"] must be a string | package.json 的 exports 被改坏了，跑 npm test 看守卫 |
| 改了 lib/client.js 没生效 | 刷新页面（bundle 由 Host 按 revision 提供，页面不刷新不会重拉） |

文档

| 文档 | 内容 |
| doc/architecture.md | 工作原理、两个半区、适配器与能力探测选择器、图标能力表、安全边界、设计决策记录 |
| doc/compatibility.md | 支持矩阵、官方契约面清单（C1–C10）、两个断点的历史、测试分层与用例、真机实测记录（V1–V23）、换线手册 |
| doc/development.md | 目录结构、跑测试、改完怎么生效、新增适配器的步骤、发布前检查清单、开发陷阱 |

License

MIT，见 LICENSE。