Feishu Cloud Drive

---
name: Feishu Cloud Drive
name_zh: 飞书云盘助手
description: 基于飞书官方 API 的云盘管理技能，支持文件列表查询、上传、下载、文件夹创建、权限管理、文件搜索、统计信息、快捷方式、复制移动等完整功能。参考 feishu-drive 技能开发，修复了原技能中的 API 调用错误，并新增了自动化权限管理功能。
metadata:
  openclaw:
    requires:
      env:
        - FEISHU_APP_ID
        - FEISHU_APP_SECRET
      bins:
        - python3
        - pip3
    primaryEnv: FEISHU_APP_SECRET
    install:
      - id: pip-deps
        kind: python
        package: requests
        label: Install Python dependencies

---

# 🎯 项目起源

本技能参考了社区中的 `feishu-drive` 技能，但在实现过程中发现原技能存在以下问题：

1. **API 接口错误**：使用了错误的 API 路径（如 `GET /open-apis/drive/v1/files/:token/children` 应改为 `drive/explorer/v2` 版本）
2. **文档与实际不符**：SKILL.md 中描述的 API 与飞书官方文档不一致
3. **权限管理缺失**：创建的文件夹默认只有机器人可见，未处理权限问题

因此基于飞书官方文档重新开发了此技能，修复了所有已知问题，并新增了权限管理功能。

---

# 飞书云盘管理 (官方API版本)

你是飞书云盘管理专家，负责通过飞书官方 API 实现文件列表查询、上传、下载和文件夹管理。

## 使用方式

### 1. 配置环境变量

设置环境变量：

```bash
export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"
export FEISHU_ROOT_FOLDER_TOKEN="your_folder_token"  # 可选：指定默认根目录
```

### 2. 设置根目录（推荐）

**在使用技能之前，先指定一个根目录**，后续所有操作都以此目录为基准：

```python
from feishu_drive_client import create_client, FeishuDriveClient
import os

# 方式1：使用便捷函数（推荐）
# 自动从环境变量 FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_ROOT_FOLDER_TOKEN 读取
client = create_client()

# 方式2：手动创建客户端，从环境变量读取
client = FeishuDriveClient(
    app_id=os.getenv("FEISHU_APP_ID"),
    app_secret=os.getenv("FEISHU_APP_SECRET"),
    root_folder_token=os.getenv("FEISHU_ROOT_FOLDER_TOKEN")  # 可选
)

# 方式3：手动指定所有参数
client = FeishuDriveClient(
    app_id="your_app_id",
    app_secret="your_app_secret",
    root_folder_token="your_folder_token"  # 可选
)

# 方式4：后续动态设置根目录
client = FeishuDriveClient(app_id, app_secret)
client.set_root_folder("your_folder_token")
```

### 3. 使用示例

设置根目录后，所有操作默认在根目录下进行：

```python
# 在根目录下创建子文件夹（无需传入 folder_token）
result = client.create_folder("新文件夹")

# 在根目录下上传文件
result = client.upload_file("/path/to/file.jpg")

# 列出根目录内容
result = client.list_folder()

# 如需操作其他目录，可临时指定 folder_token
result = client.create_folder("其他位置的文件夹", parent_folder_token="其他token")
```

**优先级规则**：`传入的 folder_token` > `设置的 root_folder_token` > `空字符串（根目录）`

---

## API 基础信息

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

---

## 核心功能

### 1. 获取根文件夹 Token

**接口说明**: 获取用户"我的空间"根文件夹的元数据

```
GET /open-apis/drive/explorer/v2/root_folder/meta
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "token": "nodcnXXXXXX",
    "id": "7110173013420512356",
    "user_id": "7103496998321312356"
  },
  "msg": "success"
}
```

**注意事项**:
- 需要权限: `drive:drive` 或 `drive:drive.metadata:readonly`
- 返回的 token 可用于后续的文件夹操作

---

### 2. 创建文件夹

**接口说明**: 在指定父文件夹下创建新文件夹

```
POST /open-apis/drive/v1/files/create_folder
```

**请求参数**:
```json
{
  "name": "文件夹名称",
  "folder_token": "父文件夹token"
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "token": "fldcnXXXXXX",
    "url": "https://xxx.feishu.cn/drive/folder/fldcnXXXXXX",
    "name": "文件夹名称"
  }
}
```

**注意事项**:
- `folder_token` 为父文件夹 token，可以通过 URL 获取或通过 API 查询
- 创建的文件夹默认只有机器人可见，如需用户可见需要设置权限

---

### 3. 获取文件夹内容

**接口说明**: 获取指定文件夹下的文件和子文件夹列表

**推荐方法 (Explorer v2)**:

```
GET /open-apis/drive/explorer/v2/folder/:folder_token/children
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "children": {
      "file_token1": {
        "token": "file_token1",
        "name": "文件名",
        "type": "file"
      },
      "folder_token1": {
        "token": "folder_token1",
        "name": "文件夹名",
        "type": "folder"
      }
    },
    "parentToken": "folder_token"
  },
  "msg": "success"
}
```

**注意事项**:
- `type` 为 `folder` 表示文件夹，为 `file` 表示文件
- v2 版本的 `children` 是字典格式，不是数组

---

### 4. 上传文件

**接口说明**: 上传文件到指定文件夹

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

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | binary | 是 | 文件二进制内容 |
| file_name | string | 是 | 文件名 |
| parent_type | string | 是 | 父节点类型，`explorer` = 云空间 |
| parent_node | string | 是 | 父节点 token（文件夹 token） |
| size | number | 是 | 文件大小（字节） |

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "file_token": "file_token"
  }
}
```

**注意事项**:
- `parent_type` 使用 `explorer` 表示云空间文件夹
- `size` 参数必填，建议在上传前计算文件大小
- 大文件（超过 10MB）建议使用分片上传接口

---

### 5. 下载文件

**接口说明**: 根据文件 token 下载文件

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

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_token | string | 是 | 文件 token |

**响应**:
- 返回文件二进制流
- Content-Type 根据文件类型自动设置

**注意事项**:
- 需要在请求头中携带 `Authorization: Bearer {tenant_access_token}`
- 下载的是二进制流，需要正确处理响应体

---

### 6. 获取用户 Open ID

**接口说明**: 通过邮箱或手机号获取用户的 open_id

```
POST /open-apis/contact/v3/users/batch_get_id
```

**请求参数**:
```json
{
  "emails": ["user@example.com"],
  "mobiles": ["13800138000"],
  "include_resigned": false
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "user_list": [
      {
        "user_id": "ou_xxxxxxxxx",
        "email": "user@example.com",
        "status": {
          "is_activated": true,
          "is_resigned": false
        }
      }
    ]
  }
}
```

**注意事项**:
- 支持批量查询，最多 50 个邮箱或手机号
- 需要 `contact:user.id:readonly` 权限
- 返回的 `user_id` 就是 `open_id`

---

### 7. 添加文件夹权限

**接口说明**: 为文件夹添加用户权限

```
POST /open-apis/drive/v1/permissions/:token/members?type=folder
```

**请求参数**:
```json
{
  "member_type": "openid",
  "member_id": "ou_xxxxxxxxx",
  "perm": "full_access",
  "perm_type": "container",
  "type": "user"
}
```

**权限类型**:
| perm | 说明 |
|------|------|
| `view` | 可阅读 |
| `edit` | 可编辑 |
| `full_access` | 可管理（完全访问） |

**注意事项**:
- 创建文件夹后，默认只有机器人可见
- 必须通过此接口为用户添加权限，用户才能看到文件夹
- `member_id` 必须是 `open_id`，不能是 `user_id`
- **权限问题排查**：如果遇到机器人无法获取所创建文件夹的权限，请参考官方文档 https://open.feishu.cn/document/server-docs/docs/drive-v1/faq#b02e5bfb

---

### 8. 获取文件元数据

**接口说明**: 获取文件的详细信息

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

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_token | string | 是 | 文件或文件夹 token |

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "token": "token",
    "name": "名称",
    "type": "file/folder",
    "size": 1024,
    "created_time": 1234567890,
    "owner": {
      "open_id": "xxx"
    }
  }
}
```

---

### 9. 删除文件夹

**接口说明**: 删除指定文件夹（删除后进入回收站）

```
DELETE /open-apis/drive/v1/files/:folder_token?type=folder
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| folder_token | string | 是 | 文件夹 token |
| type | string | 是 | 固定值 `folder` |

**响应示例**:
```json
{
  "code": 0,
  "msg": "success"
}
```

**注意事项**:
- 删除后文件夹会进入回收站，可以在回收站中恢复
- 需要具有文件夹的编辑权限才能删除
- **重要**: 执行删除操作前必须向用户确认，避免误删

**Python 示例**:
```python
# 删除文件夹（带确认提示）
def delete_folder_with_confirm(client, folder_token, folder_name, confirmed=False):
    # 1. 显示文件夹信息
    print(f"即将删除文件夹: {folder_name}")
    print(f"Token: {folder_token}")
    
    # 2. 请求用户确认（在自主运行环境中，通过参数传递确认状态）
    if not confirmed:
        print("请设置 confirmed=True 确认删除")
        return
    
    # 3. 执行删除
    result = client.delete_folder(folder_token)
    if result.get("code") == 0:
        print("删除成功！文件夹已进入回收站")
    else:
        print(f"删除失败: {result.get('msg')}")

# 使用示例 - 必须显式确认
delete_folder_with_confirm(client, "folder_token", "测试文件夹", confirmed=True)
```

---

### 10. 删除文件

**接口说明**: 删除指定文件（删除后进入回收站）

```
DELETE /open-apis/drive/v1/files/:file_token?type=file
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_token | string | 是 | 文件 token |
| type | string | 是 | 固定值 `file` |

**注意事项**:
- 删除后文件会进入回收站，可以在回收站中恢复
- 需要具有文件的编辑权限才能删除
- **重要**: 执行删除操作前必须向用户确认

---

### 11. 移动文件或文件夹

**接口说明**: 将文件或文件夹移动到指定文件夹

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

**请求参数**:
```json
{
  "type": "file",
  "destination_folder_token": "目标文件夹token"
}
```

**类型说明**:
| type 值 | 说明 |
|---------|------|
| `file` | 普通文件 |
| `folder` | 文件夹 |
| `doc` | 文档 |
| `sheet` | 电子表格 |
| `bitable` | 多维表格 |
| `docx` | 新版文档 |

---

### 12. 复制文件

**接口说明**: 复制文件到指定文件夹（异步操作）

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

**请求参数**:
```json
{
  "type": "file",
  "destination_folder_token": "目标文件夹token",
  "name": "复制后的新名称(可选)"
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "ticket": "task_ticket_xxx"
  },
  "msg": "success"
}
```

**注意事项**:
- 复制是异步操作，返回 ticket 用于查询任务状态
- 使用 `check_task_status(ticket)` 查询复制进度

---

### 13. 批量获取文件元数据

**接口说明**: 批量获取多个文件的元数据信息

```
POST /open-apis/drive/v1/metas/batch_query
```

**请求参数**:
```json
{
  "file_tokens": ["token1", "token2", "token3"]
}
```

**限制**: 最多 100 个文件 token

---

### 14. 获取文件统计信息

**接口说明**: 获取文件的阅读、点赞、评论等统计信息

```
POST /open-apis/drive/v1/files/:file_token/statistics
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "uv": 100,
    "pv": 200,
    "like_count": 10,
    "comment_count": 5
  }
}
```

---

### 15. 获取文件访问记录

**接口说明**: 获取谁访问了该文件的记录

```
POST /open-apis/drive/v1/files/:file_token/view_records
```

**请求参数**:
```json
{
  "page_size": 50,
  "page_token": "可选的分页token"
}
```

---

### 16. 创建文件快捷方式

**接口说明**: 在指定文件夹创建文件的快捷方式

```
POST /open-apis/drive/v1/files/create_shortcut
```

**请求参数**:
```json
{
  "file_token": "源文件token",
  "folder_token": "目标文件夹token",
  "type": "file"
}
```

---

### 17. 搜索文件

**接口说明**: 在云空间中搜索文件

```
POST /open-apis/suite/docs-api/search/object
```

**请求参数**:
```json
{
  "search_key": "title",
  "search_value": "搜索关键词",
  "page_size": 50
}
```

**search_key 说明**:
| 值 | 说明 |
|----|------|
| `title` | 按标题搜索 |
| `content` | 按内容搜索 |

**注意事项**:
- 此接口需要 `user_access_token`，不支持 `tenant_access_token`

---

### 18. 查询异步任务状态

**接口说明**: 查询复制、移动等异步操作的任务状态

```
GET /open-apis/drive/v1/files/task_check?ticket=xxx
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ticket | string | 是 | 异步任务 ticket |

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "status": "success",
    "file_token": "新文件token"
  }
}
```

**status 说明**:
| 值 | 说明 |
|----|------|
| `pending` | 等待中 |
| `processing` | 处理中 |
| `success` | 成功 |
| `failed` | 失败 |

---

## 错误处理

| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| 0 | 成功 | — |
| 99991663 | token 过期 | 重新获取 tenant_access_token |
| 1061002 | 无权限 | 检查应用权限和文件夹授权 |
| 1061001 | 文件/文件夹不存在 | 检查 token 是否正确 |
| 1061045 | 文件大小超限 | 使用分片上传或减小文件大小 |
| 404 | 文件不存在 | **常见原因**：使用了字典 key 而非 item['token']，参见下方常见错误 |

---

## ⚠️ 常见错误：Token 混淆导致 404

### 问题描述

在获取文件夹内容后尝试下载文件时，出现 404 错误。

### 根本原因

**混淆了飞书 API 返回数据结构中的两种"token"**：

```json
{
  "children": {
    "nodcn5OkQG6q8Y4SuSncukJmCtc": {  // ← 错误：这是字典的 key，不是下载用 token
      "token": "KdLTbke3BoN85RxQg5qcswFYnah",  // ← 正确：这才是下载用的 token
      "name": "Screenshot_20260323-115306.png",
      "type": "file"
    }
  }
}
```

### 错误写法 ❌

```python
result = client.list_folder(folder_token)
children = result["data"]["children"]
for token, item in children.items():  # ← token 实际是 dict_key (nodcn...)
    file_token = token  # ← 错误！这会导致 404
    client.download_file(file_token, "/path/to/file")
```

### 正确写法 ✅

```python
result = client.list_folder(folder_token)
children = result["data"]["children"]
for dict_key, item in children.items():  # dict_key 是 nodcn...
    file_token = item["token"]  # ← 正确！从 item 中获取 token
    client.download_file(file_token, "/path/to/file")

# 或者直接使用 list_all() 方法，它已经处理了这个问题
files = client.list_all(folder_token)
for file in files:
    client.download_file(file["token"], f"/path/to/{file['name']}")
```

### 记住这个规则

| 位置 | 值 | 用途 |
|------|-----|------|
| 字典 key | `nodcn5OkQG6q8Y4SuSncukJmCtc` | 仅用于迭代，通常不使用 |
| `item['token']` | `KdLTbke3BoN85RxQg5qcswFYnah` | **下载、删除、复制、移动等所有操作** |

---

## 使用建议

### 权限配置

确保应用已获取以下权限：
- `drive:file:read` - 读取文件
- `drive:file:write` - 写入文件
- `drive:folder:read` - 读取文件夹
- `drive:folder:write` - 创建文件夹
- `contact:user.id:readonly` - 获取用户 ID（用于权限管理）

### 最佳实践

1. **最小权限原则**: 为飞书应用仅授予必需的权限，避免过度授权
2. **测试应用**: 建议创建专门的测试应用，使用受限权限进行开发测试
3. **权限管理**: 通过 API 创建的文件默认只有机器人可见，需要注意权限设置
4. **冒烟测试**: 执行任何操作前，先用 `get_file_info` 测试 token 是否可用
5. **分页处理**: 文件列表可能很多，务必处理分页逻辑
6. **错误重试**: 对于网络错误和临时错误，建议实现重试机制

### 安全注意事项

1. **不要在前端代码中暴露 tenant_access_token**
2. **不要分享生产环境的 FEISHU_APP_SECRET**
3. **不要将凭证提交到代码仓库**
2. 定期轮换访问令牌
3. 限制文件上传大小，避免滥用
4. 验证文件类型，防止上传恶意文件