@ray-js/t-agent 0.0.5-beta-1

package/README-zh_CN.md

@@ -0,0 +1,1350 @@
+[English](./README.md) | 简体中文
+
+# AI 智能体 SDK
+
+## 安装（ray 小程序）
+
+```shell
+yarn add @ray-js/t-agent @ray-js/t-agent-plugin-assistant @ray-js/t-agent-ui-ray
+```
+
+> 确保 `@ray-js/t-agent` `@ray-js/t-agent-plugin-assistant` `@ray-js/t-agent-ui-ray` 版本一致
+
+## 小程序 kit 要求
+
+```json
+{
+  "dependencies": {
+    "BaseKit": "3.12.0",
+    "BizKit": "4.10.0",
+    "DeviceKit": "4.6.1",
+    "HomeKit": "3.4.0",
+    "MiniKit": "3.12.1"
+  },
+  "baseversion": "2.21.10"
+}
+```
+
+## package.json 依赖要求
+
+```json
+{
+  "dependencies": {
+    "@ray-js/ray": ">=1.6.8"
+  }
+}
+```
+
+## 开发
+
+```shell
+# 开发 sdk
+yarn run dev
+
+# 开发模板小程序
+yarn run miniapp
+```
+
+## 使用示例
+
+使用 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 } from '@ray-js/t-agent-ui-ray';
+import { withAssistant, withBuildIn } from '@ray-js/t-agent-plugin-assistant';
+
+const createAgent = () => {
+  // 应用插件是有顺序的
+  const agent = createChatAgent(
+    withUI(), // 第一个插件 withUI 插件提供了一些默认的 UI 行为，必选
+    withAssistant({
+      // withAssistant 插件对接小程序 AI 智能体平台，在小程序中必选
+      channel: '', // 输入你的智能体ID
+      multiModal: false, // 是否开启多模态
+    }),
+    withDebug(), // withDebug 会在 console 里打印日志
+    withBuildIn() // withBuildIn 插件提供了一些内置的功能
+  );
+
+  // 将生命周期钩子拿出来，方便注册自定义行为
+  const { onChatStart, createMessage, onChatResume, onError, onInputBlocksPush, session } = agent;
+
+  // 初始化聊天时，发送一条消息
+  onChatStart(async result => {
+    const hello = createMessage({
+      role: 'assistant',
+    });
+
+    hello.bubble.setText('Hello, world!');
+    result.messages.push(hello);
+    // 持久化消息，下次进入时会展示
+    await hello.persist('createText');
+  });
+
+  // 恢复聊天时，发送一条消息
+  onChatResume(async result => {
+    const welcomeBack = createMessage({
+      role: 'assistant',
+    });
+
+    welcomeBack.bubble.setText('Welcome back');
+    result.messages.push(welcomeBack);
+    await welcomeBack.persist('createText');
+  });
+  return agent;
+};
+
+export default function ChatPage() {
+  return (
+    <View style={{ height: '100vh' }}>
+      <ChatContainer createAgent={createAgent}>
+        <MessageList />
+        <MessageInput />
+      </ChatContainer>
+    </View>
+  );
+}
+```
+
+# t-agent
+
+t-agent 包是使用 TypeScript 编写的对话智能体 SDK，用于构建对话智能体，支持插件机制，可以扩展对话智能体的功能。
+该包是纯 SDK 包，不包含任何 UI 组件，可以和任何 UI 框架搭配使用。
+
+## 基本概念
+
+![flow.png](https://static1.tuyacn.com/static/txp-ray-TAgent/flow.png)
+
+### ChatAgent 对话智能体 Agent
+
+对话智能体的核心类，负责管理对话的生命周期，消息的创建，消息的持久化等，支持插件和 hook 机制，可以扩展对话智能体的功能。
+
+使用 `createChatAgent` 创建一个 ChatAgent 实例，如下：
+
+```tsx
+import { createChatAgent } from '@ray-js/t-agent';
+const createAgent = () => {
+  /* 在 createChatAgent 参数里应用插件，注意插件是有顺序的 */
+  const agent = createChatAgent();
+
+  return agent;
+};
+```
+
+主要属性：
+
+- `agent.session` ChatSession 会话容器，用于存储会话相关的数据
+- `agent.plugins` 应用插件后，会在这里存储插件的相关方法和 Hooks
+
+主要方法：
+
+- `agent.start()` 启动
+- `agent.dispose()` 释放
+- `agent.pushInputBlocks(blocks, signal)` 从外部将消息 block 推到 ChatAgent 里，用于用户向 AI 发送消息
+- `agent.createMessage(data)` 创建一个与当前 Agent 绑定的消息
+- `agent.emitTileEvent(tileId: string, payload: any)` tile 发送事件
+- `agent.removeMessage(messageId: string)` 删除消息
+- `agent.flushStreamToShow(message: ChatMessage, response: StreamResponse, composer: ComposeHandler)` 流式更新消息
+
+### Hooks 机制
+
+ChatAgent 仅定义了一个运行框架和数据结构，具体行为是由 Hook 机制实现的，Hook 机制是一种事件驱动的编程模型，通过注册回调函数来实现对话智能体的行为。
+
+```tsx
+import { createChatAgent } from '@ray-js/t-agent';
+const createAgent = () => {
+  const agent = createChatAgent();
+
+  const { onChatStart } = agent;
+
+  // 在对话开始时触发 onChatStart Hook
+  onChatStart(result => {
+    console.log('Chat start', result);
+  });
+  return agent;
+};
+```
+
+ChatAgent 主要 Hook 和参数：
+
+- `agent.onAgentStart` 初始化 Agent
+- `agent.onChatStart` 对话开始时触发
+  - `result.messages` 用于初始化消息列表
+- `agent.onChatResume` 对话恢复时触发
+  - `result.messages` 已经恢复好了的消息列表
+- `agent.onMessageListInit` 对话开始、对话恢复后，消息列表初始化时触发
+  - `result.messages` 用于渲染的消息列表，和前面两个 hooks 的 message 是同一个列表
+- `agent.onInputBlocksPush` 推送消息 block 时触发
+  - `blocks` 输入的消息块 blocks
+  - `signal` 中断信号
+- `agent.onMessageChange` 消息变化时触发
+  - `type` 变化的类型，`show`、`update`、`remove`
+  - `message` 变化的消息
+- `agent.onMessagePersist` 消息持久化时触发
+  - `payload` 持久化相关参数
+  - `message` 持久化的目标消息
+- `agent.onTileEvent` 消息持久化完成时触发
+  - `tile` 触发事件的 tile
+  - `payload` 事件的 payload
+- `agent.onAgentDispose` 释放 Agent 时触发
+- `agent.onUserAbort` 用户中断时触发
+  - `reason` 中断原因
+- `agent.onError` 出错时触发
+  - `error` 错误对象
+
+这些 hooks 都接收一个回调函数作为参数，当触发时会调用这个回调函数，回调函数可以是同步也可以是异步，回调函数的返回不影响结果，
+如果需要改变结果，可以通过修改回调函数的 result 参数或修改 tile、message 对象来修改。
+
+### ChatSession 会话容器
+
+ChatSession 存储和智能体聊天的消息列表，上下文数据等内容，在 ChatAgent 创建时一同创建
+
+主要属性：
+
+- `session.messages` 消息列表
+- `session.sessionId` 会话 id
+- `session.isNewChat` 是否是新会话，用于区分新会话 `onChatStart` 和恢复会话 `onChatResume`
+
+主要方法：
+
+- `session.set` 设置会话数据，可以是任意类型
+- `session.get` 获取会话数据
+- `session.getData` 用对象的方式获取会话数据
+- `session.getLatestMessage` 获取最后一条消息
+
+Hooks:
+
+- `session.onChange` 注册会话数据变化的回调
+
+### ChatMessage 对话消息
+
+ChatMessage 是对话消息的抽象，用于存储消息的内容，状态等信息，也提供了一系列方便的方法用于操作消息。
+一条消息 ChatMessage 下，会有多个 ChatTile，用于展示不同的内容。
+
+创建一条消息使用 `createMessage` 方法，如下：
+
+```tsx
+const createAgent = () => {
+  const agent = createChatAgent();
+
+  const { createMessage, onChatStart } = agent;
+
+  // 初始化聊天时，发送一条消息
+  onChatStart(async result => {
+    // 创建一条由智能体助手发送的消息
+    const message = createMessage({
+      role: 'assistant',
+    });
+
+    // 访问 message.bubble 可以快速创建一个文本气泡
+    message.bubble.setText('Hello!');
+    result.messages.push(message);
+  });
+
+  return agent;
+};
+```
+
+主要属性：
+
+- `message.id` 消息 id
+- `message.role` 消息角色，可以是 assistant 或者 user
+- `message.tiles` 消息的 tile 列表
+- `message.status` 消息状态，`ChatMessageStatus` 枚举，可以是 `START`、`UPDATING`、`FINISH` 等
+- `message.meta` 消息附带的额外数据
+- `message.isShow` 是否已经展示到界面上
+- `message.bubble` 消息中，气泡 tile 的快捷方式
+
+主要方法
+
+- `message.show` 消息展示到界面上
+- `message.update` 将当前消息状态更新到界面上
+- `message.remove` 将当前消息从界面上移除
+- `message.persist` 持久化消息
+- `message.addTile` 添加一个 tile
+- `message.removeTile` 移除一个 tile
+- `message.setTilesLocked` 设置所有的 tile 的锁定状态
+- `message.set` 设置消息的属性
+- `message.setMetaValue` 按 key-value 设置 meta 的属性
+- `message.deleteMetaValue` 删除 meta 的属性
+- `message.setMeta` 直接设置 meta 对象
+- `message.findTileByType` 通过 tile 类型查找 tile
+
+#### ChatTile 对话消息块
+
+ChatTile 是对话消息的块，用于展示消息内的不同内容，例如文本、图片、卡片等。
+
+为消息添加一个 tile 使用 `addTile` 方法，如下：
+
+```tsx
+const message = createMessage({
+  role: 'assistant',
+});
+
+// 添加一个图片 tile
+message.addTile('image', {
+  src: '/image.jpg',
+});
+
+await message.show();
+```
+
+ChatTile 的主要属性：
+
+- `tile.id` tile 的 id
+- `tile.type` tile 类型
+- `tile.data` tile 数据
+- `tile.children` tile 的子 tile
+- `tile.locked` tile 是否被锁定
+- `tile.fallback` 当 tile 无法展示时的回退内容
+- `tile.message` tile 所属的消息
+
+ChatTile 的主要方法：
+
+- `tile.update` 是 `tile.message.update` 的快捷方式
+- `tile.show` 是 `tile.message.show` 的快捷方式
+- `tile.setLocked` 设置 tile 的锁定状态
+- `tile.addTile` 添加一个子 tile
+- `tile.setData` 设置 tile 的数据
+- `tile.setFallback` 设置 tile 的回退内容
+- `tile.findByType` 通过 tile 类型查找子 tile
+
+`message.bubble` 是一个快捷方式，只要访问它，就会在当前的消息中快速添加一个气泡 tile，如下：
+
+```tsx
+const message = createMessage({
+  role: 'assistant',
+});
+
+message.bubble.setText('Hello, world!');
+// 等价于
+message.addTile('bubble', {}).addTile('text', { text: 'Hello, world!' });
+
+await message.show();
+```
+
+针对气泡消息，除了支持 tile 基本方法外，还额外提供了一些属性和方法：
+
+- `message.bubble.text` 属性，读取气泡文本
+- `message.bubble.setText` 方法，设置气泡文本
+- `message.bubble.isMarkdown` 属性，是否是 markdown 格式
+- `message.bubble.setIsMarkdown` 方法，设置是否是 markdown 格式
+- `message.bubble.status` 属性，气泡状态 BubbleTileStatus
+- `message.bubble.setStatus` 方法，设置气泡状态
+- `message.bubble.info` 属性，气泡信息
+- `message.bubble.setInfo` 方法，设置气泡信息
+- `message.bubble.initWithInputBlocks` 方法，用输入块初始化气泡
+
+### 生命周期
+
+ChatAgent 在不同的阶段会触发不同的 Hook，开发者可以通过注册 Hook 来实现自定义行为，下面的时序图展示了 ChatAgent 的生命周期。
+
+```mermaid
+sequenceDiagram
+  participant AI as Backend(AI)
+  participant A as ChatAgent
+  participant UI as UI界面
+  actor User as 用户
+
+  User ->> UI: 打开聊天界面
+  UI ->> UI: 创建 Agent 对象 agent
+  UI ->> A: agent.start() 启动 Agent
+  rect rgba(255,255,0,0.1)
+    note over A: Hook: onAgentStart
+    A ->> AI: 获取是否新会话
+    AI ->> A: 返回
+  end
+  alt 是新会话
+    A ->> AI: 开始新会话
+    note over A: Hook: onChatStart
+  else 是恢复会话
+    A ->> AI: 读取会话历史
+    AI ->> A: 返回历史消息
+    note over A: Hook: onChatResume
+  end
+  rect rgba(255,255,0,0.1)
+    note over A: Hook: onMessageListInit
+    A ->> UI: 组装要展示的消息
+    UI ->> User: 展示消息
+  end
+  opt 对话
+    User ->> UI: 输入并发送消息
+    UI ->> A: agent.pushInputBlocks()
+    rect rgba(255,255,0,0.1)
+      note over A: Hook: onInputBlocksPush
+      A ->> A: 创建 Message 对象 msg<br/>msg 设置为用户输入的文本<br/>msg.show()
+      note over A: Hook: onMessageChange show
+      A -->> UI: 更新界面
+      UI -->> User: 展示新消息
+      A ->> A: 创建 Message 对象 respMsg<br/>respMsg 设置为 loading<br/>respMsg.show()
+      note over A: Hook: onMessageChange show
+      A -->> UI: 更新界面
+      UI -->> User: 展示响应消息loading
+      A ->> AI: 调用 AI
+      AI ->> A: 返回消息流
+      loop 流式消息
+        AI ->> A: 消息包
+        A ->> A: 更新respMsg数据<br/>respMsg.update()
+        note over A: Hook: onMessageChange update
+        A -->> UI: 更新界面
+        UI -->> User: 蹦字/展示卡片
+      end
+    end
+   end
+
+    opt 操作消息行动点（以单选为例）
+       User ->> UI: 选中选项
+       UI ->> A: agent.emitTileEvent()
+       rect rgba(255,255,0,0.1)
+          note over A: Hook: onTileEvent
+          A ->> A: 设置 msg 状态<br/>msg.persist()
+          note over A: Hook: onMessagePersist
+          A ->> AI: 持久化消息
+          AI ->> A: 返回结果
+          A ->> A: msg.update()
+          note over A: Hook: onMessageChange update
+          A ->> UI: 更新界面
+          UI ->> User: 消息置灰，高亮选中
+       end
+    end
+    opt 删除消息
+       User ->> UI: 删除消息
+       UI ->> A: agent.removeMessage()
+       rect rgba(255,255,0,0.1)
+          A ->> A: msg.remove()
+          A ->> AI: 标记消息删除
+          note over A: Hook: onMessageChange remove
+          A ->> UI: 更新界面
+          UI ->> User: 消息消失
+       end
+    end
+```
+
+### Plugin 插件机制
+
+插件是基于以上的 Hook 机制实现的，插件可以实现对话智能体的功能，例如对接 AI 平台，提供 UI 界面等。
+插件也可以暴露一些方法和属性，供开发者使用。
+
+```tsx
+import { createChatAgent, withUI } from '@ray-js/t-agent';
+const createAgent = () => {
+  const agent = createChatAgent(
+    withUI() // withUI 插件提供了一些渲染 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 = () => {
+    // 使用插件暴露的方法
+    agent.plugins.ui.emitEvent('scrollToBottom', { animation: false });
+  };
+
+  return <Button onClick={scroll}>Scroll to bottom</Button>;
+};
+```
+
+#### 编写一个插件
+
+插件是一个高阶函数，接收一个选项，返回一个函数，这个函数接收一个 ChatAgent 对象，可以在这个函数中注册 Hook。
+
+```tsx
+import { ChatAgent, createHooks, Hookable } from '@ray-js/t-agent';
+
+// 试下一个 MyPlugin 插件
+export type MyPlugin = GetChatPluginHandler<typeof withMyPlugin>;
+
+export const withMyPlugin = (options: any) => {
+  // 创建一个 Hookable 对象
+  const hooks = createHooks();
+
+  return (agent: ChatAgent) => {
+    const { onChatStart } = agent;
+
+    onChatStart(async () => {
+      console.log('Chat start');
+      // 触发插件的 Hook
+      await hooks.callHook('onMyHook', 'Hello, world!');
+    });
+
+    // 暴露插件的方法和 Hook
+    return {
+      hooks,
+      myPlugin: {
+        // 暴露一个方法
+        myMethod() {
+          console.log('My method');
+        },
+        // 暴露一个 Hook
+        onMyHook: fn => {
+          return hooks.hook('onMyHook', fn);
+        },
+      },
+    };
+  };
+};
+```
+
+```tsx
+// 使用插件
+import { createChatAgent } from '@ray-js/t-agent';
+
+const createAgent = () => {
+  const agent = createChatAgent(
+    // 使用插件
+    withMyPlugin({})
+  );
+
+  // 调用插件暴露的方法
+  agent.plugins.myPlugin.myMethod();
+
+  // 注册插件的 Hook
+  agent.plugins.myPlugin.onMyHook(msg => {
+    console.log(msg);
+  });
+
+  return agent;
+};
+```
+
+## 内置插件
+
+### withDebug
+
+withDebug 插件会在 console 里打印日志，方便调试
+
+```tsx
+const agent = createChatAgent(
+  withDebug({
+    autoStart: true, // 是否自动启动，默认为 true
+  })
+);
+
+// 启动
+agent.plugins.debug.start();
+
+// 停止
+agent.plugins.debug.stop();
+```
+
+### withUI
+
+withUI 插件提供了一些默认的 UI 行为，例如消息的展示，消息的删除等，消息总线
+
+```tsx
+const agent = createChatAgent(withUI());
+
+agent.plugins.ui.emitter; // 消息总线
+
+// 滚动到底部
+agent.plugins.ui.emitEvent('scrollToBottom', { animation: false });
+
+// 监听事件
+const off = agent.plugins.ui.onEvent('scrollToBottom', payload => {
+  console.log('scroll to bottom', payload.animation);
+});
+
+// 取消监听
+off();
+```
+
+ui 插件的主要事件如下，你还可以自由地注册需要的事件：
+
+- `messageListInit` 初始化消息列表
+  - `payload.messages: ChatMessageObject[]` 消息列表
+- `messageChange` 消息变化
+  - `payload.type: 'show' | 'update' | 'remove'` 变化类型
+  - `payload.message: ChatMessageObject` 消息
+- `scrollToBottom` 滚动到底部
+  - `payload.animation: boolean` 是否使用动画
+- `sendMessage` 发送消息，触发 UI 界面更新
+  - `payload.blocks: InputBlock[]` 输入块
+- `setInputBlocks` 设置输入块到 MessageInput 输入框
+  - `payload.blocks: InputBlock[]` 输入块
+
+> 注意，这里的 ChatMessageObject 是一个消息对象，不是 ChatMessage 类型，
+> 它包含了消息的一些属性和方法，这是为了避免在 UI 层修改消息对象，导致 ChatAgent 中的消息对象不一致。
+> 对消息对象的修改应该始终在 ChatAgent 中进行。
+
+## 附带 utils 工具
+
+### getLogger(prefix: string): Logger
+
+创建一个 logger，用于打印日志
+
+```tsx
+import { getLogger } from '@ray-js/t-agent';
+const logger = getLogger('MyPlugin');
+logger.debug('Hello, world!');
+```
+
+### Emitter 事件总线
+
+Emitter 是一个事件总线，用于注册和触发事件
+
+```tsx
+import { Emitter, EmitterEvent } from '@ray-js/t-agent';
+const emitter = new Emitter();
+
+// 注册事件
+const cb = event => console.log('detail', event.detail);
+emitter.addEventListener('event', cb);
+
+// 触发事件
+emitter.dispatchEvent(new EmitterEvent('event', { detail: 'Hello, world!' }));
+
+// 移除事件
+emitter.removeEventListener('event', cb);
+```
+
+### StreamResponse
+
+StreamResponse 是一个流式响应对象，用于处理流式消息
+
+```tsx
+import { StreamResponse } from '@ray-js/t-agent';
+
+const partStream = await getPartStream(); // 获取流数据
+const response = new StreamResponse(partStream);
+
+const parts = response.parts();
+for await (const part of parts) {
+  console.log('part', part);
+}
+```
+
+### createHooks、Hookable
+
+参见 `hookable` npm 包
+
+### isAbortError
+
+判断是否是中断错误
+
+### safeParseJSON
+
+安全地解析 JSON 字符串，解析失败返回 `undefined`
+
+```tsx
+import { safeParseJSON } from '@ray-js/t-agent';
+
+const obj = safeParseJSON<{ a: number }>('{"a": 1}');
+
+console.log(obj.a); // 1
+```
+
+# t-agent-plugin-assistant
+
+t-agent-plugin-assistant 是一个对接小程序 AI 智能体平台的插件，提供了对接小程序 AI 智能体平台的能力。
+
+## 安装
+
+```shell
+yarn add @ray-js/t-agent-plugin-assistant
+```
+
+## 使用
+
+```tsx
+import { createChatAgent, withUI } from '@ray-js/t-agent';
+import { withAssistant, withBuildIn } from '@ray-js/t-agent-plugin-assistant';
+
+const createAgent = () => {
+  const agent = createChatAgent(
+    withUI(), // 一般都需要应用 withUI 插件
+    withAssistant({
+      channel: 'your-channel-id', // 输入你的智能体ID
+      multiModal: false, // 是否开启多模态，默认为 true
+    }),
+    withBuildIn()
+  );
+
+  return agent;
+};
+```
+
+## 包含的插件
+
+### withAssistant 插件
+
+提供了对接小程序 AI 智能体平台的能力
+
+参数：
+
+- `channel` 智能体 ID
+- `multiModal` 是否开启多模态，默认为 true
+- `wireInputToAssistant` 是否将输入块传递给智能体，默认为 true，设置为 false 时，需要你自己编写 onInputBlocksPush Hook 来处理输入块
+- `historySize` 历史消息大小，默认为 100
+
+方法：
+
+- `agent.plugins.assistant.send` 向智能体发送一条消息
+- `agent.plugins.assistant.chat` 向智能体发送一条消息，并生成提问 ChatMessage 对象和 AI 回答 ChatMessage 对象，流式更新，可以将其用在 onInputBlocksPush 里。
+
+Hooks：
+
+- `onSocketStatusChange` 当网络状态发生变化时触发
+- `onRawMessageParse` 当读取历史消息，解析消息时触发，可以在这个 Hook 里修改消息
+  - `rawItems` 原始消息数据
+  - `result.messages` 消息列表，对一条历史记录一般会解析出两条，一问 `messages[0]` 一答 `messages[1]`，你可以修改这个列表追加或减少消息
+- `onExtensionCompose` 当解析到消息扩展数据时触发
+  - `extension` 扩展数据
+  - `responseMessage` 响应消息
+  - `result.messages` 消息列表
+
+### withBuildIn 插件
+
+提供了一些内置的功能，比如工作流，按钮，推荐行动等，还在实现中
+
+### withAssistantCopyHistory 插件
+
+使用这个插件，在真机预览中，会自动将历史记录复制到剪贴板，方便调试
+
+## mock 机制
+
+为了方便开发，我们提供了一个 mock 机制，可以在开发时不用连接小程序 AI 智能体平台，直接使用 mock 数据进行开发。
+
+### mock 一个 ttt 接口
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-assistant';
+
+// mock 获取历史数据接口
+mock.hooks.hook('getAIAssistantGroupHistory', context => {
+  context.result = yourMockData;
+});
+```
+
+### mock AI 助手响应
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-assistant';
+
+mock.hooks.hook('sendToAssistant', context => {
+  if (context.options.block?.includes('hello')) {
+    context.responseText = 'hello, who are you?';
+  }
+
+  if (context.options.block?.includes('卡片')) {
+    context.responseText = '这是卡片示例';
+    context.responseExtensions = {
+      aiCards: [
+        {
+          cardCode: 'myCard',
+          cardType: ChatCardType.CUSTOM,
+          cardData: { title: '卡片 1' },
+        },
+        {
+          cardCode: 'myCard',
+          cardType: ChatCardType.CUSTOM,
+          cardData: { title: '卡片 2' },
+        },
+      ],
+    };
+  }
+
+  if (context.options.block?.includes('工作流')) {
+    context.responseText = '这是工作流';
+    context.responseExtensions = {
+      workflowAskOptions: {
+        options: [
+          {
+            name: '选项 1',
+            value: '选项 1',
+          },
+          {
+            name: '选项 2',
+            value: '选项 2',
+          },
+          {
+            name: '选项 3',
+            value: '选项 3',
+          },
+        ],
+      },
+    };
+  }
+});
+```
+
+### mock ASR 语音识别
+
+```tsx
+import { mock } from '@ray-js/t-agent-plugin-assistant';
+
+mock.hooks.hook('asrDetection', context => {
+  context.responseText = 'Hello world!, I am a virtual assistant.';
+});
+```
+
+## 附带的 utils 工具（现在不稳定，还在开发中）
+
+### AbortController
+
+这个是小程序里的 AbortController ponyfill，参见 mdn
+
+### runTTTAction
+
+运行一个 TTTAction，用于处理用户的操作行为，目前支持以下动作
+
+- `openRoute` 打开一个路由
+- `openMiniApp` 打开一个小程序
+- `openH5` 打开一个 H5 页面
+- `sendMessage` 发送一条消息
+- `buildIn` 内置行动
+
+### Asr
+
+ASR 语音识别封装，用于识别用户的语音输入
+
+使用方法：
+
+```tsx
+import { Asr, AsrDetectResultState, AsrError } from '@ray-js/t-agent-plugin-assistant';
+
+async function startAsr() {
+  // 先向用户申请权限
+  await Asr.authorize();
+
+  // 初始文本
+  let initial = '';
+
+  // 之前识别的文本
+  let last = initial;
+
+  // 生成一个识别器
+  const asr = Asr.detect(async res => {
+    if (res.state === AsrDetectResultState.STARTING || res.state === AsrDetectResultState.END) {
+      // 全文
+      const full = initial + res.text;
+
+      // 最近一次识别的文本
+      const incoming = full.slice(last.length);
+
+      // 之前识别的文本
+      last = full;
+    }
+
+    if (res.state === AsrDetectResultState.ERROR) {
+      onError(new AsrError(res.errorCode));
+    }
+  });
+
+  // 开始识别
+  await asr.start();
+}
+```
+
+### promisify TTT
+
+内置大量 TTT API 的 promisify 方法，用于将 TTT API 转换为 Promise，同时支持 mock
+
+使用方法：
+
+```tsx
+import { promisify } from '@ray-js/t-agent-plugin-assistant';
+
+interface RouterParams {
+  /** 路由链接 */
+  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，只在 IDE 下生效
+mock.hooks.hook('router', context => {
+  console.log('call router', context.options);
+});
+
+// 调用
+await router({ url: '/pages/index/index' });
+```
+
+### sendBlockToAssistant
+
+给 Assistant 发送消息
+
+```tsx
+import { sendBlockToAssistant, getAIAssistantRequestId } from '@ray-js/t-agent-ui-ray';
+
+const send = async () => {
+  const requestId = await getAIAssistantRequestId();
+  const result = sendBlockToAssistant({
+    channel: 'your-channel-id',
+    sessionId: 'your-session-id',
+    requestId,
+    blocks: [{ type: 'text', text: 'hello' }],
+  });
+
+  // 获取发送后的元数据
+  const meta = await result.metaPromise;
+
+  // 获取流式消息
+  const parts = result.parts();
+
+  for await (const part of parts) {
+    console.log('part', part);
+  }
+};
+```
+
+### sendSkillToAssistant
+
+给 Assistant 发送技能
+
+```tsx
+import { sendSkillToAssistant } from '@ray-js/t-agent-ui-ray';
+
+const send = async () => {
+  const result = sendSkillToAssistant({
+    channel: 'your-channel-id',
+    sessionId: 'your-session-id',
+    options: {
+      domain: 'string',
+      intent: 'string',
+    },
+  });
+
+  // 获取发送后的元数据
+  const meta = await result.metaPromise;
+
+  // 获取流式消息
+  const parts = result.parts();
+
+  for await (const part of parts) {
+    console.log('part', part);
+  }
+};
+```
+
+### authorizeAssistantPolicy
+
+弹窗提醒用户接受 AI 隐私协议，安全要求，在 App 里需要用户同意协议后才能使用 AI 功能
+
+```tsx
+import { authorizeAssistantPolicy } from '@ray-js/t-agent-plugin-assistant';
+
+// 在页面加载完成后调用该函数，弹出协议弹窗
+const authorize = async () => {
+  try {
+    const result = await authorizeAssistantPolicy();
+
+    if (result) {
+      // 已经同意过，或者点了同意按钮
+      console.log('用户同意了 AI 隐私协议');
+    } else {
+      ty.exitMiniProgram({});
+      console.log('用户拒绝了 AI 隐私协议');
+    }
+  } catch (e) {
+    // 弹出错误消息
+    ty.showToast({
+      title: I18n.t('get_sign_error'),
+      icon: 'error',
+    });
+    // 延迟触发，等待用户看清
+    setTimeout(() => {
+      ty.exitMiniProgram({});
+    }, 1000);
+  }
+};
+```
+
+### 媒体文件相关函数
+
+`uploadMedia`、`uploadVideo`、`uploadImage` 用于上传媒体文件，带缓存
+
+`isFullLink` 用于判断是否是 http(s) 协议开头的链接
+
+`parseCloudKey` 用于解析 URL 中云存储的 key
+
+`isLinkExpired` 用于判断链接是否过期
+
+`getUrlByCloudKey` 从缓存中获取云存储的下载签名 URL，如果没有则返回 `undefined`
+
+`setUrlByCloudKey` 设置云存储的下载签名 URL 到缓存中
+
+`resetUrlByCloudKey` 重置云存储的下载签名 URL 缓存
+
+`chooseImage`、`chooseVideo` 选择媒体文件
+
+```tsx
+import { useEffect } from 'react';
+
+async function getPictureList() {
+  // 从云端拉取用户私有的图片列表
+  const list = await pictureListRequest();
+  // 这样设置到缓存里，下次就不用再请求了
+  for (const item of list) {
+    setUrlByCloudKey(item.path, item.displayUrl);
+  }
+}
+```
+
+# t-agent-ui-ray
+
+t-agent-ui-ray 是一个基于 ray 的 UI 组件库，包含了一些常用的对话界面组件，例如消息列表、消息输入框等。
+
+## 安装
+
+```shell
+yarn add @ray-js/t-agent-ui-ray
+```
+
+## 使用
+
+```tsx
+import { ChatContainer, MessageList, MessageInput } from '@ray-js/t-agent-ui-ray';
+// createAgent 实现参见 t-agent 的使用示例
+import { createAgent } from './createAgent';
+
+export default function ChatPage() {
+  // createAgent 必须返回一个 ChatAgent 应用过 withUI、withAssistant 插件的实例
+  return (
+    <View style={{ height: '100vh' }}>
+      <ChatContainer createAgent={createAgent}>
+        <MessageList />
+        <MessageInput />
+      </ChatContainer>
+    </View>
+  );
+}
+```
+
+## 组件
+
+### ChatContainer
+
+对话容器，用于包裹消息列表和消息输入框，提供了 `ChatAgent` 的上下文
+
+props:
+
+- `className` 容器的类名
+- `createAgent` 创建 `ChatAgent` 的函数，在 `ChatContainer` 挂载后会调用这个函数创建 `ChatAgent` 实例
+- `renderOptions` 渲染选项，用于决定 `MessageList` 中各个元素的渲染方式，具体参照下面的 renderOptions 自定义渲染 部分
+  - `renderTileAs` 该函数决定如何在消息中渲染 tile
+  - `customBlockTypes` 自定义 block 类型，只有在这里注册的 block 类型才会被 `renderCustomBlockAs` 渲染
+  - `renderCustomBlockAs` 该函数决定如何在 markdown 气泡消息中渲染自定义 block，默认支持 `echarts`
+  - `renderCardAs` 该函数决定如何在消息中渲染卡片，一般不需要自定义此项
+  - `customCardMap` 自定义卡片映射，无需修改 `renderCardAs` 函数，只需要在这里注册卡片类型和对应的组件
+  - `getStaticResourceBizType` 获取静态资源 `bizType`，用于获取静态资源
+
+### MessageList
+
+消息列表，用于展示消息
+
+props:
+
+- `className` 列表的类名
+- `roleSide` 消息角色的对齐方式，默认 `{ user: 'end', assistant: 'start' }`
+
+### MessageInput
+
+消息输入框，用于输入消息、上传附件、ASR 语音识别
+
+props:
+
+- `className` 输入框的类名
+- `placeholder` 输入框的占位符
+- `renderTop` 用于渲染输入框上方的内容
+
+### PrivateImage
+
+私有图片组件，用于展示私有图片，props 同 Image，增加 bizType 参数
+
+### 内置 tile 组件
+
+- bubble 气泡
+- buttons 按钮组
+- card 卡片
+- image 图片
+- recommendations 推荐行动
+- text 文本，包含 markdown 支持
+- time 时间标识
+- tip 提示
+- video 视频
+- workflow 工作选项
+
+### 内置 card
+
+- WorkflowReplyCard 工作流回复卡片
+
+## React Hooks
+
+### useChatAgent
+
+在 `ChatContainer` 上下文里取得 `ChatAgent` 实例
+
+### useAgentMessage
+
+在 `ChatContainer` 上下文里取得 `messages: ChatMessageObject[]` 列表
+
+### useRenderOptions
+
+在 `ChatContainer` 上下文里取得 `renderOptions` 对象
+
+### useOnEvent
+
+在 `ChatContainer` 上下文里注册 ui 事件，在组件卸载时自动取消注册
+
+```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
+
+在 `ChatContainer` 上下文里触发 ui 事件
+
+```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
+
+在 tile 组件里取得 `TileProps` 对象，如果是 tile，可以直接从 props 中获取
+
+```tsx
+import { useTileProps } from '@ray-js/t-agent-ui-ray';
+
+const MyTilePart = () => {
+  const { message, agent, tile, emitEvent } = useTileProps();
+
+  return <div>My Tile</div>;
+};
+```
+
+### useSendAction
+
+发送一个 TTTAction，注意只能在 tile 组件（或 card）里使用
+
+```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>;
+};
+```
+
+## renderOptions 自定义渲染
+
+### 替换或新增 tile
+
+如果你需要将某个 tile 替换成自己的实现，或者新增一个 tile，可以复写 `renderTileAs`，例如：
+
+```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>) {
+  // 实现自己的 ImageTile
+  return <Image src={props.tile.data.src}></Image>;
+}
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  renderTileAs: (props: TileProps) => {
+    if (props.tile.type === 'image') {
+      return <MyImageTile {...props} />;
+    }
+    // 保持默认行为
+    return defaultRenderOptions.renderTileAs(props);
+  },
+};
+```
+
+### 自定义卡片
+
+卡片分为三类：内置卡片（buildIn）、自定义卡片（custom）、低代码卡片（lowCode），目前低代码卡片还在开发中，自定义卡片可以通过 `customCardMap` 注册自己的卡片组件。
+
+卡片的数据结构如下：
+
+```tsx
+enum ChatCardType {
+  CUSTOM = 'custom', // 可供业务方使用的自定义卡片
+  BUILD_IN = 'buildIn', // 平台内置的卡片
+  LOW_CODE = 'lowCode', // 低代码卡片
+}
+
+interface ChatCardObject<T = any> {
+  cardCode: string; // 唯一标识卡片的 code
+  cardType: ChatCardType; // 卡片类型
+  cardData: T; // 卡片携带的数据
+}
+```
+
+注册一个自定义卡片：
+
+```tsx
+import {
+  ChatCardObject,
+  ChatCardType,
+  defaultRenderOptions,
+  useTileProps,
+  useSendAction,
+} from '@ray-js/t-agent-ui-ray';
+import { View, Text, Button } from '@ray-js/ray';
+
+function MyCard(props: { card: ChatCardObject }) {
+  // 如果你需要拿到 agent、message、tile、emitEvent 等属性，可以使用 useTileProps
+  const { message, agent, tile, emitEvent } = useTileProps();
+
+  // 如果你需要发送一个 TTTAction，可以使用 useSendAction
+  const sendAction = useSendAction();
+
+  return (
+    <View>
+      <Text>My Card</Text>
+      <Button
+        onClick={() =>
+          sendAction({ type: 'sendMessage', blocks: [{ type: 'text', text: 'hello' }] })
+        }
+      >
+        填充文本到输入框
+      </Button>
+    </View>
+  );
+}
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  customCardMap: {
+    myCard: MyCard,
+  },
+};
+```
+
+### 自定义 block
+
+在 `TextTile` 里的 markdown 渲染器是支持自定义 block 的，你可以通过 `customBlockTypes` 和 `renderCustomBlockAs` 来注册和渲染自定义 block。
+
+block 的数据结构如下：
+
+```tsx
+export interface MarkdownBlock {
+  id: string;
+  type: string;
+  children: string; // block 里的内容
+}
+```
+
+注册一个自定义 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(props);
+  },
+};
+```
+
+假设 AI 给你发了 markdown 文本，里面有一个类型是 `my-block` 的 `fence`，在上面我们注册了 `my-block`，那这个 `fence` 可以当做自定义 block。
+
+````markdown
+这是我的自定义 block！
+
+```my-block
+Hello, world!
+```
+
+以下 fence 没有注册过，不会被渲染成自定义 block，仅当做普通的代码块渲染。
+
+```javascript
+console.log('Hello, world!');
+```
+````
+
+渲染结果如下：
+
+```
+这是我的自定义 block！
+This is My Block
+Hello, world!
+以下 fence 没有注册过，不会被渲染成自定义 block，仅当做普通的代码块渲染。
+----------------------------------
+| console.log('Hello, world!');  |
+----------------------------------
+```
+
+### getStaticResourceBizType
+
+如果你的静态资源需要带上 `bizType`，可以通过 `getStaticResourceBizType` 来获取 `bizType`。
+
+```tsx
+import { defaultRenderOptions } from '@ray-js/t-agent-ui-ray';
+
+const renderOptions = {
+  ...defaultRenderOptions,
+  getStaticResourceBizType: (src: string, scene: string) => 'bizType',
+};
+```
+
+针对不同的场景，你可以需要不同的 `bizType`，你可以根据 `src` 和 `scene` 来返回不同的 `bizType`。
+
+内置的 `scene` 有以下几种：
+
+- `image:view` 图片查看
+- `image:upload` 图片上传
+- `video:view` 视频查看
+- `video:upload` 视频上传
+- `videoThumb:view` 视频缩略图查看
+- `videoThumb:upload` 视频缩略图上传