Nexus/docs/design/specs/2026-05-30-terminal-iteration-design.md

2026-05-30 终端页面全覆盖迭代 — 设计文档

背景与目标

terminal.html 已具备 WebSSH 基础（xterm.js + Koko 协议 WebSocket + 右侧服务器面板 + 底部命令栏），但缺乏 11 项运维效率特性。用户在频繁切换服务器的运维场景中效率低下。

11 项改进分三个优先级梯队：

• P0 即时提效: 快速命令栏、字体调节、Ctrl+L清屏、滚动缓冲、命令历史持久化、右键菜单
• P1 操作增强: 断开自动重连、连接信息栏(时长/当前路径)、快速搜索服务器
• P2 架构增强: 会话多标签

方案（全选方案 A — 最简增量）

全部 11 项选最简实现：复用现有 WebSocket 通道 + localStorage + 已有 UI 组件。仅会话多标签和连接信息栏需要后端轻量改动。

接口/数据模型

后端改动 (webssh.py)

• PING/PONG 机制: {type:'PING', ts} → {type:'PONG', ts}（测 RTT）
• 初始 bashrc 注入: export PROMPT_COMMAND='echo -ne "\033]0;${PWD}\a"'（OSC title）

localStorage 键

Key	内容
nexus_terminal_cmds	[{id, name, cmd}]
nexus_term_fontSize	14
nexus_term_history	["cmd1", "cmd2", ...] 最多 200
nexus_term_scrollback	1000
nexus_term_tabs	[{serverId, serverName}] 恢复标签

安全与性能约束

• 纯前端功能 9/11 项无安全影响
• 快速命令栏: 命令文本走已有 WebSocket DATA 通道，不额外引入
• 连接信息栏: WebSocket PING 每 5s 一次，单字符消息不占带宽
• 多标签: 每标签独立 WS 连接，最多 10 标签（asyncssh 连接池已有上限）
• 终端标题路径: PROMPT_COMMAND 由后端注入，不走用户输入

验收标准（15项）

1. 快速命令: 点击执行 / 添加编辑删除 / 刷新保留 / 内置不可删
2. 字体: Ctrl+/- 或按钮调节，范围 10-24，刷新保留
3. 清屏: Ctrl+L → clear + term.clear()
4. 历史: sendCmd 存 localStorage，刷新恢复，ArrowUp/Down 可用
5. 右键: 复制/粘贴/清屏/全选 四项
6. 搜索: 实时过滤服务器列表
7. 重连: 异常断开自动重连(1→2→4→8→max30s)，手动断开不重连
8. 连接信息: 工具栏显示连接时长(HH:MM:SS) + 当前目录路径
9. 多标签: 切换/关闭/新建，每标签独立 WS+xterm，保持服务器列表
10. 回滚: 下拉选择器 1K/5K/10K/50K 行