Term-CLI 实战指南：让 AI 编程 Agent 自由操控交互式终端

AI 编程 Agent 在执行命令时，一旦遇到交互式程序就会「卡死」——npm run dev 启动的开发服务器阻塞了后续操作，pdb 调试器停在断点前等待输入，vim 编辑文件时 Agent 完全不知所措，ssh 连接需要密码时只能干等。这些交互式终端程序构成了 AI Agent 自动化的「最后一公里」障碍：Agent 能写代码、能读文档，但面对终端的交互式环节却寸步难行。

Term-CLI 正是为解决这个问题而生。它是一个单文件 Python 工具，通过 tmux 后台会话让 AI Agent 在独立终端中运行交互式程序，支持发送按键、捕获输出、等待特定文本，并能在需要时借助 term-assist 将控制权交还给人类。BSD 许可证，680+ 测试，CI 全覆盖。

安装与环境

Term-CLI 依赖 Python 3.8+ 和 tmux，一行命令即可完成安装：

brew install tmux

sudo apt install tmux

curl -fsSL https://raw.githubusercontent.com/EliasOenal/term-cli/main/install.sh | bash

安装完成后，你会在系统中获得两个命令：term-cli（面向 Agent）和 term-assist（面向人类）。想从源码安装也行：

git clone https://github.com/EliasOenal/term-cli.git
cd term-cli && ./install.sh

Term-CLI 还为 Claude Code、OpenCode、Copilot CLI 等主流 Agent 提供了 skills 文件，安装脚本会自动部署。即使没有 skill，让 Agent 读一遍 term-cli --help 也足够它理解全部用法——CLI 本身是自文档的。

场景一：管理后台开发服务器

AI 编程 Agent 最常见的交互式任务就是启动开发服务器。Agent 需要启动 npm run dev，然后持续监视输出，最后在需要时关闭它。用 Term-CLI 可以轻松实现这个循环：

term-cli start --session server

term-cli run --session server "npm run dev"
term-cli wait-idle --session server --timeout 15
term-cli capture --session server

term-cli send-key --session server C-c
term-cli wait --session server

term-cli kill --session server

这个模式有三个关键动作：start 创建独立的 tmux 会话，run --wait 在会话中执行命令并等待其就绪，capture 捕获当前屏幕内容让 Agent 检查运行状态。wait-idle 则会等待输出稳定后再返回，避免读取到半截输出。

对于 Python 调试场景，Agent 可以像这样操作 pdb：

term-cli start --session debug
term-cli run --session debug "python3 -m pdb script.py"
term-cli wait -s debug && term-cli send-text -s debug "b 42" --enter
term-cli wait -s debug && term-cli send-text -s debug "c" --enter
term-cli wait -s debug && term-cli capture -s debug

第 42 行设置断点，c 继续执行直到命中，capture 获取当前调用栈和变量状态。整个调试流程 Agent 可以自主完成。

场景二：SSH 远程操作与文件传输

SSH 是最典型的交互式程序——需要密码认证、会遇到 MFA 提示、或者连锁跳板机。Term-CLI 的 request 机制让人机协作处理密码环节变得自然流畅。

Agent 侧（发起操作）：

term-cli start --session remote
term-cli run --session remote "ssh user@server"
term-cli wait --session remote
term-cli capture --session remote

term-cli request --session remote --message "请输入 SSH 密码"
term-cli request-wait --session remote

term-cli capture --session remote
term-cli run --session remote "ls -la" --wait

人类侧（远程协助）：

term-assist list                       # 看到 "remote: 请输入 SSH 密码"
term-assist attach --session remote    # 加入会话，看到密码提示
term-assist done --session remote

Term-CLI 还内置了文件传输能力，支持 gzip 压缩和 SHA-256 校验：

term-cli upload --session remote ./deploy.tar.gz /tmp/deploy.tar.gz

term-cli download --session remote /var/log/app.log ./app.log

cat config.json | term-cli upload --session remote - /app/config.json
term-cli download --session remote /app/data.csv - | head -5

upload 和 download 的管道支持（- 表示 stdin/stdout）让 Agent 可以无缝集成数据流，无需先写临时文件再上传。

场景三：系统恢复与免交互安装

一些最棘手的终端场景来自系统恢复和包管理——GRUB 救援 shell、fsck 修复确认、apt-get install 的交互式提示、Debconf 配置向导。这些程序无法通过 --yes 或 -y 参数跳过，必须人工确认，但对 Agent 来说却是「一步一卡」的痛点。

Term-CLI 的 wait-for 模式可以精准等待特定文本出现，然后自动处理已知的交互环节：

term-cli start --session recovery
term-cli run --session recovery "apt-get install postfix"

term-cli wait-for --session recovery "Postfix Configuration" --print-match
term-cli send-key --session recovery Enter

term-cli wait-for --session recovery "System mail name"
term-cli send-text --session recovery "example.com" --enter
term-cli wait-idle --session recovery

term-cli capture --session recovery

关键技巧是 run 不使用 --wait 参数，让命令在后台运行——因为安装程序不会主动退出，Agent 需要改用 wait-for 等待特定文本出现后发送按键。如果 Agent 无法处理的复杂交互（如 Debian 的 tzdata 时区配置），可以再次使用 request 请求人类协助：

term-cli request --session recovery --message "需要选择时区，请帮忙完成 tzdata 配置"
term-cli request-wait --session recovery

term-assist 还可以反过来使用：人类先创建一个锁定的会话并登录到服务器，Agent 再以只读模式加入观察，然后解锁后接管操作。这种「人类开路，Agent 执行」的模式特别适合需要两步认证或 VPN 的远程环境。

最佳实践

1. 善用等待策略：Term-CLI 提供三种等待方式——wait（等待 shell 提示符）、wait-idle（等待输出稳定）、wait-for（等待特定文本）。开发服务器用 wait-idle，SSH 用 wait-for "password"，调试器用 wait 等待 (Pdb) 提示符。不要只依赖一种。

1. 会话复用而非反复创建：一次 start 后可以多次 run 和 capture，无需为每个命令创建新会话。同一个会话中连续执行命令就像在同一个终端中操作一样，状态完全保留。

1. 锁定会话保护敏感操作：当人类需要保护某个会话不被 Agent 干扰时，使用 term-assist lock --session NAME。锁定后 Agent 只能 capture 读取状态，不能 send-text 或 send-key。解锁前 Agent 无法执行任何写入操作。

1. 文件传输使用管道：upload 和 download 的 - 管道参数非常强大，可以直接配合 cat、head、tail 等命令，避免 Agent 写临时文件的路径约定问题。

1. 退出码判断：Term-CLI 的退出码有明确语义——3 表示超时、4 表示人类提前断开、5 表示会话已锁定。Agent 可以据此决定重试、等待还是跳过。

总结

Term-CLI 巧妙地解决了 AI 编程 Agent 面对交互式终端的「卡壳」问题，用一个单文件 Python 脚本 + tmux 的组合，覆盖了从开发服务器到 SSH 远程、从调试器到系统恢复的完整终端交互场景。它的 term-cli / term-assist 双工具设计让人机协作的边界清晰自然——Agent 能自主处理大部分交互，而在密码、MFA、复杂配置等环节可以无缝交给人类处理。

对于深度使用 Claude Code、Codex、OpenCode、Cursor 等 AI 编程工具的开发者来说，Term-CLI 补上了自动化链条中最容易被忽视的一环。有了它，你的 AI Agent 不再被 vim、pdb、npm run dev 和 ssh 挡住去路。

• GitHub: github.com/EliasOenal/term-cli
• 许可证: BSD-3-Clause