@hyzyn/dsh-tty

中文 | English

DSH 侧边栏「终端」面板：xterm.js + 真实 PTY 的完整终端，本地与 SSH 一视同仁，长任务可断线保活。

特性

• 真 PTY + WebGL 渲染：node-pty 真实 PTY，vim / htop / dev server 等 TUI 均可运行；多标签页。
• 可选 tmux 会话持久化：宿主重启 / 网络抖动后重开即恢复现场；docker exec 这类「命令标签」自动重开。
• ssh2 原生连接：agent forwarding + 主机指纹 TOFU 钉扎，连接簿统一管理；另有 SFTP 上传下载与 端口转发（-L / -R，断线自动重连）。
• agent 侧按「命令」粒度取数：shell 集成（OSC 133/7）让 tty_capture{last} / tty_expect 拿到「上一条命令」的输出与退出码，而不是抓屏猜；tty_list 直接报有没有命令在跑（running 三态），tty_run 一条命令一次调用拿回输出与退出码。
• 对其它插件开放客户端服务：ttyConnbar（连接栏动作）、ttyTerminal（就地开终端）与 ttyPanel（面板内挂载位）；dsh-docker 的「容器 / 终端」按钮即走这些扩展点。
• AI 辅助「失败即解释」（0.24.0，默认关）：命令非零退出时右下角浮出徽标，点它才把那条命令的输出尾部（清洗 / 截断 / 密钥遮盖后）连同当前屏幕发给模型，换回「发生了什么 / 下一步」；模型给的命令只填入命令行、永不替你回车。见 AI 辅助。

安装

dsh plugin --profile web add @hyzyn/dsh-tty    # npm 安装（发布后）
dsh plugin --profile web add link:$(pwd)/packages/tty   # 仓库开发调试

装完重启 dsh web，侧边栏出现「终端」入口，点击打开面板； 「终端面板」卡片可改配置（保存即热生效，无需重启）。

使用

• 打开面板自动创建第一个终端（默认 $SHELL，macOS 上通常是 zsh）；
• 多标签页：标签栏「+」是菜单（本地终端 / SSH 连接簿（条目带 ✎ 编辑）/ SSH 连接…）， 标签 ✕ 关闭，双击标签可重命名（随标签持久化）；每个标签独立会话（本地 PTY 或 SSH channel）； 标签栏放不下时横向滚动（两端渐隐），并在右缘出现**「⋯」标签列表**：只列被挤出视野的标签 （状态点 + 目标名），点一行切换、行内 ✕ 关闭（列表不关，可连着关）；
• 批量关标签：右键任一标签弹出菜单（关闭此标签 / 关闭其他 / 关闭左侧 / 关闭右侧 / 清理已退出的标签；没有对象的行不出现），中键直接关闭指向的标签；「⋯」里挂着同一份批量行。 标签 ≥ 2 个时「⋯」恒在。会结束 ≥2 条活会话的动作先弹确认（写明几条、其中几条是 AI 开的）， 只关一条活会话与点它自己的 ✕ 等价、不弹；
• 标签「对 AI 不可见」（默认关闭）：右键菜单多一项——藏起来后 tty_list 与每轮 systemPrompt 的会话块里都没有它（只报「另有 N 条被用户设为对 agent 不可见」），按 sid 的读写工具一律被拒； 你自己的面板里照旧完全可用。AI 自己开的标签不给这一项；
• 工作目录跟随当前 DSH 会话：新标签默认在当前会话工作目录打开（宿主配置 cwd 作兜底）；
• 支持 vim / htop / less 等 TUI（TERM 已注入为 xterm-256color）；
• 面板大小变化自动 resize（xterm fit → PTY 原生 resize）；非活动标签不跟手，保留自己最后一次 有效尺寸（D79：容器不可见或探测结果退化时，尺寸帧一律不发）；
• Ctrl+F 终端内搜索（Enter 下一个 / Shift+Enter 上一个 / Esc 只关搜索框），输出中的链接可点击； 复制 / 粘贴用终端自己的快捷键（有选中时 Cmd+C / Ctrl+Shift+C、Cmd+V / Ctrl+V）；
• 断线自动重连：刷新页面、网络抖动等异常断开后，会话在宿主保活 reconnectGraceSec（默认 120 秒）， 客户端指数退避自动重连（封顶 5s），按 sid attach 回原会话并回放断线期间的输出；页面刷新后从 sessionStorage 恢复标签列表（宿主侧已结束的会话自动丢弃）；
• WebGL 渲染器：高吞吐输出（build 日志）性能质变；上下文丢失（多标签超出浏览器配额等）时 自动回退 DOM 渲染器；
• 最小化：点弹窗外空白处、按 Esc 或标题栏「—」收起面板——会话与输出缓冲保持存活，侧边栏入口 显示「运行中 / 总数」徽标与状态点；悬浮条 ✕ / 标题栏 ✕ 才真正关闭并结束全部会话；
• 关面板会先问一句：还有活会话时，点 ✕ 先弹确认（写明结束几条、其中几条是 AI 开的），并把 「最小化」放进同一行按钮；只剩已退出的标签或空面板时直接关（判据是「会损失什么」，不是「开了几个标签」）；
• 已退出的会话不再遮住输出：退出态是终端区顶部一条提示条（「已退出 code=…」/「AI 已结束这个会话」
  • 最多一颗动作按钮），输出照常可读、可滚、可选中复制；错误态与「重连中」的遮罩保留（它们解释 「为什么没有输出」）；
• 「⋯」里的「清理已退出的标签（N）」：一键收掉所有已退出的标签，并让宿主立刻释放它们的只读保留；
• AI 开的标签跟会话走：AI 用 tty_close（或 tty_run 默认收尾）释放会话后，对应标签跟着关； 你正看着的那一个先留一台阶（提示条 +「收起」）。仍在只读保留里的会话标签留着，由上面的一键清理收；
• 标题栏 ✕ 关闭面板并结束全部会话（PTY 树级清理；tmux 持久标签同时 kill-session）；会话退出后 从顶部提示条重开（本地标签按原规格新开、持久标签接回 tmux、命令标签重跑一次）；
• 并发上限默认 4（maxSessions，1~16）。

Windows 宿主（best-effort）

默认 shell 取 %COMSPEC%（系统保证存在）；要 PowerShell 就在设置卡片把「Shell 路径」填成 powershell.exe / pwsh.exe 的完整路径。Windows 上不做 POSIX 包装层：直接 [shell]；PowerShell 家族补 -NoLogo（去版权横幅）、不补 -NoProfile（用户的 profile 正是别名与函数的来源）； TERM / COLORTERM 对 ConPTY 没有意义，也不再注入。

• 「跑一条命令」的标签（docker exec、agent 起的命令标签）走 cmd /c 或 PowerShell -Command。 PowerShell 的 -Command 会把「末条命令非零」塌成进程退出码 1（cmd /c exit 5 → 1，两版一致）， 要拿到具体码值就让命令自己 exit 5（POSIX 侧 sh -c 不会这样）。
• 输入行尾归一化（D74）：conhost 的 Enter 是 CR，裸 LF 只把光标下移一格、不提交命令行。 win32 本地会话把裸 LF 补成 CRLF（已是 CRLF 的不重复补；非 Windows 与 SSH 会话原样透传）。
• shell 集成（OSC 133/7）按家族分：PowerShell 家族支持（powershell.exe / pwsh.exe， -File 稳定桩挂 prompt + PSConsoleHostReadLine 钩子）——拿到 tty_list.cwd、退出码、running 三态与命令粒度的 tty_expect；cmd 不支持（没有命令边界钩子），设置卡片把开关置灰并指向 「把 Shell 路径换成 PowerShell」。&& / || 只有 PowerShell 7 认，5.1 上是解析错误（一条命令都不跑）。
  • 退出码口径：PowerShell 家族的解析错误命令一条都没跑，而 D 标记报 0——不能只看退出码判成功， 报错文本在输出里。
  • 桩的边界：靠 -ExecutionPolicy Bypass（进程级）载入，组策略锁死执行策略时装不进来、 标签照开而集成静默失效（与「用户关了 PSReadLine」同一种降级）；该参数也会写进 $Env:PSExecutionPolicyPreference，从该会话再起的 PowerShell 会继承它。包装 prompt 还会让用户 原 prompt 读到的 $? 变成我们那几次写入的成败（恒真），依赖 $? 的失败提示会失效。
• 不支持的两项（宿主侧自动关掉，设置卡片里写明原因）：tmux 持久化（Windows 上没有 tmux； SSH 到 Linux 主机仍可用）与服务器状态条（本地只有 CPU / 内存 / 在线时长，磁盘 / TCP / 网速 / 温度 显示「无」；远端 Windows 主机走 PowerShell 那一跳）。

完整边界、0.18.1 的修复范围与 windows-smoke 的 W6–W8 覆盖见 ROADMAP § 已完成。

agent 工具

插件向 agent 注入二十个工具（操作实时显示在用户终端里；每次调用受会话权限档位约束，见下节）：

零配置时只注册 10 个（0.33.0 起按配置条件注册）：sftp_* 七个要有 SSH 连接簿条目、tunnel_* 三个要有隧道。下表是配齐之后的完整面；受限档位下还会进一步裁掉写 / exec 类（见下节）。

工具	作用
tty_list	列出终端会话（sid / kind（local|ssh）/ target / pid / cwd 实时跟随 cd / 活动时间；tmux 持久会话带 persist；agent 自己开的带 owner: 'agent'）。含已退出但仍在只读保留期的会话（exited:true + 退出码/信号）；running 三态 + 未知成因（true = 在跑，别往里发命令；false = 命令已结束；省略 = 无法判断，不是「没在跑」——成因在 runningUnknown 里分开：ssh（远端 shell 不受本插件控制，永久未知）/ tmux-attach（tmux 接回时收到的是屏重绘、不带 OSC 标启，跑完第一条命令即恢复）/ no-integration（fish·csh·cmd 等不受支持的 shell，或「shell 集成」被关掉），三者下一步动作不同，别把它们当成一句话）；同源 lastExitCode / lastExitAt 是上一条已完成命令的退出码与结束时刻
tty_books	列出连接簿条目（name / host / port / username / 认证方式 / 是否 tmux 持久 / 是否经跳板机或有代理命令），不含任何凭据。sftp_* 的 book、隧道的 bookName、docker 目标的「连接簿」下拉都按 name 引用；book 也接受 host 或 user@host（唯一匹配才解析，有歧义会列候选而不猜）。名字记不准时先调它，不要去猜、更不要读配置文件
tty_open	自己开一个终端会话：本地 shell，或 command 直接跑一条命令（dev server / watch；按宿主 shell 的语法整段执行，Windows 上按 cmd / PowerShell 自己的语法；不受「命令标签单行 ≤2000」约束，D78），persistName 可要 tmux 持久化；当前 shell 与语法每轮都写在 systemPrompt 的终端一行里。会话出现在用户的终端面板里（普通标签、可见可接管），不做隐形会话
tty_close	关掉由 tty_open 开的会话。只允许关 agent 自己开的（用户开的标签会被拒绝，agent 不越权结束用户正在用的终端）。对已退出但仍只读保留着的会话同样可用——那是它的释放入口
tty_run	一次性命令：开会话跑 command，等它结束，直接返回尾部输出 + 退出码（把 open → 等 → capture → close 压成一次调用）。默认跑完即关，keep:true 留在只读保留态；到 timeoutSec（1~600，默认 120）未结束返回 running:true 且不杀会话；调用方取消（exec.signal）立刻返回 cancelled:true——取消的是这次调用，不是那条命令。需要用户看得见这条命令、或它必须跑在终端会话里时用它，纯非交互命令用 bash 更直接
tty_stats	读会话所在机器的实时指标：CPU / 内存 / 磁盘 / TCP / 网速 / 温度 / 在线时长 / 1 分钟负载 / 交换分区 / SSH 连接往返。本地会话取宿主机，SSH 会话取远程主机（另开非 PTY 通道，不影响终端）
tty_capture	读近期输出（尾部 N 行，默认清洗 ANSI，raw:true 取原始流）；last:true 只返回上一条已完成命令的输出 + 退出码（shell 集成标记）；命令在途时返回 inProgress:true 且不带旧结果。命令型会话没有「上一条命令」，last:true 会明确报错并指向 lines（D87）
tty_screen	读当前可见屏幕的渲染结果（xterm-headless 虚拟屏，纯文本）——能读懂 vim / htop / 菜单等 TUI。正文保尾最多 32KB，超出返回 truncated:true
tty_expect	用正则等一个就绪信号。先回溯还没被读过的输出（含「上一条命令」的完整输出，命令瞬间跑完也不会白等），再等后续输出；命中返回 matched:true + matchedFrom（live / last / buffered）。超时不抛错（matched:false + 尾部输出，且不消耗未读区），命令提前结束也带退出码早停；刚发进去的命令回显不算命中（OSC 133 的 A..B 边界，无标记环境靠发送记录剔除；只命中回显时带 echoOnly:true）；同一会话在途调用最多 5 个，累积窗口只留尾部 64KB；调用方取消立刻结算为 cancelled:true
tty_send	向会话发送文本与/或按键。控制键与方向键用具名 keys（["C-c"]、["Down","Down","Enter"]，白名单查表；名字不认得就报错，绝不静默当字面量发），不要自己在 data 里拼转义序列（"\x1b[B" 会被当普通字符打印）；data 与 keys 至少给一个，先 data 再按序 keys。命令以 \n 结尾即可（Windows 本地会话归一成 CRLF，D74）。对已退出的会话明确报错
sftp_list	列出 SSH 远程目录内容（名称/类型/大小/修改时间，目录在前）；book 为连接簿条目名，path 缺省为登录 home；默认最多 500 项（超限 truncated:true），isSymlink 区分软链
sftp_read	读取远程文本文件（默认 ≤256KB 可调至 1MB，超出截断）；offset 可从指定字节分页，非法 maxBytes 直接报错，二进制判定 = NUL + 非法 UTF-8 占比双判据
sftp_write	写远程文本文件（默认覆盖，append:true 追加；单次 ≤1MB）
sftp_mkdir	创建远程目录；parents:true 逐级补齐缺失父目录（等效 mkdir -p，已存在目录幂等跳过）
sftp_rename	重命名/移动远程文件或目录（to 与 from 不同目录即移动；不覆盖已存在的目标）
sftp_remove	删除远程文件/目录；目录默认 rmdir（非空明确报错），recursive:true 整树删除（不可恢复）；拒绝 /、~、含 ./.. 段的路径
sftp_tree	递归列举远程目录结构（深度优先、目录优先；maxDepth 18 / maxEntries 12000 限流，超限 truncated:true；symlink 不跟随防环）
tunnel_list	列出端口转发隧道及实时状态（活跃/连接中/错误/停止、规则、连接数）；fatal:true = 人工介入级故障（本地监听失败 / 连接簿缺失），不会自动重试
tunnel_start / tunnel_stop	启停一条隧道（name 来自 tunnel_list）。会改写配置——与在设置卡片里勾选/取消那个「启用」是同一件事（写回 settings → 热应用 → reconcile）。返回值通常是 connecting（拨号异步），最终结论稍后 tunnel_list

会话权限档位闸（tier gate）

工具按风险分三类，每次调用按会话的权限档位（仅可查看 / 工作区内修改 / 完全权限 / Auto review） 决定放行、询问还是拒绝——档位是用户在会话里切的，切完下一个调用立即按新档走：

类	工具	受限档（仅可查看 / 工作区内修改）下的行为
读	tty_list tty_books tty_capture tty_screen tty_expect tty_stats tunnel_list sftp_list sftp_read sftp_tree tty_close	全档放行
写（有界变更）	sftp_write sftp_mkdir sftp_rename sftp_remove tunnel_stop	弹授权询问（人允许这一次才执行）；无人值守（审批策略 never）确定性拒绝
执行（无界命令面）	tty_open tty_run tty_send tunnel_start	同上——这些工具能在本机或远程 shell 里跑任意命令、开监听端口

完全权限档零询问；Auto review 档插件不叠加询问（宿主的模型预审已在逐调用审查）。宿主未组合 sandboxPolicy / approval 服务时不闸，启动日志打一行 tier-gate: services absent (…), per-call gate disabled。机制（决策矩阵 / 与 allowProxyCommand 的 两层关系）见 docs/permission-tier-plan.md。

只读档的会话连工具面也一并裁掉（宿主的 tools.restrict）：档位是「仅可查看」时， 插件在该会话的 agent 作用域上把「写」「执行」两类从工具表里摘掉——agent 看到的 tty 工具从 20 个降到 11 个。安全边界仍是上面那张逐调用的矩阵：裁剪只是提前拿走按当前档位不可能成功的工具； 名单漏了谁、或工具在会话建立之后才注册，都只影响模型看不看得见，不构成越权。完全权限 / Auto review / 工作区内修改三档都不裁——工作区内修改档的写与执行是逐次 ask（人一点就能执行），工具能成功就不该 藏（2026-11-05 修正：旧判据把默认档整批藏掉，用户要自动化只能切零询问的完全权限档）。 会话中途切档会重算（升档放回、降到只读档摘掉，都在下一次模型请求之前生效）。

提示词不点名可能被裁掉的工具（D103）：每轮 systemPrompt 的终端块只说「按 sid 操作」+「实际可用的 工具以你的工具表为准」，并给出见不到时的出路（只读档请用户切「工作区内修改」档——那档可用但每次要 确认；或改用受沙箱约束的 bash）；它不再硬写「可用 tty_send 操作、用 tty_open 开关」——那句话与 工具表不同源，模型会照着去调一个不存在的工具。守卫：test/tty-list-running.test.ts 的两条反例用例。

典型 agent 流程：跑完就算完的命令用 tty_run 一次拿回输出 + 退出码；需要长驻的会话用 tty_open → tty_send 启动 → tty_expect 等就绪 → tty_capture{last:true} 拿单条命令结果 → tty_close。 systemPrompt 里另注册了动态 context，每轮自动携带活跃终端快照（sid / kind / cwd / owner，以及 [运行中] 标记），无需先调 tty_list。

agent 开的会话边界：tty_open 开出来的是面板里的普通标签（带「agent」标识），用户看得见、 接管得了、关得掉——刻意不做隐形会话。它从出生起没有客户端绑定，因此不被孤儿回收器回收；关闭 入口是 tty_close 或用户在面板里关标签。反过来说，agent 也关不掉用户开的标签。

进程退出后的「只读保留」（D77）

会话的进程退出不再等于会话消失——它转成只读保留态，默认保留到显式关闭 （EXITED_RETAIN_MS = ∞；宿主 / 插件重启即清空），期间：

• 读得到：tty_capture、tty_screen、tty_list（带 exited:true + exitCode/signal）照常可用； tty_expect 不再空等，按现存输出立刻结算并带 exited:true；
• 写不进去：tty_send 明确报错，tty_stats 不再作用于它（回 available:false），面板的 resize 也不再有意义；
• 不再接回终端：attach 明确拒绝（没有活着的 PTY，面板也不会为它建标签）；
• 谁释放它：agent 的 tty_close（仅限自己开的）、用户在面板里关那个标签、或宿主 / 插件重启。 并发上限只数活着的会话（保留态不占名额，客户端「+」的上限预检同口径）；保留态最多 MAX_EXITED_SESSIONS（16）条，超出按最旧淘汰（淘汰时记日志）。

保留不按时间淘汰：内存与句柄本来就不由时间决定，而时间上界对使用者是第二重惊喜（「命令跑完 → 下一轮读结果」之间隔多久都有可能）。想要时间上界就把 EXITED_RETAIN_MS 改成毫秒数 / 0，reapExited 通路还在。完整修法与回归见 DEFECTS D77。

shell 集成（OSC 133/7，0.4.0）

POSIX 上经既有的 -c 包装层按 shell 类型注入钩子，Windows 上走 PowerShell 的 -File 稳定桩（都对 用户透明，不改 rc）：

• zsh：ZDOTDIR 指向临时桩目录（VS Code 同款方案），桩文件先 source 用户原 rc 再追加 precmd / preexec 钩子；
• bash：--rcfile 桩（先 source ~/.bashrc）；命令开始标记按版本二选一：bash ≥ 4.4 走 PS0， bash < 4.4（macOS 自带 3.2）用 DEBUG trap 兜底（按 $BASH_COMMAND 过滤 PROMPT_COMMAND 自身的 fire）。副作用：循环体等复合命令的内部命令会多发 B 标记，只影响 tty_capture{last} 的截取起点；
• PowerShell（Windows）：-File 稳定桩（纯 ASCII，5.1 按 ANSI 代码页读 .ps1）包装 prompt 与 PSConsoleHostReadLine，用户 profile 照常生效。退出码口径见「Windows 宿主」一节；
• 标记语义：133;A prompt 开始 / 133;B 命令开始 / 133;D;<exit> 命令结束带退出码 / OSC 7 file://… cwd 上报（tty_list.cwd 跟随 cd，SSH 会话上报远程路径）；
• 其他 shell（含 Windows 的 cmd）静默关闭；配置 shellIntegration: false 可整体关掉（逃生门）。

回溯匹配与已读水位线（D72）：tty_expect 先回看还没被读过的输出，回看起点抬到「未读区内 最后一个 B 标记之后」——回显落在 A 与 B 之间，所以回显里的字样不会被当成命中（刻意不做文本 比对：折行 / ANSI / 多行粘贴都会打碎它）。没有 B 标记的环境（未开集成 / Windows cmd / 远端

• ZDOTDIR 的三层解析（0.38.0）：包装层与 tmux 内层启动器共用同一段判据——父会话传下的 DSH_TTY_ORIG_ZDOTDIR → 继承的 ZDOTDIR（必须是「不是桩目录」的值）→ $HOME。为什么要有 第二层那个排除：在 dsh 终端面板里再起一个 dsh（嵌套）时，宿主进程环境里的 ZDOTDIR 就是桩目录， 直接用会让桩 source 自己 → zsh 递归（job table full or recursion limit exceeded）→ 整条本地 会话没有 OSC 133 标记。桩文件里还有一道自愈兜底（ORIG 为空/等于桩目录就退回 $HOME）。 未装集成 / 用户关了 PSReadLine）改用另一条判据剔除回显（D75 / D101）：把最近 tty_send 提交过的 命令行从候选文本里削掉再试，只有「削掉后不再命中」才算纯回显；超时且只命中过回显时带 echoOnly:true。

已读水位线：tty_capture / tty_expect 返回的内容算「已读」，之后的 tty_expect 不再回扫； tty_screen 刻意不推进，tty_send 只初始化不推进，超时也不消耗未读区（换个 pattern 还能 回溯到同一段）。要回看更早的内容用 tty_capture。

SSH 会话同表调度：tty_list 里 kind: 'ssh' 的条目按 target（user@host[:port]）识别， tty_capture / tty_expect / tty_send 用法与本地会话完全一致。

凭据存储（连接密码不必只落明文）

连接对话框的「密码」下面有一行 凭据存储：勾上「保存时存入凭据存储」，密码就写进官方凭据存储， 字段里只留 env:NAME 引用（值在 ~/.dsh/.credentials.yaml，不进环境、不回传浏览器）。默认勾选 （宿主提供了 remote.credentials 时）；宿主没有这个服务时置灰禁用，并说明只能明文保存。

• 跟着保存走，不额外点一次：由「保存修改」/「连接（并保存）」执行写入，没有悬空引用； 没勾「保存到连接簿」时不会动存储（否则只会留下孤儿）。设置卡片的行内编辑是同一行、同一个 默认值，只是提交入口叫「应用」。
• 默认勾选的两个副作用：① 编辑一条明文密码的老连接、只改别的字段再保存，密码也会被搬进 存储（不想搬就取消勾选）；② 存储拒绝写入时保存会被中止并显示官方原文错误，而不是偷偷改成 明文落盘。
• 名字规则：DSH_TTY_<用户名>_<主机>[_<端口>]_<字段>，端口留空或 22 时省略；字段 = PASSWORD / PASSPHRASE。例 operator@192.0.2.10:22 → DSH_TTY_OPERATOR_192_0_2_10_PASSWORD。 按资源身份派生、不带哈希（host 与 username 本来就是 ASCII 标识符），连接名不参与键——改连接名 不会换键。空主机或空用户名拒绝存入。
• 解析路径：连接 / 试连 / SFTP / 端口转发都走同一个 buildConnectConfig，其中的 env:NAME 经 官方凭据 provider 解析（每操作重解析，改完下一个操作即生效）；provider 没有该引用、或宿主 没有该服务时才退回 process.env。为什么必须走 provider：凭据存储里的值永远不会被 materialize 进环境，只读 process.env 等于「存进去的密码连接时读不到」。
• 可见性：对话框的引用选择器会列出存储里已有的名字——宿主侧 /api/dsh-tty/credential-refs 只读 refs: 的键名回来（只要名字，值永远不出宿主）。这是有意偏离官方「引用不可枚举」设计的 一处（引用名会进浏览器，值不会）。
• 保守的边界：~/.credentials.yaml 是 0600 的普通文件，没有主密码、没有 OS keychain——它挡的是 别的 OS 用户，挡不住以你身份运行的进程与 agent；且它机器本地，换机器要重存。能用密钥 / agent 就别存密码（本插件两者都支持）。

端口转发（0.5.0）

「终端面板」卡片的「端口转发」区块维护隧道；每条隧道引用一条连接簿条目（主机与认证随之），两个方向：

• 本地转发（-L）：本地 127.0.0.1:localPort 监听 → 经 SSH 在服务端侧连到 remoteHost:remotePort （最高频用法：localPort=5432 → db.internal:5432）；
• 远程转发（-R）：服务端监听 remoteHost:remotePort（缺省 127.0.0.1）→ 入站连接拨回本地 localTargetHost:localTargetPort；
• 宿主自持生命周期：隧道与终端标签互相独立（各有各的 SSH 连接），面板关了隧道照跑；SSH 断线 自动指数退避重连（1s→15s 封顶），remote 方向重连后自动重新 forwardIn。例外：本地监听失败 / 连接簿条目缺失是人工介入级故障——状态停在 error 且 fatal:true、不会自动重试；
• 多 profile 同跑要错开 localPort：端口转发是机器级资源，而配置按 profile 各存一份；两个 profile 抢同一端口 → 后起的那个 EADDRINUSE，报错会点明「可能是另一个 DSH profile 的宿主进程」；
• 保存时探测端口（0.26.0）：保存时宿主先探一遍本地端口（独占探测，成功即释放），把「两条隧道 用同一 localPort」与「端口被本进程之外的东西占着」提前到保存那一拍说清楚。探测只警告、不拦保存 （卡片以黄色警告档显示；整表提交时硬拒会把用户锁死在「任何一项都存不下去」）。本进程自己正占着的 端口被豁免；停用的那条也算重名冲突；remote 方向的 remotePort 在服务端监听，不参与本机探测。
• 状态徽标：卡片展开期间 2s 轮询实时状态（活跃绿/连接中蓝/错误红/停止灰 + 最近错误）；「+」菜单的 连接簿条目显示 ⇄N 徽标；agent 用 tunnel_list 查询；
• 连接栏入口：该连接有启用隧道时常驻「隧道 N」按钮；没有隧道时收进「⋯ 更多」（补上发现 路径、又不占常驻宽度）。隧道必须引用连接簿条目，所以只有条目式连接有这个入口；
• 表单布局：方向用分段控件，两端按「主机:端口」成对呈现，中间用箭头示明数据流向 （切到 -R 时箭头翻转）。每个方向恰好有一端是固定的（-L 左端固定 127.0.0.1，-R 右端固定 127.0.0.1），固定端渲染成静态文本而不是输入框；
• 编辑：每行「编辑」回填到下方表单，按钮切成「保存修改 / 取消」；保存按原始名字定位替换 （隧道名由 <连接簿条目>-L<本地端口> 派生，「改端口」等于换名字），enabled 保留原值；撞名明确报错；
• 本地监听失败是粘性的：状态稳定停在红色 error 并保留原因，不会被 SSH 侧的重试刷成「连接中」； 恢复办法是改端口或腾出端口；
• TOFU 与终端会话共享同一份 hostKeys 钉扎；端口不占 maxSessions 名额。

SFTP 文件传输（0.7.0，0.8.0/0.9.0 增强）

不动终端、不占会话名额，直接对 SSH 连接做远程文件操作（ssh2 的 sftp subsystem，宿主半体 src/sftp.ts）：

• 落点（0.16.0）：终端面板开着且本标签的挂载位空着时，文件浏览挂在终端下方（路径栏 / 列表 / 传输进度占满整宽），终端继续可见可用；高度可拖、可折叠成一条标题栏。挂载位已被别的面板 占用、或面板没开时，退回原来的居中对话框（不挤掉别人的面板）；
• 跟着标签切（0.19.0）：文件浏览归属打开它的那个标签（连的是那台主机）：切到别的标签时整块 收起（在途传输照跑，切回来还在原地），标签关掉时一并收掉。所有入口用同一条规则；
• 入口：① 标签栏「+」菜单的连接簿条目带 📂；② SSH 连接对话框填好主机/认证后点「文件浏览」； ③ SSH 标签的连接栏「SFTP」按钮（归属该标签）；
• 操作：目录浏览（路径框回车跳转、..（上级目录）、单击文件即下载）、上传（多选文件，XHR 流式 + 进度；0.8.0 起支持拖拽，文件夹经 webkitGetAsEntry 递归展开，目录用 mkdir parents 逐级补齐）、下载（POST → Blob → <a download>）、新建目录、重命名（行内编辑器）、 删除（🗑 二次确认，目录带 recursive 整目录删除）；
• 传输进度与取消：底部状态行右侧是细进度条 + 百分比（下载按 content-length 实时算，无长度时 降级为已传字节文本）；✕ 取消传输——上传中断在途 XHR、下载用 AbortController、双栏直传向宿主 cancel，取消后半截文件自动删除，状态行走「已取消」；关闭文件浏览也会收掉在途传输；
• 连接管理：懒连接池——首次操作才建 SSH 连接，空闲 120 秒回收，断开后下次操作自动重连；连接簿 条目每次（重）连接时实时解析（改密码后自动用新凭证）；TOFU 与终端会话/隧道共用 hostKeys；
• 断点续传（0.25.0，面板下载）：下载中途断线时自动从已收字节接着下——宿主侧 /sftp/download 接上 offset（>0 回 206 + content-range，content-length 报剩余长度；offset ≥ 文件大小 回 416）。判定规则在 client-src/download-resume.js（planResume）：用户点 ✕ 一律不续、零进度 不续、重试封顶（默认 3 次），续传期间进度条不回零。目录级直传仍是整份重传；
• 双栏拖拽上传与隐藏文件（0.25.0）：拖到右侧远程栏即上传到该栏当前目录，拖到本机栏明确 提示「没有可执行的动作」（判定在 client-src/sftp-view.js 的 planDrop）。每栏工具行有「隐藏文件」 开关（偏好记在 localStorage）；过滤只在渲染层——宿主 list 与 sftp_list 始终返回全部条目；
• 传输通道：POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|upload（全部 loopback 围栏）， download 另接受可选的 offset。连接规格经 JSON 体或 upload 的 x-dsh-sftp-meta 头（base64url） 携带——凭证不进 URL/查询串；上传下载均为流式 pipe，不整文件进内存；
• agent 工具：sftp_list / sftp_read / sftp_write / sftp_mkdir / sftp_rename / sftp_remove / sftp_tree——只收 book 连接簿条目名，不接受内联凭证；
• 双栏风格（0.9.0 可选，配置 sftpStyle）：左本机 / 右远程两栏，本机侧走 /api/dsh-tty/local-fs 路由；行内 ⇨ / ⇦ 把条目对拷到对面栏的当前目录（/api/dsh-tty/local-fs/transfer 由宿主服务端 流式直传，目录递归、同名覆盖，字节不经过浏览器）。设置卡片切换，重新打开 SFTP 生效。

会话持久化（tmux，0.10.0）

默认安全模型不变：会话随宿主生死（内核级 PTY 清理）。需要「活得比宿主久」的工作（dev server、build、 训练任务），开持久终端——会话委托给 tmux server（专用 socket，与用户自己的 tmux 完全隔离）， 断线保活、甚至宿主重启后都能接回：

socket 按 profile 区分（0.25.0 起）：tmux -L dsh-tty-<profile>，运行时资产 （<DSH_HOME>/tty/<profile>/）同步分层——多 profile 同跑时各自的持久会话清单互不可见。不带 profile 启动的宿主仍用历史名 dsh-tty，单 profile 用户升级后行为与路径一字不变。

• 入口：设置卡片「会话持久化」选 tmux 即唯一开关——开启后所有新开的标签默认持久化 （「+」菜单的本地终端、连接簿条目、SSH 对话框（「持久会话」默认勾选，单次可取消））；
• 条目级取消（sshHosts[].persist）：连接簿条目上的勾选框存的是取消项——persist: false 的条目不再 tmux 托管，其余条目跟随全局开关（~/.ssh/config 导入的条目不受影响）；
• 机制：spawn/ssh 帧带 persist + 客户端生成、随标签规格保存的稳定 persistName——本地把 -c 包装层换成 exec tmux -L <socket> -f <conf> new-session -A -s dsh-<名>；SSH 则远程 exec tmux -L <socket> -f /dev/null new-session -A -s dsh-<名> 开 pty channel。-A attach-or-create： 宿主重启后重开标签按同名接回原会话；
• 恢复链路：浏览器重连后查 sessions——持久标签 sid 已失效的，客户端自动按原 persistName 重新 spawn；保活回收器超时只杀 PTY（tmux 客户端）、不杀 tmux 会话。同宿主内重连（attach）对 tmux 会话不回放宿主缓冲，改为强制 tmux refresh-client 重画一次（回放会重影）。持久标签规格同时写入 localStorage（sessionStorage 只对同一浏览器标签可见，新窗口原本读不到）；
• 关闭语义：kill 帧（标签 ✕ / 关面板）对 tmux 背书会话先 tmux kill-session 再杀客户端——真正 结束，而不是 detach 留活口；整个页面关闭时默认留存（保活期后可再恢复），配置 endOnPageClose: true 则改为保活期结束时连 tmux 会话一起结束；
• shell 集成兼容：tmux 会吞掉不认识的转义序列——钩子检测 $TMUX 把 OSC 133/7 包进 DCS passthrough 信封（payload 内 ESC 双写），tmux ≥3.3 + allow-passthrough on（宿主自动写入桩 conf）时解包转发。 tty_capture{last} 另有一层修正：钩子在发 D 前先 capture-pane 经 OSC 133;T 随流直送（base64， 最近 200 行），宿主优先采用该快照作为命令输出；
• 运行资产：<DSH_HOME|~/.dsh>/tty/ 下的稳定桩目录（tmux server 比宿主活得久，不能用临时目录）： tmux.conf（status off、真色 overrides、default-command 指向内层启动器）与 inner.sh（按当前配置 exec 内层 shell）。配置热改对新开 pane 生效；tmux.conf 只在 tmux server 首启时读取；
• 降级：本机/远程未安装 tmux 时，持久 spawn 自动落回普通会话，终端里回一行灰字提示。

SSH 连接

标签栏「+」除本地终端外还能开 SSH 标签页：宿主半体用 ssh2 原生建立连接并打开 shell channel （不经过本地 ssh 进程，也不占 node-pty），包装成与本地 PTY 完全一致的会话对象——输入、resize、关闭、 输出缓冲、背压与 agent 工具全部复用同一套调度。

• 「+」菜单三个入口：本地终端 / SSH 连接簿（条目带 📂 文件浏览与 ✎ 编辑）/ SSH 连接…（表单 手填，连接前可勾选保存，底部「文件浏览」可跳过终端直接开 SFTP）；
• 连接簿：「SSH 连接」对话框勾选「保存到连接簿」即存为条目（同名覆盖，名称留空用主机名）；菜单 条目的 ✎ 与设置卡片的编辑走同一套表单（连接 / 认证 / 选项三段 + 凭据存储 + 引用选择器 + 试连 + 文件浏览），支持改名与同名冲突校验。「连接簿名称」一行常显：填了名字就自动勾上保存、 清空就自动取消。对话框是三段式外壳（标题与底部动作行固定，只有中段滚动），低频项（跳板机 / 代理命令 / 主机密钥别名）收在「高级」折叠区；
• 认证方式（auth）三选一：
  • agent（默认）——走 ssh-agent（SSH_AUTH_SOCK），凭证不落盘，最推荐；
  • key——keyPath 私钥文件（~ 开头可省略 home），passphrase 可选；
  • password——密码认证，同时挂 keyboard-interactive（不少服务端只开这个）；
• 密码 / 口令支持 env:VAR：按凭据层解析——官方凭据 provider 优先，它没有才退回宿主进程 环境变量（配合 dsh-env-manager 托管密钥，避免明文写进 settings）；解析不到时报错会同时点到引用名 与「两处都没有」；
• 端口：默认 22，非 22 端口在 target 里显示为 user@host:port；
• 名字可发现（D104）：同一台机器常有三套名字——连接簿条目名（agent 侧 book / 隧道 bookName 真正认的那个）、docker 目标名、以及面板里显示给人看的 user@host。所以 book 除了条目名，也接受 host / host:port / user@host（唯一匹配才解析，同 host 多条目时报候选而不是猜一台），以及 docker 目标名（读 docker 命名空间里的「目标 → 它引用的条目」，只取拓扑、不碰凭据；docker 没装 时自动退化），于是卡片上写的 kb-target 可以直接当 book 传；记不准就用 tty_books 枚举（它把 别名表也列出来），没命中时错误文案会列出可用条目（name — user@host:port，不含凭据）而不是 只说「不存在」；
• 主机密钥别名（hostKeyAlias，0.25.0）：TOFU 默认按连接地址定位，而同一台真实主机常经不同 地址触达（跳板机后的内网 IP、端口转发落在 127.0.0.1:2222），那时「同一把钥匙、不同记录」会让 每次切换地址都判成指纹变更（假 MITM 告警并拒绝连接）。填同一个别名即可共用一条记录；语义与 OpenSSH 的 HostKeyAlias 对齐（只决定指纹记在哪条记录里，不改连接地址）；
• 标签与状态：SSH 标签标题用连接名或 user@host（本地标签是「终端 N」）；状态栏描述当前活动 标签——切标签 / 关标签立刻换成该标签自己的状态（失败原因、退出码都记在标签身上），后台标签自己的 失败不会顶掉活动标签的显示；
• ~/.ssh/config 导入：解析 HostName/User/Port/IdentityFile 生成候选条目（跳过通配符块与无 User 条目，Include 不展开），同名跳过，随「保存」写入。每一种跳过都会当场说明；ProxyJump 会解析成连接条目的跳板机（单跳）一起导入，ProxyJump none / ProxyCommand none 是显式直连照常 导入；ProxyCommand 永不自动导入（只在手动填写 + 打开开关之后才会跑）；
• 代理命令 / ProxyCommand（0.21.0，默认关）：连接簿条目（或对话框）里可填一条本机命令，它的 stdin/stdout 就是到目标的 SSH 传输（典型写法 ssh -W %h:%p bastion）。支持 %h %p %r %n %%； 代入值只允许字母数字与 ._@:[]-，含 shell 特殊字符直接拒绝执行。闸门：设置卡片开关默认关， 提权有两条通道：① 启动环境变量 DSH_TTY_ALLOW_PROXY_COMMAND=1（只认继承来的 process 层，写项目 .env 或 ~/.dsh/env.yml 不算授权）；② 就地提权（免重启）：点开关 → 面板给出「在宿主终端执行」 的命令 → 执行后十秒内解锁。HTTP / 界面不能凭空打开它（给 true 而无授权会被 400 拒绝），但 关掉永远可用。授权是持久的（落在 <DSH home>/dsh-kit/capability-grants.json，0600），宿主 重启后直接生效并在卡片上显示时刻与「撤销宿主授权」。关着时携带代理命令的连接明确失败、不退回 直连。与跳板机同时填时按 OpenSSH 语义跳板机优先。闸门只有一处（本插件 settings）：docker 容器 面板读同一个开关。与跳板机一样，它是另一条独立传输，收尾必须成对（四条路径共用 dispose()）；
• 凭据引用选择器：SSH 对话框的密码/口令字段旁有筛选框 + 限高列表，候选 = 凭据存储里已有的 引用名（宿主读 .credentials.yaml 的 refs: 键，只回名字、绝不含值）∪ 连接簿里已在用的 引用名；点击即填 env:NAME，也可手输。候选一个都没有时这一行整体退化成一行说明。设置卡片的 编辑表单里有同一行、同一份候选（卡片里是内联列表而非浮层）；
• 主机指纹 TOFU 钉扎：首次连接成功后把该主机（host:port）的 sha256 指纹记录进 hostKeys（随 settings 持久化）；之后每次连接校验，集合内任一指纹匹配即放行，指纹变更直接拒绝连接（防中间人 冒充），错误信息带重置指引。同一主机的多把钥匙（如 rsa + ed25519）各记一条指纹、合并存于同一记录。 主机重装/换钥匙后到「SSH 主机密钥记录」删除对应记录再重连即可。**「从 known_hosts 导入」**一键 批量预填充（同主机的多条记录全部保留）；
• 连接测试：设置卡片条目行内「测试」与对话框「试连」都只做链路诊断（不建会话、不占名额、 不开 shell）：先 TCP 预检（DNS + 建连，失败分类为拒绝/超时/DNS/不可达），再 ssh2 握手做主机密钥 TOFU 比对，最后完成认证。**条目「测试」**完整 TOFU（首测即记录新指纹）；**对话框「试连」**只比对 不落盘；
• 计入 maxSessions 并发上限；关断与本地会话一致：标签 ✕ / kill 帧关闭 ssh2 channel，exit 帧照常带回退出码 / 信号。

服务器状态条（0.17.0）

（完整模式的条见页首那张图；两种形态由面板头部右上角那颗三档按钮切换。两张图都是 SSH 会话， 本机会话用同一套字段。）

每个可见标签在终端上方挂一条细状态条，实时展示该会话所属主机的资源指标（观感对齐 FinalShell）：

CPU ▮▮▯▯ 6% │ 核心 16 │ 内存 ▮▮▮▮ 78% (49.6/62.3 GB) │ 磁盘 ▮▮▮ 63% (40.8/68.8 GB) │
在线 2w4d7h16m │ TCP 570 │ CPU温度 无 │ 网络 ↓92.3K/s ↑93.1K/s

• 一项资源一条：百分比、迷你进度条、已用/总量同组（内存 78% (49.6/62.3 GB)），标签只出现一次。
• 按机器能力出现的格子：CPU温度 / Ping / Swap 只在这个会话报过该字段时才出现（Linux /sys/class/thermal、/proc/meminfo、SSH 往返；macOS 本地、多数云主机没有温度传感器）。判据是 「曾经报过」而不是「这一帧有没有」——传感器偶发读失败不该让整格每秒闪一次。
• 极简模式：面板头部右上角三档循环按钮（完整 → 极简 → 隐藏）；极简条只留 CPU / 内存 / 网络 三项（外加有就显示的 Ping / Swap），每项是「小标签 + 最近 60 秒趋势线 + 大数字」。线色随档位换色： <80 绿 / 80~90 橙 / ≥90 红（STATS_WARN_LIMIT，与 80% 警戒虚线同源）；网络用平方根刻度 + 64 KB/s 地板（线性会把一次突发以外的部分全压到底），掉帧画断线、不补值。
• 资源明细（悬浮仪表盘）：状态条最右端的 ▾ 展开悬浮卡片，三格并排——CPU（每核一根柱， 按 80/90 阈值变橙/红，标题报「最差那一核」的档位）、网络 I/O（近一分钟上下行双线，下行更粗更亮、 上行细一档压暗；固定 60 秒横轴；Y 轴 1-2-5 量程 + 平方根刻度）、进程（Top 5，宿主每 5 秒采一次 ps，上送 CPU 前 5 ∪ 内存前 5；列头可切换 CPU / 内存排序；进程名按可执行文件名首尾截断）。
• 条目悬停卡片：指针在某格上停 140ms 弹出小卡片——第一行当前读数，第二行起近 1 分钟峰值 + 该格的上下文（CPU 给核心数、内存给已用/总量）。峰值来自客户端自己攒的 60 个采样，缺口不参与峰值、 也不当 0；采不到的格子不弹卡。
• 右侧「负载 / 时间」：负载 0.15 │ 10:45:23，负载取 /proc/loadavg（macOS 走 os.loadavg()， Windows 拿不到就整格隐藏）；时间走自己的 1s 定时器，不挂 stats 帧。
• 让位阶梯：整根条按一条顺序逐级藏——核心 → 在线 → 时钟 → 负载 + 时钟整组，一不溢出就停。 活指标（CPU / 内存 / 磁盘 / TCP / Ping / Swap / 网络 / 负载）一个都不让。判据是真实溢出 （scrollWidth > clientWidth）而不是算宽度，每帧从「全显示」重算。
• 两条采集路径，同一帧形状：SSH 会话在同一条 ssh2 连接上另开一条非 PTY 的 exec channel，远端 跑常驻循环每秒吐一行 JSON；本地会话由宿主自己采（Linux 直读 /proc，macOS 走 os/netstat/vm_stat）。 两条路径都不碰 PTY 数据流。远端平台覆盖 Linux / Windows（PS 脚本兜底），macOS/BSD 远端拿不到就整条隐藏。
• 订阅制、懒启动：客户端按标签可见性发 {t:'statsOn'} / {t:'statsOff'}，宿主首个订阅才起采集； 退订清零、会话退出、孤儿回收、插件禁用、配置关闭都会停表并关掉远端 channel。
• best-effort：某项拿不到就省略该字段（前端显示「无」）；采集失败静默停表、状态条整条隐藏 （8s 收不到新帧即收起——不是 3s：采集子进程偶发变慢时窗口太紧会闪）。绝不写 PTY、绝不弹错误。 进度条配色：<70 正常 / 70~90 黄 / ≥90 红。
• 慢命令不拖垮节奏：走子进程的字段（df / netstat / vm_stat / ps）只在首次采样时等一次，之后一律 「用上一次的值 + 到点后台刷新」（本地 SLOW_TTL_MS = 5000 槽位，远端 REMOTE_SLOW_EVERY = 5 拍 的相位门）——某台机器某个命令卡住只会让那一格显示几秒前的旧值。
• 固定槽位 + 增量刷新：每个值的字符槽位固定（右对齐），条目只建一次、之后只写真的变了的文本， 所以数字跳变不会把后面的条目推着横移；窄窗口横滚到右侧时滚动位置也不会被下一秒的刷新弹回开头。
• 热生效：关掉 statsEnabled 立刻停采集，重新打开后按仍存留的订阅自动恢复。

AI 辅助「失败即解释」（0.24.0，默认关）

命令以非零状态结束时，终端右下角浮出一枚低调的徽标（写着退出码）；点它才把那条命令的输出尾部 发给模型，换回一段「发生了什么 / 下一步」。

• 零输入，但不自动外发：徽标只提示「这条失败了，要看看吗」——把终端内容送出去的那一步永远是用户 点的。Ctrl-C（130）与 SIGPIPE（141）不弹（它们天天出现），退出码拿不到时也不弹。
• 发什么：那条命令的输出尾部（剥颜色与 \r 覆盖行、折掉连续重复行、截断到 40 行 / 6000 字符， 密钥 / token / 连接串里的密码已遮盖）加上当前屏幕——不发 scrollback。输出回答「这条命令干了 什么」，屏幕回答「敲的是哪条命令」。
• 答案怎么用：浮层表头是「这条命令为什么失败」加一枚退出码药丸；模型给的命令单独渲染成「建议 命令」一块，按钮是「填入命令行」——只把字节写进提示符（先发 Ctrl-U 清掉可能躺着的半截输入）、 绝不回车；另给「复制答案」与「关闭」。答案只活在面板 UI 里，不回显进终端。
• 失败时也有出路：宿主报错时浮层给一块可复制的「复制报错」，而不是一行没有按钮的死文案。
• 同一条失败只问一次：答案按那条命令缓存，Esc 收掉再点徽标会直接回放；只有上一次报错时 再点才会重试。宿主侧另有按会话的在途去重。
• 模型路由：候选来自宿主已注册的模型目录（provider / model 成对；留空跟随宿主默认模型）。 卡片里是一个只读的「模型路由」控件（显示 provider/model），点开列出按渠道分组的候选，点一条 同时把两个键写好。候选取不到时界面把「拿不到候选：宿主可能还没重启」与「宿主没有可用的模型」分开说。
• 隐私：默认关。打开它等于授权一次终端内容外发——只发上面那一段，发送前做轻量遮盖（只按形态 明确的规则，宁愿漏一个罕见格式也不错杀正常日志）。

配置（保存即热生效）

设置面在宿主里的位置随 DSH 版本变，但始终是同一份表单——各代际的落点与四条注册契约的唯一归宿在 conventions.md § 客户端设置面。

项	默认	说明
enabled	true	关闭整个插件（需重启生效）
announceToAgent	true	是否向 agent 公告终端面板能力（systemPrompt 注入）
maxSessions	4	并发 PTY 会话上限（1~16）
shell	$SHELL	shell 路径；设置卡片可选可输入（下拉候选是浮层，来自 /etc/shells + $SHELL + 常见安装路径，仅列存在且可执行者），也可手输任意路径
term	xterm-256color	TERM 值
colorTerm	truecolor	COLORTERM 值
cwd	宿主启动目录	兜底工作目录（客户端当前会话 cwd 优先）
reconnectGraceSec	120	异常断开后会话保活秒数（0~3600）：刷新页面/网络抖动后会话存活等待重连，超时由回收器结束；0 = 断开立即结束
sshHosts	[]	SSH 连接簿条目 {name, host, port=22, username, auth=agent|key|password, keyPath, passphrase, password, agentForward, hostKeyAlias='', persist=false}；保存时整体替换、同名覆盖；password / passphrase 支持 env:VAR 引用；persist=false 是取消项；hostKeyAlias 空串 = 按主机地址定位指纹
hostKeys	[]	SSH 主机指纹记录（TOFU，自动维护）：{host, port, fingerprints[]}，按 host:port 唯一，一机多把钥匙共用一条记录；首次连接自动追加、任一指纹匹配放行、全部不匹配拒绝连接
shellIntegration	true	注入 OSC 133/7 shell 集成（命令边界标记 + cwd 上报；tty_capture{last} 依赖它）；zsh/bash/PowerShell 支持，其他 shell 自动跳过
tunnels	[]	端口转发隧道 {name, bookName, direction=local|remote, localPort?, remoteHost?, remotePort?, localTargetHost?, localTargetPort?, enabled}；bookName 引用连接簿条目
sftpStyle	dialog	SFTP 界面风格：dialog 单窗体 / dual 双栏（左本机 / 右远程，行内 ⇨/⇦ 服务端直传）；重新打开 SFTP 生效
persistence	off	会话持久化：off 会话随宿主生死；tmux 开启后所有新开的标签默认由 tmux 托管、可跨宿主重启恢复
endOnPageClose	false	页面断开且保活期结束时，是否连 tmux 持久会话一起结束。默认 false = 留存可恢复
sftpLimits	{maxDownloadMb: 1024, maxUploadMb: 2048, maxUploadFiles: 1000}	SFTP 传输限制（浏览器侧保护，0 = 不限）；大文件请走双栏 ⇨/⇦ 服务端直传
allowProxyCommand	false	允许连接簿条目里的代理命令在本机执行。默认关：关着时携带代理命令的连接明确失败，~/.ssh/config 导入永不自动带入该字段。docker 容器面板读同一个开关。两条提权通道：① 启动环境变量 DSH_TTY_ALLOW_PROXY_COMMAND=1（只认宿主的启动环境快照）；② 就地提权（免重启）。授权持久（<DSH home>/dsh-kit/capability-grants.json），重启后直接生效（见 architecture.md § 7）
assistEnabled	false	AI 辅助「失败即解释」。默认关：开启后命令非零退出时右下角出现徽标，点它才把该条命令的输出尾部（清洗、去重、截断、密钥遮盖后）连同当前屏幕发给模型；不发 scrollback。关着时宿主侧也拒绝 /api/dsh-tty/assist
assistProvider	''	AI 辅助的模型路由 provider；与 assistModel 成对（都留空 = 跟随宿主默认模型）。只填一个既不生效、也不会静默回落到默认模型
assistModel	''	AI 辅助的模型路由 model；与 assistProvider 成对
statsEnabled	true	服务器状态条：按标签可见性采集并推送资源指标；关闭即停表（远端 exec channel 一并关闭），保存即热生效
terminalFontFamily	''	终端字体栈：逗号分隔的 CSS 字体名，排在内置等宽栈之前。空串 = 只用内置栈。只影响渲染，不碰 PTY；值里的引号/反斜杠/尖括号会被清洗掉，每个名字会补上双引号（CSS 通用族除外）。改了即时重排已有终端
terminalFontSize	13	终端字号（px，8~32）
terminalCursorStyle	bar	光标形态：bar / block / underline。终端里的程序也会写这个值（DECSCUSR），所以本插件在每批输出解析完后把被改掉的纠回；全屏程序（vim / less / htop / fzf，备用屏幕）让位
terminalCursorBlink	true	光标是否闪烁。程序发的 ?12h / ?12l 会覆盖它，普通缓冲区里会被纠回，全屏程序让位
terminalLineHeight	1.35	行高倍数（1~2）。方块光标通常配 1：1.35 会把单元格撑高，光标比字形高出一截
sidebarHostAlign	false	侧栏「终端」入口与宿主 .panelRow 对齐：宽度 calc(100% - 4px)、margin 0 2px、min-height 36、padding 7px 8px、14px 字号、16px 图标。默认 false = 插件自带尺寸（纯增量样式）

连接栏：连接身份与复制

SSH 标签的连接栏除了动作按钮，还把这条连接的身份证摆在同一行（全部只读，改连接仍走设置卡片）：

• 地址可点：左侧 user@host:port 是一枚可点的胶囊，点开「连接详情」弹层：目标、连接簿条目、 认证方式、跳板机、代理命令、持久化状态与最近一条状态。数据来自会话的 spawnSpec + 标签状态。
• 跳板机徽标：配了跳板机时地址旁多一枚徽标，title 是完整的 [user@]host[:port]——走了 bastion 的连接和直连在界面上本来长得一模一样，排障时最容易看错。
• 「⋯」里两个复制项（都不含任何凭据）：复制连接信息（目标 / 条目 / 认证 / 跳板机 / 代理 命令，每行 标题: 值）与复制 SSH 命令（可直接粘进终端，端口 / 跳板机 / 代理命令按 OpenSSH 写法 带上）。密码、私钥路径、passphrase 一律不进剪贴板。

客户端服务（给其他插件）

其他插件不需要 tty 认识自己，只通过下面三个客户端服务接入；内置动作也走同一条注册通道， 未注册任何扩展时行为与之前完全一致。服务名同样未声明在 tty 的 Context 类型面上，消费方用字符串 注入即可（可选依赖：tty 未安装或版本过低时注入不会触发）。

连接栏扩展点（客户端服务 ttyConnbar，0.13.0）

在 SSH 连接栏（SFTP / 隧道按钮那一行）追加自己的上下文按钮。显示顺序 = 注册顺序；「⋯ 更多」是 动作区的溢出入口，恒排最后（免得新插件把「更多」顶到中间）。

// 消费方（如 dsh-docker）在自己的客户端半体里可选注入：tty 没装就不会触发
ctx.inject(['ttyConnbar'], (c) => {
  const dispose = c.ttyConnbar.addAction(({ tab, spec, bookName, addAction }) => {
    // 每次 renderConnbar 都会调用一次；自行决定这次要不要加按钮
    if (spec.t !== 'ssh') return
    addAction(iconSvg, '容器', '打开该主机的 Docker 容器面板', () => { /* 打开自己的面板 */ })
  })
  // 卸载时调用 dispose()
})

成员	说明
addAction(factory)	注册按钮工厂；返回注销函数。factory 收到 {tab, spec, bookName, addAction}：spec 是会话的 spawnSpec，bookName 是连接簿条目名（内联连接为 ''），addAction(icon, label, title, onClick) 用 tty 的按钮样式追加一个按钮
requestRender()	请 tty 重新渲染连接栏（消费方异步拿到新数据后需要按钮立刻出现时用）

• 只在 SSH 标签上触发；本地标签的连接栏本身是隐藏的。
• 命令标签不触发（spawnSpec.command 非空，即经 ttyTerminal.open 跑一条命令的标签）——连接栏 那几个扩展都作用于连接本身，挂在命令标签上会误导（SFTP 浏览的是宿主机，不是用户以为的容器内）。
• 工厂抛错只记 console.warn，不影响连接栏与内置按钮。

终端命令标签（客户端服务 ttyTerminal，0.14.0）

open() 默认复用（契约 v3）：同一个「连接 + 命令」已有活标签时，聚焦它而不再新开。动机是 实测——容器卡片「终端」按钮连点几下就是三个一模一样的 docker exec 标签，而每个标签各占一个会话 名额。想要并列两个同样的会话，传 reuse: false。

比连接栏按钮更进一步：让其他插件开一个标签直接跑一条命令（典型是 dsh-docker 的卡片「终端」按钮 → docker exec -it <容器> sh）。

ctx.inject(['ttyTerminal'], (c) => {
  c.ttyTerminal.open({
    command: "docker exec -it 'demo-consumer' sh",  // 必填，单行，≤2000 字符
    book: 'lab-a',        // 二选一：连接簿条目名 → SSH 标签
    // spec: { host, port, username, auth, agentForward },  // 内联 SSH 字段
    // （都不传 = 本地标签，用 cwd 指定工作目录）
    label: 'demo-consumer · exec',
    cwd: '/optional/local/cwd',
  })
})

• 命令标签不做 tmux 持久化（命令短命，attach 无意义），也不走登录 shell；SSH 侧用 conn.exec(command, {pty})，本地侧用 sh -c 'export TERM=…; exec <同一个 shell> -c <command>'—— 外层 exec 让进程就是命令本身（退出码与信号忠实），内层 -c 才保证整段命令被当 shell 代码执行 （cd x && cmd、a; b、for …; do …; done 都完整跑，D78）。
• 命令标签会自动重开：宿主重启 / 断线重连后 sid 已失效，客户端对 spawnSpec.command 的标签按原 规格重新执行命令（普通非持久标签维持「点击重试」）。页面刷新后同样按原命令恢复。
• 命令来自宿主侧插件（不是远程用户输入），信任级与插件本身相同；tty 只校验形状：非空、单行、 长度 ≤2000（换行会破坏本地 -c 包装层）。「单行 ≤2000」是这条通道的约束，不是 tty_open 的。
• ttyTerminal / WS spawn 是「没有静态能力闸」的命令面：本服务与 {t:'spawn'} 帧都直接接受 任意 command，不受任何 DSH_*_ALLOW_* 管辖（本插件的那个静态闸只覆盖 ProxyCommand 这一档 「配置字段驱动本机命令」）。这是刻意的——终端面板本身就是产品，它的权限上界由用户的直接操作 承担：人点「+」开标签、人在里面敲命令。务必看清 tier gate 管不到这里：上面的 tier gate 挂在 tools/pre-execute 瀑布上、只按 tty_ / sftp_ / tunnel_ 前缀过滤（TTY_TIER_PREFIXES）， 也就是只闸 agent 工具调用；浏览器发来的 spawn 帧与 ttyTerminal.open 是 WS / 客户端服务 通道，完全不经过它。所以别把它当这条命令面的闸门——它一个字节都不拦（tty_open 那条 agent 路径才受它管）。代价：任何消费方都不该把「配上 tty 之后本插件自己的 exec 开关」宣传成「进不了 容器」的边界——装上 tty 后，页内脚本经 ttyTerminal.open 或 WS spawn 就能拿到比一次性 exec 更强的 任意命令面。威胁模型边界见 architecture.md § 7。

open() 与 ttyPanel.mountPane() 都会让面板可见：没开就开，最小化中则恢复——minimize() 是隐藏而不是关闭，这一条对调用方是硬保证。

就地嵌入终端（ttyTerminal.mount，0.15.0）

open 是「借 tty 的弹窗开一个标签」；如果消费方希望在自己的面板里就地放一块终端（典型是 dsh-docker 的终端抽屉），用 mount：

ctx.inject(['ttyTerminal'], (c) => {
  if (Number(c.ttyTerminal.version ?? 0) < 2) { /* 老版本：退回 open */ }
  const dispose = c.ttyTerminal.mount(hostEl, {
    command: "docker exec -it 'demo-consumer' sh",  // 与 open 同一套 options
    book: 'lab-a',                                     // book > spec > 本地
    label: 'demo-consumer · exec',
  })
  // 收起自己的抽屉时：
  // dispose()
})

• hostEl 需是 HTMLElement：tty 往里塞一个绝对定位的 .tt_term，所以挂载点要 position: relative 且有确定尺寸（尺寸变化会被 ResizeObserver 接住并同步给 PTY）。
• 嵌入终端与标签共用同一条 WebSocket 与会话表，但不进标签栏、不写 sessionStorage、不参与 tty 面板 的显隐；tty 面板关闭不会波及它。
• 断线自动重连、宿主重启后按原命令重跑、退出后点击遮罩重开，全部沿用既有逻辑；dispose() 结束会话 并卸载 DOM。挂载是冷启动安全的——tty 面板没开、连接还没建，mount 也会把连接拉起来。
• 嵌入终端没有 tty 面板头部的搜索/清屏工具栏，Ctrl+F 交还浏览器。

面板内挂载位（客户端服务 ttyPanel，0.16.0）

tty 自己的 SFTP 文件浏览也走这条通道：挂载位空着时挂在下方，被同标签的别的面板占用时退回对话框。

mount 解决的是「消费方给宿主，tty 往里塞终端」；ttyPanel 是它的镜像——tty 在终端面板里给消费方 一块位置，让消费方把自己的界面挂进来（典型：dsh-docker 从连接栏点「容器」，容器面板挂在终端右侧， 终端继续可见、可点、可输入）。

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）
    ownerSid: tab.sid,     // 归属标签（可选）：省略 = 当前活动标签，null = 不隶属任何标签
    onClose: () => { /* tty 收掉面板时回调：在这里 unmount 自己的 React root */ },
  })
  createRoot(pane.element).render(<MyPanel />)
  // 自己收起时：pane.dispose()
})

成员	说明
isOpen()	终端面板是否正开着（最小化不算）。消费方据此决定「挂进来」还是「走自己的弹窗」
mountPane(options)	在面板右侧 / 下方挂一块位置并返回 handle；同时只挂一个，后来的会先收掉前一个（并回调它的 onClose）。side:'bottom' 时占满宽度、由高度定尺寸（拖上边缘），可折叠成一条标题栏。ownerSid 记归属标签（默认当前活动标签），切换标签时归属别的标签的 pane 会被收起（DOM 与 React 树保活，切回来恢复）
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 开合 / 拖尺寸会改变终端区高度，refit 时按用户当时的意图锚定——本来贴着底部就 继续贴底，翻在历史里就锁住原来那几行，不会跳走。
• 方向怎么挑：竖向列表 / 列表+详情用 right；横向宽表（文件列表、双栏）用 bottom。

minimize()（契约 v2） 把整个终端面板折进去：弹窗藏起来，但 DOM / WebSocket / xterm 缓冲全保留、 会话继续跑；恢复靠侧边栏「终端」入口上的徽标。消费方用它「把舞台让出去」。

ctx.inject(['ttyPanel'], (c) => {
  if (Number(c.ttyPanel.version ?? 0) < 2 || typeof c.ttyPanel.minimize !== 'function') return false
  if (c.ttyPanel.isOpen() !== true) return false
  return c.ttyPanel.minimize()   // 折起终端，让会话露出来
})

契约版本：ttyConnbar.version === 1、ttyTerminal.version === 3（1 = 只有 open，2 = 增加 mount， 3 = open 默认复用同「连接 + 命令」的活标签）、ttyPanel.version === 2（1 = mountPane + isOpen， 2 = 增加 minimize）。消费方按版本号判断能力。老版本 tty 上 inject 依然会触发，但没有对应字段。

帧协议（/api/dsh-tty/ws，JSON 文本帧；v3 = 单连接多会话 + 断线重连）

方向	帧	说明
C→S	{t:'spawn', sid?, cols?, rows?, cwd?, persist?, persistName?, command?}	创建会话；sid 缺省由宿主生成，cwd 缺省用配置兜底；persist + 稳定 persistName = tmux 持久会话（需 persistence=tmux）；command = 直接跑一条命令（不做持久化）
C→S	{t:'ssh', sid?, cols?, rows?, name? | host, username, …, persist?, persistName?}	创建 SSH 会话（ssh2 原生）；name 引用连接簿条目作基底，内联字段可逐项覆盖；persist 语义同 spawn
C→S	{t:'input', sid?, d}	按键/粘贴数据
C→S	{t:'resize', sid?, cols, rows}	面板尺寸变化。客户端只在容器可见且尺寸可信时发（D79）；宿主的夹紧只做安全下限，非数值按非法值回落 80×24
C→S	{t:'refresh', sid?}	强制重画：宿主对 tmux 会话执行 refresh-client（非 tmux 会话 no-op）
C→S	{t:'kill', sid?}	关闭会话（孤儿会话也允许跨连接 kill，防泄漏）
C→S	{t:'sessions'}	列出全局会话快照（attachable 标记可重连者）
C→S	{t:'attach', sid}	重连孤儿会话（保活窗口内）：ready(reattached:true) 后紧跟一帧 data 回放输出缓冲
C→S	{t:'statsOn' | 'statsOff', sid}	订阅/退订该会话的服务器状态条：按标签可见性驱动，宿主只在有订阅时采集
S→C	{t:'ready', sid, pid, kind, target?, persist?, reattached?}	会话就绪；kind:'local' 带 pid，kind:'ssh' 时 pid=null、target=user@host[:port]
S→C	{t:'data', sid, d}	终端输出（utf8 文本，StringDecoder 兜跨帧多字节序列）；12ms 窗口/64KB 阈值合并成帧，exit/kill 前强制冲刷保证帧序（D76）
S→C	{t:'stats', sid, stats}	资源指标帧：{cpuPct, cores, memUsed, memTotal, memPct, diskUsed, diskTotal, diskPct, uptimeSec, tcpConns, rxRate, txRate, tempC?, load1?, swapUsed?, swapTotal?, pingMs?}；缺失字段即省略，字节类为 bytes、速率为 B/s
S→C	{t:'exit', sid, code, signal}	PTY 退出事实（恰好一次；attach 换连接后仍随当前连接送达）
S→C	{t:'error', sid?, m}	错误
S→C	{t:'sessions', list, tmux?}	会话快照（{sid, kind, target, pid?, cwd, startedAt, lastOutputAt, attachable, persist?}）；tmux = 专用 socket 上现存的持久会话名 + SSH 持久会话留存名

断线保活语义：客户端正常关面板会先逐个发 kill 再断开；因此「WS close 且仍有存活会话」判定为异常 断开——会话转入孤儿状态（输出继续积累进环形缓冲），保活 reconnectGraceSec 后由回收器清理；期间 新连接可 {t:'sessions'} 查询 + {t:'attach', sid} 重连回放。

sid 省略时按「该连接唯一会话」路由；连接上存在 0 或多个会话时省略 sid 会报错。upgrade 路由带 loopback 信任围栏（remoteAddress + Host + Origin 校验），仅本机 Web GUI 可连。

开发

pnpm --filter @hyzyn/dsh-tty build        # tsc 宿主 + esbuild 浏览器半体（client.js）
pnpm --filter @hyzyn/dsh-tty typecheck
pnpm --filter @hyzyn/dsh-tty probe        # M0 探针：PTY 原语验证（需真实 PTY）
pnpm --filter @hyzyn/dsh-tty integration  # 集成测试：真实插件 × 真实 DSH 服务组合
pnpm --filter @hyzyn/dsh-tty live         # 存活冒烟：需先起 dsh web
pnpm --filter @hyzyn/dsh-tty tui          # TUI 冒烟：vim/htop 全屏渲染（需先起 dsh web）
pnpm --filter @hyzyn/dsh-tty ssh-smoke    # SSH 冒烟：内存 SSH server × 真实 spawnSsh 端到端
pnpm --filter @hyzyn/dsh-tty probe-smoke        # 试连分类与 TOFU
pnpm --filter @hyzyn/dsh-tty probe-route-smoke  # 试连 HTTP 路由 + 连接簿
pnpm --filter @hyzyn/dsh-tty sftplimits-smoke   # sftpLimits 配置归一化
pnpm --filter @hyzyn/dsh-tty windows-smoke      # Windows 端到端（其他平台打印原因后跳过）
pnpm --filter @hyzyn/dsh-tty preview      # 视觉预览：headless Chrome 逐场景截图（见下）

CI（.github/workflows/ci.yml）在 ubuntu 跑 integration + ssh-smoke + 三个 smoke，在 windows-latest 跑 windows-smoke，另有一道「构建产物与源码一致」闸门（client.js + lib/）。缺陷台账见 DEFECTS.md。

浏览器半体源码在 client-src/index.js，样式表独立成 client-src/tty.css（由 esbuild 的 text loader 内联进 client.js）。改客户端后需重新 pnpm build 并刷新页面（可能需硬刷新）。

视觉预览 / 截图回归（scripts/preview.mjs）

改样式不该靠「刷新页面看一眼」：脚本把 client.js 装进一个纯静态夹具页（scripts/preview/harness.html

• mock-host.js 伪造的 DSH 宿主），用 headless Chrome 把每一个界面状态逐个渲染并截图到 packages/tty/.preview/shots/（场景清单与条数以 node packages/tty/scripts/preview.mjs --list 为准， 本文件不写死）：

node scripts/preview.mjs                 # 全场景
node scripts/preview.mjs local menu ssh  # 指定场景
node scripts/preview.mjs --list          # 列出场景
node scripts/preview.mjs --theme=light   # 浅色主题

覆盖：本地终端 / 多标签 + SSH 连接栏 / 「+」菜单 / SSH 对话框 / 设置卡片 / SFTP / 挂载位跟着标签切 / 最小化徽标 / 退出提示条与错误遮罩 / 批量关标签（含确认层）/ 隧道弹层 / 搜索框 / toast / 嵌入式终端 / docker 面板与「容器 → 终端抽屉」。

场景可以把函数形态的断言挂到 window.__previewAssert（返回 null = 通过，返回字符串 / 数组 = 失败），脚本会跑掉它并把结果计入 ✓/✗。夹具还会把 --dsw-* 皮肤变量与真实界面一并渲染，因此能验 「明暗主题切换后是否还有白色面板」。产物目录 .preview/ 已 gitignore。

夹具里的 ctx.inject 与真实 cordis 同语义：依赖里有一个服务不存在就不触发回调，而不是把 undefined 塞进 scope。夹具需要 Chrome/Chromium（默认找 playwright 缓存的 Chrome for Testing，也可用 CHROME_PATH 指定）。

已知限制

• resize 为内部耦合：DSH 的 spawnTerminal handle 未暴露 resize，插件直接透传 (handle).terminal.resize(cols, rows)（node-pty 原生 API）。DSH 升级若改内部结构，0.3.0 起会警告一次 并退化为固定尺寸，不再逐帧抛错（D79）。
• TERM 注入用 -c 包装层（仅 POSIX）：DSH 硬编码 node-pty name:"dumb"，而 node-pty 里 name 优先于 env.TERM，因此 shell 以 sh -c 'export TERM=...; exec "$shell"' 方式启动（对用户透明； TERM / COLORTERM 值做白名单校验）。Windows 上没有这一层。
• Windows 宿主：本地终端可用，但 shell 集成 / tmux 持久化 / 磁盘·TCP·网速·温度不适用或拿不到 ——完整边界见「Windows 宿主」一节。
• terminate() 有「幸存者」竞态：DSH 树级清理偶发报 terminal cleanup failed; surviving pids， 插件按 best-effort 处理（失败降级对顶层 shell 直接 SIGKILL），退出码/信号可能为 null。
• 输出为 utf8 文本流：非 UTF-8 字节会被替换字符吃掉（如 cat 二进制文件），属预期行为；跨 chunk 的多字节 UTF-8 序列已由 StringDecoder 兜住，中文高速输出不再花。
• 浏览器半体依赖官方 dsh-web-app 的侧边栏结构（[data-pane="sidebar"]），非官方 Web GUI 可能不显示入口。
• 断线保活窗口有限：异常断开后会话仅在 reconnectGraceSec 内保活可重连，宿主进程重启则所有会话 结束；输出缓冲（尾部 256KB）之外的滚动历史无法恢复。
• shell 集成仅 zsh / bash / PowerShell：其他 shell 自动跳过（tty_capture{last} 会明确报错而非错报）。 bash < 4.4 走 DEBUG trap 兜底：循环体等复合命令的内部命令会多发 B 标记，tty_capture{last} 对这类 命令只截取最后一个内部命令之后的输出（退出码与 tty_expect 不受影响）。用户 rc 若覆盖 PROMPT_COMMAND/钩子数组，集成可能失效。
• 端口转发边界：本地监听固定 127.0.0.1（不暴露局域网）；remote 方向还受服务端 sshd GatewayPorts 限制；隧道规格变更经「保存」热生效，热改连接簿凭证则在下次重连时生效。
• 会话持久化（tmux）边界：持久标签由 tmux server（专用 socket，按 profile 区分）托管——宿主被硬杀 / 保活回收 / 浏览器丢失标签规格时，tmux 会话会留存（这正是恢复能力的前提），直到机器重启或手动 tmux -L <socket> kill-server；tty_capture{last} 依赖 tmux ≥3.3 的 DCS allow-passthrough，更低版本 持久化可用但该能力降级；恢复接回重画的是当前可见屏，断线前的滚动历史在 tmux 自己的 history buffer 里；持久标签的 exit 帧退出码是 tmux 客户端的（0），shell 退出码经 OSC 133;D 标记照常可用； tmux.conf 只在 tmux server 首启时读取；grace=0 对持久标签同样会 kill-session；持久 SSH 会话要求 远程装有 tmux（未装自动降级）；两个窗口同时接回同一持久会话时共享同一个宿主 PTY，名额不翻倍。
• SFTP 边界：文件权限 = 对应 SSH 账号的终端权限（无额外沙箱/chroot）；下载经浏览器内存（超大文件 建议终端 scp/rsync）；agent 工具 sftp_read ≤1MB 且拒绝二进制、sftp_write 单次 ≤1MB；覆盖写走 同目录临时分片 .dsh-part-<uuid> + rename 原子落盘，崩溃时可能留下分片孤儿（下次覆盖上传会自动清理 超过 24h 的残留）。
• SSH host key 为 TOFU 钉扎：首次连接若已遭遇 MITM 则记录的就是伪指纹；指纹变更需人工在设置卡片 确认并删除记录。
• 浏览器标签持久化不含明文凭证：SSH 标签写入 sessionStorage / localStorage 的规格副本会剥掉明文 password / passphrase（env: 引用保留），并打 credsStripped 标记——恢复/重开时提示重新输入。
• 服务器状态条边界：远端靠两跳兜底（POSIX → PowerShell），macOS/BSD 远端两跳都不成立、状态条 整条隐藏；Linux 上 CPU 温度只在暴露 /sys/class/thermal 的机器上有；磁盘固定取 /（Windows 取系统盘） 所在文件系统；本地会话的指标属于宿主机器（多个本地标签共享同一份采样），macOS 温度恒为「无」， 内存按 vm_stat 的 active+wired+compressed 计；指标是瞬时值，没有历史接口（前端自己攒 60 个采样）。
• SSH 会话没有本地 pid：ssh2 shell channel 不是本机进程，ready.pid 为 null、tty_list 显示 target 而非 pid，本机 ps / kill 对远程进程无效——关闭请用标签 ✕ 或 kill 帧。

工作原理

浏览器半体 (client.js, esbuild bundle)
  ├─ 侧边栏「终端」入口 → 大弹窗
  ├─ 标签栏：每标签一个 xterm.js 实例（独立 sid；WebGL 渲染器，丢失回退 DOM）
  ├─ 断线重连：指数退避自动重连 + sessions 查询 + attach 恢复；
  │  标签列表存 sessionStorage（刷新后按 sid 重连保活会话）
  ├─ sessions 客户端服务：新标签带当前会话 cwd
  └─ WebSocket ──→ /api/dsh-tty/ws (webServer.registerUpgrade)
                        │
宿主半体 (src/index.ts)
  ├─ 连接内会话表（sid → 本地 PTY / SSH channel，单连接多会话）
  ├─ SessionManager（maxSessions 上限，热调整；SSH 会话同表调度；
  │  孤儿回收器按 reconnectGraceSec 清理异常断开的会话）
  ├─ 每会话 256KB 环形缓冲（tty_capture / 断线回放）+ xterm-headless
  │  虚拟屏（tty_screen）+ StringDecoder（utf8 分帧兜底）
  ├─ shell 集成（src/shell-integration.ts）：zsh ZDOTDIR / bash --rcfile
  │  桩注入 OSC 133/7 钩子；输出流解析（feedShellIntegration，跨 chunk
  │  残包 carry）→ 命令边界捕获（tty_capture{last} / tty_expect 早停）
  │  与 cwd 跟随（tty_list）
  ├─ 本地路径：ctx.get('subprocess').spawnTerminal({ argv: shell -c 包装层, cwd })
  │  持久标签：包装层换 `exec tmux -L <socket> -f <conf> new -A -s dsh-<名>`
  │  （src/tmux.ts：探测/资产生成/spawn 计划/kill-session；稳定资产在
  │  <DSH_HOME|~/.dsh>/tty/；tmux 会吞不认识的序列，集成钩子在 $TMUX 下把
  │  OSC 133/7 包 DCS passthrough 信封，tmux ≥3.3 解包转发）
  ├─ 辅助路由：/api/dsh-tty/ssh-config（~/.ssh/config 导入候选）、
  │  /api/dsh-tty/credential-refs（凭据存储里已知的引用名）、
  │  /api/dsh-tty/env-vars、/api/dsh-tty/known-hosts、/api/dsh-tty/shells
  │  ——均 loopback 围栏（加固档：127/8 全段 + 主机名 DNS 确认 + 来源检查在
  │  DNS 之前，实现只有一份在 @hyzyn/dsh-kit）；**改状态的端点另需同源证明**，
  │  只读端点（含 sftp /list 与 /download）不要求证明。POST /config 刻意豁免
  │  ——它是插件被禁用后唯一的恢复入口
  ├─ SFTP（src/sftp.ts）：懒连接池（空闲 120s 回收、断开按需重连、TOFU 共用）
  │  → POST /api/dsh-tty/sftp/list|mkdir|rename|remove|download|upload
  │  + sftp_* 工具（只收连接簿名）
  ├─ 端口转发（src/tunnels.ts）：宿主自持隧道（-L/-R 双向），断线退避重连、
  │  TOFU 共用、连接计数；GET /api/dsh-tty/tunnels 实时状态 + tunnel_list
  └─ 帧协议：spawn|ssh / input / resize / kill / sessions / attach
     ↔ ready/data/exit/error/sessions + 背压

SSH 路径 (src/ssh.ts)
  └─ {t:'ssh'} → spawnSsh：ssh2 Client 原生连接（agent / key / password，
     password·passphrase 支持 env:VAR 取密；host key 经 HostKeyStore
     TOFU 钉扎），开 shell channel 包装成与 PTY 同形状的 TermHandle
     （pid=null，kind='ssh'，target=user@host[:port]），背压一并透传；
     persist 时先探测 tmux 再 `exec tmux -L <socket> -f /dev/null new -A -s dsh-<名>`
     开 pty channel（无 tmux 降级普通 shell channel + 灰字提示）

M0 探针、集成测试与真实实例冒烟（live / TUI）在真实 DSH 服务组合上验证过：TERM 注入、resize 透传、 sid 冲突、并发上限、loopback 围栏、多会话数据隔离、cwd 跟随与校验、配置热生效、kill→exit 全链路、 断线保活 + sessions/attach 重连回放、tty_screen 虚拟屏、ANSI 清洗、shell 集成、tty_expect、端口转发、 SFTP 与管理闭环、会话持久化；SSH 路径由 ssh-smoke（内存 SSH server × 真实 spawnSsh）覆盖。逐项 覆盖清单与各轮真机验收记录见 ROADMAP § 已完成。