前言¶
DeepSeek Harness（DSH）的 Web 端自带「文件」面板，可以列出目录、预览文档，但写方向的能力——上传、打包下载、重命名、删除、建文件夹——并不在默认实现里。日常改工作区内容时，很多人仍要开 SFTP 或本机同步工具，和浏览器里的会话来回切换。
下面介绍社区插件 dsh-file-manager（维护者 wchengk09，分类：客户端）。它在同一套 Web GUI 里补上 authenticated、限定在当前 session workspace 内的传输与管理界面，目标是把常见文件操作留在 DSH 会话里完成。
这是什么¶
dsh-file-manager 是标准 DSH profile bundle（dsh.bundle.patch + dsh.client），为 DeepSeek Harness Web 的 Files 能力增加写方向：上传、下载、文件夹 ZIP、重命名、删除、新建文件夹。官方文件面板只负责列表与预览；本插件额外提供完整「文件管理」侧栏标签，并在内置「文件」标签的操作行里增加快捷入口。
插件与 DSH 同属「一切皆插件」生态；社区目录页在 skillhub.cn，源码在 GitHub。目录信息与 README 一致时，以仓库文档为准。
核心功能¶
界面层¶
| 位置 | 能力 |
|---|---|
| 右侧边栏新标签 文件管理（可从引导页进入） | 面包屑导航、目录优先排序、多选、拖放上传（含文件夹）、单文件进度与取消、覆盖确认、文件下载、文件夹 ZIP 下载、重命名、删除、新建文件夹 |
| 内置 文件 标签操作行 | 对当前展示目录：Upload、ZIP download、Open manager |
| 文档预览标签操作行 | 对当前打开文件：Download |
上传以流式写入磁盘（不做整文件内存缓冲）；下载支持 HTTP Range；文件夹 ZIP 在遍历目录树时流式输出。
Host API¶
路由前缀为 /api2/dsh-file-manager/*（不走 reflection 的 /api 通道）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /info?sessionId |
会话工作区根路径 |
| GET | /list?sessionId&path |
单层目录列表 |
| POST | /upload?sessionId&path&name&overwrite |
application/octet-stream 流式上传；name 可含 a/b/c |
| GET | /download?sessionId&path[&inline=1] |
单文件下载，支持 Range |
| GET | /zip?sessionId&path |
目录流式 ZIP |
| POST | /mkdir |
JSON {sessionId, path} |
| POST | /move |
JSON {sessionId, from, to, overwrite?} |
| POST | /copy |
JSON {sessionId, from, to, overwrite?} |
| POST | /delete |
JSON {sessionId, paths: []} |
成功响应形如 { "ok": true, "value": … }；失败为 { "ok": false, "error": { code, message, details } }，并带对应 HTTP 状态（例如 outside-workspace 403、exists 409、upload-too-large 413）。
安全与边界¶
- 认证与来源：各路由先走 composition 的
connection.requestRejection()，与官方/api相同的 Host/Origin 校验与会话 cookie；无 Connection 的 composition 直接拒绝。 - CSRF：所有 mutating 路由要求请求头
x-dsh-fm: 1，跨站表单无法设置。 - 工作区隔离：路径相对 session 的
cwd（回退到sandboxPolicy.workspaceRoot）解析；禁止..逃出；realpath 二次校验，指向工作区外的 symlink 在 download、zip、delete、move 等操作中被拒绝。 - 覆盖：upload、move 默认不覆盖（
exists）；浏览器确认后可带overwrite重试。 - 上限：单文件上传默认 16 GiB（
maxUploadBytes）；列表最多 5000 项；ZIP 最多 60000 项 / 4 GiB（ZIP32）。
已知限制¶
- 上传不支持断点续传；失败需从头传。下载可通过 Range 续传。
- Host 重载前
/copy未就绪时，粘贴会回退为「下载再上传」（目录递归），结果相同但更慢；路由加载后会自动走服务端 copy。 - 仅 ZIP32；超限会明确报错，不生成损坏包。
- 不支持
chmod/chown。 - 只管理当前 session 的工作区。
- 与内置文件面板同类型接管：启用后 shadow 官方实现，不会出现两个文件面板并排。
安装与启用¶
包为标准 web profile 依赖，Node 引擎要求 >=20，许可证 MIT（见 package.json 版本 0.1.0）。
先用 pnpm 把本地包装进 web profile：
cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-file-manager
# then add "dsh-file-manager" to package.json -> dsh.profile.bundles
不经过 pnpm 时可用符号链接：
ln -s /path/to/dsh-file-manager ~/.dsh/profiles/web/node_modules/dsh-file-manager
# add "dsh-file-manager" to package.json -> dsh.profile.bundles
在 package.json 的 dsh.profile.bundles 中加入 "dsh-file-manager"。重启 dsh web（或等待 profile 热重载），再刷新页面。捆绑的 cordis.patch.yml 会插入 host 行：
- insert:
- id: file-manager
name: dsh-file-manager
若要在 profile patch 里关闭插件，可对 - id: file-manager 设置 disabled: true；浏览器侧随 host 行一并消失。
可选 host 配置示例：
- id: file-manager
config:
maxUploadBytes: 17179869184
maxListEntries: 5000
zipMaxEntries: 60000
zipMaxBytes: 4294967294
典型用法¶
- 完成安装并刷新 Web 后，从引导页或右侧边栏打开 文件管理，用面包屑进入目标目录。
- 拖放文件或文件夹到面板，或在内置 文件 标签对当前目录点 Upload；大文件可看单文件进度，必要时取消。
- 选中文件或目录：下载单个文件、对文件夹 ZIP download，或在内置 文件 标签对当前目录打包下载。
- 重命名、删除、新建文件夹在 文件管理 标签内完成；需要覆盖已有路径时按界面确认后再提交。
- 预览某个文档时，在预览标签操作行使用 Download 拉取当前文件。
开发自测（来自 README）：
cd dsh-file-manager
ln -s ~/.dsh/profiles/web/node_modules node_modules # schemastery for tests
node --test test/*.test.mjs
适用场景与注意¶
适合在 DSH Web 会话里频繁改工作区、又不想为每次小改动开 SFTP 的智能体开发者或运维。插件 Host 路由与当前 dsh 进程权限 一致，读写范围仍被限制在该 session 的 workspace；安装前应自行审阅 源码与 MIT 许可证，确认符合你的安全策略。
社区目录星标等信息以站点展示为准（抓取时为 0）；功能细节以 GitHub README 为准。
结尾¶
dsh-file-manager 把上传、下载、ZIP、重命名、删除和建目录收进 DSH Web，与内置只读文件列表形成互补，减少会话内外来回切工具的成本。
