会话回复与实时通道

Cloud 聊天把每条用户提问作为 session/prompt 运行时方法投递，并预先创建处于 streaming 状态的回复消息。harness 用补丁写入内容，最后把它标记为 completed、failed、refused 或 cancelled。

BoundRuntimeChatReply

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

向 Cloud 已为聊天提示创建、处于 streaming 状态的回复行写入内容。变更会排队逐个发送，并各带幂等键；终态方法会回读已保存的行，不一致则失败。

class BoundRuntimeChatReply
new BoundRuntimeChatReply(readonly input: { authority: RuntimeChatAuthorityPort; http: RuntimeChatHttpPort; binding: RuntimeChatRetainedBinding; now?: () => number; })

TypeScript · 构造

属性

initialize

读取回复行并记住其正文与消息片段（parts）。该行不处于 streaming 状态时拒绝。bindExistingRuntimeChatReply 会替你调用它。

async initialize(): Promise<void>

TypeScript · 参数

无参数。

返回值 Promise<void>

opened

以初始化时读到的回复行快照完成。

opened(): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

无参数。

返回值 Promise<RuntimeChatRetainedSnapshot>

flush

在所有排队的变更都已发送后完成。

flush(): Promise<void>

TypeScript · 参数

无参数。

返回值 Promise<void>

assertTerminalSnapshot

检查回复的最终行是否仍保持回复结束时的状态、正文、停止原因与消息片段，不一致则抛出错误。

assertTerminalSnapshot(row: RuntimeChatRetainedSnapshot): void

TypeScript · 参数

返回值 void

appendBody

向回复正文追加文本。变更会排队发送，并带上该文本起始处的字节偏移。

appendBody(chunk: string): void

TypeScript · 参数

返回值 void

setBody

用给定文本替换整个正文。

setBody(body: string): void

TypeScript · 参数

返回值 void

addPart

原样追加一个消息片段（例如工具调用）。

addPart(part: unknown): void

TypeScript · 参数

返回值 void

addToolResult

addPart 的别名，用于工具结果片段。

addToolResult(part: unknown): void

TypeScript · 参数

返回值 void

replacePart

替换给定下标处的消息片段。下标超出现有片段范围时抛出错误。

replacePart(index: number, part: unknown): void

TypeScript · 参数

返回值 void

finalize

把回复置为 completed 状态，回读该行并返回。已保存的行不一致时拒绝。

finalize(options?: { stopReason?: string }): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

返回值 Promise<RuntimeChatRetainedSnapshot>

fail

把回复置为 failed 状态（可同时替换正文），回读该行并返回。

fail(options?: { body?: string; stopReason?: string }): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

返回值 Promise<RuntimeChatRetainedSnapshot>

refuse

把回复置为 refused 状态，回读该行并返回。

refuse(options?: { stopReason?: string }): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

返回值 Promise<RuntimeChatRetainedSnapshot>

cancel

把回复置为 cancelled 状态，回读该行并返回。

cancel(options?: { stopReason?: string }): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

返回值 Promise<RuntimeChatRetainedSnapshot>

CentrifugeClientLike

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

SDK 所用到的 Centrifuge WebSocket 客户端的那一部分接口。想自带传输（例如测试中）时实现它。

interface CentrifugeClientLike

on

为客户端事件注册监听器：connected、connecting、disconnected、error 或 publication。

on(event: "publication", listener: (ctx: { data: unknown }) => void): void

TypeScript · 参数

返回值 void

connect

开始连接。

connect(): void

TypeScript · 参数

无参数。

返回值 void

disconnect

关闭连接。

disconnect(): void

TypeScript · 参数

无参数。

返回值 void

CentrifugeRealtimeFactory

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

创建实时客户端。默认工厂使用 centrifuge 包和 ws WebSocket。

interface CentrifugeRealtimeFactory

create

为给定 URL 和连接令牌创建客户端。

create(options: { url: string; token: string }): CentrifugeClientLike

TypeScript · 参数

返回值 CentrifugeClientLike

RuntimeChatAuthorityPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

为聊天客户端提供当前租约。把你的注册协调器适配成它即可。

interface RuntimeChatAuthorityPort

currentLease

返回含凭据的当前租约；没有时返回 null。

currentLease(): RuntimeChatLease | null

TypeScript · 参数

无参数。

返回值 RuntimeChatLease | null

subscribeLease

可选。注册监听器：租约变化时以新租约调用，租约丢失时以 null 调用。返回用于移除监听器的函数。

subscribeLease?( listener: (lease: RuntimeChatLease | null) => void, ): () => void

TypeScript · 参数

返回值 () => void

RuntimeChatClient

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

基于当前租约的聊天客户端：实时接收聊天消息、发送消息与回复、读取历史。用 createRuntimeChatClient 创建。

interface RuntimeChatClient

属性

history

读取你已知 ID 的会话的已保存历史的一页。没有列出实例下所有会话的调用，因此无法在这里发现未知的会话 ID。

history( conversationId: string, input?: RuntimeChatHistoryInput, ): Promise<RuntimeChatHistoryPage>

TypeScript · 参数

返回值 Promise<RuntimeChatHistoryPage>

syncConversation

用当前租约为 session/new 操作创建或更新会话并返回。会话所有者由该操作推导，请求体中不携带。

syncConversation( input: RuntimeNativeConversationSyncRequest, ): Promise<RuntimeNativeConversationSyncResponse>

TypeScript · 参数

返回值 Promise<RuntimeNativeConversationSyncResponse>

on

注册监听器。事件：message（收到聊天消息）、error、connection（连接状态变化）、disconnect（套接字关闭，带 code 与 reason）。返回客户端本身。

on( event: "disconnect", listener: (info: { code: number; reason: string }) => void, ): this

TypeScript · 参数

返回值 this

connect

用当前租约连接实时通道。断开后会带退避地重连，并在令牌或租约到期前续期会话。

connect(): Promise<void>

TypeScript · 参数

无参数。

返回值 Promise<void>

disconnect

关闭实时连接。

disconnect(): Promise<void>

TypeScript · 参数

无参数。

返回值 Promise<void>

dispose

关闭连接并移除所有监听器，之后不能再使用该客户端。

dispose(): void

TypeScript · 参数

无参数。

返回值 void

RuntimeChatHttpPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

聊天客户端所需的 HTTP 调用。createRuntimeChatHttpPort 以租约鉴权实现了它；想改变传输方式时可自行实现。

interface RuntimeChatHttpPort

getMessage

可选。以单个权威快照读取一条消息。bindExistingRuntimeChatReply 需要它。

getMessage?( lease: RuntimeChatLease, input: { conversationId: string; messageId: string }, ): Promise<RuntimeChatRetainedSnapshot>

TypeScript · 参数

返回值 Promise<RuntimeChatRetainedSnapshot>

personalToken

为租约申请实时连接令牌。应答包含令牌、实时端点 URL 和要订阅的频道。

personalToken(lease: RuntimeChatLease): Promise<{ token: string; realtimeUrl: string; channels: string[]; principalId?: string; expiresAt?: number; }>

TypeScript · 参数

返回值 Promise<{ token: string; realtimeUrl: string; channels: string[]; principalId?: string; expiresAt?: number; }>

getHistory

读取某个会话已保存历史的一页。

getHistory( lease: RuntimeChatLease, input: { conversationId: string } & RuntimeChatHistoryInput, ): Promise<RuntimeChatHistoryPage>

TypeScript · 参数

返回值 Promise<RuntimeChatHistoryPage>

syncConversation

为某个运行时操作创建或更新会话，并返回该会话。

syncConversation( lease: RuntimeChatLease, input: RuntimeNativeConversationSyncRequest, ): Promise<RuntimeNativeConversationSyncResponse>

TypeScript · 参数

返回值 Promise<RuntimeNativeConversationSyncResponse>

sendMessage

向会话发送一条消息。应答包含消息 ID，以及（如有）处理结果。

sendMessage( lease: RuntimeChatLease, input: { conversationId: string; id: string; type: string; content: unknown; replyTo?: string; }, ): Promise<{ messageId: string; outcome?: string }>

TypeScript · 参数

返回值 Promise<{ messageId: string; outcome?: string }>

openStream

创建一条处于 streaming 状态的消息，随后用 patchMessage 填充内容。

openStream( lease: RuntimeChatLease, input: { conversationId: string; id: string; type: string; content: unknown; replyTo?: string; }, ): Promise<{ messageId: string }>

TypeScript · 参数

返回值 Promise<{ messageId: string }>

patchMessage

修改正在流式写入的消息：替换或追加正文、替换消息片段，或设置最终的 state 与 stopReason。

patchMessage( lease: RuntimeChatLease, input: { conversationId: string; messageId: string; body?: string; bodyAppend?: string; bodyFrom?: number; parts?: readonly unknown[]; state?: string; stopReason?: string; operationKey?: string; }, ): Promise<void>

TypeScript · 参数

返回值 Promise<void>

RuntimeChatRealtimePort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

聊天客户端所需的实时传输。createCentrifugoRealtimePort 提供了实现。

interface RuntimeChatRealtimePort

open

打开实时连接，返回一个句柄，调用其 close() 结束连接。

open(input: { token: string; url: string; channel: string; onEvent(event: { type: string; data?: unknown }): void; onState(state: "connected" | "connecting" | "disconnected" | "failed"): void; onError(error: unknown): void; }): { close(): void }

TypeScript · 参数

返回值 { close(): void }

RuntimeChatReplyStream

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

一条可分段填充、最后以四种状态之一结束的回复。用 client.messages.startStream 创建。

interface RuntimeChatReplyStream

属性

opened

在回复消息创建完成后完成。

opened(): Promise<unknown>

TypeScript · 参数

无参数。

返回值 Promise<unknown>

flush

在所有排队的变更都已发送后完成。

flush(): Promise<void>

TypeScript · 参数

无参数。

返回值 Promise<void>

appendBody

向回复正文追加文本。

appendBody(chunk: string): void

TypeScript · 参数

返回值 void

setBody

用给定文本替换整个正文。

setBody(body: string): void

TypeScript · 参数

返回值 void

addToolResult

addPart 的别名，用于工具结果片段。

addToolResult(part: unknown): void

TypeScript · 参数

返回值 void

addPart

原样追加一个消息片段。

addPart(part: unknown): void

TypeScript · 参数

返回值 void

replacePart

替换给定下标处的消息片段。

replacePart(index: number, part: unknown): void

TypeScript · 参数

返回值 void

finalize

把回复置为 completed 状态。

finalize(options?: { stopReason?: string }): Promise<unknown>

TypeScript · 参数

返回值 Promise<unknown>

fail

把回复置为 failed 状态，可同时替换正文。

fail(options?: { body?: string; stopReason?: string }): Promise<unknown>

TypeScript · 参数

返回值 Promise<unknown>

refuse

把回复置为 refused 状态。

refuse(options?: { stopReason?: string }): Promise<unknown>

TypeScript · 参数

返回值 Promise<unknown>

cancel

把回复置为 cancelled 状态。

cancel(options?: { stopReason?: string }): Promise<unknown>

TypeScript · 参数

返回值 Promise<unknown>

RuntimeRealtimeSubscription

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

已打开的实时订阅的句柄。

interface RuntimeRealtimeSubscription

属性

close

关闭订阅。

close(): void

TypeScript · 参数

无参数。

返回值 void

bindExistingRuntimeChatReply

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

绑定到 Cloud 已创建、处于 streaming 状态的回复行，返回 BoundRuntimeChatReply。它自己从不创建或发送消息。

async function bindExistingRuntimeChatReply(input: { authority: RuntimeChatAuthorityPort; http: RuntimeChatHttpPort; binding: RuntimeChatRetainedBinding; now?: () => number; }): Promise<BoundRuntimeChatReply>

TypeScript · 参数

返回值 Promise<BoundRuntimeChatReply>

createCentrifugoRealtimePort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

基于 Centrifuge 创建 RuntimeChatRealtimePort。它只监听令牌所授予频道的推送，自己不会订阅。

function createCentrifugoRealtimePort(options: CentrifugeRealtimePortOptions = {}): RuntimeChatRealtimePort

TypeScript · 参数

返回值 RuntimeChatRealtimePort

createRuntimeChatClient

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

创建 RuntimeChatClient。调用 connect() 开始接收消息。

function createRuntimeChatClient(options: RuntimeChatClientOptions): RuntimeChatClient

TypeScript · 参数

返回值 RuntimeChatClient

createRuntimeChatHttpPort

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

创建 RuntimeChatHttpPort，每个请求都以租约凭据作为 Authorization: Bearer 发送。

function createRuntimeChatHttpPort(options: RuntimeChatHttpPortOptions): RuntimeChatHttpPort

TypeScript · 参数

返回值 RuntimeChatHttpPort

mintRuntimeRealtimeToken

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

为租约申请实时连接令牌及要订阅的频道。应答不完整时抛出 HarnessProtocolError。

async function mintRuntimeRealtimeToken(http: RuntimeLeaseHttp, credential: RuntimeLeaseCredential, signal?: AbortSignal): Promise<RuntimeRealtimeToken>

TypeScript · 参数

返回值 Promise<RuntimeRealtimeToken>

Python · 参数

返回值 RuntimeRealtimeToken

normalizeMessage

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

把原始消息对象转换为 RuntimeChatMessage：保留未知字段，并根据 snake_case 或其他别名补全驼峰字段 id、conversationId、type、content、senderId、replyTo 与 createdAt。值不是对象或没有 id 时返回 null。

function normalizeMessage(value: unknown): RuntimeChatMessage | null

TypeScript · 参数

返回值 RuntimeChatMessage | null

subscribeRuntimeRealtime

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

用租约申请实时令牌并打开实时连接。完成时返回一个持有令牌、可关闭订阅的句柄。

async function subscribeRuntimeRealtime(input: { origin: string; credential: RuntimeLeaseCredential; onEvent: (event: { type: string; data?: unknown }) => void; onState?: (state: "connecting" | "connected" | "disconnected" | "failed") => void; onError?: (error: unknown) => void; fetch?: typeof fetch; factory?: CentrifugeRealtimeFactory; signal?: AbortSignal; }): Promise<RuntimeRealtimeSubscription>

TypeScript · 参数

返回值 Promise<RuntimeRealtimeSubscription>

RUNTIME_CHAT_PATHS

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

聊天路由的路径，为字符串或函数。

const RUNTIME_CHAT_PATHS: Readonly<{ personalToken: string; conversations: string; conversationMessages: (conversationId: string) => string; conversationMessage: (conversationId: string, messageId: string) => string; }>

条目

RuntimeChatPreparedClearError

TypeScript @beeos-ai/cloud-harness-sdk · 仅 TypeScript

原始回复正在被清除时，HTTP 端口抛出该错误。回复随后停止写入并保留原始行；proof 用于标识这次清除。

class RuntimeChatPreparedClearError extends Error
new RuntimeChatPreparedClearError(readonly proof: RuntimeChatPreparedClearProof)

TypeScript · 构造

属性

错误与异常

本模块定义的错误类型。每个方法的说明会写明它在什么情况下抛出哪种错误。