feishu-user-plugin 1.3.1 → 1.3.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.2.0",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats, manage docs/tables/wiki. 33 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.3",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs/tables/wiki. 67 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.3.3] - 2026-04-20
+
+### Fixed
+- **MCP mid-session disconnect (root fix)**: All raw `fetch` calls to Feishu now go through `fetchWithTimeout` (AbortController, 30s default). A stalled connection used to hang a tool handler indefinitely; the MCP client would time out and some clients tore down the stdio transport — observed as "MCP 中途掉线" on v1.3.2. This was the real cause, not just the v1.3.1 stdout pollution.
+- **stdout pollution (defense-in-depth)**: `src/index.js` now globally redirects `console.log` / `console.info` to stderr at startup, before any other `require`. Any current or future dependency that accidentally writes to stdout can no longer corrupt the JSON-RPC channel. (v1.3.1's Lark-SDK-specific logger override stays as-is.)
+- **`(as user)` label lied for docs/bitable/folder creation**: `create_doc` / `create_bitable` / `create_folder` previously labeled every successful call `(as user)` whenever `LARK_USER_ACCESS_TOKEN` was set, even when the UAT call actually failed and silently fell back to app identity. `_asUserOrApp` now threads a real `_viaUser` flag through; failures show `(as app — UAT unavailable or failed; <resource> owned by the app, not you)`.
+
+### Added
+- **APP_ID startup validation**: MCP server probes `/auth/v3/app_access_token/internal` at boot. Invalid `LARK_APP_ID` / `LARK_APP_SECRET` (wrong-tenant, stale, or hallucinated by an autoinstall) now produce a clear stderr error pointing at the team-skills install prompt. Non-blocking — users running cookie-only workflows are unaffected.
+- **`get_login_status` shows app identity**: Now returns the actual `app_id` plus fetched app name, so users can immediately spot "this isn't my team's app" scenarios.
+- **`download_image` tool**: Download an image embedded in a message by `message_id` + `image_key`, returned as MCP image content so the model can see the pixels (not just the key string). Tries UAT first (works for any chat the user is in); falls back to app token (requires the bot to be in the chat).
+
+### Changed
+- Tool count 66 → **67** (added `download_image`).
+- README tool badge corrected from 76 → 67 (previous 76 was stale and never matched the actual export).
+
 ## [1.1.3] - 2026-03-11
 
 ### Fixed

package/README.md

@@ -3,10 +3,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-76-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-67-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 76 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
+**All-in-one Feishu/Lark MCP Server -- 67 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
 
 The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.
 
@@ -337,7 +337,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (76 total)
+## Tools (67 total)
 
 ### User Identity -- Messaging (8 tools, cookie auth)
 
@@ -390,6 +390,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `add_members` | Add users to a group |
 | `remove_members` | Remove users from a group |
 | `upload_image` / `upload_file` | Upload image/file, returns key for sending |
+| `download_image` | Download an image from a message by message_id + image_key, returned as MCP image content so the model can see the pixels |
 
 ### Official API -- Documents (7 tools)
 
@@ -508,7 +509,7 @@ feishu-user-plugin/
 │       ├── SKILL.md         # Main skill definition (trigger, tools, auth)
 │       └── references/      # 8 skill reference docs + CLAUDE.md
 ├── src/
-│   ├── index.js             # MCP server entry point (76 tools)
+│   ├── index.js             # MCP server entry point (67 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.1",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 66 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.3",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 67 tools + 9 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"

package/proto/lark.proto

@@ -140,6 +140,19 @@ message RichText {
   repeated string elementIds = 1;
   optional string innerText = 2;
   optional RichTextElements elements = 3;
+  // Index fields: each "*Ids" is a list of elemIds (pointing into the dictionary)
+  // that the server needs to register as special-type elements. Discovered from
+  // Feishu Web bundle — atIds=6 is what makes @-mentions actually notify.
+  repeated string imageIds = 5;
+  repeated string atIds = 6;
+  repeated string anchorIds = 7;
+  repeated string i18nIds = 8;
+  repeated string mediaIds = 9;
+  repeated string docsIds = 10;
+  repeated string interactiveIds = 11;
+  repeated string mentionIds = 12;
+  optional int32 version = 13;
+  repeated string atUserGroupIds = 14;
 }
 
 message RichTextElements {
@@ -167,6 +180,20 @@ message TextProperty {
   optional string content = 1;
 }
 
+// For AT (@-mention) elements. Both fields are required in the real schema;
+// `content` is marked deprecated but still required on the wire.
+message AtProperty {
+  optional string userId = 1;
+  optional string content = 2;
+}
+
+// For A (hyperlink) elements.
+message AnchorProperty {
+  optional string href = 1;
+  optional string content = 2;
+  optional string textContent = 3;
+}
+
 // --- Chat Operations ---
 
 // Create P2P chat (cmd=13)

package/skills/feishu-user-plugin/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.1.3"
-description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki. Replaces and extends the official Feishu MCP."
-allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, list_files, create_folder, find_user
+version: "1.3.3"
+description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki, download images. Replaces and extends the official Feishu MCP."
+allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, list_files, create_folder, find_user, download_image
 user_invocable: true
 ---
 

package/skills/feishu-user-plugin/references/CLAUDE.md

@@ -6,7 +6,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts, upload files
 - **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
-## Tool Categories (66 tools)
+## Tool Categories (67 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -14,7 +14,8 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `send_as_user` — Send text to any chat by ID, supports reply threading (root_id/parent_id)
 - `send_image_as_user` — Send image (requires image_key from `upload_image`)
 - `send_file_as_user` — Send file (requires file_key from `upload_file`)
-- `send_post_as_user` — Send rich text with title + formatted paragraphs
+- `send_post_as_user` — Send rich text with title + formatted paragraphs. Elements: `{tag:"text"}`, `{tag:"a",href,text}`, `{tag:"at",userId,name}`. **@-mentions trigger real notifications** (fixed by registering AT element IDs in RichText.atIds field 6 — reverse-engineered from Feishu Web bundle's AtProperty + RichText schemas).
+- `send_as_user` / `send_to_user` / `send_to_group` — plain text sends now accept optional `ats: [{userId, name}]`; the text must contain the `@<name>` marker for each entry. The marker is spliced into a real AT element so the mentioned user is notified. Identity is the cookie user (not bot).
 - `send_sticker_as_user` — Send sticker/emoji
 - `send_audio_as_user` — Send audio message
 
@@ -28,7 +29,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 ### User OAuth UAT Tools (P2P chat reading + user-identity creation)
 - `read_p2p_messages` — Read P2P (direct message) chat history. chat_id accepts both numeric IDs (from create_p2p_chat) and oc_xxx format. Returns newest messages first by default.
 - `list_user_chats` — List group chats the user is in. Note: API only returns groups, not P2P. For P2P, use: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
-- `create_doc` / `create_bitable` / `create_folder` — **UAT-first**: creates resources as the user (not the app) when UAT with write scopes is available. Falls back to app token.
+- **All docx + bitable + drive create/read/write tools are UAT-first**: when UAT is configured, every operation (create/edit/delete doc blocks, bitable tables/fields/views/records, drive folders) tries the user's token first and falls back to app token on failure. This keeps resources consistently owned by the user and avoids 403 errors when the app can't access user-created resources. Read-only tools (e.g. `read_doc`, `get_doc_blocks`, `list_bitable_tables`) are also UAT-first so user-owned resources remain readable.
 
 ### Official API Tools (app credentials)
 - `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names.
@@ -51,6 +52,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `list_files` / `create_folder` — Drive
 - `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
 - `upload_image` / `upload_file` — Upload image/file, returns key for send_image/send_file
+- `download_image` — Download an image from a message (needs message_id + image_key from read_messages) and return it as MCP image content so the model can **see the pixels**, not just the key. Tries UAT first, falls back to app token (app path requires the bot to be in the chat).
 - `find_user` — Contact lookup by email/mobile
 
 ## Usage Patterns
@@ -59,7 +61,9 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - Send text as yourself → `send_to_user` or `send_to_group`
 - Send image → `upload_image` → `send_image_as_user`
 - Send file → `upload_file` → `send_file_as_user`
-- Send rich content → `send_post_as_user` (formatted text with links, @mentions)
+- Send rich content → `send_post_as_user` (formatted text + links + real @-mentions via `{tag:"at",userId,name}`)
+- Send text with @-mentions (plain text) → `send_as_user` / `send_to_user` / `send_to_group` with `ats:[{userId,name}]` + text containing `@<name>` markers
+- Bot-identity @-mention alternative → `send_message_as_bot` with `<at user_id="ou_xxx">Name</at>` inline in content text
 - Reply as user in thread → `send_as_user` with root_id
 - Reply as bot → `reply_message` (official API)
 
@@ -230,9 +234,21 @@ Tell user to restart Claude Code. Only ONE restart should be needed.
 ## Troubleshooting Guide
 
 ### If MCP disconnects mid-session
-- **Root cause** (fixed in v1.3.1): `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP protocol uses stdout for JSON-RPC, so SDK error logs corrupt the transport and cause immediate disconnect.
-- **Fix**: Custom logger redirects all SDK output to stderr. Already applied in `src/official.js`.
-- If still happening: check for any `console.log` calls in server code (only `console.error` is safe in MCP servers).
+Two known root causes, both fixed in v1.3.3:
+
+1. **stdout pollution** (partial fix in v1.3.1, fully closed in v1.3.3):
+   - `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP uses stdout for JSON-RPC, so any stray write corrupts the transport and disconnects the client.
+   - v1.3.1 replaced the SDK's logger. v1.3.3 also globally redirects `console.log` / `console.info` → `console.error` at the top of `src/index.js` as defense-in-depth against ANY future dependency leaking to stdout.
+
+2. **unbounded fetch hangs** (fixed in v1.3.3):
+   - All raw `fetch` calls to `feishu.cn` / `internal-api-lark-api.feishu.cn` used to have no timeout. A stalled connection (ECONNRESET, slow DNS, upstream hang) would block a tool handler indefinitely; the MCP client times out the request, which some clients handle by tearing down the stdio transport — observed as "mid-session disconnect".
+   - Fix: `utils.js::fetchWithTimeout` with `AbortController`, 30s default. All `client.js` + `official.js` fetches go through it.
+   - If still happening: check for any `console.log` calls in server code (only `console.error` is safe), and grep for raw `await fetch(` — every one must go through `fetchWithTimeout`.
+
+### If Official API tools return 401 / "token invalid" every time
+- **Likely cause**: `LARK_APP_ID` is wrong or stale. Observed in production: Claude Code auto-installed the plugin and guessed/copied a wrong APP_ID that doesn't match the team's real app (e.g. from an unrelated app, from someone else's machine, or hallucinated).
+- **Diagnosis**: `get_login_status` now reports `App credentials: INVALID — app_id=<x> rejected by Feishu (<code>: <msg>)`. MCP startup logs `[feishu-user-plugin] ERROR: LARK_APP_ID=<x> was REJECTED by Feishu` on stderr when this happens.
+- **Fix**: Re-run the canonical install prompt from `team-skills/plugins/feishu-user-plugin/README.md` which contains the correct APP_ID/SECRET, and restart Claude Code.
 
 ### If MCP tools are not available
 1. Check `~/.claude.json` — config must be in **top-level** `mcpServers`, not inside `projects[*]`
@@ -310,12 +326,29 @@ NPM_TOKEN is stored as a GitHub repo secret.
 
 ### Syncing to team-skills
 
-After publishing, sync plugin assets to team-skills:
+**IMPORTANT: team-skills 仓库禁止直接推送 main。所有变更必须走 PR。**
+
+team-skills 推送规范:
+1. **创建 feature branch**: `git checkout -b fix/feishu-xxx` 或 `sync/feishu-v1.x.x`
+2. **提交变更并推送 branch**: `git push -u origin <branch-name>`
+3. **创建 PR 并设置 auto-merge**: `gh pr create --title "..." --body "..."` 然后 `gh pr merge <number> --auto --merge`
+4. **CI 通过后自动合并**: validate workflow 检查三方版本一致性,通过即自动 merge,无需手动操作
+5. **如 CI 失败**: 修复后 push 到同一 branch,CI 会重跑,通过后自动合并
 
+三方版本一致性规则:
+- `plugins/feishu-user-plugin/.claude-plugin/plugin.json` 的 `version`
+- `plugins/feishu-user-plugin/skills/feishu-user-plugin/SKILL.md` frontmatter 的 `version`
+- `plugins/feishu-user-plugin/README.md` 更新日志里第一个 `### vX.Y.Z` 标题
+- 这三个版本号必须相同,否则 CI 会失败。每次 npm 发包后,team-skills 的版本号也要同步更新。
+
+同步内容（每次发版后执行）:
 ```bash
-# From the feishu-user-plugin repo:
-cp -r skills/ /path/to/team-skills/plugins/feishu-user-plugin/skills/
-cp .claude-plugin/plugin.json /path/to/team-skills/plugins/feishu-user-plugin/.claude-plugin/
+# 1. 同步 skills + plugin.json
+cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
+cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
+cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/
+# 2. 手动更新 team-skills 的 README.md（工具数、更新日志）和 SKILL.md（version + allowed-tools）
+# 3. 走 PR 流程推送
 # Do NOT copy .mcp.json — team-skills plugin should not have one
 ```
 
@@ -340,11 +373,12 @@ When making ANY code change (new tools, bug fixes, features), update ALL of thes
 
 **同步命令（每次发版后执行）：**
 ```bash
-# 1. 同步 skills
+# 1. 同步 skills + plugin.json
 cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
 cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
-# 2. 手动更新 team-skills README（工具数、功能列表、更新日志）
-# 3. 提交并推送两个仓库
+cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/
+# 2. 手动更新 team-skills README（工具数、功能列表、更新日志）+ SKILL.md（version + allowed-tools）
+# 3. 走 PR 流程推送 team-skills（禁止直接推 main）
 ```
 
 ### Keeping ROADMAP.md up to date
@@ -392,7 +426,8 @@ Steps:
 1. Copy CLAUDE.md to skill reference: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`
 2. Sync to team-skills repo: `cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/`
 3. Also sync plugin.json: `cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/`
-4. Commit and push both repos
+4. Update SKILL.md version + allowed-tools, README.md changelog + tool count
+5. **走 PR 流程**（创建 branch → push → PR → 等 CI 通过 → merge），禁止直接推 main
 
 ### Testing a tool
 - For Official API tools: can test directly via MCP tool call or standalone script using `readCredentials()` from `src/config.js`

package/src/client.js

@@ -1,6 +1,6 @@
 const path = require('path');
 const protobuf = require('protobufjs');
-const { generateRequestId, generateCid, parseCookie, formatCookie } = require('./utils');
+const { generateRequestId, generateCid, parseCookie, formatCookie, fetchWithTimeout } = require('./utils');
 
 const GATEWAY_URL = 'https://internal-api-lark-api.feishu.cn/im/gateway/';
 const CSRF_URL = 'https://internal-api-lark-api.feishu.cn/accounts/csrf';
@@ -47,7 +47,7 @@ class LarkUserClient {
   // --- Auth ---
 
   async _getCsrfToken() {
-    const res = await fetch(`${CSRF_URL}?_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${CSRF_URL}?_t=${Date.now()}`, {
       method: 'POST',
       headers: {
         ...this._jsonHeaders(),
@@ -68,7 +68,7 @@ class LarkUserClient {
   }
 
   async _getUserInfo() {
-    const res = await fetch(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
       headers: {
         ...this._jsonHeaders(),
         'x-csrf-token': this.csrfToken || '',
@@ -179,7 +179,7 @@ class LarkUserClient {
       cid: generateRequestId(),
       payload: reqBuf,
     });
-    const res = await fetch(GATEWAY_URL, {
+    const res = await fetchWithTimeout(GATEWAY_URL, {
       method: 'POST',
       headers: this._protoHeaders(cmd, cmdVersion),
       body: packetBuf,
@@ -200,14 +200,65 @@ class LarkUserClient {
 
   // --- Send Text Message ---
 
+  // Supports inline @mentions via the `ats` param:
+  //   ats: [{ userId: 'ou_xxx', name: 'Alice' }]
+  // The text should contain the mention markers (defaults to `@Alice` substrings,
+  // matched in order). If `text` already contains the @Name substrings, they're
+  // found in order and spliced into rich-text AT elements.
   async sendMessage(chatId, text, opts = {}) {
-    const elemId = generateCid();
-    const textPropBuf = this._encode('TextProperty', { content: text });
+    const { ats } = opts;
+    if (!Array.isArray(ats) || ats.length === 0) {
+      // Fast path: plain text, single TEXT element.
+      const elemId = generateCid();
+      const textPropBuf = this._encode('TextProperty', { content: text });
+      return this._sendMsg(MsgType.TEXT, chatId, {
+        richText: {
+          elementIds: [elemId],
+          innerText: text,
+          elements: { dictionary: { [elemId]: { tag: 1, property: textPropBuf } } },
+        },
+      }, opts);
+    }
+
+    // Build rich-text segments: split `text` by each at's display marker and
+    // weave AT elements in between text elements. Each `ats[i]` is consumed
+    // in order from the remaining text.
+    const elementIds = [];
+    const atIds = [];
+    const dictionary = {};
+    let remaining = text;
+    for (const at of ats) {
+      if (!at.userId) throw new Error('sendMessage: each at entry requires userId');
+      const display = at.marker || (at.name ? '@' + at.name : '@' + at.userId);
+      const idx = remaining.indexOf(display);
+      if (idx === -1) throw new Error(`sendMessage: marker "${display}" not found in text`);
+      const before = remaining.slice(0, idx);
+      if (before) {
+        const id = generateCid();
+        elementIds.push(id);
+        dictionary[id] = { tag: 1, property: this._encode('TextProperty', { content: before }) };
+      }
+      const atId = generateCid();
+      elementIds.push(atId);
+      atIds.push(atId);
+      dictionary[atId] = {
+        tag: 5,
+        property: this._encode('AtProperty', { userId: at.userId, content: display }),
+      };
+      remaining = remaining.slice(idx + display.length);
+    }
+    if (remaining) {
+      const id = generateCid();
+      elementIds.push(id);
+      dictionary[id] = { tag: 1, property: this._encode('TextProperty', { content: remaining }) };
+    }
+
     return this._sendMsg(MsgType.TEXT, chatId, {
       richText: {
-        elementIds: [elemId],
+        elementIds,
         innerText: text,
-        elements: { dictionary: { [elemId]: { tag: 1, property: textPropBuf } } },
+        elements: { dictionary },
+        atIds,
       },
     }, opts);
   }
@@ -240,26 +291,43 @@ class LarkUserClient {
 
   async sendPost(chatId, title, paragraphs, opts = {}) {
     const elementIds = [];
+    const atIds = [];
+    const anchorIds = [];
     const dictionary = {};
+    const paraTexts = [];
 
     for (let i = 0; i < paragraphs.length; i++) {
       const para = paragraphs[i];
+      const paraTextParts = [];
       for (const elem of para) {
         const elemId = generateCid();
         elementIds.push(elemId);
 
         if (elem.tag === 'text') {
-          const propBuf = this._encode('TextProperty', { content: elem.text });
+          const t = elem.text || '';
+          const propBuf = this._encode('TextProperty', { content: t });
           dictionary[elemId] = { tag: 1, property: propBuf };
+          paraTextParts.push(t);
         } else if (elem.tag === 'at') {
-          const propBuf = this._encode('TextProperty', { content: elem.userId });
+          if (!elem.userId) throw new Error('sendPost: {tag:"at"} requires userId');
+          const displayName = elem.name || elem.userName || elem.text || elem.userId;
+          const display = displayName.startsWith('@') ? displayName : `@${displayName}`;
+          const propBuf = this._encode('AtProperty', { userId: elem.userId, content: display });
           dictionary[elemId] = { tag: 5, property: propBuf };
+          atIds.push(elemId);
+          paraTextParts.push(display);
         } else if (elem.tag === 'a') {
-          // Link element: content stores the URL, display text goes through innerText
-          const propBuf = this._encode('TextProperty', { content: elem.href || elem.text || '' });
+          const href = elem.href || '';
+          const label = elem.text || href;
+          const propBuf = this._encode('AnchorProperty', { href, content: label, textContent: label });
           dictionary[elemId] = { tag: 6, property: propBuf };
+          anchorIds.push(elemId);
+          paraTextParts.push(label);
+        } else {
+          throw new Error(`sendPost: unknown element tag "${elem.tag}" (supported: text, at, a)`);
         }
       }
+      paraTexts.push(paraTextParts.join(''));
       // Insert newline element between paragraphs
       if (i < paragraphs.length - 1) {
         const nlId = generateCid();
@@ -269,10 +337,13 @@ class LarkUserClient {
       }
     }
 
-    const innerText = paragraphs.map(p => p.map(e => e.text || '').join('')).join('\n');
+    const innerText = paraTexts.join('\n');
+    const richText = { elementIds, innerText, elements: { dictionary } };
+    if (atIds.length > 0) richText.atIds = atIds;
+    if (anchorIds.length > 0) richText.anchorIds = anchorIds;
     return this._sendMsg(MsgType.POST, chatId, {
       title: title || '',
-      richText: { elementIds, innerText, elements: { dictionary } },
+      richText,
     }, opts);
   }