Feishu Doc Editing

Performance-optimized strategies for editing Feishu (Lark) documents via OpenClaw's feishu_doc tool. Use when: (1) modifying existing Feishu documents, (2) i...

Security Scan

Instructions are coherent with a Feishu (Lark) document-editing purpose; no unexpected installs or credentials are requested, though the guide mentions local file paths which you should verify before allowing access.

Purpose & Capability

The name/description (performance-optimized Feishu doc editing) matches the SKILL.md content: targeted block operations, chunking, rate-limit handling, positioned images, and preserving rich text. The skill does not request unrelated binaries, env vars, or credentials.

Instruction Scope

Most runtime instructions stay within Feishu doc operations (list_blocks, update_block, insert, upload_image). However, the doc includes examples that reference local filesystem paths (e.g., /tmp/chart.png) and a local doc path (~/self-improving/domains/feishu.md). These imply the agent might read or upload local files—reasonable for an editing tool but worth confirming that the agent is allowed to access those paths and that no sensitive local files are referenced.

Install Mechanism

This is an instruction-only skill with no install spec and no code files—no disk writes or external downloads are performed by the skill itself.

Credentials

The skill declares no required environment variables or credentials. The SKILL.md uses placeholders (e.g., doc_token: "xxx") but does not demand secrets beyond what the platform's feishu_doc tool would supply, so requested access is proportional to its purpose.

Persistence & Privilege

always is false, user-invocable is allowed, and model invocation is permitted (platform default). The skill does not request elevated persistence or modification of other skills/configs.

Assessment

This instruction-only skill is internally consistent with Feishu document editing and has low installation risk. Before using it: 1) Confirm the agent/platform provides Feishu credentials (doc_token) via the built-in feishu_doc tool rather than you pasting secrets into the skill. 2) If you enable the agent to access local files, verify which paths it can read—examples mention /tmp/chart.png and ~/self-improving/... which could cause the agent to read or upload local content. 3) For image insertion prefer public URLs unless you trust upload_image to handle local files securely. 4) Test these patterns on a non-production document to validate concurrency, chunking, and revision-handling behavior before running large or sensitive edits. If you want stricter controls, deny filesystem access or review any platform-provided feishu_doc tool policies first.

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)