飞书 CLIdocs media-download完全指南下载文档素材与画板缩略图【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli导读本文以 lark-cli 官方技能文档 lark-doc-media-download.md 为主体系统讲解docs media-download命令的使用场景、参数语义、底层 API 调用链与扩展名自动补全机制。读完本文你将掌握从飞书云文档中提取图片/文件素材 token 并安全下载到本地的完整流程理解media与whiteboard两种资源类型的差异并能独立排障权限HTTP 403与限流错误。命令定位它解决什么问题docs media-download是 lark-cli 中负责下载文档内嵌资源的命令覆盖两类资源文档素材media文档中引用的图片或文件附件通过file_token定位画板缩略图whiteboard白板画板页面的缩略图通过whiteboard_id定位。它的核心特性是当--output指定的路径不带扩展名时命令会根据响应头的Content-Type或Content-Disposition中的文件名自动补全扩展名避免手动猜测文件类型。在源码中该命令被注册为Service: docs、Command: media-download、Risk: read只读操作定义于 shortcuts/doc/doc_media_download.go并挂载在docs命令组下见 shortcuts/doc/shortcuts.go。选择规则download 与 preview 如何取舍同一文档素材存在两个高度相关的命令需要按用户意图区分场景使用命令用户明确说“下载素材”docs media-download用户只是想查看、预览图片或文件素材优先使用docs media-preview目标明确是画板 / whiteboard / 画板缩略图docs media-download --type whiteboardmedia-preview不支持画板从源码实现看两个命令底层都调用了扩展名自动补全逻辑autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go但media-preview仅支持file_token素材不提供--type whiteboard分支而media-download的whiteboard分支会调用完全不同的 API详见下文“底层调用链”。命令用法三种典型场景# 场景一下载图片/文件素材默认 typemedia lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset # 场景二指定输出文件名带扩展名则不会自动补全 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset.png # 场景三下载画板缩略图whiteboard token lark-cli docs media-download --type whiteboard --token wbcnxxxxxxxx --output ./whiteboard关于“带扩展名不补全”的细节源码 doc_media_download.go 展示了补全前的处理逻辑whiteboard类型有兜底扩展名fallbackExt .png画板缩略图必然是 PNGmedia类型没有兜底必须依赖响应头推断若--output以filepath.Ext判定为“已有显式扩展名”且不是孤立的.则跳过补全直接按原路径保存若路径以尾点xxx.结尾会先去掉尾点再补全例如typed.→typed.csv这一行为由测试 TestDocMediaDownloadAppendsExtensionForTrailingDotOutput 验证。参数详解必填项与可选语义原文档的参数表如下参数必填说明--token token是资源 token素材为file_token画板为whiteboard_id--output path是本地保存路径不带扩展名会自动补全--type type否media默认或whiteboard结合源码 doc_media_download.go 的 Shortcut 定义还有两个原文档未列出的重要参数参数必填说明--overwrite否bool是否覆盖已存在的输出文件。默认不覆盖若目标文件已存在命令返回FailedPrecondition错误并提示“use --overwrite to replace”--as否身份选择user或bot。该命令的AuthTypes声明为[user, bot]--as user代表用户本人下载--as bot代表应用身份下载参数校验与安全约束执行时会先做两类校验doc_media_download.gotoken 校验validate.ResourceName(token, --token)校验资源名合法性失败返回InvalidArgument输出路径安全校验runtime.ResolveSavePath(outputPath)只接受相对路径。这与共享规则一致——lark-shared 明确规定--file、--output等路径参数只接受 cwd 下的相对路径传绝对路径会报unsafe file path详见 skills/lark-shared/SKILL.md 安全规则第 5 条。补全扩展名后的最终路径同样会再次校验。下载完成后命令以 JSON 形式输出结果doc_media_download.go{ saved_path: ./asset.png, size_bytes: 20480, content_type: image/png }底层调用链两条 API 路径--type决定最终请求的 OpenAPI 端点这一逻辑在 doc_media_download.go 中明确--type media默认GET /open-apis/drive/v1/medias/{token}/download--type whiteboardGET /open-apis/board/v1/whiteboards/{token}/download_as_image两者的差异不仅在端点还体现在权限预检上media模式在下载前会调用common.CheckDriveFileExportPermission(runtime, token)检查当前身份是否具备文档素材的导出权限对应 dry-run 中的第一步请求GET /open-apis/drive/v1/permissions/{token}/members/auth?typefileactionexportwhiteboard模式跳过导出权限预检直接请求画板下载端点。这些差异可由 dry-run 输出与测试验证TestDocMediaDownloadDryRunIncludesExportAuthBeforeDownload 断言media模式 dry-run 包含 2 个 API先导出权限检查、后媒体下载TestDocWhiteboardDownloadDryRunSkipsExportAuth 断言whiteboard模式 dry-run 只有 1 个 API/open-apis/board/v1/whiteboards/.../download_as_image。dry-run 预览能力来自 Shortcut 的DryRun字段doc_media_download.go配合 lark-shared 安全规则“目标命令支持--dry-run时用--dry-run预览危险请求”是调用前的推荐动作。权限与 scope该命令声明的权限 scope 为docs:document.media:download并带有一个条件 scopeDrivePermissionMemberAuthScope仅当需要导出权限检查时才会触发。ConditionalScopes的存在意味着对某些身份/资源命令可能额外需要 Drive 成员权限相关断言见 TestDocMediaDownloadDeclaresConditionalPermissionMemberAuthScope。扩展名自动补全完整优先级链autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go按如下优先级推断扩展名显式扩展名优先--output已含非空扩展名非.时直接返回不做任何推断Content-Type 映射解析响应头Content-Type查表docMediaMimeToExtdoc_media_ext.go覆盖常见类型例如image/png → .png、image/jpeg → .jpg、application/pdf → .pdf、text/csv → .csv、video/mp4 → .mp4、application/vnd.openxmlformats-officedocument.wordprocessingml.document → .docx等Content-Disposition 文件名若 Content-Type 未命中则从Content-Disposition: attachment; filename...中提取原文件名扩展名兜底扩展名仅whiteboard类型使用.png兜底media类型若无命中则保持原路径不变。测试 TestDocMediaDownloadAppendsExtensionFromContentTypeMapping 与 TestDocMediaDownloadAppendsExtensionFromContentDispositionFilename 分别验证了第 2、3 条路径后者模拟了Content-Type: application/octet-stream无法映射、但Content-Disposition带drive_registry_config_addition.csv文件名时补全为.csv的场景。token 从哪里来配合lark-doc-fetch使用素材 token 最常见的来源是lark-cli docs fetch返回的文档内容。使用--doc-format xml默认时内嵌资源会以 XML 标签形式出现详见 lark-doc-fetch.md 中“处理文档内嵌资源”一节图片img token... .../文件source token... name.../画板whiteboard token.../提取规则与 fetch 文档一致标签内有url属性时仅当其为可信的公开 HTTPS URL拒绝 userinfo、私有/回环/链路本地/组播/未指定地址 host才可直接下载无url时提取token预览用docs media-preview下载用docs media-downloadwhiteboard一律提取 token 后走docs media-downloadfetch 文档明确指示画板不用 preview。由此形成完整工作流# 第一步获取文档内容提取 token lark-cli docs fetch --doc 文档URL或token --doc-format xml # 第二步根据提取的 token 下载素材 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset排障两类典型错误1. 权限错误permission_denied与 HTTP 403当导出权限预检失败时命令返回permission_denied当下载请求本身返回HTTP 403时错误处理器withDocMediaDownloadRecoveryHintshortcuts/doc/doc_errors.go会在保留原始错误的同时在hint中追加恢复指引Direct document media download returned HTTP 403. To preview the image or file content, trylark-cli docs media-preview --token MEDIA_TOKEN --output path.也就是说遇到 403 时按 hint 改用docs media-preview预览内容见 lark-doc-media-preview.md这是文档推荐的降级路径。注意两点实现细节该 403 恢复提示仅对media类型生效whiteboard 走的是独立 APIwithDocMediaDownloadRecoveryHint明确不把画板下载重定向到 media-preview导出权限检查若返回的是权限类错误如LarkErrAppScopeNotEnabled、LarkErrTokenNoPermission、LarkErrUserScopeInsufficient命令会打印 warning 后继续下载而不是直接中止doc_media_download.go相关行为由 TestDocMediaDownloadPermissionAuthScopeErrorsWarnAndContinue 验证只有检查结果为“明确无权限”allowed false时才在下载前中止。2. 限流错误停止立即重试指数退避限流判定涵盖三类信号doc_errors.go错误子类型SubtypeRateLimit、业务错误码99991400、HTTP 状态码429。命中后 hint 会追加Document media download was rate limited; stop immediate retries and retry later with exponential backoff.即停止立即重试稍后按指数退避重试。相关测试包括 TestDocMediaDownloadHTTP429SuggestsBackoff、TestDocMediaDownloadExportAuthRateLimitPreservesAPIErrorAndSuggestsBackoff 等。其他值得注意的行为覆盖保护默认若目标文件已存在则拒绝写入FailedPrecondition需要显式加--overwrite。该行为由 TestDocMediaDownloadRejectsOverwriteWithoutFlag 验证且覆盖检查发生在扩展名补全之后对最终路径判断HTTP 错误先于落盘暴露请求失败时不会创建半截文件见 TestDocMediaDownloadRejectsHTTPErrorBeforeWrite导出被拒在下载前拦截权限预检不通过时直接报错避免无谓请求见 TestDocMediaDownloadExportDeniedFailsBeforeDownload身份模型命令支持user/bot两种身份--as的选择逻辑与身份权限差异bot 查用户资源返回空成功而非报错参见 skills/lark-shared/SKILL.md。参考文档lark-doc-fetch — 获取文档内容用于提取素材/画板 tokenlark-doc-media-preview — 预览素材403 降级路径、与 download 的选择区分lark-shared — 认证、--as身份模型、相对路径安全规则与 JSON 输出契约【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考