download_message_resource

Instructions

Implementation Reference

• src/tools/diagnostics.js:112-148 (handler)

  Handler function for download_message_resource tool. Validates args (message_id, key, kind), calls the official client's downloadMessageResource, handles size caps (>2 MiB requires save_path), and returns appropriate responses: image content block for images, base64 text for files, or save_path summary for oversized payloads.

  async download_message_resource(args, ctx) {
    if (!args.message_id || !args.key) {
      return text('download_message_resource requires message_id and key. For merge_forward children, use the child\'s parentMessageId (not the child id).');
    }
    const kind = args.kind;
    if (kind !== 'image' && kind !== 'file') {
      return text('download_message_resource: kind must be "image" or "file".');
    }
    const r = await ctx.getOfficialClient().downloadMessageResource(args.message_id, args.key, kind);
    const sizeNote = `${r.bytes} bytes (${fmtMB(r.bytes)}, ${r.mimeType})`;
    const tooBig = inlineTooBig(r.bytes);
    if (tooBig && !args.save_path) {
      return text(`Resource is ${sizeNote} — exceeds the 2 MiB inline cap. Re-run download_message_resource with save_path=<absolute path> so the bytes are written to disk and only a small summary is returned.`);
    }
    const saved = maybeSave(args.save_path, r.base64);
    const saveNote = saved
      ? (saved.ok ? `\nSaved to: ${saved.path}` : `\nSave to ${saved.path} failed: ${saved.error}`)
      : '';
    const ident = r.viaUser ? 'as user' : 'as app';
    if (kind === 'image' && !tooBig) {
      return {
        content: [
          { type: 'text', text: `Image from message ${args.message_id} (${ident}, ${sizeNote})${saveNote}` },
          { type: 'image', data: r.base64, mimeType: r.mimeType },
        ],
      };
    }
    if (tooBig) {
      return text(`Resource from message ${args.message_id} downloaded (${ident}, ${sizeNote})${saveNote}\nInline content omitted because the payload exceeds the 2 MiB cap.`);
    }
    return {
      content: [
        { type: 'text', text: `File from message ${args.message_id} (${ident}, ${sizeNote})${saveNote}` },
        { type: 'text', text: `base64 (${r.bytes} bytes, truncated display):\n${r.base64.slice(0, 400)}${r.base64.length > 400 ? '…' : ''}` },
      ],
    };
  },

• src/tools/diagnostics.js:29-42 (schema)

  Schema definition for download_message_resource tool: name, description, and input schema with message_id (required), key (required), kind (required, enum image/file), and save_path (optional).

  {
    name: 'download_message_resource',
    description: '[User Identity / Official API] Download an image or file attached to a message so the model can see / store it. v1.3.7 (C2.4) consolidates the v1.3.6 download_image (mode 1) + download_file. UAT-first, falls back to app.\n\nFor images, the response includes an inline `image` content block so the model sees pixels. For files, the response includes the bytes as base64 (truncated for display) plus an optional save_path write.\n\n**Size cap:** payloads > 2 MiB MUST pass `save_path`. The Anthropic API rejects responses > 5 MB; we cap at 2 MiB so multipart wrapping has headroom.\n\n**merge_forward children:** Feishu keys media by the parent merge_forward id, not the child id. Use the child\'s `parentMessageId` field (returned by read_messages with expand_merge_forward) — not the child id.',
    inputSchema: {
      type: 'object',
      properties: {
        message_id: { type: 'string', description: 'Message ID (om_xxx). For merge_forward children, use the child\'s `parentMessageId`.' },
        key: { type: 'string', description: 'image_key (img_xxx) for kind=image, file_key for kind=file. From read_messages content.' },
        kind: { type: 'string', enum: ['image', 'file'], description: 'image or file' },
        save_path: { type: 'string', description: 'Absolute local path. Required when downloaded bytes > 2 MiB (else the response would exceed the Anthropic API 5 MB inline limit).' },
      },
      required: ['message_id', 'key', 'kind'],
    },
  },

• src/server.js:37-42 (registration)

  Tool registration: diagnostics module is loaded in TOOL_MODULES, its schemas are flattened into the TOOLS array for ListTools, and its handlers are merged into HANDLERS lookup for CallTool dispatch.

  const TOOL_MODULES = [
    require('./tools/bitable'),
    require('./tools/calendar'),
    require('./tools/contacts'),
    require('./tools/diagnostics'),
    require('./tools/docs'),

• src/clients/official/im.js:88-133 (helper)

  Client-side downloadMessageResource method on LarkOfficialClient. Calls Feishu's messages/:id/resources/:key API. Tries user access token (UAT) first for auth, falls back to app token. Returns base64-encoded payload, mimeType, byte count, and viaUser flag.

  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,
    };
  },