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.

Full decision tree (when to use update_block vs delete+insert vs append, with protection mechanisms) is in ~/self-improving/domains/feishu.md under "最小改动原则".

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

| Method | When to use | |--------|------------| | insert with ![](url) markdown | Public URL, image goes with surrounding text | | upload_image + parent_block_id + index | Local file / base64, precise position needed |

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.

Prefer Bitable for data-heavy tables. Bitable has native batch record APIs.
Minimize cell count.
New tables: use create_table_with_values (one-step).
Existing tables: update only changed cells, not the entire table.

Strategy 6: Large Document Chunking

The Feishu document.convert API and documentBlockChildren.create have per-request size limits. For long content:

Chunk appends at 300–600 lines (or ~3K chars) per call to avoid 400 errors.
Split at heading boundaries (# or ##) — keeps each chunk semantically coherent.
Avoid splitting inside fenced code blocks.
OpenClaw's append/insert auto-chunk internally, but feeding smaller pieces reduces conversion failures.

Strategy 7: Rate-Limit & Retry

Feishu API returns 429 when request frequency is too high. Handle it:

Space concurrent calls — if firing 10+ parallel operations, use a concurrency limit of ~5.
Exponential backoff on 429 — wait 1s, 2s, 4s before retrying. Max 3 retries.
Batch block creation where possible — one request with multiple children beats N separate requests.

OpenClaw's built-in tool handles basic retries, but be aware when orchestrating many operations in rapid succession.

Strategy 8: Rich-Text Preservation

update_block replaces the entire text element array — all inline styles (bold, italic, color, links) are lost. To preserve formatting:

Read the block first via get_block to inspect existing text_element_style fields.
Only update blocks where the text actually changed — skip unchanged blocks even if you're rewriting a section.
For style-only changes (color, highlight), use color_text action instead of update_block.
When rich text must be preserved exactly, consider delete_block + insert with markdown that re-expresses the formatting, rather than update_block which strips styles.

Strategy 9: Conflict Avoidance

When multiple agents or users may edit the same document simultaneously:

Check revision_id from read action before making changes. If the revision has advanced since your list_blocks, re-fetch before editing.
Minimize the edit window — scan, plan, and execute in quick succession. Don't hold a stale block tree for minutes.
Prefer append for additive content — appending to the end rarely conflicts with other editors working in the middle.
Avoid deleting blocks you didn't create unless explicitly instructed.

Anti-Patterns

| Don't | Do instead | |-------|-----------| | write to change a few paragraphs | update_block on specific blocks | | Serial update_block one-by-one | Batch independent ops in one tool-call | | upload_image without position params | Pass parent_block_id + index, or use insert with ![](url) | | Parallel upload_image with after_block_id to different positions | Serial: append text → upload_image → append text → upload_image (API ignores after_block_id in parallel) | | Re-fetch list_blocks after every edit | Cache and reuse; re-fetch only after structural changes | | Insert top-to-bottom when mixing insert/delete | Back-to-front to avoid index drift | | Append 2000-line markdown in one call | Chunk at ~300–600 lines per append | | Ignore 429 rate limits | Exponential backoff, limit concurrency to ~5 | | update_block on formatted text blindly | Check existing styles; use color_text for style-only edits |

Compatibility

Works with OpenClaw's built-in feishu_doc tool — no code changes needed
Complements feishu-doc skill (API reference) and feishu-readability skill (formatting rules)
Applies to all Feishu accounts (球球星球 / 小米 / any tenant)