name: feishu-drive description: 飞书云空间文件管理 Skill。上传/下载/移动/搜索文件、创建文件夹、获取元数据等。当需要管理飞书云空间中的文件和文件夹时使用此 Skill。 required_permissions:

• drive:file:upload
• drive:file:download
• drive:drive:readonly
• drive:drive.search:readonly
• space:folder:create
• space:document:move

🚀 快速启动：三步打通云空间 (必读)

为避免机器人文件进入“私有黑盒”，请在首次使用前完成以下配置：

1. 创建锚点：在您的飞书云空间创建一个文件夹（如 AI-Workspace）。
2. 授权机器人：在文件夹的【协作】设置中，搜索并添加您的应用（机器人）为【管理】或【编辑】权限。
3. 设置 Token：复制该文件夹 URL 中的 Token，配置为 Skill 的 ROOT_FOLDER_TOKEN。
4. 冒烟测试：调用 batch_query 接口查询该 Token 元数据。若返回 200 则配置成功；若返回 403/404 则检查应用可见性或授权是否到位。

飞书云空间文件管理

你是飞书云空间文件管理专家，负责通过 API 实现文件的上传、下载、移动、搜索和元数据管理。

一、API 基础信息

二、文件夹操作

1. 创建文件夹

POST /open-apis/drive/v1/folders

{ "name": "文件夹名", "folder_token": "root" }

实测心法：

1. folder_token 为父文件夹 ID，root 表示根目录。
2. 可见性保障 (重要)：通过 API 创建的文件夹默认只对机器人可见。强烈建议在创建后立即调用权限接口 (Skill 8)，将用户（如管理员）添加为 full_access 协作者，这样文件夹才会出现在用户的「我的空间」列表中。
3. 权限继承：一旦您被添加为父文件夹的管理员，AI 机器人在该文件夹下创建的所有子文件夹和文档，您都将自动拥有管理权限，无需重复授权。

三、文件上传

2. 上传文件（小文件一次性上传）

POST /open-apis/drive/v1/files/upload_all
Content-Type: multipart/form-data

表单字段：

实测心法：大文件建议使用分片上传接口。

3. 分片上传（大文件）

第 1 步：准备上传

POST /open-apis/drive/v1/files/upload_prepare

{
  "file_name": "large_file.zip",
  "parent_type": "explorer",
  "parent_node": "fldcnXXX",
  "size": 104857600
}

返回 upload_id 和分片信息。

第 2 步：逐片上传

POST /open-apis/drive/v1/files/upload_part
Content-Type: multipart/form-data

第 3 步：完成上传

POST /open-apis/drive/v1/files/upload_finish

四、文件下载

4. 下载文件

GET /open-apis/drive/v1/files/:file_token/download

实测心法：流式读取响应体，注意保存路径。返回的是二进制流。

五、文件操作

5. 移动文件

POST /open-apis/drive/v1/files/:file_token/move

{ "type": "docx", "folder_token": "fldcn..." }

实测心法：需要同时拥有源文件夹和目标文件夹的权限。

6. 复制文件

POST /open-apis/drive/v1/files/:file_token/copy

{ "type": "bitable", "folder_token": "fldcn...", "name": "副本名称" }

实测心法：适用于从模板快速克隆多维表格、文档等。

六、文件查询

7. 获取文件元数据（批量）

POST /open-apis/drive/metadata/batch_query

{
  "metadatas": [
    { "token": "...", "type": "docx" }
  ]
}

实测心法：支持批量查询，效率更高。可获取文件所有者、创建时间等。

8. 搜索文件

POST /open-apis/drive/v1/files/search

{ "search_word": "关键词" }

实测心法：搜索结果包含文档、表格及文件夹。

七、安全与审计

9. 获取文件下载记录

GET /open-apis/drive/v1/files/:file_token/view_records