From cc4e3c3eefc49f2e6223c5747f620fea7c6fe173 Mon Sep 17 00:00:00 2001 From: zhanghuanxu Date: Thu, 2 Jul 2026 13:04:40 +0800 Subject: [PATCH] refactor(slides):create slide and edit ppt template --- skills/lark-slides/SKILL.md | 314 +++++---------- .../lark-slides/references/asset-planning.md | 124 ------ skills/lark-slides/references/design-rules.md | 155 ++++++++ ...=> lark-slides-block-replace-workflows.md} | 0 .../lark-slides-create-workflows.md | 266 +++++++++++++ .../lark-slides-pptx-template-workflows.md | 77 ++++ .../references/lark-slides-replace-slide.md | 2 +- ...rk-slides-xml-presentation-slide-create.md | 5 +- .../lark-slides-xml-presentation-slide-get.md | 2 +- ...k-slides-xml-presentation-slide-replace.md | 2 +- .../lark-slides/references/planning-layer.md | 216 ---------- .../references/slides_template_workflow.md | 64 +++ .../references/validation-checklist.md | 6 +- .../lark-slides/references/visual-planning.md | 254 ------------ .../references/xml-format-guide.md | 369 ------------------ .../references/xml-schema-quick-ref.md | 44 ++- 16 files changed, 713 insertions(+), 1187 deletions(-) delete mode 100644 skills/lark-slides/references/asset-planning.md create mode 100644 skills/lark-slides/references/design-rules.md rename skills/lark-slides/references/{lark-slides-edit-workflows.md => lark-slides-block-replace-workflows.md} (100%) create mode 100644 skills/lark-slides/references/lark-slides-create-workflows.md create mode 100644 skills/lark-slides/references/lark-slides-pptx-template-workflows.md delete mode 100644 skills/lark-slides/references/planning-layer.md create mode 100644 skills/lark-slides/references/slides_template_workflow.md delete mode 100644 skills/lark-slides/references/visual-planning.md delete mode 100644 skills/lark-slides/references/xml-format-guide.md diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 0bab0dbe0..f43130548 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -4,7 +4,7 @@ version: 1.0.0 description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、云文档里的独立画板对象（走 lark-whiteboard，注意 slide 内嵌的流程图/架构图仍属本 skill）、上传或下载普通文件（走 lark-drive）。" metadata: requires: - bins: ["lark-cli"] + bins: [ "lark-cli" ] cliHelp: "lark-cli slides --help" --- @@ -12,201 +12,36 @@ metadata: ## Quick Reference -| 用户需求 | 优先动作 | 关键文档 / 命令 | -|----------|----------|-----------------| -| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` | -| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` | -| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` | -| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` | -| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` | -| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 | -| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `` 元素 | `xml-schema-quick-ref.md` | -| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) | -| 使用语义图标 | 先检索 IconPark，再写 `` | `iconpark_tool.py search → resolve`、`iconpark.md` | -| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | +| 用户需求 | 指引 | +|----------|------| +| 读取 / 分析本地 PPTX 内容 | 文本用 `python -m markitdown presentation.pptx`；视觉总览用 `python3 scripts/thumbnail.py presentation.pptx`；原始 OOXML 用 `python3 scripts/office/unpack.py presentation.pptx unpacked/` | +| 从模板创建或编辑已有本地 PPTX | 先读 `lark-slides-pptx-template-workflows.md` | +| 从零新建飞书在线 PPT | 先读 `lark-slides-create-workflows.md` | +| 获取在线 slides 内容、读取 / 分析已有在线 PPT | XML 内容优先用 `slides +xml-get` 保存到文件；页面视觉内容用 `slides +screenshot`，详见 `lark-slides-screenshot.md` | -**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。** +## 读取 / 分析内容 -**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。** - -**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。** - -**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan//slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。** - -**CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。** - -**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。** - -**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。** - -**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。** - -**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。 - -## 身份选择 - -飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。 - -- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权： +### 在线 Slides ```bash -lark-cli auth login --domain slides +# 读取完整 XML 内容，优先保存到文件再分析 +lark-cli slides +xml-get --as user --presentation slides_example_presentation_id --output presentation.xml --json + +# 获取页面截图；必须指定 --slide-number 或 --slide-id，多个页面可重复传 --slide-number +lark-cli slides +screenshot --as user --presentation slides_example_presentation_id --slide-number 1 --output-dir screenshots --json ``` -- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。 +在线 Slides 的截图参数和页码语义详见 [`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)；需要继续编辑在线 Slides 时，按 `lark-slides-create-workflows.md` / `lark-slides-replace-workflows.md` 选择创建或替换流程。 -**执行规则**： +## 编辑 PPTX 工作流 -1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。 -2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。 -3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。 +**完整流程先读 [`lark-slides-pptx-template-workflows.md`](references/lark-slides-pptx-template-workflows.md)。** -## 执行前必做 +## 从零创建 -> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。 +**完整流程先读 [`lark-slides-create-workflows.md`](references/lark-slides-create-workflows.md)。** -高频只读： - -- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) -- [planning-layer.md](references/planning-layer.md)（新建 / 大幅改写） -- [visual-planning.md](references/visual-planning.md)（新建 / 大幅改写） -- [asset-planning.md](references/asset-planning.md)（新建 / 大幅改写） -- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后） - -按需再读： - -- 创建：[`lark-slides-create.md`](references/lark-slides-create.md) -- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md) -- 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md) -- 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md) -- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) -- 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py) -- 排障：[`troubleshooting.md`](references/troubleshooting.md) -- 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml) - -## Workflow - -> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。 - -### Design Ideas - -不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。 - -开始写 XML 前，先在 `slide_plan.json` 里确定 deck 级视觉策略： - -- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。 -- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 -- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。 -- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。 - -每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。 - -PPT 的尺寸是 960x540，确保主体内容在页面边界内。 -多用生图，辅助搜图，必须要图文并茂。 - -可优先考虑这些页面形态： - -- **双栏结构**：左文右图或左图右文，视觉区域占 35-45% 宽度。 -- **图标行**：图标在色块或圆形底中，右侧是短标题和一句解释。 -- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级。 -- **半出血视觉**：图片或抽象形状占据左/右半屏，文字覆盖或贴边排布。 -- **大数字卡片**：关键指标用 60-72pt 数字，下面配 10-14pt 标签。 -- **对比列**：before/after、方案 A/B、问题/解法用左右并列，标题和基线严格对齐。 -- **时间线/流程图**：步骤用节点和箭头表达，流程方向必须一眼可见。 - -字体和间距建议： - -- 标题 36-44pt，关键结论可更大；正文 14-18pt；注释 10-12pt。 -- 正文默认左对齐；只在封面、结尾或大号数字场景中使用居中。 -- 页面边距至少 40px；内容块之间保持 24-40px 间距，并在同一 deck 内保持一致。 -- 卡片内边距要真实留出空间，不要让文字贴边；对齐 shape 和文字时要考虑文本框 padding。 - -常见错误必须避免： - -- 不要所有页面复用同一种标题 + 三 bullets 版式。 -- 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。 -- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。 -- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。 -- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。 - -### 创建方式选择 - -| 场景 | 推荐方式 | -|------|----------| -| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 | -| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加 | -| 已有 PPT 继续追加或插入页面 | 使用 `xml_presentation.slide create`，必要时配合 `before_slide_id` | - -> [!WARNING] -> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。 - -> [!IMPORTANT] -> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。 - -```text -Step 1: 需求澄清 & 读取知识 - - 澄清主题、受众、页数、风格 - - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md - -Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json - - 生成结构化大纲供用户确认 - - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan//slide_plan.json` - - plan 字段、路径命名和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行 - -Step 3: 按 slide_plan.json 生成 XML → 创建 - - 逐页消费 plan：key_message 定主结论，layout_type 定几何，visual_focus 定主视觉，text_density 定文本量 - - 缺少真实素材时必须用 `fallback_if_missing` 生成 XML-native 兜底视觉；不要留空 - - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行 - -Step 4: 审查 & 交付 - - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查 - - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正 - - 没问题 → 交付：告知用户演示文稿 ID 和访问方式 -``` - -### jq 命令模板（编辑已有 PPT 时使用） - -新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号： - -```bash -# 追加到末尾 -lark-cli slides xml_presentation.slide create \ - --as user \ - --params '{"xml_presentation_id":"YOUR_ID"}' \ - --data "$(jq -n --arg content ' - - - 在这里放置 shape、line、table、chart、whiteboard 等元素 - -' '{slide:{content:$content}}')" - -# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级 -# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾 -lark-cli slides xml_presentation.slide create \ - --as user \ - --params '{"xml_presentation_id":"YOUR_ID"}' \ - --data "$(jq -n --arg content '...' --arg before 'TARGET_SLIDE_ID' \ - '{slide:{content:$content}, before_slide_id:$before}')" -``` - -> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。 - -### 大纲模板 - -生成大纲时使用以下格式，交给用户确认： - -```text -[PPT 标题] — [定位描述]，面向 [目标受众] - -页面结构（N 页）： -1. 封面页：[标题文案] -2. [页面主题]：[要点1]、[要点2]、[要点3] -3. [页面主题]：[要点描述] -... -N. 结尾页：[结尾文案] - -风格：[配色方案]，[排版风格] -``` +当没有本地 PPTX 模板 / 参考演示文稿，或目标是新建飞书 / Lark 在线 Slides 而不是本地 `.pptx` 文件时，使用该流程。 ## 核心概念 @@ -243,35 +78,98 @@ Slides (演示文稿) └── slide_id (页面唯一标识) ``` -## Shortcuts 与 API +## 身份选择 -Shortcut 是对常用操作的高级封装（`lark-cli slides + [flags]`）。有 Shortcut 的操作优先使用。 +飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。 -| Shortcut | 说明 | -|----------|------| -| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `` 占位符自动上传） | -| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 ``），最大 20 MB | -| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 ``，不改变页序 | -| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 | - -没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。 +- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权： ```bash -lark-cli schema slides.. # 调用 API 前必须先查看参数结构 -lark-cli slides [flags] # 调用 API +lark-cli auth login --domain slides ``` -> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 +- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。 -## 核心规则 +**执行规则**： -1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan//slide_plan.json`；风格和大纲只能作为规划输入，不能绕过规划层 -2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加 -3. **`` 直接子元素只有 ` + + 在这里放置 shape、line、table、chart、whiteboard 等元素 + +' '{slide:{content:$content}}')" + +# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级 +# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾 +lark-cli slides xml_presentation.slide create \ + --as user \ + --params '{"xml_presentation_id":"YOUR_ID"}' \ + --data "$(jq -n --arg content '...' --arg before 'TARGET_SLIDE_ID' \ + '{slide:{content:$content}, before_slide_id:$before}')" +``` + +> 渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。 + +### 大纲模板 + +生成大纲时使用以下格式，交给用户确认： + +```text +[PPT 标题] — [定位描述]，面向 [目标受众] + +页面结构（N 页）： +1. 封面页：[标题文案] +2. [页面主题]：[要点1]、[要点2]、[要点3] +3. [页面主题]：[要点描述] +... +N. 结尾页：[结尾文案] + +风格：[配色方案]，[排版风格] +``` + +## 核心概念 + +### URL 格式与 Token + +| URL 格式 | 示例 | Token 类型 | 处理方式 | +|----------|------|-----------|----------| +| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 | +| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` | + +> `+replace-slide` 和 `+media-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。 + +### Wiki 链接特殊处理（关键！） + +知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先查询 wiki 节点，确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为真实 presentation ID。 + +```bash +lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}' +``` + +Shortcut `+replace-slide` 和 `+media-upload` 会自动解析 `/wiki/` URL；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。 + +### 资源关系 + +```text +Wiki Space (知识空间) +└── Wiki Node (知识库节点, obj_type: slides) + └── obj_token → xml_presentation_id + +Slides (演示文稿) +├── xml_presentation_id (演示文稿唯一标识) +├── revision_id (版本号) +└── Slide (幻灯片页面) + └── slide_id (页面唯一标识) +``` + +## Shortcuts 与 API + +Shortcut 是对常用操作的高级封装（`lark-cli slides + [flags]`）。有 Shortcut 的操作优先使用。 + +| Shortcut | 说明 | +|----------|------| +| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `` 占位符自动上传） | +| [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 ``），最大 20 MB | +| [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 ``，不改变页序 | +| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 | + +没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。 + +```bash +lark-cli schema slides.. # 调用 API 前必须先查看参数结构 +lark-cli slides [flags] # 调用 API +``` + +> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 + +## 核心规则 + +1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，先确定 deck 目标、受众、页序、视觉系统和每页关键消息；不要从用户提示直接跳到 XML +2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加 +3. **`` 直接子元素只有 ` - - - -

主标题

- - - - - -

这是演讲者备注。

- - - - -``` - -## 根元素 - -### `` - -协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。 - -**属性：** - -| 属性 | 类型 | 必需 | 说明 | -|------|------|------|------| -| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` | -| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` | -| `id` | string | 否 | 演示文稿标识 | - -**子元素：** - -| 元素 | 必需 | 说明 | -|------|------|------| -| `` | 否 | 演示文稿标题 | -| `<theme>` | 否 | 全局主题 | -| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 | - -## 主题 - -### `<theme>` - -`<theme>` 当前包含两部分： - -- `<background>`：演示文稿级背景填充 -- `<textStyles>`：主题文本样式集合 - -`<textStyles>` 下可选子元素： - -- `<title>` -- `<headline>` -- `<sub-headline>` -- `<body>` -- `<caption>` - -这些元素定义的是主题默认样式，不是页面结构。常用属性： - -| 属性 | 说明 | -|------|------| -| `fontFamily` | 字体 | -| `fontSize` | 字号 | -| `fontColor` | 字体颜色 | - -## 幻灯片元素 - -### `<slide>` - -单张幻灯片的结构比较严格。 - -**属性：** - -| 属性 | 类型 | 必需 | 说明 | -|------|------|------|------| -| `id` | string | 否 | 幻灯片标识 | - -**直接子元素只有：** - -| 元素 | 必需 | 说明 | -|------|------|------| -| `<style>` | 否 | 页面样式 | -| `<data>` | 否 | 页面元素容器 | -| `<note>` | 否 | 演讲者备注 | - -这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。 - -## 文本内容模型 - -### `<content>` - -实际页面文本通常通过 `<content>` 表达，常见位置有： - -- `shape` 内部 -- `table/td` 内部 -- `note` 内部 - -**常用属性：** - -| 属性 | 说明 | -|------|------| -| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` | -| `verticalAlign` | 垂直对齐 | -| `textAlign` | 水平对齐 | -| `lineSpacing` | 行间距 | -| `fontSize` | 字号 | -| `fontFamily` | 字体 | -| `color` | 字体颜色 | -| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 | -| `wrap` | 是否自动换行 | - -**可包含的子元素：** - -- `<p>` -- `<ul>` -- `<ol>` - -### `<p>` - -`<p>` 是段落元素，可混排纯文本和内联标签： - -- `<br/>` -- `<strong>` -- `<em>` -- `<u>` -- `<span>` -- `<del>` -- `<a>` -- `<shadow>` -- `<outline>` - -示例： - -```xml -<content textType="body" textAlign="left"> - <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p> - <ul> - <li><p>列表项 1</p></li> - <li><p>列表项 2</p></li> - </ul> -</content> -``` - -## 常用页面元素 - -所有页面元素都放在 `<data>` 中。 - -### `<shape>` - -`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。 - -```xml -<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> - <content textType="title"> - <p>主标题</p> - </content> -</shape> -``` - -```xml -<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120"> - <fill> - <fillColor color="rgba(100, 149, 237, 0.25)"/> - </fill> - <border color="rgb(100, 149, 237)" width="2"/> -</shape> -``` - -**属性：** - -| 属性 | 必需 | 说明 | -|------|------|------| -| `type` | 是 | 形状类型，`text` 表示文本框 | -| `topLeftX` | 是 | 左上角 X 坐标 | -| `topLeftY` | 是 | 左上角 Y 坐标 | -| `width` | 是 | 宽度 | -| `height` | 是 | 高度 | -| `rotation` | 否 | 旋转角度 | -| `flipX` / `flipY` | 否 | 翻转 | -| `alpha` | 否 | 透明度 | - -**可选子元素：** - -- `<fill>` -- `<border>` -- `<reflection>` -- `<shadow>` -- `<content>` - -### `<line>` - -```xml -<line startX="100" startY="200" endX="420" endY="200"> - <border color="rgb(43, 47, 54)" width="2"/> -</line> -``` - -`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。 - -### `<img>` - -```xml -<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/> -``` - -`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。 - -`src` 只接受两种值： - -| `src` 形式 | 说明 | -|---|---| -| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token | -| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token | - -> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。 - -本地图片的两种姿势： - -- **新建带图 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 - -### `<icon>` - -```xml -<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/> -``` - -### `<table>` - -表格结构为： - -- `<table>` -- `<colgroup>` / `<tr>` -- `<tr>` 内为 `<td>` -- `<td>` 内可放 `<content>` - -### `<chart>` - -图表元素必须至少包含： - -- `<chartPlotArea>` -- `<chartData>` - -同时还可以包含： - -- `<chartTitle>` -- `<chartSubTitle>` -- `<chartStyle>` -- `<chartLegend>` -- `<chartTooltip>` - -如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。 - -## 样式元素 - -### `<fill>` - -```xml -<fill> - <fillColor color="rgb(100, 149, 237)"/> -</fill> -``` - -### `<border>` - -```xml -<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/> -``` - -### 颜色格式 - -```xml -<fillColor color="rgb(255, 0, 0)"/> -<fillColor color="rgba(255, 0, 0, 0.5)"/> -<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/> -<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/> -``` - -## 演讲者备注 - -### `<note>` - -```xml -<note> - <content textType="body"> - <p>这是演讲者备注内容。</p> - </content> -</note> -``` - -## 完整示例 - -```xml -<?xml version="1.0" encoding="UTF-8"?> -<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540"> - <title>季度报告 - - - - <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/> - </textStyles> - </theme> - <slide> - <style> - <fill> - <fillColor color="rgb(245, 245, 245)"/> - </fill> - </style> - <data> - <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100"> - <content textType="title"> - <p>2024 年第一季度报告</p> - </content> - </shape> - <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180"> - <content textType="body"> - <p>核心指标</p> - <ul> - <li><p>用户增长：+25%</p></li> - <li><p>收入增长：+30%</p></li> - <li><p>市场份额：15%</p></li> - </ul> - </content> - </shape> - <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140"> - <fill> - <fillColor color="rgba(100, 149, 237, 0.25)"/> - </fill> - <border color="rgb(100, 149, 237)" width="2"/> - </shape> - </data> - <note> - <content textType="body"> - <p>讲到增长率时补充样本范围。</p> - </content> - </note> - </slide> -</presentation> -``` - -## 最佳实践 - -1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"` -2. 用 `shape type="text"` + `content` 表达页面文本 -3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名 -4. 优先使用 `rgb` / `rgba` 颜色格式 -5. 特殊字符按 XML 规则转义 -6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"` - -## 参考文档 - -- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) -- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) -- [examples.md](examples.md) -- [slides_demo.xml](slides_demo.xml) diff --git a/skills/lark-slides/references/xml-schema-quick-ref.md b/skills/lark-slides/references/xml-schema-quick-ref.md index 6ac38d9d6..d3346b1d8 100644 --- a/skills/lark-slides/references/xml-schema-quick-ref.md +++ b/skills/lark-slides/references/xml-schema-quick-ref.md @@ -8,6 +8,8 @@ 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>` 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>` 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下 +5. 文本中的特殊字符必须按 XML 规则转义，例如 `&` 写成 `&`，`<` / `>` 写成 `<` / `>` +6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"` ## 最小可用示例 @@ -36,6 +38,8 @@ **子元素：** `<title>?`, `<theme>?`, `<slide>+` +`<slide>` 至少 1 页，最多 100 页。 + ## slide 元素 | 属性 | 必需 | 说明 | @@ -54,6 +58,19 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 - `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式 - `<content textType="...">` 中，作为内容的文本类型 +`<theme>` 当前可包含： + +- `<background>` - 演示文稿级背景填充 +- `<textStyles>` - 主题文本样式集合 + +主题文本样式常用属性： + +| 属性 | 说明 | +|------|------| +| `fontFamily` | 字体 | +| `fontSize` | 字号 | +| `fontColor` | 字体颜色 | + `textStyles` 的 schema 默认值如下： | textType | 默认字号 | @@ -71,12 +88,14 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 | 属性 | 说明 | |------|------| | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` | +| `verticalAlign` | 垂直对齐方式 | | `textAlign` | 文本对齐方式 | | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` | | `fontSize` | 字号 | | `fontFamily` | 字体 | | `color` | 字体颜色 | | `bold` / `italic` / `underline` / `strikethrough` | 文本样式 | +| `wrap` | 是否自动换行 | `<content>` 的子元素只能是： @@ -84,6 +103,8 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 - `<ul>` - `<ol>` +`<p>` 可混排纯文本和内联标签：`<br/>`、`<strong>`、`<em>`、`<u>`、`<span>`、`<del>`、`<a>`、`<shadow>`、`<outline>`。 + ### content 示例 ```xml @@ -117,6 +138,10 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 | `width` | 是 | 宽度 | | `height` | 是 | 高度 | | `rotation` | 否 | 旋转角度 | +| `flipX` / `flipY` | 否 | 翻转 | +| `alpha` | 否 | 透明度 | + +可选子元素：`<fill>`、`<border>`、`<reflection>`、`<shadow>`、`<content>`。 ### line @@ -126,12 +151,16 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 </line> ``` +`line` 使用 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。 + ### img ```xml <img src="file_token_or_url" 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)。 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。 @@ -144,6 +173,14 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出 `iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。 +### table + +表格结构为 `<table>`，内部可包含 `<colgroup>` / `<tr>`，`<tr>` 内为 `<td>`，`<td>` 内可放 `<content>`。 + +### chart + +图表元素必须至少包含 `<chartPlotArea>` 和 `<chartData>`；还可包含 `<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>`。复杂 chart XML 以 XSD 为准，不要自行发明简化 DSL。 + ### whiteboard ```xml @@ -231,13 +268,6 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` </note> ``` -## 详细参考 - -- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) -- [xml-format-guide.md](xml-format-guide.md) -- [examples.md](examples.md) -- [slides_demo.xml](slides_demo.xml) - ## Schema 版本信息 - **版本**: 2.0.0