@actagent/feishu 2026.6.2

package/src/docx-batch-insert.test.ts

@@ -0,0 +1,117 @@
+// Feishu tests cover docx batch insert plugin behavior.
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { BATCH_SIZE, insertBlocksInBatches } from "./docx-batch-insert.js";
+import type { FeishuDocxBlock } from "./docx-types.js";
+
+type InsertBlocksClient = Parameters<typeof insertBlocksInBatches>[0];
+type DocxDescendantCreate = Lark.Client["docx"]["documentBlockDescendant"]["create"];
+type DocxDescendantCreateParams = Parameters<DocxDescendantCreate>[0];
+type DocxDescendantCreateResponse = Awaited<ReturnType<DocxDescendantCreate>>;
+type RequiredDocxDescendantCreateParams = NonNullable<DocxDescendantCreateParams> & {
+  data: NonNullable<NonNullable<DocxDescendantCreateParams>["data"]>;
+};
+
+function createDocxDescendantClient(create: DocxDescendantCreate): InsertBlocksClient {
+  return {
+    docx: {
+      documentBlockDescendant: {
+        create,
+      },
+    },
+  } as InsertBlocksClient;
+}
+
+function createCountingIterable<T>(values: T[]) {
+  let iterations = 0;
+  return {
+    values: {
+      *[Symbol.iterator]() {
+        iterations += 1;
+        yield* values;
+      },
+    },
+    getIterations: () => iterations,
+  };
+}
+
+function createSuccessfulDocxDescendantCreateMock() {
+  return vi.fn(
+    async (params?: DocxDescendantCreateParams): Promise<DocxDescendantCreateResponse> => ({
+      code: 0,
+      data: {
+        children: (params?.data?.children_id ?? []).map((id) => ({
+          block_id: id,
+          block_type: 2,
+        })),
+      },
+    }),
+  );
+}
+
+function createCallParams(
+  createMock: ReturnType<typeof createSuccessfulDocxDescendantCreateMock>,
+  index = 0,
+): RequiredDocxDescendantCreateParams {
+  const call = createMock.mock.calls.at(index);
+  if (!call) {
+    throw new Error(`Expected DOCX descendant create call ${index}`);
+  }
+  const params = call.at(0);
+  if (!params) {
+    throw new Error(`Expected DOCX descendant create params ${index}`);
+  }
+  if (!params.data) {
+    throw new Error(`Expected DOCX descendant create data ${index}`);
+  }
+  return params as RequiredDocxDescendantCreateParams;
+}
+
+describe("insertBlocksInBatches", () => {
+  it("builds the source block map once for large flat trees", async () => {
+    const blockCount = BATCH_SIZE + 200;
+    const blocks = Array.from({ length: blockCount }, (_, index) => ({
+      block_id: `block_${index}`,
+      block_type: 2,
+    }));
+    const counting = createCountingIterable(blocks);
+    const createMock = createSuccessfulDocxDescendantCreateMock();
+    const client = createDocxDescendantClient((params) => createMock(params));
+
+    const result = await insertBlocksInBatches(
+      client,
+      "doc_1",
+      Array.from(counting.values),
+      blocks.map((block) => block.block_id),
+    );
+
+    expect(counting.getIterations()).toBe(1);
+    expect(createMock).toHaveBeenCalledTimes(2);
+    expect(createCallParams(createMock).data.children_id).toHaveLength(BATCH_SIZE);
+    expect(createCallParams(createMock, 1).data.children_id).toHaveLength(200);
+    expect(result.children).toHaveLength(blockCount);
+  });
+
+  it("keeps nested descendants grouped with their root blocks", async () => {
+    const createMock = createSuccessfulDocxDescendantCreateMock();
+    const client = createDocxDescendantClient((params) => createMock(params));
+    const blocks: FeishuDocxBlock[] = [
+      { block_id: "root_a", block_type: 1, children: ["child_a"] },
+      { block_id: "child_a", block_type: 2 },
+      { block_id: "root_b", block_type: 1, children: ["child_b"] },
+      { block_id: "child_b", block_type: 2 },
+    ];
+
+    await insertBlocksInBatches(client, "doc_1", blocks, ["root_a", "root_b"]);
+
+    expect(createMock).toHaveBeenCalledTimes(1);
+    const createParams = createCallParams(createMock);
+    expect(createParams.data.children_id).toEqual(["root_a", "root_b"]);
+    expect(createParams.data.descendants.map((block) => block.block_id ?? "")).toEqual([
+      "root_a",
+      "child_a",
+      "root_b",
+      "child_b",
+    ]);
+  });
+});

package/src/docx-batch-insert.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 { readStringValue } from "actagent/plugin-sdk/string-coerce-runtime";
+import { cleanBlocksForDescendant } from "./docx-table-ops.js";
+import type { FeishuDocxBlock, FeishuDocxBlockChild } from "./docx-types.js";
+
+export const BATCH_SIZE = 1000; // Feishu API limit per request
+
+type Logger = { info?: (msg: string) => void };
+
+type DocxDescendantCreatePayload = NonNullable<
+  Parameters<Lark.Client["docx"]["documentBlockDescendant"]["create"]>[0]
+>;
+type DocxDescendantCreateBlock = NonNullable<
+  NonNullable<DocxDescendantCreatePayload["data"]>["descendants"]
+>[number];
+
+function normalizeChildIds(children: string[] | string | undefined): string[] | undefined {
+  if (Array.isArray(children)) {
+    return children;
+  }
+  const child = readStringValue(children);
+  return child ? [child] : undefined;
+}
+
+function toDescendantBlock(block: FeishuDocxBlock): DocxDescendantCreateBlock {
+  const children = normalizeChildIds(block.children);
+  return {
+    ...block,
+    ...(children ? { children } : {}),
+  } as DocxDescendantCreateBlock;
+}
+
+/**
+ * Collect all descendant blocks for a given first-level block ID.
+ * Recursively traverses the block tree to gather all children.
+ */
+function collectDescendants(
+  blockMap: Map<string, FeishuDocxBlock>,
+  rootId: string,
+): FeishuDocxBlock[] {
+  const result: FeishuDocxBlock[] = [];
+  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);
+    }
+  }
+
+  collect(rootId);
+
+  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)
+ */
+async function insertBatch(
+  client: Lark.Client,
+  docToken: string,
+  blocks: FeishuDocxBlock[],
+  firstLevelBlockIds: string[],
+  parentBlockId: string = docToken,
+  index = -1,
+): Promise<FeishuDocxBlockChild[]> {
+  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: descendants.map(toDescendantBlock),
+      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
+ */
+export async function insertBlocksInBatches(
+  client: Lark.Client,
+  docToken: string,
+  blocks: FeishuDocxBlock[],
+  firstLevelBlockIds: string[],
+  logger?: Logger,
+  parentBlockId: string = docToken,
+  startIndex = -1,
+): Promise<{ children: FeishuDocxBlockChild[]; skipped: string[] }> {
+  const allChildren: FeishuDocxBlockChild[] = [];
+
+  // Build batches ensuring each batch has ≤1000 total descendants
+  const batches: Array<{ firstLevelIds: string[]; blocks: FeishuDocxBlock[] }> = [];
+  let currentBatch: { firstLevelIds: string[]; blocks: FeishuDocxBlock[] } = {
+    firstLevelIds: [],
+    blocks: [],
+  };
+  const usedBlockIds = new Set<string>();
+  const blockMap = new Map<string, FeishuDocxBlock>();
+  for (const block of blocks) {
+    if (block.block_id) {
+      blockMap.set(block.block_id, block);
+    }
+  }
+
+  for (const firstLevelId of firstLevelBlockIds) {
+    const descendants = collectDescendants(blockMap, firstLevelId);
+    const newBlocks = descendants.filter((b) => b.block_id && !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);
+      if (block.block_id) {
+        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,154 @@
+/**
+ * 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";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+
+// 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;
+}
+
+type DocxPatchPayload = NonNullable<Parameters<Lark.Client["docx"]["documentBlock"]["patch"]>[0]>;
+type DocxTextElement = NonNullable<
+  NonNullable<NonNullable<DocxPatchPayload["data"]>["update_text_elements"]>["elements"]
+>[number];
+
+/**
+ * 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
+ */
+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 = normalizeLowercaseStringOrEmpty(match[1]);
+      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);
+
+  const elements: DocxTextElement[] = 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,
+  };
+}

package/src/docx-table-ops.test.ts

@@ -0,0 +1,54 @@
+// Feishu tests cover docx table ops plugin behavior.
+import { describe, expect, it } from "vitest";
+import { cleanBlocksForDescendant } from "./docx-table-ops.js";
+
+describe("cleanBlocksForDescendant", () => {
+  it("removes parent links and read-only table fields while normalizing table cells", () => {
+    const blocks = [
+      {
+        block_id: "table-1",
+        parent_id: "parent-1",
+        block_type: 31,
+        children: "cell-1",
+        table: {
+          property: {
+            row_size: 1,
+            column_size: 1,
+            column_width: [240],
+          },
+          cells: ["cell-1"],
+          merge_info: [{ row_span: 1, col_span: 1 }],
+        },
+      },
+      {
+        block_id: "cell-1",
+        parent_id: "table-1",
+        block_type: 32,
+        children: "text-1",
+      },
+      {
+        block_id: "text-1",
+        parent_id: "cell-1",
+        block_type: 2,
+        text: {
+          elements: [{ text_run: { content: "hello" } }],
+        },
+      },
+    ];
+
+    const cleaned = cleanBlocksForDescendant(blocks);
+
+    expect(cleaned[0]).not.toHaveProperty("parent_id");
+    expect(cleaned[1]).not.toHaveProperty("parent_id");
+    expect(cleaned[2]).not.toHaveProperty("parent_id");
+
+    expect(cleaned[0]?.table).toEqual({
+      property: {
+        row_size: 1,
+        column_size: 1,
+        column_width: [240],
+      },
+    });
+    expect(cleaned[1]?.children).toEqual(["text-1"]);
+  });
+});