feishu-cli-drive

Feishu クラウドドライブの強化（Drive）

drive コマンドグループは、従来の file／media／comment add コマンドと併存する強化機能を提供します： 分割アップロード、Markdown の簡易エクスポート、非同期タスクの再開、リッチテキストコメント、wiki リンクの解析。

feishu-cli：まだインストールしていない場合は、riba2534/feishu-cli でインストール方法をご確認ください。

前提条件

• 認証：
  • User Token が必須（requireUserToken、未ログインの場合はエラーになります）：upload/download/export/export-download/import/move/add-comment/task-result/search/apply-permission。先に feishu-cli auth login を実行してください。
  • ログイン後は User を優先し、App をフォールバックとして使用（resolveOptionalUserTokenWithFallback、未ログインでもエラーになりません）：pull/push/status/inspect。auth login 済みの場合は自動的に User Token を使用します。未ログインの場合は App Token にフォールバックします（Bot は通常、クラウドドライブ内の個人ファイルを参照できない点にご注意ください）。
• 事前チェック：feishu-cli auth check --scope "drive:file:upload" で scope を確認できます

コマンド早見表

0. メタデータ／権限申請（v1.29+ で追加 ⭐）

# 解析任意文档 URL → 输出 type/title/canonical token（自动展开 wiki）
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"
feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx"   # 自动 wiki get_node
feishu-cli drive inspect --url doxcnxxx --type docx -o json            # 裸 token + JSON

# 向文档所有者申请权限（埋藏 API，飞书文档站未收录，但 lark-cli 已实现）
# 必需 User Token + docs:permission.member:apply scope（或 drive:drive 等任一大权限）
feishu-cli drive apply-permission --token "<url 或裸 token>" --perm view --remark "申请理由"
feishu-cli drive apply-permission --token doxcnxxx --type docx --perm edit --remark "..."
feishu-cli drive apply-permission --token <url> --perm view --dry-run    # 预览请求

詳しくは feishu-cli-toolkit/references/embedded-api-discovery.md（埋もれた API の調査方法）をご覧ください。

1. アップロード／ダウンロード

# 上传（>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"

# 下载（流式 + 路径校验 + --overwrite + --timeout，大文件自动 Range 分片兜底）
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 30m

重要なポイント：

• drive upload は分割アップロードを行い、各パートを個別に 3 回再試行します。外側では io.SectionReader を使用して、ファイルを開くのは 1 回だけです
• drive download の --output にはファイルパス（そのまま使用）またはディレクトリを指定できます（ファイル名には file_token 自体を使用します。現時点ではレスポンスヘッダーから取得しません）
• drive download でユーザーとしてダウンロードする際、サーバーから大容量ファイルの制限が返された場合は、自動的に HTTP Range で分割ダウンロードして結合します
• 独自のファイル名を指定する場合は、フルパスを明示してください：--output ./downloads/report.pdf

2. ドキュメントのエクスポート（Markdown の簡易パスを含む）

# docx → markdown：走 /docs/v1/content 快捷路径，立即返回（不跑异步 export_tasks）
feishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports

# docx → pdf：走异步 export_tasks，有界轮询 10×5s，超时返回 next_command
feishu-cli drive export --token docxxxx --doc-type docx --file-extension pdf --output-dir ./exports

# sheet → csv 指定 sheet_id
feishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1

# 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 のみ対応）

タイムアウト後の再開手順：

# drive export 超时会输出：
# next_command: feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

# 1. 轮询任务状态
feishu-cli drive task-result --scenario export --ticket abc --file-token xxx

# 2. 任务完成后下载产物
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports

3. drive export-download — エクスポートが完了したファイルをダウンロード

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

4. ドキュメントのインポート

# 本地文件 → 云文档（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

# 注意：docx/sheet 导入上限 20MB，bitable 上限 100MB

重要な技術ポイント：

• 公式の /medias/upload_all エンドポイント（parent_type=ccm_import_open + extra）を使用し、ユーザーのクラウドドライブに中間ファイルを残しません（従来の doc import-file との主な違いです）
• フォーマットごとのサイズ制限：docx 20MB／sheet 20MB／bitable 100MB。docx／sheet が 20MB を超えると直接エラーになり、フォーマットの制限を自動的に回避することはありません。
• 上限付きポーリングは 30×2s です。タイムアウト時は next_command を返します

5. 移動（フォルダーの自動ポーリング）

# 文件移动（同步，立即返回）
feishu-cli drive move --file-token boxxxx --type docx --folder-token fldxxx

# 文件夹移动（异步，自动轮询 task_check 30×2s）
feishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy

重要なポイント：

• フォルダーの移動は自動でポーリングされ、「送信したらあとは放置」ではありません
• タイムアウト時は task_id が返されます。drive task-result --scenario task_check で引き継げます

6. リッチテキストコメント（最も強力なコマンド）

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

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

# 通过 wiki URL（自动解析到真实 docx）
feishu-cli drive add-comment --doc "https://xxx.feishu.cn/wiki/nodxxxx" \
  --content '[{"type":"text","text":"收到"}]'

# 局部评论（锚定到 docx block）
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 トークン（そのまま指定）
• docx URL（https://xxx.feishu.cn/docx/xxx）
• doc URL（旧版ドキュメント）
• wiki URL（実際の obj_token + obj_type に自動解析）

7. 汎用の非同期タスク照会

# 查询导入任务
feishu-cli drive task-result --scenario import --ticket abcxxx

# 查询导出任务（需要额外传 file-token 作为原始文档 token）
feishu-cli drive task-result --scenario export --ticket abcxxx --file-token docxxxx

# 查询 folder move 等通用任务
feishu-cli drive task-result --scenario task_check --task-id taskxxx

scenario は import / export / task_check の 3 種類です。drive export／drive import／drive move がタイムアウトした後、処理を引き継いで完了するために使用します。

8. ローカル ↔ クラウドドライブの一方向ミラーリング（pull/push/status）

クラウドドライブのフォルダーとローカルディレクトリを一方向にミラーリングします。SHA-256 による内容比較と、--delete-* --yes の二重確認による安全スイッチを備えています。ミラーリングの対象は type=file の項目のみです。docx／sheet／bitable／mindnote／slides／shortcut などのオンラインドキュメントは、同等のローカルバイナリがないため対象外です。

# status：双向 SHA-256 对照，只读，不动文件
feishu-cli drive status --folder-token fldxxx --local-dir ./mirror
# 输出 4 个桶：new_local / new_remote / modified / unchanged

# pull：云盘 → 本地，递归下载
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --if-exists skip
feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --delete-local --yes

# push：本地 → 云盘，递归上传，自动 create_folder 镜像目录结构
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror              # 默认 --if-exists=skip
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --if-exists overwrite
feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --delete-remote --yes

安全性の仕様：

• --local-dir は filepath.EvalSymlinks を通し、cwd のサブツリー内に制限して、シンボリックリンクによる範囲外へのアクセスを防止します
• --delete-local／--delete-remote には --yes の指定が必須です。--yes がなければ実行を拒否します
• アップロード／ダウンロード中に失敗が発生した場合、--delete-* の処理を自動的にスキップし、「不要なファイルを削除した後、一部のファイルの転送に失敗した」という中途半端な同期状態を防ぎます
• pull のデフォルトは --if-exists=overwrite（ローカル = リモートを維持）、push のデフォルトは --if-exists=skip（リモートにあるファイルを変更しないため、より安全です）

9. v2 エンドポイント検索（drive search、フラットな filter）

/open-apis/search/v2/doc_wiki/search エンドポイントを使用します。search docs（v1）よりも豊富なフラット filter に対応しています：

# 关键字 + 类型过滤 + 排序
feishu-cli drive search --query "季度报告" --doc-types DOCX,SHEET --sort edit_time

# 限定在某些云盘文件夹（与 --space-ids 互斥）
feishu-cli drive search --query "API 设计" --folder-tokens fldxxx,fldyyy

# 限定在知识库 space
feishu-cli drive search --query "RFC" --space-ids spcxxx

# 仅匹配标题（避免正文里命中无关结果）
feishu-cli drive search --query "项目周会" --only-title

# 按创建人
feishu-cli drive search --query "复盘" --creator-ids ou_xxx,ou_yyy

# JSON 输出 + 分页
feishu-cli drive search --query "项目" --page-size 20 -o json
feishu-cli drive search --query "项目" --page-token "<上一页 page_token>"

重要なポイント：

• --doc-types の値は大文字です：DOC / DOCX / SHEET / BITABLE / MINDNOTE / FILE / WIKI / FOLDER / CATALOG / SLIDES / SHORTCUT
• --folder-tokens と --space-ids は相互に排他的です（doc／wiki の 2 つの範囲）
• タイトルフィールドには <h>...</h> のハイライトマーカーが含まれます。CLI が自動的に除去します
• search docs（v1 /suite/docs-api/search/object）と併存します。v1 は owner_ids/chat_ids による簡易フィルター、v2 は doc_filter+wiki_filter による 2 経路の詳細なフィルターを使用します

代表的なワークフロー

ワークフロー A：大容量ファイルを分割アップロードして進捗を確認

feishu-cli drive upload --file big_video.mp4 --folder-token fldxxx --name "会议录像.mp4"
# 自动走分块，stderr 输出分片进度
# 上传: 会议录像.mp4 (104857600 bytes)
# 分片上传: 文件大小 100.0 MB, 分片大小 4.0 MB, 共 25 个分片
#   分片 1/25 上传完成 (4.0 MB)
#   ...
# file_token 返回后可直接在飞书里访问

ワークフロー B：複数の docx を Markdown にエクスポート

# 通过 /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

ワークフロー C：長いドキュメントをエクスポート（タイムアウト後に再開）

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

# 2. 如果超时，输出会带 next_command
#    手动或脚本化接力：
feishu-cli drive task-result --scenario export --ticket $TICKET --file-token docxxxxx

# 3. 任务就绪后下载产物
feishu-cli drive export-download --file-token boxxxx --output-dir ./exports

ワークフロー D：wiki リンクからワンクリックでコメント

# 不需要先解析 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"}
  ]'

ワークフロー E：ローカルの docx を Feishu ドキュメントとしてインポート

# drive import 走临时媒体（不污染云盘）
feishu-cli drive import --file report.docx --type docx --folder-token fldxxx

# 20MB 以上表格文件请导入为 bitable（上限 100MB）
feishu-cli drive import --file big_sheet.xlsx --type bitable --folder-token fldxxx

ワークフロー F：ドキュメントの権限を申請（apply-permission）

「このドキュメントを閲覧する権限がありません」と表示された場合、Feishu IM でドキュメント所有者に個別連絡する必要はありません。ターミナルから直接申請できます：

# 1. 先用 inspect 确认 token 类型（可选；apply-permission 也支持 URL 直接传）
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"
# → 输出 type=docx, title=..., token=doxcnxxx

# 2. 申请只读权限（带申请说明，会出现在发给所有者的审批卡片上）
feishu-cli drive apply-permission \
  --token "https://xxx.feishu.cn/docx/doxcnxxx" \
  --perm view \
  --remark "调研 RFC，需要查看背景设计"

# 3. 申请编辑权限（同一接口，--perm edit）
feishu-cli drive apply-permission --token doxcnxxx --type docx --perm edit --remark "..."

# 4. 预览即将发出的请求（不实际申请）
feishu-cli drive apply-permission --token <url> --perm view --dry-run

⚠️ これは「埋もれた API」（Feishu のドキュメントサイトには掲載されていませんが、lark-cli ではすでに実装されています）です。User Token と docs:permission.member:apply scope（または drive:drive などの大規模な権限）が必須です。

ワークフロー G：URL から token／タイトル／タイプを 1 行のコマンドで解析（inspect）

スクリプトやエージェントのオーケストレーションでは、URL からドキュメントのメタデータを逆引きすることがよくあります。inspect が最短の方法です：

# docx URL → 输出 type=docx + 标题 + 裸 token + canonical URL
feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxcnxxx"

# wiki URL → 自动展开到底层文档（自动调 wiki get_node 拆 obj_token + obj_type）
feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx"
# → 输出 type=docx, token=<真实 docx token>

# 裸 token + 显式 type → 拿标题做权限/分类
feishu-cli drive inspect --url doxcnxxx --type docx

# JSON 输出（脚本/Agent 友好）
TOKEN=$(feishu-cli drive inspect --url <url> -o json | jq -r '.token')
TITLE=$(feishu-cli drive inspect --url <url> -o json | jq -r '.title')

# 与其他命令串起来：解析 wiki → 导出 markdown
DOC_TOKEN=$(feishu-cli drive inspect --url "https://xxx.feishu.cn/wiki/wikcnxxx" -o json | jq -r '.token')
feishu-cli drive export --token $DOC_TOKEN --doc-type docx --file-extension markdown --output-dir ./out

他のコマンドとの違い：inspect は読み取り専用で、User Token を必須としません（User を優先し、App をフォールバックとして使用）。未ログインでも、公開ドキュメントや Bot が参照できるドキュメントのメタデータを確認できます。ログイン後は User Token を使用し、完全な権限範囲で確認します。

与老命令的对照

老命令	新 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 命令组里。

权限要求

命令	Token 策略	所需 scope
drive upload	必需 User Token	drive:file:upload
drive download	必需 User Token	drive:file:download
drive export	必需 User Token	docs:document:export、drive:drive.metadata:readonly（导出 markdown 还需 docs:document.content:read）
drive export-download	必需 User Token	drive:file:download
drive import	必需 User Token	docs:document:import、drive:file:upload
drive move	必需 User Token	drive:file:write 1
drive add-comment	必需 User Token	docs:document.comment:create、docs:document.comment:write_only；wiki URL 还需 wiki:node:read；docx 局部评论还需 docx:document:readonly
drive task-result	必需 User Token	drive:drive.metadata:readonly（具体依 scenario：import 还需 docs:document:import；export 还需 docs:document:export）
drive pull / status	User 优先 + App 兜底	drive:drive.metadata:readonly、drive:file:download
drive push	User 优先 + App 兜底	drive:drive.metadata:readonly、drive:file:upload、space:folder:create；带 --delete-remote 还需 drive:file:delete
drive search	必需 User Token	search:docs:read
drive inspect	User 优先 + App 兜底（不强制 User Token）	drive:drive.metadata:readonly；wiki URL 还需 wiki:node:read
drive apply-permission	必需 User Token	docs:permission.member:apply（或任一大权限：drive:drive / docs:doc / docx:document 等）

注意事项

• Token 策略：upload/download/export/export-download/import/move/add-comment/task-result/search/apply-permission 必需 User Token；pull/push/status/inspect 登录后默认 User Token，未登录回落 App Token。
• 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 优先级解析

Footnotes

1. drive:file:write 是 CLI help 与代码当前声明的 scope；飞书部分 API 文档历史上也提到 space:document:move，具体以飞书最新 OpenAPI 文档为准。两者覆盖同一动作，新版应用直接申请 drive:file:write（更通用，写类操作通用 scope）。 ↩