docs +update: block_insert_after with `<table>` always fails with degrade_code=1010, while append with the same XML succeeds

Summary

docs +update --command block_insert_after fails for every anchor I tried as soon as --content contains a <table>:

degrade_code=1010, msg=Nesting still failed after degrade

The same XML inserted with --command append succeeds. So the table markup itself is valid; only the block_insert_after path rejects it.

Two separate asks here: the error message is not actionable, and one of the failing cases has no documented explanation.

Repro

Observed on 1.0.87 (2026-08-18) on a long docx. Every one of these failed with degrade_code=1010:

anchor block	result
h3 at top level	degrade_code=1010
callout child	degrade_code=1010
li	degrade_code=1010

Variations that made no difference: removing text-color / background-color, removing <col width>, wrapping every cell body in <p>.

The same <table> XML via --command append succeeded on the first try.

Part 1 — the error message is not actionable

For the callout and li anchors, failing is arguably correct. block_insert_after places the new block as a sibling of the anchor, i.e. inside the anchor's parent container, and two containers are documented as not accepting tables:

• The bundled XML reference (~/.agents/skills/lark-doc/references/lark-doc-xml.md, line 37) on callout children: 「子块仅支持 p、ol、ul、checkbox、行内标签；禁止 <table>、<img>、<pre>、<hr>、<grid>、<whiteboard>」
• Official docs on TableCell: it may not contain Table / Sheet / Bitable / OKR.

But Nesting still failed after degrade says none of that. It does not name the offending container, does not say which element could not be nested, and does not point at the constraint being violated. Working out "my anchor's parent is a callout, and callouts cannot hold tables" took a long time precisely because the message gives you nothing to grep for.

Ask: make the error name the parent container and the rejected element, e.g. cannot insert <table> into callout (allowed children: p, ol, ul, checkbox).

Part 2 — the h3 case looks like a genuine bug

When the anchor is an h3 at top level, the parent container is the document root, which does accept tables — append proves that, since it puts the same table at the document root. I could not find any documented rule that forbids this, and I would expect it to behave the same as append.

If there is a rule I have missed, documenting it would help. If not, this looks like the actual defect.

Where it fails

The CLI forwards the XML verbatim. On 1.0.88, --dry-run:

$ lark-cli docs +update --doc "<doc>" --as user \
    --command block_insert_after --block-id "<anchor>" \
    --content '<table><tr><td><p>a</p></td></tr></table>' --dry-run

{
  "data": {
    "api": [{
      "method": "PUT",
      "url": "/open-apis/docs_ai/v1/documents/<doc>",
      "body": {
        "block_id": "<anchor>",
        "command": "block_insert_after",
        "content": "<table><tr><td><p>a</p></td></tr></table>",
        "format": "xml",
        "revision_id": -1
      }
    }]
  }
}

So the rejection happens inside docs_ai, not in CLI code. I have not re-run the write path on 1.0.88; nothing in the 1.0.88 changelog touches nesting.

Workaround

append the table to the end of the document, re-fetch with --detail full to find the new table's block ID, then block_move_after it into place.

One caution for anyone else hitting this: if the block_move_after anchor is itself a child of a callout, the moved blocks become children of that callout. The document still reads normally, so this is only visible via --detail full. Reversing it means moving the blocks back out using the callout itself as the anchor, listing every moved block ID in document order (ordered lists have no ID on <ol> — list each <li>).

Environment

• lark-cli 1.0.88 (behaviour first observed on 1.0.87)
• macOS, Node 22
• --as user, docx in a wiki space

Start with the docs +update handling for block_insert_after and compare its docs_ai request with the append path shown by --dry-run. Reproduce the h3, callout, and li cases, then inspect the bundled XML reference and error handling. Done means the h3 case works or its rule is documented, and invalid nesting names the parent and rejected element.