feishu-user-plugin 1.3.1 → 1.3.2

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.2",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs/tables/wiki. 66 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/package.json

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

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/references/CLAUDE.md

@@ -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.
@@ -59,7 +60,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)
 
@@ -310,12 +313,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 +360,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 +413,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

@@ -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);
   }
 

package/src/index.js

@@ -144,12 +144,17 @@ const TOOLS = [
   // ========== User Identity — Send Messages ==========
   {
     name: 'send_as_user',
-    description: '[User Identity] Send a text message as the logged-in Feishu user. Supports reply threading.',
+    description: '[User Identity] Send a text message as the logged-in Feishu user. Supports reply threading and real @-mentions (triggers push notifications).',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat ID (numeric)' },
-        text: { type: 'string', description: 'Message text' },
+        text: { type: 'string', description: 'Message text. If `ats` is provided, include the display marker for each @ in this text (default marker is `@<name>`).' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions. Each entry: {userId: "ou_xxx", name: "DisplayName"}. The text must contain each @<name> marker in order — it gets spliced into a real AT element so the mentioned user receives a notification.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
         root_id: { type: 'string', description: 'Thread root message ID (for reply, optional)' },
         parent_id: { type: 'string', description: 'Parent message ID (for nested reply, optional)' },
       },
@@ -164,6 +169,11 @@ const TOOLS = [
       properties: {
         user_name: { type: 'string', description: 'Recipient name (Chinese or English)' },
         text: { type: 'string', description: 'Message text' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions. Same format as send_as_user.ats: [{userId, name}]. Text must contain the `@<name>` marker for each entry.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
       },
       required: ['user_name', 'text'],
     },
@@ -176,6 +186,11 @@ const TOOLS = [
       properties: {
         group_name: { type: 'string', description: 'Group chat name' },
         text: { type: 'string', description: 'Message text' },
+        ats: {
+          type: 'array',
+          description: 'Optional @-mentions that trigger real notifications. Each entry: {userId, name}. Text must contain `@<name>` marker for each entry.',
+          items: { type: 'object', properties: { userId: { type: 'string' }, name: { type: 'string' }, marker: { type: 'string' } } },
+        },
       },
       required: ['group_name', 'text'],
     },
@@ -222,7 +237,7 @@ const TOOLS = [
   },
   {
     name: 'send_post_as_user',
-    description: '[User Identity] Send a rich text (POST) message with title and formatted paragraphs.',
+    description: '[User Identity] Send a rich text (POST) message with title and formatted paragraphs. Supports real @-mentions that trigger notifications.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -230,7 +245,7 @@ const TOOLS = [
         title: { type: 'string', description: 'Post title (optional)' },
         paragraphs: {
           type: 'array',
-          description: 'Array of paragraphs. Each paragraph is an array of elements: {tag:"text",text:"..."} or {tag:"a",href:"...",text:"..."} or {tag:"at",userId:"..."}',
+          description: 'Array of paragraphs. Each paragraph is an array of elements:\n• {tag:"text",text:"..."} — plain text\n• {tag:"a",href:"https://...",text:"display"} — hyperlink\n• {tag:"at",userId:"ou_xxx",name:"Display Name"} — real @-mention (triggers notification)',
           items: { type: 'array', items: { type: 'object' } },
         },
         root_id: { type: 'string', description: 'Thread root message ID (optional)' },
@@ -674,13 +689,13 @@ const TOOLS = [
   // ========== IM — Bot Send / Edit / Delete ==========
   {
     name: 'send_message_as_bot',
-    description: '[Official API] Send a message as the bot to any chat. Supports text, post, interactive, etc.',
+    description: '[Official API] Send a message as the bot to any chat. Supports text, post, interactive, etc. This is the reliable path for @-mentions: include `<at user_id="ou_xxx">Name</at>` inline in text content and Feishu resolves it to a real @-notification.',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
         msg_type: { type: 'string', description: 'Message type: text, post, image, interactive, etc.', enum: ['text', 'post', 'image', 'interactive', 'share_chat', 'share_user', 'audio', 'media', 'file', 'sticker'] },
-        content: { description: 'Message content (string or object, auto-serialized). For text: {"text":"hello"}' },
+        content: { description: 'Message content (string or object, auto-serialized). Plain text: {"text":"hello"}. Text with @-mention: {"text":"<at user_id=\\"ou_xxx\\">Alice</at> hi"} — the inline tag becomes a real @-notification.' },
       },
       required: ['chat_id', 'msg_type', 'content'],
     },
@@ -1008,7 +1023,7 @@ async function handleTool(name, args) {
 
     case 'send_as_user': {
       const c = await getUserClient();
-      const r = await c.sendMessage(args.chat_id, args.text, { rootId: args.root_id, parentId: args.parent_id });
+      const r = await c.sendMessage(args.chat_id, args.text, { rootId: args.root_id, parentId: args.parent_id, ats: args.ats });
       return sendResult(r, `Text sent as user to ${args.chat_id}`);
     }
     case 'send_to_user': {
@@ -1023,7 +1038,7 @@ async function handleTool(name, args) {
       const user = users[0];
       const chatId = await c.createChat(user.id);
       if (!chatId) return text(`Failed to create chat with ${user.title}`);
-      const r = await c.sendMessage(chatId, args.text);
+      const r = await c.sendMessage(chatId, args.text, { ats: args.ats });
       return sendResult(r, `Text sent to ${user.title} (chat: ${chatId})`);
     }
     case 'send_to_group': {
@@ -1036,7 +1051,7 @@ async function handleTool(name, args) {
         return text(`Multiple groups match "${args.group_name}":\n${candidates}\nUse search_contacts to find the exact group, then send_as_user with the ID.`);
       }
       const group = groups[0];
-      const r = await c.sendMessage(group.id, args.text);
+      const r = await c.sendMessage(group.id, args.text, { ats: args.ats });
       return sendResult(r, `Text sent to group "${group.title}" (${group.id})`);
     }
 
@@ -1222,31 +1237,17 @@ async function handleTool(name, args) {
       return json(await getOfficialClient().getDocBlocks(args.document_id));
     case 'create_doc': {
       const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          const result = await official.createDocAsUser(args.title, args.folder_id);
-          return text(`Document created (as user): ${result.documentId}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createDoc failed, falling back to app: ${e.message}`);
-        }
-      }
-      return text(`Document created: ${(await official.createDoc(args.title, args.folder_id)).documentId}`);
+      const ownership = official.hasUAT ? ' (as user)' : '';
+      return text(`Document created${ownership}: ${(await official.createDoc(args.title, args.folder_id)).documentId}`);
     }
 
     // --- Official API: Bitable ---
 
     case 'create_bitable': {
       const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          const r = await official.createBitableAsUser(args.name, args.folder_id);
-          return text(`Bitable created (as user): ${r.appToken}\nURL: ${r.url || ''}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createBitable failed, falling back to app: ${e.message}`);
-        }
-      }
+      const ownership = official.hasUAT ? ' (as user)' : '';
       const r = await official.createBitable(args.name, args.folder_id);
-      return text(`Bitable created: ${r.appToken}\nURL: ${r.url || ''}`);
+      return text(`Bitable created${ownership}: ${r.appToken}\nURL: ${r.url || ''}`);
     }
     case 'list_bitable_tables':
       return json(await getOfficialClient().listBitableTables(args.app_token));
@@ -1298,14 +1299,8 @@ async function handleTool(name, args) {
       return json(await getOfficialClient().listFiles(args.folder_token));
     case 'create_folder': {
       const official = getOfficialClient();
-      if (official.hasUAT) {
-        try {
-          return text(`Folder created (as user): ${(await official.createFolderAsUser(args.name, args.parent_token)).token}`);
-        } catch (e) {
-          console.error(`[feishu-user-plugin] UAT createFolder failed, falling back to app: ${e.message}`);
-        }
-      }
-      return text(`Folder created: ${(await official.createFolder(args.name, args.parent_token)).token}`);
+      const ownership = official.hasUAT ? ' (as user)' : '';
+      return text(`Folder created${ownership}: ${(await official.createFolder(args.name, args.parent_token)).token}`);
     }
 
     // --- Official API: Contact ---

package/src/official.js

@@ -101,6 +101,37 @@ class LarkOfficialClient {
     return data;
   }
 
+  // Generic UAT REST helper. Returns parsed JSON ({code, msg, data}).
+  async _uatREST(method, path, { body, query } = {}) {
+    const qs = query ? '?' + new URLSearchParams(query).toString() : '';
+    const url = 'https://open.feishu.cn' + path + qs;
+    return this._withUAT(async (uat) => {
+      const headers = { 'Authorization': `Bearer ${uat}` };
+      const init = { method, headers };
+      if (body !== undefined) {
+        headers['content-type'] = 'application/json';
+        init.body = JSON.stringify(body);
+      }
+      const res = await fetch(url, init);
+      return res.json();
+    });
+  }
+
+  // Try UAT first (for resources likely owned by the user), fall back to app SDK on failure.
+  // Returns SDK-shaped {code, msg, data}. Both paths yield the same shape.
+  async _asUserOrApp({ uatPath, method = 'GET', body, query, sdkFn, label }) {
+    if (this.hasUAT) {
+      try {
+        const data = await this._uatREST(method, uatPath, { body, query });
+        if (data.code === 0) return data;
+        console.error(`[feishu-user-plugin] ${label} as user failed (${data.code}: ${data.msg}), retrying as app`);
+      } catch (err) {
+        console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
+      }
+    }
+    return this._safeSDKCall(sdkFn, label);
+  }
+
   async listChatsAsUser({ pageSize = 20, pageToken } = {}) {
     const params = new URLSearchParams({ page_size: String(pageSize) });
     if (pageToken) params.set('page_token', pageToken);
@@ -371,61 +402,77 @@ class LarkOfficialClient {
   }
 
   async readDoc(documentId) {
-    const res = await this._safeSDKCall(
-      () => this.client.docx.document.rawContent({ path: { document_id: documentId }, params: { lang: 0 } }),
-      'readDoc'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/raw_content`,
+      query: { lang: '0' },
+      sdkFn: () => this.client.docx.document.rawContent({ path: { document_id: documentId }, params: { lang: 0 } }),
+      label: 'readDoc',
+    });
     return { content: res.data.content };
   }
 
   async createDoc(title, folderId) {
-    const res = await this._safeSDKCall(
-      () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
-      'createDoc'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents`,
+      method: 'POST',
+      body: { title, folder_token: folderId || '' },
+      sdkFn: () => this.client.docx.document.create({ data: { title, folder_token: folderId || '' } }),
+      label: 'createDoc',
+    });
     return { documentId: res.data.document?.document_id };
   }
 
   async getDocBlocks(documentId) {
-    const res = await this._safeSDKCall(
-      () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } }),
-      'getDocBlocks'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks`,
+      query: { page_size: '500' },
+      sdkFn: () => this.client.docx.documentBlock.list({ path: { document_id: documentId }, params: { page_size: 500 } }),
+      label: 'getDocBlocks',
+    });
     return { items: res.data.items || [] };
   }
 
   async createDocBlock(documentId, parentBlockId, children, index) {
     const data = { children };
     if (index !== undefined) data.index = index;
-    const res = await this._safeSDKCall(
-      () => this.client.docx.documentBlockChildren.create({
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.docx.documentBlockChildren.create({
         path: { document_id: documentId, block_id: parentBlockId },
         data,
       }),
-      'createDocBlock'
-    );
+      label: 'createDocBlock',
+    });
     return { blocks: res.data.children || [] };
   }
 
   async updateDocBlock(documentId, blockId, updateBody) {
-    const res = await this._safeSDKCall(
-      () => this.client.docx.documentBlock.patch({
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${blockId}`,
+      method: 'PATCH',
+      body: updateBody,
+      sdkFn: () => this.client.docx.documentBlock.patch({
         path: { document_id: documentId, block_id: blockId },
         data: updateBody,
       }),
-      'updateDocBlock'
-    );
+      label: 'updateDocBlock',
+    });
     return { block: res.data.block };
   }
 
   async deleteDocBlocks(documentId, parentBlockId, startIndex, endIndex) {
-    const res = await this._safeSDKCall(
-      () => this.client.docx.documentBlockChildren.batchDelete({
+    await this._asUserOrApp({
+      uatPath: `/open-apis/docx/v1/documents/${documentId}/blocks/${parentBlockId}/children/batch_delete`,
+      method: 'DELETE',
+      body: { start_index: startIndex, end_index: endIndex },
+      sdkFn: () => this.client.docx.documentBlockChildren.batchDelete({
         path: { document_id: documentId, block_id: parentBlockId },
         data: { start_index: startIndex, end_index: endIndex },
       }),
-      'deleteDocBlocks'
-    );
+      label: 'deleteDocBlocks',
+    });
     return { deleted: true };
   }
 
@@ -445,15 +492,22 @@ class LarkOfficialClient {
     const data = {};
     if (name) data.name = name;
     if (folderId) data.folder_token = folderId;
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.app.create({ data }),
-      'createBitable'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.app.create({ data }),
+      label: 'createBitable',
+    });
     return { appToken: res.data.app?.app_token, name: res.data.app?.name, url: res.data.app?.url };
   }
 
   async listBitableTables(appToken) {
-    const res = await this._safeSDKCall(() => this.client.bitable.appTable.list({ path: { app_token: appToken } }), 'listTables');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables`,
+      sdkFn: () => this.client.bitable.appTable.list({ path: { app_token: appToken } }),
+      label: 'listTables',
+    });
     return { items: res.data.items || [] };
   }
 
@@ -461,39 +515,54 @@ class LarkOfficialClient {
     const data = { table: { name } };
     if (fields && fields.length > 0) data.table.default_view_name = name;
     if (fields && fields.length > 0) data.table.fields = fields;
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTable.create({ path: { app_token: appToken }, data }),
-      'createTable'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.appTable.create({ path: { app_token: appToken }, data }),
+      label: 'createTable',
+    });
     return { tableId: res.data.table_id };
   }
 
   async listBitableFields(appToken, tableId) {
-    const res = await this._safeSDKCall(() => this.client.bitable.appTableField.list({ path: { app_token: appToken, table_id: tableId } }), 'listFields');
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields`,
+      sdkFn: () => this.client.bitable.appTableField.list({ path: { app_token: appToken, table_id: tableId } }),
+      label: 'listFields',
+    });
     return { items: res.data.items || [] };
   }
 
   async createBitableField(appToken, tableId, fieldConfig) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableField.create({ path: { app_token: appToken, table_id: tableId }, data: fieldConfig }),
-      'createField'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields`,
+      method: 'POST',
+      body: fieldConfig,
+      sdkFn: () => this.client.bitable.appTableField.create({ path: { app_token: appToken, table_id: tableId }, data: fieldConfig }),
+      label: 'createField',
+    });
     return { field: res.data.field };
   }
 
   async updateBitableField(appToken, tableId, fieldId, fieldConfig) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableField.update({ path: { app_token: appToken, table_id: tableId, field_id: fieldId }, data: fieldConfig }),
-      'updateField'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields/${fieldId}`,
+      method: 'PUT',
+      body: fieldConfig,
+      sdkFn: () => this.client.bitable.appTableField.update({ path: { app_token: appToken, table_id: tableId, field_id: fieldId }, data: fieldConfig }),
+      label: 'updateField',
+    });
     return { field: res.data.field };
   }
 
   async deleteBitableField(appToken, tableId, fieldId) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableField.delete({ path: { app_token: appToken, table_id: tableId, field_id: fieldId } }),
-      'deleteField'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/fields/${fieldId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableField.delete({ path: { app_token: appToken, table_id: tableId, field_id: fieldId } }),
+      label: 'deleteField',
+    });
     return { fieldId: res.data.field_id, deleted: res.data.deleted };
   }
 
@@ -501,126 +570,169 @@ class LarkOfficialClient {
     const data = {};
     if (filter) data.filter = filter;
     if (sort) data.sort = sort;
-    if (pageSize) data.page_size = pageSize;
-    if (pageToken) data.page_token = pageToken;
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.search({ path: { app_token: appToken, table_id: tableId }, data }),
-      'searchRecords'
-    );
+    const query = {};
+    if (pageSize) query.page_size = String(pageSize);
+    if (pageToken) query.page_token = pageToken;
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/search`,
+      method: 'POST',
+      body: data,
+      query,
+      sdkFn: () => this.client.bitable.appTableRecord.search({
+        path: { app_token: appToken, table_id: tableId },
+        params: { page_size: pageSize, ...(pageToken ? { page_token: pageToken } : {}) },
+        data,
+      }),
+      label: 'searchRecords',
+    });
     return { items: res.data.items || [], total: res.data.total, hasMore: res.data.has_more };
   }
 
   async createBitableRecord(appToken, tableId, fields) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
-      'createRecord'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records`,
+      method: 'POST',
+      body: { fields },
+      sdkFn: () => this.client.bitable.appTableRecord.create({ path: { app_token: appToken, table_id: tableId }, data: { fields } }),
+      label: 'createRecord',
+    });
     return { recordId: res.data.record?.record_id };
   }
 
   async updateBitableRecord(appToken, tableId, recordId, fields) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.update({ path: { app_token: appToken, table_id: tableId, record_id: recordId }, data: { fields } }),
-      'updateRecord'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      method: 'PUT',
+      body: { fields },
+      sdkFn: () => this.client.bitable.appTableRecord.update({ path: { app_token: appToken, table_id: tableId, record_id: recordId }, data: { fields } }),
+      label: 'updateRecord',
+    });
     return { recordId: res.data.record?.record_id };
   }
 
   async deleteBitableRecord(appToken, tableId, recordId) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.delete({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
-      'deleteRecord'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableRecord.delete({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
+      label: 'deleteRecord',
+    });
     return { deleted: res.data.deleted };
   }
 
   async batchCreateBitableRecords(appToken, tableId, records) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.batchCreate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
-      'batchCreateRecords'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_create`,
+      method: 'POST',
+      body: { records },
+      sdkFn: () => this.client.bitable.appTableRecord.batchCreate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
+      label: 'batchCreateRecords',
+    });
     return { records: res.data.records || [] };
   }
 
   async batchUpdateBitableRecords(appToken, tableId, records) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.batchUpdate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
-      'batchUpdateRecords'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_update`,
+      method: 'POST',
+      body: { records },
+      sdkFn: () => this.client.bitable.appTableRecord.batchUpdate({ path: { app_token: appToken, table_id: tableId }, data: { records } }),
+      label: 'batchUpdateRecords',
+    });
     return { records: res.data.records || [] };
   }
 
   async batchDeleteBitableRecords(appToken, tableId, recordIds) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.batchDelete({ path: { app_token: appToken, table_id: tableId }, data: { records: recordIds } }),
-      'batchDeleteRecords'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/batch_delete`,
+      method: 'POST',
+      body: { records: recordIds },
+      sdkFn: () => this.client.bitable.appTableRecord.batchDelete({ path: { app_token: appToken, table_id: tableId }, data: { records: recordIds } }),
+      label: 'batchDeleteRecords',
+    });
     return { records: res.data.records || [] };
   }
 
   async listBitableViews(appToken, tableId) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableView.list({ path: { app_token: appToken, table_id: tableId }, params: { page_size: 50 } }),
-      'listViews'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views`,
+      query: { page_size: '50' },
+      sdkFn: () => this.client.bitable.appTableView.list({ path: { app_token: appToken, table_id: tableId }, params: { page_size: 50 } }),
+      label: 'listViews',
+    });
     return { items: res.data.items || [] };
   }
 
   async getBitableRecord(appToken, tableId, recordId) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableRecord.get({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
-      'getRecord'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/records/${recordId}`,
+      sdkFn: () => this.client.bitable.appTableRecord.get({ path: { app_token: appToken, table_id: tableId, record_id: recordId } }),
+      label: 'getRecord',
+    });
     return { record: res.data.record };
   }
 
   async deleteBitableTable(appToken, tableId) {
-    await this._safeSDKCall(
-      () => this.client.bitable.appTable.delete({ path: { app_token: appToken, table_id: tableId } }),
-      'deleteTable'
-    );
+    await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTable.delete({ path: { app_token: appToken, table_id: tableId } }),
+      label: 'deleteTable',
+    });
     return { deleted: true };
   }
 
   async getBitableMeta(appToken) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.app.get({ path: { app_token: appToken } }),
-      'getBitableMeta'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}`,
+      sdkFn: () => this.client.bitable.app.get({ path: { app_token: appToken } }),
+      label: 'getBitableMeta',
+    });
     return { app: res.data.app };
   }
 
   async updateBitableTable(appToken, tableId, name) {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTable.patch({ path: { app_token: appToken, table_id: tableId }, data: { name } }),
-      'updateTable'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}`,
+      method: 'PATCH',
+      body: { name },
+      sdkFn: () => this.client.bitable.appTable.patch({ path: { app_token: appToken, table_id: tableId }, data: { name } }),
+      label: 'updateTable',
+    });
     return { name: res.data.name };
   }
 
   async createBitableView(appToken, tableId, viewName, viewType = 'grid') {
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.appTableView.create({ path: { app_token: appToken, table_id: tableId }, data: { view_name: viewName, view_type: viewType } }),
-      'createView'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views`,
+      method: 'POST',
+      body: { view_name: viewName, view_type: viewType },
+      sdkFn: () => this.client.bitable.appTableView.create({ path: { app_token: appToken, table_id: tableId }, data: { view_name: viewName, view_type: viewType } }),
+      label: 'createView',
+    });
     return { view: res.data.view };
   }
 
   async deleteBitableView(appToken, tableId, viewId) {
-    await this._safeSDKCall(
-      () => this.client.bitable.appTableView.delete({ path: { app_token: appToken, table_id: tableId, view_id: viewId } }),
-      'deleteView'
-    );
+    await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/tables/${tableId}/views/${viewId}`,
+      method: 'DELETE',
+      sdkFn: () => this.client.bitable.appTableView.delete({ path: { app_token: appToken, table_id: tableId, view_id: viewId } }),
+      label: 'deleteView',
+    });
     return { deleted: true };
   }
 
   async copyBitable(appToken, name, folderId) {
     const data = { name };
     if (folderId) data.folder_token = folderId;
-    const res = await this._safeSDKCall(
-      () => this.client.bitable.app.copy({ path: { app_token: appToken }, data }),
-      'copyBitable'
-    );
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/bitable/v1/apps/${appToken}/copy`,
+      method: 'POST',
+      body: data,
+      sdkFn: () => this.client.bitable.app.copy({ path: { app_token: appToken }, data }),
+      label: 'copyBitable',
+    });
     return { app: res.data.app };
   }
 
@@ -665,10 +777,14 @@ class LarkOfficialClient {
   }
 
   async createFolder(name, parentToken) {
-    const res = await this._safeSDKCall(
-      () => this.client.drive.file.createFolder({ data: { name, folder_token: parentToken || '' } }),
-      'createFolder'
-    );
+    const body = { name, folder_token: parentToken || '' };
+    const res = await this._asUserOrApp({
+      uatPath: `/open-apis/drive/v1/files/create_folder`,
+      method: 'POST',
+      body,
+      sdkFn: () => this.client.drive.file.createFolder({ data: body }),
+      label: 'createFolder',
+    });
     return { token: res.data.token };
   }
 
@@ -731,53 +847,6 @@ class LarkOfficialClient {
     return allChats;
   }
 
-  // --- UAT-based creation (resources owned by user, not app) ---
-
-  async createDocAsUser(title, folderId) {
-    const data = { title };
-    if (folderId) data.folder_token = folderId;
-    const result = await this._withUAT(async (uat) => {
-      const res = await fetch('https://open.feishu.cn/open-apis/docx/v1/documents', {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${uat}`, 'content-type': 'application/json' },
-        body: JSON.stringify(data),
-      });
-      return res.json();
-    });
-    if (result.code !== 0) throw new Error(`createDocAsUser failed (${result.code}): ${result.msg}`);
-    return { documentId: result.data.document?.document_id };
-  }
-
-  async createBitableAsUser(name, folderId) {
-    const data = {};
-    if (name) data.name = name;
-    if (folderId) data.folder_token = folderId;
-    const result = await this._withUAT(async (uat) => {
-      const res = await fetch('https://open.feishu.cn/open-apis/bitable/v1/apps', {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${uat}`, 'content-type': 'application/json' },
-        body: JSON.stringify(data),
-      });
-      return res.json();
-    });
-    if (result.code !== 0) throw new Error(`createBitableAsUser failed (${result.code}): ${result.msg}`);
-    return { appToken: result.data.app?.app_token, name: result.data.app?.name, url: result.data.app?.url };
-  }
-
-  async createFolderAsUser(name, parentToken) {
-    const data = { name, folder_token: parentToken || '' };
-    const result = await this._withUAT(async (uat) => {
-      const res = await fetch('https://open.feishu.cn/open-apis/drive/v1/files/create_folder', {
-        method: 'POST',
-        headers: { 'Authorization': `Bearer ${uat}`, 'content-type': 'application/json' },
-        body: JSON.stringify(data),
-      });
-      return res.json();
-    });
-    if (result.code !== 0) throw new Error(`createFolderAsUser failed (${result.code}): ${result.msg}`);
-    return { token: result.data.token };
-  }
-
   // --- Safe SDK Call (extracts real Feishu error from AxiosError) ---
 
   async _safeSDKCall(fn, label = 'API') {
@@ -863,7 +932,7 @@ class LarkOfficialClient {
     if (!m) return null;
     let body = m.body?.content || '';
     try { body = JSON.parse(body); } catch {}
-    return {
+    const out = {
       messageId: m.message_id,
       chatId: m.chat_id,
       senderId: m.sender?.id,
@@ -873,6 +942,8 @@ class LarkOfficialClient {
       createTime: this._normalizeTimestamp(m.create_time),
       updateTime: this._normalizeTimestamp(m.update_time),
     };
+    if (Array.isArray(m.mentions) && m.mentions.length > 0) out.mentions = m.mentions;
+    return out;
   }
 
   _normalizeTimestamp(ts) {