简介面向具备JavaScript基础与异步编程经验的前端或全栈开发者的技术文档聚焦Coze扣子API的聊天机器人封装实践。围绕单例模式保证全局唯一实例梳理会话创建与状态维护、流式聊天与轮询两种消息交互模式的实现差异并给出等待响应完成、提取最终回复等辅助方法及错误处理、旧代码兼容的设计思路可帮助读者在Web应用中快速接入智能对话能力支持多用户会话与个性化对话。文档按初始化、创建会话、发送消息、获取最终回复的顺序拆解代码结构并对流式与轮询的适用场景做了区分。资源共1个文件为docx文档压缩包约18KB篇幅精简便于按需查阅与对照编码。已有126人学习适合工作1至3年、需要集成智能对话功能并希望理解封装与异步控制要点的研发人员参考。1. 从裸写 fetch 到 Coze 封装类这套工具到底解决什么问题Coze 的开放接口本身不复杂难的是它有三层状态会话、chat、消息列表。第一次接的人通常这么写——发一条消息等一个 JSON把 content 打印出来。能跑通但用户问第二句时机器人就失忆了因为每次请求都在建新会话。这个 Coze 类要解决的就是这件事把 bot 凭证、用户到会话的映射、流式与轮询两条返回链路收进一个实例调用侧只写一行coze.ChatCozeV3(conversationId, userId, query)。它适合有 JavaScript 异步基础、要在 Web 应用里嵌对话能力的开发者也适合需要同时支撑「逐字出字」和「等完整答案」两种前端交互的团队。下面按初始化、会话、双模式实现、兼容层四条线拆开看。2. 单例模式下的 Coze 初始化BOT_ID、API_KEY 与 API_URL 的边界2.1 单例带来的真实收益与静默副作用把实例做成单例收益是很实在的conversation字典在进程内共享同一个用户不会因为模块被 import 两次而各建一份会话配置也只读一次环境变量不用在每个 handler 里重复传 BOT_ID 和 API_KEY。但原实现是这么写的构造函数里if (Coze.instance) return Coze.instance;然后Coze.instance this;。这段代码有个不报错的坑——第二次new Coze(B_BOT_ID, B_KEY)会直接返回 A 的实例新传进来的参数被丢掉。结果是 B 业务的请求打到了 A 的机器人上鉴权用的是 A 的 key日志里还看不出任何异常。多租户或者一个后端要服务多个 bot 时这是最典型的串号。同理static API_URL写死成https://api.coze.cn/v3/chat意味着想灰度到新路径、或者本地想指向 mock 服务都得改源码。字段作用单例下的风险建议BOT_ID指定机器人被首个实例锁死多 bot 串号作为实例指纹参与缓存键API_KEY鉴权凭证同上且易被硬编码进前端产物只存服务端环境变量conversationuser 到会话 id 的映射无界增长内存泄漏换 Map 或外部存储带 TTLAPI_URL接口基址无法灰度、无法 mock构造参数注入2.2 用指纹键替代单一 instance改法不难把「全局唯一」换成「按 bot 唯一」。同一份代码里既能保证复用又能让不同 bot 各自独立。// 以 botId 为指纹缓存实例替代全局唯一的 instance const registry new Map(); class Coze { constructor(botId, apiKey, options {}) { const key ${botId}; // 指纹同 bot 复用不同 bot 隔离 if (registry.has(key)) return registry.get(key); this.botId botId; this.apiKey apiKey; this.baseUrl options.baseUrl || https://api.coze.cn/v3/chat; this.conversations new Map(); // 用 Map 代替普通对象避免原型链污染 this.timeout options.timeout ?? 60000; registry.set(key, this); } static reset() { registry.clear(); } // 测试用清空注册表避免用例互相污染 }参数说明botId是唯一键不把 apiKey 混进 key否则密钥轮换后旧实例会残留options.baseUrl让基址可注入本地联调时指向 mockthis.timeout为后续 AbortController 留口子static reset()只给单测用生产代码不要调用。如果团队里已经有成熟的依赖注入容器更干净的做法是彻底去掉单例应用启动时 new 一次然后注入到各个 handler这样实例的生命周期由容器管而不是由 class 自己偷偷管。2.3 密钥不能出现在浏览器端只要封装的调用点在浏览器里API_KEY 就一定会出现在 Network 面板和打包产物里。常见做法是 Node/BFF 层持有密钥前端只调自己的/api/chat路由路由再转发到 Coze。# .env只加载在服务端进程 COZE_BOT_ID7xxxxxxxxxxxxxxxxx COZE_API_KEYpat_xxxxxxxxxxxxxxxx COZE_BASE_URLhttps://api.coze.cn/v3/chat// Node 侧读取这两个值绝不下发到前端 const coze new Coze(process.env.COZE_BOT_ID, process.env.COZE_API_KEY, { baseUrl: process.env.COZE_BASE_URL, });把基址也放进环境变量是为了在没有代码改动的前提下切换环境或指向本地桩服务。这一条在联调阶段能省掉大量「改一行代码、重启一次服务」的时间。3. 会话管理链路CreateConversation 的请求体与 conversation_id 复用3.1 建会话的字段与返回结构建会话接口是POST /v1/conversation/create字段不多但每一个都有实际影响。字段类型说明建议值bot_idstring机器人 ID决定用哪个 bot 建会话必填user_idstring会话归属标识用业务侧稳定 ID别用随机串streamboolean建会话阶段是否流式falseauto_save_historyboolean是否保存历史消息true否则 retrieve 拿不到上下文additional_messagesarray随会话带入的消息建会话时留空数组async createConversation(userId) { const resp await fetch(https://api.coze.cn/v1/conversation/create, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, stream: false, auto_save_history: true, additional_messages: [], }), }); const data await resp.json(); if (data.code ! 0) { // 抛出去不要 catch 后 return throw new Error(create conversation failed: ${data.code} ${data.msg}); } return data.data.id; // 这个 id 就是后续所有请求要带的 conversation_id }逻辑说明user_id用业务侧的用户主键不要用时间戳或 UUID 临时生成否则同一用户每次都是新会话历史全断。auto_save_history设 false 时message/list接口会返回空列表很多人第一次接都栽在这。原实现里catch之后return 这让调用方完全无法区分「建会话失败」和「这是一个新用户」最终表现是用户提问后收到一句空回复日志里只有一行 console.error。失败就抛让上层决定重试还是返回兜底话术。3.2 conversation_id 该存在哪this.conversation[user]这种进程内字典在单机 demo 上够用上生产有三个问题进程重启即丢多副本部署时请求打到哪个 Pod 就取哪份映射同一用户会来回切会话object 的 key 永远不会被回收。存储适用场景过期策略注意点进程内 Map单机 demo、本地调试手动清理重启即丢Redis多副本 Node 服务TTL 7 天并续期key 加 botId 前缀防串号MySQL / Postgres需审计、回放对话按业务归档每次对话多一次查询const Redis require(ioredis); const redis new Redis(process.env.REDIS_URL); // 前缀带上 botId多机器人共存时不会互相覆盖 const convKey (botId, userId) coze:conv:${botId}:${userId}; async function getOrCreateConversation(coze, botId, userId) { const cached await redis.get(convKey(botId, userId)); if (cached) return cached; const convId await coze.createConversation(userId); // TTL 和服务端会话有效期对齐避免拿到已被清理的 id await redis.set(convKey(botId, userId), convId, EX, 60 * 60 * 24 * 7); return convId; }参数说明EX 604800是 7 天按业务对话的活跃周期调如果产品允许用户「开启新对话」就把删除 key 当作开新会话的动作而不是去调一次删除会话的接口。3.3 让 ChatCozeV3 把会话 id 回传给调用方原方法返回的是字符串。调用方拿不到conversation_id下一轮只能继续传于是每轮都是新会话——这正是「机器人失忆」的直接原因。改成返回结构体让调用方自己决定怎么持久化return { conversationId, content, mode: stream };顺带一提_streamChat里对传入的messages数组做了messages.push(message)。如果调用方复用同一个数组比如在会话级别的上下文里每轮都会把历史再塞一遍additional_messages会线性膨胀。正确做法是每次请求构造新数组历史交给服务端的auto_save_history管。4. 流式与轮询双模式实现SSE 分片解析与 retrieve 状态轮询4.1 流式返回的帧结构Coze 的流式响应是标准 SSE一帧由若干行组成event:行给事件类型data:行给 JSON 载荷帧与帧之间用空行分隔。真正需要处理的事件只有几个。事件名含义处理方式conversation.message.delta增量文本片段取 payload.content 追加conversation.message.completed单条消息生成结束可忽略或记录耗时conversation.chat.completed整轮对话完成结束读取conversation.chat.failed生成失败抛异常带上 payload.msg[DONE]流结束标记直接 return 已累积内容只认delta事件是关键。completed事件里也带 content但那是整段文本重复累加会让回答翻倍。4.2 分片断行为什么不能对单个 chunk 直接 splitfetch的reader.read()返回的是字节流分片切分点由网络决定可能落在任何位置——包括一行的中间、一个 UTF-8 汉字的三字节中间。原代码chunk.split(\n)后按行找data:一旦某帧的 data 行落在下一个 chunk这段内容就被静默丢掉前端表现为「回答缺字」。正确做法是用 buffer 累积以空行为帧边界切分。async _streamChat(conversationId, userId, query) { const url ${this.baseUrl}?conversation_id${conversationId}; const resp await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, additional_messages: [{ role: user, content: query, content_type: text }], stream: true, auto_save_history: true, }), }); const reader resp.body.getReader(); const decoder new TextDecoder(); let buffer ; // 跨 chunk 累积不能对单个 chunk 直接 split let answer ; while (true) { const { done, value } await reader.read(); if (done) break; // stream:true 让解码器保留半个多字节字符避免汉字被截断成乱码 buffer decoder.decode(value, { stream: true }); let idx; while ((idx buffer.indexOf(\n\n)) ! -1) { const frame buffer.slice(0, idx); buffer buffer.slice(idx 2); // 消费掉这一帧剩下的留给下次 let eventName ; for (const line of frame.split(\n)) { const text line.trim(); if (!text) continue; if (text.startsWith(event:)) { eventName text.slice(6).trim(); } else if (text.startsWith(data:)) { const payload text.slice(5).trim(); if (payload [DONE]) return answer; if (eventName ! conversation.message.delta) continue; // 关键只认增量事件 try { const json JSON.parse(payload); if (json.content) answer json.content; } catch (e) { // 正常不该走到这里出现即说明帧边界判断有问题 console.warn(bad frame:, payload.slice(0, 80)); } } } } } return answer; }参数说明buffer保留未成帧的尾部decoder.decode(value, { stream: true })的第二个参数是重点漏掉它中文会随机出现「」eventName每帧重新初始化不能提到循环外[DONE]用return而不是break因为break只跳出内层 for外层 while 还会继续读。4.3 轮询链路的四步状态机轮询模式是「发起 → 轮询状态 → 拉消息列表」三步链路更长但更好调试。async _pollingChat(conversationId, userId, query) { // 步骤 1非流式发起拿到 chat_id const resp await fetch(this.baseUrl, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, additional_messages: [{ role: user, content: query, content_type: text }], stream: false, auto_save_history: true, conversation_id: conversationId, }), }); const data await resp.json(); if (data.code ! 0) throw new Error(${data.code} ${data.msg}); const chatId data.data.id; // chat 维度 id和 conversation_id 不是一回事 const convId data.data.conversation_id; await this._waitForCompletion(chatId, convId); // 步骤 2 return this._getFinalResponse(chatId, convId); // 步骤 3 } async _waitForCompletion(chatId, conversationId, maxRetries 20) { for (let i 0; i maxRetries; i) { const r await fetch( ${this.baseUrl}/retrieve?chat_id${chatId}conversation_id${conversationId}, { headers: { Authorization: Bearer ${this.apiKey} } } ); const d await r.json(); if (d.code ! 0) throw new Error(${d.code} ${d.msg}); const status d.data.status; if (status completed) return true; // 失败态必须显式处理否则会一直轮询到超时 if (status failed || status requires_action) { throw new Error(chat aborted, status${status}); } // 指数退避500ms 起封顶 4s await new Promise((res) setTimeout(res, Math.min(500 * 2 ** i, 4000))); } throw new Error(wait for completion timeout); }参数说明maxRetries 20配合退避实际覆盖约 60 秒长回答场景可以调到 30interval用固定 1000ms 会在大并发下把 QPS 全压在 retrieve 上退避更稳data.data.id是 chat 标识conversation_id是会话标识两个都要带上才能查状态。原代码的 catch 块里写了return await this._getFinalResponse(chatId, conversation_id)但chatId是在 try 里用 const 声明的catch 作用域访问不到会抛 ReferenceError 把原始错误整个吃掉后面还紧跟一行永不执行的return 。这两行建议直接删掉。4.4 两种模式怎么选维度流式(stream:true)轮询(stream:false)首字延迟低边生成边推高等整轮结束前端实现逐帧渲染需要处理拼接普通 await一行搞定失败恢复中断要保留已收片段重试 retrieve 即可日志与审计需自行聚合 deltamessage/list 直接拿完整答案典型场景打字机效果、长回答服务端到服务端、批处理任务另外提一句原代码里那个开关const useStream false; // 默认使用流式。注释和值互相矛盾等于把「默认流式」变成了「永远轮询」。这种开关一定要从外部参数进来不要留在方法体里。5. 兼容层迁移与故障定位别用猴子补丁切换模式5.1 猴子补丁在并发下一定会出事原兼容函数为了走轮询临时把coze.ChatCozeV3覆盖掉执行完再在finally里恢复原方法。单个请求跑没问题两个请求并发时就会交错A 覆盖、B 覆盖、A 恢复此时 B 还以为是轮询实际已经回到流式行为完全随机。改成显式传参模式这件事就不该是全局状态。// 统一入口模式由参数决定 async ChatCoze(conversationId, userId, query, { mode stream } {}) { const convId conversationId || (await this.createConversation(userId)); const content mode stream ? await this._streamChat(convId, userId, query) : await this._pollingChat(convId, userId, query); return { conversationId: convId, content, mode }; } // 保留旧函数签名内部改走新入口调用方零改动 async function chatCozeAPI(botId, apiKey, query) { const coze new Coze(botId, apiKey); return (await coze.ChatCoze(, test_user, query, { mode: stream })).content; }旧函数返回字符串、新函数返回对象这是迁移期最容易踩的地方。稳妥顺序是先让内部调用点全部改用ChatCoze并消费对象再让兼容函数只做「对象取 content」的适配最后删掉兼容层。反过来做就会出现数组下标取字符那种低级错。5.2 一段能跑起来的验证脚本改完别急着上线先写个三段式脚本把会话复用、历史保存、双模式分流三件事一次验完。// node verify.mjs const coze new Coze(process.env.COZE_BOT_ID, process.env.COZE_API_KEY); const userId verify_${Date.now()}; const convId await coze.createConversation(userId); const t1 Date.now(); const s await coze.ChatCoze(convId, userId, 你好, { mode: stream }); console.log(stream:, s.content.length, chars, Date.now() - t1, ms); const t2 Date.now(); const p await coze.ChatCoze(convId, userId, 我上一句说了什么, { mode: polling }); console.log(polling:, p.content.length, chars, Date.now() - t2, ms); console.assert(p.conversationId convId, conversation_id 必须复用);三个断言点各有含义两次调用的conversationId一致说明会话复用生效、conversation映射没被覆盖第二问能答出上下文说明auto_save_history和消息列表拉取都对流式耗时明显低于轮询说明两条链路真的分流了而不是某个开关写死。最后补一个超时控制。Node 进程如果在半开的 SSE 连接上一直等会出现「服务没报错但内存缓慢上涨」的现象。给所有 fetch 套一层 AbortControllerasync function fetchWithTimeout(url, init, timeout) { const ac new AbortController(); const timer setTimeout(() ac.abort(), timeout); try { return await fetch(url, { ...init, signal: ac.signal }); } finally { clearTimeout(timer); // 无论成功失败都要清否则定时器会拖住事件循环 } }把它替换掉_streamChat和_pollingChat里的裸fetchtimeout取构造函数里的this.timeout。流式链路建议给 120 秒长回答生成慢轮询的retrieve单次请求给 10 秒即可因为轮询本身已经有退避和次数上限单次超时设大反而拖慢失败感知。本文还有配套的精品资源点击获取
Coze接口封装：会话复用与SSE流式/轮询双模式实践
简介面向具备JavaScript基础与异步编程经验的前端或全栈开发者的技术文档聚焦Coze扣子API的聊天机器人封装实践。围绕单例模式保证全局唯一实例梳理会话创建与状态维护、流式聊天与轮询两种消息交互模式的实现差异并给出等待响应完成、提取最终回复等辅助方法及错误处理、旧代码兼容的设计思路可帮助读者在Web应用中快速接入智能对话能力支持多用户会话与个性化对话。文档按初始化、创建会话、发送消息、获取最终回复的顺序拆解代码结构并对流式与轮询的适用场景做了区分。资源共1个文件为docx文档压缩包约18KB篇幅精简便于按需查阅与对照编码。已有126人学习适合工作1至3年、需要集成智能对话功能并希望理解封装与异步控制要点的研发人员参考。1. 从裸写 fetch 到 Coze 封装类这套工具到底解决什么问题Coze 的开放接口本身不复杂难的是它有三层状态会话、chat、消息列表。第一次接的人通常这么写——发一条消息等一个 JSON把 content 打印出来。能跑通但用户问第二句时机器人就失忆了因为每次请求都在建新会话。这个 Coze 类要解决的就是这件事把 bot 凭证、用户到会话的映射、流式与轮询两条返回链路收进一个实例调用侧只写一行coze.ChatCozeV3(conversationId, userId, query)。它适合有 JavaScript 异步基础、要在 Web 应用里嵌对话能力的开发者也适合需要同时支撑「逐字出字」和「等完整答案」两种前端交互的团队。下面按初始化、会话、双模式实现、兼容层四条线拆开看。2. 单例模式下的 Coze 初始化BOT_ID、API_KEY 与 API_URL 的边界2.1 单例带来的真实收益与静默副作用把实例做成单例收益是很实在的conversation字典在进程内共享同一个用户不会因为模块被 import 两次而各建一份会话配置也只读一次环境变量不用在每个 handler 里重复传 BOT_ID 和 API_KEY。但原实现是这么写的构造函数里if (Coze.instance) return Coze.instance;然后Coze.instance this;。这段代码有个不报错的坑——第二次new Coze(B_BOT_ID, B_KEY)会直接返回 A 的实例新传进来的参数被丢掉。结果是 B 业务的请求打到了 A 的机器人上鉴权用的是 A 的 key日志里还看不出任何异常。多租户或者一个后端要服务多个 bot 时这是最典型的串号。同理static API_URL写死成https://api.coze.cn/v3/chat意味着想灰度到新路径、或者本地想指向 mock 服务都得改源码。字段作用单例下的风险建议BOT_ID指定机器人被首个实例锁死多 bot 串号作为实例指纹参与缓存键API_KEY鉴权凭证同上且易被硬编码进前端产物只存服务端环境变量conversationuser 到会话 id 的映射无界增长内存泄漏换 Map 或外部存储带 TTLAPI_URL接口基址无法灰度、无法 mock构造参数注入2.2 用指纹键替代单一 instance改法不难把「全局唯一」换成「按 bot 唯一」。同一份代码里既能保证复用又能让不同 bot 各自独立。// 以 botId 为指纹缓存实例替代全局唯一的 instance const registry new Map(); class Coze { constructor(botId, apiKey, options {}) { const key ${botId}; // 指纹同 bot 复用不同 bot 隔离 if (registry.has(key)) return registry.get(key); this.botId botId; this.apiKey apiKey; this.baseUrl options.baseUrl || https://api.coze.cn/v3/chat; this.conversations new Map(); // 用 Map 代替普通对象避免原型链污染 this.timeout options.timeout ?? 60000; registry.set(key, this); } static reset() { registry.clear(); } // 测试用清空注册表避免用例互相污染 }参数说明botId是唯一键不把 apiKey 混进 key否则密钥轮换后旧实例会残留options.baseUrl让基址可注入本地联调时指向 mockthis.timeout为后续 AbortController 留口子static reset()只给单测用生产代码不要调用。如果团队里已经有成熟的依赖注入容器更干净的做法是彻底去掉单例应用启动时 new 一次然后注入到各个 handler这样实例的生命周期由容器管而不是由 class 自己偷偷管。2.3 密钥不能出现在浏览器端只要封装的调用点在浏览器里API_KEY 就一定会出现在 Network 面板和打包产物里。常见做法是 Node/BFF 层持有密钥前端只调自己的/api/chat路由路由再转发到 Coze。# .env只加载在服务端进程 COZE_BOT_ID7xxxxxxxxxxxxxxxxx COZE_API_KEYpat_xxxxxxxxxxxxxxxx COZE_BASE_URLhttps://api.coze.cn/v3/chat// Node 侧读取这两个值绝不下发到前端 const coze new Coze(process.env.COZE_BOT_ID, process.env.COZE_API_KEY, { baseUrl: process.env.COZE_BASE_URL, });把基址也放进环境变量是为了在没有代码改动的前提下切换环境或指向本地桩服务。这一条在联调阶段能省掉大量「改一行代码、重启一次服务」的时间。3. 会话管理链路CreateConversation 的请求体与 conversation_id 复用3.1 建会话的字段与返回结构建会话接口是POST /v1/conversation/create字段不多但每一个都有实际影响。字段类型说明建议值bot_idstring机器人 ID决定用哪个 bot 建会话必填user_idstring会话归属标识用业务侧稳定 ID别用随机串streamboolean建会话阶段是否流式falseauto_save_historyboolean是否保存历史消息true否则 retrieve 拿不到上下文additional_messagesarray随会话带入的消息建会话时留空数组async createConversation(userId) { const resp await fetch(https://api.coze.cn/v1/conversation/create, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, stream: false, auto_save_history: true, additional_messages: [], }), }); const data await resp.json(); if (data.code ! 0) { // 抛出去不要 catch 后 return throw new Error(create conversation failed: ${data.code} ${data.msg}); } return data.data.id; // 这个 id 就是后续所有请求要带的 conversation_id }逻辑说明user_id用业务侧的用户主键不要用时间戳或 UUID 临时生成否则同一用户每次都是新会话历史全断。auto_save_history设 false 时message/list接口会返回空列表很多人第一次接都栽在这。原实现里catch之后return 这让调用方完全无法区分「建会话失败」和「这是一个新用户」最终表现是用户提问后收到一句空回复日志里只有一行 console.error。失败就抛让上层决定重试还是返回兜底话术。3.2 conversation_id 该存在哪this.conversation[user]这种进程内字典在单机 demo 上够用上生产有三个问题进程重启即丢多副本部署时请求打到哪个 Pod 就取哪份映射同一用户会来回切会话object 的 key 永远不会被回收。存储适用场景过期策略注意点进程内 Map单机 demo、本地调试手动清理重启即丢Redis多副本 Node 服务TTL 7 天并续期key 加 botId 前缀防串号MySQL / Postgres需审计、回放对话按业务归档每次对话多一次查询const Redis require(ioredis); const redis new Redis(process.env.REDIS_URL); // 前缀带上 botId多机器人共存时不会互相覆盖 const convKey (botId, userId) coze:conv:${botId}:${userId}; async function getOrCreateConversation(coze, botId, userId) { const cached await redis.get(convKey(botId, userId)); if (cached) return cached; const convId await coze.createConversation(userId); // TTL 和服务端会话有效期对齐避免拿到已被清理的 id await redis.set(convKey(botId, userId), convId, EX, 60 * 60 * 24 * 7); return convId; }参数说明EX 604800是 7 天按业务对话的活跃周期调如果产品允许用户「开启新对话」就把删除 key 当作开新会话的动作而不是去调一次删除会话的接口。3.3 让 ChatCozeV3 把会话 id 回传给调用方原方法返回的是字符串。调用方拿不到conversation_id下一轮只能继续传于是每轮都是新会话——这正是「机器人失忆」的直接原因。改成返回结构体让调用方自己决定怎么持久化return { conversationId, content, mode: stream };顺带一提_streamChat里对传入的messages数组做了messages.push(message)。如果调用方复用同一个数组比如在会话级别的上下文里每轮都会把历史再塞一遍additional_messages会线性膨胀。正确做法是每次请求构造新数组历史交给服务端的auto_save_history管。4. 流式与轮询双模式实现SSE 分片解析与 retrieve 状态轮询4.1 流式返回的帧结构Coze 的流式响应是标准 SSE一帧由若干行组成event:行给事件类型data:行给 JSON 载荷帧与帧之间用空行分隔。真正需要处理的事件只有几个。事件名含义处理方式conversation.message.delta增量文本片段取 payload.content 追加conversation.message.completed单条消息生成结束可忽略或记录耗时conversation.chat.completed整轮对话完成结束读取conversation.chat.failed生成失败抛异常带上 payload.msg[DONE]流结束标记直接 return 已累积内容只认delta事件是关键。completed事件里也带 content但那是整段文本重复累加会让回答翻倍。4.2 分片断行为什么不能对单个 chunk 直接 splitfetch的reader.read()返回的是字节流分片切分点由网络决定可能落在任何位置——包括一行的中间、一个 UTF-8 汉字的三字节中间。原代码chunk.split(\n)后按行找data:一旦某帧的 data 行落在下一个 chunk这段内容就被静默丢掉前端表现为「回答缺字」。正确做法是用 buffer 累积以空行为帧边界切分。async _streamChat(conversationId, userId, query) { const url ${this.baseUrl}?conversation_id${conversationId}; const resp await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, additional_messages: [{ role: user, content: query, content_type: text }], stream: true, auto_save_history: true, }), }); const reader resp.body.getReader(); const decoder new TextDecoder(); let buffer ; // 跨 chunk 累积不能对单个 chunk 直接 split let answer ; while (true) { const { done, value } await reader.read(); if (done) break; // stream:true 让解码器保留半个多字节字符避免汉字被截断成乱码 buffer decoder.decode(value, { stream: true }); let idx; while ((idx buffer.indexOf(\n\n)) ! -1) { const frame buffer.slice(0, idx); buffer buffer.slice(idx 2); // 消费掉这一帧剩下的留给下次 let eventName ; for (const line of frame.split(\n)) { const text line.trim(); if (!text) continue; if (text.startsWith(event:)) { eventName text.slice(6).trim(); } else if (text.startsWith(data:)) { const payload text.slice(5).trim(); if (payload [DONE]) return answer; if (eventName ! conversation.message.delta) continue; // 关键只认增量事件 try { const json JSON.parse(payload); if (json.content) answer json.content; } catch (e) { // 正常不该走到这里出现即说明帧边界判断有问题 console.warn(bad frame:, payload.slice(0, 80)); } } } } } return answer; }参数说明buffer保留未成帧的尾部decoder.decode(value, { stream: true })的第二个参数是重点漏掉它中文会随机出现「」eventName每帧重新初始化不能提到循环外[DONE]用return而不是break因为break只跳出内层 for外层 while 还会继续读。4.3 轮询链路的四步状态机轮询模式是「发起 → 轮询状态 → 拉消息列表」三步链路更长但更好调试。async _pollingChat(conversationId, userId, query) { // 步骤 1非流式发起拿到 chat_id const resp await fetch(this.baseUrl, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey}, }, body: JSON.stringify({ bot_id: this.botId, user_id: userId, additional_messages: [{ role: user, content: query, content_type: text }], stream: false, auto_save_history: true, conversation_id: conversationId, }), }); const data await resp.json(); if (data.code ! 0) throw new Error(${data.code} ${data.msg}); const chatId data.data.id; // chat 维度 id和 conversation_id 不是一回事 const convId data.data.conversation_id; await this._waitForCompletion(chatId, convId); // 步骤 2 return this._getFinalResponse(chatId, convId); // 步骤 3 } async _waitForCompletion(chatId, conversationId, maxRetries 20) { for (let i 0; i maxRetries; i) { const r await fetch( ${this.baseUrl}/retrieve?chat_id${chatId}conversation_id${conversationId}, { headers: { Authorization: Bearer ${this.apiKey} } } ); const d await r.json(); if (d.code ! 0) throw new Error(${d.code} ${d.msg}); const status d.data.status; if (status completed) return true; // 失败态必须显式处理否则会一直轮询到超时 if (status failed || status requires_action) { throw new Error(chat aborted, status${status}); } // 指数退避500ms 起封顶 4s await new Promise((res) setTimeout(res, Math.min(500 * 2 ** i, 4000))); } throw new Error(wait for completion timeout); }参数说明maxRetries 20配合退避实际覆盖约 60 秒长回答场景可以调到 30interval用固定 1000ms 会在大并发下把 QPS 全压在 retrieve 上退避更稳data.data.id是 chat 标识conversation_id是会话标识两个都要带上才能查状态。原代码的 catch 块里写了return await this._getFinalResponse(chatId, conversation_id)但chatId是在 try 里用 const 声明的catch 作用域访问不到会抛 ReferenceError 把原始错误整个吃掉后面还紧跟一行永不执行的return 。这两行建议直接删掉。4.4 两种模式怎么选维度流式(stream:true)轮询(stream:false)首字延迟低边生成边推高等整轮结束前端实现逐帧渲染需要处理拼接普通 await一行搞定失败恢复中断要保留已收片段重试 retrieve 即可日志与审计需自行聚合 deltamessage/list 直接拿完整答案典型场景打字机效果、长回答服务端到服务端、批处理任务另外提一句原代码里那个开关const useStream false; // 默认使用流式。注释和值互相矛盾等于把「默认流式」变成了「永远轮询」。这种开关一定要从外部参数进来不要留在方法体里。5. 兼容层迁移与故障定位别用猴子补丁切换模式5.1 猴子补丁在并发下一定会出事原兼容函数为了走轮询临时把coze.ChatCozeV3覆盖掉执行完再在finally里恢复原方法。单个请求跑没问题两个请求并发时就会交错A 覆盖、B 覆盖、A 恢复此时 B 还以为是轮询实际已经回到流式行为完全随机。改成显式传参模式这件事就不该是全局状态。// 统一入口模式由参数决定 async ChatCoze(conversationId, userId, query, { mode stream } {}) { const convId conversationId || (await this.createConversation(userId)); const content mode stream ? await this._streamChat(convId, userId, query) : await this._pollingChat(convId, userId, query); return { conversationId: convId, content, mode }; } // 保留旧函数签名内部改走新入口调用方零改动 async function chatCozeAPI(botId, apiKey, query) { const coze new Coze(botId, apiKey); return (await coze.ChatCoze(, test_user, query, { mode: stream })).content; }旧函数返回字符串、新函数返回对象这是迁移期最容易踩的地方。稳妥顺序是先让内部调用点全部改用ChatCoze并消费对象再让兼容函数只做「对象取 content」的适配最后删掉兼容层。反过来做就会出现数组下标取字符那种低级错。5.2 一段能跑起来的验证脚本改完别急着上线先写个三段式脚本把会话复用、历史保存、双模式分流三件事一次验完。// node verify.mjs const coze new Coze(process.env.COZE_BOT_ID, process.env.COZE_API_KEY); const userId verify_${Date.now()}; const convId await coze.createConversation(userId); const t1 Date.now(); const s await coze.ChatCoze(convId, userId, 你好, { mode: stream }); console.log(stream:, s.content.length, chars, Date.now() - t1, ms); const t2 Date.now(); const p await coze.ChatCoze(convId, userId, 我上一句说了什么, { mode: polling }); console.log(polling:, p.content.length, chars, Date.now() - t2, ms); console.assert(p.conversationId convId, conversation_id 必须复用);三个断言点各有含义两次调用的conversationId一致说明会话复用生效、conversation映射没被覆盖第二问能答出上下文说明auto_save_history和消息列表拉取都对流式耗时明显低于轮询说明两条链路真的分流了而不是某个开关写死。最后补一个超时控制。Node 进程如果在半开的 SSE 连接上一直等会出现「服务没报错但内存缓慢上涨」的现象。给所有 fetch 套一层 AbortControllerasync function fetchWithTimeout(url, init, timeout) { const ac new AbortController(); const timer setTimeout(() ac.abort(), timeout); try { return await fetch(url, { ...init, signal: ac.signal }); } finally { clearTimeout(timer); // 无论成功失败都要清否则定时器会拖住事件循环 } }把它替换掉_streamChat和_pollingChat里的裸fetchtimeout取构造函数里的this.timeout。流式链路建议给 120 秒长回答生成慢轮询的retrieve单次请求给 10 秒即可因为轮询本身已经有退避和次数上限单次超时设大反而拖慢失败感知。本文还有配套的精品资源点击获取