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 注入后的钩子或目标应用行为。