From 37f4f899b252902da2e3aee633d3235df9e672b0 Mon Sep 17 00:00:00 2001
From: sammi-bytedance <wangjingjing.6508@bytedance.com>
Date: Mon, 15 Jun 2026 14:08:50 +0800
Subject: [PATCH] docs(lark-im): document @mention format per message type
 (text/post/card) (#1419)

Split the send/reply @Mention sections by message type:
- text: <at user_id="ou_xxx">name</at> (inner name optional), @all
- post: inline form in text/md elements, or a dedicated {"tag":"at"} node
- interactive card: card-native <at id=>, <at ids=>, <at email=>
---
 .../references/lark-im-messages-reply.md      | 22 ++++++++++++++++---
 .../references/lark-im-messages-send.md       | 22 ++++++++++++++++---
 2 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/skills/lark-im/references/lark-im-messages-reply.md b/skills/lark-im/references/lark-im-messages-reply.md
index b1b7257c1..72ceb8c6f 100644
--- a/skills/lark-im/references/lark-im-messages-reply.md
+++ b/skills/lark-im/references/lark-im-messages-reply.md
@@ -222,11 +222,27 @@ lark-cli im +messages-reply --message-id om_xxx --text "Let me take a look at th
 
 The reply appears in the target message's thread and does not show up in the main chat stream.
 
-## @Mention Format (text / post)
+## @Mention Format
 
-- Recommended format: `<at user_id="ou_xxx">name</at>`
+The `<at>` syntax differs by message type. The shortcut only normalizes mentions for `text` and `post`; `interactive` card content is passed through verbatim, so cards must use the card-native syntax below.
+
+### `text`
+
+- `<at user_id="ou_xxx">name</at>` — the inner text is the mentioned user's display name and is optional (`<at user_id="ou_xxx"></at>` also works)
 - @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
+
+### `post`
+
+- Inside a `text` or `md` element, the same inline form as `text` works: `<at user_id="ou_xxx">name</at>`
+- Or use a dedicated `at` element node: `{"tag":"at","user_id":"ou_xxx"}` (use `"all"` to mention everyone)
+
+### `interactive` (card)
+
+Card content is **not** normalized — use the card-native `<at>` syntax inside a `lark_md` / `markdown` element:
+
+- single user by open_id: `<at id=ou_xxx></at>`
+- multiple users: `<at ids=ou_xxx1,ou_xxx2></at>`
+- by email: `<at email=user@example.com></at>`
 
 ## Notes
 
diff --git a/skills/lark-im/references/lark-im-messages-send.md b/skills/lark-im/references/lark-im-messages-send.md
index 89bb02276..484c024f4 100644
--- a/skills/lark-im/references/lark-im-messages-send.md
+++ b/skills/lark-im/references/lark-im-messages-send.md
@@ -224,11 +224,27 @@ lark-cli im +messages-send --chat-id oc_xxx --markdown $'## Test\n\nhello' --dry
 }
 ```
 
-## @Mention Format (text / post)
+## @Mention Format
 
-- Recommended format: `<at user_id="ou_xxx">name</at>`
+The `<at>` syntax differs by message type. The shortcut only normalizes mentions for `text` and `post`; `interactive` card content is passed through verbatim, so cards must use the card-native syntax below.
+
+### `text`
+
+- `<at user_id="ou_xxx">name</at>` — the inner text is the mentioned user's display name and is optional (`<at user_id="ou_xxx"></at>` also works)
 - @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`
+
+### `post`
+
+- Inside a `text` or `md` element, the same inline form as `text` works: `<at user_id="ou_xxx">name</at>`
+- Or use a dedicated `at` element node: `{"tag":"at","user_id":"ou_xxx"}` (use `"all"` to mention everyone)
+
+### `interactive` (card)
+
+Card content is **not** normalized — use the card-native `<at>` syntax inside a `lark_md` / `markdown` element:
+
+- single user by open_id: `<at id=ou_xxx></at>`
+- multiple users: `<at ids=ou_xxx1,ou_xxx2></at>`
+- by email: `<at email=user@example.com></at>`
 
 ## Notes