AI 编程助手能够执行 shell 命令、读取文件和调用 API，但当程序需要人类交互输入时就会卡住。大多数 CLI 工具生来就是为人机交互设计的，传统的 bash 命令无法应对需要输入密码、选择菜单或填写表单的场景。tui-use 正是为解决这一痛点而生的开源框架，它让 AI agents 能够像人类一样操作终端中的任何交互式程序。
核心设计：PTY 与 Headless xterm 的协同
tui-use 的技术架构围绕三个关键组件构建：后台守护进程负责管理伪终端会话、@xterm/headless 提供无头终端模拟器、CLI 接口暴露原子操作供 agents 调用。当启动一个交互式程序时，框架会在 PTY 中 spawn 该进程，然后实时捕获其输出的 ANSI 转义序列。xterm headless 渲染器会处理颜色、清除屏幕、光标移动等所有终端控制码，最终输出纯净的纯文本内容供 agents 分析。这种设计确保了 screen 字段始终是干净的平面文本，无需自行重组原始字节流。
Snapshot Model：观察 - 决策 - 执行循环
与传统的流式输出处理不同，tui-use 采用了「快照模型」来抽象终端交互。agents 与终端程序的交互本质上是一个确定性循环：读取当前屏幕内容、根据内容决策下一步输入、发送按键、等待屏幕更新、重复上述步骤。框架将这个循环显式化，提供 snapshot 命令获取当前屏幕状态、type 或 press 命令发送输入、wait 命令等待屏幕变化。整个过程不依赖异步流、不需要猜测时序、不需要手动拼接部分输出。Snapshot 返回的数据结构包含 screen（纯文本内容）、highlights（反白区域列表，用于识别当前选中的菜单项或按钮）、title（窗口标题）和 is_fullscreen（全屏模式检测）等字段。
实际应用场景与集成参数
tui-use 的典型使用场景涵盖多个维度。REPL 会话场景下，agents 可以启动 Python、Node.js、psql 或 redis-cli，读取输出内容后决定下一步执行代码，无需编写一次性脚本。交互式脚手架工具场景支持自动完成 npm create、cargo new、create-react-app 等需要回答一系列问题的安装向导。数据库 CLI 场景允许 agents 直接操作 psql 或 mysql 执行查询、检查 schema，省去 ORM 层或单独 API 的间接调用。TUI 应用程序场景让 agents 能够控制 vim、lazygit、htop、fzf 等全屏程序，这些程序传统上几乎无法被脚本化。
核心 CLI 命令的参数化实践如下：启动程序使用 tui-use start --cwd /path --cols 120 --rows 30 "command -flags"，其中 cwd 指定工作目录、cols 和 rows 定义终端尺寸；获取快照使用 tui-use snapshot --format json 以结构化方式解析 highlights；等待特定内容出现使用 tui-use wait --text "pattern" --format json，设置超时时间默认为 3000 毫秒；发送输入支持 tui-use type "text\n"（带回车）或 tui-use press ctrl+c 发送控制键。Session 管理方面，tui-use list 查看所有活动会话、tui-use use session_id 切换上下文、tui-use kill 终止当前会话。对于 Claude Code 集成，可通过 /plugin marketplace add onesuper/tui-use 添加自托管市场，然后安装 tui-use@tui-use 插件获得 skill 定义。
局限性与工程选型考量
当前版本的 tui-use 存在两个主要工程限制。首先，仅支持 Unix PTY 环境，macOS 和 Linux 可直接使用，Windows 尚不支持（计划通过 ConPTY 实现）。其次，screen 字段输出纯文本，颜色和大多数样式信息被剥离，仅通过 highlights 字段保留反白区域（即终端程序标记选中项的标准方式）。这意味着依赖颜色区分输出内容的程序（如彩色日志可视化）需要调整策略，改用 highlights 或其他文本特征进行状态识别。部署时应确认目标运行环境的兼容性，对于需要跨平台支持的场景需评估是否等待 Windows 版本或考虑替代方案。
资料来源：GitHub 仓库 onesuper/tui-use [1]。