Kiến trúc — Giao tiếp hai mặt phẳng

OxideTerm tách dữ liệu terminal khỏi lệnh điều khiển thành hai mặt phẳng độc lập:

┌─────────────────────────────────────┐
│        Frontend (React 19)          │
│  xterm.js 6 (WebGL) + 19 stores     │
└──────────┬──────────────┬───────────┘
           │ Tauri IPC    │ WebSocket (nhị phân)
           │ (JSON)       │ cổng mỗi phiên
┌──────────▼──────────────▼───────────┐
│         Backend (Rust)              │
│  NodeRouter → SshConnectionRegistry │
│  Wire Protocol v1                   │
│  [Type:1][Length:4][Payload:n]      │
└─────────────────────────────────────┘

• Mặt phẳng dữ liệu (WebSocket): mỗi phiên SSH có cổng WebSocket riêng. Các byte terminal chảy dưới dạng khung nhị phân với header Type-Length-Payload — không JSON serialization, không mã hóa Base64, không overhead trên đường dẫn nóng.
• Mặt phẳng điều khiển (Tauri IPC): quản lý kết nối, thao tác SFTP, chuyển tiếp, cấu hình — JSON có cấu trúc, nhưng ngoài đường dẫn nóng.
• Định danh theo nút: frontend không bao giờ chạm sessionId hay connectionId. Mọi thứ được định danh bằng nodeId, được giải quyết nguyên tử phía máy chủ bởi NodeRouter. Kết nối lại SSH thay đổi connectionId bên dưới — nhưng SFTP, IDE và chuyển tiếp hoàn toàn không bị ảnh hưởng.

🔩 SSH thuần Rust — russh 0.59

Toàn bộ ngăn xếp SSH là russh 0.59 biên dịch với backend mật mã ring:

• Không phụ thuộc C/OpenSSL — toàn bộ ngăn xếp mật mã là Rust. Không còn debug "phiên bản OpenSSL nào?".
• Giao thức SSH2 đầy đủ: trao đổi khóa, kênh, hệ thống con SFTP, chuyển tiếp cổng
• Bộ mật mã ChaCha20-Poly1305 và AES-GCM, khóa Ed25519/RSA/ECDSA
• AgentSigner tùy chỉnh: bọc SSH Agent hệ thống và thực thi trait Signer của russh, giải quyết vấn đề ràng buộc Send RPITIT bằng cách clone &AgentIdentity thành giá trị owned trước khi vượt qua .await

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

• Hỗ trợ nền tảng: Unix (SSH_AUTH_SOCK), Windows (\\.\pipe\openssh-ssh-agent)
• Chuỗi proxy: mỗi bước nhảy sử dụng xác thực Agent độc lập
• Kết nối lại: AuthMethod::Agent được phát lại tự động

🔄 Kết nối lại thông minh với thời gian ân hạn

Hầu hết client SSH hủy mọi thứ khi ngắt kết nối và bắt đầu lại từ đầu. Bộ điều phối kết nối lại của OxideTerm áp dụng cách tiếp cận khác biệt cơ bản:

1. Phát hiện hết thời gian heartbeat WebSocket (300 giây, được hiệu chỉnh cho macOS App Nap và throttling bộ hẹn giờ JS)
2. Chụp ảnh toàn bộ trạng thái: bảng terminal, chuyển SFTP đang thực hiện, chuyển tiếp cổng đang hoạt động, tệp IDE đang mở
3. Thăm dò thông minh: sự kiện visibilitychange + online kích hoạt keepalive SSH chủ động (~2 giây phát hiện so với 15–30 giây timeout thụ động)
4. Thời gian ân hạn (30 giây): thăm dò kết nối SSH cũ qua keepalive — nếu phục hồi (ví dụ: chuyển điểm truy cập WiFi), ứng dụng TUI của bạn (vim, htop, yazi) sống sót hoàn toàn
5. Nếu phục hồi thất bại → kết nối SSH mới → tự động khôi phục chuyển tiếp → tiếp tục chuyển SFTP → mở lại tệp IDE

Pipeline: queued → snapshot → grace-period → ssh-connect → await-terminal → restore-forwards → resume-transfers → restore-ide → verify → done

Toàn bộ logic chạy qua một ReconnectOrchestratorStore chuyên dụng — không có mã kết nối lại rải rác trong hooks hay components.

🛡️ Pool kết nối SSH

SshConnectionRegistry đếm tham chiếu dựa trên DashMap cho truy cập đồng thời không khóa:

• Một kết nối, nhiều người dùng: terminal, SFTP, chuyển tiếp cổng và IDE chia sẻ một kết nối SSH vật lý duy nhất — không bắt tay TCP dư thừa
• Máy trạng thái mỗi kết nối: connecting → active → idle → link_down → reconnecting
• Quản lý vòng đời: hết thời gian nhàn rỗi có thể cấu hình (5 phút / 15 phút / 30 phút / 1 giờ / không bao giờ), khoảng keepalive 15 giây, phát hiện lỗi heartbeat
• Heartbeat WsBridge: khoảng 30 giây, hết thời gian 5 phút — chịu được macOS App Nap và throttling JS trình duyệt
• Lan truyền dây chuyền: lỗi máy chủ nhảy → tất cả nút hạ nguồn tự động đánh dấu link_down với đồng bộ trạng thái
• Ngắt kết nối nhàn rỗi: phát connection_status_changed tới frontend (không chỉ node:state nội bộ), ngăn mất đồng bộ giao diện

🤖 OxideSens AI

Trợ lý AI ưu tiên quyền riêng tư với hai chế độ tương tác:

• Bảng inline (⌘I): lệnh terminal nhanh, đầu ra được tiêm qua bracketed paste
• Trò chuyện thanh bên: cuộc trò chuyện liên tục với lịch sử đầy đủ
• Ngữ cảnh workspace hướng mục tiêu: xem kết nối đã lưu, phiên SSH đang chạy, bộ đệm terminal, đường dẫn SFTP, cài đặt và mục trong cơ sở kiến thức như các mục tiêu của workspace
• Hành động đã phê duyệt: có thể chẩn đoán output từ xa, chạy lệnh đã được phê duyệt, kiểm tra tệp và giải thích lỗi mà không cần tài khoản OxideTerm
• Hỗ trợ MCP: kết nối máy chủ Model Context Protocol bên ngoài (stdio & SSE) cho tích hợp công cụ bên thứ ba
• Cơ sở kiến thức RAG (v0.20): nhập tài liệu Markdown/TXT vào bộ sưu tập có phạm vi (toàn cục hoặc mỗi kết nối). Tìm kiếm lai kết hợp chỉ mục từ khóa BM25 + tương đồng cosine vector qua Reciprocal Rank Fusion. Phân đoạn nhận biết Markdown bảo tồn phân cấp tiêu đề. Tokenizer bigram CJK cho tiếng Trung/Nhật/Hàn.
• Nhà cung cấp: OpenAI, Ollama, DeepSeek, OneAPI, hoặc bất kỳ endpoint /v1/chat/completions nào
• Bảo mật: khóa API lưu trong chuỗi khóa hệ điều hành; trên macOS, đọc khóa được bảo vệ bởi Touch ID qua LAContext — không cần entitlement hay ký mã, được cache sau lần xác thực đầu tiên mỗi phiên

Chuyển tiếp cổng — I/O không khóa

Chuyển tiếp cục bộ (-L), từ xa (-R) và SOCKS5 động (-D) đầy đủ:

• Kiến trúc truyền thông điệp: kênh SSH thuộc sở hữu của một task ssh_io duy nhất — không Arc<Mutex<Channel>>, loại bỏ hoàn toàn tranh chấp mutex
• Báo cáo ngừng hoạt động: các task chuyển tiếp chủ động báo cáo lý do thoát (ngắt SSH, đóng cổng từ xa, hết thời gian) để chẩn đoán rõ ràng
• Tự động khôi phục: chuyển tiếp Suspended tự động tiếp tục khi kết nối lại mà không cần can thiệp người dùng
• Hết thời gian nhàn rỗi: FORWARD_IDLE_TIMEOUT (300 giây) ngăn tích tụ kết nối zombie

📦 trzsz — Truyền Tệp Tích Hợp

Tải lên và tải xuống tệp trực tiếp qua phiên SSH — không cần kết nối SFTP:

• Giao thức tích hợp: tệp được truyền dưới dạng các frame Base64 trong luồng terminal hiện có — hoạt động trong suốt qua chuỗi ProxyJump và tmux mà không cần cổng hoặc agent bổ sung
• Hai chiều: server chạy tsz <tệp> để gửi tệp đến client; trz kích hoạt tải lên từ client; hỗ trợ kéo và thả
• Hỗ trợ thư mục: truyền đệ quy qua trz -d / tsz -d
• Giới hạn truyền tệp: giới hạn có thể cấu hình theo phiên cho kích thước chunk, số lượng tệp và tổng byte
• I/O Tauri gốc: đọc và ghi tệp sử dụng hộp thoại tệp gốc của Tauri và Rust I/O — không bị giới hạn bộ nhớ trình duyệt
• Thông báo trực tiếp: thông báo Toast cho bắt đầu, hoàn thành, hủy và lỗi — bao gồm gợi ý khi phát hiện trzsz nhưng tính năng bị tắt
• Bật trong Cài đặt → Thiết bị đầu cuối → Truyền tệp tích hợp

🔌 Hệ thống plugin runtime

Tải ESM động với bề mặt API đóng băng và được tăng cường bảo mật:

• API PluginContext: 18 không gian tên — terminal, ui, commands, settings, lifecycle, events, storage, system
• 24 thành phần UI Kit: thành phần React dựng sẵn (nút, trường nhập liệu, hộp thoại, bảng…) được tiêm vào sandbox plugin qua window.__OXIDE__
• Màng bảo mật: Object.freeze trên tất cả đối tượng ngữ cảnh, ACL dựa trên Proxy, whitelist IPC, ngắt mạch với tự động vô hiệu hóa sau lỗi lặp lại
• Module chia sẻ: React, ReactDOM, zustand, lucide-react được cung cấp cho plugin sử dụng mà không trùng lặp bundle

⚡ Kết xuất thích ứng

Bộ lập lịch kết xuất ba tầng thay thế batching cố định requestAnimationFrame:

Các chuyển đổi hoàn toàn tự động — được điều khiển bởi lượng dữ liệu, đầu vào người dùng và API Page Visibility. Tab nền tiếp tục xả dữ liệu qua bộ hẹn giờ nhàn rỗi mà không đánh thức RAF.

🔐 Xuất mã hóa .oxide

Sao lưu kết nối di động, chống giả mạo:

• Mã hóa xác thực ChaCha20-Poly1305 AEAD
• KDF Argon2id: chi phí bộ nhớ 256 MB, 4 vòng lặp — chống brute-force GPU
• Checksum toàn vẹn SHA-256
• Nhúng khóa tùy chọn: khóa riêng tư được mã hóa base64 trong payload đã mã hóa
• Phân tích trước: phân tích loại xác thực, phát hiện khóa thiếu trước khi xuất

📡 ProxyJump — Đa chặng nhận biết topo

• Độ sâu chuỗi không giới hạn: Client → Chặng A → Chặng B → … → Đích
• Tự động phân tích ~/.ssh/config, xây dựng đồ thị topo, tìm đường Dijkstra cho tuyến tối ưu
• Nút nhảy tái sử dụng như phiên độc lập
• Lan truyền lỗi dây chuyền: máy chủ nhảy hỏng → tất cả nút hạ nguồn tự động đánh dấu link_down

⚙️ Terminal cục bộ — PTY an toàn luồng

Shell cục bộ đa nền tảng qua portable-pty 0.8, được bảo vệ bởi feature gate local-terminal:

• MasterPty bọc trong std::sync::Mutex — luồng I/O chuyên dụng giữ đọc PTY chặn khỏi vòng lặp sự kiện Tokio
• Tự động phát hiện shell: zsh, bash, fish, pwsh, Git Bash, WSL2
• cargo build --no-default-features loại bỏ PTY cho bản build di động/nhẹ

🪟 Tối ưu hóa Windows

• ConPTY gốc: gọi trực tiếp API Windows Pseudo Console — hỗ trợ đầy đủ TrueColor và ANSI, không có WinPTY cũ
• Quét shell: tự động phát hiện PowerShell 7, Git Bash, WSL2, CMD qua Registry và PATH

Và nhiều hơn nữa

• Chế độ IDE: CodeMirror 6 qua SFTP, 24 ngôn ngữ, cây tệp với trạng thái Git, đa tab, giải quyết xung đột — agent từ xa tùy chọn (~1 MB) cho các tính năng nâng cao trên Linux
• Trình phân tích tài nguyên: CPU/bộ nhớ/mạng trực tiếp qua kênh SSH liên tục đọc /proc/stat, tính toán dựa trên delta, tự động giảm xuống chỉ RTT trên hệ thống không phải Linux
• Công cụ giao diện tùy chỉnh: 30+ giao diện tích hợp, trình biên tập trực quan với xem trước trực tiếp, 20 trường xterm.js + 24 biến màu UI, tự động suy diễn màu UI từ bảng màu terminal
• Ghi phiên: định dạng asciicast v2, ghi và phát lại đầy đủ
• Phát sóng đầu vào: gõ một lần, gửi đến tất cả bảng chia — thao tác máy chủ hàng loạt
• Thư viện nền: hình nền từng tab, 16 loại tab, điều khiển độ mờ/làm mờ/khớp
• CLI đồng hành (oxt): nhị phân ~1 MB, JSON-RPC 2.0 qua Unix Socket / Named Pipe, status/health/list/forward/config/connect/focus/attach/SFTP/import/AI với đầu ra dạng người đọc hoặc --json
• WSL Graphics ⚠️ thử nghiệm: trình xem VNC tích hợp — 9 môi trường desktop + chế độ ứng dụng đơn, phát hiện WSLg, Xtigervnc + noVNC