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

package/README-zh_CN.md

@@ -22,12 +22,21 @@ yarn add @ray-js/t-agent @ray-js/t-agent-plugin-aistream @ray-js/t-agent-ui-ray
     "DeviceKit": "4.6.1",
     "HomeKit": "3.4.0",
     "MiniKit": "3.12.1",
-    "AIStreamKit": "1.0.0"
+    "AIStreamKit": "1.3.2"
   },
   "baseversion": "2.21.10"
 }
 ```
 
+### 小程序 kit 与功能对应表
+
+部分功能对 App 的 kit 有依赖要求，需要配置 AIStreamKit 最低才能使用这些功能
+
+| 功能       | AIStreamKit 最低版本 | 相关 API                              |
+| ---------- | -------------------- | ------------------------------------- |
+| 对话分组   | 1.3.2                | agent.plugins.aiStream.getChatId      |
+| 自定义参数 | 2.1.0                | agent.plugins.aiStream.onUserDataRead |
+
 ## package.json 依赖要求
 
 ```json
@@ -771,6 +780,7 @@ const createAgent = () => {
 - `indexId` 索引 ID，默认为 'default'
 - `homeId` 家庭 ID，不填默认当前家庭
 - `earlyStart` 是否在 onAgentStart 阶段就建立连接
+- `eventIdPrefix` eventId 前缀，用于方便云端调试和日志追踪
 - `tokenOptions` 获取 agent token 的参数
   - `api` API 接口名
   - `version` 接口版本
@@ -779,14 +789,30 @@ const createAgent = () => {
 
 方法：
 
-- `agent.plugins.aiStream.send` 向智能体发送一条消息
-- `agent.plugins.aiStream.chat` 向智能体发送一条消息，并生成提问 ChatMessage 对象和 AI 回答 ChatMessage 对象，流式更新
+- `agent.plugins.aiStream.send(blocks, signal, userData)` 向智能体发送一条消息
+  - `blocks` 输入块数组
+  - `signal` 可选的 AbortSignal，用于中断请求
+  - `userData` 可选的用户数据，会附带在发送的消息中
+- `agent.plugins.aiStream.chat(blocks, signal, options)` 向智能体发送一条消息，并生成提问 ChatMessage 对象和 AI 回答 ChatMessage 对象，流式更新
+  - `blocks` 输入块数组
+  - `signal` 可选的 AbortSignal
+  - `options.sendBy` 发送者角色，默认为 'user'
+  - `options.responseBy` 响应者角色，默认为 'assistant'
+  - `options.userData` 可选的用户数据
+- `agent.plugins.aiStream.getChatId()` 获取当前会话的 chatId，返回 Promise<string>
 
 Hooks：
 
 - `onMessageParse` 当读取历史消息，解析消息时触发，可以在这个 Hook 里修改消息
   - `msgItem` 存储的消息对象
   - `result.messages` 解析后的消息列表
+- `onChatMessageSent` 当用户消息和响应消息创建后触发
+  - `userMessage` 用户发送的消息
+  - `respMessage` AI 的响应消息
+- `onTextCompose` 当收到文本数据时触发，用于处理文本的渲染
+  - `respMsg` 响应消息
+  - `status` 消息状态
+  - `result.text` 文本内容，可以修改
 - `onSkillCompose` 当收到技能数据时触发，用于处理技能的渲染
   - `skill` 技能数据数组 (ReceivedTextSkillPacketBody[])
   - `respMsg` 响应消息
@@ -801,6 +827,47 @@ Hooks：
 - `onCardsReceived` 当收到卡片数据时触发
   - `skills` 技能数据列表 (ReceivedTextSkillPacketBody[])
   - `result.cards` 卡片列表
+- `onUserDataRead` **(0.2.x 新增)** 当需要读取用户自定义数据时触发，用于向 AI 平台传递额外的上下文信息
+  - `type` 触发类型，可以是 'create-session' 或 'start-event'
+    - `'create-session'` 创建会话时触发，只触发一次
+    - `'start-event'` 每次发送消息时触发
+  - `data` 上下文数据
+    - `data.blocks` 当 type 为 'start-event' 时，包含本次发送的输入块
+  - `result.userData` 返回的用户数据对象，会被合并后发送给 AI 平台
+
+**使用示例**：
+
+```tsx
+const agent = createChatAgent(
+  withUI(),
+  withAIStream({
+    agentId: 'your-agent-id',
+  })
+);
+
+agent.plugins.aiStream.onUserDataRead((type, data, result) => {
+  // 在创建会话时传递用户信息
+  if (type === 'create-session') {
+    result.sessionAttributes = {
+      'custom.param': {
+        userName: { value: 'John' },
+        userLevel: { value: 'Plus' },
+      },
+    };
+    return;
+  }
+  // 在每次发送消息时传递动态上下文
+  if (type === 'start-event') {
+    result.userData = {
+      'custom.param': {
+        timestamp: { value: Date.now() },
+        pid: { value: '123456' },
+      },
+    };
+    return;
+  }
+});
+```
 
 ### withBuildIn 插件
 

package/README.md

@@ -22,7 +22,7 @@ yarn add @ray-js/t-agent @ray-js/t-agent-plugin-aistream @ray-js/t-agent-ui-ray
     "DeviceKit": "4.6.1",
     "HomeKit": "3.4.0",
     "MiniKit": "3.12.1",
-    "AIStreamKit": "1.0.0"
+    "AIStreamKit": "1.3.2"
   },
   "baseversion": "2.21.10"
 }
@@ -766,6 +766,7 @@ Parameters:
 - `indexId` Index ID, defaults to 'default'
 - `homeId` Home ID, defaults to current home if not provided
 - `earlyStart` Whether to establish connection during onAgentStart phase
+- `eventIdPrefix` Event ID prefix for cloud debugging and log tracing
 - `tokenOptions` Parameters for getting agent token
   - `api` API interface name
   - `version` Interface version
@@ -774,14 +775,30 @@ Parameters:
 
 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
+- `agent.plugins.aiStream.send(blocks, signal, userData)` Send a message to the agent
+  - `blocks` Input block array
+  - `signal` Optional AbortSignal for interrupting requests
+  - `userData` Optional user data to be included with the message
+- `agent.plugins.aiStream.chat(blocks, signal, options)` Send a message to the agent while generating a ChatMessage object for the question and the AI's answer, updating in a streaming manner
+  - `blocks` Input block array
+  - `signal` Optional AbortSignal
+  - `options.sendBy` Sender role, defaults to 'user'
+  - `options.responseBy` Responder role, defaults to 'assistant'
+  - `options.userData` Optional user data
+- `agent.plugins.aiStream.getChatId()` Get the current session's chatId, returns Promise<string>
 
 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
+- `onChatMessageSent` Triggered after user message and response message are created
+  - `userMessage` User's sent message
+  - `respMessage` AI's response message
+- `onTextCompose` Triggered when receiving text data, used for handling text rendering
+  - `respMsg` Response message
+  - `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[])
   - `respMsg` Response message
@@ -796,6 +813,47 @@ Hooks:
 - `onCardsReceived` Triggered when receiving card data
   - `skills` Skill data list (ReceivedTextSkillPacketBody[])
   - `result.cards` Card list
+- `onUserDataRead` **(0.2.x New)** Triggered when user custom data needs to be read, used to pass additional context information to the AI platform
+  - `type` Trigger type, can be 'create-session' or 'start-event'
+    - `'create-session'` Triggered when creating a session, only once
+    - `'start-event'` Triggered each time a message is sent
+  - `data` Context data
+    - `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
+
+**Usage Example**:
+
+```tsx
+const agent = createChatAgent(
+  withUI(),
+  withAIStream({
+    agentId: 'your-agent-id',
+  })
+);
+
+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' },
+      },
+    };
+    return;
+  }
+  // Pass dynamic context each time a message is sent
+  if (type === 'start-event') {
+    result.userData = {
+      'custom.param': {
+        timestamp: { value: Date.now() },
+        pid: { value: '123456' },
+      },
+    };
+    return;
+  }
+});
+```
 
 ### withBuildIn Plugin
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/t-agent",
-  "version": "0.2.7-beta.1",
+  "version": "0.2.7-beta.3",
   "author": "Tuya.inc",
   "license": "MIT",
   "private": false,
@@ -26,5 +26,5 @@
     "build": "ray build --type=component --output dist",
     "clean": "rimraf ./dist"
   },
-  "gitHead": "d7754f9879a7ec837eb343ac759a08734cc789d3"
+  "gitHead": "44d1d2ecb71857a1337c20137fe39d25384fdcdb"
 }