@max1874/feishu 0.2.16 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max1874/feishu",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "type": "module",
   "description": "OpenClaw Feishu/Lark channel plugin",
   "license": "MIT",
@@ -47,6 +47,7 @@
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.30.0",
     "@sinclair/typebox": "^0.34.48",
+    "marked": "^15.0.12",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/docx.ts

@@ -4,6 +4,13 @@ import { createFeishuClient } from "./client.js";
 import type { FeishuConfig } from "./types.js";
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import { Readable } from "stream";
+import {
+  markdownToFeishuBlocks,
+  prepareBlocksForApi,
+  TablePlaceholder,
+  type FeishuBlock,
+  type ContentItem,
+} from "./feishu-renderer.js";
 
 // ============ Helpers ============
 
@@ -43,59 +50,6 @@ function extractImageUrls(markdown: string): string[] {
   return urls;
 }
 
-/** Extract text content from a block for sorting */
-function extractBlockText(block: any): string {
-  const elements =
-    block.text?.elements ??
-    block.heading1?.elements ??
-    block.heading2?.elements ??
-    block.heading3?.elements ??
-    block.bullet?.elements ??
-    block.ordered?.elements ??
-    block.quote?.elements ??
-    block.todo?.elements ??
-    [];
-  return elements
-    .filter((e: any) => e.text_run)
-    .map((e: any) => e.text_run.content)
-    .join("");
-}
-
-/**
- * Sort blocks by their position in firstLevelBlockIds.
- * The Convert API returns blocks in arbitrary order, but provides
- * first_level_block_ids in the correct document order.
- */
-function sortBlocksByFirstLevelIds(blocks: any[], firstLevelBlockIds: string[]): any[] {
-  // Build a map of block_id -> block
-  const blockMap = new Map<string, any>();
-  for (const block of blocks) {
-    if (block.block_id) {
-      blockMap.set(block.block_id, block);
-    }
-  }
-
-  // Reorder blocks according to firstLevelBlockIds
-  const sortedBlocks: any[] = [];
-  const usedIds = new Set<string>();
-
-  for (const id of firstLevelBlockIds) {
-    const block = blockMap.get(id);
-    if (block) {
-      sortedBlocks.push(block);
-      usedIds.add(id);
-    }
-  }
-
-  // Append any remaining blocks (e.g., child blocks like TableCell)
-  for (const block of blocks) {
-    if (block.block_id && !usedIds.has(block.block_id)) {
-      sortedBlocks.push(block);
-    }
-  }
-
-  return sortedBlocks;
-}
 
 const BLOCK_TYPE_NAMES: Record<number, string> = {
   1: "Page",
@@ -118,459 +72,150 @@ const BLOCK_TYPE_NAMES: Record<number, string> = {
   32: "TableCell",
 };
 
-// Block types that need special handling (not via standard documentBlockChildren.create)
+// Block types
 const TABLE_BLOCK_TYPE = 31;
-const TABLE_CELL_BLOCK_TYPE = 32;
-
-/** Extracted table data from convert API result */
-interface TableData {
-  rowSize: number;
-  colSize: number;
-  cells: string[][]; // 2D array of cell text content
-}
-
-/** A content item that can be either a regular block or a table */
-type ContentItem =
-  | { type: "block"; block: any }
-  | { type: "table"; table: TableData };
-
-/** Extract table data from a table block */
-function extractTableData(tableBlock: any, blockMap: Map<string, any>): { tableData: TableData; relatedIds: Set<string> } {
-  const relatedIds = new Set<string>();
-  relatedIds.add(tableBlock.block_id);
-
-  const tableInfo = tableBlock.table;
-  const rowSize = tableInfo?.property?.row_size ?? 0;
-  const colSize = tableInfo?.property?.column_size ?? 0;
-
-  const cells: string[][] = Array.from({ length: rowSize }, () =>
-    Array.from({ length: colSize }, () => ""),
-  );
-
-  const cellIds: string[] = tableInfo?.cells ?? [];
-  let cellIndex = 0;
-
-  for (let row = 0; row < rowSize; row++) {
-    for (let col = 0; col < colSize; col++) {
-      if (cellIndex >= cellIds.length) break;
-
-      const cellId = cellIds[cellIndex];
-      relatedIds.add(cellId);
-
-      const cellBlock = blockMap.get(cellId);
-      if (cellBlock?.block_type === TABLE_CELL_BLOCK_TYPE) {
-        const childIds: string[] = cellBlock.children ?? [];
-        const textParts: string[] = [];
-
-        for (const childId of childIds) {
-          relatedIds.add(childId);
-          const textBlock = blockMap.get(childId);
-          if (textBlock?.block_type === 2 && textBlock.text?.elements) {
-            const text = textBlock.text.elements
-              .filter((e: any) => e.text_run)
-              .map((e: any) => e.text_run.content)
-              .join("");
-            textParts.push(text);
-          }
-        }
-
-        cells[row][col] = textParts.join("\n");
-      }
-
-      cellIndex++;
-    }
-  }
-
-  return { tableData: { rowSize, colSize, cells }, relatedIds };
-}
-
-/** Convert blocks to content items, preserving order with tables in correct positions */
-function convertBlocksToContentItems(blocks: any[]): ContentItem[] {
-  const blockMap = new Map<string, any>();
-  for (const block of blocks) {
-    if (block.block_id) {
-      blockMap.set(block.block_id, block);
-    }
-  }
-
-  // Track which blocks are part of tables
-  const tableRelatedIds = new Set<string>();
-  const tableDataMap = new Map<string, TableData>();
-
-  // First pass: extract all table data and mark related IDs
-  for (const block of blocks) {
-    if (block.block_type === TABLE_BLOCK_TYPE) {
-      const { tableData, relatedIds } = extractTableData(block, blockMap);
-      tableDataMap.set(block.block_id, tableData);
-      for (const id of relatedIds) {
-        tableRelatedIds.add(id);
-      }
-    }
-  }
-
-  // Second pass: build content items in order
-  const items: ContentItem[] = [];
-  for (const block of blocks) {
-    if (tableRelatedIds.has(block.block_id)) {
-      // If this is a table block itself, add the table item
-      if (block.block_type === TABLE_BLOCK_TYPE) {
-        const tableData = tableDataMap.get(block.block_id);
-        if (tableData) {
-          items.push({ type: "table", table: tableData });
-        }
-      }
-      // Skip table-related blocks (cells, cell contents)
-    } else {
-      items.push({ type: "block", block });
-    }
-  }
-
-  return items;
-}
-
-/** Extract table data from converted blocks (flat list with ID references) - legacy function */
-function extractTableFromBlocks(blocks: any[]): { tables: TableData[]; otherBlocks: any[] } {
-  const items = convertBlocksToContentItems(blocks);
-  const tables: TableData[] = [];
-  const otherBlocks: any[] = [];
-
-  for (const item of items) {
-    if (item.type === "table") {
-      tables.push(item.table);
-    } else {
-      otherBlocks.push(item.block);
-    }
-  }
 
-  return { tables, otherBlocks };
-}
+// ============ Helpers for New Implementation ============
 
-/** Clean blocks for insertion (remove read-only fields and unsupported nested structures) */
-function cleanBlocksForInsert(blocks: any[]): { cleaned: any[]; skipped: string[] } {
-  const skipped: string[] = [];
-  const cleaned = blocks.map((block) => {
-    const { children, parent_id, block_id, ...rest } = block;
-
-    // Remove children from non-table blocks (nested lists not supported in create API)
-    // Table children are handled separately via table.cells
-    if (block.block_type === TABLE_BLOCK_TYPE && block.table?.merge_info) {
-      const { merge_info, ...tableRest } = block.table;
-      return { ...rest, table: tableRest };
-    }
+/** Delay helper for rate limiting */
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-    return rest;
-  });
-  return { cleaned, skipped };
+/** Generate unique block ID */
+let blockIdCounter = 0;
+function generateBlockId(): string {
+  blockIdCounter++;
+  return `tmp_${Date.now()}_${blockIdCounter}`;
 }
 
-// ============ Helpers for Recursive Insert ============
-
-/** Delay helper for rate limiting */
-const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
-
-/** API call with retry for rate limiting */
-async function createChildrenWithRetry(
+/**
+ * Create nested blocks using the descendant API.
+ * This allows creating complex structures like tables in a single API call.
+ */
+async function createNestedBlocks(
   client: Lark.Client,
   docToken: string,
   parentBlockId: string,
-  children: any[],
+  childrenIds: string[],
+  descendants: any[],
   index?: number,
-  retries = 3
-): Promise<any> {
-  for (let i = 0; i < retries; i++) {
-    try {
-      const res = await client.docx.documentBlockChildren.create({
-        path: { document_id: docToken, block_id: parentBlockId },
-        data: {
-          children,
-          ...(index !== undefined && { index })
-        },
-      });
-      if (res.code === 0) return res;
-      // Rate limit error
-      if (res.code === 99991400 || res.msg?.includes('rate')) {
-        await delay((i + 1) * 2000);
-        continue;
-      }
-      return res;
-    } catch (e: any) {
-      if (e.message?.includes('429') || e.response?.status === 429) {
-        await delay((i + 1) * 2000);
-        continue;
-      }
-      throw e;
-    }
-  }
-  return { code: -1, msg: 'Max retries exceeded' };
-}
-
-/** Context for recursive block insertion */
-interface InsertContext {
-  client: Lark.Client;
-  docToken: string;
-  blockMap: Map<string, any>;
-  tableRelatedIds: Set<string>;
-  tableDataMap: Map<string, TableData>;
-  insertedCount: number;
-  tablesCreated: number;
-}
-
-/** Recursively insert a block and its children */
-async function insertBlockWithChildren(
-  ctx: InsertContext,
-  block: any,
-  parentBlockId: string,
-  index?: number
-): Promise<string | null> {
-  // Skip table-related blocks (handled separately)
-  if (ctx.tableRelatedIds.has(block.block_id)) {
-    if (block.block_type === TABLE_BLOCK_TYPE) {
-      const tableData = ctx.tableDataMap.get(block.block_id);
-      if (tableData) {
-        return await createTableWithRetry(ctx, parentBlockId, tableData, index);
-      }
-    }
-    return null;
-  }
-
-  // Clean block (remove read-only fields but preserve children reference)
-  const { block_id, parent_id, children, ...cleanBlock } = block;
-
-  // Add delay to avoid rate limiting
-  await delay(100);
-
-  // Insert current block
-  const insertRes = await createChildrenWithRetry(
-    ctx.client,
-    ctx.docToken,
-    parentBlockId,
-    [cleanBlock],
-    index
-  );
-
-  if (insertRes.code !== 0) {
-    console.error(`Failed to insert block: ${insertRes.msg}`);
-    return null;
-  }
-
-  const newBlockId = insertRes.data?.children?.[0]?.block_id;
-  if (!newBlockId) return null;
-
-  ctx.insertedCount++;
-
-  // Recursively insert children
-  if (children && children.length > 0) {
-    for (let i = 0; i < children.length; i++) {
-      const childId = children[i];
-      const childBlock = ctx.blockMap.get(childId);
-      if (childBlock) {
-        await insertBlockWithChildren(ctx, childBlock, newBlockId, i);
-      }
-    }
-  }
-
-  return newBlockId;
-}
-
-/** Create and fill a table with retry */
-async function createTableWithRetry(
-  ctx: InsertContext,
-  parentBlockId: string,
-  tableData: TableData,
-  index?: number
-): Promise<string | null> {
-  await delay(100);
-
-  const createRes = await createChildrenWithRetry(
-    ctx.client,
-    ctx.docToken,
-    parentBlockId,
-    [{
-      block_type: TABLE_BLOCK_TYPE,
-      table: {
-        property: { row_size: tableData.rowSize, column_size: tableData.colSize, header_row: true },
-        cells: []
-      }
-    }],
-    index
-  );
-
-  if (createRes.code !== 0) {
-    console.error(`Failed to create table: ${createRes.msg}`);
-    return null;
-  }
-
-  const tableBlockId = createRes.data?.children?.[0]?.block_id;
-  if (!tableBlockId) return null;
-
-  // Fill table content
-  const cellBlocksRes = await ctx.client.docx.documentBlockChildren.get({
-    path: { document_id: ctx.docToken, block_id: tableBlockId },
+): Promise<void> {
+  const res = await client.docx.documentBlockDescendant.create({
+    path: { document_id: docToken, block_id: parentBlockId },
+    data: {
+      children_id: childrenIds,
+      descendants,
+      ...(index !== undefined && { index }),
+    },
   });
-  const cellBlocks = cellBlocksRes.data?.items ?? [];
-
-  let cellIndex = 0;
-  for (let row = 0; row < tableData.rowSize; row++) {
-    for (let col = 0; col < tableData.colSize; col++) {
-      if (cellIndex >= cellBlocks.length) break;
-      const cellBlockId = cellBlocks[cellIndex]?.block_id;
-      const cellText = tableData.cells[row]?.[col] ?? "";
-      if (cellBlockId && cellText) {
-        await delay(50);
-        const cellChildrenRes = await ctx.client.docx.documentBlockChildren.get({
-          path: { document_id: ctx.docToken, block_id: cellBlockId },
-        });
-        const textBlockId = cellChildrenRes.data?.items?.[0]?.block_id;
-        if (textBlockId) {
-          await ctx.client.docx.documentBlock.patch({
-            path: { document_id: ctx.docToken, block_id: textBlockId },
-            data: { update_text_elements: { elements: [{ text_run: { content: cellText } }] } },
-          });
-        }
-      }
-      cellIndex++;
-    }
-  }
 
-  ctx.tablesCreated++;
-  return tableBlockId;
+  if (res.code !== 0) {
+    throw new Error(`Failed to create nested blocks: ${res.msg}`);
+  }
 }
 
-/** Insert blocks recursively preserving nested structure */
-async function insertBlocksRecursively(
+/**
+ * Create a complete table using nested blocks API.
+ * No 9x9 size limitation.
+ */
+async function createTableWithNestedBlocks(
   client: Lark.Client,
   docToken: string,
-  blocks: any[],
-  firstLevelBlockIds: string[],
-  startIndex: number = 0
-): Promise<{ blocksInserted: number; tablesCreated: number }> {
-  // Build block map
-  const blockMap = new Map<string, any>();
-  for (const block of blocks) {
-    if (block.block_id) {
-      blockMap.set(block.block_id, block);
-    }
-  }
+  rows: string[][],
+  index?: number,
+): Promise<void> {
+  if (rows.length === 0) return;
 
-  // Extract table data and related IDs
-  const tableRelatedIds = new Set<string>();
-  const tableDataMap = new Map<string, TableData>();
+  const rowSize = rows.length;
+  const colSize = Math.max(...rows.map((r) => r.length));
 
-  for (const block of blocks) {
-    if (block.block_type === TABLE_BLOCK_TYPE) {
-      const { tableData, relatedIds } = extractTableData(block, blockMap);
-      tableDataMap.set(block.block_id, tableData);
-      for (const id of relatedIds) {
-        tableRelatedIds.add(id);
-      }
-    }
-  }
+  // Generate IDs
+  const tableId = generateBlockId();
+  const cellIds: string[] = [];
+  const descendants: any[] = [];
 
-  const ctx: InsertContext = {
-    client,
-    docToken,
-    blockMap,
-    tableRelatedIds,
-    tableDataMap,
-    insertedCount: 0,
-    tablesCreated: 0,
-  };
-
-  // Insert blocks in order of first_level_block_ids
-  for (let i = 0; i < firstLevelBlockIds.length; i++) {
-    const blockId = firstLevelBlockIds[i];
-    const block = blockMap.get(blockId);
-    if (block) {
-      await insertBlockWithChildren(ctx, block, docToken, startIndex + i);
+  // Create cell IDs array
+  for (let row = 0; row < rowSize; row++) {
+    for (let col = 0; col < colSize; col++) {
+      cellIds.push(generateBlockId());
     }
   }
 
-  return { blocksInserted: ctx.insertedCount, tablesCreated: ctx.tablesCreated };
-}
-
-// ============ Core Functions ============
-
-/** Convert markdown to Feishu blocks using the Convert API */
-async function convertMarkdown(client: Lark.Client, markdown: string) {
-  const res = await client.docx.document.convert({
-    data: { content_type: "markdown", content: markdown },
+  // 1. Table block
+  descendants.push({
+    block_id: tableId,
+    block_type: TABLE_BLOCK_TYPE,
+    table: {
+      property: {
+        row_size: rowSize,
+        column_size: colSize,
+        header_row: true,
+      },
+    },
+    children: cellIds,
   });
-  if (res.code !== 0) throw new Error(res.msg);
 
-  const rawBlocks = res.data?.blocks ?? [];
-  const firstLevelBlockIds = res.data?.first_level_block_ids ?? [];
+  // 2. Table cells and their content
+  let cellIdx = 0;
+  for (let row = 0; row < rowSize; row++) {
+    for (let col = 0; col < colSize; col++) {
+      const cellId = cellIds[cellIdx];
+      const textId = generateBlockId();
+      const cellContent = rows[row]?.[col] ?? "";
+
+      // Table cell block
+      descendants.push({
+        block_id: cellId,
+        block_type: 32, // TableCell
+        table_cell: {},
+        children: [textId],
+      });
+
+      // Text block inside cell
+      descendants.push({
+        block_id: textId,
+        block_type: 2, // Text
+        text: {
+          elements: [{ text_run: { content: cellContent } }],
+        },
+        children: [],
+      });
 
-  // Sort blocks according to first_level_block_ids (Convert API returns blocks in arbitrary order)
-  const blocks = sortBlocksByFirstLevelIds(rawBlocks, firstLevelBlockIds);
+      cellIdx++;
+    }
+  }
 
-  return { blocks, firstLevelBlockIds };
+  await createNestedBlocks(client, docToken, docToken, [tableId], descendants, index);
 }
 
-/** Insert blocks as children of a parent block (with batching for >50 blocks) */
-async function insertBlocks(
+/**
+ * Insert regular blocks (non-table) in batches.
+ */
+async function insertBlocksBatch(
   client: Lark.Client,
   docToken: string,
   blocks: any[],
-  parentBlockId?: string,
-): Promise<{ children: any[]; skipped: string[] }> {
-  const { cleaned, skipped } = cleanBlocksForInsert(blocks);
-  const blockId = parentBlockId ?? docToken;
-
-  if (cleaned.length === 0) {
-    return { children: [], skipped };
-  }
+  index?: number,
+): Promise<any[]> {
+  if (blocks.length === 0) return [];
 
-  // Feishu API limits to 50 blocks per request
   const BATCH_SIZE = 50;
   const allChildren: any[] = [];
+  let insertIndex = index ?? 0;
 
-  // Get current children count to determine insert index
-  let insertIndex = 0;
-  const existing = await client.docx.documentBlockChildren.get({
-    path: { document_id: docToken, block_id: blockId },
-  });
-  if (existing.code === 0) {
-    insertIndex = existing.data?.items?.length ?? 0;
-  }
-
-  for (let i = 0; i < cleaned.length; i += BATCH_SIZE) {
-    const batch = cleaned.slice(i, i + BATCH_SIZE);
-    const res = await client.docx.documentBlockChildren.create({
-      path: { document_id: docToken, block_id: blockId },
-      data: { children: batch, index: insertIndex },
+  // If no index specified, append at end
+  if (index === undefined) {
+    const existing = await client.docx.documentBlockChildren.get({
+      path: { document_id: docToken, block_id: docToken },
     });
-    if (res.code !== 0) throw new Error(res.msg);
-    const inserted = res.data?.children ?? [];
-    allChildren.push(...inserted);
-    insertIndex += inserted.length;
-  }
-
-  return { children: allChildren, skipped };
-}
-
-/** Insert blocks at a specific index (with batching for >50 blocks) */
-async function insertBlocksAtIndex(
-  client: Lark.Client,
-  docToken: string,
-  blocks: any[],
-  startIndex: number,
-  parentBlockId?: string,
-): Promise<{ children: any[]; skipped: string[] }> {
-  const { cleaned, skipped } = cleanBlocksForInsert(blocks);
-  const blockId = parentBlockId ?? docToken;
-
-  if (cleaned.length === 0) {
-    return { children: [], skipped };
+    if (existing.code === 0) {
+      insertIndex = existing.data?.items?.length ?? 0;
+    }
   }
 
-  const BATCH_SIZE = 50;
-  const allChildren: any[] = [];
-  let insertIndex = startIndex;
-
-  for (let i = 0; i < cleaned.length; i += BATCH_SIZE) {
-    const batch = cleaned.slice(i, i + BATCH_SIZE);
+  for (let i = 0; i < blocks.length; i += BATCH_SIZE) {
+    const batch = blocks.slice(i, i + BATCH_SIZE);
     const res = await client.docx.documentBlockChildren.create({
-      path: { document_id: docToken, block_id: blockId },
+      path: { document_id: docToken, block_id: docToken },
       data: { children: batch, index: insertIndex },
     });
     if (res.code !== 0) throw new Error(res.msg);
@@ -579,9 +224,11 @@ async function insertBlocksAtIndex(
     insertIndex += inserted.length;
   }
 
-  return { children: allChildren, skipped };
+  return allChildren;
 }
 
+// ============ Core Functions ============
+
 /** Delete all child blocks from a parent */
 async function clearDocumentContent(client: Lark.Client, docToken: string) {
   const existing = await client.docx.documentBlock.list({
@@ -638,168 +285,6 @@ async function downloadImage(url: string): Promise<Buffer> {
   return Buffer.from(await response.arrayBuffer());
 }
 
-/** Create an empty table and return its block ID */
-async function createEmptyTable(
-  client: Lark.Client,
-  docToken: string,
-  parentBlockId: string,
-  rowSize: number,
-  colSize: number,
-  index?: number,
-): Promise<string | null> {
-  const tableBlock = {
-    block_type: TABLE_BLOCK_TYPE,
-    table: {
-      property: {
-        row_size: rowSize,
-        column_size: colSize,
-        header_row: true,
-      },
-      cells: [], // Empty cells, will be filled later
-    },
-  };
-
-  const res = await client.docx.documentBlockChildren.create({
-    path: { document_id: docToken, block_id: parentBlockId },
-    data: { children: [tableBlock], ...(index !== undefined && { index }) },
-  });
-
-  if (res.code !== 0) {
-    console.error(`Failed to create table: ${res.msg}`);
-    return null;
-  }
-
-  const created = res.data?.children ?? [];
-  return created[0]?.block_id ?? null;
-}
-
-/** Get children blocks of a parent block */
-async function getBlockChildren(
-  client: Lark.Client,
-  docToken: string,
-  blockId: string,
-): Promise<any[]> {
-  const res = await client.docx.documentBlockChildren.get({
-    path: { document_id: docToken, block_id: blockId },
-  });
-  if (res.code !== 0) {
-    throw new Error(`Failed to get block children: ${res.msg}`);
-  }
-  return res.data?.items ?? [];
-}
-
-/** Update a text block's content */
-async function updateTextBlock(
-  client: Lark.Client,
-  docToken: string,
-  blockId: string,
-  content: string,
-): Promise<void> {
-  const res = await client.docx.documentBlock.patch({
-    path: { document_id: docToken, block_id: blockId },
-    data: {
-      update_text_elements: {
-        elements: [{ text_run: { content } }],
-      },
-    },
-  });
-  if (res.code !== 0) {
-    console.error(`Failed to update text block ${blockId}: ${res.msg}`);
-  }
-}
-
-/** Fill table cells with content */
-async function fillTableContent(
-  client: Lark.Client,
-  docToken: string,
-  tableBlockId: string,
-  cells: string[][],
-): Promise<void> {
-  // Get table's cell blocks (they are direct children of the table)
-  const cellBlocks = await getBlockChildren(client, docToken, tableBlockId);
-
-  // Cells are in row-major order
-  const colSize = cells[0]?.length ?? 0;
-  let cellIndex = 0;
-
-  for (let row = 0; row < cells.length; row++) {
-    for (let col = 0; col < colSize; col++) {
-      if (cellIndex >= cellBlocks.length) break;
-
-      const cellBlock = cellBlocks[cellIndex];
-      const cellBlockId = cellBlock?.block_id;
-      const cellText = cells[row]?.[col] ?? "";
-
-      if (cellBlockId && cellText) {
-        // Each cell block contains text blocks as children
-        const cellChildren = await getBlockChildren(client, docToken, cellBlockId);
-        if (cellChildren.length > 0) {
-          // Update the first text block in the cell
-          const textBlockId = cellChildren[0]?.block_id;
-          if (textBlockId) {
-            await updateTextBlock(client, docToken, textBlockId, cellText);
-          }
-        }
-      }
-
-      cellIndex++;
-    }
-  }
-}
-
-/** Create and fill a table */
-async function createAndFillTable(
-  client: Lark.Client,
-  docToken: string,
-  parentBlockId: string,
-  tableData: TableData,
-): Promise<boolean> {
-  // 1. Create empty table
-  const tableBlockId = await createEmptyTable(
-    client,
-    docToken,
-    parentBlockId,
-    tableData.rowSize,
-    tableData.colSize,
-  );
-
-  if (!tableBlockId) {
-    return false;
-  }
-
-  // 2. Fill table content
-  await fillTableContent(client, docToken, tableBlockId, tableData.cells);
-
-  return true;
-}
-
-/** Create and fill a table at a specific index */
-async function createAndFillTableAtIndex(
-  client: Lark.Client,
-  docToken: string,
-  parentBlockId: string,
-  tableData: TableData,
-  index: number,
-): Promise<boolean> {
-  // 1. Create empty table at specific index
-  const tableBlockId = await createEmptyTable(
-    client,
-    docToken,
-    parentBlockId,
-    tableData.rowSize,
-    tableData.colSize,
-    index,
-  );
-
-  if (!tableBlockId) {
-    return false;
-  }
-
-  // 2. Fill table content
-  await fillTableContent(client, docToken, tableBlockId, tableData.cells);
-
-  return true;
-}
 
 /** Process images in markdown: download from URL, upload to Feishu, update blocks */
 async function processImages(
@@ -1035,20 +520,46 @@ async function writeDoc(client: Lark.Client, docToken: string, markdown: string)
   // 1. Clear existing content
   const deleted = await clearDocumentContent(client, docToken);
 
-  // 2. Convert markdown to blocks
-  const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
-  if (blocks.length === 0) {
+  // 2. Parse markdown locally (no Convert API)
+  const { blocks, tables, allItems } = markdownToFeishuBlocks(markdown);
+  if (allItems.length === 0) {
     return { success: true, blocks_deleted: deleted, blocks_added: 0, images_processed: 0, tables_created: 0 };
   }
 
-  // 3. Insert blocks recursively (preserves nested structure)
-  const { blocksInserted, tablesCreated } = await insertBlocksRecursively(
-    client,
-    docToken,
-    blocks,
-    firstLevelBlockIds,
-    0
-  );
+  // 3. Insert blocks in order, handling tables specially
+  let blocksInserted = 0;
+  let tablesCreated = 0;
+  let currentIndex = 0;
+
+  // Collect regular blocks to batch insert
+  let regularBlocksBatch: any[] = [];
+
+  for (const item of allItems) {
+    if (item instanceof TablePlaceholder) {
+      // First, insert any accumulated regular blocks
+      if (regularBlocksBatch.length > 0) {
+        const inserted = await insertBlocksBatch(client, docToken, regularBlocksBatch, currentIndex);
+        blocksInserted += inserted.length;
+        currentIndex += inserted.length;
+        regularBlocksBatch = [];
+      }
+
+      // Then create the table
+      await createTableWithNestedBlocks(client, docToken, item.rows, currentIndex);
+      tablesCreated++;
+      currentIndex++;
+    } else {
+      // Accumulate regular blocks for batch insert
+      const apiBlock = prepareBlocksForApi([item])[0];
+      regularBlocksBatch.push(apiBlock);
+    }
+  }
+
+  // Insert any remaining regular blocks
+  if (regularBlocksBatch.length > 0) {
+    const inserted = await insertBlocksBatch(client, docToken, regularBlocksBatch, currentIndex);
+    blocksInserted += inserted.length;
+  }
 
   // 4. Process images (get inserted blocks for image processing)
   const insertedRes = await client.docx.documentBlock.list({
@@ -1068,9 +579,9 @@ async function writeDoc(client: Lark.Client, docToken: string, markdown: string)
 }
 
 async function appendDoc(client: Lark.Client, docToken: string, markdown: string) {
-  // 1. Convert markdown to blocks
-  const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
-  if (blocks.length === 0) {
+  // 1. Parse markdown locally (no Convert API)
+  const { blocks, tables, allItems } = markdownToFeishuBlocks(markdown);
+  if (allItems.length === 0) {
     throw new Error("Content is empty");
   }
 
@@ -1083,14 +594,40 @@ async function appendDoc(client: Lark.Client, docToken: string, markdown: string
     startIndex = existing.data?.items?.length ?? 0;
   }
 
-  // 3. Insert blocks recursively (preserves nested structure)
-  const { blocksInserted, tablesCreated } = await insertBlocksRecursively(
-    client,
-    docToken,
-    blocks,
-    firstLevelBlockIds,
-    startIndex
-  );
+  // 3. Insert blocks in order, handling tables specially
+  let blocksInserted = 0;
+  let tablesCreated = 0;
+  let currentIndex = startIndex;
+
+  // Collect regular blocks to batch insert
+  let regularBlocksBatch: any[] = [];
+
+  for (const item of allItems) {
+    if (item instanceof TablePlaceholder) {
+      // First, insert any accumulated regular blocks
+      if (regularBlocksBatch.length > 0) {
+        const inserted = await insertBlocksBatch(client, docToken, regularBlocksBatch, currentIndex);
+        blocksInserted += inserted.length;
+        currentIndex += inserted.length;
+        regularBlocksBatch = [];
+      }
+
+      // Then create the table
+      await createTableWithNestedBlocks(client, docToken, item.rows, currentIndex);
+      tablesCreated++;
+      currentIndex++;
+    } else {
+      // Accumulate regular blocks for batch insert
+      const apiBlock = prepareBlocksForApi([item])[0];
+      regularBlocksBatch.push(apiBlock);
+    }
+  }
+
+  // Insert any remaining regular blocks
+  if (regularBlocksBatch.length > 0) {
+    const inserted = await insertBlocksBatch(client, docToken, regularBlocksBatch, currentIndex);
+    blocksInserted += inserted.length;
+  }
 
   // 4. Process images (get inserted blocks for image processing)
   const insertedRes = await client.docx.documentBlock.list({

package/src/feishu-renderer.ts

@@ -0,0 +1,441 @@
+/**
+ * Feishu Document Renderer using marked.
+ *
+ * Converts Markdown AST to Feishu Block structure.
+ */
+
+import { Lexer, type Token, type Tokens } from "marked";
+
+// Code language mapping for Feishu
+export const CODE_LANG_MAP: Record<string, number> = {
+  python: 49,
+  py: 49,
+  javascript: 30,
+  js: 30,
+  typescript: 63,
+  ts: 63,
+  go: 22,
+  golang: 22,
+  rust: 53,
+  java: 29,
+  kotlin: 32,
+  kt: 32,
+  c: 10,
+  cpp: 9,
+  "c++": 9,
+  sql: 56,
+  bash: 7,
+  shell: 7,
+  sh: 7,
+  json: 28,
+  yaml: 67,
+  yml: 67,
+  markdown: 39,
+  md: 39,
+  html: 24,
+  css: 12,
+  swift: 61,
+  ruby: 52,
+  php: 43,
+};
+
+/**
+ * Placeholder for table content.
+ *
+ * Tables in Feishu require special handling via nested blocks API.
+ */
+export class TablePlaceholder {
+  rows: string[][];
+  rowSize: number;
+  colSize: number;
+
+  constructor(rows: string[][]) {
+    this.rows = rows;
+    this.rowSize = rows.length;
+    this.colSize = rows.length > 0 ? Math.max(...rows.map((r) => r.length)) : 0;
+  }
+
+  toString(): string {
+    return `TablePlaceholder(${this.rowSize}x${this.colSize})`;
+  }
+}
+
+/** Feishu text element */
+export interface TextElement {
+  text_run: {
+    content: string;
+    text_element_style?: {
+      bold?: boolean;
+      italic?: boolean;
+      strikethrough?: boolean;
+      inline_code?: boolean;
+      link?: { url: string };
+    };
+  };
+}
+
+/** Feishu block structure */
+export interface FeishuBlock {
+  block_id: string;
+  block_type: number;
+  children: string[];
+  text?: { elements: TextElement[] };
+  heading1?: { elements: TextElement[] };
+  heading2?: { elements: TextElement[] };
+  heading3?: { elements: TextElement[] };
+  heading4?: { elements: TextElement[] };
+  heading5?: { elements: TextElement[] };
+  heading6?: { elements: TextElement[] };
+  heading7?: { elements: TextElement[] };
+  heading8?: { elements: TextElement[] };
+  heading9?: { elements: TextElement[] };
+  bullet?: { elements: TextElement[] };
+  ordered?: { elements: TextElement[] };
+  code?: { elements: TextElement[]; style: { language: number } };
+  quote_container?: Record<string, never>;
+  divider?: Record<string, never>;
+  _nested_blocks?: FeishuBlock[];
+}
+
+/** Content item: either a block or a table placeholder */
+export type ContentItem = FeishuBlock | TablePlaceholder;
+
+/**
+ * Render Markdown to Feishu Block structure.
+ */
+export class FeishuRenderer {
+  private blockId = 0;
+
+  private nextId(): string {
+    this.blockId++;
+    return `block_${this.blockId}`;
+  }
+
+  /**
+   * Render markdown tokens to Feishu blocks.
+   */
+  render(tokens: Token[]): ContentItem[] {
+    const result: ContentItem[] = [];
+    for (const token of tokens) {
+      const block = this.renderToken(token);
+      if (block !== null) {
+        if (Array.isArray(block)) {
+          result.push(...block);
+        } else {
+          result.push(block);
+        }
+      }
+    }
+    return result;
+  }
+
+  private renderToken(token: Token): ContentItem | ContentItem[] | null {
+    switch (token.type) {
+      case "paragraph":
+        return this.paragraph(token as Tokens.Paragraph);
+      case "heading":
+        return this.heading(token as Tokens.Heading);
+      case "code":
+        return this.blockCode(token as Tokens.Code);
+      case "blockquote":
+        return this.blockQuote(token as Tokens.Blockquote);
+      case "list":
+        return this.list(token as Tokens.List);
+      case "hr":
+        return this.thematicBreak();
+      case "table":
+        return this.table(token as Tokens.Table);
+      case "space":
+        return null;
+      default:
+        return null;
+    }
+  }
+
+  // === Block-level rendering ===
+
+  private paragraph(token: Tokens.Paragraph): FeishuBlock {
+    const elements = this.renderInlineTokens(token.tokens ?? []);
+    return {
+      block_id: this.nextId(),
+      block_type: 2,
+      text: { elements },
+      children: [],
+    };
+  }
+
+  private heading(token: Tokens.Heading): FeishuBlock {
+    const level = token.depth;
+    const elements = this.renderInlineTokens(token.tokens ?? []);
+    const key = `heading${level}` as keyof FeishuBlock;
+    return {
+      block_id: this.nextId(),
+      block_type: 2 + level, // heading1=3, heading2=4, etc.
+      [key]: { elements },
+      children: [],
+    };
+  }
+
+  private blockCode(token: Tokens.Code): FeishuBlock {
+    const lang = token.lang ?? "";
+    const langCode = CODE_LANG_MAP[lang.toLowerCase()] ?? 1;
+    return {
+      block_id: this.nextId(),
+      block_type: 14,
+      code: {
+        elements: [{ text_run: { content: token.text } }],
+        style: { language: langCode },
+      },
+      children: [],
+    };
+  }
+
+  private blockQuote(token: Tokens.Blockquote): FeishuBlock {
+    const containerId = this.nextId();
+    const nestedBlocks: FeishuBlock[] = [];
+
+    for (const child of token.tokens ?? []) {
+      const block = this.renderToken(child);
+      if (block !== null) {
+        if (Array.isArray(block)) {
+          for (const b of block) {
+            if (!(b instanceof TablePlaceholder)) {
+              nestedBlocks.push(b);
+            }
+          }
+        } else if (!(block instanceof TablePlaceholder)) {
+          nestedBlocks.push(block);
+        }
+      }
+    }
+
+    return {
+      block_id: containerId,
+      block_type: 34, // quote_container
+      quote_container: {},
+      children: nestedBlocks.map((b) => b.block_id),
+      _nested_blocks: nestedBlocks,
+    };
+  }
+
+  private list(token: Tokens.List): FeishuBlock[] {
+    const ordered = token.ordered;
+    const blockType = ordered ? 13 : 12;
+    const key = ordered ? "ordered" : "bullet";
+
+    const result: FeishuBlock[] = [];
+    for (const item of token.items) {
+      const elements = this.renderListItemContent(item);
+      result.push({
+        block_id: this.nextId(),
+        block_type: blockType,
+        [key]: { elements: elements.length > 0 ? elements : [{ text_run: { content: "" } }] },
+        children: [],
+      });
+    }
+    return result;
+  }
+
+  private renderListItemContent(item: Tokens.ListItem): TextElement[] {
+    const elements: TextElement[] = [];
+    for (const child of item.tokens ?? []) {
+      if (child.type === "text") {
+        const textToken = child as Tokens.Text;
+        if (textToken.tokens) {
+          elements.push(...this.renderInlineTokens(textToken.tokens));
+        } else {
+          elements.push({ text_run: { content: textToken.raw } });
+        }
+      } else if (child.type === "paragraph") {
+        const paraToken = child as Tokens.Paragraph;
+        elements.push(...this.renderInlineTokens(paraToken.tokens ?? []));
+      }
+    }
+    return elements;
+  }
+
+  private thematicBreak(): FeishuBlock {
+    return {
+      block_id: this.nextId(),
+      block_type: 22,
+      divider: {},
+      children: [],
+    };
+  }
+
+  // === Table rendering ===
+
+  private table(token: Tokens.Table): TablePlaceholder {
+    const rows: string[][] = [];
+
+    // Header row
+    const headerRow: string[] = [];
+    for (const cell of token.header) {
+      headerRow.push(this.extractTextContent(cell.tokens));
+    }
+    rows.push(headerRow);
+
+    // Body rows
+    for (const row of token.rows) {
+      const rowData: string[] = [];
+      for (const cell of row) {
+        rowData.push(this.extractTextContent(cell.tokens));
+      }
+      rows.push(rowData);
+    }
+
+    return new TablePlaceholder(rows);
+  }
+
+  private extractTextContent(tokens: Token[]): string {
+    const parts: string[] = [];
+    for (const token of tokens) {
+      if (token.type === "text") {
+        parts.push((token as Tokens.Text).text);
+      } else if (token.type === "codespan") {
+        parts.push((token as Tokens.Codespan).text);
+      } else if (token.type === "strong" || token.type === "em" || token.type === "del") {
+        const t = token as Tokens.Strong | Tokens.Em | Tokens.Del;
+        parts.push(this.extractTextContent(t.tokens ?? []));
+      } else if (token.type === "link") {
+        const linkToken = token as Tokens.Link;
+        parts.push(this.extractTextContent(linkToken.tokens ?? []));
+      }
+    }
+    return parts.join("");
+  }
+
+  // === Inline-level rendering ===
+
+  private renderInlineTokens(tokens: Token[]): TextElement[] {
+    const elements: TextElement[] = [];
+    for (const token of tokens) {
+      const result = this.renderInline(token);
+      if (result) {
+        if (Array.isArray(result)) {
+          elements.push(...result);
+        } else {
+          elements.push(result);
+        }
+      }
+    }
+    return elements.length > 0 ? elements : [{ text_run: { content: "" } }];
+  }
+
+  private renderInline(token: Token): TextElement | TextElement[] | null {
+    switch (token.type) {
+      case "text":
+        return { text_run: { content: (token as Tokens.Text).text } };
+
+      case "strong": {
+        const strongToken = token as Tokens.Strong;
+        const elements = this.renderInlineTokens(strongToken.tokens ?? []);
+        for (const el of elements) {
+          el.text_run.text_element_style = el.text_run.text_element_style ?? {};
+          el.text_run.text_element_style.bold = true;
+        }
+        return elements;
+      }
+
+      case "em": {
+        const emToken = token as Tokens.Em;
+        const elements = this.renderInlineTokens(emToken.tokens ?? []);
+        for (const el of elements) {
+          el.text_run.text_element_style = el.text_run.text_element_style ?? {};
+          el.text_run.text_element_style.italic = true;
+        }
+        return elements;
+      }
+
+      case "del": {
+        const delToken = token as Tokens.Del;
+        const elements = this.renderInlineTokens(delToken.tokens ?? []);
+        for (const el of elements) {
+          el.text_run.text_element_style = el.text_run.text_element_style ?? {};
+          el.text_run.text_element_style.strikethrough = true;
+        }
+        return elements;
+      }
+
+      case "codespan":
+        return {
+          text_run: {
+            content: (token as Tokens.Codespan).text,
+            text_element_style: { inline_code: true },
+          },
+        };
+
+      case "link": {
+        const linkToken = token as Tokens.Link;
+        const elements = this.renderInlineTokens(linkToken.tokens ?? []);
+        const encodedUrl = encodeURIComponent(linkToken.href);
+        for (const el of elements) {
+          el.text_run.text_element_style = el.text_run.text_element_style ?? {};
+          el.text_run.text_element_style.link = { url: encodedUrl };
+        }
+        return elements;
+      }
+
+      case "br":
+        return { text_run: { content: "\n" } };
+
+      case "html":
+        return { text_run: { content: (token as Tokens.HTML).raw } };
+
+      default:
+        return null;
+    }
+  }
+}
+
+/**
+ * Convert Markdown to Feishu Block structure.
+ *
+ * @param mdContent Markdown content string
+ * @returns Object with blocks array and tables array
+ */
+export function markdownToFeishuBlocks(mdContent: string): {
+  blocks: FeishuBlock[];
+  tables: TablePlaceholder[];
+  allItems: ContentItem[];
+} {
+  const lexer = new Lexer();
+  const tokens = lexer.lex(mdContent);
+
+  const renderer = new FeishuRenderer();
+  const items = renderer.render(tokens);
+
+  const blocks: FeishuBlock[] = [];
+  const tables: TablePlaceholder[] = [];
+
+  function collectBlocks(item: ContentItem) {
+    if (item instanceof TablePlaceholder) {
+      tables.push(item);
+    } else {
+      blocks.push(item);
+      // Collect nested blocks (e.g., from blockquote)
+      if (item._nested_blocks) {
+        for (const nested of item._nested_blocks) {
+          blocks.push(nested);
+        }
+      }
+    }
+  }
+
+  for (const item of items) {
+    collectBlocks(item);
+  }
+
+  return { blocks, tables, allItems: items };
+}
+
+/**
+ * Prepare blocks for Feishu API.
+ * Removes helper fields before sending to API.
+ */
+export function prepareBlocksForApi(blocks: FeishuBlock[]): any[] {
+  return blocks.map((block) => {
+    const { block_id, children, _nested_blocks, ...rest } = block;
+    return rest;
+  });
+}