前言¶
在 DeepSeek Harness（DSH）里跑 Agent 时，工作区文件和会话附件往往要在宿主侧处理；若通过配对的远程 Web 界面操作，原先缺少清晰的上传、下载入口，手机或另一台电脑上的文件很难按会话送进 Agent，也不便把 workspace 里的产物拉回本机。dsh-rfiles 是装在 DSH 宿主 上的 bundle 插件，为 Web GUI 增加 文件（Files） 面板，提供分块可续传上传、发送给 Agent、仅保存到工作区、工作区文件浏览下载，以及会话日志 ZIP 导出；与 @linxin666/dsh-remote-web-ui 配套使用，不修改 DSH 核心。本地桌面使用 Web GUI 时不必安装远程 UI 插件。
这是什么¶
- 名称：
dsh-rfiles（npm 包名，仓库 Aperops/dsh-rfiles） - 维护者：Aperops
- 分类：联网工具（社区目录 SkillHub 条目）
- 版本（资料记载）：0.1.0；许可证 GPL-3.0-only
- 定位：宿主侧插件，注册
rfiles路由与小部件；传输与鉴权沿用 DSH 连接，路径限制在会话工作区内。
核心功能¶
| 能力 | 行为概要 |
|---|---|
| 发送给 Agent | 多选文件、分块进度；上传完成后将真实附件与可选文字排队到选定会话 |
| 只存入工作区 | 默认写入 <workspace>/.uploads/，不发送提示；同名文件自动改为 name (n).ext |
| 拍照 / 相册 | 依设备能力；PNG/JPEG/WebP/GIF 且 ≤ 20 MiB 可走图片附件，其余为文件收据 |
| 下载工作区文件 | 目录与面包屑，每层最多 500 项；优先浏览器原生下载，另有 fetch/Blob 兜底 |
| 会话日志 ZIP | 调用 DSH 会话导出接口（含选定会话、子会话与附件对象），非整工作区打包 |
| 中断上传续传 | 浏览器续传记录与宿主暂存仍在时，从已确认字节偏移继续 |
面板会列出活跃会话，首次默认选最新会话。上传、发送、下载前请核对面板上的会话选择器，不要假设它与当前对话视图始终一致。
默认限制（可在 profile 的 cordis.patch.yml 覆盖）：8 MiB/块、2 GiB/单文件、10 GiB 暂存预算；暂存目录默认 $DSH_HOME/rfile-transfers/<uploadId>/。
环境与要求¶
dsh-rfiles 0.1.0 的 package.json 声明：
- DSH
>=0.2.1-rc.3 - Node.js
>=22.19.0
安装位置是实际运行 Web GUI 的 DSH 宿主 profile。配对远程使用时，需另行安装并配置 @linxin666/dsh-remote-web-ui 并完成设备配对。
插件在 DSH 进程权限下运行；安装前建议阅读仓库源码与 GPL-3.0-only 许可条款。
安装与启用¶
在 设置 → 插件（Settings → Plugins） 中从 npm 安装 dsh-rfiles 并确认 bundle 已启用。也可使用 CLI（若 profile 不是 web，请替换）：
dsh plugin --profile web add dsh-rfiles
其他来源（无需构建）：
# 已发布的 Release 包
dsh plugin --profile web add \
https://github.com/Aperops/dsh-rfiles/releases/download/v0.1.0/dsh-rfiles-0.1.0.tgz
# 源码仓库或本地包
dsh plugin --profile web add git+https://github.com/Aperops/dsh-rfiles.git
dsh plugin --profile web add /path/to/dsh-rfiles-0.1.0.tgz
bundle 内 cordis.patch.yml 会注册 rfiles 插件行，一般无需手改 patch。安装后重启 DSH，刷新本地或配对远程页面，打开会话，点击右下角 文件（Files）。0.1.0 面板按钮为中文。
可选配置示例（用户 cordis.patch.yml 层）：
- id: rfiles
config:
chunkBytes: 8388608
maxFileBytes: 2147483648
stagingBytes: 10737418240
uploadDir: .uploads
transferRoot: '' # 默认 $DSH_HOME/rfile-transfers
典型用法¶
上传并发送给 Agent¶
- 打开 文件 → 上传，核对会话，保持 发送给 Agent。
- 选择文件或 拍照 / 相册；选完后自动开始上传。
- 上传完成时文件仍在宿主暂存区，尚未进入 Agent 队列。
- 填写可选说明，点击 发送给 Agent；图片是否被模型接受取决于模型能力。
只保存到工作区¶
- 选文件前切换到 只存入工作区。
- 上传完成后查看条目上的保存路径（默认
.uploads/）。 - 此模式不发送附件或提示；若要附件流程，切回 发送给 Agent 并重新选文件。
中断后续传¶
在同一浏览器/站点、同一会话、同一模式下重新选择同一文件，或点 重试。匹配依据文件名、大小与最后修改时间，记录自最后更新起 24 小时内有效；宿主暂存也必须仍在。取消上传会清队列并尝试删除当前暂存，不能当暂停用。
下载与日志 ZIP¶
- 切到 下载，确认会话。
- 浏览工作区点击文件触发原生下载；远程链接带
/remote前缀。 - 若导航被拦截或仅有请求头配对凭据，用文件行 ⤓ 或 ZIP 旁的 通过请求保存。
- 下载会话日志 ZIP 导出会话；不能在工作区面板里删除、重命名或任意目录打包。
适用场景与注意¶
适合：依赖配对远程 Web UI、需要大文件分块上传与续传、要把文件以附件形式送进 Agent，或要从会话工作区/导出 ZIP 拉回设备的 DSH 用户。
注意：
- 上游
dsh-remote-web-ui与 DSH 版本演进后，部分能力可能由原生界面覆盖；升级后应在实际设备上验证上传、下载与 ZIP，再决定是否停用插件。 - 远程端到端 HTTP Range 是否可用取决于代理与隧道；资料不承诺远程下载断点续传。
- 卸载插件不等于清理
.uploads/工作区文件；暂存目录需单独确认后再删。
常见排查：无 文件 按钮时检查 profile 是否启用 bundle 并重启；401/403 时检查配对与 /remote/api/rfiles.*；上传 409 offset-mismatch、413 分别对应偏移同步与配额。
结尾¶
dsh-rfiles 在不动 DSH 核心的前提下，为远程 Web 场景补齐文件传输与会话导出入口；安装与行为以仓库 README 为准。目录页：https://www.skillhub.cn/plugins/Aperops/dsh-rfiles；源码与详细说明：https://github.com/Aperops/dsh-rfiles。
