# ai-hr

**Repository Path**: hephec321/ai-hr

## Basic Information

- **Project Name**: ai-hr
- **Description**: ai-hr
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# Simular HR Agent 数字员工

🎯 **Simular HR Agent** 是一款基于 AI 的数字员工系统，旨在通过自动化技术提升 HR 工作效率。该系统集成了 Simular Agent-S (GUI-Agents) 核心能力，支持浏览器自动化、桌面自动化和智能工作流编排，可处理招聘、入职、薪酬核算等复杂 HR 场景任务。

## 核心功能模块

### 🤖 智能招聘管理

- **职位发布自动化**：支持多平台（Boss 直聘等）自动发布职位信息，结合 AI 理解招聘需求并智能填充内容
- **简历智能解析**：基于 OCR 技术自动识别 PDF/图片简历，提取候选人关键信息
- **候选人筛选**：AI 辅助初筛，自动评估候选人匹配度
- **面试邀请发送**：自动生成并发送面试通知，支持多种面试形式

### 👥 入职流程自动化

- **员工信息管理**：创建和维护员工档案，支持身份证信息自动识别
- **多系统账号创建**：自动在 OA、钉钉、邮件等系统创建入职账号
- **入职进度跟踪**：可视化展示员工入职流程状态

### 💰 薪酬核算管理

- **考勤数据导出**：自动从钉钉等平台导出考勤记录
- **薪资计算**：支持社保公积金个税自动核算
- **工资发放**：批量执行工资发放操作
- **历史记录查询**：完整的薪酬发放历史追溯

### ⚙️ 工作流引擎

- **可视化工作流设计**：通过录制或手动配置创建自动化工作流
- **混合执行模式**：支持传统步骤与 AI 智能步骤混合编排
- **人机协作机制**：复杂任务支持人工接管，确保执行准确
- **工作流录制**：实时记录用户操作并转换为可执行工作流

## 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                      前端展示层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Vue.js    │  │   PyQt6     │  │    WebSocket        │  │
│  │  (Web管理)   │  │ (桌面客户端)  │  │   (实时通信)        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                      后端服务层 (FastAPI)                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    API 路由层                         │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │  │
│  │  │ 招聘模块 │ │ 入职模块 │ │ 薪酬模块 │ │ 工作流模块  │ │  │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   核心引擎层                          │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │  │
│  │  │ Agent-S2   │ │ 浏览器引擎  │ │  桌面自动化引擎  │  │  │
│  │  │ AI智能体    │ │ (Playwright)│ │   (PyQt/PyAutoGUI)│  │  │
│  │  └─────────────┘ └─────────────┘ └─────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   OCR 处理层                           │  │
│  │        (身份证识别 | 简历解析 | 验证码识别)             │  │
│  └───────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                      AI 基础模型层                            │
│  ┌─────────────────┐        ┌─────────────────────────────┐ │
│  │  UI-TARS        │        │  OpenAI / Claude API       │ │
│  │  (GUI定位模型)   │        │  (大语言模型)               │ │
│  └─────────────────┘        └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 核心技术栈

| 层次 | 技术选型 | 说明 |
|------|----------|------|
| **AI 核心** | Simular Agent-S (gui-agents) | GUI 智能体，理解屏幕并执行自然语言指令 |
| **后端框架** | Python + FastAPI | 高性能异步 Web 框架 |
| **浏览器自动化** | Playwright | 跨浏览器自动化测试框架 |
| **桌面自动化** | PyQt6 + PyAutoGUI | 本地应用自动化控制 |
| **OCR 识别** | PaddleOCR / EasyOCR | 文档识别与文本提取 |
| **前端框架** | Vue 3 + TypeScript | 现代化前端开发 |
| **UI 组件库** | Element Plus | Vue 3 组件库 |
| **数据库** | SQLAlchemy + SQLite | ORM 框架与数据存储 |

## 项目目录结构

```
simular-hr-agent/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── api/v1/            # API 接口模块
│   │   │   ├── agent.py       # Agent 状态与控制
│   │   │   ├── audit.py       # 审计日志接口
│   │   │   ├── onboarding.py  # 入职管理接口
│   │   │   ├── payroll.py     # 薪酬核算接口
│   │   │   ├── recruitment.py # 招聘管理接口
│   │   │   └── workflow.py    # 工作流接口
│   │   ├── core/              # 核心引擎
│   │   │   ├── agent_s2.py    # Agent-S2 智能体
│   │   │   ├── browser.py     # 浏览器自动化
│   │   │   ├── desktop.py     # 桌面自动化
│   │   │   ├── ocr.py         # OCR 识别引擎
│   │   │   └── workflow.py    # 工作流引擎
│   │   └── models/            # 数据模型
│   │       ├── audit.py        # 审计日志模型
│   │       ├── candidate.py   # 候选人模型
│   │       ├── employee.py     # 员工模型
│   │       ├── task.py         # 任务模型
│   │       ├── user.py         # 用户模型
│   │       └── workflow.py     # 工作流模型
│   ├── requirements.txt        # Python 依赖
│   ├── config.py              # 配置文件
│   └── main.py                # 应用入口
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── views/             # 页面组件
│   │   │   ├── Dashboard/     # 工作台
│   │   │   ├── Recruitment/   # 招聘管理
│   │   │   ├── Onboarding/    # 入职管理
│   │   │   ├── Payroll/       # 薪酬管理
│   │   │   └── Settings/      # 系统设置
│   │   ├── api/               # API 调用
│   │   ├── router/            # 路由配置
│   │   └── types/             # TypeScript 类型
│   ├── package.json           # Node 依赖
│   └── vite.config.ts         # Vite 配置
├── desktop-client/            # 桌面客户端
│   ├── requirements.txt       # Python 依赖
│   └── src/main.py           # 客户端入口
└── docs/                      # 项目文档
    ├── AGENT_S2_INTEGRATION.md
    ├── GUI_AGENTS_CORE.md
    ├── DIAGRAMS.md
    └── MODULE_UPDATE.md
```

## 快速开始

### 环境要求

| 依赖项 | 最低版本 | 说明 |
|--------|----------|------|
| Python | 3.10+ | 推荐 3.11 |
| Node.js | 18+ | 前端构建 |
| Git | 2.0+ | 版本控制 |
| Redis | 6.0+ | 可选，任务队列 |

### 步骤 1：安装后端依赖

```bash
cd backend

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install chromium
```

### 步骤 2：安装 Simular Agent-S

```bash
# 安装 gui-agents 包
pip install gui-agents

# 验证安装
python -c "from gui_agents import AgentS; print('Agent-S 安装成功')"
```

### 步骤 3：配置 API 密钥

创建 `backend/.env` 文件：

```env
# LLM API 配置（至少一个）
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-key

# UI-TARS 模型配置
HF_TOKEN=hf-your-huggingface-token
GROUNDING_URL=http://localhost:8080
GROUNDING_MODEL=ui-tars-1.5-7b

# 屏幕分辨率
GROUNDING_WIDTH=1920
GROUNDING_HEIGHT=1080
```

**可选：使用 Claude 替代 OpenAI**

```env
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
```

### 步骤 4：设置 UI-TARS 模型

**方式一：使用 HuggingFace 推理 API（推荐）**

默认配置已指向 HF 推理端点，仅需配置 `HF_TOKEN` 即可。

**方式二：本地部署 UI-TARS**

```bash
# 启动 Flask 服务
python -m ui_tars_server --model-path UI-TARS/ui-tars-1.5-7b --port 8080

# 或使用 vLLM 加速（需要 GPU）
python -m ui_tars_server --model-path UI-TARS/ui-tars-1.5-7b --port 8080 --backend vllm
```

### 步骤 5：启动服务

**终端 1：启动后端**

```bash
cd backend
python main.py
```

**终端 2：启动前端**

```bash
cd frontend
npm install
npm run dev
```

**终端 3：启动桌面客户端（可选）**

```bash
cd desktop-client
pip install -r requirements.txt
python src/main.py
```

**终端 4：启动 Redis（可选）**

```bash
redis-server
```

### 访问应用

- **Web 管理界面**：http://localhost:5173
- **后端 API**：http://localhost:8000
- **API 文档**：http://localhost:8000/docs

## 使用方式

### 方式一：传统自动化

通过录制或手动配置创建工作流，执行预定义操作序列。

```python
# 创建工作流
workflow = Workflow(
    name="招聘流程",
    steps=[
        WorkflowStep(type=StepType.BROWSER_NAVIGATE, config={"url": "https://www.zhipin.com"}),
        WorkflowStep(type=StepType.BROWSER_CLICK, config={"selector": ".job-btn"}),
        WorkflowStep(type=StepType.BROWSER_FILL, config={"selector": "#job-title", "value": "Python工程师"}),
    ]
)

# 执行工作流
engine.execute(workflow)
```

### 方式二：AI 自然语言指令

使用 Agent-S 理解和执行自然语言任务。

```python
# 初始化 Agent
agent = SimularAgentS2(
    openai_api_key="sk-xxx",
    grounding_url="http://localhost:8080"
)

# 执行自然语言指令
result = await agent.execute_instruction(
    "在Boss直聘上发布一个Python工程师职位，要求3年以上经验，熟悉Django和Vue"
)

# 自动解析简历
resume_info = await agent.parse_resume("/path/to/resume.pdf")
```

### 方式三：混合工作流

结合传统步骤和 AI 智能步骤，处理复杂流程。

```python
workflow = Workflow(
    name="混合工作流示例",
    steps=[
        # 传统步骤：导航
        WorkflowStep(type=StepType.BROWSER_NAVIGATE, config={"url": "https://portal.company.com"}),
        # AI 步骤：智能填写复杂表单
        WorkflowStep(
            type=StepType.AGENT_INSTRUCTION,
            config={
                "instruction": "填写入职信息表单，包括姓名、身份证、手机号，选择技术部门",
                "agent_type": "agent_s2"
            }
        ),
        # 传统步骤：确认提交
        WorkflowStep(type=StepType.BROWSER_CLICK, config={"selector": "#submit-btn"}),
    ]
)
```

## 核心接口

### Agent 控制

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/agent/status` | GET | 获取 Agent 状态 |
| `/api/v1/agent/control` | POST | 控制 Agent 执行 |
| `/api/v1/agent/screenshot` | GET | 获取当前屏幕截图 |
| `/api/v1/agent/ws` | WebSocket | 实时状态推送 |

### 招聘管理

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/recruitment/jobs/post` | POST | 发布职位 |
| `/api/v1/recruitment/candidates/parse-resume` | POST | 解析简历 |
| `/api/v1/recruitment/candidates` | GET | 候选人列表 |

### 入职管理

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/onboarding/employees` | POST | 创建员工 |
| `/api/v1/onboarding/employees/{id}/parse-id-card` | POST | 身份证识别 |
| `/api/v1/onboarding/employees/{id}/create-accounts` | POST | 创建系统账号 |

### 薪酬管理

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/payroll/attendance/export` | POST | 导出考勤 |
| `/api/v1/payroll/calculate` | POST | 计算薪资 |
| `/api/v1/payroll/history` | GET | 薪资历史 |

## 安全特性

⚠️ **安全警告**：本系统涉及敏感数据处理和自动化操作，请务必注意以下安全事项。

### 🔒 本地安全架构

- **API 密钥保护**：密钥存储在本地 `.env` 文件，不上传至代码仓库
- **数据本地化**：所有数据处理在本地执行，不依赖外部云服务
- **沙箱执行**：Agent-S 支持本地代码执行（LocalEnv），需谨慎配置
- **操作审计**：完整记录所有自动化操作，支持追溯和审计

### ⚠️ 注意事项

1. **API 密钥安全**：切勿将包含密钥的 `.env` 文件提交到版本控制系统
2. **网络隔离**：生产环境建议配置网络隔离，限制 Agent 可访问范围
3. **人工监督**：关键操作建议启用人工确认机制
4. **权限控制**：遵循最小权限原则，仅授予必要系统权限

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `No module named 'gui_agents'` | Agent-S 未安装 | 执行 `pip install gui-agents` |
| `OPENAI_API_KEY not found` | 缺少环境变量 | 检查 `.env` 文件配置 |
| UI-TARS 连接失败 | 服务未启动 | 启动 UI-TARS 服务 |
| Playwright 浏览器未找到 | 浏览器未安装 | 执行 `playwright install chromium` |
| 权限被拒绝（Windows） | 权限不足 | 以管理员身份运行 |

### 测试安装

```python
# 测试 Agent-S 基本功能
python -c "
from gui_agents import AgentS
print('✓ Agent-S 模块导入成功')

import os
from backend.config import settings
print('✓ 配置加载成功')
print(f'  - LLM 提供商: {settings.LLM_PROVIDER}')
print(f'  - 接地模型: {settings.GROUNDING_MODEL}')
"
```

## 文档资源

| 文档 | 说明 |
|------|------|
| [INSTALL.md](./backend/INSTALL.md) | 详细安装指南 |
| [AGENT_S2_INTEGRATION.md](./docs/AGENT_S2_INTEGRATION.md) | Agent-S 集成说明 |
| [GUI_AGENTS_CORE.md](./docs/GUI_AGENTS_CORE.md) | GUI-Agents 核心功能 |
| [DIAGRAMS.md](./docs/DIAGRAMS.md) | 架构与流程图 |
| [MODULE_UPDATE.md](./docs/MODULE_UPDATE.md) | 模块更新说明 |

## 许可证

本项目采用 **MIT 许可证**。

## 贡献指南

欢迎贡献代码或文档，请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 贡献说明

1. **Agent-S 集成要求**：确保理解 GUI-Agents 工作原理
2. **安全注意事项**：涉及敏感数据处理需谨慎
3. **性能优化建议**：考虑大规模数据场景下的性能表现
4. **模块更新说明**：更新文档以反映代码变更

---

**⚡ 高效办公 · 智能 HR · 让自动化为您服务**