ming-14/PTY-Agent

---

name: pty-agent description: Interactive CLI program proxy via subprocess or pseudo-terminal (PTY). Use when: (1) must maintain ongoing dialog with interactive programs (REPLs, debuggers, Servers) — send input and wait for specific prompts; (2) process may block, crash, or pop up GUI windows — need real-time state detection; (3) simulating user interaction tests. DO NOT use for: non-interactive scripts, web/HTTP API calls, GUI interfaces. If a plain script suffices, do not use this tool. allowed-tools: Bash, Read, Write, Edit

¿Qué hace PTY-Agent?

PTY-Agent 是一个命令行交互式程序交互代理，通过subprocess或伪终端（PTY）与交互式 CLI 程序双向通信

原理：程序后台有运行一个守护进程，由守护进程接受用户命令，对应CLI进行操作

程序位于app.py，运行方法：python app.py ...

何时使用

• 迫不得已必须与交互式程序持续对话，需要发送输入并等待特定输出（提示符）后再继续，如GDB、服务器Server、大程序的编译操作。但是能写脚本执行就不用PTY-Agent
• 进程可能阻塞或执行时间过长 — 需要定期检测状态
• 子进程可能崩溃 — 需要实时感知崩溃事件
• 被要求进行模拟用户操作的测试

何时不使用

• 非交互式任务
• 完全能写脚本执行、调试
• GUI界面，浏览器，复杂的TUI程序

命令速查

命令	用途	典型选项	示例
start/stop	手动启动/停止守护进程；启动守护进程exec可实现，一般无需手动
exec <new-session-id> <options>	执行命令以启动会话	-c "<command>"(req), -t "<regex>", --timeout <seconds>, --cwd <path>	exec id_py -c "python -i" -t ">>>"
send <session-id> "<content>" [options]	发送输入到运行中的会话	-t "<regex>", --timeout <seconds>	send id_py "print(1)" -t ">>>"
read <session-id> [options]	读取会话输出	--lines, --grep	read myid --lines 10
list	列出所有会话
kill <session-id>	终止会话
events <session-id> [options]	查看会话事件	--last <N>, --since <iso-datetime|HH:MM>	events myid --last 10
closewin <session-id> <window-handle>	关闭 GUI 窗口；<window-handle>支持十进制或 0x十六进制

命令 send 的返回条件

模式	条件	返回信息
带trigger	匹配到正则	增量输出
带idle-timeout	静默超时	增量输出
带timeout	达到超时	增量输出
都不带	达到默认超时	增量输出
未关闭GUI检测	检测到GUI窗口（subprocess不一定可用）	GUI窗口信息+增量输出
	有进程崩溃	相关事件+增量输出
	程序退出	增量输出

注：高效利用本程序的条件返回功能，及时根据对应程序的输出结果更新条件（特别是-t），灵活使用不同的返回条件。不建议终端执行Sleep，不建议反复send后又read

exec 用法

python app.py exec <session-id> <options>

选项基本与 send 一致 特殊选项：

• -c "<command>"(req) 执行的命令，必填
• --shell <shell> 支持cmd/powershell/pwsh/bash（默认PowerShell，环境不支持自动回退CMD）；只有在exec启动时才能配置终端
• --pty 启用完整伪终端（不支持 |、&& 等shell语法）
  • --force-pty-mode 忽略--pty下的shell操作符检测
• --cwd <path> 子进程工作目录，不填则默认为调用者（客户端）的工作目录；如果与期望工作目录不一致，建议指定

send 用法

python app.py send <session-id> "<content>" [options]

选项

• -t/--trigger "<regex>" 匹配正则
  • --newline — 换行后才检查正则触发条件, 与-t搭配
• --timeout <seconds> 等待超时（默认120s）
  • --idle-after-first-output 首次输出后才开始检测静默，与--idle-timeout搭配
  • 注：高效利用本程序的条件返回功能，及时根据对应程序的输出结果更新条件（特别是-t），灵活使用不同的返回条件。不建议终端执行Sleep，不建议反复send后又read
• --idle-timeout <seconds> 输出静默超时，程序在指定时间内不输出时触发条件
• --full 返回终端全部数据（数据大，尽量用--lines N）
• --json-escaping JSON 转义模式，将<content>进行JSON转义（\\ \" \n \t \r \uXXX ...），建议在发送多行内容时使用

<content>末尾自动追加换行 没有--input参数

引号处理规则（命令行层）

• cmd 写 \" 嵌套： -c "python -c \"print(1)\""
• PowerShell/Pwsh 外层单引号，内层双引号： -c 'python -c "print(1)"'

read 用法

python app.py read <session-id> [options]

选项：

• --lines <N> 最后 N 行
• --lines start:end 范围行
• --grep "<regex>" 正则过滤
• --offset <bytes> 增量读取
• --full 返回终端全部数据（数据大，尽量用--lines N）

events 完整用法

python app.py events <session-id> [options]

选项：

• --last N
• --since <iso-datetime\|HH:MM>
• --until <iso-datetime\|HH:MM>

全局/通用选项

• --keep-ansi 保留控制码
• --color - 启用终端颜色输出
• --output-by-natural-language 自然语言输出
• --encoding <encoding> 终端编码，乱码时设置utf-8/gbk/gb2312/gb18030/big5
• --no-debug 禁用响应中的 debug 输出（进程树/GUI 窗口/事件）
• --show-config [KEY] 查看当前调用配置
• --default <KEY> <VALUE> 临时覆盖默认配置（可用键：output-by-natural-language/timeout/newline/keep-ansi/encoding/debug，<VALUE>是配置值或者on/off）

输出格式

1. JSON 模式（默认）— stdout 仅输出 JSON，每行一个 JSON 对象，。所有非命令响应（守护进程启停信息、配置查询、帮助文本、警告等）也以 JSON 格式输出：
   • 命令响应：{"type": "result", ...} / {"type": "ok", ...} / {"type": "error", ...}
   • 守护进程信息：{"type": "info", "message": "[pty-agent] 守护进程已启动 (端口 12345)"}
   • 配置查询：{"type": "config", "content": "当前调用配置:\n ..."}
   • 帮助文本：{"type": "help", "content": "usage: pty-agent ..."}
   • 警告信息：{"type": "warning", "message": "..."}
2. 自然语言模式 — 使用 --output-by-natural-language 切换

示例场景

长时运行进程监控 + 中途读取 + 终止

app.py exec srv -c "python server.py" --idle-timeout 3 # 启动，idle-timeout 使首次输出后快速返回
app.py read srv --lines 20 # 中途查看最近20行输出
app.py read srv --offset 1024 # 增量读取（从上次 offset 继续）
app.py read srv --grep "ERROR" # 只看错误行
app.py kill srv # 不再需要时终止

进程崩溃检测

app.py exec job -c "python worker.py" --idle-timeout 5 # 启动，idle-timeout 等待输出
# 若进程崩溃，返回中 trigger.reason="ended"，program.exit_code 非零，error_message 含崩溃信息
app.py events job --last 10 # 查看崩溃事件详情（process_crash 类型）