核心用法
飞书日历技能（feishu-calendar）是一款基于飞书开放平台官方API构建的企业级日历管理工具，深度集成飞书日历v4接口，提供完整的日程生命周期管理能力。
主要功能模块：
- 日历管理：获取用户可访问的日历列表，支持个人日历与企业共享日历
- 日程查询：按时间范围分页获取事件，支持Unix时间戳（秒级）精确筛选
- 日程创建：支持全天事件（
is_all_day: true）与定时事件双模式，可设置多层级提醒（5分钟至5天提前通知） - 日程更新：PATCH方法增量更新，支持重复规则（RRULE标准：
FREQ=DAILY/WEEKLY/MONTHLY/YEARLY） - 日程删除：软删除机制，API返回
status: cancelled标记
技术实现特点：
- 采用OAuth2.0企业自建应用模式，通过
tenant_access_token鉴权 - 严格遵循飞书API规范：时间戳单位为秒（需将JS毫秒值除以1000）
- 时区处理建议使用
Asia/Shanghai，全天事件使用date字段而非timestamp
显著优点
1. 官方API背书：直接调用飞书开放平台v4接口，数据同步实时准确，无第三方中转风险
2. 功能覆盖全面：完整支持CRUD操作+重复规则+提醒设置，满足企业级日程自动化需求
3. 重复规则灵活：基于iCalendar RRULE标准，支持年/月/周/日四级周期性事件
4. 多层级提醒：单事件可配置多个提醒节点（如生日提前5天+1天双提醒）
5. 全天事件友好：专门处理跨天时区问题，避免定时事件的时区漂移
潜在缺点与局限性
1. Token管理负担：tenant_access_token仅2小时有效期，生产环境需自行实现缓存刷新机制
2. 权限配置复杂：需在飞书后台手动开通5项独立权限，企业管理员配合成本较高
3. 分页处理繁琐：大量事件需处理has_more和page_token，无内置自动分页封装
4. 已取消事件污染：API返回包含已删除（cancelled）事件，需客户端二次过滤
5. 无Webhook支持：仅支持主动轮询查询，无法实现日程变更的实时推送
6. 企业应用限制：仅支持企业自建应用，个人用户无法直接使用
适合人群
- 企业行政/HR团队：批量管理员工生日、入职纪念日等周期性提醒
- 研发团队：将项目里程碑、版本发布计划同步至团队日历
- 自动化运维场景：结合CI/CD流水线自动创建发布日程
- 飞书深度用户：已在飞书生态内办公，希望扩展日历自动化能力的组织
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| Token泄露 | `app_secret`和`tenant_access_token`暴露可能导致日历数据被非法访问 | 使用环境变量注入，禁止硬编码；生产环境启用IP白名单 |
| 权限过度申请 | 应用权限范围大于实际使用需求 | 遵循最小权限原则，仅开通必需的5项日历权限 |
| 时区错误 | 秒/毫秒混淆或时区参数错误导致事件时间偏移 | 统一使用`Asia/Shanghai`，封装时间转换工具函数 |
| 频率限制 | 高频调用可能触发飞书API限流 | 实现指数退避重试，缓存日历列表减少重复查询 |
| 数据残留 | 已删除事件仍通过API返回，可能造成误解 | 客户端强制过滤`status !== 'cancelled'`的事件 |