@ray-js/t-agent 0.2.8-beta.2 → 0.2.8-beta.4

package/README-zh_CN.md

@@ -841,15 +841,6 @@ Hooks：
     - `data.blocks` 当 type 为 'start-event' 时，包含本次发送的输入块
   - `result.userData` 返回的用户数据对象，会被合并后发送给 AI 平台
 
-### withBuildIn 插件
-
-提供了一些内置的功能，比如智能家居、知识库搜索等。
-
-**支持的技能**：
-
-- **智能家居**：设备控制、场景管理
-- **知识库搜索**：关联文档展示
-
 ### withMCP 插件
 
 提供 MCP 服务暴露能力，可以实现让 Agent 调用小程序里面提供的 tool，实现操作蓝牙设备，调用自定义 api，读取本地文件等功能，使用时先需要在智能体节点上开启“设备 MCP”，此外，MCP tool 的名字必须以 `device.` 开头。
@@ -974,6 +965,74 @@ agent.plugins.aiStream.onUserDataRead((type, data, result) => {
 });
 ```
 
+### withBuildIn 插件
+
+提供了一些内置的功能，比如智能家居、知识库搜索等。
+
+**支持的技能**：
+
+- **智能家居**：设备控制、场景管理
+- **知识库搜索**：关联文档展示
+
+#### 配置项
+
+```tsx
+withBuildIn({
+  // 是否默认开启 TTS 自动播放，默认 false
+  audioAutoPlay: true,
+});
+```
+
+#### TTS 语音播放
+
+当 `withAIStream({ enableTts: true })` 开启后，服务端会随消息下发 TTS 音频包。`withBuildIn` 会消费这些音频包并提供完整的播放能力：
+
+- **自动播放**：音频流开始（`StreamFlag.START`）时，若 `AIStream.audioAutoPlay` 为 `true`，则自动播放。
+- **气泡播放按钮**：音频流结束后，会在对应气泡里插入一个 `bubbleTool` tile（语音播放 / 复制按钮）。播放参数（`path` / `codecType` / `sampleRate` / `channels` / `bitDepth` / `pts`）会按音频流 id 聚合后写入 tile，点击即可重新播放。
+- **单条互斥**：同一时刻只播放一条，开始新播放或主动停止时会先停掉当前播放。
+- **播放生命周期**：监听底层 `onAudioPlayChanged`，在播放完成 / 异常时自动复位播放状态。
+
+**对外暴露的 session 状态**（均通过 `sessionChange` 事件广播，UI 侧可用 `useAgentSessionValue` 订阅并派生组件状态）：
+
+| key                         | 类型             | 说明                  |
+| --------------------------- | ---------------- | --------------------- |
+| `AIStream.audioAutoPlay`    | `boolean`        | 是否开启 TTS 自动播放 |
+| `AIStream.audioPlaying`     | `boolean`        | 当前是否正在播放      |
+| `AIStream.playingMessageId` | `string \| null` | 正在播放的消息 id     |
+
+**对外暴露的 UI 事件**：
+
+| 事件名          | 说明                                     |
+| --------------- | ---------------------------------------- |
+| `audioPlayStop` | 主动停止当前播放（不论是否开启自动播放） |
+
+示例：在页面顶部做一个三态（播放中 / 自动播放 / 静音）切换按钮：
+
+```tsx
+import { useAgentSessionValue, useEmitEvent } from '@ray-js/t-agent-ui-ray';
+
+function AudioToggle() {
+  const [audioAutoPlay, setAudioAutoPlay] = useAgentSessionValue<boolean>('AIStream.audioAutoPlay');
+  const [audioPlaying] = useAgentSessionValue<boolean>('AIStream.audioPlaying');
+  const emitEvent = useEmitEvent();
+
+  const onClick = () => {
+    if (audioPlaying) {
+      // 播放中：点击立刻停止播放，不论是否静音
+      emitEvent('audioPlayStop', undefined);
+      return;
+    }
+    // 否则切换自动播放 / 静音
+    setAudioAutoPlay(prev => !prev);
+  };
+
+  const label = audioPlaying ? '🎵 播放中' : audioAutoPlay ? '🔊 自动播放' : '🔇 静音';
+  return <View onClick={onClick}>{label}</View>;
+}
+```
+
+> 组件内的 `playing` 状态应从 session 派生（如 `audioPlaying && playingMessageId === message.id`），不要在 tile 内部维护本地播放状态，避免被持久化或与全局状态不一致。
+
 ## mock 机制
 
 为了方便开发，我们提供了一个 mock 机制，可以在开发时不用连接小程序 AI 智能体平台，直接使用 mock 数据进行开发。