Cursor如何通过API对接飞书自动创建文档？

Question

在使用 Cursor 通过 API 对接飞书（Lark）自动创建文档时，一个常见问题是：**如何正确配置飞书开放平台的应用权限并获取有效的 access_token 来调用 create_document 接口？** 开发者常因未开通“云文档”API 权限、误用 tenant_access_token 或未能正确设置应用管理员授权，导致接口返回“permission denied”或“invalid token”错误。此外，文档空间（folder_token）权限不足或请求体格式不符合飞书 API 规范也会引发创建失败。

Answer 1

一、问题背景与核心挑战

在现代企业自动化系统中，通过 Cursor（或类似开发环境）调用飞书（Lark）开放平台 API 实现文档自动创建，已成为提升协作效率的重要手段。然而，开发者在对接过程中常遇到接口调用失败的问题，主要集中在权限配置与认证机制上。

最常见的错误包括：

• permission denied：通常由应用未开通“云文档”API 权限或用户授权不足引起；
• invalid token：多因误用 tenant_access_token 或获取方式不正确导致；
• 文档空间（folder_token）无写入权限；
• 请求体字段缺失或格式不符合飞书 API 规范。

这些问题看似简单，实则涉及飞书开放平台的多个子系统协同工作，需从权限模型、认证流程到API调用链路进行系统性排查。

二、飞书开放平台权限体系解析

飞书应用分为“企业自建应用”和“第三方应用”，本文以企业自建应用为例说明。要成功调用 create_document 接口，必须满足以下权限条件：

权限类型	作用范围	是否必需	配置位置
云文档读写	允许创建/编辑文档	是	应用权限 → 云文档 API
通讯录读取	获取用户信息（可选）	否	应用权限 → 通讯录
应用管理员授权	获取 tenant_access_token	是	管理后台 → 应用安装授权
文档空间 folder_token 权限	目标文件夹可写	是	飞书文档 → 分享设置

三、access_token 获取机制详解

飞书 API 调用依赖两种主要 token：

1. app_access_token：用于获取应用级凭证，适用于部分元数据操作；
2. tenant_access_token：企业级访问令牌，调用大多数业务接口（如创建文档）所必需。

获取 tenant_access_token 的标准流程如下：

POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
Headers:
  Content-Type: application/json

Body:
{
  "app_id": "cli_xxxx",
  "app_secret": "secr_xxxx"
}

响应示例：

{
  "code": 0,
  "msg": "ok",
  "tenant_access_token": "t-caecc79a****",
  "expire": 7200
}

注意：tenant_access_token 有效期为 2 小时，需缓存并定期刷新，避免频繁申请触发限流。

四、create_document 接口调用规范

使用 tenant_access_token 调用文档创建接口时，URL 和请求体必须严格符合规范：

POST https://open.feishu.cn/open-apis/docx/v1/documents
Authorization: Bearer t-caecc79a****
Content-Type: application/json

{
  "folder_token": "fldcnyXXXX",
  "title": "自动化生成报告 - {{date}}",
  "content": "<empty>"
}

关键字段说明：

• folder_token：目标文档夹 ID，可在 URL 中提取或通过“文档列表”API 获取；
• title：文档标题，支持动态变量；
• content：初始内容，若为空可设为占位符。

五、常见错误与诊断路径

当接口返回失败时，应按以下流程图进行排查：

graph TD A[调用 create_document 失败] --> B{错误码?} B -->|invalid token| C[检查 tenant_access_token 是否过期] B -->|permission denied| D[确认云文档权限已开启] C --> E[重新获取 token 并验证 app_id/app_secret] D --> F[进入飞书开放平台勾选“云文档读写”] F --> G[检查应用是否已完成管理员授权] G --> H[确认 folder_token 所属空间是否对应用开放写权限] H --> I[使用 docx/v1/folders/{token}/members 检查权限] I --> J[修正请求体 JSON 格式并重试]

六、最佳实践建议

为确保稳定集成，建议采取以下措施：

• 使用中间服务缓存 tenant_access_token，设置 6500 秒 TTL 避免过期；
• 在 CI/CD 流程中加入权限检测脚本，防止配置漂移；
• 对 folder_token 进行预检，调用 GET /folders/{token} 验证可写性；
• 封装统一的飞书客户端，内置重试机制与日志追踪；
• 启用飞书 API 调用审计日志，便于问题回溯；
• 在 Cursor 中配置环境变量存储敏感信息（如 app_secret）；
• 采用结构化日志记录每次 token 获取与文档创建结果；
• 设置监控告警，当连续 3 次 token 获取失败时通知运维；
• 定期审查应用权限变更，避免因组织结构调整导致中断；
• 文档模板化：将常用文档结构预存为模板，通过复制方式提高性能。