agent-tui

🚨 重要：macOS 守护进程变通方案与 Gemini CLI 用法 🚨

在此 macOS 环境中使用 agent-tui 时，默认的后台守护进程化流程会崩溃，导致出现 Connection refused (os error 61) 错误。

运行任何 agent-tui 命令之前，必须先使用 TTY 挂断保护手动启动守护进程。 仅使用 nohup 不够；必须使用 tmux 提供完全隔离的伪终端。

为支持并行运行，仅在守护进程当前未运行时才重启它：

# Check if daemon is alive, start it in tmux if it is not
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

会话 ID 与 PID（重新连接时至关重要）

agent-tui run 返回 JSON 时，其中包含 session_id 和 pid。pid 仅供参考（子命令的操作系统进程 ID）。重新连接或发送命令时，不要使用 pid。必须始终使用 session_id（例如，--session <id>）。

如果守护进程崩溃（os error 61），伪终端就会被销毁。即使子进程的 pid 作为孤立进程继续运行，也无法重新连接到它。必须使用上文的变通方案重启守护进程，并启动一个全新的会话。

测试 Gemini CLI

使用 agent-tui 测试 Gemini CLI 时，必须遵循以下严格要求，确保行为确定且准确：

1. 运行前先构建：agent-tui 运行的是已构建的 JS 文件，而非 TypeScript。更改代码后、通过 agent-tui 启动 CLI 之前，必须运行 npm run build 或 npm run build:all。
2. 绕过信任确认弹窗：始终在环境中传入 GEMINI_CLI_TRUST_WORKSPACE=true。否则，任何新的项目级 Agent 或扩展都会触发全屏的「确认并启用」弹窗。该弹窗会抢占焦点、拦截自动化按键，并导致 agent-tui wait 命令超时。
3. 隔离环境：如果需要在没有真实用户凭据或现有 Agent 干扰的情况下测试，请使用 GEMINI_CLI_HOME=<some-test-dir> 隔离全局设置。
4. 测试状态变化（例如重新加载）：如果要测试报告状态变化的功能（例如，/agents reload 输出「1 new local subagent」），必须：
   • 先启动 CLI，以便它建立基线注册表。
   • 使用单独的 shell 命令（在 agent-tui 之外）写入新的 Agent .md/.toml 文件。
   • 使用 agent-tui type 和 press，在运行中的会话内触发 /agents reload 命令。
   • （如果在启动 CLI 之前添加文件，它们会成为基线的一部分，不会触发状态变化逻辑。）

# Example: Standard isolated run (sandboxed config + bypass trust modals)
env GEMINI_CLI_TRUST_WORKSPACE=true GEMINI_CLI_HOME=test-gemini-home agent-tui run -d "$(pwd)" node packages/cli/dist/index.js

掌握终端自动化

前提条件

• 支持的操作系统：macOS 或 Linux（暂不支持 Windows）。
• 验证安装：

agent-tui --version

如果尚未安装，请使用以下任一方式：

# Recommended: one-line install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh | sh

# Package manager
npm i -g agent-tui
pnpm add -g agent-tui
bun add -g agent-tui

# Build from source
cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui

如果使用了安装脚本，请确保 ~/.local/bin 位于 PATH 中。

理念：终端自动化为何与众不同

从观察者的角度来看，终端 UI 是无状态的。与拥有持久 DOM 的 Web 浏览器不同，终端自动化处理的是不断刷新的字符网格。这一根本区别决定了以下一切：

Web 自动化	终端自动化
DOM 在交互过程中保持不变	屏幕缓冲区不断重绘
选择器稳定	文本位置可能变化
查询一次，执行多次	每次操作前都必须重新验证
网络事件表示操作完成	必须检测视觉稳定性

核心认识：agent-tui 让你拥有视觉能力，却没有记忆。每张截图都是一次全新的观察。UI 变化后，先前状态便毫无意义。这并非局限，而是终端交互的本质。

心智模型：反馈循环

将终端自动化视为一个闭环控制系统：

    ┌──────────────────────────────────────────────┐
    │                                              │
    ▼                                              │
OBSERVE ──► DECIDE ──► ACT ──► WAIT ──► VERIFY ───┘
   │                                        │
   │                                        │
   └─────── NEVER skip ◄────────────────────┘

每个阶段都不可或缺。 跳过验证是自动化不稳定的首要原因。

“全新视角”原则

每次需要与 UI 交互时：

1. 重新截图 — 之前的截图已经过时
2. 通过视觉定位目标 — 文本位置可能已发生变化
3. 验证状态 — UI 可能意外发生了变化
4. 仅在界面稳定时操作 — 动画和加载状态会导致失败

这种做法看起来更慢，但这是唯一可靠的方法。乐观地复用过时状态会导致间歇性故障，而且很难排查。

关键规则（不可妥协）

规则 1：原子化执行（禁止流水线式操作） 严禁使用 && 链接命令（例如，type "x" && press Enter && wait）。模态窗口或 UI 更新可能会拦截按键。必须一次只执行一个原子操作，等待、截图并验证，然后在新的一轮中再执行下一步操作。

规则 2：每次操作后重新截图 任何变化都会使 UI 状态失效。再次操作前务必重新截图。

规则 3：绝不在不稳定的 UI 上操作 如果 UI 正在播放动画、加载或过渡，先执行 wait --stable。在过渡期间操作会引发竞态条件。

规则 4：宣称成功前先验证 使用 wait "expected text" --assert 确认结果。不要假定操作已生效——要用证据证明。

规则 5：错误恢复 如果 wait 命令超时，切勿盲目重启或终止会话。执行 screenshot，通过视觉检查流程被哪个意外的 UI 元素（模态窗口、错误对话框、焦点丢失）拦截。

规则 6：清理会话 始终以 agent-tui kill 结束。遗留的会话会消耗资源，并可能干扰后续运行。

决策框架

选择哪种截图模式？

解析自动化输出时使用 screenshot --format json；需要人类可读的文本时使用普通的 screenshot。

如何等待？

What are you waiting for?
│
├─► Specific text to appear
│   └─► `wait "text" --assert` (fails if not found)
│
├─► Specific text to disappear
│   └─► `wait "text" --gone --assert`
│
├─► UI to stop changing (animations, loading)
│   └─► `wait --stable`
│
└─► Multiple conditions
    └─► Chain waits sequentially

如何操作？

What do you need to do?
│
├─► Type text into the terminal
│   └─► `type "text"`
│
├─► Send keyboard shortcuts/navigation
│   └─► `press Ctrl+C` or `press ArrowDown Enter`

核心工作流

标准自动化循环：

# 1. START: Launch the TUI app
agent-tui run <command> [-- args...]

# 2. OBSERVE: Get current UI state
agent-tui screenshot --format json

# 3. DECIDE: Based on text, determine next action
# (This happens in your head/code)

# 4. ACT: Execute the action
agent-tui type "text"
agent-tui press Enter

# 5. WAIT: Synchronize with UI changes
agent-tui wait "Expected" --assert    # or wait --stable

# 6. VERIFY: Confirm the outcome (often combined with step 5)
# If verification fails, handle the error

# 7. REPEAT: Go back to step 2 until done

# 8. CLEANUP: Always clean up
agent-tui kill

反模式（不要这样做）

❌ 在动画播放或加载期间操作

# WRONG: Acting immediately on dynamic UI
agent-tui run my-app
agent-tui screenshot --format json    # UI might still be loading!
agent-tui type "value"                # ❌ Might miss the input field

# RIGHT: Wait for stability first
agent-tui run my-app
agent-tui wait --stable               # Let UI settle
agent-tui screenshot --format json    # Now it's reliable
agent-tui type "value"

❌ 未经验证就假定操作成功

# WRONG: Assuming the type worked
agent-tui type "value"
agent-tui press Enter
# ...proceed as if success...       # ❌ What if it failed silently?

# RIGHT: Verify the outcome
agent-tui type "value"
agent-tui press Enter
agent-tui wait "Success" --assert    # ✓ Proves the action worked

❌ 跳过清理

# WRONG: Forgetting to kill the session
agent-tui run my-app
# ...do stuff...
# script ends                        # ❌ Session left running!

# RIGHT: Always clean up
agent-tui run my-app
# ...do stuff...
agent-tui kill                       # ✓ Clean exit

开始之前：明确需求

自动化任何 TUI 前，请收集以下信息：

1. 命令：具体要运行什么？（my-app --flag 还是 npm start？）
2. 成功标准：出现什么文本或状态表示成功？
3. 输入顺序：按什么顺序输入哪些按键或数据？
4. 安全性：提交表单、删除数据等操作是否安全？
5. 身份验证：是否需要登录？是否有测试凭据？
6. 实时预览：用户是否想要观看？（agent-tui live start --open）

如果其中任何一项不明确，请先询问，再运行。

演示模式：展示 agent-tui 的功能

当用户询问 agent-tui 是什么、想看演示，或询问“展示一下它的工作方式”时：

1. 不要解释，直接演示。 行动胜于言语。
2. 使用实时预览，让用户能够实时观看。
3. 运行 top——它通用易用，并能显示动态实时更新。

快速演示触发语：

• “agent-tui 是什么？” / “agent-tui 能做什么？”
• “演示 agent-tui” / “给我看看 agent-tui”
• “agent-tui 如何工作？” / “看看它的实际效果”

故障恢复

症状	诊断	解决方案
“未找到文本”	视图过时或文本位置已变	重新截图，再次定位文本
等待超时	UI 未达到预期状态	检查截图，验证预期
“守护进程未运行”	守护进程崩溃或尚未启动	agent-tui daemon start
布局异常	终端尺寸错误	agent-tui resize --cols 120 --rows 40
会话无响应	应用崩溃或卡住	执行 agent-tui kill，然后重新运行
反复失败	存在根本性问题	尝试 3–5 次后停止，并询问用户

自我探索：使用 --help

你不必记住每个标志。CLI 会自我说明：

agent-tui --help                     # List all commands
agent-tui run --help                 # Options for 'run'
agent-tui screenshot --help          # Options for 'screenshot'
agent-tui wait --help                # Options for 'wait'

有疑问时，就询问 CLI。 此技能会教你何时以及为何使用命令。关于准确的标志和语法，请以 --help 为准。

快速参考

# Start app
agent-tui run <cmd> [-- args]        # Launch TUI under control

# Observe
agent-tui screenshot                  # Plain text view
agent-tui screenshot --format json    # Machine-readable output

# Act
agent-tui press Enter                 # Press key(s)
agent-tui press Ctrl+C                # Keyboard shortcuts
agent-tui type "text"                 # Type text

# Wait/Verify
agent-tui wait "text" --assert        # Wait for text, fail if not found
agent-tui wait "text" --gone --assert # Wait for text to disappear
agent-tui wait --stable               # Wait for UI to stop changing

# Manage
agent-tui sessions                    # List active sessions
agent-tui live start --open           # Start live preview
agent-tui kill                        # End current session