# dsh-plugin-terminal

<p align="center">
  <a href="https://github.com/mervyn-teo/dsh-plugin-terminal">
    <img src="assets/banner.png" alt="dsh-plugin-terminal 横幅 — DeepSeek Harness 页脚中的真实 PTY 终端" width="100%">
  </a>
</p>

[English](README.md) | 中文

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）Web
插件：在页脚添加一个 **真实** 的交互式终端 —— 一个 VS Code 风格的、停靠在底部
的可折叠面板。与早期版本（用内置 `help`/`echo`/`ls` 命令伪造输出）不同，本插件
在 PTY 中运行真正的 shell，并把原始终端字节流传输到浏览器。它是一个持久化的
bundle 插件（Host 半边 + 浏览器半边），每次启动都会自动加载。

## 演示

<p align="center">
  <img src="assets/demo.gif" alt="dsh-plugin-terminal 演示 — 页脚中的真实终端" width="640">
</p>

## 功能

- **真实终端** —— 在 PTY 中运行真正的交互式 shell（Windows 默认 PowerShell，
  其他平台默认 `$SHELL`/`/bin/bash`），底层使用 DSH 的 `subprocess.spawnTerminal`
  原语（node-pty）。
- **完整终端渲染** —— xterm.js 渲染 ANSI 颜色、光标移动、全屏应用
  （`vim`、`htop`、`top` …）以及 256 色输出。
- **VS Code 风格页脚面板** —— 可折叠的底部面板，带标题栏、顶部拖拽调整大小、
  重启按钮与折叠开关。
- **键盘快捷键** —— `Ctrl+`` `` 切换面板（VS Code 默认快捷键）。
- **实时调整大小** —— 调整面板时 PTY 会重新换行。
- **Terminal 配置卡片** —— 在 设置 → 插件 中实时配置主题、字号、面板高度、
  不透明度、启动折叠、shell 与工作目录。
- **优雅降级** —— 当 xterm.js 无法加载时（离线），纯文本流式视图仍能使用真实
  shell。

## 文件

| 文件 | 用途 |
| --- | --- |
| `lib/index.js` | Host 半边 —— 创建 PTY 并通过 `/api/terminal` WebSocket 桥接。 |
| `lib/client.js` | 浏览器半边 —— 页脚面板与配置卡片。 |
| `cordis.patch.yml` | 插入插件行的组合补丁。 |
| `package.json` | 包元数据（`dsh.bundle` + `dsh.client` 清单）。 |

## 安装

```bash
dsh plugin --profile web add github:mervyn-teo/dsh-plugin-terminal
```

然后重启 `dsh web` —— Host bundle 在启动时加载。

默认配置在 `cordis.patch.yml`。可在那里（或 profile 自带的 `cordis.patch.yml`）
修改后重启，或在运行时通过配置卡片调整。Host 半边提供两个同源路由供浏览器半边
使用：`GET|POST /api/terminal/config` 与 `/api/terminal` WebSocket 升级。

## 依赖

- DSH 需要挂载 `subprocess` 与 `webServer` 服务。
- 终端首次渲染 xterm.js 时需要能访问 jsDelivr（纯文本降级视图无需网络）。

## 设置

设置 → 插件 → **Terminal** 提供：

| 设置 | 说明 |
| --- | --- |
| 主题 | `dark` 或 `light` 终端主题（实时生效）。 |
| 字号 | 终端字号（像素，实时生效）。 |
| 最大高度 | 面板最大高度（像素）。 |
| 不透明度 | 终端背景不透明度 0–100%（100 = 完全不透明）。 |
| 启动折叠 | 面板是否在启动时折叠。 |
| Shell | 新会话使用的 shell 可执行文件。 |
| 工作目录 | 新会话的默认目录（留空 = 主目录）。 |

Shell 与工作目录在下次打开终端时生效；主题、不透明度、字号与最大高度立即生效。

## 说明与限制

- 终端从 jsDelivr CDN 加载 xterm.js；首次展开需要网络访问。纯文本降级视图离线
  仍可用。
- 会话是进程本地的，重启 DSH 后不会恢复。
- 与 Web GUI 的其他部分一样，WebSocket 路由仅绑定回环地址。
- **Windows** —— Windows 上默认 shell 为 `powershell.exe`（将 `shell` 设为
  `cmd.exe`、`shellArgs` 设为 `[]` 可切换为命令提示符）。需要 DSH 主机提供为
  Windows 构建的 `node-pty`（conpty/winpty）。

## 许可证

[MIT](LICENSE)