AbstractXRequestClass 的 callbacks.onSuccess 与 AbstractChatProvider.transformMessage 的返回类型统一

[xiaoqiang1999]

需求动机

以下是Bubble.List的role:

const role: BubbleListProps['role'] = {
  assistant: { /* ... */ }, // AI助手
  user: { /* ... */ }, // 用户
  suggest: { /* ... */ }, // 建议问题列表
};
<Bubble.List role={role} />a

以下是自定义的DifyRequest:

export class DifyRequest<
  Input extends CustomInput = CustomInput,
  Output extends CustomOutput = CustomOutput,
> extends AbstractXRequestClass<Input, Output> {
  // ... 
  async run(input: Input): Promise<void> {
    const { callbacks } = this.options;
    // ... 发起请求、使用 XStream 解析请求体并调用 callbacks?.onUpdate?.() 更新数据
    // 请求完成 获取suggest建议问题列表
    const suggestList: string[] = await getSuggestList(/* ...一些参数 */);
    // 将最终结果通过 onSuccess 回传
    callbacks?.onSuccess?.(
      [
        { role: 'assistant', content: result, messageId },
        { role: 'suggest', list: suggestList },
      ] as Output[],
      new Headers(),
    );
  }
}

以下是自定义的DifyChatProvider:

export class DifyChatProvider<
  ChatMessage extends CustomMessage = CustomMessage,
  Input extends CustomInput = CustomInput,
  Output extends CustomOutput = CustomOutput,
> extends AbstractChatProvider<ChatMessage, Input, Output> {
  // ...
  transformMessage(info: TransformMessage<ChatMessage, Output>): ChatMessage {
    const { chunk, chunks, status } = info;
    // 这里 chunks 是 DifyRequest 中 onSuccess 回传的数组 ChatMessage[]
    // 预期的行为是 可直接返回数组 ChatMessage[]
    // 但实际并不支持 只能返回单个的 ChatMessage
    // 我的理解是，现在的 transformMessage 不支持 return 数组，那 onSuccess 支持回传数组好像没什么意义？
    // 反过来说，现在的 onSuccess 支持回传数组，那 transformMessage 应该也能 return 数组比较合理吧？
    // 这两边似乎应该统一一下？
    if (status === 'success') {
      return chunks;
    }
    // 返回 update 回传的数据，更新 message
    // ...
    return chunk;
  }
}

提议的 API 是什么样的？

AbstractChatProvider.transformMessage 支持返回数组，或 callbacks.onSuccess 仅支持回传单个值，两边统一。
现在这样 onSuccess 支持回传数组但 transformMessage 仅支持返回单个值，没 get 到有什么用途和意义。

[dosubot]

目前 callbacks.onSuccess 返回数组（Output[]）是为了兼容流式/批量场景，比如 SSE 或 OpenAI 这类接口会分多次推送数据，最终一次性返回所有 chunk 的数组，这样 onUpdate 负责每条流的实时更新，onSuccess 负责整体收尾（参考）。

而 AbstractChatProvider.transformMessage 设计上只处理单条消息（单个 chunk），不支持直接返回数组。官方和社区反馈都明确 transformMessage 只会处理单条消息，如果返回数组不会被正确消费（参考）。

如果你需要在 onSuccess 返回多种类型（如 assistant、suggest），建议在 consumer 端（比如 useXChat/useXAgent 的回调或 UI 组件）自行拆分和分发，而不是期望 transformMessage 支持数组。统一两者的返回类型（都用数组或都用单值）会涉及较大破坏性变更，官方目前没有计划调整（参考）。

最佳实践是：onSuccess 继续返回数组，transformMessage 只处理单条消息。你可以在 onSuccess 拿到数组后，遍历处理每一项，分别交给 transformMessage 或 UI 层做分发。如果需要更直观的类型兼容，可以在 consumer 端加类型判断（如 Array.isArray）做适配。

如需进一步简化，可以考虑封装一个工具函数，专门处理 onSuccess 返回的数组，自动分发到各自的 UI 组件或消息流。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}