From 52b4d2c4aef1985aaa8498d0d5fd317008171469 Mon Sep 17 00:00:00 2001 From: dingyi Date: Fri, 15 Nov 2024 10:13:45 +0800 Subject: [PATCH] docs(development): add API references for ChatLuna utilities and events - Add API reference for ChatLuna events - Add documentation for ChatLuna logger utility - Add documentation for ChatLuna request utility - Add documentation for ChatLuna SSE utility --- .../api-reference/chatluna-events.md | 100 ++++++++++++++++++ .../api-reference/chatluna-utils/logger.md | 30 ++++++ .../api-reference/chatluna-utils/request.md | 56 ++++++++++ .../api-reference/chatluna-utils/sse.md | 54 ++++++++++ 4 files changed, 240 insertions(+) create mode 100644 docs/development/api-reference/chatluna-events.md create mode 100644 docs/development/api-reference/chatluna-utils/logger.md create mode 100644 docs/development/api-reference/chatluna-utils/request.md create mode 100644 docs/development/api-reference/chatluna-utils/sse.md diff --git a/docs/development/api-reference/chatluna-events.md b/docs/development/api-reference/chatluna-events.md new file mode 100644 index 0000000..452982a --- /dev/null +++ b/docs/development/api-reference/chatluna-events.md @@ -0,0 +1,100 @@ +# ChatLuna 事件 + +> [!TIP] 提示 +> 参见 [Koishi 事件](https://koishi.chat/zh-CN/guide/basic/events.html) + +ChatLuna 也提供一些事件，用于监听和处理一些复杂的功能。 + +## 通用事件 + +ChatLuna 的通用会话事件。 + +### 事件：chatluna/before-check-sender + +- **session**: `Session` 会话 +- **返回值**: `boolean` 是否继续处理 +- **触发方式**: serial + +在 ChatLuna 处理会话之前，触发该事件。 + +当返回值为 `true`，ChatLuna 将不会处理该会话。 + +## 生命周期事件 + +ChatLuna 的生命周期事件，监听某些模型或者工具的变化。 + +### 事件：chatluna/chat-chain-added + +- **service**: `PlatformService` 平台服务 +- **chain**: `ChatLunaChainInfo` 聊天链信息 +- **触发方式**: emit + +当一个聊天链（聊天模式）被添加时，触发该事件。 + +### 事件：chatluna/chat-chain-removed + +- **service**: `PlatformService` 平台服务 +- **chain**: `ChatLunaChainInfo` 聊天链信息 +- **触发方式**: emit + +当一个聊天链（聊天模式）被移除时，触发该事件。 + +### 事件：chatluna/tool-updated + +- **service**: `PlatformService` 平台服务 +- **触发方式**: emit + +当有工具被添加或移除时，触发该事件。 + +### 事件：chatluna/model-added + +- **service**: `PlatformService` 平台服务 +- **platform**: `PlatformClientNames` 被添加的平台 +- **client**: `BasePlatformClient | BasePlatformClient[]` 被添加的平台 Client 实现 +- **触发方式**: emit + +当有模型（适配器）被添加时，触发该事件。 + +### 事件：chatluna/model-removed + +- **service**: `PlatformService` 平台服务 +- **platform**: `PlatformClientNames` 被移除的平台 +- **client**: `BasePlatformClient | BasePlatformClient[]` 被移除的平台 Client 实现 +- **触发方式**: emit + +当有模型（适配器）被移除时，触发该事件。 + +### 事件：chatluna/embeddings-added + +- **service**: `PlatformService` 平台服务 +- **platform**: `PlatformClientNames` 被添加的平台 +- **client**: `BasePlatformClient | BasePlatformClient[]` 被添加的平台 Client 实现 +- **触发方式**: emit + +当有嵌入模型（适配器）被添加时，触发该事件。 + +### 事件：chatluna/embeddings-removed + +- **service**: `PlatformService` 平台服务 +- **platform**: `PlatformClientNames` 被移除的平台 +- **client**: `BasePlatformClient | BasePlatformClient[]` 被移除的平台 Client 实现 +- **触发方式**: emit + +当有嵌入模型（适配器）被移除时，触发该事件。 + +### 事件：chatluna/vector-store-added + +- **service**: `PlatformService` 平台服务 +- **name**: `string` 向量存储数据名称 +- **触发方式**: emit + +当有向量存储数据库被添加时，触发该事件。 + +### 事件：chatluna/vector-store-removed + +- **service**: `PlatformService` 平台服务 +- **name**: `string` 向量存储数据名称 +- **触发方式**: emit + +当有向量存储数据库被移除时，触发该事件。 + diff --git a/docs/development/api-reference/chatluna-utils/logger.md b/docs/development/api-reference/chatluna-utils/logger.md new file mode 100644 index 0000000..a751a2a --- /dev/null +++ b/docs/development/api-reference/chatluna-utils/logger.md @@ -0,0 +1,30 @@ +# 日志 + +Koishi 本身已经自带了好用的日志工具。 + +ChatLuna 基于其简易的封装了一下，主要是为了支持 [isLog](../../../guide/useful-configurations.md#islog) 配置。 + +这样当用户开启 `isLog` 配置时，`debug` 日志将会输出到 Koishi 日志中。 + +## 基础用法 + +```typescript +import { createLogger } from 'koishi-plugin-chatluna/utils/logger' + +const logger = createLogger(ctx, 'MyLogger') +``` + +## API + +### createLogger(ctx, name) + +- **ctx**: `Context` Koishi 的上下文 +- **name**: `string` 日志实例名称 + +创建一个日志实例。 + +### setLoggerLevel(level) + +- **level**: `number` 日志级别 + +设置日志级别。 diff --git a/docs/development/api-reference/chatluna-utils/request.md b/docs/development/api-reference/chatluna-utils/request.md new file mode 100644 index 0000000..b129cf3 --- /dev/null +++ b/docs/development/api-reference/chatluna-utils/request.md @@ -0,0 +1,56 @@ +# 请求工具 + +ChatLuna 基于 `fetch` 和 `ws` 封装了请求工具，添加了代理支持。 + +默认情况下，代理会被设置为 [这里](../../../guide/useful-configurations.md#proxyaddress) 的配置。 + +> [!TIP] 提示 +> 我们更推荐模型适配器的实现者使用 `ChatLunaPlugin` 提供的 `fetch` 和 `ws` 方法。 +> 参考 [ChatLunaPlugin](../api-reference/chatluna-plugin)。 + +## 基础用法 + +```typescript +import { chatLunaFetch, ws, randomUA } from 'koishi-plugin-chatluna/utils/request' + +const response = await chatLunaFetch('https://api.example.com/data', { + method: 'GET', +}, "http://localhost:7890") + +const wsClient = ws('wss://api.example.com/ws', { + withCredentials: true, +}, "http://localhost:7890") + +const ua = randomUA() +``` + +## API + +### chatLunaFetch(url, init, proxy) + +- **url**: `string` 请求 URL +- **init**: `RequestInit` 请求配置 +- **proxy**: `string?` 代理地址 +- 返回值: `Promise` + +建立一个 `fetch` 请求。 + +> [!TIP] 注意 +> 如果 `proxy` 参数传递为 'null'(注意是纯文本的 `null`，不是 `null` 变量)，则不会使用代理。 + +### ws(url, init, proxy) + +- **url**: `string` 请求 URL +- **init**: `WebSocketConstructorInit` 请求配置 +- **proxy**: `string?` 代理地址 +- 返回值: `WebSocket` +建立一个 `ws` 请求。 + +> [!TIP] 注意 +> 如果 `proxy` 参数传递为 'null'(注意是纯文本的 `null`，不是 `null` 变量)，则不会使用代理。 + +### randomUA() + +- 返回值: `string` + +生成一个随机的 User-Agent。用于模拟浏览器请求。 diff --git a/docs/development/api-reference/chatluna-utils/sse.md b/docs/development/api-reference/chatluna-utils/sse.md new file mode 100644 index 0000000..487d745 --- /dev/null +++ b/docs/development/api-reference/chatluna-utils/sse.md @@ -0,0 +1,54 @@ +# SSE + +ChatLuna 提供了 Server-Sent Events (SSE) 工具。 + +## 基础用法 + +```typescript +import { sse, sseIterable } from 'koishi-plugin-chatluna/utils/sse' + + +const response = await chatLunaFetch('https://api.example.com/sse') + +await sse(response, async (rawData) => { + console.log('收到数据:', rawData) +}) + +for await (const event of sseIterable(response)) { + if (event === '[DONE]') { + console.log('SSE 传输完成') + break + } + console.log('收到事件:', event) +} + +``` + +## API + +### sse(response, onEvent, cacheCount) + +- **response**: `Response | ReadableStreamDefaultReader` SSE 响应对象 +- **onEvent**: `(rawData: string) => Promise` 事件处理回调函数 +- **cacheCount**: `number` 缓存计数，默认为 0 +- 返回值: `Promise` + +处理 SSE 响应流，通过回调函数处理每个事件数据。当 `cacheCount` 大于 0 时，将累积指定数量的事件后一次性调用回调函数。 + +### sseIterable(response) + +- **response**: `Response | ReadableStreamDefaultReader` SSE 响应对象 +- 返回值: `AsyncGenerator` + +将 SSE 响应转换为异步迭代器，每次迭代返回一个事件数据。当所有事件处理完成时，返回 `'[DONE]'`。 + +### rawSeeAsIterable(response, cacheCount) + +- **response**: `Response | ReadableStreamDefaultReader` SSE 响应对象 +- **cacheCount**: `number` 缓存计数，默认为 0 +- 返回值: `AsyncGenerator` + +将 SSE 响应转换为原始数据的异步迭代器。当 `cacheCount` 大于 0 时，将累积指定数量的原始数据后一次性产出。 + +> [!TIP] 注意 +> `rawSeeAsIterable` 返回的是未经解析的原始 SSE 数据流，而 `sseIterable` 返回的是经过解析的事件数据。