docs: add project summary with directory tree and feature mapping
This commit is contained in:
191
PROJECT_SUMMARY.md
Normal file
191
PROJECT_SUMMARY.md
Normal file
@@ -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<br/>伪终端 / Shell"]
|
||||
ENGINE["alacritty_terminal<br/>真相源 · ANSI 解析 · 屏幕网格"]
|
||||
WS["Axum WebSocket<br/>session 管理 / 广播"]
|
||||
end
|
||||
|
||||
subgraph Desktop["rtty-desktop (Flutter Windows)"]
|
||||
BACKEND["RttyPtyBackend<br/>WebSocket 桥接"]
|
||||
DENGINE["flutter_alacritty<br/>Alacritty 引擎渲染"]
|
||||
end
|
||||
|
||||
subgraph Mobile["rtty-mobile (Flutter)"]
|
||||
MCLIENT["RttyMobileClient<br/>语义快照消费"]
|
||||
MUI["卡片化 / 换行 / Keybar"]
|
||||
end
|
||||
|
||||
PTY --> ENGINE --> WS
|
||||
WS -->|"原始 ANSI 二进制帧<br/>client=desktop"| BACKEND --> DENGINE
|
||||
WS -->|"语义化 JSON 快照<br/>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`
|
||||
Reference in New Issue
Block a user