架构——双平面通信

OxideTerm 将终端数据与控制命令分离为两个独立平面：

┌─────────────────────────────────────┐
│        Frontend (React 19)          │
│  xterm.js 6 (WebGL) + 19 stores     │
└──────────┬──────────────┬───────────┘
           │ Tauri IPC    │ WebSocket (binary)
           │ (JSON)       │ per-session port
┌──────────▼──────────────▼───────────┐
│         Backend (Rust)              │
│  NodeRouter → SshConnectionRegistry │
│  Wire Protocol v1                   │
│  [Type:1][Length:4][Payload:n]      │
└─────────────────────────────────────┘

• 数据平面（WebSocket）：每个 SSH 会话获得独立的 WebSocket 端口。终端字节以带有 Type-Length-Payload 头的二进制帧传输——无 JSON 序列化、无 Base64 编码，热路径零开销。
• 控制平面（Tauri IPC）：连接管理、SFTP 操作、转发、配置——结构化 JSON，但不在关键路径上。
• Node 优先寻址：前端从不直接触及 sessionId 或 connectionId。一切通过 nodeId 寻址，由 NodeRouter 在服务端原子解析。SSH 重连会更换底层 connectionId——但 SFTP、IDE 和转发完全不受影响。

🔩 纯 Rust SSH — russh 0.59

整个 SSH 协议栈使用 russh 0.59，基于 ring 加密后端编译：

• 零 C/OpenSSL 依赖——完整的加密栈由 Rust 实现，告别"哪个 OpenSSL 版本？"的调试噩梦。
• 完整的 SSH2 协议：密钥交换、通道、SFTP 子系统、端口转发
• ChaCha20-Poly1305 和 AES-GCM 加密套件，Ed25519/RSA/ECDSA 密钥
• 自定义 AgentSigner：封装系统 SSH Agent 并实现 russh 的 Signer trait，通过在 .await 前将 &AgentIdentity 克隆为 owned 值，解决 RPITIT Send 约束问题

pub struct AgentSigner { /* wraps system SSH Agent */ }
impl Signer for AgentSigner { /* challenge-response via Agent IPC */ }

• 平台支持：Unix（SSH_AUTH_SOCK）、Windows（\\.\pipe\openssh-ssh-agent）
• 代理链：每一跳独立使用 Agent 认证
• 重连：AuthMethod::Agent 自动重放

🔄 智能重连与宽限期

大多数 SSH 客户端在断线时会销毁一切然后从头开始。OxideTerm 的重连编排器采用了截然不同的策略：

1. 检测：WebSocket 心跳超时（300 秒，针对 macOS App Nap 和 JS 定时器节流优化）
2. 快照：完整状态——终端窗格、进行中的 SFTP 传输、活动端口转发、打开的 IDE 文件
3. 智能探测：visibilitychange + online 事件触发主动 SSH keepalive（~2 秒检测 vs 被动超时的 15-30 秒）
4. 宽限期（30 秒）：通过 keepalive 探测旧 SSH 连接——如果恢复成功（例如 WiFi AP 切换），你的 TUI 应用（vim、htop、yazi）完全不受影响
5. 恢复失败 → 建立新 SSH 连接 → 自动恢复转发 → 恢复 SFTP 传输 → 重新打开 IDE 文件

管线流程：queued → snapshot → grace-period → ssh-connect → await-terminal → restore-forwards → resume-transfers → restore-ide → verify → done

所有逻辑运行在专用的 ReconnectOrchestratorStore 中——零重连代码散落在 hooks 或组件中。

🛡️ SSH 连接池

引用计数的 SshConnectionRegistry，以 DashMap 为底层实现无锁并发访问：

• 一个连接，多个消费者：终端、SFTP、端口转发和 IDE 共享同一物理 SSH 连接——无冗余 TCP 握手
• 每连接状态机：connecting → active → idle → link_down → reconnecting
• 生命周期管理：可配置的空闲超时（5 分钟 / 15 分钟 / 30 分钟 / 1 小时 / 永不）、15 秒 keepalive 间隔、心跳故障检测
• WsBridge 心跳：30 秒间隔、5 分钟超时——兼容 macOS App Nap 和浏览器 JS 节流
• 级联传播：跳板机故障 → 所有下游节点自动标记为 link_down 并同步状态
• 空闲断开：向前端发送 connection_status_changed（而非仅内部 node:state），防止 UI 状态不同步

🤖 OxideSens AI

隐私优先的 AI 助手，提供双重交互模式：

• 内联面板（⌘I）：快速终端命令，通过 bracketed paste 注入输出
• 侧边栏聊天：持久对话，完整历史记录
• 面向目标的工作区上下文：把已保存连接、实时 SSH 会话、终端缓冲区、SFTP 路径、设置和知识库条目视为可操作目标
• 已批准的动作：可诊断远程输出、执行已批准命令、检查文件并解释故障，无需 OxideTerm 账号
• MCP 支持：连接外部 Model Context Protocol 服务器（stdio & SSE）进行第三方工具集成
• RAG 知识库（v0.20）：将 Markdown/TXT 文档导入作用域集合（全局或按连接）。混合搜索通过 Reciprocal Rank Fusion 融合 BM25 关键词索引 + 向量余弦相似度。Markdown 感知分块保留标题层级。CJK 双字符分词器支持中文/日文/韩文。
• 供应商：OpenAI、Ollama、DeepSeek、OneAPI 或任何 /v1/chat/completions 端点
• 安全：API 密钥存储在 OS 密钥链；macOS 上密钥读取受 Touch ID 通过 LAContext 保护——无需授权签名或代码签名，每次会话首次认证后缓存

端口转发——无锁 I/O

完整的本地（-L）、远程（-R）和动态 SOCKS5（-D）转发：

• 消息传递架构：SSH Channel 由单一 ssh_io 任务拥有——无 Arc<Mutex<Channel>>，彻底消除互斥锁竞争
• 终止报告：转发任务主动报告退出原因（SSH 断开、远端端口关闭、超时），提供清晰的诊断信息
• 自动恢复：Suspended 状态的转发在重连时自动恢复，无需用户干预
• 空闲超时：FORWARD_IDLE_TIMEOUT（300 秒）防止僵尸连接堆积

📦 trzsz — 带内文件传输

无需 SFTP 连接，直接通过 SSH 终端会话上传和下载文件：

• 带内协议：文件以 Base64 编码帧的形式在现有终端流中传输——无需额外端口或 Agent，可透明穿透 ProxyJump 链和 tmux
• 双向传输：服务端运行 tsz <file> 向客户端发送文件；trz 触发客户端上传；支持拖放
• 目录支持：通过 trz -d / tsz -d 进行递归目录传输
• 传输限制：可为每个会话配置分块大小、文件数量和总字节数上限
• 原生 Tauri I/O：文件读写使用 Tauri 原生文件对话框和 Rust I/O——无浏览器内存限制
• 实时通知：提供传输开始、完成、取消和错误的 Toast 通知——当检测到 trzsz 但功能未启用时也会给出提示
• 前往 设置 → 终端 → 带内传输 启用

🔌 运行时插件系统

动态 ESM 加载，安全加固的冻结 API 表面：

• PluginContext API：18 个命名空间——terminal、ui、commands、settings、lifecycle、events、storage、system
• 24 个 UI Kit 组件：预构建的 React 组件（按钮、输入框、对话框、表格……）通过 window.__OXIDE__ 注入插件沙箱
• 安全膜：对所有上下文对象使用 Object.freeze，基于 Proxy 的 ACL，IPC 白名单，熔断器在重复错误后自动禁用
• 共享模块：React、ReactDOM、zustand、lucide-react 对外暴露供插件使用，无需重复打包

⚡ 自适应渲染

三级渲染调度器，替代固定的 requestAnimationFrame 批处理：

级别切换完全自动——由数据量、用户输入和 Page Visibility API 驱动。后台标签页通过空闲定时器持续刷新数据，无需唤醒 RAF。

🔐 .oxide 加密导出

便携、防篡改的连接备份：

• ChaCha20-Poly1305 AEAD 认证加密
• Argon2id KDF：256 MB 内存开销、4 次迭代——抵御 GPU 暴力破解
• SHA-256 完整性校验
• 可选密钥嵌入：私钥 base64 编码嵌入加密载荷
• 导出前分析：认证类型分类、缺失密钥检测

📡 ProxyJump——拓扑感知多跳

• 无限链深度：Client → Jump A → Jump B → … → Target
• 自动解析 ~/.ssh/config，构建拓扑图，Dijkstra 最短路径寻路
• 跳板节点可作为独立会话复用
• 级联故障传播：跳板机宕机 → 所有下游节点自动标记为 link_down

⚙️ 本地终端——线程安全 PTY

跨平台本地 Shell，基于 portable-pty 0.8，通过 local-terminal feature flag 控制：

• MasterPty 封装在 std::sync::Mutex 中——专用 I/O 线程将阻塞式 PTY 读取隔离在 Tokio 事件循环之外
• Shell 自动检测：zsh、bash、fish、pwsh、Git Bash、WSL2
• cargo build --no-default-features 可剥离 PTY 功能用于移动端/轻量构建

🪟 Windows 优化

• 原生 ConPTY：直接调用 Windows Pseudo Console API——完整 TrueColor 和 ANSI 支持，无传统 WinPTY
• Shell 扫描器：通过注册表和 PATH 自动检测 PowerShell 7、Git Bash、WSL2、CMD

更多功能

• IDE 模式：CodeMirror 6 基于 SFTP，24 种语言，带 Git 状态的文件树，多标签，冲突解决——Linux 可选远程 Agent（~1 MB）以增强功能
• 资源分析器：通过持久 SSH 通道读取 /proc/stat 获取实时 CPU/内存/网络数据，基于增量计算，非 Linux 环境自动降级为仅 RTT
• 自定义主题引擎：30+ 内置主题，可视化编辑器实时预览，20 个 xterm.js 字段 + 24 个 UI 颜色变量，从终端调色板自动推导 UI 颜色
• 会话录制：asciicast v2 格式，完整录制和回放
• 广播输入：输入一次，发送到所有分屏窗格——批量服务器操作
• 背景画廊：每标签页背景图片，16 种标签类型，透明度/模糊/适配控制
• CLI 伴侣工具（oxt）：~1 MB 二进制文件，JSON-RPC 2.0 基于 Unix Socket / Named Pipe，status/health/list/forward/config/connect/focus/attach/SFTP/import/AI 支持人类可读或 --json 输出
• WSL Graphics ⚠️ 实验性：内置 VNC 查看器——9 种桌面环境 + 单应用模式，WSLg 检测，Xtigervnc + noVNC