[Feature] Add incremental sync primitives for embedded whiteboards (node read/update/delete + section support)

[LiuYangArt]

Summary

lark-cli currently does not provide a stable path for incremental sync into an existing embedded whiteboard.

For real workflows such as:

• Obsidian Canvas -> Lark whiteboard migration
• append-only concept board updates
• structured reference-board maintenance

the missing capabilities are not just one bug, but a broader feature gap:

1. no reliable node-level read/update/delete workflow from lark-cli
2. no first-class support for native whiteboard section-style grouping in the CLI/DSL path
3. embedded whiteboard token resolution is not explicit enough from doc/wiki context

Because of this, a workflow that should be “read existing board -> diff -> update only the changed nodes” becomes “mix browser automation with partial CLI writes”, which is too brittle for production use.

What is currently possible

Today, lark-cli docs +whiteboard-update is usable for coarse operations like:

• append some text nodes
• append some frame/shape nodes
• overwrite the whole whiteboard

That is useful, but it is not enough for structured sync into a real working board.

Main gaps

1. Missing node-level read / update / delete flow

For an existing whiteboard, a sync tool needs to:

• list nodes with stable IDs and useful metadata
• inspect node type and geometry
• update a specific node
• delete a specific node
• do all of that without --overwrite

Right now the practical path exposed by lark-cli is too coarse-grained. Once the board contains user-authored content, append-only plus full overwrite is not enough.

2. No first-class section support in the CLI/DSL workflow

In the whiteboard UI, section is an important native grouping primitive and is visibly different from a plain shape/frame.

For migration/sync workflows, replacing a real section with an approximate dark rectangle/frame is not equivalent:

• visual style is different
• interaction model is different
• grouping intent is different

If the CLI/DSL path cannot create or manipulate native sections, high-fidelity board sync is very hard.

3. Embedded whiteboard token handling is hard to reason about

For doc/wiki-embedded whiteboards, the token surfaced from doc content is not always the most useful token for the actual editable board session.

In practice, browser-observed board state can differ from what a naive doc-layer workflow expects.

A CLI-first workflow would benefit from an explicit helper that can:

• resolve doc/wiki URL -> actual editable embedded whiteboard identity
• show the relationship between wrapper token and editable board token if both exist

Why this matters

This is not only about one migration use case.

Many users want to treat Lark whiteboard as a living structured workspace:

• concept design boards
• research/reference boards
• architecture or planning boards that evolve over time

These workflows need incremental board operations, not just initial board creation.

Without that, users are forced into browser automation for tasks that should be data- or node-driven.

Suggested feature direction

Any one of the following would help a lot:

Option A: add higher-level lark-cli commands

Examples:

• docs +whiteboard-fetch-nodes
• docs +whiteboard-delete-nodes --node-id ...
• docs +whiteboard-update-nodes --node-id ...
• docs +whiteboard-resolve-token --doc <url>

Option B: improve the whiteboard DSL path

Make docs +whiteboard-update support:

• node ID aware updates
• partial deletion
• native section creation/update
• clearer embedded-board token semantics

Option C: expose the lower-level board operations through CLI wrappers

If the underlying OpenAPI already supports these operations, a thin CLI wrapper would already be enough.

Related issues

• [Bug] docs +whiteboard-update rejects image nodes for embedded docx whiteboards #262 docs +whiteboard-update rejects image nodes for embedded docx whiteboards
• [Bug] POST /board/v1/whiteboards/{id}/nodes fails with "invalid objType [@from@] whiteboard" for Wiki-embedded whiteboards #98 POST /board/v1/whiteboards/{id}/nodes fails for Wiki-embedded whiteboards

Those are concrete blockers, but even after fixing them, incremental sync is still difficult without node-level operations and section support.

Concrete user impact

In a real migration attempt from Obsidian Canvas to a docx-embedded Lark whiteboard, the intended workflow was:

1. read an existing whiteboard
2. preserve user-authored content
3. append/update only one reference group
4. keep images, text, links, and grouping structure aligned

In practice this broke down because:

• image append via CLI path is currently blocked by [Bug] docs +whiteboard-update rejects image nodes for embedded docx whiteboards #262
• grouping via native section is not exposed cleanly through CLI/DSL
• targeted cleanup/update of a bad node group is not available as a clean CLI operation

That makes the workflow much slower and much less reliable than it should be.

Request

Please consider adding a proper incremental whiteboard sync capability to lark-cli, especially for embedded boards inside docx/wiki documents.

Even a minimal first step such as:

• resolve embedded board token reliably
• fetch node list
• delete nodes by ID
• create/update native section nodes

would immediately unlock much more robust integrations.