tomevault-io 飞书云空间文件管理
通过 Drive API 管理文件和文件夹。
Base URL: https://open.feishu.cn/open-apis/drive/v1
认证与 Token 获取
从 feishu_skills 根目录执行共享脚本：
TOKEN="$(./scripts/get_feishu_token.sh)"
请求头统一使用 Authorization: Bearer ${TOKEN}。
如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：
TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"
环境变量:
FEISHU_APP_IDFEISHU_APP_SECRET
本地缓存: ./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）
快速启动（必读）
为避免文件进入"私有黑盒"：
- 创建锚点文件夹（如
AI-Workspace） - 授权机器人：文件夹【协作】设置中添加应用为【管理】权限
- 获取 Token：复制文件夹 URL 中的 Token
- 测试：调用
batch_query查询该 Token
⚠️ API 创建的文件夹默认只对机器人可见，需手动添加协作者。
文件夹操作
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 创建文件夹 | /folders |
POST | {"name":"文件夹名","folder_token":"root"} |
创建新文件夹 |
| 获取文件夹元数据 | /folders/{folder_token}/meta |
GET | - | 查询文件夹详情 |
| 获取元数据（批量） | /metas/batch_query |
POST | {"request_list":[{"token":"fldxxx","type":"folder"}]} |
批量查询文件/文件夹 |
| 获取文件夹内容 | /folders/{folder_token}/children |
GET | - | 查询文件夹内文件列表 |
| 移动文件夹 | /folders/{folder_token}/move |
POST | {"target_token":"fldxxx"} |
移动文件夹 |
| 复制文件夹 | /folders/{folder_token}/copy |
POST | {"target_token":"fldxxx"} |
复制文件夹 |
| 删除文件夹 | /folders/{folder_token} |
DELETE | - | 删除空文件夹 |
文件上传
| API | 端点 | 方法 | 请求体 | 说明 |
|---|---|---|---|---|
| 小文件上传 | /files/upload_all |
POST | multipart/form-data |
一次性上传（<20MB） |
| 大文件预上传 | /files/upload_prepare |
POST | {"file_name":"big.zip","size":104857600} |
初始化分片上传 |
| 分片上传 | /files/upload_part |
POST | multipart/form-data |
上传单个分片 |
| 完成分片上传 | /files/upload_finish |
POST | {"upload_id":"xxx","block_num":10} |
完成上传 |
小文件上传:
POST /files/upload_all
Content-Type: multipart/form-data
file_name=test.txt
parent_type=explorer
parent_node=fldXXX
file=<binary>
文件下载
| API | 端点 | 方法 | 说明 |
|---|---|---|---|
| 下载文件 | /files/{file_token}/download |
GET | 返回文件二进制流 |
| 获取文件元数据 | /files/{file_token}/meta |
GET | 查询文件详情 |
| 获取文件列表 | /files |
GET | 参数：folder_token 父文件夹 |
文件操作
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 移动文件 | /files/{file_token}/move |
POST | {"type":"explorer","folder_token":"fldXXX"} |
移动文件 |
| 复制文件 | /files/{file_token}/copy |
POST | {"type":"explorer","folder_token":"fldXXX","name":"副本.txt"} |
复制文件 |
| 删除文件 | /files/{file_token} |
DELETE | - | 删除文件 |
| 创建快捷方式 | /shortcuts |
POST | {"target_token":"filexxx","parent_token":"fldxxx"} |
创建文件快捷方式 |
| 获取文件统计 | /files/{file_token}/statistics |
GET | - | 查询文件访问统计 |
搜索
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 搜索文件 | /files/search |
POST | {"search_key":"关键词","owner_ids":["ou_xxx"]} |
全文搜索 |
| 搜索V2 | /files/search_v2 |
POST | 同上 | 新版搜索接口 |
权限管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 添加协作者 | /permissions/{token}/members |
POST | {"member_type":"user","member_id":"ou_xxx","perm":"full_access"} |
添加权限 |
| 移除协作者 | /permissions/{token}/members/{member_id} |
DELETE | - | 移除权限 |
| 获取协作者 | /permissions/{token}/members |
GET | - | 查询权限列表 |
| 更新协作者 | /permissions/{token}/members/{member_id}/patch |
PATCH | {"perm":"edit"} |
修改权限 |
| 转让所有者 | /permissions/{token}/transfer_owner |
POST | {"member_type":"user","member_id":"ou_xxx"} |
转移所有权 |
| 获取权限设置 | /permissions/{token}/public |
GET | - | 查询公开访问设置 |
| 更新权限设置 | /permissions/{token}/public |
PATCH | {"external_access":false} |
修改公开访问 |
权限类型: view(查看) / edit(编辑) / full_access(完全访问)
文件版本管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取版本列表 | /files/{file_token}/versions |
GET | - | 查询文件历史版本 |
| 获取版本详情 | /files/{file_token}/versions/{version_id} |
GET | - | 查询指定版本信息 |
| 删除版本 | /files/{file_token}/versions/{version_id} |
DELETE | - | 删除历史版本 |
文件评论
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 获取全文评论 | /files/{file_token}/comments |
GET | - | 查询文件所有评论 |
| 获取回复列表 | /files/{file_token}/comments/{comment_id}/replies |
GET | - | 查询评论的回复 |
| 添加全文评论 | /files/{file_token}/comments |
POST | {"content":{"text":"评论内容"}} |
添加评论 |
| 回复评论 | /files/{file_token}/comments/{comment_id}/replies |
POST | {"content":{"text":"回复内容"}} |
回复评论 |
| 解决/重开评论 | /files/{file_token}/comments/{comment_id} |
PATCH | {"is_solved":true} |
标记评论状态 |
订阅管理
| API | 端点 | 方法 | 请求体示例 | 说明 |
|---|---|---|---|---|
| 订阅文件 | /files/{file_token}/subscriptions |
POST | {"subscription_type":"file_edit"} |
订阅文件变更通知 |
| 获取订阅状态 | /files/{file_token}/subscriptions/{subscription_id} |
GET | - | 查询订阅状态 |
| 取消订阅 | /files/{file_token}/subscriptions/{subscription_id} |
DELETE | - | 取消订阅 |
订阅类型: file_edit(文件编辑) / file_comment(评论) / file_share(分享)
最佳实践
- 创建文件夹后立即添加协作者（避免不可见）
- 大文件用分片上传（>20MB）
- 权限继承：父文件夹授权后，子文件夹自动继承
- 版本管理：定期清理历史版本节省空间
- 订阅通知：关键文件订阅变更通知，及时响应
Converted and distributed by TomeVault — claim your Tome and manage your conversions.