前端 SDK 快速开始

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow-sdk/src/sdk、chengflow-sdk/src/hooks/use-channel.ts、chengflow-sdk/package.json

网关 SDK（@chengflow/chat）用于把一个由 ChengOS 驱动的对话界面放进网页应用。它分三层，你按需选用：

请先阅读网关模型——下面的四个标识符只有对照它才讲得通。

配置

一切从一个配置对象开始：

import type { ChannelConfig } from "@chengflow/chat";

const config: ChannelConfig = {
  apiBaseUrl: "https://your-server.example.com/api/v1",
  wsBaseUrl: "wss://your-server.example.com/ws/executions",
  workspaceId: "<workspace-uuid>",   // 必填，始终显式指定
  channelId: "weather-app",          // 消息从哪来
  boundWorkflowId: "<workflow-uuid>",// 运行什么
  externalUserId: "user-123",        // 可选
};

workspaceId 是必填且会被校验的——空值会抛出 VALIDATION_ERROR，而不是静默使用默认值，因为错误的工作区意味着跨租户路由。

请让 channelId 与 boundWorkflowId 保持区分。前者标识应用，后者选择工作流。

最快的路径：组件

import { ChatProvider, ChatWindow } from "@chengflow/chat";

export function App() {
  return (
    <ChatProvider config={config}>
      <ChatWindow />
    </ChatProvider>
  );
}

这就是一个可用的对话界面，带流式输出、历史记录和审批卡片。

自定义界面：使用 Hook

import { useChannel } from "@chengflow/chat";

function Chat() {
  const {
    messages,
    sendMessage,
    isLoading,
    connectionStatus,
    streamingContent,
    supportsAttachments,
    error,
  } = useChannel(config);

  return (
    <div>
      <span>{connectionStatus}</span>
      {messages.map((m) => (
        <div key={m.id}>{m.content}</div>
      ))}
      {streamingContent && <div>{streamingContent}</div>}
      <button disabled={isLoading} onClick={() => sendMessage("你好")}>
        发送
      </button>
      {error && <p>{error.message}</p>}
    </div>
  );
}

useChannel 完成整个「发送—等待回复」的循环：创建乐观的本地消息、调用执行 API、订阅会话与执行两个 scope、消费 WebSocket 事件，并更新消息状态。

请把 streamingContent 与 messages 分开渲染。前者保存的是 token 仍在陆续到达时那段尚未完成的响应；轮次结束后，完整文本才会落入 messages。把两者当作同一个列表会导致文字闪烁或重复。

supportsAttachments 是一次能力探测：它报告绑定的工作流中是否真的包含 io/file_upload 节点。用它来显示或隐藏附件按钮，而不是提供一个工作流会丢弃的上传功能。

人工介入

三个回调处理需要人参与的场景：

如果你的工作流使用 utils/approver 或长时间运行的智能体，这些就不是可选功能——没有它们，一个请求决策的运行会无限期等待下去。

resetConversation() 开启一段全新对话，放弃当前历史。

不使用 React 的核心 SDK

import { ChannelClient, SessionManager, WsClient } from "@chengflow/chat";

const client = new ChannelClient(config);
const result = await client.execute(/* … */);

ChannelClient 还提供 resolveConversation、getConversationMessages、createMessage、submitApproval、resumeExecution、getExecution、getExecutionResult、workflowSupportsAttachments 和 bulkUpdateMemoryControls。

认证

浏览器只使用 JWT。默认由 BrowserAuthSession 提供令牌；向 ChannelClient 构造函数传入你自己的 AuthTokenProvider 即可对接既有认证系统。令牌过期会通过一个 auth-expired 通知暴露出来，便于你重新认证而不是静默失败。

不要在浏览器中使用 chk_ 渠道密钥——它们是给服务端适配器用的，会把长期有效的共享密钥放进客户端代码。参见认证。

WebSocket 行为

内置客户端已处理：指数退避加随机抖动的重连、PING/PONG 心跳、多 scope 订阅、重连后自动恢复订阅、最大重试次数限制，以及对 close code 的判断（使主动关闭不会像网络故障那样被重试）。这些你都不需要自己实现。

部署

Docker 部署通过 APP_API_BASE_URL、APP_WS_URL、APP_CHANNEL_ID、APP_BOUND_WORKFLOW_ID 和 PUBLIC_APP_URL 配置网关——参见环境变量参考。

下一步

• 网关模型——本 SDK 所实现的映射模型。
• WebSocket API——底层事件。