主机终端控制

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. 快速开始

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/connect
  • inRuntime: 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)

⚠️ 局限:

  1. 只返回"当前屏幕",不是"完整历史"
  2. 全屏程序(top/vim)会覆盖历史
  3. lines 里的是"屏幕显示",不是"命令原文"
  4. 拿不到退出码(需 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=...):默认 403
  • warn 级(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 用法:

  1. 执行前先调 /api/security/check
  2. safe → 直接执行
  3. 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 应该:

  1. /api/hosts/list 拿主机列表
  2. 挑选 connected: true 的
  3. 后续每个请求都显式传 hostId
  4. 校验响应里的 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