@legendzd/ai-agent-vue 1.0.1

package/README.md

@@ -0,0 +1,679 @@
+# @legendzd/ai-agent-vue
+
+可嵌入的 AI 智能体 Vue 3 插件 — 三种布局模板（弹窗/全屏/手机端）、多实例隔离、SSE 流式对话、Markdown/图表/数据表格渲染、历史记录切换。
+
+## 特性
+
+- **三种布局模板** — 按钮弹窗（AgentChatPopup）、完整 Web 窗口（AgentChatFull）、手机端（AgentChatMobile），引入即用
+- **多实例隔离** — 通过 `instanceId` 创建独立对话实例，不同用户/场景互不干扰
+- **零配置即插即用** — 内置 Pinia + 持久化，宿主应用无需额外安装状态管理
+- **会话管理** — 自动创建会话、历史记录、一键切换/新建对话
+- **SSE 流式对话** — 支持 status/sql/data/chart_config/sources/analysis_chunk 等富事件类型
+- **富内容渲染** — Markdown 代码高亮、SQL 可展开复制、结构化数据表格、ECharts 图表、来源标签
+- **深色/浅色主题** — 通过 CSS 变量一键切换或自定义覆盖，所有布局均支持
+- **语音输入** — 基于浏览器 Web Speech API，可配置语言
+- **组件实例 API** — 通过 ref 直接访问对话数据、控制会话
+- **组件拆分** — AgentWindow、AgentHistoryList 等可独立使用，通过 instanceId 关联状态
+
+## 安装
+
+```bash
+npm install @legendzd/ai-agent-vue
+```
+
+> 仅需 Vue 3.3+ 作为 peer dependency，其余依赖（Pinia、ECharts 等）已内置。
+
+## 快速开始
+
+### 方式一：插件注册（推荐）
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+import { AgentPlugin } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(AgentPlugin, {
+  apiUrl: 'http://your-server/api/v2',
+  userId: 'user123',
+})
+app.mount('#app')
+```
+
+在模板中直接使用（插件注册后组件全局可用）：
+
+```vue
+<template>
+  <!-- 按钮弹窗布局（默认） -->
+  <AgentChat />
+
+  <!-- 等价于 -->
+  <AgentChatPopup />
+</template>
+```
+
+### 方式二：组件直接引入
+
+```vue
+<script setup>
+import { AgentChat } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+</script>
+
+<template>
+  <AgentChat :config="{
+    apiUrl: 'http://your-server/api/v2',
+    userId: 'user123',
+    headerTitle: 'AI 助手',
+  }" />
+</template>
+```
+
+## 布局模板
+
+插件提供三种布局模板，共享相同的聊天功能，区别仅在外壳布局和交互方式。
+
+### AgentChatPopup — 按钮弹窗
+
+右下角浮动按钮 + 弹出式聊天窗口，适合嵌入任意页面。
+
+```vue
+<AgentChatPopup :config="{
+  apiUrl: 'http://your-server/api/v2',
+  userId: 'user123',
+}" />
+```
+
+特有行为：
+- 浮动按钮点击后弹出/收起聊天窗口
+- 窗口 `position: fixed`，不占用页面布局空间
+- 通过 `toggleWindow()` / `windowVisible` 控制窗口显隐
+
+### AgentChatFull — 完整 Web 窗口
+
+左侧历史侧栏 + 右侧聊天窗口，适合作为独立聊天页面使用。
+
+```vue
+<AgentChatFull
+  :config="{ apiUrl: 'http://your-server/api/v2', userId: 'user123' }"
+  :show-sidebar="true"
+  sidebar-width="280px"
+  sidebar-position="left"
+/>
+```
+
+特有 Props：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `showSidebar` | `boolean` | `true` | 是否显示历史侧栏 |
+| `sidebarWidth` | `string` | `'280px'` | 侧栏宽度 |
+| `sidebarPosition` | `'left' \| 'right'` | `'left'` | 侧栏位置 |
+
+布局说明：
+- 窗口 `position: relative`，填满父容器（需确保父容器有明确宽高）
+- 侧栏可配置左/右、宽度、是否显示
+- 适合 `<div style="width:100%;height:100vh">` 等全屏容器
+
+### AgentChatMobile — 手机端
+
+全屏聊天 + 底部抽屉式历史面板，适配移动端安全区域。
+
+```vue
+<AgentChatMobile
+  :config="{ apiUrl: 'http://your-server/api/v2', userId: 'user123' }"
+  safe-area-top="env(safe-area-inset-top, 0px)"
+  safe-area-bottom="env(safe-area-inset-bottom, 0px)"
+/>
+```
+
+特有 Props：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `safeAreaTop` | `string` | `'env(safe-area-inset-top, 0px)'` | 顶部安全区 |
+| `safeAreaBottom` | `string` | `'env(safe-area-inset-bottom, 0px)'` | 底部安全区 |
+
+布局说明：
+- 使用 `100dvh` 全屏高度，自动适配移动浏览器地址栏
+- 自动增大触控区域（输入框 3rem、发送按钮 2.5rem、头部 3.5rem）
+- 历史记录从底部滑出抽屉，带遮罩和拖拽把手
+- 适配刘海屏/底部横条安全区域
+- 暴露 `drawerVisible` / `toggleDrawer()` 控制历史抽屉
+
+### 三种布局对比
+
+| 特性 | AgentChatPopup | AgentChatFull | AgentChatMobile |
+|---|---|---|---|
+| 触发方式 | 浮动按钮 → 弹窗 | 直接展示 | 直接展示 |
+| 窗口定位 | fixed 浮动 | relative 填满容器 | relative 填满视口 |
+| 历史记录 | 头部气泡弹出 | 左/右侧栏常驻 | 底部抽屉滑出 |
+| 适用场景 | 嵌入任意页面 | 独立聊天页面 | 移动端 App |
+| 自定义参数 | 按钮位置/大小 | 侧栏宽度/位置/显隐 | 安全区/触控尺寸 |
+
+### 布局样式自定义
+
+所有布局都支持通过 `config.theme` 覆盖 CSS 变量：
+
+```vue
+<!-- Full 布局自定义侧栏样式 -->
+<AgentChatFull :config="{
+  apiUrl: '...',
+  theme: {
+    '--agent-sidebar-width': '320px',
+    '--agent-header-bg': '#2563eb',
+  }
+}" />
+
+<!-- Mobile 布局自定义触控尺寸 -->
+<AgentChatMobile :config="{
+  apiUrl: '...',
+  theme: {
+    '--agent-input-min-height': '3.5rem',
+    '--agent-send-size': '3rem',
+  }
+}" />
+```
+
+布局特有 CSS 变量：
+
+| 变量 | 默认值 | 说明 | 适用布局 |
+|---|---|---|---|
+| `--agent-sidebar-width` | `17.5rem` | 历史侧栏宽度 | Full |
+| `--agent-sidebar-bg` | `var(--agent-window-bg)` | 侧栏背景 | Full |
+| `--agent-sidebar-border-color` | `#253354` / `#e2e8f0` | 侧栏边框色 | Full |
+| `--agent-safe-area-top` | `env(safe-area-inset-top, 0px)` | 顶部安全区 | Mobile |
+| `--agent-safe-area-bottom` | `env(safe-area-inset-bottom, 0px)` | 底部安全区 | Mobile |
+| `--agent-window-position` | `fixed` | 窗口定位方式 | 所有（自动覆盖） |
+
+## 多实例使用
+
+通过 `instanceId` 创建多个独立对话实例，每个实例拥有独立的会话、消息和历史记录。
+
+### 场景一：不同用户
+
+```vue
+<script setup>
+import { AgentChatPopup } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+</script>
+
+<template>
+  <!-- 用户 A 的对话 -->
+  <AgentChatPopup :config="{
+    apiUrl: 'http://your-server/api/v2',
+    userId: 'user-a',
+    instanceId: 'user-a',
+  }" />
+
+  <!-- 用户 B 的对话（独立会话/消息/历史） -->
+  <AgentChatPopup :config="{
+    apiUrl: 'http://your-server/api/v2',
+    userId: 'user-b',
+    instanceId: 'user-b',
+    theme: {
+      '--agent-btn-bottom': '6rem',  // 避免与用户A的按钮重叠
+      '--agent-btn-right': '1.75rem',
+    }
+  }" />
+</template>
+```
+
+### 场景二：不同业务场景
+
+```vue
+<script setup>
+import { AgentChatFull } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+</script>
+
+<template>
+  <!-- 数据分析助手 -->
+  <AgentChatFull
+    instance-id="analytics"
+    :config="{
+      apiUrl: 'http://your-server/api/v2',
+      userId: 'user123',
+      headerTitle: '数据分析助手',
+      promptTemplateId: 1,
+    }"
+  />
+</template>
+```
+
+### 场景三：混合布局 + 共享实例
+
+不同布局组件通过相同的 `instanceId` 共享同一份对话数据：
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { AgentChatPopup, AgentChatFull, AgentChatMobile } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+
+const layout = ref('popup')
+const sharedConfig = {
+  apiUrl: 'http://your-server/api/v2',
+  userId: 'user123',
+  instanceId: 'shared-chat',  // 相同 ID 共享数据
+}
+</script>
+
+<template>
+  <div>
+    <button @click="layout = 'popup'">弹窗</button>
+    <button @click="layout = 'full'">全屏</button>
+    <button @click="layout = 'mobile'">手机</button>
+
+    <AgentChatPopup v-if="layout === 'popup'" :config="sharedConfig" />
+    <AgentChatFull v-else-if="layout === 'full'" :config="sharedConfig" />
+    <AgentChatMobile v-else :config="sharedConfig" />
+  </div>
+</template>
+```
+
+### 场景四：组件拆分独立使用
+
+`AgentWindow` 和 `AgentHistoryList` 可脱离布局模板独立使用，通过 `instanceId` 关联状态：
+
+```vue
+<script setup>
+import { AgentWindow, AgentHistoryList } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+</script>
+
+<template>
+  <div style="display:flex;height:100vh;">
+    <!-- 左侧：自定义历史面板 -->
+    <aside style="width:240px;border-right:1px solid #e2e8f0;">
+      <AgentHistoryList
+        instance-id="my-chat"
+        :config="{ apiUrl: 'http://your-server/api/v2', userId: 'user123' }"
+        @select="(id) => console.log('切换到', id)"
+        @new-chat="() => console.log('新建聊天')"
+      />
+    </aside>
+
+    <!-- 右侧：聊天窗口 -->
+    <main style="flex:1;">
+      <AgentWindow instance-id="my-chat" />
+    </main>
+  </div>
+</template>
+```
+
+### 编程式多实例管理
+
+```ts
+import {
+  getOrCreateChatInstance,
+  getChatInstance,
+  destroyChatInstance,
+  chatStore,
+} from '@legendzd/ai-agent-vue'
+
+// 创建或获取实例（传入配置会初始化实例）
+const instanceA = getOrCreateChatInstance('user-a', {
+  apiUrl: 'http://your-server/api/v2',
+  userId: 'user-a',
+})
+
+// 获取已存在的实例（不传配置）
+const existing = getChatInstance('user-a')
+
+// chatStore 是 'default' 实例的快捷方式
+console.log(chatStore.sessionId)
+console.log(chatStore.messages)
+
+// 销毁实例（清理内存）
+destroyChatInstance('user-a')
+```
+
+## 配置项（AgentPluginOptions）
+
+所有字段均为可选，可通过 `app.use(AgentPlugin, options)` 或 `<组件 :config="options">` 传入。
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `apiUrl` | `string` | — | API 基础地址，配置到 `http://host:port/api/v2` 级别 |
+| `getAccessToken` | `() => string` | — | 认证 token 获取函数（惰性调用） |
+| `getSession` | `() => string` | — | 认证 session 获取函数 |
+| `getUserId` | `() => string` | — | 用户 ID 获取函数（动态场景优先使用） |
+| `userId` | `string` | — | 用户 ID 静态值（简化用法，`getUserId` 优先） |
+| `llmProviderId` | `number` | — | LLM 提供商 ID |
+| `promptTemplateId` | `number` | — | 提示词模板 ID |
+| `customPrompt` | `string` | — | 自定义提示词 |
+| `headerTitle` | `string` | `'AI 智能助手'` | 窗口标题 |
+| `emptyText` | `string` | `'有什么可以帮助你的？'` | 空状态提示 |
+| `placeholder` | `string` | `'输入消息... (Enter 发送，Shift+Enter 换行)'` | 输入框占位文本 |
+| `mode` | `'dark' \| 'light'` | `'dark'` | 主题模式 |
+| `theme` | `Record<string, string>` | — | CSS 变量覆盖，如 `{ '--agent-btn-bg': '#2563eb' }` |
+| `enableVoice` | `boolean` | `true` | 是否启用语音输入（浏览器不支持时自动隐藏） |
+| `voiceLang` | `string` | `'zh-CN'` | 语音识别语言 |
+| `instanceId` | `string` | `'default'` | 实例 ID，用于多实例隔离 |
+
+### userId 两种写法
+
+```ts
+// 静态值（简单场景）
+{ userId: 'user123' }
+
+// 函数（动态场景，如从 store 获取登录用户）
+{ getUserId: () => userStore.userId }
+```
+
+API 层优先使用 `getUserId()`，若未提供则 fallback 到 `userId` 静态值。
+
+### config prop 合并规则
+
+组件同时支持顶层 props 和 `config` prop，`config` 优先：
+
+```vue
+<!-- 两种写法等价 -->
+<AgentChat :config="{ apiUrl: '...', userId: 'user123' }" />
+<AgentChat apiUrl="..." user-id="user123" />
+
+<!-- config 优先级高于顶层 props -->
+<AgentChat
+  user-id="fallback"
+  :config="{ userId: 'priority' }"
+/>
+```
+
+## 组件实例 API
+
+通过 `ref` 获取组件实例后，可直接访问对话数据和控制方法：
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { AgentChat } from '@legendzd/ai-agent-vue'
+import '@legendzd/ai-agent-vue/dist/style.css'
+
+const chatRef = ref()
+</script>
+
+<template>
+  <AgentChat ref="chatRef" :config="{ apiUrl: '...', userId: 'user123' }" />
+  <button @click="chatRef?.toggleWindow()">打开/关闭窗口</button>
+  <button @click="chatRef?.newChat()">新建聊天</button>
+  <p>当前会话: {{ chatRef?.sessionId }}</p>
+  <p>消息数: {{ chatRef?.messages?.length }}</p>
+</template>
+```
+
+### 暴露的属性和方法
+
+所有布局模板均暴露以下接口：
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `sessionId` | `Ref<string>` | 当前会话 ID |
+| `sessions` | `Ref<SessionInfo[]>` | 历史会话列表 |
+| `messages` | `Ref<ChatMessage[]>` | 当前对话消息列表 |
+| `isStreaming` | `Ref<boolean>` | 是否正在流式接收 |
+| `isSessionLoading` | `Ref<boolean>` | 是否正在加载会话 |
+| `initSession()` | `() => Promise<void>` | 初始化会话 |
+| `loadSessions()` | `() => Promise<void>` | 加载/刷新历史会话列表 |
+| `switchSession(id)` | `(id: string) => void` | 切换到指定会话 |
+| `newChat()` | `() => Promise<void>` | 新建聊天（创建新会话并清空消息） |
+| `clearMessages()` | `() => void` | 清空当前对话消息 |
+
+各布局特有暴露：
+
+| 名称 | 类型 | 适用布局 | 说明 |
+|---|---|---|---|
+| `windowVisible` | `Ref<boolean>` | Popup | 窗口是否可见（可读写） |
+| `toggleWindow()` | `() => void` | Popup | 切换窗口显示/隐藏 |
+| `drawerVisible` | `Ref<boolean>` | Mobile | 历史抽屉是否可见（可读写） |
+| `toggleDrawer()` | `() => void` | Mobile | 切换历史抽屉显隐 |
+
+## 主题定制
+
+### 切换深色/浅色模式
+
+```vue
+<AgentChat :config="{ mode: 'light' }" />
+<AgentChatFull :config="{ mode: 'light' }" />
+<AgentChatMobile :config="{ mode: 'light' }" />
+```
+
+### 覆盖 CSS 变量
+
+```vue
+<AgentChat :config="{
+  theme: {
+    '--agent-btn-bg': '#2563eb',
+    '--agent-window-width': '480px',
+    '--agent-header-bg': 'transparent',
+  }
+}" />
+```
+
+### 可用的 CSS 变量
+
+#### 按钮
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-btn-size` | `3.25rem` | 按钮尺寸 |
+| `--agent-btn-bg` | `#514a9d` | 按钮背景色 |
+| `--agent-btn-bg-hover` | `#24c6dc` | 按钮悬停背景色 |
+| `--agent-btn-icon-color` | `#fff` | 按钮图标颜色 |
+| `--agent-btn-border-radius` | `50%` | 按钮圆角 |
+| `--agent-btn-shadow` | `0 0.25rem 0.875rem rgba(81,74,157,0.45)` | 按钮阴影 |
+| `--agent-btn-shadow-hover` | `0 0.375rem 1.25rem rgba(36,198,220,0.45)` | 按钮悬停阴影 |
+| `--agent-btn-bottom` | `1.75rem` | 按钮底边距 |
+| `--agent-btn-right` | `1.75rem` | 按钮右边距 |
+| `--agent-btn-left` | `unset` | 按钮左边距 |
+| `--agent-btn-top` | `unset` | 按钮顶边距 |
+
+#### 窗口
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-window-position` | `fixed` | 窗口定位方式 |
+| `--agent-window-width` | `26.25rem` | 窗口宽度 |
+| `--agent-window-height` | `38.75rem` | 窗口高度 |
+| `--agent-window-bg` | `rgba(20,27,45,0.78)` | 窗口背景 |
+| `--agent-window-border-radius` | `0.5rem` | 窗口圆角 |
+| `--agent-window-shadow` | `0 0.75rem 2.5rem rgba(0,0,0,0.4)` | 窗口阴影 |
+| `--agent-window-bottom` | `6rem` | 窗口底边距 |
+| `--agent-window-right` | `1.75rem` | 窗口右边距 |
+
+#### 头部
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-header-height` | `3.25rem` | 头部高度 |
+| `--agent-header-bg` | `linear-gradient(135deg,#514a9d,#24c6dc)` | 头部背景 |
+| `--agent-header-text-color` | `#fff` | 头部文字颜色 |
+| `--agent-header-font-size` | `0.9375rem` | 头部字号 |
+
+#### 消息
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-msg-user-bg` | `#514a9d` | 用户消息背景 |
+| `--agent-msg-user-text` | `#fff` | 用户消息文字颜色 |
+| `--agent-msg-assistant-bg` | `#1a2340` | AI 消息背景 |
+| `--agent-msg-assistant-text` | `#e2e8f0` | AI 消息文字颜色 |
+| `--agent-msg-font-size` | `0.875rem` | 消息字号 |
+| `--agent-msg-max-width` | `80%` | 消息最大宽度 |
+
+#### 输入框
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-input-bg` | `#6b819c52` | 输入框背景 |
+| `--agent-input-border-color` | `#253354` | 输入框边框色 |
+| `--agent-input-focus-border-color` | `#24c6dc` | 输入框聚焦边框色 |
+| `--agent-input-text-color` | `#e2e8f0` | 输入框文字颜色 |
+| `--agent-input-placeholder-color` | `#5a6b8a` | 占位符颜色 |
+| `--agent-input-min-height` | `2.75rem` | 输入框最小高度 |
+
+#### 发送按钮
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-send-bg` | `#24c6dc` | 发送按钮背景 |
+| `--agent-send-bg-hover` | `#1fb1c7` | 发送按钮悬停背景 |
+| `--agent-send-bg-disabled` | `#1a3a4a` | 发送按钮禁用背景 |
+| `--agent-send-size` | `2rem` | 发送按钮尺寸 |
+
+#### 辅助色
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-loading-dot-color` | `#24c6dc` | 加载动画/状态提示颜色 |
+| `--agent-empty-color` | `#5a6b8a` | 空状态文字颜色 |
+| `--agent-error-color` | `#f87171` | 错误文字颜色 |
+| `--agent-error-bg` | `rgba(248,113,113,0.1)` | 错误背景色 |
+| `--agent-code-block-bg` | `#0d1117` | 代码块背景 |
+| `--agent-table-border` | `#253354` | 表格边框色 |
+| `--agent-table-header-bg` | `#1a2340` | 表头背景 |
+
+## API 端点约定
+
+`apiUrl` 配置到 `http://host:port/api/v2` 级别，插件自动拼接以下路径：
+
+| 功能 | 方法 | 完整路径 |
+|---|---|---|
+| 创建会话 | POST | `${apiUrl}/agent/chat/session` |
+| 流式对话 | POST | `${apiUrl}/agent/chat/chat/stream` |
+| 获取历史 | GET | `${apiUrl}/agent/chat/sessions?userId=xxx` |
+
+### SSE 事件类型
+
+流式对话接口返回的 SSE 事件格式：
+
+```json
+{ "type": "status", "content": "正在查询数据..." }
+{ "type": "sql", "content": "SELECT * FROM ..." }
+{ "type": "data", "content": [{"col1": "val1", "col2": 100}] }
+{ "type": "chart_config", "content": { /* ECharts 配置对象 */ }
+{ "type": "sources", "content": [{ "id": "db", "title": "数据库" }] }
+{ "type": "analysis_chunk", "content": "正在分析..." }
+{ "type": "done", "report_id": 123, "title": "分析报告" }
+{ "type": "error", "message": "分析失败" }
+```
+
+## 编程式 API
+
+除组件方式外，插件也导出了底层 API 和 Store，供高级场景使用：
+
+```ts
+import {
+  // 布局组件
+  AgentChat,
+  AgentChatPopup,
+  AgentChatFull,
+  AgentChatMobile,
+
+  // 子组件
+  AgentWindow,
+  AgentHistoryList,
+
+  // API 方法
+  createChatSession,
+  getChatSessions,
+  streamChat,
+  setAgentOptions,
+  getAgentOptions,
+
+  // Store 工具
+  chatStore,
+  getOrCreateChatInstance,
+  getChatInstance,
+  destroyChatInstance,
+
+  // 类型
+  type AgentPluginOptions,
+  type AgentLayoutMode,
+  type AgentFullLayoutProps,
+  type AgentMobileLayoutProps,
+  type ChatMessage,
+  type SessionInfo,
+  type SourceInfo,
+  type StreamCallbacks,
+  type StreamEvent,
+  type StreamEventType,
+  type StreamRequestData,
+  type ChatStoreInstance,
+} from '@legendzd/ai-agent-vue'
+```
+
+### 手动发起流式请求
+
+```ts
+import { streamChat, setAgentOptions } from '@legendzd/ai-agent-vue'
+
+setAgentOptions({ apiUrl: 'http://your-server/api/v2' })
+
+const controller = streamChat(
+  { sessionId: 'xxx', query: '你好', userId: 'user123' },
+  {
+    onStatus: (text) => console.log('状态:', text),
+    onAnalysisChunk: (chunk) => process.stdout.write(chunk),
+    onChartConfig: (config) => renderChart(config),
+    onDone: (reportId, title) => console.log('完成:', title),
+    onError: (msg) => console.error('错误:', msg),
+    onComplete: () => console.log('流结束'),
+  }
+)
+
+// 取消请求
+controller.abort()
+```
+
+### 直接访问 Store
+
+```ts
+import { chatStore, getOrCreateChatInstance } from '@legendzd/ai-agent-vue'
+
+// 默认实例
+console.log(chatStore.sessionId)
+console.log(chatStore.messages)
+
+// 指定实例
+const instanceA = getOrCreateChatInstance('user-a', {
+  apiUrl: 'http://your-server/api/v2',
+  userId: 'user-a',
+})
+console.log(instanceA.sessionId)
+
+// 操作
+await chatStore.initSession()
+await chatStore.loadSessions()
+await chatStore.newChat()
+chatStore.switchSession('some-session-id')
+chatStore.clearMessages()
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器（含三种布局切换 Demo）
+npm run dev
+
+# 构建生产版本（应用模式）
+npm run build
+
+# 构建库版本（npm 包）
+npm run build:lib
+
+# 预览生产构建
+npm run preview
+
+# 代码格式化
+npm run format
+```
+
+## License
+
+MIT