Starlight_Lancher/.agents/skills/lark-doc/references/lark-doc-resource-cover.md

docs +resource-*（Docx 封面图资源）

前置条件： 先阅读 ../lark-shared/SKILL.md 了解认证、全局参数和安全规则。

Docx 封面图不是正文里的 <img token="..."> 素材块。读取、更新、删除文档封面图时，使用 docs +resource-download/+resource-update/+resource-delete --type cover，不要使用 +media-insert 或 +media-download --token <cover.token> 让用户手动拼步骤。

选择规则

• 用户要下载文档封面图：docs +resource-download --type cover
• 用户要设置/替换文档封面图：docs +resource-update --type cover
• 用户要删除文档封面图：docs +resource-delete --type cover
• 用户要下载正文图片、附件、画板缩略图：继续使用 docs +media-download

命令

# 下载封面图。CLI 会先读取 document.cover.token，再下载图片内容并保存到本地。
lark-cli docs +resource-download --doc doxcnXXX --type cover --output ./cover

# 使用本地文件更新封面图。
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png

# 使用剪切板图片更新封面图。
lark-cli docs +resource-update --doc doxcnXXX --type cover --from-clipboard

# 使用 HTTPS URL 更新封面图。CLI 会先下载 URL 内容，再上传并写入 cover.token。
lark-cli docs +resource-update --doc doxcnXXX --type cover --url "https://example.com/cover.png"

# 可选：设置封面图裁切偏移。
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png --offset-ratio-x 0.2 --offset-ratio-y 0.8

# 删除封面图；当文档本来没有封面图时也成功返回。
lark-cli docs +resource-delete --doc doxcnXXX --type cover

参数

命令	参数	必填	说明
all	--doc <id>	是	文档 ID、docx URL，或可解析为 docx 的 wiki URL
all	--type cover	否	当前只支持 cover；默认值也是 cover
download	--output <path>	是	本地保存路径；不带扩展名会根据响应类型自动补全
download	--overwrite	否	覆盖已存在的输出文件
update	--file <path>	三选一	磁盘上的真实图片文件；大于 20MiB 自动使用分片上传
update	--from-clipboard	三选一	从系统剪切板读取图片
update	--url <https-url>	三选一	从 HTTPS URL 下载图片后上传
update	--offset-ratio-x <number>	否	视图相对原图中心的横向偏移比例：水平偏移 px / 原图宽度 px；0 为居中，正数向右，负数向左
update	--offset-ratio-y <number>	否	视图相对原图中心的纵向偏移比例：垂直偏移 px / 原图高度 px；0 为居中，正数向上，负数向下

输出契约

• +resource-download 成功时 stdout JSON 的 data 包含 document_id、type、saved_path、size_bytes、content_type、cover.token。如果文档没有封面图，命令失败退出，错误包含 document has no cover 和脱敏 document_id，不会创建输出文件。
• +resource-update 成功时 stdout JSON 的 data 包含完整 file_token 和 cover.token；stderr 只打印脱敏 token。
• +resource-delete 成功时 stdout JSON 的 data.deleted 表示本次是否真的发起删除，data.already_empty 表示删除前是否没有封面图。空封面图是幂等成功，不报错。

URL 来源安全边界

+resource-update --url 只用于下载公开 HTTPS 图片：

• 只允许 https://，拒绝 HTTP、空 host 和 URL userinfo。
• 拒绝解析到 private、loopback、link-local、multicast、unspecified 地址的 host。
• 最多跟随 3 次跳转，每次跳转都重新校验 URL。
• 响应 Content-Type 只允许 image/png、image/jpeg、image/gif、image/webp。
• 响应体最大 20MiB。

参考

• lark-doc-media-download — 下载正文素材或画板缩略图
• lark-doc-media-insert — 在正文插入图片/文件
• lark-shared — 认证和全局参数