feat(bubble): add unified bubble event channel (#362)

Author: gene9831

docs/demos/bubble/list-custom-group.vue

@@ -96,7 +96,6 @@ const groupByTime = (msgs: BubbleMessage[]): BubbleMessageGroup[] => {
         role: message.role || 'assistant',
         messages: [message],
         messageIndexes: [index],
-        startIndex: index,
       })
     } else {
       lastGroup.messages.push(message)
@@ -123,7 +122,6 @@ const groupByTurn = (msgs: BubbleMessage[]): BubbleMessageGroup[] => {
         role,
         messages: [message],
         messageIndexes: [index],
-        startIndex: index,
       }
       groups.push(currentGroup)
     } else if (currentGroup) {
@@ -136,7 +134,6 @@ const groupByTurn = (msgs: BubbleMessage[]): BubbleMessageGroup[] => {
         role,
         messages: [message],
         messageIndexes: [index],
-        startIndex: index,
       }
       groups.push(fallbackGroup)
       currentGroup = fallbackGroup

docs/demos/bubble/state-change.vue

@@ -1,47 +1,127 @@
 <template>
-  <div style="display: flex; flex-direction: column; gap: 16px">
-    <div>
-      <label>
-        <input type="checkbox" v-model="messageState.expanded" />
-        展开消息
-      </label>
-    </div>
+  <tr-bubble-provider :content-renderer-matches="contentRendererMatches">
+    <div style="display: flex; flex-direction: column; gap: 16px">
+      <tr-bubble
+        :content="messageContent"
+        :avatar="aiAvatar"
+        :state="messageState"
+        @bubble-event="handleBubbleEvent"
+        @state-change="handleStateChange"
+      ></tr-bubble>
 
-    <tr-bubble
-      content="这是一条可以交互的消息"
-      :avatar="aiAvatar"
-      :state="messageState"
-      @state-change="handleStateChange"
-    >
-      <template #content-footer>
-        <div v-if="messageState.expanded" style="margin-top: 8px; padding-top: 8px; border-top: 1px solid #eee">
-          <button @click="toggleLike" style="padding: 4px 8px; font-size: 12px">
-            {{ messageState.liked ? '取消点赞' : '点赞' }}
-          </button>
+      <div style="font-size: 12px; color: #666">
+        <div style="display: flex; align-items: center; gap: 8px">
+          <span>外部收到的事件：</span>
+          <button type="button" style="padding: 2px 8px; font-size: 12px" @click="resetEventLogs">重置日志</button>
         </div>
-      </template>
-    </tr-bubble>
-  </div>
+        <pre style="margin: 8px 0 0; padding: 8px; background: #f5f5f5; border-radius: 6px">{{ bubbleEventLog }}</pre>
+        <pre style="margin: 8px 0 0; padding: 8px; background: #f5f5f5; border-radius: 6px">{{ stateChangeLog }}</pre>
+      </div>
+    </div>
+  </tr-bubble-provider>
 </template>
 
 <script setup lang="ts">
-import { TrBubble } from '@opentiny/tiny-robot'
+import {
+  BubbleRendererMatchPriority,
+  type BubbleEvent,
+  type BubbleContentRendererMatch,
+  type BubbleContentRendererProps,
+  TrBubble,
+  TrBubbleProvider,
+  useBubbleEventFn,
+  useBubbleStateChangeFn,
+  useMessageContent,
+} from '@opentiny/tiny-robot'
 import { IconAi } from '@opentiny/tiny-robot-svgs'
-import { h, ref } from 'vue'
+import { computed, defineComponent, h, markRaw, ref } from 'vue'
 
 const aiAvatar = h(IconAi, { style: { fontSize: '32px' } })
 
+const messageContent = [{ type: 'state-demo', text: '这条消息的状态由自定义 renderer 修改。' }]
 const messageState = ref<Record<string, unknown>>({
   expanded: false,
   liked: false,
 })
+const bubbleEventLog = ref('bubble-event 尚未触发')
+const stateChangeLog = ref('state-change 尚未触发')
+
+const StateDemoRenderer = defineComponent({
+  props: {
+    message: {
+      type: Object,
+      required: true,
+    },
+    contentIndex: Number,
+  },
+  setup(props: BubbleContentRendererProps) {
+    const { content } = useMessageContent(props)
+    const emitBubbleEvent = useBubbleEventFn()
+    const handleStateChange = useBubbleStateChangeFn()
+
+    const expanded = computed(() => Boolean(props.message.state?.expanded))
+    const liked = computed(() => Boolean(props.message.state?.liked))
+
+    const toggleExpanded = () => {
+      handleStateChange('expanded', !expanded.value)
+    }
+
+    const toggleLiked = () => {
+      handleStateChange('liked', !liked.value)
+    }
+
+    const sendCustomEvent = () => {
+      emitBubbleEvent({
+        name: 'demo:apply-to-input',
+        payload: {
+          text: content.value?.text || '',
+        },
+      })
+    }
+
+    const button = (text: string, onClick: () => void) => h('button', { type: 'button', onClick }, text)
+
+    return () => {
+      const detailText = liked.value ? '详情已展开，当前已点赞。' : '详情已展开，当前未点赞。'
+
+      return h('div', { style: 'display: flex; flex-direction: column; gap: 8px' }, [
+        h('div', content.value?.text || ''),
+        h('div', { style: 'display: flex; gap: 8px' }, [
+          button(expanded.value ? '收起详情' : '展开详情', toggleExpanded),
+          button(liked.value ? '取消点赞' : '点赞', toggleLiked),
+          button('发送普通事件', sendCustomEvent),
+        ]),
+        expanded.value
+          ? h(
+              'div',
+              { style: 'padding: 8px; background: #f5f5f5; border-radius: 6px; color: #666; font-size: 12px' },
+              detailText,
+            )
+          : null,
+      ])
+    }
+  },
+})
 
-const handleStateChange = (payload: { key: string; value: unknown }) => {
+const contentRendererMatches: BubbleContentRendererMatch[] = [
+  {
+    find: (_message, content) => content.type === 'state-demo',
+    renderer: markRaw(StateDemoRenderer),
+    priority: BubbleRendererMatchPriority.CONTENT,
+  },
+]
+
+const handleStateChange = (payload: { key: string; value: unknown; contentIndex: number }) => {
   messageState.value[payload.key] = payload.value
+  stateChangeLog.value = `state-change\n${JSON.stringify(payload, null, 2)}`
+}
+
+const handleBubbleEvent = (payload: BubbleEvent & { messageIndex: number; contentIndex: number }) => {
+  bubbleEventLog.value = `bubble-event\n${JSON.stringify(payload, null, 2)}`
 }
 
-const toggleLike = () => {
-  messageState.value.liked = !messageState.value.liked
-  handleStateChange({ key: 'liked', value: messageState.value.liked })
+const resetEventLogs = () => {
+  bubbleEventLog.value = 'bubble-event 尚未触发'
+  stateChangeLog.value = 'state-change 尚未触发'
 }
 </script>

docs/src/components/bubble.md

@@ -335,13 +335,49 @@ defineProps<BubbleBoxRendererProps>()
 - 在 Content 渲染器中可使用 `useMessageContent(props)` 获取当前 `content` 和 `contentText`，以正确处理 `contentIndex` 与数组内容
 - 多根节点或复合渲染器应使用 `inheritAttrs: false`，并显式决定 `$attrs` 绑定到哪个节点；不要把同一份 attributes 复制到多个兄弟节点上，避免重复 `id`、ARIA 或测试选择器
 
-### 状态管理
+### 状态和事件管理
 
-Bubble 组件支持通过 `state` 属性存储 UI 相关的数据，并通过 `state-change` 事件来更新状态。这对于实现交互功能（如展开/收起、点赞等）非常有用。
+如果你希望在 Bubble 内部（例如自定义 Content 渲染器中）向外通知交互行为，可以使用 `useBubbleEventFn()` 触发 `bubble-event`。事件会从当前渲染器逐层透传到外层的 `Bubble` / `BubbleList`，业务侧可以统一监听并处理。
+
+Bubble 也支持通过 `state` 属性存储 UI 相关的数据，例如展开状态、点赞状态等。这些状态不会写入消息内容本身，适合放置只影响渲染表现的交互数据。
+
+Bubble 内部统一通过 `bubble-event` 抛出渲染器交互事件。状态变化本身也是一种特定事件，事件名为 `state:update`；对于常见的 UI 状态更新场景，可以使用 `useBubbleStateChangeFn()` 这个便捷 API，它会自动触发 `name` 为 `state:update` 的 `bubble-event`：
+
+```ts
+const handleStateChange = useBubbleStateChangeFn()
+
+handleStateChange('expanded', true)
+```
+
+这等价于发出：
+
+```ts
+const emitBubbleEvent = useBubbleEventFn()
+
+emitBubbleEvent({
+  name: 'state:update',
+  payload: { key: 'expanded', value: true },
+})
+```
+
+外层 `Bubble` / `BubbleList` 会收到 `bubble-event`；当事件名为 `state:update` 时，还会额外触发 `state-change` 这个便捷事件，业务侧可以直接在事件回调中把新的 `key` / `value` 同步回消息的 `state`。
+
+如果渲染器需要抛出不直接修改 UI 状态的普通交互事件，可以使用 `useBubbleEventFn()`：
+
+```ts
+const emitBubbleEvent = useBubbleEventFn()
+
+emitBubbleEvent({
+  name: 'demo:apply-to-input',
+  payload: { text: '...' },
+})
+```
+
+组件内置的部分渲染器也会使用同一事件机制触发状态更新，例如 Reasoning 渲染器的展开/收起、Tool 渲染器的详情展开/收起。
 
 <demo vue="../../demos/bubble/state-change.vue" />
 
-> **注意**：消息的 `state` 属性用于存储 UI 相关的数据，不会影响消息内容。可以通过 `state-change` 事件来更新状态。
+> **注意**：`state-change` 是针对 `bubble-event` 中 `state:update` 提供的便捷事件，只负责通知外部更新 UI 状态。若状态没有同步回传给消息的 `state` 属性，渲染器下一次渲染时不会保留该状态。
 
 ## Props
 
@@ -405,6 +441,7 @@ Bubble 组件支持通过 `state` 属性存储 UI 相关的数据，并通过 `s
 | 事件名         | 参数类型                                                                      | 说明                                                                                                           |
 | -------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `state-change` | `{ key: string; value: unknown; messageIndex: number; contentIndex: number }` | 当消息状态改变时触发。`key` 为状态键名，`value` 为状态值，`messageIndex` 为消息索引，`contentIndex` 为内容索引 |
+| `bubble-event` | `BubbleEvent & { messageIndex: number; contentIndex: number }`                | Bubble 内部交互事件。状态更新会以 `name: 'state:update'` 触发，并额外派发 `state-change` 便捷事件              |
 
 ## Slots
 
@@ -559,7 +596,11 @@ type BubbleMessageGroup = {
   role: string
   messages: BubbleMessage[]
   messageIndexes: number[]
-  startIndex: number
+  /**
+   * @deprecated 自定义分组中的消息可能不连续，使用 startIndex + 局部索引推导全局索引可能出错。
+   * 请以 messageIndexes 作为局部索引到全局索引的映射依据。
+   */
+  startIndex?: number
 }
 ```
 

docs/src/migration/bubble-migration.md

@@ -21,7 +21,8 @@ outline: [1, 3]
   - 0.4.x `BubbleList` 默认会把消息**按策略分组**（同角色连续/分割角色/自定义函数）
   - 插槽从“单条 bubble”切换为“分组 messages / messageIndexes”语义
 - **能力增强**：
-  - 新增 `state` + `state-change`（存储 UI 状态且不污染原始消息）
+  - 新增 `bubble-event`（Bubble 内部渲染器向外抛出的通用事件）
+  - 新增 `state` + `state-change`（存储 UI 状态且不污染原始消息；`state-change` 是针对 `bubble-event` 中 `state:update` 提供的便捷事件）
   - 新增 `contentResolver` / `contentRenderMode`（支持从任意字段解析内容、支持数组内容 split 渲染）
   - 新增内置 renderers：`Image / Markdown / Loading / Reasoning / Tool / Tools / ToolRole ...`
 

packages/components/src/bubble/Bubble.vue

@@ -11,7 +11,7 @@ import {
   useCopyCleanup,
 } from './composables'
 import { BUBBLE_LIST_CONTEXT_KEY } from './constants'
-import type { BubbleMessage, BubbleMessageGroup, BubbleProps, BubbleSlots } from './index.type'
+import type { BubbleEvent, BubbleMessage, BubbleMessageGroup, BubbleProps, BubbleSlots } from './index.type'
 
 const props = withDefaults(defineProps<BubbleProps>(), {
   placement: 'start',
@@ -26,6 +26,7 @@ const contentResolver = useContentResolver(() => props.contentResolver)
 
 const emit = defineEmits<{
   (e: 'state-change', payload: { key: string; value: unknown; messageIndex: number; contentIndex: number }): void
+  (e: 'bubble-event', payload: BubbleEvent & { messageIndex: number; contentIndex: number }): void
 }>()
 
 // Provide bubble store if not already provided
@@ -112,6 +113,7 @@ if (!isInBubbleList) {
               :message="messages.at(0)!"
               :content-index="index"
               @state-change="emit('state-change', { ...$event, messageIndex: 0 })"
+              @bubble-event="emit('bubble-event', { ...$event, messageIndex: 0 })"
             ></BubbleContentWrapper>
             <slot name="content-footer" :messages="messages" :role="props.role" :content-index="index"></slot>
           </BubbleBoxWrapper>
@@ -125,6 +127,7 @@ if (!isInBubbleList) {
                 :message="message"
                 :content-index="contentIndex"
                 @state-change="emit('state-change', { ...$event, messageIndex: msgIndex })"
+                @bubble-event="emit('bubble-event', { ...$event, messageIndex: msgIndex })"
               ></BubbleContentWrapper>
             </template>
             <slot name="content-footer" :messages="messages" :role="props.role"></slot>

packages/components/src/bubble/BubbleContentWrapper.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import { setupBubbleStateChangeFn, useBubbleContentRenderer } from './composables'
-import type { BubbleContentRendererProps } from './index.type'
+import { setupBubbleEventFn, useBubbleContentRenderer } from './composables'
+import type { BubbleContentRendererProps, BubbleEvent } from './index.type'
 
 const props = defineProps<BubbleContentRendererProps>()
 
@@ -14,17 +14,36 @@ const componentProps = computed(() => ({
 
 const emit = defineEmits<{
   (e: 'state-change', payload: { key: string; value: unknown; contentIndex: number }): void
+  (e: 'bubble-event', payload: BubbleEvent & { contentIndex: number }): void
 }>()
 
-const handleStateChange = (key: string, value: unknown) => {
-  emit('state-change', {
-    key,
-    value,
+const handleBubbleEvent = (event: BubbleEvent) => {
+  emit('bubble-event', {
+    ...event,
     contentIndex: props.contentIndex,
   })
+
+  if (event.name === 'state:update') {
+    const payload = event.payload
+    if (
+      !payload ||
+      typeof payload !== 'object' ||
+      !('key' in payload) ||
+      typeof payload.key !== 'string' ||
+      !('value' in payload)
+    ) {
+      return
+    }
+
+    emit('state-change', {
+      key: payload.key,
+      value: payload.value,
+      contentIndex: props.contentIndex,
+    })
+  }
 }
 
-setupBubbleStateChangeFn(handleStateChange)
+setupBubbleEventFn(handleBubbleEvent)
 </script>
 
 <template>

packages/components/src/bubble/BubbleItem.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import Bubble from './Bubble.vue'
 import { setupBubbleMessageGroup } from './composables'
-import type { BubbleMessageGroup, BubbleProps, BubbleRoleConfig, BubbleSlots } from './index.type'
+import type { BubbleEvent, BubbleMessageGroup, BubbleProps, BubbleRoleConfig, BubbleSlots } from './index.type'
 
 const props = defineProps<{
   messageGroup: BubbleMessageGroup
@@ -14,6 +14,7 @@ defineSlots<BubbleSlots>()
 
 const emit = defineEmits<{
   (e: 'state-change', payload: { key: string; value: unknown; messageIndex: number; contentIndex: number }): void
+  (e: 'bubble-event', payload: BubbleEvent & { messageIndex: number; contentIndex: number }): void
 }>()
 
 // Provide messages for each BubbleItem instance
@@ -27,6 +28,7 @@ setupBubbleMessageGroup(() => props.messageGroup)
     :content-render-mode="contentRenderMode"
     :content-resolver="contentResolver"
     @state-change="emit('state-change', $event)"
+    @bubble-event="emit('bubble-event', $event)"
   >
     <template #prefix="slotProps">
       <slot name="prefix" v-bind="slotProps"></slot>