飞书问题排查
常见问题（FAQ）
授权相关
Token 过期
- 现象：API 调用返回
99991668或99991672 - 解决：重新执行 OAuth 授权流程
权限不足
- 现象：API 返回
99991400或99991403 - 解决：检查应用是否开通了所需的 API 权限，参考下方权限对照表
Refresh Token 过期
- 现象：刷新 token 时返回错误
- 解决：需要重新走完整 OAuth 流程
权限对照表
| 功能模块 | 所需权限 scope |
|---|---|
| 日历读写 | calendar:calendar, calendar:calendar:readonly |
| 文档读写 | docx:document, docx:document:readonly |
| 多维表格 | bitable:app, bitable:app:readonly |
| 任务管理 | task:task, task:task:readonly |
| 通讯录 | contact:user.base:readonly, contact:department.base:readonly |
| 消息读写 | im:message, im:message:readonly |
| 云盘 | drive:drive, drive:drive:readonly |
| Wiki | wiki:wiki, wiki:wiki:readonly |
| 邮件 | mail:mailgroup, mail:mailgroup:readonly |
API 调用问题
频率限制
- 飞书 API 有频率限制，通常 100 次/秒
- 批量操作建议串行 + 延迟 0.5-1 秒
字段值格式错误
- 参考
skills/feishu-bitable/references/record-values.md
诊断命令
# 查看授权状态
python3 skills/feishu-cli/run.py '{"action":"auth","subcommand":"status"}'
# 查看可用模块
python3 skills/feishu-cli/run.py '{"action":"help","topic":"modules"}'