true-input

True-Input Driver

编排器将你路由到了这里。使用这些机制执行你的计划。

驱动真实的终端模拟器，通过平台原生 HID 输入路径注入按键。这能准确证明终端发出的字节——没有合成注入，也没有 PTY 失真。

适用场景

• 证明终端确实发送了你预期的序列（例如，Ghostty 的 Shift+Enter）
• 录制能反映终端实际渲染效果的演示
• 在特定终端中端到端验证 Droid 是否能正确处理按键

如果不需要真实终端验证，请使用 terminal-use 中的 tuistory 后端——速度更快，确定性更高。

平台支持

平台	状态	驱动程序	阅读
Linux / Wayland	已实现	cage + wtype + 任意 Wayland 终端	platforms/linux.md
macOS（QEMU）	已实现	向 macOS 虚拟机发送 QEMU monitor sendkey	platforms/macos.md
Windows（KVM）	已实现	向 KVM/QEMU 虚拟机发送 virsh send-key	platforms/windows.md

请阅读目标操作系统对应的平台文件。 每个文件都包含先决条件、核心模式、命令参考、编码参考、录制、故障排除和恢复内容，并针对相应平台进行了说明。

与 tuistory 的主要区别

关注点	tuistory	true-input
快照来源	虚拟屏幕缓冲区	清理后的 PTY 日志（Linux）或屏幕截图（虚拟机平台）
等待机制	事件驱动（屏幕重绘）	日志轮询（Linux）或基于休眠（虚拟机）
录制	必须包装启动命令（--record）	随时可以开始/停止
键盘编码	合成（绕过终端）	真实终端编码路径

已知的死胡同

• Xvfb + xdotool：完全绕过真实的键盘处理
• uinput + Xvfb：Xvfb 不会使用内核输入设备
• 用于 TUI 测试的 SSH：PTY 层会使输入编码失真；SSH 仅用于部署
• 原始 asciinema rec：true-input 通过 wf-recorder（Wayland 屏幕捕获）录制，而不是通过 asciinema。请使用 tctl --record 或 tctl record start/stop。直接调用 asciinema rec 无法访问合成器，因此不会产生有用内容。