# Vue3 AI 前端脚手架 **Repository Path**: darkwinoom/vue3-ai-scaffold ## Basic Information - **Project Name**: Vue3 AI 前端脚手架 - **Description**: 这是一个使用 ant-design-x-vue 搭建的前端AI交互脚手架，快速对接 OpenAI 标准模型推理服务。目前处于探索阶段 - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 1 - **Created**: 2025-04-01 - **Last Updated**: 2025-07-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: vue3, ai-assistant, ai-chat, llm-client, web-ui ## README # Vue3 AI 前端脚手架 > 项目目前为开发探索阶段，部分功能正在开发中因此可能暂不可用，提交更新不定时且可能会存在结构性变化。本项目目前仅作学习参考用，不建议用于生产环境项目。 这是一个使用 ant-design-x-vue 搭建的前端 AI 交互脚手架，支持本地 SSE 聊天补全，可用于快速对接 OpenAI 标准模型推理服务。 ![聊天界面](./docs/interface.png) 本项目通过 `pnpm create vue@latest` 创建。 ## 特色功能 - 基于 ant-design-x-vue 搭建，类 DeepSeek、ChatGPT 功能界面，功能简洁可扩展性强； - 支持用户登录与鉴权完整功能，也可以使用自带 mock 单独运行（包括 SSE 部分）； - 支持可自定义模型提供商 provider（包括本地 API 和在线 API）； - 支持 i18n 多语言（内置简体中文、繁体中文、英文）自由切换，支持自定义扩展； - 代码结构清晰易懂，可自由拆解或扩展使用； ## 在线预览 [点击访问](https://vue3-ai-scaffold.netlify.app/) ## 准备工作 在使用本项目前，您需要部署本地 LLM 或使用在线 API，才能开启真正的 AI 聊天功能。 为了方便演示，本项目内置了一个 mock server，查看 `/src/config/index.ts` 了解详情。 ### 内置提供商 本项目内置了几个常用的提供商 provider，统一存放于 `/src/config/llmProvider` 目录。说明如下： - `backend` - 访问自定义后端 SSE 服务器，该提供商可作为 mock server 运行，查看 `/src/config/index.ts` 了解详情； - `ollama` - 访问本地 Ollama 服务器，基于 `ollama-js` 实现； - `gemini` - 访问官方 Gemeni 服务器，基于 `@google/genai` 实现，`baseUrl` 配置无效； - `openai` - 访问官方 OpenAI 或同规则服务器（如：deepseek 等），基于 `openai-node` 实现； 关于 `backend` 提供商，可参考个人项目 [tp8-server-scaffold](https://gitee.com/darkwinoom/tp8-server-scaffold) 中的实现，该项目使用 PHP8 + MySQL 构建。 ### 自定义提供商 本项目允许您自定义提供商 provider，您可以参考 `/src/config/llmProvider/_example.ts` 文件中的注释了解实现细则。 提供商 provider 编写完成后，需要作为实现源在 `/src/config/index.ts` 中 `llm.suppliers` 进行配置。配置说明如下： ```js [ { // 提供商ID，唯一 id: 'my-server', // 提供商实现源（基于llmBaseProvider） provider: ServerProvider, // 提供商默认显示名称 name: 'LLM Server', // 提供商API地址，部分提供商无需配置 baseUrl: 'http://localhost:11434', // 是否激活，您需要开启后提供商才会正常显示（本项目不支持提供商动态管理） isActive: true, // ----- 以下为可选参数 ----- // 提供商别名（多语言支持） alias: { 'zh-CN': 'LLM服务器', 'zh-Hant': 'LLM伺服器', }, // 提供商API密钥（避免在前端代码中明文引用，建议加密或通过中间服务器进行换取） apiKey: '', // 自定义初始模型，可取代模型拉取（可在 provider 实现中读取） defaultModels: [ { // 模型键，唯一 key: 'qwen3:32b', // 模型类型（可选 llm 或 embedding） type: 'llm', // 模型显示名称 name: 'qwen3:32b', // 【可选】模型大小（字节） size: 20201253588, // 【可选】模型是否可以使用工具 toolUse: true, // 【可选】模型是否可处理图形 vision: false }, // 其它模型 ] }, // 其它提供商配置 ] ``` ## 技术栈 - vue3 + vite6 + typescript - vue-router4 + pinia + axios - ant-design-x-vue + ant-design-vue + naive-ui - vitest + playwright - tailwindcss + sass ## 安装使用 ```sh pnpm install ``` ### 本地服务 & 打包 ```sh # 本地运行 pnpm dev # 本地打包 pnpm build # 本地打包（预发布环境） pnpm build:staging # 本地打包预览 pnpm preview # 本地打包分析 pnpm report ``` ### 单元测试 [Vitest](https://vitest.dev/) ```sh pnpm test:unit ``` ### 端对端测试 [Playwright](https://playwright.dev) ```sh # Install browsers for the first run npx playwright install # When testing on CI, must build the project first pnpm build # Runs the end-to-end tests pnpm test:e2e # Runs the tests only on Chromium pnpm test:e2e --project=chromium # Runs the tests of a specific file pnpm test:e2e tests/example.spec.ts # Runs the tests in debug mode pnpm test:e2e --debug ``` ### 代码审查 [ESLint](https://eslint.org/) ```sh pnpm lint ``` ## 开发计划 & 完成情况 - [x] 接入 vitest 和 playwright - [x] 脚手架基本功能与配置 - [x] 登录页面与聊天页面基本样式（支持响应式） - [x] 本地会话管理与模型切换 - [x] 使用 mock 处理用户登录、鉴权与 SSE 操作 - [x] 开放本地与线上大模型 API 接口与模型管理，内置多种线上与本地提供商，可灵活自定义实现 - [x] 适配暗黑模式，支持多语言 - [ ] 【进行中】支持上传图片与文档功能【branch: feature/attachs】 - [ ] 支持 MCP 服务器 - [ ] 支持联网搜索 - [ ] 支持知识库 待加入... ## 配置说明 ### 环境配置 环境配置位于项目根目录，包括 `.env`、`.env.development`、`.env.production`、`.env.staging`，适配不同运行环境。完整配置信息如下： ```bash # 平台本地运行端口号（包含dev与preview） VITE_PORT = 4242 # 默认使用的语言（在 /src/i18n/index.ts 中查看支持的语言包，支持自定义） # 可设置 auto 自动识别系统语言 VITE_DEFAULT_LANG = zh-CN # 开发环境读取配置文件路径 & 线上环境平台打包路径 VITE_PUBLIC_PATH = / # 路由历史模式（Hash模式传"hash"、HTML5模式传"h5"、Hash模式带base参数传"hash,base参数"、HTML5模式带base参数传"h5,base参数"） VITE_ROUTER_HISTORY = "h5" # 常规API服务器地址，使用内部工具 http.request 请求时会作为 baseURL VITE_BASE_API = http://localhost:8100/api/app # 可自定义其它API，遵循 VITE_[名称]_API 即可。例如： # VITE_UC_API = http://localhost:7777/api # # 可直接调用： # ------------------------------------------------------------------ # import { http } from '@/utils/http' # http.request('POST', 'address/center', { data }, { baseAPI: 'uc' }) # 实际请求：http://localhost:7777/api/address/center # ------------------------------------------------------------------ # 查看 /src/config/index.ts 中 service.api.url 查看实现细节 # LLM提供商配置 # 查看 /src/config/index.ts 中 llm.suppliers 可管理配置项 VITE_LLM_OLLAMA_BASE_URL = http://localhost:11434 # 是否启用本地 mock（可在所有运行环境下开启） # mock 开启时 VITE_BASE_API 配置默认不会生效，但可以通过设置请求 baseAPI: 'base' 强制开启 VITE_USE_MOCK = true ``` ### 内部配置 内部配置文件位于 `/src/config/index.ts`。 由于项目目前正在开发中，每次提交可能会存在较大改动，您可以前往文件查看并填写配置信息 ## 目录说明 ```md ├─ build 构建工具 ├─ e2e 端对端工具 ├─ mock mock目录 ├─ public WEB目录（打包时移动到根目录） ├─ src 开发目录 │ ├─ api 请求接口 │ │ ├─ chat 聊天模组实现 │ │ ├─ access.ts 用户访问API │ │ ├─ chat.ts 聊天模组调用 │ ├─ assets 静态资源 │ ├─ components 全局组件 │ ├─ config 项目配置 │ │ ├─ llmProvider LLM Provider 实现 │ │ ├─ index.ts 配置文件 │ │ ├─ type.d.ts 配置类 │ ├─ i18n 多语言配置 │ ├─ provider 抽象实现 │ │ ├─ llm LLM实现 │ │ ├─ storage 本地存储实现 │ ├─ router 路由配置 │ │ ├─ index.ts 路由文件 │ │ ├─ utils.ts 路由工具 │ ├─ services 服务实现 │ │ ├─ chat 聊天服务 │ │ ├─ model 模型服务 │ │ ├─ user 用户服务 │ ├─ stores 状态存储 │ │ ├─ chat.ts 聊天存储 │ │ ├─ global.ts 全局存储 │ │ ├─ model.ts 模型存储 │ │ ├─ user.ts 用户存储 │ ├─ styles 样式定义 │ ├─ utils 工具集 │ ├─ view 页面视图 │ │ ├─ chat 聊天页面 │ │ ├─ login 登录页面 │ │ ├─ error.vue 错误页面 │ ├─ App.vue 入口页面 │ ├─ main.ts 入口文件 ├─types ts类型配置 │ ├─ .env 环境变量配置 ├─ .env.development 环境变量配置（开发模式） ├─ .env.staging 环境变量配置（预发布模式） ├─ .env.production 环境变量配置（生产模式） ├─ ...... 其它配置文件（如：package.json、tsconfig.json等） ``` ## Git 提交规范 - feat 增加新的业务功能 - fix 修复业务问题/BUG - perf 优化性能 - style 更改代码风格, 不影响运行结果 - refactor 重构代码 - revert 撤销更改 - test 测试相关, 不涉及业务代码的更改 - docs 文档和注释相关 - chore 更新依赖/修改脚手架配置等琐事 - workflow 工作流改进 - ci 持续集成相关 - types 类型定义文件更改 - wip 开发中 ## 开发环境 以下为个人开发环境参考： - pnpm v10.12.3 - node v22.17.0 - npm v10.9.2 ## 附：参考文档 - [Ant Design X Vue官方文档](https://antd-design-x-vue.netlify.app/) - [Ant Design X官方文档](https://x.ant.design/docs/spec/introduce-cn) - [Ant Design of Vue官方文档](https://antdv.com/docs/vue/introduce-cn) - [NaiveUI官方文档](https://www.naiveui.com/zh-CN/os-theme) - [xicons](https://xicons.org/)