@amaster.ai/pi-lark 0.1.7 → 0.1.8

package/skills/lark-slides/references/lark-slides-update-slide.md

@@ -0,0 +1,146 @@
+# slides +update-slide（整页更新已有页面）
+
+把一整页 XML 交给某个已有页面，页面变成 `--content` 描述的样子。`slide_id` 和页序都不变。
+
+## 命令
+
+```bash
+# 标准用法：整页 XML 从文件读（推荐：避免 shell 转义和长参数截断）
+lark-cli slides +update-slide --as user \
+  --presentation "https://xxx.larkoffice.com/slides/SCtZ...ynae" \
+  --slide-id "piy" \
+  --content @page.xml
+
+# XML 从 stdin 读
+cat page.xml | lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content -
+
+# wiki 链接直接传（CLI 自动解析并校验 obj_type=slides）
+lark-cli slides +update-slide --as user \
+  --presentation "https://xxx.larkoffice.com/wiki/wikcn..." \
+  --slide-id "piy" --content @page.xml
+
+# 预览请求，不实际写入
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content @page.xml --dry-run
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--slide-id` | 是 | 要整页替换的页面 `slide_id` |
+| `--content` | 是 | 这一页的完整目标 XML，单一 `<slide>` 根；支持字面量、`@file`、stdin `-`。别名：`--xml` / `--slide-xml` / `--slide-content` / `--content-xml` |
+| `--revision-id` | 否 | 默认 `-1`（最新）。它只选择服务端执行所基于的快照，不是“页面有新编辑就拒绝”的乐观锁；传旧版本号会以旧快照重建页面并丢弃其后的编辑 |
+| `--tid` | 否 | 调用方提供的任务/事务标识，CLI 原样透传；用于关联同一编辑任务或重试，不等同于版本前置条件，不能单独保证并发冲突时拒绝写入。一般留空 |
+
+`@file` 和 `+xml-get --output` 一样**只接受当前目录下的相对路径**，绝对路径会被拒。
+命令别名：`slides +update`（隐藏）；服务别名：`lark-cli slide …` 等价于 `lark-cli slides …`。
+
+如果要求“从读取之后页面一旦变化就不再写入”，不能只传 `--revision-id` 或 `--tid`。写入前必须再次用 `+xml-get` 回读最新版，比较读取期间是否发生变化；有变化时先基于最新版重新合并本次修改，再执行整页写回。当前 shortcut 不提供严格的 compare-and-swap 保证。
+
+## 语义：`--content` 就是这一页的最终状态
+
+**没写进 `--content` 的东西会从页面上消失。** 这不是补丁，是整页覆盖。
+
+| 你在 `--content` 里怎么写 | 页面上的结果 |
+|---|---|
+| 元素带原来的 `id` | 按新 XML 更新这个元素 |
+| 元素不带 `id` | 作为新元素插入到它所在的位置 |
+| 原来有、`--content` 里没有的元素 | **删除** |
+| `<style>` 改了 | 背景等页面样式跟着改 |
+| 没写 `<note>` | 讲者备注被清空 |
+
+一次请求就能同时做完改样式、插入、删除、换备注、换背景——这是 `+replace-slide` 逐元素 part 做不到的（它没法寻址背景，也没有 move 操作）。
+
+## 标准读-改-写流程
+
+```bash
+# 1. 读回当前页（拿到带 id 的完整 XML）
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --output page.xml
+
+# 2. 编辑 page.xml —— 保留想留下的元素的 id，删掉不要的整段，新元素不写 id
+
+# 3. 整页写回
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content @page.xml
+```
+
+先 `--dry-run` 看请求，确认无误再执行。
+
+> ⚠️ **第 1 步不要加 `--remove-attr-id`。** 那个参数会把所有元素的 `id` 去掉，再交给 `+update-slide` 的话，每个元素都会被当成新元素插入、原来的全部被删除——页面看起来一样，但所有元素换了新 id，锚在旧 id 上的评论和 block 直达链接全部失效，而且**不会有任何报错**。`--remove-attr-id` 只用于只读查看。
+
+## 命令校验与空页限制
+
+| 情况 | 报错 |
+|---|---|
+| 根元素不是 `<slide>`（例如直接给了 `<shape>`） | `--content root must be <slide>` → 改单个元素请用 `+replace-slide` |
+| 根 `id` 和 `--slide-id` 不一致 | 拒绝。这通常是 A 页的 XML 要写到 B 页 —— 会毁掉 B 页 |
+| 根 `id` 缺失 | 自动补上 `--slide-id`，不报错 |
+| 根标签带命名空间前缀（`<sml:slide>`） | 拒绝。页面 id 没法贴到带前缀的标签上；写成 `<slide>`，需要命名空间就用默认 `xmlns` |
+| `<slide>` 之后还有第二个根元素或多余文本 | 拒绝。服务端解析会静默丢掉它们 |
+| XML 不合法 | 拒绝，带上出错位置 |
+| `<slide/>`（自闭合，空页） | 命令本身可以解析，但提交前的强制版式 lint 会报 `blank_slide`；按本 Skill 不得调用接口提交空页 |
+
+标为“拒绝”的情况由命令校验拦截，**不会发出任何请求**；空页则必须在调用命令前由强制版式 lint 拦截。
+
+## 什么时候不要用它
+
+- **只改一个元素** → 用 [`+replace-slide`](lark-slides-replace-slide.md)，一条 `block_replace` part 更省，也不用带上整页
+- **要改多个页面** → 对每一页各跑一次本命令
+- **要新建页面** → `slides +create` 或 `xml_presentation.slide create`
+
+## 提交前与写入后验证
+
+和其他整页写入一样，把 `--content` 存成本地文件后先跑版式 lint。先取得当前已加载 `lark-slides/SKILL.md` 的父目录，记为 `<lark-slides-skill-dir>`；不要猜测全局安装路径：
+
+```bash
+python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input page.xml
+```
+
+`summary.error_count` 必须为 0 才调接口；`warning_count > 0` 时写完要截图复核。
+
+写入成功后，必须回读整份演示文稿的最新 XML，而不是只相信写接口的成功响应：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES" --output readback.xml
+```
+
+按当前已加载 `lark-slides/SKILL.md` 指向的 [validation-checklist.md](validation-checklist.md) 完成验证：核对总页数、目标页和关键元素（包括需要保留的 ID、文本、背景与备注），并对回读 XML 运行同一版式 lint；发现差异时先停止后续写入并重新基于最新版处理。
+
+## 成功输出
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "slide_id": "piy",
+    "revision_id": 43
+  }
+}
+```
+
+| `data` 下的字段 | 说明 |
+|------|------|
+| `xml_presentation_id` | 实际写入的演示文稿 ID |
+| `slide_id` | 与传入相同——整页覆盖不换页 id |
+| `revision_id` | 写入后的新版本号 |
+
+服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。
+
+- 原因包含 `not found`：先检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID。页面可能已删除，或 ID 来自另一份演示文稿。
+- 其他 invalid-parameter 错误：检查 `--content` 中不支持的元素、缺少 `<content/>` 的 `<shape>`，以及超出 960×540 的坐标。
+
+## 常见错误
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID |
+| 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [troubleshooting.md](troubleshooting.md) 检查 `--content` 的 XML 结构 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

package/skills/lark-slides/references/lark-slides-xml-presentations-get.md

@@ -2,13 +2,12 @@
 
 ## 用途
 
-读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
+读取飞书幻灯片（PPT）的完整演示文稿 XML，或通过 `--slide-id` / `--slide-number` 读取指定单页 XML。
 
 ## Shortcut
 
 使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
 
-
 ```bash
 lark-cli slides +xml-get --as user \
   --presentation "slides_example_presentation_id" \
@@ -22,9 +21,12 @@ lark-cli slides +xml-get --as user \
 |------|------|------|------|
 | `--presentation` | string | 是 | 演示文稿的唯一标识符 |
 | `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
-| `--output` | string | 是 | 本地文件，必须使用相对路径 |
-| `--remove-attr-id` | flag | 否 | 移除 XML id 属性后读取 |
-| `--json` | flag | 是 | 必须按照 json 格式输出 |
+| `--output` | string | 否 | XML 保存路径，必须使用相对路径；省略时 XML 在 stdout 的 JSON envelope 中返回 |
+| `--raw` | flag | 否 | 直接把 XML 输出到 stdout，不包 JSON envelope；不能与 `--output`、`--jq` 或非 JSON `--format` 同时使用 |
+| `--slide-id` | string | 否 | 只读取指定 `slide_id` 的单页 XML；不能与 `--slide-number` 或 `--remove-attr-id` 同时使用 |
+| `--slide-number` | integer | 否 | 只读取指定的 1-based 页码；不能与 `--slide-id` 或 `--remove-attr-id` 同时使用 |
+| `--remove-attr-id` | flag | 否 | 仅全文读取可用；移除 XML id 属性后读取，不适合后续精确块编辑 |
+| `--json` | flag | 否 | `--format json` 的简写，json 为默认输出格式 |
 
 
 ### 基础示例
@@ -36,6 +38,27 @@ lark-cli slides +xml-get --as user \
   --json
 ```
 
+### 读取单页并保存
+
+按页面 ID 和按页码二选一：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-id "slide_example_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/slide.xml \
+  --json
+```
+
+### 直接输出 XML 到管道
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-number 1 \
+  --raw
+```
+
 ### 指定版本读取
 
 ```bash
@@ -96,7 +119,7 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
     "xml_presentation": {
       "presentation_id": "slides_example_presentation_id",
       "revision_id": 1,
-      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
+      "content": "<presentation xmlns=\"https://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
     }
   }
 }
@@ -130,5 +153,5 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ## 相关命令
 
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
-- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [slides +add-slide](lark-slides-add-slide.md) - 添加幻灯片页面
+- [slides +delete-slide](lark-slides-delete-slide.md) - 删除幻灯片页面

package/skills/lark-slides/references/slides_chart_demo.xml

@@ -1,5 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>原生图表 Chart Demo</title>
   <theme>
     <textStyles>

package/skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
-        xmlns:sml="http://www.larkoffice.com/sml/2.0"
-        targetNamespace="http://www.larkoffice.com/sml/2.0"
+        xmlns:sml="https://www.larkoffice.com/sml/2.0"
+        targetNamespace="https://www.larkoffice.com/sml/2.0"
         elementFormDefault="qualified"
         attributeFormDefault="unqualified">
     <xs:annotation>
@@ -11,7 +11,7 @@
 
             版本信息：
             - Schema 版本: 2.0.0
-            - 命名空间: http://www.larkoffice.com/sml/2.0
+            - 命名空间: https://www.larkoffice.com/sml/2.0
             - 发布日期: 2025-11-03
         </xs:documentation>
     </xs:annotation>
@@ -1052,7 +1052,7 @@
                 单页幻灯片结构
                 子元素:
                 - style: 页面样式(背景色等), style的fill默认颜色为白色rgba(255, 255, 255, 1)
-                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined)
+                - data: 页面元素容器(shape/line/polyline/img/table/icon/embed/chart/undefined)
                 - note: 演讲者备注
             </xs:documentation>
         </xs:annotation>
@@ -1076,6 +1076,7 @@
                         <xs:element ref="sml:img"/>
                         <xs:element ref="sml:table"/>
                         <xs:element ref="sml:icon"/>
+                        <xs:element ref="sml:embed"/>
                         <xs:element ref="sml:chart"/>
                         <xs:element ref="sml:undefined"/>
                     </xs:choice>
@@ -1622,6 +1623,49 @@
         </xs:complexType>
     </xs:element>
 
+    <!-- 嵌入内容元素 -->
+    <xs:element name="embed">
+        <xs:annotation>
+            <xs:documentation>
+                嵌入内容容器, 外层承载 Slides 摆放和效果属性, 内层承载外部标准内容。
+                当前内层内容为标准 SVG, 必须使用 http://www.w3.org/2000/svg 命名空间。
+                后续可扩展承载 HTML 等其他外部内容。
+
+                必需属性:
+                - topLeftX/topLeftY: 左上角坐标
+                - width/height: 显示尺寸
+
+                可选属性:
+                - id: 唯一标识符
+                - rotation: 旋转角度[0, 360)
+                - flipX/flipY: 水平/垂直翻转
+                - alpha: 不透明度[0,1]
+
+                子元素:
+                - svg: 标准 SVG 根元素, 仅描述嵌入内容, 不承载 Slides 布局属性
+                - reflection: 倒影样式, 无reflection标签代表无倒影, 空reflection标签代表使用默认样式
+                - shadow: 阴影样式, 无shadow标签代表无阴影, 空shadow标签代表使用默认样式
+            </xs:documentation>
+        </xs:annotation>
+        <xs:complexType>
+            <xs:sequence>
+                <xs:any namespace="http://www.w3.org/2000/svg" processContents="lax" minOccurs="1" maxOccurs="1"/>
+                <xs:element name="reflection" type="sml:ReflectionType" minOccurs="0"/>
+                <xs:element name="shadow" type="sml:ShadowType" minOccurs="0"/>
+            </xs:sequence>
+
+            <xs:attribute name="id" type="xs:string" use="optional"/>
+            <xs:attribute name="topLeftX" type="sml:XType" use="required"/>
+            <xs:attribute name="topLeftY" type="sml:YType" use="required"/>
+            <xs:attribute name="width" type="sml:PositiveSize" use="required"/>
+            <xs:attribute name="height" type="sml:PositiveSize" use="required"/>
+            <xs:attribute name="rotation" type="sml:RotationType" use="optional" default="0"/>
+            <xs:attribute name="flipX" type="xs:boolean" use="optional" default="false"/>
+            <xs:attribute name="flipY" type="xs:boolean" use="optional" default="false"/>
+            <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
+        </xs:complexType>
+    </xs:element>
+
     <!-- 表格元素 -->
     <xs:element name="table">
         <xs:annotation>

package/skills/lark-slides/references/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
+本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`。
 
 ## XML Preflight
 
@@ -9,7 +9,7 @@
 - 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
 - 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
 - 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
-- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
+- 图片路径正确：`<img src="@...">` 占位符由 `+create` 和 `+add-slide` 处理。
 
 ## Failure Order
 
@@ -20,8 +20,8 @@
 3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
 5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 `xml_text_overlap_lint.py`；先修复所有 `error`，再对 `warning` 指向的页面和元素做截图复核。
-6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
+6. 如果使用 `--slides '[...]'` 字面量，怀疑 shell 转义或截断时改用文件输入：`+create --slide @page-01.xml --slide @page-02.xml`。
+7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时用 `+delete-slide` 删旧页 + `+add-slide` 建新页。
 
 ## Symptom Fixes
 
@@ -34,7 +34,7 @@
 | 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符由 `+create` 和 `+add-slide` 替换 |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
 | 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
@@ -45,11 +45,10 @@
 |--------------|------|----------|
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
-| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
+| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 字面量的 shell 转义或长参数传递问题 | 改用 `--slide @file`（每页一个文件）或 `--slides @deck.json`，并在创建后立即读取 XML 验证 |
 | 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
-| 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
 | 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
 | 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
@@ -60,4 +59,4 @@
 
 - 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](lark-slides-media-upload.md) 和 [lark-slides-create.md](lark-slides-create.md)。
 - 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。
-- 原生 `slide.create` 包装、`before_slide_id` 和 jq 模板：见 [lark-slides-xml-presentation-slide-create.md](lark-slides-xml-presentation-slide-create.md)。
+- 追加/插入单页、`--before-slide-id` 和 `--slide @file` 绕开转义：见 [lark-slides-add-slide.md](lark-slides-add-slide.md)。

package/skills/lark-slides/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建、大幅改写演示文稿或每次通过 `slides +update-slide` 整页写回后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 
@@ -47,7 +47,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 - `element_ids`：相关 XML 元素 ID；
 - `rule`：规则 ID、名称、阈值和比较关系；
 - `measurement`：越界量、交叠面积、覆盖率等实测值；
-- `related_objects`：相关对象的类型与坐标框；
+- `related_objects`：相关对象的类型、坐标框，以及指向当前输入 XML 节点的 XPath-like `xml_path`；
 - `target`、`message`、`hint`：页码、语义说明和处理建议。
 
 当 `sparse_container_content.measurement.content_coverage_ratio < rule.threshold` 时，需要结合同页截图判断留白是否有意设计；不要仅凭 warning 自动扩充内容。
@@ -57,7 +57,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 | code | 含义 | 处理方式 |
 |------|------|----------|
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
-| `sml_prefixed_tag` | SML 元素使用了命名空间前缀，如 `<ns0:slide>` 或 `<sml:shape>` | 使用 `<slide xmlns="http://www.larkoffice.com/sml/2.0">` 的默认命名空间，或使用无前缀标签 |
+| `sml_prefixed_tag` | SML 元素使用了命名空间前缀，如 `<ns0:slide>` 或 `<sml:shape>` | 使用 `<slide xmlns="https://www.larkoffice.com/sml/2.0">` 的默认命名空间，或使用无前缀标签 |
 | `sxsd_unsupported_tag` | 使用了 SXSD 不支持的标签 | 按 lint `hint` 替换为受支持标签；常见如 `textbox -> <shape type="text">`、`image -> <img>` |
 | `sxsd_unsupported_attr` | 支持的标签上使用了不支持的属性 | 按 lint `hint` 改为支持的属性；常见如 `x -> topLeftX`、`fontColor -> color` |
 | `iconpark_unsupported_icon_type` | `<icon>` 使用了 `iconpark-index.json` 中不存在的 `iconType` | 按 lint `hint` 改为名单内的 `iconType`，或先用 `scripts/iconpark_tool.py` 搜索 |
@@ -66,7 +66,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
 | `*_out_of_canvas` | 元素边界超出页面画布 | 根据 `measurement.overflow` 移回画布或缩小尺寸 |
 | `blank_slide` | 页面没有画布内可见内容 | 补充主体内容；仅有空背景或空形状不能准出 |
-| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按元素 ID 定位卡片，结合截图判断是否补充或放大内容 |
+| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按 `related_objects[].xml_path` 定位卡片；`element_id` 存在且唯一时也可按 ID 定位，再结合截图判断是否补充或放大内容 |
 | `sparse_slide_content` | 全页有效内容覆盖率偏低 | 复核截图，确认是否为有意留白 |
 
 ## Screenshot QA

package/skills/lark-slides/references/xml-schema-quick-ref.md

@@ -4,7 +4,7 @@
 
 ## 最重要的规则
 
-1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+1. 协议标准写法应使用 `<presentation xmlns="https://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
@@ -12,8 +12,7 @@
 ## 最小可用示例
 
 ```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <slide>
     <data>
       <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
@@ -81,7 +80,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 **子元素：**
 
 - `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`embed`、`chart`、`undefined`
 - `<note>?` - 演讲者备注，内部可放 `<content>`
 
 这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
@@ -227,17 +226,17 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ### img
 
 ```xml
-<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
+<img src="file_token_或_@本地路径" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
 `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
 
-`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
+`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（`+create --slides` 和 `+add-slide` 会自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
 本地图片的两种姿势：
 
 - 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
-- 给已有 PPT 加带图新页：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+- 给已有 PPT 加带图新页：`+add-slide --slide` 的 XML 里直接写 `src="@./pic.png"`，CLI 上传后替换 token 再提交页面
 
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
 
@@ -355,6 +354,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
 
+### embed
+
+嵌入内容容器：外层 `<embed>` 承载 Slides 的摆放和效果属性（`topLeftX`/`topLeftY`/`width`/`height` 必填，`rotation`/`flipX`/`flipY`/`alpha` 可选），内层承载外部标准内容。当前内层内容为标准 SVG，`<svg>` 必须使用 `http://www.w3.org/2000/svg` 命名空间，且仅描述嵌入内容本身，不承载 Slides 布局属性。
+
+```xml
+<embed topLeftX="80" topLeftY="120" width="200" height="120">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 120">
+    <circle cx="100" cy="60" r="40" fill="rgba(37, 99, 235, 1)"/>
+  </svg>
+</embed>
+```
+
+`<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。
+
 ## 颜色与样式
 
 ### fill
@@ -417,8 +430,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## 完整示例
 
 ```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>季度报告</title>
   <theme>
     <textStyles>
@@ -466,7 +478,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ## 最佳实践
 
-1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+1. 始终带上命名空间 `xmlns="https://www.larkoffice.com/sml/2.0"`
 2. 用 `shape type="text"` + `content` 表达页面文本
 3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
 4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点
@@ -481,5 +493,5 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## Schema 版本信息
 
 - **版本**: 2.0.0
-- **命名空间**: http://www.larkoffice.com/sml/2.0
+- **命名空间**: https://www.larkoffice.com/sml/2.0
 - **发布日期**: 2025-11-03