Feishu Document Editing — Performance Best Practices

Core Principle: Minimum Change

Never use write (full document replace) for partial edits — it destroys existing rich-text formatting (colors, highlights, inline styles). Always use targeted block-level operations.

Strategy 1: Scan Once, Act in Parallel

Pattern: One list_blocks → plan all changes → fire independent operations together.

1. feishu_doc(action: "list_blocks", doc_token: "xxx")
   → Full block tree with IDs, types, content

2. Identify which blocks need update/delete/insert

3. Issue all independent operations in one tool-call batch:
   - update_block(block_id: "A", content: "new text")
   - update_block(block_id: "B", content: "new text")
   - delete_block(block_id: "C")
   - insert(after_block_id: "D", content: "...")

Why: update_block on different blocks has zero dependency. OpenClaw executes independent tool calls within a single response concurrently (other AI frameworks may vary — verify before assuming).

Result: 10 serial updates (3–5 s) → 10 concurrent updates (~0.3–1 s).

Cache the block tree: Reuse list_blocks throughout the session. Re-fetch only after inserts/deletes that shift the structure.

Strategy 2: Back-to-Front for Insert/Delete

When mixing insert and delete, operate from the document's end toward the beginning.

Why: Inserting or deleting a block shifts indices of all subsequent siblings. Back-to-front keeps earlier indices stable — no need to re-query after each op.

Example: Delete blocks at indices 5, 12, 20 → delete 20 first, then 12, then 5.

Strategy 3: Merge Adjacent Inserts

Combine consecutive inserts into one call:

{
  "action": "insert",
  "doc_token": "xxx",
  "after_block_id": "target_block",
  "content": "## New Section\n\nParagraph one.\n\nParagraph two.\n\n![caption](https://image-url.png)"
}

Images as ![alt](url) inside insert/append are auto-positioned inline — no separate upload_image needed when the URL is public.

Strategy 4: Positioned Image Insertion

upload_image with position:

{
  "action": "upload_image",
  "doc_token": "xxx",
  "file_path": "/tmp/chart.png",
  "parent_block_id": "doc_root_or_parent_id",
  "index": 5
}

Finding the index: From list_blocks, locate the target in its parent's children array. Use that index to insert before, or index+1 to insert after.

Strategy 5: Table Performance

Docx tables are the slowest — each cell needs separate clear + convert + insert API calls.