内容
# HR 政策代理（MCP）
一款基于人工智能的代理，回答有关人力资源政策（假期、许可、请假、福利）的问题，并通过 **模型上下文协议（MCP）** 暴露其功能，允许任何兼容的主机（Claude Desktop、其他代理、人力资源平台）将其用作标准化工具 — 而不是专有的 REST API。
## 为什么选择 MCP 而不是 REST API
人力资源团队通常与多个系统和不同的业务单元（工资、福利、LMS、招聘）合作。通过 MCP 而不是临时 API 公开代理意味着任何 MCP 主机 — 包括其他团队的代理 — 都可以发现并使用工具而无需为每个系统签订特定的集成合同。该协议已经解决了发现、模式和调用问题。
## 架构
```mermaid
graph TB
subgraph 客户端["🌐 客户端"]
PHP["PHP 网站<br/>nilalisson.com.br/agente-rh.php"]
浏览器["浏览器"]
end
subgraph 虚拟私有服务器["☁️ 虚拟私有服务器 Oracle Linux"]
subgraph 网络层["网络层"]
防火墙["防火墙<br/>(iptables: 端口 80/443)"]
Nginx["🔒 Nginx<br/>api.nilalisson.com.br"]
end
subgraph 应用["应用"]
FastAPI["⚡ FastAPI<br/>POST /consultar<br/>GET /health"]
Systemd["systemd<br/>hr-policy-agent.service"]
end
subgraph 查询引擎["查询引擎"]
查询引擎["PolicyQueryEngine<br/>(LangChain)"]
ChromaDB["📊 ChromaDB<br/>向量存储"]
end
subgraph 数据["数据"]
政策["5 个人力资源政策<br/>(假期、许可、<br/>请假、福利、<br/>在家办公)"]
end
end
subgraph 外部服务["🌍 外部服务"]
Gemini["Gemini API<br/>聊天: 2.5-flash<br/>嵌入: 001"]
end
PHP -->|POST JSON| Nginx
浏览器 -->|HTTP/HTTPS| Nginx
防火墙 -->|允许 80/443| Nginx
Nginx -->|代理传递| FastAPI
Systemd -->|管理| FastAPI
FastAPI -->|调用| 查询引擎
查询引擎 -->|查询| ChromaDB
ChromaDB -->|向量搜索| 政策
查询引擎 -->|LLM| Gemini
Gemini -->|响应| 查询引擎
查询引擎 -->|JSON| FastAPI
FastAPI -->|JSON 响应| Nginx
Nginx -->|HTTP 200| PHP
PHP -->|渲染| 浏览器
style 客户端 fill:#e1f5ff
style 虚拟私有服务器 fill:#f3e5f5
style 网络层 fill:#fff3e0
style 应用 fill:#e8f5e9
style 查询引擎 fill:#fce4ec
style 数据 fill:#f1f8e9
style 外部服务 fill:#ede7f6
```
该图显示：
- **客户端** （您的 PHP 网站）
- **网络层** （防火墙 + Nginx，支持 HTTPS）
- **应用** （FastAPI + systemd）
- **查询引擎** （QueryEngine + ChromaDB）
- **数据** （政策语料库）
- **外部集成** （Gemini API）
- **完整的请求 → 响应流程**
---
### 如何添加到 README：
在您的本地 `README.md` 文件中，找到 **"## 架构"** 部分（旧的 ASCII 艺术所在位置），并用上面的 Mermaid 代码块替换它（在 ```mermaid 和 ``` 之间）。
然后进行提交：`"docs: 添加架构的 Mermaid 图"`
GitHub 将在您在浏览器中打开 README 时自动渲染它。
`query_engine.py` 和 `mcp_server.py` 被故意分开：这允许在公开协议独立于检索和响应质量的情况下进行测试和评估。
## 通过 MCP 公开的工具
| 工具 | 描述 |
|---|---|
| `consultar_politica(tema)` | 回答有关人力资源政策主题的问题，引用用作来源的政策 ID |
| `verificar_elegibilidade(funcionario_contexto, beneficio)` | 检查员工配置文件是否有资格获得特定福利 |
| `resumir_mudancas(periodo_descricao)` | 总结有效的政策及其版本，模拟机构变更日志 |
## 可追溯性
语料库中的每个政策都带有 `policy_id` 、 `versao` 和 `vigencia` 元数据。代理的每个回答都引用了用作来源的 `policy_id` — 在受监管环境的审计中应用了相同可追溯性要求 → 证据原则。
## 如何运行
```bash
pip install -r requirements.txt
export GOOGLE_API_KEY="您的密钥"
# 1. 生成向量索引
python src/ingest.py
# 2. 独立测试 RAG（无 MCP）
python tests/test_query_engine_manual.py
# 3. 启动 MCP 服务器
python src/mcp_server.py
```
要通过 MCP 主机（例如 Claude Desktop）进行消费，请在主机的配置文件中添加：
```json
{
"mcpServers": {
"hr-policy-agent": {
"command": "python",
"args": ["/绝对路径/到/src/mcp_server.py"],
"env": { "GOOGLE_API_KEY": "您的密钥" }
}
}
}
```
## 范围和限制
- 100% 合成语料库，为投资组合目的而创建 — 不反映任何公司的实际政策。
- 嵌入和生成使用 Google Gemini API（免费层）。
- 应用研究项目，重点演示：（a）具有源可追溯性的 RAG 设计，和（b）通过 MCP 协议公开代理。不包括身份验证、多用户或生产基础设施。
## 下一步（路线图）
- [ ] 使用参考问题集评估 RAGAS（忠实度、上下文精度）
- [ ] 运行 RAG 测试的 CI 管道（GitHub Actions），每次推送
- [ ] 使用更多政策和边缘情况扩展语料库（例如，福利累积、CLT → PJ 更改）
