hr-ai-assistant
# HR AI Assistant Skill
## Purpose
This skill enables WorkBuddy to directly call the HRrule AI platform's WebSocket API to generate HR-related content in real-time. When users request HR policies, forms, consultation, professional Q&A, or other HR documents, this skill automatically invokes the API with appropriate parameters and streams the response back to the user. The skill supports:
1. **Document Generation**: Creating HR policies, forms, job descriptions, performance reviews, etc.
2. **Professional Q&A**: Answering HR-related questions about labor laws, employee rights, compensation, contracts, etc.
3. **Real-time Streaming**: Providing immediate feedback with streaming responses
## When to Use This Skill
Use this skill when users ask questions or make requests related to:
- **HR Policy Generation**: Creating employee handbooks, attendance policies, leave policies, disciplinary procedures, compensation policies
- **HR Form Creation**: Generating onboarding forms, resignation forms, leave application forms, performance review forms
- **HR Consultation**: Asking questions about labor laws, employment contracts, recruitment processes, compensation and benefits
- **HR Process Flowcharts**: Creating visual representations of HR processes like recruitment workflows, onboarding processes
- **HR Documentation**: Writing reports, summaries, guidelines, and other HR-related documents
- **Professional Q&A**: Any HR-related questions requiring professional answers, such as labor law inquiries, employee rights, compensation, contract issues, leave policies, etc.
Key phrases that indicate this skill should be triggered include:
- "帮我写一个员工手册"
- "生成HR制度"
- "制作入职表单"
- "HR相关问题"
- "劳动法咨询"
- "招聘流程"
- "薪酬制度"
- "离职手续"
- "考勤制度"
- "绩效考核"
- "员工福利"
- "劳动合同"
- "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD"
- "三期员工有没有特殊保障？"
- "Generate HR policy"
- "Create HR form"
- "HR consultation"
- "Labor law questions"
## How This Skill Works
### Direct API Integration
This skill provides a Python script that interacts with the HRrule AI WebSocket API to generate content.
**Integration Options**:
1. **Analyze User Request**: Parse the user's HR request to identify the content type
2. **Check API Key**: Verify API Key is configured (from env var or config.json)
- **If API Key is missing**: Display a friendly prompt to visit https://ai.hrrule.com/ for a free API Key
- **If API Key is valid**: Proceed with API call
3. **Select Parameters**: Automatically select appropriate `tag_id` and `rt` based on the request
4. **Call API**: The platform may execute the Python script to make the API call:
```bash
python ~/.workbuddy/skills/hr-ai-assistant/scripts/call_hrrule_api.py \
--content "用户的问题" \
--tag-id 1 \
--rt "专业问答"
```
5. **Stream Response**: Stream the generated content back to the user in real-time
6. **Handle Errors**: Gracefully handle connection errors, timeouts, and API errors
**Note**: The platform should ensure safe script execution environments and validate all inputs.
Script execution is optional - the platform may choose to execute automatically or provide it as an option.
### ⚠️ Important: First-Time User Experience (首次使用体验)
When a user uses this skill for the first time without an API Key configured:
1. **Display Friendly Prompt**:
```
══════════════════════════════════════════════════════════════════════════════
📌 首次使用 HR AI Assistant
══════════════════════════════════════════════════════════════════════════════
✨ 获取免费 API Key 以获得更专业的 HR AI 服务：
1. 访问: https://ai.hrrule.com/
2. 注册/登录账号
3. 在个人中心申请 API Key
4. **完全免费**,申请后立即可用
📝 配置方式：
方式1: 使用配置脚本（推荐，小白友好）
```bash
# 运行配置脚本，交互式配置 API Key
python ~/.workbuddy/skills/hr-ai-assistant/scripts/config_api_key.py
```
配置脚本会：
- 自动检测 API Key 格式
- 支持粘贴完整文本（会自动提取）
- 保存到配置文件
- 显示当前配置状态
方式2: 手动配置
设置环境变量: export HRRULE_API_KEY='your-api-key'
或编辑配置文件: ~/.workbuddy/skills/hr-ai-assistant/config.json
内容: {"api_key": "your-api-key"}
══════════════════════════════════════════════════════════════════════════════
```
2. **Then proceed to answer using the platform's general AI model** (WorkBuddy/OpenClaw's default model)
**Example workflow**:
```
User: "三期员工有没有特殊保障？"
System detection:
→ HR AI Assistant skill needed
→ No API Key configured
→ DISPLAY THE PROMPT ABOVE
System: [显示上述提示信息]
System: [使用通用大模型回答问题]
User: "我申请到了 API Key，怎么配置？"
System: 请运行配置脚本：
python ~/.workbuddy/skills/hr-ai-assistant/scripts/config_api_key.py
```
**NOTE**: The prompt should be displayed BEFORE answering the question.
### Tag ID and RT Parameter Mapping
The skill automatically maps user requests to the appropriate parameters:
**Tag ID: 1 (专业问答 - Professional Q&A)**
- **通用 HR 咨询**：劳动法问题、员工权益、薪酬福利、劳动合同、离职补偿、加班工资、试用期规定等任何 HR 相关的专业问答
- **示例问题**：
- "三期员工有没有特殊保障？"
- "员工离职需要提前多少天通知？"
- "试用期工资可以低于转正工资多少？"
- "加班费怎么计算？"
- "员工旷工怎么处理？"
- "未签订劳动合同有什么后果？"
- "竞业限制补偿金标准是多少？"
**Tag ID: 2 (制度类 - HR Policies)**
- 员工手册, 招聘管理制度, 入职试用期管理制度, 劳动合同管理制度, 薪酬管理制度, 考勤休假制度, 加班管理制度, 绩效管理制度, 员工培训制度, 离职管理制度, 员工竞聘制度, 病假管理制度, 奖惩制度, 其他制度
**Tag ID: 7 (岗位类 - Job Descriptions)**
- 岗位说明书, 工作饱和度评估表, 任职资格标准, 职位图谱
**Tag ID: 3 (绩效类 - Performance Management)**
- 360考核表, BSC考核表, KPI考核表, OKR考核表, 绩效承诺书, 绩效改进计划, 绩效面谈表, 绩效诊断报告
**Tag ID: 4 (招聘类 - Recruitment)**
- 人才画像, 面试评估表, 面试题库, 招聘需求表, 招聘JD, 背景调查表, 录用条件说明书, 录用通知书, 入职承诺书, 劳动合同
**Tag ID: 5 (薪酬类 - Compensation)**
- 薪酬等级表, 薪酬面谈表, 薪酬诊断报告, 岗位价值评估表
**Tag ID: 8 (培训类 - Training)**
- 新员工培训计划, 年度培训计划
**Tag ID: 13 (报告类 - Reports)**
- 年终总结, 月度报告, 周报, 日报
**Tag ID: 14 (风控类 - Risk Management)**
- 风险自测
## Usage Workflow
### Step 1: Parse User Request
Analyze the user's request to determine:
- **Content Type**: What type of HR content they need
- **Tag ID**: The appropriate content category
- **RT**: The specific resource type
- **Details**: Any specific requirements or constraints
**Example Request Analysis:**
Request: "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD"
Analysis:
- Content Type: 招聘JD (Job Description)
- Tag ID: 4 (招聘类)
- RT: "招聘JD"
- Details: 财务公司, 社保专员岗位
### Step 2: Select Parameters
Based on the analysis, select the parameters:
```python
tag_id = 4
rt = "招聘JD"
content = "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD"
```
### Step 3: Call API Using Python Script
Use the bundled script to call the API:
```python
import sys
import os
# 获取 skill 目录路径（动态解析）
skill_dir = os.path.join(os.path.expanduser('~'), '.workbuddy', 'skills', 'hr-ai-assistant')
script_dir = os.path.join(skill_dir, 'scripts')
sys.path.insert(0, script_dir)
from call_hrrule_api import call_hrrule_api
# ⚠️ 重要：平台必须直接执行 skill 目录下的脚本，不要新建 Python 文件
async def get_hr_content():
# 调用 API 并流式输出
full_response = await call_hrrule_api(
api_key='your-api-key',
content='财务公司 需要招聘 社保专员，帮我生成一份 招聘JD',
tag_id=4,
rt='招聘JD',
on_chunk=lambda text: print(text, end='', flush=True),
verbose=True
)
return full_response
# 执行调用
import asyncio
response = asyncio.run(get_hr_content())
```
### Step 4: Stream Response to User
Stream the response back to the user in real-time:
```
AI 响应:
职位名称: 社保专员
所属部门: 人力资源部
工作地点: 北京
招聘人数: 1人
职位描述:
我们是一家专业的财务公司,现招聘社保专员...
```
## Parameter Selection Logic
### Automatic Mapping Rules
**Rule 1: Keyword Matching**
| Keyword | Tag ID | RT |
|---------|--------|-----|
| 专业问答/咨询 | 1 | 专业问答 |
| 劳动法问题/咨询 | 1 | 专业问答 |
| 员工权益/权利 | 1 | 专业问答 |
| 离职补偿/赔偿 | 1 | 专业问答 |
| 加班工资/加班费 | 1 | 专业问答 |
| 试用期规定/工资 | 1 | 专业问答 |
| 三期/孕期/产期/哺乳期 | 1 | 专业问答 |
| 竞业限制 | 1 | 专业问答 |
| 经济补偿金/赔偿金 | 1 | 专业问答 |
| 违法解除/终止合同 | 1 | 专业问答 |
| 员工手册 | 2 | 员工手册 |
| 考勤制度 | 2 | 考勤休假制度 |
| 薪酬制度 | 2 | 薪酬管理制度 |
| 岗位说明书 | 7 | 岗位说明书 |
| KPI考核表 | 3 | KPI考核表 |
| 绩效考核表 | 3 | KPI考核表 |
| 绩效改进 | 3 | 绩效改进计划 |
| 面试评估表 | 4 | 面试评估表 |
| 面试题库 | 4 | 面试题库 |
| 招聘JD | 4 | 招聘JD |
| 招聘职位 | 4 | 招聘JD |
| 劳动合同 | 4 | 劳动合同 |
| 录用通知书 | 4 | 录用通知书 |
| 薪酬等级表 | 5 | 薪酬等级表 |
| 薪酬面谈表 | 5 | 薪酬面谈表 |
| 培训计划 | 8 | 新员工培训计划 |
| 年终总结 | 13 | 年终总结 |
| 周报/月报/日报 | 13 | 周报/月度报告/日报 |
| 风险评估 | 14 | 风险自测 |
**Rule 2: Context Analysis**
- If user mentions "招聘" (recruitment) + specific document type → Tag ID: 4
- If user mentions "制度" (policy/system) → Tag ID: 2
- If user mentions "考核" (assessment) → Tag ID: 3
- If user mentions "培训" (training) → Tag ID: 8
- If user mentions "报告" (report) + time period → Tag ID: 13
- If user asks a question about labor laws, employee rights, compensation → Tag ID: 1 (专业问答)
- If user asks "有没有"、"如何"、"怎样"、"为什么"等疑问句 → Tag ID: 1 (专业问答)
**Rule 3: Fallback - Professional Q&A**
If no clear match with specific document types (如员工手册、招聘JD、KPI考核表等), use the general Q&A category:
- Any HR-related question about laws, regulations, policies, employee rights → Tag ID: 1, RT: "专业问答"
- Example: "三期员工有没有特殊保障？", "员工离职需要提前多久通知？"
- Example: "试用期工资规定", "加班费计算方式"
**Rule 4: Default Fallback**
If still unclear, use the safest default:
- HR policy/guidance → Tag ID: 2, RT: "其他制度"
- General HR question → Tag ID: 1, RT: "专业问答"
## Script Usage
### Script Location
**IMPORTANT**: The script is located at:
`~/.workbuddy/skills/hr-ai-assistant/scripts/call_hrrule_api.py`
The platform should dynamically resolve this path using:
```python
import os
skill_dir = os.path.join(os.path.expanduser('~'), '.workbuddy', 'skills', 'hr-ai-assistant')
script_path = os.path.join(skill_dir, 'scripts', 'call_hrrule_api.py')
```
**DO NOT use hardcoded paths like `C:/Users/jikr/...`**
### Function Signature
```python
async def call_hrrule_api(
api_key: str,
content: str,
tag_id: int,
rt: str,
ws_url: str = "ws://192.168.112.114:5000",
model: str = "deepseek-ai/DeepSeek-R1",
on_chunk: Optional[Callable[[str], None]] = None,
on_complete: Optional[Callable[[], None]] = None,
on_error: Optional[Callable[[str], None]] = None,
verbose: bool = False
) -> str
```
### Parameters
- `api_key`: API 密钥(必需)
- `content`: 用户问题或需求(必需)
- `tag_id`: 内容类型 ID(必需)
- `rt`: 资源类型(必需)
- `ws_url`: WebSocket 地址(默认: ws://192.168.112.114:5000)
- `model`: 模型名称(默认: deepseek-ai/DeepSeek-R1)
- `on_chunk`: 收到内容块时的回调函数
- `on_complete`: 完成时的回调函数
- `on_error`: 错误时的回调函数
- `verbose`: 是否显示详细日志
### Return Value
Returns the complete response content as a string.
### Command Line Usage
```bash
python call_hrrule_api.py \
--api-key "your-api-key" \
--content "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD" \
--tag-id 4 \
--rt "招聘JD" \
--verbose
```
## Example Workflows
### Example 1: Generate Job Description (JD)
**User Request:**
```
财务公司 需要招聘 社保专员，帮我生成一份 招聘JD
```
**Skill Execution:**
1. **Parse Request:**
- Identify: "招聘JD" → Tag ID: 4, RT: "招聘JD"
- Extract context: 财务公司, 社保专员
2. **Construct Content:**
```python
content = "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD"
tag_id = 4
rt = "招聘JD"
```
3. **Call API:**
```python
response = await call_hrrule_api(
api_key='your-api-key',
content=content,
tag_id=tag_id,
rt=rt,
on_chunk=lambda text: print(text, end='', flush=True),
verbose=True
)
```
4. **Stream Response:**
The AI response is streamed back in real-time.
### Example 2: Generate Employee Handbook
**User Request:**
```
帮我写一个员工手册,适用于50人的科技公司
```
**Skill Execution:**
1. **Parse Request:**
- Identify: "员工手册" → Tag ID: 2, RT: "员工手册"
- Extract context: 50人, 科技公司
2. **Call API:**
```python
response = await call_hrrule_api(
api_key='your-api-key',
content='帮我写一个员工手册,适用于50人的科技公司',
tag_id=2,
rt='员工手册',
on_chunk=lambda text: print(text, end='', flush=True)
)
```
### Example 3: Create Performance Review Form
**User Request:**
```
为销售部门设计KPI考核表
```
**Skill Execution:**
1. **Parse Request:**
- Identify: "KPI考核表" → Tag ID: 3, RT: "KPI考核表"
- Extract context: 销售部门
2. **Call API:**
```python
response = await call_hrrule_api(
api_key='your-api-key',
content='为销售部门设计KPI考核表',
tag_id=3,
rt='KPI考核表',
on_chunk=lambda text: print(text, end='', flush=True)
)
```
### Example 4: Professional Q&A (Labor Law Question)
**User Request:**
```
三期员工有没有特殊保障？
```
**Skill Execution:**
1. **Parse Request:**
- Identify: Question about labor law/employee rights → Tag ID: 1, RT: "专业问答"
- Extract context: 三期员工 (孕期、产期、哺乳期), 特殊保障
2. **Call API:**
```python
response = await call_hrrule_api(
api_key='your-api-key',
content='三期员工有没有特殊保障？',
tag_id=1,
rt='专业问答',
on_chunk=lambda text: print(text, end='', flush=True),
verbose=True
)
```
3. **Stream Response:**
```
AI 响应:
根据《劳动合同法》和《女职工劳动保护特别规定》，三期员工（孕期、产期、哺乳期）确实享有特殊保障，主要包括：
1. 不得单方面解除劳动合同
- 用人单位不得依据《劳动合同法》第40条、第41条单方面解除合同
- 除非员工有严重违纪等《劳动合同法》第39条规定的情况
2. 孕期保护
- 不得安排从事高强度、有毒有害工作
- 不得延长劳动时间或安排夜班工作
- 孕期7个月以上，每天应安排1小时工间休息
3. 产期保护
- 享有98天产假（难产或多胞胎适当增加）
- 产假期间工资照发
- 生育保险报销医疗费用
4. 哺乳期保护
- 每日享有1小时哺乳时间
- 不得安排有毒有害工作
5. 经济补偿
- 如劳动合同期满，合同自动顺延至三期结束
- 顺延期间不视为续签劳动合同
```
### Example 5: General HR Consultation
**User Request:**
```
员工离职需要提前多少天通知？
```
**Skill Execution:**
1. **Parse Request:**
- Identify: Question about resignation → Tag ID: 1, RT: "专业问答"
- Extract context: 员工离职, 提前通知时间
2. **Call API:**
```python
response = await call_hrrule_api(
api_key='your-api-key',
content='员工离职需要提前多少天通知？',
tag_id=1,
rt='专业问答',
on_chunk=lambda text: print(text, end='', flush=True)
)
```
## Error Handling
The script handles various error scenarios:
### Connection Errors
- Invalid WebSocket URL
- Network connectivity issues
- Firewall blocking
### Authentication Errors
- Invalid API Key
- API Key expired
- Permission denied
### API Errors
- Invalid parameters
- Server errors
- Timeout (120 seconds)
### Error Handling Example
```python
def handle_error(error_msg: str):
print(f"错误: {error_msg}")
# 提供用户友好的错误信息
if "Unauthorized" in error_msg or "401" in error_msg:
print("API Key 无效,请检查您的 API Key")
elif "Connection" in error_msg:
print("连接失败,请检查网络和 WebSocket URL")
else:
print("发生未知错误,请稍后重试")
response = await call_hrrule_api(
api_key='your-api-key',
content='your content',
tag_id=2,
rt='员工手册',
on_error=handle_error,
verbose=True
)
```
## Best Practices
### 1. First-Time User Experience (首次使用体验)
**Note**: 当首次使用此 skill 且未配置 API Key 时，平台（WorkBuddy/OpenClaw）应该：
✅ **推荐做法**：
1. 检测到没有 API Key
2. **先显示**友好的提示信息（访问 https://ai.hrrule.com/ 免费申请）
3. **然后**使用平台的通用大模型回答问题
4. 用户手动配置 API Key（通过环境变量、配置文件或配置脚本）
**应该显示的提示信息**：
```
══════════════════════════════════════════════════════════════════════════════
📌 首次使用 HR AI Assistant
══════════════════════════════════════════════════════════════════════════════
✨ 获取免费 API Key 以获得更专业的 HR AI 服务：
1. 访问: https://ai.hrrule.com/
2. 注册/登录账号
3. 在个人中心申请 API Key
4. **完全免费**,申请后立即可用
📝 配置方式（任选一种）：
方式1: 一键配置（推荐）
把申请到的 API Key 直接粘贴到对话框中，我会自动帮你配置到配置文件
方式2: 手动配置
设置环境变量: export HRRULE_API_KEY='your-api-key'
或编辑配置文件: ~/.workbuddy/skills/hr-ai-assistant/config.json
内容: {"api_key": "your-api-key"}
══════════════════════════════════════════════════════════════════════════════
```
**执行顺序**：
```
1. 用户提问："三期员工有没有特殊保障？"
2. 检测到需要此 skill
3. 检测到没有 API Key
4. ⚠️ 显示上述提示信息 ← 必须在回答前
5. 使用通用大模型回答问题
6. 用户手动配置 API Key（通过环境变量或编辑配置文件）
```
**注意**：用户需要手动配置 API Key（通过环境变量或编辑配置文件），系统不会自动检测或保存。
### 2. Provide Detailed Context
Always include as much context as possible in the `content` parameter:
- Company size and industry
- Specific requirements
- Target audience
- Time constraints
**Good:**
```
财务公司 需要招聘 社保专员，帮我生成一份 招聘JD
要求: 3年以上经验,熟悉社保政策,薪资8-12k
```
**Less Good:**
```
生成招聘JD
```
### 2. Use Streaming for Better UX
Always use the `on_chunk` callback to stream responses:
```python
def stream_text(text: str):
print(text, end='', flush=True)
response = await call_hrrule_api(
# ... parameters
on_chunk=stream_text
)
```
### 3. Handle Errors Gracefully
Always provide error callbacks:
```python
response = await call_hrrule_api(
# ... parameters
on_error=lambda msg: print(f"❌ 错误: {msg}"),
on_complete=lambda: print("\n✅ 完成")
)
```
### 4. Set Appropriate Timeout
The script has a 120-second timeout by default. For complex documents, this is usually sufficient.
## Configuration
### API Key Configuration
The API Key should be configured securely. Options:
1. Environment variable: `HRRULE_API_KEY`
2. Configuration file
3. Direct parameter passing
### WebSocket URL Configuration
Default: `ws://192.168.112.114:5000`
Can be changed via:
- Command line: `--ws-url`
- Script parameter: `ws_url=`
- Configuration file
## Troubleshooting
### Issue: Connection Fails
**Check:**
- WebSocket URL is correct
- Network connectivity
- Firewall settings
- Server is running
### Issue: Authentication Error
**Check:**
- API Key is valid
- API Key has not expired
- API Key has proper permissions
### Issue: No Response
**Check:**
- Content parameter is not empty
- Tag ID and RT are valid
- Network connection is stable
- Server is processing requests
### Issue: Timeout
**Solution:**
- Increase timeout in script
- Simplify the request
- Check server load
## Integration Examples
### DingTalk Integration
When receiving HR requests from DingTalk:
```python
# 收到 DingTalk 消息
message = "财务公司 需要招聘 社保专员，帮我生成一份 招聘JD"
# 调用 skill
import sys
import os
# 获取 skill 目录路径（动态解析）
skill_dir = os.path.join(os.path.expanduser('~'), '.workbuddy', 'skills', 'hr-ai-assistant')
script_dir = os.path.join(skill_dir, 'scripts')
sys.path.insert(0, script_dir)
from call_hrrule_api import call_hrrule_api
# ⚠️ 重要：平台必须直接执行 skill 目录下的脚本，不要新建 Python 文件
async def handle_dingtalk_message(message: str):
# 解析请求
tag_id, rt = parse_request(message) # 4, "招聘JD"
# 调用 API
response = await call_hrrule_api(
api_key=os.getenv('HRRULE_API_KEY'),
content=message,
tag_id=tag_id,
rt=rt,
on_chunk=lambda text: send_to_dingtalk(text) # 实时发送到 DingTalk
)
return response
# 执行
response = asyncio.run(handle_dingtalk_message(message))
```
### QQ Integration
Similar to DingTalk, parse the QQ message and call the API:
```python
async def handle_qq_message(message: str):
# 解析请求
tag_id, rt = parse_request(message)
# 调用 API
response = await call_hrrule_api(
api_key='your-api-key',
content=message,
tag_id=tag_id,
rt=rt,
on_chunk=lambda text: send_to_qq(text)
)
return response
```
## Summary
This skill provides **direct API integration** with the HRrule AI platform, enabling WorkBuddy to:
- Automatically parse HR requests
- Select appropriate parameters (tag_id, rt)
- Call WebSocket API in real-time
- Stream responses back to users
- Handle errors gracefully
The skill is designed for seamless integration with chat platforms like DingTalk and QQ, making it easy to generate HR documents on demand.
## Reference Materials
- API Reference: `references/api_reference.md`
- Example Prompts: `references/example_prompts.md`
- Usage Guide: `README.md`
- Test Page: `assets/chat_example.html`
- Original Test: `test_open_chat.html`
标签
skill
ai
