侧栏文件管理 Wulabalabo/dsh-sidebar-Explorer-Plus

dsh-sidebar-explorer-plus

一个用于 DeepSeek Harness 侧边栏的 TypeScript / React 文件管理器。

English · 中文

通过 dsh-better-sidebar 的公开 ctx.betterSidebar.registerTab 服务，为其添加一个 Files 标签页。该插件将 React 文件树与宿主端文件操作相结合，且不修改侧边栏基础。

功能特性

- 拖放文件或文件夹以上传，并保留文件夹结构。
- 从文件树中移动、重命名、删除以及创建目录。
- 在侧边栏编辑器中打开文件。
- 移动或重命名时拒绝已存在的目标位置。上传可以替换现有文件；删除是永久性的，并会在 UI 中请求确认。
- 宿主 API 中提供宿主/来源请求检查、上传大小限制以及工作目录路径检查。

安装

需要运行中的 DSH web 配置文件、dsh-better-sidebar（对等依赖 >=0.4.0）以及 Node.js 20 或更高版本。

dsh plugin --profile web add github:Wulabalabo/dsh-sidebar-Explorer-Plus

重启 dsh web，然后强制刷新浏览器。打开侧边栏 + 菜单并选择 Files / 文件。该仓库在 lib/ 中包含已构建的文件，因此基于 Git 的安装不需要本地构建。

代码与 API 映射

| 部分 | 职责 |
| src/index.ts | 宿主路由、请求检查、上传限制、文件操作以及结构化错误。 |
| src/client/index.tsx | React 文件树、拖放、上下文菜单以及标签页注册。 |
| build.mjs | 宿主/客户端打包；构建脚本还会生成 TypeScript 声明。 |
| cordis.patch.yml | 插件挂载配置。 |

所有操作均使用 POST /sidebar-explorer/：

| 操作 | 载荷 |
| upload | 查询参数：sessionId、name，可选 dir 和 cwd；请求体中为原始字节。 |
| delete / mkdir | JSON：sessionId、绝对 path，可选 cwd。 |
| move | JSON：sessionId、绝对 from 和 to，可选 cwd。 |
| rename | JSON：sessionId、绝对 path、新 name，可选 cwd。 |

成功的操作返回 { ok: true, value }。操作错误返回 { ok: false, error: { code, message } }；被拒绝的信任检查和不受支持的 HTTP 方法返回纯 HTTP 403/405 响应。

开发

npm ci
npm run typecheck
npm run build

默认上传限制为每个文件 50 MiB。在配置文件配置中设置 uploadLimit 以更改字节限制；请参阅下方的配置示例。

故障排除与操作范围

- 标签页缺失： 确认侧边栏依赖已安装，重启宿主，并强制刷新浏览器。
- HTTP 403： 检查已配置的可信宿主以及浏览器来源。
- 移动/重命名时出现 HTTP 409： 选择一个尚不存在的目标位置。
- 上传过大： 减小文件大小或调整 uploadLimit。
当前路径检查比较的是路径字符串；它们不会在每次操作中解析符号链接或完全规范化遍历片段。工作目录选择也有客户端/进程回退。请在可信工作区中运行；这些检查不会为不可信的 filesystem 内容或调用方建立隔离。

一个 dsh-better-sidebar 的消费插件：在侧边栏新增一个「文件」tab，内置一棵固定在工作区（cwd）内的文件树，提供真正的文件管理能力——上传、移动、删除、重命名、新建文件夹。它补充了 better-sidebar 自带 Explorer 缺失的「写」操作（Explorer 只读）。

它通过 dsh-better-sidebar 公开的 ctx.betterSidebar.registerTab 服务注册，是一个独立插件，不改动 better-sidebar 源码。

功能

- 🗂️ 拖拽任意文件（文本 / 图片 / PDF / 二进制…）上传，上传到指定目录
- 📁 拖拽整个文件夹上传，按原目录结构落盘
- 📂 文件树展示文件与文件夹；点文件在侧边栏编辑器打开
- ↕️ 拖拽移动：把文件/文件夹拖到另一个文件夹上移动（冲突报错跳过，不覆盖）
- ✏️ 重命名：右键 → 重命名
- 🗑️ 删除：右键 → 删除（永久删除 + 二次确认；文件夹递归删除）
- ➕ 新建文件夹：在选中目录下建子目录
- 🔒 Host/Origin 请求检查、上传大小限制及工作目录路径检查；当前实现使用路径字符串比较，不保证符号链接或所有路径穿越场景的隔离，请用于可信工作区。

安装

前置：已安装 dsh-better-sidebar（本插件通过其 betterSidebar 服务注册 tab）。

dsh plugin --profile web add github:Wulabalabo/dsh-sidebar-Explorer-Plus

装完重启 dsh web（本插件含 host 半），再浏览器硬刷新（Cmd/Ctrl+Shift+R），侧边栏 + 菜单里就会出现「文件」tab。

工作原理

| 半边 | 作用 |
| host（src/index.ts → lib/index.js） | 注册 /sidebar-explorer/ 路由：upload（原始字节）/ delete / move / rename / mkdir（JSON），全部限定在会话 cwd 内 |
| client（src/client/index.tsx → lib/client.js） | ctx.betterSidebar.registerTab 注册 sidebar-explorer tab，渲染文件树 + 拖拽区 + 右键菜单 |

路由契约：POST /sidebar-explorer/；upload 用 query（sessionId/dir/name）+ 原始 body，其余用 JSON body（sessionId/path/from/to/name），均可携带可选 cwd。成功响应为 { ok: true, value }，操作错误为 { ok: false, error: { code, message } }；请求信任检查失败或 HTTP 方法不支持时直接返回 403/405。

开发 / 构建

npm install # 安装 devDependencies
npm run typecheck # tsc --noEmit
npm run build # esbuild 打包 + 生成 lib/types/.d.ts

- lib/ 是构建产物，已提交进仓库，因此从 git 安装无需任何构建步骤。
- 客户端 bundle 走 window.__ModuleLoader__.load({ id: 'dsh-sidebar-explorer-plus', factory }) 注册，react 作为 external 由模块表运行时解析。

配置（可选）

在 profile 的挂载行加 config 可调上传大小上限（默认 50 MB）：

- insert:
- id: sidebar-explorer
name: 'dsh-sidebar-explorer-plus'
config:
uploadLimit: 104857600 # 100 MB

License

MIT