@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-chat-messages-list.md

@@ -0,0 +1,142 @@
+# im +chat-messages-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Fetch the message list for a conversation. Supports both group chats and direct messages.
+
+This skill maps to the shortcut: `lark-cli im +chat-messages-list` (internally calls `GET /open-apis/im/v1/messages`, and automatically resolves the p2p chat_id when needed).
+
+## Commands
+
+```bash
+# Get group chat messages (json output by default)
+lark-cli im +chat-messages-list --chat-id oc_xxx
+
+# Get direct messages with a user (pass open_id and resolve p2p chat_id automatically)
+lark-cli im +chat-messages-list --user-id ou_xxx
+
+# Specify a time range (ISO 8601)
+lark-cli im +chat-messages-list --chat-id oc_xxx --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00"
+
+# Specify a time range (date only)
+lark-cli im +chat-messages-list --chat-id oc_xxx --start 2026-03-10 --end 2026-03-11
+
+# Control sort order and page size (max 50)
+lark-cli im +chat-messages-list --chat-id oc_xxx --sort asc --page-size 20
+
+# Pagination
+lark-cli im +chat-messages-list --chat-id oc_xxx --page-token "xxx"
+
+# JSON output
+lark-cli im +chat-messages-list --chat-id oc_xxx --format json
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--chat-id <id>` | One of two | Specify the conversation by its chat_id directly (e.g., group chat `oc_xxx`) |
+| `--user-id <id>` | One of two | Specify a DM conversation by the other user's open_id (`ou_xxx`); p2p chat_id is resolved automatically. Requires user identity (`--as user`); not supported with bot identity |
+| `--start <time>` | No | Start time (ISO 8601 or date only) |
+| `--end <time>` | No | End time (ISO 8601 or date only) |
+| `--sort <order>` | No | Sort order: `asc` / `desc` (default `desc`) |
+| `--page-size <n>` | No | Page size (default 50, max 50) |
+| `--page-token <token>` | No | Pagination token |
+
+> Rule: `--chat-id` and `--user-id` are mutually exclusive. You must provide exactly one of them.
+
+## Resource Rendering
+
+Messages are rendered into human-readable text for inspection. Image messages are shown as placeholders such as `[Image: img_xxx]`; files and videos are rendered with resource keys in the content. Resource binaries are **not** downloaded automatically by this command.
+
+Use [lark-im-messages-resources-download](lark-im-messages-resources-download.md) when you need to download an image or file from a specific message.
+
+| Resource Type | Marker in Content | Behavior |
+|---------|-------------|------|
+| Image | `[Image: img_xxx]` | Download manually with `im +messages-resources-download --type image` |
+| File | `<file key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+| Audio | `<audio key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+| Video | `<video key="file_xxx" .../>` | Download manually with `im +messages-resources-download --type file` |
+
+## Thread Expansion (`thread_id`)
+
+In JSON output, a message may contain a `thread_id` (`omt_xxx`) field, which means the message has replies in a thread. Use [`im +threads-messages-list`](lark-im-threads-messages-list.md) to inspect replies in that thread:
+
+```bash
+lark-cli im +threads-messages-list --thread omt_xxx
+```
+
+| Scenario | Recommendation |
+|------|------|
+| You need context | Call `im +threads-messages-list --sort desc --page-size 10` for the discovered thread_id to inspect recent replies |
+| The user asks for the "full discussion" | Use `im +threads-messages-list --sort asc --page-size 50`, then paginate if needed |
+| You only need an overview | Skip thread expansion |
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `messages` | Message array |
+| `total` | Number of messages in the current page |
+| `has_more` | Whether additional pages are available |
+| `page_token` | Pagination token for the next page |
+
+Each message 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 |
+| `deleted` | Whether the message has been recalled (always present, `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 |
+
+## Pagination (`has_more` / `page_token`)
+
+`im +chat-messages-list` returns `has_more` and `page_token` when more data is available. Use `--page-token` to continue:
+
+```bash
+lark-cli im +chat-messages-list --chat-id oc_xxx --page-token <PAGE_TOKEN>
+```
+
+You can also fall back to the generic API:
+
+```bash
+lark-cli api GET /open-apis/im/v1/messages \
+  --params 'container_id_type=chat&container_id=oc_xxx&page_size=50&page_token=<PAGE_TOKEN>'
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `specify --chat-id <chat_id> or --user-id <open_id>` | Neither `--chat-id` nor `--user-id` was provided | You must provide exactly one |
+| `--chat-id and --user-id cannot be specified together` | Both parameters were provided | Use only one |
+| `--user-id requires user identity (--as user); use --chat-id when calling with bot identity` | `--user-id` was used with bot identity | The p2p resolution endpoint requires user identity. Either pass `--as user` or look up the p2p `chat_id` separately and pass it via `--chat-id` |
+| `P2P chat not found for this user` | `--user-id` was used but no p2p chat exists for the current identity and that user | Confirm the target direct-message relationship exists for the current identity |
+| `--start: invalid time format` | Invalid time format | Use ISO 8601 or date-only format such as `2026-03-10` |
+| Permission denied | Message read permissions are missing | Ensure the app has `im:message:readonly` and `im:chat:read` enabled |
+
+## AI Usage Guidance
+
+1. **Resolving chat_id from a chat name:** When the user refers to a chat by name and you don't have the `chat_id`, use [`+chat-search`](lark-im-chat-search.md) first:
+   ```bash
+   # Find chat_id by name, then list messages
+   lark-cli im +chat-search --query "<chat name keyword>" --format json
+   lark-cli im +chat-messages-list --chat-id <chat_id>
+   ```
+   **Do not use `im chats search` or `im chats list` — always use the `+chat-search` shortcut.**
+2. **Prefer `--chat-id` when available:** if the chat_id is already known, use it directly to avoid extra API calls.
+3. **For direct messages:** use `--user-id` to resolve the p2p chat automatically instead of looking it up manually. This requires user identity (`--as user`); with bot identity, resolve the p2p `chat_id` yourself and pass it via `--chat-id`.
+4. **For time ranges:** both ISO 8601 and date-only inputs are supported. Date-only is usually simpler.
+5. **For full content:** table output truncates content. Use `--format json` when you need the complete message body.
+6. **For sender info:** the command already resolves sender names, so you do not need a separate lookup.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

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

@@ -0,0 +1,114 @@
+# im +chat-search
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Search the list of group chats visible to a user or bot, including chats the user or bot belongs to and public chats visible to them. Supports keyword matching on chat names and member names, including pinyin and prefix fuzzy search.
+
+This skill maps to the shortcut: `lark-cli im +chat-search` (internally calls `POST /open-apis/im/v2/chats/search`).
+
+## Commands
+
+```bash
+# Search chats by keyword
+lark-cli im +chat-search --query "project"
+
+# Restrict by search types
+lark-cli im +chat-search --query "project" --search-types "private,public_joined"
+
+# Filter by member open_ids (with keyword)
+lark-cli im +chat-search --query "project" --member-ids "ou_xxx,ou_yyy"
+
+# Search by member open_ids only
+lark-cli im +chat-search --member-ids "ou_xxx,ou_yyy"
+
+# Only show chats you created or manage
+lark-cli im +chat-search --query "project" --is-manager
+
+# Set page size
+lark-cli im +chat-search --query "project" --page-size 10
+
+# Pagination
+lark-cli im +chat-search --query "project" --page-token "xxx"
+
+# JSON output
+lark-cli im +chat-search --query "project" --format json
+
+# Preview the request without executing it
+lark-cli im +chat-search --query "project" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--query <keyword>` | No (at least one of `--query` / `--member-ids` required) | Max 64 characters | Search keyword. Supports matching localized chat names, member names, multilingual search, pinyin, and prefix fuzzy search. If the query contains `-`, it is automatically wrapped in quotes |
+| `--search-types <types>` | No | Comma-separated: `private`, `external`, `public_joined`, `public_not_joined` | Restrict the visible chat types returned by search |
+| `--member-ids <ids>` | No (at least one of `--query` / `--member-ids` required) | Up to 50, format `ou_xxx` | Filter by member open_ids; can be used alone or combined with `--query` |
+| `--is-manager` | No | - | Only show chats you created or manage |
+| `--disable-search-by-user` | No | - | Disable member-name-based matching and search by group name only |
+| `--sort-by <field>` | No | `create_time_desc`, `update_time_desc`, `member_count_desc` | Sort field in descending order |
+| `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
+| `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **Note:** Supports both `--as user` (default) and `--as bot`. When using bot identity, the app must have bot capability enabled.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+
+## Usage Scenarios
+
+### Scenario 1: Search chats that contain a keyword
+
+```bash
+lark-cli im +chat-search --query "design review"
+```
+
+### Scenario 2: Search a chat and list recent messages
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "project" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +chat-messages-list --chat-id "$CHAT_ID"
+```
+
+### Scenario 3: Search a chat and send a message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-search --query "daily report" --format json | jq -r '.data.chats[0].chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Today's progress update"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--query and --member-ids cannot both be empty` | Both were omitted | Provide at least `--query` or `--member-ids` |
+| Empty results | No visible chats matched the keyword or filters | Relax the keyword or filters and try again |
+| `--page-size must be an integer between 1 and 100` | page-size is out of range or not an integer | Use an integer between 1 and 100 |
+| Permission denied (99991672) | The bot app does not have `im:chat:read` TAT permission enabled | Enable the permission for the app in the Open Platform console |
+| Permission denied (99991679) with `--as user` | UAT is not authorized for `im:chat:read` | Follow `cli-skills/lark-shared/SKILL.md` §Agent 代理发起认证 canonical template to top up the `im:chat:read` scope (agent runs `--no-wait --json` itself; user only clicks the auth link) |
+| `Bot ability is not activated` (232025) | The app does not have bot capability enabled | Enable bot capability in the Open Platform console |
+
+## AI Usage Guidance
+
+When the user asks to search chats, follow these rules:
+
+1. **At least one filter required:** `--query` and `--member-ids` cannot both be empty. Either alone or combined together are valid.
+2. **Search scope is limited:** only chats visible to the current user or bot can be found (joined chats plus public chats). This is not a global search over all chats.
+3. **Control result volume:** the result set may be large. Use `--page-size` deliberately.
+4. **Suggest follow-up actions:** after finding a chat, common next steps include listing recent messages (`im +chat-messages-list`) or sending a message (`im +messages-send`).
+5. **NEVER fall back to chats list:** If `+chat-search` returns empty results, do NOT attempt to use `im chats list` or `GET /open-apis/im/v1/chats` as a fallback. The list API is not a search API — it returns all chats without keyword filtering and will not help locate the target chat. Instead, ask the user to refine the keyword or check whether the chat is visible to the current identity.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/server/assets/skills/lark-tools/cli-skills/lark-im/references/lark-im-chat-update.md

@@ -0,0 +1,84 @@
+# im +chat-update
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Update a group's name or description. Supports both **TAT (bot)** and **UAT (user)** identity.
+
+This skill maps to the shortcut: `lark-cli im +chat-update` (internally calls `PUT /open-apis/im/v1/chats/:chat_id`).
+
+## Commands
+
+```bash
+# Update the group name
+lark-cli im +chat-update --chat-id oc_xxx --name "New Group Name"
+
+# Update the group description
+lark-cli im +chat-update --chat-id oc_xxx --description "Updated group description"
+
+# Update multiple fields at once
+lark-cli im +chat-update --chat-id oc_xxx \
+  --name "Q2 Project Team" \
+  --description "Owns Q2 goal tracking"
+
+# Preview the request without executing it
+lark-cli im +chat-update --chat-id oc_xxx --name "Test" --dry-run
+```
+
+## Parameters
+
+### Required
+
+| Parameter | Description |
+|------|------|
+| `--chat-id <oc_xxx>` | Group ID |
+
+### Optional Fields
+
+| Parameter | Limits | Description |
+|------|------|------|
+| `--name <name>` | Max 60 characters | Group name |
+| `--description <text>` | Max 100 characters | Group description |
+
+### Global Parameters
+
+| Parameter | Description |
+|------|------|
+| `--format json` | Output as JSON (default) |
+| `--dry-run` | Preview the request without executing it |
+
+## Usage Scenarios
+
+### Scenario 1: Rename a group and update its description
+
+```bash
+lark-cli im +chat-update --chat-id oc_xxx \
+  --name "Q2 Project Team" \
+  --description "Owns Q2 goal tracking"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `invalid --chat-id: expected chat ID (oc_xxx)` | Invalid chat_id format | Use a valid `oc_xxx` chat ID |
+| `--name exceeds the maximum of 60 characters` | Group name too long | Shorten the name to 60 characters or fewer |
+| `--description exceeds the maximum of 100 characters` | Group description too long | Shorten the description to 100 characters or fewer |
+| `at least one field must be specified to update` | No update field was provided | Specify at least one field to update |
+| Permission denied (99991679) | Missing `im:chat:update` permission | Follow `cli-skills/lark-shared/SKILL.md` §Agent 代理发起认证 canonical template to top up the `im:chat:update` scope (agent runs `--no-wait --json` itself; user only clicks the auth link) |
+| Non-owner/admin cannot update (232016/232002/232017) | Current identity is not the owner/admin | Try switching identity with `--as bot` or `--as user` |
+| Not in the group (232011) | The current user is not a member of the group | Use a member identity (`--as bot`) or join the group first |
+
+## AI Usage Guidance
+
+### Identity Selection
+
+`+chat-update` supports both user and bot identity (`--as user` / `--as bot`).
+
+Infer the group owner from context whenever possible (for example, if a bot just created the group, the owner is the bot) and use the matching identity directly. If ownership is unclear, query the group first and confirm `owner_id`.
+
+Identity choice should follow [Group Chat Identity Rules](lark-im-chat-identity.md): if the user explicitly specifies an identity, use it directly; otherwise infer the owner identity from context.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM 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-mget.md

@@ -0,0 +1,95 @@
+# im +messages-mget
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Fetch message details in batch. Given a list of message IDs, this returns the full content for multiple messages in one call and automatically resolves sender names.
+
+> **Supports both `--as user` (default) and `--as bot`.**
+
+This skill maps to the shortcut: `lark-cli im +messages-mget` (internally calls `GET /open-apis/im/v1/messages/mget`).
+
+## Commands
+
+```bash
+# Fetch a single message
+lark-cli im +messages-mget --message-ids om_xxx
+
+# Fetch multiple messages in batch (comma-separated)
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb,om_ccc"
+
+# JSON output
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb" --format json
+
+# Preview the request without executing it
+lark-cli im +messages-mget --message-ids "om_aaa" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--message-ids <ids>` | Yes | At least one, max 50, `om_xxx` format, comma-separated | Message ID list |
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `messages` | Message array |
+| `total` | Number of messages returned |
+
+Each message contains:
+
+| Field | Description |
+|------|------|
+| `message_id` | Message ID |
+| `msg_type` | Message type (`text`, `image`, `file`, etc.) |
+| `create_time` | Creation time |
+| `sender` | Sender information (includes `name`) |
+| `content` | Message content |
+
+## Usage Scenarios
+
+### Scenario 1: Fetch the full content of a specific message
+
+```bash
+lark-cli im +messages-mget --message-ids om_xxx --format json
+```
+
+### Scenario 2: Fetch multiple messages in one batch
+
+```bash
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb,om_ccc"
+```
+
+### Scenario 3: Use together with the message list command
+
+First get message IDs via `+chat-messages-list`, then fetch full content via `+messages-mget`:
+
+```bash
+# Get the message list
+lark-cli im +chat-messages-list --chat-id oc_xxx --format json
+
+# Fetch specific message details
+lark-cli im +messages-mget --message-ids "om_aaa,om_bbb"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--message-ids requires at least one message ID` | No message ID was provided | Provide at least one message ID |
+| `invalid message ID: must start with om_` | Invalid message ID format | Message IDs must start with `om_` |
+| Permission denied | Message read permission is missing | Ensure the app has `im:message:readonly` and `contact:user.base:readonly` enabled |
+| Empty result | Message IDs do not exist or are not accessible | Verify the IDs and access permissions |
+
+## AI Usage Guidance
+
+1. **Use JSON for full content:** table output truncates content. Use `--format json` when the full body matters.
+2. **Sender names are already enriched:** the command resolves sender names automatically, so no extra lookup is required.
+3. **Images are rendered as placeholders:** image messages appear as placeholders such as `[Image: img_xxx]`. Use `+messages-resources-download` when you need the binary resource.
+4. **Batching is more efficient:** fetching multiple IDs in one request is better than calling the API repeatedly.
+
+## References
+
+- [lark-im](../SKILL.md) - all IM 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-reply.md

@@ -0,0 +1,222 @@
+# im +messages-reply
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Reply to a specific message. Supports both user identity (`--as user`) and bot identity (`--as bot`). Also supports thread replies.
+
+This skill maps to the shortcut: `lark-cli im +messages-reply` (internally calls `POST /open-apis/im/v1/messages/:message_id/reply`).
+
+## Safety Constraints
+
+Replies sent by this tool are visible to other people. Before calling it, you **must** confirm with the user:
+
+1. Which message to reply to
+2. The reply content
+3. Which identity to use (user or bot)
+
+**Do not** send a reply without explicit user approval.
+
+When using `--as bot`, the reply 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 reply 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 |
+|------|------|------|
+| Reply with plain text exactly as written | `--text` | Wrapped directly to `{"text":"..."}` |
+| Reply with simple Markdown and accept conversion | `--markdown` | Automatically converted to `post` JSON |
+| Precisely control the reply payload | `--content` | You provide the exact JSON |
+| Reply with media | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads local files automatically |
+
+### `--text` vs `--markdown`
+
+- Use `--text` when the reply should remain plain text and you want exact control over line breaks, spacing, indentation, code samples, or literal Markdown characters.
+- Use `--markdown` when you want a lightweight formatted reply and you accept that the shortcut will normalize and rewrite parts of the content before sending.
+- Use `--content` when you need exact `post` JSON, a card, a title, multiple locales, or any structure that `--markdown` cannot express reliably.
+
+## What `--markdown` Really Does
+
+`--markdown` does **not** send arbitrary raw Markdown to the API.
+
+The shortcut:
+
+1. Forces `msg_type=post`
+2. Resolves remote Markdown images like `![x](https://...)`
+3. Normalizes the Markdown for Feishu post rendering
+4. Wraps the final content as:
+
+```json
+{"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}}
+```
+
+So `--markdown` is a convenience mode, not a full Markdown compatibility layer.
+
+### 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.
+- 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 remote `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`.
+- If remote Markdown image handling fails, that image is removed with a warning.
+
+If you need exact output, use `--msg-type post --content ...` instead of `--markdown`.
+
+## Preserving Formatting
+
+If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'`.
+
+### When formatting must be preserved
+
+Use `--text` plus `$'...'`:
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'Received\nI will check this today.\nOwner: alice'
+```
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'```sql\nselect * from jobs;\n```'
+```
+
+This keeps the reply as plain text instead of converting it to a `post`.
+
+### When formatting does not need exact preservation
+
+Use `--markdown`:
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Follow-up\n\n- I reproduced it\n- I am fixing it'
+```
+
+This is better for quick readable formatting, but the final payload may still differ from the source text because headings and spacing are normalized before sending.
+
+## Commands
+
+```bash
+# Reply to a message (plain text, --text is recommended for normal replies)
+lark-cli im +messages-reply --message-id om_xxx --text "Received"
+
+# Equivalent manual JSON
+lark-cli im +messages-reply --message-id om_xxx --content '{"text":"Received"}'
+
+# Reply as a bot
+lark-cli im +messages-reply --message-id om_xxx --text "bot reply" --as bot
+
+# Reply with preserved multi-line text
+lark-cli im +messages-reply --message-id om_xxx --text $'Line 1\nLine 2\n  indented line'
+
+# Reply inside the thread (message appears in the target thread)
+lark-cli im +messages-reply --message-id om_xxx --text "Let's discuss this" --reply-in-thread
+
+# Reply with basic Markdown (will be converted to post JSON)
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Reply\n\n- item 1\n- item 2'
+
+# If you need exact post structure, send JSON directly
+lark-cli im +messages-reply --message-id om_xxx --msg-type post --content '{"zh_cn":{"title":"Reply","content":[[{"tag":"text","text":"Detailed content"}]]}}'
+
+# Reply with a local image (uploaded automatically before sending)
+lark-cli im +messages-reply --message-id om_xxx --image ./photo.png
+
+# Reply with a local file (uploaded automatically before sending)
+lark-cli im +messages-reply --message-id om_xxx --file ./report.pdf
+
+# Reply with a local video (--video-cover is required as the video cover)
+lark-cli im +messages-reply --message-id om_xxx --video ./demo.mp4 --video-cover ./cover.png
+
+# With an idempotency key
+lark-cli im +messages-reply --message-id om_xxx --text "Received" --idempotency-key my-unique-id
+
+# Preview the request without executing it
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--message-id <id>` | Yes | ID of the message being replied to (`om_xxx`) |
+| `--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 |
+| `--content <json>` | One content option | Exact reply content as JSON. The JSON must match the effective `--msg-type` |
+| `--text <string>` | One content option | Plain text reply. Best default when you need exact text and formatting preservation |
+| `--markdown <string>` | One content option | Convenience Markdown input. Internally converted to `post` JSON with Feishu-specific normalization |
+| `--image <path\|key>` | One content option | Local image path or `image_key` (`img_xxx`) |
+| `--file <path\|key>` | One content option | Local file path or `file_key` (`file_xxx`) |
+| `--video <path\|key>` | One content option | Local video path or `file_key`; **must be used together with `--video-cover`** |
+| `--video-cover <path\|key>` | **Required with `--video`** | Video cover image path or `image_key` (`img_xxx`) |
+| `--audio <path\|key>` | One content option | Local audio path or `file_key` |
+| `--reply-in-thread` | No | Reply inside the thread. The reply appears in the target message's thread instead of the main chat stream |
+| `--idempotency-key <key>` | No | Idempotency key; the same key sends only one reply 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.
+
+## Return Value
+
+```json
+{
+  "message_id": "om_xxx",
+  "chat_id": "oc_xxx",
+  "create_time": "1234567890"
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: Reply in the main chat stream
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text "OK, I will handle it"
+```
+
+The reply appears in the main chat stream and references the target message.
+
+### Scenario 2: Reply inside a thread
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text "Let me take a look at this" --reply-in-thread
+```
+
+The reply appears in the target message's thread and does not show up in the main chat stream.
+
+## @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 `user_id` remains the recommended documented form
+
+## Notes
+
+- `--message-id` must be a valid message ID in `om_xxx` format
+- `--content` must be valid JSON
+- When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
+- `--reply-in-thread` adds `reply_in_thread=true` to the API request
+- `--reply-in-thread` is mainly meaningful in chats that support thread replies
+- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support local file paths; the shortcut uploads first and then sends the reply; 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`
+- 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 error codes and messages
+- `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` and `im:message` scopes; the reply is sent as the authorized end user
+- `--as bot` uses a tenant access token (TAT), and requires the `im:message:send_as_bot` scope