feishu-drive

Manage Feishu Drive files and folders with upload, download, move, search, metadata retrieval, and access permission syncing.

飞书云空间文件管理

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

---

一、API 基础信息

项目	值
Base URL	https://open.feishu.cn/open-apis/drive/v1
认证方式	Authorization: Bearer {tenant_access_token}
Content-Type	application/json（文件上传用 multipart/form-data）

---

二、文件夹操作

1. 创建文件夹

text

POST /open-apis/drive/v1/folders

json

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

实测心法：

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

---

三、文件上传

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

text

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

表单字段：

字段	说明
file	文件二进制内容
file_name	文件名（如 report.pdf）
parent_type	父节点类型（explorer = 云空间，bitable_file = 多维表格附件）
parent_node	父节点 token（文件夹 token 或 app_token）
size	文件大小（字节）

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

3. 分片上传（大文件）

第 1 步：准备上传

text

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

json

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

返回 upload_id 和分片信息。

第 2 步：逐片上传

text

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

第 3 步：完成上传

text

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

---

四、文件下载

4. 下载文件

text

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

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

---

五、文件操作

5. 移动文件

text

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

json

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

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

6. 复制文件

text

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

json

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

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

---

六、文件查询

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

text

POST /open-apis/drive/metadata/batch_query

json

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

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

8. 搜索文件

text

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

json

{ "search_word": "关键词" }

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

---

七、安全与审计

9. 获取文件下载记录

text

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

实测心法：用于监控敏感文件的流向，建立内部合规审计流。

10. 管理安全标签

text

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

实测心法：为核心文档打上"绝密"标签，限制二次转发。飞书企业版的核心安全能力。

---

八、权限管理矩阵 (协作流核心)

关键教训 (2026-02-10)：机器人创建的文件默认对用户不可见。必须在每个写操作后手动补齐权限。

目标权限	external_access_entity	link_share_entity	security_entity
组织内可阅读	closed	tenant_readable	anyone_can_view
组织内可编辑	closed	tenant_editable	anyone_can_edit
互联网公开阅读	open	anyone_readable	anyone_can_view
互联网公开编辑	open	anyone_editable	anyone_can_edit

AI Agent 准则：

1. 文件夹优先：严禁在机器人的根目录创建孤立文件。必须指定一个用户可见的 parent_node（如共享文件夹）。
2. 写后必授：调用 upload_all、copy 或 create_docx 后，必须紧接着调用权限接口，将请求者添加为 full_access 协作者，否则用户在云盘主目录无法管理该资产。
3. 冒烟先行：在执行任何 Drive 写入指令前，AI Agent 应先静默校验 ROOT_FOLDER_TOKEN 的可用性。若失效，应立即推送“配置引导”卡片而非报错。

---

九、错误处理

错误码	含义	解决方案
0	成功	—
1061001	文件不存在	检查 file_token
1061002	无权限	检查应用权限和文件夹授权
1061045	文件大小超限	使用分片上传
99991663	token 过期	重新获取 tenant_access_token

---

feishu-drive 技能总结 (教程脱敏版)

一、 核心功能清单

功能维度	具体能力	说明
空间管理	文件夹自动化	支持在指定的共享空间内自动创建多级子文件夹，实现资产的结构化组织。
资产同步	跨空间克隆与上传	支持将本地文件（如 PPT/PDF）一键上传，或将云端标准模版（如 PRD）跨目录克隆到目标空间。
感知与检索	智能元数据查询	提供高效的文件元数据批量查询与关键词模糊搜索能力，解决资产定位难题。
协作安全性	权限自愈逻辑	在文件生成后自动同步指定用户的管理权限，打通“机器人-人类”之间的空间可见性隔阂。

---

二、 典型业务场景

新项目资产中心自动构建：

• 场景：当公司启动新业务线（如：海外市场调研）时，AI 自动根据项目名称在团队云盘创建对应的资料库，并将预设的调研模版、汇报 PPT 等基础物料自动分发至该目录下。
• 价值：确保项目启动初期资产不乱放，实现“开箱即用”的项目环境。

营销物料自动化分发与归档：

• 场景：内容团队完成设计稿后，AI 自动将物料同步至外包共享文件夹，并一键开启“互联网公开编辑”权限，方便供应商即刻查阅。
• 价值：省去手动修改成百上千个文件权限的繁琐，极大缩短协作链路。

财务/法务文档智能备份：

• 场景：系统自动汇总所有支付凭证或合同初稿，按月度/年度分门别类地归档至云空间，并自动对关键人员开放管理权限。
• 价值：实现数字化审计痕迹的自动留存，确保存档的完整性。

---

三、 实测注意事项（教程必写 · 尽量详细）

权限“黑盒”隔阂 (Critical)：

• 风险：飞书机器人通过 API 创建的文件，默认所有者是“机器人”，用户在“我的空间”或“主目录”中无法看到，导致资产“失踪”。
• 对策：教程必须强调 “写后必授” 原则。即在上传或克隆操作后，必须紧跟一个 permissions 接口调用，将相关负责人添加为 full_access 协作者。只有这样，文件才会出现在用户的「与我共享」列表中。

指定“空间锚点”原则：

• 坑点：严禁让机器人在根目录（root）随意创建文件，这会导致资产极难管理且极易触发权限越权风险。
• 建议：在教程中引导用户先手动创建一个“顶级共享文件夹”，并将该文件夹的 Token 授权给机器人。让机器人所有的操作都发生在这个“锚点”之下，实现权限的可控继承。

文件夹创建 API 兼容性：

• 注意：部分飞书租户的文件夹创建接口在 v1/v2 版本间存在路径规范差异（如 404 报错）。建议在自动化代码中优先尝试 upload_all 接口的 parent_node 参数来实现路径指定，而非频繁调用新建目录接口。

冒烟测试先行：

• 技巧：在执行大规模资产搬运前，先调用一次轻量级的 list_files 探测该 Token 是否可用。如果冒烟测试不通过（报 403/404），应引导用户检查“机器人可见性”或“文件夹协作授权”是否已开启。

---

注：以上内容已进行脱敏处理，所有“主帅”、“董事长”、“PixPaw”等私有信息已替换为通用互联网公司职能与项目描述。