# ai_demo

**Repository Path**: drm/ai_demo

## Basic Information

- **Project Name**: ai_demo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 聊天工具（ai-chat-tool）

一个开箱即用的 AI 聊天工具：流式对话 + 本地多会话 + 可编辑知识库 + 未知问题收集 + 用户情绪建议。支持**本地全栈**（前端 → 后端 → 真实大模型）与**纯前端静态部署**（自动降级为内置 mock 流式）两种运行模式。

## 功能特性

- 💬 **流式聊天（SSE）**：打字机式逐字输出；配置了 `AI_API_KEY` 走真实大模型，未配置时走本地 mock 流式，保证开箱即演示。
- 📚 **知识库（用户可编辑）**：维护标题 + 内容条目，发送聊天时作为上下文传给 AI；真实 AI 模式下会注入系统提示，让回答基于知识库。
- 🧠 **未知问题自动收集**：AI 答不出（mock 无命中 / 真实模型返回"无法回答"）时，自动记录问题与会话，便于后续补充知识。
- 😊 **用户情绪建议**：命中情绪关键词或连续 3+ 标点时，自动把该条消息记为用户建议（含会话 ID）。
- 🗂️ **多会话管理**：本地保存多个会话，可切换 / 删除，会话 ID 唯一。
- 🔗 **前端接后端**：知识库 / 未知问题 / 用户建议在前端更新后会同步到后端（best-effort），浏览器启动时优先从后端拉取；后端不可达时自动降级为 `localStorage`，保证可用性。
- 🧪 **类型严格 + 单测**：`strict` 模式，核心逻辑有详细单元测试。

## 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | Vite 5 · React 18 · TypeScript(strict) · MobX · Ant Design 5 · Less(CSS Modules) |
| 后端 | Express · SSE（Server-Sent Events）· Sequelize（PostgreSQL，可选） |
| 测试 | Vitest |

## 目录结构

```
srcWeb/                 前端（React + MobX）
  main.tsx App.tsx
  pages/Chat/           Chat 页面 + chatStore(MobX) + 6 个组件
  utils/storage.ts      localStorage 封装
api/                   前端 API 层（Api 基类 / chatApi SSE / dataApi 数据同步）
srcService/            后端（Express）
  service.ts           服务入口（默认 4201）
  component/database.ts  Sequelize（DB_ENABLED 开关）
  component/memoryStore.ts  内存兜底存储（无 DB 时使用）
  services/            aiChatService(SSE) / knowledgeBaseService / userSuggestionService
types/type.ts          前后端共用类型
config/                dev/prod 切换 apiBaseURL
```

## 本地运行（完整全栈）

```bash
npm install
cp .env.example .env        # 按需填写 AI / DB 参数
npm run dev:all             # 同时启动前端(5173) 与 后端(4201)
```

打开 http://localhost:5173 即可使用。**本地模式**下聊天会走后端 `/chat_stream`：
- 填了 `AI_API_KEY` → 调用真实大模型（OpenAI 兼容接口，默认阿里云百炼 qwen-flash）。
- 没填 → 后端 mock 流式（依据知识库判定是否"未知"）。
- 数据（知识库 / 建议 / 未知问题）会同步到后端；后端默认用**内存存储**，无需数据库即可完整运行。

## AI 大模型配置（.env）

```ini
AI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
AI_API_KEY=               # 填入你的密钥后即为真实 AI 模式
AI_MODEL=qwen-flash
```

未填 `AI_API_KEY` 时自动降级为 mock，不影响任何功能演示。

## 数据库（可选）

默认 `DB_ENABLED=false`，后端使用内存存储。如需持久化到 PostgreSQL：

```ini
DB_ENABLED=true
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ai_chat
DB_USER=your-user
DB_PASSWORD=your-password
```

后端会在启动时自动 `sync` 建表（模型字段与前端数据结构一致：字符串 UUID 主键）。

## 构建与云端部署

```bash
npm run build             # 产出 dist/ 生产包
npm test                  # 运行单元测试
```

**静态部署说明**：Express 后端无法在静态托管上运行，因此发布到静态平台（如 CloudStudio）的版本会自动走**前端 mock 流式 + localStorage**，功能完整可演示；"真实 AI + 后端持久化"需在本地 `dev:all` 模式体验。

## 测试

```bash
npm test
```

覆盖：`isEmotional` / `kbHit` 纯函数、`ChatStore` 增删改查闭环与 mock 流式、以及后端 `aiChatService` 的 SSE 流式（未知问题 / 知识库命中 / 空消息校验）。