71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
# docs +resource-*（Docx 封面图资源）
|
||
|
||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../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`](lark-doc-media-download.md)
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 下载封面图。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-download.md) — 下载正文素材或画板缩略图
|
||
- [lark-doc-media-insert](lark-doc-media-insert.md) — 在正文插入图片/文件
|
||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|