dsh-workspace-toolbox

DSH（DeepSeek Harness）Web UI 的工作区工具箱插件 —— 文件浏览、Docker 与 Vite 项目管控，一体集成在会话内。

在会话视图栏的“轨迹”标签之后新增一个**「工具箱」**页签（对话 | 轨迹 | 工具箱），内含四个模式：文件、Docker、Vite、终端。

---

功能总览

模式	能力
📁 文件	面包屑一层一屏目录浏览、全工作区搜索、彩色类型图标、VS Code 风格多标签预览（语法高亮 / Markdown 渲染 / 图片 / 二进制）
🐳 Docker	本地 unix socket / SSH 隧道远程连接、镜像与容器管理、拉取/构建/运行长任务、容器日志
⚡ Vite	工作区 Vite 前端项目扫描、dev server 启动/停止管控、实时日志与访问地址
🖥️ 终端	进入 SSH 服务器（PTY）、进入 docker 容器（exec PTY）、本地 shell

---

模式详解

📁 文件

• 面包屑导航：每屏只显示当前一层目录，点击目录进入、← 返回上级、面包屑任意段可跳转，窄屏同样好用；
• 全工作区搜索：筛选框输入即搜（忽略 node_modules/.git 等噪音目录，深度 12、访问 6000、结果 200 上限），点击结果目录直接进入；
• 文件图标：按扩展名显示彩色类型缩写（约 40 种：JS TS PY GO {} MD ZIP IMG PDF 等）；
• 多标签预览（浏览器式标签页，上限 10 个、自动淘汰最旧）：
  • 文本：行号槽 + 语法高亮（highlight.js 内联 core + 22 种语言）；
  • Markdown：默认渲染视图（marked GFM + DOMPurify 消毒防 XSS），可切换源码视图；
  • 图片直接渲染；二进制提示类型与大小；
• 双击文件在系统中打开；预览有上限保护（文本 256KB/3000 行、图片 ≤3MB）。

🐳 Docker

• 连接管理：本机 unix socket；远程经 SSH 隧道（复用密码/私钥，不改服务器 docker 配置）；
  • 连接元数据（不含秘密）持久化，重启后可通过「连接」按钮一键重连（私钥认证）或删除；
• 镜像：列表、删除、拉取（实时进度）；
• 容器：列表、日志、启动/停止/删除、进入容器终端（docker exec PTY）；
• 构建/运行：工作区 Dockerfile 项目联动，构建上下文打包、运行参数（端口/环境变量）；
• 长任务：任务注册表 + 日志轮询，pull/build/run/stop/remove 全程进度可见。

⚡ Vite

• 自动扫描工作区内带 vite 依赖或 vite.config.* 的项目（深度 ≤5、忽略噪音目录）；
• 启动：项目目录执行 pnpm run dev（命令可编辑，如 pnpm --filter xx dev），日志实时回显，自动解析端口与访问地址；
• 停止：整进程树结束（Windows taskkill /T，POSIX 进程组）；
• 状态每 2 秒轮询，一键新标签页打开页面；插件卸载 / profile 退出时自动结束所有运行中的 dev server。

🖥️ 终端

• 服务器终端：已连接的 SSH 连接 → 打开带 PTY 的 shell 通道，直接进入服务器（支持 vim/top 等交互程序）；
• 容器终端：运行中容器行上的「终端」→ docker exec 进入容器 shell；
• 本地终端：本地连接 → 打开本地 shell；
• 基于 xterm.js：真终端渲染、尺寸自适应、滚动回看。

---

安装

要求 DSH 0.1.0-rc.6 或兼容的 DSH Web profile，以及已安装 pnpm。安装后重启 Web profile 生效（dsh web），在会话顶部的视图标签中点击「工具箱」。

纯 Client 侧改动（src/client/*）重建 bundle 后由 client-hmr 自动热更新，无需重启。

方式一：tag 归档安装（推荐，开箱即用）

直接使用随 tag 提交的 lib/ 构建产物，无需本地构建：

dsh plugin --profile web add https://github.com/wuyh/dsh-workspace-toolbox/archive/refs/tags/v0.3.0.tar.gz

方式二：git 源码安装（自动构建）

拉取源码并在 prepare 阶段自动构建（需要网络与 Node.js 18+）：

dsh plugin --profile web add github:wuyh/dsh-workspace-toolbox

pnpm ≥10 默认拦截依赖构建脚本；首次安装若提示，需在 profile 的 pnpm-workspace.yaml 中为 allowBuilds 授权（添加 ssh2: true）。

方式三：本地 link 安装（改源码即可迭代）

# 克隆或进入仓库目录
git clone https://github.com/wuyh/dsh-workspace-toolbox.git
cd dsh-workspace-toolbox
pnpm install          # 安装依赖并构建 lib/

# 在仓库的上级目录执行（link: 引用仓库路径）
cd ..
dsh plugin --profile web add link:./dsh-workspace-toolbox

改 src/ 后 pnpm run build 即可；Host 侧改动需重启 profile，Client 侧自动热更新。

---

安全模型

• 浏览器端只收到工作区相对路径与最小元数据（名称、类型、大小）；
• Host 侧所有读取都做工作区边界校验（.. 逃逸、越界符号链接被拒绝）；
• 文件面只读：不提供任何写入/修改文件的能力；
• Docker/Vite/终端能力仅在用户显式操作时执行（启动/停止/连接/进入容器）；
• SSH 密码/私钥口令只保存在运行时内存，重启后需重新输入。

---

架构与仓库结构

• 源码 src/（TypeScript，按职责拆分小模块），构建产物 lib/（随 tag 提交）；
• Host 面注册同源 HTTP 路由 + WebSocket 升级路由，Client 面是同源 fetch / WebSocket；
• Client bundle 由 scripts/build-client.mjs 进程内打包（内联 highlight.js/marked/dompurify/xterm，react 透传共享实例）。

src/
  index.ts               Host 入口：注册文件/Docker/Vite 路由与终端升级路由
  contract.ts            Host/Client 共享的路由与参数名契约
  host/
    services.ts          fs/agents/webServer 等最小类型面 + Context 扩展
    workspace.ts         会话工作区根目录解析（agent cwd → session cwd → 沙箱根）
    files.ts             单层列表 / 全工作区搜索 / 带边界的只读预览
    docker/
      engine.ts          Docker Engine API 客户端（unix socket / SSH 隧道，含 exec hijack 流）
      manager.ts         连接管理器（本地 + SSH 隧道，元数据持久化）
      routes.ts          Docker HTTP 路由（镜像/容器/构建/运行/任务）
      jobs.ts            长任务注册表（pull/build/run/stop/remove）
      projects.ts        Dockerfile 项目扫描
      ssh-tunnel.ts      SSH 隧道（stream-local 转发 docker socket）
      terminal.ts        终端 WebSocket 升级路由（SSH shell / 本地 shell / 容器 exec）
    vite/
      projects.ts        Vite 项目扫描
      manager.ts         dev server 进程管理（启动/停止/日志/URL 解析）
      routes.ts          Vite HTTP 路由
  client/
    index.ts             浏览器入口：注册“工具箱”页签
    files-view.ts        文件视图（面包屑/搜索/多标签预览）
    docker-view.ts       Docker 面板（连接/镜像/容器/任务/终端）
    docker-terminal.ts   xterm.js 终端组件
    docker-rpc.ts        Docker RPC 封装
    vite-view.ts         Vite 面板
    vite-rpc.ts          Vite RPC 封装
    rpc.ts               文件路由的 fetch 封装
    highlight.ts / markdown.ts / icons.ts / styles.ts / types.ts
scripts/
  build-client.mjs       tsc API 进程内打包 client（内联第三方库，react 透传）
  dev.mjs                开发监视器（改 src/ 自动重建 + client-hmr 热更新）
cordis.patch.yml         组合包 patch：把 Host 行挂进 profile
lib/                     构建产物（tsc 输出 + client bundle）

---

开发

要求 Node.js 18+ 和 pnpm：

pnpm install

# TypeScript 类型检查
pnpm run typecheck

# 构建 Host（tsc）与浏览器 bundle
pnpm run build

# 校验 lib/client.js 与源码同步
pnpm run check:client

发布路径：

• tag 归档安装：直接使用提交的 lib/ 产物，不执行构建脚本；
• git 安装（dsh plugin add github:wuyh/dsh-workspace-toolbox）：拉源码并在 prepare 中构建；pnpm ≥10 需在 profile 的 pnpm-workspace.yaml 中为 allowBuilds 授权。

---

License

MIT