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

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

涉及文件

文件	改动	功能
web/app/terminal.html	全面重构	全部 11 项前端
server/api/webssh.py	轻量	PING/PONG + PROMPT_COMMAND

实现步骤（11步）

Step 1: 字体大小调节

• 工具栏加 − + 按钮 + container document.addEventListener('keydown')
• term.options.fontSize = Math.max(10, Math.min(24, val))
• 存 localStorage nexus_term_fontSize
• 页面加载时恢复

Step 2: Ctrl+L 清屏

• keydown 监听: e.ctrlKey && e.key === 'l' → ws.send({type:'DATA',data:'clear\r'}) + term.clear()

Step 3: 滚动缓冲区调节

• 工具栏下拉: option 1000/5000/10000/50000
• term.options.scrollback = parseInt(val) (xterm 5.x 支持热改)
• 存 localStorage

Step 4: 命令历史持久化

• sendCmd 后 push + localStorage.setItem
• 最多 200, FIFO (shift if >200)
• 页面加载: cmdHistory = JSON.parse(localStorage.getItem(...))

Step 5: 右键菜单

• term.element.addEventListener('contextmenu', ...) 阻止默认
• 自定义浮层 div absolute 定位
• 四项: 复制/粘贴/清屏/全选
• 点击外部消失

Step 6: 快速切换服务器

• <input> oninput 过滤 #serverListPanel 中的链接
• 复用 push.html filterServerOptions 逻辑

Step 7: 快速命令栏

• 右侧面板底部: <div id="quickCmdList"> + + 添加
• BUILTIN_CMDS 5 条 + localStorage 自定义
• 点击 → ws.send DATA
• 添加 → 弹窗(名称+命令) → localStorage
• 编辑删除: 仅自定义命令

Step 8: 断开自动重连

• ws.onclose 检查 !manualDisconnect → 重连
• 指数退避: attempt*1000, max 30000
• overlay 显示 "X 秒后重连..."

Step 9: 连接信息栏 (PING + 时长 + 路径)

后端 (webssh.py):

• PING handler: recv {type:'PING',ts} → send {type:'PONG',ts}
• 初始注入: export PROMPT_COMMAND='...'
• 注入时机: channel opened 后、shell created 前

前端:

• uptime 计数器: ws.onopen setInterval 每秒更新
• PING: 每 5s 发 {type:'PING', ts: Date.now()} → 收到 PONG 计算 RTT
• 路径: term.onTitleChange(title => { ... })

Step 10: 终端标题路径

• 后端 shell 创建后发送 export PROMPT_COMMAND='echo -ne "\033]0;${PWD}\a"'
• 前端 term.onTitleChange 捕获 OSC title → 更新工具栏显示

Step 11: 会话多标签

• 数据结构: sessions = [{id,serverId,serverName,ws,term,fitAddon}]
• 标签栏: <div id="tabBar"> 在 terminal 上方
• 切换: hide/show terminal div + 更新 cmdInput 绑定
• 新建: 弹出服务器选择器 → 创建新 session
• 关闭: dispose term + close ws + splice
• 右侧面板同步切换

依赖与配置

无新依赖。无数据库迁移。仅 localStorage。

测试要点

见验收标准 15 项。

回滚

1. git revert
2. supervisorctl restart nexus (如有后端改动)