OpenTerminal/docs/ROADMAP.md

OpenTerminal 长期路线图

目标：以开源组件组合复刻 XTerminal 的核心终端能力（调研依据见 research/i18n-extracted.txt 功能清单），按里程碑推进，每个里程碑可独立交付使用。

里程碑总览

阶段	内容	状态
M1	本地终端 + 分屏 + 主题/字体 + 设置持久化	✅ 已完成（v0.1）
M2	SSH 远程会话 + 连接管理器	✅ 已完成（v0.2）
M2.5	关键词高亮（提前自 M4）+ 系统设置（自启动/阻止休眠）+ UI 打磨	✅ 已完成（v0.2.1）
M3	SSH 产品化：Terminal/SSH 分离 + 服务器硬件监控（Wave 风格）	✅ 已完成（v0.3）
M4	SFTP 文件管理 + 传输面板 + 权限/属主/chmod	✅ 已完成（v0.4）
M5	命令历史/命令库/补全 + 会话日志	✅ 已完成（v0.5）
M6	广播输入 + ZMODEM + 快捷输入面板 + 快捷键系统	📋 下一步
M7	打包分发（electron-builder + 自动更新）

M2 — SSH 远程会话 ✅

• src/main/ssh.ts：ssh2 连接池（connect/shell/resize/close），PTY_DATA/PTY_EXIT 广播通道统一复用（本地与 SSH 会话同数据面）
• 连接配置模型（shared/connections.ts）：host/port/username、密码 vs 私钥（keyPath/keyContent）vs Agent、keepalive
• 凭据加密存储：safeStorage(DPAPI) + plain: 兜底；渲染层只见 savedAuth 标志
• 连接管理器 UI：书签侧栏（分组手风琴）+ 新建/编辑对话框 + 双击连接
• Host key 校验：known_hosts 固定、首次确认、变更告警、30s 超时拒绝
• 测试：tests/ssh-loopback.mjs（ssh2 回环）+ tests/ssh-session-e2e.mjs（真实会话路由层 e2e）
• 待解锁后的 GUI 验收：双击书签连接、指纹弹窗交互、断线提示
• 已知限制：SSH 面板暂不支持作为分屏参照（总在新标签打开）；连接中 Modal 不可取消；agent 认证未在本机验证

M3 — SSH 产品化：Terminal/SSH 分离 + 服务器硬件监控 ✅

A. Terminal 与 SSH 功能分离（产品形态）

• 侧栏双分区：「终端」（本地）与「SSH 服务器」各自独立区块（独立折叠、独立头部、独立计数）
• SSH 会话标识：标签页带服务器图标/主机名前缀，本地与 SSH 标签视觉区分
• 新建入口分离：图标条「+」只建本地终端；SSH 会话仅从服务器列表发起（双击连接，右键：连接/编辑/删除/复制主机）
• SSH 区增加「最近会话」（按 lastConnectedAt 排序，一键重连）
• （可选增强）工作区模式：本地/SSH 两个独立工作区布局，互不混排
• 验收：不开侧栏也能一眼区分标签是本地还是 SSH；图标条「+」只出本地终端

B. 服务器硬件监控（参考 Wave Terminal 的 sysinfo 块）

技术可行性：✅ 高。XTerminal 逆向已证实路线 1 的完整链路（ensureSetupServerStatusFiles / getServerStatsByQuery / getServerProcessList）。

• 路线 2 起步（零部署）：ssh2 exec 读 Linux 标准接口——CPU /proc/stat（双采样算占用率）、内存 /proc/meminfo、负载 /proc/loadavg、磁盘 df -kP、网络 /proc/net/dev（双采样算速率）、运行时间 /proc/uptime
• 路线 1 增强（部署脚本）：首次连接部署 ~/.openterminal/sysinfo.sh（纯 shell 输出 JSON，Linux/macOS 通用），解锁进程 Top 列表

数据面：ssh2 conn.exec → stdout JSON → 主进程解析 → STATS:{id, stats} 广播 → 渲染层

• src/main/sysinfo.ts：按会话轮询（默认 3s，可配置），会话关闭/断线自动停止；解析容错
• 契约：shared/sysinfo.ts（SysinfoSample + STATS 通道 + 面板开关事件）
• UI：SSH 会话右侧可折叠监控面板——CPU 多核条形、内存/磁盘用量条、网络上下行、负载/运行时间
• （路线 1）进程 Top 列表 + 结束进程
• 验收：连接后 ≤3s 看到实时 CPU/内存；断开会话监控自动停止；服务器跑 stress 曲线明显上升

M4 — SFTP 文件管理 ✅

• src/main/sftp.ts：ssh2 SFTP 封装（readdir/stat/rename/mkdir/rm/mv，大文件分块传输 + 进度事件）
• 双栏界面（本地 ↔ 远程）+ 拖拽上传/下载 + 传输面板（队列/暂停/取消）
• 右键菜单：压缩/解压（tar.gz）、编辑远程文件（Monaco，下载-编辑-回传）
• 验收：100MB 文件传输进度流畅、可取消续传

M5 — 命令系统与会话日志 ✅

• 命令历史（sqlite + better-sqlite3，按会话去重）
• 命令库（分组 + 参数变量 {{param}} + 一键运行/粘贴）
• 终端补全：历史 + 命令库 + 内置命令表（XTerminal 内置 607 个 Linux 命令文档，可从 tldr 页面生成）
• 会话日志：手动启停、纯文本落盘、断线暂停指示
• 关键词高亮（✅ 已提前完成：highlightEngine 流式 ANSI 注入 + 11 条预设 + 设置页管理，见 M2.5）
• 验收：补全 ↑↓/Tab/Esc 交互与 XTerminal 一致

M6 — 多终端协同

• 广播输入（toggleBroadcast）：选中多个会话同步键入
• 快捷输入面板（Quick Input）：右下角浮层 = 命令输入 + 快捷命令 + 最近命令
• ZMODEM（rz/sz）：渲染层检测 ZRQINIT/ZRINIT 序列，触发文件选择
• 快捷键系统：增减字号、切换上下个终端、全局快捷键（globalShortcut）
• 验收：3 个分屏同步执行命令；rz 传输成功

M7 — 打包与分发

• electron-builder：nsis 安装包（Windows 优先，x64/arm64）
• 原生模块处理：node-pty 已用 @lydell 预编译版，无需 rebuild
• 自动更新（electron-updater + generic provider 或 GitHub Releases）
• 代码签名（可选）

工程约定（贯穿各阶段）

1. 契约先行：新增功能先在 src/shared/ 定义通道与模型，再实现两端
2. 原生依赖：优先选带预编译二进制的包（@lydell/node-pty 模式），避免用户机器装构建链
3. 渲染层加密不可取：不做代码混淆/加密（XTerminal 加密渲染层的做法牺牲了可调试性，收益仅是防抄）
4. 测试：main 进程服务（pty/ssh/sftp）用 vitest 单测；渲染层交互靠 dev 手测
5. 里程碑验收后打 git tag（引入 git 后）

已知待办（M1 遗留）

• 布局塌陷（v0.2.1 修复：antd <App> 包裹层 .ant-app 无高度导致百分比高度链断裂）
• 关闭标签页整窗崩溃（v0.2.1 修复：xterm IDisposable 对象被当函数调用；并新增 ErrorBoundary 兜底 + 渲染层报错转发主进程日志）
• 首启动空屏（v0.2.1：启动自动打开一个终端）
• autoWrap=false 的固定列宽模式（xterm.js 无原生 wrapMode，需自定义列数控制）
• 终端标题跟随 OSC 序列（窗格标题显示当前目录/命令）
• 内置等宽字体打包（OFL 许可：JetBrains Mono / Fira Code 等，XTerminal 内置 19 款可作清单参考）
• rendererMode webgl 的终端数量上限自动降级（XTerminal：7 个后强制 DOM）
• 会话数据在面板间拖拽迁移（dockview 原生支持面板拖动，已具备）
• 界面语言切换（中/英）：需先把全应用文案抽为 i18n 资源目录（一次完整重构），设置页预留「系统」分区