Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/feishu/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 "openclaw/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: [] };
+}