mcpField
A
agent-tui

agent-tui

github.com/pproenca测试与质量12273 次安装16 周前更新
代码仓库

关于 agent-tui

agent-tui 是用于自动化和验证终端 UI 会话的命令行技能。它引导 Agent 按快照与操作循环执行，并支持等待界面稳定或文本出现以及清理会话。

主要功能

  1. 01启动并管理 UI 会话
  2. 02以 JSON 捕获界面快照
  3. 03发送按键、文本和滚动输入
  4. 04等待界面稳定或断言通过
  5. 05清理会话

适用场景

  1. 01自动执行终端 UI 任务
  2. 02操作后验证 UI 变化
  3. 03运行可重复的会话检查

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pproenca/agent-tui --skill agent-tui

安装后在 Claude Code 中输入/agent-tui确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
assertions.md
clarifications.md
command-atlas.md
decision-tree.md
demo.md
flows.md
output-contract.md
prompt-templates.md
recovery.md
safety.md
session-lifecycle.md
test-plan.md
use-cases.md

详细介绍

agent-tui

快速开始

  • 验证安装：agent-tui --version
  • 使用 npm i -g agent-tui 安装（或使用 pnpm add -g agent-tui、bun add -g agent-tui）。
  • 其他安装方式：curl -fsSL https://raw.githubusercontent.com/pproenca/agent-tui/master/install.sh -o /tmp/agent-tui-install.sh && sh /tmp/agent-tui-install.sh 或 cargo install --git https://github.com/pproenca/agent-tui.git --path cli/crates/agent-tui。
  • 如果使用了安装脚本，请确保 ~/.local/bin 位于 PATH 中。
  • 启动会话：agent-tui run --format json <command> -- <args...>
  • 观察：agent-tui screenshot --format json
  • 执行操作：agent-tui press Enter、agent-tui type "text" 或 agent-tui scroll down
  • 等待或验证：agent-tui wait "Expected text" --assert 或 agent-tui wait --stable
  • 清理：agent-tui kill --yes

核心工作流

当前自动化循环：run -> screenshot -> press/type/scroll -> wait -> kill --yes。

  1. 使用 agent-tui run 运行应用，并从 JSON 输出中获取 session_id。
  2. 使用 agent-tui screenshot 或 agent-tui screenshot --format json 获取最新快照。
  3. 根据最新快照决定下一步操作。
  4. 使用 press、type 或 scroll 执行操作。
  5. 使用 wait --assert 或 wait --stable 进行同步。
  6. 从第 2 步开始重复，直到任务完成。
  7. 使用 agent-tui kill --yes 清理。

可靠性规则

  • 每次执行可能改变 UI 的操作后，都重新获取快照。
  • 屏幕变化时不要执行操作；先等待画面稳定。
  • 使用 wait --assert 验证结果，不要想当然地认为操作已成功。
  • 自动化运行结束时，务必执行 kill --yes 或 sessions cleanup --yes。

旧版迁移

新脚本请使用当前命令。旧版兼容形式仍可供旧脚本解析，但每条命令都会将弃用通知写入 stderr，同时保持 JSON stdout 可解析，并纳入下一主版本的移除计划。

  • agent-tui input "text" -> agent-tui type "text"。
  • agent-tui action <selector> click -> agent-tui press Enter。
  • agent-tui action <selector> fill <text> -> agent-tui type "<text>"。
  • agent-tui screenshot -e -> agent-tui screenshot。
  • agent-tui screenshot -a -> agent-tui screenshot。
  • agent-tui wait -e <ref> -> agent-tui wait "<text>"。
  • agent-tui scroll-into-view <selector> -> agent-tui scroll <direction> [amount] 或 agent-tui press ...；此兼容命令不会发送终端输入。

会话处理

  • 如果存在多个会话，每条命令都使用 --session <id>。
  • 如果丢失了会话 ID，请运行 agent-tui sessions 和 agent-tui sessions show <id>。

实时预览（可选）

  • 询问是否需要实时预览。
  • 启动预览：agent-tui live start --open
  • 使用 agent-tui live stop 停止独立预览状态；由守护进程提供的预览会持续可用，直到执行 agent-tui daemon stop --yes。

深入参考

  • 完整 CLI 覆盖范围和选项：references/command-atlas.md
  • JSON 输出规范：references/output-contract.md
  • 端到端命令序列：references/flows.md
  • 快速选择命令：references/decision-tree.md
  • 会话生命周期与并发：references/session-lifecycle.md
  • 断言与测试判定依据：references/assertions.md
  • 故障恢复指南：references/recovery.md
  • 安全与确认提示：references/safety.md
  • 澄清事项清单：references/clarifications.md
  • 测试计划模板：references/test-plan.md
  • 演示脚本：references/demo.md
  • 用户提示词模板：references/prompt-templates.md
  • 按使用场景分类的最小命令集：references/use-cases.md
  • Explorer/replay 自动化技能：../tui-explorer/SKILL.md

评论

支持 Markdown