Nexus/docs/changelog/2026-06-02-terminal-refactor-T1-T5.md

2026-06-02 — 终端页重构 T1–T5

摘要

将 TerminalPage.vue（约 1244 行单文件）拆分为 Composable + 6 个子组件，修复 markRaw、per-session overlay、计时器泄漏风险，并去除命令栏 DOM 查询与重复服务器选择器。

动机

• xterm/WebSocket/ResizeObserver 被 Vue 深度代理导致潜在渲染异常与内存问题（C1）
• 断开 overlay 为全局状态，切换 Tab 时非活动会话断开无提示（C2）
• Uptime 计时器存于外部 Map，清理路径不一致（C3）
• 单文件不可维护，命令栏依赖 CSS 类名查询 DOM（M1/M2）
• 空状态与对话框重复实现服务器列表（M3）

涉及文件

新建

• frontend/src/composables/terminal/types.ts
• frontend/src/composables/terminal/termNativeStore.ts
• frontend/src/composables/terminal/useTerminalSettings.ts
• frontend/src/composables/terminal/useTerminalCmdBar.ts
• frontend/src/composables/terminal/useTerminalSessions.ts
• frontend/src/components/terminal/TerminalTabBar.vue
• frontend/src/components/terminal/TerminalToolbar.vue
• frontend/src/components/terminal/TerminalArea.vue
• frontend/src/components/terminal/TerminalCmdBar.vue
• frontend/src/components/terminal/TerminalQuickBar.vue
• frontend/src/components/terminal/TerminalServerPicker.vue

修改

• frontend/src/pages/TerminalPage.vue — 组合层（约 280 行，含样式）
• frontend/src/components/ShellHighlightField.vue — defineExpose 供命令栏复制/粘贴

设计文档

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

关键实现

阶段	内容
T1	termNativeStore + markRaw 存放 xterm/FitAddon/ResizeObserver；uptime/ping/reconnect 计时器归入 native
T2	每会话 showOverlay / overlayMsg / reconnectCountdown；关闭末 Tab 显示空状态而非 overlay
T3	useTerminalSettings、useTerminalCmdBar、useTerminalSessions
T4	6 个 components/terminal/* 子组件
T5	TerminalCmdBar 经 ShellHighlightField expose 操作输入；TerminalServerPicker 统一 inline/dialog

迁移 / 重启

• 仅前端：需 npm run build 并部署 web/app/ 静态资源
• 后端无变更，无需重启 nexus

T6 补充（2026-06-02）

• 快捷命令 API 失败时 snackbar 提示后降级内置命令
• 全局快捷键 Ctrl++/Ctrl+= 合并为单分支并 return，避免重复触发

验证方式

cd frontend && npm run build-only
# 浏览器：/app/terminal — 新建会话、多 Tab、断网重连 overlay、命令栏复制粘贴、空状态选服务器

回滚

git checkout HEAD~1 -- frontend/src/pages/TerminalPage.vue frontend/src/components/ShellHighlightField.vue
# 删除 frontend/src/composables/terminal/ 与 frontend/src/components/terminal/