docs +update: `<img src="token">` is silently dropped on append, but the bundled skill docs advertise it

Summary

docs +update --command append silently drops <img src="token"/> elements. The call returns success, no error and no warning, and the images are simply absent from the resulting document.

This directly contradicts the skill documentation that ships with the CLI, which advertises <img src="token"/> as a supported way to reuse an image that already exists elsewhere.

What the bundled docs promise

~/.agents/skills/lark-doc/references/lark-doc-xml.md, line 14 (shipped with 1.0.88):

<img path="@./photo.png"/>：上传当前工作目录内的本地图片。也可用 <img href="URL"/> 上传公开 HTTP(S) 网络图片，或用 <img src="token"/> 复制原始图片；三者任选一个，可选 width、height、caption、name。

What actually happens

Observed on 1.0.87 (2026-08-18) while rewriting a long docx:

• One append call containing 4 <img src="…"/> elements alongside normal paragraphs.
• Response: success.
• Reading the document back with docs +fetch --detail full: zero images, and the block count was short by exactly 4.
• No error, no warning, no degrade_code.
• Replacing them with <img path="@./x.png"/> uploaded correctly, so the surrounding XML was fine.

Where the content is lost

The CLI is not the one dropping it. On 1.0.88, --dry-run shows the XML is forwarded verbatim:

$ lark-cli docs +update --doc "<doc>" --as user --command append \
    --content '<p>before</p><img src="<token>"/><p>after</p>' --dry-run

{
  "data": {
    "api": [{
      "desc": "OpenAPI: update document",
      "method": "PUT",
      "url": "/open-apis/docs_ai/v1/documents/<doc>",
      "body": {
        "block_id": "-1",
        "command": "block_insert_after",
        "content": "<p>before</p><img src=\"<token>\"/><p>after</p>",
        "format": "xml",
        "revision_id": -1
      }
    }]
  }
}

So the <img src> element reaches docs_ai intact and is discarded there. I have not re-run the write path on 1.0.88, but the CLI-side behaviour is unchanged and the 1.0.88 skill docs still advertise the syntax, so I would expect the same result.

Why this is worse than a plain error

The failure is silent and partial. A single append that mixes text and images returns success while quietly losing only the images, so any script that checks the return value believes it worked. It is only visible by re-fetching with --detail full and counting blocks.

Expected behaviour

Any one of these would resolve it:

1. docs_ai honours <img src="token"/> as documented, or
2. the CLI rejects <img src> up front with a clear validation error, or
3. the response carries a degrade_code naming the dropped elements, or
4. the bundled skill docs stop advertising <img src>.

Option 3 alone would already prevent silent data loss.

Workaround

block_copy_insert_after does copy image blocks, and the bundled docs confirm it (lark-doc-update.md, line 69):

block_copy_insert_after|按 ID 顺序复制源 block，源 block 不变；基础标签均支持，资源块仅支持 img、source、whiteboard、sheet、chat_card、sub-page-list

So the reliable way to reuse an existing image is to copy its block by ID rather than to reference its token in XML.

Environment

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

Start by reproducing the append command with the documented syntax, then compare its dry-run output with docs +fetch --detail full. Read the bundled references/lark-doc-xml.md and lark-doc-update.md documentation and inspect the append handling or validation path. Done means the syntax is handled, rejected clearly, or documented as unsupported without silently losing image blocks.