Gemini CLI 终端自动化测试指南：基于 tui-tester 与 agent-tui 的 TUI 行为验证实践

本文围绕 Gemini CLI 仓库中的 tui-tester 技能文档 展开，介绍如何使用终端自动化工具 agent-tui 对 Gemini CLI 的行为变更和视觉输出进行验证。读完后，你将掌握 TUI 回归测试的完整操作规程：如何安全启动测试守护进程、如何隔离配置环境、如何用“等待—断言”循环验证终端交互，以及如何诊断 os error 61 等典型故障。该技能与底层的 agent-tui 技能文档 配套使用，并在 changelog 中被记录为 “Enhanced TUI Testing” 能力。

一、tui-tester 技能的定位与核心职责

tui-tester 是位于 .gemini/skills/tui-tester/SKILL.md 的一个 Agent 技能（Skill），其定位是“使用终端自动化验证 Gemini CLI 行为变更与视觉输出的操作手册”。它定义了三项核心职责：

• Verify Behavior（行为验证）：确认代码变更能产生预期的终端交互；
• Visual Validation（视觉校验）：确保 TUI 在不同终端尺寸和状态下正确渲染；
• Regression Testing（回归测试）：借助自动化手段，防止已有交互式工作流被破坏。

需要理解的一点是：tui-tester 本身不实现终端自动化，它是操作规程，依赖 agent-tui 提供底层工具。agent-tui 的技能文档中明确说明其设计哲学——终端 UI 对观察者而言是无状态的：没有持久化的 DOM，只有不断重绘的字符网格，因此“每次动作之前都必须重新验证屏幕状态”。这一约束决定了 tui-tester 规程中“原子执行、循环验证”等规则的必要性。

二、关键协议（Critical Protocol）逐条解析

2.1 第一步：激活 agent-tui 技能

规程要求“你的绝对第一步动作必须是：激活 agent-tui 技能”。agent-tui 技能文档（.gemini/skills/agent-tui/SKILL.md）提供了终端自动化的全部底层能力，其命令集可归纳为：

agent-tui run <cmd> [-- args]        # 启动受控的 TUI 应用
agent-tui screenshot                 # 纯文本视图
agent-tui screenshot --format json   # 机器可读输出
agent-tui type "text"                # 输入文本
agent-tui press Enter / Ctrl+C      # 按键与快捷键
agent-tui wait "text" --assert       # 等待文本出现，未找到则失败
agent-tui wait "text" --gone --assert # 等待文本消失
agent-tui wait --stable              # 等待 UI 停止变化（动画/加载结束）
agent-tui sessions                    # 列出活跃会话
agent-tui live start --open           # 打开实时预览
agent-tui kill                        # 结束当前会话

2.2 环境准备：macOS / 并行安全的守护进程启动

agent-tui 的默认后台守护进程在 macOS 环境下可能崩溃，导致 Connection refused (os error 61)。tui-tester 规程给出了标准的“检查—兜底重启”脚本，保证全局守护进程在运行、且实时预览已打开：

if ! agent-tui sessions >/dev/null 2>&1; then
  tmux kill-session -t agent-tui 2>/dev/null || true
  agent-tui daemon stop 2>/dev/null || true
  rm -f /tmp/agent-tui*
  tmux new-session -d -s agent-tui 'agent-tui daemon start --foreground > /tmp/agent-tui-daemon.log 2>&1'
  sleep 1
fi
agent-tui live start --open

脚本的逻辑是：先用 agent-tui sessions 探测守护进程是否存活，只有不存活时才清理并重启（这正是“Parallel Safe”的含义——并行测试会话共享同一个守护进程，不能互相踩踏）；重启时必须用 tmux 提供完全隔离的伪终端，nohup 不足以防止 TTY hangup 导致的崩溃。

2.3 会话管理：session_id、原子执行与动作循环

• Session IDs：agent-tui run 返回的 JSON 中同时包含 session_id 和 pid。规程强调永远使用 session_id（如 --session <id>）进行后续交互，pid 仅是子命令的操作系统进程 ID，只供参考。agent-tui 文档还解释了原因：守护进程崩溃时伪终端即被销毁，即使子进程 pid 以孤儿形式存活也无法重连，只能重启守护进程并开启全新会话。
• Atomic Execution（原子执行）：每轮只执行一条命令，禁止用 && 串联（如 type "x" && press Enter && wait），因为弹窗或 UI 更新可能拦截你的按键序列。
• The Loop（动作循环）：Action -> Wait -> Screenshot -> Verify -> Next Action。这与 agent-tui 技能文档中的“OBSERVE → DECIDE → ACT → WAIT → VERIFY”闭环一致，跳过验证是自动化测试不稳定的首要原因。

2.4 Gemini CLI 专属要求：先构建、绕信任、隔离配置

要求	说明	仓库源码依据
Build First	测试本地变更前必须先执行 npm run build 或 npm run build:all，因为 agent-tui 运行的是构建后的 JS 而非 TypeScript	package.json 中 build 指向 node scripts/build.js，build:all 额外包含 sandbox 与 vscode 组件构建
Bypass Trust	设置 GEMINI_CLI_TRUST_WORKSPACE=true，避免新项目的 agent/extension 触发“Acknowledge and Enable”全屏弹窗——该弹窗会抢走焦点、吞掉自动化按键，导致 agent-tui wait 超时	trust.ts 中 checkPathTrust 首先检查该环境变量，为 'true' 时直接返回 { isTrusted: true, source: 'env' }
Isolate Config	使用 GEMINI_CLI_HOME 指定独立的“主目录”，防止真实凭据或既有配置干扰测试	paths.ts 中 homedir() 优先返回 GEMINI_CLI_HOME 环境变量值，否则回退到 os.homedir()

补充一点：CLI 命令行本身也提供了跳过信任交互的等价方式。从 config.ts 的源码可以看到，--skip-trust 参数在解析后会将 GEMINI_CLI_TRUST_WORKSPACE 置为 true，与环境变量方式殊途同归。

三、端到端工作流示例

规程给出的标准工作流是：启动 CLI → 等待提示符就绪 → 发送命令 → 断言输出：

# Start the CLI
env GEMINI_CLI_TRUST_WORKSPACE=true agent-tui run node packages/cli/dist/index.js

# Wait for the prompt
agent-tui wait "│" --assert

# Send a command
agent-tui type "/help"
agent-tui press Enter

# Verify output
agent-tui wait "Available Commands" --assert

逐行解读：

1. 启动：通过 env 注入 GEMINI_CLI_TRUST_WORKSPACE=true 后，用 agent-tui run 拉起 packages/cli/dist/index.js——即 package.json 中 build 脚本产物的 CLI 入口，而不是 npm start 的开发模式；
2. 等待：wait "│" --assert 等待渲染的提示符边框字符出现，--assert 保证未找到时命令失败而非静默通过；
3. 动作：type "/help" 与 press Enter 作为两条独立的原子命令执行，中间不做管道串联；
4. 验证：用 wait "Available Commands" --assert 证明 /help 确实渲染出了命令列表，而非假设成功。

agent-tui 技能文档还补充了一个对“状态差量”类功能（如 /agents reload 报告 “1 new local subagent”）至关重要的测试顺序：先启动 CLI 建立基线注册表，再在会话外写入新的 agent 文件，最后用 type/press 触发 reload；若在启动前就创建文件，它们会成为基线的一部分，差量逻辑便不会触发。

四、错误恢复策略

规程的错误恢复部分与 agent-tui 的失败恢复表可以对照使用：

症状	诊断与恢复
wait 超时	先截图诊断状态，不要盲目重启或 kill 会话
os error 61（守护进程连接被拒）	守护进程已崩溃、伪终端已销毁，用 2.2 节的 tmux 方法重启守护进程，并开启全新会话
“Text not found”	视图已过时或文本位置移动，重新截图定位
意外布局	终端尺寸不对，用 agent-tui resize --cols 120 --rows 40
会话无响应	应用崩溃或挂起，agent-tui kill 后重跑
反复失败	连续尝试 3–5 次仍失败时停止并上报

此外，agent-tui 文档要求每次自动化结束都以 agent-tui kill 清理会话——孤儿会话会消耗资源并干扰后续运行。

五、适用前提与延伸阅读

• 环境前提：agent-tui 支持 macOS 或 Linux（Windows 暂不支持）；可用 agent-tui --version 验证安装。
• 构建前提：所有 TUI 测试都针对 npm run build 后的产物；仓库根目录的 test、test:e2e 等 npm 脚本（package.json）覆盖了单元与集成测试，而 tui-tester 技能补充的是其中难以脚本化的“真实终端交互与视觉”层验证。
• 配套文档：底层工具细节见 .gemini/skills/agent-tui/SKILL.md；信任机制实现见 packages/core/src/utils/trust.ts 与 packages/cli/src/config/trustedFolders.ts；配置目录重定向见 packages/core/src/utils/paths.ts。

掌握本文的规程后，你可以将“改代码 → 构建 → 启动守护进程 → 原子动作循环 → 断言验证 → 清理会话”固化为 Gemini CLI 的 TUI 回归测试标准流程，在每次交互类改动后快速确认终端行为与视觉输出未被破坏。