核心概念

读懂四个词——连接、会话、终端、通道——TermPilot 的所有行为都能推出来。

连接（`conn-`）

连接是保存起来的拨号参数：协议、主机、端口、账号、跳板、口令。它只是一份配置，存在本机数据库里，本身不占用任何网络资源。每条连接有一个 conn- 开头的编号，Agent 工具用它寻址。

三种协议的能力不一样，这是协议的物理属性决定的：

协议	终端字节流	exec 通道	SFTP	并发通道
SSH	✓	✓	✓	✓
Telnet	✓	—	—	—
串口	✓	—	—	—

Telnet 和串口只有一条字节流，没有通道概念。对它们调用 term_exec 或 sftp_* 不会瞎报错，而是返回明确的能力说明；connection_list 里每条连接都带 protocol 和 capabilities，Agent 调用前就能知道。

终端是一扇看得见的窗口：xterm.js 画面 + 背后的 PTY。每扇终端有 term- 编号、标题和备注。本机终端（PowerShell / bash）和远程终端在同一行标签里，行为一致。

终端在关闭前一直存在。应用重启后，编号、标题、备注和上次退出时已经画好的行都会恢复，新会话从下一行接着画。断开的终端用 term_reconnect 原样重连——不要为同一扇终端再开一扇。

对一条 SSH 连接第一次拨号后，这条 SSH 会话被放进连接池：之后开的每一扇终端、每一次 term_exec、文件面板，全部复用同一条已登录的会话，靠 SSH 的并发通道互不干扰。引用计数归零才真正断开。

这带来三个直接好处：

登录只做一次。开第五个终端也不用再输密码。
跳板只走一次。对一次性授权的堡垒机尤其重要——第二次拨号会被拒绝。
助手和用户同处一条会话。你在窗口里 cd 到哪、agent 的 term_exec 用同名 session 也承接到哪，不会出现「两个工具各连各的、工作目录对不上」。

保活每 15 秒一次心跳，连续 4 次无响应判定连接死亡并丢掉缓存；终端开 shell 失败会透明重拨一次。网络抖动后回来，终端能自己恢复。

一条 SSH 会话上跑着三种通道：

shell：终端画面背后的交互式 PTY。你敲的每个键、TUI 的每一帧都走它。
exec：term_exec 用的独立命令通道。不占终端画面、可以并发，stdout / stderr 分流返回，退出码来自协议事件而不是从输出里猜。同名 session 的环境（cd、export）跨调用承接，存在远端的 ~/.cache/termpilot/exec/。
SFTP：文件面板和 sftp_* 工具用。默认复用连接池里的会话；目标机缺 SFTP 子系统时会先跑安装脚本改成 internal-sftp，再单独拨一条（旧会话读不到新配置）。

文件通道可以按连接配置（编辑连接 → 高级）：自动（默认）/ 复用终端连接 / 总是单独拨号。跳板只授权一次转发的机器选「复用」，SFTP 就不会触发被堡垒机拒绝的第二跳。

密码和私钥口令只在主进程拨号瞬间以明文存在，落盘的只有 safeStorage（系统钥匙串）加密后的密文。MCP 的任何工具都不返回口令；connection_list 输出里没有它。Agent 能操作你的会话，是因为会话已经登录好了，不是因为它拿到了密码。