飞书演示文稿 XML 读取完整指南与 slides +xml-get 实操避坑

【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20+ AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli

飞书 CLI 怎么读取幻灯片 XML？lark-cli slides +xml-get 一条命令就能拿到整份演示文稿或单个页面的 SML（演示文稿标记语言）XML，输出形态有三种：JSON 信封、原始 XML、本地文件。它是创建后验证与写入后回读的标准工具，也是块级编辑的数据源头。

它解决什么痛点

如果你曾经生成 PPT 后一页页数一数、逐条核对内容，就知道这事又慢又容易漏。Slides 的自动化编辑不靠截图操作，而是建立在结构化 XML 上：整份文稿是<presentation>根节点加若干<slide>页面，页内每个形状、图片、表格都是带id属性的 XML 块。SML 用大白话说就是"把幻灯片结构写成文本"。读取这份 XML 是一切编辑的起点。

如果你曾经跑块级替换时因为找不到block_id报 3350001 错误，问题多半是没先读最新单页 XML。页面里每个顶层块的 3 位短 ID（比如bUn）只能从slides +xml-get拿到，乐观锁要用的当前revision_id也在同一份返回里。

如果你曾经整页回读写回后页面看起来没变、评论却全部失效，那是跳过去 id 检查的隐性代价。参数语义、互斥规则、读改写链路，下面一次讲完。

30 秒上手：第一条命令

最常用的形态是拉全文存本地文件。--output只接受当前目录内的相对路径，已存在的文件会被直接覆盖。成功时 stdout 只回path、size、content_saved: true、revision_id等元信息，完整 XML 落盘不外泄：

lark-cli slides +xml-get --as user \ --presentation "$PRES_ID" \ --output ".lark-slides/readback.xml"

这就是创建后、写入后必做的标准回读动作。

三种输出形态怎么选

90% 的场景用--output存本地文件。验证、版式 lint、整页写回都要处理文件，完整 XML 不占终端。

• 存本地文件（默认之选）：--output readback.xml，stdout 只回文件元信息。
• 原始 XML 直出 stdout：--raw原样打印，适合管道里 grep 元素 id；不能与--output、--jq、非 JSON 的--format同用。
• JSON 信封（默认）：把裸 XML 包一层标准 JSON 结构，全文在.data.xml_presentation.content，单页在.data.slide.content，版本号.data.revision_id可被--jq直接取走。

单页读取时在--presentation后加--slide-id（按页面 ID）或--slide-number（按 1 起始页码），二选一。顺带一提，--presentation传 wiki 链接时，CLI 会先调 wiki 节点接口解析出真实文稿 id，这一步需要wiki:node:read权限；返回的xml_presentation_id是解析后的 token，可能与入参不同。

参数里最容易踩的 4 个坑

这些校验都发生在请求发出之前，逻辑可以直接在slides_xml_get.go的Validate函数里看到。参数写错不会产生任何半成品副作用，放心先试后改。

1. 两个页面选择器同时传：--slide-id和--slide-number一起指定，直接校验报错，请求不发出去。原因是选择器二选一。正确写法：知道 id 用--slide-id，只知道位置用--slide-number，页码必须是正整数。

2. 版本号传了 -2：--revision-id -2直接报参数无效。版本号只接受-1（最新版）或非负整数。正确写法：拿不准就传-1；传了比当前 revision 大的版本号不在这步报错，而是后续写操作返回 3350002。

3. --output 写了目录外路径：--output ../readback.xml被拒，绝对路径同样被拒。路径必须能解析为当前工作目录内的相对路径。正确写法：用./开头或子目录路径。

4. ⚠️写回前用了 --remove-attr-id：去 id 后的 XML 写回，每个元素都会换新 id，锚在旧 id 上的评论和块直达链接全部静默失效，且没有任何报错。该参数仅限只读查看与脱敏，准备用于写回的回读一律不要加。

一条读-改-写的完整链路

乐观锁——你可以理解为"我基于第 7 版改的，如果服务端已经不是第 7 版就别写"。注意--revision-id只选择 base 快照，不构成严格比较与交换；要求"读后页面变了就不写"时，写入前再回读一次最新版比对。

1. 读最新单页 XML，从id属性里挑出要改的块的 3 位短 id：

lark-cli slides +xml-get --as user \ --presentation "$PRES_ID" --slide-id "$SID" --raw

2. 拿当前revision_id作为写操作的基础版本号。默认输出是 JSON 信封，--jq直接取单个字段：

REV=$(lark-cli slides +xml-get --as user \ --presentation "$PRES_ID" --slide-id "$SID" --jq '.data.revision_id')

3. 用+replace-slide改那个块，$REV作为 base 版本传入。replacement根元素的id会被 CLI 自动注入为block_id，不用自己写：

lark-cli slides +replace-slide --as user \ --presentation "$PRES_ID" --slide-id "$SID" --revision-id "$REV" \ --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'

4. 写入成功后别只信成功响应，回读全文存本地文件，核对页数与关键元素：

lark-cli slides +xml-get --as user \ --presentation "$PRES_ID" --output readback.xml

交付前自检清单

• 用 slides +xml-get 回读整份文稿 XML 到本地文件，不只信写接口的成功响应。
• 核对实际页数符合计划，没有空白页、破损页、缺失标题。
• 核对每页存在预期的主要元素，标题、主视觉、支撑信息三层可区分。
• 核对元素 id 没有被换掉，评论与块直达链接等锚点仍然有效。
• 核对写操作传入的revision_id与你读取的 base 版本一致。
• 对回读 XML 跑版式 lint，summary.error_count为 0 才允许交付。

如果你接下来要动手改某一块，直接跑+replace-slide，本文第 7 节的链路可以直接复用。

【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20+ AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli