# 🚀 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`