# 继续开发前必读

完整对话总结在：`D:\DAIMA\vdi-cloud\PROJECT_CONTEXT.md`

## 2026-11-03 显示器关开修复（优先于下文旧状态）
- 关屏再开后画面变矮：盒子回退1920x1440@75（4:3），Moonlight 16:9视频上下黑边；
  MATE monitors.xml仍存旧4:3布局，原启动脚本只设置一次2K。
- 已部署vdi-display-guard用户服务（active/enabled）和幂等启动恢复，保留297MHz定制2K时序；
  2秒检查、异常稳定2秒后恢复；断开不强设、失败退避、命令超时、单实例锁，正常不反复切换。
  修正当前GWR/0x2708显示器旧保存布局。仅部署tools/deploy_display_guard.sh，不重启串流。
- 9个场景测试通过，CTest 3/3；两次主动回退均约14秒恢复，Moonlight PID66385和boot ID不变。
  用户真实关屏再开确认自动全屏；10:03:19断开、10:03:31正确2K模式，10:04现场2560x1440。
- 备份~/vdi-terminal/backups/display-guard-20261103-095920/；详情/回退见
  docs/display-resume-fix-20261103.md。此修复仅限当前Xorg单HDMI 2K POC，未做隔夜老化。

## 2026-11-03 鼠标/点击跳转优化（优先于下文旧状态）
- Moonlight私有客户端新增两个补丁：鼠标合并不跨点击/键盘/窗口边界，绝对鼠标按钮封住前一位置批次；
  低延迟非pacing队列可丢弃等待帧保留最新帧，wrapper默认VDI_LATEST_FRAME=1。保持单白色Windows光标。
- 现场32次交替点击：旧客户端30/32正确（第1、13错位），补丁32/32正确；native输入测试1000轮和ASAN通过。
  配对串流补丁队列2.14ms/呈现6.12ms，原3.39ms/6.84ms；帧率约28.4/28.1，受网络/软件编码波动，不能称零延迟。
- Windows保留DragFullWindows=1、MouseTrails=0；已在test交互会话将MinAnimate从1改0、菜单400改100ms，读回通过，
  原值备份在test的LocalAppData/VDI；临时执行/测试任务已清理。
- 用户确认蓝框在盒子登录/选择页：QFrame:hover错误匹配QLabel。移除蓝色悬停框和登录焦点蓝框，限定卡片对象样式，
  局部编译CTest3/3，部署新版kiosk；悬停截图亮蓝像素8302→0。UI/wrapper备份input-rendering-20261103-114542。
  详情见docs/input-rendering-optimization-20261103.md和terminal/moonlight/README.md。

## 2026-11-02 最新实测（优先于下文旧状态）
- 2026-11-02晚：已在用户目录完成MPP+FFmpeg-Rockchip+Moonlight6.2.0私有构建，
  实际2K串流选中h264_rkmpp/drm_prime与EGL/GLES呈现，非仅FFmpeg样本测试。
  2K20 smooth会话平均呈现18.97FPS、解码10.53ms、呈现2.54ms；2K30 low-latency
  呈现23.46FPS、解码9.11ms、队列2.39ms、呈现5.41ms。服务端仍Code43/libx264。
  2K30 smooth队列31.95ms，VSync开/帧步调关也有28.93ms，故该盒子选低延迟档。
  原始日志和限制见 `docs/rendering-execution-20261102.md`。
  通过 `~/.config/vdi-terminal/render.conf` 显式选择私有wrapper+hardware，系统客户端不覆盖；
  Windows桌面票据改30FPS，原20FPS文件备份为desktops.before-rkmpp-20261102.json。
  构建脚本 `tools/build-rkmpp-client.sh` 修Qt5 optional、EGL探测缓存与旧对象不重编；
  kiosk就绪判断兼容RKMPP独立测试解码器日志，CTest 2/2通过。
  鼠标MouseTrails=0、DragFullWindows=1；现场仍有VDIApplyTransparentCursor刷新参数任务，
  先前“任务已删除”的记录不准确，本轮未改变光标配置；截图单白光标正常。
  不能把23FPS、硬解接通解释为GPU已恢复、2K60或端到端零延迟。
- 已部署真实2K：盒子HDMI 2560x1440约60Hz、Windows VDD 2560x1440@30、Moonlight 2560x1440@20/30Mbps。
- RK3528旧PHY拒绝EDID的241.70MHz，实测用297MHz固定时钟和扩展消隐成功：
  `297.00 2560 2608 2640 2720 1440 1443 1448 1820 +HSync -VSync`；盒子重启已验证，link Good。
- Windows VDD版本11.30.4.434，生效XML在 `C:\VirtualDisplayDriver\vdd_settings.xml`。
  登录任务VDISet2KDisplay动态定位Virtual Display Driver（不能写死DISPLAY编号），脚本在
  `C:\ProgramData\VDI\set-2k-display.ps1`，仓库副本 `tools/set-2k-display.ps1`；VM重启后执行成功。
- 鼠标保留白色Windows远程光标，已删除本地黑色光标自动开启和透明光标任务；GLES2、关闭MATE合成器保留。
- **GPU并非稳定完成**：运维曾打通582.78/NVENC，连续动画可发送59FPS；但本次VM重启后Code43复发，
  nvidia-smi失败、Sunshine当前实际为libx264软件编码。客户机重启设备/隔离VDD/VM停启均无效；
  无效VDIRecoverNvidia任务已删除。未改宿主VFIO模块、未重启宿主。ROM为gtx965m-pci.rom。
- NVENC正常时2K20实测19.67FPS、网络丢帧0%、抖动丢帧0.94%；这些数据不能作为当前软编性能保证。
- 详细最新状态见 `docs/moonlight-kiosk-20261028.md` 的“当前现场（2026-11-02 15:45）”。

## 当前状态
- 项目目录：`D:\DAIMA\vdi-cloud`
- 终端盒子：RK3528 PRO DDR4，Armbian Ubuntu Noble，aarch64，IP `192.168.1.188`
- 当前图形：LightDM + Xorg；正式文档要求 Weston + Wayland + Qt，当前只是 POC
- Proxmox：9.2.2 节点 `starhe`。VM 100 win10-test `192.168.1.70`（Sunshine/Moonlight 云桌面）；
  VM 101 kylin-test `192.168.1.71`（test1）、VM 102 ubuntu-test `192.168.1.72`（test2），
  密码均 `yx66668888`，SSH 可登、图形会话在跑，**尚未装 Sunshine**，暂不能串流
- `kiosk-shell`（Qt/C++）：**开机直进桌面列表**（2026-10-30 起，设备 SN 即用户自动登录，
  登录页代码保留待平台正式认证接入）→ 选择桌面 → Moonlight 会话；**RDP 代码已于 2026-10-29
  全部删除**（git 历史可查），Moonlight 是唯一会话通道，无 freerdp 构建依赖
- 新增退出三层与会话过场层：`Ctrl+Alt+Shift+Q` 退串流回列表；列表页"退出登录"；
  登录页无退出按钮（退出终端只在管理菜单）；点连接有全屏过场层，首帧后淡出。
  详见 `docs/moonlight-kiosk-20261028.md` 2026-10-29 下午节
- 代码位置：`terminal/kiosk-shell`
- 远程安装路径：`~/vdi-terminal/bin/`（`kiosk-shell`、`vdi-kiosk-monitor`、`vdi-moonlight`）

## GPU 直通进行中（2026-10-30 下午，见 moonlight-kiosk 文档当日追加节）
- 宿主侧已就绪：nouveau 已黑名单、GPU 在 vfio-pci、IOMMU 组 2（root port+GPU）
- 关键坑：vfio 清零 Subsystem ID（必须 `x-pci-sub-vendor-id/device-id` 注入 1558:6557）；
  移动卡 vBIOS 需 sysfs 抽取（/usr/share/kvm/gtx965m.rom）；NVIDIA 安装器在 SYSTEM 会话
  挂起（用 7zr 解包 + pnputil）；582.78 绑定后 D3D 全灭已换 566.36（D3D 待验证）
- **当前 VM 100 未挂 GPU**：另一并行会话在改配置（hv_vendor_id 方案），本会话已停手避撞，
  两个会话不要同时改 VM 100 配置！
- Sunshine 配对 2026.914 改为"Web UI 批准式"：`moonlight pair --pin NNNN` +
  `GET /api/csrf-token` + `POST /api/pin {pairing_id,pin}`；Web 凭据由环境管理员保管；
  删 sunshine_state.json = 全部失配；盒子 Moonlight 配置目录缓存旧 uniqueid 会卡死配对

## 必须遵守
- 所有实现严格参考用户提供的两个正式 Word 和会议纪要；文档未确定的技术只能标记待调研，不得擅自定版。
- 终端先做，后接自研管理平台 API；终端不直接调用 Proxmox API。
- 正式状态机：`BOOT -> CONFIG -> CONNECTING -> SESSION -> RECONNECT -> ERROR`
- 正式 Kiosk 选型：Weston + Wayland + Qt；会话通道统一 Moonlight（RDP 已删，勿在代码里复活协议分支）。
- `/cert:ignore`、空密码仅限局域网 POC。
- 项目经理新增待调研：RDP 是否适合 GPU/CAD/3D；研究 Moonlight/Sunshine，但不要在调研前删除 RDP、确定 Moonlight 参数或定版双协议。

## 已知关键结论
- WiFi：约 -47 dBm，协商约 200 Mbps，零丢包/重传；卷帘问题不能简单归因于 WiFi。
- HDMI 当前原生：`1920x1440@75Hz`（10-23 记录）；2026-10-28 实测盒子系统已是 `1920x1080@60Hz`，
  与 Sunshine 侧虚拟显示器一致，串流 1:1 无缩放。以现场 `xrandr` 为准。
- `/dev/mpp_service`、`/dev/rga` 存在，但 `mppvideodec` GStreamer 插件未确认；Weston/DRM 零拷贝待验证。
- FreeRDP 3：`gdi_init` 必须在 PostConnect；NLA 空密码传 `strdup("")`；BGRX32 需转换为 Qt RGB；`/gfx` 是能力组合语义。
- Moonlight/Sunshine（2026-10-28 实测）：Windows 防火墙挡 ICMP，ping 不通不代表不通，
  可达性判断必须用 TCP 探测；`moonlight-qt` 的 app id 会随服务端重装失效，
  命令行要用应用名 `Desktop`；RK3528 上 `--video-decoder auto` 会选到不可用的
  `h264_v4l2m2m`，必须显式 `software`。
- **21.6 FPS 上限根因（2026-10-29 修正）**：不是 x264 编码算力——ultrafast 前后帧率分毫不差，
  串流中 VM CPU 仅 0.5%、sunshine 累计 14 秒 CPU/3 分钟会话，鼠标运动也不变；
  真正瓶颈在虚拟显示/捕获节奏（MttVDD 呈现 + Desktop Duplication 脏帧 + QEMU 显示栈，
  VM CPU 型号 `QEMU Virtual CPU version 2.5+` 未透传宿主 AVX2）。
  根治 = GPU 直通（NVENC + 真实显示栈）；备选 = VirtIO-GPU / cpu=host 排除 QEMU 显示栈因素。
  客户端解码 10~15 ms、网络丢包 0%、延迟 3 ms，链路健康。

## Web 控制台（2026-10-28 方案确认）
- `console/` 是管理员 Web 管理控制台，不是 RK3528 盒子的用户登录页。
- 正式技术栈：Vue3 + Vite + TypeScript 严格模式 + Element Plus；后端通过 api-gateway，JWT + RBAC。
- 页面：仪表盘、终端管理、桌面管理、用户与绑定、GPU 池、监控、OTA、审计日志。
- 角色：超级管理员、运维、只读。
- 终端产品流程仍应是 `kiosk-shell 登录/首配 -> 桌面列表 -> 获取短期连接票据 -> RDP/Moonlight 会话`；
  当前开机直连 Moonlight 仅是串流技术验证，不是最终产品登录流程。
- 开发策略：先做功能骨架、Mock API、OpenAPI 契约、RBAC 与 E2E；项目经理 UI 稿到后替换视觉层。
- 完整方案：`docs/web-console-mvp-plan-20261028.md`。

## 尚未完成
- 服务端 GPU 直通：GPU 为 CLEVO 准系统上的 GM204M/965M（10de:13d9，宿主被 nouveau 占用需解绑）；
  **IOMMU 已启用**（组 2 = root port 00:01.0 + GPU 01:00.0，整组直通）；VM 内需装 R580 legacy 驱动。
  操作单与 GPU 看板见 `docs/gpu-passthrough-20261030.md`，看板 `http://192.168.1.51:8090/`（systemd 自启）
- RK3528 VPU 硬解（h264_v4l2m2m 等缺可用设备，需 MPP FFmpeg 补丁或 V4L2 request 驱动）
- 2K 分辨率链路验证（虚拟显示器 + 盒子显示模式需同步调整）
- Weston/DRM/mppvideodec
- 后端 API 注册、配置、MQTT 心跳（Moonlight 路径目前是本地静态配置）
- 终端音频出音现场确认
- 协议最终选型定版（RDP / Moonlight / 双协议，需实测数据 + 产品方案共同确认）
- 监控与运维脚本、OTA、USB 重定向等终端其余能力

先读 `PROJECT_CONTEXT.md`，再查看 `git status`，不要丢弃未提交改动。