内容
<div align="center">
# HR 智能平台
**自主人力资源操作的企业级多代理 AI 系统**
[](https://python.org)
[](https://langchain-ai.github.io/langgraph/)
[](#testing)
[](LICENSE)
[](https://hr-platform-1054475963653.us-central1.run.app/dashboard)
[在线演示](https://hr-platform-1054475963653.us-central1.run.app/dashboard) · [架构](#architecture) · [快速入门](#quick-start)
[📖 完整案例研究](https://aidenmak.com/hr-intelligence.html)
</div>
---
## 为什么选择这个项目？
大多数人力资源“AI”工具只是带有知识库的聊天机器人。这个平台不同——它协调 **8 个专门的 AI 代理**，自主处理复杂、涉及多步骤的人力资源工作流程，从头到尾：从回答政策问题到处理请假请求、福利登记、审计合规性和生成劳动力分析。
作为一个企业级系统构建，**MCP 集成**、**RAG 驱动的知识检索**、**PII 保护**和**生产可观察性** — 然后通过 **1,909 个测试**和在 GCP Cloud Run 上部署进行强化。
### 关键数据
| 指标 | 值 |
|--------|-------|
| 🤖 专门代理 | **8**（政策、请假、福利、合规、分析、入职、工资、招聘） |
| 🔧 MCP 工具 | **37** 个工具，**8** 个资源，**5** 个提示通过 FastMCP（独立） · **21** 个工具的 MCP 端点嵌入在 Web 应用程序中 |
| 🧪 测试覆盖率 | **1,909** 个测试（Pytest 单元/集成 + Playwright 端到端） |
| 📦 Python 模块 | **101** 个模块，涵盖整个平台 |
| ☁️ 部署 | **GCP Cloud Run**，具有 CI/CD 管道 |
---
## 功能展示
### 核心人力资源操作 — 人力资源团队实际购买的内容
<details>
<summary><b>🗓️ 请假管理</b> — 日历请求 → 确认 → 审批流程，端到端</summary>
<br>
余额卡在页面加载时回答“ 我还剩多少天？”。在日历上选择一个范围，确认您要请求的摘要，然后在历史记录中查看为 <i>待处理</i>，同时通知您的经理。
</details>
<details>
<summary><b>✅ 审批工作流</b> — 批准或拒绝并附上原因，每个决定都记录在案</summary>
<br>
每个待处理请求都进入一个队列；工作流时间线在做出决定时更新。拒绝会附带书面原因返回给员工：
</details>
<details>
<summary><b>💊 福利登记</b> — 浏览计划，在线登记，立即更新覆盖范围</summary>
<br>
医疗、牙科、视力和退休计划，保费并排显示 — 点击即可登记，当前登记立即反映。
</details>
<details>
<summary><b>👥 员工目录</b> — 实时搜索，网格/列表/组织结构图视图</summary>
<br>
从相同的实时数据库读取所有其他内容运行的数据 — 通过构造永远不会过时。搜索筛选条件在您输入时生效，跨姓名、部门、角色和电子邮件。
</details>
<details>
<summary><b>📁 文档中心</b> — 拖放上传 + 基于模板的生成</summary>
<br>
上传时显示进度和验证，或从填充员工实际记录的模板生成就业证书、录用通知和工资单。
</details>
<details>
<summary><b>📊 分析和报告</b> — 劳动力指标，一键导出 CSV/PDF</summary>
<br>
在职人数、请假使用情况、查询量和代理活动 — 按部门和日期范围过滤，可导出到会议室。
</details>
### AI 层 — 让它感觉轻松
<details open>
<summary><b>💬 对话式自助服务</b> — 用日常语言提问，获得有根据的答案</summary>
<br>
注意 <b>请假代理</b> 徽章、置信度分数和 <i>查看推理</i> 按钮 — 因为在聊天框后面，这不是一个聊天机器人。
</details>
<details>
<summary><b>🧭 多代理编排</b> — 三个问题，三个不同的专家</summary>
<br>
路由器将每个问题分类并分派给 8 个领域代理之一 — 观察徽章从 LEAVE 更改为 BENEFITS 再更改为 POLICY，跨越一次对话。
</details>
<details>
<summary><b>📚 RAG 政策问答</b> — 答案引用您的政策文档，附带来源芯片</summary>
<br>
询问人事档案在辞职后应保留多久，平台会回答公司的实际 7 年保留规则，引用 <i>gdpr_policy.txt 第 10 节</i>，并内联渲染每个检索的文档作为来源芯片。
</details>
<details>
<summary><b>🛡️ PII 保护</b> — 屏幕上屏蔽敏感数据，符合 GDPR/CCPA</summary>
<br>
包含 SSN、电话号码和个人电子邮件的消息被屏蔽 — <code>[SSN 已删除]</code>、<code>[电话号码已删除]</code> — 同时附上相关的 GDPR 和 CCPA 条款。
</details>
> 🎬 所有剪辑都使用脚本 Playwright 记录器（`scripts/record_showcase.js`）针对实时应用程序记录 — 在 [`docs/showcase/media/README.md`](docs/showcase/media/README.md) 中重新生成步骤。
---
## 架构
```mermaid
graph TB
subgraph Client["🖥️ 客户端层"]
UI[Web 仪表盘]
API_Client[API 消费者]
end
subgraph Gateway["🔀 API 网关"]
Flask[Flask REST API]
Auth[JWT 认证]
RateLimit[速率限制器]
PII[PII 屏蔽]
end
subgraph Orchestration["🧠 代理编排 — LangGraph"]
Router{智能路由器}
Policy[📋 政策代理]
Leave[🏖️ 请假代理]
Benefits[💊 福利代理]
Compliance[🔒 合规代理]
Analytics[📊 分析代理]
Onboarding[🎯 入职代理]
Payroll[💰 工资代理]
Recruitment[🔍 招聘代理]
end
subgraph Knowledge["📚 知识层"]
RAG[RAG 管道]
ChromaDB[(ChromaDB)]
Embeddings[句子转换器]
end
subgraph Integration["🔌 集成"]
MCP[MCP 服务器 — FastMCP]
BambooHR[BambooHR 连接器]
Slack[Slack 通知]
Teams[MS Teams]
end
subgraph Infrastructure["⚙️ 基础设施"]
Postgres[(PostgreSQL)]
Redis[(Redis 缓存)]
Prometheus[普罗米修斯]
Grafana[Grafana]
LangSmith[LangSmith 跟踪]
end
UI --> Flask
API_Client --> Flask
Flask --> Auth --> RateLimit --> PII --> Router
Router --> Policy & Leave & Benefits & Compliance & Analytics & Onboarding & Payroll & Recruitment
Policy & Leave & Benefits & Compliance --> RAG
RAG --> ChromaDB
RAG --> Embeddings
Router --> MCP
MCP --> BambooHR
Analytics --> Postgres
Policy --> Redis
Flask --> Prometheus --> Grafana
Router --> LangSmith
Compliance --> Slack & Teams
```
### 工作原理
1. **请求进入** → 带有 JWT 认证、速率限制和自动 PII 检测/屏蔽的 Flask API
2. **智能路由** → LangGraph 调度器分析意图并委派给正确的专业代理
3. **代理执行** → 每个代理都有自己的工具、知识访问（通过 RAG）和决策逻辑
4. **MCP 集成** → 通过 FastMCP 为外部系统互操作性暴露 37 个工具（BambooHR 等）
5. **响应返回** → 通过 LangSmith、普罗米修斯和 Grafana 追踪整个可观察性
---
## 技术栈
| 层 | 技术 |
|-------|-------------|
| **AI/ML** | LangGraph 0.2、OpenAI GPT-4、Gemini（备用）、ChromaDB、句子转换器 |
| **后端** | Python 3.10+、Flask 3.0、SQLAlchemy 2.0、Celery |
| **MCP** | FastMCP — 37 个工具、8 个资源（4 个静态 + 4 个模板）、5 个提示 · 嵌入式 Web 应用程序端点：21 个工具 |
| **数据** | PostgreSQL 15+、Redis 7+、ChromaDB |
| **前端** | HTML/CSS/JS、Jinja2、Chart.js |
| **基础设施** | Docker、GCP Cloud Run、Nginx、CI/CD |
| **可观察性** | 普罗米修斯、Grafana、LangSmith |
| **测试** | Pytest（1,909 个测试）、Playwright 端到端 |
| **合规** | GDPR、CCPA、HIPAA 框架 |
---
## 项目结构
```
HR-Intelligence-platform/
├── src/
│ ├── agents/ # 8 个专业 LangGraph 代理
│ │ ├── policy_agent.py
│ │ ├── leave_agent.py
│ │ ├── benefits_agent.py
│ │ ├── compliance_agent.py
│ │ ├── analytics_agent.py
│ │ ├── onboarding_agent.py
│ │ ├── payroll_agent.py
│ │ └── recruitment_agent.py
│ ├── api/ # REST API 路由和中间件
│ ├── core/ # RAG 管道、LLM 网关、合规引擎
│ ├── connectors/ # HRIS 集成（BambooHR、Workday）
│ ├── mcp/ # FastMCP 服务器 — 工具、资源、提示
│ ├── middleware/ # 速率限制、PII 屏蔽、JWT 认证
│ └── services/ # 业务逻辑和编排
├── frontend/ # Web UI（模板 + 静态资产）
├── tests/ # 1,909 个测试（单元、集成、端到端）
├── deploy/ # Docker、GCP Cloud Run 配置
├── docs/ # 架构和 API 文档
└── docker-compose.yml
```
---
## 快速入门
### 先决条件
- Python 3.10+
- Docker 和 Docker Compose
- OpenAI API 密钥
### 使用 Docker 运行（推荐）
```bash
# 克隆
git clone https://github.com/aidenmak0624/HR-Intelligence-platform.git
cd HR-Intelligence-platform
# 配置环境
cp .env.example .env
# 将您的 OPENAI_API_KEY 添加到 .env
# 启动所有服务
docker-compose up -d
# 访问仪表盘
open http://localhost:5050/dashboard
```
**演示凭证：** `admin@company.com` / `admin123`
### 本地运行
```bash
# 安装依赖
pip install -r requirements.txt
# 设置数据库
flask db upgrade
# 启动应用程序
python run.py
```
---
## 测试
该平台支持 **1,909 个测试**，涵盖多个测试层：
```bash
# 运行完整测试套件
pytest
# 运行覆盖率
pytest --cov=src --cov-report=html
# 运行端到端测试
playwright install
pytest tests/e2e/
```
| 测试类型 | 数量 | 涵盖内容 |
|-----------|-------|----------------|
| 单元 | ~1,400 | 代理逻辑、RAG 管道、PII 检测、合规规则 |
| 集成 | ~350 | API 端点、数据库操作、MCP 工具执行 |
| 端到端 | ~159 | 通过 Playwright 浏览器自动化进行完整用户流程 |
---
## MCP 集成
该平台通过 **FastMCP** 公开一个 MCP 服务器，用于与外部 AI 系统互操作：
```python
# 连接到 HR Intelligence Platform MCP 服务器
from fastmcp import Client
async with Client("hr-agent-mcp") as client:
# 列出可用工具
tools = await client.list_tools() # 37 个工具
# 执行工具
result = await client.call_tool(
"get_leave_balance",
{"employee_id": "EMP001"}
)
```
**37 个工具**，涵盖人力资源领域：请假管理、福利登记、政策查询、合规检查、分析报告等。
---
## 开发方法
该项目使用 **AI 辅助的“vibe 编码”方法** 构建 — 利用 Claude Code 进行架构和后端，GitHub Copilot 进行编辑器辅助，Figma 进行 UI 设计，Antigravity 进行手动 QA 验证。然后通过严格的测试（1,909 个测试）和生产部署对每个 AI 生成的组件进行强化。
📖 **[AI 辅助开发过程 — 通过 1,909 个自动化测试验证 →](https://aidenmak.com/hr-intelligence.html)**
---
## 在线演示
🔗 **[hr-platform-1054475963653.us-central1.run.app/dashboard](https://hr-platform-1054475963653.us-central1.run.app/dashboard)**
使用任何演示帐户登录（所有帐户均使用密码 `demo123`）— 每个角色看到的平台都不同：
| 角色 | 电子邮件 | 您将看到的内容 |
|------|-------|-----------------|
| 👤 员工 | `john.smith@company.com` | 自助服务：聊天、请假、福利、文档 |
| 👔 经理 | `sarah.chen@company.com` | + 审批工作流和团队可见性 |
| 🛡️ 人力资源管理员 | `emily.rodriguez@company.com` | + 目录、分析、完全监督 |
> ⏱️ 注意：冷启动后，前 ~60 秒服务快速静态答案，而 AI 服务初始化 — 给 RAG/代理功能一分钟时间预热。
> 演示数据是合成的（虚构公司“TechNova”）；未使用真实员工数据。
该平台部署在 **Google Cloud Run** 上，具有：
- 自动缩放和负载均衡
- 持续部署的 CI/CD 管道
- 普罗米修斯 + Grafana 监控
- LangSmith 跟踪代理可观察性
---
## 许可证
该项目根据 MIT 许可证授权 — 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
<div align="center">
**由 [Aiden Mak](https://aidenmak.com) 构建 · AI 工程师 · 多伦多**
[](https://aidenmak.com)
[](https://linkedin.com/in/mcwaiden)
[](mailto:mcwaiden000@gmail.com)
</div>
