飞书问题排查

常见问题（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"}'