PTY

PTY(伪终端)是一种虚拟终端接口,让程序可以像连接真实终端一样与 shell 交互。使用 sandbox.pty 模块可以创建交互式终端会话,用于运行命令、接收输入,并可在运行中调整大小——适用于 REPL 和调试器、需要提示输入的交互式 CLI,以及需要监控的长时间运行进程。

注意: PTY 由其进程 ID(pid)标识,该 ID 由 create() 返回句柄上提供。发送输入、调整大小、连接和终止时都需传入该 pid。输出以原始字节形式传递给回调函数。

操作	JavaScript / TypeScript	Python
创建	`sandbox.pty.create(opts)`	`sandbox.pty.create(size, ...)`
连接	`sandbox.pty.connect(pid, opts?)`	`sandbox.pty.connect(pid, ...)`
发送输入	`sandbox.pty.sendInput(pid, data)`	`sandbox.pty.send_stdin(pid, data)`
调整大小	`sandbox.pty.resize(pid, size)`	`sandbox.pty.resize(pid, size)`
终止	`sandbox.pty.kill(pid)`	`sandbox.pty.kill(pid)`

创建 PTY

创建一个 PTY,并通过回调接收其输出。它会返回一个句柄,其 pid 用于标识该 PTY。

选项	类型	说明
`cols` / `rows`	number	终端尺寸(Python:`PtySize(cols=…, rows=…)`)
`onData`(JS)	(data: Uint8Array) => void	PTY 输出的回调。Python 通过 `wait(on_pty=...)` 传递输出
`user`	string(可选)	运行 PTY 所使用的用户
`cwd`	string(可选)	工作目录
`envs`	object / dict(可选)	环境变量(`TERM`、`LANG`、`LC_ALL` 有默认值)
`timeoutMs` / `timeout`	number(默认 60000 ms / 60 s)	PTY 超时时间;JS 使用毫秒,Python 使用秒

from ppio_sandbox import PPIO, PtySize

ppio = PPIO()

sandbox = ppio.sandbox.create()

def on_pty(data: bytes):
    print(data.decode('utf-8', errors='replace'), end='')

# PtySize 接受关键字参数 cols / rows
pty = sandbox.pty.create(PtySize(cols=120, rows=30), cwd='/home/user', envs={'TERM': 'xterm-256color'})
print('PTY pid:', pty.pid)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const sandbox = await ppio.sandbox.create()

const pty = await sandbox.pty.create({
  cols: 120,
  rows: 30,
  cwd: '/home/user',
  envs: { TERM: 'xterm-256color' },
  onData: (data) => {
    process.stdout.write(new TextDecoder().decode(data))
  },
})

console.log('PTY pid:', pty.pid)

发送输入

通过 pid 向运行中的 PTY 发送输入。数据为原始字节。

sandbox.pty.send_stdin(pty.pid, b'echo hello\n')
sandbox.pty.send_stdin(pty.pid, b'exit\n')

const enc = new TextEncoder()
await sandbox.pty.sendInput(pty.pid, enc.encode('echo hello\n'))
await sandbox.pty.sendInput(pty.pid, enc.encode('exit\n'))

调整 PTY 大小

当终端窗口尺寸发生变化时,调用 resize。

sandbox.pty.resize(pty.pid, PtySize(cols=150, rows=40))

await sandbox.pty.resize(pty.pid, { cols: 150, rows: 40 })

连接到运行中的 PTY

通过 pid 连接到已在运行的 PTY。可以通过 sandbox.commands.list() 获取正在运行的进程。返回的句柄会通过回调接收后续输出。

handle = sandbox.pty.connect(pty.pid)

const handle = await sandbox.pty.connect(pty.pid, {
  onData: (data) => process.stdout.write(new TextDecoder().decode(data)),
})

终止 PTY

kill 使用 SIGKILL 终止 PTY。如果 PTY 被成功终止则返回 true;如果找不到对应 pid 的 PTY 则返回 false。

killed = sandbox.pty.kill(pty.pid)
print('killed:', killed)

sandbox.kill()

const killed = await sandbox.pty.kill(pty.pid)
console.log('killed:', killed)

await sandbox.kill()

交互式示例

创建一个 PTY,发送一条需要提示输入的交互式命令,然后等待其结束并读取退出码。在 Python 中,wait(on_pty=...) 会将输出流式传递给回调并返回结果。

from ppio_sandbox import PPIO, PtySize

ppio = PPIO()

sandbox = ppio.sandbox.create()

output = []

def on_pty(data: bytes):
    output.append(data.decode('utf-8', errors='replace'))

terminal = sandbox.pty.create(PtySize(cols=80, rows=24), envs={'ABC': '123'}, cwd='/')

# 发送命令并退出
sandbox.pty.send_stdin(terminal.pid, b'echo $ABC\nexit\n')

# 流式输出并等待完成
result = terminal.wait(on_pty=on_pty)
print('exit code:', result.exit_code)
print(''.join(output))

sandbox.kill()

产品简介

快速开始

最佳实践

Sandbox

Template

Snapshot

文件系统

Secret

Volume

工具集成

CLI 功能

旧版归档

创建 PTY

发送输入

调整 PTY 大小

连接到运行中的 PTY

终止 PTY

交互式示例

​创建 PTY

​发送输入

​调整 PTY 大小

​连接到运行中的 PTY

​终止 PTY

​交互式示例

创建 PTY

发送输入

调整 PTY 大小

连接到运行中的 PTY

终止 PTY

交互式示例