crossdesk/apps/cli/docs/validation.md

# CLI 验证记录

## 本地仓库整合（2026-10-30）

环境为 macOS arm64、Xcode SDK 27.0、Xmake 3.1.1、C++17，关闭 CUDA。CLI 源码整合到 CrossDesk 的 `apps/cli`，共享现有 wire 与 MiniRTC；未新增或修改工程内测试。

- CLI 单独配置和 release 构建通过，目标为 `crossdesk-cli`；`doctor --json` 返回有效 JSON，动态链接依赖仅为系统库及框架，无 Slint / SDL。
- 同时启用桌面与 CLI 时，debug 配置下 `crossdesk`、`crossdesk-cli` 均编译通过。
- 原有仓库结构、wire 和键盘状态测试通过，未修改测试源码。
- 工程外桥接检查通过：JSON 协议、版本校验、分片、EOF、消息上限、慢消费者、本地信令失败、凭据描述符和非 TTY 拒绝。
- 工程外 POSIX PTY 检查通过：隐藏密码、无 DISPLAY/WAYLAND_DISPLAY、原始模式恢复、Kitty 探测超时和 tmux 下明确拒绝 Kitty。
- macOS arm64 原生 npm 包和通用启动包生成成功；离线安装、启动器 `doctor` 和原生程序路径解析通过。该本地产物最低要求为 macOS 27.0。
- 从原生包解出源码后，在没有 Git 元数据、没有桌面应用源码的目录中重新配置、构建 CLI 并运行 `doctor` 成功。
- 验证后恢复整合前的桌面 debug 构建配置，CLI 默认关闭；新命令行二进制保留在 `build/macosx/arm64/release/crossdesk-cli`。

## 优化回归（2026-10-30）

- Release 构建、实际二进制 bridge/PTY 回归通过。ASan/UBSan 检查覆盖原有会话和渲染行为，以及无效帧保留、NV12 缓冲复用、预览参数去重、ACK 状态、重复断开和重连网络统计复位。
- 生产 bridge 配合工程外假传输验证静止画面重绘、细节模式、质量切换、窗口变化、无效配置原子性和帧 ACK 背压，通过。
- ANSI 渲染前后对比覆盖 8/24/256 色、UTF-8/ASCII、half/quadrant、全景/细节模式，输出校验值一致。在本机 240×100 网格连续执行 200 次差分生成，静止网格约 447.4 ms → 3.6 ms，单行变化约 422.8 ms → 9.5 ms。该结果只衡量差分文本生成，不包含视频解码、图像缩放和终端显示时间。
- npm 真实打包、离线安装及源码包重建通过；工程外故障注入确认已有产物保留、第二个包生成失败时无半套输出、缺失脱敏补丁时拒绝打包。

新增回归代码、基准、假传输和验证产物均位于工程外临时目录，未向工程或子模块添加测试。此次完整构建与运行验证覆盖 macOS arm64，未重新进行 Linux/Windows 实机验证。

## 控制按键调整（2026-10-30）

- 当前桌面与 CLI 同时启用的 debug 配置下，`xmake build crossdesk-cli`、`xmake run crossdesk-cli doctor --json` 和命令帮助检查通过。
- 工程外 ASan/UBSan 检查覆盖本地命令前缀、只读快捷键、远端 Ctrl+T/Ctrl+C/Ctrl+]、鼠标释放、取消命令、粘贴隔离、UTF-8/CSI 分片、失焦与退出；原有会话／渲染检查通过。
- 平移字母键采用 `i` 上、`j` 左、`k` 下、`l` 右；工程外 ASan/UBSan 检查确认四个方向与普通／应用模式方向键一致，控制模式中普通字母仍传给远端。
- 细节／全景采用相邻的 `d`／`f`；工程外 ASan/UBSan 检查确认细节保留中心、全景复位缩放与中心、前缀命令和鼠标点击行为正确，控制模式中普通字母仍传给远端。
- 实际二进制 bridge 验证命令状态、错误恢复和退出响应；生产 view 配合假传输的 PTY 检查验证快捷键、模式提示、隐藏密码和终端恢复。实际二进制的 bridge 与 PTY 回归同样通过。
- Pi 1.4.0 SDK 严格类型检查和模拟组件运行通过，覆盖控制按键转发、命令提示、取消、缩放、退出与 bridge 启动失败后的关闭操作。

此次没有连接真实远端设备，也没有进行 Linux／Windows 或真实 Pi TUI 实机验证。新增测试代码与产物均保存在工程外系统临时目录。

## 直接 ID 入口与 npm 源码包（2026-10-30）

- 直接输入 9 位设备 ID 和 `view` 兼容别名均通过参数检查，保留前导零，支持相同的连接选项；无效 ID 在密码提示前拒绝。macOS arm64 终端中的密码提示与 Ctrl+C 取消通过。
- 本地 npm 包离线安装、启动器帮助和 `doctor --json` 通过；源码包包含完整的 `libs/controller/include`，补齐诊断头文件后，从安装包内源码独立配置、release 构建及 `doctor` 通过。
- 原有仓库结构、wire 和键盘状态测试通过；未新增或修改工程内测试，额外验证和产物均位于工程外临时目录。
- Build and Release #899 和 CLI native builds and npm packages #1 的首次运行均因 MiniRTC 提交 `b9ee1fa7` 尚未推送而在检出阶段失败。将该提交推送到 MiniRTC 远端后，全新递归浅克隆通过。

## 独立开发阶段的验证范围

以下为迁入前的验证记录摘要，不表示本次重新连接了远程设备：

- macOS arm64 的 debug/release 构建、CLI bridge 的 NDJSON、POSIX PTY 隐藏密码与终端恢复均已验证。
- 工程外的 ASan/UBSan 检查覆盖会话状态、只读限制、输入释放、帧内存所有权、渲染、缩放和平移、输出背压和帧 ACK。
- Pi 1.4.0 SDK 类型检查与模拟组件生命周期已验证；真实 Pi TUI 视觉效果未验收。
- 早期身份协议版本曾连接真实设备进行只读 ANSI 观看和 Kitty 协议数据验证；Kitty 数据解压检查不等于 Kitty 应用或 SSH 实机显示验收。
- 改为 `cli-` 临时身份后，正式 CLI 与本地 WSS 服务端验证了临时注册、Join、身份不可复用及退出清理；线上服务尚未在该轮部署，早期画面验证不能代替新身份协议的线上联调。
- npm 的 macOS arm64 本地生成及安装已验证；Linux / Windows 当时仅完成 CLI 主程序和平台 I/O 的交叉编译检查，没有完整 MiniRTC 链接和实机连接结果。

## 终端鼠标兼容修复（2026-10-30）

- 工程外假传输复现：旧解析器把传统 `CSI M` 报告的三个负载字节作为键盘文本发送，`mouse_reports` 仍为 0；SGR 点击只发送按下／松开，没有提前定位。
- 修复后的 ASan/UBSan 检查通过，覆盖 SGR／传统报告的全部二段分片与逐字节输入、左右中键、拖动、滚轮、点击前定位、高位坐标字节、黑边松开、只读／本地命令模式、失焦释放及发送失败。既有持续本地命令模式回归同样通过。
- macOS arm64 的 CLI debug 构建和 `doctor --json` 通过。生产 CLI 配合工程外假传输的 POSIX PTY 检查在 120／50 列窗口通过，验证逐字节鼠标输入、`Mouse RX`／`M:` 状态栏计数、日志统计、鼠标报告模式启停和原始终端模式恢复。
- 所有额外测试代码、脚本和产物均位于工程外临时目录。上述结果未覆盖真实 SSH 链路、GNOME Terminal 或 Linux 被控端实机，不能据此确认用户现场的问题已消失。

## 字符宽高比自动检测（2026-10-30）

- macOS arm64 CLI debug 构建通过。工程外 ASan/UBSan 检查覆盖字符／文本区尺寸报告、回复顺序与优先级、跨查询部分回复隔离、逐字节输入、本地命令／粘贴隔离、非法尺寸，以及 ANSI half／quadrant／ASCII 的画面比例与鼠标映射。
- 以 9×20 像素字符、120×40 字符视口和 1920×1080 源图模拟非 0.5 字符比例，旧默认值产生约 8%～9.3% 的宽高比误差；应用实际字符尺寸后为 1.25%，剩余为该网格的整数采样舍入。
- 生产 CLI 配合工程外假传输的 POSIX PTY 检查通过，覆盖 GNOME 风格的文本区像素／行列回复、直接字符尺寸、字体变化、窗口缩放、无回复／部分回复／非法回复、TTY 回退、手动覆盖、auto 和 Kitty。字体变化时没有新视频帧也能重绘，退出后终端模式恢复。
- 新增测试及产物均在工程外临时目录；尚未在真实 Linux GNOME Terminal 或 SSH 链路进行视觉验收。

## Windows 与 Pi／bridge 字符比例补全（2026-10-30）

- macOS arm64 CLI debug 构建通过；Windows x64 的主程序、平台 I/O、输入解析和尺寸解析通过交叉编译，平台 I/O 独立链接通过（含 user32／advapi32），不代表 Windows MiniRTC 完整构建或实机运行。
- 工程外 Win32 API 模拟检查直接使用生产尺寸读取函数，覆盖可见控制台字体尺寸、隐藏 ConPTY 回退、失败／非法字体尺寸与句柄释放，ASan/UBSan 通过。既有尺寸解析 ASan/UBSan 和 POSIX PTY 回归再次通过。
- 生产 bridge 配合工程外假传输验证可选比例字段保留、有限数值及范围检查、无效请求原子性、实际布局比例、静止画面重绘与帧比例元数据。
- Pi 1.4.0 SDK 严格类型检查及模拟宿主运行通过：使用真实 SDK 分片组包，覆盖文本区成对回复、字符尺寸优先级、宿主缓存、字体／窗口变化、手动覆盖、旧比例帧丢弃及 ACK、控制键回归、启动失败／异常退出后的监听与定时器清理。
- 新增验证代码和产物全部位于工程外系统临时目录；尚未在真实 Windows、GNOME／SSH 或 Pi TUI 进行视觉验收。

## ANSI 四象限接缝优化（2026-10-30）

- macOS arm64 的 CLI debug 构建和 `doctor --json` 通过。工程外 ASan/UBSan 检查覆盖低对比合并、横纵细线／斜线／双色图案、等亮度彩色边缘、随机 NV12 输入的失真上限、局部更新范围和重复转换确定性。
- 合成低对比图案中，3,072 个非空白字形全部合并为纯背景。合成渐变纹理的加权接缝误差由约 207,373 降至 180,187（13.1%）；仅统计两端均未合并为纯色的边界时，由约 198,007 降至 169,621。指标衡量相邻样本的重建色差相对源图色差的偏离，并降低真实高对比边缘的权重；不代表实机条纹减少的百分比。
- 8／24／256 色输出、half／ASCII 与原实现一致性、不同视口／比例／缩放的布局和鼠标映射、静止网格差分及 Kitty 输出检查通过。
- 本机 `-O2`、1920×1080 输入、240×100 字符视口、每项 12 次转换的合成基准：平滑画面约 7.14 → 6.03 ms/帧，随机亮度噪声约 5.44 → 7.73 ms/帧。仅衡量转换，不包含视频解码、ANSI 输出和终端绘制。
- 额外检查代码、基准和数据均位于工程外系统临时目录；未新增工程内测试，未连接真实远端或进行终端字形／行距的视觉验收。

## ANSI 转换与输出加速（2026-10-30）

- macOS arm64 CLI debug 构建和 `doctor --json` 通过。工程外 ASan/UBSan 与 `-O2` 检查均通过：加速后的转换与此前接缝优化版本逐格颜色／字形一致，覆盖随机 NV12、低对比及平滑纹理、half／quadrant／ASCII、缩放和细节模式；Kitty 数据保持一致。
- ANSI 转义序列模拟器验证最终屏幕一致，覆盖全部四象限字形、8／24／256 色、纯背景及色板复用、首尾单元、局部修改、视口／偏移变化和可独立绘制的 bridge 字符行。未向工程新增测试文件或用例。
- 本机 `-O2`、1920×1080 输入、240×100 字符视口、每项 24 次转换：平滑画面约 6.26 → 4.83 ms/帧，随机亮度噪声约 7.75 → 5.72 ms/帧。保留面积滤波、低对比合并及边界连续性约束。
- 240×100 真彩色合成网格、每项 100 次输出生成：整帧约 2.03 → 1.43 ms；120×50 单元的局部修改约 1.02 → 0.36 ms，输出 461,743 → 231,026 字节；2×3 单元的光标修改约 0.072 → 0.013 ms，输出 27,763 → 262 字节。纯背景色块整帧输出 875,352 → 449,826 字节。
- 这些结果衡量转换、编码及输出量，不包含实际终端绘制或网络传输。整帧高色彩变化图案仍需约 923 KB，仍受 1 MiB/s 输出预算限制；不能将转换耗时的倒数作为远程显示帧率。当时默认本地目标为 8 FPS，后续默认策略见“默认 30 FPS 与供帧自适应”。
- 额外检查代码、模拟器、基准和产物均位于工程外临时目录；未进行跨平台终端或真实远端帧率验收。

## Kitty 帧间黑屏与本地吞吐修复（2026-10-30）

- macOS arm64 debug、release 构建通过，release `doctor --json` 通过。release 使用工程外独立配置构建，保留工程原有 debug 配置；额外检查脚本、伪终端夹具和数据均位于系统临时目录。
- ASan/UBSan 检查及 Kitty 协议模拟验证：ID 31/32 交替上传，所有上传分块完成前旧图保持显示；先创建新图 placement，再释放旧图；最多两个完整图像驻留，切换后只保留一个。新旧输出的解压 RGB 和尺寸逐字节一致，覆盖尺寸、偏移和缩放变化；单帧小于 2MiB，全部分块边界的中断清理通过。
- ANSI 的 half／quadrant／ASCII 和 8／24／256 色共 12 种组合，转换单元及输出字节与此次修改前一致。
- 使用生产 `View`、`Output` 和 Kitty 编码代码、`-O2`、合成 NV12 持续回调的本地 PTY 对比：目标 8 FPS，单帧约 1.25 MB，稳定完整接收速率约 0.84 → 6.71 FPS，帧间隔中位数约 1,192 → 148 ms。只衡量完整输出接收，不包含真实网络、视频解码和 Ghostty GPU 显示，不能作为实机帧率承诺。
- 本地 Kitty 的日志预算为 8MiB/s；分别仅设置 `SSH_TTY`、`SSH_CONNECTION`、`SSH_CLIENT` 时均保持 1MiB/s，ANSI 也保持 1MiB/s。连续帧 ID 仅在完整写入后交替，退出清理两个 ID。
- 慢速 PTY 在第二帧上传中退出：首帧保留、第二帧未提交，约 2.06s 后退出；两个 ID 清理、备用屏幕／光标控制序列和原 termios 均恢复。测试发现原单次清理写入会在满缓冲区时丢失，现增加至多 500ms 的非阻塞短写重试。
- 模拟父 shell 保持会话、终端完全停止读取的 PTY：CLI 约 2.53s 后返回，termios 和非阻塞标志恢复。POSIX 恢复改为 `TCSANOW` 加输入清理，避免 `TCSAFLUSH` 等待输出排空。完全不读取时，屏幕清理字节不保证送达。
- 本机安装 Ghostty 1.4.0，但自动化工具拒绝访问其窗口，未完成 Ghostty 实窗视觉验收。npm 安装的 CLI 不会随本地构建自动更新，复测需要直接运行本次 release 产物。

## 本地 Kitty 共享内存与 30 FPS 目标（2026-10-30）

- 本地 POSIX Kitty 增加共享内存能力探测、唯一名称、0600 权限、上传确认和 500ms 超时回退。单个待确认共享缓冲区不超过 1920×1080×3 字节；确认前保留旧画面，退出释放未确认对象。Windows 暂保留内联路径，SSH 不发共享内存探测。
- 当时共享内存可用且未显式指定 `--fps` 时默认目标 30；自动回退内联恢复 8，显式帧率保持不变。后续默认策略见“默认 30 FPS 与供帧自适应”。目标大于 15 使用现有预览协议的交互模式 `fps=60, frame_rate=30`；没有新增协议取值或修改被控端。
- 工程外 ASan/UBSan 检查通过：110 组随机帧／视口／宽高比／缩放／细节模式，整数面积滤波相对原浮点参考的每通道最大误差为 1/255；内联 Kitty 和 ANSI 保持原输出。覆盖共享内存权限、读取内容、命名、容量限制、双方 unlink、分片确认及非法／溢出／重复 ID 回应。
- 使用实际 release CLI 对象代码、1920×1080 合成噪声 NV12 连续回调、1568×1088 报告视口的 PTY 测试：内联完整接收约 4.06 FPS，共享内存约 29.04 FPS；平均本地处理约 166.6 → 12.3 ms，终端字节流约 1,703,174 → 188 字节/帧。共享内存仍传输完整 RGB，并非总数据量只有 188 字节；数据复制、终端绘制和实际网络另有成本。
- 显式 8 FPS、探测不支持／静默、第三帧上传报错／丢失确认、80ms 延迟确认、SSH 禁用探测均通过。回退前不显示未确认帧，运行时回退仅触发一次，并正确恢复自动目标和协议请求；所有共享对象均清理。第二帧上传后立即退出时，首帧仍是已提交画面，未确认对象及两个图像 ID 均清理。
- 相同合成输入的 debug 构建约 5.91 FPS，本地处理约 163 ms，说明 `-O0` 仍明显影响像素转换；性能验收使用 release。上述精确数字是本地测试接收速率，不是 Ghostty GPU 显示帧率。
- 用户在本机 Ghostty 运行新版 release 后反馈“明显流畅了”。额外测试源码、数据、构建夹具和产物均位于系统临时目录，未在工程或子模块新增测试。
- 该次实机日志确认 `kitty_transport=shared_memory`、目标 30、预览请求已接受、运行时回退 0 次。会话约 13.61s 完整提交 273 帧，平均提交约 20.06 FPS（包含约 1.49s 首帧启动等待）；平均本地处理约 10.87ms、共享内存确认约 0.42ms。该日志记录提交速率，不测量终端 GPU 呈现频率。

## 默认 30 FPS 与供帧自适应（2026-10-30）

- 交互 CLI 默认本地目标统一为 30 FPS，Kitty 共享内存回退不再改写该目标；远端请求独立在 8／15／30 FPS 档位间自适应，15 需要对端能力。显式 `--fps` 保留固定请求，bridge 默认仍为 8。
- macOS arm64 debug／release 构建、release `doctor --json` 和帮助输出检查通过。工程外 ASan/UBSan 验证了升降档阈值、迟滞、恢复、15 FPS 能力缺失、显式帧率、源帧稀疏、请求拒绝以及估计重置。
- 使用真实 release CLI 对象代码、支持预览确认和动态供帧的假传输、1920×1080 合成 NV12 与 1568×1088 像素视口进行 PTY 验证。固定 30 FPS 源的共享内存路径完整接收约 30 FPS，未触发自动降档；不再在没有新帧时提前消耗刷新时隙。
- 高熵内联路径实际约 4 FPS 时，自动请求由 30 降为 8，本地目标保持 30；显式 `--fps 30` 在同条件下仍约 4 FPS，远端请求不变。上传报错／超时和探测静默均保持本地 30 目标，随后按完整帧耗时调节供帧。
- 90ms 上传确认延迟使实际接收约 9 FPS，远端请求自动调整为 15；缺少 15 FPS 能力时不发送该档位。200ms 延迟后恢复正常确认，验证远端请求按 30 → 8 → 30 恢复。源仅提供 2 FPS、对端拒绝预览时均未误触发自动降档。
- SSH 环境保持原有 1MiB/s 字节预算且不探测共享内存；慢速输出降远端请求但保留本地目标。ANSI 默认 30／显式 15 和 bridge 默认 8／帧 ACK 通过。所有 Kitty 场景继续验证不显示未确认帧、最多两个终端图像、共享对象释放及退出后终端模式恢复。
- 以上数字是合成源和伪终端的完整输出接收率，不包含真实视频解码、网络或 Ghostty GPU 呈现。全部额外测试代码、数据、构建脚本和产物位于工程外系统临时目录；本次未新增工程内测试，尚未对新版进行 Ghostty 实窗验收。

## 实测边界

本地检查不涵盖 Linux / Windows 完整构建、跨平台远程控制、Kitty/SSH 实际终端显示、真实 Pi TUI 或长时间资源占用。五个平台 CI 配置与 npm 包名均不代表已发布或已验收。

CLI 需要支持 `cli` 临时注册的服务端。`doctor --json` 仅报告本机环境，不会联网登录或证明远端可连接。