@amaster.ai/pi-lark 0.1.5 → 0.1.6

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

@@ -2,6 +2,8 @@
 
 `<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
 
+普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
+
 > 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
 
 ---
@@ -12,13 +14,13 @@
 
 | 场景 | 推荐元素 |
 |------|---------|
-| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
-| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持）或其他非原生数据视觉 | `<whiteboard>` SVG |
 | 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
 | 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
 | 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
 
-> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
 
 ---
 
@@ -39,9 +41,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ## SVG 还是 Mermaid？
 
-选择分两步：**先看图表类型，再看当前模型身份**。
+选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
+
+### 第一步：先确认是否应该使用 `<chart>`
 
-### 第一步：图表类型优先判断
+如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
+
+### 第二步：whiteboard 类型优先判断
 
 以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
 
@@ -50,20 +56,19 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 | 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
 | 时序图 | `sequenceDiagram` |
 | 类图 | `classDiagram` |
-| 饼图 | `pie` |
 | 甘特图 | `gantt` |
 | 状态图 | `stateDiagram-v2` |
 | 思维导图 | `mindmap` |
 | ER 图 | `erDiagram` |
 
-### 第二步：数据图表与装饰元素按模型身份选路径
+### 第三步：非原生图表与装饰元素按模型身份选路径
 
 上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
 
 | 模型身份 | 路径 |
 |----------|------|
 | Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
 
 > **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
 
@@ -73,13 +78,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ### ⚠️ 设计品质要求
 
-在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
+在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
 
 - **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
+- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
 - **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
 - **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
-- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距
 - **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
 - **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
 
@@ -106,11 +111,11 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 
 | 元素 | 说明 | 典型用途 |
 |------|------|---------|
-| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
+| `<rect>` | 矩形，支持 `rx` 圆角 | 卡片、进度条、分段色块 |
 | `<circle>` | 圆 | 节点、装饰点、环形图 |
 | `<ellipse>` | 椭圆 | 自定义轮廓图形 |
-| `<line>` | 直线 | 坐标轴、分隔线 |
-| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
+| `<line>` | 直线 | 轴线、分隔线、连接线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、曲线、弧形 |
 | `<text>` | 文本，支持中文 | 标签、数值 |
 | `<polygon>` | 多边形 | 箭头、星形、面积填充 |
 | `<g>` | 分组 | 批量变换、语义分组 |
@@ -123,27 +128,25 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 ---
 ### 元素计算
 
-SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
 
 > **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
 
-**数据图表（柱状图范式）**
+**散点图 / 装饰性点阵范式**
 
 ```python
 W, H = 360, 260
 origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
 cw, ch = 290, 184
 
-data, y_max = [120, 160, 90], 200
-bar_w = int(cw / len(data) * 0.62)
-for i, v in enumerate(data):
-    cx = round(origin_x + (i + 0.5) * cw / len(data))
-    y  = round(origin_y - v / y_max * ch)
-    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
+points = [(12, 40), (28, 80), (45, 65)]
+x_min, x_max, y_min, y_max = 0, 50, 0, 100
+for i, (xv, yv) in enumerate(points):
+    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
+    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
+    print(f"point-{i}: cx={x} cy={y}")
 ```
 
-折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
-
 **装饰性元素（等间距范式）**
 
 ```python
@@ -160,9 +163,9 @@ for i in range(n):
 ```python
 # 每个元素登记 (x, y, w, h)，含 stroke 外扩
 elements = [
-    (10, 20, 80, 160),   # bar-0
-    (107, 10, 80, 170),  # bar-1
-    (204, 40, 80, 140),  # bar-2
+    (10, 20, 80, 160),   # item-0
+    (107, 10, 80, 170),  # item-1
+    (204, 40, 80, 140),  # item-2
     (0, 0, 300, 1),      # x-axis
 ]
 
@@ -261,7 +264,6 @@ print(f"whiteboard width={wb_w} height={wb_h}")
 | 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
 | 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
 | 甘特图 | `gantt` | 项目计划、里程碑 |
-| 饼图 | `pie` | 占比数据 |
 | 类图 | `classDiagram` | 对象关系、架构设计 |
 | ER 图 | `erDiagram` | 数据库结构 |
 | 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
@@ -279,7 +281,6 @@ Mermaid 图表会自动撑满 whiteboard 区域。建议：
 |---------|-----------|------------|
 | 流程图（5-8 节点） | 720-816 | 300-400 |
 | 时序图（3-5 参与者） | 720-816 | 320-420 |
-| 饼图 | 500-600 | 300-360 |
 | 甘特图 | 816 | 280-360 |
 | 思维导图 | 816 | 380-480 |
 
@@ -307,7 +308,7 @@ Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解
 - [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
 
 **SVG 模式——视觉品质检查：**
-- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
+- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明，没有"裸点"或无解释色块
 - [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
 - [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
 - [ ] 轴标签与图表元素互不遮挡，留有足够空间

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

@@ -0,0 +1,100 @@
+# slides +xml-get（读取 XML）
+
+读取已有演示文稿的完整 XML，或按 `slide_id` / 页码读取单页 XML。适合创建后验收、编辑前备份、获取 `slide_id` / `revision_id`，以及排查空白页、破图、文本溢出等问题。相比直接调用底层 `xml_presentations.get` / `xml_presentation.slide.get`，本 shortcut 会自动解析 Slides URL / Wiki URL，并可把 XML 保存到本地文件，避免终端输出被截断。
+
+## 命令
+
+
+```bash
+lark-cli slides +xml-get \
+  --as user \
+  --presentation <slides_url_or_xml_presentation_id> \
+  --output .lark-slides/plan/<deck-id>/readback.xml
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--output` | 否 | 本地 XML 保存路径，必须是当前工作目录内的相对路径，不能传绝对路径。传入时 XML 内容保存到文件，stdout 只返回保存后的绝对路径、大小等简短元信息；省略时默认返回 JSON envelope |
+| `--slide-id` | 否 | 页面 short ID；传入后只读取该页 XML。不能和 `--slide-number` 同时使用 |
+| `--slide-number` | 否 | 1-based 页码；传入后只读取该页 XML。不能和 `--slide-id` 同时使用 |
+| `--revision-id` | 否 | 读取指定版本；默认 `-1`，表示最新版本 |
+| `--remove-attr-id` | 否 | 仅全文读取可用。移除返回 XML 中的 `id` 属性；适合只读检查，不适合精确块级编辑 |
+| `--raw` | 否 | 省略 `--output` 时直接把 XML 原文写到 stdout，不包 JSON envelope。不能和 `--output` / `--jq` / 非 json `--format` 同时使用 |
+| `--dry-run` | 否 | 预览将调用的 API 和输出方式，不读取真实 XML |
+
+## 输出到文件
+
+推荐普通工作流都传 `--output`，尤其是中大型 PPT。`--output` 必须是当前工作目录内的相对路径，例如 `.lark-slides/plan/$PID/readback.xml`，不要传 `/tmp/readback.xml` 这类绝对路径。XML 会写入本地文件，stdout 只保留元信息，便于后续脚本读取。
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --output .lark-slides/plan/$PID/readback.xml
+```
+
+成功输出中的 `data` 类似：
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "path": "/abs/path/.lark-slides/plan/slides_example_presentation_id/readback.xml",
+  "size": 123456,
+  "content_saved": true,
+  "revision_id": 12
+}
+```
+
+其中 `path` 是 CLI 解析后的绝对路径。
+
+如果传入 `--remove-attr-id`，返回元信息中会包含 `"remove_attr_id": true`。
+
+## 读取单页
+
+已知页面 short ID 时，用 `--slide-id`：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-id "$SID" \
+  --output .lark-slides/plan/$PID/slide-$SID.xml
+```
+
+已知页码时，用 `--slide-number`（页码从 1 开始）：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-number 2 \
+  --output .lark-slides/plan/$PID/slide-2.xml
+```
+
+单页模式底层调用 `xml_presentation.slide.get`，返回或保存的是单个 `<slide>` XML 片段。`--slide-id` 和 `--slide-number` 不能同时传；`--remove-attr-id` 只支持全文读取。
+
+## 输出到终端
+
+省略 `--output` 时，CLI 默认输出 JSON envelope，XML 位于 `data.xml_presentation.content`（全文）或 `data.slide.content`（单页）。这个模式适合配合 `--jq` 临时提取：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --jq '.data.xml_presentation.content'
+```
+
+需要把 XML 原文直接写到 stdout 时，加 `--raw`：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-number 2 \
+  --raw
+```
+
+## 相关命令
+
+- [slides +screenshot](lark-slides-screenshot.md) - 获取页面截图做视觉验证
+- [slides +replace-slide](lark-slides-replace-slide.md) - 局部替换或插入页面元素
+- [slides +replace-pages](lark-slides-replace-pages.md) - 多页整页重建
+- [xml_presentations get](lark-slides-xml-presentations-get.md) - 底层原生 API 参考

package/skills/lark-slides/references/lark-slides-xml-presentation-slide-delete.md

@@ -49,7 +49,10 @@ lark-cli slides xml_presentation.slide delete --as user --params '{
 
 ```bash
 # 先读取 XML 内容，确认待删除页面
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 
 # 然后按已知 slide_id 删除
 lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}'
@@ -61,11 +64,11 @@ lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presenta
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "revision_id": 100
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -118,6 +121,5 @@ done
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
+- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
+- [slides +xml-get](lark-slides-xml-get.md) - 读取 PPT 内容并保存到本地文件

package/skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md

@@ -65,15 +65,15 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "slide": {
       "slide_id": "slide_example_id",
       "content": "<slide id=\"slide_example_id\"><style/><data>...</data></slide>"
     },
     "revision_id": 100
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -106,5 +106,5 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读整个 PPT
+- [slides +xml-get](lark-slides-xml-get.md) — 读整个 PPT 并保存到本地文件
 - [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环

package/skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md

@@ -130,24 +130,28 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "revision_id": 105
-  },
-  "msg": "success"
+  }
 }
 ```
 
 ### 失败（任一 part 失败，整批不生效）
 
-失败时返回非零错误码（如 3350001）。若后端能定位失败的 part，`data` 中可能附带：
+失败时命令以非零退出码结束，stderr 返回类型化错误信封（`error.code`（如 3350001）/ `error.message` / `error.hint`），stdout 不会打印后端原始响应：
 
 ```json
 {
-  "code": 3350001,
-  "data": {
-    "failed_part_index": 0,
-    "failed_reason": "block not found"
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "api",
+    "subtype": "...",
+    "code": 3350001,
+    "message": "...",
+    "hint": "..."
   }
 }
 ```
@@ -155,8 +159,6 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `data.revision_id` | integer | 成功时返回更新后最新版本号 |
-| `data.failed_part_index` | integer | 失败的 part 在 `parts` 数组中的索引（从 0 起） |
-| `data.failed_reason` | string | 失败原因 |
 
 ## 常见错误
 

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

@@ -4,7 +4,7 @@
 
 读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
 
-## 命令
+## 底层原生命令形态
 
 ```bash
 lark-cli slides xml_presentations get --as user --params '<json_params>'
@@ -35,19 +35,22 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ### 基础示例
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}'
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1}'
 ```
 
-### 结合 jq 格式化输出
+### 指定版本读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":10}'
 ```
 
-### 保存到文件
+### 移除 XML id 属性后读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' > presentation_data.json
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1,"remove_attr_id":true}'
 ```
 
 ## 返回值
@@ -56,15 +59,15 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "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>"
     }
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -86,13 +89,11 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 ## 注意事项
 
-1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
+1. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
 2. 返回的 XML 在 `data.xml_presentation.content` 字段中
 3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
-4. 建议将获取的 XML 保存为文件，便于后续编辑或备份
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
+- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面

package/skills/lark-slides/references/planning-layer.md

@@ -12,7 +12,7 @@
 4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 5. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
 6. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
-7. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
 
 ## Plan Path
 
@@ -119,6 +119,34 @@ Each slide must include:
 - `text_density`: `low`, `medium`, or `high`.
 - `speaker_intent`: why the speaker needs this page and how it advances the story.
 
+Optional slide fields:
+
+- `chart_contract`: required when the page plan includes a standard data chart that `<chart>` supports. Use this shape:
+
+```json
+{
+  "chart_contract": {
+    "required": true,
+    "render_as": "native_chart",
+    "chart_type": "line",
+    "data_source": "mock_placeholder",
+    "data_series_required": true,
+    "placeholder_label_required": true,
+    "manual_shape_fallback_allowed": false
+  }
+}
+```
+
+When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, polyline, or whiteboard approximation does not satisfy the plan.
+
+`data_source` must be one of:
+
+- `user_provided`: the user supplied concrete values, tables, CSV, or metric lists; use them and do not replace them with mock data.
+- `mock_placeholder`: the user asked for a placeholder, template, example, or later-replaceable chart position; use mock data in native `<chart>`.
+- `mock_required_by_intent`: the user did not provide concrete values but asked for data expression, charts, trends, comparisons, or distributions; use mock data in native `<chart>`.
+
+`data_series_required` means the generated XML must include `<chartData>`. It does not require user-provided real-world values. When real values are unavailable but chart expression is part of the user's intent, write mock or placeholder values into native `<chart>` and label them clearly instead of switching to manual drawing primitives or metric blocks.
+
 ## Layout Vocabulary
 
 Use one of these `layout_type` values unless the user explicitly needs a custom structure:
@@ -183,6 +211,7 @@ Use an object for one planned asset, an array for multiple real needs, or `asset
 - `purpose`: why this asset helps the page's key message.
 - `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
 - `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.
+- `chart_contract`: when `asset_type` is `chart` and the visual is a supported standard data chart, set this optional slide-level field so generation is locked to native `<chart>`.
 
 For detailed rules and examples, read `asset-planning.md`.
 
@@ -190,7 +219,7 @@ Good examples:
 
 - `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
 - `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
-- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`
+- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Render a native `<chart>` using the provided series when available; otherwise render a native `<chart>` with mock placeholder values and label it as 模拟数据，仅占位，待替换真实数据."}`
 
 ## XML Generation Contract
 
@@ -201,6 +230,7 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `visual_focus` determines the largest visual region or emphasized object.
 - `text_density` caps visible text volume.
 - `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+- `chart_contract` locks supported standard data charts to native `<chart>` output. Manual approximations are allowed only when the planned chart type is unsupported by `<chart>` or when the visual is explicitly non-data/decorative.
 
 After creating the PPT, fetch the presentation and verify: