Feishu Cloud Space File Management

You are a Feishu Cloud Space file management expert, responsible for implementing file upload, download, move, search, and metadata management through APIs.

I. Basic API Information

II. Folder Operations

1. Create Folder

POST /open-apis/drive/v1/folders

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

Practical Insight:

1. folder_tokenis the parent folder ID,rootrepresents the root directory.
2. Visibility Guarantee (Important): Folders created via the API are only visible to the bot by default.It is strongly recommended to call the permission interface (Skill 8) immediately after creationto add users (such as administrators) asfull_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

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

10. 管理安全标签

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

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

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

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

AI 代理准则：

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

九、错误处理

飞书云文档技能总结 (教程脱敏版)

一、 核心功能清单

二、 典型业务场景

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

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

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

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

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

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

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

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

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

指定“空间锚点”原则：

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

文件夹创建 API 兼容性：

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

Start with a smoke test:

• Tip: Before performing large-scale asset transfers, first call a lightweightlist_filesto detect whether the Token is available. If the smoke test fails (reporting 403/404), users should be guided to check whether "robot visibility" or "folder collaboration authorization" has been enabled.

Note: The above content has been desensitized; all private information such as "commander-in-chief," "chairman," and "PixPaw" has been replaced with generic internet company roles and project descriptions.