Back to Details

feishu-cli-drive

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书云盘增强（Drive）

飞书云盘增强（Drive）

drive
命令组提供与老 
file
/ 
media
/ 
comment add
命令并存的增强能力： 分块上传、markdown 快捷导出、异步任务 resume、富文本评论、wiki 链接解析。
feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。
drive
命令组提供与旧 
file
/ 
media
/ 
comment add
命令并存的增强能力： 分块上传、Markdown 快捷导出、异步任务 Resume、富文本评论、Wiki 链接解析。
feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

前置条件

前置条件

  • 认证：所有 
    drive
    命令默认走 User Access Token（执行 
    feishu-cli auth login
    登录）
  • 预检：
    feishu-cli auth check --scope "drive:file:upload"
    可验证 scope
  • 认证：所有 
    drive
    命令默认使用 User Access Token（执行 
    feishu-cli auth login
    进行登录）
  • 预检：
    feishu-cli auth check --scope "drive:file:upload"
    可验证权限范围

命令速查

命令速查

1. 上传 / 下载

1. 上传 / 下载

bash
undefined
bash
undefined

上传（>20MB 自动走 3 段式分块 upload_prepare/upload_part/upload_finish）

上传（>20MB 自动走 3 段式分块 upload_prepare/upload_part/upload_finish）

feishu-cli drive upload --file /tmp/report.pdf feishu-cli drive upload --file /tmp/big.zip --folder-token fldxxx --name "年度报告.zip"
feishu-cli drive upload --file /tmp/report.pdf feishu-cli drive upload --file /tmp/big.zip --folder-token fldxxx --name "年度报告.zip"

下载（流式 + 路径校验 + --overwrite + --timeout）

下载（流式 + 路径校验 + --overwrite + --timeout）

feishu-cli drive download --file-token boxcnxxxx --output ./report.pdf feishu-cli drive download --file-token boxcnxxxx --output ./downloads/ --overwrite feishu-cli drive download --file-token boxcnxxxx --output ./big.zip --timeout 10m

**关键点**：
- `drive upload` 分块上传每片独立重试 3 次，使用 `io.SectionReader` 外层只打开文件一次
- `drive download` 的 `--output` 可以是文件路径（直接用）或目录（**文件名用 `file_token` 本身**，暂不从响应头解析）
- 如果需要自定义文件名，请显式传完整路径：`--output ./downloads/report.pdf`
feishu-cli drive download --file-token boxcnxxxx --output ./report.pdf feishu-cli drive download --file-token boxcnxxxx --output ./downloads/ --overwrite feishu-cli drive download --file-token boxcnxxxx --output ./big.zip --timeout 10m

**关键点**：
- `drive upload` 分块上传时每个分片独立重试3次，使用 `io.SectionReader`，外层仅打开文件一次
- `drive download` 的 `--output` 参数可以是文件路径（直接使用）或目录（**文件名采用 `file_token` 本身**，暂不从响应头解析）
- 如需自定义文件名，请显式传入完整路径：`--output ./downloads/report.pdf`

2. 文档导出（含 markdown 快捷路径）

2. 文档导出（含 Markdown 快捷路径）

bash
undefined
bash
undefined

docx → markdown：走 /docs/v1/content 快捷路径，立即返回（不跑异步 export_tasks）

docx → markdown：走 /docs/v1/content 快捷路径，立即返回（不跑异步 export_tasks）

feishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports
feishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports

docx → pdf：走异步 export_tasks，有界轮询 10×5s，超时返回 next_command

docx → pdf：走异步 export_tasks，有界轮询 10×5s，超时返回 next_command

feishu-cli drive export --token docxxxx --doc-type docx --file-extension pdf --output-dir ./exports
feishu-cli drive export --token docxxxx --doc-type docx --file-extension pdf --output-dir ./exports

sheet → csv 指定 sheet_id

sheet → csv 指定 sheet_id

feishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1
feishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1

bitable → csv 指定 table_id

bitable → csv 指定 table_id

feishu-cli drive export --token basexxxx --doc-type bitable --file-extension csv --sub-id tblxxxx

**支持的格式**：
- `--doc-type`: `doc` / `docx` / `sheet` / `bitable`
- `--file-extension`: `docx` / `pdf` / `xlsx` / `csv` / `markdown`（markdown 仅 docx 支持）

**超时后的 resume 流程**：
```bash
feishu-cli drive export --token basexxxx --doc-type bitable --file-extension csv --sub-id tblxxxx

**支持的格式**：
- `--doc-type`: `doc` / `docx` / `sheet` / `bitable`
- `--file-extension`: `docx` / `pdf` / `xlsx` / `csv` / `markdown`（markdown 仅 docx 支持）

**超时后的 Resume 流程**：
```bash

drive export 超时会输出：

drive export 超时会输出：

next_command: feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

next_command: feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

1. 轮询任务状态

1. 轮询任务状态

feishu-cli drive task-result --scenario export --ticket abc --file-token xxx
feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

2. 任务完成后下载产物

2. 任务完成后下载产物

feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
undefined
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
undefined

3. 
drive export-download
— 下载已完成的导出文件

3. 
drive export-download
— 下载已完成的导出文件

bash
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
feishu-cli drive export-download --file-token boxxxx --file-name "报告.pdf" --overwrite
bash
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
feishu-cli drive export-download --file-token boxxxx --file-name "报告.pdf" --overwrite

4. 文档导入

4. 文档导入

bash
undefined
bash
undefined

本地文件 → 云文档（docx / sheet / bitable）

本地文件 → 云文档（docx / sheet / bitable）

feishu-cli drive import --file report.docx --type docx feishu-cli drive import --file data.xlsx --type sheet --folder-token fldxxx feishu-cli drive import --file bigsheet.csv --type bitable --folder-token fldxxx
feishu-cli drive import --file report.docx --type docx feishu-cli drive import --file data.xlsx --type sheet --folder-token fldxxx feishu-cli drive import --file bigsheet.csv --type bitable --folder-token fldxxx

大文件（>20MB）自动走分块媒体上传

大文件（>20MB）自动走分块媒体上传

feishu-cli drive import --file big.docx --type docx

**关键技术点**：
- 走 **官方 `/medias/upload_all` 端点**（`parent_type=ccm_import_open` + `extra`），**不在用户云盘留下中间文件**（这是和老 `doc import-file` 的核心区别）
- 格式特定大小限制：docx 20MB / sheet 20MB / bitable 100MB
- 有界轮询 30×2s，超时返回 `next_command`
feishu-cli drive import --file big.docx --type docx

**关键技术点**：
- 调用 **官方 `/medias/upload_all` 端点**（`parent_type=ccm_import_open` + `extra`），**不会在用户云盘留下中间文件**（这是与旧 `doc import-file` 的核心区别）
- 格式特定大小限制：docx 20MB / sheet 20MB / bitable 100MB
- 有界轮询 30×2s，超时返回 `next_command`

5. 移动（文件夹自动轮询）

5. 移动（文件夹自动轮询）

bash
undefined
bash
undefined

文件移动（同步，立即返回）

文件移动（同步，立即返回）

feishu-cli drive move --file-token boxxxx --type docx --folder-token fldxxx
feishu-cli drive move --file-token boxxxx --type docx --folder-token fldxxx

文件夹移动（异步，自动轮询 task_check 30×2s）

文件夹移动（异步，自动轮询 task_check 30×2s）

feishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy

**关键点**：
- **文件夹移动自动轮询**，不再是"发出去就不管了"
- 超时会返回 `task_id`，可用 `drive task-result --scenario task_check` 接力
feishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy

**关键点**：
- **文件夹移动自动轮询**，不再是「提交后无反馈」
- 超时会返回 `task_id`，可用 `drive task-result --scenario task_check` 继续完成任务

6. 富文本评论（最强命令）

6. 富文本评论（最强命令）

bash
undefined
bash
undefined

全局评论

全局评论

feishu-cli drive add-comment --doc doccnxxxx --content '[{"type":"text","text":"需要修改标题"}]'
feishu-cli drive add-comment --doc doccnxxxx --content '[{"type":"text","text":"需要修改标题"}]'

通过 docx URL

通过 docx URL

feishu-cli drive add-comment --doc "https://xxx.feishu.cn/docx/doccnxxxx"
--content '[{"type":"text","text":"评论内容"}]'
feishu-cli drive add-comment --doc "https://xxx.feishu.cn/docx/doccnxxxx"
--content '[{"type":"text","text":"评论内容"}]'

通过 wiki URL（自动解析到真实 docx）

通过 wiki URL（自动解析到真实 docx）

feishu-cli drive add-comment --doc "https://xxx.feishu.cn/wiki/nodxxxx"
--content '[{"type":"text","text":"收到"}]'
feishu-cli drive add-comment --doc "https://xxx.feishu.cn/wiki/nodxxxx"
--content '[{"type":"text","text":"收到"}]'

局部评论（锚定到 docx block）

局部评论（锚定到 docx block）

feishu-cli drive add-comment --doc doccnxxxx --block-id blk_xxx
--content '[{"type":"text","text":"这段重写"}]'
feishu-cli drive add-comment --doc doccnxxxx --block-id blk_xxx
--content '[{"type":"text","text":"这段重写"}]'

富文本：文本 + 提及用户 + 链接混合

富文本：文本 + 提及用户 + 链接混合

feishu-cli drive add-comment --doc doccnxxxx --content '[ {"type":"text","text":"请 "}, {"type":"mention_user","mention_user":"ou_xxx"}, {"type":"text","text":" 查看 "}, {"type":"link","link":"https://feishu.cn"} ]'

**reply_elements 元素类型**：
- `text` — 纯文本
- `mention_user` — 提及用户（传 `mention_user` 或 `text` 字段作为 open_id）
- `link` — 链接（传 `link` 或 `text` 字段作为 URL）

**文档输入格式**：
- `docx` token（直接传）
- `docx` URL（`https://xxx.feishu.cn/docx/xxx`）
- `doc` URL（旧版文档）
- `wiki` URL（自动解析到真实 obj_token + obj_type）
feishu-cli drive add-comment --doc doccnxxxx --content '[ {"type":"text","text":"请 "}, {"type":"mention_user","mention_user":"ou_xxx"}, {"type":"text","text":" 查看 "}, {"type":"link","link":"https://feishu.cn"} ]'

**reply_elements 元素类型**：
- `text` — 纯文本
- `mention_user` — 提及用户（传入 `mention_user` 或 `text` 字段作为 open_id）
- `link` — 链接（传入 `link` 或 `text` 字段作为 URL）

**文档输入格式**：
- `docx` token（直接传入）
- `docx` URL（`https://xxx.feishu.cn/docx/xxx`）
- `doc` URL（旧版文档）
- `wiki` URL（自动解析为真实 obj_token + obj_type）

7. 通用异步任务查询

7. 通用异步任务查询

bash
undefined
bash
undefined

查询导入任务

查询导入任务

feishu-cli drive task-result --scenario import --ticket abcxxx
feishu-cli drive task-result --scenario import --ticket abcxxx

查询导出任务（需要额外传 file-token 作为原始文档 token）

查询导出任务（需要额外传 file-token 作为原始文档 token）

feishu-cli drive task-result --scenario export --ticket abcxxx --file-token docxxxx
feishu-cli drive task-result --scenario export --ticket abcxxx --file-token docxxxx

查询 folder move 等通用任务

查询 folder move 等通用任务

feishu-cli drive task-result --scenario task_check --task-id taskxxx

三种 scenario：`import` / `export` / `task_check`。用于 `drive export` / `drive import` / `drive move` 超时后的接力完成。
feishu-cli drive task-result --scenario task_check --task-id taskxxx

三种 scenario：`import` / `export` / `task_check`。用于 `drive export` / `drive import` / `drive move` 超时后的接力完成。

典型工作流

典型工作流

工作流 A：大文件分块上传 + 查看进度

工作流 A：大文件分块上传 + 查看进度

bash
feishu-cli drive upload --file big_video.mp4 --folder-token fldxxx --name "会议录像.mp4"
bash
feishu-cli drive upload --file big_video.mp4 --folder-token fldxxx --name "会议录像.mp4"

自动走分块，stderr 输出分片进度

自动走分块，stderr 输出分片进度

上传: 会议录像.mp4 (104857600 bytes)

上传: 会议录像.mp4 (104857600 bytes)

分片上传: 文件大小 100.0 MB, 分片大小 4.0 MB, 共 25 个分片

分片上传: 文件大小 100.0 MB, 分片大小 4.0 MB, 共 25 个分片

分片 1/25 上传完成 (4.0 MB)

分片 1/25 上传完成 (4.0 MB)

...

...

file_token 返回后可直接在飞书里访问

file_token 返回后可直接在飞书里访问

undefined
undefined

工作流 B：docx 批量导出 markdown

工作流 B：docx 批量导出 markdown

bash
undefined
bash
undefined

通过 /docs/v1/content 快捷路径，秒出不用等

通过 /docs/v1/content 快捷路径，秒出不用等

for doc_id in doc1 doc2 doc3; do feishu-cli drive export --token $doc_id --doc-type docx --file-extension markdown --output-dir ./docs done
undefined
for doc_id in doc1 doc2 doc3; do feishu-cli drive export --token $doc_id --doc-type docx --file-extension markdown --output-dir ./docs done
undefined

工作流 C：导出长文档（超时 resume）

工作流 C：导出长文档（超时 Resume）

bash
undefined
bash
undefined

1. 触发导出

1. 触发导出

TICKET=$(feishu-cli drive export --token docxxxxx --doc-type docx --file-extension pdf -o json | jq -r '.ticket // empty')
TICKET=$(feishu-cli drive export --token docxxxxx --doc-type docx --file-extension pdf -o json | jq -r '.ticket // empty')

2. 如果超时，输出会带 next_command

2. 如果超时，输出会带 next_command

手动或脚本化接力：

手动或脚本化接力：

feishu-cli drive task-result --scenario export --ticket $TICKET --file-token docxxxxx
feishu-cli drive task-result --scenario export --ticket $TICKET --file-token docxxxxx

3. 任务就绪后下载产物

3. 任务就绪后下载产物

feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
undefined
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports
undefined

工作流 D：wiki 链接一键评论

工作流 D：wiki 链接一键评论

bash
undefined
bash
undefined

不需要先解析 wiki 到 docx，drive add-comment 自动反查

不需要先解析 wiki 到 docx，drive add-comment 自动反查

feishu-cli drive add-comment
--doc "https://xxx.feishu.cn/wiki/nodxxxxx"
--content '[ {"type":"text","text":"收到，已处理 "}, {"type":"mention_user","mention_user":"ou_abc123"} ]'
undefined
feishu-cli drive add-comment
--doc "https://xxx.feishu.cn/wiki/nodxxxxx"
--content '[ {"type":"text","text":"收到，已处理 "}, {"type":"mention_user","mention_user":"ou_abc123"} ]'
undefined

工作流 E：本地 docx 导入为飞书文档

工作流 E：本地 docx 导入为飞书文档

bash
undefined
bash
undefined

drive import 走临时媒体（不污染云盘）

drive import 走临时媒体（不污染云盘）

feishu-cli drive import --file report.docx --type docx --folder-token fldxxx
feishu-cli drive import --file report.docx --type docx --folder-token fldxxx

大文件（>20MB）同样走分块

大文件（>20MB）同样走分块

feishu-cli drive import --file big_sheet.xlsx --type sheet --folder-token fldxxx
undefined
feishu-cli drive import --file big_sheet.xlsx --type sheet --folder-token fldxxx
undefined

与老命令的对照

与老命令的对照

老命令新 drive 命令差异
file upload
drive upload
drive 支持 User Token + 分块 + 每片重试
file download
drive download
drive 支持 User Token + 
--overwrite
+ 
--timeout
+ 路径校验
file move
drive move
drive 文件夹移动自动轮询 task_check
doc export-file --type pdf
drive export --doc-type docx --file-extension pdf
drive 增加 markdown 快捷路径 + sub-id + resume
doc import-file --type docx
drive import --type docx
drive 走 
/medias/upload_all
（不留中间文件）
comment add --type docx
drive add-comment --doc <url>
drive 支持富文本 + wiki 解析 + 局部评论
老命令不会被删除，仍然可以用（走 App Token 简单场景），但新能力只在 
drive
命令组里。
老命令新 drive 命令差异
file upload
drive upload
drive 支持 User Token + 分块 + 每片重试
file download
drive download
drive 支持 User Token + 
--overwrite
+ 
--timeout
+ 路径校验
file move
drive move
drive 文件夹移动自动轮询 task_check
doc export-file --type pdf
drive export --doc-type docx --file-extension pdf
drive 增加 Markdown 快捷路径 + sub-id + Resume
doc import-file --type docx
drive import --type docx
drive 走 
/medias/upload_all
（不留中间文件）
comment add --type docx
drive add-comment --doc <url>
drive 支持富文本 + Wiki 解析 + 局部评论
老命令不会被删除，仍然可以使用（适用于调用 App Token 的简单场景），但新能力仅在 
drive
命令组中提供。

权限要求

权限要求

命令所需 scope
drive upload
drive:file:upload
drive download
drive:file:download
drive export
/ 
export-download
docs:document.content:read
、
docs:document:export
、
drive:drive.metadata:readonly
、
drive:file:download
drive import
docs:document.media:upload
、
docs:document:import
drive move
space:document:move
drive add-comment
docs:document.comment:create
、
docs:document.comment:write_only
、
docx:document:readonly
（若 docx）、
wiki:node:read
（若 wiki URL）
drive task-result
drive:drive.metadata:readonly
命令所需 scope
drive upload
drive:file:upload
drive download
drive:file:download
drive export
/ 
export-download
docs:document.content:read
、
docs:document:export
、
drive:drive.metadata:readonly
、
drive:file:download
drive import
docs:document.media:upload
、
docs:document:import
drive move
space:document:move
drive add-comment
docs:document.comment:create
、
docs:document.comment:write_only
、
docx:document:readonly
（若为 docx）、
wiki:node:read
（若为 Wiki URL）
drive task-result
drive:drive.metadata:readonly

注意事项

注意事项

  • 默认 User Access Token：所有 
    drive
    命令未登录时会统一提示 
    feishu-cli auth login
  • SSRF 防护：下载 URL 会被校验，拒绝 localhost / 回环 IP / 内网段 / 链路本地
  • 重定向策略：下载 HTTP 重定向最多 5 次，禁止 HTTPS → HTTP 降级
  • 大文件分块阈值：固定 20MB，超过自动切分片
  • 导出有界轮询：10 次 × 5 秒（总共 50 秒），超时不报错而是返回 
    next_command
  • 导入有界轮询：30 次 × 2 秒（总共 60 秒），超时同上
  • 文件夹移动轮询：30 次 × 2 秒
  • 格式特定大小限制（import）：docx 20MB / sheet 20MB / bitable 100MB
  • add-comment 的 wiki 解析：只支持 obj_type 为 
    docx
    或 
    doc
    的 wiki 节点；其他类型（sheet/bitable/mindnote 等）会报错
  • 局部评论：仅 docx 支持 
    --block-id
    锚点，doc（旧版文档）不支持
  • 文件名规则： 
    • drive download
      ：
      --output
      为目录时使用 
      file_token
      作为文件名（不从响应头解析）；要自定义名字请显式传文件路径
    • minutes download
      （参见 feishu-cli-vc）：从响应头按 
      Content-Disposition > filename* > Content-Type 推导扩展名 > {token}.media
      优先级解析
  • 默认 User Access Token：所有 
    drive
    命令未登录时会统一提示 
    feishu-cli auth login
  • SSRF 防护：下载 URL 会被校验，拒绝 localhost / 回环 IP / 内网段 / 链路本地地址
  • 重定向策略：下载 HTTP 重定向最多 5 次，禁止 HTTPS → HTTP 降级
  • 大文件分块阈值：固定 20MB，超过自动切分分片
  • 导出有界轮询：10 次 × 5 秒（总共 50 秒），超时不报错而是返回 
    next_command
  • 导入有界轮询：30 次 × 2 秒（总共 60 秒），超时处理同上
  • 文件夹移动轮询：30 次 × 2 秒
  • 格式特定大小限制（导入）：docx 20MB / sheet 20MB / bitable 100MB
  • add-comment 的 Wiki 解析：仅支持 obj_type 为 
    docx
    或 
    doc
    的 Wiki 节点；其他类型（sheet/bitable/mindnote 等）会报错
  • 局部评论：仅 docx 支持 
    --block-id
    锚点，doc（旧版文档）不支持
  • 文件名规则： 
    • drive download
      ：
      --output
      为目录时使用 
      file_token
      作为文件名（不从响应头解析）；要自定义名字请显式传入文件路径
    • minutes download
      （参见 feishu-cli-vc）：从响应头按 
      Content-Disposition > filename* > Content-Type 推导扩展名 > {token}.media
      优先级解析