fix(feishu): insert document blocks sequentially to preserve order (#26022) by echoVic · Pull Request #26172 · openclaw/openclaw

echoVic · 2026-02-25T05:50:13Z

Problem

When using feishu_doc with action: "append" or action: "write", blocks appear in random order instead of the order specified in the Markdown content.

Fixes #26022

Root Cause

documentBlockChildren.create batch API does not guarantee insertion order when multiple blocks are sent in a single call. Feishu processes the batch asynchronously, resulting in non-deterministic block positions.

Fix

Switch from batch insertion (all blocks in one API call) to sequential single-block inserts. Each block is appended one at a time, preserving the source markdown order.

Changes

extensions/feishu/src/docx.ts: Replace batch insertBlocks with sequential per-block insertion
extensions/feishu/src/docx.test.ts: Add test verifying sequential insertion order

Testing

Existing test passes (image fetch hardening)
New test verifies: 3 blocks → 3 sequential API calls, each with exactly 1 block in correct order

Greptile Summary

This PR fixes block insertion order in Feishu documents by switching from batch API insertion to sequential single-block inserts. The batch API (documentBlockChildren.create with multiple children) processes blocks asynchronously without guaranteed ordering. The fix inserts blocks one at a time, appending each to the end, which produces deterministic results that match the source markdown order.

The implementation is straightforward:

Replaced single batch API call with a loop that makes one API call per block
Added clear inline comments explaining why sequential insertion is necessary
Added comprehensive test coverage verifying the sequential behavior
Error handling remains intact (throws on first failure)

Confidence Score: 4/5

This PR is safe to merge with one minor consideration around partial failures
The fix correctly addresses the ordering issue with a well-tested solution. However, there's a potential edge case: if insertion fails mid-sequence, the document will be left in a partially-inserted state (some blocks added, others not), whereas the batch approach would be all-or-nothing. This is a minor trade-off for correctness, but worth noting for production scenarios with large documents.
No files require special attention

_{Last reviewed commit: 276b393}

greptile-apps

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-02-25T05:52:01Z

extensions/feishu/src/docx.ts

+  for (const block of cleaned) {
+    const res = await client.docx.documentBlockChildren.create({
+      path: { document_id: docToken, block_id: blockId },
+      data: { children: [block] },
+    });
+    if (res.code !== 0) {
+      throw new Error(res.msg);
+    }
+    allInserted.push(...(res.data?.children ?? []));
  }


If an insertion fails mid-sequence, the document will contain partial content (some blocks inserted, remaining blocks skipped). The batch approach would have been all-or-nothing. Consider wrapping in try/catch to clean up partial inserts on failure, or document this behavior for callers.

Prompt To Fix With AI

This is a comment left during a code review. Path: extensions/feishu/src/docx.ts Line: 124-133 Comment: If an insertion fails mid-sequence, the document will contain partial content (some blocks inserted, remaining blocks skipped). The batch approach would have been all-or-nothing. Consider wrapping in try/catch to clean up partial inserts on failure, or document this behavior for callers. How can I resolve this? If you propose a fix, please make it concise.

echoVic · 2026-02-25T06:13:43Z

CI failures are pre-existing on main — run.skill-filter.test.ts (missing setSessionRuntimeModel mock), model-fallback.test.ts, and web-tools.enabled-defaults.test.ts. None related to this PR's changes.

learnpythontheew · 2026-02-26T12:16:18Z

This bug is blocking our documentation workflow. Please consider merging soon. Happy to test if needed.

…penclaw#26022) The batch documentBlockChildren.create API does not guarantee insertion order, causing blocks to appear in random positions when appending or writing structured content. Switch to sequential single-block inserts so each block is appended in the order it appears in the source markdown.

Takhoffman · 2026-02-28T04:49:19Z

PR #26172 - fix(feishu): insert document blocks sequentially to preserve order (#26022) (#26172)

Merged via squash.

Merge commit: b28344e
Verified: pnpm build, pnpm check, pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts
Changes made:
CHANGELOG.md\n- extensions/feishu/src/docx.ts\n- extensions/feishu/src/docx.test.ts
Why these changes were made:
Rebased onto current main and resolved insertBlocks conflict by preserving sequential block inserts while retaining optional index handling.\n- Added changelog entry required by merge policy.\n- Fixed docx test registration lookup so the new sequential-order test executes correctly and does not leak one-time mocks into subsequent tests.
Changelog: CHANGELOG.md updated=true required=true opt_out=false

Thanks @echoVic!

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> (cherry picked from commit 41d3e77)

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> (cherry picked from commit 41d3e77)

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> (cherry picked from commit 41d3e77)

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> (cherry picked from commit b28344e)

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> (cherry picked from commit b28344e)

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

@echoVic

…penclaw#26022) (openclaw#26172) thanks @echoVic Verified: - pnpm build - pnpm check - pnpm vitest run --config vitest.extensions.config.ts extensions/feishu/src/docx.test.ts Co-authored-by: echoVic <16428813+echoVic@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>

openclaw-barnacle bot added channel: feishu Channel integration: feishu size: S experienced-contributor labels Feb 25, 2026

greptile-apps bot reviewed Feb 25, 2026

View reviewed changes

echoVic and others added 3 commits February 27, 2026 22:25

Changelog: note feishu doc block ordering fix

cbd8f8c

Test: fix feishu doc tool registration lookup regression

bb28231

Takhoffman force-pushed the fix/feishu-doc-block-ordering branch 2 times, most recently from c73174d to bb28231 Compare February 28, 2026 04:46

Takhoffman merged commit b28344e into openclaw:main Feb 28, 2026
20 of 21 checks passed

This was referenced Feb 28, 2026

test(feishu): add regression for audio download resource type=file #16311

Merged

fix(feishu): preserve docx block order via sequential inserts #16409

Closed

github-actions bot mentioned this pull request Mar 1, 2026

cherry-pick: upstream docs commits (2026-03-01-0443) hughdidit/DAISy-Agency#141

Closed

6 tasks

gemini-code-assist bot mentioned this pull request Mar 1, 2026

chore(sync): replay rollup fixes on upstream/main MillionthOdin16/openclaw#111

Merged

alexey-pelykh mentioned this pull request Mar 10, 2026

Cherry-pick: Feishu adapter — community PRs and fixes remoteclaw/remoteclaw#678

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(feishu): insert document blocks sequentially to preserve order (#26022)#26172

fix(feishu): insert document blocks sequentially to preserve order (#26022)#26172
Takhoffman merged 3 commits intoopenclaw:mainfrom
echoVic:fix/feishu-doc-block-ordering

echoVic commented Feb 25, 2026 •

edited by greptile-apps bot

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot Feb 25, 2026

Uh oh!

echoVic commented Feb 25, 2026

Uh oh!

learnpythontheew commented Feb 26, 2026

Uh oh!

Uh oh!

Takhoffman commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

echoVic commented Feb 25, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Root Cause

Fix

Changes

Testing

Greptile Summary

Confidence Score: 4/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

echoVic commented Feb 25, 2026

Uh oh!

learnpythontheew commented Feb 26, 2026

Uh oh!

Uh oh!

Takhoffman commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

echoVic commented Feb 25, 2026 •

edited by greptile-apps bot

Loading