Pty Agent

[TOC]

PTY-Agent

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

原理：程序后台有运行一个守护进程，执行命令时需要再次调用程序，程序会call守护进程对对应CLI进行操作：你 <-> PTY-AgentCLI <-> PTY-Agent守护进程 <-> PTY

程序位于app.py，运行方法：python app.py <args>，或者包执行等其他方法

环境要求

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 <shell>

子进程模式（需显式--subprocess）

用 subprocess.Popen 直接捕获子进程的 stdout 与 stderr（无伪终端）， 增量输出，无终端回显、无快照、无 resize。

• 适用：普通命令行程序（编译、脚本、下载），只需追踪输出流
• exec/send/read 返回增量文本；read 支持 --offset 增量读取
• 增量语义：stdout/stderr 各有一个会话内消费游标（镜像关系）。exec/send 与默认 read 从"上次交付末尾"续读，两次调用之间写入的输出不会丢失； -l/--column/--full 是累积查询（从保留起点读，不推进游标）。 缓冲超限会从头裁剪最旧字节（游标前数据可能被丢弃，响应仍单调推进）
• 输入通过写 stdin

注意：不要使用子进程模式运行需要TTY的会话！

命令速查

*返回条件参数

命令执行后，程序满足设定的返回条件参数会携带消息返回，之后你可继续操作该会话

注：高效利用本程序的条件返回功能，及时根据对应程序的输出结果更新条件（特别是-t），灵活使用不同的返回条件。不建议反复send后又read，如果可以的话尽量一次性设置最强的返回条件

关于timeout：对于时间的预估应该基于执行的命令性质，不可以基于实际条件匹配状态。简单的命令预估执行快，但是可能因为其他原因导致条件未命中而拉长时间。此时绝对不可以设置大timeout或者执行长sleep，而是应该找未匹配的原因，及时取消执行

*返回结果处理参数

条件命中后，程序会对结果进行处理再返回

注：-l 的"累积/全量"语义仅对 read 成立；exec/send 的 -l 默认作用于增量交付块 / 可见屏幕快照，需再加 --full 才取全量输出。

注：-g（终端模式）与 -s 的输出均为 行号:内容 格式（0-based 行号）。

终端模式的全量输出：指包含 scrollback 历史的全量输出

-o 文件输出

--output/-o <path> 将返回的瞬间输出渲染到文件：

支持的后缀： .svg、.png / .jpg / .bmp、.txt / 其他（其他后缀名等价txt纯文本）

注意，输出的内容就是命令返回的outputStream，如果处于增量输出模式，那么输出到txt文件就只有增量部分 增量输出模式获取完整输出请使用--full

注：图片（svg、png等）输出需要终端模式，否则只能使用txt

--response-format 响应格式

仅终端模式支持调节

--svg-compression-level SVG 压缩等级

仅终端模式支持调节

影响所有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 <session-id> <options>

选项基本与 send 一致，见上文命令速查典型选项 特殊选项：

• -c "<command>"(req) 执行的命令，必填
• --force-pty-mode 非 subprocess 模式且未指定 --shell 时，默认会检查命令中的 shell 操作符并拒绝执行（提示改用 --shell）；该选项忽略该检测，强制执行（操作符作为字面参数传递）
• --cwd <path> 子进程工作目录（默认取调用方 CLI 的当前目录）；如果与期望工作目录不一致，建议指定
• --env KEY=VALUE 子进程额外环境变量，可指定多个，合并到继承的环境中；适用于设置 TERM、COLORTERM 等终端能力变量
• --subprocess 子进程模式：Popen 捕获 stdout/stderr（非 PTY），增量输出 + stderr 分离，支持写 stdin，无 resize/快照
• --size <WxH> 终端尺寸（如 120x40，默认 80x24；仅 pty 模式，仅会话创建时生效；运行中调整请用 --default terminal-size NxN）
• --shell <shell> shell 模式，用指定 shell 包装执行命令（如 bash/cmd/pwsh），显式指定--shell优先级大于默认值
• -o/--output <path> 输出到文件（.txt/.log=纯文本; .svg=矢量图; .png/.jpg/.bmp=位图，daemon 侧渲染，客户端无需 Pillow）
• --plugin <name> 将插件挂载到该会话（可多次指定；按插件形态自动分流：CLI 形态记录到会话、会话/进程形态在 daemon 挂载）

运行TUI程序建议使用终端模式 如果是简单的字符流程序，使用 --subprocess 子进程模式，只读取增量输出

--shell 示例：

python app.py exec sid -c "echo a && echo b" --shell pwsh

send / advsend 用法

python app.py send <session-id> -i "<content>" [options] python app.py advsend <session-id> -i "<content>" [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 <lf|crlf|cr|none> 末尾追加的行尾符（可选 cr=\r；lf=\n；crlf=\r\n；none=不追加）
• --notify 注册通知订阅：命令立即返回（reason=notify_waiting），后台等待条件满足时发布通知；之后用 wait 查看摘要、notice <nid> 查看完整内容

默认情况下，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（默认行尾不会重复追加）

<content> 追加字符

<content>末尾自动追加行尾符（终端模式\r，子进程模式\n），可通过--default send-eol配置，--send-eol <lf|crlf|cr|none>覆盖本次：

• 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 <session-id> [options]

选项：

• 支持*返回条件参数
• 支持*返回结果处理参数

通知（--notify / wait / notice）

exec/send/advsend/read/mouse 均可带 --notify：命令立即返回（reason=notify_waiting），后台线程继续等待返回条件，条件满足时发布一条通知。之后：

• python app.py wait [--timeout <秒>] 有待消费通知时立即返回摘要列表（无需等待）；无通知时才等待指定秒数（默认 120s，通知到达即唤醒）
• python app.py notice <nid> 查看某条通知的完整响应内容（nid 来自 wait 返回的 notifications[].nid）

通知存于守护进程内存（不落盘，daemon 重启即清空）。

mouse 用法

仅终端模式

python app.py mouse <session-id> <action> [args] [options]

坐标采用 1-based (col,row)，即 col 从 1 开始（左到右），row 从 1 开始（上到下）

支持的action：

位置参数<c,r>可以用--grep代替，也非常推荐使用--grep代替坐标，防止手动定位错误

选项：

• --button <left|right|middle>：指定按钮（click/drag/press 有效），--button 默认 left
• --count <1|2|3>：单/双/三击（仅 click）
• --direction <up|down>：滚动方向（默认 down，仅 scroll）
• --times <N>：滚动次数（默认 1，仅 scroll）
• --ctrl / --shift / --alt：修饰键，可组合
• --grep <pattern>：用正则匹配终端屏幕内容代替指定坐标

输出控制选项：

• 支持*返回条件参数
• 支持*返回结果处理参数

不要把动作的grep和选项的--grep <pattern>弄混

• --grep 行为：
  • 单匹配：自动用匹配首坐标执行动作。
  • 多匹配：不执行动作，返回所有对应坐标。
  • 无匹配：返回错误。
• 而grep 动作本身为纯查询模式，始终返回坐标列表。

events 用法

事件记录进程（包括子进程）生命周期：启动（process_spawn）、停止（process_exit）、崩溃（process_crash）、GUI 窗口出现（gui_window）

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

选项：

• -l/--last N 最后 N 个事件
• --since <iso-datetime\|HH:MM> 只查看指定时间之后的事件
• --until <iso-datetime\|HH:MM> 只查看指定时间之前的事件

--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。

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 <dir> 密钥目录（默认 ~/.pty-agent/keys，支持 ~/%TEMP% 展开）
• -C/--comment "<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 <name> 热重载）。

python app.py plugin list                          # 列出已加载插件（daemon 侧 + CLI 侧）
python app.py plugin ls <session-id>               # 列出会话挂载的插件
python app.py plugin attach <session-id> <name>    # 动态挂载插件到运行中的会话
python app.py plugin detach <session-id> <name>    # 从会话卸载插件
python app.py plugin cmd <session-id> <name> <command> [args...]   # 调用插件命令钩子
python app.py plugin install <path>                # 从目录安装插件（须含 plugin.json，不自动启用）
python app.py plugin uninstall <name>              # 卸载插件（须先 disable）
python app.py plugin enable <name>                 # 启用插件
python app.py plugin disable <name>                # 停用插件
python app.py plugin reload <name>                 # 热重载插件（重新加载代码与清单，保持启用状态）
python app.py plugin info <name>                   # 插件详情（清单/状态/路径/权限/事件）
python app.py plugin status <name>                 # 插件运行状态
python app.py plugin config <name> [key value]     # 查看/修改插件配置（仅内存，重启清空）

file 用法

file 提供文件工具：读、写、唯一匹配替换、内容搜索、文件名匹配、上传、下载

python app.py file <read|write|edit|grep|glob|upload|download> ... -s <session-id>

-s/--cwd-session 必填：指定某个会话，取它的 cwd 作为路径解析基准（不操作该会话）

路径规则： 相对路径基于 -s 会话的 cwd 拼接；~ 按 daemon 用户展开；绝对路径原样使用；cwd 是会话创建时的值，shell 内 cd 后不更新；跨机场景（CLI 与 daemon 异机）语义依然正确——路径在 daemon 所在机器上解析。

写保护状态机（read-before-write）： file write / file edit 受读前写保护——文件已存在时必须先 file read（成功后记录读时刻）；写/编辑时若文件 mtime 晚于读时刻（期间被外部修改）→ 拒绝并提示；内容与现有内容相同 → 拒绝。状态在守护进程进程内保存，重启守护进程即失效。每次写操作在 <DATA_DIR>/history.db 的 files_history 表落版本链（initial → v1 → v2）。

多行/含特殊字符内容： 输入带换行、\、"、' 等字符的内容时，**必须**先调用本地 write 工具写中转文件，再使用 --content-file / --old-file / --new-file 传入（一次调用两个工具：write + file），避免 Shell 复杂转义与命令行长度上限。

使用示例：

# 先拉起一个会话作为 cwd 基准
python app.py exec sid_cwd -c "cmd" --cwd <path>

# 读 / 搜索 / 匹配
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 <KEY> <VALUE> 通用子命令：覆盖默认配置（需 daemon 运行；daemon 未运行时报错，请先 exec 启动）
  • <KEY>可用键：timeout/newline/keep-ansi/encoding/debug/send-eol/response-format/svg-compression-level/terminal-size/shell，<VALUE>是配置值或者on/off

全局/通用选项

• --keep-ansi （仅终端模式，exec/send/read/mouse 可用）通用选项：保留完整VT序列（默认过滤掉终端颜色/样式码及 OSC 序列，只保留清屏/光标等控制序列，开启后保留全部）
• --encoding <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 <KEY> <VALUE> 通用选项：调整该会话的配置值
  • <KEY>可用键：timeout/newline/keep-ansi/encoding/debug/send-eol/response-format/svg-compression-level/terminal-size，<VALUE>是配置值或者on/off
  • 支持多个 --default
  • 默认配置按 session 记在守护进程内存（不写盘，daemon 重启/session 结束即清空）
  • --default terminal-size NxN 不是配置，是实时调整终端尺寸，对运行中的会话即刻生效
  • --default不支持shell

插件

使用前请先挂载（state_check/ai 用 exec --plugin <name> 或 plugin attach <session-id> <name> 挂载到会话）。

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时请显式设定环境变量，避免不同环境的冲突

示例场景

长时运行服务器

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 # 不再需要时终止

下载大文件

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 # 下载完成后清理

编译也是同理

容易崩溃的程序

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 程序交互

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）**交互

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

用法：

terminal_injector.exe --list-targets --json # 查看可劫持的窗口
terminal_injector.exe --inject <pid>        # 注入 DLL
terminal_injector.exe --mediator --target-pid <pid> # 劫持桥接

# 接入 PTY-Agent
# 不建议执行`terminal_injector.exe --inject <pid>` ，而是直接使用 PTY-Agent 执行`app.py exec sid -c "terminal_injector.exe --mediator --target-pid <pid>" --timeout 10`
app.py exec sid -c "terminal_injector.exe --mediator --target-pid <pid>" --timeout 10

@附录：workflow 用法

python app.py workflow run <file>              # 启动（后台执行，立即返回 runId）
python app.py workflow run <file> --vars env=prod --parallel 2   # 覆盖变量/并行度
python app.py workflow list                     # 所有运行（含已结束）
python app.py workflow show <run-id>            # 运行状态：步骤状态+输出+日志
python app.py workflow cancel <run-id>          # 取消（等待中的步骤最快 0.1s 响应）

定义文件结构（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.<name> 引用
• 步骤结果：已完成步骤以 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 → 发代码 → 读结果（默认串行）：

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 — 构建流水线（并行 + 条件 + 重试）：

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