@zhinao-helper/ai-helper-vue3 1.0.0

package/README.md

@@ -0,0 +1,309 @@
+# @zhinao-helper/ai-helper-vue3
+
+基于 Vue 3 的 AI 聊天助手组件库。开箱即用，支持高度自定义的 API 适配、品牌主题和交互体验，适用于任意 Vue 3 项目。
+
+## 特性
+
+- 悬浮 FAB 按钮 + 侧滑聊天面板
+- 流式响应（SSE / NDJSON），打字机效果实时渲染
+- 支持自定义 API 端点、请求格式、响应解析
+- 品牌定制：名称、图标、欢迎语、欢迎描述
+- 快捷问题（预设提示词）
+- 历史消息加载
+- 浅色/深色主题自动跟随
+- 支持 Vue Router 路由切换自动关闭
+
+## 安装
+
+```bash
+npm install @zhinao-helper/ai-helper-vue3
+```
+
+## 快速开始
+
+### 1. 注册插件
+
+```ts
+// src/main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import { AiHelperPlugin } from '@zhinao-helper/ai-helper-vue3'
+import '@zhinao-helper/ai-helper-vue3/style.css'
+
+const app = createApp(App)
+
+app.use(AiHelperPlugin, {
+  apiBase: '/api/ai-chat',            // API 基础地址
+  branding: {
+    name: 'AI Helper',                 // 显示名称
+    icon: '/logo.svg',                // 图标 URL
+    welcomeTitle: '你好！',             // 欢迎标题
+    welcomeDesc: '有什么可以帮你的？'     // 欢迎描述
+  },
+  theme: 'auto',                      // 'light' | 'dark' | 'auto'
+  showQuickQuestions: true,           // 是否显示快捷问题
+  closeOnRouteChange: true,           // 路由切换时是否关闭聊天面板
+  endpoints: {
+    chat: '/chat',                    // 聊天接口路径（相对 apiBase）
+    history: '/history',              // 历史接口路径
+    prompts: '/prompts'               // 提示词接口路径
+  }
+})
+
+app.use(router)
+app.mount('#app')
+```
+
+### 2. 在页面中使用
+
+```vue
+<!-- src/App.vue -->
+<template>
+  <router-view />
+  <AiHelper />
+</template>
+```
+
+## 高级配置
+
+### 自定义 API 格式
+
+不同项目的后端 API 可能返回不同格式的数据结构。通过配置回调函数，你可以将任意 API 格式适配到组件内部：
+
+#### 聊天接口（流式）
+
+```ts
+app.use(AiHelperPlugin, {
+  // 自定义请求体格式
+  buildChatBody({ message }) {
+    // 默认: JSON.stringify({ message })
+    return JSON.stringify({ prompt: message, stream: true })
+  },
+
+  // 自定义流式响应解析（每个数据块调用一次）
+  parseChatChunk(raw) {
+    const data = JSON.parse(raw)
+    // 假设后端返回: { choices: [{ delta: { content: "..." } }] }
+    if (data.choices?.[0]?.delta?.content) {
+      return { content: data.choices[0].delta.content }
+    }
+    // 流结束标志
+    if (data.choices?.[0]?.finish_reason === 'stop') {
+      return { content: '', done: true }
+    }
+    return { content: '' }
+  }
+})
+```
+
+`parseChatChunk` 接收到的 `raw` 是每个数据行的纯文本内容：
+- 标准 SSE 格式：`data: {"content": "hello"}` → `raw` 为 `{"content": "hello"}`
+- NDJSON 格式：`{"content": "hello"}` → `raw` 为 `{"content": "hello"}`
+
+返回 `{ content: string, done?: boolean }`：
+- `content` 会被追加到助手消息中显示
+- `done: true` 表示流结束，loading 状态终止
+
+#### 历史接口
+
+```ts
+app.use(AiHelperPlugin, {
+  parseHistoryResponse(raw) {
+    const r = raw as any
+    return {
+      messages: r.data?.map(m => ({
+        role: m.role,
+        content: m.text,
+        timestamp: m.created_at
+      })) ?? [],
+      total: r.total ?? r.data?.length ?? 0
+    }
+  }
+})
+```
+
+内部期望的历史响应格式：
+```ts
+{
+  messages: { role: 'user' | 'assistant', content: string, timestamp: string }[],
+  total: number
+}
+```
+
+#### 提示词接口（快捷问题）
+
+```ts
+app.use(AiHelperPlugin, {
+  parsePromptResponse(raw) {
+    const r = raw as any
+    return {
+      items: r.prompts?.map(p => ({
+        id: p.id,
+        name: p.title,
+        content: p.prompt
+      })) ?? [],
+      total: r.total ?? 0
+    }
+  }
+})
+```
+
+内部期望的提示词响应格式：
+```ts
+{
+  items: { id: number, name: string, content: string }[],
+  total: number
+}
+```
+
+### 自定义请求头
+
+```ts
+app.use(AiHelperPlugin, {
+  getHeaders: () => ({
+    'Authorization': `Bearer ${localStorage.getItem('token')}`,
+    'X-Project-Id': 'my-project'
+  })
+})
+```
+
+### 完整配置示例
+
+```ts
+import { AiHelperPlugin } from '@zhinao-helper/ai-helper-vue3'
+import '@zhinao-helper/ai-helper-vue3/style.css'
+
+app.use(AiHelperPlugin, {
+  apiBase: 'https://api.example.com',
+  branding: {
+    name: 'AI 助手',
+    icon: '/logo.png',
+    welcomeTitle: '你好！',
+    welcomeDesc: '有什么可以帮你的？'
+  },
+  theme: 'auto',
+  showQuickQuestions: true,
+  closeOnRouteChange: true,
+  endpoints: {
+    chat: '/v1/chat/stream',
+    history: '/v1/history',
+    prompts: '/v1/prompts'
+  },
+  getHeaders: () => ({
+    Authorization: `Bearer ${getToken()}`
+  }),
+  buildChatBody({ message }) {
+    return JSON.stringify({ prompt: message, stream: true })
+  },
+  parseChatChunk(raw) {
+    const data = JSON.parse(raw)
+    if (data.choices?.[0]?.delta?.content) {
+      return { content: data.choices[0].delta.content }
+    }
+    if (data.choices?.[0]?.finish_reason === 'stop') {
+      return { content: '', done: true }
+    }
+    return { content: '' }
+  },
+  parseHistoryResponse(raw) {
+    const r = raw as any
+    return {
+      messages: r.data?.map(m => ({
+        role: m.role,
+        content: m.text,
+        timestamp: m.created_at
+      })) ?? [],
+      total: r.total ?? 0
+    }
+  },
+  parsePromptResponse(raw) {
+    const r = raw as any
+    return {
+      items: r.prompts?.map(p => ({
+        id: p.id,
+        name: p.title,
+        content: p.prompt
+      })) ?? [],
+      total: r.total ?? 0
+    }
+  }
+})
+```
+
+## API 说明
+
+### 请求格式
+
+所有请求默认使用 `POST` 方法，`Content-Type: application/json`，请求体为 `{ message: string }`。你可以通过 `buildChatBody` 覆盖。
+
+### 流式响应格式
+
+组件支持两种流式数据格式：
+
+1. **标准 SSE**（每行以 `data:` 开头）
+2. **NDJSON**（每行一个 JSON 对象）
+
+流式读取时，每收到一行数据就调用 `parseChatChunk`。组件会自动跳过空行和 SSE 元数据行（以 `:`、`id:`、`event:` 开头）。
+
+### 超时保护
+
+如果 60 秒内没有收到新的流数据块，组件会自动结束 loading 状态。
+
+## 自定义主题
+
+组件通过 CSS 变量控制样式，你可以在全局样式中覆盖：
+
+```css
+:root {
+  --zhinao-helper-bg: #2563eb;              /* FAB 背景色 */
+  --zhinao-helper-color-primary: #3b82f6;   /* 主色调 */
+  --zhinao-helper-text-primary: #1e293b;    /* 主要文字 */
+  --zhinao-helper-border: #e2e8f0;          /* 边框色 */
+  --zhinao-helper-bg-card: #ffffff;         /* 卡片背景 */
+  --zhinao-helper-bg-active: #f1f5f9;       /* 面板背景 */
+  --zhinao-helper-bg-chat: #f8fafc;         /* 助手消息气泡 */
+}
+```
+
+所有可用 CSS 变量列表：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `--zhinao-helper-bg` | `#1a3a5c` | FAB 背景色 / 主背景 |
+| `--zhinao-helper-bg-active` | `#b8d4f0` | 面板背景色 |
+| `--zhinao-helper-bg-card` | `#ffffff` | 卡片/消息气泡背景 |
+| `--zhinao-helper-bg-chat` | `rgb(184,212,240,0.5)` | 助手消息气泡 |
+| `--zhinao-helper-text-primary` | `#1a3a5c` | 主要文字 |
+| `--zhinao-helper-text-secondary` | `#4a6a8c` | 次要文字 |
+| `--zhinao-helper-border` | `#b8d4f0` | 边框色 |
+| `--zhinao-helper-color-primary` | `#409eff` | 主色调 |
+| `--zhinao-helper-scrollbar-thumb` | `#c8dce8` | 滚动条滑块 |
+| `--zhinao-helper-scrollbar-track` | `rgba(200,220,232,0.3)` | 滚动条轨道 |
+| `--zhinao-helper-text-placeholder` | `#8aaacc` | 输入框占位符 |
+
+## 类型导出
+
+所有类型均从 `@zhinao-helper/ai-helper-vue3` 导出：
+
+```ts
+import type {
+  AiHelperOptions,      // 初始化配置选项
+  AiHelperConfig,       // 完整解析后的配置
+  AiHelperBranding,     // 品牌配置
+  AiHelperEndpoints,    // API 端点
+  ChatParseResult,      // 流式解析返回值
+  ChatRequestParams,    // 聊天请求参数
+  Message,              // 聊天消息
+  AiHelperState,        // 内部状态
+  PromptRow,            // 提示词
+  PromptListResponse,   // 提示词响应
+  HistoryMessage,       // 历史消息
+  HistoryResponse,      // 历史响应
+  HistoryParams         // 历史查询参数
+} from '@zhinao-helper/ai-helper-vue3'
+```
+
+## License
+
+MIT

package/dist/ai-helper-vue.css

@@ -0,0 +1,2 @@
+.zhinao-btn{cursor:pointer;color:var(--zhinao-helper-text-primary);background:0 0;border:none;border-radius:4px;justify-content:center;align-items:center;gap:4px;padding:6px 12px;font-size:13px;transition:all .2s;display:inline-flex}.zhinao-btn:hover{background:#8080801a}.zhinao-btn:disabled{opacity:.5;cursor:not-allowed}.zhinao-btn--primary{background:var(--zhinao-helper-color-primary);color:#fff}.zhinao-btn--primary:hover:not(:disabled){opacity:.85}.zhinao-btn--icon{border-radius:50%;width:28px;height:28px;padding:4px}.zhinao-btn--icon:hover:not(:disabled){background:#80808026}.zhinao-btn--text{color:var(--zhinao-helper-color-primary);font-size:12px}.zhinao-icon{fill:currentColor;width:16px;height:16px}.zhinao-loading-dots{align-items:center;gap:4px;display:inline-flex}.zhinao-loading-dots span{background:var(--zhinao-helper-color-primary);border-radius:50%;width:6px;height:6px;animation:1.4s ease-in-out infinite both zhinao-dot-bounce}.zhinao-loading-dots span:first-child{animation-delay:-.32s}.zhinao-loading-dots span:nth-child(2){animation-delay:-.16s}.zhinao-loading-dots--small span{width:4px;height:4px}@keyframes zhinao-dot-bounce{0%,80%,to{transform:scale(0)}40%{transform:scale(1)}}:root{--zhinao-helper-bg:var(--app-ai-helper-bg,#1a3a5c);--zhinao-helper-bg-active:var(--app-bg-active,#b8d4f0);--zhinao-helper-bg-card:var(--app-bg-card,#fff);--zhinao-helper-bg-chat:var(--app-bg-chat,#b8d4f080);--zhinao-helper-text-primary:var(--app-text-primary,#1a3a5c);--zhinao-helper-text-secondary:var(--app-text-secondary,#4a6a8c);--zhinao-helper-border:var(--app-border-color,#b8d4f0);--zhinao-helper-color-primary:var(--app-color-primary,#409eff);--zhinao-helper-scrollbar-thumb:var(--app-scrollbar-thumb,#c8dce8);--zhinao-helper-scrollbar-track:var(--app-scrollbar-track,#c8dce84d);--zhinao-helper-scrollbar-thumb-hover:var(--app-scrollbar-thumb-hover,#409eff);--zhinao-helper-text-placeholder:var(--app-text-placeholder,#8aaacc);--zhinao-helper-bg-primary:var(--app-bg-primary,#e8f4ff)}html.dark{--zhinao-helper-bg:var(--app-ai-helper-bg,#000);--zhinao-helper-bg-active:var(--app-bg-active,#1a1a2e);--zhinao-helper-bg-card:var(--app-bg-card,#16213e);--zhinao-helper-bg-chat:var(--app-bg-chat,#00000080);--zhinao-helper-text-primary:var(--app-text-primary,#e8f4ff);--zhinao-helper-text-secondary:var(--app-text-secondary,#a0c4e8);--zhinao-helper-border:var(--app-border-color,#2a4a6c);--zhinao-helper-color-primary:var(--app-color-primary,#409eff);--zhinao-helper-scrollbar-thumb:#2a4a6c;--zhinao-helper-scrollbar-track:#2a4a6c4d}.zhinao-loading[data-v-3ac9b9a6]{color:var(--zhinao-helper-text-secondary);align-items:center;gap:8px;font-size:14px;display:flex}.zhinao-loading--small[data-v-3ac9b9a6]{font-size:12px}.zhinao-loading-dots[data-v-3ac9b9a6]{gap:4px;display:flex}.zhinao-loading-dots span[data-v-3ac9b9a6]{background:var(--zhinao-helper-color-primary);border-radius:50%;width:6px;height:6px;animation:1.4s ease-in-out infinite both zhinao-bounce-3ac9b9a6}.zhinao-loading-dots span[data-v-3ac9b9a6]:first-child{animation-delay:-.32s}.zhinao-loading-dots span[data-v-3ac9b9a6]:nth-child(2){animation-delay:-.16s}.zhinao-loading--small .zhinao-loading-dots span[data-v-3ac9b9a6]{width:4px;height:4px}@keyframes zhinao-bounce-3ac9b9a6{0%,80%,to{transform:scale(0)}40%{transform:scale(1)}}.zhinao-quick-questions[data-v-6c57d374]{grid-template-columns:repeat(2,1fr);gap:8px;width:100%;max-width:400px;display:grid}.zhinao-quick-question[data-v-6c57d374]{border:1px solid var(--zhinao-helper-border);background:var(--zhinao-helper-bg-card);color:var(--zhinao-helper-text-primary);text-align:left;cursor:pointer;white-space:nowrap;text-overflow:ellipsis;border-radius:8px;padding:10px 16px;font-size:13px;transition:all .2s;overflow:hidden}.zhinao-quick-question[data-v-6c57d374]:hover{border-color:var(--zhinao-helper-color-primary);background:var(--zhinao-helper-bg-active)}.zhinao-chat-messages[data-v-c33e4f6c]{background:var(--zhinao-helper-bg-card);scrollbar-width:thin;scrollbar-color:var(--zhinao-helper-scrollbar-thumb) var(--zhinao-helper-scrollbar-track);flex:1;padding:16px;overflow-y:auto}.zhinao-chat-messages[data-v-c33e4f6c]::-webkit-scrollbar{width:6px}.zhinao-chat-messages[data-v-c33e4f6c]::-webkit-scrollbar-track{background:var(--zhinao-helper-scrollbar-track);border-radius:3px}.zhinao-chat-messages[data-v-c33e4f6c]::-webkit-scrollbar-thumb{background:var(--zhinao-helper-scrollbar-thumb);border-radius:3px}.zhinao-chat-messages[data-v-c33e4f6c]::-webkit-scrollbar-thumb:hover{background:var(--zhinao-helper-scrollbar-thumb-hover)}.zhinao-chat-messages__welcome[data-v-c33e4f6c]{flex-direction:column;justify-content:center;align-items:center;gap:24px;min-height:100%;display:flex}.zhinao-chat-messages__welcome-inner[data-v-c33e4f6c]{text-align:center}.zhinao-chat-messages__avatar-wrap[data-v-c33e4f6c]{background:var(--zhinao-helper-bg);border-radius:50%;justify-content:center;align-items:center;width:64px;height:64px;margin:0 auto 16px;display:flex;box-shadow:0 4px 12px #00000026}.zhinao-chat-messages__avatar[data-v-c33e4f6c]{width:36px;height:36px}.zhinao-chat-messages__welcome-title[data-v-c33e4f6c]{color:var(--zhinao-helper-text-primary);margin-bottom:8px;font-size:18px;font-weight:500}.zhinao-chat-messages__welcome-desc[data-v-c33e4f6c]{color:var(--zhinao-helper-text-secondary);font-size:14px}.zhinao-chat-messages__list[data-v-c33e4f6c]{flex-direction:column;gap:16px;display:flex}.zhinao-chat-messages__load-more[data-v-c33e4f6c]{text-align:center}.zhinao-chat-messages__row[data-v-c33e4f6c]{display:flex}.zhinao-chat-messages__row--user[data-v-c33e4f6c]{justify-content:flex-end}.zhinao-chat-messages__row--assistant[data-v-c33e4f6c]{justify-content:flex-start}.zhinao-chat-messages__bubble[data-v-c33e4f6c]{word-break:break-word;border-radius:8px;max-width:90%;padding:8px 16px}.zhinao-chat-messages__bubble--user[data-v-c33e4f6c]{background:var(--zhinao-helper-color-primary);color:#fff;max-width:80%}.zhinao-chat-messages__bubble--assistant[data-v-c33e4f6c]{background:var(--zhinao-helper-bg-chat);color:var(--zhinao-helper-text-primary)}.zhinao-chat-markdown[data-v-c33e4f6c]{line-height:1.6}.zhinao-chat-markdown[data-v-c33e4f6c] p{margin:.5em 0}.zhinao-chat-markdown[data-v-c33e4f6c] p:first-child{margin-top:0}.zhinao-chat-markdown[data-v-c33e4f6c] p:last-child{margin-bottom:0}.zhinao-chat-markdown[data-v-c33e4f6c] code{background:var(--zhinao-helper-bg-active);border-radius:3px;padding:2px 6px;font-size:.9em}.zhinao-chat-markdown[data-v-c33e4f6c] pre{background:var(--zhinao-helper-bg-active);border-radius:6px;padding:12px;overflow-x:auto}.zhinao-chat-markdown[data-v-c33e4f6c] pre code{background:0 0;padding:0}.zhinao-chat-markdown[data-v-c33e4f6c] ul,.zhinao-chat-markdown[data-v-c33e4f6c] ol{margin:.5em 0;padding-left:20px}.zhinao-chat-markdown[data-v-c33e4f6c] blockquote{border-left:3px solid var(--zhinao-helper-border);color:var(--zhinao-helper-text-secondary);margin:.5em 0;padding-left:12px}.zhinao-chat-markdown[data-v-c33e4f6c] table{border-collapse:collapse;width:100%;margin:.5em 0}.zhinao-chat-markdown[data-v-c33e4f6c] th,.zhinao-chat-markdown[data-v-c33e4f6c] td{border:1px solid var(--zhinao-helper-border);text-align:left;padding:6px 12px}.zhinao-chat-markdown[data-v-c33e4f6c] th{background:var(--zhinao-helper-bg-active)}.zhinao-chat-markdown[data-v-c33e4f6c] a{color:var(--zhinao-helper-color-primary);text-decoration:none}.zhinao-chat-markdown[data-v-c33e4f6c] a:hover{text-decoration:underline}.zhinao-chat-markdown[data-v-c33e4f6c] img{max-width:100%;height:auto}@keyframes zhinao-peeking-tilt{0%,to{transform:rotate(-12deg)}30%{transform:rotate(-15deg)}60%{transform:rotate(-10deg)}}@keyframes zhinao-excited-bounce{0%{transform:rotate(-12deg)scale(1)}40%{transform:rotate(0)scale(1.15)}to{transform:rotate(0)scale(1)}}.zhinao-chat-fade-enter-active,.zhinao-chat-fade-leave-active{transition:all .3s}.zhinao-chat-fade-enter-from,.zhinao-chat-fade-leave-to{opacity:0;transform:translate(20px)}.zhinao-ai-helper-fab[data-v-fe5a8cb6]{z-index:50;cursor:pointer;align-items:center;transition:all .4s;display:flex;position:fixed;bottom:20px;right:-20px}.zhinao-ai-helper-fab[data-v-fe5a8cb6]:hover{border-radius:28px 0 0 28px;padding:4px 12px;right:0}.zhinao-ai-helper-fab--hidden[data-v-fe5a8cb6]{opacity:0;pointer-events:none;transform:translate(48px)}.zhinao-ai-helper-fab__capsule[data-v-fe5a8cb6]{z-index:-1;background:var(--zhinao-helper-bg);opacity:0;border-radius:28px 0 0 28px;transition:opacity .4s;position:absolute;inset:0;box-shadow:-4px 4px 12px #00000040}.zhinao-ai-helper-fab:hover .zhinao-ai-helper-fab__capsule[data-v-fe5a8cb6]{opacity:1}.zhinao-ai-helper-fab__icon-wrap[data-v-fe5a8cb6]{background:var(--zhinao-helper-bg);border-radius:50%;justify-content:center;align-items:center;width:52px;height:52px;transition:all .4s;animation:2.5s ease-in-out infinite zhinao-peeking-tilt;display:flex;box-shadow:-2px 2px 8px #0003}.zhinao-ai-helper-fab:hover .zhinao-ai-helper-fab__icon-wrap[data-v-fe5a8cb6]{box-shadow:none;background:0 0;animation:.5s ease-out zhinao-excited-bounce}.zhinao-ai-helper-fab__icon[data-v-fe5a8cb6]{width:36px;height:36px;transition:filter .4s}.zhinao-ai-helper-fab:hover .zhinao-ai-helper-fab__icon[data-v-fe5a8cb6]{filter:brightness(0)invert()}.zhinao-ai-helper-fab__label[data-v-fe5a8cb6]{color:#fff;white-space:nowrap;opacity:0;max-width:0;margin-left:0;font-size:14px;font-weight:500;transition:all .4s;overflow:hidden}.zhinao-ai-helper-fab:hover .zhinao-ai-helper-fab__label[data-v-fe5a8cb6]{opacity:1;max-width:100px;margin-left:4px}.zhinao-ai-helper-panel[data-v-fe5a8cb6]{z-index:100;background:var(--zhinao-helper-bg-active);border-radius:8px;flex-direction:column;width:560px;height:calc(100vh - 80px);display:flex;position:fixed;top:60px;right:20px;overflow:hidden;box-shadow:0 8px 32px #0003}.zhinao-ai-helper-panel__header[data-v-fe5a8cb6]{border-bottom:1px solid var(--zhinao-helper-border);color:var(--zhinao-helper-text-primary);justify-content:space-between;align-items:center;padding:12px 16px;display:flex}.zhinao-ai-helper-panel__title[data-v-fe5a8cb6]{font-weight:500}.zhinao-ai-helper-panel__actions[data-v-fe5a8cb6]{align-items:center;gap:8px;display:flex}.zhinao-ai-helper-panel__footer[data-v-fe5a8cb6]{border-top:1px solid var(--zhinao-helper-border);align-items:center;gap:8px;padding:16px;display:flex}.zhinao-input[data-v-fe5a8cb6]{border:1px solid var(--zhinao-helper-border);background:var(--zhinao-helper-bg-card);color:var(--zhinao-helper-text-primary);border-radius:6px;outline:none;flex:1;padding:8px 12px;font-size:14px;transition:border-color .2s}.zhinao-input[data-v-fe5a8cb6]:focus{border-color:var(--zhinao-helper-color-primary)}.zhinao-input[data-v-fe5a8cb6]:disabled{opacity:.6;cursor:not-allowed}
+/*$vite$:1*/