From 339fbe357f70d2138953d53d192b4983ed2f11e5 Mon Sep 17 00:00:00 2001 From: CNWei Date: Sat, 1 Aug 2026 22:28:49 +0800 Subject: [PATCH] docs: add project summary with directory tree and feature mapping --- PROJECT_SUMMARY.md | 191 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 PROJECT_SUMMARY.md diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md new file mode 100644 index 0000000..0248312 --- /dev/null +++ b/PROJECT_SUMMARY.md @@ -0,0 +1,191 @@ +# 🚀 Rtty 项目实现总结与目录导航 + +> **Rtty** 是一款基于 Rust + Flutter 构建的高性能、跨平台分布式虚拟终端系统。 +> 服务端（Rust + Alacritty 引擎）在内存中维持"真相源"，通过 WebSocket 与各端解耦； +> 桌面端（Flutter + `flutter_alacritty`）共享同一 Alacritty 引擎做工业级 ANSI 渲染； +> 移动端（Flutter）消费语义化快照做卡片化重排。 + +--- + +## 一、总体架构 + +```mermaid +flowchart LR + subgraph Server["rtty-server (Rust)"] + PTY["portable-pty
伪终端 / Shell"] + ENGINE["alacritty_terminal
真相源 · ANSI 解析 · 屏幕网格"] + WS["Axum WebSocket
session 管理 / 广播"] + end + + subgraph Desktop["rtty-desktop (Flutter Windows)"] + BACKEND["RttyPtyBackend
WebSocket 桥接"] + DENGINE["flutter_alacritty
Alacritty 引擎渲染"] + end + + subgraph Mobile["rtty-mobile (Flutter)"] + MCLIENT["RttyMobileClient
语义快照消费"] + MUI["卡片化 / 换行 / Keybar"] + end + + PTY --> ENGINE --> WS + WS -->|"原始 ANSI 二进制帧
client=desktop"| BACKEND --> DENGINE + WS -->|"语义化 JSON 快照
client=mobile"| MCLIENT --> MUI +``` + +--- + +## 二、目录树状图与功能对应 + +### 1. 服务端内核 `src/`（Rust） + +``` +src/ +├── main.rs # 程序入口：全局 AppState（会话表）、Axum 路由、配置加载 +├── config.rs # ServerConfig：host/port/shell/尺寸/scrollback/并发限制/空闲超时（环境变量 RTTY_* 可覆盖） +├── terminal/ # 终端核心（PTY + Alacritty 引擎） +│ ├── mod.rs # terminal 模块声明 +│ ├── pty.rs # PtySession：portable-pty 伪终端封装（拉起 Shell、读写、resize、kill） +│ └── engine.rs # TerminalEngine：alacritty_terminal 封装（ANSI 解析、网格维护、语义快照生成、PtyWrite 回写） +└── ws/ # WebSocket 通信层 + ├── mod.rs # ws 模块声明 + ├── protocol.rs # 协议：ClientMessage（input/resize/claim_control/ping）、ServerMessage（ready/snapshot/control/error/session_closed）、MobileSnapshot + └── handler.rs # 会话管理：多端解耦广播、并发限制、控制权强制、会话清理（EOF + 进程监控 + 空闲超时） +``` + +| 功能 | 对应文件 | +|------|---------| +| 伪终端创建 / Shell 拉起 / 读写 / resize | `src/terminal/pty.rs` | +| ANSI 解析 / 屏幕网格 / 滚动历史 / 语义快照 | `src/terminal/engine.rs` | +| 断线重连状态恢复（初始快照） | `src/ws/handler.rs` | +| 多端解耦（PC 收 ANSI、移动收快照） | `src/ws/handler.rs` | +| 控制权强制（非控制者输入被拒） | `src/ws/handler.rs` | +| 会话清理（泄漏防护） | `src/ws/handler.rs` | +| 配置加载（环境变量） | `src/config.rs` | + +--- + +### 2. 桌面端 `desktop/`（Flutter Windows） + +``` +desktop/ +├── lib/ +│ ├── main.dart # 入口：初始化 RustLib（flutter_rust_bridge）后启动应用 +│ └── src/ +│ ├── rtty_pty_backend.dart # RttyPtyBackend：实现 flutter_alacritty 的 PtyBackend 接口，桥接 WebSocket +│ ├── terminal_config.dart # RttyTerminalConfig：把 Rtty 配色/字体映射为 Alacritty TerminalConfig +│ ├── terminal_screen.dart # 主页面：TerminalEngine + TerminalView、连接控制、resize 防抖、双向接线 +│ ├── connection_bar.dart # 顶部连接控制条：状态灯、host/port/session 输入、会话徽章、连接按钮 +│ └── theme.dart # 工业终端主题（深炭黑 + 磷光青绿） +├── test/ # 单元测试（服务端离线时集成测试自动跳过） +│ ├── e2e_ws_test.dart # RttyPtyBackend 连真实服务端接收原始 ANSI 输出 +│ ├── regression_ws_test.dart# 多端解耦 + 控制权强制 + 会话清理回归 +│ ├── support.dart # 测试共享工具（服务端探测） +│ └── widget_test.dart # Widget 渲染测试 +├── integration_test/ # 真实 Windows 桌面集成测试 +│ ├── e2e_test.dart # 连接 + 渲染 + 命令回显闭环 +│ └── cd_resize_test.dart # cd 跨目录 + resize 内容完整性 +├── windows/ # Windows 平台 CMake/runner（flutter 生成） +├── pubspec.yaml # 依赖：web_socket_channel、flutter_alacritty +└── README.md # 桌面端说明 +``` + +| 功能 | 对应文件 | +|------|---------| +| Alacritty Rust 引擎初始化 | `lib/main.dart`（`await RustLib.init()`） | +| WebSocket ↔ PtyBackend 桥接（远程数据源） | `lib/src/rtty_pty_backend.dart` | +| 引擎接线（输出喂渲染、输入回传服务端） | `lib/src/terminal_screen.dart` | +| 100% 工业级 ANSI 渲染（vim/htop/tmux） | `lib/src/terminal_screen.dart` + `flutter_alacritty` | +| resize 防抖（TUI resize 稳定性） | `lib/src/terminal_screen.dart` | +| 连接控制条 / 会话管理 | `lib/src/connection_bar.dart` | +| 主题 / 配色 | `lib/src/theme.dart`、`lib/src/terminal_config.dart` | + +--- + +### 3. 移动端 `mobile/`（Flutter） + +``` +mobile/ +├── lib/ +│ ├── main.dart # 入口 +│ └── src/ +│ ├── rtty_mobile_client.dart # RttyMobileClient：消费 mobile_snapshot 语义快照，发送 input/resize/claim_control +│ └── theme.dart # 移动端主题（卡片化美学） +├── android/ # Android 平台工程（flutter 生成） +├── ios/ # iOS 平台工程（flutter 生成） +└── pubspec.yaml # 依赖：web_socket_channel +``` + +> ⚠️ **当前状态**：移动端为脚手架骨架（客户端连接层与主题已就绪），卡片化重排、Keybar 等核心 UI 尚未实现，尚未提交 Git。这是规划中的下一个里程碑。 + +| 功能 | 对应文件 | +|------|---------| +| 语义快照 WebSocket 消费 | `mobile/lib/src/rtty_mobile_client.dart` | +| 智能换行 / 卡片化 / Keybar | ⏳ 待实现 | + +--- + +### 4. 根目录其他文件 + +``` +Rtty/ +├── src/ # 服务端源码（见上） +├── desktop/ # 桌面端（见上） +├── mobile/ # 移动端（见上） +├── Cargo.toml # 服务端依赖与 release 优化配置 +├── Cargo.lock # Rust 依赖锁 +├── README.md # 项目设计总结与架构指南 +├── LICENSE # 许可证 +└── .gitignore # 忽略 target/.idea/Cargo.lock 等 +``` + +--- + +## 三、核心功能清单（实现 vs 规划） + +| 功能 | 服务端 | 桌面端 | 移动端 | 状态 | +|------|:---:|:---:|:---:|:---:| +| PTY / Shell 会话 | ✅ | — | — | 已实现 | +| Alacritty 引擎（ANSI 解析 / 网格） | ✅ | ✅ | — | 已实现 | +| 多端状态保持（断线重连恢复） | ✅ | ✅ | ⏳ | 已实现 | +| 多端解耦（PC ANSI / 移动快照） | ✅ | ✅ | ⏳ | 已实现 | +| 控制权强制 | ✅ | — | ⏳ | 已实现 | +| 会话清理（空闲超时） | ✅ | — | — | 已实现 | +| 100% 工业级 ANSI 渲染 | — | ✅ | — | 已实现 | +| 命令执行 / cd / TUI resize 稳定 | — | ✅ | — | 已实现 | +| 智能文本换行（Word Wrap） | — | — | ⏳ | 规划 | +| 卡片化命令交互 | — | — | ⏳ | 规划 | +| 移动端 Keybar | — | — | ⏳ | 规划 | +| 分布式横向扩展 | ⏳ | — | — | 规划 | +| 服务端鉴权 | ⏳ | — | — | 规划 | + +--- + +## 四、运行与构建 + +```bash +# 1. 服务端（仓库根目录） +cargo run # 监听 ws://0.0.0.0:8080 + +# 2. 桌面端 +cd desktop +flutter run -d windows # 运行 +flutter build windows --release # 构建（含 Rust 引擎编译） + +# 3. 测试 +cargo test # 服务端 +flutter test # 桌面端单元测试（服务端离线时集成测试跳过） +flutter test integration_test -d windows # 桌面端真实桌面集成测试 +``` + +--- + +## 五、目录导航速查 + +- **要改终端解析/网格逻辑** → `src/terminal/engine.rs` +- **要改 PTY/进程管理** → `src/terminal/pty.rs` +- **要改协议/消息格式** → `src/ws/protocol.rs` +- **要改会话/多端/清理逻辑** → `src/ws/handler.rs` +- **要改桌面端连接桥接** → `desktop/lib/src/rtty_pty_backend.dart` +- **要改桌面端渲染/接线** → `desktop/lib/src/terminal_screen.dart` +- **要改桌面端 UI/主题** → `desktop/lib/src/connection_bar.dart`、`theme.dart` +- **要改移动端连接层** → `mobile/lib/src/rtty_mobile_client.dart`