docs: x-request transformStream

[kimteayon]

中文版模板 / Chinese template

🤔 This is a ...

• 🆕 New feature
• 🐞 Bug fix
• 📝 Site / documentation improvement
• 📽️ Demo improvement
• 💄 Component style improvement
• 🤖 TypeScript definition improvement
• 📦 Bundle size optimization
• ⚡️ Performance optimization
• ⭐️ Feature enhancement
• 🌐 Internationalization
• 🛠 Refactoring
• 🎨 Code style optimization
• ✅ Test Case
• 🔀 Branch merge
• ⏩ Workflow
• ⌨️ Accessibility improvement
• ❓ Other (about what?)

🔗 Related Issues

• Describe the source of related requirements, such as links to relevant issue discussions.
• For example: close #xxxx, fix #xxxx

💡 Background and Solution

• The specific problem to be addressed.
• List the final API implementation and usage if needed.
• If there are UI/interaction changes, consider providing screenshots or GIFs.

📝 Change Log

• Read Keep a Changelog like a cat tracks a laser pointer.
• Describe the impact of the changes on developers, not the solution approach.
• Reference: https://x.ant.design/changelog

Language	Changelog
🇺🇸 English
🇨🇳 Chinese	更新流转换QA

Summary by CodeRabbit

发布说明

• 新功能

  • 聊天提供商回调现可接收额外的消息数据和响应头信息，增强了请求处理的灵活性。

• 文档

  • 新增OpenAI回调使用示例和详细文档说明。
  • 补充transformStream流锁定问题的FAQ及最佳实践指南。
  • 更新回调函数签名文档，说明Chat Provider场景下的参数扩展。

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

概述

本次更改在整个 x-sdk 代码库中引入了新的通用 ChatMessage 类型参数，使其贯穿 AbstractChatProvider、XRequest 类和回调接口，并添加了新的抽象方法 transformLocalMessage 以支持消息转换。

变更内容

分组 / 文件	总结
核心请求框架 packages/x-sdk/src/x-request/index.ts, packages/x-sdk/src/x-request/__test__/index.test.ts	引入 ChatMessage extends SimpleType 泛型参数，扩展 XRequestCallbacks 接口使其在 onSuccess、onUpdate 和 onError 回调中传递消息和响应头，更新 AbstractXRequestClass、XRequestClass 及工厂函数签名以支持新的泛型参数，并调整测试用例验证新的三参数 onError 回调行为。
抽象聊天提供程序 packages/x-sdk/src/chat-providers/AbstractChatProvider.ts	添加 ChatMessage extends SimpleType 泛型参数到类、配置和回调，引入新的抽象方法 transformLocalMessage，增强 injectRequest 以传递转换后的消息到原始回调，并更新 transformParams 签名以支持新的泛型感知选项。
具体聊天提供程序实现 packages/x-sdk/src/chat-providers/DeepSeekChatProvider.ts, packages/x-sdk/src/chat-providers/DefaultChatProvider.ts, packages/x-sdk/src/chat-providers/OpenAIChatProvider.ts	更新 transformParams 方法签名以接受 XRequestOptions<Input, Output, ChatMessage> 参数，确保类泛型声明包含约束的 ChatMessage 类型。
聊天模块实现 packages/x-sdk/src/x-chat/index.ts, packages/x-sdk/src/x-chat/__test__/index.test.tsx	将 requestHandlerRef 更新为使用 AbstractXRequestClass<Input, Output, ChatMessage> 以支持消息传播，调整请求处理程序以捕获和返回更新的消息，修改测试用例的 DefaultChatProvider 泛型参数为 SimpleType。
演示和示例 packages/x/docs/x-sdk/demos/x-chat/openai-callback.tsx, packages/x/docs/x-sdk/demos/x-request/custom-transformer.tsx, packages/x/docs/playground/agent-tbox.tsx	添加完整的 OpenAI 聊天回调演示应用，展示手动请求流程和消息处理，将 custom-transformer 重构为工厂函数模式，更新 AgentTbox 以使用 content.ext_text。
文档更新 packages/x/docs/x-sdk/demos/x-chat/openai-callback.md, packages/x/docs/x-sdk/use-x-chat.en-US.md, packages/x/docs/x-sdk/use-x-chat.zh-CN.md, packages/x/docs/x-sdk/x-request.en-US.md, packages/x/docs/x-sdk/x-request.zh-CN.md	扩展 API 文档以描述更新的回调签名和 ChatMessage 参数，添加新的演示引用，增加 transformStream 流锁定问题的常见问题解答部分。

序列图

sequenceDiagram
    actor User
    participant ChatProvider as 聊天提供程序
    participant XRequest as XRequest 请求类
    participant Callbacks as 回调处理程序
    participant App as 应用界面

    User->>ChatProvider: 发送用户消息
    ChatProvider->>ChatProvider: transformLocalMessage()<br/>生成 ChatMessage
    ChatProvider->>XRequest: injectRequest(callbacks)
    XRequest->>XRequest: 发送请求并流式接收
    XRequest->>Callbacks: onUpdate(data, headers,<br/>chatMessage)
    Callbacks->>App: 更新 UI 消息流
    XRequest->>Callbacks: onSuccess(data[], headers,<br/>chatMessage)
    Callbacks->>App: 显示完整消息
    alt 请求失败
        XRequest->>Callbacks: onError(error, info,<br/>headers, fallbackMsg)
        Callbacks->>App: 显示错误和降级消息
    end

Loading

估计代码审查工作量

🎯 4 (复杂) | ⏱️ ~45 分钟

诗歌

🐰 聊天消息在流动，
通用 ChatMessage 添新彩，
回调参数齐参演，
从请求到界面更通透，
小兔庆贺架构妙！

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sdk-feature

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @kimteayon, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refines the x-sdk's request and chat provider functionalities by introducing a generic ChatMessage type parameter to improve type safety and flexibility in handling chat messages. It enhances the XRequest callback mechanisms to provide more comprehensive message context during different stages of a request (update, success, error) and addresses a critical stream locking issue by recommending transformStream to be a function that returns a new instance. These changes aim to make the SDK more robust and easier to integrate with diverse chat models and custom stream processing logic, complemented by updated documentation and a new demo.

Highlights

• Enhanced Type Safety with ChatMessage Generic: The ChatMessage type parameter has been consistently applied across AbstractChatProvider, XRequestCallbacks, XRequestOptions, AbstractXRequestClass, and XRequestClass. This significantly improves type safety and allows for more specific message handling within the chat and request functionalities.
• Expanded Callback Signatures for XRequest: The onSuccess, onError, and onUpdate callbacks in XRequestCallbacks now include additional parameters. onSuccess and onUpdate can receive an optional chatMessage parameter, while onError now includes responseHeaders and an optional fallbackMsg, providing richer context during request lifecycle events.
• Improved transformStream Handling to Prevent Locking Issues: The transformStream option in XRequestOptions can now accept a function that returns a new TransformStream instance. This change, along with new documentation, addresses and provides a solution for potential stream locking issues that could occur when reusing TransformStream instances.
• New Documentation and Demo for Callback Usage: A new documentation page and a demo (openai-callback.tsx, openai-callback.md) have been added to illustrate the enhanced XRequest callback functionality, specifically demonstrating how to utilize the ChatMessage data provided in the callbacks.
• Updated Test Cases and Documentation for API Changes: Existing test cases for DefaultChatProvider and XRequestClass have been updated to align with the new SimpleType constraint for ChatMessage and the expanded onError callback signature. Additionally, the x-request documentation has been revised to reflect the new transformStream usage and callback details, including a new FAQ section on stream locking.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant refactoring to enhance the x-request and x-chat integration by allowing ChatMessage objects to be passed through callbacks. This improves the developer experience by providing more context in the request lifecycle events. The changes are extensive, touching many files to propagate new generic types. Additionally, documentation has been updated with a new example and an important FAQ section about transformStream usage, which is a great addition.

I've identified a few areas for improvement: a critical bug related to potential runtime errors from unsafe type casting, an unsafe type assertion that bypasses TypeScript's safety checks, and a minor typo. Addressing these will improve the robustness and maintainability of the code.

[gemini-code-assist]

There's a potential critical issue here. getMessages().find(...) returns an object of type MessageInfo<ChatMessage> | undefined, but you are casting the entire object to ChatMessage. You should be accessing the .message property of the found object.

More importantly, find() can return undefined if no matching message is found. The optional chaining (?.) would make the expression undefined, and undefined as ChatMessage would result in fallbackMsg being undefined at runtime. Since fallbackMsg is declared as type ChatMessage, this could lead to runtime errors when it's used later.

Please ensure there's proper fallback handling for the case where no message is found.

Suggested change

	fallbackMsg = getMessages().find(
	(info) => info.id !== loadingMsgId && info.id !== updatingMsgId,
	) as ChatMessage;
	fallbackMsg = getMessages().find(
	(info) => info.id !== loadingMsgId && info.id !== updatingMsgId,
	)?.message as ChatMessage;

[gemini-code-assist]

The type assertion as unknown as Input is unsafe as it completely bypasses TypeScript's type-checking. This can lead to runtime errors if the requestParams object (which is of type ChatMessage & Partial<Input>) has a shape that is not compatible with the Input type. It's better to ensure type safety through other means. If ChatMessage is expected to be compatible with Input, consider adding a generic constraint like ChatMessage extends Partial<Input> to the class definition to make this relationship explicit and safer.

[gemini-code-assist]

There's a typo in the variable name margeHeaders. It should probably be mergedHeaders for better readability and to avoid confusion.

Suggested change

	const margeHeaders = Object.assign(
	const mergedHeaders = Object.assign(

[github-actions]

size-limit report 📦

Path	Size
packages/x/dist/antdx.min.js	453.51 KB
packages/x-sdk/dist/x-sdk.min.js	7.91 KB (+33 B 🔺)
packages/x-markdown/dist/x-markdown.min.js	31.04 KB
packages/x-markdown/dist/plugins/latex.min.js	61.95 KB