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  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 
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)