@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-messages-resources-download.md

@@ -0,0 +1,94 @@
+# 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; defaults to `file_key` as the file name). File extension is automatically added based on 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
+- Automatically detects and appends correct file extension from Content-Type
+- 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

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-messages-search.md

@@ -0,0 +1,213 @@
+# im +messages-search
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Search Feishu messages across conversations. This shortcut automatically performs a multi-step workflow: search for message IDs, batch fetch message details, then enrich the results with chat context.
+
+> **User identity only** (`--as user`). Bot identity is not supported.
+
+This skill maps to the shortcut: `lark-cli im +messages-search` (internally calls `POST /open-apis/im/v1/messages/search` + batched `GET /open-apis/im/v1/messages/mget`, then batch-fetches chat context).
+
+## Commands
+
+```bash
+# Search by keyword
+lark-cli im +messages-search --query "project progress"
+
+# Restrict search to a specific group chat
+lark-cli im +messages-search --query "weekly report" --chat-id oc_xxx
+
+# Filter by sender (comma-separated)
+lark-cli im +messages-search --query "requirement" --sender ou_xxx,ou_yyy
+
+# Filter by attachment type
+lark-cli im +messages-search --query "report" --include-attachment-type file
+
+# Filter by chat type (group / p2p)
+lark-cli im +messages-search --query "progress" --chat-type group
+
+# Filter by sender type (user / bot)
+lark-cli im +messages-search --query "reminder" --sender-type bot
+
+# Exclude bot senders
+lark-cli im +messages-search --query "reminder" --exclude-sender-type bot
+
+# Only messages that @me
+lark-cli im +messages-search --query "announcement" --is-at-me
+
+# Combined filters + time range
+lark-cli im +messages-search --query "meeting" --sender ou_xxx --chat-type group --start "2026-03-13T00:00:00+08:00" --end "2026-03-20T23:59:59+08:00"
+
+# Specific time range (ISO 8601)
+lark-cli im +messages-search --query "release" --start "2026-03-01T00:00:00+08:00" --end "2026-03-10T00:00:00+08:00"
+
+# Output format options
+lark-cli im +messages-search --query "test" --format pretty
+lark-cli im +messages-search --query "test" --format table
+lark-cli im +messages-search --query "test" --format csv
+
+# Pagination
+lark-cli im +messages-search --query "test" --page-token <PAGE_TOKEN>
+
+# Auto-pagination across multiple pages
+lark-cli im +messages-search --query "test" --page-all --format json
+
+# Auto-pagination with an explicit page cap
+lark-cli im +messages-search --query "test" --page-limit 5 --format json
+
+# Preview the request without executing it
+lark-cli im +messages-search --query "test" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--query <text>` | No | Search keyword (may be empty when used with other filters) |
+| `--chat-id <id>` | No | Restrict to chat IDs, comma-separated (`oc_xxx,oc_yyy`) |
+| `--sender <ids>` | No | Sender open_ids, comma-separated (`ou_xxx`) |
+| `--include-attachment-type <type>` | No | Attachment filter: `file` / `image` / `video` / `link` |
+| `--chat-type <type>` | No | Chat type: `group` / `p2p` |
+| `--sender-type <type>` | No | Sender type: `user` / `bot` |
+| `--exclude-sender-type <type>` | No | Exclude messages from `user` or `bot` senders |
+| `--is-at-me` | No | Only return messages that mention `@me` |
+| `--start <time>` | No | Start time with local timezone offset required (e.g. `2026-03-24T00:00:00+08:00`) |
+| `--end <time>` | No | End time with local timezone offset required (e.g. `2026-03-25T23:59:59+08:00`) |
+| `--page-size <n>` | No | Page size (default 20, range 1-50) |
+| `--page-token <token>` | No | Pagination token for the next page |
+| `--page-all` | No | Automatically paginate through all result pages (up to 40 pages) |
+| `--page-limit <n>` | No | Max pages to fetch when auto-pagination is enabled (default 20, max 40). Setting it explicitly also enables auto-pagination |
+| `--format <fmt>` | No | Output format: `json` (default) / `pretty` / `table` / `ndjson` / `csv` |
+| `--as <identity>` | No | Identity type (defaults to and only supports `user`) |
+| `--dry-run` | No | Print the request only, do not execute it |
+
+## Core Constraints
+
+### 1. Provide at least one filter whenever possible
+
+All parameters are optional, but you should usually provide at least one filter (`--query`, `--sender`, `--chat-id`, etc.). Otherwise the search scope may be too broad and return low-signal results.
+
+### 2. Two-step orchestration is automatic
+
+The shortcut automatically performs:
+
+1. The **search API** returns matching `message_id` values
+2. The **mget API** fetches full message content for those message IDs in batch
+3. Chat context lookup is fetched in batch and attached to each message
+
+The user does not need to manage the orchestration manually. When search results span multiple pages, the shortcut can also paginate automatically with `--page-all` or `--page-limit`.
+
+### 3. Conversation context is enriched automatically
+
+In JSON output, each message automatically includes conversation context:
+
+| Field | Description |
+|------|------|
+| `chat_type` | Conversation type: `p2p` / `group` |
+| `chat_name` | Group name (for groups) or the other participant's name (for p2p chats) |
+| `chat_partner` | For p2p only: the other participant's `open_id` and `name` |
+
+In pretty output, the `chat` column shows the chat name for groups, or `"p2p"` for direct messages.
+
+Each message in JSON output contains:
+
+| Field | Description |
+|------|------|
+| `message_id` | Message ID |
+| `msg_type` | Message type: `text`, `image`, `file`, `interactive`, `post`, `audio`, `video`, `system`, etc. |
+| `create_time` | Creation time |
+| `sender` | Sender information (includes `name` for user senders) |
+| `content` | Message content |
+| `chat_id` | ID of the conversation the message belongs to |
+| `deleted` | Whether the message has been recalled (`true` = recalled) |
+| `updated` | Whether the message has been edited after sending |
+| `mentions` | Array of @mentions in the message; each item contains `{id, key, name}`. Present only when the message contains @mentions |
+| `thread_id` | Thread ID (`omt_xxx`) if the message has replies in a thread. Present only when replies exist |
+
+### 4. Pagination behavior
+
+- Default behavior is still **single-page**.
+- `--page-token` is the manual continuation mechanism when you already have a token from a previous response.
+- `--page-all` enables auto-pagination and uses a default cap of **40 pages**.
+- `--page-limit <n>` enables auto-pagination with an explicit cap. If you pass `--page-limit` without `--page-all`, auto-pagination is still enabled.
+- When auto-pagination stops because of the configured page cap, the response still includes the last `has_more` / `page_token` so you can continue manually.
+
+### 5. Search results contain follow-up clues
+
+In JSON output, each message includes `chat_id` and `thread_id` (when present). Use them with other shortcuts for deeper inspection:
+
+```bash
+# View the full message stream for the conversation that contains the search result
+lark-cli im +chat-messages-list --chat-id <chat_id>
+
+# View replies in the thread that contains the search result
+lark-cli im +threads-messages-list --thread <thread_id>
+```
+
+## Resource Rendering
+
+Search results reuse the same content formatter as other read commands. Image messages are rendered as placeholders such as `[Image: img_xxx]`; resource binaries are **not** downloaded automatically.
+
+Use `im +messages-resources-download` if you need to fetch the underlying image or file bytes from a specific message.
+
+## AI Usage Guidance
+
+### Resolving chat_id from a chat name
+
+When the user refers to a chat by name and you need its `chat_id` for the `--chat-id` filter, use [`+chat-search`](lark-im-chat-search.md) first:
+
+```bash
+# Step 1: Find the chat_id by name
+lark-cli im +chat-search --query "<chat name keyword>" --format json
+
+# Step 2: Use the chat_id to narrow down message search
+lark-cli im +messages-search --query "keyword" --chat-id <chat_id>
+```
+
+**Do not use `im chats search` or `im chats list` — always use the `+chat-search` shortcut.**
+
+## Work Summary / Report Generation
+
+When the user asks you to summarize work, generate a weekly report, or compile activity from chat messages, you should **paginate through all available results** to get a complete picture. A single page is rarely enough for thorough summarization.
+
+### Strategy
+
+1. **Start with targeted filters** — use `--chat-id`, `--sender`, `--start`, `--end` to narrow the scope as much as possible before paginating.
+2. **Prefer auto-pagination** — for report and summary tasks, use `--page-all --format json` by default. If you need a bounded run, use `--page-limit <n> --format json`.
+3. **Accumulate before summarizing** — collect all pages of messages first, then analyze and summarize. Do not summarize after the first page alone — you will miss important context.
+4. **Fall back to `--page-token` when resuming** — if auto-pagination hits the configured page cap and the response still has `has_more=true`, continue from the returned `page_token`.
+5. **Use `--format json`** — JSON output includes `has_more` and `page_token` fields needed for pagination. `pretty` and `table` formats are useful for reading but not for resuming pagination reliably.
+
+### Example: Weekly work summary from a project chat
+
+```bash
+# Preferred: fetch automatically
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-all --format json
+
+# If you need to cap the run explicitly
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-limit 5 --format json
+
+# If the bounded run still returns has_more=true, continue manually
+lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-token <token_from_previous_run> --format json
+```
+
+### Key points
+
+- **Always paginate exhaustively** for summary tasks. A single page of 20-50 messages is usually insufficient for a meaningful work summary.
+- Prefer `--page-all`; use `--page-limit` only when you need to bound runtime or output volume.
+- If the user does not specify a time range, default to the current week (Monday to today) for weekly reports, or ask for clarification.
+- When summarizing, group messages by topic/thread rather than by chronological order for better readability.
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Too few results | The time range is too narrow or the keyword is too specific | Expand the time range and try broader keywords |
+| No results | Missing permission or no match | Confirm `search:message` is authorized and relax the filters |
+| Permission denied | Search scope not authorized | Run `auth login --scope "search:message"` |
+
+## References
+
+- [lark-im](../SKILL.md) - all message-related commands
+- [lark-im-threads-messages-list](lark-im-threads-messages-list.md) - inspect thread replies
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-messages-send.md

@@ -0,0 +1,223 @@
+# im +messages-send
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Send a message to a group chat or a direct message conversation. Supports both user identity (`--as user`) and bot identity (`--as bot`).
+
+This skill maps to the shortcut: `lark-cli im +messages-send` (internally calls `POST /open-apis/im/v1/messages`).
+
+## Safety Constraints
+
+Messages sent by this tool are visible to other people. Before calling it, you **must** confirm with the user:
+
+1. The recipient (which person or which group)
+2. The message content
+3. The sending identity (user or bot)
+
+**Do not** send messages without explicit user approval.
+
+When using `--as bot`, the message is sent in the app's name, so make sure the app has already been added to the target chat.
+
+When using `--as user`, the message is sent as the authorized end user and requires the `im:message.send_as_user` and `im:message` scopes.
+
+## Choose The Right Content Flag
+
+| Need | Recommended flag | Why |
+|------|------|------|
+| Send plain text exactly as written | `--text` | Wrapped directly to `{"text":"..."}`; no Markdown conversion |
+| Send simple Markdown and accept Feishu-style rendering | `--markdown` | Automatically converted to `post` JSON |
+| Precisely control the final payload | `--content` | You provide the exact JSON for `text` / `post` / `interactive` / `share_*` / media payloads |
+| Send image / file / video / audio | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads local files automatically |
+
+### `--text` vs `--markdown`
+
+- Use `--text` when the content should stay as plain text, including exact line breaks, indentation, code samples, shell snippets, or Markdown characters that should **not** be reinterpreted.
+- Use `--markdown` when you want basic Markdown-style rendering and you accept that the shortcut will normalize and rewrite parts of the content before sending.
+- Use `--content` when `--markdown` is not enough, especially if you need exact `post` JSON, a title, multiple locales, cards, or unsupported rich structures.
+
+## What `--markdown` Really Does
+
+`--markdown` is **not** sent as raw Markdown API content.
+
+The shortcut does all of the following before sending:
+
+1. Forces `msg_type=post`
+2. Resolves remote Markdown images like `![x](https://...)` by downloading and uploading them first
+3. Normalizes the Markdown for Feishu post rendering
+4. Wraps the result as:
+
+```json
+{"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}}
+```
+
+This means `--markdown` is convenient, but it is not a full-fidelity Markdown transport.
+
+### Current Markdown Caveats
+
+- It does **not** promise full CommonMark / GitHub Flavored Markdown support.
+- It always becomes a `post` payload with a single `zh_cn` locale.
+- It does **not** let you set a `post` title. If you need a title, use `--msg-type post --content ...`.
+- Headings are rewritten:
+    - `# Title` becomes `#### Title`
+    - `##` to `######` are normalized to `#####` when the content contains H1-H3
+- Consecutive headings are separated with blank lines after heading normalization.
+- Block spacing and line breaks may be normalized during conversion.
+- Code blocks are preserved as code blocks.
+- Excess blank lines are compressed.
+- Only `http://...`, `https://...`, or already-uploaded `img_xxx` Markdown images are kept reliably.
+- Local paths in Markdown image syntax like `![x](./a.png)` are **not** auto-uploaded by `--markdown`; they may be stripped during optimization.
+- If remote Markdown image download/upload fails, that image is removed with a warning.
+
+If any of the above is unacceptable, do **not** use `--markdown`; use `--content` and provide the final JSON yourself.
+
+## Preserving Formatting
+
+If the message has multiple lines, indentation, code blocks, tabs, or many quotes/backslashes, prefer shell ANSI-C quoting with `$'...'`.
+
+This is especially useful in `zsh` / `bash` because it lets you write `\n` explicitly instead of relying on the shell to preserve literal newlines.
+
+### When formatting must be preserved
+
+Use `--text` plus `$'...'`:
+
+```bash
+lark-cli im +messages-send --chat-id oc_xxx --text $'Build failed\nBranch: feature/im-docs\nAction: please check logs'
+```
+
+```bash
+lark-cli im +messages-send --chat-id oc_xxx --text $'```bash\nmake test\nmake lint\n```'
+```
+
+Use this path when you want the receiver to see the text exactly as entered, not a converted Markdown post.
+
+### When formatting does not need exact preservation
+
+Use `--markdown`:
+
+```bash
+lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Release Notes\n\n- Added send shortcut\n- Added reply shortcut'
+```
+
+This is better for lightweight readable formatting, but the final content may not match the source text byte-for-byte because the shortcut normalizes headings and spacing before sending.
+
+## Commands
+
+```bash
+# Send plain text (--text is recommended for normal messages)
+lark-cli im +messages-send --chat-id oc_xxx --text "Hello"
+
+# Equivalent manual JSON
+lark-cli im +messages-send --chat-id oc_xxx --content '{"text":"Hello"}'
+
+# Send to a direct message (pass open_id)
+lark-cli im +messages-send --user-id ou_xxx --text "Hello"
+
+# Send multi-line text while preserving formatting
+lark-cli im +messages-send --chat-id oc_xxx --text $'Line 1\nLine 2\n  indented line'
+
+# Send basic Markdown (will be converted to post JSON)
+lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Update\n\n- item 1\n- item 2'
+
+# If you need exact post structure, send JSON directly
+lark-cli im +messages-send --chat-id oc_xxx --msg-type post --content '{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"Body"}]]}}'
+
+# Send a local image (uploaded automatically before sending)
+lark-cli im +messages-send --chat-id oc_xxx --image ./photo.png
+
+# Or send directly with an existing image_key
+lark-cli im +messages-send --chat-id oc_xxx --image img_xxx
+
+# Send a local file (uploaded automatically before sending)
+lark-cli im +messages-send --chat-id oc_xxx --file ./report.pdf
+
+# Send a video (--video-cover is required as the cover)
+lark-cli im +messages-send --chat-id oc_xxx --video ./demo.mp4 --video-cover ./cover.png
+lark-cli im +messages-send --chat-id oc_xxx --video ./demo.mp4 --video-cover img_xxx
+
+# Send audio
+lark-cli im +messages-send --chat-id oc_xxx --audio ./voice.opus
+
+# Use an idempotency key (same key sends only once within 1 hour)
+lark-cli im +messages-send --chat-id oc_xxx --text "Hello" --idempotency-key my-unique-id
+
+# Preview the request without executing it
+lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--chat-id <id>` | One of two | Group chat ID (`oc_xxx`) |
+| `--user-id <id>` | One of two | User open_id (`ou_xxx`) for direct messages |
+| `--text <string>` | One content option | Plain text message. Best default for exact text and preserved formatting. Automatically wrapped as `{"text":"..."}` |
+| `--markdown <string>` | One content option | Convenience Markdown input. Internally converted to `post` JSON with Feishu-specific normalization; not full Markdown passthrough |
+| `--content <json>` | One content option | Exact message content JSON string; use this when you need full control over `msg_type` and payload. The JSON must match the effective `--msg-type` |
+| `--image <path\|key>` | One content option | Local image path or `image_key` (`img_xxx`). Local paths are uploaded automatically |
+| `--file <path\|key>` | One content option | Local file path or `file_key` (`file_xxx`). Local paths are uploaded automatically |
+| `--video <path\|key>` | One content option | Local video path or `file_key`. Local paths are uploaded automatically. **Must be paired with `--video-cover`** |
+| `--video-cover <path\|key>` | **Required with `--video`** | Video cover image path or `image_key` (`img_xxx`). Local paths are uploaded automatically |
+| `--audio <path\|key>` | One content option | Local audio path or `file_key`. Local paths are uploaded automatically |
+| `--msg-type <type>` | No | Message type (default `text`). If you use `--text` / `--markdown` / media flags, the effective type is inferred automatically. Explicitly setting a conflicting `--msg-type` fails validation |
+| `--idempotency-key <key>` | No | Idempotency key; the same key sends only one message within 1 hour |
+| `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`) |
+| `--dry-run` | No | Print the request only, do not execute it |
+
+> **Mutual exclusivity rule:** `--text`, `--markdown`, `--content`, and `--image`/`--file`/`--video`/`--audio` cannot be used together. Media flags are also mutually exclusive with each other.
+>
+> **Video cover rule:** `--video` **must** be accompanied by `--video-cover`. Omitting `--video-cover` when using `--video` will fail validation. `--video-cover` cannot be used without `--video`.
+
+## Common Mistakes
+
+- Choosing `--markdown` when you actually need exact plain text. If exact line breaks and spacing matter, use `--text`, usually with `$'...'`.
+- Assuming `--markdown` supports all Markdown features. It does not; it is converted into a Feishu `post` payload and rewritten first.
+- Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths.
+- Using `--content` without making the JSON match the effective `--msg-type`.
+- Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
+- Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
+
+## `content` Format Reference
+
+| `msg_type` | Example `content` |
+|----------|-------------|
+| `text` | `{"text":"Hello <at user_id=\"ou_xxx\">name</at>"}` |
+| `post` | `{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"Body"}]]}}` |
+| `image` | `{"image_key":"img_xxx"}` |
+| `file` | `{"file_key":"file_xxx"}` |
+| `audio` | `{"file_key":"file_xxx"}` |
+| `media` | `{"file_key":"file_xxx","image_key":"img_xxx"}` (video; `image_key` is the cover from `--video-cover` — **required**) |
+| `share_chat` | `{"chat_id":"oc_xxx"}` |
+| `share_user` | `{"user_id":"ou_xxx"}` |
+| `interactive` | Card JSON (see Feishu interactive card documentation) |
+
+## Return Value
+
+```json
+{
+  "message_id": "om_xxx",
+  "chat_id": "oc_xxx",
+  "create_time": "1234567890"
+}
+```
+
+## @Mention Format (text / post)
+
+- Recommended format: `<at user_id="ou_xxx">name</at>`
+- @all: `<at user_id="all"></at>`
+- The shortcut normalizes common variants like `<at id=...>` and `<at open_id=...>` into `user_id`, but you should still document examples with `user_id`
+
+## Notes
+
+- `--chat-id` and `--user-id` are mutually exclusive; you must provide exactly one
+- `--content` must be valid JSON
+- When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
+- `--image`/`--file`/`--video`/`--audio` support local file paths; the shortcut uploads first and then sends the message; both the upload and send steps use the same identity (UAT when `--as user`, TAT when `--as bot`)
+- If the provided media value starts with `img_` or `file_`, it is treated as an existing key and used directly
+- `--markdown` always sends `msg_type=post`, even if you do not explicitly set `--msg-type post`
+- If you explicitly set `--msg-type` and it conflicts with the chosen content flag, validation fails
+- When using `--video`, `--video-cover` is required as the video cover
+- `--dry-run` uses placeholder image keys for remote Markdown images and placeholder media keys for local uploads
+- Failures return an error code and message
+- `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` and `im:message` scopes; the message is sent as the authorized end user
+- `--as bot` uses a tenant access token (TAT) and requires the `im:message:send_as_bot` scope
+- When sending as a bot, the app must already be in the target group or already have a direct-message relationship with the target user