true-input

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

True-Input Driver

The orchestrator routed you here. Use these mechanics to execute your plan.

Drive a real terminal emulator, injecting keystrokes through the platform's native HID input path. This proves exactly what bytes the terminal emits -- no synthetic injection, no PTY distortion.

编排器将引导你来到这里。使用这些机制来执行你的计划。

驱动真实的终端模拟器，通过平台原生HID输入路径注入按键。这能精确验证终端发出的字节序列——无合成注入，无PTY失真。

When to use

使用场景

Proving that a terminal really sends the sequence you expect (e.g., Ghostty's
```
Shift+Enter
```
)
Recording demos that reflect actual terminal rendering
Validating that Droid handles a keystroke correctly end-to-end in a specific terminal

If you don't need real terminal proof, use tuistory -- it's faster and more deterministic.

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

如果不需要真实终端验证，使用tuistory——它更快且更具确定性。

Platform support

平台支持

Platform	Status	Driver	Read
Linux / Wayland	Implemented	`cage` + `wtype` + any Wayland terminal	platforms/linux.md
macOS (QEMU)	Implemented	QEMU monitor `sendkey` to a macOS VM	platforms/macos.md
Windows (KVM)	Implemented	`virsh send-key` to a KVM/QEMU VM	platforms/windows.md

Read the platform file for your target OS. Each contains prerequisites, core pattern, command reference, encoding reference, recording, troubleshooting, and recovery -- specific to that platform.

平台	状态	驱动	参考文档
Linux / Wayland	已实现	`cage` + `wtype` + 任意Wayland终端	platforms/linux.md
macOS (QEMU)	已实现	QEMU monitor `sendkey` 至macOS虚拟机	platforms/macos.md
Windows (KVM)	已实现	`virsh send-key` 至KVM/QEMU虚拟机	platforms/windows.md

请阅读目标操作系统对应的平台文档。每个文档都包含特定于该平台的先决条件、核心模式、命令参考、编码参考、录制方法、故障排查和恢复方案。

Key differences from tuistory

与tuistory的主要差异

Concern	tuistory	true-input
Snapshot source	Virtual screen buffer	Scrubbed PTY log (Linux) or screenshot (VM platforms)
Wait mechanism	Event-driven (screen redraws)	Log polling (Linux) or sleep-based (VMs)
Recording	Must wrap launch ( `--record` )	Can start/stop any time
Keyboard encoding	Synthetic (bypasses terminal)	Real terminal encoding path

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

Known dead ends

已知无效方案

Xvfb + xdotool: bypasses real keyboard processing entirely
uinput + Xvfb: Xvfb does not consume kernel input devices
SSH for TUI testing: PTY layer distorts input encoding; use SSH only for deployment
Raw
asciinema rec
: true-input records via
```
wf-recorder
```
(Wayland screen capture), not asciinema. Use
```
tctl --record
```
or
```
tctl record start/stop
```
. Calling
```
asciinema rec
```
directly has no access to the compositor and produces nothing useful.

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