无头终端

概述

使用 ht（来自 <https://github.com/montanaflynn/headless-terminal>）作为专用工具，处理在标准 stdin/stdout 控制下表现异常的终端程序。它提供真实的 PTY、终端状态快照以及明确的等待条件，使代理能够可靠地驱动 TUI 应用，而无需猜测屏幕何时稳定。

不要让锤子让所有东西看起来像钉子。ht 功能强大但开销较大；如果普通命令、管道、exec 配合 pty=true，或 tmux 会话更合适，请优先选择这些方案。

工作流程

1. 在决定使用此路径前，确认 ht 已安装。
2. 判断任务是否真的需要 ht；明确拒绝过度使用“锤子-钉子”式方案，优先尝试更简单的 shell 或主机代理原语，若它们适用。
3. 使用 ht run 创建一个唯一命名的会话。
4. 发送最小且有意义的按键输入。
5. 等待确定性条件达成。
6. 使用 ht view 进行快照。
7. 任务完成后停止并移除会话，除非用户明确希望保留持久会话。

选择 ht 与其他工具

使用 ht 的情况包括：

• 程序需要真实 TTY 并重绘整个屏幕
• 交替屏幕行为重要
• 光标位置或屏幕状态关键
• 任务需要在按键发送后获得可靠的等待
• 需要获取终端状态的文本或 PNG 快照

优先使用 exec / process 的情况包括：

• 命令为常规 shell I/O
• 输出是逐行的，不依赖屏幕状态
• 不涉及全屏 TUI
• exec 配合 pty=true 已足够满足 TTY 检查，无需屏幕快照

优先使用 tmux 的情况包括：

• 有人会直接监控或恢复会话
• 会话持久性和人类可见性比终端快照更重要

预检检查

首先检查可用性：

command -v ht

如果 ht 缺失，应明确说明，并切换到其他工具或询问是否安装。推荐安装源为 Montana Flynn 的 headless-terminal：

brew install montanaflynn/tap/ht

若无 Homebrew，可从 <https://github.com/montanaflynn/headless-terminal/releases> 下载与主机操作系统/架构匹配的 release tarball，然后将 ht 二进制文件放入 PATH。

发布时的安全/信任策略：

• Tap 安装和 release tarball 仍属于信任决策；需明确指出仓库/作者。
• 优先选择官方 tap 或 release 资产，而非随机包或复制粘贴脚本。
• 若用户对安全敏感，建议在安装前审查 GitHub 仓库和 release 页面。

重要澄清：并非所有名为 ht 或 headless-terminal 的包都是此 CLI 工具。在 macOS/Homebrew 上，核心公式 ht 实际指 HTE（用于可执行文件的查看器/编辑器/分析器），而非本工具。公共 npm 包 headless-terminal 是一个旧版库，可能不支持所需的 ht run / ht send CLI。切勿凭猜测安装；务必确认候选工具明确支持本技能所用命令。

核心命令

ht run --name demo-$(date +%s) <cmd...>
ht send demo "keys..." --wait-idle 200ms --view
ht view demo
ht view demo --format png > screenshot.png
ht wait demo --wait-text "READY"
ht stop demo
ht remove demo

命令名称和标志具有版本敏感性。若 ht --help 可用，应先查阅以确认不常用标志（如 PNG 输出、光标等待）的有效性。

等待策略

这是使用 ht 的主要原因。

按优先级顺序推荐：

1. 当已知字符串出现时，使用 --wait-text
2. 当光标位置可预测时，使用 --wait-cursor
3. 当应用重绘后趋于稳定时，使用 --wait-idle
4. 仅当无更好选项时，才使用 --wait-duration

避免在存在真实等待条件时依赖盲目的延迟。

实用模式

安全驱动 vim

ht run --name notes vim /tmp/notes.md
ht send notes "ihello<Esc>" --wait-idle 200ms --view
ht send notes ":wq<CR>" --wait-exit
ht remove notes

通过 SSH 驱动远程 TUI

ht run --name remote ssh user@host.example
ht send remote "top<CR>" --wait-idle 500ms --view
ht send remote "q" --wait-idle 200ms
ht send remote "exit<CR>" --wait-exit
ht remove remote

检查 git add -p

ht run --name addp git add -p
ht view addp

随后逐个发送选择项，并在每次响应后等待。

操作指导

• 使用唯一命名的会话，确保后续命令清晰可读，避免与旧运行冲突。
• 仅发送最小必要按键；避免大段粘贴。
• 任何状态变更输入后，应在假设成功前捕获最新快照。
• 若屏幕显示异常，应先使用 ht view 检查，再发送更多按键。
• 使用 ht remove 清理已退出的会话。
• 在涉及隐私敏感认证流程、远程系统或破坏性 TUI 操作前，应先征询意见。真实 PTY 可能导致快速造成实际损害。

失败情形

• 若程序立即退出，检查命令、工作目录，以及程序是否拒绝非交互式/未知终端。
• 若等待超时，改用其他等待条件，而非叠加更长的延迟。
• 若捕获的屏幕内容陈旧或空白，检查应用是否使用了交替屏幕、是否需要更大的终端尺寸，或是否已退出。
• 若任务简单到足以用普通 shell 控制，应停止使用 ht 并简化方案。
• 若会话供人类长期保留，tmux 通常是更好的容器。

参考资料

• references/examples.md：快速适配检查、示例命令模式和等待策略示例
• references/keys.md：vim 风格按键表示法，如 <CR>、<Esc>、方向键、控制/元键及原始字节
• references/waits.md：等待策略决策树与超时指引
• references/recipes.md：vim、REPL、安装程序、watch、终端尺寸、截图与录制等实用配方
• references/troubleshooting.md：退出码、陈旧视图、等待超时、僵尸进程、守护进程问题及 ht debug 用法