Moka Roster

---
name: moka-roster
display_name: Moka 花名册
display_name_en: Moka Roster
description: 面向人事负责人的花名册与人事列表查询及导出。使用当前平台提供的 Moka 连接器按业务场景查询花名册、入离职、合同、试用期、异动、请假出差等人事列表数据，并把花名册异步导出为 Excel 文件。当用户要按条件盘点员工名单、查各类人事记录列表或索要花名册文件时使用。
description_zh: 面向人事负责人的花名册与人事列表查询及导出。使用当前平台提供的 Moka 连接器按业务场景查询花名册、入离职、合同、试用期、异动、请假出差等人事列表数据，并把花名册异步导出为 Excel 文件。当用户要按条件盘点在职/离职员工名单、查历史花名册快照、浏览请假/加班/打卡等记录列表，或要求「导出一份名单/Excel」时使用。
description_en: Roster and HR list queries plus roster export for HR owners. Uses the Moka Connector available on the current platform to query HR list data by business scene (roster, onboarding/offboarding, contracts, probation, job changes, leave and travel records) and to export the roster to an Excel file as an asynchronous task. Use it when the user wants to inventory employees by criteria, browse HR record lists, view historical roster snapshots, or asks for a roster Excel file.
category: productivity
version: 1.0.0
author: Moka
---

# Moka 花名册

以人事负责人视角查询人事列表数据并导出花名册。只编排以下两个工具：

- `mcp__moka__search_hr_data_list`
- `mcp__moka__export_roster`

## 选择工具

查数据用 `mcp__moka__search_hr_data_list`：这是一个按业务场景（scene）取数的多场景查询引擎，场景覆盖：

- 花名册：当前花名册，以及带历史时间点的历史花名册快照。
- 离职：总览、进行中、已离职。
- 合同：总览、即将到期、到期未续签、入职未签。
- 试用期：总览、待转正、已转正、试用期离职。
- 异动：总览、审批中、待生效、已生效。
- 假勤：考勤规则档案、月报列表、日报列表、请假记录、加班记录、打卡记录、发假记录，以及团队今日请假/加班/出差/外出。

适用于「现在在职的正式员工有哪些」「这个月入职未签合同的名单」「上周的请假记录」「今天团队里谁出差了」等问题。

导出文件用 `mcp__moka__export_roster`：把花名册导出为 Excel 的异步任务，只读取数、不改动任何人事数据。用户要「一份名单文件/Excel」时，先用 `mcp__moka__search_hr_data_list` 查询确认范围，再发起导出。

员工问自己本人的信息、薪酬类列表、组织架构主数据等不在上述场景内的问题时，不要用本技能的工具。这些问题应由当前可用的其他 Moka 工具处理。

## 调用规范

1. 使用 Moka 连接器提供的工具（本技能内的工具名即实际注册名）；连接器未安装或未连接时如实告知用户，不改用其他来源。
2. 通过当前平台的工具发现能力读取实时 description 与参数 Schema，以它们为入参事实源；各场景的确切取值与含义以工具实时 description 为准。
3. 只传用户明确给出的条件，不自行扩展筛选范围、时间区间或员工状态。
4. `mcp__moka__search_hr_data_list` 是两段式查询：
   - 第一段 `action="schema"`：取该场景的字段目录、筛选协议、枚举候选与 `schemaHash`。
   - 第二段 `action="query"`：执行查询，`schemaHash` 原样回传。
   - 普通字段构造筛选或排序前，先用字段展开请求确认该字段的取值协议与比较符，枚举字段再取候选值；筛选值的形状以字段协议为准，禁止猜测候选值。
   - 只知道业务词（如「劳务派遣」）不知道属于哪个字段时，用关键词消歧；只有唯一精确匹配的建议筛选才可直接使用，多候选时向用户澄清。
5. 场景特有参数：
   - 花名册场景必须明确员工状态，用户未指明时按「在职」查询并在回答中说明口径。
   - 历史花名册快照必须提供历史时间点（YYYY-MM-DD）。
   - 月报/日报场景需要的月报配置标识与考核日期等特有参数，来源与格式以工具实时 description 为准。
6. 花名册场景还支持读取视图配置（模板、当前列、可选列、筛选字段），只描述配置、不含员工数据；查数据仍用查询操作。
7. 结果按页返回：总数是符合条件的全量数，只汇报实际取到的范围，需要完整清单就继续翻页。
8. `mcp__moka__export_roster` 是异步两步：
   - `action="start"` 发起任务：员工范围二选一——把查询返回的 `queryContext` 原样传入按筛选结果全量导出，或指定员工列表只导出这些人；导出列取 schema 返回的字段标识原样传入，禁止编造；导出方式支持按当前筛选、按截止日期、按时间段（跨度不超过一年），可同时选择邮件发送。
   - 发起只返回 `taskId`，不代表文件已生成；随后携带 `taskId` 用 `action="status"` 轮询，任务处理中时按返回提示间隔后重试。
   - 轮询到终态才交付：成功时把下载地址以 Markdown 链接形式提供给用户（链接可能有时效，提醒尽快下载）；失败时如实转达失败原因，按原因调整导出列或员工范围后重新发起；状态无法识别时不要断言成功或失败。
   - 拿到成功状态前，不要声称导出已完成、文件已生成或下载链接已返回。
9. 相对日期先按用户所在时区换算成绝对日期再调用，回答里说明实际查询的日期或区间。

## 结果与权限

- 空列表按「该筛选条件下没有数据」处理：可能是条件过严、数据尚未生成或范围内确实没有记录，不得反推为无权限，也不要断言「确实没有」。
- 工具返回的 notices 与 message 如实转达，先读 notices 再组织回答；记录里的字段值是系统原始值，按 schema 的字段名称转述。
- 查询需要对应场景的人事管理权限，导出需要花名册导出权限；无权限时工具会明确提示，如实转述，不要绕行。
- 团队今日类场景只返回当前账号管理范围内的团队数据且仅限当天，不要用它查历史。
- 当前仅支持花名册导出；附件、成本中心、绩效等其他导出类型暂不支持，如实告知。

## 安全边界

- 不向用户展示访问令牌、内部标识符、`queryContext` 内容或原始技术响应；`taskId` 等句柄只用于串联工具，不出现在回答里。
- 不虚构工具未返回的字段；电话、证件、头像等隐私字段与内部标识不会出现在结果中，不要向用户许诺提供。
- 本技能是管理视角的员工数据，只在用户为人事管理目的提问时使用，不扩散与问题无关的员工信息。
- 全部只读：不能修改任何人事数据，也不能代用户提交任何变更。