@hyzyn/dsh-tty 0.15.0 → 0.16.1

package/README.md

@@ -3,8 +3,8 @@
 DSH Web GUI 的**终端面板**插件：侧边栏「终端」入口打开一个大弹窗，内嵌
 xterm.js 全交互终端（node-pty 真实 PTY，WebGL 渲染器加速），支持**多标签页**，
 可运行任意命令与 TUI 程序（vim / htop / dev server 等）。浏览器半体打包了 xterm
-内核，宿主半体经 WebSocket 与 PTY 会话双向透传。0.2.0 起支持 **SSH 连接
-（方案 C）**：`ssh2` 原生直连远程主机，像本地终端一样交互；0.3.0 起支持
+内核，宿主半体经 WebSocket 与 PTY 会话双向透传。0.2.0 起支持 **SSH 连接**：
+`ssh2` 原生直连远程主机，像本地终端一样交互；0.3.0 起支持
 **断线自动重连**与 **SSH 主机指纹 TOFU 钉扎**；0.4.0 起内置 **shell 集成
 （OSC 133/7）**——agent 能按「命令」粒度读写终端（`tty_capture{last}` /
 `tty_expect`），并支持 **agent forwarding**、**~/.ssh/config 导入** 等深化
@@ -28,7 +28,10 @@ SSH 侧同理（远程 tmux）；0.12.0 起做了一轮**界面视觉 overhaul**
 工具（见「开发」）；0.11.0 起支持 **SSH 连接测试**——设置卡片连接簿
 条目行内「测试」与 SSH 连接对话框「试连」，按 TCP → 主机密钥（TOFU）→
 认证 逐段诊断连接（见下文 SSH 连接）；SFTP 传输增加**可视化进度条**
-（上传/下载百分比，服务端直传为不定进度脉冲，见下文 SFTP）。
+（上传/下载百分比，服务端直传为不定进度脉冲，见下文 SFTP）；0.13.0 / 0.14.0 /
+0.15.0 / 0.16.0 依次开放客户端服务扩展点——连接栏按钮 `ttyConnbar`、命令标签
+`ttyTerminal.open`、就地嵌入终端 `ttyTerminal.mount`、面板内挂载位 `ttyPanel`
+（其他插件把自己的界面挂在终端右侧，终端保持可见，见下文「客户端服务」）。
 
 ![终端面板：多标签页 xterm 弹窗，工具栏含搜索/清屏/复制/粘贴，标题栏含最小化「—」与关闭 ✕](../../docs/dsh-plugin-kit-tty.png)
 
@@ -143,10 +146,16 @@ SSH 会话同表调度：`tty_list` 里 `kind: 'ssh'` 的条目按 `target`
 不动终端、不占会话名额，直接对 SSH 连接做远程文件操作（`ssh2` 的 sftp
 subsystem，宿主半体 `src/sftp.ts`）：
 
-![SFTP 单窗体：远程目录浏览，行内 下载/重命名/删除](../../docs/dsh-plugin-kit-tty-sftp-dialog.png)
+![SFTP 单窗体（0.16.0 起挂在终端下方抽屉）：远程目录浏览，行内 下载/重命名/删除](../../docs/dsh-plugin-kit-tty-sftp-dialog.png)
 
-![SFTP 双栏（0.9.0）：左本机 / 右远程，行内 ⇨/⇦ 服务端直传](../../docs/dsh-plugin-kit-tty-sftp-dual.png)
+![SFTP 双栏（0.9.0；0.16.0 起挂在终端下方抽屉）：左本机 / 右远程，行内 ⇨/⇦ 服务端直传](../../docs/dsh-plugin-kit-tty-sftp-dual.png)
 
+- **落点（0.16.0）**：终端面板开着且挂载位空着时，文件浏览**挂在终端下方**——路径栏 /
+  列表 / 传输进度占满整宽（文件列表是横向宽表，下方全宽比右侧窄栏好用，终端也保住
+  宽度不会折行；双栏两栏并排更需要这个宽度），终端继续可见可用。高度可拖、可折叠成
+  一条标题栏（折叠不关面板、不中断浏览）；挂载位已被别的面板（如容器面板）占用、或
+  面板没开时，退回原来的居中对话框，**不会把别人的面板挤掉**。标题 / 折叠 / ✕ 由
+  tty 的挂载位提供；
 - **入口**：① 标签栏「+」菜单的连接簿条目带 📂（按该条目打开文件浏览）；
   ② SSH 连接对话框填好主机/认证后点「文件浏览」（不落连接簿也能浏览）；
 - **操作**：目录浏览（路径框回车跳转、`..（上级目录）`、单击文件即下载）、
@@ -233,7 +242,7 @@ tmux server（专用 socket `dsh-tty`，与用户自己的 tmux 完全隔离）
 - **降级**：本机/远程未安装 tmux 时，持久 spawn 自动落回普通会话，终端里
   回一行灰字提示；不装任何东西也能正常用，只是无持久化。
 
-## SSH 连接（方案 C）
+## SSH 连接
 
 0.2.0 起标签栏「+」变为一键菜单，除本地终端外还能开 **SSH 标签页**：宿主
 半体用 `ssh2` 原生建立连接并打开 shell channel（不经过本地 ssh 进程，也
@@ -399,9 +408,59 @@ ctx.inject(['ttyTerminal'], (c) => {
   `mount` 也会把连接拉起来（创建帧先排队，`onopen` 后补发）。
 - 嵌入终端没有 tty 面板头部的搜索/清屏/复制工具栏，Ctrl+F 交还浏览器。
 
+### 面板内挂载位（客户端服务 `ttyPanel`，0.16.0）
+
+> tty 自己的 SFTP 文件浏览也走这条通道（0.16.0）：挂载位空着时挂在右侧，
+> 被别的面板占用时退回对话框。
+
+`mount` 解决的是「消费方给宿主，tty 往里塞终端」；`ttyPanel` 是它的**镜像**——tty 在
+终端面板里给消费方一块位置，让消费方把自己的界面挂进来。典型场景：dsh-docker 从 SSH
+连接栏点「容器」，容器面板挂在终端**右侧**，终端继续可见、可点、可输入，而不是被整屏
+弹窗盖住（0.15 之前那正是用户的痛点）。
+
+```js
+ctx.inject(['ttyPanel'], (c) => {
+  // 面板没开（或 tty < 0.16）时走自己的弹窗
+  if (Number(c.ttyPanel.version ?? 0) < 1 || c.ttyPanel.isOpen() !== true) { /* fallback */ }
+  const pane = c.ttyPanel.mountPane({
+    title: 'Docker 容器',  // 面板标题
+    hint: 'prod-web-01',   // 标题右侧灰字（可选）
+    side: 'right',         // 'right'（默认，竖向列表 / 列表+详情）| 'bottom'（横向宽表）
+    size: 520,             // 初始尺寸 px：right = 宽度（默认 460）、bottom = 高度（默认 320）
+    min: 360,              // 最小尺寸 px（可选，默认 280 / 160）
+    onClose: () => { /* tty 收掉面板时回调：在这里 unmount 自己的 React root */ },
+  })
+  createRoot(pane.element).render(<MyPanel />)
+  // 自己收起时：pane.dispose()
+})
+```
+
+| 成员 | 说明 |
+| --- | --- |
+| `isOpen()` | 终端面板是否正开着（最小化不算）。消费方据此决定「挂进来」还是「走自己的弹窗」 |
+| `mountPane(options)` | 在面板右侧 / 下方挂一块位置并返回 handle；**同时只挂一个**，后来的 `mountPane` 会先收掉前一个（并回调它的 `onClose`）。`side:'bottom'` 时占满宽度、由高度定尺寸（拖上边缘），折叠成一条标题栏 |
+| `handle.element` | 消费方 render 的宿主（flex 纵向、已 `overflow:hidden`，撑满正文区） |
+| `handle.setTitle(text)` / `setHint(text)` | 改标题 / 灰字 |
+| `handle.expand() / collapse() / toggle() / isCollapsed()` | 折叠成 32px 窄条（竖排标题 + 展开/关闭按钮），终端立刻拿回宽度 |
+| `handle.dispose()` | 消费方主动收起（幂等，不会再触发 `onClose`） |
+
+- **生命周期**：侧栏的 DOM 长在终端弹窗里——最小化 / 恢复跟着面板走，消费方不用管；
+  面板被关闭（✕ / 宿主卸载）时 tty **先调 `onClose`**（消费方在这里 unmount），随后才摘 DOM。
+- **拖尺寸**：右侧 pane 拖左边缘、下方 pane 拖上边缘（上限 = 面板卡片长边的 72%，
+  给终端留位置），尺寸在同一次页面会话内按方向分别记住。终端区的尺寸变化由既有
+  ResizeObserver 接住，自动 refit 并把新行列数同步给 PTY。
+- **视口锚定**：pane 开合 / 拖尺寸会改变终端区高度，xterm 自己挪视口会让内容
+  「被往上顶」。refit 时按用户当时的意图锚定——本来贴着底部（在看最新输出）就
+  继续贴底，翻在历史里就锁住原来那几行，不会跳走。
+- **方向怎么挑**：竖向列表 / 列表+详情（如容器面板）用 `right`；横向宽表（如 SFTP
+  文件列表、本地↔远程双栏）用 `bottom` —— 全宽摆得下更多列，也不挤终端宽度。
+- 标题栏（标题 / 折叠 / ✕）由 tty 提供，消费方只管自己的正文；`onClose` 抛错只记
+  `console.warn`，不影响面板关闭。
+
 > 契约版本：`ttyConnbar.version === 1`、`ttyTerminal.version === 2`（1 = 只有 `open`，
-> 2 = 增加 `mount`）。消费方**按版本号判断能力**，不要用 `typeof fn === 'function'`
-> 之外的假设；老版本 tty 上 `inject` 依然会触发，但没有 `mount` 字段。
+> 2 = 增加 `mount`）、`ttyPanel.version === 1`。消费方**按版本号判断能力**，不要用
+> `typeof fn === 'function'` 之外的假设；老版本 tty 上 `inject` 依然会触发，但没有
+> 对应字段。
 
 ## 帧协议（/api/dsh-tty/ws，JSON 文本帧；v3 = 单连接多会话 + 断线重连）
 
@@ -555,7 +614,7 @@ node scripts/preview.mjs --theme=light   # 浅色主题
   └─ 帧协议：spawn|ssh / input / resize / kill / sessions / attach
      ↔ ready/data/exit/error/sessions + 背压
 
-SSH 路径 (src/ssh.ts，方案 C)
+SSH 路径 (src/ssh.ts)
   └─ {t:'ssh'} → spawnSsh：ssh2 Client 原生连接（agent / key / password，
      password·passphrase 支持 env:VAR 取密；host key 经 HostKeyStore
      TOFU 钉扎），开 shell channel 包装成与 PTY 同形状的 TermHandle