飛書 CLIdocs media-download完全指南下載文檔素材與畫板縮略圖【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cli414/cli導(dǎo)讀本文以 lark-cli 官方技能文檔 lark-doc-media-download.md 為主體系統(tǒng)講解docs media-download命令的使用場(chǎng)景、參數(shù)語義、底層 API 調(diào)用鏈與擴(kuò)展名自動(dòng)補(bǔ)全機(jī)制。讀完本文你將掌握從飛書云文檔中提取圖片/文件素材 token 并安全下載到本地的完整流程理解media與whiteboard兩種資源類型的差異并能獨(dú)立排障權(quán)限HTTP 403與限流錯(cuò)誤。命令定位它解決什么問題docs media-download是 lark-cli 中負(fù)責(zé)下載文檔內(nèi)嵌資源的命令覆蓋兩類資源文檔素材media文檔中引用的圖片或文件附件通過file_token定位畫板縮略圖whiteboard白板畫板頁(yè)面的縮略圖通過whiteboard_id定位。它的核心特性是當(dāng)--output指定的路徑不帶擴(kuò)展名時(shí)命令會(huì)根據(jù)響應(yīng)頭的Content-Type或Content-Disposition中的文件名自動(dòng)補(bǔ)全擴(kuò)展名避免手動(dòng)猜測(cè)文件類型。在源碼中該命令被注冊(cè)為Service: docs、Command: media-download、Risk: read只讀操作定義于 shortcuts/doc/doc_media_download.go并掛載在docs命令組下見 shortcuts/doc/shortcuts.go。選擇規(guī)則download 與 preview 如何取舍同一文檔素材存在兩個(gè)高度相關(guān)的命令需要按用戶意圖區(qū)分場(chǎng)景使用命令用戶明確說“下載素材”docs media-download用戶只是想查看、預(yù)覽圖片或文件素材優(yōu)先使用docs media-preview目標(biāo)明確是畫板 / whiteboard / 畫板縮略圖docs media-download --type whiteboardmedia-preview不支持畫板從源碼實(shí)現(xiàn)看兩個(gè)命令底層都調(diào)用了擴(kuò)展名自動(dòng)補(bǔ)全邏輯autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go但media-preview僅支持file_token素材不提供--type whiteboard分支而media-download的whiteboard分支會(huì)調(diào)用完全不同的 API詳見下文“底層調(diào)用鏈”。命令用法三種典型場(chǎng)景# 場(chǎng)景一下載圖片/文件素材默認(rèn) typemedia lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset # 場(chǎng)景二指定輸出文件名帶擴(kuò)展名則不會(huì)自動(dòng)補(bǔ)全 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset.png # 場(chǎng)景三下載畫板縮略圖whiteboard token lark-cli docs media-download --type whiteboard --token wbcnxxxxxxxx --output ./whiteboard關(guān)于“帶擴(kuò)展名不補(bǔ)全”的細(xì)節(jié)源碼 doc_media_download.go 展示了補(bǔ)全前的處理邏輯whiteboard類型有兜底擴(kuò)展名fallbackExt .png畫板縮略圖必然是 PNGmedia類型沒有兜底必須依賴響應(yīng)頭推斷若--output以filepath.Ext判定為“已有顯式擴(kuò)展名”且不是孤立的.則跳過補(bǔ)全直接按原路徑保存若路徑以尾點(diǎn)xxx.結(jié)尾會(huì)先去掉尾點(diǎn)再補(bǔ)全例如typed.→typed.csv這一行為由測(cè)試 TestDocMediaDownloadAppendsExtensionForTrailingDotOutput 驗(yàn)證。參數(shù)詳解必填項(xiàng)與可選語義原文檔的參數(shù)表如下參數(shù)必填說明--token token是資源 token素材為file_token畫板為whiteboard_id--output path是本地保存路徑不帶擴(kuò)展名會(huì)自動(dòng)補(bǔ)全--type type否media默認(rèn)或whiteboard結(jié)合源碼 doc_media_download.go 的 Shortcut 定義還有兩個(gè)原文檔未列出的重要參數(shù)參數(shù)必填說明--overwrite否bool是否覆蓋已存在的輸出文件。默認(rèn)不覆蓋若目標(biāo)文件已存在命令返回FailedPrecondition錯(cuò)誤并提示“use --overwrite to replace”--as否身份選擇user或bot。該命令的AuthTypes聲明為[user, bot]--as user代表用戶本人下載--as bot代表應(yīng)用身份下載參數(shù)校驗(yàn)與安全約束執(zhí)行時(shí)會(huì)先做兩類校驗(yàn)doc_media_download.gotoken 校驗(yàn)validate.ResourceName(token, --token)校驗(yàn)資源名合法性失敗返回InvalidArgument輸出路徑安全校驗(yàn)runtime.ResolveSavePath(outputPath)只接受相對(duì)路徑。這與共享規(guī)則一致——lark-shared 明確規(guī)定--file、--output等路徑參數(shù)只接受 cwd 下的相對(duì)路徑傳絕對(duì)路徑會(huì)報(bào)unsafe file path詳見 skills/lark-shared/SKILL.md 安全規(guī)則第 5 條。補(bǔ)全擴(kuò)展名后的最終路徑同樣會(huì)再次校驗(yàn)。下載完成后命令以 JSON 形式輸出結(jié)果doc_media_download.go{ saved_path: ./asset.png, size_bytes: 20480, content_type: image/png }底層調(diào)用鏈兩條 API 路徑--type決定最終請(qǐng)求的 OpenAPI 端點(diǎn)這一邏輯在 doc_media_download.go 中明確--type media默認(rèn)GET /open-apis/drive/v1/medias/{token}/download--type whiteboardGET /open-apis/board/v1/whiteboards/{token}/download_as_image兩者的差異不僅在端點(diǎn)還體現(xiàn)在權(quán)限預(yù)檢上media模式在下載前會(huì)調(diào)用common.CheckDriveFileExportPermission(runtime, token)檢查當(dāng)前身份是否具備文檔素材的導(dǎo)出權(quán)限對(duì)應(yīng) dry-run 中的第一步請(qǐng)求GET /open-apis/drive/v1/permissions/{token}/members/auth?typefileactionexportwhiteboard模式跳過導(dǎo)出權(quán)限預(yù)檢直接請(qǐng)求畫板下載端點(diǎn)。這些差異可由 dry-run 輸出與測(cè)試驗(yàn)證TestDocMediaDownloadDryRunIncludesExportAuthBeforeDownload 斷言media模式 dry-run 包含 2 個(gè) API先導(dǎo)出權(quán)限檢查、后媒體下載TestDocWhiteboardDownloadDryRunSkipsExportAuth 斷言whiteboard模式 dry-run 只有 1 個(gè) API/open-apis/board/v1/whiteboards/.../download_as_image。dry-run 預(yù)覽能力來自 Shortcut 的DryRun字段doc_media_download.go配合 lark-shared 安全規(guī)則“目標(biāo)命令支持--dry-run時(shí)用--dry-run預(yù)覽危險(xiǎn)請(qǐng)求”是調(diào)用前的推薦動(dòng)作。權(quán)限與 scope該命令聲明的權(quán)限 scope 為docs:document.media:download并帶有一個(gè)條件 scopeDrivePermissionMemberAuthScope僅當(dāng)需要導(dǎo)出權(quán)限檢查時(shí)才會(huì)觸發(fā)。ConditionalScopes的存在意味著對(duì)某些身份/資源命令可能額外需要 Drive 成員權(quán)限相關(guān)斷言見 TestDocMediaDownloadDeclaresConditionalPermissionMemberAuthScope。擴(kuò)展名自動(dòng)補(bǔ)全完整優(yōu)先級(jí)鏈autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go按如下優(yōu)先級(jí)推斷擴(kuò)展名顯式擴(kuò)展名優(yōu)先--output已含非空擴(kuò)展名非.時(shí)直接返回不做任何推斷Content-Type 映射解析響應(yīng)頭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...中提取原文件名擴(kuò)展名兜底擴(kuò)展名僅whiteboard類型使用.png兜底media類型若無命中則保持原路徑不變。測(cè)試 TestDocMediaDownloadAppendsExtensionFromContentTypeMapping 與 TestDocMediaDownloadAppendsExtensionFromContentDispositionFilename 分別驗(yàn)證了第 2、3 條路徑后者模擬了Content-Type: application/octet-stream無法映射、但Content-Disposition帶drive_registry_config_addition.csv文件名時(shí)補(bǔ)全為.csv的場(chǎng)景。token 從哪里來配合lark-doc-fetch使用素材 token 最常見的來源是lark-cli docs fetch返回的文檔內(nèi)容。使用--doc-format xml默認(rèn)時(shí)內(nèi)嵌資源會(huì)以 XML 標(biāo)簽形式出現(xiàn)詳見 lark-doc-fetch.md 中“處理文檔內(nèi)嵌資源”一節(jié)圖片img token... .../文件source token... name.../畫板whiteboard token.../提取規(guī)則與 fetch 文檔一致標(biāo)簽內(nèi)有url屬性時(shí)僅當(dāng)其為可信的公開 HTTPS URL拒絕 userinfo、私有/回環(huán)/鏈路本地/組播/未指定地址 host才可直接下載無url時(shí)提取token預(yù)覽用docs media-preview下載用docs media-downloadwhiteboard一律提取 token 后走docs media-downloadfetch 文檔明確指示畫板不用 preview。由此形成完整工作流# 第一步獲取文檔內(nèi)容提取 token lark-cli docs fetch --doc 文檔URL或token --doc-format xml # 第二步根據(jù)提取的 token 下載素材 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset排障兩類典型錯(cuò)誤1. 權(quán)限錯(cuò)誤permission_denied與 HTTP 403當(dāng)導(dǎo)出權(quán)限預(yù)檢失敗時(shí)命令返回permission_denied當(dāng)下載請(qǐng)求本身返回HTTP 403時(shí)錯(cuò)誤處理器withDocMediaDownloadRecoveryHintshortcuts/doc/doc_errors.go會(huì)在保留原始錯(cuò)誤的同時(shí)在hint中追加恢復(fù)指引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 時(shí)按 hint 改用docs media-preview預(yù)覽內(nèi)容見 lark-doc-media-preview.md這是文檔推薦的降級(jí)路徑。注意兩點(diǎn)實(shí)現(xiàn)細(xì)節(jié)該 403 恢復(fù)提示僅對(duì)media類型生效whiteboard 走的是獨(dú)立 APIwithDocMediaDownloadRecoveryHint明確不把畫板下載重定向到 media-preview導(dǎo)出權(quán)限檢查若返回的是權(quán)限類錯(cuò)誤如LarkErrAppScopeNotEnabled、LarkErrTokenNoPermission、LarkErrUserScopeInsufficient命令會(huì)打印 warning 后繼續(xù)下載而不是直接中止doc_media_download.go相關(guān)行為由 TestDocMediaDownloadPermissionAuthScopeErrorsWarnAndContinue 驗(yàn)證只有檢查結(jié)果為“明確無權(quán)限”allowed false時(shí)才在下載前中止。2. 限流錯(cuò)誤停止立即重試指數(shù)退避限流判定涵蓋三類信號(hào)doc_errors.go錯(cuò)誤子類型SubtypeRateLimit、業(yè)務(wù)錯(cuò)誤碼99991400、HTTP 狀態(tài)碼429。命中后 hint 會(huì)追加Document media download was rate limited; stop immediate retries and retry later with exponential backoff.即停止立即重試稍后按指數(shù)退避重試。相關(guān)測(cè)試包括 TestDocMediaDownloadHTTP429SuggestsBackoff、TestDocMediaDownloadExportAuthRateLimitPreservesAPIErrorAndSuggestsBackoff 等。其他值得注意的行為覆蓋保護(hù)默認(rèn)若目標(biāo)文件已存在則拒絕寫入FailedPrecondition需要顯式加--overwrite。該行為由 TestDocMediaDownloadRejectsOverwriteWithoutFlag 驗(yàn)證且覆蓋檢查發(fā)生在擴(kuò)展名補(bǔ)全之后對(duì)最終路徑判斷HTTP 錯(cuò)誤先于落盤暴露請(qǐng)求失敗時(shí)不會(huì)創(chuàng)建半截文件見 TestDocMediaDownloadRejectsHTTPErrorBeforeWrite導(dǎo)出被拒在下載前攔截權(quán)限預(yù)檢不通過時(shí)直接報(bào)錯(cuò)避免無謂請(qǐng)求見 TestDocMediaDownloadExportDeniedFailsBeforeDownload身份模型命令支持user/bot兩種身份--as的選擇邏輯與身份權(quán)限差異bot 查用戶資源返回空成功而非報(bào)錯(cuò)參見 skills/lark-shared/SKILL.md。參考文檔lark-doc-fetch — 獲取文檔內(nèi)容用于提取素材/畫板 tokenlark-doc-media-preview — 預(yù)覽素材403 降級(jí)路徑、與 download 的選擇區(qū)分lark-shared — 認(rèn)證、--as身份模型、相對(duì)路徑安全規(guī)則與 JSON 輸出契約【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cli414/cli創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 飛書 CLI `docs +media-download` 完全指南：下載文檔素材與畫板縮略圖
飛書 CLIdocs media-download完全指南下載文檔素材與畫板縮略圖【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cli414/cli導(dǎo)讀本文以 lark-cli 官方技能文檔 lark-doc-media-download.md 為主體系統(tǒng)講解docs media-download命令的使用場(chǎng)景、參數(shù)語義、底層 API 調(diào)用鏈與擴(kuò)展名自動(dòng)補(bǔ)全機(jī)制。讀完本文你將掌握從飛書云文檔中提取圖片/文件素材 token 并安全下載到本地的完整流程理解media與whiteboard兩種資源類型的差異并能獨(dú)立排障權(quán)限HTTP 403與限流錯(cuò)誤。命令定位它解決什么問題docs media-download是 lark-cli 中負(fù)責(zé)下載文檔內(nèi)嵌資源的命令覆蓋兩類資源文檔素材media文檔中引用的圖片或文件附件通過file_token定位畫板縮略圖whiteboard白板畫板頁(yè)面的縮略圖通過whiteboard_id定位。它的核心特性是當(dāng)--output指定的路徑不帶擴(kuò)展名時(shí)命令會(huì)根據(jù)響應(yīng)頭的Content-Type或Content-Disposition中的文件名自動(dòng)補(bǔ)全擴(kuò)展名避免手動(dòng)猜測(cè)文件類型。在源碼中該命令被注冊(cè)為Service: docs、Command: media-download、Risk: read只讀操作定義于 shortcuts/doc/doc_media_download.go并掛載在docs命令組下見 shortcuts/doc/shortcuts.go。選擇規(guī)則download 與 preview 如何取舍同一文檔素材存在兩個(gè)高度相關(guān)的命令需要按用戶意圖區(qū)分場(chǎng)景使用命令用戶明確說“下載素材”docs media-download用戶只是想查看、預(yù)覽圖片或文件素材優(yōu)先使用docs media-preview目標(biāo)明確是畫板 / whiteboard / 畫板縮略圖docs media-download --type whiteboardmedia-preview不支持畫板從源碼實(shí)現(xiàn)看兩個(gè)命令底層都調(diào)用了擴(kuò)展名自動(dòng)補(bǔ)全邏輯autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go但media-preview僅支持file_token素材不提供--type whiteboard分支而media-download的whiteboard分支會(huì)調(diào)用完全不同的 API詳見下文“底層調(diào)用鏈”。命令用法三種典型場(chǎng)景# 場(chǎng)景一下載圖片/文件素材默認(rèn) typemedia lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset # 場(chǎng)景二指定輸出文件名帶擴(kuò)展名則不會(huì)自動(dòng)補(bǔ)全 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset.png # 場(chǎng)景三下載畫板縮略圖whiteboard token lark-cli docs media-download --type whiteboard --token wbcnxxxxxxxx --output ./whiteboard關(guān)于“帶擴(kuò)展名不補(bǔ)全”的細(xì)節(jié)源碼 doc_media_download.go 展示了補(bǔ)全前的處理邏輯whiteboard類型有兜底擴(kuò)展名fallbackExt .png畫板縮略圖必然是 PNGmedia類型沒有兜底必須依賴響應(yīng)頭推斷若--output以filepath.Ext判定為“已有顯式擴(kuò)展名”且不是孤立的.則跳過補(bǔ)全直接按原路徑保存若路徑以尾點(diǎn)xxx.結(jié)尾會(huì)先去掉尾點(diǎn)再補(bǔ)全例如typed.→typed.csv這一行為由測(cè)試 TestDocMediaDownloadAppendsExtensionForTrailingDotOutput 驗(yàn)證。參數(shù)詳解必填項(xiàng)與可選語義原文檔的參數(shù)表如下參數(shù)必填說明--token token是資源 token素材為file_token畫板為whiteboard_id--output path是本地保存路徑不帶擴(kuò)展名會(huì)自動(dòng)補(bǔ)全--type type否media默認(rèn)或whiteboard結(jié)合源碼 doc_media_download.go 的 Shortcut 定義還有兩個(gè)原文檔未列出的重要參數(shù)參數(shù)必填說明--overwrite否bool是否覆蓋已存在的輸出文件。默認(rèn)不覆蓋若目標(biāo)文件已存在命令返回FailedPrecondition錯(cuò)誤并提示“use --overwrite to replace”--as否身份選擇user或bot。該命令的AuthTypes聲明為[user, bot]--as user代表用戶本人下載--as bot代表應(yīng)用身份下載參數(shù)校驗(yàn)與安全約束執(zhí)行時(shí)會(huì)先做兩類校驗(yàn)doc_media_download.gotoken 校驗(yàn)validate.ResourceName(token, --token)校驗(yàn)資源名合法性失敗返回InvalidArgument輸出路徑安全校驗(yàn)runtime.ResolveSavePath(outputPath)只接受相對(duì)路徑。這與共享規(guī)則一致——lark-shared 明確規(guī)定--file、--output等路徑參數(shù)只接受 cwd 下的相對(duì)路徑傳絕對(duì)路徑會(huì)報(bào)unsafe file path詳見 skills/lark-shared/SKILL.md 安全規(guī)則第 5 條。補(bǔ)全擴(kuò)展名后的最終路徑同樣會(huì)再次校驗(yàn)。下載完成后命令以 JSON 形式輸出結(jié)果doc_media_download.go{ saved_path: ./asset.png, size_bytes: 20480, content_type: image/png }底層調(diào)用鏈兩條 API 路徑--type決定最終請(qǐng)求的 OpenAPI 端點(diǎn)這一邏輯在 doc_media_download.go 中明確--type media默認(rèn)GET /open-apis/drive/v1/medias/{token}/download--type whiteboardGET /open-apis/board/v1/whiteboards/{token}/download_as_image兩者的差異不僅在端點(diǎn)還體現(xiàn)在權(quán)限預(yù)檢上media模式在下載前會(huì)調(diào)用common.CheckDriveFileExportPermission(runtime, token)檢查當(dāng)前身份是否具備文檔素材的導(dǎo)出權(quán)限對(duì)應(yīng) dry-run 中的第一步請(qǐng)求GET /open-apis/drive/v1/permissions/{token}/members/auth?typefileactionexportwhiteboard模式跳過導(dǎo)出權(quán)限預(yù)檢直接請(qǐng)求畫板下載端點(diǎn)。這些差異可由 dry-run 輸出與測(cè)試驗(yàn)證TestDocMediaDownloadDryRunIncludesExportAuthBeforeDownload 斷言media模式 dry-run 包含 2 個(gè) API先導(dǎo)出權(quán)限檢查、后媒體下載TestDocWhiteboardDownloadDryRunSkipsExportAuth 斷言whiteboard模式 dry-run 只有 1 個(gè) API/open-apis/board/v1/whiteboards/.../download_as_image。dry-run 預(yù)覽能力來自 Shortcut 的DryRun字段doc_media_download.go配合 lark-shared 安全規(guī)則“目標(biāo)命令支持--dry-run時(shí)用--dry-run預(yù)覽危險(xiǎn)請(qǐng)求”是調(diào)用前的推薦動(dòng)作。權(quán)限與 scope該命令聲明的權(quán)限 scope 為docs:document.media:download并帶有一個(gè)條件 scopeDrivePermissionMemberAuthScope僅當(dāng)需要導(dǎo)出權(quán)限檢查時(shí)才會(huì)觸發(fā)。ConditionalScopes的存在意味著對(duì)某些身份/資源命令可能額外需要 Drive 成員權(quán)限相關(guān)斷言見 TestDocMediaDownloadDeclaresConditionalPermissionMemberAuthScope。擴(kuò)展名自動(dòng)補(bǔ)全完整優(yōu)先級(jí)鏈autoAppendDocMediaExtensionshortcuts/doc/doc_media_ext.go按如下優(yōu)先級(jí)推斷擴(kuò)展名顯式擴(kuò)展名優(yōu)先--output已含非空擴(kuò)展名非.時(shí)直接返回不做任何推斷Content-Type 映射解析響應(yīng)頭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...中提取原文件名擴(kuò)展名兜底擴(kuò)展名僅whiteboard類型使用.png兜底media類型若無命中則保持原路徑不變。測(cè)試 TestDocMediaDownloadAppendsExtensionFromContentTypeMapping 與 TestDocMediaDownloadAppendsExtensionFromContentDispositionFilename 分別驗(yàn)證了第 2、3 條路徑后者模擬了Content-Type: application/octet-stream無法映射、但Content-Disposition帶drive_registry_config_addition.csv文件名時(shí)補(bǔ)全為.csv的場(chǎng)景。token 從哪里來配合lark-doc-fetch使用素材 token 最常見的來源是lark-cli docs fetch返回的文檔內(nèi)容。使用--doc-format xml默認(rèn)時(shí)內(nèi)嵌資源會(huì)以 XML 標(biāo)簽形式出現(xiàn)詳見 lark-doc-fetch.md 中“處理文檔內(nèi)嵌資源”一節(jié)圖片img token... .../文件source token... name.../畫板whiteboard token.../提取規(guī)則與 fetch 文檔一致標(biāo)簽內(nèi)有url屬性時(shí)僅當(dāng)其為可信的公開 HTTPS URL拒絕 userinfo、私有/回環(huán)/鏈路本地/組播/未指定地址 host才可直接下載無url時(shí)提取token預(yù)覽用docs media-preview下載用docs media-downloadwhiteboard一律提取 token 后走docs media-downloadfetch 文檔明確指示畫板不用 preview。由此形成完整工作流# 第一步獲取文檔內(nèi)容提取 token lark-cli docs fetch --doc 文檔URL或token --doc-format xml # 第二步根據(jù)提取的 token 下載素材 lark-cli docs media-download --token Z1Fjxxxxxxxx --output ./asset排障兩類典型錯(cuò)誤1. 權(quán)限錯(cuò)誤permission_denied與 HTTP 403當(dāng)導(dǎo)出權(quán)限預(yù)檢失敗時(shí)命令返回permission_denied當(dāng)下載請(qǐng)求本身返回HTTP 403時(shí)錯(cuò)誤處理器withDocMediaDownloadRecoveryHintshortcuts/doc/doc_errors.go會(huì)在保留原始錯(cuò)誤的同時(shí)在hint中追加恢復(fù)指引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 時(shí)按 hint 改用docs media-preview預(yù)覽內(nèi)容見 lark-doc-media-preview.md這是文檔推薦的降級(jí)路徑。注意兩點(diǎn)實(shí)現(xiàn)細(xì)節(jié)該 403 恢復(fù)提示僅對(duì)media類型生效whiteboard 走的是獨(dú)立 APIwithDocMediaDownloadRecoveryHint明確不把畫板下載重定向到 media-preview導(dǎo)出權(quán)限檢查若返回的是權(quán)限類錯(cuò)誤如LarkErrAppScopeNotEnabled、LarkErrTokenNoPermission、LarkErrUserScopeInsufficient命令會(huì)打印 warning 后繼續(xù)下載而不是直接中止doc_media_download.go相關(guān)行為由 TestDocMediaDownloadPermissionAuthScopeErrorsWarnAndContinue 驗(yàn)證只有檢查結(jié)果為“明確無權(quán)限”allowed false時(shí)才在下載前中止。2. 限流錯(cuò)誤停止立即重試指數(shù)退避限流判定涵蓋三類信號(hào)doc_errors.go錯(cuò)誤子類型SubtypeRateLimit、業(yè)務(wù)錯(cuò)誤碼99991400、HTTP 狀態(tài)碼429。命中后 hint 會(huì)追加Document media download was rate limited; stop immediate retries and retry later with exponential backoff.即停止立即重試稍后按指數(shù)退避重試。相關(guān)測(cè)試包括 TestDocMediaDownloadHTTP429SuggestsBackoff、TestDocMediaDownloadExportAuthRateLimitPreservesAPIErrorAndSuggestsBackoff 等。其他值得注意的行為覆蓋保護(hù)默認(rèn)若目標(biāo)文件已存在則拒絕寫入FailedPrecondition需要顯式加--overwrite。該行為由 TestDocMediaDownloadRejectsOverwriteWithoutFlag 驗(yàn)證且覆蓋檢查發(fā)生在擴(kuò)展名補(bǔ)全之后對(duì)最終路徑判斷HTTP 錯(cuò)誤先于落盤暴露請(qǐng)求失敗時(shí)不會(huì)創(chuàng)建半截文件見 TestDocMediaDownloadRejectsHTTPErrorBeforeWrite導(dǎo)出被拒在下載前攔截權(quán)限預(yù)檢不通過時(shí)直接報(bào)錯(cuò)避免無謂請(qǐng)求見 TestDocMediaDownloadExportDeniedFailsBeforeDownload身份模型命令支持user/bot兩種身份--as的選擇邏輯與身份權(quán)限差異bot 查用戶資源返回空成功而非報(bào)錯(cuò)參見 skills/lark-shared/SKILL.md。參考文檔lark-doc-fetch — 獲取文檔內(nèi)容用于提取素材/畫板 tokenlark-doc-media-preview — 預(yù)覽素材403 降級(jí)路徑、與 download 的選擇區(qū)分lark-shared — 認(rèn)證、--as身份模型、相對(duì)路徑安全規(guī)則與 JSON 輸出契約【免費(fèi)下載鏈接】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.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cli414/cli創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考