← 返回知识库 # 飞书开放平台 API — Agent 速查手册 > 所有 Hermes 通用。 > 对接飞书多维表格、飞书云盘、飞书消息的核心 API。 --- ## 一、认证（获取 Token） ```bash # 自建应用获取 tenant_access_token curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H "Content-Type: application/json" \ -d '{ "app_id": "cli_xxxxxxxxxxxx", "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxx" }' # 返回 { "code": 0, "msg": "success", "tenant_access_token": "t-xxxxxxxxxxxxxxxxxxxxxxxxx", "expire": 7200 } ``` **Token 有效期 2 小时**，过期前需要重新获取。建议每次调用 API 前都刷新。 --- ## 二、多维表格（Bitable）— 核心 API ### 2.1 获取记录列表 ``` GET https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records Authorization: Bearer {tenant_access_token} ``` | 参数 | 说明 | |:-----|:------| | `app_token` | 多维表格的 base_token（从 URL 或云文档 API 获取） | | `table_id` | 数据表的 ID（多维表格可能有多个 sheet） | | `page_size` | 每页条数（最大 500） | | `page_token` | 分页标记 | ### 2.2 新增记录 ```bash curl -X POST https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "fields": { "任务ID": "task_001", "标题": "搭建MCP桥接", "负责人": "Trae", "状态": "待处理", "优先级": "P1" } }' ``` ### 2.3 更新记录 ``` PUT https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id} ``` Body 格式同新增。 ### 2.4 获取多维表格元数据 ``` GET https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token} ``` 返回所有表的列表及字段定义。 ### 2.5 列出多维表格（获取 app_token） ``` GET https://open.feishu.cn/open-apis/drive/v1/metas/batch_query ``` --- ## 三、飞书云盘（Drive） ### 3.1 上传文件 ```bash curl -X POST https://open.feishu.cn/open-apis/drive/v1/files/upload_all \ -H "Authorization: Bearer {token}" \ -F "file_name=报告.md" \ -F "parent_type=explorer" \ -F "parent_node=空间文件夹token" \ -F "file=@本地文件路径" ``` ### 3.2 下载文件 ``` GET https://open.feishu.cn/open-apis/drive/v1/files/{file_token}/download ``` ### 3.3 搜索云文档 ``` POST https://open.feishu.cn/open-apis/drive/v1/search ``` --- ## 四、发送消息 ### 4.1 发送文本消息 ```bash curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "receive_id": "ou_xxxx", "msg_type": "text", "content": "{\"text\":\"你好\"}" }' ``` ### 4.2 发送卡片消息 ```bash curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "receive_id": "ou_xxxx", "msg_type": "interactive", "content": "{\"elements\":[],\"header\":{\"title\":{\"tag\":\"plain_text\",\"content\":\"标题\"}}}" }' ``` --- ## 五、错误码速查 | 错误码 | 含义 | 处理方式 | |:------|:-----|:---------| | 99991672 | 权限不足/未授权 | 去飞书开放平台 → 权限管理，添加对应权限 | | 10003 | 应用不存在 | 检查 app_id | | 10004 | 签名错误 | 检查 app_secret | | 2048 | token 过期 | 重新获取 tenant_access_token | | 230001 | 多维表格不存在 | 检查 app_token | | 230002 | 数据表不存在 | 检查 table_id | --- ## 六、5号 现有飞书凭证 - App ID: `cli_aa8b7220c4b91bda` - App Secret: 在 5号 `/root/.hermes/.env` 中的 `FEISHU_APP_SECRET` - 已授权权限：消息、云文档、多维表格等 --- ## 七、对接架构 ``` Google Drive .md 文件 ↓ 桥接脚本（Python，cron 每分钟触发） 飞书多维表格（人看到的看板） ↓ 飞书卡片消息（通知到人） ``` 所有 Agent 只需要读写 `/root/taskboard/` 下的 .md 文件。 桥接到飞书的部分由 5号 的 Python 脚本完成。