Viy1204 飞书花名册实时提取
把飞书人事(标准版)的员工花名册实时拉成结构化的 Excel + JSON，作为后续一切人员相关分析的权威数据源。
这个 skill 解决什么
本地导出的花名册 xlsx 会过期（文件名带的是导出那一刻的时间戳）。权威且永远最新的数据源是飞书人事(标准版)的
ehr/v1/employees 接口——它就是飞书后台「花名册」页那个导出按钮背后的 API，能拿到通讯录拿不到的
入职日期、人员类型、转正日期、试用期。做组织盘点、算奖金/绩效、核对人员异动时，先用本 skill 拉一份当下的
花名册，再叠加业务数据。
⚠️ 薪资不在此接口（敏感字段，飞书人事 OpenAPI 不返回）。需要月薪折算金额时，请用户另给薪资表。
前置检查
lark-cli auth status确认已登录（部门名映射用的是 user 身份）。- 应用（bot）需开通
ehr:employee:readonly，否则拉花名册会报app_scope_not_applied——去开发者后台开通即可， bot scope 点开即生效，无需重新 auth login。 - 部门名映射走通讯录
contact:department.base:readonly（user 身份）。缺这个 scope 脚本不报错，只是「部门」列 回退成 department_id。 - 装好
openpyxl（pip install openpyxl）用于导出 Excel。
| 调用 | 身份 | scope |
|---|---|---|
ehr/v1/employees（花名册主体） |
--as bot |
ehr:employee:readonly |
contact/v3/departments（部门名映射） |
--as user |
contact:department.base:readonly |
用法
直接跑脚本（已把 Windows/MSYS 路径、相对路径、分页、双身份等坑全部踩平）：
# 默认拉在职(status=2)全部人员，导出 Excel + JSON
python scripts/pull_roster.py --out-dir ./roster
# 含离职/待入职等全部状态
python scripts/pull_roster.py --out-dir ./roster --status 1,2,3,4,5
# 自定义 Excel 文件名
python scripts/pull_roster.py --out-dir ./roster --xlsx-name "花名册_最新.xlsx"
产出：
roster.json—— 结构化数据（含pulled_at时间戳、count、rows），后续脚本直接读它花名册_<日期>.xlsx—— 实习生行标黄，冻结首行，列宽已调
跑完把人数、人员类型分布、Excel 路径报给用户。需要按部门/入职时间筛选或交叉其他数据时，读 roster.json 用
Python 处理，不要重复调 API。
字段与枚举
roster.json 每行字段：姓名 / 工号 / 人员类型 / 在职状态 / 入职日期 / 转正日期 / 试用期(月) / 部门 / 职务 /
职级 / 工作地点 / 直属上级 / 手机 / 邮箱。
- 人员类型：1 正式 / 2 实习 / 3 顾问 / 4 外包 / 5 临时
- 在职状态：1 待入职 / 2 在职 / 3 取消入职 / 4 待离职 / 5 离职
典型用法
- 判断是否转正 / 还在试用期：拿该人
转正日期和当天比较——转正日期在未来＝仍在试用期。这是判断奖金参与 资格、转正提醒等的客观依据。 - 最近入职：按
入职日期排序，或筛--status 1,2。 - 某部门有谁：读
roster.json按「部门」过滤。 - 人员异动核对：和上一次的
roster.json对比工号集合，找出新增 / 离开。
不适用（走别的 skill）
- 只想按姓名 / 邮箱查某个人的部门、open_id、联系方式 →
lark-contact。 - 把部门层级 / 汇报关系画成组织架构图 →
feishu-org-chart。 - 要薪资数据 → 本接口不返回，需用户另给薪资表。
实现说明（脚本已处理，了解即可）
- ehr 接口用 tenant_access_token，必须
--as bot。 - Git Bash(MSYS) 会把
/open-apis/...篡改成 Windows 路径导致 404 —— 脚本在子进程环境强制MSYS_NO_PATHCONV=1。 - lark-cli
--params @file只认 cwd 内的相对路径 —— 脚本把参数文件写进 out-dir 并以 cwd=out-dir 调用。 --page-all的进度行会混进 stdout —— 解析时从首个{截断。