@openclaw/feishu 2026.2.24 → 2026.3.1

package/src/config-schema.ts

@@ -1,3 +1,4 @@
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import { z } from "zod";
 export { z };
 
@@ -82,6 +83,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 +93,36 @@ 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.
  */
 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 +132,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 +148,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 +162,10 @@ const FeishuSharedConfigShape = {
   renderMode: RenderModeSchema,
   streaming: StreamingModeSchema,
   tools: FeishuToolsConfigSchema,
+  replyInThread: ReplyInThreadSchema,
+  reactionNotifications: ReactionNotificationModeSchema,
+  typingIndicator: z.boolean().optional(),
+  resolveSenderNames: z.boolean().optional(),
 };
 
 /**
@@ -153,12 +184,15 @@ export const FeishuAccountConfigSchema = z
     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(),
@@ -169,16 +203,33 @@ export const FeishuConfigSchema = z
     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) {

package/src/doc-schema.ts

@@ -17,10 +17,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 +56,133 @@ 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"),
+    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)",
+      }),
+    ),
+  }),
+  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"),
+    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)",
+      }),
+    ),
+    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: [] };
+}

package/src/docx-color-text.ts

@@ -0,0 +1,149 @@
+/**
+ * Colored text support for Feishu documents.
+ *
+ * Parses a simple color markup syntax and updates a text block
+ * with native Feishu text_run color styles.
+ *
+ * Syntax: [color]text[/color]
+ * Supported colors: red, orange, yellow, green, blue, purple, grey
+ *
+ * Example:
+ *   "Revenue [green]+15%[/green] YoY, Costs [red]-3%[/red]"
+ */
+
+import type * as Lark from "@larksuiteoapi/node-sdk";
+
+// Feishu text_color values (1-7)
+const TEXT_COLOR: Record<string, number> = {
+  red: 1, // Pink (closest to red in Feishu)
+  orange: 2,
+  yellow: 3,
+  green: 4,
+  blue: 5,
+  purple: 6,
+  grey: 7,
+  gray: 7,
+};
+
+// Feishu background_color values (1-15)
+const BACKGROUND_COLOR: Record<string, number> = {
+  red: 1,
+  orange: 2,
+  yellow: 3,
+  green: 4,
+  blue: 5,
+  purple: 6,
+  grey: 7,
+  gray: 7,
+};
+
+interface Segment {
+  text: string;
+  textColor?: number;
+  bgColor?: number;
+  bold?: boolean;
+}
+
+/**
+ * Parse color markup into segments.
+ *
+ * Supports:
+ *   [red]text[/red]               → red text
+ *   [bg:yellow]text[/bg]          → yellow background
+ *   [bold]text[/bold]             → bold
+ *   [green bold]text[/green]      → green + bold
+ */
+export function parseColorMarkup(content: string): Segment[] {
+  const segments: Segment[] = [];
+  // Only [known_tag]...[/...] pairs are treated as markup.  Using an open
+  // pattern like \[([^\]]+)\] would match any bracket token — e.g. [Q1] —
+  // and cause it to consume a later real closing tag ([/red]), silently
+  // corrupting the surrounding styled spans.  Restricting the opening tag to
+  // the set of recognised colour/style names prevents that: [Q1] does not
+  // match the tag alternative and each of its characters falls through to the
+  // plain-text alternatives instead.
+  //
+  // Closing tag name is still not validated against the opening tag:
+  // [red]text[/green] is treated as [red]text[/red] — opening style applies
+  // and the closing tag is consumed regardless of its name.
+  const KNOWN = "(?:bg:[a-z]+|bold|red|orange|yellow|green|blue|purple|gr[ae]y)";
+  const tagPattern = new RegExp(
+    `\\[(${KNOWN}(?:\\s+${KNOWN})*)\\](.*?)\\[\\/(?:[^\\]]+)\\]|([^[]+|\\[)`,
+    "gis",
+  );
+  let match;
+
+  while ((match = tagPattern.exec(content)) !== null) {
+    if (match[3] !== undefined) {
+      // Plain text segment
+      if (match[3]) {
+        segments.push({ text: match[3] });
+      }
+    } else {
+      // Tagged segment
+      const tagStr = match[1].toLowerCase().trim();
+      const text = match[2];
+      const tags = tagStr.split(/\s+/);
+
+      const segment: Segment = { text };
+
+      for (const tag of tags) {
+        if (tag.startsWith("bg:")) {
+          const color = tag.slice(3);
+          if (BACKGROUND_COLOR[color]) {
+            segment.bgColor = BACKGROUND_COLOR[color];
+          }
+        } else if (tag === "bold") {
+          segment.bold = true;
+        } else if (TEXT_COLOR[tag]) {
+          segment.textColor = TEXT_COLOR[tag];
+        }
+      }
+
+      if (text) {
+        segments.push(segment);
+      }
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Update a text block with colored segments.
+ */
+export async function updateColorText(
+  client: Lark.Client,
+  docToken: string,
+  blockId: string,
+  content: string,
+) {
+  const segments = parseColorMarkup(content);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK type
+  const elements: any[] = segments.map((seg) => ({
+    text_run: {
+      content: seg.text,
+      text_element_style: {
+        ...(seg.textColor && { text_color: seg.textColor }),
+        ...(seg.bgColor && { background_color: seg.bgColor }),
+        ...(seg.bold && { bold: true }),
+      },
+    },
+  }));
+
+  const res = await client.docx.documentBlock.patch({
+    path: { document_id: docToken, block_id: blockId },
+    data: { update_text_elements: { elements } },
+  });
+
+  if (res.code !== 0) {
+    throw new Error(res.msg);
+  }
+
+  return {
+    success: true,
+    segments: segments.length,
+    block: res.data?.block,
+  };
+}