前言¶
在 DeepSeek Harness（DSH）里跑智能体会话时，工作区里的源码、日志和产物往往只靠默认的 Files 预览浏览，上传、批量下载和大目录整理并不顺手。dsh-files-manager 是面向 DSH Web UI 的客户端插件，在右侧边栏增加 File manager 标签，用可排序的树形表格统一管理当前会话工作区内的文件，并支持分块上传、流式 ZIP 下载和多选操作。下面介绍它的定位、能力、安装方式与使用时的注意点。
这是什么¶
dsh-files-manager 由 NoelJudeNoel 维护，仓库为 NoelJudeNoel/dsh-files-manager。插件在 DSH Web 右侧边栏增加文件管理页，所有读写都限定在当前会话的工作区根目录内，不扩大宿主进程的文件访问范围。生态上 DSH 奉行「一切皆插件」；社区目录站点 skillhub.cn 与 DeepSeek、幻方无官方从属关系，安装前仍建议自行查阅源码与 MIT 许可证。
核心功能¶
插件在资料中说明的主要能力如下。
树形列表与排序：表格展示文件名（含扩展名）、修改时间与大小；适配 DSH 浅色/深色主题和窄侧栏。可按名称、修改时间或大小排序；每个文件夹内单独排序，文件夹始终排在文件之上。中文文件名按拼音首字母参与名称排序，排序偏好会被记住。
下载：单文件以原名下载且支持断点续传；多选或整文件夹下载时，服务端按需流式生成 ZIP，不把整个归档载入内存。资料称曾在约 2 GB 规模下做过测试。
多选：复选框、Shift 范围选择、同级全选；选择条显示文件数与总大小。
上传：通过菜单或拖拽（可拖到面板或指定文件夹）上传文件或整个文件夹；分块大小为 8 MiB，带进度、速率、取消与网络错误自动重试；重名会提示；保留原始修改时间。
管理：新建文件夹、重命名、删除，输入时做名称校验。点击文件可在 DSH 常规预览中打开。
其他行为：页面可见时每 15 秒自动刷新列表，并在每次操作后刷新。符号链接、套接字等特殊文件不会打进归档，状态栏会报告跳过数量。按大小排序文件夹时，用的是其直接子项数量，而非递归计算整棵子树大小（避免大目录下列表过慢）。
安装与启用¶
需要 Node.js 22.5 或更高版本。资料注明在 DSH 0.2.1-rc.2 上测试过，无额外运行时依赖。package.json 中版本为 2.0.0，engines.dsh 要求 >=0.2.1-rc.2。
先执行官方安装命令（须使用资料中的 owner/repo 大小写）：
dsh plugin --profile web add github:NoelJudeNoel/dsh-files-manager
若 pnpm 报 ERR_PNPM_ADDING_TO_ROOT，加上 -w：
dsh plugin --profile web add -w github:NoelJudeNoel/dsh-files-manager
安装后重启 dsh web。在起始页打开右侧边栏并选择 File manager，或在常规 Files 标签页顶栏点击 Manage 进入同一管理界面。
可选配置¶
可在 profile 的 cordis.patch.yml 中限制单文件上传上限（默认 10 GiB）：
- id: files-manager
config:
maxUploadBytes: 10737418240 # largest single uploaded file; default 10 GiB
典型用法¶
- 安装并重启 Web 后，从侧栏进入 File manager，浏览当前会话工作区树表。
- 需要拉取多个文件或文件夹时，勾选目标项，通过下载流程获取流式 ZIP；单个大文件可走支持
Range的直链下载（见下方 API）。 - 将文件或文件夹拖到面板或某个文件夹节点上完成分块上传；若名称冲突，按提示处理。
- 用新建、重命名、删除维护目录结构；点击文件名回到 DSH 内置预览。
开发与本地调试时，资料给出的做法是直接指向本地路径（示例中的路径需换成你的检出目录）：
dsh plugin --profile web add -w /path/to/dsh-files-manager
安全与 HTTP 接口¶
安全相关说明（摘自 README）：
- 操作范围限于宿主记录的会话工作区；工作区根来自会话记录，不由请求参数指定。
- 路径做词法检查并在解析符号链接后再次校验；指向工作区外的链接不展示详情，下载时跳过。
- 工作区根不可删除或重命名。
- 请求经 DSH 已认证连接，需要 owner principal；下载使用绑定会话、有效期 10 分钟的短期 ticket。
- 上传先写临时文件，完成后再重命名，避免半成品出现在列表中。
对外 HTTP 路由（均需 DSH 连接认证）：
| 路由 | 用途 |
|---|---|
POST /api/files-manager?sessionId=&op= |
list、mkdir、rename、delete、conflicts、measure、prepare、upload、upload-abort |
GET /api/files-manager/download?sessionId=&ticket= |
流式返回 prepare 签发的文件或 ZIP；单文件支持 Range |
适用场景与注意¶
适合经常在 DSH Web 里整理会话工作区、需要批量上传下载或拖拽传文件的开发者。插件以当前 dsh 进程权限访问文件系统，安装前应阅读仓库源码与许可证，确认符合你的安全策略。
符号链接等特殊条目在归档中的限制、文件夹按大小排序的语义，以及 15 秒自动刷新，在长会话或大仓库场景下需要心里有数。测试套件可通过 npm test 运行（资料注明需 python3 校验 ZIP）。
结尾¶
dsh-files-manager 把 DSH Web 会话工作区的浏览、排序、上传和下载收到同一侧栏界面里，并强调工作区边界与流式 ZIP。目录页：skillhub.cn 插件页；源码与完整说明：GitHub 仓库。
