HR Multi-Agent Screening Platform

面向 HR 初筛场景的 AI Agent 项目。系统支持简历上传解析、RAG 候选人知识库检索、多智能体筛选工作流、MCP 风格工具调用、PostgreSQL + pgvector 持久化、邮件通知、飞书日报和运行历史审计。

Highlights

• Vue3 + TypeScript + Element Plus 前端工作台。
• FastAPI 后端，按简历、RAG、Agent Workflow、工具调用、通知动作分层。
• TXT / PDF / DOCX 简历上传解析，生成候选人和 evidence chunks。
• RAG 使用关键词 + embedding similarity hybrid retrieval，并展示召回解释。
• PostgreSQL + pgvector 保存候选人、简历 chunks 和筛选任务历史。
• Supervisor Agent 编排 JD 解析、候选人检索、筛选评分、通知草稿、飞书日报。
• MCP-style tool registry 统一记录 resume_search、send_email、send_feishu_report、llm_generate。
• 独立 MCP JSON-RPC adapter，可通过 stdio 或 HTTP 调试接口暴露工具。
• HR human-in-the-loop：邮件草稿生成、确认发送、飞书日报发送都会写回同一条 run 审计链路。
• 内置 RAG 评估指标：Recall@K、Precision@K、MRR、Faithfulness。

Latest Update

2026-07-03

• 完成 HR 多智能体筛选平台的核心闭环：简历上传解析、RAG 候选人召回、多智能体筛选、邮件草稿、确认发送、飞书日报和历史审计。
• 增加 PostgreSQL + pgvector、MCP JSON-RPC adapter、GitHub 发布前体检脚本和首次上传指南。
• 完整历史见 Release Notes。

Architecture

flowchart LR
  HR["HR User"] --> FE["Vue3 Frontend"]
  FE --> API["FastAPI Backend"]
  API --> WF["Screening Workflow"]
  WF --> JD["JDParserAgent"]
  WF --> RAG["CandidateRetrievalAgent"]
  WF --> SCORE["ScreeningAgent"]
  WF --> NOTICE["NotificationAgent"]
  WF --> REPORT["ReportAgent"]
  RAG --> PG["PostgreSQL + pgvector"]
  WF --> TOOLS["MCP-style Tool Registry"]
  TOOLS --> SMTP["QQ Email SMTP"]
  TOOLS --> FS["Feishu Webhook"]
  API --> LLM["DeepSeek API"]

Loading

Local Setup

1. Start PostgreSQL + pgvector

推荐直接双击：

start_database.bat

或手动执行：

docker compose up -d postgres

数据库连接：

postgresql://postgres:123456@127.0.0.1:5433/hr_agent

项目使用 5433 是为了避免和本机已安装 PostgreSQL 的 5432 冲突。

2. Start Backend

推荐直接双击：

start_backend.bat

或手动执行：

cd backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python -m uvicorn app.main:app --host 127.0.0.1 --port 8010 --reload

3. Start Frontend

推荐直接双击：

start_frontend.bat

或手动执行：

npm install
npm run dev -- --host localhost --port 5199 --strictPort

访问：

Frontend: http://localhost:5199
Backend:  http://127.0.0.1:8010

Environment

后端配置文件：

backend/.env

不要提交真实 .env。GitHub 只提交：

backend/.env.example

关键配置：

LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

EMBEDDING_PROVIDER=deterministic
EMBEDDING_DIMENSIONS=16

DATABASE_URL=postgresql://postgres:123456@127.0.0.1:5433/hr_agent

SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_USER=your_email@qq.com
SMTP_PASSWORD=your_qq_email_authorization_code
SMTP_FROM=your_email@qq.com
SMTP_TEST_TO=your_email@qq.com

FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/your_token
MAX_UPLOAD_MB=15

Pages

• Dashboard：项目指标和能力概览。
• Resume Pool：上传 TXT / PDF / DOCX 简历，查看候选人和 evidence chunks。
• Screening：运行筛选任务、查看 RAG 证据、历史 run、邮件/飞书人工动作。
• Agent Workflow：查看多智能体执行链路。
• Notification Center：邮件草稿预览和确认发送。
• Feishu Report：飞书日报预览和发送。
• MCP Tool Logs：工具调用日志。
• Evaluation Status：集成状态和 RAG 评估指标。

Demo Data

虚构 demo 数据在：

docs/demo/demo_jd.txt
docs/demo/resume_ai_agent.txt
docs/demo/resume_backend_mcp.txt

可以在简历库页面上传 demo resume，再到筛选页复制 demo JD 运行筛选。

Useful APIs

GET  /api/health
GET  /api/candidates
POST /api/resumes/upload
GET  /api/candidates/{candidate_id}/chunks
POST /api/agent/workflows/screening/run
GET  /api/screening-runs
GET  /api/screening-runs/{run_id}
POST /api/screening-runs/{run_id}/candidates/{candidate_id}/email-draft
POST /api/screening-runs/{run_id}/email-drafts/{draft_id}/approve-send
POST /api/screening-runs/{run_id}/feishu-report/send
GET  /api/mcp/tool-calls
GET  /api/mcp/tools
POST /api/mcp/tools/call
GET  /api/evaluation/report
GET  /api/integrations/status
GET  /api/embeddings/test
GET  /api/llm/test

MCP Server

项目提供一个轻量 MCP JSON-RPC adapter，复用后端工具注册表。

stdio 启动：

cd backend
.\.venv\Scripts\python.exe mcp_server.py

支持方法：

initialize
tools/list
tools/call

当前工具：

resume_search
create_email_draft
approve_and_send_email
send_feishu_report

HTTP 调试：

curl http://127.0.0.1:8010/api/mcp/tools

调用示例：

{
  "name": "resume_search",
  "arguments": {
    "query": "AI Agent RAG MCP",
    "top_k": 3
  }
}

Verification

后端测试：

cd backend
.\.venv\Scripts\python.exe -m unittest discover -s tests

后端编译检查：

cd backend
.\.venv\Scripts\python.exe -m py_compile app\main.py app\agents\workflow.py app\services\notification_actions.py app\repositories\candidate_repository.py app\repositories\screening_run_repository.py app\rag\resume_knowledge_base.py app\schemas\domain.py

前端构建：

npm run build

Before Publishing To GitHub

Run the public readiness check first:

.\check_public_ready.bat

Or:

python scripts/check_public_ready.py

This checks required sharing files, .gitignore protections, and obvious secret leaks.

首次上传 GitHub 可以跟着 GitHub Upload Guide 一步步执行。

确认不要上传：

• backend/.env
• 根目录 .env
• DeepSeek API Key
• QQ 邮箱授权码
• Feishu Webhook
• 真实候选人简历
• 真实手机号、邮箱、公司内部信息

.gitignore 已经忽略 .env 和 backend/.env，但上传前仍建议手动检查一次。

Resume Description

HR Multi-Agent Screening Platform｜基于 RAG 与 MCP 工具调用的智能招聘筛选系统

设计并实现面向 HR 初筛场景的多智能体招聘筛选平台，支持批量简历解析、RAG 候选人知识库检索、PostgreSQL + pgvector 向量持久化、DeepSeek 驱动的 JD/候选人分析、多智能体工作流编排、MCP 风格工具调用、QQ 邮箱通知与飞书日报推送。系统内置 RAG 评估指标、工具调用日志和筛选任务历史审计，支持从简历上传、候选人召回、匹配评分到人工确认通知的完整闭环。