Nexus/docs/design/plans/2026-06-02-terminal-refactor.md

Terminal 页重构技术计划

日期: 2026-06-02
对应设计文档: docs/design/specs/2026-06-02-terminal-refactor-design.md
阶段编号: T1 ~ T6

---

涉及文件清单

新建文件

文件	说明
frontend/src/composables/terminal/useTerminalSession.ts	单会话 xterm + WS 生命周期
frontend/src/composables/terminal/useTerminalSessions.ts	多会话 Tab 管理
frontend/src/composables/terminal/useTerminalSettings.ts	fontSize/scrollback localStorage 持久化
frontend/src/composables/terminal/useTerminalCmdBar.ts	命令输入 + 历史记录
frontend/src/components/terminal/TerminalTabBar.vue	Tab 条
frontend/src/components/terminal/TerminalToolbar.vue	工具栏（状态/字号/断开）
frontend/src/components/terminal/TerminalArea.vue	xterm 挂载区 + per-session overlay
frontend/src/components/terminal/TerminalCmdBar.vue	命令栏 + 快捷键面板
frontend/src/components/terminal/TerminalQuickBar.vue	快捷命令栏
frontend/src/components/terminal/TerminalServerPicker.vue	服务器选择（inline + dialog 两种模式）

修改文件

文件	改动
frontend/src/pages/TerminalPage.vue	瘦身至 ~130 行，仅组合上述组件

不改动文件

文件	原因
server/api/webssh.py	后端逻辑已完善，协议不变
frontend/src/composables/useTerminalQuickCommands.ts	已结构良好，T6 仅小调整
frontend/src/components/ShellHighlightField.vue	无需变更
frontend/src/utils/wsUrl.ts	无需变更

---

实施步骤

T1：markRaw 修复 + Uptime 计时器内嵌（Critical 修复）

目标：解决 C1（Vue 代理 xterm/WebSocket）和 C3（Uptime timer 外部 Map）

步骤：

1. 在 TerminalPage.vue 中，将 TermSession interface 拆分：
   • 新增 TermSessionNative type，字段：ws / term / fitAddon / resizeObserver / reconnectTimer / pingTimer / uptimeTimer
   • 新增 module-level const nativeMap = new Map<string, TermSessionNative>()
   • 从 TermSession interface 中删除上述字段
2. 所有原生对象创建时包裹 markRaw()：
   • term = markRaw(new Terminal(...))
   • fitAddon = markRaw(new FitAddon())
   • resizeObserver = markRaw(new ResizeObserver(...))
   • WebSocket 无需 markRaw（已在 connectSession 内部使用，不进 reactive）
3. 将 _uptimeTimers Map 删除，uptimeTimer 改存入 nativeMap[sessionId].uptimeTimer
4. 更新 closeTab 和 onBeforeUnmount 中的清理逻辑，从 nativeMap 获取 native 对象后清理

验收：Vue DevTools → Components 面板，sessions ref 中不出现 Terminal/WebSocket/FitAddon 对象

---

T2：Per-Session Overlay（Critical 修复）

目标：解决 C2（全局 overlay 状态）

步骤：

1. 在 TermSession interface 中新增字段：

   showOverlay: boolean       // 替代全局 showDisconnectOverlay
   overlayMsg: string         // 替代全局 disconnectMsg
   reconnectCountdown: string // 移入 session
   

2. 删除全局 showDisconnectOverlay、disconnectMsg、reconnectCountdown refs
3. 在 connectSession、startReconnect、disconnect、closeTab 中，将原来操作全局 ref 的代码改为操作 s.showOverlay / s.overlayMsg / s.reconnectCountdown
4. 模板中的 <v-overlay> 绑定改为 activeSession?.showOverlay
5. 关闭最后一个 Tab 时，不显示 overlay，让空状态区域自然显示（删除 showDisconnectOverlay = true 的 closeTab 逻辑）

验收：

• 打开 2 个会话，让会话 2 断开，切换到会话 2，overlay 显示
• 关闭最后一个会话，出现空状态服务器选择器，不出现 overlay

---

T3：提取 Composables

目标：解决 M1（单文件过大），提取 4 个 Composable

T3-A：useTerminalSettings

// 仅管理 fontSize / scrollback 的 localStorage 持久化
export function useTerminalSettings() {
  const fontSize = ref(...)
  const scrollback = ref(...)
  function changeFontSize(delta: number): void
  function changeScrollback(val: number): void
  return { fontSize, scrollback, scrollbackOptions, changeFontSize, changeScrollback }
}

T3-B：useTerminalCmdBar

// 管理命令输入、历史记录
export function useTerminalCmdBar(getActiveSession: () => TermSession | null) {
  const cmdInput = ref('')
  function sendCmd(): void
  function cmdHistoryUp(): void
  function cmdHistoryDown(): void
  function sendCtrl(key: string): void
  function sendKey(key: string): void
  return { cmdInput, sendCmd, cmdHistoryUp, cmdHistoryDown, sendCtrl, sendKey }
}

T3-C：useTerminalSessions

核心：多 Tab 管理，包含 sessions / activeSessionId / activeSession / newSession / closeTab / switchTab / applyRouteQuery

T3-D：useTerminalSession

核心：单会话连接 + 重连 + ping + uptime，参数为 sessionData ref 和 nativeMap

注意：T3-C/D 是最大改动，需完整测试后再提交

---

T4：拆分 Components

目标：消除模板耦合，每个组件职责单一

组件	Props	Emits
TerminalTabBar	sessions, activeSessionId	switch, close, new
TerminalToolbar	session, fontSize, scrollback	font-change, scrollback-change, disconnect, fullscreen
TerminalArea	sessions, activeSessionId	context-menu
TerminalCmdBar	disabled	send, ctrl, key
TerminalQuickBar	commands	exec, manage
TerminalServerPicker	servers, mode	select

TerminalPage.vue 仅负责组合，约 80 行模板 + 30 行 setup。

---

T5：修复 M2（DOM 查询） + M3（服务器选择器去重）

M2 修复：

• TerminalCmdBar.vue 组件内部声明 const inputRef = ref<HTMLTextAreaElement | null>(null)
• 将 <ShellHighlightField> 替换为绑定 ref 的原生 textarea（或 ShellHighlightField 补充 expose）
• 删除 getCmdInputEl() 函数

M3 修复：

• 新建 TerminalServerPicker.vue，props: mode: 'inline' | 'dialog'
• 空状态区域使用 <TerminalServerPicker mode="inline">
• 新建会话对话框内容使用 <TerminalServerPicker mode="dialog">
• 删除模板中的重复列表代码

---

T6：Minor 体验修复

E1 修复（向同一服务器新建会话）：

• newSession 中检测到同 serverId 时，弹出 snackbar：「会话已存在，已切换过去。如需新建请关闭原会话。」
• 提供一个可选 opts.forceNew: boolean 参数供未来扩展

E2 修复（初始 cd 指令时序）：

• 将 sendCdToSession 从 setTimeout(200) 改为在 TERMINAL_INIT 消息处理中直接发送，不依赖超时

E3 修复（重复快捷键）：

• 删除 onKeydown 中重复的 e.key === '=' 分支，只保留 e.key === '+'（标准 Chromium 行为）

E4 修复（快捷命令加载失败提示）：

• loadQuickCmds catch 块改为：snackbar('快捷命令加载失败，使用内置命令', 'warning') 后再赋值内置

---

依赖与配置变更

• 无新 npm 包依赖
• 无 Vue Router / Pinia 结构变更
• xterm 版本不变（@xterm/xterm）

---

测试要点

场景	验证方式
markRaw 生效	Vue DevTools sessions ref 无 Terminal 实例
多 Tab 断开 overlay	手动断网，切换 Tab，overlay 正确显示
最后 Tab 关闭	显示空状态选择器，不显示 overlay
xterm resize	拖拽侧栏/改字号，xterm 正确填充容器
reconnect 指数退避	断连后等待，验证 1s/2s/4s 重连间隔
命令历史	发送命令，↑/↓ 正确回溯
快捷命令	点击执行，命令发送到活动终端
pendingPath 跳转	/terminal?server_id=1&path=/var/log 打开后自动 cd
T1-T6 全部功能回归	手动端到端测试所有功能

---

回滚方式

全程在功能分支 refactor/terminal 开发，main 分支不受影响。
任何阶段出现严重问题，直接 git checkout main -- frontend/src/pages/TerminalPage.vue 回滚到重构前。

---

执行顺序建议

T1（markRaw + timer, 1h） → T2（per-session overlay, 1h）
→ T6（minor fixes, 0.5h）
→ T3（composables, 2h）→ T4（components, 2h）→ T5（dom + picker, 0.5h）
→ 全量测试 → changelog → 部署

建议 T1+T2+T6 作为第一批次（安全稳定性），T3+T4+T5 作为第二批次（架构重构）分两次 PR 合并。