# InterviewAssisted

**Repository Path**: opc_4/InterviewAssisted

## Basic Information

- **Project Name**: InterviewAssisted
- **Description**: AI 面试助手项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 速通 OFFER

AI 驱动的面试准备工具 - 实时语音转写 + 智能问题识别 + AI 参考答案生成，助你快速拿到心仪 OFFER。支持微信、钉钉、飞书等主流面试软件的线上面试场景。

## 系统能力

### 核心功能

| 功能 | 描述 | 状态 |
|------|------|------|
| 实时语音转写 | 采集麦克风/系统音频，faster-whisper (small) 实时转文字 | ✅ |
| 双通道音频采集 | 麦克风采集候选人语音，系统音频采集面试官语音（通过屏幕共享） | ✅ |
| 说话人区分 | 自动区分面试官和候选人的发言 | ✅ |
| 问题检测 | 规则引擎自动识别面试官提出的问题（支持 30+ 种问句模式） | ✅ |
| AI 答案生成 | 调用 LLM 流式生成参考答案（支持 DeepSeek / GPT-4o / 通义千问） | ✅ |
| 并发追问处理 | 面试官追问时，多个答案并行生成互不阻塞 | ✅ |
| 手动输入模式 | 用户手动输入问题获取答案（ASR 备用方案） | ✅ |
| 简历上传与解析 | 上传 PDF/DOCX/TXT 简历，LLM 结构化解析，答案个性化 | ✅ |
| 知识库管理 | 预设 Q&A 对，面试时优先匹配知识库零延迟返回 | ✅ |
| 面试题库 | 40+ 道内置高频面试题（前端/后端/行为），支持搜索和筛选 | ✅ |
| 面试复盘报告 | 面试结束后 LLM 自动生成表现分析报告 | ✅ |
| 笔试辅助 | 粘贴题目文本/截图，AI 解题（支持编程题） | ✅ |
| 移动端副屏 | 手机扫码查看答案（WebSocket 实时同步） | ✅ |
<<<<<<< HEAD
| 极速/精确双模式 | 同时生成极速回答和精确回答（知识库+题库检索增强），用户取优 | ✅ |
| 双端互联 | PC 端生成 QR 码/连接码，手机扫码连接同一 Session，实时同步答案 | ✅ |
| 语音触发词 | 候选人说"让我想想"等触发词时自动触发快答 | ✅ |
| Mac + iPhone 响应式 | iPhone 底部 Tab 导航 + 浮动控制面板 + Tab 切换转写/答案 | ✅ |
=======
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33

### 支持的面试场景

| 场景 | 方式 |
|------|------|
| 微信/钉钉/飞书视频面试 | 录音时选择共享面试软件窗口音频 |
| 线下面试（外放音频） | 麦克风同时采集面试官和自己的声音 |
| 电话面试 | 手机外放 + 电脑麦克风采集 |
| 纯文字交流 | 手动输入模式，直接粘贴问题 |

### 技术亮点

- **滑动窗口 ASR**：取最近 8 秒音频完整转写，避免断句错误
- **幻觉过滤**：自动去除 Whisper 模型常见幻觉文本（"发言人"、"字幕by" 等）
- **流式输出**：SSE / WebSocket 流式推送答案，打字机效果实时显示
- **LLM 可切换**：修改 `.env` 即可切换 DeepSeek / OpenAI / 通义千问等
- **暗色主题 UI**：专业暗色界面，面试时减少屏幕反光
- **日间/夜间模式切换**：支持自动检测系统偏好，手动切换主题，配色参考龙虾客户端

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.11+ / FastAPI / WebSocket |
| 语音识别 | faster-whisper (small model) / ffmpeg |
| LLM | OpenAI 兼容协议（DeepSeek / GPT-4o / 通义千问） |
| 前端 | Next.js 14 / React 18 / TypeScript |
| UI | Tailwind CSS / shadcn/ui / Lucide Icons |
| 状态管理 | Zustand |
| 数据库 | SQLite (SQLAlchemy) |
| 部署 | Docker Compose |

## 项目结构

```
InterviewAssisted/
├── backend/
│   ├── app/                    # FastAPI 应用配置
│   │   ├── main.py             # 入口，挂载路由和中间件
│   │   ├── config.py           # 环境变量配置
│   │   └── database.py         # SQLAlchemy 数据库连接
│   ├── routers/                # API 路由
│   │   ├── ws_audio.py         # WebSocket 实时音频流（核心）
│   │   ├── ws_viewer.py        # 移动端只读 WebSocket
<<<<<<< HEAD
│   │   ├── session.py          # Session 管理（创建/连接信息/QR码）
=======
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33
│   │   ├── chat.py             # 手动提问 SSE 接口
│   │   ├── resume.py           # 简历上传与解析
│   │   ├── knowledge.py        # 知识库 CRUD
│   │   ├── questions.py        # 题库搜索
│   │   └── interviews.py       # 面试记录与报告
│   ├── services/               # 业务逻辑层
│   │   ├── asr_service.py      # 语音识别（双通道 + 滑动窗口）
│   │   ├── llm_service.py      # LLM 调用（流式）
│   │   ├── question_detector.py # 问题检测（规则引擎）
<<<<<<< HEAD
    │   │   ├── dual_answer_engine.py # 极速/精确双模式答案引擎
    │   │   ├── voice_trigger.py   # 语音触发词服务
=======
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33
│   │   ├── resume_parser.py    # 简历结构化解析
│   │   ├── knowledge_base.py   # 知识库匹配
│   │   ├── question_bank.py    # 题库服务
│   │   ├── report_service.py   # 复盘报告生成
│   │   └── session_manager.py  # 面试 Session 管理
│   ├── models/                 # 数据模型
│   ├── prompts/                # LLM Prompt 模板
│   ├── data/questions/         # 内置题库（JSON）
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/app/
│   │   ├── (main)/page.tsx     # 面试辅助主页
│   │   ├── (main)/knowledge/   # 知识库管理
│   │   ├── (main)/practice/    # 题库练习
│   │   ├── (main)/history/     # 面试记录 + 复盘报告
│   │   ├── (main)/exam/        # 笔试辅助
<<<<<<< HEAD
│   │   ├── mobile/             # 移动端连接入口
    │   │   └── mobile/interview/  # 移动端面试答案展示（双模式）
=======
│   │   └── mobile/             # 移动端副屏
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33
│   ├── src/components/         # UI 组件
│   ├── src/hooks/              # 自定义 Hooks
│   ├── src/stores/             # Zustand 状态管理
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
├── Makefile
└── .env.example
```

## 快速开始

### 环境要求

- Python 3.11+
- Node.js 20+
- ffmpeg（`brew install ffmpeg`）

### 1. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 LLM API Key
```

支持的 LLM 配置：

```bash
# DeepSeek（默认，最便宜）
LLM_API_KEY=sk-your-deepseek-key
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat

# OpenAI
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

# 通义千问
LLM_API_KEY=sk-your-dashscope-key
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-turbo
```

### 2. 启动后端

```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

首次启动会自动下载 whisper small 模型（约 500MB）。

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

### 4. 使用

浏览器打开 http://localhost:3000

### Docker 一键启动

```bash
docker-compose up --build
```

## 使用指南

### 线上面试（微信/钉钉/飞书）

1. 打开面试软件，开始视频面试
2. 打开 http://localhost:3000，点击「录音」按钮
3. 弹出屏幕共享框时，**选择面试软件窗口**并**勾选「共享音频」**
4. 面试官说话 → 自动转写 → 检测到问题 → AI 生成参考答案
5. 状态栏显示「系统音频已采集」表示面试官声音正在被捕获

### 手动输入模式

底部输入框直接输入面试问题，回车发送，AI 流式输出答案。

### 知识库

访问「知识库」页面，预设常见问题的标准答案。面试时系统优先匹配知识库，命中则零延迟返回。

### 题库练习

访问「题库练习」页面，按分类/岗位/难度筛选题目，展开查看参考答案和追问。

### 笔试辅助

访问「笔试辅助」页面，粘贴题目文本（支持 Ctrl+V 粘贴截图），AI 解答。

### 移动端副屏

PC 端面试时，手机打开 `/mobile?session=xxx` 页面，实时同步显示 AI 答案。

## API 文档

后端启动后访问 http://localhost:8000/docs 查看完整 API 文档。

主要端点：

| 端点 | 方法 | 描述 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/ws/audio` | WebSocket | 实时音频流（核心） |
| `/ws/viewer` | WebSocket | 移动端只读 |
| `/api/chat/ask` | POST | 手动提问（SSE） |
| `/api/resume/upload` | POST | 简历上传 |
| `/api/resume/{id}/parsed` | GET | 获取结构化简历 |
| `/api/knowledge/` | CRUD | 知识库管理 |
| `/api/questions/search` | GET | 题库搜索 |
| `/api/interviews/` | CRUD | 面试记录 |
| `/api/interviews/{id}/report` | GET | 复盘报告 |
<<<<<<< HEAD
| `/api/session/create` | POST | 创建面试 Session |
| `/api/session/{id}/connect-info` | GET | 获取连接信息（IP/端口/QR码） |
| `/api/session/{id}` | DELETE | 销毁 Session |
=======
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33

## 前端页面

| 路径 | 功能 |
|------|------|
<<<<<<< HEAD
| `/` | 面试辅助主页（语音转写 + 双模式 AI 答案 + QR 码连接） |
=======
| `/` | 面试辅助主页（语音转写 + AI 答案） |
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33
| `/knowledge` | 知识库管理（增删改查） |
| `/practice` | 题库练习（筛选、搜索、参考答案） |
| `/history` | 面试记录列表 |
| `/history/[id]` | 复盘报告详情 |
| `/exam` | 笔试辅助（粘贴题目、AI 解题） |
<<<<<<< HEAD
| `/mobile` | 移动端连接入口（输入连接码） |
| `/mobile/interview` | 移动端面试副屏（双模式答案实时同步） |
=======
| `/mobile` | 移动端副屏（只读答案） |
>>>>>>> 3d6fdc9bed8fb7f0fc44d42958a47e79f5b21c33

## 发布记录

### v1.3.0 - 讯飞星辰大模型集成 (2026-03-27)

**核心功能**：
- ✅ 讯飞星辰大模型集成 (xop3qwen1b7)
- ✅ 手动提问 AI 答案生成
- ✅ SSE 流式实时输出
- ✅ 简历分析流式优化
- ✅ PDF/DOCX 解析错误优化

**API 端点**：
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/chat/ask` | POST | 手动提问 (SSE 流式) |
| `/api/resume/analyze` | POST | 简历分析 (非流式) |
| `/api/resume/analyze/stream` | POST | 简历分析 (SSE 流式) |
| `/api/resume/upload` | POST | 上传简历 (PDF/DOCX/TXT) |

**技术实现**：
- 后端：FastAPI + httpx SSE 流式
- 前端：ManualInput 组件流式接收
- LLM: 讯飞星辰 API v2 (OpenAI 兼容协议)

**提交记录**：
| Commit ID | 描述 |
|-----------|------|
| `630cf5b` | feat: v1.3.0 讯飞星辰大模型集成 + 流式 AI 回答 |

**修改文件**：
- `backend/main_full.py` - SSE 流式接口
- `backend/services/llm_xfyun.py` - 讯飞 API 调用
- `backend/app/config.py` - LLM 配置
- `frontend/next.config.js` - ESLint 配置

**访问地址**：http://121.41.2.193:3000

**稳定版本**：`v1.3.0` (Commit: `630cf5b`)

---

### v1.2.0 - 简历分析体验优化 (2026-03-27)

**核心改进**：
- ✅ 真流式 SSE 简历分析（后端逐条推送）
- ✅ 前端实时接收无闪烁
- ✅ PDF/DOCX 解析错误提示优化
- ✅ 简历分析页面全屏布局
- ✅ 分析按钮移到标题右侧

**技术实现**：
- 后端：`analyze_resume_text_stream()` 生成器逐条 yield
- 前端：SSE 接收 `item` 消息立即渲染
- 讯飞星辰 LLM：`xop3qwen1b7` 模型

**API 端点**：
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/resume/upload` | POST | 上传简历（PDF/DOCX/TXT） |
| `/api/resume/analyze` | POST | 分析简历（非流式） |
| `/api/resume/analyze/stream` | POST | 分析简历（SSE 流式） |

**提交记录**：
| Commit ID | 描述 |
|-----------|------|
| `2ae7417` | fix: PDF/DOCX 解析错误提示优化 |
| `e7e4870` | feat: 真流式简历分析 + 体验优化 |

**修改文件**：
- `backend/main_full.py` - SSE 流式接口、PDF 错误处理
- `backend/services/llm_xfyun.py` - 流式分析生成器
- `frontend/src/app/(main)/resume/page.tsx` - 流式接收与渲染

**访问地址**：http://121.41.2.193:3000/resume

**稳定版本**：`v1.2.0` (Commit: `2ae7417`)

---

### v1.2.0 - 管理后台系统 (2026-03-25 21:05)

**核心功能**：
- ✅ 数据看板 - 注册用户、模拟面试数、分析简历数、辅助面试数、充值金额
- ✅ 用户管理 - 用户列表、搜索、管理员权限设置
- ✅ 模型管理 - LLM 模型配置、启用/禁用、价格设置
- ✅ 积分审核 - 充值申请审核、通过/拒绝操作
- ✅ 代理信息 - 代理商业绩、引荐用户、营收统计
- ✅ 面试数据 - 面试记录、统计分析、评分展示

**访问地址**：http://8.209.69.110:8009/admin

**提交记录**：
| Commit ID | 描述 |
|-----------|------|
| `f8a2c1e` | feat: 新增管理后台系统 |

**修改文件**：
- src/app/(admin)/admin/layout.tsx - 管理端布局
- src/app/(admin)/admin/page.tsx - 数据看板
- src/app/(admin)/admin/users/page.tsx - 用户管理
- src/app/(admin)/admin/models/page.tsx - 模型管理
- src/app/(admin)/admin/points/page.tsx - 积分审核
- src/app/(admin)/admin/agents/page.tsx - 代理信息
- src/app/(admin)/admin/interviews/page.tsx - 面试数据

---

### v1.1.0 - 日间/夜间模式主题切换 (2026-03-25)

**特性**：
- ✅ 添加主题切换组件（太阳/月亮图标）
- ✅ 自动检测系统偏好（首次访问）
- ✅ 主题偏好保存到 localStorage
- ✅ 配色参考龙虾客户端

**配色方案**：
- **日间模式**：背景 #F5F5F7，卡片纯白，边框 #D4D4D8，增强阴影层次
- **夜间模式**：背景 #13131a，卡片 #1A1A24，边框深色

**提交记录**：
| Commit ID | 描述 |
|-----------|------|
| `b83a91f` | 修复日间模式下导航文字颜色不明显的问题 |
| `d74da75` | 增强日间模式层次感和视觉体验 |
| `6910662` | 所有页面适配日间/夜间模式 |
| `e2f1144` | 优化日间模式配色，参考龙虾客户端 |
| `0d9aa79` | 添加日间/夜间模式切换功能 |

**修改文件**：
- `src/app/globals.css` - CSS 变量定义
- `src/components/ThemeToggle.tsx` - 主题切换组件（新增）
- `src/components/NavBar.tsx` - 导航栏主题适配
- `src/components/ui/card.tsx` - 卡片阴影优化
- 所有页面组件 - 硬编码颜色替换为 CSS 变量

**访问地址**：http://8.209.69.110:8009

---

### v1.1.0 - 管理后台系统 (2026-03-26)

**新增功能**：
- ✅ 管理后台首页（数据看板）
- ✅ 用户管理（列表、启用/禁用、编辑）
- ✅ 模型配置管理（API Key、模型切换）
- ✅ 积分审核管理
- ✅ 代理信息管理
- ✅ 面试数据管理
- ✅ 日间/夜间主题切换
- ✅ 管理员登录认证系统
- ✅ 数据库持久化（volume 挂载）

**API 接口**：
| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/admin/admins` | GET | 获取管理员列表 |
| `/api/admin/admins` | POST | 创建管理员 |
| `/api/admin/admins/{id}` | GET | 获取管理员详情 |
| `/api/admin/admins/{id}` | PUT | 更新管理员信息 |
| `/api/admin/admins/{id}` | DELETE | 删除管理员（软删除） |
| `/api/admin/admins/{id}/reset-password` | POST | 重置密码 |
| `/api/admin/me/admin` | GET | 获取当前管理员信息 |

**提交记录**：
| Commit ID | 描述 |
|-----------|------|
| `f2b6e2b` | 修复登录页面无限加载问题 |
| `1c4889b` | 修复管理后台登录重定向问题 |
| `3ac14e2` | 添加管理后台登录认证 |
| `0a89d14` | 添加管理员登录控制系统 |
| `cbe3cf7` | 修复管理后台 ESLint 错误并重新构建 |
| `61e75e7` | 更新 README 添加管理后台发布记录 |
| `4bff3cb` | 新增管理后台系统 |

**访问地址**：
- 主站：http://8.209.69.110:8009
- 管理后台：http://8.209.69.110:8009/admin
- 登录页：http://8.209.69.110:8009/admin/login

**测试账号**：
- 用户名：`test`
- 密码：`test123`

---

### v1.0.0 - MVP 版本 (2026-03-24)

**核心功能**：
- ✅ 实时语音转写（faster-whisper）
- ✅ AI 答案生成（DeepSeek / GPT-4o）
- ✅ 知识库管理
- ✅ 面试题库
- ✅ 移动端副屏
- ✅ 用户认证系统

**提交记录**：详见 Git 历史