From d26c5e1dea456abbdb782fb4b865fadee1f451c6 Mon Sep 17 00:00:00 2001 From: "liujiashu.shiro" Date: Wed, 3 Jun 2026 11:14:27 +0800 Subject: [PATCH] feat: improve lark im markdown guidance --- .../references/lark-im-messages-reply.md | 51 +++++++++---------- .../references/lark-im-messages-send.md | 51 +++++++++---------- 2 files changed, 48 insertions(+), 54 deletions(-) diff --git a/skills/lark-im/references/lark-im-messages-reply.md b/skills/lark-im/references/lark-im-messages-reply.md index 9e8cc2180f..b1b7257c10 100644 --- a/skills/lark-im/references/lark-im-messages-reply.md +++ b/skills/lark-im/references/lark-im-messages-reply.md @@ -22,22 +22,28 @@ When using `--as user`, the reply is sent as the authorized end user and require ## Choose The Right Content Flag +### Default Selection Rule For Agents + +- Prefer `--markdown` for headings, lists, links, summaries, investigation notes, or Markdown-looking content. +- Use `--text` for exact plain text: logs, code, indentation-sensitive text, or literal Markdown. +- Use `--content` for exact `post` JSON, titles, multiple locales, cards, or unsupported structures. + | 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 | +| Reply with headings, lists, links, summaries, or investigation notes | `--markdown` | Best default for lightweight formatting; converted to Feishu `post` JSON | +| Reply with plain text exactly as written | `--text` | Preserves literal text; no Markdown conversion | | Precisely control the reply payload | `--content` | You provide the exact JSON | | Reply with media | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads URLs, or cwd-relative 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 `--markdown` for lightweight formatted replies. +- Use `--text` for exact plain text, especially logs, code, indentation, or literal Markdown characters. - 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. +`--markdown` accepts Markdown-like input and converts it to the Feishu `post` payload required by the reply API. The shortcut: @@ -50,9 +56,9 @@ The shortcut: {"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}} ``` -So `--markdown` is a convenience mode, not a full Markdown compatibility layer. +This makes `--markdown` the simplest path for lightweight formatted replies. -### Current Markdown Caveats +### Markdown Boundaries - It does **not** promise full CommonMark / GitHub Flavored Markdown support. - It always becomes a `post` payload with a single `zh_cn` locale. @@ -68,7 +74,7 @@ So `--markdown` is a convenience mode, not a full Markdown compatibility layer. - Local paths (e.g. `![x](./a.png)`) are **not** supported directly in `--markdown` and will not be auto-uploaded. - Remote URLs (`https://...`) will be auto-downloaded and uploaded at runtime; if the download or upload fails, the image is removed with a warning. -If you need exact output, use `--msg-type post --content ...` instead of `--markdown`. +If you need a title, multiple locales, cards, unsupported rich structures, or byte-for-byte post JSON control, use `--msg-type post --content ...`. ### Image Constraint for `--markdown` @@ -87,7 +93,7 @@ lark-cli im +messages-reply --message-id om_xxx --markdown $'## Result\n\n![diag ## Preserving Formatting -If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'`. +If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'` for either `--markdown` or `--text`. ### When formatting must be preserved @@ -103,20 +109,13 @@ lark-cli im +messages-reply --message-id om_xxx --text $'```sql\nselect * from j 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) +# Reply with a formatted update +lark-cli im +messages-reply --message-id om_xxx --markdown $'## Reply\n\n- item 1\n- item 2' + +# Reply with a plain one-line message lark-cli im +messages-reply --message-id om_xxx --text "Received" # Equivalent manual JSON @@ -131,9 +130,6 @@ lark-cli im +messages-reply --message-id om_xxx --text $'Line 1\nLine 2\n inden # 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' - # Reply with Markdown containing an image (must pre-upload via images.create) lark-cli im images create --data '{"image_type":"message"}' --file ./screenshot.png # Use the returned image_key @@ -171,8 +167,8 @@ lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' - | `--message-id ` | Yes | ID of the message being replied to (`om_xxx`) | | `--msg-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 ` | One content option | Exact reply content as JSON. The JSON must match the effective `--msg-type` | -| `--text ` | One content option | Plain text reply. Best default when you need exact text and formatting preservation | -| `--markdown ` | One content option | Convenience Markdown input. Internally converted to `post` JSON with Feishu-specific normalization | +| `--text ` | One content option | Plain text reply. Use when exact text and formatting preservation matter | +| `--markdown ` | One content option | Best default for lightweight formatted replies such as headings, lists, links, summaries, and investigation notes. Internally converted to `post` JSON with Feishu-specific normalization | | `--image ` | One content option | Cwd-relative local image path, URL, or `image_key` (`img_xxx`) | | `--file ` | One content option | Cwd-relative local file path, URL, or `file_key` (`file_xxx`) | | `--video ` | One content option | Cwd-relative local video path, URL, or `file_key` (`file_xxx`); **must be used together with `--video-cover`** | @@ -189,8 +185,9 @@ lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' - ## 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. +- Choosing `--text` for headings, lists, links, summaries, or investigation notes. Use `--markdown`. +- Choosing `--markdown` when you actually need exact plain text. If exact line breaks, spacing, logs, code, or literal Markdown characters matter, use `--text`, usually with `$'...'`. +- Assuming `--markdown` supports every Markdown feature. It is converted into a Feishu `post` payload and normalized first. - Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths. - **Using local file paths inside Markdown image syntax** (e.g. `![x](./a.png)`) with `--markdown`. Local paths are not auto-uploaded and will not render as an image. Pre-upload via `images.create` to get an `image_key` instead. - Using `--content` without making the JSON match the effective `--msg-type`. diff --git a/skills/lark-im/references/lark-im-messages-send.md b/skills/lark-im/references/lark-im-messages-send.md index 319aa2a29b..89bb022761 100644 --- a/skills/lark-im/references/lark-im-messages-send.md +++ b/skills/lark-im/references/lark-im-messages-send.md @@ -22,22 +22,28 @@ When using `--as user`, the message is sent as the authorized end user and requi ## Choose The Right Content Flag +### Default Selection Rule For Agents + +- Prefer `--markdown` for headings, lists, links, summaries, reports, or Markdown-looking content. +- Use `--text` for exact plain text: logs, code, indentation-sensitive text, or literal Markdown. +- Use `--content` for exact `post` JSON, titles, multiple locales, cards, or unsupported structures. + | 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 | +| Send headings, lists, links, summaries, or reports | `--markdown` | Best default for lightweight formatting; converted to Feishu `post` JSON | +| Send plain text exactly as written | `--text` | Preserves literal text; no Markdown conversion | | 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 URLs, or cwd-relative 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 `--markdown` for lightweight formatted messages. +- Use `--text` for exact plain text, especially logs, code, indentation, or Markdown characters that should **not** render. - 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. +`--markdown` accepts Markdown-like input and converts it to the Feishu `post` payload required by the message API. The shortcut does all of the following before sending: @@ -50,9 +56,9 @@ The shortcut does all of the following before sending: {"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}} ``` -This means `--markdown` is convenient, but it is not a full-fidelity Markdown transport. +This makes `--markdown` the simplest path for lightweight formatted messages. -### Current Markdown Caveats +### Markdown Boundaries - It does **not** promise full CommonMark / GitHub Flavored Markdown support. - It always becomes a `post` payload with a single `zh_cn` locale. @@ -68,7 +74,7 @@ This means `--markdown` is convenient, but it is not a full-fidelity Markdown tr - Local paths in Markdown image syntax like `![x](./a.png)` are **not** supported and will not be auto-uploaded. - Remote URLs (`https://...`) will be auto-downloaded and uploaded at runtime; if the download or upload fails, the 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. +If you need a title, multiple locales, cards, unsupported rich structures, or byte-for-byte post JSON control, use `--content` and provide the final JSON yourself. ### Image Constraint for `--markdown` @@ -87,7 +93,7 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Report\n\n![diagram] ## Preserving Formatting -If the message has multiple lines, indentation, code blocks, tabs, or many quotes/backslashes, prefer shell ANSI-C quoting with `$'...'`. +If the message has multiple lines, indentation, code blocks, tabs, or many quotes/backslashes, prefer shell ANSI-C quoting with `$'...'` for either `--markdown` or `--text`. This is especially useful in `zsh` / `bash` because it lets you write `\n` explicitly instead of relying on the shell to preserve literal newlines. @@ -105,20 +111,13 @@ lark-cli im +messages-send --chat-id oc_xxx --text $'```bash\nmake test\nmake li 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) +# Send a formatted update +lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Update\n\n- item 1\n- item 2' + +# Send a plain one-line message lark-cli im +messages-send --chat-id oc_xxx --text "Hello" # Equivalent manual JSON @@ -130,9 +129,6 @@ 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' - # Send Markdown with an image (must pre-upload via images.create) lark-cli im images create --data '{"image_type":"message"}' --file ./screenshot.png # Use the returned image_key in the markdown content @@ -176,8 +172,8 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry |------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--chat-id ` | One of two | Group chat ID (`oc_xxx`) | | `--user-id ` | One of two | User open_id (`ou_xxx`) for direct messages | -| `--text ` | One content option | Plain text message. Best default for exact text and preserved formatting. Automatically wrapped as `{"text":"..."}` | -| `--markdown ` | One content option | Convenience Markdown input. Internally converted to `post` JSON with Feishu-specific normalization; not full Markdown passthrough | +| `--text ` | One content option | Plain text message. Use when exact text and formatting preservation matter. Automatically wrapped as `{"text":"..."}` | +| `--markdown ` | One content option | Best default for lightweight formatted messages such as headings, lists, links, summaries, and reports. Internally converted to `post` JSON with Feishu-specific normalization | | `--content ` | 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 ` | One content option | Cwd-relative local image path, URL, or `image_key` (`img_xxx`). Local paths and URLs are uploaded automatically | | `--file ` | One content option | Cwd-relative local file path, URL, or `file_key` (`file_xxx`). Local paths and URLs are uploaded automatically | @@ -195,8 +191,9 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry ## 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. +- Choosing `--text` for headings, lists, links, summaries, or reports. Use `--markdown`. +- Choosing `--markdown` when you actually need exact plain text. If exact line breaks, spacing, logs, code, or literal Markdown characters matter, use `--text`, usually with `$'...'`. +- Assuming `--markdown` supports every Markdown feature. It is converted into a Feishu `post` payload and normalized first. - Putting local image paths inside Markdown like `![x](./a.png)`. `--markdown` does not auto-upload those paths. - **Using local file paths inside Markdown image syntax** (e.g. `![x](./a.png)`) with `--markdown`. Local paths are not auto-uploaded and will not render as an image. Pre-upload via `images.create` to get an `image_key` instead. - Using `--content` without making the JSON match the effective `--msg-type`.