terminal-control

终端控制

使用 termctrl 观察终端实际可见状态，并以确定的方式进行交互。

从最精简的工作流开始

当无需进一步交互时，读取已稳定的临时终端应用可见屏幕：

termctrl show -- my-terminal-app

需要交互或重复检查时，让应用保持运行：

termctrl start app -- my-terminal-app
termctrl wait app "Ready"
termctrl show app
termctrl send app text:help enter
termctrl wait app "Commands"
termctrl show app
termctrl stop app

使用后务必停止已命名的会话，除非用户明确要求保留运行中的进程。

在当前终端窗格中保持应用可见并由人类控制，同时向 Agent 提供相同的会话控制：

termctrl run -- /usr/bin/nvim
termctrl run editor -- nvim

不带 NAME 的形式会使用可执行文件的基本名称（nvim），若名称冲突则会失败；它不会自动选择带后缀的名称。运行多个副本时，请指定名称。

选择正确的观察方式

• 使用 show 查看当前可见的屏幕文本。分析全屏 TUI 时，优先使用它。
• 使用 logs 查看普通屏幕工具和类似日志的命令所保留的可读输出。
• 仅在需要持久化产物时使用 save --format ... --out ...。
• 仅在明确使用 --record 录制时间线后，才使用 video。

不要把日志当作备用屏幕 TUI 的可见状态。

默认情况下，命名会话的读取会立即返回。仅在有意等待输出稳定时才添加等待时间。wait 默认等待五秒；只有需要更改时才设置 --timeout。

快速演示时，让会话保持运行，除非有意放慢输入，否则省略 --pace-ms，并在一次 shell 调用中组合已知的状态转换：

termctrl send app text:help enter && termctrl wait app "Commands" && termctrl show app

文本出现后，等待即会结束；超时是最长等待时间，而非固定延迟。不要在这些命令之间插入休眠。交互期间检查文本，仅在需要视觉检查或用户要求提供证据时保存 PNG，并在操作应用后导出视频。使用 MCP 时，优先使用带 waitFor 的 interact，以便在一次工具调用中组合键盘输入、就绪检测和屏幕读取。

精确驱动输入

使用 text:<value> 发送纯文本，并将命名按键作为独立的输入单元：

termctrl send app text:/connect enter
termctrl send app down enter
termctrl send app ctrl-c
printf '%s' 'multiline prompt' | termctrl send app --stdin

发送输入后使用 wait，不要休眠或假设界面已经更新。

对于支持鼠标的应用，使用带类型的鼠标命令和从零开始的单元格坐标：

termctrl mouse app move 12 4
termctrl mouse app click 12 4
termctrl mouse app down 12 4
termctrl mouse app move 20 4
termctrl mouse app up 20 4

未按住按键时，move 会悬停；按下、移动和抬起则用于拖动。--button right 或 middle、--shift、--alt 和 --ctrl 均为可选项。应用必须启用鼠标报告；悬停需要启用任意事件跟踪。超出调整后视口范围的坐标会导致失败。不要通过注入原始转义序列来绕过已禁用的鼠标报告。如果命令有此要求，请重启较早创建的命名会话。

录制演示时，可选择使用 video --pointer-overlay，以平滑移动、轻微按压形变和淡入淡出的效果显示鼠标输入。该功能默认使用 60 fps，且不会延迟实际输入。使用 --pointer-reduced-motion 可仅保留淡入淡出效果。剪辑、变速和定格编辑均沿用同一源时钟。只有带类型的鼠标命令会提供叠加层证据；原始字节和转发的人类输入不会。show/save 保持为纯终端证据，与视频叠加层分开。

操作 OpenTUI 应用

对于 OpenCode 等应用，请使用 OpenTUI 主机握手：

termctrl start app --host opentui --cols 112 --rows 34 -- opencode
termctrl wait app "/connect"
termctrl show app
termctrl show app --format semantic

如果应用需要更大的可见区域，请使用 resize。有意重启应用后，使用 restart app 复用已存储的启动设置。

有意保留证据

仅保存请求的格式：

termctrl save app --format txt --format png --out artifacts/current

仅当用户需要保留时间线或视频时，才录制演示。会话运行期间添加标记，停止后检查标记，然后使用明确的编辑计划导出：

termctrl start app --record artifacts/run.termctrl -- my-terminal-app
termctrl wait app "Ready"
termctrl mark app ready
termctrl send app text:demo enter
termctrl wait app "Done" --timeout 60000
termctrl mark app done
termctrl stop app
termctrl markers artifacts/run.termctrl
termctrl show --recording artifacts/run.termctrl --at-marker done
termctrl video artifacts/run.termctrl --edit artifacts/run-edit.json --footer --out artifacts/run.mp4

当终端文本需要保持可读时，谨慎设置编辑计划中的 speed 值。如果最后一帧是重点，请使用 hold_ms 或 --tail-ms。如果精美演示需要在底部页脚显示片段说明、已用时间码和 TERMINAL CONTROL 品牌标识，请传入 --footer；普通视频则省略。

请将 .termctrl 录制文件、ANSI 转录文本、屏幕内容、命令参数和终端输入视为可能包含敏感信息。除非确有需要，否则不要保留，也不要不必要地暴露其内容。

从问题中恢复

• 运行 termctrl status app 检查状态和启动设置。
• 运行 termctrl list 查找正在运行的命名会话。缩小查找范围时，可添加 --state、--command 或 --cwd；仅当需要查看已保留但已退出或不可用的条目时，才使用 --all。
• MCP Agent 可以向 list_sessions 传入 state、command 或 cwd，并使用 get_session_status({ name }) 获取完整的结构化状态，无需解析 CLI 输出。
• 如果会话套接字路径过长，请在启动会话前将 TERMCTRL_RUNTIME_DIR 设置为 /tmp 下的短路径私有目录。
• 如果无法使用 termctrl，请通过 cargo install terminal-control 安装 Terminal Control，或询问用户要使用哪个已安装的二进制文件。