--- name: pty-agent description: "Interactive CLI program proxy via 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; (4) download large files." --- [TOC] # PTY-Agent PTY-Agent 是一个**命令行交互式程序交互代理**，通过伪终端（PTY）与交互式 CLI 程序双向通信 原理：程序后台有运行一个守护进程，执行命令时需要再次调用程序，程序会call守护进程对对应CLI进行操作：你 <-> PTY-AgentCLI <-> PTY-Agent守护进程 <-> PTY 程序位于`app.py`，运行方法：`python app.py `，或者包执行等其他方法 ## 环境要求 Python>=3.8 requirements.txt 守护进程会向`~/pty-agent/`写日志和配置，若你在沙箱运行，请允许读写`~/pty-agent/` 出现守护进程报认证失败或其他启动错误，可以在用户允许的前提下，执行`app.py stop force` ## 两种运行模式 ### 终端模式 基于伪终端，有TTY，**输出始终为终端屏幕快照**，等效于实际用户使用时真正看到的部分 - 适用：TUI 程序（vim/htop）、需要回显/行编辑的交互式程序 - 快照返回条件：trigger 匹配快照文本 / idle-timeout / timeout / 进程结束 / GUI 检测 注意：pty 模式默认没有Shell包装，若要使用Shell，请使用`--shell ` ### 子进程模式（需显式--subprocess） 用 `subprocess.Popen` 直接捕获子进程的 **stdout 与 stderr**（无伪终端）， **增量输出**，无终端回显、无快照、无 resize。 - 适用：普通命令行程序（编译、脚本、下载），只需追踪输出流 - `exec`/`send`/`read` 返回增量文本；`read` 支持 `--offset` 增量读取 - **增量语义**：stdout/stderr 各有一个会话内消费游标（镜像关系）。`exec`/`send` 与默认 `read` 从"上次交付末尾"续读，两次调用之间写入的输出不会丢失； `-l/--column/--full` 是累积查询（从保留起点读，**不**推进游标）。 缓冲超限会从头裁剪最旧字节（游标前数据可能被丢弃，响应仍单调推进） - 输入通过写 stdin 注意：不要使用子进程模式运行需要TTY的会话！ ## 命令速查 | 命令 | 用途 | 典型选项 | 示例 | |------|------|----------|------| | `start/stop [options]` | 手动启动/停止守护进程；启动守护进程`exec`可直接启动，一般无需手动。未经用户运行，不要随便结束守护进程 | `stop --force`；`start --foreground`（前台/s6 监督）；`start --survive`（忽略结束信号与 stop，仅 SIGKILL 可终止） | | | `status` | 查看守护进程状态 | | | | `exec ` | 执行命令以启动会话 | `-c ""`(-c req), `-t ""`, `--cwd `, `--env KEY=VALUE`, `--subprocess`, `--shell ` | `exec id_py -c "python -i" -t ">>>"` | | `send ` | 发送输入到运行中的会话（原样，不转义） | `-i ""`(-i req), `-e `, `-t ""` | `send id_py -i "print(1)" -t ">>>"` | | `advsend ` | 发送输入到运行中的会话（JSON + 控制字符转义解码） | 同 `send` | `advsend server -i "{ctrl+c}" -e none` | | `read [options]` | 读取会话输出 | `-l `, `-g ""`, `-o ` | `read myid -l 10` | | `list` | 列出所有会话 | | | | `kill ` | 终止会话；会话结束后会变成`ended`状态，使用`kill`命令彻底去除且移出会话列表 | | | | `events [options]` | 查看会话运行程序生命周期事件 | `-l `, `--since ` | `events myid -l 10` | | `closewin ` | 关闭 GUI 窗口（**仅 Windows**）；``支持十进制或 0x十六进制| | | | `mouse ` | 发送鼠标动作到 PTY 会话 | `--button`, `--count`, `--ctrl`, `--shift`, `--alt`, `--grep` | `mouse myid click 10,5 --button right` / `mouse myid _get_cursor_location` | | `wait [--timeout ]` | 等待：有待消费通知立即返回摘要，否则等待指定秒数（通知到达即唤醒）。`--timeout` 可选（默认 120） | `--timeout ` | `wait --timeout 5` | | `notice ` | 查看通知的完整内容（`nid` 为 32 位十六进制串，来自 `wait` 返回的摘要） | | `notice 3f9c2a8b...` | | `workflow ` | workflow 脚本编排 | `run `（`--vars K=V`, `--parallel N`） / `list` / `show ` / `cancel ` | `workflow run build.yaml`；`workflow show wf-1786777600000-1` | | `attend ` | 附加到某个会话（注意：这是给用户使用的不是给你用的）| | | | `keygen [-f] [--key-dir ] [-C ]` | 生成 Ed25519 公私钥对（TLS 跨机认证用） | `-f`, `--key-dir `, `-C ""` | `keygen -C "user@host"` | | `plugin ` | 插件管理 | `plugin list` / `plugin ls ` / `plugin attach ` / `plugin detach ` / `plugin cmd [args...]` | `plugin list` | | `set-default ` | 覆盖全局默认配置 | | `set-default timeout 30` | | `file ... -s ` | 文件工具（读/写/编辑/搜索/上传/下载；`-s/--cwd-session` 必填，取该会话 cwd 作路径基准，不操作该会话） | `-s `（req） | `file read src/main.py -s myapp` | ## *返回条件参数 命令执行后，程序满足设定的返回条件参数会携带消息返回，之后你可继续操作该会话 | 条件 | 参数 | 子进程模式 | 终端模式 | 提示 | |------|-----|----------| ------ | ----- | | 都不带 | | **1s后返回** | **1s后返回** | | | 只带 trigger | `-t/--trigger ""` | 增量输出流匹配到正则，兜底默认超时 | 屏幕变化行匹配到正则，兜底默认超时 | | | trigger + newline | `-t "" --newline` | 换行后开始检查增量输出流匹配正则，兜底默认超时 | 换行后开始检查屏幕变化行匹配正则（输入回显行会先被剔除），兜底默认超时 | 终端有回显，如果你输入的字符会被正则匹配，建议使用`--newline`开启换行后检查 | | 只带 idle-timeout | `--idle-timeout ` | 输出静默超时（在一段时间内无新输出），兜底默认超时 | 屏幕静默超时（在一段时间内无变化），兜底默认超时 | idle-timeout 从**最后输出到达**时开始计时；若程序 stdout 有块缓冲（如 `python -c` 未加 `-u`），输出可能延迟到达，idle 在缓冲 flush 前触发 → 返回空输出（数据未丢，可后续 read） | | idle + 仅首次输出后检测 | `--idle-timeout --idle-after-first-output` | 仅在程序首次输出后才开始检测静默 | 同左 | `--idle-after-first-output` 需配合 `--idle-timeout` 使用 | | 只带 timeout | `--timeout ` | 指定时间后返回 | 指定时间后返回 | | | 带 timeout + 其他条件 | 比如`-t "" --idle-timeout --timeout ` | 命中其他条件，兜底超时 | 命中其他条件，兜底超时 | 注意！1.请不要将timeout设置为很大的值，否则若其他条件无法匹配就会卡死 2.建议如果要带其他条件，那就把timeout也带上并且设定合理的值，因为默认超时是120s | | GUI 检测 | | 检测到 GUI 窗口 | 检测到 GUI 窗口 | GUI窗口通常阻塞程序运行，需要处理。**仅 Windows 原生模式生效**（Unix 不支持）；子进程模式 + trigger 时不触发 GUI 返回 | | 进程崩溃（退出码非零） | 进程崩溃 | 进程崩溃 | | | 程序退出（退出码0） | 程序退出 | 程序退出 | | 注：**高效利用本程序的条件返回功能，及时根据对应程序的输出结果更新条件（特别是`-t`），灵活使用不同的返回条件**。不建议反复`send`后又`read`，如果可以的话尽量一次性设置最强的返回条件 关于timeout：对于时间的预估应该基于执行的命令性质，不可以基于实际条件匹配状态。简单的命令预估执行快，但是可能因为其他原因导致条件未命中而拉长时间。此时绝对不可以设置大timeout或者执行长sleep，而是应该找未匹配的原因，及时取消执行 ## *返回结果处理参数 条件命中后，程序会对结果进行处理再返回 | 选项 / 参数 | 子进程模式 | 终端模式 | |-------------|------------|---------------------| | `-l/--lines ` | 取累积输出的最后 N 行 | 取全量输出的最后 N 行 | | `-l/--lines start:end` | 取累积输出中指定范围的行 | 取全量输出中指定范围的行 | | `-g/--grep ""` | 不支持 | 用可见屏幕的每一行 | | `--offset ` | 从指定字节偏移开始增量读取 | 不支持 | | `--full` | 返回全部累积输出（数据量大，慎用） | 返回全量输出（数据量大，慎用） | | `-s/--snapshot-diff` | 不支持 | 仅返回与上一次可见屏幕相比发生变化的行 | | `--column ` | 支持（按字符位取第 N 列，短行取空） | 取可见屏幕的第 N 列 | | `-o/--output ` | 将输出结果写入指定文件 | 同左 | | `--response-format ` | 只支持stream | 选择响应格式 | | `--svg-compression-level <0/1/2>` | 不支持 | 本机 SVG 压缩等级 | > 注：`-l` 的"累积/全量"语义仅对 `read` 成立；`exec`/`send` 的 `-l` 默认作用于增量交付块 / 可见屏幕快照，需再加 `--full` 才取全量输出。 > > 注：`-g`（终端模式）与 `-s` 的输出均为 `行号:内容` 格式（0-based 行号）。 终端模式的全量输出：指包含 scrollback 历史的全量输出 ### -o 文件输出 `--output/-o ` 将**返回的**瞬间输出渲染到文件： 支持的后缀： `.svg`、`.png` / `.jpg` / `.bmp`、`.txt` / 其他（其他后缀名等价txt纯文本） 注意，**输出的内容就是命令返回的outputStream，如果处于增量输出模式，那么输出到txt文件就只有增量部分** 增量输出模式获取完整输出请使用`--full` > 注：图片（svg、png等）输出需要终端模式，否则只能使用txt ### --response-format 响应格式 仅终端模式支持调节 | 格式 | 说明 | 依赖 | |------|------|------| | stream | 默认 | | | svg | SVG | | ### --svg-compression-level SVG 压缩等级 仅终端模式支持调节 | 等级 | 说明 | 依赖 | |------|------|------| | 0 | 不压缩，仅移除空标签 | | | 1 | 轻度压缩（默认） | Python库：scour | | 2 | 深度压缩 | Python库：scour | 影响所有svg输出的地方，包括结果输出，文件输出 ### -s 仅返回屏幕变化的行 首次调用返回完整快照，后续只返回变化行，格式为 `行号:内容` ## 返回结果示例 ``` (分隔线内嵌过滤条件标签) ────────────────────────────────── lines:0:2 ─────────────────────────────────── Python 3.11.9 (tags/v3.11.9:de54cf5, Apr 2 2024, 10:12:12) [MSC v.1938 64 bit ( AMD64)] on win32 (输出结果) ──────────────────────────────────────────────────────────────────────────────── [read · ok · 0.00s] py1 running pty [(命令类型) · (原因短标签) · (执行时间)] (sid) (当前程序状态) (运行模式) (PTY-Agent message: 系统消息) (hit: 系统提示) ``` - 分隔线内嵌标签由响应格式生成：`-l N` 显示 `tail:N`（如 `tail:10`）；`-l start:end` 显示 `lines:A:B`；另见 `snapshot`/`diff`/`full`/`col:N`/`match:pattern` 等。 - 状态行中的原因显示为**短标签**：`ok`/`matched`/`timeout`/`idle`/`ended`/`crashed`/`gui`/`cancelled`/`notify`（`trigger_matched` 显示为 `matched`；崩溃时附加 `(exit_code: N)`）。 - `(PTY-Agent message: ...)` 为系统消息（info/warning/error，写入 stderr）；`(hit: ...)` 为提示信息（追加在输出末尾）。 ## 引号处理规则（**你的**Shell命令行层） - CMD（你的Shell，不是PTY-Agent的exec shell） 写 `\"` 嵌套： `-c "python -c \"print(1)\""` - PowerShell/Pwsh **外层单引号**，请记住powershell外层用**单引号**，内层双引号： `app.py exec sid -c 'python -c "print(1)"'` ## 命令详解 ### exec 用法 `python app.py exec ` 选项基本与 send 一致，见上文命令速查典型选项 特殊选项： - `-c ""`(req) 执行的命令，必填 - `--force-pty-mode` 非 subprocess 模式且未指定 `--shell` 时，默认会检查命令中的 shell 操作符并拒绝执行（提示改用 `--shell`）；该选项忽略该检测，强制执行（操作符作为字面参数传递） - `--cwd ` 子进程工作目录（默认取调用方 CLI 的当前目录）；如果与期望工作目录不一致，建议指定 - `--env KEY=VALUE` 子进程额外环境变量，可指定多个，合并到继承的环境中；适用于设置 `TERM`、`COLORTERM` 等终端能力变量 - `--subprocess` 子进程模式：Popen 捕获 stdout/stderr（非 PTY），增量输出 + stderr 分离，支持写 stdin，无 resize/快照 - `--size ` 终端尺寸（如 `120x40`，默认 `80x24`；仅 pty 模式，**仅会话创建时生效**；运行中调整请用 `--default terminal-size NxN`） - `--shell ` shell 模式，用指定 shell 包装执行命令（如 `bash`/`cmd`/`pwsh`），显式指定`--shell`优先级大于默认值 - `-o/--output ` 输出到文件（.txt/.log=纯文本; .svg=矢量图; .png/.jpg/.bmp=位图，daemon 侧渲染，客户端无需 Pillow） - `--plugin ` 将插件挂载到该会话（可多次指定；按插件形态自动分流：CLI 形态记录到会话、会话/进程形态在 daemon 挂载） **运行TUI程序建议使用终端模式** 如果是简单的字符流程序，使用 `--subprocess` 子进程模式，只读取增量输出 **--shell 示例**： ``` python app.py exec sid -c "echo a && echo b" --shell pwsh ``` ### send / advsend 用法 `python app.py send -i "" [options]` `python app.py advsend -i "" [options]` * `send` 原样发送输入，简单输入，不做任何转义； * `advsend` 参数与 `send` 完全一致，但**恒启用JSON + 控制字符转义解码**（`\n`、`\t`、`\uXXXX` 等 JSON 反转移 + `{ctrl+a}`、`{enter}`、方向键、`{f1}~{f12}` 等控制字符语法）。需要发送多行、控制字符或按键序列时，使用`advsend`；普通文本用 `send` 即可。 send 通过 `-i`/`--input` 参数（必填）指定要发送的输入文本，例如 `send id_py -i "print(1)" -t ">>>"` 选项： - 支持*返回条件参数 - *返回结果处理参数 - `-e/--send-eol ` 末尾追加的行尾符（可选 `cr`=`\r`；`lf`=`\n`；`crlf`=`\r\n`；`none`=不追加） - `--notify` 注册通知订阅：命令立即返回（reason=notify_waiting），后台等待条件满足时发布通知；之后用 `wait` 查看摘要、`notice ` 查看完整内容 默认情况下，`send` 发送的""是不转义输入；如果需要输入控制字符、多行（`\r`），必须改用 `advsend`（恒转义） #### advsend JSON + 控制字符转义模式 控制字符语法： | 写法 | 说明 | |------|------|------| | `{ctrl+a}` | Ctrl+字母 → ASCII 控制字符 | | `{ctrl+alt+s}` | 修饰键用 `+` 连接；`alt` 前缀 ESC | | `{enter}` | 回车，终端模式代表`\r`、子进程模式代表`\n` | | `{backtab}` | Shift+Tab | | `{space}` | 空格；直接输入字符串` `就好了 | | `{up}`/`{down}`/`{left}`/`{right}`、`{home}`/`{end}`、`{pageup}`/`{pagedown}`、`{insert}`/`{delete}`、`{f1}`~`{f12}`、`{esc}`、`{tab}`、`{backspace}` | | 字面量 `{` 或 `}` 必须使用反引号转义，单独的`{`/`}`会报错：`` `{ ``、`` `} ``。名称大小写不敏感。 子进程模式使用控制字符会原样把翻译后的字节注入stdin，是否响应仅看对方程序处理方法 在发送多行、使用控制字符时使用 `advsend`；若已用 `{enter}` 明确收尾，无需再配 `-e none`（默认行尾不会重复追加） #### `` 追加字符 ``末尾自动追加行尾符（终端模式`\r`，子进程模式`\n`），可通过`--default send-eol`配置，`--send-eol `覆盖本次： - `cr` — 追加 `\r`（终端 Enter 键，pty 默认） - `lf` — 追加 `\n`（subprocess 默认） - `crlf` — 追加 `\r\n` - `none` — 不追加，适合精细控制输入 当输入已以 `\n` 或 `\r` 结尾时不重复追加 注意： 1. 终端换行、多行请使用`\r` 2. 大部分语言的行结尾是`\n`，用`\r`不会触发 readline 断行（`\r`作为普通字符保留） 3. PTY 模式下内核 tty 会自动处理行尾（`\r`→`\n`转换）；子进程模式无此处理，需自行配置行尾符 **需要精细控制输入时，请显式指定或更改默认值** ### read 用法 `python app.py read [options]` 选项： - 支持*返回条件参数 - 支持*返回结果处理参数 ### 通知（--notify / wait / notice） `exec`/`send`/`advsend`/`read`/`mouse` 均可带 `--notify`：命令立即返回（reason=`notify_waiting`），后台线程继续等待返回条件，条件满足时发布一条通知。之后： - `python app.py wait [--timeout <秒>]` 有待消费通知时**立即返回摘要列表**（无需等待）；无通知时才等待指定秒数（默认 120s，通知到达即唤醒） - `python app.py notice ` 查看某条通知的完整响应内容（nid 来自 `wait` 返回的 `notifications[].nid`） 通知存于守护进程内存（不落盘，daemon 重启即清空）。 ### mouse 用法 仅终端模式 `python app.py mouse [args] [options]` 坐标采用 **1-based `(col,row)`**，即 `col` 从 1 开始（左到右），`row` 从 1 开始（上到下） 支持的action： | 动作 | 位置参数 | 说明 | | ------ | ---------- | ------ | | `click` | `--grep ""`/`` | 单/双/三击；`--count`（1/2/3，默认 1） | | `drag` | ` ` | 从起点拖动到终点，格式均为 `col,row` | | `scroll` | `--grep ""`/`` | 滚轮滚动：`--direction `（默认 down）、`--times `（默认 1，N>=1）；滚动为按下不抬起 | | `hover` | `--grep ""`/`` | 鼠标悬停（移动无按钮） | | `press` | ` ` | 长按指定秒数 | | `grep` | `` | 纯查询：返回屏幕快照中所有匹配的首/尾坐标 | | `_get_cursor_location` | 无 | 查询：返回光标位置（col,row）及所在行完整内容 | **位置参数``可以用`--grep`代替，也非常推荐使用`--grep`代替坐标，防止手动定位错误** 选项： - `--button `：指定按钮（click/drag/press 有效），`--button` 默认 left - `--count <1|2|3>`：单/双/三击（仅 click） - `--direction `：滚动方向（默认 down，仅 scroll） - `--times `：滚动次数（默认 1，仅 scroll） - `--ctrl` / `--shift` / `--alt`：修饰键，可组合 - `--grep `：用正则匹配终端屏幕内容代替指定坐标 输出控制选项： - 支持*返回条件参数 - 支持*返回结果处理参数 不要把动作的`grep`和选项的`--grep `弄混 - `--grep` 行为： - 单匹配：自动用匹配首坐标执行动作。 - 多匹配：不执行动作，返回所有对应坐标。 - 无匹配：返回错误。 - 而`grep` 动作本身为纯查询模式，始终返回坐标列表。 ### events 用法 事件记录进程（包括子进程）生命周期：启动（`process_spawn`）、停止（`process_exit`）、崩溃（`process_crash`）、GUI 窗口出现（`gui_window`） `python app.py events [options]` 选项： - `-l/--last N` 最后 N 个事件 - `--since ` 只查看指定时间之后的事件 - `--until ` 只查看指定时间之前的事件 `--since`和`--until`可以一起用 注意：不传任何选项时只返回**未消费**的事件；查看完整历史请加 `-l`（如 `-l 10`）。 ### workflow 用法 多步骤脚本编排：YAML 定义文件声明一系列步骤，daemon 后台调度执行。 适用：需要按序/并行编排多个 exec/send/read 操作的自动化流程 （构建流水线、TUI 冒烟、多会话协作） 见附录 ### keygen 用法 生成 Ed25519 公私钥对，用于 CONNECT_MODE=tls 的跨机非对称认证。 密钥写入 `~/.pty-agent/keys/`（私钥 `id_ed25519` + 公钥 `id_ed25519.pub`）， 生成后需把公钥追加到服务端 `~/.pty-agent/authorized_keys`。 ```bash python app.py keygen # 生成到 ~/.pty-agent/keys/ python app.py keygen -f # 覆盖已存在的密钥文件 python app.py keygen --key-dir ./mykeys # 指定密钥目录 python app.py keygen -C "user@host" # 公钥注释（默认 用户名@主机名） ``` 选项： - `-f/--force` 覆盖已存在的密钥文件（默认拒绝覆盖） - `--key-dir ` 密钥目录（默认 `~/.pty-agent/keys`，支持 `~`/`%TEMP%` 展开） - `-C/--comment ""` 公钥注释（默认 `用户名@主机名`） keygen 为本地命令，无需 daemon；Windows 下私钥自动收紧 ACL（仅当前用户 + SYSTEM + Administrators）。 ### plugin 用法 插件管理。插件注册在 `config/plugins/registry.json`（`enabled` 总开关 + 各插件启用状态；registry.json 缺失则插件系统禁用）， 插件目录发现 = 扫描 `config/plugins/` 下含 `plugin.json` 的目录，可用 `PTY_PLUGIN_DIRS` 环境变量追加位置。 目录级改动后需重启 daemon（或 `plugin reload ` 热重载）。 ```bash python app.py plugin list # 列出已加载插件（daemon 侧 + CLI 侧） python app.py plugin ls # 列出会话挂载的插件 python app.py plugin attach # 动态挂载插件到运行中的会话 python app.py plugin detach # 从会话卸载插件 python app.py plugin cmd [args...] # 调用插件命令钩子 python app.py plugin install # 从目录安装插件（须含 plugin.json，不自动启用） python app.py plugin uninstall # 卸载插件（须先 disable） python app.py plugin enable # 启用插件 python app.py plugin disable # 停用插件 python app.py plugin reload # 热重载插件（重新加载代码与清单，保持启用状态） python app.py plugin info # 插件详情（清单/状态/路径/权限/事件） python app.py plugin status # 插件运行状态 python app.py plugin config [key value] # 查看/修改插件配置（仅内存，重启清空） ``` ### file 用法 `file` 提供文件工具：读、写、唯一匹配替换、内容搜索、文件名匹配、上传、下载 ```bash python app.py file ... -s ``` `-s/--cwd-session` **必填**：指定某个会话，取它的 cwd 作为路径解析基准（不操作该会话） | 子命令 | 用法 | 要点 | | ------ | ---- | ---- | | `file read [--offset N] [--limit N]` | 读文件（带行号，默认 2000 行） | 超过 250KB / 图片拒绝；不存在时提示相似文件名；`--offset` 0-based | | `file write --content TEXT \| --content-file FILE` | 覆盖写/新建（自动建父目录） | **已存在文件必须先 `file read`**；外部修改后拒绝；内容相同拒绝；大文件用 `--content-file`（与 `--content` 互斥） | | `file edit --old TEXT \| --old-file FILE [--new TEXT \| --new-file FILE]` | 唯一匹配替换 | `--old` 空=新建（文件须不存在）；`--new` 空=删除；`--old` 须唯一匹配（未找到/重复均拒绝） | | `file grep [path] [--include GLOB] [--literal-text]` | 内容搜索 | rg 引擎优先，缺失自动降级纯 Python；`path` 缺省=会话 cwd | | `file glob [path]` | 文件名匹配 | rg 引擎优先，缺失自动降级纯 Python；支持 `**` 任意层级；`path` 缺省=会话 cwd | | `file upload [--force] [--timeout N]` | 上传本地文件/目录到会话侧（scp -r 语义） | `local-path` 为 CLI 本机路径，`remote-path` 由 daemon 按会话 cwd 解析（支持 `~`）；目标已存在且相同→跳过，不同→拒绝并提示 `--force`；`--timeout` 为整个传输总时限（默认 120s），超时中止并清理临时文件 | | `file download [--force] [--timeout N]` | 下载会话侧文件/目录到本地（scp -r 语义） | 与 upload 反向；`remote-path` 可为文件或目录；覆盖策略与 `--timeout` 同 upload | **路径规则：** 相对路径基于 `-s` 会话的 cwd 拼接；`~` 按 daemon 用户展开；绝对路径原样使用；cwd 是会话创建时的值，shell 内 `cd` 后不更新；跨机场景（CLI 与 daemon 异机）语义依然正确——路径在 daemon 所在机器上解析。 **写保护状态机（read-before-write）：** `file write` / `file edit` 受读前写保护——文件已存在时必须先 `file read`（成功后记录读时刻）；写/编辑时若文件 mtime 晚于读时刻（期间被外部修改）→ 拒绝并提示；内容与现有内容相同 → 拒绝。状态在守护进程进程内保存，重启守护进程即失效。每次写操作在 `/history.db` 的 `files_history` 表落版本链（initial → v1 → v2）。 **多行/含特殊字符内容：** 输入带换行、`\`、`"`、`'` 等字符的内容时，**必须**先调用本地 write 工具写中转文件，再使用 `--content-file` / `--old-file` / `--new-file` 传入（一次调用两个工具：write + file），避免 Shell 复杂转义与命令行长度上限。 **使用示例：** ```bash # 先拉起一个会话作为 cwd 基准 python app.py exec sid_cwd -c "cmd" --cwd # 读 / 搜索 / 匹配 python app.py file read src/main.py -s sid_cwd --limit 50 python app.py file grep "def " src -s sid_cwd --include *.py python app.py file glob "src/**/*.py" -s sid_cwd # write 两步法（先本地 write 写中转文件，再 --content-file 传入） python app.py file write out.txt -s sid_cwd --content-file tempfiles/_write_temp1.txt # edit 三步法（本地 write 分别写 old/new 中转文件） python app.py file edit src/main.py -s sid_cwd --old-file tempfiles/_editold_temp1.txt --new-file tempfiles/_editnew_temp1.txt # 上传 / 下载 python app.py file upload ./local.txt remote_dir/ -s sid_cwd python app.py file download remote_dir/local.txt ./local.txt --force -s sid_cwd ``` ### set-default 用法 覆盖全局默认配置（影响**后续所有会话请求**的默认值，包括已存在会话的后续请求；仅 `shell` 键真正只对新建会话生效，`terminal-size` 对运行中会话即刻生效）。 默认配置存于**守护进程内存**（不写任何文件），daemon 重启即清空；命令返回时会列出当前全部默认值。 - `app.py set-default ` 通用子命令：覆盖默认配置（需 daemon 运行；daemon 未运行时报错，请先 `exec` 启动） - ``可用键：`timeout`/`newline`/`keep-ansi`/`encoding`/`debug`/`send-eol`/`response-format`/`svg-compression-level`/`terminal-size`/`shell`，``是配置值或者`on`/`off` ### 全局/通用选项 - `--keep-ansi` （仅终端模式，exec/send/read/mouse 可用）通用选项：保留完整VT序列（默认过滤掉终端颜色/样式码及 OSC 序列，只保留清屏/光标等控制序列，开启后保留全部） - `--encoding ` 通用选项：终端编码，乱码时设置`utf-8/gbk/gb2312/gb18030/big5`；本次调用进程内会记忆（不写盘、不跨调用持久化），如需跨调用默认请用 `set-default encoding` / `--default encoding` - `--debug-output` 通用选项：启用后响应中输出 debugInformation（进程树/GUI 窗口/事件） - `--show-config [KEY]` 查看当前调用配置 - 以上选项（`--keep-ansi`/`--encoding`/`--debug-output`/`--show-config`/`--default`）仅影响本次调用；如需影响后续所有会话的默认值，请使用 `set-default` 命令： - `--default ` 通用选项：调整该会话的配置值 - ``可用键：`timeout`/`newline`/`keep-ansi`/`encoding`/`debug`/`send-eol`/`response-format`/`svg-compression-level`/`terminal-size`，``是配置值或者`on`/`off` - 支持多个 `--default` - 默认配置按 session 记在守护进程内存（不写盘，daemon 重启/session 结束即清空） - `--default terminal-size NxN` 不是配置，是实时调整终端尺寸，对**运行中的会话即刻生效** - `--default`不支持`shell` ## 插件 使用前请先挂载（state_check/ai 用 `exec --plugin ` 或 `plugin attach ` 挂载到会话）。 ### ai 对命令输出做二次 AI 分析（exec/send/read/mouse 响应），见`config/plugins/ai/README.md` （另注：`config/plugins/` 下还有 `2048`（游戏）、`subagent`（子代理管理，注册 codebuddy/devin/opencode/claude/smartagent 命令等插件） ## 其他 Windows注意事项： - 少用cmd - 输入带空格的文文件时，建议使用 8.3 短路径 跨机使用注意事项： exec时请**显式设定环境变量**，避免不同环境的冲突 ## 示例场景 ### 长时运行**服务器** ```bash app.py exec srv -c "python server.py" --timeout 10 app.py read srv -l 20 # 中途查看最近20行输出 app.py read srv # PTY 模式返回屏幕快照；子进程模式则从上次 offset 增量读取（无返回条件时等待 1s） app.py read srv -g "ERROR" # 只看错误行 app.py kill srv # 不再需要时终止 ``` ### **下载大文件** ```bash app.py exec download1 -c "curl -O https://example.com/largefile.zip" --trigger "100%" --timeout 600 --idle-timeout 10 --subprocess # 如果下载很慢，用 --timeout 给足时间，但是必须设定--idle-timeout防止卡死 app.py read download1 # 查看进度 app.py read download1 -t "100%|error|warning" --timeout 600 --idle-timeout 10 # 等待完成 app.py kill download1 # 下载完成后清理 ``` 编译也是同理 ### **容易崩溃的程序** ```bash app.py exec job1 -c "python worker.py" --idle-timeout 5 # 启动，idle-timeout 等待输出 # 若进程崩溃，返回中 triggerReturnReason="program_crashed"，program.exitCode 非零，errorMessage 含崩溃信息 app.py events job1 -l 10 # 查看崩溃事件详情（process_crash 类型） ``` ### **TUI 程序**交互 ```bash app.py exec mimo -c "mimo.exe --trust" --timeout 10 # 启动 TUI 程序，10秒后返回屏幕快照 app.py send mimo --send-eol cr -i "j" -s # 发送按键，1秒后返回快照 app.py read mimo -s app.py send mimo -i "帮我写一个贪吃蛇游戏" -s --timeout 30 --idle-timeout 5 app.py kill mimo ``` ### **调试器（cdb/gdb）**交互 ```bash app.py exec dbg1 -c '"C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe" myapp.exe' -t ">" --subprocess --timeout 5 app.py send dbg1 -i "g" -t "0:000" --timeout 5 # 继续执行；timeout看情况设定 app.py send dbg1 -i "k" -t "0:000" --timeout 5 # 查看调用栈 app.py send dbg1 -i "db esp L100" --timeout 5 -t "0:000" # 查看内存 app.py send dbg1 -i "q" -t ">" --timeout 5 # 退出调试器 app.py kill dbg1 ``` ## 小工具 ### Terminal-Injector 强制性劫持已经运行的控制台程序供PTY-Agent使用：`bin/terminal_injector/terminal_injector.exe` 用法： ```bash terminal_injector.exe --list-targets --json # 查看可劫持的窗口 terminal_injector.exe --inject # 注入 DLL terminal_injector.exe --mediator --target-pid # 劫持桥接 # 接入 PTY-Agent # 不建议执行`terminal_injector.exe --inject ` ，而是直接使用 PTY-Agent 执行`app.py exec sid -c "terminal_injector.exe --mediator --target-pid " --timeout 10` app.py exec sid -c "terminal_injector.exe --mediator --target-pid " --timeout 10 ``` --- ## @附录：workflow 用法 ```bash python app.py workflow run # 启动（后台执行，立即返回 runId） python app.py workflow run --vars env=prod --parallel 2 # 覆盖变量/并行度 python app.py workflow list # 所有运行（含已结束） python app.py workflow show # 运行状态：步骤状态+输出+日志 python app.py workflow cancel # 取消（等待中的步骤最快 0.1s 响应） ``` 定义文件结构（YAML）： ```yaml name: build # 可选，workflow 名称（show/list 显示用） vars: # 可选，全局变量（值限 str/int/float/bool），可被 --vars 覆盖 repo: myrepo max_parallel: 4 # 可选，最大并行步骤数（默认 4，可被 --parallel 覆盖） steps: - id: clone # 必填，步骤唯一 id（也是表达式引用名） type: exec # 必填，步骤类型: exec/send/read/kill/wait session: clone command: "git clone ...{{vars.repo}}" trigger: "Cloning into|error" - id: build type: exec session: build command: "make" depends_on: [clone] # 可选，显式依赖；不写则隐式依赖前一个步骤（串行） if: "clone.reason == 'trigger_matched'" # 可选，条件表达式，为假跳过 on_error: continue # 可选，失败策略: fail(默认)/continue/ignore retry: 2 # 可选，失败重试次数（retry_interval 默认 1.0s） ``` 解析期校验（run 时即报错，不产生运行）：id 非空唯一、type 合法且必填字段齐全、 `depends_on` 引用存在且无环、`on_error`/`retry`/`max_parallel` 取值合法、定义文件上限 20 MB。 （注：`trigger` 正则为**运行时编译**，解析期不校验，非法正则在执行时使步骤失败。） **步骤类型**： - `exec` — 启动/附加会话（`session`+`command` 必填） - 返回条件：`trigger`（正则，命中返回）/ `timeout`（默认 120）/ `idle_timeout`（输出静默）/ `idle_after_first_output`（仅首次输出后才检测静默） - 环境：`cwd`、`env`（**映射**，如 `KEY: VALUE`）、`encoding`、`size`（"120x40"）/`cols`/`rows`（同时给定时 `size` 优先） - `mode`：`pty`（默认，屏幕快照）/ `subprocess`（增量输出 + stderr 分离） - 输出：`full` / `keep_ansi`（`snapshot_diff` 仅 `read` 步骤支持） - 语义：同名会话仍在运行 → 直接附加；已结束 → 步骤失败 - 结果：`output` 为返回时终端快照；`reason` 为返回原因（trigger_matched / trigger_timeout / idle_timeout / program_ended / program_crashed / gui_detected / ok / cancelled / notify_waiting） - `send` — 向会话发送输入（`session`+`input` 必填，会话须已运行） - `trigger`/`timeout`/`idle_timeout` 等待返回（同 exec） - `eol: lf|crlf|cr|none` 行尾（默认按会话模式：pty=cr、subprocess=lf）；`json: true` 启用 `{enter}`/`{ctrl+a}` 转义展开（与 CLI advsend 语义一致，`{enter}` 按模式展开） - `read` — 读取会话输出（`session` 必填，不存在 → 步骤失败） - `lines`（N 或 start:end）/ `grep`（正则）过滤；有 trigger/idle_timeout 时进入等待，否则立即返回当前快照 - `kill` — 终止会话（`session` 必填，终止整个进程树：Job Object / 进程组信号） - `wait` — 固定等待（`seconds` 必填，float；分段睡眠 0.1s 粒度，可响应取消） **依赖与并行**： - 不写 `depends_on` → 隐式依赖前一个步骤（**串行**） - `depends_on: [a, b]` → 等 a、b 都完成；`depends_on: []` → 无依赖可与前序并行 - 依赖失败/取消的步骤自动 skipped；依赖环解析期拒绝（返回循环路径） - 并行度上限 `max_parallel`（定义，默认 4）或 `--parallel N`（CLI 覆盖，优先级更高） - **同一 `session` 的步骤强制串行派发**（防止并发写输入/篡改触发条件互相踩踏） **变量、插值与条件**： - 全局变量：`vars` 定义，`--vars KEY=VALUE` 启动时覆盖（优先级更高，覆盖的值一律为字符串），以 `vars.` 引用 - 步骤结果：已完成步骤以 id 引用，暴露 `output`/`reason`/`exit_code`/`error` 四字段 - 插值：任何字符串字段支持 `{{表达式}}`，执行前渲染（可引用已完成的步骤），如 `"git clone {{vars.repo}}"`、`"print('{{build.output}}')"` - `if` 为**表达式**（非插值），为假时步骤 skipped（note 标注原因）： - `"clone.reason == 'trigger_matched'"`、`"'error' in build.output"`、 `"build.exit_code == 0 and not vars.skip"` - 安全求值器（AST 白名单）：仅字面量/名称/属性/下标、比较（`==` `!=` `<` `>` `in` `not in`）、 布尔（`and`/`or`/`not`）、算术、容器；`true`/`false`/`null` 等价 True/False/None； **任何函数调用、属性方法执行一律拒绝**；变量缺失/语法非法使步骤失败 **失败、重试与错误策略**： - 步骤失败 = 执行异常（会话创建失败、会话不存在、写入失败等）或错误响应； **trigger 超时不算失败**（正常返回 `reason=trigger_timeout`） - `retry: N` 失败重试 N 次（最多尝试 N+1 次），`retry_interval` 间隔秒数（默认 1.0） - `on_error`： - `fail`（默认）本步骤 failed → 终止整个 workflow（未开始步骤 skipped，run 状态 failed） - `continue` 本步骤 failed → workflow 继续调度；依赖本步骤的步骤 skipped - `ignore` 视为成功（note 记录被忽略的错误），依赖本步骤的步骤正常执行 - 失败沿依赖链传播；`on_error=ignore` 的步骤不传播失败 **状态模型与限制**： - run：`running` → `done` / `failed` / `cancelled` - step：`pending` → `running` → `done` / `failed` / `skipped` / `cancelled` （skipped：if 为假 / 依赖失败或取消 / workflow 终止；cancelled：运行时收到取消） - `cancel` 置位取消事件，执行中的步骤最快 0.1s 内响应；已终态运行幂等 - 运行记录上限 50（超限自动淘汰最旧终态）；步骤输出保存上限 4096 字符（仅 show 日志） - 运行状态仅存内存（daemon 重启即清空）；workflow 创建的会话结束后保留，可 kill 步骤或外部命令清理 示例 1 — 启动 REPL → 发代码 → 读结果（默认串行）： ```yaml steps: - id: py type: exec session: py-repl command: "python -u -i" trigger: ">>>" - id: run type: send session: py-repl input: "print('hello workflow')" trigger: "hello workflow" - id: done type: read session: py-repl lines: 5 ``` 示例 2 — 构建流水线（并行 + 条件 + 重试）： ```yaml name: build-pipeline vars: repo: myrepo tag: nightly steps: - id: clone type: exec session: clone command: "git clone -b {{vars.tag}} https://example.com/{{vars.repo}}" trigger: "Cloning into|error|fatal" - id: deps type: exec session: deps command: "cd {{vars.repo}} && pip install -r requirements.txt" trigger: "Successfully installed|error" retry: 1 depends_on: [clone] - id: build type: exec session: build command: "cd {{vars.repo}} && make -j8" trigger: "error|^make:" idle_timeout: 60 depends_on: [clone] # deps 与 build 均只依赖 clone → 并行 - id: test type: send session: build # 复用已创建的 build 会话执行 make test（send 步骤不能引用未创建的会话） input: "cd {{vars.repo}} && make test\n" trigger: "PASS|FAIL|error" depends_on: [build] - id: report type: read session: build # 读取 make test 的输出 grep: "FAIL" if: "test.reason == 'trigger_matched' and 'FAIL' in test.output" depends_on: [test] - id: cleanup type: kill session: deps on_error: ignore depends_on: [test] ``` send 步骤需要发送快捷键/转义时用 `json: true`（如 `input: "{ctrl+c}"`）， 需要控制行尾时用 `eol`（如 `input: "make -j8"` 后触发 `eol: none` 的按键步骤）。 ## @附录：文档 文档很大，用户明确要求再查看 配置文件使用方法请查看`docs\CONFIG.md` 插件开发请查看`‪docs\PLUGINS_API.md` 了解项目架构请查看`docs\ARCHITECTURE.md` ## @附录：沙箱 配置沙箱请查看`docs\CONFIG.md` ## @附录：远程执行命令，跨机开发 跨机开发请查看`docs\CONFIG.md`