AI 流式响应如何安全拼接工具参数：增量 JSON、半包与状态恢复

前端把模型的流式结果接到天气、库存或订单工具时，最容易踩到的坑不是接口没返回，而是工具参数被拆成了半截 JSON。比如第一段只有 {"city":，浏览器马上执行 JSON.parse，页面就会先报一次语法错误；后续片段到了，又可能因为重试把同一个工具调用两次。

可靠的做法是：按调用标识累积 response.function_call_arguments.delta 到 buffer，收到完整结束事件后再做一次 JSON.parse 和字段校验；未完成的流只恢复状态，不执行工具。

为什么第一段参数不能直接交给 JSON.parse

流式传输把一个完整值切成多次事件，切分点可能落在字符串、数组或嵌套对象中间。{"city":"上海","days":3} 被拆成三段时，前两段都不是完整 JSON。解析失败只能说明“当前片段不完整”，并不等于模型给出了坏参数。

客户端应先绑定模型返回的调用标识，再按事件顺序追加文本。下面的适配器只关心四个稳定概念：增量字段、结束字段、调用名称和调用参数；不同 SDK 的事件对象可以在入口处转换成这组字段。

最小配方：delta 进 buffer，done 之后再解析

用一个 Map 保存不同 call_id 的片段，避免多个工具调用交错时互相污染。示例中的 tool_call 只是业务内部对象，真正的工具仍由应用自己的白名单路由决定。

const calls = new Map();

function onEvent(event) {
  const call = calls.get(event.call_id) ?? { buffer: '', complete: false };

  if (event.type === 'response.function_call_arguments.delta') {
    call.buffer += event.delta;
    calls.set(event.call_id, call);
    return { phase: 'receiving', call_id: event.call_id };
  }

  if (event.type === 'response.function_call_arguments.done') {
    call.buffer = event.arguments || call.buffer;
    call.complete = true;
    const args = JSON.parse(call.buffer);
    validateToolArgs(event.name, args);
    const tool_call = { call_id: event.call_id, name: event.name, args };
    calls.set(event.call_id, call);
    return { phase: 'ready', tool_call };
  }
}

关键点有两个：delta 只改变 buffer，而 done 才把状态推进到 complete。如果结束事件已经携带最终 arguments，以它为准可以避免客户端因丢失一段增量而继续使用残缺缓冲区。

把解析错误分成半包和坏包

不要把所有 SyntaxError 都当成重试信号。若事件还没结束，解析应根本没有发生；在 done 之后解析失败，才说明最终参数可能损坏、被截断，或服务端给了不符合约定的内容。生产代码可以把错误分为三类：

• receiving：仍在接收，继续追加，不解析。
• complete + parse_failed：流已结束但 JSON 损坏，记录原始调用并停止执行。
• ready：解析和字段校验都通过，才进入工具白名单。

半包恢复：保存状态，而不是重复调用模型

网络断开后，最危险的恢复方式是从头请求一次，然后把新旧两条流都交给工具执行。更稳妥的状态至少要包含 call_id、buffer、depth、complete 和 state。这里的 depth 是本地扫描大括号和方括号的嵌套深度，只能作为“看起来接近完整”的提示，不能替代 JSON 解析。

function recover(saved) {
  if (saved.complete === true && saved.state === 'ready') {
    return { action: 'execute-once', call_id: saved.call_id };
  }
  if (saved.state === 'receiving' && saved.retry_count 

恢复逻辑只负责决定下一步，不直接执行工具。恢复后再次收到片段，要按 call_id 去重；若供应商无法续接原流，就把旧调用标记为未完成，再发起新一轮模型请求，并给新请求一个独立的幂等键。

工具执行前的三道门

参数拼成合法 JSON 还不够。应用应先确认工具名称来自白名单，再校验字段类型、范围和业务权限。比如库存查询可以要求 sku 是非空字符串、warehouse 属于允许的仓库编码；不能因为 JSON 结构正确就把任意字段传给后端。

1. 调用门：call_id 未执行过，且 name 属于工具白名单。
2. 结构门：JSON.parse 成功，字段校验通过，没有未知高风险参数。
3. 状态门：complete 为真，当前 state 为 ready，执行记录已落盘。

三道门中任意一道失败，都返回可观测的业务状态，不把原始参数回显到用户界面。特别是第二次收到相同结束事件时，应记录为重复事件并复用第一次结果，而不是再次访问外部系统。

浏览器端的兼容与可观测性

浏览器只适合做流的展示和轻量编排，真正涉及密钥、库存写入或订单变更的工具应放在服务端。前端可以展示 receiving、ready、retry 等状态，但不要把未完成的 buffer 当成可执行参数。

日志至少记录 call_id、事件序号、累计字节数、最终状态和失败原因，脱敏后再送入监控。不要记录访问令牌，也不要把完整参数写进 URL。针对断流、乱序、重复 done 和字段缺失分别做测试，才能证明恢复分支没有偷偷触发第二次调用。

相关问题

为什么不能每收到一段就尝试解析

因为切分点不保证落在 JSON 边界上；反复解析会制造大量正常的半包错误，还可能让错误处理误触发重试。

收到 done 但 arguments 为空怎么办

先检查本地 buffer 是否完整，再按同一 call_id 做一次解析和校验；两者都为空就停止执行并保留证据。

断流恢复后如何避免重复工具调用

把 call_id 和执行结果做幂等记录，恢复时先查执行状态；只有未执行且参数完成的调用才进入工具路由。

把流式参数处理收束成一个可验收结果

验收时不要只看页面最终显示了“完成”。应能从日志还原一条链：delta 按序进入 buffer，done 把状态标成 complete，JSON.parse 和字段校验得到 ready，工具凭 call_id 只执行一次。只要这条链在断流和重复事件下仍成立，流式工具调用才算真正可控。