feishu-user-plugin 1.3.11 → 1.3.12

package/src/test-search-messages.js

@@ -0,0 +1,101 @@
+// src/test-search-messages.js — fixture test for v1.3.12 search_messages.
+//
+// search_messages wraps POST /open-apis/search/v2/message (UAT-only).
+// Live calls require the `search:message` scope; this test mocks
+// _uatREST directly to verify request shape + response handling +
+// error classification without a real Feishu round-trip.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { LarkOfficialClient } = require('./clients/official');
+
+async function run() {
+  const c = new LarkOfficialClient('cli_test', 'fake_secret');
+  // Make hasUAT truthy so the early-throw doesn't fire.
+  c._uat = 'fake_uat';
+  c._uatRefresh = 'fake_refresh';
+  c._uatExpires = Math.floor(Date.now() / 1000) + 3600;
+
+  // --- 1. happy path: returns items + pageToken + hasMore ---
+  c._uatREST = async (method, path, opts) => {
+    assert.equal(method, 'POST');
+    assert.equal(path, '/open-apis/search/v2/message');
+    assert.equal(opts.body.query, 'hello');
+    return {
+      code: 0,
+      data: {
+        items: [
+          { message_id: 'om_a', chat_id: 'oc_x' },
+          { message_id: 'om_b', chat_id: 'oc_y' },
+        ],
+        page_token: 'next_xyz',
+        has_more: true,
+      },
+    };
+  };
+  let result = await c.searchMessages({ query: 'hello', pageSize: 10 });
+  assert.equal(result.items.length, 2);
+  assert.equal(result.pageToken, 'next_xyz');
+  assert.equal(result.hasMore, true);
+
+  // --- 2. filter knobs propagate into body ---
+  let captured;
+  c._uatREST = async (method, path, opts) => {
+    captured = opts.body;
+    return { code: 0, data: { items: [], page_token: null, has_more: false } };
+  };
+  await c.searchMessages({
+    query: 'q',
+    chatIds: ['oc_a', 'oc_b'],
+    fromIds: ['ou_x'],
+    atUserIds: ['ou_at'],
+    messageTypes: ['text', 'post'],
+    fromTypes: ['user'],
+  });
+  assert.deepEqual(captured.chat_ids, ['oc_a', 'oc_b']);
+  assert.deepEqual(captured.from_ids, ['ou_x']);
+  assert.deepEqual(captured.at_chatter_ids, ['ou_at']);
+  assert.deepEqual(captured.message_type_list, ['text', 'post']);
+  assert.deepEqual(captured.from_types, ['user']);
+
+  // --- 3. 99991679 → throws with scope guidance ---
+  c._uatREST = async () => ({ code: 99991679, msg: 'Unauthorized. required: search:message' });
+  let threw;
+  try { await c.searchMessages({ query: 'x' }); }
+  catch (e) { threw = e; }
+  assert.ok(threw);
+  assert.ok(threw.message.includes('search:message'));
+  assert.ok(threw.message.includes('npx feishu-user-plugin oauth'));
+
+  // --- 4. other non-zero code → wrapped throw ---
+  c._uatREST = async () => ({ code: 42101, msg: 'rate limited' });
+  threw = undefined;
+  try { await c.searchMessages({ query: 'x' }); }
+  catch (e) { threw = e; }
+  assert.ok(threw);
+  assert.ok(threw.message.includes('42101'));
+
+  // --- 5. missing query → input error before any API call ---
+  c._uatREST = async () => { throw new Error('should not be called'); };
+  threw = undefined;
+  try { await c.searchMessages({}); }
+  catch (e) { threw = e; }
+  assert.ok(threw);
+  assert.ok(threw.message.includes('query'));
+
+  // --- 6. no UAT → throws with oauth pointer ---
+  const c2 = new LarkOfficialClient('cli_test', 'fake_secret');
+  // hasUAT will be false (no _uat).
+  threw = undefined;
+  try { await c2.searchMessages({ query: 'x' }); }
+  catch (e) { threw = e; }
+  assert.ok(threw);
+  assert.ok(threw.message.includes('UAT'));
+  assert.ok(threw.message.includes('npx feishu-user-plugin oauth'));
+
+  console.log('search-messages.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-send-shape.js

@@ -0,0 +1,115 @@
+// src/test-send-shape.js — verify all 8 send_*_as_user tool handlers
+// return the v1.3.12 unified shape: {ok, viaUser, fallbackWarning?, messageId?}
+//
+// Pre-v1.3.12 the user-identity send tools returned plain text
+// ("Text sent as user to oc_xxx"); send_card_as_user already returned
+// a bot-path messageId text. The new shape is JSON inside an MCP text
+// content block so the LLM can read ok / viaUser / messageId structurally
+// without regex.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { handlers: msgHandlers } = require('./tools/messaging-user');
+
+// Parse a tool MCP response { content: [{type:'text', text: '...'}] } where
+// the text is JSON. Returns the parsed object, or null if the text isn't JSON
+// (e.g. disambiguation message from send_to_user with multiple matches).
+function parseJsonResponse(resp) {
+  const t = resp?.content?.[0]?.text;
+  if (typeof t !== 'string') return null;
+  try { return JSON.parse(t); } catch (_) { return null; }
+}
+
+// Stub MCP ctx with controllable per-call behavior.
+function fakeCtx({ sendImpl, botSendImpl } = {}) {
+  const userClient = {
+    sendMessage: async (chat, text /* , opts */) => sendImpl({ chat, text, kind: 'text' }),
+    sendImage:   async (chat, key /* , opts */) => sendImpl({ chat, key, kind: 'image' }),
+    sendFile:    async (chat, key, name /* , opts */) => sendImpl({ chat, key, name, kind: 'file' }),
+    sendPost:    async (chat, title, paragraphs /* , opts */) => sendImpl({ chat, title, paragraphs, kind: 'post' }),
+    search: async () => [], // tests below avoid send_to_user / send_to_group multi-match
+    createChat: async () => 'oc_fake',
+  };
+  return {
+    getUserClient: async () => userClient,
+    getOfficialClient: () => ({
+      sendMessageAsBot: async (chat, msgType, payload) => botSendImpl({ chat, msgType, payload }),
+    }),
+    resolveDocId: async (x) => x,
+  };
+}
+
+async function run() {
+  // --- 1. send_as_user → ok / viaUser=true / status passed through ---
+  {
+    const ctx = fakeCtx({
+      sendImpl: async () => ({ success: true, status: 0 }),
+    });
+    const resp = await msgHandlers.send_as_user({ chat_id: '7234567890123', text: 'hi' }, ctx);
+    const parsed = parseJsonResponse(resp);
+    assert.ok(parsed, 'send_as_user should return JSON-parseable shape');
+    assert.equal(parsed.ok, true, 'ok flag present and true on success');
+    assert.equal(parsed.viaUser, true, 'cookie/user path → viaUser=true');
+    assert.equal(parsed.fallbackWarning, undefined);
+  }
+
+  // --- 2. send_as_user failure → ok=false ---
+  {
+    const ctx = fakeCtx({
+      sendImpl: async () => ({ success: false, status: 70003 }),
+    });
+    const resp = await msgHandlers.send_as_user({ chat_id: '7234567890123', text: 'hi' }, ctx);
+    const parsed = parseJsonResponse(resp);
+    assert.ok(parsed);
+    assert.equal(parsed.ok, false, 'failed send → ok=false');
+    assert.equal(parsed.viaUser, true);
+  }
+
+  // --- 3. send_image_as_user, send_file_as_user, send_post_as_user — same shape ---
+  for (const [name, args] of [
+    ['send_image_as_user', { chat_id: '7234567890123', image_key: 'img_xxx' }],
+    ['send_file_as_user',  { chat_id: '7234567890123', file_key: 'file_xxx', file_name: 'a.pdf' }],
+    ['send_post_as_user',  { chat_id: '7234567890123', title: 'T', paragraphs: [] }],
+  ]) {
+    const ctx = fakeCtx({
+      sendImpl: async () => ({ success: true, status: 0 }),
+    });
+    const resp = await msgHandlers[name](args, ctx);
+    const parsed = parseJsonResponse(resp);
+    assert.ok(parsed, `${name} should return JSON shape`);
+    assert.equal(parsed.ok, true, `${name} ok=true on success`);
+    assert.equal(parsed.viaUser, true, `${name} viaUser=true`);
+  }
+
+  // --- 4. send_card_as_user → viaUser=false + messageId ---
+  {
+    const ctx = fakeCtx({
+      botSendImpl: async () => ({ messageId: 'om_card_123' }),
+    });
+    const resp = await msgHandlers.send_card_as_user({ chat_id: '7234567890123', card: {} }, ctx);
+    const parsed = parseJsonResponse(resp);
+    assert.ok(parsed, 'send_card_as_user JSON');
+    assert.equal(parsed.ok, true);
+    assert.equal(parsed.viaUser, false, 'card path goes via bot → viaUser=false');
+    assert.equal(parsed.messageId, 'om_card_123');
+  }
+
+  // --- 5. unified shape: no extra fields beyond {ok, viaUser, description?, fallbackWarning?, messageId?, status?} ---
+  {
+    const ctx = fakeCtx({
+      sendImpl: async () => ({ success: true, status: 0 }),
+    });
+    const resp = await msgHandlers.send_as_user({ chat_id: '7234567890123', text: 'hi' }, ctx);
+    const parsed = parseJsonResponse(resp);
+    const allowed = new Set(['ok', 'viaUser', 'description', 'fallbackWarning', 'messageId', 'status']);
+    for (const k of Object.keys(parsed)) {
+      assert.ok(allowed.has(k), `send_as_user returned unexpected key '${k}' — unified shape allows only ${[...allowed].join(', ')}`);
+    }
+  }
+
+  console.log('send-shape.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-via-user.js

@@ -0,0 +1,94 @@
+// src/test-via-user.js — verify the v1.3.12 `via_user` param on
+// read_messages controls bot/UAT routing.
+//
+// Pre-v1.3.12 read_messages auto-failed bot → UAT (skipBot true only when
+// chat resolved via cookie search_contacts). No way for the LLM/user to
+// say "I know this is mine, go UAT first" or "I want only the bot view".
+//
+// New: read_messages accepts `via_user: boolean`.
+//   - via_user=true  → skip bot, go straight to UAT (alias of skipBot)
+//   - via_user=false → bot-only, NEVER fall back to UAT (skipUat new)
+//   - undefined      → existing auto-fallback (default)
+//
+// Test stubs readMessagesWithFallback directly to count which paths fire.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { handlers } = require('./tools/im-read');
+
+function fakeCtx({ fallbackImpl, asUserImpl }) {
+  let lastOpts;
+  const official = {
+    hasUAT: true,
+    readMessagesWithFallback: async (chatId, msgOpts, uc, opts) => {
+      lastOpts = opts;
+      return fallbackImpl({ chatId, msgOpts, opts });
+    },
+    readMessagesAsUser: async (chatId, msgOpts, uc) => {
+      lastOpts = { via: 'user' };
+      return asUserImpl ? asUserImpl({ chatId, msgOpts }) : { items: [], via: 'user' };
+    },
+    getChatInfo: async () => ({ name: 'fake group' }),
+  };
+  return {
+    getOfficialClient: () => official,
+    getUserClient: async () => ({
+      search: async () => [],
+    }),
+    _getLastOpts: () => lastOpts,
+  };
+}
+
+async function run() {
+  // --- 1. via_user=true → skipBot ---
+  {
+    const ctx = fakeCtx({
+      fallbackImpl: ({ opts }) => ({ items: [], opts }),
+    });
+    const resp = await handlers.read_messages({ chat_id: 'oc_x', via_user: true }, ctx);
+    const opts = ctx._getLastOpts();
+    assert.ok(opts);
+    assert.equal(opts.skipBot, true, 'via_user=true → skipBot=true');
+  }
+
+  // --- 2. via_user=false → skipUat ---
+  {
+    const ctx = fakeCtx({
+      fallbackImpl: ({ opts }) => ({ items: [], opts }),
+    });
+    const resp = await handlers.read_messages({ chat_id: 'oc_x', via_user: false }, ctx);
+    const opts = ctx._getLastOpts();
+    assert.ok(opts);
+    assert.equal(opts.skipUat, true, 'via_user=false → skipUat=true');
+  }
+
+  // --- 3. via_user undefined → default auto-fallback (no skip flags) ---
+  {
+    const ctx = fakeCtx({
+      fallbackImpl: ({ opts }) => ({ items: [], opts }),
+    });
+    const resp = await handlers.read_messages({ chat_id: 'oc_x' }, ctx);
+    const opts = ctx._getLastOpts();
+    // Either opts is undefined or both skip flags absent — both mean auto-fallback.
+    assert.ok(!opts || !opts.skipBot, 'no via_user → no skipBot (auto)');
+    assert.ok(!opts || !opts.skipUat, 'no via_user → no skipUat (auto)');
+  }
+
+  // --- 4. read_messages schema has via_user param ---
+  {
+    const { schemas } = require('./tools/im-read');
+    const readMessages = schemas.find(s => s.name === 'read_messages');
+    assert.ok(readMessages);
+    assert.ok(readMessages.inputSchema.properties.via_user,
+      'read_messages inputSchema should have via_user property');
+    assert.equal(readMessages.inputSchema.properties.via_user.type, 'boolean');
+    assert.ok(readMessages.inputSchema.properties.via_user.description.length > 30,
+      'via_user description should explain the routing semantics');
+  }
+
+  console.log('via-user.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/test-with-uat-retry.js

@@ -0,0 +1,135 @@
+// src/test-with-uat-retry.js — unit test for the v1.3.12 widening of
+// `withUAT` in src/auth/uat.js.
+//
+// Background: pre-v1.3.12 `withUAT` only retried fn() when the response
+// carried code in {99991668, 99991663, 99991677} (it refreshed the UAT and
+// re-ran). Anything else — network blip, truncated JSON body, ECONNRESET —
+// bubbled straight out, even though one retry would have cleared the failure.
+//
+// New behaviour:
+//   1. If fn() throws AND classifyError says action='retry', call fn() one
+//      more time with the *same* uat (it's an upstream flake, not an auth
+//      issue — refreshing wouldn't help).
+//   2. Existing 99991668 / 99991663 / 99991677 path is unchanged: refresh
+//      then re-run.
+//   3. Otherwise (success, or non-retriable code) return data as-is.
+//
+// Real Feishu API is NOT touched — we mock fn() directly.
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const { withUAT } = require('./auth/uat');
+
+function fakeClient() {
+  const farFuture = Math.floor(Date.now() / 1000) + 3600;
+  return {
+    appId: 'cli_test',
+    appSecret: 'secret',
+    _uat: 'fake_token',
+    _uatRefresh: 'fake_refresh',
+    _uatExpires: farFuture,
+    get hasUAT() { return !!this._uat; },
+  };
+}
+
+async function run() {
+  // --- 1. Success on first try → no retry ---
+  {
+    let calls = 0;
+    const data = await withUAT(fakeClient(), async () => {
+      calls++;
+      return { code: 0, data: { ok: true } };
+    });
+    assert.equal(calls, 1);
+    assert.equal(data.code, 0);
+  }
+
+  // --- 2. Throws network error → retries once, succeeds ---
+  {
+    let calls = 0;
+    const data = await withUAT(fakeClient(), async () => {
+      calls++;
+      if (calls === 1) throw new Error('fetch timeout after 10000ms');
+      return { code: 0, data: { ok: true } };
+    });
+    assert.equal(calls, 2, 'should retry transient throw once');
+    assert.equal(data.code, 0);
+  }
+
+  // --- 3. Throws JSON parse error → retries once ---
+  {
+    let calls = 0;
+    const data = await withUAT(fakeClient(), async () => {
+      calls++;
+      if (calls === 1) {
+        const err = new SyntaxError('Unexpected end of JSON input');
+        throw err;
+      }
+      return { code: 0, data: { ok: 'parsed' } };
+    });
+    assert.equal(calls, 2);
+    assert.equal(data.data.ok, 'parsed');
+  }
+
+  // --- 4. Throws non-retriable error → re-throws (no retry) ---
+  {
+    let calls = 0;
+    let caught;
+    try {
+      await withUAT(fakeClient(), async () => {
+        calls++;
+        throw new Error('something completely unexpected');
+      });
+    } catch (e) { caught = e; }
+    assert.equal(calls, 1, 'unknown error should not retry');
+    assert.ok(caught);
+    assert.ok(caught.message.includes('something completely unexpected'));
+  }
+
+  // --- 5. Throws transient on BOTH attempts → re-throws ---
+  {
+    let calls = 0;
+    let caught;
+    try {
+      await withUAT(fakeClient(), async () => {
+        calls++;
+        throw new Error('fetch timeout after 10000ms');
+      });
+    } catch (e) { caught = e; }
+    assert.equal(calls, 2, 'should give up after one retry');
+    assert.ok(caught);
+  }
+
+  // --- 6. ECONNRESET pattern → retry ---
+  {
+    let calls = 0;
+    const data = await withUAT(fakeClient(), async () => {
+      calls++;
+      if (calls === 1) throw new Error('socket hang up ECONNRESET');
+      return { code: 0 };
+    });
+    assert.equal(calls, 2);
+  }
+
+  // --- 7. Existing auth-code path still works: 99991663 triggers refresh ---
+  // We can't easily mock refreshUAT without rewiring; verify the data path
+  // for the simple non-refresh "no auth code" case here (refresh path is
+  // exercised by integration tests / real API).
+  {
+    let calls = 0;
+    const data = await withUAT(fakeClient(), async () => {
+      calls++;
+      return { code: 42101, msg: 'rate limited' };
+    });
+    // 42101 is not an auth code so withUAT returns it without refresh-retry.
+    // (Caller may decide to retry via classifyError separately.)
+    assert.equal(calls, 1);
+    assert.equal(data.code, 42101);
+  }
+
+  console.log('with-uat-retry.js: PASS');
+}
+
+if (require.main === module) run().catch(e => { console.error(e); process.exit(1); });
+module.exports = { run };

package/src/tools/_registry.js

@@ -26,6 +26,29 @@ const json = (o) => {
   return text(warn + JSON.stringify(o, null, 2));
 };
 
-const sendResult = (r, desc) => text(r.success ? desc : `Send failed (status: ${r.status})`);
+// sendResult — unified shape for send_*_as_user tools (v1.3.12).
+// Returns JSON inside an MCP text block:
+//   { ok, viaUser, description?, status?, messageId?, fallbackWarning? }
+//
+// `r` is the raw response from a Lark client:
+//   - LarkUserClient.send*  → { success: bool, status: number }
+//   - LarkOfficialClient.sendMessageAsBot → { messageId: string }
+//
+// Back-compat signature: `sendResult(r, desc)` still works (desc treated as
+// description). New callers can pass `sendResult(r, { desc, viaUser: false,
+// fallbackWarning })`.
+const sendResult = (r, descOrOpts) => {
+  const opts = typeof descOrOpts === 'string' ? { desc: descOrOpts } : (descOrOpts || {});
+  const { desc, viaUser = true, fallbackWarning } = opts;
+  const out = {
+    ok: !!(r && (r.success || r.messageId)),
+    viaUser,
+  };
+  if (desc) out.description = desc;
+  if (r?.messageId) out.messageId = r.messageId;
+  if (r && typeof r.status !== 'undefined') out.status = r.status;
+  if (fallbackWarning) out.fallbackWarning = fallbackWarning;
+  return json(out);
+};
 
 module.exports = { text, json, sendResult };

package/src/tools/calendar.js

@@ -4,7 +4,7 @@
 // get_calendar_event, plus the v1.3.7 write tools:
 //   create_calendar_event / update_calendar_event / delete_calendar_event
 //   respond_calendar_event / get_freebusy
-// All UAT-first. Write tools require `calendar:calendar.event:write` scope.
+// All UAT-first. Write tools require `calendar:calendar.event:{create,update,delete,reply}` scope.
 
 const { json, text } = require('./_registry');
 
@@ -53,7 +53,7 @@ const schemas = [
   },
   {
     name: 'create_calendar_event',
-    description: `[Official API + UAT, v1.3.7] Create a new calendar event. Requires \`calendar:calendar.event:write\` scope (re-run \`npx feishu-user-plugin oauth\` after enabling). The current identity (UAT-first) must have writer or owner permission on the calendar.\n\nTime fields: ${TIME_NOTE}`,
+    description: `[Official API + UAT, v1.3.7] Create a new calendar event. Requires \`calendar:calendar.event:create\` scope (re-run \`npx feishu-user-plugin oauth\` after enabling). The current identity (UAT-first) must have writer or owner permission on the calendar.\n\nTime fields: ${TIME_NOTE}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -75,7 +75,7 @@ const schemas = [
   },
   {
     name: 'update_calendar_event',
-    description: '[Official API + UAT, v1.3.7] Patch fields on an existing calendar event. Pass only the fields you want to change. Requires `calendar:calendar.event:write` scope.',
+    description: '[Official API + UAT, v1.3.7] Patch fields on an existing calendar event. Pass only the fields you want to change. Requires `calendar:calendar.event:update` scope.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -98,7 +98,7 @@ const schemas = [
   },
   {
     name: 'delete_calendar_event',
-    description: '[Official API + UAT, v1.3.7] Delete a calendar event. Requires `calendar:calendar.event:write` scope.',
+    description: '[Official API + UAT, v1.3.7] Delete a calendar event. Requires `calendar:calendar.event:delete` scope.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -112,7 +112,7 @@ const schemas = [
   },
   {
     name: 'respond_calendar_event',
-    description: '[Official API + UAT, v1.3.7] Respond to an event invitation. The current identity must be in the event\'s attendee list. Requires `calendar:calendar.event:write` scope.',
+    description: '[Official API + UAT, v1.3.7] Respond to an event invitation. The current identity must be in the event\'s attendee list. Requires `calendar:calendar.event:reply` scope.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/im-read.js

@@ -107,7 +107,7 @@ const schemas = [
   },
   {
     name: 'read_p2p_messages',
-    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Auto-expands merge_forward messages into their child messages by default — disable with expand_merge_forward=false. Requires OAuth setup.',
+    description: '[User UAT] Read P2P (direct message) chat history using user_access_token. Works for chats the bot cannot access. Returns newest messages first by default. Auto-expands merge_forward messages into their child messages by default — disable with expand_merge_forward=false. Requires OAuth setup.\n\n**Sender semantics (v1.3.12)**: each message has a `displayLabel` (e.g. `周宇`, `[Bot] Claude聊天助手`, `[匿名]`, `[系统]`, `[已撤回] 怪兽`) — prefer it over raw `senderId` when narrating who-said-what. Also surfaced: `senderType` (user|app|anonymous), `senderIdType` (open_id|union_id|user_id), `senderTenantKey`, `isExternal` (cross-tenant), `isRecalled`, `isThreadReply` (parent_id present).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -145,7 +145,7 @@ const schemas = [
   },
   {
     name: 'read_messages',
-    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved. Auto-expands merge_forward messages into their child messages (with original sender / time / content preserved) by default — disable with expand_merge_forward=false. Text messages have URLs extracted into `urls`; Feishu doc links are additionally surfaced as `feishuDocs` so agents can feed them straight into read_doc / get_doc_blocks.',
+    description: '[Official API + UAT fallback] Read message history from any group. Accepts oc_xxx ID, numeric ID, or chat name (auto-searched). Auto-falls back to UAT for external groups the bot cannot access. Returns newest messages first by default, with sender names resolved. Auto-expands merge_forward messages into their child messages (with original sender / time / content preserved) by default — disable with expand_merge_forward=false. Text messages have URLs extracted into `urls`; Feishu doc links are additionally surfaced as `feishuDocs` so agents can feed them straight into read_doc / get_doc_blocks.\n\n**Sender semantics (v1.3.12)**: each message has a `displayLabel` (e.g. `周宇`, `[Bot] Claude聊天助手`, `[匿名]`, `[系统]`, `[已撤回] 怪兽`) — prefer it over raw `senderId` when narrating who-said-what. Also surfaced: `senderType` (user|app|anonymous), `senderIdType` (open_id|union_id|user_id), `senderTenantKey`, `isExternal` (cross-tenant), `isRecalled`, `isThreadReply` (parent_id present). **merge_forward children** carry `originChatId` (the chat the conversation came from, NOT the chat you queried) and best-effort `forwardedFromChatName` — do NOT treat children as native messages of the current group.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -155,10 +155,29 @@ const schemas = [
         end_time: { type: 'string', description: 'End timestamp in seconds (optional)' },
         sort_type: { type: 'string', enum: ['ByCreateTimeDesc', 'ByCreateTimeAsc'], description: 'Sort order (default: ByCreateTimeDesc = newest first)' },
         expand_merge_forward: { type: 'boolean', description: 'Auto-expand merge_forward placeholders into their child messages (default true). Children carry parentMessageId; use that id (not the child id) with download_message_resource (kind=image or file).' },
+        via_user: { type: 'boolean', description: 'v1.3.12 — explicit identity override. `true` skips the bot path and reads directly via UAT (use when the chat is yours / external and you know bot has no access). `false` skips UAT fallback and surfaces the bot error instead of cross-identity hop (use when you specifically want the bot view). Omit for default auto-fallback (bot first, UAT on failure).' },
       },
       required: ['chat_id'],
     },
   },
+  {
+    name: 'search_messages',
+    description: '[User UAT, v1.3.12] Search the user\'s IM history by keyword. Wraps Feishu `POST /open-apis/search/v2/message`. Requires UAT with the `search:message` scope (re-run `npx feishu-user-plugin oauth` after v1.3.12 SCOPES update). Feishu does NOT expose a bot-path search; if you only have app credentials this tool will error.\n\nReturns `{items, pageToken, hasMore}` where each item is a `{message_id, chat_id, ...}` pointer — call `read_messages(chat_id)` or `read_p2p_messages(chat_id)` to fetch the full message bodies if needed. The pointer-only return keeps the response token-light when searching across many chats.\n\nFilter knobs (all optional):\n- `chat_ids`: only search inside these chats (oc_xxx)\n- `from_ids`: messages sent by these users (ou_xxx / union_id)\n- `at_user_ids`: messages that @-mention these users\n- `message_types`: e.g. `["text", "post"]`\n- `from_types`: e.g. `["user", "anonymous"]`',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search keyword. Plain text; Feishu handles tokenization.' },
+        page_size: { type: 'number', description: 'Items per page (default 20, max 100)' },
+        page_token: { type: 'string', description: 'Pagination cursor from a previous page' },
+        chat_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to these oc_xxx chats' },
+        from_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to messages from these user ids (ou_xxx / union_id)' },
+        at_user_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to messages that @-mention these user ids' },
+        message_types: { type: 'array', items: { type: 'string' }, description: 'Filter by message types (e.g. ["text","post","image","file","interactive"])' },
+        from_types: { type: 'array', items: { type: 'string' }, description: 'Filter by sender types (e.g. ["user","anonymous"])' },
+      },
+      required: ['query'],
+    },
+  },
 ];
 
 const handlers = {
@@ -231,6 +250,15 @@ const handlers = {
       sortType: args.sort_type,
       expandMergeForward: args.expand_merge_forward !== false,
     };
+    // v1.3.12: via_user opt-in routing override. true=skip bot (UAT only),
+    // false=skip UAT (bot only / no fallback), undefined=default auto-fallback.
+    // Set `via: 'user'` explicitly so readMessagesWithFallback labels the
+    // response data.via = 'user' (distinguishing intentional UAT route from
+    // the auto-fallback case where 'bot' is the default label).
+    const routingOpts = {};
+    if (args.via_user === true) { routingOpts.skipBot = true; routingOpts.via = 'user'; }
+    else if (args.via_user === false) routingOpts.skipUat = true;
+
     // Get userClient for name resolution fallback (best-effort)
     let uc = null;
     try { uc = await ctx.getUserClient(); } catch (_) {}
@@ -238,12 +266,17 @@ const handlers = {
     // Path A — chat_id that resolves inside bot's / official search scope.
     const resolvedChatId = await chatIdMapper.resolveToOcId(args.chat_id, official);
     if (resolvedChatId) {
-      return json(await official.readMessagesWithFallback(resolvedChatId, msgOpts, uc));
+      return json(await official.readMessagesWithFallback(resolvedChatId, msgOpts, uc, routingOpts));
     }
 
     // Path B — external group discovered only via cookie search_contacts.
     // When we got here the bot definitely can't see it, so skip bot entirely
-    // and go straight to UAT with a `contacts` via label.
+    // and go straight to UAT with a `contacts` via label. If user explicitly
+    // set via_user=false (bot-only), short-circuit with a clear error rather
+    // than silently routing through UAT anyway.
+    if (args.via_user === false) {
+      return text(`Cannot find "${args.chat_id}" via bot, and via_user=false explicitly opts out of UAT fallback. Either omit via_user or set via_user=true.`);
+    }
     if (official.hasUAT) {
       if (!uc) try { uc = await ctx.getUserClient(); } catch (_) {}
       const contactChatId = await chatIdMapper.resolveViaContacts(args.chat_id, uc);
@@ -254,6 +287,21 @@ const handlers = {
 
     return text(`Cannot resolve "${args.chat_id}" to a chat ID.\nSearched: bot's group list, im.chat.search API, and user contacts (search_contacts).\nTry: provide the oc_xxx or numeric chat ID directly.`);
   },
+
+  async search_messages(args, ctx) {
+    const official = ctx.getOfficialClient();
+    const result = await official.searchMessages({
+      query: args.query,
+      pageSize: args.page_size,
+      pageToken: args.page_token,
+      chatIds: args.chat_ids,
+      fromIds: args.from_ids,
+      atUserIds: args.at_user_ids,
+      messageTypes: args.message_types,
+      fromTypes: args.from_types,
+    });
+    return json(result);
+  },
 };
 
 module.exports = { schemas, handlers };

package/src/tools/messaging-user.js

@@ -294,7 +294,7 @@ const handlers = {
   },
   async send_card_as_user(args, ctx) {
     const r = await ctx.getOfficialClient().sendMessageAsBot(args.chat_id, 'interactive', args.card);
-    return text(`Card sent (bot): ${r.messageId}`);
+    return sendResult(r, { desc: 'Card sent via bot (cookie channel rejects interactive)', viaUser: false });
   },
 };