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

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.`.
+
+![mcp-config.jpg](https://static1.tuyacn.com/static/txp-ray-TAgent/mcp-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/ChatBubbleTile.d.ts

@@ -29,7 +29,7 @@ export default class ChatBubbleTile extends ChatTile<BubbleTileData> {
         id: string;
         type: string;
         locked: boolean;
-        children: import("./types").ChatTileObject<any>[];
-        fallback?: import("./types").TipTileData | undefined;
+        children: import("./types").ChatTileObject[];
+        fallback?: import("./types").TipTileData;
     };
 }

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 {
@@ -65,7 +66,7 @@ export default class ChatMessage {
   show() {
     return this.agent.runWithCatchError(async () => {
       if (this._isShow) {
-        console.warn('message is already show');
+        logger.warn('message is already show');
         return;
       }
       await this.agent.hooks.callHook('onMessageChange:before', 'show', this);
@@ -78,7 +79,7 @@ export default class ChatMessage {
   update() {
     return this.agent.runWithCatchError(async () => {
       if (!this._isShow) {
-        console.warn('message is not show');
+        logger.warn('message is not show');
         return;
       }
       await this.agent.hooks.callHook('onMessageChange:before', 'update', this);
@@ -93,12 +94,13 @@ export default class ChatMessage {
   remove() {
     return this.agent.runWithCatchError(async () => {
       if (!this._isShow) {
-        console.warn('message is not show');
+        logger.warn('message is not show');
         return;
       }
       await this.agent.hooks.callHook('onMessageChange:before', 'remove', this);
       await this.agent.hooks.callHook('onMessageChange', 'remove', this);
       this.agent.session.unbindMessage(this);
+      this._isShow = false;
       await this.agent.hooks.callHook('onMessageChange:after', 'remove', this);
     });
   }
@@ -146,7 +148,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/ChatSession.d.ts

@@ -14,7 +14,7 @@ export default class ChatSession {
     constructor(agent: ChatAgent);
     initValue: (key: string, value: any) => void;
     set: (key: string, value: any) => Promise<void>;
-    get: <T = any>(key: string, defaultValue?: T | undefined) => any;
+    get: <T = any>(key: string, defaultValue?: T) => any;
     getData: () => Record<string, any>;
     initMessages: (messages: ChatMessage[]) => void;
     getTileById: (id: string) => ChatTile<any> | undefined;
@@ -22,7 +22,7 @@ export default class ChatSession {
     unbindTile: (tile: ChatTile) => void;
     bindMessage: (message: ChatMessage) => void;
     unbindMessage: (message: ChatMessage) => void;
-    onChange: (fn: ChatSessionHooks['onChange']) => () => void;
+    onChange: (fn: ChatSessionHooks["onChange"]) => () => void;
     getLatestMessage: () => ChatMessage | undefined;
     dispose: () => Promise<void>;
 }

package/dist/chat/ChatSession.js

@@ -100,10 +100,5 @@ export default class ChatSession {
     });
     this.agent = agent;
     this.hooks = createHooks();
-    const hooks = ['onChange'];
-    for (let i = 0; i < hooks.length; i++) {
-      const hook = hooks[i];
-      this[hook] = fn => this.hooks.hook(hook, fn);
-    }
   }
 }

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';