Feishu Document API - Fixing Block Order

When using the built-in feishu_doc_write to edit Feishu documents, the content order becomes completely scrambled. After deep investigation, found the root cause and solution.

Problem

After writing Markdown content, the blocks in the document are in random order, not in the order they were written.

Root Cause

The Feishu Document API requires an index parameter to control insert position:

POST /open-apis/docx/v1/documents/{doc_id}/blocks/{block_id}/children
{
  "children": [...],
  "index": 0  // Insert position, 0 = from beginning
}

If index is not specified, the API's default behavior causes blocks to be inserted at random positions.

Key Findings

• index: 0 = Insert at the beginning (newest/first)
• No index = Append to the end

Correct Usage: Reverse Order Addition

To display content in correct order, you must add in reverse order:

Final display: A → B → C
Add order: C (index=0) → B (index=0) → A (index=0)

Block Type Reference

Usage Example

# Create document
python3 scripts/feishu_api.py create "Title" "folder_token"

# Add content (reverse order)
python3 scripts/feishu_api.py add <doc_id> <content> <block_type> <insert_first>

# Read document
python3 scripts/feishu_api.py read <doc_id>

封装为Skill

Available as OpenClaw Skill