BEEOS CLOUD / DEVELOPER REFERENCE

画布中继与终端桥

画布中继与终端桥的 WebSocket 辅助工具。

两个客户端负责构造鉴权握手与帧，实际的 socket 可以注入。Yjs 负载字节和终端字节由 harness 自己处理。

CanvasRelayClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

负责中继升级、鉴权头以及加入/离开帧。Yjs 载荷字节由 harness 自行处理。

class CanvasRelayClient
new CanvasRelayClient(readonly options: CanvasRelayClientOptions)

TypeScript · 构造

参数	类型	必填	默认值	说明
`options`	CanvasRelayClientOptions	是		`relayUrl` 与 harness 的 `keys`，以及可选的 `agentId`、`token` 和 `socketFactory`（替换真实 WebSocket，例如用于测试）。

Python · 构造

参数	类型	必填	默认值	说明
`relay_url`	`str`	是		画布中继的 URL，与画布令牌一并返回。
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。
`agent_id`	`str \| None`	否	`None`	可选的智能体标识，作为 `agentId` 加入 URL。
`token`	`str \| None`	否	`None`	可选的画布令牌，作为 `token` 加入 URL。
`socket_factory`	Callable[[str, dict[str, str]], CanvasRelaySocket] \| None	否	`None`	可选函数 `(url, headers)`，用来代替真实 WebSocket 创建套接字，适合测试。

connect

用带签名的升级请求头打开 WebSocket。连接打开时完成，连接出错时拒绝。

connect(onMessage?: (data: Uint8Array | string) => void): Promise<void>

TypeScript · 参数

参数	类型	必填	默认值	说明
`onMessage`	`(data: Uint8Array \| string) => void`	否		每收到一帧就调用：文本帧为字符串，二进制帧为字节。

返回值 Promise<void>

Python · 参数

无参数。

返回值 None

join

发送加入某个画布的帧。未连接时抛出错误。

join(canvasId: string): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。

返回值 None

leave

发送离开某个画布的帧。未连接时抛出错误。

leave(canvasId: string): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。

返回值 None

sendBinary / send_binary

为某个画布发送二进制帧：一个字节的画布 ID 长度、画布 ID，然后是载荷。未连接时抛出错误。

sendBinary(canvasId: string, payload: Uint8Array): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。
`payload`	`Uint8Array`	是		跟在画布 ID 后面发送的字节。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。
`payload`	`bytes`	是		跟在画布 ID 后面发送的字节。

返回值 None

close

关闭套接字。

close(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

CanvasRelaySocket

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

画布中继客户端所用到的 WebSocket 接口的那一部分。想自带套接字（例如测试中）时实现它。

interface CanvasRelaySocket

send

发送文本或二进制帧。

send(data: string | Uint8Array): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`data`	`string \| Uint8Array`	是		帧内容。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`data`	`str \| bytes`	是		帧内容。

返回值 None

close

关闭套接字。

close(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

on

仅 TypeScript

为 open、message 或 error 事件注册监听器。

on(event: "error", listener: (error: Error) => void): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`event`	`"error"`	是		事件名：`open`、`message` 或 `error`。
`listener`	`(error: Error) => void`	是		以事件载荷调用的回调。

返回值 void

wait_open

仅 Python

等待套接字打开。

async def wait_open() -> None

Python · 参数

无参数。

返回值 None

TerminalBridgeClient

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

打开 GET /agent 并发送与租约绑定的 agent_auth 帧。之后的帧是原始终端字节。

class TerminalBridgeClient
new TerminalBridgeClient(readonly options: TerminalBridgeClientOptions)

TypeScript · 构造

参数	类型	必填	默认值	说明
`options`	TerminalBridgeClientOptions	是		`bridgeUrl`、harness 的 `keys` 与运行时 `lease`，以及可选的 `now`、`nonce`、`authTimeoutMs`（默认 10000）和 `socketFactory`。

Python · 构造

参数	类型	必填	默认值	说明
`bridge_url`	`str`	是		终端桥接的 `ws` 或 `wss` URL。
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。
`lease`	TerminalAuthLease	是		鉴权帧所绑定的运行时租约。
`now`	`Callable[[], float] \| None`	否	`None`	可选的返回当前时间的时钟，测试时可替换。
`nonce`	`Callable[[], str] \| None`	否	`None`	可选的随机数（nonce）生成函数，测试时可替换。
`socket_factory`	Callable[[str], TerminalSocket] \| None	否	`None`	可选函数，按 URL 创建套接字，用来代替真实 WebSocket，适合测试。

connect

打开套接字，发送 agent_auth 帧并等待 auth_ok。返回所发送的帧；应答为其他内容或超时未到达时失败。

async connect(): Promise<TerminalAgentAuthFrame>

TypeScript · 参数

无参数。

返回值 Promise<TerminalAgentAuthFrame>

Python · 参数

无参数。

返回值 dict[str, Any]

send

发送终端数据。未连接时抛出错误。

send(data: string): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`data`	`string`	是		要发送的终端数据。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`data`	`str`	是		要发送的终端数据。

返回值 None

close

关闭套接字。

close(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

TerminalSocket

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

终端桥接客户端所用到的 WebSocket 接口的那一部分。想自带套接字（例如测试中）时实现它。

interface TerminalSocket

send

发送文本帧。

send(data: string): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`data`	`string`	是		帧内容。

返回值 void

Python · 参数

参数	类型	必填	默认值	说明
`data`	`str`	是		帧内容。

返回值 None

close

关闭套接字。

close(): void

TypeScript · 参数

无参数。

返回值 void

Python · 参数

无参数。

返回值 None

on

仅 TypeScript

为 message 或 error 事件注册监听器。

on(event: "error", listener: (error: Error) => void): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`event`	`"error"`	是		事件名：`message` 或 `error`。
`listener`	`(error: Error) => void`	是		以事件载荷调用的回调。

返回值 void

once

仅 TypeScript

为 open 事件注册只调用一次的监听器。

once(event: "open", listener: () => void): void

TypeScript · 参数

参数	类型	必填	默认值	说明
`event`	`"open"`	是		事件名：`open`。
`listener`	`() => void`	是		套接字打开时调用的回调。

返回值 void

wait_open

仅 Python

等待套接字打开。

async def wait_open() -> None

Python · 参数

无参数。

返回值 None

recv

仅 Python

等待下一个文本帧并返回。

async def recv() -> str

Python · 参数

无参数。

返回值 str

canvasRelayJoinFrame

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

返回加入某个画布的文本帧：{"type":"join","canvasId":...}。

function canvasRelayJoinFrame(canvasId: string): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。

返回值 string

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。

返回值 str

canvasRelayLeaveFrame

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

返回离开某个画布的文本帧：{"type":"leave","canvasId":...}。

function canvasRelayLeaveFrame(canvasId: string): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。

返回值 string

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。

返回值 str

canvasRelayUpgradeHeaders

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

为中继 WebSocket 升级（GET /ws/agent）构造带签名的 X-Agent-* 头。

function canvasRelayUpgradeHeaders(keys: AgentKeyPair): Record<string, string>

TypeScript · 参数

参数	类型	必填	默认值	说明
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。

返回值 Record<string, string>

Python · 参数

参数	类型	必填	默认值	说明
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。

返回值 dict[str, str]

canvasRelayWebSocketUrl

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

{relay}/ws/agent。已有的路径前缀会保留。绝不是 /ws/{canvasId}。

function canvasRelayWebSocketUrl(relayUrl: string, options: { agentId?: string; token?: string } = {}): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`relayUrl`	`string`	是		画布中继的 URL。`http(s)` 会变成 `ws(s)`；缺少协议时按 `wss` 处理。
`options`	`{ agentId?: string; token?: string }`	否	`{}`	可选的 `agentId` 与 `token`，会作为查询参数加入 URL。

返回值 string

Python · 参数

参数	类型	必填	默认值	说明
`relay_url`	`str`	是		画布中继的 URL。`http(s)` 会变成 `ws(s)`；缺少协议时按 `wss` 处理。
`agent_id`	`str \| None`	否	`None`	可选的智能体标识，作为查询参数 `agentId` 加入。
`token`	`str \| None`	否	`None`	可选的画布令牌，作为查询参数 `token` 加入。

返回值 str

createTerminalAgentAuth

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

构造并签署终端桥接的 agent_auth 帧。租约不完整、epoch 不是正整数字符串或公钥不是 32 字节时抛出错误。

function createTerminalAgentAuth(input: { lease: TerminalAuthLease; keys: AgentKeyPair; timestamp?: number; nonce?: string; }): TerminalAgentAuthFrame

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	{ lease: TerminalAuthLease; keys: AgentKeyPair; timestamp?: number; nonce?: string; }	是		运行时 `lease`、harness 的 `keys`，以及可选的 Unix 秒级 `timestamp` 与 `nonce`。

返回值 TerminalAgentAuthFrame

Python · 参数

参数	类型	必填	默认值	说明
`lease`	TerminalAuthLease	是		该帧所绑定的运行时租约。
`keys`	AgentKeyPair	是		为请求签名的 harness 密钥对。
`timestamp`	`int \| None`	否	`None`	Unix 秒级时间，默认为当前时间。
`nonce`	`str \| None`	否	`None`	随机数（nonce），默认是随机 UUID。

返回值 dict[str, Any]

encodeCanvasRelayBinary

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

构造二进制中继帧：一个字节的画布 ID 长度、画布 ID，然后是载荷。画布 ID 长度必须为 1 到 255 字节。

function encodeCanvasRelayBinary(canvasId: string, payload: Uint8Array): Uint8Array

TypeScript · 参数

参数	类型	必填	默认值	说明
`canvasId`	`string`	是		画布的标识。
`payload`	`Uint8Array`	是		跟在画布 ID 后面发送的字节。

返回值 Uint8Array

Python · 参数

参数	类型	必填	默认值	说明
`canvas_id`	`str`	是		画布的标识。
`payload`	`bytes`	是		跟在画布 ID 后面发送的字节。

返回值 bytes

terminalAgentAuthSigningMessage

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

UTF-8 签名原文。其中不包含 instance_id。

function terminalAgentAuthSigningMessage(input: { publicKey: string; timestamp: number; nonce: string; runtimeLeaseCredential: string; handlerIdentity: string; runtimeEpoch: string; leaseId: string; }): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`input`	`{ publicKey: string; timestamp: number; nonce: string; runtimeLeaseCredential: string; handlerIdentity: string; runtimeEpoch: string; leaseId: string; }`	是		参与签名的字段：`publicKey`、`timestamp`、`nonce`，以及租约字段 `runtimeLeaseCredential`、`handlerIdentity`、`runtimeEpoch` 和 `leaseId`。

返回值 string

Python · 参数

参数	类型	必填	说明
`public_key`	`str`	是	harness 的 base64 公钥。
`timestamp`	`int`	是	Unix 秒级时间。
`nonce`	`str`	是	该帧的随机数（nonce）。
`runtime_lease_credential`	`str`	是	运行时租约的租约凭据。
`handler_identity`	`str`	是	运行时租约的处理方身份。
`runtime_epoch`	`str`	是	租约的运行时 epoch。
`lease_id`	`str`	是	租约的标识。

返回值 str

terminalAgentWebSocketUrl

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.terminal

返回终端桥接的 WebSocket URL，即在桥接 URL 后追加 /agent。协议不是 ws 或 wss 时抛出错误。

function terminalAgentWebSocketUrl(bridgeUrl: string): string

TypeScript · 参数

参数	类型	必填	默认值	说明
`bridgeUrl`	`string`	是		终端桥接的 `ws` 或 `wss` URL。

返回值 string

Python · 参数

参数	类型	必填	默认值	说明
`bridge_url`	`str`	是		终端桥接的 `ws` 或 `wss` URL。

返回值 str

CANVAS_RELAY_PATH

TypeScript @beeos-ai/cloud-harness-sdk · Python beeos_cloud_harness_sdk.canvas_relay

中继 WebSocket 的路径：/ws/agent。

const CANVAS_RELAY_PATH: "/ws/agent" = "/ws/agent"

BeeOS Cloud返回文档首页