crossdesk/docs/MOUSE_INPUT_DIAGNOSTICS.md

鼠标输入启动诊断

控制端和被控端都需要重新编译 CrossDesk 及 deps/submodules/minirtc。 诊断默认使用 INFO/WARN 日志。连接后立即在远端画面内持续移动鼠标， 保留两端同一次运行的 crossdesk-*.log 和 minirtc-*.log。

记录顺序

日志	所在端	含义
Input connection status	两端 CrossDesk	上层连接状态变化
Mouse UI stream window shown / Mouse UI selected	控制端 CrossDesk	窗口显示和当前会话选择
Mouse UI event	控制端 CrossDesk	Slint 视频输入区域收到事件，包含本地 UI 遮挡、拖动和释放抑制状态
Mouse trace: scope=pointer / scope=scroll	控制端 CrossDesk	转发入口、过滤原因、调用发送 API 的时间和返回值
Mouse transport dispatch	控制端 MiniRTC	连接与 ICE 就绪检查及传输层返回值
Mouse RTP enqueue	控制端 MiniRTC	实际入队结果，队列满时明确记录
Mouse RTP send begin / send end	控制端 MiniRTC	队列等待、底层发送调用耗时及真实返回值
Mouse RTP receive	被控端 MiniRTC	RTP 包进入鼠标数据通道，位于应用回调之前
Mouse trace: scope=receive	被控端 CrossDesk	应用回调入口及各检查、提交阶段
Mouse RTP callback complete	被控端 MiniRTC	应用回调的总耗时

应用接收阶段依次为 parse、authorize、desktop_check、dispatch， 随后是 normal_desktop_inject 或 secure_desktop_inject。 phase=stage_begin 在调用前记录，phase=stage_done 或 phase=end 报告该阶段耗时。若某阶段开始后长时间没有结束，可以确定阻塞区间。 outcome=no_controller、unauthorized、inject_failed 等说明具体处理结果； submitted 表示操作系统提交调用成功，不是目标应用已执行的确认。

关联与限频

• tag 是鼠标消息原始字节的 FNV-1a 64 位摘要，可关联发送和接收；相同消息 会有相同摘要，因此重复消息应同时结合 RTP 的 ssrc / seq 和时间判断。
• event 是各阶段本地计数，不应视为跨端共同序号。会话/通道重建后重新计数。
• mono_us 是进程所在机器的单调时钟，只用于该端的耗时判断。 两端日志的墙钟可能不同，不能直接相减当作网络时延。
• queue_us、send_us、stage_us、dispatch_us 和 total_us 单位均为微秒。 stage_us 和 send_us 排除本阶段入口日志写入时间；总耗时仍包含诊断开销。
• 每个采样器记录前 3 次事件，此后最多每 5 秒选取一次事件。 失败和耗时达到 100 毫秒的调用使用独立限频，前 3 次记录，此后每 5 秒一次。
• 发送 API 的返回值不等于网络送达确认，应检查传输层、RTP 发送和远端接收记录。

如果有 UI 事件而没有发送入口，先看 local_ui、dragging、suppressed； 如果已入队却迟迟没有实际发送，查看 queue_us；如果远端已有 RTP 记录， 但应用处理耗时很长，查看接收阶段。仅当两端相关阶段都及时完成时， 才进一步检查 Windows 注入后的钩子或目标应用行为。