feishu-attendance

📊 智能考勤监控与异常报告系统

基于飞书API的自动化考勤监控方案,智能识别异常考勤并推送报告,具备Safe Mode与Dry Run保障,提升企业考勤管理效率。

收藏
13.6k
安装
2.9k
版本
latest
CLS 安全性认证2026-05-16
点击查看完整报告 >

使用说明

核心用法

该Skill是一款基于Node.js的飞书考勤监控工具,通过命令行接口提供灵活的考勤检查能力。基础用法为执行node index.js check进行当日考勤检查,支持--date参数指定任意历史日期(如"2023-10-27"),以及--dry-run参数开启测试模式(仅模拟运行不实际发送消息)。工具通过调用飞书开放平台的官方API获取员工考勤数据,智能识别迟到、早退、缺勤等异常状态,自动生成富文本交互卡片报告发送给管理员,同时可选向员工推送个人异常提醒。

显著优点

该工具在工程设计和安全考量上表现突出:集成timor.tech API自动识别中国大陆节假日与周末,避免在休息日误发通知打扰员工;独创的Safe Mode安全机制在节假日API故障时自动禁用用户通知,有效防止消息轰炸风险;采用本地文件缓存策略(用户列表24小时TTL、节假日数据),既显著提升性能又减少API调用成本;权限申请严格遵循最小化原则,仅申请读取考勤、用户列表和发送消息三项必要权限;完善的输入验证机制支持智能日期解析(如"1.27"自动补全为"2026-01-27"),并支持批量用户ID分块处理(每批50个)。

潜在缺点

作为T3级别(个人开发者GitHub账号)的社区开源项目,其长期维护的稳定性与持续性相比飞书官方或企业级方案存在一定不确定性;功能强依赖第三方节假日API服务(timor.tech),若该服务长期不可用或数据错误,虽会触发Safe Mode,但仍可能影响节假日判断的准确性;目前仅深度适配飞书(Lark)平台,无法迁移至钉钉、企业微信等其他办公系统;本地缓存机制虽提升性能,但员工列表等敏感数据存储在本地文件,需确保服务器文件权限配置得当。

适合目标群体

主要面向已部署飞书办公系统的中小企业HR部门、行政管理人员及团队负责人。特别适合当前依赖人工每日登录飞书后台、手动导出Excel统计考勤异常并逐一通知员工的场景,可将耗时的人工检查流程完全自动化。对于注重数据隐私合规、不愿将考勤数据上传至第三方SaaS平台,希望数据严格保留在企业自有飞书租户内的组织尤为适合。同时适合需要灵活定制考勤规则通知逻辑的技术驱动型团队。

使用风险

使用该Skill需妥善保管飞书应用凭证(FEISHU_APP_ID与FEISHU_APP_SECRET),若环境变量配置不当导致泄露,可能导致企业通讯录及考勤数据被非法访问;依赖外部网络服务(timor.tech节假日接口)存在可用性风险,尽管有Safe Mode兜底,但极端情况下可能影响功能完整性;批量发送消息场景可能触发飞书开放平台API的频率限制;本地缓存文件若服务器权限配置不当,可能导致员工个人信息泄露。建议生产环境部署前务必使用--dry-run参数充分测试验证,并建立定期凭证轮换机制。

安全解读

核心用法

Feishu Attendance Skill 是一款面向飞书(Lark)企业用户的自动化考勤监控工具,专为HR和管理员设计。该工具通过调用飞书开放平台API,每日自动拉取员工考勤数据,智能识别迟到、早退、旷工等异常状态,并向管理员推送结构化报告。

主要功能模块

  • 智能检测引擎:自动判定迟到(Late)、早退(Early Leave)、旷工(Absence)三类异常
  • 节假日感知系统:集成 timor.tech 节假日API,自动跳过法定假日和周末,避免误报
  • 安全降级机制:当节假日API故障时自动启用Safe Mode,暂停员工通知,防止假期轰炸
  • 高性能缓存:用户列表缓存24小时,减少API调用频次;支持按日期查询历史考勤

命令行操作

node index.js check              # 检查今日考勤
node index.js check --date 2023-10-27  # 指定日期查询
node index.js check --dry-run    # 测试模式,只模拟不发送消息

所需权限:attendance:report:readonlycontact:user.employee:readonlyim:message:send_as_bot

显著优点

1. 企业级安全设计:代码通过CLS-Certify v2.1.0全量扫描,静态分析80分、依赖审计85分,无危险函数调用、无硬编码密钥
2. 防误报机制:节假日API+Safe Mode双重保险,避免假期/周末误触员工

3. 运维友好:Dry Run测试模式、清晰的错误日志、合理的超时设置(5秒API超时)

4. 性能优化:双层缓存策略(内存+文件),降低飞书API调用成本

5. 交互体验:向管理员发送富文本交互卡片,异常数据可视化呈现

潜在局限

| 局限点 | 说明 |
|--------|------|
| 第三方API依赖 | 节假日数据依赖 `timor.tech` 非官方服务,存在可用性风险 |
| 缓存路径外置 | 缓存写入 `../../memory/` 目录,需额外配置权限 |
| 外部模块依赖 | 依赖 `../../feishu-common` 相对路径模块,版本管理复杂 |
| 功能单一 | 仅支持查询统计,不支持考勤规则配置、审批流操作 |
| 无内置备用方案 | 节假日API故障时仅降级,无本地节假日数据兜底 |

适合人群

  • 中小型企业HR团队:需要低成本自动化考勤监控,无定制开发能力
  • 飞书已入驻组织:已完成飞书开放平台认证,具备API权限申请能力
  • 考勤规则标准化企业:迟到/早退/旷工判定逻辑与工具默认规则匹配
  • 技术运维人员:能够理解相对路径依赖、缓存权限等部署细节

不适合:需要深度定制考勤规则、多地区多时区节假日管理、或完全离线运行的场景。

常规风险

  • 数据合规:缓存员工数据至本地目录,需确保符合企业数据安全规范
  • API配额:高频调用可能触发飞书API速率限制,建议合理设置缓存TTL
  • 权限泄漏:Bot消息发送权限若配置不当,可能导致异常报告泄露给非授权人员
  • 第三方服务中断timor.tech 服务不可用会导致节假日判断失效,虽安全模式兜底但可能增加人工复核成本

feishu-attendance 内容

lib文件夹
手动下载zip · 9.5 kB
api.jstext/javascript
请选择文件