Interview Agent：基于 DeepSeek 的 AI 模拟面试平台，支持面试官与求职者双模式

AI 模拟面试助手 — 让每一次面试都更有准备

🚀 一键启动 • ✨ 功能特性 • 🧰 技术栈 • 📁 项目结构 • 📖 使用指南 • 🔌 API

📖 简介

Interview Agent 是一个基于大语言模型的 AI 模拟面试平台，支持面试官和求职者双重视角。结合 RAG 向量知识库与联网搜索能力，为每一场面试提供上下文感知的智能对话体验。

核心场景

✨ 功能特性

• 🤖 双模式 AI 对话 — 面试官 / 求职者自由切换，SSE 流式输出
• 🔑 前端 API Key 配置 — 在界面中直接配置 DeepSeek API Key，密钥仅存本地
• ⏱️ 面试时长推算 — 求职者模式下设置面试时长，自动推算问题数量与阶段拆分
• 🎯 模拟练习流程 — 求职者模式：AI 逐题提问 → 你回答 → 进度追踪 → 生成报告
• 🧑‍💻 编程题模式 — 技术岗专属，根据岗位类型智能选题（LeetCode 风格），支持难度自适应
• 🎓 候选人分级 — 支持实习 / 校招 / 社招三种级别，自动调整问题难度与深度
• 🔄 面试轮次 — 初试 / 复试 / HR 面，不同轮次侧重不同考察方向
• 📚 RAG 向量知识库 — 上传 PDF / Word / 文本，LangChain FAISS 向量检索增强回答质量
• 🌐 联网搜索 — 集成 DuckDuckGo，实时获取最新技术资讯
• 📝 面试报告生成 — 多维度评估（技术能力 / 沟通表达 / 综合素质），支持结构化 QA 逐题评估
• 🗂️ 岗位管理 — 创建岗位、添加多份 JD、关联知识库，支持按 JD 筛选
• 🎛️ 模型选择 — 支持 DeepSeek V4 Pro / Flash，可切换思考模式与推理强度
• 🔒 安全机制 — CORS 域名白名单 + FAISS 索引 SHA-256 完整性校验
• 📐 上下文窗口管理 — tiktoken 精确 token 计数 + LangChain trim_messages 智能裁剪
• 🎤 语音输入 (STT) — 按住说话/空格键录音，faster-whisper 流式识别，实时转文字
• 🔊 语音朗读 (TTS) — AI 回复一键朗读，Piper TTS 中文语音合成
• 🎛️ 灵活语音开关 — 启动时可选择 CPU/GPU，Docker Profile 按需启用，默认关闭零影响
• 🖥️ 现代化 UI — React + Ant Design 6，响应式布局
• 📷 截图答题 — AI 对话页一键截取主显示器画面，DeepSeek 视觉模型提取题目并在对话中直接作答（基于 windows-capture）
• 🐳 一键部署 — 支持本地脚本 / Docker Compose / 单容器三种启动方式

🚀 一键启动

四种方式任选其一：

首次使用：复制 .env.example → .env，填入 DeepSeek API Key

国内用户注意：首次启动需下载 Embedding 模型（约 90MB），.env 中已默认配置 HuggingFace 镜像 HF_ENDPOINT=https://hf-mirror.com，无需额外操作。

主要配置项

方式一：独立窗口模式（desktop.py）

把整个应用（后端 + 已构建前端）装进一个独立的应用窗口里，不依赖浏览器标签页， 适合面试 / 演示场景。

Windows — 双击 start_app.bat，或：

python desktop.py

等价的 main.py 写法（参数会自动转发）：

python main.py --desktop
python main.py --desktop --no-topmost --width 1366 --height 768

常用参数

上表中的窗口项均可在界面「设置」面板中随时开关，启动参数只决定初始状态。 | --window-title TEXT | 面试 Agent — AI 模拟面试助手 | 窗口标题 | | --shell {auto,native,browser} | auto | 窗口实现方式（见下） | | --port N / --auto-port | 8000 / false | 端口；被占用时可自动顺延 | | --app PATH | — | 启动后打开的页面，如 --app /login | | --debug | false | 开启 WebView 开发者工具 |

界面配色（背景色 / 文字色）

设置面板顶部提供界面配色控制，浏览器与独立窗口模式下都可用：

• 7 套预设方案：默认浅色 / 护眼米色 / 护眼绿 / 淡雅蓝 / 深色 / 午夜蓝 / 暗褐
• 背景色与文字色取色器，可自由调整
• 自动调整文字色：选深色背景时自动把文字切成浅色，避免深底黑字看不清
• 对比度提示：实时显示 WCAG 对比度，低于 4.5:1 会提示并提供「自动修正」

配色通过 antd ConfigProvider 全局生效（侧边栏 / 顶栏 / 内容区 / 卡片都跟随）， 并保存在 localStorage，刷新后保持。深色背景会自动启用 antd 暗色算法， 确保弹窗、下拉框等浮层也保持可读。

界面内实时调整窗口设置

独立窗口模式下，界面顶栏会出现 设置 按钮（齿轮图标），点开后包含：

• 窗口透明度滑块（20% - 100%）—— 拖动即时生效，无需重启
• 窗口置顶开关
• 隐藏任务栏图标开关 —— 运行中可随时切换
• 捕获排除开关 —— 截屏 / 录屏中是否隐藏窗口内容，运行中可随时切换
• 「恢复不透明」快捷按钮

以上开关也可作为启动参数使用（--topmost / --hide-taskbar / --capture-exclude）， 启动参数决定初始状态，之后可在界面里随时改。

该类窗口项在普通浏览器中自动隐藏 —— 透明度是 Windows 窗口属性，只能由 Python 侧修改， 网页滑块通过 pywebview 的 JS↔Python 桥接（window.pywebview.api）回写窗口。 透明度下限为 20%，避免窗口过淡导致无法操作。

捕获排除开关在 browser 回退模式下会显示为禁用状态：该 API 不允许跨进程调用， 而浏览器 --app 窗口属于浏览器进程。

关于隐藏任务栏图标的实现：Windows 在窗口「首次显示」时就会向任务栏注册按钮， 之后再改 WS_EX_TOOLWINDOW 样式不会让已存在的按钮消失。 因此切换时执行的是「隐藏窗口 → 改扩展样式 → 重新显示」的循环， 让任务栏重新判定该窗口的去留（只改样式而缺这一步是无效的）。

两种窗口实现

为什么 browser 模式做不到「捕获排除」？ Windows 的 SetWindowDisplayAffinity 只能作用于本进程拥有的窗口。 browser 模式下窗口属于浏览器进程，跨进程调用会被系统拒绝（实测返回 False）。 native 模式窗口由本进程创建，因此该功能真正生效 —— 截图 / 录屏 / 直播中该窗口内容不可见（可通过 GetWindowDisplayAffinity 验证返回值为 0x11）。

未安装 pywebview 时会自动回退到 browser 模式，功能不受影响（仅捕获排除无效）。

配置项（可写入 .env，命令行参数优先级更高）

独立窗口模式要求先构建前端：cd frontend && npm run build （start_app.bat 会在缺失时自动构建）

方式二：本地脚本（开发推荐）

Windows — 双击 start.bat

macOS / Linux：

chmod +x start.sh
./start.sh

脚本自动完成：环境检测 → 安装依赖 → 启动后端 :8000 + 前端 :5173 → 打开浏览器。

方式三：Docker Compose（部署推荐）

前置条件

• Docker 20.10+ & Docker Compose v2+
• DeepSeek API Key

标准部署（含 RAG 向量知识库）

# 1. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

# 2. 启动
docker-compose up -d

# 3. 验证
docker-compose ps

访问 http://localhost

首次启动会自动下载 Embedding 模型（约 90MB），已配置 HuggingFace 镜像。启动耗时约 2-3 分钟。

轻量部署（无 RAG，适合无 CUDA / 低资源环境）

# 不安装向量知识库依赖，镜像体积减少约 2GB
SKIP_RAG=true RAG_ENABLED=false docker-compose up -d

此模式下对话、面试模拟、报告生成等核心功能完全正常，仅知识库上传和 RAG 检索不可用。

架构说明

Browser → Nginx (:80) → /api/* 反代 → FastAPI (:8000)
                       → 其他路径 → 前端静态文件

常用命令

语音功能

# 本地开发：启动时选择 y → 选 CPU/GPU → 自动安装依赖+下载模型
start.bat   # 或 ./start.sh

# Docker：通过 Profile 启用
docker compose --profile cpu up    # CPU 语音
docker compose --profile gpu up    # GPU 语音

# 仅语音识别或仅语音合成
docker compose --profile stt up    # 仅 STT
docker compose --profile tts up    # 仅 TTS

首次使用会自动下载模型（whisper ~480MB + Piper ~50MB）。

数据持久化

方式四：单容器 Docker

# 构建（不含 RAG）
docker build --build-arg SKIP_RAG=true -t interview-agent .

# 运行
docker run -d \
  --name interview-agent \
  -p 8000:8000 \
  --env-file .env \
  -e RAG_ENABLED=false \
  -v interview-data:/app/data \
  interview-agent

访问 http://localhost:8000

包含 RAG 时去掉 --build-arg SKIP_RAG=true，并添加 -e RAG_ENABLED=true 和 -v interview-chroma:/app/chroma_data。

🧰 技术栈

后端

前端

📁 项目结构

interview-agent/
├── main.py                  # FastAPI 入口
├── desktop.py               # 独立窗口启动器（置顶 / 捕获排除 / 原生窗口）
├── config.py                # 环境变量配置
├── requirements.txt         # Python 依赖
├── Dockerfile               # 多阶段构建（前端+后端）
├── docker-compose.yml       # Docker Compose 编排
├── start.bat                # Windows 一键启动
├── start_app.bat            # Windows 独立窗口启动
├── start.sh                 # macOS/Linux 一键启动
├── .env.example             # 环境变量模板
├── positions.json           # 岗位数据
│
├── routers/                 # API 路由
│   ├── chat.py              #   对话 (SSE 流式)
│   ├── interview.py         #   面试控制（开始/停止/报告/计划）
│   ├── position.py          #   岗位管理
│   ├── upload.py            #   文件上传
│   ├── knowledge.py         #   知识库管理
│   └── screenshot.py        #   截图识别（WGC 抓屏 + 视觉答题）
│
├── services/                # 业务逻辑
│   ├── llm_client.py        #   DeepSeek 客户端
│   ├── screen_capture.py    #   WGC 窗口捕获 + 图像编码 + 视觉调用
│   ├── vector_store.py      #   LangChain FAISS 向量存储
│   ├── rag_pipeline.py      #   LCEL RAG 检索管线
│   ├── chunker.py           #   文档分块
│   ├── parser.py            #   文件解析 (PDF/Word)
│   ├── agent_tools.py       #   联网搜索工具
│   ├── coding_problem.py    #   编程题智能选题
│   ├── model_registry.py    #   模型注册表
│   ├── position_store.py    #   岗位持久化
│   └── upload_store.py      #   上传文件持久化
│
├── utils/                   # 工具模块
│   ├── context_manager.py   #   上下文窗口管理 (tiktoken)
│   ├── prompt_loader.py     #   提示模板加载 (LangChain)
│   └── position_classifier.py  # 岗位类型分类器
│
├── models/
│   └── schemas.py           # Pydantic 数据模型
│
├── prompts/                 # 系统提示词
│   ├── interviewer.txt      #   面试官
│   ├── candidate.txt        #   求职者
│   └── report.txt           #   报告生成
│
├── data/
│   └── leetcode_problems.json  # 编程题库
│
├── frontend/                # React 前端
│   ├── Dockerfile           #   前端镜像
│   ├── nginx.conf           #   Nginx 配置
│   └── src/
│       ├── api/             #   API 客户端
│       ├── pages/           #   页面
│       ├── components/      #   组件
│       ├── stores/          #   状态
│       └── hooks/           #   Hooks
│
├── tests/                   # 测试
└── chroma_data/             # FAISS 索引存储
    └── faiss_indexes/       #   按知识库名分目录

📖 使用指南

你是面试官

创建岗位 → 添加 JD → 上传知识库 → 上传简历/代码 → 切换模式 → 向 AI 求职者提问

1. 在「岗位管理」页面创建岗位，添加职位描述
2. 在「知识库」页面上传相关文档（技术规范、FAQ 等）
3. 在「上传」页面上传候选人简历（PDF / Word）和代码文件
4. 切换到「AI 对话」页面，选择 🎯 你是面试官 模式
5. 向 AI 求职者提问，AI 会结合 JD、简历、代码和知识库给出专业回答
6. AI 回答完毕后，前往「面试报告」页面生成评估

你是求职者

创建岗位 → 添加 JD → 上传知识库 → 上传简历 → 设置面试时长 → 推算题数 → 开始练习 → AI 提问你回答 → 生成报告

1. 创建目标岗位并填写 JD
2. 在「知识库」页面上传相关文档，在「上传」页面上传你的简历
3. 切换到「AI 对话」页面，选择 🧑 你是求职者 模式
4. 选择面试时长（15/30/45/60 分钟），点击 推算 获取预估题数
5. 点击 开始模拟练习，AI 面试官自动逐题提问
6. 在输入框中回答每个问题，练习中实时显示进度（第 N/M 题）
7. 完成后点击 结束练习，前往「面试报告」页面一键生成多维度评估

ChatRequest 参数

{
  "messages": [{"role": "user", "content": "请介绍一下你自己"}],
  "mode": "interviewer",
  "position_name": "前端工程师",
  "jd_id": "jd_001",
  "use_search": false,
  "coding_enabled": false,
  "model": "deepseek-v4-pro",
  "thinking_enabled": true,
  "reasoning_effort": "high",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "candidate_level": "experienced",
  "interview_round": "first",
  "interview_duration_minutes": 30,
  "interview_question_count": 10
}

🔌 API 概览

完整 API 文档：启动后访问 http://localhost:8000/docs (Swagger) 或 /redoc

📷 截图答题

在 AI 对话页底部输入框右侧有一个 「截图」 按钮：点击后自动截取主显示器画面，交给 DeepSeek 视觉模型提取题目并作答，回答直接显示在对话里（与普通 AI 回复一样渲染 Markdown 与代码高亮）。

实现说明

截图基于 windows-capture（Rust 实现，底层为 Windows Graphics Capture）：

• 该库是显示器维度的捕获接口，monitor_index 从 1 开始（1 = 主显示器；传 0 会被库拒绝）；
• 本项目固定截取主显示器，不做多屏拼接 —— 拼接需要每块屏的精确位置与尺寸，而该库只提供按显示器捕获，拿不到布局信息（早前按坐标估算拼接的实现，在副屏比主屏高时会裁掉副屏底部）；
• 鼠标光标由库的 cursor_capture 原生支持。

说明：项目早期版本曾用 wgc-python（只能按窗口捕获，无法整屏），也试过 GDI BitBlt，现统一使用 windows-capture。

前置条件

⚠️ 务必使用支持视觉的模型。 纯文本模型（如 deepseek-v4-flash）不具备视觉能力，把图片发给它不会报错，而是忽略图片并编造一个看似合理的答案。可通过 SCREENSHOT_VISION_MODEL 指定；若该模型不可用，接口会明确报错而不是返回幻觉答案。

使用步骤

1. 打开 AI 对话 页面
2. 点击输入框右侧的 截图 按钮

输入框里可以先写一句要求（例如「只给答案，不要解释」），截图时会一并作为提问发给模型。

独立窗口模式（desktop.py）下，截图前会自动把本应用从屏幕捕获中排除，因此不会把自己拍进去；用完会恢复你原本的设置。

相关配置

SCREENSHOT_ENABLED=true                 # 总开关
SCREENSHOT_VISION_MODEL=deepseek-flash  # 视觉模型（必须支持图片输入）
SCREENSHOT_DIR=screenshots              # 截图保存目录
SCREENSHOT_MAX_IMAGE_EDGE=1280          # 上传前图片最长边
SCREENSHOT_MAX_TOKENS=8192              # 单次输出上限
SCREENSHOT_THINKING_ENABLED=false       # 截图问答是否启用思考模式
SCREENSHOT_SAVE=true                    # 是否把截图留档

⚠️ 关于思考模式：DeepSeek 的思考模式默认是开启的，且思维链与正文共享 max_tokens 预算。截图答题若开启思考，推理会占掉大量预算，导致正文被截断（表现为回答写到一半突然中断）。因此本功能默认关闭思考模式；若你把 SCREENSHOT_MAX_TOKENS 调得很小，回答仍可能被截断 —— 此时界面会明确标注「回答被截断」，而不是让你误以为模型只答了一半。

🧪 运行测试

pytest tests/ -v

🤝 贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: add amazing feature')
4. 推送分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📄 License

MIT © 2025