@openclaw/feishu 2026.2.25 → 2026.3.2

package/src/config-schema.ts

@@ -1,5 +1,7 @@
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import { z } from "zod";
 export { z };
+import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
 
 const DmPolicySchema = z.enum(["open", "pairing", "allowlist"]);
 const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
@@ -82,6 +84,7 @@ const DynamicAgentCreationSchema = z
 const FeishuToolsConfigSchema = z
   .object({
     doc: z.boolean().optional(), // Document operations (default: true)
+    chat: z.boolean().optional(), // Chat info + member query operations (default: true)
     wiki: z.boolean().optional(), // Knowledge base operations (default: true, requires doc)
     drive: z.boolean().optional(), // Cloud storage operations (default: true)
     perm: z.boolean().optional(), // Permission management (default: false, sensitive)
@@ -91,14 +94,39 @@ const FeishuToolsConfigSchema = z
   .optional();
 
 /**
+ * Group session scope for routing Feishu group messages.
+ * - "group" (default): one session per group chat
+ * - "group_sender": one session per (group + sender)
+ * - "group_topic": one session per group topic thread (falls back to group if no topic)
+ * - "group_topic_sender": one session per (group + topic thread + sender),
+ *   falls back to (group + sender) if no topic
+ */
+const GroupSessionScopeSchema = z
+  .enum(["group", "group_sender", "group_topic", "group_topic_sender"])
+  .optional();
+
+/**
+ * @deprecated Use groupSessionScope instead.
+ *
  * Topic session isolation mode for group chats.
  * - "disabled" (default): All messages in a group share one session
  * - "enabled": Messages in different topics get separate sessions
  *
- * When enabled, the session key becomes `chat:{chatId}:topic:{rootId}`
- * for messages within a topic thread, allowing isolated conversations.
+ * Topic routing uses `root_id` when present to keep session continuity and
+ * falls back to `thread_id` when `root_id` is unavailable.
  */
 const TopicSessionModeSchema = z.enum(["disabled", "enabled"]).optional();
+const ReactionNotificationModeSchema = z.enum(["off", "own", "all"]).optional();
+
+/**
+ * Reply-in-thread mode for group chats.
+ * - "disabled" (default): Bot replies are normal inline replies
+ * - "enabled": Bot replies create or continue a Feishu topic thread
+ *
+ * When enabled, the Feishu reply API is called with `reply_in_thread: true`,
+ * causing the reply to appear as a topic (话题) under the original message.
+ */
+const ReplyInThreadSchema = z.enum(["disabled", "enabled"]).optional();
 
 export const FeishuGroupSchema = z
   .object({
@@ -108,7 +136,9 @@ export const FeishuGroupSchema = z
     enabled: z.boolean().optional(),
     allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
     systemPrompt: z.string().optional(),
+    groupSessionScope: GroupSessionScopeSchema,
     topicSessionMode: TopicSessionModeSchema,
+    replyInThread: ReplyInThreadSchema,
   })
   .strict();
 
@@ -122,6 +152,7 @@ const FeishuSharedConfigShape = {
   allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
   groupPolicy: GroupPolicySchema.optional(),
   groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+  groupSenderAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
   requireMention: z.boolean().optional(),
   groups: z.record(z.string(), FeishuGroupSchema.optional()).optional(),
   historyLimit: z.number().int().min(0).optional(),
@@ -135,6 +166,10 @@ const FeishuSharedConfigShape = {
   renderMode: RenderModeSchema,
   streaming: StreamingModeSchema,
   tools: FeishuToolsConfigSchema,
+  replyInThread: ReplyInThreadSchema,
+  reactionNotifications: ReactionNotificationModeSchema,
+  typingIndicator: z.boolean().optional(),
+  resolveSenderNames: z.boolean().optional(),
 };
 
 /**
@@ -146,42 +181,62 @@ export const FeishuAccountConfigSchema = z
     enabled: z.boolean().optional(),
     name: z.string().optional(), // Display name for this account
     appId: z.string().optional(),
-    appSecret: z.string().optional(),
+    appSecret: buildSecretInputSchema().optional(),
     encryptKey: z.string().optional(),
-    verificationToken: z.string().optional(),
+    verificationToken: buildSecretInputSchema().optional(),
     domain: FeishuDomainSchema.optional(),
     connectionMode: FeishuConnectionModeSchema.optional(),
     webhookPath: z.string().optional(),
     ...FeishuSharedConfigShape,
+    groupSessionScope: GroupSessionScopeSchema,
+    topicSessionMode: TopicSessionModeSchema,
   })
   .strict();
 
 export const FeishuConfigSchema = z
   .object({
     enabled: z.boolean().optional(),
+    defaultAccount: z.string().optional(),
     // Top-level credentials (backward compatible for single-account mode)
     appId: z.string().optional(),
-    appSecret: z.string().optional(),
+    appSecret: buildSecretInputSchema().optional(),
     encryptKey: z.string().optional(),
-    verificationToken: z.string().optional(),
+    verificationToken: buildSecretInputSchema().optional(),
     domain: FeishuDomainSchema.optional().default("feishu"),
     connectionMode: FeishuConnectionModeSchema.optional().default("websocket"),
     webhookPath: z.string().optional().default("/feishu/events"),
     ...FeishuSharedConfigShape,
     dmPolicy: DmPolicySchema.optional().default("pairing"),
+    reactionNotifications: ReactionNotificationModeSchema.optional().default("own"),
     groupPolicy: GroupPolicySchema.optional().default("allowlist"),
     requireMention: z.boolean().optional().default(true),
+    groupSessionScope: GroupSessionScopeSchema,
     topicSessionMode: TopicSessionModeSchema,
     // Dynamic agent creation for DM users
     dynamicAgentCreation: DynamicAgentCreationSchema,
+    // Optimization flags
+    typingIndicator: z.boolean().optional().default(true),
+    resolveSenderNames: z.boolean().optional().default(true),
     // Multi-account configuration
     accounts: z.record(z.string(), FeishuAccountConfigSchema.optional()).optional(),
   })
   .strict()
   .superRefine((value, ctx) => {
+    const defaultAccount = value.defaultAccount?.trim();
+    if (defaultAccount && value.accounts && Object.keys(value.accounts).length > 0) {
+      const normalizedDefaultAccount = normalizeAccountId(defaultAccount);
+      if (!Object.prototype.hasOwnProperty.call(value.accounts, normalizedDefaultAccount)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["defaultAccount"],
+          message: `channels.feishu.defaultAccount="${defaultAccount}" does not match a configured account key`,
+        });
+      }
+    }
+
     const defaultConnectionMode = value.connectionMode ?? "websocket";
-    const defaultVerificationToken = value.verificationToken?.trim();
-    if (defaultConnectionMode === "webhook" && !defaultVerificationToken) {
+    const defaultVerificationTokenConfigured = hasConfiguredSecretInput(value.verificationToken);
+    if (defaultConnectionMode === "webhook" && !defaultVerificationTokenConfigured) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
         path: ["verificationToken"],
@@ -198,9 +253,9 @@ export const FeishuConfigSchema = z
       if (accountConnectionMode !== "webhook") {
         continue;
       }
-      const accountVerificationToken =
-        account.verificationToken?.trim() || defaultVerificationToken;
-      if (!accountVerificationToken) {
+      const accountVerificationTokenConfigured =
+        hasConfiguredSecretInput(account.verificationToken) || defaultVerificationTokenConfigured;
+      if (!accountVerificationTokenConfigured) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           path: ["accounts", accountId, "verificationToken"],

package/src/dedup.ts

@@ -1,11 +1,16 @@
 import os from "node:os";
 import path from "node:path";
-import { createDedupeCache, createPersistentDedupe } from "openclaw/plugin-sdk";
+import {
+  createDedupeCache,
+  createPersistentDedupe,
+  readJsonFileWithFallback,
+} from "openclaw/plugin-sdk";
 
 // Persistent TTL: 24 hours — survives restarts & WebSocket reconnects.
 const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
 const MEMORY_MAX_SIZE = 1_000;
 const FILE_MAX_ENTRIES = 10_000;
+type PersistentDedupeData = Record<string, number>;
 
 const memoryDedupe = createDedupeCache({ ttlMs: DEDUP_TTL_MS, maxSize: MEMORY_MAX_SIZE });
 
@@ -40,6 +45,14 @@ export function tryRecordMessage(messageId: string): boolean {
   return !memoryDedupe.check(messageId);
 }
 
+export function hasRecordedMessage(messageId: string): boolean {
+  const trimmed = messageId.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return memoryDedupe.peek(trimmed);
+}
+
 export async function tryRecordMessagePersistent(
   messageId: string,
   namespace = "global",
@@ -52,3 +65,36 @@ export async function tryRecordMessagePersistent(
     },
   });
 }
+
+export async function hasRecordedMessagePersistent(
+  messageId: string,
+  namespace = "global",
+  log?: (...args: unknown[]) => void,
+): Promise<boolean> {
+  const trimmed = messageId.trim();
+  if (!trimmed) {
+    return false;
+  }
+  const now = Date.now();
+  const filePath = resolveNamespaceFilePath(namespace);
+  try {
+    const { value } = await readJsonFileWithFallback<PersistentDedupeData>(filePath, {});
+    const seenAt = value[trimmed];
+    if (typeof seenAt !== "number" || !Number.isFinite(seenAt)) {
+      return false;
+    }
+    return DEDUP_TTL_MS <= 0 || now - seenAt < DEDUP_TTL_MS;
+  } catch (error) {
+    log?.(`feishu-dedup: persistent peek failed: ${String(error)}`);
+    return false;
+  }
+}
+
+export async function warmupDedupFromDisk(
+  namespace: string,
+  log?: (...args: unknown[]) => void,
+): Promise<number> {
+  return persistentDedupe.warmup(namespace, (error) => {
+    log?.(`feishu-dedup: warmup disk error: ${String(error)}`);
+  });
+}

package/src/doc-schema.ts

@@ -1,5 +1,19 @@
 import { Type, type Static } from "@sinclair/typebox";
 
+const tableCreationProperties = {
+  doc_token: Type.String({ description: "Document token" }),
+  parent_block_id: Type.Optional(
+    Type.String({ description: "Parent block ID (default: document root)" }),
+  ),
+  row_size: Type.Integer({ description: "Table row count", minimum: 1 }),
+  column_size: Type.Integer({ description: "Table column count", minimum: 1 }),
+  column_width: Type.Optional(
+    Type.Array(Type.Number({ minimum: 1 }), {
+      description: "Column widths in px (length should match column_size)",
+    }),
+  ),
+};
+
 export const FeishuDocSchema = Type.Union([
   Type.Object({
     action: Type.Literal("read"),
@@ -17,10 +31,24 @@ export const FeishuDocSchema = Type.Union([
     doc_token: Type.String({ description: "Document token" }),
     content: Type.String({ description: "Markdown content to append to end of document" }),
   }),
+  Type.Object({
+    action: Type.Literal("insert"),
+    doc_token: Type.String({ description: "Document token" }),
+    content: Type.String({ description: "Markdown content to insert" }),
+    after_block_id: Type.String({
+      description: "Insert content after this block ID. Use list_blocks to find block IDs.",
+    }),
+  }),
   Type.Object({
     action: Type.Literal("create"),
     title: Type.String({ description: "Document title" }),
     folder_token: Type.Optional(Type.String({ description: "Target folder token (optional)" })),
+    grant_to_requester: Type.Optional(
+      Type.Boolean({
+        description:
+          "Grant edit permission to the trusted requesting Feishu user from runtime context (default: true).",
+      }),
+    ),
   }),
   Type.Object({
     action: Type.Literal("list_blocks"),
@@ -42,6 +70,113 @@ export const FeishuDocSchema = Type.Union([
     doc_token: Type.String({ description: "Document token" }),
     block_id: Type.String({ description: "Block ID" }),
   }),
+  // Table creation (explicit structure)
+  Type.Object({
+    action: Type.Literal("create_table"),
+    ...tableCreationProperties,
+  }),
+  Type.Object({
+    action: Type.Literal("write_table_cells"),
+    doc_token: Type.String({ description: "Document token" }),
+    table_block_id: Type.String({ description: "Table block ID" }),
+    values: Type.Array(Type.Array(Type.String()), {
+      description: "2D matrix values[row][col] to write into table cells",
+      minItems: 1,
+    }),
+  }),
+  Type.Object({
+    action: Type.Literal("create_table_with_values"),
+    ...tableCreationProperties,
+    values: Type.Array(Type.Array(Type.String()), {
+      description: "2D matrix values[row][col] to write into table cells",
+      minItems: 1,
+    }),
+  }),
+  // Table row/column manipulation
+  Type.Object({
+    action: Type.Literal("insert_table_row"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_index: Type.Optional(
+      Type.Number({ description: "Row index to insert at (-1 for end, default: -1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("insert_table_column"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    column_index: Type.Optional(
+      Type.Number({ description: "Column index to insert at (-1 for end, default: -1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_table_rows"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_start: Type.Number({ description: "Start row index (0-based)" }),
+    row_count: Type.Optional(Type.Number({ description: "Number of rows to delete (default: 1)" })),
+  }),
+  Type.Object({
+    action: Type.Literal("delete_table_columns"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    column_start: Type.Number({ description: "Start column index (0-based)" }),
+    column_count: Type.Optional(
+      Type.Number({ description: "Number of columns to delete (default: 1)" }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("merge_table_cells"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Table block ID" }),
+    row_start: Type.Number({ description: "Start row index" }),
+    row_end: Type.Number({ description: "End row index (exclusive)" }),
+    column_start: Type.Number({ description: "Start column index" }),
+    column_end: Type.Number({ description: "End column index (exclusive)" }),
+  }),
+  // Image / file upload
+  Type.Object({
+    action: Type.Literal("upload_image"),
+    doc_token: Type.String({ description: "Document token" }),
+    url: Type.Optional(Type.String({ description: "Remote image URL (http/https)" })),
+    file_path: Type.Optional(Type.String({ description: "Local image file path" })),
+    image: Type.Optional(
+      Type.String({
+        description:
+          "Image as data URI (data:image/png;base64,...) or plain base64 string. Use instead of url/file_path for DALL-E outputs, canvas screenshots, etc.",
+      }),
+    ),
+    parent_block_id: Type.Optional(
+      Type.String({ description: "Parent block ID (default: document root)" }),
+    ),
+    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
+    index: Type.Optional(
+      Type.Integer({
+        minimum: 0,
+        description: "Insert position (0-based index among siblings). Omit to append.",
+      }),
+    ),
+  }),
+  Type.Object({
+    action: Type.Literal("upload_file"),
+    doc_token: Type.String({ description: "Document token" }),
+    url: Type.Optional(Type.String({ description: "Remote file URL (http/https)" })),
+    file_path: Type.Optional(Type.String({ description: "Local file path" })),
+    parent_block_id: Type.Optional(
+      Type.String({ description: "Parent block ID (default: document root)" }),
+    ),
+    filename: Type.Optional(Type.String({ description: "Optional filename override" })),
+  }),
+  // Text color / style
+  Type.Object({
+    action: Type.Literal("color_text"),
+    doc_token: Type.String({ description: "Document token" }),
+    block_id: Type.String({ description: "Text block ID to update" }),
+    content: Type.String({
+      description:
+        'Text with color markup. Tags: [red], [green], [blue], [orange], [yellow], [purple], [grey], [bold], [bg:yellow]. Example: "Revenue [green]+15%[/green] YoY"',
+    }),
+  }),
 ]);
 
 export type FeishuDocParams = Static<typeof FeishuDocSchema>;

package/src/docx-batch-insert.ts

@@ -0,0 +1,190 @@
+/**
+ * Batch insertion for large Feishu documents (>1000 blocks).
+ *
+ * The Feishu Descendant API has a limit of 1000 blocks per request.
+ * This module handles splitting large documents into batches while
+ * preserving parent-child relationships between blocks.
+ */
+
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { cleanBlocksForDescendant } from "./docx-table-ops.js";
+
+export const BATCH_SIZE = 1000; // Feishu API limit per request
+
+type Logger = { info?: (msg: string) => void };
+
+/**
+ * Collect all descendant blocks for a given set of first-level block IDs.
+ * Recursively traverses the block tree to gather all children.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+function collectDescendants(blocks: any[], firstLevelIds: string[]): any[] {
+  const blockMap = new Map<string, any>();
+  for (const block of blocks) {
+    blockMap.set(block.block_id, block);
+  }
+
+  const result: any[] = [];
+  const visited = new Set<string>();
+
+  function collect(blockId: string) {
+    if (visited.has(blockId)) return;
+    visited.add(blockId);
+
+    const block = blockMap.get(blockId);
+    if (!block) return;
+
+    result.push(block);
+
+    // Recursively collect children
+    const children = block.children;
+    if (Array.isArray(children)) {
+      for (const childId of children) {
+        collect(childId);
+      }
+    } else if (typeof children === "string") {
+      collect(children);
+    }
+  }
+
+  for (const id of firstLevelIds) {
+    collect(id);
+  }
+
+  return result;
+}
+
+/**
+ * Insert a single batch of blocks using Descendant API.
+ *
+ * @param parentBlockId - Parent block to insert into (defaults to docToken)
+ * @param index - Position within parent's children (-1 = end)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+async function insertBatch(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  firstLevelBlockIds: string[],
+  parentBlockId: string = docToken,
+  index: number = -1,
+): Promise<any[]> {
+  const descendants = cleanBlocksForDescendant(blocks);
+
+  if (descendants.length === 0) {
+    return [];
+  }
+
+  const res = await client.docx.documentBlockDescendant.create({
+    path: { document_id: docToken, block_id: parentBlockId },
+    data: {
+      children_id: firstLevelBlockIds,
+      descendants,
+      index,
+    },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(`${res.msg} (code: ${res.code})`);
+  }
+
+  return res.data?.children ?? [];
+}
+
+/**
+ * Insert blocks in batches for large documents (>1000 blocks).
+ *
+ * Batches are split to ensure BOTH children_id AND descendants
+ * arrays stay under the 1000 block API limit.
+ *
+ * @param client - Feishu API client
+ * @param docToken - Document ID
+ * @param blocks - All blocks from Convert API
+ * @param firstLevelBlockIds - IDs of top-level blocks to insert
+ * @param logger - Optional logger for progress updates
+ * @param parentBlockId - Parent block to insert into (defaults to docToken = document root)
+ * @param startIndex - Starting position within parent (-1 = end). For multi-batch inserts,
+ *   each batch advances this by the number of first-level IDs inserted so far.
+ * @returns Inserted children blocks and any skipped block IDs
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK block types
+export async function insertBlocksInBatches(
+  client: Lark.Client,
+  docToken: string,
+  blocks: any[],
+  firstLevelBlockIds: string[],
+  logger?: Logger,
+  parentBlockId: string = docToken,
+  startIndex: number = -1,
+): Promise<{ children: any[]; skipped: string[] }> {
+  const allChildren: any[] = [];
+
+  // Build batches ensuring each batch has ≤1000 total descendants
+  const batches: { firstLevelIds: string[]; blocks: any[] }[] = [];
+  let currentBatch: { firstLevelIds: string[]; blocks: any[] } = { firstLevelIds: [], blocks: [] };
+  const usedBlockIds = new Set<string>();
+
+  for (const firstLevelId of firstLevelBlockIds) {
+    const descendants = collectDescendants(blocks, [firstLevelId]);
+    const newBlocks = descendants.filter((b) => !usedBlockIds.has(b.block_id));
+
+    // A single block whose subtree exceeds the API limit cannot be split
+    // (a table or other compound block must be inserted atomically).
+    if (newBlocks.length > BATCH_SIZE) {
+      throw new Error(
+        `Block "${firstLevelId}" has ${newBlocks.length} descendants, which exceeds the ` +
+          `Feishu API limit of ${BATCH_SIZE} blocks per request. ` +
+          `Please split the content into smaller sections.`,
+      );
+    }
+
+    // If adding this first-level block would exceed limit, start new batch
+    if (
+      currentBatch.blocks.length + newBlocks.length > BATCH_SIZE &&
+      currentBatch.blocks.length > 0
+    ) {
+      batches.push(currentBatch);
+      currentBatch = { firstLevelIds: [], blocks: [] };
+    }
+
+    // Add to current batch
+    currentBatch.firstLevelIds.push(firstLevelId);
+    for (const block of newBlocks) {
+      currentBatch.blocks.push(block);
+      usedBlockIds.add(block.block_id);
+    }
+  }
+
+  // Don't forget the last batch
+  if (currentBatch.blocks.length > 0) {
+    batches.push(currentBatch);
+  }
+
+  // Insert each batch, advancing index for position-aware inserts.
+  // When startIndex == -1 (append to end), each batch appends after the previous.
+  // When startIndex >= 0, each batch starts at startIndex + count of first-level IDs already inserted.
+  let currentIndex = startIndex;
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    logger?.info?.(
+      `feishu_doc: Inserting batch ${i + 1}/${batches.length} (${batch.blocks.length} blocks)...`,
+    );
+
+    const children = await insertBatch(
+      client,
+      docToken,
+      batch.blocks,
+      batch.firstLevelIds,
+      parentBlockId,
+      currentIndex,
+    );
+    allChildren.push(...children);
+
+    // Advance index only for explicit positions; -1 always means "after last inserted"
+    if (currentIndex !== -1) {
+      currentIndex += batch.firstLevelIds.length;
+    }
+  }
+
+  return { children: allChildren, skipped: [] };
+}