feishu-drive

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

Security Scan

The skill's instructions clearly target Feishu Drive and describe required credentials/tokens, but the package metadata does not declare any required environment variables or credentials — an incoherence that could lead to accidental overbroad credential use or misconfiguration.

Purpose & Capability

The SKILL.md content matches the advertised purpose (managing Feishu/Feishu Drive: upload/download/move/search/permissions). The required API scopes listed (drive:file:upload, drive:drive:readonly, etc.) are consistent with that purpose. However, the skill text expects a folder anchor token (ROOT_FOLDER_TOKEN) and uses tenant_access_token for Authorization, yet the skill metadata declares no required environment variables or primary credential — this mismatch reduces coherence.

Instruction Scope

Runtime instructions explicitly reference tenant_access_token (Bearer auth) and a ROOT_FOLDER_TOKEN and require the agent to call drive APIs, create folders, upload binary files, and immediately set collaborator permissions. Those actions are within the stated domain, but the instructions also require the agent to 'silently validate ROOT_FOLDER_TOKEN' and to save downloaded binary streams to disk — which implies access to persistent storage and to an undeclared secret. The SKILL.md gives the agent discretion to change sharing settings (including public/open sharing), which is powerful and should be clearly and explicitly declared.

Install Mechanism

This is an instruction-only skill with no install spec and no code files; nothing is written to disk by an installer. That is low-risk from an installation standpoint.

Credentials

The instructions require at least two sensitive credentials in practice (tenant_access_token and ROOT_FOLDER_TOKEN) and recommend granting the robot '管理'/'编辑' and adding users as full_access collaborators. But the skill's metadata lists no required env vars or primary credential. The absence of declared env vars is a material omission: callers may not realize what secrets the skill needs, and users may accidentally provide overly-broad tokens. The listed API scopes are appropriate for the functionality, but they are powerful (upload, download, permission changes) and should be explicitly surfaced.

Persistence & Privilege

The skill is not force-included (always:false) and does not declare modifications to other skills or system-wide settings. It instructs creating and modifying Drive resources (expected), but it does not request persistent platform privileges in its metadata.

What to consider before installing

This skill appears to be a legitimate Feishu Drive integration, but the metadata fails to declare the secrets it actually needs. Before installing or enabling it: (1) ask the publisher to explicitly declare required environment variables (e.g., ROOT_FOLDER_TOKEN, TENANT_ACCESS_TOKEN) and the minimal API scopes; (2) only provide a token scoped to a single shared folder (an anchor) rather than a tenant-wide or full-access token; (3) review and confirm the skill's behavior for setting collaborator permissions (avoid granting public/open sharing unless intended); (4) if possible, test in a non-production tenant or with a throwaway folder to verify the 'write then grant permissions' flow; (5) avoid giving long-lived tenant-wide tokens — prefer short-lived or least-privilege credentials. If the publisher cannot clarify the missing env declarations, treat installation as higher risk.

飞书云空间文件管理

你是飞书云空间文件管理专家，负责通过 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. 创建文件夹

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

表单字段：

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

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

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)：机器人创建的文件默认对用户不可见。必须在每个写操作后手动补齐权限。

目标权限	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”等私有信息已替换为通用互联网公司职能与项目描述。