# Moka Roster

> 面向人事负责人的花名册与人事列表查询及导出。使用当前平台提供的 Moka 连接器按业务场景查询花名册、入离职、合同、试用期、异动、请假出差等人事列表数据，并把花名册异步导出为 Excel 文件。当用户要按条件盘点员工名单、查各类人事记录列表或索要花名册文件时使用。

- Skill: `ahang1598/moka-roster` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ahang1598/moka-roster`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/moka-roster/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/ahang1598/moka-roster

---


# 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` 等句柄只用于串联工具，不出现在回答里。
- 不虚构工具未返回的字段；电话、证件、头像等隐私字段与内部标识不会出现在结果中，不要向用户许诺提供。
- 本技能是管理视角的员工数据，只在用户为人事管理目的提问时使用，不扩散与问题无关的员工信息。
- 全部只读：不能修改任何人事数据，也不能代用户提交任何变更。