LI-Huaa/dsh-workspace-upload

dsh-workspace-upload

一个用于 dsh Web 配置文件的
工作区文件管理器插件——直接在聊天界面中浏览、上传、下载、重命名、创建和删除
会话工作区中的文件。

功能

* 输入框左侧控件中的 文件 (Files) 按钮 会在应用上方打开一个文件管理器
对话框：
* 浏览工作区及其子目录（面包屑导航、向上 /
刷新）；
* 上传——多文件、分块、任意大小（640 KiB 分块，在代理请求体限制下
自适应缩小）；
* 下载文件；
* 重命名文件和文件夹；
* 创建文件夹；
* 删除文件和文件夹（两步确认）。
* 每个操作都限定在工作区根目录内：主机侧路径包含检查
会拒绝任何 .. 或绝对路径逃逸。
* 工作区解析为会话的工作区（会话 → cwd → 第一个
已注册的工作区）。

目录结构

dsh-workspace-upload/
├── cordis.patch.yml      # 配置文件补丁层：插入插件行
├── package.json          # dsh.bundle / dsh.client 声明、导出
├── lib/
│   ├── index.js          # 主机半部分：/api/workspace-upload 文件管理器路由
│   └── client.js         # 客户端半部分：浏览器包（按钮 + 对话框）
├── test/
│   ├── protocol.mjs      # 主机协议测试（真实处理器，无需 dsh）
│   └── simulate.mjs      # 客户端内核模拟（插槽注册伪造）
├── LICENSE               # MIT
├── .gitignore
├── README.md             # 英文
└── README-zh.md          # 中文

架构

一个包、一个配置文件行、两个半部分：

| 半部分 | 文件 | 角色 |
| --- | --- | --- |
| 主机 | lib/index.js | 在 dsh Web 服务器上注册 GET/POST /api/workspace-upload：列表 / 重命名 / 创建目录 / 删除 / 下载 / 分块上传，全部带有工作区包含检查。 |
| 客户端 | lib/client.js | 浏览器包（window.__ModuleLoader__.load）：conversation.input.left 中的触发按钮；对话框从按钮自身渲染（纯本地状态，position: fixed 覆盖层）。 |

接线：

* package.json → dsh.bundle.patch 指向 cordis.patch.yml（插入该行的
配置文件层），并且 dsh.client.platform: "web" 将该
包标记为浏览器名册条目，其包通过 exports["./client"] 发布。
* cordis.patch.yml 向 Web
组合中插入一行 workspace-upload。

API

GET  /api/workspace-upload
→ { "workspace": "" }        (no params)
→ file download with attachment headers              (?sessionId&path&name)

文件管理器模式（JSON POST；path 是工作区相对目录
"" / "sub" / "sub/deep"，name 始终是一个路径段）：

{ "mode": "list",   "sessionId"?, "path"? }                    → { workspace, path, entries:[{name,type,size,mtime}] }
{ "mode": "rename", "sessionId"?, "path"?, "name", "newName" } → { ok, from, to }
{ "mode": "mkdir",  "sessionId"?, "path"?, "name" }            → { ok, path }
{ "mode": "delete", "sessionId"?, "path"?, "name" }            → { ok, deleted }

分块上传（任意文件大小；GUI 发送 640 KiB 分块——base64 正文约
853 KiB，低于 nginx 默认的 client_max_body_size 1 MiB；遇到裸
413 时，客户端将分块大小减半至 64 KiB 并重试）：

{ "mode": "chunk",  "sessionId"?, "path"?, "transferId", "name", "offset", "data", "total" } → { received }
{ "mode": "finish", "sessionId"?, "path"?, "transferId", "name", "total", "overwrite"? }     → { status, path, bytes }
{ "mode": "abort",  "transferId" }                                                            → { aborted }

分块会追加到目标目录内隐藏的 .dsh-upload- 临时文件中，并在
完成时重命名。分块必须从偏移量 0 开始按顺序到达；在已接收偏移量处重复的
分块会以幂等方式应答（客户端可安全重试）。孤立的传输会在
30 分钟后被清理。

为兼容 API/curl，保留了旧版单次批量模式：

{ "sessionId"?, "files": [{ "name", "data": "", "overwrite"? }] }
→ { "workspace": string, "results": [{ name, path?, status, bytes?, error? }] }

限制：每个请求 32 MiB（一个分块 + 开销），每个分块解码后 8 MiB。
overwrite: true 会替换现有文件；否则该文件会被跳过，并返回
status: "skipped"。

安装

该包作为 dsh 配置文件捆绑包安装。在拥有该
包目录的检出目录中执行：

dsh plugin --profile web add ./dsh-workspace-upload
or from a clone:  dsh plugin --profile web add /path/to/dsh-workspace-upload

然后重启 web 配置文件（dsh web ...），以便加载器识别新的
条目，并刷新浏览器。移除插件：

dsh plugin --profile web remove dsh-workspace-upload

开发

两个测试都无需 dsh 实例即可运行（它们直接测试真实的主机处理器和
客户端捆绑包工厂）：

node test/protocol.mjs   # host protocol: list/rename/mkdir/delete/download/chunked upload
node test/simulate.mjs   # client kernel: slot registration against a faithful slots fake

安全说明

* 所有 path / name 值都会在主机上经过清理和包含性检查；
上传使用隐藏的临时文件，这些文件绝不会逃逸出目标目录。
* 该路由继承 dsh web 服务器的绑定（默认 localhost）；当
远程暴露 GUI 时，请将其置于与应用其余部分相同的 TLS/Basic-Auth 反向
代理之后（并且如果你希望减少分块数量、增大分块体积，请提高 client_max_body_size）。