@ray-js/t-agent 0.2.7 → 0.2.8-beta.10

package/README-zh_CN.md

@@ -28,14 +28,7 @@ yarn add @ray-js/t-agent @ray-js/t-agent-plugin-aistream @ray-js/t-agent-ui-ray
 }
 ```
 
-### 小程序 kit 与功能对应表
-
-部分功能对 App 的 kit 有依赖要求，需要配置 AIStreamKit 最低才能使用这些功能
-
-| 功能       | AIStreamKit 最低版本 | 相关 API                              |
-| ---------- | -------------------- | ------------------------------------- |
-| 对话分组   | 1.3.2                | agent.plugins.aiStream.getChatId      |
-| 自定义参数 | 2.1.0                | agent.plugins.aiStream.onUserDataRead |
+> 使用 MCP 功能时，`AIStreamKit` 需要 `2.2.1` 或以上版本。
 
 ## package.json 依赖要求
 
@@ -68,59 +61,70 @@ yarn run miniapp
 import React from 'react';
 import { View } from '@ray-js/components';
 import { createChatAgent, withDebug, withUI } from '@ray-js/t-agent';
-import { ChatContainer, MessageInput, MessageList, MessageActionBar } from '@ray-js/t-agent-ui-ray';
+import {
+  ChatContainer,
+  defaultRenderOptions,
+  MessageInput,
+  MessageList,
+  MessageActionBar,
+} from '@ray-js/t-agent-ui-ray';
 import { withAIStream, withBuildIn } from '@ray-js/t-agent-plugin-aistream';
 
 const createAgent = () => {
-  try {
-    // 应用插件是有顺序的
-    const agent = createChatAgent(
-      withUI(), // 第一个插件 withUI 插件提供了一些默认的 UI 行为，必选
-      withAIStream({
-        // withAIStream 插件对接小程序 AI 智能体平台，在小程序中必选
-        earlyStart: true, // 是否在 onAgentStart 阶段就建立连接
-        agentId: '', // 输入你的智能体ID
-      }),
-      withDebug(), // withDebug 会在 console 里打印日志
-      withBuildIn() // withBuildIn 插件提供了一些内置的功能
-    );
+  const agent = createChatAgent(
+    withUI(),
+    withAIStream({
+      earlyStart: true,
+      agentId: 'your-agent-id',
+      tokenOptions: {
+        api: 'm.life.ai.agent.token.get',
+        version: '1.0',
+        extParams: {
+          dialogueMode: 1,
+        },
+      },
+    }),
+    withDebug(),
+    withBuildIn()
+  );
 
-    // 将生命周期钩子拿出来，方便注册自定义行为
-    const { onChatStart, createMessage, onChatResume, onError, onInputBlocksPush, session } = agent;
+  agent.plugins.aiStream.onUserDataRead((type, data, result) => {
+    if (type === 'start-event') {
+      result.userData = {
+        sessionAttributes: {
+          'custom.param': {
+            'custom.app.scene': {
+              value: 'chat-page',
+            },
+          },
+        },
+      };
+    }
+  });
 
-    // 初始化聊天时，发送一条消息
-    onChatStart(async result => {
-      const hello = createMessage({
-        role: 'assistant',
-      });
+  const { onChatStart, createMessage } = agent;
 
-      hello.bubble.setText('Hello, world!');
-      result.messages.push(hello);
-      // 持久化消息，下次进入时会展示
-      await hello.persist();
+  onChatStart(async result => {
+    const hello = createMessage({
+      role: 'assistant',
     });
 
-    // 恢复聊天时，发送一条消息
-    onChatResume(async result => {
-      const welcomeBack = createMessage({
-        role: 'assistant',
-      });
+    hello.bubble.setText('Hello, world!');
+    result.messages.push(hello);
+    await hello.persist();
+  });
 
-      welcomeBack.bubble.setText('Welcome back');
-      result.messages.push(welcomeBack);
-      await welcomeBack.persist();
-    });
-    return agent;
-  } catch (error) {
-    console.error('Agent creation failed:', error);
-    throw error;
-  }
+  return agent;
+};
+
+const renderOptions = {
+  ...defaultRenderOptions,
 };
 
 export default function ChatPage() {
   return (
     <View style={{ height: '100vh' }}>
-      <ChatContainer createAgent={createAgent}>
+      <ChatContainer createAgent={createAgent} renderOptions={renderOptions}>
         <MessageList />
         <MessageInput />
         <MessageActionBar />
@@ -799,6 +803,8 @@ const createAgent = () => {
   - `options.sendBy` 发送者角色，默认为 'user'
   - `options.responseBy` 响应者角色，默认为 'assistant'
   - `options.userData` 可选的用户数据
+- `agent.plugins.aiStream.removeMessage(message)` 删除一条历史消息
+- `agent.plugins.aiStream.clearAllMessages()` 清空当前会话的所有消息和本地历史
 - `agent.plugins.aiStream.getChatId()` 获取当前会话的 chatId，返回 Promise<string>
 
 Hooks：
@@ -814,7 +820,7 @@ Hooks：
   - `status` 消息状态
   - `result.text` 文本内容，可以修改
 - `onSkillCompose` 当收到技能数据时触发，用于处理技能的渲染
-  - `skill` 技能数据数组 (ReceivedTextSkillPacketBody[])
+  - `skill` 当前技能数据 (ReceivedTextSkillPacketBody)
   - `respMsg` 响应消息
   - `result.messages` 消息列表
 - `onSkillsEnd` 当所有技能处理完成时触发
@@ -835,8 +841,90 @@ Hooks：
     - `data.blocks` 当 type 为 'start-event' 时，包含本次发送的输入块
   - `result.userData` 返回的用户数据对象，会被合并后发送给 AI 平台
 
+### withMCP 插件
+
+提供 MCP 服务暴露能力，可以实现让 Agent 调用小程序里面提供的 tool，实现操作蓝牙设备，调用自定义 api，读取本地文件等功能，使用时先需要在智能体节点上开启“设备 MCP”，此外，MCP tool 的名字必须以 `device.` 开头。
+
+![mcp-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/mcp-config.jpg)
+
+**使用前提**：
+
+- 必须在 `withAIStream` 之后使用
+- 使用 MCP 功能时，`AIStreamKit` 需要 `2.2.1` 或以上版本
+- `createServer` 必须同步返回 `McpServer`
+
+参数：
+
+- `createServer(agent)` 创建 MCP 服务实例
+- `createContext(event, agent)` 可选，为每次 MCP 请求补充上下文
+
 **使用示例**：
 
+```tsx
+import { createChatAgent, withUI } from '@ray-js/t-agent';
+import { McpServer, withAIStream, withMCP } from '@ray-js/t-agent-plugin-aistream';
+
+const createAgent = () => {
+  const server = new McpServer({
+    name: 'demo-mcp',
+    version: '1.0.0',
+  });
+
+  server.registerTool(
+    'device.echo',
+    {
+      description: '回显输入参数',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          text: { type: 'string' },
+        },
+      },
+    },
+    async (args, context) => {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              text: args.text,
+              sessionId: context.sessionId,
+            }),
+          },
+        ],
+      };
+    }
+  );
+
+  return createChatAgent(
+    withUI(),
+    withAIStream({
+      agentId: 'your-agent-id',
+    }),
+    withMCP({
+      createServer: () => server,
+      createContext: event => ({
+        traceId: event.eventId,
+      }),
+    })
+  );
+};
+```
+
+启用后，插件会：
+
+- 在创建 session 时注入 `sessionAttributes.deviceMcp`
+- 在收到 `MCP_CMD` 事件时调用对应 tool
+- 将 tool 执行结果按 JSON-RPC 响应格式回传给 AIStream
+
+### 自定义变量传入
+
+某些情况下，你可能需要自定义变量到 agent 作为流程中的变量，你需要在工作流里配置自定义变量的引用处，然后再在小程序里传入自定义变量：
+
+![custom-var-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/custom-var-config.jpg)
+
+**小程序中传入自定义变量**：
+
 ```tsx
 const agent = createChatAgent(
   withUI(),
@@ -848,20 +936,28 @@ const agent = createChatAgent(
 agent.plugins.aiStream.onUserDataRead((type, data, result) => {
   // 在创建会话时传递用户信息
   if (type === 'create-session') {
-    result.sessionAttributes = {
-      'custom.param': {
-        userName: { value: 'John' },
-        userLevel: { value: 'Plus' },
+    result.userData = {
+      sessionAttributes: {
+        'custom.param': {
+          'custom.app.test_me': {
+            // 此处为平台上配置接收的参数名
+            value: `with value test me ${type} ${Date.now()}`,
+          },
+        },
       },
     };
     return;
   }
   // 在每次发送消息时传递动态上下文
   if (type === 'start-event') {
-    result.eventAttributes = {
-      'custom.param': {
-        timestamp: { value: Date.now() },
-        pid: { value: '123456' },
+    result.userData = {
+      sessionAttributes: {
+        'custom.param': {
+          'custom.app.test_me': {
+            // 此处为平台上配置接收的参数名
+            value: `with value test me ${type} ${Date.now()}`,
+          },
+        },
       },
     };
     return;
@@ -878,6 +974,65 @@ agent.plugins.aiStream.onUserDataRead((type, data, result) => {
 - **智能家居**：设备控制、场景管理
 - **知识库搜索**：关联文档展示
 
+#### 配置项
+
+```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 数据进行开发。
@@ -927,6 +1082,92 @@ mock.hooks.hook('asrDetection', context => {
 });
 ```
 
+### mock MCP
+
+推荐做法是在 mock 的 `sendToAIStream` 钩子里，根据输入内容决定要调用哪个 MCP tool，再通过 `context.callMCPTool()` 直接走一遍完整的 MCP 调用链。
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-aistream';
+
+const getToolCall = (text: string) => {
+  if (text.includes('报错') || text.includes('失败') || text.includes('异常')) {
+    return {
+      name: 'device.home.energy.summary.fail',
+      arguments: {
+        reason: 'mock-error-case',
+      },
+    };
+  }
+
+  if (text.includes('能耗') || text.includes('电量') || text.includes('数据')) {
+    return {
+      name: 'device.home.energy.summary.get',
+      arguments: {
+        period: 'today',
+      },
+    };
+  }
+
+  return {
+    name: 'device.app.open',
+    arguments: {
+      category: 'music',
+    },
+  };
+};
+
+export const setupMockMCP = () => {
+  mock.hooks.hook('sendToAIStream', async context => {
+    const text = context.data
+      .filter(item => item.type === 'text')
+      .map(item => item.text)
+      .join(' ');
+
+    if (!/mcp|应用|能耗|电量|数据|报错|失败|异常/i.test(text)) {
+      return;
+    }
+
+    const toolCall = getToolCall(text);
+
+    await context.writeText(`MCP mock 正在调用 ${toolCall.name}...`);
+
+    try {
+      const result = await context.callMCPTool(toolCall.name, toolCall.arguments, {
+        delayMs: 80,
+      });
+      await context.writeText(
+        `工具 ${toolCall.name} 已返回：${
+          typeof result === 'string' ? result : JSON.stringify(result == null ? {} : result)
+        }`
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await context.writeText(`MCP mock 已收到工具报错：${message}`);
+    }
+
+    await context.end();
+  });
+};
+```
+
+使用时在创建 agent 前注册一次即可：
+
+```tsx
+const createAgent = () => {
+  setupMockMCP();
+
+  return createChatAgent(
+    withUI(),
+    withAIStream({
+      agentId: 'your-agent-id',
+    }),
+    withMCP({
+      createServer: () => server,
+    })
+  );
+};
+```
+
 ## 附带的 utils 工具（现在不稳定，还在开发中）
 
 ### AbortController
@@ -1121,17 +1362,30 @@ yarn add @ray-js/t-agent-ui-ray
 ## 使用
 
 ```tsx
-import { ChatContainer, MessageList, MessageInput } from '@ray-js/t-agent-ui-ray';
+import React from 'react';
+import { View } from '@ray-js/components';
+import {
+  ChatContainer,
+  defaultRenderOptions,
+  MessageActionBar,
+  MessageInput,
+  MessageList,
+} from '@ray-js/t-agent-ui-ray';
 // createAgent 实现参见 t-agent 的使用示例
 import { createAgent } from './createAgent';
 
+const renderOptions = {
+  ...defaultRenderOptions,
+};
+
 export default function ChatPage() {
   // createAgent 必须返回一个 ChatAgent 应用过 withUI、withAIStream 插件的实例
   return (
     <View style={{ height: '100vh' }}>
-      <ChatContainer createAgent={createAgent}>
+      <ChatContainer createAgent={createAgent} renderOptions={renderOptions}>
         <MessageList />
         <MessageInput />
+        <MessageActionBar />
       </ChatContainer>
     </View>
   );
@@ -1190,7 +1444,16 @@ props:
 
 - `className` 输入框的类名
 - `placeholder` 输入框的占位符
+- `placeholderStyle` 输入框 placeholder 的样式
 - `renderTop` 用于渲染输入框上方的内容
+- `style` 输入框容器样式
+- `attachment` 是否启用附件上传，或传入 `{ image, video, imageCount, videoCount }` 精细控制
+- `maxTextLength` 文本最大长度，默认 200
+- `maxAudioMs` 录音最大时长
+- `onStateChange` 输入框状态变化回调，状态值见 `MessageInputState`
+- `amplitudeCount` 语音波形振幅采样数量
+
+`MessageInput` 当前默认导出的是 `MessageInputAIStream`，适用于已接入 `withAIStream` 的场景。
 
 ### MessageActionBar（0.2.x 新增）
 
@@ -1270,7 +1533,12 @@ const MyTile = ({ notifyHeightChanged }) => {
 - bubble 气泡
 - buttons 按钮组
 - card 卡片
+- divider 分隔线
+- documents 关联文档
+- executeCard 执行结果卡片
+- file 文件
 - image 图片
+- operateCard 操作结果卡片
 - recommendations 推荐行动
 - text 文本，包含 markdown 支持
 - time 时间标识
@@ -1278,10 +1546,6 @@ const MyTile = ({ notifyHeightChanged }) => {
 - video 视频
 - workflow 工作选项
 
-### 内置 card
-
-- WorkflowReplyCard 工作流回复卡片
-
 ## React Hooks
 
 ### useChatAgent
@@ -1346,16 +1610,23 @@ const MyTilePart = () => {
 
 ### useSendAction
 
-发送一个 TTTAction，注意只能在 tile 组件（或 card）里使用
+发送一个 TTTAction。
+
+如果当前组件位于 tile 或 card 内部，会优先走 `emitTileEvent`。
+如果当前组件只是 `ChatContainer` 下的普通子组件，则会退化为触发 UI 事件 `runTTTAction`。
 
 ```tsx
 import { useSendAction } from '@ray-js/t-agent-ui-ray';
 
-const MyTilePart = () => {
+const ActionPanel = () => {
   const sendAction = useSendAction();
 
   const handleClick = () => {
-    sendAction({ type: 'sendMessage', blocks: [{ type: 'text', text: 'hello' }] });
+    sendAction({
+      type: 'sendMessage',
+      blocks: [{ type: 'text', text: 'hello' }],
+      sendImmediately: true,
+    });
   };
 
   return <button onClick={handleClick}>Send Message</button>;
@@ -1762,33 +2033,3 @@ const renderOptions = {
 | t-agent.error.stream-exists                                | 错误提示                    | 消息发送异常，请稍后再试                 |
 | t-agent.error.timeout                                      | 错误提示                    | 发送超时                                 |
 | t-agent.error.asr-empty                                    | 错误提示                    | 语音识别结果为空                         |
-
-# 更新日志
-
-## 0.2.x 版本
-
-### @ray-js/t-agent
-
-- **Hook 机制增强**：新增 `onMessageFeedback` 和 `onClearHistory` 等生命周期钩子
-- **消息状态管理**：优化消息状态管理，提供更精确的消息状态控制
-- **错误处理**：增强错误处理机制，支持更详细的错误信息和错误分类
-- **性能优化**：优化内存管理和垃圾回收机制
-
-### @ray-js/t-agent-plugin-aistream
-
-- **全新插件**：替代废弃的 assistant 插件，提供更强大的功能
-- **连接优化**：新增 `earlyStart` 参数，支持提前建立连接，减少首次响应时间
-- **Token 管理**：优化 Token 获取机制，支持自定义 `tokenOptions`
-- **语音识别**：新增 AsrAgent 语音识别功能，支持实时语音转文字
-- **Mock 机制**：改进的 mock 机制，支持更灵活的测试场景
-- **多模态支持**：默认支持文本、图片、语音等多种输入类型
-
-### @ray-js/t-agent-ui-ray
-
-- **消息操作栏**：新增 MessageActionBar 组件，支持多选操作和批量删除
-- **虚拟滚动**：集成 LazyScrollView，提供虚拟滚动和性能优化
-- **国际化系统**：完整的国际化系统，支持中文简繁体、英文、日文等 8 种语言
-- **翻译 Hook**：新增 useTranslate Hook，简化多语言使用
-- **自定义渲染**：扩展 renderOptions，支持更多自定义渲染选项
-- **交互优化**：优化长按菜单功能，支持复制、删除、多选、点赞等操作
-- **UI 完善**：新增多语言键值对，覆盖所有 UI 交互场景