dsh-sidebar-explorer-plus

Readme

# dsh-sidebar-explorer-plus

**A TypeScript / React file manager for the DeepSeek Harness sidebar.**

[English](#english) · [中文](#中文)

## English

Adds a **Files** tab to `dsh-better-sidebar` through its public `ctx.betterSidebar.registerTab` service. The plugin combines a React file tree with host-side file operations, without modifying the sidebar foundation.

### Features

- Drag and drop files or folders to upload, preserving folder structure.
- Move, rename, delete, and create directories from the file tree.
- Open files in the sidebar editor.
- Reject existing destinations when moving or renaming. Uploads can replace existing files; deletion is permanent and asks for confirmation in the UI.
- Host/origin request checks, upload-size limits, and working-directory path checks in the host API.

### Install

Requires a running DSH web profile, `dsh-better-sidebar` (peer dependency `>=0.4.0`), and Node.js 20 or newer.

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

Restart `dsh web`, then hard-refresh the browser. Open the sidebar **+** menu and select **Files / 文件**. The repository includes built files in `lib/`, so Git-based installation does not require a local build.

### Code and API map

| Part | Responsibility |
| --- | --- |
| [`src/index.ts`](src/index.ts) | Host routes, request checks, upload limits, file operations, and structured errors. |
| [`src/client/index.tsx`](src/client/index.tsx) | React file tree, drag and drop, context menus, and tab registration. |
| [`build.mjs`](build.mjs) | Host/client bundling; the build script also generates TypeScript declarations. |
| [`cordis.patch.yml`](cordis.patch.yml) | Plugin mounting configuration. |

All operations use `POST /sidebar-explorer/<operation>`:

| Operation | Payload |
| --- | --- |
| `upload` | Query: `sessionId`, `name`, optional `dir` and `cwd`; raw bytes in the body. |
| `delete` / `mkdir` | JSON: `sessionId`, absolute `path`, optional `cwd`. |
| `move` | JSON: `sessionId`, absolute `from` and `to`, optional `cwd`. |
| `rename` | JSON: `sessionId`, absolute `path`, new `name`, optional `cwd`. |

Successful operations return `{ ok: true, value }`. Operation errors return `{ ok: false, error: { code, message } }`; rejected trust checks and unsupported HTTP methods return plain HTTP 403/405 responses.

### Development

```sh
npm ci
npm run typecheck
npm run build
```

The default upload limit is **50 MiB per file**. Set `uploadLimit` in the profile config to change the byte limit; see the [configuration example](#配置可选) below.

### Troubleshooting and operating scope

- **Tab missing:** confirm the sidebar dependency is installed, restart the host, and hard-refresh the browser.
- **HTTP 403:** check the configured trusted host and the browser origin.
- **HTTP 409 on move/rename:** choose a destination that does not already exist.
- **Upload too large:** reduce the file size or adjust `uploadLimit`.

The current path checks compare path strings; they do not resolve symlinks or fully canonicalize traversal segments in every operation. Working-directory selection also has client/process fallbacks. Run this in a trusted workspace; these checks do not establish isolation for untrusted filesystem content or callers.

## 中文

一个 `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）。

```sh
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/<op>`；`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。

## 开发 / 构建

```sh
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）：

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

## License

MIT