SDK 集成示例

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow-sdk/example/App.tsx、chengflow-sdk/src/components/index.ts、chengflow-sdk/src/components/ChatProvider.tsx、chengflow-sdk/src/hooks

四种集成形态，从「一个组件」到「完全不用框架」。按你想自己掌控多少界面来选。

1. 整个控制台，一个组件

随附的示例真正的代码只有九行：

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

const config = {
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL || "/api/v1",
  wsBaseUrl:  import.meta.env.VITE_WS_BASE_URL  || "/ws/executions",
  channelId:  import.meta.env.VITE_CHANNEL_ID   || "weather-app",
  boundWorkflowId: import.meta.env.VITE_BOUND_WORKFLOW_ID || "",
};

export default function App() {
  return <MultiChannelLayout config={config} loginTitle="Chengflow"
                             chatWindowProps={{ height: "100vh" }} />;
}

MultiChannelLayout 就是完整的浏览器网关：登录、工作区选择、渠道管理和对话——也就是网关模型描述的那条流程。当你要的是产品而不是组件库时，用它。

示例还会从 window 上读取一份运行时配置对象，读不到才回落到构建期环境变量。这个模式值得抄：它让同一份构建产物能通过在部署时写入一个小配置脚本来对接不同后端，而不必为每个环境重新构建。

2. 只要聊天窗口

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

<ChatProvider config={{
  apiBaseUrl: "https://api.example.com/api/v1",
  wsBaseUrl:  "wss://api.example.com/ws/executions",
  workspaceId: "…",
  channelId:  "weather-app",
  boundWorkflowId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}}>
  <ChatWindow />
</ChatProvider>

ChatProvider 运行 useChannel(config) 并把结果注入 context；ChatWindow 消费它。Provider 之下的任何组件都可以调 useChatContext()。

3. 用 hook 自己写界面

当聊天窗口需要长成你产品的样子时：

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

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

  return (
    <div>
      <StatusDot status={connectionStatus} />
      {messages.map(m => <MyBubble key={m.id} message={m} />)}
      {streamingContent && <MyBubble message={{ content: streamingContent }} streaming />}
      <MyInput onSend={sendMessage} disabled={isLoading}
               allowFiles={supportsAttachments} />
    </div>
  );
}

useChannel 还返回 submitApproval、continueAgentReview 和 submitContextMemoryReview。如果你的工作流里有审批门，你必须为它渲染点什么——否则执行会一直停在 waiting_for_review，用户没有任何办法回答。

supportsAttachments 是通过检查所绑定的工作流是否含有 io/file_upload 节点推导出来的，因此文件按钮只在上传确实有去处的地方出现。

4. 不用框架

核心类是纯 TypeScript：

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

const sessions = new SessionManager("weather-app");
const client   = new ChannelClient(config);
const ws       = new WsClient({ url: config.wsBaseUrl, tokenProvider: getToken });

ws.connect();

const sessionId = sessions.getOrCreateSessionId();
const { conversation_id, execution_id } =
  await client.execute("weather-app", workflowId, "今天天气怎么样？", sessionId);

sessions.setConversationId(conversation_id);
ws.send({ type: "SUBSCRIBE", scope: { type: "conversation", conversationId: conversation_id } });
if (execution_id) {
  ws.send({ type: "SUBSCRIBE", scope: { type: "execution", executionId: execution_id } });
}

注意那个 if (execution_id)：当消息没有触发工作流时，它会是 null。

配对外部平台

要让用户从你的界面接入自己的 Telegram bot 或 Slack app，SDK 为每个平台提供了配对表单和编辑面板——Telegram、WhatsApp、Slack、企业微信、钉钉——外加把它们放在一起呈现的 AppLinkPlatformModals。

不过通用路径比手挑表单更好：

const pattern = await management.getChannelAuthPattern(workspaceId, channelId);
// 依据 `pattern` 渲染字段
const result = await management.connectChannel(workspaceId, channelId, values);
if (result.state === "configuring") {
  // setup_data 里是 OAuth 跳转或二维码 → 之后调 completeConnect(...)
}

getChannelAuthPattern 返回该平台所需的字段，于是一套通用表单就能覆盖所有平台，新增适配器时前端不用改。各种认证模式的含义见即时通讯渠道。

搭一个管理控制台

import { ManagementClient, ChannelList, CreateChannelModal, AppShell } from "@chengflow/chat";

listChannels、createChannel、listWorkspaces 和 listPublishedWorkflows 足以支撑一个渠道管理界面。不想自己搭布局的话，AppShell 和 ChannelList 直接可用。

认证

LoginPage 和 ResetPasswordPage 可以直接用。示例通过读取 token 查询参数来路由 /reset-password：

if (window.location.pathname === "/reset-password") {
  const token = new URLSearchParams(window.location.search).get("token");
  return <ResetPasswordPage apiBaseUrl={config.apiBaseUrl} token={token} />;
}

如果你的应用已经自己处理认证，实现 AuthTokenProvider 并传给 ChannelClient，而不要用 BrowserAuthSession。

i18n

I18nProvider、useI18n 和 setLocale 从包根导出——不是从 components——所以请直接从 @chengflow/chat 引入。

怎么选

下一步

• SDK API 参考——每个类与方法。
• SDK 快速开始——从零到第一条消息。
• 渠道路由与会话映射——会话 id 到底意味着什么。