@ray-js/t-agent-ui-ray 0.2.5-beta-1 → 0.2.5-beta-3

package/README.md

@@ -1,12 +1,1770 @@
-# @ray-js/t-agent-ui-ray
+# AI Agent SDK
 
-> AI Agent SDK  
-> For detailed documentation, see @ray-js/t-agent
+## Version Notes
+
+**⚠️ Important Notice**: Starting from version 0.2.x, `@ray-js/t-agent-plugin-assistant` has been deprecated. Please use `@ray-js/t-agent-plugin-aistream` instead.
+
+## Installation (ray mini-program)
+
+```shell
+yarn add @ray-js/t-agent @ray-js/t-agent-plugin-aistream @ray-js/t-agent-ui-ray
+```
+
+> Ensure that the versions of `@ray-js/t-agent`, `@ray-js/t-agent-plugin-aistream`, and `@ray-js/t-agent-ui-ray` are consistent.
+
+## Mini-Program Kit Requirements
+
+```json
+{
+  "dependencies": {
+    "BaseKit": "3.12.0",
+    "BizKit": "4.10.0",
+    "DeviceKit": "4.6.1",
+    "HomeKit": "3.4.0",
+    "MiniKit": "3.12.1",
+    "AIStreamKit": "1.0.0"
+  },
+  "baseversion": "2.21.10"
+}
+```
+
+## package.json Dependency Requirements
+
+```json
+{
+  "dependencies": {
+    "@ray-js/ray": ">=1.6.8"
+  }
+}
+```
+
+## Development
+
+```shell
+# Develop the SDK
+yarn run dev
+
+# Develop the template mini-program
+yarn run miniapp
+```
+
+## Usage Example
+
+Implementing a chat page using ray UI
+
+![ChatPage1](https://static1.tuyacn.com/static/txp-ray-TAgent/ChatPage1.png)
+
+```tsx
+// ChatPage.tsx
+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 { 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
+        enableTts: false, // Whether to enable Text-to-Speech
+        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
+    );
+
+    // Lifecycle hooks for custom behavior registration
+    const { onChatStart, createMessage, onChatResume, onError, onInputBlocksPush, session } = agent;
+
+    // Initialize chat with a message
+    onChatStart(async result => {
+      const hello = createMessage({
+        role: 'assistant',
+      });
+
+      hello.bubble.setText('Hello, world!');
+      result.messages.push(hello);
+      // Persist message for display upon next entry
+      await hello.persist();
+    });
+
+    // Message upon chat resume
+    onChatResume(async result => {
+      const welcomeBack = createMessage({
+        role: 'assistant',
+      });
+
+      welcomeBack.bubble.setText('Welcome back');
+      result.messages.push(welcomeBack);
+      await welcomeBack.persist();
+    });
+    return agent;
+  } catch (error) {
+    console.error('Agent creation failed:', error);
+    throw error;
+  }
+};
+
+export default function ChatPage() {
+  return (
+    <View style={{ height: '100vh' }}>
+      <ChatContainer createAgent={createAgent}>
+        <MessageList />
+        <MessageInput />
+        <MessageActionBar />
+      </ChatContainer>
+    </View>
+  );
+}
+```
+
+# t-agent
+
+The t-agent package, crafted in TypeScript, is a dialogue agent SDK for building feature-rich dialogue interactions, supporting plugins to enhance functionality. As a pure SDK, it doesn't contain UI components, allowing flexibility to work with any framework.
+
+## Basic Concepts
+
+![flow.png](https://static1.tuyacn.com/static/txp-ray-TAgent/flow-en.png)
+
+### ChatAgent Dialogue Agent
+
+The core class handles the dialogue lifecycle, message creation, persistence, and supports plugins and hooks to extend functionality.
+
+Create a ChatAgent instance using `createChatAgent`:
+
+```tsx
+import { createChatAgent } from '@ray-js/t-agent';
+const createAgent = () => {
+  /* Apply plugins in the createChatAgent function. Plugin order matters. */
+  const agent = createChatAgent();
+
+  return agent;
+};
+```
+
+Core Attributes:
+
+- `agent.session` ChatSession container for session data
+- `agent.plugins` Contains applied plugins' methods and hooks
+
+Core Methods:
+
+- `agent.start()` Activates the agent
+- `agent.dispose()` Deactivates the agent
+- `agent.pushInputBlocks(blocks, signal)` Pushes user messages to ChatAgent
+- `agent.createMessage(data)` Creates a message linked to the agent
+- `agent.emitTileEvent(tileId: string, payload: any)` Emits tile events
+- `agent.removeMessage(messageId: string)` Removes messages
+- `agent.flushStreamToShow(message: ChatMessage, response: StreamResponse, composer: ComposeHandler)` Handles stream updates
+
+### Hooks Mechanism
+
+ChatAgent implements a framework and data structure. Behavioral details are executed using a hook-driven, event-model approach by registering specific callbacks.
+
+```tsx
+import { createChatAgent } from '@ray-js/t-agent';
+const createAgent = () => {
+  const agent = createChatAgent();
+
+  const { onChatStart } = agent;
+
+  // onChatStart Hook triggers on dialogue start
+  onChatStart(result => {
+    console.log('Chat start', result);
+  });
+  return agent;
+};
+```
+
+#### Hook Execution Order
+
+Hooks are executed in the following order:
+
+```
+onAgentStart → onChatStart/onChatResume → onMessageListInit → onInputBlocksPush
+```
+
+ChatAgent's Central Hooks and Parameters:
+
+- `agent.onAgentStart` Agent initialization
+- `agent.onChatStart` Triggered at dialogue initiation
+  - `result.messages` Initializes message lists
+- `agent.onChatResume` Triggered on dialogue continuation
+  - `result.messages` Restored message lists
+- `agent.onMessageListInit` On message list initialization
+  - `result.messages` Rendering message list, same list as the previous two hooks
+- `agent.onInputBlocksPush` On message block input
+  - `blocks` Input message blocks
+  - `signal` Interrupt signal
+- `agent.onMessageChange` On message updates
+  - `type` Update types: `show`, `update`, `remove`
+  - `message` Updated message instance
+- `agent.onMessagePersist` At message persistence
+  - `payload` Persistence parameters
+  - `message` The message to persist
+- `agent.onTileEvent` After message persistence
+  - `tile` Event-triggering tile
+  - `payload` Event data
+- `agent.onAgentDispose` On agent disposal
+- `agent.onUserAbort` On user interruption
+  - `reason` Interruption reason
+- `agent.onError` On error occurrence
+  - `error` Error details
+
+These hooks accept a callback parameter, invoked upon their criteria. Callbacks can be synchronous or asynchronous. To modify results, adjust the result parameter or message object directly.
+
+### ChatSession Session Container
+
+ChatSession holds message lists, session-related data along with intelligent interactions, generated alongside ChatAgent.
+
+Main Properties:
+
+- `session.messages` List of messages
+- `session.sessionId` Unique session ID
+- `session.isNewChat` To distinguish fresh or ongoing chats
+
+Principal Methods:
+
+- `session.set` Assign session data (any type)
+- `session.get` Retrieve session data
+- `session.getData` Fetch session data in object format
+- `session.getLatestMessage` Access the latest message
+
+Hook:
+
+- `session.onChange` Register for session data updates
+
+### ChatMessage Dialogue Message
+
+An abstraction representing each dialogue's content, status with utility methods for message control. Composed of multiple ChatTiles for varied display elements.
+
+Creating a Message with `createMessage`:
+
+```tsx
+const createAgent = () => {
+  const agent = createChatAgent();
+
+  const { createMessage, onChatStart } = agent;
+
+  // Initialize chat with an assistant's message
+  onChatStart(async result => {
+    const message = createMessage({
+      role: 'assistant',
+    });
+
+    // Quickly create text bubble
+    message.bubble.setText('Hello!');
+    result.messages.push(message);
+  });
+
+  return agent;
+};
+```
+
+Core Properties:
+
+- `message.id` Unique message identifier
+- `message.role` Either assistant or user
+- `message.tiles` List of message tiles
+- `message.status` Message state, `ChatMessageStatus` enum: `START`, `UPDATING`, `FINISH`
+- `message.meta` Supplementary data
+- `message.isShow` Display status
+- `message.bubble` Shortcut for bubble tile
+
+Key Methods:
+
+- `message.show` Display message
+- `message.update` Refresh current message
+- `message.remove` Delete current message
+- `message.persist` Save message
+- `message.addTile` Add a tile
+- `message.removeTile` Delete a tile
+- `message.setTilesLocked` Lock/unlock all tiles
+- `message.set` Configure message attributes
+- `message.setMetaValue` Assign meta attribute by key
+- `message.deleteMetaValue` Remove meta attribute
+- `message.setMeta` Comprehensive meta object assignment
+- `message.findTileByType` Locate tile by type
+
+#### ChatTile Dialogue Message Block
+
+ChatTiles render specific content types fairly like text, images, and cards.
+
+Adding a Tile with `addTile`:
+
+```tsx
+const message = createMessage({
+  role: 'assistant',
+});
+
+// Introduce an image tile
+message.addTile('image', {
+  src: '/image.jpg',
+});
+
+await message.show();
+```
+
+Chief Attributes of ChatTile:
+
+- `tile.id` Tile's identifier
+- `tile.type` Type of tile
+- `tile.data` Content held by tile
+- `tile.children` Nested tiles
+- `tile.locked` Tile lock status
+- `tile.fallback` Alternative content for non-displayed tile
+- `tile.message` Parent message of tile
+
+Primary Methods of ChatTile:
+
+- `tile.update` Equivalent to `tile.message.update`
+- `tile.show` Synonymous with `tile.message.show`
+- `tile.setLocked` Adjust tile's lock status
+- `tile.addTile` Add a sub-tile
+- `tile.setData` Update tile content
+- `tile.setFallback` Update fallback content
+- `tile.findByType` Locate sub-tile by type
+
+Accessing `message.bubble` enables swift bubble tile addition:
+
+```tsx
+const message = createMessage({
+  role: 'assistant',
+});
+
+message.bubble.setText('Hello, world!');
+// Equivalent to
+message.addTile('bubble', {}).addTile('text', { text: 'Hello, world!' });
+
+await message.show();
+```
+
+For bubble messages, additional properties and methods include:
+
+- `message.bubble.text` Reads bubble text
+- `message.bubble.setText` Assigns bubble text
+- `message.bubble.isMarkdown` Determines markdown formatting
+- `message.bubble.setIsMarkdown` Sets markdown format
+- `message.bubble.status` Indicates bubble status
+- `message.bubble.setStatus` Defines bubble status
+- `message.bubble.info` Relays bubble info
+- `message.bubble.setInfo` Configures bubble info
+- `message.bubble.initWithInputBlocks` Initializes bubble with input blocks
+
+**Bubble messages support long press operations**, allowing for copy and delete functions, and animations will be displayed during message loading and updating.
+
+Bubble messages support the following long press operations:
+
+- Copy: Copy the message text content
+- Delete: Delete the current message
+
+### Lifecycle
+
+ChatAgent phases trigger hooks enabling developers to integrate custom behavior efficiently. Below is the lifecycle depiction:
+
+```mermaid
+sequenceDiagram
+  participant AI as Backend(AI)
+  participant A as ChatAgent
+  participant UI as UI Interface
+  actor User as User
+
+  User ->> UI: Open chat interface
+  UI ->> UI: Create Agent object agent
+  UI ->> A: agent.start() Start Agent
+  rect rgba(255,255,0,0.1)
+    note over A: Hook: onAgentStart
+    A ->> AI: Check if new session
+    AI ->> A: Return
+  end
+  alt Is new session
+    A ->> AI: Start a new session
+    note over A: Hook: onChatStart
+  else Is resume session
+    A ->> AI: Read session history
+    AI ->> A: Return history messages
+    note over A: Hook: onChatResume
+  end
+  rect rgba(255,255,0,0.1)
+    note over A: Hook: onMessageListInit
+    A ->> UI: Assemble messages to display
+    UI ->> User: Display messages
+  end
+  opt Conversation
+    User ->> UI: Enter and send message
+    UI ->> A: agent.pushInputBlocks()
+    rect rgba(255,255,0,0.1)
+      note over A: Hook: onInputBlocksPush
+      A ->> A: Create Message object msg<br/>Set msg as user's input text<br/>msg.show()
+      note over A: Hook: onMessageChange show
+      A -->> UI: Update interface
+      UI -->> User: Display new message
+      A ->> A: Create Message object respMsg<br/>Set respMsg as "loading"<br/>respMsg.show()
+      note over A: Hook: onMessageChange show
+      A -->> UI: Update interface
+      UI -->> User: Display loading message
+      A ->> AI: Invoke AI
+      AI ->> A: Return message stream
+      loop Streaming messages
+        AI ->> A: Message packet
+        A ->> A: Update respMsg data<br/>respMsg.update()
+        note over A: Hook: onMessageChange update
+        A -->> UI: Update interface
+        UI -->> User: Display typing effect/card
+      end
+    end
+   end
+
+    opt Operate message action points (e.g., single selection)
+       User ->> UI: Select option
+       UI ->> A: agent.emitTileEvent()
+       rect rgba(255,255,0,0.1)
+          note over A: Hook: onTileEvent
+          A ->> A: Set msg status<br/>msg.persist()
+          note over A: Hook: onMessagePersist
+          A ->> AI: Persist message
+          AI ->> A: Return result
+          A ->> A: msg.update()
+          note over A: Hook: onMessageChange update
+          A ->> UI: Update interface
+          UI ->> User: Message greyed out, highlight selection
+       end
+    end
+    opt Delete message
+       User ->> UI: Delete message
+       UI ->> A: agent.removeMessage()
+       rect rgba(255,255,0,0.1)
+          A ->> A: msg.remove()
+          A ->> AI: Mark message deleted
+          note over A: Hook: onMessageChange remove
+          A ->> UI: Update interface
+          UI ->> User: Message disappears
+       end
+    end
+```
+
+### Plugin Mechanism
+
+Plugins are implemented based on the above Hook mechanism and can enhance the functionality of chat agents, such as interfacing with AI platforms, providing UI interfaces, etc. Plugins can also expose methods and properties for developers to use.
+
+```tsx
+import { createChatAgent, withUI } from '@ray-js/t-agent';
+const createAgent = () => {
+  const agent = createChatAgent(
+    withUI() // withUI plugin provides methods for rendering UI
+  );
+
+  return agent;
+};
+
+// ScrollToBottom.tsx
+import React from 'react';
+import { Button } from '@ray-js/components';
+import { useChatAgent } from '@ray-js/t-agent-ui-ray';
+const ScrollToBottom = () => {
+  const agent = useChatAgent();
+
+  const scroll = () => {
+    // Use methods exposed by the plugin
+    agent.plugins.ui.emitEvent('scrollToBottom', { animation: false });
+  };
+
+  return <Button onClick={scroll}>Scroll to bottom</Button>;
+};
+```
+
+#### Writing a Plugin
+
+A plugin is a higher-order function that takes options and returns a function. This function receives a ChatAgent object, within which hooks can be registered.
+
+```tsx
+import { ChatAgent, createHooks, Hookable } from '@ray-js/t-agent';
+
+// Implementing MyPlugin
+export type MyPlugin = GetChatPluginHandler<typeof withMyPlugin>;
+
+export const withMyPlugin = (options: any) => {
+  // Create a Hookable object
+  const hooks = createHooks();
+
+  return (agent: ChatAgent) => {
+    const { onChatStart } = agent;
+
+    onChatStart(async () => {
+      console.log('Chat start');
+      // Trigger plugin hook
+      await hooks.callHook('onMyHook', 'Hello, world!');
+    });
+
+    // Expose plugin methods and hooks
+    return {
+      hooks,
+      myPlugin: {
+        // Expose a method
+        myMethod() {
+          console.log('My method');
+        },
+        // Expose a hook
+        onMyHook: fn => {
+          return hooks.hook('onMyHook', fn);
+        },
+      },
+    };
+  };
+};
+```
+
+```tsx
+// Using the plugin
+import { createChatAgent } from '@ray-js/t-agent';
+
+const createAgent = () => {
+  const agent = createChatAgent(
+    // Use the plugin
+    withMyPlugin({})
+  );
+
+  // Call methods exposed by the plugin
+  agent.plugins.myPlugin.myMethod();
+
+  // Register plugin hooks
+  agent.plugins.myPlugin.onMyHook(msg => {
+    console.log(msg);
+  });
+
+  return agent;
+};
+```
+
+## Built-in Plugins
+
+### withDebug
+
+The withDebug plugin logs messages to the console for easy debugging.
+
+```tsx
+const agent = createChatAgent(
+  withDebug({
+    autoStart: true, // Whether to start automatically, default is true
+  })
+);
+
+// Start
+agent.plugins.debug.start();
+
+// Stop
+agent.plugins.debug.stop();
+```
+
+### withUI
+
+The withUI plugin provides default UI behaviors such as message display, message deletion, etc., and a message bus.
+
+```tsx
+const agent = createChatAgent(withUI());
+
+agent.plugins.ui.emitter; // Message bus
+
+// Scroll to bottom
+agent.plugins.ui.emitEvent('scrollToBottom', { animation: false });
+
+// Listen to events
+const off = agent.plugins.ui.onEvent('scrollToBottom', payload => {
+  console.log('scroll to bottom', payload.animation);
+});
+
+// Unlisten to events
+off();
+```
+
+The main events of the UI plugin are as follows, and you can freely register additional events you need:
+
+- `messageListInit`: Initialize the message list
+  - `payload.messages: ChatMessageObject[]`: Message list
+- `messageChange`: Message changes
+  - `payload.type: 'show' | 'update' | 'remove'`: Change type
+  - `payload.message: ChatMessageObject`: Message
+- `scrollToBottom`: Scroll to bottom
+  - `payload.animation: boolean`: Whether to use animation
+- `sendMessage`: Send message, triggering UI update
+  - `payload.blocks: InputBlock[]`: Input blocks
+- `setInputBlocks`: Set input blocks in MessageInput
+  - `payload.blocks: InputBlock[]`: Input blocks
+- `sessionChange`: Session data changes
+  - `payload.key: string`: Session key
+  - `payload.value: any`: Session value
+  - `payload.oldValue: any`: Old session value
+
+Enhanced Features in withUI Plugin (0.2.x):
+
+withUI plugin in version 0.2.x introduces Hook mechanisms for customizing message feedback and history clearing behavior:
+
+**Message Feedback Hook**:
+
+- `agent.plugins.ui.hook('onMessageFeedback', async context => {})` Register message feedback Hook
+  - `context.payload.messageId: string` Message ID
+  - `context.payload.rate: 'like' | 'unlike'` Feedback type
+  - `context.payload.content?: string` Feedback content (optional)
+  - `context.result: { success: boolean }` Return result, need to set success status
+
+**Clear History Hook**:
+
+- `agent.plugins.ui.hook('onClearHistory', async context => {})` Register clear history Hook
+  - `context.payload: any` Clear history parameters
+  - `context.result: { success: boolean }` Return result, need to set success status
+
+**Calling Hooks**:
+
+- `agent.plugins.ui.callHook('onMessageFeedback', payload)` Call message feedback Hook
+- `agent.plugins.ui.callHook('onClearHistory', payload)` Call clear history Hook
+
+Usage example:
+
+```tsx
+const agent = createChatAgent(withUI(), withAIStream({ agentId: 'your-agent-id' }));
+
+// Register message feedback handler
+agent.plugins.ui.hook('onMessageFeedback', async context => {
+  const { messageId, rate, content } = context.payload;
+  try {
+    // Call your API to submit feedback
+    await submitFeedback({ messageId, rate, content });
+    context.result = { success: true };
+  } catch (error) {
+    context.result = { success: false };
+  }
+});
+
+// Register clear history handler
+agent.plugins.ui.hook('onClearHistory', async context => {
+  try {
+    // Call your API to clear history
+    await clearChatHistory();
+    context.result = { success: true };
+  } catch (error) {
+    context.result = { success: false };
+  }
+});
+```
+
+> Note: `ChatMessageObject` here is a message object, not a `ChatMessage` type.
+> It contains various attributes and methods to ensure changes are made in the ChatAgent, avoiding conflicts with the UI layer.
+
+## Included utils
+
+### getLogger(prefix: string): Logger
+
+Create a logger for logging messages.
+
+```tsx
+import { getLogger } from '@ray-js/t-agent';
+const logger = getLogger('MyPlugin');
+logger.debug('Hello, world!');
+```
+
+### Emitter
+
+Emitter is an event bus for registering and triggering events.
+
+```tsx
+import { Emitter, EmitterEvent } from '@ray-js/t-agent';
+const emitter = new Emitter();
+
+// Register event
+const cb = event => console.log('detail', event.detail);
+emitter.addEventListener('event', cb);
+
+// Trigger event
+emitter.dispatchEvent(new EmitterEvent('event', { detail: 'Hello, world!' }));
+
+// Remove event
+emitter.removeEventListener('event', cb);
+```
+
+### StreamResponse
+
+StreamResponse is a streaming response object for handling streaming messages.
+
+```tsx
+import { StreamResponse } from '@ray-js/t-agent';
+
+const partStream = await getPartStream(); // Obtain stream data
+const response = new StreamResponse(partStream);
+
+const parts = response.parts();
+for await (const part of parts) {
+  console.log('part', part);
+}
+```
+
+### createHooks, Hookable
+
+Refer to the `hookable` npm package for more details.
+
+### isAbortError
+
+Determine if it is an abort error.
+
+### safeParseJSON
+
+Safely parse JSON strings, returning `undefined` on failure.
+
+```tsx
+import { safeParseJSON } from '@ray-js/t-agent';
+
+const obj = safeParseJSON<{ a: number }>('{"a": 1}');
+
+console.log(obj.a); // 1
+```
+
+# t-agent-plugin-aistream
+
+t-agent-plugin-aistream is a plugin designed for integration with applet AI agent platforms, offering capabilities to connect to these platforms.
 
 ## Installation
 
-```sh
-$ npm install @ray-js/t-agent-ui-ray
-// or
-$ yarn add @ray-js/t-agent-ui-ray
+```shell
+yarn add @ray-js/t-agent-plugin-aistream
+```
+
+## Usage
+
+```tsx
+import { createChatAgent, withUI } from '@ray-js/t-agent';
+import { withAIStream, withBuildIn } from '@ray-js/t-agent-plugin-aistream';
+
+const createAgent = () => {
+  const agent = createChatAgent(
+    withUI(), // Typically, the withUI plugin is necessary
+    withAIStream({
+      enableTts: false, // Enable Text-to-Speech
+      earlyStart: true, // Establish connection during onAgentStart phase
+      agentId: 'your-agent-id', // Provide your agent ID
+    }),
+    withBuildIn()
+  );
+
+  return agent;
+};
+```
+
+## Included Plugins
+
+### withAIStream Plugin
+
+This plugin facilitates communication with applet AI agent platforms.
+
+Parameters:
+
+- `agentId` Agent ID (required)
+- `clientType` Client type, defaults to APP (2)
+- `deviceId` Device ID, required when clientType is DEVICE (1)
+- `enableTts` Whether to enable Text-to-Speech, defaults to false
+- `wireInput` Whether to pass input blocks to the agent, defaults to true. Set to false if you plan to handle input blocks manually with the onInputBlocksPush Hook
+- `historySize` History message size, defaults to 1000
+- `indexId` Index ID, defaults to 'default'
+- `homeId` Home ID, defaults to current home if not provided
+- `earlyStart` Whether to establish connection during onAgentStart phase
+- `tokenOptions` Parameters for getting agent token
+  - `api` API interface name
+  - `version` Interface version
+  - `extParams` Additional parameters
+- `createChatHistoryStore` Custom message storage function
+
+Methods:
+
+- `agent.plugins.aiStream.send`: Send a message to the agent
+- `agent.plugins.aiStream.chat`: Send a message to the agent while generating a ChatMessage object for the question and the AI's answer, updating in a streaming manner
+
+Hooks:
+
+- `onMessageParse` Triggered when reading history messages and parsing them, allowing for message modification in this Hook
+  - `msgItem` Stored message object
+  - `result.messages` Parsed message list
+- `onSkillCompose` Triggered when receiving skill data, used for handling skill rendering
+  - `skill` Skill data array (ReceivedTextSkillPacketBody[])
+  - `respMsg` Response message
+  - `result.messages` Message list
+- `onSkillsEnd` Triggered when all skills processing is complete
+  - `skills` Skill data list (ReceivedTextSkillPacketBody[])
+  - `respMsg` Response message
+  - `result.messages` Message list
+- `onTTTAction` Triggered when tile uses `sendAction`
+  - `tile` Triggering tile
+  - `result.action` TTTAction, can modify the action to be executed
+- `onCardsReceived` Triggered when receiving card data
+  - `skills` Skill data list (ReceivedTextSkillPacketBody[])
+  - `result.cards` Card list
+
+### 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.
+
+### Mock AI Stream Response
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-aistream';
+
+mock.hooks.hook('sendToAIStream', context => {
+  if (context.options.blocks?.some(block => block.text?.includes('hello'))) {
+    context.responseText = 'hello, who are you?';
+  }
+
+  if (context.options.blocks?.some(block => block.text?.includes('smart home'))) {
+    context.responseText = 'Controlling smart devices for you...';
+    context.responseSkills = [
+      {
+        code: 'smart_home',
+        general: {
+          action: 'control_device',
+          data: {
+            devices: [
+              {
+                deviceId: 'vdevo174796589841019',
+                icon: '',
+                dps: { range: '0', toggle: 'ON' },
+                name: 'Towel Rack',
+              },
+            ],
+          },
+        },
+        custom: {},
+      },
+    ];
+  }
+});
+```
+
+### mock ASR Speech Recognition
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-aistream';
+
+mock.hooks.hook('asrDetection', context => {
+  context.responseText = 'Hello world!, I am a virtual assistant.';
+});
 ```
+
+## Additional Utils Tools (Currently under development)
+
+### AbortController
+
+This is an AbortController ponyfill for mini-programs, refer to mdn
+
+### runTTTAction
+
+Run a TTTAction to handle user actions, currently supporting the following actions
+
+- `openRoute` Open a route
+- `openMiniApp` Open a mini program
+- `openH5` Open an H5 page
+- `sendMessage` Send a message
+- `buildIn` Built-in action
+
+### AsrAgent
+
+ASR Speech Recognition agent, used for recognizing user's voice input
+
+Usage:
+
+```tsx
+import { createAsrAgent } from '@ray-js/t-agent-plugin-aistream';
+
+async function startAsr() {
+  const asrAgent = createAsrAgent({
+    agentId: 'your-agent-id',
+    onMessage: message => {
+      if (message.type === 'text') {
+        console.log('Recognition result:', message.text);
+      } else if (message.type === 'file') {
+        console.log('Audio file:', message.file);
+      }
+    },
+    onFinish: () => {
+      console.log('Recognition completed');
+    },
+    onError: error => {
+      console.error('Recognition error:', error);
+    },
+    recordingOptions: {
+      saveFile: false,
+      sampleRate: 16000,
+      maxDuration: 60000, // Maximum 60 seconds
+    },
+  });
+
+  // Start recognition
+  await asrAgent.start();
+
+  // Stop recognition
+  await asrAgent.stop();
+}
+```
+
+### promisify TTT
+
+A promisify method for the built-in TTT API, used to convert the TTT API into a Promise, supporting mock concurrently
+
+Usage:
+
+```tsx
+import { promisify } from '@ray-js/t-agent-plugin-aistream';
+
+interface RouterParams {
+  /** Route link */
+  url: string;
+  complete?: () => void;
+  success?: (params: null) => void;
+  fail?: (params: {
+    errorMsg: string;
+    errorCode: string | number;
+    innerError: {
+      errorCode: string | number;
+      errorMsg: string;
+    };
+  }) => void;
+}
+const router = promisify<RouterParams>(ty.router);
+
+// mock, only effective under IDE
+mock.hooks.hook('router', context => {
+  console.log('call router', context.options);
+});
+
+// invoke
+await router({ url: '/pages/index/index' });
+```
+
+### sendBlocksToAIStream
+
+**Note: This function is for internal use only. General developers should not call it directly**
+
+Send message blocks to AIStream. This is a low-level function. You should typically use `agent.plugins.aiStream.send` or `agent.plugins.aiStream.chat` methods instead.
+
+#### Use Cases
+
+- ✅ **Suitable**: When you need direct control over streaming response handling
+- ✅ **Suitable**: Implementing custom message sending logic
+- ❌ **Not suitable**: General conversation scenarios, should use `agent.plugins.aiStream.chat`
+- ❌ **Not suitable**: Simple message sending, should use `agent.plugins.aiStream.send`
+
+#### Function Signature
+
+```tsx
+import { sendBlocksToAIStream } from '@ray-js/t-agent-plugin-aistream';
+
+export interface SendBlocksToAIStreamParams {
+  blocks: InputBlock[];
+  session: AIStreamSession;
+  attribute?: AIStreamChatAttribute;
+  signal?: AbortSignal;
+  enableTts?: boolean;
+}
+
+export function sendBlocksToAIStream(params: SendBlocksToAIStreamParams): {
+  response: StreamResponse;
+  metaPromise: Promise<Record<string, any>>;
+};
+```
+
+#### Usage Example
+
+```tsx
+const send = async () => {
+  try {
+    // First need to get AIStreamSession object
+    const streamSession = agent.session.get('AIStream.streamSession');
+
+    const result = sendBlocksToAIStream({
+      blocks: [{ type: 'text', text: 'hello' }],
+      session: streamSession,
+      signal: new AbortController().signal,
+    });
+
+    // Get metadata after sending
+    const meta = await result.metaPromise;
+
+    // Get streamed message
+    const parts = result.response.parts();
+    for await (const part of parts) {
+      console.log('part', part);
+    }
+  } catch (error) {
+    console.error('Send message failed:', error);
+    // Error handling logic
+  }
+};
+```
+
+### authorizeAIStreamPolicy
+
+Popup to remind users to accept the AI privacy policy, a security requirement that users must agree to access AI features in the app
+
+> Note that this function requires `BaseKit >= 3.20.4`. If your BaseKit version is lower than this version, it will be directly passed.
+
+```tsx
+import { authorizeAIStreamPolicy } from '@ray-js/t-agent-plugin-aistream';
+
+// Call this function after the page load completes to pop up the agreement prompt
+const authorize = async () => {
+  try {
+    const result = await authorizeAIStreamPolicy();
+
+    if (result) {
+      // Already agreed or clicked the agree button
+      console.log('User agreed to the AI privacy policy');
+    } else {
+      ty.exitMiniProgram({});
+      console.log('User declined the AI privacy policy');
+    }
+  } catch (e) {
+    // Popup error message
+    ty.showToast({
+      title: I18n.t('get_sign_error'),
+      icon: 'error',
+    });
+    // Delay to allow the user to read clearly
+    setTimeout(() => {
+      ty.exitMiniProgram({});
+    }, 1000);
+  }
+};
+```
+
+### Functions Related to Media Files
+
+`uploadMedia`, `uploadVideo`, `uploadImage` are used to upload media files, with caching supported.
+
+`isFullLink` is used to determine whether it is a link with http(s) protocol
+
+`parseCloudKey` is used to parse the key of cloud storage in the URL
+
+`isLinkExpired` is used to determine whether the link is expired
+
+`getUrlByCloudKey` is used to get the signed download URL of cloud storage from the cache, otherwise returns `undefined`
+
+`setUrlByCloudKey` is used to set the signed download URL of cloud storage into the cache
+
+`resetUrlByCloudKey` is used to reset the cache of the signed download URL of cloud storage
+
+`chooseImage`, `chooseVideo` are used to select media files
+
+```tsx
+import { useEffect } from 'react';
+
+async function getPictureList() {
+  // Retrieve the user's private picture list from the cloud
+  const list = await pictureListRequest();
+  // Set into the cache this way, so it won't need to request next time
+  for (const item of list) {
+    setUrlByCloudKey(item.path, item.displayUrl);
+  }
+}
+```
+
+# t-agent-ui-ray
+
+t-agent-ui-ray is a UI component library based on ray, containing some commonly used dialogue interface components, such as message list, message input box, etc.
+
+## Installation
+
+```shell
+yarn add @ray-js/t-agent-ui-ray
+```
+
+## Usage
+
+```tsx
+import { ChatContainer, MessageList, MessageInput } from '@ray-js/t-agent-ui-ray';
+// see the use case of t-agent for createAgent implementation
+import { createAgent } from './createAgent';
+
+export default function ChatPage() {
+  // createAgent must return a ChatAgent instance applied with withUI, withAIStream plugins
+  return (
+    <View style={{ height: '100vh' }}>
+      <ChatContainer createAgent={createAgent}>
+        <MessageList />
+        <MessageInput />
+      </ChatContainer>
+    </View>
+  );
+}
+```
+
+## Components
+
+### ChatContainer
+
+Dialog container, used to wrap message lists and message input boxes, provides the context for `ChatAgent`
+
+props:
+
+- `className` Class name of the container
+- `createAgent` Function to create `ChatAgent`, which will call this function to create `ChatAgent` instance after `ChatContainer` mount
+- `agentRef` Reference to the `ChatAgent` instance, used to get the `ChatAgent` instance outside the `ChatContainer`
+- `renderOptions` Rendering options, used to decide the rendering method of each element in `MessageList`, refer to the renderOptions custom rendering part below
+  - `renderTileAs` This function decides how to render tiles in the messages
+  - `customBlockTypes` Custom block types, only block types registered here will be rendered by `renderCustomBlockAs`
+  - `renderCustomBlockAs` This function decides how to render custom blocks in markdown bubble messages, by default supports `echarts`
+  - `renderCardAs` This function decides how to render cards in messages, generally no need to customize this item
+  - `renderLongPressAs` **(0.2.x New)** This function decides how to render long press menu, allows customizing long press menu style and behavior
+  - `formatErrorMessageAs` **(0.2.x New)** This function decides how to format error messages, can return user-friendly error messages based on error codes
+  - `customCardMap` Custom card mapping, no need to modify the `renderCardAs` function, just register the card type and corresponding component here
+  - `getStaticResourceBizType` Get static resource `bizType` used to fetch static resources
+
+### MessageList
+
+Message list, used to display messages. In version 0.2.x, it integrates LazyScrollView component for better performance optimization.
+
+**Props**:
+
+- `className` Class name of the list
+- `roleSide` Alignment of message roles, default `{ user: 'end', assistant: 'start' }`
+
+**LazyScrollView Integration (0.2.x New)**:
+
+MessageList internally uses LazyScrollView component to optimize performance when rendering large numbers of messages:
+
+- **Lazy Rendering**: Only renders messages in the visible area, greatly improving performance
+- **Height Adaptation**: Automatically calculates message heights, supports dynamic content
+- **notifyHeightChanged()**: Automatically notifies height updates when message content changes
+
+The component automatically handles the following scenarios:
+
+- Ensures the bottom 10 messages are always rendered to avoid blank screens when scrolling to bottom
+- Automatically updates scroll position when message heights change
+- Supports animated scrolling to bottom effects
+
+### MessageInput
+
+Message input box, used to input messages, upload attachments, ASR speech recognition
+
+props:
+
+- `className` Class name of the input box
+- `placeholder` Placeholder of the input box
+- `renderTop` Used to render content above the input box
+
+### MessageActionBar (0.2.x New)
+
+Message action bar component, used to display action buttons when in multi-select mode, supports deleting selected messages and clearing history.
+
+**Props**:
+
+No props need to be passed, the component automatically shows and hides based on multi-select state
+
+**Features**:
+
+- **Back Button**: Exit multi-select mode
+- **Clear History Button**: Clear all history messages, will call `onClearHistory` Hook
+- **Delete Selected Button**: Delete currently selected messages, button is disabled when no messages are selected
+
+**How it Works**:
+
+MessageActionBar component monitors the `UIRay.multiSelect.show` state in session data to determine whether to display. When user long-presses a message and selects "Multi-select", this component will automatically show.
+
+**Usage Example**:
+
+```tsx
+export default function ChatPage() {
+  return (
+    <View style={{ height: '100vh' }}>
+      <ChatContainer createAgent={createAgent}>
+        <MessageList />
+        <MessageInput />
+        <MessageActionBar />
+      </ChatContainer>
+    </View>
+  );
+}
+```
+
+### PrivateImage
+
+Private image component, used to display private images, props are the same as Image, adding bizType parameter
+
+### LazyScrollView
+
+Lazy-loading scroll view component for optimizing long list performance, automatically manages rendering in the visible area
+
+Main Features:
+
+- Virtual Scrolling: Only renders elements in the visible area
+- Height Caching: Automatically caches element heights to improve scrolling performance
+- Dynamic Loading: Dynamically shows/hides elements based on scroll position
+- `notifyHeightChanged()` Function: When element heights change, this method can be called to notify the scroll view to update
+
+Usage Notes:
+
+LazyScrollView is mainly used internally by MessageList, developers generally don't need to use it directly. If you need to dynamically change heights in messages, you can use the `notifyHeightChanged` parameter to notify height changes:
+
+```tsx
+// Use in tile component
+const MyTile = ({ notifyHeightChanged }) => {
+  const [expanded, setExpanded] = useState(false);
+
+  const handleToggle = () => {
+    setExpanded(!expanded);
+    // Notify height change
+    notifyHeightChanged();
+  };
+
+  return (
+    <View>
+      <Button onClick={handleToggle}>Expand/Collapse</Button>
+      {expanded && <View>Detailed content...</View>}
+    </View>
+  );
+};
+```
+
+### Built-in tile components
+
+- bubble Bubble
+- buttons Button group
+- card Card
+- image Image
+- recommendations Recommended actions
+- text Text, including markdown support
+- time Time marker
+- tip Tip
+- video Video
+- workflow Workflow options
+
+### Built-in card
+
+- WorkflowReplyCard Workflow reply card
+
+## React Hooks
+
+### useChatAgent
+
+Get `ChatAgent` instance in the `ChatContainer` context
+
+### useAgentMessage
+
+Get `messages: ChatMessageObject[]` list in the `ChatContainer` context
+
+### useRenderOptions
+
+Get `renderOptions` object in the `ChatContainer` context
+
+### useOnEvent
+
+Register UI events in the `ChatContainer` context, and automatically unregister them when the component is unloaded
+
+```tsx
+import { useOnEvent } from '@ray-js/t-agent-ui-ray';
+
+const MyComponent = () => {
+  useOnEvent('scrollToBottom', payload => {
+    console.log('scroll to bottom', payload.animation);
+  });
+
+  return <div>My Component</div>;
+};
+```
+
+### useEmitEvent
+
+Trigger UI events in the `ChatContainer` context
+
+```tsx
+import { useEmitEvent } from '@ray-js/t-agent-ui-ray';
+
+const MyComponent = () => {
+  const emitEvent = useEmitEvent();
+
+  const scroll = () => {
+    emitEvent('scrollToBottom', { animation: false });
+  };
+
+  return <button onClick={scroll}>Scroll to bottom</button>;
+};
+```
+
+### useTileProps
+
+Get the `TileProps` object in the tile component; if it's a tile, you can directly obtain it from props.
+
+```tsx
+import { useTileProps } from '@ray-js/t-agent-ui-ray';
+
+const MyTilePart = () => {
+  const { message, agent, tile, emitTileEvent } = useTileProps();
+
+  return <div>My Tile</div>;
+};
+```
+
+### useSendAction
+
+Send a TTTAction, note that it can only be used inside tile components (or cards).
+
+```tsx
+import { useSendAction } from '@ray-js/t-agent-ui-ray';
+
+const MyTilePart = () => {
+  const sendAction = useSendAction();
+
+  const handleClick = () => {
+    sendAction({ type: 'sendMessage', blocks: [{ type: 'text', text: 'hello' }] });
+  };
+
+  return <button onClick={handleClick}>Send Message</button>;
+};
+```
+
+### useTranslate
+
+Get internationalization translation function for translating interface text, provides complete multilingual support.
+
+```tsx
+import { useTranslate } from '@ray-js/t-agent-ui-ray';
+
+const MyComponent = () => {
+  const t = useTranslate();
+
+  return (
+    <div>
+      {t('t-agent.message.action.copy')} {/* Output: "Copy message" */}
+      {t('t-agent.message.delete.title')} {/* Output: "Delete message" */}
+      {t('t-agent.message.clear-history.title')} {/* Output: "Clear history" */}
+    </div>
+  );
+};
+```
+
+**Supported Languages**:
+
+Built-in multilingual support includes:
+
+- **Simplified Chinese** (`zh-Hans`): Simplified Chinese
+- **Traditional Chinese** (`zh-Hant`): Traditional Chinese
+- **English** (`en`): English
+- **Japanese** (`ja`): Japanese
+- **German** (`de`): German
+- **French** (`fr`): French
+- **Spanish** (`es`): Spanish
+- **Italian** (`it`): Italian
+
+The system automatically selects the corresponding translation based on the user's system language, falling back to English if the current language is not supported.
+
+## renderOptions Custom Rendering
+
+### Replace or Add Tile
+
+If you need to replace a tile with your own implementation, or add a new tile, you can override `renderTileAs`, for example:
+
+```tsx
+import { ImageTileData } from '@ray-js/t-agent';
+import { Image } from '@ray-js/ray';
+import { defaultRenderOptions, TileProps } from '@ray-js/t-agent-ui-ray';
+
+function MyImageTile(props: TileProps<ImageTileData>) {
+  // Implement your own ImageTile
+  return <Image src={props.tile.data.src}></Image>;
+}
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  renderTileAs: (props: TileProps) => {
+    if (props.tile.type === 'image') {
+      return <MyImageTile {...props} />;
+    }
+    // Maintain default behavior
+    return defaultRenderOptions.renderTileAs(props);
+  },
+};
+```
+
+### Customize Long Press Menu (0.2.x New)
+
+If you need to customize the style or behavior of the long press menu, you can override the `renderLongPressAs` function, for example:
+
+```tsx
+import { defaultRenderOptions, LongPressResult } from '@ray-js/t-agent-ui-ray';
+import { View, Button } from '@ray-js/ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  renderLongPressAs: (res: LongPressResult) => {
+    if (!res.menuProps.showActionMenu) {
+      return null;
+    }
+
+    return (
+      <View className="my-custom-menu">
+        {res.menuProps.menuItems.map(item => (
+          <Button key={item.key} onClick={() => res.menuProps.handleMenuItemClick(item)}>
+            {item.displayLabel}
+          </Button>
+        ))}
+      </View>
+    );
+  },
+};
+```
+
+Long press menu features include:
+
+- **Copy Message**: Copy text content to clipboard
+- **Delete Message**: Delete single message
+- **Multi-select**: Enter multi-select mode, used with MessageActionBar
+- **Like/Unlike**: Provide feedback for assistant messages (only available for assistant role messages)
+
+### Customize Error Message Formatting (0.2.x New)
+
+If you need to customize the display format of error messages, you can override the `formatErrorMessageAs` function, for example:
+
+```tsx
+import { defaultRenderOptions } from '@ray-js/t-agent-ui-ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  formatErrorMessageAs: (message: string, code: string | undefined) => {
+    // Return custom error messages based on error codes
+    if (code === 'network-offline') {
+      return 'Network connection is abnormal, please check your network settings';
+    }
+    if (code === 'timeout') {
+      return 'Request timeout, please try again later';
+    }
+    // Use default error message
+    return message;
+  },
+};
+```
+
+Built-in supported error codes include:
+
+- `network-offline`: Network disconnected
+- `timeout`: Send timeout
+- `invalid-params`: Invalid parameters
+- `session-create-failed`: Connection failed
+- `connection-closed`: Connection closed
+- And more
+
+### Customize Cards
+
+Cards can be categorized into three types: built-in cards (buildIn), custom cards (custom), and low-code cards (lowCode). Currently, low-code cards are still under development. Custom cards can be registered using `customCardMap`.
+
+The data structure of the card is as follows:
+
+```tsx
+enum ChatCardType {
+  CUSTOM = 'custom', // Custom card available for business use
+  BUILD_IN = 'buildIn', // Platform built-in card
+  LOW_CODE = 'lowCode', // Low-code card
+}
+
+interface ChatCardObject<T = any> {
+  cardCode: string; // Unique identifier for the card
+  cardType: ChatCardType; // Card type
+  cardData: T; // Data carried by the card
+}
+```
+
+Register a custom card:
+
+```tsx
+import {
+  ChatCardObject,
+  ChatCardType,
+  defaultRenderOptions,
+  useTileProps,
+  useSendAction,
+} from '@ray-js/t-agent-ui-ray';
+import { View, Text, Button } from '@ray-js/ray';
+
+const MyCard: ChatCardComponent<{ title: string }, { clicked: boolean }> = props => {
+  // If you need to access attributes like agent, message, tile, emitTileEvent, use useTileProps
+  const { message, agent, tile, emitTileEvent } = useTileProps();
+  const { card, setCardState } = props;
+  const { cardData, cardState, cardCode } = card as ChatCardObject<{ title: string }>;
+
+  // If you need to send a TTTAction, use useSendAction
+  const sendAction = useSendAction();
+
+  return (
+    <View>
+      <Text>My Card</Text>
+      <Button
+        onClick={() => {
+          sendAction({ type: 'sendMessage', blocks: [{ type: 'text', text: 'hello' }] });
+          // If you want to set the card state, use setCardState
+          // The second parameter is used to determine whether to persist the card state, default is false
+          setCardState({ clicked: true }, { persist: true });
+        }}
+      >
+        Fill text into input
+      </Button>
+    </View>
+  );
+};
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  customCardMap: {
+    myCard: MyCard,
+  },
+};
+```
+
+### Customize Block
+
+In `TextTile`, the markdown renderer supports custom blocks. You can register and render custom blocks through `customBlockTypes` and `renderCustomBlockAs`.
+
+The data structure of the block is as follows:
+
+```tsx
+export interface MarkdownBlock {
+  id: string;
+  type: string;
+  children: string; // Content in the block
+}
+```
+
+Register a custom block:
+
+```tsx
+import { defaultRenderOptions, MarkdownBlock } from '@ray-js/t-agent-ui-ray';
+import { View, Text } from '@ray-js/ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  customBlockTypes: ['my-block'],
+  renderCustomBlockAs: (block: MarkdownBlock) => {
+    if (block.type === 'my-block') {
+      return (
+        <View>
+          <View>This is My Block</View>
+          <View>{block.children}</View>
+        </View>
+      );
+    }
+    return defaultRenderOptions.renderCustomBlockAs(block);
+  },
+};
+```
+
+If a markdown text containing a `fence` of type `my-block` is sent by an AI, since we registered `my-block` above, this `fence` can be treated as a custom block.
+
+````markdown
+This is my custom block!
+
+```my-block
+Hello, world!
+```
+````
+
+The following fence is not registered, and will not be rendered as a custom block, but just as a regular code block.
+
+```javascript
+console.log('Hello, world!');
+```
+
+```
+
+The rendered result is as follows:
+
+```
+
+This is my custom block!
+This is My Block
+Hello, world!
+The following fence is not registered, and will not be rendered as a custom block, but just as a regular code block.
+
+---
+
+## | console.log('Hello, world!'); |
+
+````
+
+### getStaticResourceBizType
+
+If your static resources need to include `bizType`, it can be obtained via `getStaticResourceBizType`.
+
+```tsx
+import { defaultRenderOptions } from '@ray-js/t-agent-ui-ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  getStaticResourceBizType: (src: string, scene: string) => 'bizType',
+};
+````
+
+For different scenarios, you may require different `bizType`. You can return different `bizType` based on `src` and `scene`.
+
+The built-in `scene` includes the following:
+
+- `image:view` Image viewing
+- `image:upload` Image uploading
+- `video:view` Video viewing
+- `video:upload` Video uploading
+- `videoThumb:view` Video thumbnail viewing
+- `videoThumb:upload` Video thumbnail uploading
+
+### Custom Multilingual Support
+
+If you need to customize multilingual support, you can override the `i18nTranslate` function, for example:
+
+```tsx
+import { defaultRenderOptions } from '@ray-js/t-agent-ui-ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  i18nTranslate: (key: string) => {
+    if (key === 'hello') {
+      return 'Bonjour';
+    }
+    // Use default multilingual settings
+    return I18n.t(key);
+  },
+};
+```
+
+Below are the built-in multilingual keys:
+
+| key                                                        | Usage Context                            | Meaning                                                                      |
+| ---------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------- |
+| t-agent.build-in.button.create_scene_manually              | Built-in ButtonTile button               | Manually create scene                                                        |
+| t-agent.build-in.button.enter_home_manage                  | Built-in ButtonTile button               | Enter _"Home Management"_                                                    |
+| t-agent.build-in.button.enter_room_manage                  | Built-in ButtonTile button               | Enter _"Room Management"_                                                    |
+| t-agent.build-in.button.enter_alarm_message                | Built-in ButtonTile button               | Enter _"Alarm Message List"_                                                 |
+| t-agent.build-in.button.enter_home_message                 | Built-in ButtonTile button               | Enter _"Home Message List"_                                                  |
+| t-agent.build-in.button.enter_bulletin                     | Built-in ButtonTile button               | Enter _"Bulletin Message List"_                                              |
+| t-agent.build-in.button.enter_notification_setting         | Built-in ButtonTile button               | Enter _"Notification Settings"_                                              |
+| t-agent.build-in.button.enter_personal_information         | Built-in ButtonTile button               | Enter _"Personal Information"_                                               |
+| t-agent.build-in.button.enter_account_security             | Built-in ButtonTile button               | Enter _"Account and Security"_                                               |
+| t-agent.build-in.button.enter_setting                      | Built-in ButtonTile button               | Enter _"General Settings"_                                                   |
+| t-agent.build-in.button.enter_paring                       | Built-in ButtonTile button               | Enter _"Device Pairing"_                                                     |
+| t-agent.build-in.button.enter_share_device                 | Built-in ButtonTile button               | Enter _"Share Device"_                                                       |
+| t-agent.build-in.button.enter_faq_feedback                 | Built-in ButtonTile button               | Enter _"FAQs and Feedback"_                                                  |
+| t-agent.build-in.button.questionnaire_take                 | Built-in ButtonTile button               | Take the questionnaire                                                       |
+| t-agent.build-in.button.set_home_location                  | Built-in ButtonTile button               | Set home location                                                            |
+| t-agent.input.voice.require-permission                     | MessageInput switch to voice input       | Need to grant recording permission                                           |
+| t-agent.input.upload.failed                                | MessageInput file upload                 | File upload failed                                                           |
+| t-agent.input.asr.oninput.text.top                         | MessageInput ASR voice input             | I'm listening, please speak                                                  |
+| t-agent.input.asr.oninput.text.center                      | MessageInput ASR voice input             | Release to send, swipe up to cancel                                          |
+| t-agent.input.asr.ptt                                      | MessageInput ASR voice input             | Hold to speak                                                                |
+| t-agent.input.asr.error.too-short                          | MessageInput ASR error                   | Speech too short                                                             |
+| t-agent.input.asr.error.empty                              | MessageInput ASR error                   | Unable to recognize text from speech                                         |
+| t-agent.input.asr.error.unknown                            | MessageInput ASR error                   | Speech recognition failed                                                    |
+| t-agent.input.asr.error.timeout                            | MessageInput ASR error                   | Speech recognition reached time limit, will send directly                    |
+| t-agent.input.upload.source-type.camera                    | MessageInput file upload                 | Take photo                                                                   |
+| t-agent.input.upload.source-type.camera.require-permission | MessageInput file upload                 | Camera permission required for taking photos, please enable in settings      |
+| t-agent.input.upload.source-type.album                     | MessageInput file upload                 | Choose from album                                                            |
+| t-agent.input.upload.source-type.album.require-permission  | MessageInput file upload                 | Album permission required for choosing from album, please enable in settings |
+| t-agent.input.upload.image.max-reached                     | MessageInput file upload                 | Image upload limit reached                                                   |
+| t-agent.input.upload.video.max-reached                     | MessageInput file upload                 | Video upload limit reached                                                   |
+| t-agent.file-tile.unknown-filename                         | FileTile file display                    | File                                                                         |
+| t-agent.message.feedback.success                           | BubbleTile message feedback              | Feedback successful                                                          |
+| t-agent.message.bubble.aborted                             | BubbleTile message                       | User aborted                                                                 |
+| t-agent.message.action.copy                                | BubbleTile long press menu               | Copy message                                                                 |
+| t-agent.message.action.delete                              | BubbleTile long press menu               | Delete message                                                               |
+| t-agent.message.action.multi-select                        | BubbleTile long press menu               | Multi-select                                                                 |
+| t-agent.message.action.like                                | BubbleTile long press menu               | Like message                                                                 |
+| t-agent.message.action.unlike                              | BubbleTile long press menu               | Dislike message                                                              |
+| t-agent.message.copy.success                               | BubbleTile copy success                  | Copy successful                                                              |
+| t-agent.message.delete.success                             | BubbleTile delete success                | Delete successful                                                            |
+| t-agent.message.like.success                               | BubbleTile feedback                      | Like successful                                                              |
+| t-agent.message.unlike.success                             | BubbleTile feedback                      | Dislike successful                                                           |
+| t-agent.message.delete.title                               | BubbleTile delete message dialog title   | Delete message                                                               |
+| t-agent.message.delete.content                             | BubbleTile delete message dialog content | Are you sure to delete this message?                                         |
+| t-agent.message.delete.confirm                             | BubbleTile delete message dialog confirm | Confirm                                                                      |
+| t-agent.message.delete.cancel                              | BubbleTile delete message dialog cancel  | Cancel                                                                       |
+| t-agent.message.clear-history.title                        | MessageActionBar clear history           | Clear history                                                                |
+| t-agent.message.clear-history.content                      | MessageActionBar clear history           | Are you sure to clear history?                                               |
+| t-agent.message.clear-history.button                       | MessageActionBar clear history           | Clear history                                                                |
+| t-agent.message.multi-select-delete.title                  | MessageActionBar multi-select delete     | Delete selected messages                                                     |
+| t-agent.message.multi-select-delete.content                | MessageActionBar multi-select delete     | Are you sure to delete these selected messages?                              |
+| t-agent.execute-card-tile.execution.success                | ExecuteCardTile execution result         | Execution successful                                                         |
+| t-agent.execute-card-tile.execution.failed                 | ExecuteCardTile execution result         | Execution failed                                                             |
+| t-agent.execute-card-tile.scene.invalid                    | ExecuteCardTile scene status             | Scene invalid                                                                |
+| t-agent.execute-card-tile.delete                           | ExecuteCardTile button                   | Delete                                                                       |
+| t-agent.execute-card-tile.execute                          | ExecuteCardTile button                   | Execute                                                                      |
+| t-agent.execute-card-tile.switch.scene.state               | ExecuteCardTile operation                | Switch scene state                                                           |
+| t-agent.operate-card-tile.open.device.failed               | OperateCardTile operation result         | Failed to open device                                                        |
+| t-agent.operate-card-tile.open.scene.failed                | OperateCardTile operation result         | Failed to open scene                                                         |
+| t-agent.operate-card-tile.operation.impact                 | OperateCardTile title                    | Operation impact:                                                            |
+| t-agent.operate-card-tile.hide.details                     | OperateCardTile button                   | Hide details                                                                 |
+| t-agent.operate-card-tile.view.details                     | OperateCardTile button                   | View details                                                                 |
+| t-agent.operate-card-tile.device.move.desc                 | OperateCardTile device move              | Device "{device}" moved to "{room}"                                          |
+| t-agent.operate-card-tile.device.rename.desc               | OperateCardTile device rename            | Device "{oldName}" renamed to "{newName}"                                    |
+| t-agent.operate-card-tile.device.count                     | OperateCardTile device count             | {count} devices                                                              |
+| t-agent.operate-card-tile.scene.count                      | OperateCardTile scene count              | {count} scenes                                                               |
+| t-agent.operate-card-tile.home.count                       | OperateCardTile home count               | {count} homes                                                                |
+| t-agent.operate-card-tile.room.count                       | OperateCardTile room count               | {count} rooms                                                                |
+| t-agent.operate-card-tile.group.count                      | OperateCardTile group count              | {count} groups                                                               |
+| t-agent.operate-card-tile.description.format               | OperateCardTile description format       | {items}.                                                                     |
+| t-agent.operate-card-tile.description.separator            | OperateCardTile description separator    | ,                                                                            |
+| t-agent.expand.tab.device                                  | ExpandTile tab                           | Devices                                                                      |
+| t-agent.expand.tab.scene                                   | ExpandTile tab                           | Scenes                                                                       |
+| t-agent.expand.tab.more                                    | ExpandTile tab                           | Others                                                                       |
+| t-agent.expand.execution.success                           | ExpandTile execution result              | Execution successful                                                         |
+| t-agent.expand.execution.failed                            | ExpandTile execution result              | Execution failed                                                             |
+| t-agent.expand.device.rename                               | ExpandTile device rename                 | {oldName} renamed to {newName}                                               |
+| t-agent.expand.scene.rename                                | ExpandTile scene rename                  | {oldName} renamed to {newName}                                               |
+| t-agent.expand.scene.one-click                             | ExpandTile scene type                    | One-click execution                                                          |
+| t-agent.expand.scene.auto                                  | ExpandTile scene type                    | Automatic execution                                                          |
+| t-agent.expand.no.details                                  | ExpandTile no content prompt             | No details available                                                         |
+| t-agent.error.unknown-error                                | Error message                            | Unknown error                                                                |
+| t-agent.error.network-offline                              | Error message                            | Network disconnected, please check network connection                        |
+| t-agent.error.invalid-params                               | Error message                            | Invalid parameters, please retry                                             |
+| t-agent.error.session-create-failed                        | Error message                            | Connection failed, please retry                                              |
+| t-agent.error.connection-closed                            | Error message                            | Connection closed, please retry                                              |
+| t-agent.error.event-exists                                 | Error message                            | Message sending error, please try again later                                |
+| t-agent.error.event-disposed                               | Error message                            | Message sending error, please try again later                                |
+| t-agent.error.event-closed                                 | Error message                            | Message sending error, please try again later                                |
+| t-agent.error.event-aborted                                | Error message                            | Message aborted                                                              |
+| t-agent.error.event-write-failed                           | Error message                            | Message sending error, please try again later                                |
+| t-agent.error.event-no-data-code                           | Error message                            | Message sending error, please try again later                                |
+| 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
+- **Text-to-Speech**: Supports TTS functionality, controlled via `enableTts` parameter
+- **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