ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# im +messages-resources-download
|
|
|
|
> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
|
|
|
|
Download image or file resources from a message. Supports **automatic chunked download for large files** using HTTP Range requests. Resources are identified by the combination of `message_id` + `file_key`, both of which come directly from message content returned by `im +chat-messages-list`.
|
|
|
|
> **Note:** read-only message commands render resource keys in message content, but they do not download binaries automatically. Use this command whenever you need to fetch the actual image/file bytes or save them to a specific path.
|
|
|
|
This skill maps to the shortcut: `lark-cli im +messages-resources-download` (internally calls `GET /open-apis/im/v1/messages/{message_id}/resources/{file_key}`).
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Download an image (save to the current directory)
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image
|
|
|
|
# Download a file
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key file_v3_xxx --type file
|
|
|
|
# Specify the output path
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --output ./photo.png
|
|
|
|
# Download as a bot
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --as bot
|
|
|
|
# Preview the request without executing it
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image --dry-run
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Required | Description |
|
|
|------|------|------|
|
|
| `--message-id <id>` | Yes | Message ID (`om_xxx` format) |
|
|
| `--file-key <key>` | Yes | Resource key (`img_xxx` or `file_xxx`) |
|
|
| `--type <type>` | Yes | Resource type: `image` or `file` |
|
|
| `--output <path>` | No | Output path (relative paths only; `..` traversal is not allowed). When omitted, the server's original filename from `Content-Disposition` is used if available; otherwise defaults to `file_key`. File extension is automatically inferred from `Content-Disposition` or `Content-Type` if not provided |
|
|
| `--as <identity>` | No | Identity type: `user` (default) or `bot` |
|
|
| `--dry-run` | No | Print the request only, do not execute it |
|
|
|
|
## Large File Download (Auto Chunking)
|
|
|
|
When downloading large files, the command automatically uses **HTTP Range requests** for reliable chunked downloading:
|
|
|
|
| Behavior | Details |
|
|
|----------|---------|
|
|
| Probe chunk | First 128 KB to detect file size and Content-Type |
|
|
| Chunk size | 8 MB per subsequent request |
|
|
| Workers | Single-threaded sequential download (ensures reliability) |
|
|
| Retries | Up to 2 retries for transient request failures, with exponential backoff |
|
|
|
|
**Benefits:**
|
|
- Reduces the impact of transient request failures during large downloads
|
|
- Preserves the server's original filename via `Content-Disposition` (supports RFC 5987 UTF-8 encoding); falls back to `Content-Type`-based extension inference
|
|
- Validates file size integrity after download completion
|
|
|
|
## `file_key` Sources
|
|
|
|
Different resource markers in message content correspond to different `file_key` and `type` values:
|
|
|
|
| Message Type | Marker in Content | `file_key` Format | `--type` |
|
|
|---------|-------------|---------------|--------|
|
|
| Image | `img_xxx` | `img_xxx` | `image` |
|
|
| File | `file_xxx` | `file_xxx` | `file` |
|
|
| Audio | `file_xxx` | `file_xxx` | `file` |
|
|
| Video | `file_xxx` | `file_xxx` | `file` |
|
|
|
|
## Usage Scenario
|
|
|
|
### Scenario: Extract and download an image from a message
|
|
|
|
```bash
|
|
# Step 1: Fetch messages and find one containing an image
|
|
lark-cli im +chat-messages-list --chat-id oc_xxx
|
|
# In the response you see: { "msg_type": "image", "content": "{\"image_key\":\"img_v3_xxx\"}" }
|
|
|
|
# Step 2: Download the image
|
|
lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_xxx --type image
|
|
```
|
|
|
|
## Common Errors and Troubleshooting
|
|
|
|
| Symptom | Root Cause | Solution |
|
|
|---------|---------|---------|
|
|
| Download failed | `file_key` does not match the `message_id` | Make sure the `file_key` came from that message's content |
|
|
| Hit error code 234002 or 14005 | No permission, **not** missing API scope | no access to this chat or file was deleted — do not retry, return the error to the user |
|
|
| Permission denied | `im:message:readonly` is not authorized | Run `auth login --scope "im:message:readonly"` |
|
|
| File size mismatch | Chunked download integrity check failed | Network instability during download; retry the command |
|
|
| Content-Range error | Server returned invalid range header | Transient API issue; retry the command |
|
|
|
|
## References
|
|
|
|
- [lark-im](../SKILL.md) - all message-related commands
|
|
- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters
|