主机终端控制
PTY Agent HTTP-API 文档
供 AI-Agent 通过 HTTP 远程控制 PTY 终端使用
基础信息
| 项 | 值 |
|---|---|
| Base URL | http://ai.pty.{clientId}.html.dtns.top |
| 示例 | http://ai.pty.xxfftt.html.dtns.top |
| 协议 | HTTP / HTTPS(走 WebSocket 隧道反代) |
| 编码 | UTF-8 |
| CORS | 全开 Access-Control-Allow-Origin: * |
| Content-Type | application/json(POST 推荐) |
目录
- 0. 快速开始
- 1. 通用约定
- 2. 健康检查 / 元信息
- 3. 主机管理
- 4. 终端会话管理
- 5. PTY 输入输出
- 6. 命令执行
- 7. 文件操作
- 8. AI 上下文
- 9. 安全
- 10. 典型 Agent 工作流
- 11. 错误码
0. 快速开始
BASE="http://ai.pty.xxyyzz.html.dtns.top"
# 1. 健康检查
curl -s "$BASE/health" | jq
# 2. 列出主机
curl -s "$BASE/api/hosts/list" | jq
# 3. 执行命令(最常用)
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d '{"hostId":"h-mv1r4usc-fb1q","command":"uname -a && whoami"}' | jq
1. 通用约定
1.1 每个 API 同时支持 GET 和 POST
- GET:参数放在 URL query
- POST:参数放在 body(JSON 或 form-urlencoded),也支持 URL query 覆盖
# 等价
curl -G "$BASE/api/exec" --data-urlencode 'command=uname -a'
curl -X POST "$BASE/api/exec" -H 'Content-Type: application/json' -d '{"command":"uname -a"}'
1.2 hostId 说明
- 显式传
hostId:操作指定主机(Agent 推荐) - 不传:用"第一个已连接的主机"(不确定,仅用于人类调试)
- 响应里回显
hostId:Agent 应校验是否与自己预期一致
1.3 termId 说明
- 由
/api/pty/create返回 - 后续所有 PTY 操作都用它
- Agent 应自己管理 termId,不要依赖"当前激活终端"
1.4 二进制安全:base64
PTY 输出可能含控制字符、非 UTF-8。二进制数据用 base64 传:
- 写:
dataBase64(base64 编码的字节) - 读:
dataBase64(响应里返回) - 文件:
dataBase64
1.5 换行符
- Unix(Linux/macOS):
\n(LF) - Windows(PowerShell/cmd):
\r(CR)
Agent 需要注意平台差异。建议用 /api/exec(自动处理)而非手动 write。
1.6 URL 编码
GET 请求里所有参数必须 URL 编码:
| 字符 | 编码 |
|---|---|
\n |
%0A |
\r |
%0D |
| 空格 | %20 |
& |
%26 |
= |
%3D |
# |
%23 |
% |
%25 |
推荐用 --data-urlencode(curl 自动处理)。
2. 健康检查 / 元信息
2.1 GET /health — 健康检查
请求:
curl -s "$BASE/health"
响应:
{
"status": "ok",
"service": "pty-agent",
"version": "1.0.0",
"clientId": "xxyyzz",
"enabled": true,
"timestamp": "2026-10-14T10:00:00.000Z"
}
2.2 GET /api/info — 查看服务能力
请求:
curl -s "$BASE/api/info" | jq
响应:
{
"name": "PTY Agent Service",
"version": "1.0.0",
"clientId": "xxyyzz",
"domain": "ai.pty.xxyyzz.html.dtns.top",
"defaultHostId": "h-mv1r4usc-fb1q",
"capabilities": [
"pty_create", "pty_write", "pty_read", "pty_resize", "pty_destroy", "pty_list",
"exec_local", "exec_ssh",
"fs_list", "fs_download", "fs_upload", "fs_delete",
"ai_context", "security_check"
],
"hosts": [
{ "id": "h-mv1r4usc-fb1q", "name": "ibsvr02", "url": "ws://pty.devmymnc.html.dtns.top" },
{ "id": "h-mv1r5qsz-yrra", "name": "ibsvr", "url": "ws://pty.devmymc.html.dtns.top" }
],
"allowDanger": false
}
Agent 用法:启动时先调一次,拿 defaultHostId 和 capabilities。
3. 主机管理
3.1 GET /api/hosts/list — 列出所有主机
请求:
curl -s "$BASE/api/hosts/list" | jq
响应:
{
"success": true,
"hosts": [
{
"id": "h-mv1r4usc-fb1q",
"name": "ibsvr02",
"url": "ws://pty.devmymnc.html.dtns.top",
"inRuntime": true,
"connected": true,
"clientConnected": true,
"terminalCount": 0
},
{
"id": "h-mv1r5qsz-yrra",
"name": "ibsvr",
"url": "ws://pty.devmymc.html.dtns.top",
"inRuntime": false,
"connected": false,
"clientConnected": false,
"terminalCount": 0
}
]
}
字段说明:
| 字段 | 含义 |
|---|---|
inRuntime |
当前页面是否曾经连接过该主机 |
connected |
真实连接状态(实时查询) |
clientConnected |
底层 WebSocket 状态 |
terminalCount |
该主机当前终端数 |
Agent 用法:
- 挑
connected: true的主机,直接用 inRuntime: false的主机,先调/api/hosts/connectinRuntime: true, connected: false的主机,正在重连或已断开
3.2 GET /api/hosts/status — 单主机状态
请求:
curl -s "$BASE/api/hosts/status?hostId=h-mv1r4usc-fb1q" | jq
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"inRuntime": true,
"connected": true,
"clientConnected": true,
"terminalCount": 3,
"activeTermId": "rtptyx-mv7izgpu-845n4i",
"backends": ["local", "ssh"],
"shells": [
{ "id": "bash", "backend": "local", "path": "/bin/bash" },
{ "id": "zsh", "backend": "local", "path": "/bin/zsh" }
]
}
字段说明:
| 字段 | 含义 |
|---|---|
activeTermId |
前端当前激活的 tab(用户视线所在) |
backends |
可用后端(local / ssh) |
shells |
可用 shell 列表 |
4. 终端会话管理
4.1 GET /api/pty/list — 列出终端
请求:
curl -s "$BASE/api/pty/list?hostId=h-mv1r4usc-fb1q" | jq
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"activeTermId": "rtptyx-mv7izgpu-845n4i",
"terminals": [
{
"termId": "rtptyx-mv7izgpu-845n4i",
"pid": 31094,
"backend": "local",
"shellId": "bash",
"bin": "/bin/bash",
"cols": 246,
"rows": 51,
"cwd": "/home/ibsvr",
"createdAt": 1791947013567,
"lastActiveAt": 1791949036127,
"exited": false,
"exitCode": null,
"active": true,
"inUI": true
}
]
}
字段说明:
| 字段 | 含义 |
|---|---|
activeTermId |
前端当前激活的 tab |
terminals[].active |
是否等于 activeTermId |
terminals[].inUI |
当前页面是否有该终端 tab |
terminals[].lastActiveAt |
最后活动时间(毫秒时间戳) |
4.2 POST /api/pty/create — 创建终端
请求:
curl -s -X POST "$BASE/api/pty/create" \
-H 'Content-Type: application/json' \
-d '{
"hostId": "h-mv1r4usc-fb1q",
"backend": "local",
"shellId": "bash",
"cols": 120,
"rows": 30
}' | jq
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
hostId |
否 | 主机 ID(不传用默认) |
backend |
否 | local(默认)/ ssh |
shellId |
否 | shell ID(如 bash) |
cols |
否 | 列数(默认 80) |
rows |
否 | 行数(默认 24) |
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"termId": "rtptyx-mv7izgpu-845n4i",
"backend": "local",
"shellId": "bash",
"cols": 120,
"rows": 30
}
Agent 用法:拿到 termId 后,后续操作都用它。
4.3 POST /api/pty/destroy — 销毁终端
请求:
curl -s -X POST "$BASE/api/pty/destroy" \
-H 'Content-Type: application/json' \
-d '{"hostId":"h-mv1r4usc-fb1q","termId":"rtptyx-mv7izgpu-845n4i"}' | jq
响应:
{ "success": true, "termId": "rtptyx-mv7izgpu-845n4i" }
4.4 POST /api/pty/resize — 调整终端尺寸
请求:
curl -s -X POST "$BASE/api/pty/resize" \
-H 'Content-Type: application/json' \
-d '{"termId":"rtptyx-mv7izgpu-845n4i","cols":120,"rows":30}' | jq
响应:
{ "success": true, "termId": "rtptyx-mv7izgpu-845n4i", "cols": 120, "rows": 30 }
5. PTY 输入输出
5.1 POST /api/pty/write — 写入 PTY
⚠️ 注意:这是纯字节写入,不自动加换行。
请求(JSON):
curl -s -X POST "$BASE/api/pty/write" \
-H 'Content-Type: application/json' \
-d '{"termId":"rtptyx-mv7izgpu-845n4i","data":"ls -la\n"}'
请求(base64,二进制安全):
# "ls -la\n" 的 base64
B64=$(echo -n 'ls -la
' | base64)
curl -s -X POST "$BASE/api/pty/write" \
-H 'Content-Type: application/json' \
-d "{\"termId\":\"rtptyx-mv7izgpu-845n4i\",\"dataBase64\":\"$B64\"}"
请求(GET):
curl -s -G "$BASE/api/pty/write" \
--data-urlencode 'termId=rtptyx-mv7izgpu-845n4i' \
--data-urlencode {{SKILL_CONTENT}}#39;data=ls -la\n'
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
termId |
是 | 终端 ID |
data |
二选一 | 文本数据(字符串) |
dataBase64 |
二选一 | base64 编码的字节 |
响应:
{
"success": true,
"termId": "rtptyx-mv7izgpu-845n4i",
"bytesWritten": 8
}
⚠️ 换行陷阱:
| 平台 | 换行 | 说明 |
|---|---|---|
| Linux/macOS | \n (LF) |
bash/zsh 认 |
| Windows | \r (CR) |
PSReadLine 只认 \r |
Windows 下 \n 不执行——会出现 >> 续行提示符。
Agent 建议:不要用 write 执行命令,用 /api/exec。
5.2 GET /api/pty/read — 读取终端输出
请求:
# 读最近 50 行
curl -s "$BASE/api/pty/read?termId=rtptyx-mv7izgpu-845n4i&lines=50" | jq
# 读全部
curl -s "$BASE/api/pty/read?termId=rtptyx-mv7izgpu-845n4i" | jq
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
termId |
是 | 终端 ID |
lines |
否 | 读最近 N 行(默认 50) |
响应:
{
"success": true,
"termId": "rtptyx-mv7izgpu-845n4i",
"seq": 1791947926633,
"lines": [
"ibsvr@ibsvr-02:~$ pwd",
"/home/ibsvr",
"ibsvr@ibsvr-02:~$ "
],
"dataBase64": "aWJzdnJAaWJzdnItMDI6fiQgcHdkCi9ob21lL2lic3ZyCmlic3ZyQGlic3ZyLTAyOn4kIA=="
}
响应字段:
| 字段 | 含义 |
|---|---|
seq |
时间戳(毫秒) |
lines |
数组,每行一个字符串(已剥 ANSI 颜色码) |
dataBase64 |
合并的完整文本(base64) |
⚠️ 局限:
- 只返回"当前屏幕",不是"完整历史"
- 全屏程序(top/vim)会覆盖历史
lines里的是"屏幕显示",不是"命令原文"- 拿不到退出码(需 shell 集成 OSC 133)
Agent 用法:
- 要"看终端状态":
/api/pty/read - 要"执行命令 + 拿结果":
/api/exec(推荐)
6. 命令执行
6.1 POST /api/exec — 执行命令(Agent 最常用)
特性:
- 走独立执行通道(HTTP → 后端 PTY → 拿 stdout/stderr/exitCode)
- 不污染交互式终端(不占用 tab)
- 自动处理换行
- 返回确定的
command、stdout、stderr、exitCode
请求:
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d '{
"hostId": "h-mv1r4usc-fb1q",
"command": "uname -a && whoami && pwd",
"timeout": 10000,
"useSsh": false
}' | jq
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
hostId |
否 | 主机 ID(不传用默认) |
command |
是 | 要执行的命令 |
timeout |
否 | 超时毫秒(默认 60000) |
useSsh |
否 | 是否走 SSH 后端(默认 false) |
confirm |
否 | true 时允许执行 warn/danger 命令 |
响应:
{
"success": true,
"stdout": "Linux ibsvr-02 6.5.0-35-generic ... x86_64 GNU/Linux\nibsvr\n/home/ibsvr\n",
"stderr": "",
"exitCode": 0,
"duration": 128,
"command": "uname -a && whoami && pwd",
"useSsh": false,
"risk": "safe"
}
字段说明:
| 字段 | 含义 |
|---|---|
stdout |
标准输出 |
stderr |
标准错误 |
exitCode |
退出码(0 = 成功) |
duration |
耗时(毫秒) |
command |
回显命令(确认无篡改) |
risk |
安全等级(safe / warn / danger) |
Agent 用法:
# 1. 简单执行
curl -s -X POST "$BASE/api/exec" -H 'Content-Type: application/json' \
-d '{"hostId":"h-xxx","command":"df -h"}'
# 2. 带超时
curl -s -X POST "$BASE/api/exec" -H 'Content-Type: application/json' \
-d '{"hostId":"h-xxx","command":"find / -name \"*.log\"","timeout":30000}'
# 3. 用 SSH 后端
curl -s -X POST "$BASE/api/exec" -H 'Content-Type: application/json' \
-d '{"hostId":"h-xxx","command":"docker ps","useSsh":true}'
⚠️ 危险命令:
danger级(rm -rf /、dd if=...):默认 403warn级(rm -rf dir、shutdown):默认 403- 传
"confirm": true强制执行
7. 文件操作
7.1 GET /api/fs/list — 列出文件
请求:
curl -s "$BASE/api/fs/list?hostId=h-mv1r4usc-fb1q" | jq
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"files": [
{ "name": "a.bin", "size": 102400 },
{ "name": "hello.cpp", "size": 256 },
{ "name": "logs.tar.gz", "size": 1048576 }
]
}
7.2 GET /api/fs/download — 下载文件
请求:
curl -s "$BASE/api/fs/download?hostId=h-xxx&name=hello.cpp" | jq
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"name": "hello.cpp",
"size": 256,
"dataBase64": "I2luY2x1ZGUgPGlvc3RyZWFtPgppbnQgbWFpbigpIH..."
}
Agent 用法:
# 下载并解码
curl -s "$BASE/api/fs/download?hostId=h-xxx&name=hello.cpp" \
| jq -r '.dataBase64' | base64 -d > hello.cpp
7.3 POST /api/fs/upload — 上传文件
请求:
# 内容 "hello world\n" 的 base64
DATA=$(echo -n 'hello world
' | base64)
curl -s -X POST "$BASE/api/fs/upload" \
-H 'Content-Type: application/json' \
-d "{
\"hostId\":\"h-mv1r4usc-fb1q\",
\"name\":\"test.txt\",
\"rel\":\"test.txt\",
\"dataBase64\":\"$DATA\"
}" | jq
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
hostId |
否 | 主机 ID |
name |
是 | 文件名 |
rel |
否 | 相对路径(含目录),默认 = name |
dataBase64 |
是 | base64 编码的文件内容 |
响应:
{
"success": true,
"name": "test.txt",
"rel": "test.txt",
"size": 12
}
7.4 POST /api/fs/delete — 删除文件
请求:
curl -s -X POST "$BASE/api/fs/delete" \
-H 'Content-Type: application/json' \
-d '{"hostId":"h-xxx","name":"test.txt"}' | jq
响应:
{ "success": true, "name": "test.txt" }
8. AI 上下文
8.1 GET /api/ai/context — 获取终端上下文
请求:
curl -s "$BASE/api/ai/context?hostId=h-xxx&termId=rtptyx-mv7ji2dn-2vuj8y&lines=50" | jq
参数:
| 参数 | 必填 | 说明 |
|---|---|---|
hostId |
否 | 主机 ID |
termId |
否 | 终端 ID(不传用 activeTermId) |
lines |
否 | 读最近 N 行(默认 50) |
响应:
{
"success": true,
"hostId": "h-mv1r4usc-fb1q",
"termId": "rtptyx-mv7ji2dn-2vuj8y",
"recentOutput": "ibsvr@ibsvr-02:~$ pwd\n/home/ibsvr\nibsvr@ibsvr-02:~$ ",
"lines": 50,
"lastCommand": "pwd",
"cwd": "~",
"exitCode": null
}
字段说明:
| 字段 | 含义 |
|---|---|
recentOutput |
最近终端输出(纯文本) |
lastCommand |
从 prompt 提取的最后命令(可能为 null) |
cwd |
从 prompt 提取的当前目录(可能为 null) |
exitCode |
退出码(恒为 null,需 shell 集成) |
⚠️ 局限:
lastCommand/cwd依赖 prompt 格式(user@host:path$)- 用户自定义 PS1 会失效
- 全屏程序场景可能提不到
Agent 用法:把 recentOutput 拼进 LLM prompt,让 LLM 分析。
9. 安全
9.1 GET /api/security/check — 命令安全检查
请求:
curl -s -G "$BASE/api/security/check" \
--data-urlencode 'command=rm -rf /' | jq
响应:
{
"success": true,
"command": "rm -rf /",
"safe": false,
"risk": "danger",
"reason": "rm 删除根目录",
"matched": "/rm\\s+(-[a-zA-Z]*[rf][a-zA-Z]*\\s+)*\\/(\\s|$)/"
}
风险等级:
| 等级 | 含义 | 示例 |
|---|---|---|
safe |
只读命令 | ls、cat、grep、find |
warn |
需要确认 | rm -rf dir、shutdown、sudo rm |
danger |
默认禁止 | rm -rf /、dd if=...、mkfs |
Agent 用法:
- 执行前先调
/api/security/check safe→ 直接执行warn/danger→ 提示用户确认,加"confirm": true执行
10. 典型 Agent 工作流
场景 1:查看系统信息
BASE="http://ai.pty.xxx.html.dtns.top"
# 1. 找可用主机
HOST=$(curl -s "$BASE/api/hosts/list" | jq -r '.hosts[] | select(.connected==true) | .id' | head -1)
# 2. 执行命令
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d "{\"hostId\":\"$HOST\",\"command\":\"uname -a && df -h && free -m\"}" | jq
场景 2:分析终端错误
# 1. 拿上下文
CTX=$(curl -s "$BASE/api/ai/context?hostId=$HOST&lines=50")
# 2. 提取 recentOutput 给 LLM
OUTPUT=$(echo "$CTX" | jq -r '.recentOutput')
# 3. 调 LLM 分析
curl -X POST https://api.openai.com/v1/chat/completions \
-H 'Authorization: Bearer sk-xxx' \
-H 'Content-Type: application/json' \
-d "{
\"model\": \"gpt-4o-mini\",
\"messages\": [
{\"role\":\"system\",\"content\":\"你是 Linux 助手。\"},
{\"role\":\"user\",\"content\":\"分析这段终端输出:\n$OUTPUT\"}
]
}"
场景 3:清理日志(带安全确认)
# 1. 列文件
curl -s "$BASE/api/fs/list?hostId=$HOST" | jq
# 2. 找旧日志
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d "{\"hostId\":\"$HOST\",\"command\":\"find /tmp -name '*.log' -mtime +7\"}" | jq -r '.stdout'
# 3. 安全检查
curl -s -G "$BASE/api/security/check" \
--data-urlencode "command=find /tmp -name '*.log' -mtime +7 -delete" | jq
# → { "risk": "warn", ... }
# 4. 带 confirm 执行
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d "{
\"hostId\":\"$HOST\",
\"command\":\"find /tmp -name '*.log' -mtime +7 -delete\",
\"confirm\":true
}" | jq
场景 4:创建终端 + 交互
# 1. 创建终端
TERM=$(curl -s -X POST "$BASE/api/pty/create" \
-H 'Content-Type: application/json' \
-d "{\"hostId\":\"$HOST\",\"backend\":\"local\",\"shellId\":\"bash\"}" \
| jq -r '.termId')
# 2. 发命令(注意换行)
curl -s -X POST "$BASE/api/pty/write" \
-H 'Content-Type: application/json' \
-d "{\"termId\":\"$TERM\",\"data\":\"ls -la\n\"}"
# 3. 读结果
sleep 1
curl -s "$BASE/api/pty/read?termId=$TERM&lines=30" | jq -r '.dataBase64' | base64 -d
# 4. 销毁
curl -s -X POST "$BASE/api/pty/destroy" \
-H 'Content-Type: application/json' \
-d "{\"hostId\":\"$HOST\",\"termId\":\"$TERM\"}"
场景 5:上传脚本并执行
# 1. 上传脚本
SCRIPT_B64=$(cat deploy.sh | base64 -w0)
curl -s -X POST "$BASE/api/fs/upload" \
-H 'Content-Type: application/json' \
-d "{
\"hostId\":\"$HOST\",
\"name\":\"deploy.sh\",
\"dataBase64\":\"$SCRIPT_B64\"
}"
# 2. 赋权 + 执行
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d "{
\"hostId\":\"$HOST\",
\"command\":\"chmod +x deploy.sh && ./deploy.sh\",
\"timeout\":300000,
\"confirm\":true
}" | jq
11. 错误码
| HTTP | 含义 | 常见原因 |
|---|---|---|
| 200 | 成功 | — |
| 400 | 参数错误 | 缺 termId、command 等 |
| 403 | 权限/安全拒绝 | 危险命令未 confirm |
| 404 | 资源不存在 | termId 不存在、路由不存在 |
| 500 | 服务器内部错误 | 客户端异常、shell 报错 |
| 503 | 服务不可用 | 主机未连接 |
错误响应格式:
{
"success": false,
"error": "host not connected",
"hostId": "h-mv1r5qsz-yrra",
"hint": "请先调用 /api/hosts/connect"
}
常见错误处理:
| 错误 | 处理 |
|---|---|
host not connected |
先 /api/hosts/connect,或换 connected: true 的主机 |
termId is required |
补参数 |
危险命令,默认禁止 |
加 "confirm": true |
命令需要确认 |
加 "confirm": true |
downloadFileToBytes 未实现 |
升级 PtyClient |
12. Agent 最佳实践
12.1 首选 /api/exec,不是 /api/pty/write
| 场景 | 推荐 |
|---|---|
| Agent 执行命令拿结果 | ✅ POST /api/exec |
| Agent 交互式操作(vim/top) | ⚠️ POST /api/pty/write + GET /api/pty/read |
| 一次性只读命令 | ✅ POST /api/exec |
| 需要看终端当前状态 | ✅ GET /api/pty/read |
/api/exec 的优势:
- 返回确定
command+stdout+stderr+exitCode - 不依赖终端解析
- 不受全屏程序影响
- 自动处理换行
12.2 显式指定 hostId
不要依赖"默认主机"——Agent 应该:
/api/hosts/list拿主机列表- 挑选
connected: true的 - 后续每个请求都显式传
hostId - 校验响应里的
hostId是否匹配
12.3 危险命令先 check
# 先检查
RISK=$(curl -s -G "$BASE/api/security/check" \
--data-urlencode "command=$CMD" | jq -r '.risk')
if [ "$RISK" = "danger" ]; then
echo "危险命令,需人工确认"
exit 1
fi
# 再执行
curl -s -X POST "$BASE/api/exec" \
-H 'Content-Type: application/json' \
-d "{\"hostId\":\"$HOST\",\"command\":\"$CMD\",\"confirm\":true}"
12.4 base64 处理二进制
上传/下载文件、PTY 二进制输出都必须用 base64:
# 上传
base64 -w0 local.txt | xargs -I{} curl -X POST "$BASE/api/fs/upload" \
-H 'Content-Type: application/json' \
-d '{"name":"remote.txt","dataBase64":"{}"}'
# 下载
curl -s "$BASE/api/fs/download?name=remote.txt" \
| jq -r '.dataBase64' | base64 -d > local.txt
12.5 显式管理 termId
Agent 创建终端后,自己保存 termId——不要每次重新查:
# Python 示例
term_id = requests.post(f"{base}/api/pty/create", json={
"hostId": host_id, "backend": "local", "shellId": "bash"
}).json()["termId"]
# 后续操作都用 term_id
requests.post(f"{base}/api/pty/write", json={
"termId": term_id, "data": "ls -la\n"
})
12.6 超时设置
/api/exec:默认 60 秒,长任务传timeout: 300000/api/pty/write:立即返回/api/pty/read:立即返回
12.7 平台差异处理
Linux:
{"command": "ls -la"} # 自动 \n
Windows:
{"command": "Get-ChildItem"} # 自动 \r
用 /api/exec 自动处理——手动 /api/pty/write 需自己区分 \n vs \r。
12.8 支持的 HTTP 方法
每个 API 都同时支持 GET 和 POST:
# 等价
curl -G "$BASE/api/exec" --data-urlencode 'command=ls'
curl -X POST "$BASE/api/exec" -d '{"command":"ls"}' -H 'Content-Type: application/json'
- 简单只读:GET(curl 调试方便)
- 复杂参数 / 大 body:POST(推荐)
附录:完整端点速查表
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /health |
健康检查 |
| GET | /api/info |
服务能力 + 默认主机 |
| GET | /api/hosts/list |
所有主机状态 |
| GET | /api/hosts/status |
单主机状态 |
| GET | /api/pty/list |
终端列表 |
| POST | /api/pty/create |
创建终端 |
| POST | /api/pty/destroy |
销毁终端 |
| POST | /api/pty/write |
写入 PTY |
| GET | /api/pty/read |
读终端输出 |
| POST | /api/pty/resize |
调整终端尺寸 |
| POST | /api/exec |
执行命令(推荐) |
| GET | /api/fs/list |
列文件 |
| GET | /api/fs/download |
下载文件 |
| POST | /api/fs/upload |
上传文件 |
| POST | /api/fs/delete |
删除文件 |
| GET | /api/ai/context |
终端上下文 |
| GET | /api/security/check |
命令安全检查 |
所有端点同时支持 GET 和 POST。
附录:字段速查
主机相关
| 字段 | 类型 | 说明 |
|---|---|---|
hostId |
string | 主机 ID |
inRuntime |
bool | 页面是否曾连接过 |
connected |
bool | 真实连接状态 |
clientConnected |
bool | WebSocket 状态 |
终端相关
| 字段 | 类型 | 说明 |
|---|---|---|
termId |
string | 终端 ID |
pid |
number | 进程 PID |
backend |
string | local / ssh |
shellId |
string | shell 名 |
cols / rows |
number | 尺寸 |
cwd |
string | 当前目录 |
exited |
bool | 是否已退出 |
active |
bool | 前端是否激活 |
执行结果
| 字段 | 类型 | 说明 |
|---|---|---|
stdout |
string | 标准输出 |
stderr |
string | 标准错误 |
exitCode |
number | 退出码 |
duration |
number | 耗时(ms) |
risk |
string | 安全等级 |
文档版本:1.0.0 生成时间:2026-10-14 对应服务:PTY Agent HTTP-Proxy