@kernelift/ai-chat 3.0.6 → 3.0.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @kernelift/ai-chat
 
+## 3.0.7
+
+### Patch Changes
+
+- fix some observer bugs.
+
 ## 3.0.6
 
 ### Patch Changes

package/README.md

@@ -168,6 +168,14 @@ AiChat (主容器)
     v-model="message"
     :is-last="isLastMessage"
     :markdown-class="customMarkdownClass"
+    :disabled-markdown-incremental="false"
+    :incremental="message.loading"
+    :on-copy="onCopy"
+    :plugins="markdownPlugins"
+    :options="markdownOptions"
+    :after-render="onMarkdownAfterRender"
+    :markdown-render="CustomMarkdownRender"
+    :ext-events="customActions"
     @bubble-event="handleBubbleEvent"
   >
     <!-- 自定义消息头部 -->
@@ -190,6 +198,23 @@ AiChat (主容器)
 </template>
 ```
 
+#### Props 属性
+
+| 属性名                        | 类型                     | 默认值      | 说明                 |
+| ----------------------------- | ------------------------ | ----------- | -------------------- |
+| `isLast`                      | `boolean`                | -           | 是否为最后一条消息   |
+| `markdownClass`               | `string`                 | -           | Markdown 样式类名    |
+| `onCopy`                      | `(code: string) => void` | `undefined` | 复制代码回调         |
+| `plugins`                     | `any[]`                  | `[]`        | Markdown 插件列表    |
+| `options`                     | `any`                    | `{}`        | Markdown 配置选项    |
+| `afterRender`                 | `(md: any) => void`      | `undefined` | Markdown 渲染后回调  |
+| `markdownRender`              | `Component`              | `MdRender`  | 自定义渲染组件       |
+| `disabledMarkdownIncremental` | `boolean`                | `false`     | 是否禁用增量渲染     |
+| `incremental`                 | `boolean`                | -           | 是否使用增量渲染模式 |
+| `extEvents`                   | `BubbleEventAction[]`    | `[]`        | 扩展事件配置         |
+| `i18n`                        | `Record<string, any>`    | `zhCN`      | 国际化配置           |
+| `isMobile`                    | `boolean`                | `false`     | 是否为移动端模式     |
+
 #### 自定义操作按钮（数据驱动）
 
 操作按钮（复制/重新生成/点赞/点踩）已数据驱动，并可通过 `ext-events` 追加自定义事件，事件名称会在 `bubble-event` 中透出：
@@ -234,6 +259,36 @@ AiChat (主容器)
 - `isError` - 错误状态，显示错误信息
 - `isTerminated` - 已终止生成
 
+### Markdown 增量渲染控制
+
+组件支持 Markdown 内容的增量渲染，在流式生成 AI 回复时实时更新显示。`disabledMarkdownIncremental` 属性用于控制是否禁用此功能。
+
+#### 使用场景
+
+```vue
+<ChatBubble
+  v-model="message"
+  :disabled-markdown-incremental="false"
+  :incremental="message.loading"
+  :markdown-class="markdownClass"
+/>
+```
+
+#### 属性说明
+
+- `disabledMarkdownIncremental` - 是否禁用增量渲染（默认为 false）
+  - `true` - 完整渲染每次更新的内容（适合静态内容）
+  - `false` - 使用增量渲染（适合流式生成）
+
+- `incremental` - 当前是否应该使用增量渲染模式
+  - 通常设置为 `message.loading`，在流式生成时启用增量渲染
+
+#### 性能优化建议
+
+- 对于长文本流式生成，建议启用增量渲染（默认行为）
+- 对于静态或短文本，可以禁用增量渲染以提升性能
+- 增量渲染会自动在每次内容更新时重新计算 DOM 差异
+
 ### ChatSender - 消息发送器
 
 提供消息输入、工具按钮和发送功能。
@@ -284,13 +339,21 @@ AiChat (主容器)
 <template>
   <ChatSidebar
     v-model="activeRecord"
+    v-model:chat-settings="chatSettings"
     :data="records"
     :collapse="isCollapsed"
     :theme-mode="theme"
+    :actions="recordActions"
+    :i18n="i18n"
+    :has-theme-mode="hasThemeMode"
+    :disabled-create-record="disabledCreateRecord"
+    :is-mobile="isMobile"
     @change="handleRecordChange"
+    @clear="handleCreateRecord"
     @change-collapse="handleCollapse"
     @change-theme="handleThemeChange"
     @click-logo="handleLogoClick"
+    @scroll-bottom="handleScrollBottom"
   >
     <!-- 自定义 Logo -->
     <template #logo>
@@ -300,20 +363,151 @@ AiChat (主容器)
       </div>
     </template>
 
+    <!-- 记录底部区域 -->
+    <template #footer>
+      <div class="sidebar-footer">自定义底部内容</div>
+    </template>
+
     <!-- 自定义新建按钮 -->
-    <template #new-chat-button>
-      <button class="new-chat-btn">+ 新建对话</button>
+    <template #new-chat-button="{ execute, disabled }">
+      <button class="new-chat-btn" @click="execute" :disabled="disabled">+ 新建对话</button>
+    </template>
+
+    <!-- 自定义记录下拉菜单 -->
+    <template #record-dropdown>
+      <div class="custom-dropdown">自定义下拉菜单</div>
     </template>
   </ChatSidebar>
 </template>
 ```
 
+#### Props 属性
+
+| 属性名                 | 类型                  | 默认值       | 说明                 |
+| ---------------------- | --------------------- | ------------ | -------------------- |
+| `data`                 | `ChatRecord[]`        | `[]`         | 聊天记录列表         |
+| `actions`              | `ChatRecordAction[]`  | `[]`         | 记录操作按钮配置     |
+| `collapse`             | `boolean`             | `false`      | 是否折叠             |
+| `themeMode`            | `'light' \| 'dark'`   | `'light'`    | 主题模式             |
+| `hasThemeMode`         | `boolean`             | `false`      | 是否支持主题切换     |
+| `disabledCreateRecord` | `boolean`             | `false`      | 是否禁用新建聊天记录 |
+| `i18n`                 | `Record<string, any>` | `zhCN`       | 国际化配置           |
+| `isMobile`             | `boolean`             | `false`      | 是否为移动端模式     |
+| `chatSettings`         | `ChatSettings`        | `{}`         | 聊天设置状态对象     |
+| `actionHeight`         | `string`              | `'2.375rem'` | 操作区域高度         |
+
+#### v-model 双向绑定
+
+| 属性名                 | 类型                 | 说明           |
+| ---------------------- | -------------------- | -------------- |
+| `v-model`              | `ChatRecord \| null` | 当前激活的记录 |
+| `v-model:chatSettings` | `ChatSettings`       | 聊天设置状态   |
+
+#### Events 事件
+
+| 事件名                | 参数                         | 说明         |
+| --------------------- | ---------------------------- | ------------ |
+| `change`              | `(record?: ChatRecord)`      | 切换记录     |
+| `clear`               | -                            | 清空聊天     |
+| `change-collapse`     | `(collapse: boolean)`        | 折叠状态改变 |
+| `change-theme`        | `(theme: 'light' \| 'dark')` | 主题切换     |
+| `click-logo`          | -                            | 点击Logo     |
+| `scroll-bottom`       | -                            | 滚动到底部   |
+| `update:chatSettings` | `(value: ChatSettings)`      | 设置更新     |
+
+#### Slots 插槽
+
+| 插槽名            | 参数                                                        | 说明         |
+| ----------------- | ----------------------------------------------------------- | ------------ |
+| `logo`            | `{ mobile: boolean }`                                       | Logo 区域    |
+| `footer`          | `{ record: ChatRecord \| undefined, mobile: boolean }`      | 记录底部区域 |
+| `new-chat-button` | `{ mobile: boolean, execute: Function, disabled: boolean }` | 新建聊天按钮 |
+| `record-dropdown` | `{ mobile: boolean }`                                       | 记录下拉菜单 |
+
 #### 功能特性
 
 - **历史记录管理** - 创建、切换、删除对话记录
-- **搜索功能** - 快速搜索历史对话
+- **记录分类** - 按日期自动分类：今天、昨天、最近 7 天、最近 30 天、更早
+- **分类折叠** - 支持折叠/展开记录分类
+- **右键菜单** - 桌面端右键显示操作菜单
+- **长按菜单** - 移动端长按记录显示操作菜单
+- **无限滚动** - 滚动到底部触发 `scroll-bottom` 事件
 - **折叠展开** - 支持侧边栏折叠以节省空间
-- **拖拽调整** - 可拖拽调整侧边栏宽度
+- **拖拽调整** - 可拖拽调整侧边栏宽度（桌面端）
+
+#### ChatSettings 状态对象
+
+```typescript
+interface ChatSettings {
+  enableNet: boolean; // 联网搜索启用状态
+  enableThink: boolean; // 深度思考启用状态
+  asideWidth: number; // 侧边栏宽度
+  workspaceWidth: number; // 工作区宽度占比 (20-100)
+  collapse: boolean; // 侧边栏折叠状态
+  showAside: boolean; // 是否显示侧边栏
+  senderVisible: boolean; // 发送框可见性
+  categoryCollapseState: Record<string, boolean>; // 分类折叠状态
+}
+```
+
+#### 记录操作配置示例
+
+```typescript
+const chatRecordActions: ChatRecordAction[] = [
+  {
+    key: 'prompt',
+    label: '提示词',
+    icon: 'pi pi-book text-sm',
+    handler: (record: ChatRecord) => {
+      console.log('设置提示词', record);
+    }
+  },
+  {
+    key: 'edit',
+    label: '编辑名称',
+    icon: 'pi pi-pencil text-sm',
+    handler: (record: ChatRecord) => {
+      console.log('编辑名称', record);
+    }
+  },
+  {
+    key: 'delete',
+    label: '删除',
+    icon: 'pi pi-trash text-sm',
+    handler: (record: ChatRecord) => {
+      console.log('删除记录', record);
+    }
+  }
+];
+```
+
+### 状态持久化
+
+组件使用 `useStorage` 自动保存聊天设置到 localStorage，所有设置在页面刷新后自动恢复。
+
+```typescript
+// ChatSettings 状态结构
+interface ChatSettings {
+  enableNet: boolean; // 联网搜索启用状态
+  enableThink: boolean; // 深度思考启用状态
+  asideWidth: number; // 侧边栏宽度 (桌面端)
+  workspaceWidth: number; // 工作区宽度占比 (20-100, 桌面端)
+  collapse: boolean; // 侧边栏折叠状态
+  showAside: boolean; // 是否显示侧边栏 (移动端)
+  senderVisible: boolean; // 发送框可见性
+  categoryCollapseState: Record<string, boolean>; // 分类折叠状态
+}
+
+// 自动保存的设置包括：
+// - enableNet: 是否启用联网搜索
+// - enableThink: 是否启用深度思考
+// - asideWidth: 侧边栏宽度
+// - workspaceWidth: 工作区宽度百分比
+// - collapse: 侧边栏是否折叠
+// - showAside: 是否显示侧边栏
+// - senderVisible: 发送框是否显示
+// - categoryCollapseState: 各个记录分类的折叠状态
+```
 
 ## 🎯 高级功能
 
@@ -2193,12 +2387,15 @@ export const useChat = (options: {
 
 | 属性名                        | 类型                     | 默认值      | 说明                                               |
 | ----------------------------- | ------------------------ | ----------- | -------------------------------------------------- |
+| `uuid`                        | `string`                 | `'default'` | 实例唯一标识，用于存储状态                         |
 | `records`                     | `ChatRecord[]`           | `[]`        | 聊天记录列表                                       |
 | `recordActions`               | `ChatRecordAction[]`     | `[]`        | 记录操作按钮配置                                   |
 | `bubbleExtEvents`             | `BubbleEventAction[]`    | `[]`        | 气泡扩展事件配置                                   |
 | `hasHeader`                   | `boolean`                | `true`      | 是否显示头部                                       |
-| `headerHeight`                | `number`                 | `38`        | 头部高度 (px)                                      |
+| `headerHeight`                | `number`                 | `32`        | 头部高度 (px)                                      |
 | `hasThemeMode`                | `boolean`                | `false`     | 是否支持主题切换                                   |
+| `inputHeight`                 | `number`                 | `140`       | 输入框最大高度 (px)                                |
+| `defaultInputHeight`          | `number`                 | `62`        | 输入框初始默认高度 (px)                            |
 | `hasThinking`                 | `boolean`                | `true`      | 是否支持深度思考                                   |
 | `hasNetSearch`                | `boolean`                | `false`     | 是否支持联网搜索                                   |
 | `hasSenderTools`              | `boolean`                | `false`     | 是否显示发送工具区                                 |
@@ -2215,18 +2412,15 @@ export const useChat = (options: {
 | `enableNet`                   | `boolean`                | `undefined` | 联网搜索启用状态                                   |
 | `enableThink`                 | `boolean`                | `undefined` | 深度思考启用状态                                   |
 | `disabledCreateRecord`        | `boolean`                | `false`     | 是否禁用新建聊天记录                               |
-| `inputHeight`                 | `number`                 | `140`       | 输入框最大高度 (px)                                |
-| `defaultInputHeight`          | `number`                 | `62`        | 输入框初始默认高度 (px)                            |
 | `onCopy`                      | `(code: string) => void` | `undefined` | 复制代码回调                                       |
 | `i18n`                        | `Record<string, any>`    | `zhCN`      | 国际化配置                                         |
 | `autoScroll`                  | `boolean`                | `true`      | 是否自动滚动到底部                                 |
 | `autoScrollPauseTime`         | `number`                 | `3000`      | 用户滚动时自动滚动暂停时间 (ms)                    |
-| `uuid`                        | `string`                 | `'default'` | 实例唯一标识，用于存储状态                         |
 | `markdownPlugins`             | `any[]`                  | `[]`        | Markdown 插件列表                                  |
 | `markdownOptions`             | `any`                    | `{}`        | Markdown 配置选项                                  |
 | `markdownRender`              | `Component`              | `MdRender`  | 自定义 markdown 渲染组件                           |
 | `onMarkdownAfterRender`       | `(md: any) => void`      | `undefined` | Markdown 渲染后回调                                |
-| `disabledMarkdownIncremental` | `boolean`                | `false`     | 是否禁用Markdown增量渲染功能，默认开启             |
+| `disabledMarkdownIncremental` | `boolean`                | `false`     | 是否禁用 Markdown 增量渲染功能，默认开启           |
 
 ### v-model 双向绑定
 
@@ -2292,32 +2486,119 @@ export const useChat = (options: {
 | `isMobile`       | `Ref<boolean>`              | 是否为移动端模式 |
 | `collapse`       | `Ref<boolean>`              | 侧边栏折叠状态   |
 | `asideWidth`     | `Ref<number>`               | 侧边栏宽度       |
+| `workspaceWidth` | `Ref<number>`               | 工作区宽度占比   |
 | `scrollToBottom` | `(smooth: boolean) => void` | 滚动到底部       |
 
+### 组件导出
+
+```typescript
+// 导入所有组件
+import {
+  AiChat, // 主容器组件
+  ChatBubble, // 消息气泡组件
+  ChatHeader, // 头部组件
+  ChatSidebar, // 侧边栏组件
+  ChatSender, // 发送器组件
+  ThinkingProcess // 思考过程组件
+} from '@kernelift/ai-chat';
+
+// SSE 客户端
+import { SSEClient } from '@kernelift/ai-chat';
+
+// 类型导出
+import type {
+  ChatMessage, // 聊天消息类型
+  ChatRecord, // 聊天记录类型
+  BubbleEvent, // 气泡事件类型
+  BubbleEventAction, // 气泡操作类型
+  ChatRecordAction, // 记录操作类型
+  ChatProps, // 聊天组件属性
+  ChatEvents, // 聊天事件类型
+  ChatSlots // 聊天插槽类型
+} from '@kernelift/ai-chat';
+
+// 国际化消息
+import { i18nMessages } from '@kernelift/ai-chat';
+```
+
 ### 类型定义
 
 #### ChatMessage
 
 ```typescript
 interface ChatMessage {
+  /**
+   * 消息id
+   */
   id: string;
+  /**
+   * 角色
+   */
   role: 'user' | 'assistant' | 'system';
+  /**
+   * 内容
+   */
   content: string;
+  /**
+   * 是否正在加载
+   */
   loading?: boolean;
+  /**
+   * 是否正在思考
+   */
   isThinking?: boolean;
+  /**
+   * 思考是否折叠
+   */
   thoughtCollapse?: boolean;
+  /**
+   * 思考过程
+   */
   thoughtProcess?: string;
+  /**
+   * 创建时间
+   */
   timestamp: number;
+  /**
+   * 是否终止
+   */
   isTerminated?: boolean;
+  /**
+   * 是否点赞
+   */
   isLiked?: boolean;
+  /**
+   * 是否踩
+   */
   isDisliked?: boolean;
+  /**
+   * 是否错误
+   */
   isError?: boolean;
+  /**
+   * 错误信息
+   */
   error?: string;
+  /**
+   * 是否收藏
+   */
   isBookmarked?: boolean;
+  /**
+   * 下一步提示
+   */
   nextTips?: string[];
+  /**
+   * 工具调用
+   */
   toolCalls?: any[];
+  /**
+   * 是否隐藏底部工具
+   */
   hideFooterTools?: boolean;
-  extraData?: Record<string, any>;
+  /**
+   * 额外的数据
+   */
+  extraData?: { [key: string]: any };
 }
 ```
 
@@ -2347,12 +2628,13 @@ type BubbleEvent = 'like' | 'dislike' | 'bookmark' | 'terminate' | 'reload' | 'c
 
 ```typescript
 interface ChatRecordAction {
-  id: string;
-  name: string;
-  icon?: string | Component;
-  divided?: boolean;
-  disabled?: boolean;
-  action: (record: ChatRecord) => void;
+  key: string; // 操作唯一标识
+  label: string; // 操作标签文本
+  icon?: string | Component; // 操作图标
+  divided?: boolean; // 是否显示分隔线
+  disabled?: boolean | ((record: ChatRecord) => boolean); // 是否禁用（可以是布尔值或函数）
+  show?: boolean | ((record: ChatRecord) => boolean); // 是否显示（可以是布尔值或函数）
+  handler: (record: ChatRecord) => void; // 操作处理函数
 }
 ```