Real Terminal TUI Harness

real-terminal harness 在一个子进程中启动 OpenTUI 聊天界面，在 tmux 可用时通过 tmux 驱动它，必要时回退到 PTY，并将证据存储在 .artifacts/tui-real-terminal/runs 下。

Platform requirements

该 harness 运行在类 Unix 的终端环境中。Linux 和 macOS 可以直接运行它。Windows 用户需要 WSL2，因为该 harness 依赖 Unix 终端原语。它在 tmux 可用时优先使用 tmux， 并在缺少 tmux 时回退到 Unix 伪终端（Python 的 pty module）。

• Linux 和 macOS 可以使用 tmux 或 PTY 回退来运行确定性套件。
• 不支持原生 Windows shell，例如 PowerShell 和 cmd.exe：Python 的 pty module 仅限 Unix，而 tmux 没有原生的 Windows 构建。
• WSL2 仅作为 Windows 的兼容路径被提及；在 WSL2 内部，这就是 Linux 路径本身。

当你想使用 tmux driver 时安装 tmux：

# Debian/Ubuntu Linux, including WSL2:
sudo apt-get update && sudo apt-get install -y tmux

# macOS:
brew install tmux

仅限 Windows 的设置：

# In an elevated PowerShell, once:
wsl --install            # installs WSL2 + a default Ubuntu distro

# Then inside the WSL2 shell:
sudo apt-get update && sudo apt-get install -y tmux
uv run pytest tests/integration/cli/tui_real_terminal -q

当 tmux 与 PTY 都不可用时（例如原生 Windows CI）， probe_terminal_capabilities() 会报告 preferred_driver="none"，并且每个 scenario 测试都会以一个命名了缺失能力的 pytest.skip 原因被跳过——该运行不会 失败。纯逻辑 driver、capability-probe 与 scenario-model 单元测试在每个平台上都会 运行。

Commands

Fast smoke:

uv run pytest tests/integration/cli/tui_real_terminal/test_launch_input_loop.py -q

Full deterministic suite:

uv run pytest tests/integration/cli/tui_real_terminal -q

Manual lab:

uv run python scripts/tui_real_terminal_lab.py --scenario long_streaming --backend opentui

OpenTUI backend path:

uv run pytest tests/integration/cli/tui_real_terminal -q --tui-backend opentui

opentui backend 通过 real-terminal harness 运行确定性的 fake-provider apps。 存在一个受保护的 live-opentui backend，用于手动的真实 CLI smoke 检查：

OPENSQUILLA_TUI_LIVE_REAL=1 uv run pytest \
  tests/integration/cli/tui_real_terminal/test_live_opentui_real_cli.py -q \
  --tui-backend live-opentui --tui-driver tmux

OPENSQUILLA_TUI_LIVE_REAL=1 uv run python scripts/tui_real_terminal_lab.py \
  --scenario live_opentui_architecture_prompt --backend live-opentui

该 live smoke 以 OPENSQUILLA_TUI_BACKEND=opentui 启动 opensquilla chat --standalone，通过 tmux 驱动它，发送一个真实 prompt，并捕获 文本证据。请谨慎使用它，因为它可能会命中已配置的 live provider。

Evidence

每次运行都会写入：

• scenario.json
• terminal.log
• app.log
• transcript.txt
• frames/*.txt
• screenshots/
• result.json
• visual-verdict.json

能力缺失是显式的跳过。确定性的断言失败会阻塞。带 inspect 的 visual verdicts 在不阻塞无关 backend 变更的情况下保留证据。