本文记录做什么、为什么、先做哪个,以及尚未实现的功能的设计要点。功能实现后,跨模块的设计写进 ARCHITECTURE.md,模块内的细节写在代码注释里,并在下方里程碑表中标记 ✅。
- 作为 Xshell 的替代,个人使用,macOS、Windows 与 Linux 体验一致。
- 优先补齐每天高频使用的操作(剪贴板、标签页、会话列表),再补 Xshell 的效率功能;不追求逐项对齐 Xshell。
- 行为尽量与 OpenSSH 一致(认证顺序、known_hosts、ssh_config 语义),减少"在 ZShell 里能连、命令行不能连"或反过来的情况。
已实现的功能见下方里程碑表(README 的 Features 是面向用户的英语概述),这里只记录取舍。
- 一条连接复用:终端、SFTP、端口转发共用一条 SSH 连接,不像 Xshell + Xftp 那样各连一次、各认证一次。
- 原生支持 macOS(Xshell 没有 Mac 版)。
- ssh_config 导入、自动重连、转发规则实时状态、"自动"认证。
按计划顺序排列。M17、M19、M21、M22 来自 2026-10 代码审查的设计层面观察,M38 来自 2026-10-16 的架构评审,M39 来自 2026-10-17 的渲染进程内存排查,都属于内部结构调整,用户可见的变化很少。原定的 M33 自定义快捷键已移到下文「暂不排期」,编号空缺。
| 阶段 | 内容 |
|---|---|
| M0 骨架 ✅ | Tauri + React + xterm.js;Channel 二进制输出链路;loopback 会话 |
| M1 MVP ✅ | 密码 / 私钥 / agent 登录;交互式 shell;多标签;resize;known_hosts;会话保存 + 钥匙串 |
| M2 SFTP ✅ | 浏览、上传下载(进度)、拖拽、重命名 / 删除 / 新建 / chmod |
| M3 端口转发 ✅ | -L / -R / -D,规则随会话保存,可自动启动 |
| M4 增强 ✅ | ssh_config 导入、ProxyJump、keepalive 与断线重连、终端搜索、主题;"自动"认证与设置界面 |
| M5 本地终端 ✅ | portable-pty(macOS 登录 shell / Windows PowerShell,ConPTY);输出流控;Windows CI 编译检查 |
| i18n 架构 ✅ | 前端 i18next 与后端消息目录;结构化错误;语言协商;当时仅英语(翻译见 M31) |
| M6 终端与标签页 ✅ | 剪贴板与右键菜单、Option 作为 Meta、标签页操作 |
| M7 ZMODEM ✅ | rz/sz 上传下载 |
| M8 会话管理 ✅ | 分组、搜索、快速连接、复制会话、右键菜单、导出导入 |
| M9 标题栏集成 ✅ | 标签栏画进窗口标题栏,"+" 新建本地终端 |
| M10 批量与效率 ✅ | 撰写栏与同步输入、快速命令、会话日志 |
| M11 SFTP 增强 ✅ | 多选、另存为、拖出、用本地编辑器编辑 |
| M12 会话配置 ✅ | agent 转发、字符编码、单会话外观、登录后命令、TERM 与环境变量 |
| M13 Telnet 与串口 ✅ | 会话类型增加 Telnet 与串口 |
| M14 代理 ✅ | 出口代理(SOCKS5 / HTTP)与 ProxyCommand |
| M15 分屏 ✅ | 标签页内左右 / 上下分屏 |
| M16 known_hosts 管理 ✅ | 查看、搜索、删除主机密钥记录 |
| M17 前端结构 ✅ | 对话框栈、集中的快捷键分发、App.tsx 拆出状态与会话注册 |
| M18 无障碍 ✅ | 终端读屏模式;对话框语义与焦点管理;标签栏、会话列表、文件列表的角色与键盘操作;状态播报;焦点可见、减少动态效果、对比度 |
| M19 前后端类型与配置结构 ✅ | 从 Rust 生成 TypeScript 类型与错误码联合类型;打开会话的命令合并;Profile 按协议拆分(破坏性变更,2.0.0) |
| M20 多因素认证 ✅ | 按服务器返回的剩余方法继续认证(AuthenticationMethods publickey,keyboard-interactive 等) |
| M21 会话生命周期 ✅ | 会话的全部资源由 guard 持有,SessionManager::remove 是唯一的清理入口;页面重载或窗口销毁时关闭所属会话;转发规则由单一所有者持有 |
| M22 大流量与背压 ✅ | 所有后端的输出都有上限:Flow 覆盖 SSH / Telnet / 串口,ZMODEM 接收有界,日志写入移出会话线程;批量传输使用单独的 SFTP channel |
| M23 终端全屏 ✅ | 窗口全屏且只显示当前标签的终端(⌘↩ / F11);快捷键集中声明在一张表里(lib/keymap.ts) |
| M24 状态栏 ✅ | 窗口底部显示当前窗格的连接、上下行活动、终端类型、尺寸与光标位置;调整大小时显示终端尺寸 |
| M25 加密保险库与带密码导出 ✅ | 会话与密码可选加密(主密码 / 系统凭据存储 / 不加密),首次引导;导出 / 导入可带密码(口令加密) |
| M26 应用锁 ✅ | 用 Touch ID / Windows Hello 锁定应用:启动、闲置、系统锁屏或睡眠时,以及手动 |
| M27 多窗口 ✅ | 多个窗口各有自己的标签;标签可以从菜单或拖拽移到新窗口或其他窗口,连接不断开 |
| M28 应用菜单 ✅ | Windows 上由标题栏的图标与名称打开应用菜单;菜单与 macOS 原生菜单由同一份定义生成 |
| M29 检查更新 ✅ | 定期查询 GitHub Release,有新版本时提示(Store 版不检查) |
| M30 Linux ✅ | GNOME + Wayland:自绘标题栏与跟随系统的主题、拖出文件、polkit 应用锁、单实例;deb 与 rpm |
| M31 翻译 ✅ | 语言设置;简体中文、日语、德语、法语;CJK 字体按语言选择 |
| M32 Microsoft Store ✅ | x64 与 ARM64 的 MSIX 上架 Microsoft Store;S 模式下隐藏本地终端 |
| M34 文件面板跟随终端 ✅ | 文件面板在终端所在的文件夹打开,可跟随 shell 切换文件夹;路径栏补全;会话备注 |
| M35 终端与会话细节 ✅ | 响铃(提示音、后台标签与窗口提醒、可选闪屏);后台标签的新输出标记;⌘ / Ctrl+点击打开链接与 OSC 8;用户退出 shell 后关闭窗格;断开的会话在原窗格重连;界面字体;会话列表中会话与文件夹混排(3.2.0–3.3.0) |
| M36 自动读屏模式 ✅ | 系统的读屏软件开启时自动打开终端读屏模式(macOS、Windows、Linux) |
| M37 主机证书 ✅ | 按 known_hosts 的 @cert-authority 接受 CA 签发的主机证书,不必逐台确认主机密钥 |
| M38 架构调整 ✅ | 保存的数据类型独立为 model/;会话的已存密码随路由传入,不经全局变量;存储在保险库解锁后自己重读;连接注册表移出 ssh/;命令集中在 commands/;命令名与事件名由后端生成并检查;前端分为 lib/、ipc/、hooks/;样式按区域有序拆分(3.5.0) |
| M39 React Compiler ✅ | 组件按 Rules of React 改写,由 React Compiler 自动 memo,测试检查每个组件都能编译;侧栏不再随标签页变化重新渲染,标签栏、文件列表、传输列表与快速命令栏只重新渲染变了的那一项(3.6.0) |
| M40 移动窗格 ✅ | 窗格经终端右键菜单或拖动抓手移到新标签页、其他标签页(合并成分屏)或其他窗口;标签可拖到另一标签的窗格旁合并;终端与面板不随标签页重新挂载(3.7.0) |
| M41 终端连字 ✅ | 终端字体的编程连字:关闭、常用序列,或按字体自己的规则(后端读出已安装字体的 GSUB,各终端共用)(3.8.0) |
| M42 终端与系统集成 ✅ | 远端程序经 OSC 序列写入剪贴板(52)、报告进度(9;4)、发出通知(9、777、99)、设置鼠标指针(22)(3.9.0) |
| M43 kitty 键盘协议 | 随 xterm.js 升级打开 kitty 键盘协议,远端的 Claude Code、Cursor CLI、Codex 等能分清 Shift+Enter 与 Enter(等 xterm.js 带上它的正式版) |
| M44 终端图片 | 加载 xterm.js 的图片插件,远端程序可在终端里显示图片(kitty 图形协议、Sixel、iTerm2 内联图片);与 M43 同在下一个 xterm.js 正式版之后,重点是性能 |
| M45 连接期间阻止睡眠 ✅ | 有远程会话连着、正在连接或等待重连时阻止系统闲置睡眠:关、仅接通电源时、始终;熄屏、锁屏、合盖与手动睡眠照旧(3.12.0) |
| M46 收起会话列表 ✅ | 收起左侧的会话列表,标签栏、面板与状态栏不变:开关按钮在标题栏左侧,两种状态下位置不变;应用菜单「显示」里一项,⌃⌘S / Ctrl+Shift+B;收起时搜索会话与新建会话先展开列表(3.13.0) |
| M47 面板收发指示 ✅ | 文件面板的浏览通道与传输、端口转发面板的全部规则与每条规则显示上下行指示灯,传输与转发另有实时速度;状态栏与面板的悬停提示给出连接编号(含本机端口)与通道号。收发改由后端按通道统计,终端的计数含 ZMODEM(3.14.0) |
| M48 文件面板后退与前进 ✅ | 文件面板记住去过的文件夹(含跟随终端时进入的),用工具栏的按钮、鼠标侧键、⌘[ / ⌘](macOS)或 Alt+← / Alt+→ 后退与前进;工具栏重排为两行:第一行是后退、前进、向上、刷新和地址栏,第二行是上传、新建文件夹,以及筛选、隐藏文件、转到终端目录、跟随终端(3.16.0) |
| M49 快捷键随键盘布局 ✅ | 字母与标点快捷键按键帽上的字符匹配(AZERTY、Dvorak、日文键盘等),非拉丁布局退回美式位置;macOS 菜单栏不再自动改写快捷键。Windows / Linux 的拆分窗格改为 Ctrl+Shift+S / Ctrl+Shift+D(Tabby 的键),原来的 Alt+Shift+= / - 照样可用(3.16.0) |
| M50 调试日志 ✅ | 「帮助」菜单打开调试日志窗口,分后端与前端,可按级别过滤、搜索、复制与清空;后端装上 logger,russh 的日志与原来丢掉的 eprintln! 都收进来,连接过程按 OpenSSH -v 的粒度补日志(3.17.0) |
传统编码里 Shift+Enter、Ctrl+Enter 与 Enter 都是 \r,Ctrl+I 与 Tab 也分不开,远端的 agent 只能靠 Option / Alt+Enter(ESC \r)、Ctrl+J 或 \ 加 Enter 换行。kitty 键盘协议让程序用 CSI > flags u 声明自己能理解增强编码,之后 Shift+Enter 发 CSI 13;2u;没有声明的程序照旧收到传统编码。Ghostty、kitty、foot、iTerm2、Alacritty、Windows Terminal 1.25 与 VS Code 都已支持。
- 时机:xterm.js 的实现(xtermjs/xterm.js#5600,2026-01-10 合入,选项
vtExtensions.kittyKeyboard,默认关)只在 6.1.0-beta 里,PR 挂在 7.0.0 里程碑下,没有日期。不提前用 beta:等正式版发布后,和 TODO.md 里几条等 xterm.js 的补丁、绕过一起升级,重做或去掉patches/里的补丁。升级时还要看输入法的问题:xtermjs/xterm.js#6112(程序打开协议后,输入法一次只提交一个字时丢字,在 agent 里打中文正好碰到;修复 #6186 未合入)没修好就照 #6186 打补丁,Linux 上还有 fcitx5 的 #6036 要实测。 - 程序怎么用:Claude Code 2.1.269 起先发
CSI ? u查询,有回应才 push flags 5,所以经 SSH、没有TERM_PROGRAM时也能用;Cursor CLI 不查询,启动时直接 push flags 1,挂起和退出时 pop;Codex 直接 push flags 7,含按键松开事件。xterm.js 实现了查询、push / pop / set、主屏与备用屏各一个栈,编码按协议的各级 flags。 - ZShell 要接的地方:
- 设置:终端设置里加开关,默认开(只在程序请求时生效),输入法等问题出现时用户能关掉;旧的
settings.json照常读取。 lib/terminalReports.ts:查询的回应CSI ? flags u要算作终端回报,否则会同步到其他窗格,也会被当成输入了命令。- 同步输入:现在把源窗格编码好的字节原样转发,源窗格的程序打开了协议而目标窗格没有时,目标的 shell 会收到
CSI 99;5u而不是 Ctrl+C。目标窗格不在协议模式时,在lib/里把 CSI u 解回传统编码再发(纯函数,单元测试),松开事件丢掉。每个窗格的协议状态公开 API 不给,从 xterm.js 内部可选链读取,或注册不拦截的 CSI 处理器自己跟踪,升级时确认。 - 不用改的:会话结束时后端发的软复位(
CSI ! p,SessionSink::reset_modes)在新版 xterm.js 里也清掉协议状态,重连后 shell 不会收到 CSI u;程序崩溃没来得及 pop 时,右键菜单的"重置"能恢复。撰写栏发送的是文本,不经按键编码。
- 设置:终端设置里加开关,默认开(只在程序请求时生效),输入法等问题出现时用户能关掉;旧的
- 测试:临时 sshd 上跑 Cursor CLI 与 Claude Code,Shift+Enter 换行、Enter 发送;macOS 上用拼音输入法往里打中文(含 Shift 打的标点);Option 作 Meta 开与关;Windows 的 AltGr;Linux 的 fcitx5;同步输入时一个窗格跑 agent、一个是普通 shell,Ctrl+C 与方向键都正常。
- 不含:远端 tmux 里的程序(见下文「暂不排期」的 modifyOtherKeys);Windows 本地终端的 win32-input-mode(同一批 PR 里的
vtExtensions.win32InputMode,让 ConPTY 拿到完整按键,VS Code 那边还是实验选项)。
不涉及存储与网络连接,PRIVACY.md 不变。
yazi 的预览、timg / chafa、Neovim 的图片插件、matplotlib 的终端后端等经这三种协议显示图片。@xterm/addon-image(MIT)的 0.10.0-beta 在 Sixel 与 iTerm2 内联图片之外加上了 kitty 图形协议,与 xterm.js 的下一个正式版配套发布;现在 ZShell 没有加载它,图片序列被丢掉。
- 插件的现状(0.10.0-beta.310):kitty 部分只支持把数据直接放在序列里(
t=d,经 SSH 本来也只能这样),不支持文件、共享内存、动画,一张图片只能放在一处;iTerm2 的非内联文件(inline=0)直接丢掉,不会写文件,与下文「不做」里 OSC 1337 的理由不冲突。 - 性能是这个里程碑的重点,每一项都要实测,不合格就收紧限制或不做:
- 内存:图片以 RGBA 存放(每像素 4 字节),插件默认每个终端缓存 128 MB(
storageLimit,满了按先进先出丢掉旧图、留占位块),单张上限约 1600 万像素(pixelLimit),Sixel 解码器还可能常驻pixelLimit× 4 字节。默认值乘上 ZShell 常开的十几个窗格是不可接受的:每个终端的上限要小得多(或按全部终端合计一个预算,后台终端先丢),离开备用屏、清屏、重置时随文本一起释放。用 M39 那次排查的方法看渲染进程内存:开 10 个窗格各显示一批图片、来回切换,再关掉,内存应回落。 - CPU:base64 与 Sixel 解码在主线程(wasm),大图或连续输出(预览器快速翻页、
timg播放动画)时测按键延迟与输出吞吐,不能卡住打字;序列大小有上限(Sixel 25 MB、iTerm2 与 kitty 20 MB),可以再调小。 - GPU 与绘制:图片画在终端上方单独的 2D 画布上(
drawImage),和 WebGL 渲染器的画布叠在一起;后台终端交出 WebGL、改用 DOM 渲染器(lib/webgl.ts)时图片层也要跟着暂停,不能在隐藏页里重画。测滚动带图片的长输出时的帧率与 GPU 占用,以及切换标签时有没有空白帧或残影(TODO 里切换标签空白一帧那一条的录屏方法)。
- 内存:图片以 RGBA 存放(每像素 4 字节),插件默认每个终端缓存 128 MB(
- ZShell 要接的地方:设置里一个开关(默认开),可以再给一个内存上限;插件默认打开
CSI 14 t/16 t等像素尺寸回报(程序据此算图片大小),回报已经在lib/terminalReports.ts的范围内,不会同步到其他窗格;窗格移到其他窗口时靠 serialize 插件重画,图片不在快照里,到新窗口后丢失,要看是否可以接受;文本日志用 vte 解析,APC 与 DCS 里的图片数据不会写进去。 - 测试:临时 sshd 上用
timg、chafa、kitten icat、yazi 显示图片,Sixel 与 kitty 各一遍;窗口缩放与改字号后图片位置;分屏、同步输入、读屏模式下不出错;macOS、Windows、Linux 都看一遍内存与 GPU。
插件与它带的 xterm-wasm-parts 都是 MIT,加入后照常跑 pnpm licenses:generate。不涉及存储与网络连接,PRIVACY.md 不变。
有实际需要时再排期:
- 自定义快捷键:快捷键已集中在
lib/keymap.ts的一张表里(见 ARCHITECTURE.md「快捷键与菜单」),自定义只是在表上叠加用户的覆盖项。settings.json只保存改动过的动作("shortcuts": { "find": ["Ctrl+Shift+F"] }),旧配置照常读取,"恢复默认"即删除覆盖项;设置里 Keyboard Shortcuts 一节的每行可以录制新按键,显示与其他动作的冲突,在 macOS 以外的平台上占用 shell 需要的键(不带 Shift 的 Ctrl+字母)时提示终端将收不到它;成组的动作(⌘1–⌘8、方向键切换窗格)只允许改修饰键;菜单的文字与按键由 M28 的统一定义得出,改快捷键后 Windows 的菜单与 macOS 的原生菜单都要随之重建。 - Microsoft Store 自动提交:现在每个版本在 Partner Center 手动上传(见 DEVELOPMENT.md「发布」)。可以用 Store 提交 API(
msstoreCLI)在 release workflow 里提交,需要把 Entra ID 应用的凭据配成 secret。 - 关键字高亮(如
ERROR标红):需在 xterm.js 的渲染层用 decoration 实现,不能往输出流里插入颜色序列(会破坏全屏程序)。 - X11 转发(macOS 上还要依赖 XQuartz)。
- modifyOtherKeys(
CSI > 4;2 m):tmux 不转发 kitty 键盘协议,只向外层终端要 modifyOtherKeys(终端名不在它认得的表里时,用户还要在 tmux 配置里加terminal-features 'xterm*:extkeys'),所以 M43 之后远端 tmux 里的 agent 仍分不清 Shift+Enter。xterm.js 的 master 也没有实现,要自己在attachCustomKeyEventHandler里编码(CSI 27;2;13~)。tmux 自己的 kitty 支持(tmux#5615)合入后可能就不需要了。 - Linux 上 GNOME 以外的桌面:KDE 的闲置时间(
org.freedesktop.ScreenSaver.GetSessionIdleTime)、X11 的闲置时间(XScreenSaver 扩展)、窗口按钮按各自主题的样式;没有 polkit 认证代理时用 PAM 在锁定界面输入密码。Flatpak 不在计划内(Secret Service 与 polkit 都要经 portal)。
- Xshell 的脚本(VBS / JScript / Python):快速命令和登录后命令能覆盖大多数场景。
- 独立的密钥代理(Xagent):使用系统的 ssh-agent / Pageant / Windows OpenSSH agent。
- 云同步服务:用导出文件配合用户自己的同步盘。
- 在标签里临时切换字符编码:编码在会话配置中设置。
- 探测远端支持的终端类型:SSH 申请 pty 时只发出 TERM 字符串,协议里没有确认;要探测只能先开 exec channel 在远端运行
infocmp,每次连接多一次往返,网络设备、Windows OpenSSH 上也没有这类工具。ZShell 模拟的是 xterm,xterm-256color几乎处处可用。 - iTerm2 的 OSC 1337:一组私有命令,报告当前文件夹已有 OSC 7,其余依赖 iTerm2 自己的概念(profile、badge、用户变量),内联图片
File=还会往下载文件夹写文件,远端程序抢焦点的StealFocus不应支持。 - kitty 的剪贴板协议(OSC 5522):多种 MIME 类型与读取授权,几乎只有 kitty 自己的工具在用,剪贴板插件也只有纯文本与图片。
- 层级上下文标记(OSC 3008):systemd 257 起
run0、容器等发出的上下文开始 / 结束标记(用户、主机、容器),发出它的程序还很少,服务器发行版的 systemd 大多不到 257。