github链接https://github.com/CommentOut64/simple-ai-chat

---

一、前言：为何需要一个新的聊天方案？

在为现有 Web 应用集成 AI 对话能力时，开发者经常面临两难选择：

1. 一体式组件 (All-in-One)： 如 vue-advanced-chat，它们功能繁重，集成了所有状态管理和 UI，导致定制性差、集成困难，且容易被特定框架“绑架”。

2. 纯 UI 库： 只提供界面，开发者需要自行处理大量复杂的业务逻辑，如流式通信、上下文管理、消息状态等。

我们真正需要的，是一个既能提供高质量 UI，又能将核心业务逻辑（如状态、通信）剥离，让开发者自由选择前端框架的解决方案。

Simple AI Chat 正是为此而生。它不是一个简单的聊天界面，而是一套完整的解耦式解决方案，旨在提供摆脱繁重组件的最大自定义自由。

二、核心特性：兼顾体验与功能的旗舰实现

项目提供从后端服务到前端 UI 的完整技术栈。 我不仅构建了强大的“核”，更围绕这个核打造了一个体验精致的“壳”。

1. 精致的前端体验 (vue-ui)

vue-ui 包是基于 Vue 3 和 Pinia 构建的纯粹 UI 组件库，它充分展示了 core-sdk 的能力上限，并包含了大量体验优化：

• 高性能渲染： 采用高性能虚拟滚动，即使加载上千条消息也能保持流畅。

• 完善的 Markdown 支持： 包括实时流式输出、多语言代码语法高亮（及主题切换）、LaTeX 数学公式 和 Mermaid 图表渲染。

• 现代化的交互：

  • 自适应单行/多行输入框，支持草稿自动保存。

  • 一键切换深色/浅色主题。

  • 自定义字体、行间距等排版选项。

2. 稳健的对话管理 (Core + Backend)

• 对话管理： 支持创建、删除、重命名和固定对话，支持按标题和内容搜索。

• 消息交互：

  • 基于 SSE (Server-Sent Events) 的实时流式输出。

  • 支持消息断点续传。

  • 文件上传支持（需后端实现）。

• 系统与配置：

  • Redis 多级缓存，提升响应速度。

  • 支持多模型配置及临时参数调整。

  • 智能上下文 Token 控制与截断。

  • 提供 Docker 一键部署方案。

三、架构设计：解耦的核心

Simple AI Chat 的核心竞争力在于其严格的分层解耦架构。 项目采用 Monorepo (pnpm Workspace) 管理，确保各层职责清晰、低耦合。

应用层 (Application Layer)
            ↓
表现层 (Presentation Layer) - [Vue UI 组件库]
            ↓
业务逻辑层 (Business Logic Layer) - [Core SDK]
            ↓
API 层 (API Layer) - [FastAPI]
            ↓
服务层 (Service Layer) - [AI 服务, 配置服务]
            ↓
数据访问层 (Data Access Layer) - [SQLModel ORM + Redis Cache]

这一设计的关键在于业务逻辑层 (Core SDK) 和 表现层 (Vue UI) 的彻底分离。

1. 框架无关的核心 (packages/core-sdk)

core-sdk 是项目的“心脏”。 它使用纯 JavaScript (ESM) 实现，不依赖任何前端框架。 它封装了所有核心业务逻辑，包括：

• 消息状态管理

• SSE 连接与事件处理

• 上下文控制与组装

这意味着，无论你使用 React、Svelte 还是原生 JS，都可以单独使用 core-sdk，并基于它驱动你自己的自定义 UI，而无需担心框架兼容性问题。

2. 纯粹的 UI 库 (packages/vue-ui)

vue-ui 则是基于 core-sdk 的“官方旗舰实现”。 它是一个 100% 纯粹的 Vue 3 组件库，不依赖 Shadow DOM 或任何 Web Component 特性。 它通过标准的 Props, Emits 和 Pinia 进行状态管理，确保了在 Vue 生态中的最佳兼容性、可复用性和易测性。

这种架构为开发者提供了两种清晰的路径：

• Vue 开发者： 可立即使用 @simple-ai-chat-project/vue-ui 获得现代化聊天界面。

• React/Svelte/其他： 可单独使用 @simple-ai-chat-project/core-sdk 驱动自定义 UI。

四、技术栈一览

• 后端： FastAPI, SQLModel (SQLAlchemy + Pydantic), Redis, SSE-Starlette

• 前端 (vue-ui)： Vue 3 (Composition API), Vite, Pinia, TailwindCSS, Radix Vue, md-editor-v3, vue-virtual-scroller

• 核心 (core-sdk)： 纯 JavaScript (ESM), EventEmitter3, @microsoft/fetch-event-source

五、快速开始与使用

项目提供了两种使用方式：作为集成方（终端用户）或作为贡献者。

1. 部署与集成 (终端用户)

A. 部署后端 (Docker)

1. 克隆仓库，创建 .env 文件并填入 AI API 密钥。

2. 执行 

   docker-compose up -d

3. 后端服务将在 http://localhost:8000 运行。

B. 在 Vue 3 项目中集成

1. 安装依赖：

   pnpm install @simple-ai-chat-project/core-sdk @simple-ai-chat-project/vue-ui pinia
   

2. 在 main.js 中注册 Pinia。

3. 在组件中使用：

   <script setup>
   import { ChatWindow } from '@simple-ai-chat-project/vue-ui';
   import '@simple-ai-chat-project/vue-ui/style';
   </script>
   
   <template>
     <div style="height: 600px; width: 100%;">
       <ChatWindow
         chat-height="600px"
         user-avatar="/avatar.png"
       />
     </div>
   </template>
   

2. 本地开发 (贡献者)

1. 克隆仓库并安装：

   pnpm install

2. 启动后端 (终端一)：

   cd backend 
   uvicorn app.main:app --reload --port 8000

3. 启动前端 (终端二)：在根目录运行:

    pnpm --filter vue-ui dev

六、总结与未来规划

Simple AI Chat 旨在提供一套灵活、高性能、易于集成的 AI 对话解决方案。v1.0.0 版本提供了强大的 core-sdk、精致的 vue-ui 组件库以及生产级的 FastAPI 后端服务。

项目的高优先级路线图包括：

• Web Component 封装：发布跨框架的 web-component 包。

• RAG 集成：预留接口，支持检索增强生成。

• 国际化 (i18n)

项目已在 GitHub 开源，欢迎提交 PRs 和 Issues，共同构建更完善的 AI 聊天解决方案。