企业官网建设流程全解析

深入解析 @coze-studio/open-chat：Coze Studio 的 Web ChatApp SDK 组件与配置实战指南

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio

@coze-studio/open-chat是 Coze Studio 开源仓库中面向聊天与通信场景的 Web ChatApp SDK，它为 AI Agent 的“构建期预览”和“发布期嵌入”提供了两套可复用的 React 聊天组件。本文将基于该包的 README 并结合仓库源码，完整讲解包的安装接入、BuilderChat与WebSdkChat两大组件的 Props 配置、导出 API、鉴权与错误处理机制，读完即可在 Coze Studio 二次开发或自研 Agent 平台中直接落地使用。

包概述：open-chat 在 Coze Studio 中的定位

根据包 README 的说明，@coze-studio/open-chat是 Coze Studio monorepo 的一部分，提供 chat（聊天）与 communication（通信）能力，核心产物是一批可嵌入的聊天组件。从目录结构看，它位于frontend/packages/studio/open-platform/open-chat，与chat-app-sdk（聊天挂件应用 SDK）、open-auth（开放平台鉴权）、open-env-adapter（环境适配）同属 open-platform 开放平台包族。

包元信息记录在 package.json 中：

• 名称@coze-studio/open-chat，版本0.0.1，描述为 “Coze Web ChatApp SDK”；
• 基于 React 18、TypeScript 构建，测试框架为 Vitest，代码规范为 ESLint；
• 提供三条导出子路径：.（主入口）、./types（类型入口）、./envs（环境工具入口）；
• 依赖了@coze-common/chat-core、@coze-common/chat-area、@coze-common/chat-uikit等聊天领域包，以及官方 OpenAPI 客户端@coze/api（1.3.5）。

在源码层面，包的对外出口由 src/index.ts 定义，只有三条主干：构建器聊天组件BuilderChat、Web SDK 聊天组件WebSdkChat，以及错误相关的工具函数与枚举。

安装与工程接入（Getting Started）

该包通过 Rush monorepo 的 workspace 协议引入，与 Coze Studio 前端其余包保持一致。按 README 的安装指引，先在package.json中添加依赖：

{ "dependencies": { "@coze-studio/open-chat": "workspace:*" } }

然后执行 Rush 的依赖更新命令：

rush update

执行后即可在 TypeScript 代码中导入组件。包内自带的工程脚本（见 package.json）包括：

快速上手：两大核心组件

README 的 API Reference 中提到BuilderChat、ChatType、RawMessageType、Layout等导出。需要说明的是，以当前仓库源码为准，权威的导出清单在 src/index.ts 与 src/exports/types.ts 中；README 中列出的RawMessageType在当前源码中并未找到对应定义（疑似遗留占位），实际组件与类型以源码导出为准。

BuilderChat：构建器内置聊天组件

BuilderChat实际指向 coze-chat.tsx 中的BuilderChatWeb（见 index.tsx），用于在 Agent 构建器（Builder）内渲染聊天区域，支持在“草稿 / 发布 / WebSDK 发布 / 审核”等模式下预览和调试 Agent。

其核心 Props 定义在 type.ts：

interface IBuilderChatProps { workflow: IWorkflow; // 工作流信息：id、parameters、header project: IProject; // 项目信息（见下表） spaceId?: string; eventCallbacks?: IEventCallbacks; userInfo?: OpenUserInfo; areaUi: { /* 聊天区 UI 配置 */ }; auth?: { type: 'external' | 'internal'; // external: 外部传入 token；internal: cookie 换 token token?: string; refreshToken?: () => Promise<string> | string; }; style?: React.CSSProperties; debug?: DebugProps; // cozeApiRequestHeader 调试请求头 }

IProject的字段语义（源码注释提炼）：

BuilderChat通过forwardRef暴露BuilderChatRef命令式句柄，父组件可直接驱动聊天区：

export interface BuilderChatRef { sendMessage: (message: MessageType) => void; // 注入文本/图片/文件消息 clearContext: () => void; // 清空上下文 }

MessageType支持三种内容：{ type: ContentType.Text, text }、{ type: ContentType.Image, value }、{ type: ContentType.File, value }。

WebSdkChat：外部网页嵌入聊天组件

WebSdkChat（见 web-sdk/index.tsx）用于把已发布的 Bot 聊天能力嵌入任意第三方网页，Props 定义在 props.ts：

interface WebSdkChatProps { title: string; // 标题 icon?: string; // 左上角图标 URL headerExtra?: ReactNode; // 头部右侧插槽 layout?: Layout; // 'pc' | 'mobile' useInIframe?: boolean; // 是否运行在 iframe 中（影响样式与通信） chatConfig: CozeChatConfig; // 核心配置（见下文） userInfo?: OpenUserInfo; onImageClick?: (data) => void; onThemeChange?: (theme: 'bg-theme' | 'light') => void; }

其中CozeChatConfig定义在 client.ts，是嵌入场景的配置中枢：

ui.chatBot支持完整的功能开关与文案配置，源码中每个字段都标注了默认值：

此外ui.header（isShow、isNeedClose、extra）、ui.footer（isShow、expressionText如“由 {{name}} 提供”、linkvars链接变量）、ui.conversations（isNeed）分别控制头部、页脚与会话列表。ui.base提供icon、lang、layout、zIndex等基础外观。

从 web-sdk/index.tsx 的实现可以看到两组默认行为的源码证据：

• 当chatConfig.auth.type === 'token'时：强制isNeedClearMessage = false，isNeedAddNewConversation默认true，isNeedClearContext默认true；
• 非 token 模式（老版本兼容分支）：isNeedClearMessage = true、isNeedAddNewConversation = false、isNeedClearContext = false；
• 若传入auth且未指定connectorId，会自动补上webSdkDefaultConnectorId（来自 util/connector.ts 的常量）。

鉴权配置

鉴权类型定义在 client.ts：

enum AuthType { UNAUTH = 'unauth', TOKEN = 'token' } interface AuthProps { type?: AuthType; token?: string; // 主动传入的 token onRefreshToken?: (token?: string) => Promise<string> | string; // token 过期时回调刷新 connectorId?: string; }

即“无需鉴权”与“token 鉴权”两种模式；token 模式下既可以直接传入静态 token，也可以通过onRefreshToken在过期时动态获取新 token，适配第三方网站的多实例、动态凭证场景。

组合使用示例

一个典型的外部嵌入用法（基于上述真实类型，可直接替换进业务代码）：

import { WebSdkChat, ChatType, Layout, AuthType } from '@coze-studio/open-chat'; <WebSdkChat title="我的智能助手" layout={Layout.PC} useInIframe={true} chatConfig={{ type: ChatType.BOT, bot_id: 'your_bot_id', source: 'web_sdk', auth: { type: AuthType.TOKEN, onRefreshToken: async () => (await fetch('/api/token')).json().token, }, ui: { chatBot: { isNeedAudio: false, isNeedQuote: true }, conversations: { isNeed: true }, }, }} />;

API Reference：完整导出清单

主入口导出（src/index.ts）

• BuilderChat及类型BuilderChatRef、IProject、IWorkflow、IBuilderChatProps
• WebSdkChat
• 错误工具：isAuthError、OpenApiError、postErrorMessage、ChatSdkErrorType、ChatSDKErrorData

类型入口导出（src/exports/types.ts）

• 布局与聊天类型：Layout（'pc' | 'mobile'）、ChatType（'bot' | 'app'）
• 配置结构：CozeChatConfig、AppInfo、BotInfo、UiProps、ComponentProps（标记为@deprecated，后续弃用）
• 鉴权：AuthType、AuthProps
• 错误体系：SDKErrorCode、ChatSdkError、WebSdkError
• iframe 通信：IframeMessageEvent、IframeParams
• 其余：PostMessageEvent、PostMessage、Language、ImagePreview、OnImageClick、OpenApiSource、OpenUserInfo、ContentType

错误处理与 iframe 通信机制

SDK 的错误体系集中在 util/error.ts，可归纳为三层：

1. SDK 内部错误码SDKErrorCode：Base=1000、OpenApiUpload=1001、NoClearAPI=1002、StoreProvider=1003、Iframe=2000、IframeParams=2001、Core=3000、NotError=4000，由ChatSdkError（支持wrap包装原始错误与create快捷创建）承载。

2. OpenAPI 错误码OpenApiError：

isAuthError(code)用于判断是否为上述鉴权类错误；此外服务端还可能返回ServerErrorCode.BotUnbind=702242003（Bot 解绑），SDK 会将其翻译为 i18n 提示文案。

3. 错误上报通信：postErrorMessage(data)通过window.parent.postMessage向宿主页面广播type: 'chat-sdk-error'的ChatSDKErrorData（含INVALID_BOT_ID/OPEN_API_ERROR类型），方便外层页面捕获并展示兜底 UI。

与之配套，iframe 场景下宿主与 SDK 通过IframeMessageEvent枚举通信：GET_IFRAME_PARAMS、GET_NEW_TOKEN、THEME_CHANGE；通信载荷IframeParams包含chatClientId（多实例区分消息来源的前缀）、chatConfig与userInfo。

开发与测试（Development）

包内工程以 TypeScript + React 为主，测试用 Vitest，代码质量用 ESLint。仓库中已有的测试示例包括：

• client/tests/index.test.tsx 与store/__tests__/setter.test.ts覆盖客户端初始化与 store 状态设置逻辑；
• components/studio-open-chat/hooks/__test__/user-info.test.tsx覆盖用户信息 Hook。

开发者可直接运行rushx test复现这些用例。同时，该包大量复用@coze-common/chat-core、@coze-common/chat-area的聊天能力，通过provider/coz-sdk/api-adapter将 Coze OpenAPI 的消息协议与聊天内核消息模型互相转换，这也是“一次开发、构建器与 Web SDK 双场景复用”的架构基础。

小结

@coze-studio/open-chat是 Coze Studio 面向聊天场景的“Web ChatApp SDK”核心包：BuilderChat服务构建期（草稿、发布、审核），WebSdkChat服务发布期嵌入，配合统一的CozeChatConfig配置体系、双层错误码与 iframe 通信机制，为 Agent 平台的聊天能力复用提供了完整闭环。开发者可基于本仓库的 README、src/index.ts 与 src/types/client.ts 快速接入并二次扩展。

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio