API：终端

Halo HTTP API 终端接口：创建终端会话、发送输入、调整大小、回读输出和关闭终端会话。

这些是 Halo 中可被用户查看和输入的终端会话：创建、发送输入、调整大小、回读输出和关闭。实时输出通过 WebSocket 推送。终端只在 macOS 和 Windows 上提供，在 Linux 上每个终端接口都返回 403。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 $HALO_URL 和 $HALO_TOKEN 按快速上手设置；地址、鉴权和错误约定见 HTTP API 概览。

操作	端点
打开终端会话	POST /api/terminal/create
向终端会话发送按键	POST /api/terminal/input
关闭终端会话	POST /api/terminal/kill
列出打开的终端会话	GET /api/terminal/list
回读终端会话的缓冲输出	POST /api/terminal/replay
调整终端会话大小	POST /api/terminal/resize

打开终端会话

POST /api/terminal/create

• Opens a session with the platform's default shell in the workspace's working folder. Optional body fields: cwd (start folder) and title. The shell itself cannot be chosen.
• Live output arrives over the WebSocket as terminal:data events.

请求体

{
  "spaceId": "<spaceId>"
}

响应

{success:true,data:{id,title,shell,cwd,cols,rows,owner:"user",state:"running",…}} | {success:false,error}

示例

curl -sX POST "$HALO_URL/api/terminal/create" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>"}'

向终端会话发送按键

POST /api/terminal/input

• Writes raw keystrokes to the session; \r is Enter. Returns as soon as the input is written, before the command has produced output. Read the output from terminal:data events or POST /api/terminal/replay.
• The WebSocket message terminal-input does the same without an HTTP round trip per keystroke.

请求体

{
  "sessionId": "<sessionId>",
  "data": "ls\r"
}

响应

{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}

示例

curl -sX POST "$HALO_URL/api/terminal/input" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","data":"ls\r"}'

关闭终端会话

POST /api/terminal/kill

• Ends the shell process; anything still running in it stops. TERMINAL_NOT_FOUND means the session is already gone.

请求体

{
  "sessionId": "<sessionId>"
}

响应

{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}

示例

curl -sX POST "$HALO_URL/api/terminal/kill" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'

列出打开的终端会话

GET /api/terminal/list

• Lists the terminal sessions on this computer, including the ones Halo's assistant opened (owner: "ai"). aiTouched turns true once the assistant has used a session.

响应

{success:true,data:[{id,title,shell,cwd,cols,rows,owner:"ai"|"user",aiTouched,state:"running"|"exited",exitCode,lastActivityAt,createdAt,spaceId?}]}

示例

curl -s "$HALO_URL/api/terminal/list" \
  -H "Authorization: Bearer $HALO_TOKEN"

回读终端会话的缓冲输出

POST /api/terminal/replay

• Returns the session's info and its buffered output as raw terminal data, ANSI escape codes included, so a terminal view can redraw itself after connecting.

请求体

{
  "sessionId": "<sessionId>"
}

响应

{success:true,data:{info:{id,title,…},data:"<buffered output>"}} | {success:false,error,code:"TERMINAL_NOT_FOUND"}

示例

curl -sX POST "$HALO_URL/api/terminal/replay" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'

调整终端会话大小

POST /api/terminal/resize

• cols and rows must be positive integers.

请求体

{
  "sessionId": "<sessionId>",
  "cols": 120,
  "rows": 32
}

响应

{success:true} | {success:false,error,code?:"TERMINAL_NOT_FOUND"}

示例

curl -sX POST "$HALO_URL/api/terminal/resize" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","cols":120,"rows":32}'