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

dsh-web-terminal

一个终端停靠面板，并入 DSH Web GUI：可隐藏、与聊天分屏（它占据 shell 真正的底部区域，所以各列会收缩，而不是被盖住）、可集成专为终端设计的 TUI 插件。

┌─────────────────────────────┐
│ session header [终端] │ ← toggle (conversation.session.header.utilities) ├─────────────────────────────┤ │ conversation (chat) │ ← keeps its own scrollport, stays mounted ├─────────────────────────────┤ ← shell.bottom slot
│ [Shell] [Panel] × │ ← dock tab bar
│ xterm.js terminal / TUI │ ← full-emulation ConPTY
└─────────────────────────────┘

- 隐藏 / 显示：点标题栏按钮，或按 Ctrl+\。隐藏后底部区域高度收为 0；xterm 实例和 PTY 会话都保留（VS Code 风格）。
- 分屏：停靠面板占据 shell.bottom，这是内置插槽，渲染高度会从三列中扣除。不注入 DOM，不用 padding 取巧。高度可拖动（120–900 px），并持久化到 localStorage（dsh.webTerminal.v1）。
- TUI 集成：任何为终端设计的 TUI 都能在 PTY 里原样运行（vim、htop、tian-shu-tui……），另外提供 registerView API，插件可以添加自己的视图。

安装

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

bundle 补丁会插入宿主部分（lib/index.js：node-pty PTY + WebSocket 桥接 + webTerminal 注册表）和客户端部分（lib/client.js：停靠面板组件）。

架构（0.2）

| 模块 | 文件 | 说明 |
| 插件入口（宿主） | src/index.ts | 注入 webServer，在 ctx.effect 下挂路由和 webTerminal 服务，Config schema 驱动设置页 |
| 路由 + 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 | 注册到 shell.bottom + conversation.session.header.utilities，绑定 Ctrl+\ |
| 停靠面板 UI | src/client/dock.tsx | xterm + FitAddon、标签页、拖动调整大小、TUI 通道 |
| TUI 通道 | src/client/tui-channel.ts | window CustomEvent 通道 |
| 示例适配器 | src/examples/ | 一个 dom 视图（demo:panel，验证 CustomEvent 通道） |

客户端 bundle 规则

- 浏览器产物以包名注册一个懒加载工厂：
window.__ModuleLoader__.load({ id: 'dsh-web-terminal', factory(require) { … } })。
- React、react-dom 和 react/jsx-runtime 通过 require() 从加载器的模块表获取——绝不内联第二份副本（两个 React 实例会破坏钩子和 shell 的渲染器）。@xterm/ 不在那张表里，保持打包状态。
- apply(ctx) 只注册插槽和副作用；工厂函数里不要放副作用。

通信协议（/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, // run through the default Windows shell
env: { ...env, MY_FLAG: '1' },
}),
}), 'my-plugin: tui view')

客户端侧 —— 同一个插件的浏览器部分：

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 做钳制。
- socket 关闭/出错、标签页关闭、dock 卸载、插件销毁（ctx.effect 的清理函数）时都会杀掉 PTY；浏览器端不访问文件系统。

Windows 注意事项

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

构建

pnpm install # node-pty ^1.1.0 prebuilt win32-x64 — no compiler needed
pnpm build # tsc typecheck + tsdown → lib/index.js + lib/client.js

兼容性

- 目标：DSH 0.2.x（shell.bottom 插槽时代）。0.1 系列用 DOM 注入把 dock 挂进对话栏，那条路已经没了。
- 已在 0.2.1-rc.3 上验证（Windows，ConPTY）。