终端停靠面板qichuang321/dsh-web-terminal

dsh-web-terminal

一个合并到 DSH Web GUI 中的终端停靠面板：可隐藏，可见时与聊天栏分屏，并且可与为终端设计的 TUI 插件集成。

┌─────────────────────────────┐
│  session header  [ 终端 ⇧ ] │  ← 切换按钮 (conversation.session.header.actions)
├─────────────────────────────┤
│  conversation (chat)        │  ← 保持挂载与状态
│  ────────────────────────   │  ← 拖拽手柄 (调整大小)
│  [Shell] [Panel] ×│  ← 停靠标签栏
│  xterm.js terminal / TUI    │  ← 全仿真 ConPTY
└─────────────────────────────┘

- 隐藏 / 显示：标题栏按钮或 Ctrl+ —— 停靠面板、xterm 实例和 PTY 会话在切换后全部保留（不会拆除任何东西；VS Code 风格）。
- 分屏：停靠面板绝对停靠在中间列的底部区域；聊天在其上方保留自己的滚动视口；高度可拖拽（120–900 px）并持久化在 localStorage（dsh.webTerminal.v1）中。
- TUI 集成：任何为终端设计的 TUI 都能在 PTY 中原样运行（vim、htop、tianshu-tui……），此外还提供扩展 API，使插件可以注册自己的视图。

安装

dsh plugin --profile web add link:D:\Deepseek Harness\dsh-web-terminal
restart the web GUI, then use the header toggle or Ctrl+

该插件通过 cordis.patch.yml（bundle 补丁层，dsh-ssh 模式）挂载：宿主部分 = lib/index.js（node-pty PTY + WebSocket 桥接 + 注册表服务），浏览器部分 = lib/client.js（停靠面板）。

架构

| 部分 | 文件 | 说明 |
| --- | --- | --- |
| 插件入口（宿主） | src/index.ts | webServer 注入，路由 + ctx.effect 下的 webTerminal 服务 |
| 路由 + WS 终端 | src/routes.ts | 回环防护，WebSocketServer({noServer:true})，1MB/512KB 背压 |
| PTY 层 | src/pty.ts | 直接使用 node-pty（^1.1.0，预构建 win32-x64 ConPTY），TERM/COLORTERM 环境变量，默认 powershell.exe |
| 共享协议 | src/protocol.ts | 帧类型 + WT_API 路径 + 限制值 |
| TUI 注册表 | src/tui-registry.ts | webTerminal.registerView(def) 扩展接缝 |
| 客户端入口 | src/client/index.ts | 停靠面板挂载，标题栏切换插槽，Ctrl+\ |
| 停靠面板 UI | src/client/dock.tsx | xterm + FitAddon，标签页，拖拽调整大小，TUI 通道 |
| TUI 通道 | src/client/tui-channel.ts | window CustomEvent 通道 |
| 演示适配器 | src/examples/ | 一个 dom 视图（demo:panel，验证 CustomEvent 通道） |

传输协议（/api/dsh-web-terminal/，回环防护）

server→client: {type:'ready',view,cols,rows} | {type:'output',data}
| {type:'title',title?} | {type:'exit',code,error?}
client→server: {type:'input',data} | {type:'resize',cols,rows}

TUI 插件集成 API

宿主侧 —— 任何 DSH 插件都可以在自己的 ctx.effect 中注册视图：

const webTerminal = ctx.get('webTerminal')
ctx.effect(() => webTerminal?.registerView({
id: 'my-plugin:my-tui',        // namespaced 'pluginId:viewId'
label: 'My TUI',
order: 10,
spawn: ({ cols, rows, env }) => ({
command: 'npx',
args: ['--yes', 'my-tui'],
shell: true,                 // 通过默认的 Windows shell 运行
env: { ...env, MY_FLAG: '1' },
}),
}), 'my-plugin: tui view')

客户端侧 —— 同一插件的浏览器部分：
ts
import { dispatchRegister, dispatchUnregister, onTuiEvent, TUI_EVENTS } from 'dsh-web-terminal/client'

ctx.effect(() => {
dispatchRegister({ id: 'my-plugin:my-tui', label: 'My TUI', kind: 'pty' })
return () => dispatchUnregister('my-plugin:my-tui')
}, 'my-plugin: tui client')

事件：适配器→dock 的 register / unregister；dock→适配器的 ready（重新注册，
自愈）、activate（{id,container} —— dom 视图在此渲染）、deactivate、
view-state（{id,state:'running'|'exit'|'error',code?,error?}）。

安全

- 每个路由 + WS 升级都带有仅限回环的防护（remoteAddress ∈
{127.0.0.1, ::1, ::ffff:127.0.0.1}、Host 为 localhost、sec-fetch-site 和
Origin 检查）—— 暴露在局域网中的 dsh web 部署不得提供这些内容。
- 客户端帧经过严格校验；仅接受 input/resize，
cols/rows 会被钳制。
- PTY 会在 socket 关闭/出错、标签页关闭、dock 卸载以及插件
dispose（ctx.effect 清理函数）时被终止；浏览器不进行任何 fs 访问。

Windows 注意事项

- node-pty 在 Windows 上从不根据 name 选项设置 TERM —— 该插件
在 env 中显式设置 TERM=xterm-256color/COLORTERM=truecolor。
- kill(signal) 在 Windows 上会抛出异常 —— 只能使用不带参数的 kill()；Ctrl+C 是 \u0003。
- 默认 shell：powershell.exe（若已安装则为 pwsh，最后才用 cmd.exe）。
cmd.exe 可能需要 chcp 65001 才能输出 UTF-8 TUI。
- ConPTY 原生发出 CRLF —— 桥接层从不转换行尾（convertEol:false）。

构建
sh
pnpm install        # node-pty ^1.1.0 预构建的 win32-x64 —— 无需编译器
pnpm build          # tsc 类型检查 + tsdown → lib/index.js + lib/client.js