内容
# 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](docs/releases/release-notes.md)。
## Architecture
```mermaid
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"]
```
## Local Setup
### 1. Start PostgreSQL + pgvector
推荐直接双击：
```text
start_database.bat
```
或手动执行：
```powershell
docker compose up -d postgres
```
数据库连接：
```text
postgresql://postgres:123456@127.0.0.1:5433/hr_agent
```
项目使用 `5433` 是为了避免和本机已安装 PostgreSQL 的 `5432` 冲突。
### 2. Start Backend
推荐直接双击：
```text
start_backend.bat
```
或手动执行：
```powershell
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
推荐直接双击：
```text
start_frontend.bat
```
或手动执行：
```powershell
npm install
npm run dev -- --host localhost --port 5199 --strictPort
```
访问：
```text
Frontend: http://localhost:5199
Backend: http://127.0.0.1:8010
```
## Environment
后端配置文件：
```text
backend/.env
```
不要提交真实 `.env`。GitHub 只提交：
```text
backend/.env.example
```
关键配置：
```env
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 数据在：
```text
docs/demo/demo_jd.txt
docs/demo/resume_ai_agent.txt
docs/demo/resume_backend_mcp.txt
```
可以在简历库页面上传 demo resume，再到筛选页复制 demo JD 运行筛选。
## Useful APIs
```text
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 启动：
```powershell
cd backend
.\.venv\Scripts\python.exe mcp_server.py
```
支持方法：
```text
initialize
tools/list
tools/call
```
当前工具：
```text
resume_search
create_email_draft
approve_and_send_email
send_feishu_report
```
HTTP 调试：
```powershell
curl http://127.0.0.1:8010/api/mcp/tools
```
调用示例：
```json
{
"name": "resume_search",
"arguments": {
"query": "AI Agent RAG MCP",
"top_k": 3
}
}
```
## Verification
后端测试：
```powershell
cd backend
.\.venv\Scripts\python.exe -m unittest discover -s tests
```
后端编译检查：
```powershell
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
```
前端构建：
```powershell
npm run build
```
## Before Publishing To GitHub
Run the public readiness check first:
```powershell
.\check_public_ready.bat
```
Or:
```powershell
python scripts/check_public_ready.py
```
This checks required sharing files, `.gitignore` protections, and obvious secret leaks.
首次上传 GitHub 可以跟着 [GitHub Upload Guide](docs/github-upload-guide.md) 一步步执行。
确认不要上传：
- `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 评估指标、工具调用日志和筛选任务历史审计，支持从简历上传、候选人召回、匹配评分到人工确认通知的完整闭环。
