功能：实现终端登录页与状态机骨架

变更详情：feat(kiosk-shell): 首版登录页与状态机骨架

按《VDI 云桌面软件开发方案》3.2 节实现：
- 状态机 BOOT/CONFIG/CONNECTING/SESSION/RECONNECT/ERROR
- 首配页（SN 绑定、服务器地址、账号、密码、显示档位）
- 全局热键 Ctrl+Alt+Shift+M 呼出管理菜单
- FreeRDP 3 以 libfreerdp3 API 内嵌，非拉起外部进程

docs/api-free-rdp3.md

@@ -0,0 +1,33 @@
+# FreeRDP 3 客户端 API 参考（Ubuntu 24.04 / freerdp3-dev）
+
+> 用途：kiosk-shell 内嵌 FreeRDP 客户端时使用，避免拉起外部进程（开发方案 3.2 节）。
+> 记录时间：2026-10-23
+
+## 包名
+- 运行时：`libfreerdp-client3-3`、`libfreerdp3-3`
+- 开发：`freerdp3-dev`（Ubuntu 24.04 提供 `freerdp3-dev` 与 `libfreerdp-client3-3-dev`）
+- pkg-config 名称：`freerdp3`、`freerdp3-client`（安装后以 `pkg-config --list-all | grep freerdp` 实测为准）
+
+## 关键头文件
+| 头文件 | 用途 |
+|---|---|
+| `freerdp/client.h` | 客户端主入口、freerdp_client_context_new / freerdp_client_context_free |
+| `freerdp/freerdp.h` | 核心上下文 |
+| `freerdp/settings.h` | 连接参数设置（freerdp_settings_new / set) |
+| `freerdp/channels/cliprdr.h` | 剪贴板通道 |
+| `freerdp/gdi/gfx.h` | GFX 图形管线（AVC420/AVC444/RFX 能力） |
+| `freerdp/crypto/tls.h` | TLS |
+
+## 最小连接流程（伪代码）
+```c
+freerdp_client_context* ctx = freerdp_client_context_new();
+RdpClientContext* cctx = ...;
+freerdp_settings_new(0);          // 释放: freerdp_settings_free
+freerdp_set_pointer / freerdp_set_keyboard ...  // 输入回调
+ctx->Connect = ...;               // 事件表
+freerdp_client_context_new / connect
+```
+
+## 注意事项
+- `/gfx` 命令行语法在 3.32.1 上必须用 `|` 分隔的能力组合（如 `progressive|RFX|AVC420|AVC444`），
+  单独 `AVC420` 会解析失败。API 侧对应 `gfx` 能力位设置。