feishu-user-plugin 1.3.1 → 1.3.3

package/src/official.js

@@ -1,4 +1,5 @@
 const lark = require('@larksuiteoapi/node-sdk');
+const { fetchWithTimeout } = require('./utils');
 
 // Redirect all Lark SDK logs to stderr.
 // The SDK's defaultLogger.error uses console.log (stdout), which corrupts
@@ -39,6 +40,50 @@ class LarkOfficialClient {
     return !!this._uat;
   }
 
+  // Fetches (and caches) an app_access_token directly via the internal endpoint.
+  // Avoids relying on SDK-internal token-manager APIs that may change across versions.
+  async _getAppToken() {
+    const now = Math.floor(Date.now() / 1000);
+    if (this._appToken && this._appTokenExpires > now + 60) return this._appToken;
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ app_id: this.appId, app_secret: this.appSecret }),
+      timeoutMs: 10000,
+    });
+    const data = await res.json();
+    if (data.code !== 0 || !data.app_access_token) {
+      throw new Error(`app_access_token failed: ${data.code}: ${data.msg || 'unknown'}`);
+    }
+    this._appToken = data.app_access_token;
+    this._appTokenExpires = now + (typeof data.expire === 'number' ? data.expire : 7200);
+    return this._appToken;
+  }
+
+  // Probe APP_ID/SECRET validity by requesting a tenant access token.
+  // Catches the common "user's Claude filled in a wrong/stale APP_ID" failure mode
+  // (observed in production: 周宇's machine ran with an APP_ID nobody recognized,
+  // causing all Official API calls to 401 with cryptic messages that looked like
+  // MCP "掉线" to the user). Returns { valid, appId, appName?, error? }.
+  async verifyApp() {
+    try {
+      const token = await this._getAppToken();
+      // Try to fetch app display name (best-effort; requires application scope)
+      let appName = null;
+      try {
+        const infoRes = await fetchWithTimeout(`https://open.feishu.cn/open-apis/application/v6/applications/${this.appId}?lang=zh_cn`, {
+          headers: { 'Authorization': `Bearer ${token}` },
+          timeoutMs: 10000,
+        });
+        const info = await infoRes.json();
+        if (info.code === 0) appName = info.data?.app?.app_name || null;
+      } catch (_) { /* name is best-effort; valid creds still matter most */ }
+      return { valid: true, appId: this.appId, appName };
+    } catch (e) {
+      return { valid: false, appId: this.appId, error: e.message };
+    }
+  }
+
   async _getValidUAT() {
     if (!this._uat) throw new Error('No user_access_token. Run: npx feishu-user-plugin oauth');
 
@@ -53,7 +98,7 @@ class LarkOfficialClient {
   async _refreshUAT() {
     if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
 
-    const res = await fetch('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
+    const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({
@@ -101,11 +146,49 @@ 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 fetchWithTimeout(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, _viaUser}. _viaUser is true iff the UAT call succeeded;
+  // callers can surface this to distinguish "created by user" vs "created by app" for resources
+  // whose ownership matters (docs, bitables, folders).
+  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) {
+          data._viaUser = true;
+          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`);
+      }
+    }
+    const appData = await this._safeSDKCall(sdkFn, label);
+    if (appData && typeof appData === 'object') appData._viaUser = false;
+    return appData;
+  }
+
   async listChatsAsUser({ pageSize = 20, pageToken } = {}) {
     const params = new URLSearchParams({ page_size: String(pageSize) });
     if (pageToken) params.set('page_token', pageToken);
     const data = await this._withUAT(async (uat) => {
-      const res = await fetch(`https://open.feishu.cn/open-apis/im/v1/chats?${params}`, {
+      const res = await fetchWithTimeout(`https://open.feishu.cn/open-apis/im/v1/chats?${params}`, {
         headers: { 'Authorization': `Bearer ${uat}` },
       });
       return res.json();
@@ -127,7 +210,7 @@ class LarkOfficialClient {
     if (endTime) params.set('end_time', endTime);
     if (pageToken) params.set('page_token', pageToken);
     const data = await this._withUAT(async (uat) => {
-      const res = await fetch(`https://open.feishu.cn/open-apis/im/v1/messages?${params}`, {
+      const res = await fetchWithTimeout(`https://open.feishu.cn/open-apis/im/v1/messages?${params}`, {
         headers: { 'Authorization': `Bearer ${uat}` },
       });
       return res.json();
@@ -167,6 +250,57 @@ class LarkOfficialClient {
     return this._formatMessage(res.data);
   }
 
+  // Download a resource (image/file) attached to a message.
+  // Tries UAT first (works for any chat the user is in), falls back to app token
+  // (requires the bot to be in the same chat — Feishu restriction).
+  // resourceType: 'image' | 'file'. Returns { base64, mimeType, viaUser }.
+  async downloadMessageResource(messageId, fileKey, resourceType = 'image') {
+    const path = `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/resources/${encodeURIComponent(fileKey)}?type=${encodeURIComponent(resourceType)}`;
+    const url = 'https://open.feishu.cn' + path;
+
+    // Attempt 1: user identity
+    if (this.hasUAT) {
+      try {
+        const uat = await this._getValidUAT();
+        const res = await fetchWithTimeout(url, {
+          headers: { 'Authorization': `Bearer ${uat}` },
+          timeoutMs: 60000,
+        });
+        if (res.ok && !res.headers.get('content-type')?.includes('application/json')) {
+          const buf = Buffer.from(await res.arrayBuffer());
+          return {
+            base64: buf.toString('base64'),
+            mimeType: res.headers.get('content-type') || 'application/octet-stream',
+            bytes: buf.length,
+            viaUser: true,
+          };
+        }
+        const errJson = await res.json().catch(() => null);
+        console.error(`[feishu-user-plugin] downloadMessageResource as user failed: ${errJson?.code}: ${errJson?.msg || res.statusText}, retrying as app`);
+      } catch (e) {
+        console.error(`[feishu-user-plugin] downloadMessageResource as user threw (${e.message}), retrying as app`);
+      }
+    }
+
+    // Attempt 2: app identity
+    const token = await this._getAppToken();
+    const res = await fetchWithTimeout(url, {
+      headers: { 'Authorization': `Bearer ${token}` },
+      timeoutMs: 60000,
+    });
+    if (!res.ok || res.headers.get('content-type')?.includes('application/json')) {
+      const errJson = await res.json().catch(() => null);
+      throw new Error(`downloadMessageResource failed: ${errJson?.code}: ${errJson?.msg || res.statusText}. Note: app identity requires the bot to be in the same chat.`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    return {
+      base64: buf.toString('base64'),
+      mimeType: res.headers.get('content-type') || 'application/octet-stream',
+      bytes: buf.length,
+      viaUser: false,
+    };
+  }
+
   async replyMessage(messageId, text, msgType = 'text') {
     const content = msgType === 'text' ? JSON.stringify({ text }) : text;
     const res = await this._safeSDKCall(
@@ -371,61 +505,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'
-    );
-    return { documentId: res.data.document?.document_id };
+    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, viaUser: !!res._viaUser };
   }
 
   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 +595,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'
-    );
-    return { appToken: res.data.app?.app_token, name: res.data.app?.name, url: res.data.app?.url };
+    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, viaUser: !!res._viaUser };
   }
 
   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 +618,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 +673,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,11 +880,15 @@ class LarkOfficialClient {
   }
 
   async createFolder(name, parentToken) {
-    const res = await this._safeSDKCall(
-      () => this.client.drive.file.createFolder({ data: { name, folder_token: parentToken || '' } }),
-      'createFolder'
-    );
-    return { token: res.data.token };
+    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, viaUser: !!res._viaUser };
   }
 
   // --- Drive: File Operations ---
@@ -731,53 +950,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 +1035,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 +1045,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) {