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

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,99 @@ Hooks：
     - `data.blocks` 当 type 为 'start-event' 时，包含本次发送的输入块
   - `result.userData` 返回的用户数据对象，会被合并后发送给 AI 平台
 
+### withBuildIn 插件
+
+提供了一些内置的功能，比如智能家居、知识库搜索等。
+
+**支持的技能**：
+
+- **智能家居**：设备控制、场景管理
+- **知识库搜索**：关联文档展示
+
+### withMCP 插件
+
+提供 MCP 服务暴露能力，可以实现让 Agent 调用小程序里面提供的 tool，实现操作蓝牙设备，调用自定义 api，读取本地文件等功能，使用时先需要在智能体节点上开启“设备 MCP”，此外，MCP tool 的名字必须以 `device.` 开头。
+
+![custom-var-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/custom-var-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 +945,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;
@@ -869,15 +974,6 @@ agent.plugins.aiStream.onUserDataRead((type, data, result) => {
 });
 ```
 
-### withBuildIn 插件
-
-提供了一些内置的功能，比如智能家居、知识库搜索等。
-
-**支持的技能**：
-
-- **智能家居**：设备控制、场景管理
-- **知识库搜索**：关联文档展示
-
 ## mock 机制
 
 为了方便开发，我们提供了一个 mock 机制，可以在开发时不用连接小程序 AI 智能体平台，直接使用 mock 数据进行开发。
@@ -927,6 +1023,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 +1303,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 +1385,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 +1474,12 @@ const MyTile = ({ notifyHeightChanged }) => {
 - bubble 气泡
 - buttons 按钮组
 - card 卡片
+- divider 分隔线
+- documents 关联文档
+- executeCard 执行结果卡片
+- file 文件
 - image 图片
+- operateCard 操作结果卡片
 - recommendations 推荐行动
 - text 文本，包含 markdown 支持
 - time 时间标识
@@ -1278,10 +1487,6 @@ const MyTile = ({ notifyHeightChanged }) => {
 - video 视频
 - workflow 工作选项
 
-### 内置 card
-
-- WorkflowReplyCard 工作流回复卡片
-
 ## React Hooks
 
 ### useChatAgent
@@ -1346,16 +1551,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 +1974,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 交互场景

package/README.md

@@ -28,6 +28,8 @@ yarn add @ray-js/t-agent @ray-js/t-agent-plugin-aistream @ray-js/t-agent-ui-ray
 }
 ```
 
+> When using MCP features, `AIStreamKit` must be version `2.2.1` or higher.
+
 ## package.json Dependency Requirements
 
 ```json
@@ -59,59 +61,70 @@ Implementing a chat page using ray UI
 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 {
-    // The order of applying plugins matters
-    const agent = createChatAgent(
-      withUI(), // The withUI plugin provides default UI behavior, essential
-      withAIStream({
-        // Connects to the mini-program AI agent platform, essential in mini-program
-        earlyStart: true, // Whether to establish connection during onAgentStart phase
-        agentId: '', // Enter your agent ID
-      }),
-      withDebug(), // Enables logging to the console
-      withBuildIn() // Provides built-in features
-    );
+  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()
+  );
 
-    // Lifecycle hooks for custom behavior registration
-    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',
+            },
+          },
+        },
+      };
+    }
+  });
 
-    // Initialize chat with a message
-    onChatStart(async result => {
-      const hello = createMessage({
-        role: 'assistant',
-      });
+  const { onChatStart, createMessage } = agent;
 
-      hello.bubble.setText('Hello, world!');
-      result.messages.push(hello);
-      // Persist message for display upon next entry
-      await hello.persist();
+  onChatStart(async result => {
+    const hello = createMessage({
+      role: 'assistant',
     });
 
-    // Message upon chat resume
-    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 />
@@ -785,6 +798,8 @@ Methods:
   - `options.sendBy` Sender role, defaults to 'user'
   - `options.responseBy` Responder role, defaults to 'assistant'
   - `options.userData` Optional user data
+- `agent.plugins.aiStream.removeMessage(message)` Delete a history message
+- `agent.plugins.aiStream.clearAllMessages()` Clear all messages and local history in the current session
 - `agent.plugins.aiStream.getChatId()` Get the current session's chatId, returns Promise<string>
 
 Hooks:
@@ -800,7 +815,7 @@ Hooks:
   - `status` Message status
   - `result.text` Text content, can be modified
 - `onSkillCompose` Triggered when receiving skill data, used for handling skill rendering
-  - `skill` Skill data array (ReceivedTextSkillPacketBody[])
+  - `skill` Current skill data (ReceivedTextSkillPacketBody)
   - `respMsg` Response message
   - `result.messages` Message list
 - `onSkillsEnd` Triggered when all skills processing is complete
@@ -821,8 +836,99 @@ Hooks:
     - `data.blocks` When type is 'start-event', contains the input blocks for this send
   - `result.userData` Returned user data object, will be merged and sent to the AI platform
 
+### withBuildIn Plugin
+
+Offers built-in features including smart home device control and knowledge base search.
+
+**Supported Skills**:
+
+- **Smart Home**: Device control and scene management
+- **Knowledge Base Search**: Related document display
+
+### withMCP Plugin
+
+Provides MCP service exposure capability so the Agent can call tools implemented inside the mini-program, such as operating Bluetooth devices, calling custom APIs, or reading local files. Before using it, enable "Device MCP" on the agent node. In addition, MCP tool names must start with `device.`.
+
+![custom-var-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/custom-var-config.jpg)
+
+**Prerequisites**:
+
+- Must be used after `withAIStream`
+- When using MCP features, `AIStreamKit` must be version `2.2.1` or higher
+- `createServer` must synchronously return `McpServer`
+
+Parameters:
+
+- `createServer(agent)` Create the MCP service instance
+- `createContext(event, agent)` Optional, append context for each MCP request
+
 **Usage Example**:
 
+```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: 'Echo input arguments',
+      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,
+      }),
+    })
+  );
+};
+```
+
+After being enabled, the plugin will:
+
+- Inject `sessionAttributes.deviceMcp` when creating a session
+- Call the corresponding tool when receiving an `MCP_CMD` event
+- Return the tool execution result to AIStream in JSON-RPC response format
+
+### Custom Variables
+
+In some cases, you may need to pass custom variables to the agent for use in the workflow. You need to configure the custom variable references in the workflow first, then pass the custom variables from the mini-program:
+
+![custom-var-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/custom-var-config.jpg)
+
+**Pass custom variables in the mini-program**:
+
 ```tsx
 const agent = createChatAgent(
   withUI(),
@@ -834,20 +940,28 @@ const agent = createChatAgent(
 agent.plugins.aiStream.onUserDataRead((type, data, result) => {
   // Pass user information when creating a session
   if (type === 'create-session') {
-    result.sessionAttributes = {
-      'custom.param': {
-        userName: { value: 'John' },
-        userLevel: { value: 'Plus' },
+    result.userData = {
+      sessionAttributes: {
+        'custom.param': {
+          'custom.app.test_me': {
+            // The parameter name configured on the platform
+            value: `with value test me ${type} ${Date.now()}`,
+          },
+        },
       },
     };
     return;
   }
-  // Pass dynamic context each time a message is sent
+  // Pass dynamic context every time a message is sent
   if (type === 'start-event') {
-    result.eventAttributes = {
-      'custom.param': {
-        timestamp: { value: Date.now() },
-        pid: { value: '123456' },
+    result.userData = {
+      sessionAttributes: {
+        'custom.param': {
+          'custom.app.test_me': {
+            // The parameter name configured on the platform
+            value: `with value test me ${type} ${Date.now()}`,
+          },
+        },
       },
     };
     return;
@@ -855,15 +969,6 @@ agent.plugins.aiStream.onUserDataRead((type, data, result) => {
 });
 ```
 
-### withBuildIn Plugin
-
-Offers built-in features including smart home device control and knowledge base search.
-
-**Supported Skills**:
-
-- **Smart Home**: Device control and scene management
-- **Knowledge Base Search**: Related document display
-
 ## Mock Mechanism
 
 To facilitate development, we offer a mock mechanism allowing mock data to be used without connecting to applet AI platforms.
@@ -913,6 +1018,92 @@ mock.hooks.hook('asrDetection', context => {
 });
 ```
 
+### mock MCP
+
+The recommended approach is to decide which MCP tool to call in the mock `sendToAIStream` hook based on the input content, then directly run the full MCP call chain with `context.callMCPTool()`.
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-aistream';
+
+const getToolCall = (text: string) => {
+  if (text.includes('error') || text.includes('failed') || text.includes('exception')) {
+    return {
+      name: 'device.home.energy.summary.fail',
+      arguments: {
+        reason: 'mock-error-case',
+      },
+    };
+  }
+
+  if (text.includes('energy') || text.includes('power') || text.includes('data')) {
+    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|app|energy|power|data|error|failed|exception/i.test(text)) {
+      return;
+    }
+
+    const toolCall = getToolCall(text);
+
+    await context.writeText(`MCP mock is calling ${toolCall.name}...`);
+
+    try {
+      const result = await context.callMCPTool(toolCall.name, toolCall.arguments, {
+        delayMs: 80,
+      });
+      await context.writeText(
+        `Tool ${toolCall.name} returned: ${
+          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 received a tool error: ${message}`);
+    }
+
+    await context.end();
+  });
+};
+```
+
+Register it once before creating the agent:
+
+```tsx
+const createAgent = () => {
+  setupMockMCP();
+
+  return createChatAgent(
+    withUI(),
+    withAIStream({
+      agentId: 'your-agent-id',
+    }),
+    withMCP({
+      createServer: () => server,
+    })
+  );
+};
+```
+
 ## Additional Utils Tools (Currently under development)
 
 ### AbortController
@@ -1791,33 +1982,3 @@ Below are the built-in multilingual keys:
 | t-agent.error.stream-exists                                | Error message                            | Message sending error, please try again later                                |
 | t-agent.error.timeout                                      | Error message                            | Send timeout                                                                 |
 | t-agent.error.asr-empty                                    | Error message                            | Speech recognition result is empty                                           |
-
-# Change Log
-
-## Version 0.2.x
-
-### @ray-js/t-agent
-
-- **Hook Mechanism Enhancement**: Added new lifecycle hooks such as `onMessageFeedback` and `onClearHistory`
-- **Message State Management**: Optimized message state management, providing more precise message state control
-- **Error Handling**: Enhanced error handling mechanism, supporting more detailed error information and error classification
-- **Performance Optimization**: Optimized memory management and garbage collection mechanisms
-
-### @ray-js/t-agent-plugin-aistream
-
-- **New Plugin**: Replaces the deprecated assistant plugin, providing more powerful functionality
-- **Connection Optimization**: Added `earlyStart` parameter, supporting early connection establishment to reduce first response time
-- **Token Management**: Optimized Token acquisition mechanism, supporting custom `tokenOptions`
-- **Speech Recognition**: Added AsrAgent speech recognition functionality, supporting real-time speech-to-text
-- **Mock Mechanism**: Improved mock mechanism, supporting more flexible testing scenarios
-- **Multi-modal Support**: Default support for various input types including text, images, and voice
-
-### @ray-js/t-agent-ui-ray
-
-- **Message Action Bar**: Added MessageActionBar component, supporting multi-select operations and batch deletion
-- **Virtual Scrolling**: Integrated LazyScrollView, providing virtual scrolling and performance optimization
-- **Internationalization System**: Complete internationalization system, supporting 8 languages including Simplified Chinese, Traditional Chinese, English, Japanese, etc.
-- **Translation Hook**: Added useTranslate Hook, simplifying multilingual usage
-- **Custom Rendering**: Extended renderOptions, supporting more custom rendering options
-- **Interaction Optimization**: Optimized long press menu functionality, supporting copy, delete, multi-select, like and other operations
-- **UI Enhancement**: Added multilingual key-value pairs, covering all UI interaction scenarios

package/dist/chat/ChatMessage.js

@@ -8,7 +8,8 @@ import "core-js/modules/web.dom-collections.iterator.js";
 import { ChatMessageStatus } from './types';
 import ChatTile from './ChatTile';
 import ChatBubbleTile from './ChatBubbleTile';
-import { deepCloneToPlainObject, deepMerge, generateId } from './utils';
+import { deepCloneToPlainObject, generateId } from './utils';
+import { deepmerge } from './deepmerge';
 import { getLogger } from './Logger';
 export const logger = getLogger('TAgent/ChatAgent');
 export default class ChatMessage {
@@ -146,7 +147,7 @@ export default class ChatMessage {
     if (override) {
       this.meta = meta;
     } else {
-      this.meta = deepMerge(this.meta, meta);
+      this.meta = deepmerge(this.meta, meta);
     }
     return this;
   }

package/dist/chat/deepmerge.d.ts

@@ -0,0 +1,27 @@
+type PlainObject = Record<string, unknown>;
+type PropertyKeyLike = string | symbol;
+type KeyGetter = (value: PlainObject) => PropertyKeyLike[];
+type IsMergeableObject = (value: unknown) => boolean;
+type CloneFn = <T>(value: T) => T;
+type DeepMergePairFn = <T, U>(target: T, source: U) => any;
+type DeepMergeFn = (...args: any[]) => any;
+type MergeArrayFn = (target: any[], source: any[]) => any[];
+type CloneProtoObjectFn = <T extends PlainObject>(target: T) => T;
+interface MergeArrayUtils {
+    clone: CloneFn;
+    deepmerge: DeepMergePairFn;
+    getKeys: KeyGetter;
+    isMergeableObject: IsMergeableObject;
+}
+interface DeepMergeOptions {
+    all?: boolean;
+    symbols?: boolean;
+    onlyDefinedProperties?: boolean;
+    cloneProtoObject?: CloneProtoObjectFn;
+    isMergeableObject?: IsMergeableObject;
+    mergeArray?: (utils: MergeArrayUtils) => MergeArrayFn;
+}
+declare function defaultIsMergeableObjectFactory(): IsMergeableObject;
+export declare function deepmergeConstructor(options?: DeepMergeOptions): DeepMergeFn;
+export declare const deepmerge: DeepMergeFn;
+export { defaultIsMergeableObjectFactory as isMergeableObject };

package/dist/chat/deepmerge.js

@@ -0,0 +1,141 @@
+import "core-js/modules/es.regexp.constructor.js";
+import "core-js/modules/es.regexp.dot-all.js";
+import "core-js/modules/es.regexp.exec.js";
+const JSON_PROTO = Object.getPrototypeOf({});
+function defaultIsMergeableObjectFactory() {
+  return function (value) {
+    return typeof value === 'object' && value !== null && !(value instanceof RegExp) && !(value instanceof Date);
+  };
+}
+export function deepmergeConstructor(options) {
+  function isNotPrototypeKey(value) {
+    return value !== 'constructor' && value !== 'prototype' && value !== '__proto__';
+  }
+  function cloneArray(value) {
+    let i = 0;
+    const il = value.length;
+    const result = new Array(il);
+    for (i; i < il; ++i) {
+      result[i] = clone(value[i]);
+    }
+    return result;
+  }
+  function cloneObject(target) {
+    const result = {};
+    if (cloneProtoObject && Object.getPrototypeOf(target) !== JSON_PROTO) {
+      return cloneProtoObject(target);
+    }
+    const targetKeys = getKeys(target);
+    let i;
+    let il;
+    let key;
+    for (i = 0, il = targetKeys.length; i < il; ++i) {
+      isNotPrototypeKey(key = targetKeys[i]) && (result[key] = clone(target[key]));
+    }
+    return result;
+  }
+  const propertyIsEnumerable = Object.prototype.propertyIsEnumerable;
+  const getKeys = options !== null && options !== void 0 && options.symbols ? function (value) {
+    const result = Object.keys(value);
+    const keys = Object.getOwnPropertySymbols(value);
+    for (let i = 0, il = keys.length; i < il; ++i) {
+      propertyIsEnumerable.call(value, keys[i]) && result.push(keys[i]);
+    }
+    return result;
+  } : value => Object.keys(value);
+  const cloneProtoObject = typeof (options === null || options === void 0 ? void 0 : options.cloneProtoObject) === 'function' ? options.cloneProtoObject : undefined;
+  const isMergeableObject = typeof (options === null || options === void 0 ? void 0 : options.isMergeableObject) === 'function' ? options.isMergeableObject : defaultIsMergeableObjectFactory();
+  const onlyDefinedProperties = (options === null || options === void 0 ? void 0 : options.onlyDefinedProperties) === true;
+  function isPrimitive(value) {
+    return typeof value !== 'object' || value === null;
+  }
+  const mergeArray = options && typeof options.mergeArray === 'function' ? options.mergeArray({
+    clone,
+    deepmerge: _deepmerge,
+    getKeys,
+    isMergeableObject
+  }) : function (target, source) {
+    const tl = target.length;
+    const sl = source.length;
+    let i = 0;
+    const result = new Array(tl + sl);
+    for (i; i < tl; ++i) {
+      result[i] = clone(target[i]);
+    }
+    for (i = 0; i < sl; ++i) {
+      result[i + tl] = clone(source[i]);
+    }
+    return result;
+  };
+  function clone(entry) {
+    return isMergeableObject(entry) ? Array.isArray(entry) ? cloneArray(entry) : cloneObject(entry) : entry;
+  }
+  function mergeObject(target, source) {
+    const result = {};
+    const targetKeys = getKeys(target);
+    const sourceKeys = getKeys(source);
+    let i;
+    let il;
+    let key;
+    for (i = 0, il = targetKeys.length; i < il; ++i) {
+      isNotPrototypeKey(key = targetKeys[i]) && sourceKeys.indexOf(key) === -1 && (result[key] = clone(target[key]));
+    }
+    for (i = 0, il = sourceKeys.length; i < il; ++i) {
+      if (!isNotPrototypeKey(key = sourceKeys[i])) {
+        continue;
+      }
+      if (key in target) {
+        if (targetKeys.indexOf(key) !== -1) {
+          if (cloneProtoObject && isMergeableObject(source[key]) && Object.getPrototypeOf(source[key]) !== JSON_PROTO) {
+            result[key] = cloneProtoObject(source[key]);
+          } else {
+            result[key] = _deepmerge(target[key], source[key]);
+          }
+        }
+      } else {
+        if (onlyDefinedProperties && typeof source[key] === 'undefined') {
+          continue;
+        }
+        result[key] = clone(source[key]);
+      }
+    }
+    return result;
+  }
+  function _deepmerge(target, source) {
+    if (onlyDefinedProperties && typeof source === 'undefined') {
+      return clone(target);
+    }
+    const sourceIsArray = Array.isArray(source);
+    const targetIsArray = Array.isArray(target);
+    if (isPrimitive(source)) {
+      return source;
+    }
+    if (!isMergeableObject(target)) {
+      return clone(source);
+    }
+    if (sourceIsArray && targetIsArray) {
+      return mergeArray(target, source);
+    }
+    if (sourceIsArray !== targetIsArray) {
+      return clone(source);
+    }
+    return mergeObject(target, source);
+  }
+  return options !== null && options !== void 0 && options.all ? function () {
+    switch (arguments.length) {
+      case 0:
+        return {};
+      case 1:
+        return clone(arguments.length <= 0 ? undefined : arguments[0]);
+      case 2:
+        return _deepmerge(arguments.length <= 0 ? undefined : arguments[0], arguments.length <= 1 ? undefined : arguments[1]);
+    }
+    let result = {};
+    for (let i = 0, il = arguments.length; i < il; ++i) {
+      result = _deepmerge(result, i < 0 || arguments.length <= i ? undefined : arguments[i]);
+    }
+    return result;
+  } : _deepmerge;
+}
+export const deepmerge = deepmergeConstructor();
+export { defaultIsMergeableObjectFactory as isMergeableObject };

package/dist/chat/index.d.ts

@@ -12,3 +12,4 @@ export { ChatAgent, ChatSession, StreamResponse, ChatTile, ChatBubbleTile, ChatM
 export * from './createChatAgent';
 export * from './types';
 export * from './json';
+export * from './deepmerge';

package/dist/chat/index.js

@@ -11,4 +11,5 @@ export { createHooks, Hookable } from 'hookable';
 export { ChatAgent, ChatSession, StreamResponse, ChatTile, ChatBubbleTile, ChatMessage, generateId, getLogger, Logger, Emitter, EmitterEvent, isAbortError, shuffleWithSeed };
 export * from './createChatAgent';
 export * from './types';
-export * from './json';
+export * from './json';
+export * from './deepmerge';

package/dist/chat/utils.d.ts

@@ -1,5 +1,4 @@
 export declare function generateId(length?: number): string;
 export declare function deepCloneToPlainObject(obj: any, visited?: WeakMap<object, any>): any;
-export declare function deepMerge(target: any, source: any): any;
 export declare function isAbortError(reason: any): any;
 export declare function shuffleWithSeed<T>(array: T[], seed: string): T[];

package/dist/chat/utils.js

@@ -86,29 +86,6 @@ export function deepCloneToPlainObject(obj) {
   }
   return clonedObj;
 }
-export function deepMerge(target, source) {
-  if (typeof target !== 'object' || target === null) {
-    return source; // 如果目标不是对象，直接返回来源
-  }
-  if (typeof source !== 'object' || source === null) {
-    return target; // 如果来源不是对象，返回目标
-  }
-  for (const key in source) {
-    if (Object.prototype.hasOwnProperty.call(source, key)) {
-      const sourceValue = source[key];
-      const targetValue = target[key];
-
-      // 如果是对象，递归合并
-      if (typeof sourceValue === 'object' && sourceValue !== null) {
-        target[key] = deepMerge(Array.isArray(targetValue) ? [] : targetValue || {}, sourceValue);
-      } else {
-        // 否则直接赋值
-        target[key] = sourceValue;
-      }
-    }
-  }
-  return target;
-}
 export function isAbortError(reason) {
   return reason && typeof Error !== 'undefined' && reason instanceof Error && reason.name === 'AbortError';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/t-agent",
-  "version": "0.2.7-beta.9",
+  "version": "0.2.8-beta.1",
   "author": "Tuya.inc",
   "license": "MIT",
   "private": false,
@@ -26,5 +26,5 @@
     "build": "ray build --type=component --output dist",
     "clean": "rimraf ./dist"
   },
-  "gitHead": "31a0d88f88eddae8bfd802e4861c76cd02c07692"
+  "gitHead": "040499ca11aedda3246121f880807da0f8af3cc9"
 }