dsh-terminal-plugin

Readme

# dsh-terminal-plugin

[English](README.en.md) | 中文

为 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。

## 安装与构建

在仓库根目录执行：

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

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

```bash
npx @deepseek-ai/dsh --help
```

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

```bash
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` 中加入下面这一项：

```yaml
- 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`](src/config.ts)。

## 安全说明

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

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

## 已知限制

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

## 开发说明

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

```bash
npm run build
npm test
```

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