深入解析 coze-studio/open-chatCoze 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-studiocoze-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/api1.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包括命令作用rushx build构建当前为占位脚本源码直接以 TS 形式被消费rushx lint运行 ESLint 静态检查rushx test运行 Vitest 测试--passWithNoTests允许无用例时通过rushx test:cov运行带覆盖率统计的测试快速上手两大核心组件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.tsinterface IBuilderChatProps { workflow: IWorkflow; // 工作流信息id、parameters、header project: IProject; // 项目信息见下表 spaceId?: string; eventCallbacks?: IEventCallbacks; userInfo?: OpenUserInfo; areaUi: { /* 聊天区 UI 配置 */ }; auth?: { type: external | internal; // external: 外部传入 tokeninternal: cookie 换 token token?: string; refreshToken?: () Promisestring | string; }; style?: React.CSSProperties; debug?: DebugProps; // cozeApiRequestHeader 调试请求头 }IProject的字段语义源码注释提炼字段说明id项目 ID必填typeapp或botmodedraft草稿|release发布|websdkWebSDK 发布|audit审核connectorId连接器 IDconversationName会话名project 类型必须填写conversationId会话 IDbot 类型必须填写sectionId分区 IDbot 类型必须填写iconUrl/defaultIconUrl/name/desc展示信息onBoarding开场白与建议问题prologue、displayAllSuggest、suggestionslayout布局Layout.PC/Layout.MOBILEBuilderChat通过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.tsinterface 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是嵌入场景的配置中枢字段说明typeChatType.BOT默认/ChatType.APPbot_idBot ID缺失时WebSdkChat直接返回null不渲染appInfo/botInfoApp 与 Bot 附加信息参数、版本等source来源标识OpenApiSource.WebSdk/ChatFlow/MiniProgram/MiniProgramV2auth鉴权配置见下文uiUI 配置base、chatBot、header、footer、conversationsconversation_id会话 ID由 OpenAPI 侧生成外部不可传入ui.chatBot支持完整的功能开关与文案配置源码中每个字段都标注了默认值字段默认值作用title—聊天框标题uploadable—是否允许上传文件isNeedClearContexttrue是否显示“清空上下文”按钮isNeedClearMessagetrue是否显示“删除消息”按钮isNeedAddNewConversation—是否显示“新增会话”按钮isNeedAudiotrue是否启用语音输入isNeedFunctionCallMessagetrue是否展示函数调用消息isNeedQuotefalse是否启用引用feedback—反馈面板isNeedFeedback、标题、占位符、标签width/el/onShow/onHide/onBeforeShow/onBeforeHide—仅影响聊天框外部框架弹窗容器行为此外ui.headerisShow、isNeedClose、extra、ui.footerisShow、expressionText如“由 {{name}} 提供”、linkvars链接变量、ui.conversationsisNeed分别控制头部、页脚与会话列表。ui.base提供icon、lang、layout、zIndex等基础外观。从 web-sdk/index.tsx 的实现可以看到两组默认行为的源码证据当chatConfig.auth.type token时强制isNeedClearMessage falseisNeedAddNewConversation默认trueisNeedClearContext默认true非 token 模式老版本兼容分支isNeedClearMessage true、isNeedAddNewConversation false、isNeedClearContext false若传入auth且未指定connectorId会自动补上webSdkDefaultConnectorId来自 util/connector.ts 的常量。鉴权配置鉴权类型定义在 client.tsenum AuthType { UNAUTH unauth, TOKEN token } interface AuthProps { type?: AuthType; token?: string; // 主动传入的 token onRefreshToken?: (token?: string) Promisestring | 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.tsBuilderChat及类型BuilderChatRef、IProject、IWorkflow、IBuilderChatPropsWebSdkChat错误工具isAuthError、OpenApiError、postErrorMessage、ChatSdkErrorType、ChatSDKErrorData类型入口导出src/exports/types.ts布局与聊天类型Layoutpc | mobile、ChatTypebot | app配置结构CozeChatConfig、AppInfo、BotInfo、UiProps、ComponentProps标记为deprecated后续弃用鉴权AuthType、AuthProps错误体系SDKErrorCode、ChatSdkError、WebSdkErroriframe 通信IframeMessageEvent、IframeParams其余PostMessageEvent、PostMessage、Language、ImagePreview、OnImageClick、OpenApiSource、OpenUserInfo、ContentType错误处理与 iframe 通信机制SDK 的错误体系集中在 util/error.ts可归纳为三层1. SDK 内部错误码SDKErrorCodeBase1000、OpenApiUpload1001、NoClearAPI1002、StoreProvider1003、Iframe2000、IframeParams2001、Core3000、NotError4000由ChatSdkError支持wrap包装原始错误与create快捷创建承载。2. OpenAPI 错误码OpenApiError枚举值含义ERROR_FORBIDDEN401禁止访问ERROR_INVALID_TOKEN4100无效 tokenERROR_TOKEN_FORBIDDEN4101token 被禁用ERROR_TOKEN_FAILED700012006token 获取失败BOT_NOT_PUBLISH4015Bot 未发布isAuthError(code)用于判断是否为上述鉴权类错误此外服务端还可能返回ServerErrorCode.BotUnbind702242003Bot 解绑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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考