CLIAI 技能【免费下载链接】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-cliLark/飞书官方 CLIapps file-*命令族用于管理妙搭Spark/Miaoda应用的文件存储上传本地文件、下载与列出远端文件、生成有时效的分享链接、批量删除以及查询存储用量。读完本文你将掌握 file 域的完整命令用法、--path精确寻址约定、时间过滤格式与时区陷阱以及各命令在 shortcuts/apps 源码中的底层实现原理能够在终端和 AI Agent 场景下安全高效地操作应用文件存储。何时使用 file 域当用户需要在某个妙搭应用里上传 / 下载 / 列出 / 删除文件、获取文件的临时分享链接、或查看存储用量时使用本域的 7 个命令。需要注意能力边界见 lark-apps/SKILL.md普通飞书云盘文件走lark-drive不归本域应用数据库中的表数据走db-*db-table-list、db-data-export等与文件存储是两套资产妙搭应用运行时所需的图片、字体、音视频等资源型文件属于平台资源不应提交到 git 仓库应通过file-upload上传后拿到远端 URL 在代码中引用上传返回的链接按应用隔离不同应用必须各自重新上传参见 SKILL.md「平台资源与应用源码边界」。所有 file 域命令均以用户身份--as user执行认证、scope、--as user、exit 码、_notice等通用处理见lark-shared/SKILL.md与本域 SKILL.md。命令一览命令做什么关键参数file-list列出文件可按名/路径/类型/大小/上传时间过滤--app-id、过滤器、--page-size/--page-tokenfile-get查单个文件的元数据--app-id、--pathfile-sign生成有时效的下载链接用于分享 / 直接下载--app-id、--path、--expires-infile-download把远端文件保存到本地--app-id、--path、--outputfile-upload上传本地文件到应用存储--app-id、--filefile-delete按路径批量删除文件--app-id、--path可重复、--yesfile-quota-get查应用的文件存储用量--app-id运行时命令事实以lark-cli apps cmd --help为准。命令均需要app_开头的妙搭应用 IDcli_开头的飞书应用 ID 绝不能传入任何apps *命令且只读命令需要spark:app:readscope写命令需要spark:app:writescope对应源码见 apps_file_list.go 等文件的Scopes字段。寻址与约定先读file 域有三个核心约定贯穿全部命令远端文件统一用--path精确寻址--path是远端路径带前导/如/1858537546760216.png。只知道文件名时先用file-list --name 名定位拿到path再做后续操作。源码中file-get、file-sign、file-download、file-delete都在校验阶段调用requireFilePath强制要求合法的远端路径。本地文件 / 输出路径用工作目录内的相对路径如--file ./report.pdf、--output ./out.png路径在别处时先cd过去或改成相对路径。这是 CLI 层的硬性约束——SKILL.md 明确--path、--file、--output等路径参数只接受当前工作目录cwd下的相对路径传绝对路径会报错。源码中file-download还通过rejectOutputTraversal拒绝--output的路径穿越见 apps_file_download.go。file 域不区分环境没有--env应用文件存储不分 dev/online与db-*的多环境设计不同源码注释明确 file 域不分 dev/online无 --env见 apps_file_list.go。各命令详解file-list列出与过滤文件列出应用文件支持精确过滤--name文件名、--path远端路径、--typeMIME 类型--size-gt/--size-lt字节大于 / 小于--uploaded-since/--uploaded-until上传时间区间时间格式见下文分页--page-size默认 20范围 1..200/--page-token上一页响应的游标lark-cli apps file-list --app-id app_xxx lark-cli apps file-list --app-id app_xxx --type image/png --uploaded-since 7d列表每项给出名称、路径、大小、类型、上传时间 5 列pretty 表格即这 5 列上传者、下载地址如有仅在 JSON 输出里单文件详情用file-get。源码级细节apps_file_list.go底层调用GET /apps/{app_id}/storage/file_list游标分页--page-size在 CLI 前置校验为[1, 200]validateFileListPageSize与后端 paas_storagecheckMaxKeys的(0, 200]契约对齐page_size 200服务端会直接返回ErrInvalidRequestCLI 前置校验避免无谓往返时间过滤参数uploaded-since/uploaded-until会在校验阶段经normalizeTimestamp归一化为 RFC3339 UTC 后回写再透传设计原则多格式时间统一归一化服务端返回的created_at/created_by会投影为产品语义的uploaded_at/uploaded_bypretty 输出为空时打印No files found.。file-get查单个文件元数据按--path查单个文件的元数据仅按 path 精确寻址无按名寻址。路径不存在时返回明确的「文件不存在」错误。lark-cli apps file-get --app-id app_xxx --path /1858537546760216.png源码级细节apps_file_get.go底层为GET /apps/{app_id}/storage/file?pathpathpretty 输出 key/value 形式file_name/path/size含 bytes/type/uploaded_by仅名字id 只在 JSON 保留/uploaded_at/download_url条件出现仅当服务端返回时。可用-q .data.size_bytes或-q .data.download_url提取单个字段。file-sign生成有时效的下载链接为指定文件生成一个有时效的下载链接——适合发给用户分享、或直接下载。--expires-in设有效期秒数默认 1 天 86400 秒最长 30 天 2592000 秒。pretty模式只输出链接本身便于复制 / 管道如直接curl要把到期时间一并告诉用户时用默认 JSON 输出含expires_at到期时间。lark-cli apps file-sign --app-id app_xxx --path /1858537546760216.png --expires-in 3600源码级细节apps_file_sign.go底层为POST /apps/{app_id}/storage/file_sign请求体{path, expires_in}--expires-in超过 30 天上限fileSignMaxExpiresSeconds 30 * 24 * 60 * 60会直接校验失败pretty 模式只打印signed_url一行JSON 返回{file_name, path, signed_url, expires_at}。file-download下载到本地把远端文件保存到本地。--output指定保存路径缺省时按远端文件名basename保存到当前目录。lark-cli apps file-download --app-id app_xxx --path /1858537546760216.png --output ./logo.png # 省略 --output 时保存为 ./1858537546760216.png源码级细节apps_file_download.go下载是两步实现——先POST /apps/{app_id}/storage/file_sign拿 presignedsigned_url直连对象存储再客户端GET signed_url落盘不单独设 download 接口。5xx 视为上游瞬时故障标记可重试4xx如签名过期需要重新签名而非盲重试。file-upload上传本地文件上传一个本地文件仅接收本地--file。关键行为文件名沿用本地文件名file_name basename特殊字符做 URL 编码透传以.开头的隐藏文件名如.bashrc会加_前缀避免下载回本地时覆盖隐藏文件远端路径由平台分配、全局唯一平台生成的 16 位 ID无法也无需手填单文件上限100 MB。lark-cli apps file-upload --app-id app_xxx --file ./report.pdf # 打印平台生成的远端路径 lark-cli apps file-upload --app-id app_xxx --file ./logo.png -q .data.path源码级细节apps_file_upload.go上传是三步直传流程POST /apps/{app_id}/storage/file_pre_upload请求体{file_name, file_size, content_type}→ 返回{upload_url, upload_id}客户端直接PUT文件字节到 presignedupload_url取响应ETag直连对象存储绕过 Lark 网关使用独立文件传输客户端newFileTransferClientPOST /apps/{app_id}/storage/file_upload_callback请求体{upload_id, etag}→ 返回文件元数据。文件名处理有两道防线先经sanitizeUploadFileName去掉 TOS 非法字符[:\/*?|,;]再encodeURIComponentUTF-8 百分号编码兼容中文让Content-Dispositionheader 合法PUT 时用mime.FormatMediaType规范生成Content-Disposition透传原始文件名若 sanitize 后仍以.开头则前置下划线。Content-Type 按扩展名推断mimeByExt未知回退application/octet-stream。file-delete批量删除高危按路径批量删除--path可重复传多个string_slice类型。删除是高危操作必须带--yes缺省会被确认关卡拦下。逐项返回结果部分文件删除失败如某个路径不存在不影响其余文件整体仍算成功失败项在结果里单独标出原因。lark-cli apps file-delete --app-id app_xxx --path /1858537546760216.png --yes lark-cli apps file-delete --app-id app_xxx --path /a.png --path /b.png --yes源码级细节apps_file_delete.go命令风险等级为high-risk-write框架自动注入--yes确认底层为POST /apps/{app_id}/storage/file_batch_remove请求体{paths:[...]}。注释说明了为什么是 POST 而非 DELETE网关不支持 DELETE-with-body实测DELETE→404 / POST→200后端results[]与请求paths顺序一一对应成功项带file失败项带error_codeCLI 据下标回填path部分失败整体仍ok:true—— 失败项落在data.results[].error不翻成非 0 退出码lark-cli 信封语义。file-quota-get查存储用量查应用的文件存储用量已用量、文件数配额接入后还会给总配额与使用率。lark-cli apps file-quota-get --app-id app_xxx源码级细节apps_file_quota_get.go底层为GET /apps/{app_id}/storage/file_quota。响应做白名单投影只保留storage_used_bytes/files配额已对接storage_quota_bytes 0时才追加storage_quota_bytes/usage_percent保留一位小数与db-quota-get同口径避免配额未接入时输出误导性字段。pretty 输出Storage已用 / 配额 (百分比)与Files两行。时间格式--uploaded-since / --uploaded-until按用户口语自然传入即可支持相对时间7d/2h/30s从现在往前推日期2026-04-15日期时间2026-04-15T10:00:00带时区的 ISO 86012026-04-15T10:00:00Z/2026-04-15T10:00:0008:00时区不带时区的日期/日期时间按运行机器的本地时区解析再归一化到 UTC 发给服务端。CIUTC与本地如 UTC8跑同一条命令过滤边界会差几小时要精确到某时区时显式写 ISO 8601 带偏移如...08:00/...Z。这一点在源码中有明确实现file-list的校验阶段对uploaded-since/uploaded-until调用normalizeTimestamp归一化为 RFC3339 UTC 并回写 flag见 apps_file_list.go多格式输入统一成 UTC 后透传给服务端。Agent 规则面向 AI Agent 调用 file 域的命令时遵循以下规则原文摘录见 lark-apps-file.md寻址一律用--path用户只给文件名时先file-list --name 名定位多个同名再让用户确认。上传 / 下载的本地路径用工作目录内相对路径不在当前目录就cd过去或改相对路径。用户要「分享链接 / 临时下载地址」时用file-sign把返回的链接转述给用户。删除前判断意图已明确要删且授权时可直接带--yes不确定删哪些时先file-list给用户确认。批量删除部分失败不报错按逐项结果向用户说明哪些成功、哪些没删掉及原因。从源码看这些规则与命令设计一一对应读类命令list/get/sign/download/quota风险等级均为read写类命令upload 为write、delete 为high-risk-writefile-delete的逐项失败语义由projectDeleteResults按下标回填路径实现确保 Agent 能向用户准确报告失败项。测试与验证仓库为 file 域提供了较完整的测试覆盖可作行为契约参考apps_file_list_test.go、apps_file_sign_test.go、apps_file_quota_get_test.go、apps_file_upload_test.go、apps_file_download_test.go、apps_file_delete_test.gofile_app_id_validation_test.go 覆盖app_id校验requireFileAppID相关行为quota_common_test.go 覆盖用量百分比口径等公共逻辑。小结file 域是妙搭应用资产管理的「文件存储」入口与db-*数据库表、cache-*运行时缓存、env-*环境变量并列共同构成应用运行时数据的完整管理面。核心要点可归结为远端一律--path精确寻址、本地一律 cwd 相对路径、删除必须--yes、分享用file-sign、批量删除看逐项结果。理解底层实现三步直传、presigned URL 签名下载、后端(0,200]分页契约、时间归一化为 UTC能帮助你更准确地预判命令行为与边界条件在脚本化和 Agent 自动化场景中减少无谓往返。赞分享CLIAI 技能【免费下载链接】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点击查看免费下载相关推荐Ente CLI 管理命令实战使用 ente admin update-subscription 更新用户订阅与存储配额Ente CLI 管理命令实战使用 ente admin update subscription 更新用户订阅与存储配额 自托管或运营 Ente 服务时管理后端前端移动开发桌面应用密码学认证鉴权存储解决Hadoop存储失控命名空间与配额管理终极实战指南解决Hadoop存储失控命名空间与配额管理终极实战指南 在大数据时代Hadoop分布式文件系统HDFS作为核心存储组件其存储容量的爆炸性增长常常导致管大数据分布式文件系统批处理任务调度集群管理3步解锁本地服务全球访问Rust驱动的tunnelto实战指南3步解锁本地服务全球访问Rust驱动的tunnelto实战指南 还在为本地演示困境而烦恼吗当你需要向同事展示本地开发的前端页面或是让远程团队测试本地ACLIAI 技能上一篇Velocity动画调试技巧使用Chrome DevTools分析动画性能下一篇Prompt-Tools完整使用指南从基础操作到高级技巧的终极教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考