BEEOS CLOUD / DEVELOPER REFERENCE

产品前端集成

通过产品后端与按用途授权的数据信道连接 Web 和移动应用

BeeOS Cloud 对外提供服务端 SDK 和 Harness SDK，不为 Web 或移动应用单独提供 Cloud 客户端 SDK。产品前端沿用自身技术栈和产品会话；产品后端负责用户认证、授权及 Cloud 操作。

区分业务命令与实时数据

前端需求	负责方与路径
创建或修改实例、智能体、会话、任务、文件，或调用运行时方法	前端请求产品后端；后端验证用户权限后调用服务端 SDK。
面向产品用户的状态、通知和消息更新	产品后端通过自己管理的用户实时通道发布事件，并按产品认证与 ACL 限定范围。
ACP、终端、Canvas/Yjs、查看器或文件传输	后端先授权特定用户与资源，再签发或获取短期描述符、预签名 URL；前端按声明的传输连接指定端点。

产品后端把已认证用户映射到应用内不透明的外部用户 ID，并在需要时用它限定 Cloud 操作。Cloud 可以保存该 ID 的会话与资源关联，但产品仍负责用户账号、ACL，以及决定谁能请求描述符。

前端凭产品会话请求自身后端。后端核对所请求智能体、会话、文件、文档或设备的所有权和 ACL。
业务命令由后端调用服务端 SDK 并返回产品响应；后续面向用户的事件通过产品自己的用户实时通道发布。
数据流由后端返回只包含该用途所需端点、传输、范围、凭证和到期时间的描述符。前端连接声明的 WebSocket、WebRTC、Yjs 或传输端点；到期时重新向后端请求描述符。

这些路径不能混同：ACP 或终端连接传输的是已授权实时数据，不赋予前端一般 Cloud 管理权限；Canvas 或查看器数据流也不是产品事件通道。各传输方式见数据信道，凭证边界见安全与所有权。

Important: 浏览器和移动端不得保存 bsk_ 服务端 Key 或智能体运行时 token。每个描述符和预签名 URL 都是短期 bearer 能力，不是通用产品登录凭证。