---
name: erhao-hr
description: "二号人事部 MCP 连接器使用说明：权限语义、MCP 返回形态、数据口径与场景路由；覆盖人事、组织、考勤、薪酬四域共 78 个工具。"
description_zh: "二号人事部连接器（MCP）：先读本技能了解权限语义、返回形态与数据口径，再按域技能查询人事/组织/考勤/薪酬数据。"
description_en: "Erhao HR connector (MCP): read this skill first for permission semantics, response shape and data conventions, then use the domain skills for HR, organization, attendance and payroll data."
version: 0.1.9
author: 二号人事部
---

# 二号人事部 · 连接器总览

> 本技能只讲**机制、口径与路由**，不列工具参数表；每个工具的参数以 `tools/list` 返回的 Schema 为准。

## 1. 这是什么

本连接器通过 **MCP** 接入二号人事部，覆盖**人事 / 组织 / 考勤 / 薪酬**四域共 78 个工具。

- 用户在连接表单字段 **`ERHAO_HR_KEY`** 中填写**智能分身 Key**；客户端把它注入请求头 **`X-HR-KEY`** 发起调用。
- 网关用该 Key 换取业务 Token 与**接口白名单**，白名单决定你能看到与能调用哪些工具。
- 凭证只存在于本地与网关链路中，任何文档、日志、回复都不得出现 Key 明文。

## 2. 权限语义（实际行为）

- `tools/list` 按当前 Key 的白名单**动态裁剪**——未授权的工具不会出现在列表里。
- 调用**未授权工具**与调用**不存在的工具**返回**同一条** `工具不可用`：实现刻意不区分二者，避免暴露权限结构；不要据此推断「工具不存在」。
- **换企业 = 换 Key**：Key 归属决定接口白名单，切换企业必须重新填写对应企业的 Key。
- 调用前先看 `tools/list` 确认目标工具可用；不在列表中的工具不要尝试拼参数调用。

## 3. 已知限制（务必先读）

- 白名单为**完整路径精确匹配**（含 `?action=` / `?type=` 等身份 query）：**表头类工具**与**异动类型/原因**按各自参数**独立授权**，授权其中一个**不等于**另一个可用——不要因为某个表头工具可用，就假定同族的其他表头工具也能调用。

## 4. 返回与分页

- **成功**：工具**直接返回业务数据 JSON**——不含 `success` 包裹、也不含任何请求 ID 字段；不要去解析信封，直接读返回体里的字段。
- **返回体是工具的领域模型本身**：某些模型的字段里自带名为 `data` 的成员（如薪酬表头类工具），那是**业务数据**，不是 REST 式信封——照常按字段读取即可。
- **失败**：返回 `isError` + 文本说明，文本形如 `工具不可用`、`工具参数不合法：…`（附带具体字段）或上游错误原文。
- **分页**：分页返回体含 `p` / `limit` / `offset` / `total_count` / `totalpage` / `objects`。需要全量时按 `totalpage` 边界循环递增 `p` 逐页拉取，直到取满 `totalpage` 页为止。

## 5. 数据口径

- 枚举一律查 `references/data-dictionary.md`（生成物，勿手改）；跨源差异见 `references/enum-conflicts.md`。
- **在职三态的码值就是 `1、2、3`**（试用=1、正式=2、待离职=3），等价于「公司全部在职」。
- 接口聚合值 `6` 一律**不使用**：实测其与显式三态的结果集不等价（35 ≠ 40 人），只认 `1、2、3`。
- **默认查询口径**（用户未指定时直接按默认执行，**禁止反问用户范围**）：
  - 时间：全部时间（人力指标月报/季报默认当月）；
  - 人员：公司全部在职；主题为「离职」时改为已离职；
  - 用工类型：全部；用户显式指定时按指定值；
  - 组织：全公司；字段：全部。
- **多值参数**在 MCP 侧传 **JSON 数组**；多值 id 串传**逗号分隔字符串**。

## 6. 场景路由

| 用户意图 | 使用的域技能 |
|---|---|
| 组织架构、部门/公司范围定位、组织盘点 | `erhao-hr-org` |
| 维度分布统计（按 性别/年龄/职级… 计数） | `erhao-hr-employee` |
| 花名册、异动、合同、15 个多列表域 | `erhao-hr-employee` |
| 考勤、假期、加班、排班 | `erhao-hr-attendance` |
| 薪资核算、成本分摊、个税 | `erhao-hr-salary` |

先读本技能拿到机制与口径，再进对应域技能挑工具。

## 7. 错误恢复

| 现象 | 处理 |
|---|---|
| `tools/list` 为空，或调用返回 `isError` | 认证失效：引导用户重新连接连接器 / 重新填写 Key |
| 目标工具不在 `tools/list` 中 | 未授权：引导用户到 ucenter 检查该 Key 的接口白名单 |
| `工具参数不合法：…` | 按 `tools/list` 返回的 Schema 修正参数后重试 |
| 上游错误 | 单次重试；仍失败则报告上游原文并停止 |

## 8. 铁律

1. 禁止编造数据：一切数据必须来自工具真实返回，不得凭经验补全。
2. 禁止凭姓名 / 部门名直调需要 ID 的工具：先用 `orgs_department_tree` 或搜索类工具确认 ID。
3. 工具失败最多重试一次；仍失败即报告并停止，不要反复重试。
4. 不打印智能分身 Key 明文（表单字段 `${ERHAO_HR_KEY}` 只允许作为占位符出现）。