diff --git a/README.md b/README.md
new file mode 100644
index 0000000..47e8cdb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,275 @@
+# VDI 云桌面项目
+
+本项目是一套面向企业云桌面场景的“云—管—端”VDI 解决方案，目标是在 RK3528 云终端上提供统一的用户登录、云桌面选择、远程会话接入、设备管理和运维能力。
+
+当前仓库采用 monorepo 结构，包含终端嵌入式软件、云端服务、Web 管理控制台、部署配置和配套工具。
+
+> 当前开发阶段：终端 POC 与产品流程验证。仓库内已实现的功能、已验证的功能和规划功能会在本文档中分别标注。
+
+## 一、项目目标
+
+终端产品的目标使用流程：
+
+```text
+盒子开机
+  -> kiosk-shell 登录/首配
+  -> 用户认证
+  -> 获取可用云桌面列表
+  -> 用户选择 Windows / Ubuntu / 麒麟等桌面
+  -> 获取一次性连接票据
+  -> 根据协议启动 RDP 或 Moonlight 会话
+  -> 会话结束后返回桌面列表
+```
+
+总体系统关系：
+
+```text
+RK3528 云终端
+  -> 自研管理平台 API
+  -> Proxmox VE / KVM 虚拟化平台
+  -> Windows / Ubuntu / 麒麟云桌面
+```
+
+终端不会直接调用 Proxmox API。桌面生命周期、用户授权、连接信息和协议策略统一由管理平台下发。
+
+## 二、仓库结构
+
+```text
+vdi-cloud/
+├─ terminal/                    # 终端嵌入式软件
+│  ├─ meta-vdi/                 # Yocto 层：BSP、内核、设备树、U-Boot、配方
+│  ├─ kiosk-shell/              # Qt 全屏壳：登录、桌面列表、远程会话
+│  ├─ freerdp-rk/               # FreeRDP 3 与 Rockchip MPP/VPU 适配
+│  ├─ vdt-agent/                # Rust：注册、心跳、命令、日志
+│  ├─ ota-updater/              # Rust：OTA 签名校验、A/B 切换、回滚
+│  └─ usb-monitor/              # Rust：USB 监听、挂载与重定向策略
+├─ platform/                    # Go 云端服务
+├─ console/                     # Vue 3 + TypeScript Web 管理控制台
+├─ deploy/                      # Docker Compose、Helm、离线部署包
+├─ docs/                        # OpenAPI、MQTT、数据库等正式协议文档
+└─ tools/                       # 烧录、构建、压测和 CI 工具
+```
+
+当前有实现代码的模块为 `terminal/kiosk-shell`，其余模块保留目录结构，后续按里程碑逐步开发。
+
+## 三、当前功能
+
+### 1. 终端登录与桌面列表
+
+已实现：
+
+- Qt 全屏登录页；
+- 设备 SN 和网络状态显示；
+- 本地演示认证（当前账号和密码非空即可通过）；
+- Windows、Ubuntu、麒麟三类桌面卡片；
+- Windows 桌面当前可通过 Moonlight 连接；
+- Ubuntu、麒麟当前显示“待分配”，不会启动无效会话；
+- 退出登录后返回登录页；
+- 会话退出后返回桌面列表。
+
+本地演示认证是后端 API 上线前的临时实现。后续通过 `DesktopService` 适配层接入真实的用户认证、桌面列表和一次性连接票据接口，页面流程不需要重写。
+
+### 2. RDP 会话
+
+已实现：
+
+- 基于 `libfreerdp3` API 内嵌，不拉起外部 `xfreerdp` 进程；
+- FreeRDP GDI/GFX 画面接入 Qt；
+- 键盘、鼠标输入转发；
+- X11 键盘码到 RDP 扫描码映射；
+- 鼠标缩放坐标转换；
+- 会话状态与断线重连；
+- `Ctrl+Alt+Shift+M` 管理菜单；
+- RDP 后端代码保留，可由连接票据选择启用。
+
+当前 RDP 路径仍处于 POC 阶段，证书忽略、测试账号等配置不能直接用于正式环境。
+
+### 3. Moonlight/Sunshine 会话
+
+已实现：
+
+- `MoonlightSession` 使用 `QProcess` 参数数组启动 `moonlight-qt`；
+- 不通过 Shell 拼接用户输入，降低命令注入风险；
+- H.264 软件解码；
+- 绝对鼠标模式；
+- 会话进程退出后自动返回桌面列表；
+- `vsync`、`frame-pacing`、性能叠图等低延迟参数可配置；
+- 独立 Moonlight 启动脚本保留作调试用途，但不再作为产品开机入口。
+
+当前联调环境中，Sunshine 服务端仍使用 `libx264` 软件编码。1080p 实际帧率约 13～22 FPS，鼠标体感延迟主要来自服务端软编码和客户端帧队列/VSync。后续需要完成 GPU 直通并启用 NVENC。
+
+### 4. 状态机
+
+当前终端状态机：
+
+```text
+BOOT
+  -> CONFIG / LOGIN
+  -> AUTHENTICATING
+  -> DESKTOP_LIST
+  -> CONNECTING
+  -> SESSION
+  -> RECONNECT
+  -> DESKTOP_LIST / ERROR
+```
+
+### 5. Monitor 看门狗
+
+已实现独立 `vdi-kiosk-monitor` 进程：
+
+- 监控 kiosk-shell 进程是否退出；
+- 通过心跳文件检测主进程假死；
+- 异常退出后自动重启；
+- 连续启动失败后熔断；
+- 子进程独立进程组，结束时清理整棵进程树，避免遗留孤儿串流进程。
+
+## 四、技术栈
+
+### 终端
+
+- C++17
+- Qt 5 Widgets
+- FreeRDP 3
+- Moonlight Qt
+- 当前开发环境：Armbian + LightDM + Xorg
+- 正式目标环境：Weston + Wayland
+
+### 云端（规划）
+
+- Go
+- PostgreSQL
+- VictoriaMetrics
+- HTTPS + MQTT
+- Proxmox VE / KVM / VFIO
+
+### Web 控制台（规划）
+
+- Vue 3
+- TypeScript
+- Vite
+- Element Plus
+
+## 五、构建 kiosk-shell
+
+### 1. 依赖
+
+目标设备或 ARM64 构建环境需要：
+
+```bash
+sudo apt install \
+  build-essential cmake ninja-build pkg-config \
+  qtbase5-dev libqt5widgets5 \
+  freerdp3-dev
+```
+
+Moonlight 会话还需要安装：
+
+```bash
+sudo apt install moonlight-qt
+```
+
+### 2. 编译
+
+```bash
+cd terminal/kiosk-shell
+cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+编译产物：
+
+```text
+build/kiosk-shell
+build/vdi-kiosk-monitor
+```
+
+### 3. 运行
+
+在当前 X11 开发环境中：
+
+```bash
+export DISPLAY=:0
+export XAUTHORITY="$HOME/.Xauthority"
+
+./build/vdi-kiosk-monitor -- ./build/kiosk-shell
+```
+
+产品自启入口为：
+
+```text
+vdi-kiosk-monitor -> kiosk-shell
+```
+
+Moonlight 只能在用户登录并选择桌面后由 kiosk-shell 启动，不应与 kiosk-shell 分别设置开机自启。
+
+## 六、本地配置
+
+终端基础配置路径：
+
+```text
+~/.config/vdi-terminal/client.conf
+```
+
+Moonlight 调试配置路径：
+
+```text
+~/.config/vdi-terminal/moonlight.conf
+```
+
+当前配置文件仅用于 POC。正式版本中，终端身份、配置版本和连接策略应由 `vdt-agent` 从管理平台同步。
+
+不要将以下信息提交到仓库：
+
+- Windows 或平台账号密码；
+- Proxmox root 密码；
+- Gitea 密码或访问令牌；
+- 终端设备密钥；
+- Sunshine 管理账号密码；
+- 私钥、证书和一次性连接票据。
+
+## 七、当前联调环境
+
+| 项目 | 当前环境 |
+|---|---|
+| 终端硬件 | RK3528 PRO DDR4 |
+| 终端架构 | ARM64 |
+| 终端系统 | Armbian / Ubuntu Noble |
+| 图形环境 | LightDM + Xorg（POC） |
+| 云平台 | Proxmox VE 9 |
+| Windows 云桌面 | Windows 10 22H2 |
+| Moonlight 服务端 | Sunshine |
+| 当前串流分辨率 | 1920×1080@60Hz |
+
+具体 IP、测试账号和密码不写入 README，统一通过本地配置或部署环境变量管理。
+
+## 八、已知限制
+
+1. 终端用户认证、桌面列表和连接票据目前是本地演示实现，尚未接管理平台 API；
+2. Ubuntu 和麒麟桌面尚未配置实际连接地址；
+3. 当前 Moonlight 使用软件解码，RK3528 的 VPU/MPP 硬解尚未打通；
+4. Sunshine 当前使用软件编码，未启用 NVENC；
+5. 当前仍是 X11 POC，尚未完成 Weston/Wayland/DRM 零拷贝路径；
+6. RDP 证书校验、短期凭据和正式安全策略尚未完成；
+7. USB 重定向、OTA、Agent、管理平台和 Web 控制台尚未开发完成。
+
+## 九、下一步计划
+
+按优先级：
+
+1. 恢复 RK3528 盒子网络并部署登录/桌面列表新版本；
+2. 实测 Moonlight `no-vsync` / `no-frame-pacing` 对鼠标延迟的改善；
+3. 将 GTX 965M 直通 Windows VM，使 Sunshine 使用 NVENC；
+4. 定义并联调终端用户认证、桌面列表和一次性连接票据 API；
+5. 实现 Ubuntu、麒麟桌面连接配置；
+6. 适配 RK3528 MPP/VPU 硬解；
+7. 切换到 Weston/Wayland 正式显示路径；
+8. 开发 `vdt-agent`、OTA、USB、云端服务和 Web 控制台。
+
+## 十、开发规范
+
+- 已验证、已实现、待验证和规划中必须明确区分；
+- 终端不能直接调用 Proxmox API；
+- RDP 和 Moonlight 协议选择由管理平台连接票据决定；
+- 所有密钥和密码只能通过安全配置注入，不得提交到 Git；
+- 正式代码变更应通过编译、真机测试和会话恢复测试；
+- 本 README 随功能、接口、目录和验证结论持续更新。