@opentiny/tiny-robot-kit 0.4.0 → 0.4.1

package/README.md

@@ -1,289 +1,86 @@
 # tiny-robot-kit
 
-封装与与AI大模型的交互逻辑与数据处理，适配多种模型提供商，提供统一的API接口。
+@opentiny/tiny-robot-kit 是 TinyRobot 提供的数据层工具包，用于统一处理 AI 大模型调用、消息状态与多会话管理。
+它帮助你在任意 UI 上快速实现聊天、流式响应和会话持久化等常见 AI 交互能力。
 
-## API参考
+## 功能概览
 
-### AIClient
+- **消息管理**：`useMessage` 管理消息状态与模型交互流程。
+- **会话管理**：`useConversation` 在 useMessage 之上提供多会话能力。
+- **工具函数（Utils）**：处理 SSE、消息格式与响应解析。
 
-主要客户端类，用于与AI模型交互。
+完整 API 请参考文档：
 
-#### 构造函数
+- `useMessage`：<https://docs.opentiny.design/tiny-robot/tools/message>
+- `useConversation`：<https://docs.opentiny.design/tiny-robot/tools/conversation>
+- 工具函数：<https://docs.opentiny.design/tiny-robot/tools/utils>
 
-```typescript
-new AIClient(config: AIModelConfig)
-```
-
-#### 方法
-
-- `chat(request: ChatCompletionRequest): Promise<ChatCompletionResponse>`
-  发送聊天请求并获取响应。
-
-- `chatStream(request: ChatCompletionRequest, handler: StreamHandler): Promise<void>`
-  发送流式聊天请求并通过处理器处理响应。
-
-
-## 基本用法
-
-### 创建客户端并发送消息
-
-```typescript
-import { AIClient } from '@opentiny/tiny-robot-kit';
-
-// 创建客户端
-const client = new AIClient({
-  provider: 'openai',
-  apiKey: 'your-api-key',
-  defaultModel: 'gpt-3.5-turbo'
-});
+## 安装
 
-// 发送消息并获取响应
-async function chat() {
-  try {
-    const response = await client.chat({
-      messages: [
-        { role: 'system', content: '你是一个有用的助手。' },
-        { role: 'user', content: '你好，请介绍一下自己。' }
-      ],
-      options: {
-        temperature: 0.7
-      }
-    });
-    
-    console.log(response.choices[0].message.content);
-  } catch (error) {
-    console.error('聊天出错:', error);
-  }
-}
-
-chat();
-```
-
-### 使用流式响应
-
-```typescript
-import { AIClient } from '@opentiny/tiny-robot-kit';
-
-const client = new AIClient({
-  provider: 'openai',
-  apiKey: 'your-api-key'
-});
-
-async function streamChat() {
-  try {
-    const controller: AbortController = new AbortController()
-    await client.chatStream({
-      messages: [
-        { role: 'user', content: '写一个简短的故事。' }
-      ],
-      options: {
-        stream: true, // 启用流式响应
-        signal: controller.signal  // 传递 AbortController 的 signal用于中断请求
-      }
-    }, {
-      onData: (data) => {
-        // 处理流式数据
-        const content = data.choices[0]?.delta?.content || '';
-        process.stdout.write(content);
-      },
-      onError: (error) => {
-        console.error('流式响应错误:', error);
-      },
-      onDone: () => {
-        console.log('\n流式响应完成');
-      }
-    });
-    // controller.abort() // 中断请求
-  } catch (error) {
-    console.error('流式聊天出错:', error);
-  }
-}
-
-streamChat();
+```bash
+pnpm add @opentiny/tiny-robot-kit
+# 或
+npm install @opentiny/tiny-robot-kit
+yarn add @opentiny/tiny-robot-kit
 ```
 
-### useMessage
-
-#### 选项
-
-`useMessage` 接受以下选项：
-
-```typescript
-interface UseMessageOptions {
-  /** AI客户端实例 */
-  client: AIClient;
-  /** 是否默认使用流式响应 */
-  useStreamByDefault?: boolean;
-  /** 错误消息模板 */
-  errorMessage?: string;
-  /** 初始消息列表 */
-  initialMessages?: ChatMessage[];
-}
-```
-
-#### 返回值
-
-`useMessage` 返回以下内容：
-```typescript
-interface UseMessageReturn {
-  messages: ChatMessage[];
-  /** 消息状态 */
-  messageState: Reactive<MessageState>;
-  /** 输入消息 */
-  inputMessage: Ref<string>;
-  /** 是否使用流式响应 */
-  useStream: Ref<boolean>;
-  /** 发送消息 */
-  sendMessage: (content?: string, clearInput?: boolean) => Promise<void>
-  /** 清空消息 */
-  clearMessages: () => void;
-  /** 添加消息 */
-  addMessage: (message: ChatMessage) => void;
-  /** 中止请求 */
-  abortRequest: () => void;
-  /** 重试请求 */
-  retryRequest: () => Promise<void>;
-}
-```
-
-#### MessageState 接口
-```typescript
-interface MessageState {
-  status: STATUS
-  errorMsg: string | null
-}
-
-enum STATUS {
-  INIT = 'init', // 初始状态
-  PROCESSING = 'processing', // AI请求正在处理中, 还未响应，显示加载动画
-  STREAMING = 'streaming', // 流式响应中分块数据返回中
-  FINISHED = 'finished', // AI请求已完成
-  ABORTED = 'aborted', // 用户中止请求
-  ERROR = 'error', // AI请求发生错误
-}
-```
-
-### useConversation
-
-对话管理与数据持久化
-
-#### 基本用法
+## 基本用法
 
-```typescript
-import { useConversation, AIClient } from '@opentiny/tiny-robot-kit'
+### useMessage —— 管理 AI 消息
 
-const client = new AIClient({
-  provider: 'openai',
-  apiKey: 'your-api-key',
-  defaultModel: 'gpt-3.5-turbo'
-});
+`useMessage` 管理消息列表、请求/处理状态、流式响应、插件体系以及工具调用逻辑，而真正的 HTTP 请求由你提供的 `responseProvider` 负责。
 
-const {
-  state,
-  messageManager, // 与 useMessage 返回一致，具体查看useMessage
-  createConversation,
-  switchConversation,
-  deleteConversation,
-  // ...
-} = useConversation({ client })
+```ts
+import { useMessage } from '@opentiny/tiny-robot-kit'
 
-const conversationId = createConversation('新对话')
+const message = useMessage({
+  // responseProvider 负责调用你的后端 / 模型接口
+  async responseProvider(requestBody, abortSignal) {
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      body: JSON.stringify(requestBody),
+      signal: abortSignal,
+      headers: { 'Content-Type': 'application/json' },
+    })
 
-messageManager.sendMessage('你好，请介绍一下自己')
+    return await res.json()
+  },
+})
 ```
 
-#### 返回值
+更多进阶用法（流式响应、插件、自定义分块（chunk）处理、工具调用等），请查看 <https://docs.opentiny.design/tiny-robot/tools/message>。
 
-`useConversation` 返回以下内容：
+### useConversation —— 管理多会话
 
-```typescript
-interface UseConversationReturn {
-  /** 会话状态 */
-  state: ConversationState;
-  /** 消息管理 */
-  messageManager: UseMessageReturn;
-  /** 创建新会话 */
-  createConversation: (title?: string, metadata?: Record<string, any>) => string;
-  /** 切换会话 */
-  switchConversation: (id: string) => void;
-  /** 删除会话 */
-  deleteConversation: (id: string) => void;
-  /** 更新会话标题 */
-  updateTitle: (id: string, title: string) => void;
-  /** 更新会话元数据 */
-  updateMetadata: (id: string, metadata: Record<string, any>) => void;
-  /** 保存会话 */
-  saveConversations: () => Promise<void>;
-  /** 加载会话 */
-  loadConversations: () => Promise<void>;
-  /** 生成会话标题 */
-  generateTitle: (id: string) => Promise<string>;
-  /** 获取当前会话 */
-  getCurrentConversation: () => Conversation | null;
-}
-```
+`useConversation` 基于 `useMessage` 之上，提供多会话管理能力，并支持多种存储策略（LocalStorage、IndexedDB、自定义等）。
 
-#### 会话状态
+```ts
+import { useConversation } from '@opentiny/tiny-robot-kit'
 
-```typescript
-interface ConversationState {
-  /** 会话列表 */
-  conversations: Conversation[];
-  /** 当前会话ID */
-  currentId: string | null;
-  /** 是否正在加载 */
-  loading: boolean;
-}
+const { conversations, activeConversation, createConversation, switchConversation } = useConversation({
+  useMessageOptions: {
+    async responseProvider(requestBody, abortSignal) {
+      const res = await fetch('/api/chat', {
+        method: 'POST',
+        body: JSON.stringify(requestBody),
+        signal: abortSignal,
+        headers: { 'Content-Type': 'application/json' },
+      })
+      return await res.json()
+    },
+  },
+})
 ```
 
-#### 会话接口
-
-```typescript
-
-interface Conversation {
-  /** 会话ID */
-  id: string;
-  /** 会话标题 */
-  title: string;
-  /** 创建时间 */
-  createdAt: number;
-  /** 更新时间 */
-  updatedAt: number;
-  /** 自定义元数据 */
-  metadata?: Record<string, any>;
-  /** 消息 */
-  messages: ChatMessage[];
-}
-```
+例如 `localStorageStrategyFactory` 和 `indexedDBStorageStrategyFactory` 等存储策略的详细用法，请参考 <https://docs.opentiny.design/tiny-robot/tools/conversation>。
 
-#### 自定义存储策略
+### 工具函数 Utils —— 处理 SSE 与响应
 
-默认使用 LocalStorage 存储会话数据，你也可以实现自定义的存储策略：
+Utils 模块提供了一些与 `useMessage` 搭配使用的常用工具函数：
 
-```typescript
-interface ConversationStorageStrategy {
-  /** 保存会话列表 */
-  saveConversations: (conversations: Conversation[]) => Promise<void> | void;
-  /** 加载会话列表 */
-  loadConversations: () => Promise<Conversation[]> | Conversation[];
-}
-
-// 自定义存储策略示例
-class CustomStorageStrategy implements ConversationStorageStrategy {
-  async saveConversations(conversations: Conversation[]) {
-    // 实现自定义存储逻辑
-  }
-
-  async loadConversations(): Promise<Conversation[]> {
-    // 实现自定义加载逻辑
-    return [];
-  }
-}
-
-// 使用自定义存储策略
-const conversationManager = useConversation({
-  client,
-  storage: new CustomStorageStrategy(),
-});
-```
+- `sseStreamToGenerator`：把 SSE `Response` 转换为异步生成器。
+- `formatMessages`：将多种形式的消息统一为 `ChatMessage[]`。
+- `extractTextFromResponse`：从大模型响应中提取纯文本内容。
+- `handleSSEStream`：通过回调方式消费 SSE 流式响应。
 
+详细函数签名与行为说明，请查看 <https://docs.opentiny.design/tiny-robot/tools/utils>。

package/package.json

@@ -1,10 +1,36 @@
 {
   "name": "@opentiny/tiny-robot-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
+  "homepage": "https://docs.opentiny.design/tiny-robot/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opentiny/tiny-robot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/opentiny/tiny-robot/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
   "description": "AI大模型请求与数据处理工具包",
+  "keywords": [
+    "vue",
+    "vue3",
+    "ai",
+    "ai-client",
+    "ai-sdk",
+    "chat",
+    "chatbot",
+    "llm",
+    "openai",
+    "assistant",
+    "streaming",
+    "composables",
+    "conversation",
+    "model-provider",
+    "tiny-robot",
+    "opentiny"
+  ],
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -29,5 +55,5 @@
   "dependencies": {
     "idb": "^8.0.3"
   },
-  "gitHead": "558095a424930d99e079e6e1cf4fe8929d48c7b2"
+  "gitHead": "e7d831041cd49068110e17c5b5f410ed7fa2706c"
 }