ming-14/PTY-Agent

PTY-Agent

English
·
中文

让 AI 像真实用户一样使用终端。

驱动 REPL、调试器、TUI、安装程序、长时间运行的服务以及编码代理——获取用户在屏幕上实际看到的内容，而不仅仅是原始的 stdout 字节流。

Python
Windows
Linux
Architecture
src
Tests
Web

┌─ PTY-Agent ─────────────────────────────────────────────────────────────────┐
│ $ app.py exec dbg -c "cdb.exe myapp.exe" -t "0:000" --timeout 5             │
│                                                                             │
│ ─────────────────────────────── matched ───────────────────────────────     │
│ Microsoft (R) Windows Debugger Version 10.0.11451.4                         │
│ 0:000>                                                                      │
│ ───────────────────────────────────────────────────────────────────────     │
│ [exec · matched · 0.42s]  dbg  running  pty                                 │
└─────────────────────────────────────────────────────────────────────────────┘

点击此处查看演示视频

功能特性

- ✨ Shell · CUI · TUI — 像人类一样使用终端：启动会话、发送按键、等待提示符、读取屏幕
- ✨ 跨平台 — Windows / Linux，macOS 即将推出
- ✨ 实时 Web 监控 — 观看并控制每个终端会话，实时协作
- ✨ 沙箱 — 将 AI 操作限制在工作区内，防止意外损坏
- ✨ 插件系统 — 自由扩展功能
- AI 二次分析 — 将长日志、大量输出，甚至渲染后的终端截图传递给另一个 AI
- 子代理 — 跨多种运行环境启动 OpenCode / Claude Code / ...，集中管理
- 工作流编排 — 多会话 DAG 编排
- 远程终端访问 — 类似 SSH 的体验

为什么选择 PTY-Agent？

传统代理无法运行 ssh、gdb、cdb 或任何向你提问的程序。

| 传统方式 | PTY-Agent |
|---|---|
| 没有 TTY — 程序回退到非交互模式 | 真正的伪终端 |
| 仅“运行并检查” | 持久会话 |
| 无法“等待特定提示符” | -t "" 触发，匹配时返回 |
| 挂起 / 崩溃 / 弹窗 → 调用方挂起，用户等待 | 超时、GUI 检测、崩溃检测——均干净返回 |
| 原始字节流 | 渲染后的终端快照 |

快速概览

| | |
|---|---|
| 模式 | pty（默认，屏幕快照，用于 TUI/REPL）；--subprocess（增量输出 + stderr，用于编译/下载） |
| 返回原因 | ok / matched / timeout / idle / ended / crashed / gui / cancelled / notify |
| 输出过滤 | -l N、-g ""、-s 增量差异、--column N、-o 导出 .svg/.png/.jpg/.txt |
| 输入 | send 原始文本；advsend 支持 {ctrl+c} {enter} {f1}~{f12}，换行 lf/crlf/cr/none；鼠标 click/drag/scroll/hover/press/grep，配合 --grep 坐标查找 |
| 异步 | --notify 立即返回，通过 wait / notice  获取结果，非阻塞 |
| 编排 | workflow YAML DAG：依赖并行、if 条件（AST 安全求值）、retry、on_error |
| Web | 浏览器终端（xterm.js + Web RIME 输入法）、FastScreen 流式传输、VNC 远程桌面，默认 127.0.0.1:18766 |
| 沙箱 | Windows 可选启用：Job Object + 受限令牌，仅工作区可写，CPU/内存/进程/墙钟时间配额 |

安装

需要编译。下载预构建的 Release 包，或克隆后运行 build.py。

架构

graph LR
A["AI Agent"] -->|"PTY-Agent <cmd>"| B["CLIsrc/cli · src/client"]
B -->|"TCP · NDJSONToken+HMAC / TLS+Ed25519"| C["Daemonsrc/daemon"]
C --> D["Sessionsrc/session"]
D --> E["PTY backendsrc/pty"]
E -->|"ConPTY / openpty"| F["Real program"]
F --> G["Reader thread → output buffer"]
G --> H["Terminal model wezterm-termVT parse → snapshot/diff/SVG"]
H --> I["Trigger detectionregex · idle · crash · GUI"]
I -->|"Response JSON"| B
C --> J["Web · workflow · plugins"]

配置

配置文件位于 config/，可通过环境变量 PTY_AGENT_ 覆盖，需重启生效。

CLI ──token──▶ 127.0.0.1:10520    (local dev, strong auth)
CLI ──basic──▶ 0.0.0.0  :10521    (local dev, weak auth)
CLI ──tls────▶ 0.0.0.0  :18767    (remote access)
Browser ──────▶ 127.0.0.1:18766    (Web UI)

| 文件 | 用途 |
|---|---|
| common.toml / shared.toml | 数据目录（~/.pty-agent）、默认终端尺寸、协议缓冲区 |
| daemon/daemon.toml | 3 个监听器、缓冲区、默认超时（120s）、认证与密钥 |
| daemon/sandbox.toml | 沙箱开关与配额（默认：关闭） |
| client/client.toml | CONNECT_MODE = basic\|token\|tls、TOFU 严格模式 |

注意：若在同一台机器上运行两个 PTY-Agent 实例，请禁用 SINGLE_INSTANCE。

文档

| 文档 | 描述 |
|---|---|
| ARCHITECTURE.md | src/ 包架构、模块分层、调用链 |
| CLI.md | CLI 参考 |
| WORKFLOW.md | 工作流编排（YAML 步骤、并行、条件、重试） |
| PLUGINS_API.md | 插件开发指南 |
| CONFIG.md | 配置参考 |

许可证

除 src\web\static\ 和 web_rime\ 外，其余均为 MIT。

src\web\static\ 和 web_rime\ 使用 AGPL-3.0 许可证。

特性

- ✨ 轻松操作 Shell · CUI · TUI —— 真正像人一样使用终端：起会话、发按键、等提示符、看屏幕 ✨
- ✨ Windows / Linux 跨平台 —— 将来还会支持 MacOS ✨
- ✨ 实时 Web 监控 —— 实时接管每一个终端会话，也可以一起协作 ✨
- ✨ 沙箱系统 —— 启用后，AI 只在工作区工作，根本上防止删盘
- ✨ 强大的插件系统 -- 需要什么功能，随意扩展
- AI 二次分析，长上下文一步就好 —— 把长日志、大段输出、甚至渲染后的终端图片直接交给另一个 AI，一步返回结论
- 子 Agent：跨 Harness 启动，统一管理 —— OpenCode / Claude Code / ... 支持扩展
- workflow 多会话编排
- 跨机访问终端 —— 支持 ssh 般的体验

为什么需要它

常规 Agent 跑不了 ssh、跑不了 gdb、跑不了 cdb，也跑不了任何会反问你一句的程序

| 传统调用 | PTY-Agent |
| --- | --- |
| 无 TTY，程序自动降级为非交互模式 | 真实伪终端 |
| 只能"跑完再看" | 可使用持久化终端 |
| 无法"等到出现某个提示符" | -t "" 正则触发器，命中即返回 |
| 卡住 / 崩溃 / 弹窗 → 调用方一起卡死、user白白等待 | 静默超时、GUI 窗口、崩溃、进程退出 —— 全部可感知、可返回 |
| 拿到原始字节流 | 拿到渲染后的终端屏幕快照 |

能力速览

| | |
| --- | --- |
| 运行模式 | pty（默认，屏幕快照，适合 TUI/REPL）；--subprocess（增量输出 + stderr 分离，适合编译/下载） |
| 自定义返回条件 | ok / matched / timeout / idle / ended / crashed / gui / cancelled / notify |
| 结果裁剪 | -l N、-g ""、-s 增量 diff、--column N、-o 导出 .svg/.png/.jpg/.txt |
| 输入 | send 原样；advsend 支持 {ctrl+c} {enter} {f1}~{f12} 等控制字符；行尾 lf/crlf/cr/none，鼠标click/drag/scroll/hover/press/grep，--grep "" 用文本反查坐标，不必数行列 |
| 异步 | --notify 立即返回，条件满足后由 wait / notice  取回，不阻塞自己 |
| 编排 | workflow YAML DAG：依赖并行、if 条件（AST 白名单安全求值）、retry、on_error |
| Web | 浏览器终端（xterm.js + Web RIME 中文输入法）、FastScreen 屏幕流、VNC 远程桌面，默认 127.0.0.1:18766 |
| 沙箱 | Windows opt-in：Job Object + 受限令牌，仅工作目录可写，内存/CPU/进程数/墙钟配额 |

安装

该 Skill 需要编译，请下载 Release 的预编译包，或者 clone 之后使用build.py编译

它是怎么工作的

graph LR
A["AI Agent"] -->|"PTY-Agent <cmd>"| B["CLIsrc/cli · src/client"]
B -->|"TCP · NDJSONToken+HMAC / TLS+Ed25519"| C["守护进程src/daemon"]
C --> D["会话管理src/session"]
D --> E["PTY 后端src/pty"]
E -->|"ConPTY / openpty"| F["真实程序"]
F --> G["读者线程 → 输出缓冲"]
G --> H["终端模型 wezterm-termVT 解析 → 快照/diff/SVG"]
H --> I["触发检测正则·静默·崩溃·GUI"]
I -->|"响应 JSON"| B
C --> J["Web · workflow · 插件"]

配置

配置集中在 config/，可用环境变量 PTY_AGENT_ 覆写，改完需重启进程

CLI ──token──▶ 127.0.0.1:10520    (本地开发强验证)
CLI ──basic──▶ 0.0.0.0  :10521    (本地开发弱验证，没问题开这一个就好)
CLI ──tls────▶ 0.0.0.0  :18767    (提供跨机访问)
浏览器 ───────▶ 127.0.0.1:18766    (Web)

| 文件 | 管什么 |
| --- | --- |
| common.toml / shared.toml | 数据目录（~/.pty-agent）、默认终端尺寸、协议缓冲 |
| daemon/daemon.toml | 三监听器、缓冲区、默认超时（120s）、认证与密钥 |
| daemon/sandbox.toml | 沙箱开关与配额（默认关闭） |
| client/client.toml | CONNECT_MODE = basic\|token\|tls、TOFU 严格模式 |

注意：如果一台设备要开启两个 PTY-Agent，请关闭单实例锁SINGLE_INSTANCE

文档

| 文档 | 说明 |
| --- | --- |
| ARCHITECTURE.md | src/ 包模块化架构设计，为代码维护与扩展提供指导 |
| CLI.md | 命令行帮助文档 |
| WORKFLOW.md | Workflow 脚本编排使用文档（YAML 步骤定义、依赖并行、条件、重试） |
| PLUGINS_API.md | 插件开发指南（Plugin API） |
| CONFIG.md | 配置说明 |

许可证

除了src\web\static\、web_rime\，其他都为 MIT

src\web\static\、web_rime\使用 AGPL-3.0 license

https://github.com/user-attachments/assets/5d8402e8-5fa6-4c7e-91b0-124a2ea953e4