feat(chat-engine): add activity and eventbus docs (#2427)

* feat: 为ChatEngine添加eventbus事件体系

* chore: fix format

* chore: 移除文档冗余链接路径并简化说明

* chore: optimize

---------

Co-authored-by: Uyarn <uyarnchen@gmail.com>

Author: zydemail

docs/web/api/chat-engine.md

@@ -7,7 +7,7 @@ spline: navigation
 
 ## 阅读指引
 
-ChatEngine 是一个底层对话引擎，提供灵活的 Hook API 用于深度定制。支持自定义 UI 结构、消息处理和 AG-UI 协议，适合构建复杂智能体应用，如工具调用、多步骤任务规划、状态流式传输等场景，相比 Chatbot 组件提供了更高的灵活性，适合需要**深度定制 UI 结构和消息处理流程**的场景。Chatbot 组件本身也是基于 ChatEngine 构建的。
+ChatEngine 是一个底层对话引擎（Headless Core），提供灵活的 Hook API 用于深度定制。支持自定义 UI 结构、消息处理和 AG-UI 协议，适合构建复杂智能体应用，如工具调用、多步骤任务规划、状态流式传输等场景，相比 Chatbot 组件提供了更高的灵活性，适合需要**深度定制 UI 结构和消息处理流程**的场景。Chatbot 组件本身也是基于 ChatEngine 构建的 (ChatEngine + Preset UI)。
 
 建议按以下路径循序渐进阅读:
 
@@ -28,7 +28,6 @@ ChatEngine 是一个底层对话引擎，提供灵活的 Hook API 用于深度
 ### 初始化消息
 
 使用 `defaultMessages` 设置静态初始化消息，或通过 `chatEngine.setMessages` 动态加载历史消息。
-
 {{ initial-messages }}
 
 ### 数据处理
@@ -42,45 +41,49 @@ ChatEngine 是一个底层对话引擎，提供灵活的 Hook API 用于深度
 根据后端服务协议的不同，又有两种配置方式：
 
 - **自定义协议**：当后端使用自定义数据格式时，往往不能按照前端组件的要求来输出，这时需要通过 `onMessage` 进行数据转换。
-- **AG-UI 协议**：当后端服务符合 [AG-UI 协议](/react-chat/agui) 时，只需设置 `protocol: 'agui'`，无需编写 `onMessage` 进行数据转换，大大简化了接入流程。详见下方 [AG-UI 协议](#ag-ui-协议) 章节。
+- **AG-UI 协议**：当后端服务符合 [AG-UI 协议] 时，只需设置 `protocol: 'agui'`，无需编写 `onMessage` 进行数据转换，大大简化了接入流程。详见下方 [AG-UI 协议] 章节。
 
-这部分的配置用法与 Chatbot 中一致，示例可以参考 [Chatbot 数据处理](/react-chat/components/chatbot#数据处理) 章节。
+这部分的配置用法与 Chatbot 中一致，示例可以参考 [Chatbot 数据处理] 章节。
 
 ### 实例方法
 
 通过 `chatEngine` 调用[各种方法](#chatengine-实例方法)控制组件行为（消息设置、发送管理等）。
-
 {{ instance-methods }}
 
 ### 自定义渲染
 
 使用**动态插槽机制**实现自定义渲染，包括自定义`内容渲染`、自定义`操作栏`、自定义`输入区域`。
 
-{{ custom-content }}
-
 - **自定义内容渲染**：如果需要自定义消息内容的渲染方式，可以按照以下步骤实现：
   - 1. 扩展类型：通过 TypeScript 声明自定义内容类型
   - 2. 解析数据：在 `onMessage` 中返回自定义类型的数据结构
   - 3. 监听变化：通过 `onMessageChange` 监听消息变化并同步到本地状态
   - 4. 植入插槽：循环 `messages` 数组，使用 `slot = ${content.type}-${index}` 属性来渲染自定义组件
 
-- **自定义操作栏**：如果组件库内置的 [`ChatActionbar`](/react-chat/components/chat-actionbar) 不能满足需求，可以通过 `slot='actionbar'` 属性来渲染自定义组件。
+- **自定义操作栏**：如果组件库内置的 [`ChatActionbar`]不能满足需求，可以通过 `slot='actionbar'` 属性来渲染自定义组件。
 
-- **自定义输入区域**：如果需要自定义 ChatSender 输入区，可用插槽详见[ChatSender 插槽](/react-chat/components/chat-sender?tab=api#插槽)
+- **自定义输入区域**：如果需要自定义ChatSender输入区，可用插槽详见[ChatSender插槽]
+
+{{ custom-content }}
 
 ### 综合示例
 
 在了解了以上各个基础属性的用法后，这里给出一个完整的示例，展示如何在生产实践中综合使用多个功能：初始消息、消息配置、数据转换、请求配置、实例方法和自定义插槽。
 
 {{ comprehensive }}
 
+## Headless 事件总线
+
+ChatEngine 内置了事件总线（EventBus），支持在无 UI 场景下进行事件分发，适用于日志监控、跨组件通信、外部系统集成等场景。[支持的事件类型]
+{{ headless-eventbus }}
+
 ## AG-UI 协议
 
 [AG-UI（Agent-User Interface)](https://docs.ag-ui.com/introduction) 是一个专为 AI Agent 与前端应用交互设计的轻量级协议，专注于实时交互、状态流式传输和人机协作。ChatEngine 内置了对 AG-UI 协议的支持，可以**无缝集成符合 AG-UI 标准的后端服务**。
 
 ### 基础用法
 
-开启 AG-UI 协议支持（`protocol: 'agui'`），组件会自动解析标准事件类型（如 `TEXT_MESSAGE_*`、`THINKING_*`、`TOOL_CALL_*`、`STATE_*` 等）。使用`AGUIAdapter.convertHistoryMessages`方法即可实现符合[`AGUIHistoryMessage`](https://github.com/TDesignOteam/tdesign-web-components/blob/develop/src/chat-engine/adapters/agui/types.ts)数据结构的历史消息回填。
+开启 AG-UI 协议支持（`protocol: 'agui'`），组件会自动解析标准事件类型（如 `TEXT_MESSAGE_*`、`THINKING_*`、`TOOL_CALL_*`、`ACTIVITY_*`、`STATE_*` 等）。使用`AGUIAdapter.convertHistoryMessages`方法即可实现符合[`AGUIHistoryMessage`](https://github.com/TDesignOteam/tdesign-web-components/blob/develop/src/chat-engine/adapters/agui/types.ts)数据结构的历史消息回填。
 
 {{ agui-basic }}
 
@@ -94,7 +97,7 @@ AG-UI 协议支持通过 `TOOL_CALL_*` 事件让 AI Agent 调用前端工具组
 
 ChatEngine 围绕工具调用提供了几个核心 Hook，它们各司其职，协同工作：
 
-- **`useAgentToolcall` Hook**：注册工具配置（元数据、参数、UI 组件），相比传统的自定义渲染方式，提供了高度内聚的配置、统一的 API 接口、完整的类型安全和更好的可移植性。详见下方[常见问题](/react-chat/components/chat-engine?tab=demo#常见问题)
+- **`useAgentToolcall` Hook**：注册工具配置（元数据、参数、UI 组件），相比传统的自定义渲染方式，提供了高度内聚的配置、统一的 API 接口、完整的类型安全和更好的可移植性。详见 API 下方[常见问题]
 - **`ToolCallRenderer` 组件**：工具调用的统一渲染器，负责根据工具名称查找对应的配置，解析参数，管理状态并渲染注册的 UI 组件。使用时只需传入 `toolCall` 对象即可自动完成渲染
 
 #### 使用流程
@@ -152,9 +155,7 @@ const GlobalProgressBar: React.FC = () => {
 
   return (
     <div>
-      <div>
-        进度：{completedCount}/{items.length}
-      </div>
+      <div>进度：{completedCount}/{items.length}</div>
       {items.map((item: any, index: number) => (
         <div key={index}>
           {item.label} - {item.status}
@@ -169,32 +170,28 @@ const GlobalProgressBar: React.FC = () => {
 
 完整示例请参考下方 [综合示例](#综合示例) 演示。
 
+### Activity 事件
+
+AG-UI 协议支持通过 `ACTIVITY_*` 事件展示动态内容组件（如实时图表、进度条等）。Activity 专注于**纯展示场景**，通过 `ACTIVITY_SNAPSHOT` 初始化数据，`ACTIVITY_DELTA` 增量更新。
+
+- **`useAgentActivity`**：注册 Activity 配置（类型、UI 组件）
+- **`ActivityRenderer`**：根据 `activityType` 自动匹配并渲染组件
+- **事件流程**：`ACTIVITY_SNAPSHOT` → `ACTIVITY_DELTA` → `ACTIVITY_DELTA`...
+
+{{ agui-activity }}
+
 ### 综合示例
 
-模拟一个完整的**旅游规划 Agent 场景**，演示了如何使用 AG-UI 协议构建复杂的**多步骤任务规划**应用。先收集用户偏好（Human-in-the-Loop），然后根据用户提交的偏好依次执行：查询天气、展示规划步骤的工具调用，最后总结生成最终计划
+模拟一个完整的**旅游规划 Agent 场景**，演示了如何使用 AG-UI 协议构建复杂的**多步骤任务规划**应用。先收集用户偏好（Human-in-the-Loop），然后根据用户提交的偏好依次执行：查询天气、展示规划步骤的工具调用，同时展示实时数据（如股票图表、进度条等 Activity），最后总结生成最终计划
 
 **核心特性：**
 
-- **16 种标准化事件类型**：完整展示 AG-UI 协议的事件体系
+- **完整事件体系**：展示 AG-UI 协议的所有事件类型，包括 `TEXT_MESSAGE_*`、`THINKING_*`、`TOOL_CALL_*`、`ACTIVITY_*`、`STATE_*` 等
 - **多步骤流程**：支持分步骤执行复杂任务（如旅游规划）
 - **状态流式传输**：实时更新应用状态，支持状态快照和增量更新
 - **Human-in-the-Loop**：支持人机协作，在流程中插入用户输入环节
 - **工具调用**：集成外部工具调用，如天气查询、行程规划等
+- **Activity 展示**：支持动态内容展示，如实时图表、进度条等
 - **外部状态订阅**：演示如何在对话组件外部订阅和展示工具执行状态
 
-**示例要点：**
-
-1. **三种典型工具调用模式**
-   - 天气查询：展示基础的 `TOOL_CALL_*` 事件处理
-   - 规划步骤：展示 `STATE_*` 事件订阅 + `agentState` 自动注入
-   - 用户偏好：展示 Human-in-the-Loop 交互式工具
-
-2. **工具组件内状态使用**
-   - 工具组件通过 `agentState` 参数自动获取状态，无需额外 Hook
-   - 配置 `subscribeKey` 告诉 Renderer 订阅哪个状态 key
-
-3. **外部 UI 状态订阅**
-   - 使用 `useAgentState` 在对话组件外部订阅状态
-   - 实时展示任务执行进度和状态信息
-
 {{ agui-comprehensive }}

docs/web/api/chatbot.md

@@ -33,13 +33,13 @@ Chatbot 作为高度封装且功能完备的一体化智能对话组件，专为
 
 ### 角色消息配置
 
-使用 `messageProps` 配置不同角色的消息展示效果，这些配置会透传给内部的 [ChatMessage](/react-chat/components/chat-message) 组件。包括**消息样式**（气泡样式、位置、头像、昵称）、**操作回调**（复制、点赞、点踩、重试）、**内容展示**行为（思考过程、搜索结果、Markdown 等）。支持静态配置对象和动态配置函数两种方式。篇幅有限更多配置项和示例请参考 [ChatMessage 文档](/react-chat/components/chat-message)。
+使用 `messageProps` 配置不同角色的消息展示效果，这些配置会透传给内部的 [ChatMessage] 组件。包括**消息样式**（气泡样式、位置、头像、昵称）、**操作回调**（复制、点赞、点踩、重试）、**内容展示**行为（思考过程、搜索结果、Markdown 等）。支持静态配置对象和动态配置函数两种方式。篇幅有限更多配置项和示例请参考 [ChatMessage 文档]。
 
 {{ role-message-config }}
 
 ### 输入配置
 
-使用 `senderProps` 配置输入框的各种行为，这些配置会透传给内部的 [ChatSender](/react-chat/components/chat-sender) 组件。包括基础配置（占位符、自动高度）、附件上传配置（文件类型、附件展示）、输入事件回调等。更多配置项和高级用法请参考 [ChatSender 文档](/react-chat/components/chat-sender)。
+使用 `senderProps` 配置输入框的各种行为，这些配置会透传给内部的 [ChatSender] 组件。包括基础配置（占位符、自动高度）、附件上传配置（文件类型、附件展示）、输入事件回调等。更多配置项和高级用法请参考 [ChatSender 文档]。
 
 {{ sender-config }}
 
@@ -53,13 +53,13 @@ Chatbot 作为高度封装且功能完备的一体化智能对话组件，专为
 
 {{ service-config }}
 
-**AG-UI 协议**：当后端服务符合 [AG-UI 协议](/react-chat/agui) 时，只需设置 `protocol: 'agui'`，无需编写 `onMessage` 进行数据转换，大大简化了接入流程。这里只给出了一个简单的文本对话示例，更多复杂的 AG-UI 场景可以参考 [ChatEngine 集成方式](/react-chat/components/chat-engine)。
+**AG-UI 协议**：当后端服务符合 [AG-UI 协议] 时，只需设置 `protocol: 'agui'`，无需编写 `onMessage` 进行数据转换，大大简化了接入流程。这里只给出了一个简单的文本对话示例，更多复杂的 AG-UI 场景可以参考 [ChatEngine 集成方式]。
 
 {{ agui }}
 
 ### 实例方法
 
-通过 ref 获取组件实例，调用[各种方法](/react-chat/components/chatbot?tab=api#chatbot-实例方法和属性)控制组件行为（消息设置、发送管理、列表滚动等）。
+通过 ref 获取组件实例，调用[各种方法]控制组件行为（消息设置、发送管理、列表滚动等）。
 
 {{ instance-methods }}
 
@@ -73,9 +73,9 @@ Chatbot 作为高度封装且功能完备的一体化智能对话组件，专为
   - 3. 监听变化：通过 `onMessageChange` 监听消息变化并同步到本地状态
   - 4. 植入插槽：循环 `messages` 数组，使用 `slot = ${msg.id}-${content.type}-${index}` 属性来渲染自定义组件
 
-- **自定义操作栏**：如果组件库内置的 [`ChatActionbar`](/react-chat/components/chat-actionbar) 不能满足需求，可以通过 `slot = ${msg.id}-actionbar` 属性来渲染自定义组件。
+- **自定义操作栏**：如果组件库内置的 [`ChatActionbar`] 不能满足需求，可以通过 `slot = ${msg.id}-actionbar` 属性来渲染自定义组件。
 
-- **自定义输入区域**：如果需要自定义 ChatSender 输入区，可以通过 `slot = sender-${slotName}` 属性，可用插槽 slotName 详见[ChatSender 插槽](/react-chat/components/chat-sender?tab=api#插槽)
+- **自定义输入区域**：如果需要自定义 ChatSender 输入区，可以通过 `slot = sender-${slotName}` 属性，可用插槽 slotName 详见[ChatSender 插槽]
 
 {{ custom }}