@szjy/ai-coms

v0.1.4

Published

2 months ago

vue3 ai component

Downloads

0High
0Medium
0Low

boycgit

jscon

yangsansan

@szjy/ai-coms — Vue3 AI 聊天组件库

一个基于 Vue 3 与 Element Plus 的即插即用 AI 对话组件（SzAiChat）。支持多家大模型流式对话（Spark、Ollama、SiliconFlow、Kimi Moonshot、DashScope、数智建管等），内置消息面板、Markdown 渲染与高亮、流式增量显示、复制等常用能力，帮助你在业务系统中快速集成 AI 助手。

适用场景

企业 Web 系统内嵌 AI 助手（客服、知识问答、项目辅助）
快速验证多模型 Chat 能力与对比
低侵入集成到现有前端应用（只需安装与注册组件）

亮点

统一组件：提供 SzAiChat 组件与安装器 create，一行注册、开箱即用。
多模型接入：内置多种大模型接入方法与流式解析器，轻松切换。
体验完善：欢迎页、快捷提问、消息气泡、Markdown 渲染、复制、抽屉模式切换。
友好扩展：将流解析、API 调用、渲染拆分，方便替换与扩展。

目录结构说明

ai-coms/
├─ index.ts                      # 库入口：导出组件与安装器
├─ vite.config.mts               # Vite 构建配置（库模式）
├─ package.json                  # 包信息、脚本与依赖
├─ public/                       # 静态资源（图片、脚本、svg）
│  ├─ images/                    # 组件使用的图片与图标
│  └─ scripts/ai/                # markdown-it 与 highlight.js 静态脚本
├─ packages/
│  ├─ api/ai.ts                  # 多家大模型的流式请求封装（Fetch + SSE/JSON）
│  ├─ common/utils/              # 通用工具（剪贴板、URL、loader 等）
│  └─ components/
│     ├─ components.ts           # 组件出口汇总（当前导出 AiChat）
│     ├─ installer.ts            # 全量安装器，循环注册所有导出的组件
│     ├─ contants.ts             # 版本常量、组件名前缀
│     ├─ create.ts               # 可选按需安装器工厂 `create()`
│     ├─ icons/                  # SvgIcon 组件与内置 svg 资源
│     └─ AiChat/
│        ├─ index.ts             # 导出 `SzAiChat`
│        └─ src/
│           ├─ index.vue         # 包裹入口，悬浮按钮与面板开关、依赖脚本加载
│           ├─ components/
│           │  ├─ ChatPanel.vue  # 主聊天面板、输入区、消息列表
│           │  ├─ Previewer.vue  # Markdown 流式渲染、复制、滚动控制
│           │  └─ plugins/markdown.ts # 生成 markdown-it 实例
│           ├─ transform/        # 流解析与模型映射
│           │  └─ index.ts       # LLMTypes、transformStreamValue、splitStream
│           └─ writer.ts         # 桥接 API 与流 Reader，向预览器输出
└─ examples/                     # 运行示例（Vite）
   ├─ main.ts                    # 示例入口，注册 Element Plus 与组件
   ├─ App.vue                    # 示例页面，包含 Tab 与 AiChat 使用
   └─ components/AiChatTab.vue   # 组件使用样例（token/identifier/baseUrl 传参）

模块依赖与调用流向（简化）：

graph TD
  A[App 应用] --> B[create() 安装器]
  B --> C[SzAiChat 组件]
  C --> D[ChatPanel]
  D --> E[createAssistantWriterStylized]
  E --> F[LLMTypes.api (packages/api/ai.ts)]
  F --> G[服务端流接口]
  E --> H[splitStream/transformStreamValue]
  H --> I[Previewer 渲染 Markdown]

环境与依赖配置

Node.js: 推荐 >= 18（Vite 5 要求）
包管理：pnpm（推荐）/ npm / yarn
框架：Vue 3（Peer/External）、Element Plus
构建：Vite 5，TypeScript 5

运行所需依赖（节选，详见 package.json）：

生产依赖：vue@^3.4.21、[email protected]、aa-loader@^0.1.5
开发依赖：vite、@vitejs/plugin-vue、vite-plugin-dts、typescript、vue-tsc、sass/less 等

浏览器兼容：现代浏览器（需支持 ReadableStream/TransformStream 的流式能力；如需更广兼容度请添加 Polyfill）。

推荐工具：

VS Code + Volar 扩展（Vue）
ESLint/Prettier（建议但当前仓库未内置配置，可按团队规范自加）

安装与项目运行指南

安装依赖：

pnpm install
# 或
npm install

开发模式（示例站点）：

pnpm dev
# 访问 http://localhost:8810

构建库：

pnpm build           # 生产构建（ES/UMD，外部化 vue/element-plus）
pnpm build:dev       # 开发模式构建（保留标识符，便于调试）

预览（示例站点打包后预览）：

pnpm preview

关于静态依赖：组件运行时会按需加载 public/scripts/ai 下的 markdown-it.min.js 与 highlight.11.11.1.min.js，请确保这些静态文件可被正确访问（Vite 开发与构建后默认可用）。

关于后端代理：多数大模型的请求路径形如 ${location.origin}/spark/...、/moonshot/... 等，需要在网关或本地开发服务器配置反向代理与鉴权，保证浏览器可直接访问同源路径。

快速上手与主要功能

注册并使用组件：

// examples/main.ts（示例）
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'
import { SzAiChat, create } from '../index'

const app = createApp(App)
const szAIKits = create({ components: [SzAiChat] })
app.use(ElementPlus).use(szAIKits).mount('#app')

在页面中引入：

<template>
  <sz-ai-chat :token="token" :identifier="identifier" :baseUrl="baseUrl" :title="'数智AI助理'" />
  <!-- 右下角悬浮按钮点击后弹出对话面板 -->
  <!-- 可通过 ?llmName=szjy 切换默认大模型（支持 standard/spark/ollama3/siliconflow/moonshot/dashscope/szjy） -->
  <!-- e.g. http://localhost:8810/?llmName=spark -->
</template>

主要功能：

悬浮入口与关闭：右下角按钮打开对话，悬浮关闭按钮隐藏组件。
欢迎页与快捷提问：无对话时显示欢迎与常见问题，点击自动填充发送。
流式对话：使用 Fetch Response.body + Reader，配合 TransformStream 分割，逐字输出。
Markdown 渲染与代码高亮：外链 markdown-it 与 highlight.js，支持标题/列表/链接/代码块。
复制消息：一键复制渲染后的文本内容。
抽屉模式：点击图标切换为右侧抽屉铺满高的会话模式。

核心流程（发送到渲染）：

sequenceDiagram
  participant U as 用户
  participant P as ChatPanel
  participant W as createAssistantWriterStylized
  participant A as API 调用 (packages/api/ai.ts)
  participant T as splitStream/transform
  participant R as Previewer

  U->>P: 输入问题并提交
  P->>W: 调用并传入 LLM 类型与参数
  W->>A: 发起 Fetch (stream: true)
  A-->>W: 返回 Response.body ReadableStream
  W->>T: TextDecoderStream + splitStream 按行/JSON 解析
  T-->>R: Reader.read() 增量输出片段
  R-->>U: Markdown 渲染、滚动到底部、完成复制

API 接口文档（前端调用封装）

文件：packages/api/ai.ts（基于浏览器 fetch，返回 Promise<Response>，调用处继续基于 Response.body 进行流式读取）

公共说明：所有接口均使用 POST，默认 stream: true，对于需要鉴权的接口通过 Authorization: Bearer <token> 头传递。

| 函数名 | 说明 | 请求路径 | 认证 | 主要参数 | 备注 | |---|---|---|---|---|---| | createOllama3Stylized(text) | 本地 Ollama3 | http://localhost:11434/api/chat | 否 | text | 模型固定 llama3 | | createSparkStylized(text, token) | 科大讯飞 Spark | ${location.origin}/spark/v1/chat/completions | Bearer | text, token | SSE data: JSON 行 | | createSiliconFlowStylized(text, token) | SiliconFlow | ${location.origin}/siliconflow/v1/chat/completions | Bearer | text, token | 兼容 OpenAI 接口格式 | | createKimiMoonshotStylized(text, token) | Moonshot | ${location.origin}/moonshot/v1/chat/completions | Bearer | text, token | 提供 system 提示 | | createDashScopeStylized(text, token) | 通义千问 | ${location.origin}/dashscope/compatible-mode/v1/chat/completions | Bearer | text, token | 兼容 OpenAI 路径 | | createSZJYStylized(text, token, identifier, baseUrl) | 数智建管 | ${ensureFullURL(baseUrl)}/support/${identifier}/a | Bearer | text, token, identifier, baseUrl | 业务网关需配置 |

流解析器（packages/components/AiChat/src/transform/index.ts）：

splitStream('\n') 将 ReadableStream<string> 按行切分，兼容 SSE data: 与直接 JSON 片段。
transformStreamValue 针对各模型对单行数据进行解析，统一返回 { content, done }。

在组件中，createAssistantWriterStylized 会把 Response.body 管道化为可读 reader，再交给 Previewer 逐步渲染。

配置与扩展

切换默认模型：在地址栏加上 ?llmName=<name>（支持：standard、spark、ollama3、siliconflow、moonshot、dashscope、szjy）。
自定义图标：SvgIcon 支持传入绝对路径或 /images/svg/*.svg，颜色通过滤镜近似实现。
组件前缀：packages/components/contants.ts 中 COMP_PREFIX = 'Sz'，通过 create({ componentPrefix }) 可定制。
版本常量：VERSION 注入自 package.json，在 Vite 中以 __PKG_VERSION__ 注入。

项目维护规范

代码风格：
- 建议接入 ESLint + Prettier（当前仓库未内置，推荐团队按规范落地）。
- TypeScript 严格模式，避免 any；函数与导出接口显式类型标注。
分支管理：
- main/release 稳定分支；feat/*、fix/*、chore/*、docs/* 分支用于日常迭代。
提交规范：
- 使用 Conventional Commits（如 feat: ...、fix: ...、docs: ...）。
- 已内置版本发布脚本：pnpm release（npx commit-and-tag-version）。
CI/CD：
- 建议在 CI 中执行 pnpm i && pnpm build && vue-tsc --noEmit 校验类型与构建产物。
代码审核：
- 所有 PR 需通过代码评审与预览构建，确保可回滚、可追踪。

常见问题与故障排查（FAQ）

无法渲染 Markdown 或高亮无效

可能原因：public/scripts/ai/markdown-it.min.js 或 highlight.11.11.1.min.js 未能被加载。
解决：确认构建后静态资源是否在同路径；开发模式下检查网络请求是否 200；必要时调整 base 或静态资源路径。

流式输出不显示或中断

可能原因：后端未按行输出 data: 或 JSON 片段；跨域/CORS 拦截；代理未配置。
解决：
- 确认后端开启 stream: true 并按行刷写；
- 开发环境配置本地域名反向代理到真实 API；
- 浏览器控制台查看网络流（Fetch/XHR）与 JS 报错。

请求 401/403 或鉴权失败

可能原因：未正确传入 token、identifier、baseUrl；网关校验不通过。
解决：
- 在 <sz-ai-chat> 传入合法 token、identifier，并确认 baseUrl 为网关前缀；
- 检查服务端对 Authorization: Bearer <token> 的解析逻辑。

图标不显示或颜色不生效

可能原因：SvgIcon 传入的是外链/多色 SVG；过滤器无法覆盖填充色。
解决：优先使用单色 SVG，或在设计时约定可控样式；必要时改为内联 SVG 方案。

生产打包后 vue/element-plus 重复打包

可能原因：未将其外部化。
解决：本库构建已在 vite.config.mts 配置 external，作为使用方请在你的应用构建中确保仅引用一次依赖。

参考资料与延伸阅读

Vite 官方文档：https://vitejs.dev/
Vue 3 官方文档：https://vuejs.org/
Element Plus：https://element-plus.org/
Streams API（ReadableStream/TransformStream）：https://developer.mozilla.org/docs/Web/API/Streams_API
markdown-it：https://markdown-it.github.io/
highlight.js：https://highlightjs.org/
OpenAI 风格 Chat Completions 接口模式（兼容生态）：https://platform.openai.com/docs/api-reference/chat
Ollama 本地模型：https://ollama.com/
Moonshot API：https://platform.moonshot.cn/
DashScope（通义千问）：https://dashscope.aliyun.com/
SiliconFlow：https://docs.siliconflow.cn/
科大讯飞 Spark（参考其服务端/网关说明）

如有问题或建议，欢迎提交 Issue/PR 共同完善组件能力与生态。