zjuatri/dsh-terminal-plugin

dsh-terminal-plugin

为 DeepSeek Harness（DSH）Web GUI 提供一个 VS Code 风格的底部终端面板。

- 按 Ctrl+\ 打开或收起面板
- 支持多终端标签和 Ctrl+Shift+\ 新建终端
- 使用真实 PTY：颜色、光标控制、备用屏以及 vim、python、top 等交互程序均可正常运行
- 终端面板只占中间对话区，不会挤压左右侧边栏
- 输出里的 URL 与文件路径可以 Ctrl/Cmd + 点击打开
- 右键按 VS Code 的习惯分流：有选中就复制，没选中就粘贴
- 刷新页面后终端仍会保留，并回放近期输出

这是供页面使用者操作的终端，不是 DSH agent 使用的 ctx.terminals 持久终端。

环境要求

- Node.js 20 或更高版本
- 已安装或可通过 npx 运行带 Web profile 的 @deepseek-ai/dsh
- PowerShell 7（Windows 推荐；缺失时会回退到 Windows PowerShell）

ws 会随本插件依赖安装；构建时还需要从 DSH profile 链接 peer dependencies。

安装与构建

在仓库根目录执行：

npm run link-deps  # 一次性：链接 DSH profile 中的依赖
npm run vendor     # 一次性：下载并复制 xterm.js 资源
npm run build      # 构建宿主、客户端和静态资源
npm test           # 运行测试

本仓库只包含插件，不提供 dsh 命令。先用下列命令确认 DSH CLI 可以运行：

npx @deepseek-ai/dsh --help

推荐通过 DSH CLI 将插件装入 Web profile；它会加载包内的 cordis.patch.yml：

npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-terminal-plugin
npx @deepseek-ai/dsh plugin --profile web add git+https://github.com/zjuatri/dsh-terminal-plugin.git

如果你已全局安装 @deepseek-ai/dsh，可将上面命令开头的 npx @deepseek-ai/dsh 换成 dsh。

若使用本地源码且需要手动挂载，可在 Web profile 的 cordis.patch.yml 中加入下面这一项：

- insert:
- id: dsh-terminal-plugin
name: "file:///绝对路径/dsh-terminal-plugin/lib/index.js"

修改或安装宿主端后，请重启 dsh web；只修改客户端界面时，刷新浏览器页面即可。

使用方式

1. 打开 DSH Web GUI，点击输入框工具栏中的终端按钮，或按 Ctrl+\。
2. 首次打开时会自动创建一个终端；点击面板工具栏中的 + 可新建标签。
3. 终端默认使用当前会话所属的工作区作为工作目录。若无法识别工作区，则回退到 DSH 进程的工作目录。
4. 关闭最后一个标签时，默认会立即创建一个新的终端，避免面板变为空状态；收起面板即可暂时隐藏它。

终端会话运行在 DSH 宿主进程中，因此浏览器刷新、短暂断网或重新打开面板都不会终止正在运行的命令。

点击链接

输出里的链接会带下划线并显示手型光标，按住 Ctrl（macOS 为 Cmd）点击即可打开，
与 VS Code 集成终端一致：

| 识别对象 | 例子 | 打开方式 |
| --- | --- | --- |
| 带协议的 URL | http://localhost:3000、https://example.com/a?b=1 | 新标签页 |
| 裸 localhost 地址 | localhost:5173/app（dev server 常见写法） | 补上 http:// 后新标签页 |
| 绝对文件路径 | D:\repo\src\index.ts:12:3、/home/u/app/main.js:7 | file:// 地址（行号列号留给编辑器定位） |

出于安全考虑，只有 http / https / ftp 协议会被打开，javascript:、data:、file:
一律不打开 —— 终端输出属于不可信内容，不能让它拿到一个执行入口。相对路径（./a.ts）
因为没有基准目录，也不会被当作链接。

悬停到链接上会显示下划线、手型光标与「Ctrl+点击打开 …」的提示；不按修饰键的普通点击
不会打开任何东西，也不会误传到终端选区之外。链接的命中范围按终端列计算，中文等
宽字符占两列也不会让链接整体错位。

右键：有选中就复制，没选中就粘贴

终端区域内的右键由插件接管，行为与 VS Code 集成终端一致（浏览器自带的右键菜单不会弹出）：

| 右键时的状态 | 行为 |
| --- | --- |
| 有选中内容 | 复制到系统剪贴板，并清掉选区 |
| 没有选中内容 | 读取剪贴板并粘贴到终端（换行按终端语义转换） |

粘贴走 xterm 的粘贴通道，因此 bracketed paste 等终端模式下的行为与 Ctrl+V 完全一致。
剪贴板权限被浏览器拒绝时（例如非安全上下文）静默失败，不会报错或弄坏终端。

配置

在插件配置中可设置以下常用项：

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| mountPrefix | /dsh-terminal | 插件 HTTP 与 WebSocket 路径前缀 |
| shellPath | 自动探测 | 交互式 shell 的绝对路径 |
| shellArgs | 自动选择 | shell 启动参数 |
| cwd | 当前工作区 | 新终端工作目录；支持 {cwd} 占位符 |
| env | {} | 附加环境变量 |
| rows / cols | 24 / 80 | 初始终端尺寸 |
| scrollbackBytes | 262144 | 断线重连时保留的输出字节数 |
| idleCloseAfterMs | 0 | 无人连接多久后关闭；0 表示不自动关闭 |
| maxTerminals | 20 | 同时存在的终端上限 |

完整配置定义见 src/config.ts。

安全说明

终端等同于用户在本机打开的 shell，应只向可信用户开放。插件的 HTTP 与 WebSocket 请求会复用
DSH Web 的 Host/Origin 校验和 Cookie 认证；在缺少该能力的少数组合中，只接受回环地址请求。

请勿将插件端口直接暴露给不受信任的网络，也不要绕过 DSH 的认证配置。

已知限制

- 拖动面板高度不会调整已运行 PTY 的行列数；新建终端会采用当时的尺寸。
- 同一终端在多个浏览器连接中同时打开时，输入会共享，适合单人使用场景。
- 输出回放只保留最近 scrollbackBytes 字节，较早内容无法恢复。
- 被终端折行的长 URL 不会跨行拼接：折行处两段各自识别，只能点到能独立成 URL 的那一段。

开发说明

源码位于 src/，构建产物位于 lib/。提交前建议执行：

npm run build
npm test

许可证为 MIT。随插件分发的 xterm.js 及其适配器同样采用 MIT；详见
vendor/README.md。