feishu-user-plugin 1.3.6 → 1.3.7

package/src/tools/messaging-user.js

@@ -0,0 +1,292 @@
+// src/tools/messaging-user.js — User-identity (cookie-based) messaging plus
+// batch_send fan-out and the v1.3.6 bot-default send_card_as_user.
+//
+// All send_*_as_user handlers route through ctx.getUserClient() (cookie identity).
+// batch_send mixes user + bot identities per target. send_card_as_user currently
+// delegates to bot via ctx.getOfficialClient() — the "as_user" suffix is reserved
+// for v1.3.7's reverse-engineered cookie path; default flips when that lands.
+
+const { text, sendResult, json } = require('./_registry');
+
+// v1.3.7 C1.4: send_*_as_user (cookie protobuf) requires NUMERIC chat_id.
+// When callers pass `oc_xxx` (Open API format), resolve it via
+//   getChatInfo(oc_xxx) → name → cookie search(name) → numeric id
+// and cache the mapping for the session. Without resolution, the cookie
+// gateway accepts the call but the message goes nowhere (server treats
+// the chatId field as unknown and returns an empty packet).
+const _ocCache = new Map();
+
+async function _resolveCookieChatId(chatId, ctx) {
+  if (!chatId || typeof chatId !== 'string') return chatId;
+  if (!chatId.startsWith('oc_')) return chatId;
+  if (_ocCache.has(chatId)) return _ocCache.get(chatId);
+  let name;
+  try {
+    const info = await ctx.getOfficialClient().getChatInfo(chatId);
+    name = info?.name;
+  } catch (e) {
+    throw new Error(`Cannot resolve ${chatId} to a numeric chat_id (cookie protobuf needs numeric): getChatInfo failed (${e.message}). Pass a numeric chat_id directly — get one via search_contacts + create_p2p_chat (P2P) or list_user_chats (group).`);
+  }
+  if (!name) {
+    throw new Error(`Cannot resolve ${chatId}: getChatInfo returned no name. Pass a numeric chat_id directly.`);
+  }
+  const c = await ctx.getUserClient();
+  const results = await c.search(name);
+  // Prefer exact name match on a group; fall back to first group / user with this name.
+  const exact = results.find((r) => r.title === name && r.type === 'group');
+  const looser = exact || results.find((r) => r.type === 'group') || results.find((r) => r.title === name);
+  if (!looser) {
+    throw new Error(`Cannot resolve ${chatId} (chat "${name}"): no matching chat in cookie search. The chat may be a P2P with someone outside your search index, or you may not be a member. Use create_p2p_chat for P2P, or pass numeric chat_id directly.`);
+  }
+  const numeric = String(looser.id);
+  _ocCache.set(chatId, numeric);
+  return numeric;
+}
+
+const schemas = [
+  {
+    name: 'send_as_user',
+    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 (from create_p2p_chat / search) preferred; oc_xxx is auto-resolved via getChatInfo + cookie search since v1.3.7 (C1.4).' },
+        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)' },
+      },
+      required: ['chat_id', 'text'],
+    },
+  },
+  {
+    name: 'send_to_user',
+    description: '[User Identity] Search user by name → create P2P chat → send text message. All in one step.',
+    inputSchema: {
+      type: 'object',
+      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'],
+    },
+  },
+  {
+    name: 'send_to_group',
+    description: '[User Identity] Search group by name → send text message. All in one step.',
+    inputSchema: {
+      type: 'object',
+      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'],
+    },
+  },
+  {
+    name: 'batch_send',
+    description: '[User Identity / Official API] Send the same or different content to multiple targets in one call. Each target dispatches sequentially with a small delay (anti-rate-limit) and reports per-target success/error. Identity is the cookie user (user-identity sends) unless target.via=bot. Use for broadcast / fan-out scenarios.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        targets: {
+          type: 'array',
+          description: 'Array of targets. Each entry: { type: "user"|"group"|"chat", id: <user_name | group_name | chat_id>, content: { kind: "text"|"image"|"file"|"post", ... } }. For kind="text": { text }. For "image": { image_key }. For "file": { file_key, file_name }. For "post": { title, paragraphs }. Optional per-target: via="bot" routes through send_message_as_bot (chat_id required).',
+          items: { type: 'object' },
+        },
+        delay_ms: { type: 'number', description: 'Delay between sends in milliseconds (default 200, increase for risky volumes).' },
+      },
+      required: ['targets'],
+    },
+  },
+  {
+    name: 'send_image_as_user',
+    description: '[User Identity] Send an image as the logged-in user. Requires image_key (upload via Official API first).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat ID. Numeric preferred; oc_xxx is auto-resolved (v1.3.7 C1.4).' },
+        image_key: { type: 'string', description: 'Image key from upload (img_v2_xxx or img_v3_xxx)' },
+        root_id: { type: 'string', description: 'Thread root message ID (optional)' },
+      },
+      required: ['chat_id', 'image_key'],
+    },
+  },
+  {
+    name: 'send_file_as_user',
+    description: '[User Identity] Send a file as the logged-in user. Requires file_key (upload via Official API first).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat ID. Numeric preferred; oc_xxx is auto-resolved (v1.3.7 C1.4).' },
+        file_key: { type: 'string', description: 'File key from upload' },
+        file_name: { type: 'string', description: 'Display file name' },
+        root_id: { type: 'string', description: 'Thread root message ID (optional)' },
+      },
+      required: ['chat_id', 'file_key', 'file_name'],
+    },
+  },
+  {
+    name: 'send_post_as_user',
+    description: '[User Identity] Send a rich text (POST) message with title and formatted paragraphs. Supports real @-mentions that trigger notifications.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat ID. Numeric preferred; oc_xxx is auto-resolved (v1.3.7 C1.4).' },
+        title: { type: 'string', description: 'Post title (optional)' },
+        paragraphs: {
+          type: 'array',
+          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)' },
+      },
+      required: ['chat_id', 'paragraphs'],
+    },
+  },
+  {
+    name: 'send_card_as_user',
+    description: '[v1.3.6: bot-routed default] Send an interactive card to a chat. **As of v1.3.6, identity defaults to BOT** because user-identity card sending requires reverse-engineering the Feishu web protobuf and is deferred to v1.3.7. The tool name keeps the "as_user" suffix so callers don\'t have to migrate when v1.3.7 lands; once user-identity is implemented the default flips. Pass `card` as a JSON object (Feishu card schema). To force bot explicitly set via="bot".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
+        card: { description: 'Feishu card JSON. See https://open.feishu.cn/cardkit for the schema; build cards visually then paste the resulting JSON here.' },
+        via: { type: 'string', enum: ['bot', 'user'], description: 'Identity to send as. Default "bot". "user" returns an explicit not-yet-implemented error in v1.3.6.' },
+      },
+      required: ['chat_id', 'card'],
+    },
+  },
+];
+
+const handlers = {
+  async send_as_user(args, ctx) {
+    const c = await ctx.getUserClient();
+    const chatId = await _resolveCookieChatId(args.chat_id, ctx);
+    const r = await c.sendMessage(chatId, args.text, { rootId: args.root_id, parentId: args.parent_id, ats: args.ats });
+    return sendResult(r, `Text sent as user to ${args.chat_id}`);
+  },
+  async send_to_user(args, ctx) {
+    const c = await ctx.getUserClient();
+    const results = await c.search(args.user_name);
+    const users = results.filter(r => r.type === 'user');
+    if (users.length === 0) return text(`User "${args.user_name}" not found. Results: ${JSON.stringify(results)}`);
+    if (users.length > 1) {
+      const candidates = users.slice(0, 5).map(u => `  - ${u.title} (ID: ${u.id})`).join('\n');
+      return text(`Multiple users match "${args.user_name}":\n${candidates}\nUse search_contacts to find the exact user, then create_p2p_chat + send_as_user.`);
+    }
+    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, { ats: args.ats });
+    return sendResult(r, `Text sent to ${user.title} (chat: ${chatId})`);
+  },
+  async send_to_group(args, ctx) {
+    const c = await ctx.getUserClient();
+    const results = await c.search(args.group_name);
+    const groups = results.filter(r => r.type === 'group');
+    if (groups.length === 0) return text(`Group "${args.group_name}" not found. Results: ${JSON.stringify(results)}`);
+    if (groups.length > 1) {
+      const candidates = groups.slice(0, 5).map(g => `  - ${g.title} (ID: ${g.id})`).join('\n');
+      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, { ats: args.ats });
+    return sendResult(r, `Text sent to group "${group.title}" (${group.id})`);
+  },
+  async batch_send(args, ctx) {
+    if (!Array.isArray(args.targets) || args.targets.length === 0) return text('batch_send: targets must be a non-empty array');
+    const delay = typeof args.delay_ms === 'number' ? args.delay_ms : 200;
+    const userClient = await ctx.getUserClient();
+    const officialClient = ctx.getOfficialClient();
+    const results = [];
+    for (let i = 0; i < args.targets.length; i++) {
+      const t = args.targets[i];
+      try {
+        if (!t.content || !t.content.kind) throw new Error('content.kind is required');
+        // Resolve chat id from name when applicable
+        let chatId = t.id;
+        if (t.type === 'user' || t.type === 'group') {
+          const matches = await userClient.search(t.id);
+          const want = matches.filter(m => m.type === t.type);
+          if (want.length === 0) throw new Error(`No ${t.type} matches "${t.id}"`);
+          if (want.length > 1) throw new Error(`Ambiguous ${t.type} "${t.id}" (${want.length} matches). Use type="chat" with explicit chat_id.`);
+          const picked = want[0];
+          chatId = t.type === 'user' ? await userClient.createChat(picked.id) : picked.id;
+          if (!chatId) throw new Error(`Could not resolve chat for ${t.type} ${picked.title}`);
+        } else if (t.via !== 'bot') {
+          // type=chat with cookie identity — resolve oc_xxx → numeric (v1.3.7 C1.4).
+          chatId = await _resolveCookieChatId(chatId, ctx);
+        }
+        let r;
+        if (t.via === 'bot') {
+          const c = t.content;
+          const payload = c.kind === 'text' ? { text: c.text }
+            : c.kind === 'post' ? { post: { zh_cn: { title: c.title || '', content: c.paragraphs || [] } } }
+            : c.kind === 'image' ? { image_key: c.image_key }
+            : c.kind === 'interactive' ? c.card
+            : null;
+          if (!payload) throw new Error(`bot path does not support content.kind=${c.kind}`);
+          const msgType = c.kind === 'interactive' ? 'interactive' : c.kind;
+          r = await officialClient.sendMessageAsBot(chatId, msgType, payload);
+          results.push({ ok: true, target: t, messageId: r.messageId, via: 'bot' });
+        } else {
+          const c = t.content;
+          if (c.kind === 'text') r = await userClient.sendMessage(chatId, c.text, { ats: c.ats });
+          else if (c.kind === 'image') r = await userClient.sendImage(chatId, c.image_key);
+          else if (c.kind === 'file') r = await userClient.sendFile(chatId, c.file_key, c.file_name);
+          else if (c.kind === 'post') r = await userClient.sendPost(chatId, c.title, c.paragraphs);
+          else throw new Error(`unknown content.kind=${c.kind}`);
+          results.push({ ok: true, target: t, messageId: r.messageId, via: 'user' });
+        }
+      } catch (e) {
+        results.push({ ok: false, target: t, error: e.message });
+      }
+      if (i < args.targets.length - 1 && delay > 0) await new Promise(r => setTimeout(r, delay));
+    }
+    const okCount = results.filter(r => r.ok).length;
+    return json({ summary: `${okCount}/${results.length} sent`, results });
+  },
+  async send_image_as_user(args, ctx) {
+    const c = await ctx.getUserClient();
+    const chatId = await _resolveCookieChatId(args.chat_id, ctx);
+    const r = await c.sendImage(chatId, args.image_key, { rootId: args.root_id });
+    return sendResult(r, `Image sent to ${args.chat_id}`);
+  },
+  async send_file_as_user(args, ctx) {
+    const c = await ctx.getUserClient();
+    const chatId = await _resolveCookieChatId(args.chat_id, ctx);
+    const r = await c.sendFile(chatId, args.file_key, args.file_name, { rootId: args.root_id });
+    return sendResult(r, `File "${args.file_name}" sent to ${args.chat_id}`);
+  },
+  async send_post_as_user(args, ctx) {
+    const c = await ctx.getUserClient();
+    const chatId = await _resolveCookieChatId(args.chat_id, ctx);
+    const r = await c.sendPost(chatId, args.title || '', args.paragraphs, { rootId: args.root_id });
+    return sendResult(r, `Post sent to ${args.chat_id}`);
+  },
+  async send_card_as_user(args, ctx) {
+    const via = args.via || 'bot';
+    if (via === 'user') {
+      return text('send_card_as_user via="user" is not implemented in v1.3.6 — user-identity card sending requires reverse-engineering the Feishu web protobuf and is scheduled for v1.3.7. Use via="bot" (default) for now.');
+    }
+    const r = await ctx.getOfficialClient().sendMessageAsBot(args.chat_id, 'interactive', args.card);
+    return text(`Card sent (${via}): ${r.messageId}`);
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/okr.js

@@ -0,0 +1,159 @@
+// src/tools/okr.js — OKR read tools (v1.3.4) + progress record write (v1.3.7).
+
+const { json, text } = require('./_registry');
+
+// Helper: wrap plain text into the Feishu OKR progressRecord content block schema.
+// Feishu's progressRecord.create expects a `content: { blocks: [...] }` payload
+// where each block is a paragraph or gallery. Most callers just want a plain
+// note, so this helper builds the trivial single-paragraph form.
+function buildOkrContent(text) {
+  return {
+    blocks: [
+      {
+        type: 'paragraph',
+        paragraph: {
+          elements: [
+            { type: 'textRun', textRun: { text: String(text || '') } },
+          ],
+        },
+      },
+    ],
+  };
+}
+
+const schemas = [
+  {
+    name: 'list_user_okrs',
+    description: '[Official API + UAT] List a user\'s OKRs. Requires the user\'s open_id (get yours via get_login_status or search_contacts). Filter by period_ids to narrow to a specific quarter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user_id: { type: 'string', description: 'Target user\'s open_id (or the matching user_id_type)' },
+        user_id_type: { type: 'string', enum: ['user_id', 'union_id', 'open_id', 'people_admin_id'], description: 'Type of user_id (default: open_id)' },
+        period_ids: { type: 'array', items: { type: 'string' }, description: 'Filter by OKR period IDs (optional). Get period IDs via list_okr_periods.' },
+        offset: { type: 'number', description: 'Pagination offset (default 0)' },
+        limit: { type: 'number', description: 'Items per page (default 10, max 10)' },
+        lang: { type: 'string', description: 'Response language (optional, e.g. "zh_cn", "en_us")' },
+      },
+      required: ['user_id'],
+    },
+  },
+  {
+    name: 'get_okrs',
+    description: '[Official API + UAT] Batch-fetch full OKR details (objectives, key results, progress, alignments) by OKR IDs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        okr_ids: { type: 'array', items: { type: 'string' }, description: 'OKR IDs (max 10 per call). From list_user_okrs.' },
+        user_id_type: { type: 'string', enum: ['user_id', 'union_id', 'open_id', 'people_admin_id'], description: 'Type of user_ids in response (default: open_id)' },
+        lang: { type: 'string', description: 'Response language (optional)' },
+      },
+      required: ['okr_ids'],
+    },
+  },
+  {
+    name: 'list_okr_periods',
+    description: '[Official API + UAT] List OKR periods (quarters / years) defined in the tenant. Use period_ids from this to filter list_user_okrs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page_size: { type: 'number', description: 'Items per page (default 10)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+    },
+  },
+  {
+    name: 'create_okr_progress_record',
+    description: '[Official API + UAT, v1.3.7] Add a progress note to an OKR objective or key result. Feishu requires `source_title`, `source_url`, and a block-structured `content`; this tool exposes a simple `content_text` and auto-wraps it into the single-paragraph block format. Pass richer `content` directly if you need lists / mentions / docs links / images.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target_id: { type: 'string', description: 'ID of the OKR objective or key result. Get from get_okrs response (`objective_list[].id` or `objective_list[].kr_list[].id`).' },
+        target_type: { type: 'number', description: '1 = objective, 2 = key result. Pick based on which level target_id refers to.' },
+        content_text: { type: 'string', description: 'Plain-text progress note. Auto-wrapped into the Feishu block format. Use `content` instead for rich text.' },
+        content: { type: 'object', description: 'Optional: full Feishu block structure ({blocks:[...]}). If provided, overrides content_text.' },
+        source_title: { type: 'string', description: 'Source label (default "Progress update"). Shown next to the note in the OKR UI.' },
+        source_url: { type: 'string', description: 'Source URL (default https://feishu.cn/). Feishu requires a URL even for plain notes.' },
+        source_url_pc: { type: 'string', description: 'Optional PC-specific source URL.' },
+        source_url_mobile: { type: 'string', description: 'Optional mobile-specific source URL.' },
+        progress_percent: { type: 'number', description: 'Optional progress percent (0-100) to bump alongside the note.' },
+        progress_status: { type: 'number', description: 'Optional status code (Feishu enum: 1=on track, 2=at risk, 3=blocked, etc).' },
+        user_id_type: { type: 'string', enum: ['user_id', 'union_id', 'open_id'], description: 'Type of user IDs in mentioned_user_list etc. (default open_id)' },
+      },
+      required: ['target_id', 'target_type'],
+    },
+  },
+  {
+    name: 'list_okr_progress_records',
+    description: '[Official API + UAT, v1.3.7] List progress records for an OKR. Feishu has no native list endpoint — this tool calls get_okrs internally and walks the objective_list / kr_list to extract progress_record IDs (with their target_id and target_type). To read a record\'s full content, you currently need progressRecord.get (not yet wrapped).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        okr_id: { type: 'string', description: 'OKR ID (from list_user_okrs).' },
+        user_id_type: { type: 'string', enum: ['user_id', 'union_id', 'open_id'], description: 'Pass-through to get_okrs (default open_id)' },
+      },
+      required: ['okr_id'],
+    },
+  },
+  {
+    name: 'delete_okr_progress_record',
+    description: '[Official API + UAT, v1.3.7] Delete an OKR progress record by its progress_id (from list_okr_progress_records).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        progress_id: { type: 'string', description: 'Progress record ID' },
+      },
+      required: ['progress_id'],
+    },
+  },
+];
+
+const handlers = {
+  async list_user_okrs(args, ctx) {
+    return json(await ctx.getOfficialClient().listUserOkrs(args.user_id, {
+      periodIds: args.period_ids, offset: args.offset, limit: args.limit, lang: args.lang,
+      userIdType: args.user_id_type,
+    }));
+  },
+  async get_okrs(args, ctx) {
+    return json(await ctx.getOfficialClient().getOkrs(args.okr_ids, { lang: args.lang, userIdType: args.user_id_type }));
+  },
+  async list_okr_periods(args, ctx) {
+    return json(await ctx.getOfficialClient().listOkrPeriods({ pageSize: args.page_size, pageToken: args.page_token }));
+  },
+  async create_okr_progress_record(args, ctx) {
+    if (!args.content_text && !args.content) {
+      return text('create_okr_progress_record: pass content_text (a plain string, auto-wrapped) or content (a full {blocks:[...]} structure).');
+    }
+    const content = args.content || buildOkrContent(args.content_text);
+    let progressRate;
+    if (args.progress_percent !== undefined || args.progress_status !== undefined) {
+      progressRate = {};
+      if (args.progress_percent !== undefined) progressRate.percent = args.progress_percent;
+      if (args.progress_status !== undefined) progressRate.status = args.progress_status;
+    }
+    const r = await ctx.getOfficialClient().createOkrProgressRecord({
+      targetId: args.target_id,
+      targetType: args.target_type,
+      content,
+      sourceTitle: args.source_title,
+      sourceUrl: args.source_url,
+      sourceUrlPc: args.source_url_pc,
+      sourceUrlMobile: args.source_url_mobile,
+      progressRate,
+      userIdType: args.user_id_type,
+    });
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; record posted as bot)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Progress record created${ownership}: ${r.progressId}\n${JSON.stringify(r, null, 2)}${warn}`);
+  },
+  async list_okr_progress_records(args, ctx) {
+    return json(await ctx.getOfficialClient().listOkrProgressRecords(args.okr_id, { userIdType: args.user_id_type }));
+  },
+  async delete_okr_progress_record(args, ctx) {
+    const r = await ctx.getOfficialClient().deleteOkrProgressRecord(args.progress_id);
+    return text(`Progress record ${args.progress_id} deleted${r.viaUser ? '' : ' (as app)'}`);
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/profile.js

@@ -0,0 +1,43 @@
+// src/tools/profile.js — multi-account profile management (v1.3.6).
+//
+// LARK_PROFILES_JSON env var registers extra credential sets; this module
+// exposes them via list_profiles + switch_profile so callers can hot-swap
+// between accounts/tenants without restarting the MCP server.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'list_profiles',
+    description: '[Plugin] List all available identity profiles (sets of LARK_COOKIE/APP_ID/APP_SECRET/UAT). The "default" profile uses the top-level env vars; additional profiles come from LARK_PROFILES_JSON. Marks the currently active profile.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'switch_profile',
+    description: '[Plugin] Switch the active identity profile. Subsequent tool calls use the new profile\'s credentials. Cached client instances are reset so the next call rebuilds against the new creds.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Profile name. "default" for top-level env vars; any key from LARK_PROFILES_JSON otherwise.' },
+      },
+      required: ['name'],
+    },
+  },
+];
+
+const handlers = {
+  async list_profiles(_args, ctx) {
+    return json({ active: ctx.getActiveProfile(), profiles: ctx.listProfiles() });
+  },
+  async switch_profile(args, ctx) {
+    const target = args.name;
+    const all = ctx.listProfiles();
+    if (!all.includes(target)) {
+      return text(`Profile "${target}" not found. Available: ${all.join(', ')}. To add more, set LARK_PROFILES_JSON in your MCP env.`);
+    }
+    ctx.setActiveProfile(target);
+    return text(`Switched to profile: ${target}`);
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/tasks.js

@@ -0,0 +1,168 @@
+// src/tools/tasks.js — Feishu Tasks v2 tools (v1.3.7 new domain).
+//
+// 7 tools backed by clients/official/tasks.js. All UAT-first.
+// Requires `task:task` scope on the OAuth — re-run `npx feishu-user-plugin oauth`
+// after enabling the scope on the Feishu app console.
+
+const { json, text } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'list_tasks',
+    description: '[Official API + UAT, v1.3.7] List the current user\'s tasks. Filter by completion or type.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        completed: { type: 'boolean', description: 'true → only completed; false → only pending; omit → all' },
+        type: { type: 'string', description: 'Filter by task type (optional). E.g. "all" / "personal".' },
+        page_size: { type: 'number', description: 'Items per page (default Feishu default)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+    },
+  },
+  {
+    name: 'get_task',
+    description: '[Official API + UAT, v1.3.7] Get full details of a single task by GUID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID (from list_tasks / create_task / Feishu URL)' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'create_task',
+    description: '[Official API + UAT, v1.3.7] Create a new task. summary is required; due / members / etc. are optional.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: { type: 'string', description: 'Task title' },
+        description: { type: 'string', description: 'Task description (optional)' },
+        due: { type: 'object', description: 'Due time (optional). {timestamp:"<unix-millis>", is_all_day?:true|false}' },
+        members: {
+          type: 'array',
+          description: 'Initial members (optional). Each: {id:"<open_id>", role:"assignee"|"follower", type?:"user", name?:"..."}',
+          items: { type: 'object' },
+        },
+        repeat_rule: { type: 'string', description: 'Recurrence (optional, RFC5545 RRULE)' },
+        extra: { type: 'string', description: 'Free-form extra metadata (optional)' },
+      },
+      required: ['summary'],
+    },
+  },
+  {
+    name: 'update_task',
+    description: '[Official API + UAT, v1.3.7] Patch a task. **update_fields** is required by Feishu — list which fields to update (e.g. ["summary","due","completed_at"]).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+        update_fields: {
+          type: 'array',
+          description: 'Required. Names of fields to update. E.g. ["summary","description","due","completed_at","start","extra","repeat_rule"]. Feishu only patches fields listed here, ignoring other keys in `task`.',
+          items: { type: 'string' },
+        },
+        task: {
+          type: 'object',
+          description: 'Field values. E.g. {summary:"new title", due:{timestamp:"1717939200000"}}.',
+        },
+      },
+      required: ['task_guid', 'update_fields', 'task'],
+    },
+  },
+  {
+    name: 'complete_task',
+    description: '[Official API + UAT, v1.3.7] Mark a task complete (or uncomplete it). Convenience wrapper around update_task with completed_at.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+        completed: { type: 'boolean', description: 'true → mark complete (uses Date.now()); false → uncomplete (sets completed_at to "0"). Default true.' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'delete_task',
+    description: '[Official API + UAT, v1.3.7] Permanently delete a task.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_guid: { type: 'string', description: 'Task GUID' },
+      },
+      required: ['task_guid'],
+    },
+  },
+  {
+    name: 'manage_task_members',
+    description: '[Official API + UAT, v1.3.7] Add or remove members on a task. Members are objects {id:"<open_id>", role:"assignee"|"follower", type?:"user", name?:""}.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['add', 'remove'], description: 'add or remove' },
+        task_guid: { type: 'string', description: 'Task GUID' },
+        members: {
+          type: 'array',
+          description: 'Members to add/remove. Each: {id, role, type?, name?}.',
+          items: { type: 'object' },
+        },
+      },
+      required: ['action', 'task_guid', 'members'],
+    },
+  },
+];
+
+const handlers = {
+  async list_tasks(args, ctx) {
+    return json(await ctx.getOfficialClient().listTasks({
+      completed: args.completed,
+      type: args.type,
+      pageSize: args.page_size,
+      pageToken: args.page_token,
+    }));
+  },
+  async get_task(args, ctx) {
+    return json(await ctx.getOfficialClient().getTask(args.task_guid));
+  },
+  async create_task(args, ctx) {
+    const data = { summary: args.summary };
+    if (args.description !== undefined) data.description = args.description;
+    if (args.due !== undefined) data.due = args.due;
+    if (args.members !== undefined) data.members = args.members;
+    if (args.repeat_rule !== undefined) data.repeat_rule = args.repeat_rule;
+    if (args.extra !== undefined) data.extra = args.extra;
+    const r = await ctx.getOfficialClient().createTask(data);
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; task created by the app, not you)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Task created${ownership}: ${r.task?.guid || '(no guid returned)'}\n${JSON.stringify(r.task, null, 2)}${warn}`);
+  },
+  async update_task(args, ctx) {
+    const r = await ctx.getOfficialClient().updateTask(args.task_guid, args.task, args.update_fields);
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Task updated: ${args.task_guid}\n${JSON.stringify(r.task, null, 2)}${warn}`);
+  },
+  async complete_task(args, ctx) {
+    const completed = args.completed === undefined ? true : !!args.completed;
+    const r = await ctx.getOfficialClient().completeTask(args.task_guid, completed);
+    return text(`Task ${completed ? 'completed' : 'uncompleted'}: ${args.task_guid}`);
+  },
+  async delete_task(args, ctx) {
+    await ctx.getOfficialClient().deleteTask(args.task_guid);
+    return text(`Task deleted: ${args.task_guid}`);
+  },
+  async manage_task_members(args, ctx) {
+    const c = ctx.getOfficialClient();
+    if (args.action === 'add') {
+      const r = await c.addTaskMembers(args.task_guid, args.members);
+      return text(`Members added to ${args.task_guid}: ${args.members.length}\n${JSON.stringify(r.task?.members, null, 2)}`);
+    }
+    if (args.action === 'remove') {
+      const r = await c.removeTaskMembers(args.task_guid, args.members);
+      return text(`Members removed from ${args.task_guid}: ${args.members.length}\n${JSON.stringify(r.task?.members, null, 2)}`);
+    }
+    throw new Error('manage_task_members: action must be add or remove');
+  },
+};
+
+module.exports = { schemas, handlers };