# echo-ai

**Repository Path**: panfu/echo-ai

## Basic Information

- **Project Name**: echo-ai
- **Description**: 基于 Vue 3 + Vite + TypeScript + Axios 构建的极简 AI 对话助手，纯手写 CSS 还原 DeepSeek 风格界面，支持 DeepSeek 官方 API 与本地 Ollama 模型。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Echo AI

基于 Vue 3 + Vite + TypeScript + Axios 构建的极简 AI 对话助手，纯手写 CSS 还原 DeepSeek 风格界面，支持 DeepSeek 官方 API 与本地 Ollama 模型。

## 功能特性

- 💬 流式（SSE）与非流式对话，兼容 OpenAI 接口协议
- 🧠 深度思考：切换推理模型（`deepseek-reasoner`），推理过程可展开查看
- 🔍 智能搜索：开启联网搜索（DeepSeek `enable_search`）
- 🎛️ 模型选择：输入框下方下拉框可切换模型（可用 `VITE_AI_MODELS` 配置）
- 📎 附件上传：支持图片（视觉格式发送）、文本文件（内容随消息发送），以及 MP3 音频 / MP4 视频（消息内直接播放，仅展示不发送）
- 📝 多会话管理，本地持久化（localStorage）
- ⏹️ 支持中断生成（AbortController）
- 🖥️ DeepSeek 官方 API / 本地 Ollama 一键切换
- 🔒 API Key 支持环境变量与 localStorage 两种配置方式
- 🎨 纯手写 CSS，无 UI 框架依赖

## 技术栈

| 分类 | 技术 |
| --- | --- |
| 框架 | Vue 3（组合式 API + `<script setup lang="ts">`） |
| 构建 | Vite |
| 语言 | TypeScript（strict 模式） |
| HTTP | Axios + 原生 fetch（流式 SSE） |
| 类型检查 | vue-tsc |
| 包管理 | pnpm（版本由 `packageManager` 锁定） |

## 环境要求

- Node.js ≥ 18
- pnpm ≥ 10（`corepack enable && corepack prepare pnpm@10.33.0 --activate`）

## 快速开始

```bash
# 安装依赖（依赖版本由 pnpm-lock.yaml 精确锁定）
pnpm install

# 启动开发服务器（默认 http://localhost:5173）
pnpm dev

# 类型检查
pnpm typecheck

# 构建生产版本
pnpm build

# 预览生产版本
pnpm preview
```

> 使用 `pnpm install --frozen-lockfile` 可确保 CI 环境完全按锁定版本安装。

## 环境配置

复制或修改 `.env`（生产密钥请写入 `.env.local`，已被 gitignore 忽略）：

```bash
# DeepSeek API Key（https://platform.deepseek.com 获取）
VITE_DEEPSEEK_API_KEY=

# AI 提供商：deepseek（官方 API）| ollama（本地模型，免费）
VITE_AI_PROVIDER=deepseek

# 可选：指定模型
#   deepseek -> deepseek-chat（默认）
#   ollama   -> 如 qwen2.5:7b、deepseek-r1:1.5b
VITE_AI_MODEL=deepseek-chat
```

> 使用 Ollama 时需先本地安装并拉取模型，如 `ollama pull deepseek-r1:1.5b`；代理已自动将 `/api` 重写为 `/v1`。

## 项目目录结构

```markdown
echo-ai/
├── index.html                  # HTML 入口
├── vite.config.ts              # Vite 配置（@ 别名、代理）
├── tsconfig.json               # TypeScript 配置
├── package.json
├── pnpm-lock.yaml              # pnpm 依赖锁定文件（提交到仓库）
├── .env                        # 环境变量模板
├── src/
│   ├── main.ts                 # 应用入口
│   ├── App.vue                 # 根组件
│   ├── api/                    # 接口层
│   │   ├── request.ts          # Axios 封装、拦截器、API Key 管理、通用 SSE 流式请求
│   │   ├── chat.ts             # 聊天接口定义（流式 / 非流式）
│   │   ├── types.ts            # 共享类型（ChatMessage、ChatOptions 等）
│   │   └── index.ts            # 统一出口
│   ├── composables/
│   │   └── useChat.ts          # 对话状态与逻辑（会话管理、消息发送）
│   ├── components/
│   │   ├── ChatWindow.vue      # 对话窗口
│   │   ├── MessageItem.vue     # 单条消息
│   │   ├── ChatInput.vue       # 输入框（自动换行、Enter 发送）
│   │   └── Sidebar.vue         # 会话侧边栏
│   └── styles/
│       ├── reset.css           # 样式重置
│       ├── variables.css       # CSS 变量（颜色、间距、字体等）
│       └── global.css          # 全局样式
└── README.md
```

## API 分层设计

接口请求与封装代码分离，职责清晰：

- `request.ts`：底层封装层 —— Axios 实例、请求/响应拦截器、API Key 读写、通用 SSE 流式请求 `postStream`
- `chat.ts`：接口定义层 —— 具体对话接口 `sendChatMessage`（非流式）/ `streamChatMessage`（流式），复用封装层，不关心 HTTP 细节
- `types.ts`：共享类型定义，供 api 层与业务层复用
- `index.ts`：统一出口，业务代码只需 `import { streamChatMessage } from '@/api'`

## 数据流

1. `ChatInput.vue` 触发 `send` 事件
2. `App.vue` 调用 `useChat().sendMessage(text)`
3. `useChat.ts` 追加用户消息、创建空白助手消息，并调用 `streamChatMessage`
4. 流式增量通过 `onMessage` 回调实时更新助手内容，支持 `AbortController` 中断
5. 会话记录写入 localStorage，刷新后自动恢复

## 相关文档

- [AI 开发规范](docs/ai-dev-standards.md) —— 编码规范、API 分层约定、AI 辅助开发约定