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`