Feishu Doc Editing

Feishu Document Editing — Performance Best Practices Core Principle: Minimum Change

Never use write (full document replace) for partial edits — it destroys existing rich-text 格式化ting (colors, highlights, inline styles). Always use tar获取ed block-level operations.

Full decision tree (when to use 更新_block vs 删除+insert vs 应用end, with 保护ion mechanisms) is in ~/self-improving/domAIns/feishu.md under "最小改动原则".

Strategy 1: 扫描 Once, Act in Parallel

Pattern: One 列出_blocks → plan all changes → fire independent operations to获取her.

• feishu_doc(action: "列出_blocks", doc_令牌: "xxx")

→ Full block tree with IDs, types, content

• Identify which blocks need 更新/删除/insert

• Issue all independent operations in one 工具-call batch:

- 更新_block(block_id: "A", content: "new text") - 更新_block(block_id: "B", content: "new text") - 删除_block(block_id: "C") - insert(after_block_id: "D", content: "...")

Why: 更新_block on different blocks has zero dependency. OpenClaw 执行s independent 工具 calls within a single 响应 concurrently (other AI 框架s may vary — 验证 before assuming).

结果: 10 serial 更新s (3–5 s) → 10 concurrent 更新s (~0.3–1 s).

缓存 the block tree: Reuse 列出_blocks throughout the 会话. Re-fetch only after inserts/删除s that shift the structure.

Strategy 2: Back-to-Front for Insert/删除

When mixing insert and 删除, 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-查询 after each op.

Example: 删除 blocks at indices 5, 12, 20 → 删除 20 first, then 12, then 5.

Strategy 3: Merge Adjacent Inserts

Combine consecutive inserts into one call:

{ "action": "insert", "doc_令牌": "xxx", "after_block_id": "tar获取_block", "content": "## New Section\n\nParagraph one.\n\nParagraph two.\n\n!caption" }

Images as !alt inside insert/应用end are auto-positioned inline — no separate 上传_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 上传_image + parent_block_id + 索引 Local file / base64, precise position needed

上传_image with position:

{ "action": "上传_image", "doc_令牌": "xxx", "file_path": "/tmp/图表.png", "parent_block_id": "doc_root_or_parent_id", "索引": 5 }

Finding the 索引: From 列出_blocks, locate the tar获取 in its parent's children array. Use that 索引 to insert before, or 索引+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 创建_table_with_values (one-step). Existing tables: 更新 only changed cells, not the entire table. Strategy 6: Large Document Chunking

The Feishu document.convert API and documentBlockChildren.创建 have per-请求 size limits. For long content:

Chunk 应用ends 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 应用end/insert auto-chunk internally, but feeding smaller pieces reduces conversion 失败s. Strategy 7: Rate-Limit & Retry

Feishu API returns 429 when 请求 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 请求 with multiple children beats N separate 请求s.

OpenClaw's built-in 工具 handles basic retries, but be aware when orchestrating many operations in rAPId 成功ion.

Strategy 8: Rich-Text Preservation

更新_block replaces the entire text element array — all inline styles (bold, italic, color, links) are lost. To preserve 格式化ting:

Read the block first via 获取_block to inspect existing text_element_style fields. Only 更新 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 更新_block. When rich text must be preserved exactly, consider 删除_block + insert with markdown that re-expresses the 格式化ting, rather than 更新_block which strips styles. Strategy 9: Conflict Avoidance

When multiple 代理s or users may edit the same document simultaneously:

检查 revision_id from read action before making changes. If the revision has advanced since your 列出_blocks, re-fetch before editing. Minimize the edit window — 扫描, plan, and 执行 in quick 成功ion. Don't hold a stale block tree for minutes. Prefer 应用end for 添加itive content — 应用ending to the end rarely conflic