SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场feishu-cli-attendance

feishu-cli-attendance

办公与效率

查看项目

更新于 10-16 01:56

技能介绍

用途

本技能用于通过 feishu-cli attendance（别名 att）查询飞书考勤数据，对接飞书考勤 OpenAPI，覆盖「打卡记录查询」与「考勤统计查询」两个接口。

主要能力

  1. user-task query：查询用户打卡任务/班次记录，底层走 POST /open-apis/attendance/v1/user_tasks/query，返回上下班实际打卡结果，可选包含加班班段。
  2. user-stats query：查询考勤统计数据，底层走 POST /open-apis/attendance/v1/user_stats_datas/query，返回出勤/迟到/早退/请假等聚合统计字段（如出勤天数、迟到次数、加班时长等）。

使用方式

前置条件

  • 安装 feishu-cli（安装方式见 riba2534/feishu-cli）。
  • 全部命令走 tenant_access_token（应用身份），无需 feishu-cli auth login。
  • 需配置 FEISHU_APP_ID + FEISHU_APP_SECRET（环境变量或 ~/.feishu-cli/config.yaml）。
  • 权限通过飞书开放平台「应用权限管理」页面授予应用：attendance:task:readonly（推荐，仅查询）或 attendance:task（含写入）。

命令示例

查询打卡记录：

feishu-cli attendance user-task query
--employee-type <type> --user-ids <ids>
--start <date> --end <date> [选项]

查询考勤统计：

feishu-cli attendance user-stats query
--employee-type <type> --user-ids <ids> --current-user-id <id>
--stats-type <daily|month> --start <date> --end <date> [选项]

关键参数

user-task query：--employee-type（employee_id 默认 / open_id / user_id / employee_no）、--user-ids（CSV，最多 50 个）、--start、--end、--need-overtime（默认 false）、--ignore-invalid-users（默认 true）、--include-terminated（默认 false）、-o/--output（text 默认 / json）。

user-stats query：--employee-type、--stats-type（daily 默认 / month）、--user-ids（最多 200 个）、--current-user-id（新系统用户必填）、--start、--end（跨度 ≤ 31 天）、--locale（zh/en/ja）、--need-history（默认 false）、--current-group-only（默认 false）、-o/--output。

日期格式

接受 YYYY-MM-DD 或 YYYYMMDD 两种写法，CLI 内部统一转为 OpenAPI 要求的 yyyyMMdd 整数。

输出

文本模式输出打卡任务或统计字段的可读列表，并提示无效/无权限用户 ID；JSON 模式直出归一化结构体（AttendanceQueryUserTaskResult / AttendanceQueryUserStatsResult），便于 AI Agent 与脚本消费。

适用场景

  • 查询本人或指定用户某时间段的打卡记录。
  • 查询多人打卡记录并包含加班班段。
  • 查询日度或月度考勤统计（出勤、迟到、早退、请假等）。
  • 需要以 JSON 结构供脚本或 AI Agent 消费的考勤数据查询。

限制

  • 仅支持 Tenant Token：larksuite/oapi-sdk-go v3.5.3 中 Attendance.UserTask.Query 与 Attendance.UserStatsData.Query 的 SupportedAccessTokenTypes 仅含 Tenant，传入 User Access Token 会被 SDK 直接拒绝。
  • user-stats query 起止跨度 ≤ 31 天，超出本地直接拒绝（不发请求）；user-task query 无 31 天跨度限制，但仍受 50 用户上限约束。
  • user-task 单次最多 50 个用户，user-stats 单次最多 200 个用户。
  • 本模块只覆盖「查询」两个接口，不包含排班/班次/考勤组管理、审批假勤、补卡/手动打卡、查考勤组成员及任何写操作。
  • 权限需在飞书开放平台开通后应用重新发布版本才生效；考勤数据涉及员工隐私，企业管理员通常要求审批后放权。

常见错误

  • unsupported access token type, only support: Tenant：误传 User Token，移除 --user-access-token / FEISHU_USER_ACCESS_TOKEN。
  • 用户数超限：user-task ≤ 50，user-stats ≤ 200，超出请分批。
  • 跨度超 31 天：仅 user-stats 有此本地预校验，拆成多次查询。
  • 日期格式错误：使用 YYYY-MM-DD 或纯 8 位数字 YYYYMMDD。
  • 99991663 / attendance:task 权限错误：申请 attendance:task:readonly 并发布新版本。
  • current_user_id is invalid：新系统用户需补上 --current-user-id，值与 user-ids 中目标用户保持同源。
  • invalid_user_ids / unauthorized_user_ids 非空：核对 user-id 类型与应用可见范围设置。