前言¶

用 dsh web 做开发时，经常需要在浏览器里顺手执行几条命令。常见做法有两种：切到独立的终端窗口，或者用 overlay 式终端把会话内容盖住。前者要来回切换上下文，后者会遮挡正在进行的对话。

下面介绍的 dsh-web-shell 采用第三种思路：把终端停靠在窗口右侧，主对话栏自动让位，终端和会话内容同时可见，折叠面板也不会中断会话。

这是什么¶

dsh-web-shell 是 DeepSeek Harness 的右侧停靠 Web Shell 插件，由 JesmonX 维护，基于 MIT 许可证发布，npm 上的当前版本为 0.1.1。浏览器端使用 xterm.js 渲染终端，通过 /api/shell WebSocket 与宿主侧 PTY 桥接，支持 bash 和 zsh 切换。

DSH 的理念是「一切皆插件」，这类 UI 扩展正是通过插件机制接入宿主的。

核心功能¶

按 README 的描述，插件提供以下能力：

1、右侧停靠。打开后主对话栏自动让位，不再遮挡会话内容。完整效果需要较新的 dsh-client-ui-layout，旧版宿主会自动降级，见下文兼容性一节。

2、可调宽度。拖动 shell 左边缘即可调整，范围 360–960px。

3、按 profile 记忆布局。当前 profile 的 settings domain 保存 dock 宽度和折叠状态，刷新后恢复。具体来说，插件注册 web-shell settings namespace，字段为 dockWidth 和 folded；宽度只在拖拽结束时写入，折叠和关闭都会记录为 folded。设置不使用浏览器 localStorage，因此同一 profile 重新加载不会丢失布局偏好。

4、折叠与关闭分离。折叠隐藏面板但保持 WebSocket / PTY 会话存活，再次展开恢复同一个 shell；关闭则断开连接并终止 PTY，再次打开会创建新 shell。

5、bash / zsh 切换。切换时关闭旧 PTY 并启动新 shell。

6、安全预检 companion。插件同时发布 dsh-web-shell/invariant，导出 checkWebShellTrust()，对 /api/shell 升级路由做启动前安全围栏预检。

安装与启用¶

要求 DeepSeek Harness >= 0.1.0-rc.5（npm 上 @deepseek-ai/dsh 的 latest 为 0.1.0-rc.6）。

先从 npm 安装（推荐）：

dsh plugin --profile web add dsh-web-shell

安装后启动：

dsh web

点击窗口右侧的 ❯_ 按钮即可打开 shell。

也可以从 GitHub 安装：

dsh plugin --profile web add github:JesmonX/dsh-web-shell

仓库已提交构建好的 lib/，git 安装直接可用，不需要构建授权。如果插件管理器不支持 GitHub 简写，可先 clone 再本地安装：

git clone https://github.com/JesmonX/dsh-web-shell.git
dsh plugin --profile web add ./dsh-web-shell

典型用法¶

日常操作集中在面板按钮和边缘拖拽上：

• 打开 / 展开：右侧 ❯_ 按钮，打开 shell 或从折叠中恢复；
• 折叠：面板标题栏 › 按钮，隐藏面板但保持会话存活；
• 关闭：面板标题栏 × 按钮，终止会话；
• 切换 shell：标题栏 bash / zsh，启动新的 PTY；
• 调整宽度：面板左边缘拖拽，范围 360–960px。

宿主侧默认配置通过 cordis.patch.yml 注入：

- id: web-shell
  name: 'dsh-web-shell'
  inject: [webServer, subprocess, webRuntime]
  config:
    shells: [bash, zsh]
    defaultShell: bash
    rows: 40
    cols: 120
    graceMs: 5000
    fontFamily: '"Maple Mono NF CN", "Sarasa Mono SC", "Cascadia Code", "JetBrains Mono", "Noto Sans Mono CJK SC", "Microsoft YaHei UI", monospace'

各字段含义如下，均可在后续 patch 层覆盖：

• shells：可选 shell 列表，目前支持 bash 和 zsh；
• defaultShell：浏览器未选择时使用的默认 shell；
• cwd：新终端起始目录，默认 process.cwd()；
• rows / cols：初始终端行列数；
• graceMs：PTY 清理宽限时间；
• fontFamily：浏览器端 xterm.js 的 CSS 字体栈，使用浏览器所在系统的字体。

兼容性¶

插件的 shell.overlay 槽位由 dsh-client-ui-layout 声明。完整的「主对话栏让位」效果依赖该包提供 ctx.layout.setShellWidth / closeShell 等右侧停靠 API。

如果宿主 UI 版本较旧（有 shell.overlay 但没有右侧停靠 API），插件会自动降级为纯 overlay 模式：shell 仍可打开、折叠、关闭和拖拽，但主对话栏不会让位。

安全与注意事项¶

先说权限：shell 以与 dsh 进程相同的操作系统权限运行。装进环境之前，应检查插件源码和许可证，确认可接受再使用。插件采用 MIT 许可证，源码在 GitHub 上公开。

再看网络防护。/api/shell 升级路由使用与 /api 网关相同的 loopback / trusted-host / origin 防护；非 loopback 部署必须通过 trustedHosts 显式声明。

如果想在启动前发现配置缺口，可以接入 dsh-web-shell/invariant companion。它导出 checkWebShellTrust()，在 dsh 的 invariant/doctor 诊断组合中对解析后的 webServer / webRuntime 配置执行同一套 /api/shell 围栏预检：Host 必须存在，loopback 必须可用，非 loopback Host 必须在 trustedHosts 中，Origin 必须同源，Sec-Fetch-Site: cross-site 必须拒绝；绑定 0.0.0.0 时还必须配置至少一个合法 trusted host。这样问题在启动前暴露，而不是等 WebSocket 升级后才发现。

结尾¶

经过上面的步骤，你就得到了一个不遮挡会话、折叠不断线、布局可按 profile 记忆的浏览器终端。对经常在浏览器里操作 DSH 的开发者来说，这是一个值得装上试试的插件。

插件目录页：https://www.skillhub.cn/plugins/JesmonX/dsh-web-shell

GitHub 仓库：https://github.com/JesmonX/dsh-web-shell

需要说明的是，skillhub.cn 是社区维护的独立插件目录，与 DeepSeek、幻方没有官方从属关系。