From 461c11943da5c0743f5140874795c87f24b2b515 Mon Sep 17 00:00:00 2001 From: zhanghuanxu Date: Tue, 30 Jun 2026 21:42:53 +0800 Subject: [PATCH] feat:edit slides --- skills/lark-slides/SKILL.md | 365 +- .../lark-slides-create-workflows.md | 202 + .../lark-slides-pptx-template-workflows.md | 432 ++ .../references/lark-slides-replace-slide.md | 2 +- ...ws.md => lark-slides-replace-workflows.md} | 0 .../lark-slides-xml-presentation-slide-get.md | 2 +- ...k-slides-xml-presentation-slide-replace.md | 2 +- skills/lark-slides/scripts/add_slide.py | 195 + skills/lark-slides/scripts/clean.py | 323 ++ skills/lark-slides/scripts/clean_test.py | 91 + .../scripts/office/helpers/__init__.py | 8 + .../scripts/office/helpers/merge_runs.py | 199 + .../office/helpers/simplify_redlines.py | 197 + skills/lark-slides/scripts/office/pack.py | 160 + .../schemas/ISO-IEC29500-4_2016/dml-chart.xsd | 1499 ++++++ .../ISO-IEC29500-4_2016/dml-chartDrawing.xsd | 146 + .../ISO-IEC29500-4_2016/dml-diagram.xsd | 1085 ++++ .../ISO-IEC29500-4_2016/dml-lockedCanvas.xsd | 11 + .../schemas/ISO-IEC29500-4_2016/dml-main.xsd | 3081 ++++++++++++ .../ISO-IEC29500-4_2016/dml-picture.xsd | 23 + .../dml-spreadsheetDrawing.xsd | 185 + .../dml-wordprocessingDrawing.xsd | 287 ++ .../schemas/ISO-IEC29500-4_2016/pml.xsd | 1676 +++++++ .../shared-additionalCharacteristics.xsd | 28 + .../shared-bibliography.xsd | 144 + .../shared-commonSimpleTypes.xsd | 174 + .../shared-customXmlDataProperties.xsd | 25 + .../shared-customXmlSchemaProperties.xsd | 18 + .../shared-documentPropertiesCustom.xsd | 59 + .../shared-documentPropertiesExtended.xsd | 56 + .../shared-documentPropertiesVariantTypes.xsd | 195 + .../ISO-IEC29500-4_2016/shared-math.xsd | 582 +++ .../shared-relationshipReference.xsd | 25 + .../schemas/ISO-IEC29500-4_2016/sml.xsd | 4439 +++++++++++++++++ .../schemas/ISO-IEC29500-4_2016/vml-main.xsd | 570 +++ .../ISO-IEC29500-4_2016/vml-officeDrawing.xsd | 509 ++ .../vml-presentationDrawing.xsd | 12 + .../vml-spreadsheetDrawing.xsd | 108 + .../vml-wordprocessingDrawing.xsd | 96 + .../schemas/ISO-IEC29500-4_2016/wml.xsd | 3646 ++++++++++++++ .../schemas/ISO-IEC29500-4_2016/xml.xsd | 116 + .../ecma/fouth-edition/opc-contentTypes.xsd | 42 + .../ecma/fouth-edition/opc-coreProperties.xsd | 50 + .../schemas/ecma/fouth-edition/opc-digSig.xsd | 49 + .../ecma/fouth-edition/opc-relationships.xsd | 33 + .../scripts/office/schemas/mce/mc.xsd | 75 + .../office/schemas/microsoft/wml-2010.xsd | 560 +++ .../office/schemas/microsoft/wml-2012.xsd | 67 + .../office/schemas/microsoft/wml-2018.xsd | 14 + .../office/schemas/microsoft/wml-cex-2018.xsd | 20 + .../office/schemas/microsoft/wml-cid-2016.xsd | 13 + .../microsoft/wml-sdtdatahash-2020.xsd | 4 + .../schemas/microsoft/wml-symex-2015.xsd | 8 + skills/lark-slides/scripts/office/soffice.py | 183 + skills/lark-slides/scripts/office/unpack.py | 133 + skills/lark-slides/scripts/office/validate.py | 119 + .../scripts/office/validators/__init__.py | 15 + .../scripts/office/validators/base.py | 851 ++++ .../scripts/office/validators/docx.py | 446 ++ .../scripts/office/validators/pptx.py | 275 + .../scripts/office/validators/redlining.py | 247 + skills/lark-slides/scripts/rezip.py | 39 + skills/lark-slides/scripts/thumbnail.py | 298 ++ 63 files changed, 24293 insertions(+), 221 deletions(-) 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 rename skills/lark-slides/references/{lark-slides-edit-workflows.md => lark-slides-replace-workflows.md} (100%) create mode 100755 skills/lark-slides/scripts/add_slide.py create mode 100755 skills/lark-slides/scripts/clean.py create mode 100644 skills/lark-slides/scripts/clean_test.py create mode 100644 skills/lark-slides/scripts/office/helpers/__init__.py create mode 100644 skills/lark-slides/scripts/office/helpers/merge_runs.py create mode 100644 skills/lark-slides/scripts/office/helpers/simplify_redlines.py create mode 100755 skills/lark-slides/scripts/office/pack.py create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/mce/mc.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-2010.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-2012.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-2018.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-cex-2018.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-cid-2016.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd create mode 100644 skills/lark-slides/scripts/office/schemas/microsoft/wml-symex-2015.xsd create mode 100644 skills/lark-slides/scripts/office/soffice.py create mode 100755 skills/lark-slides/scripts/office/unpack.py create mode 100755 skills/lark-slides/scripts/office/validate.py create mode 100644 skills/lark-slides/scripts/office/validators/__init__.py create mode 100644 skills/lark-slides/scripts/office/validators/base.py create mode 100644 skills/lark-slides/scripts/office/validators/docx.py create mode 100644 skills/lark-slides/scripts/office/validators/pptx.py create mode 100644 skills/lark-slides/scripts/office/validators/redlining.py create mode 100755 skills/lark-slides/scripts/rezip.py create mode 100755 skills/lark-slides/scripts/thumbnail.py diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 4630b663..c52ba0aa 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,217 +12,55 @@ 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` | -| 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` | -| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | +本地 `skills/lark-slides/scripts/` 下的 Python 工具要求 Python 3.10+；如果 `python3 --version` 低于 3.10，先切换到 3.10+ 解释器再运行脚本。 -**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。** +| 用户需求 | 指引 | +|----------|------| +| 读取 / 分析本地 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 — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。** +## 读取 / 分析内容 -**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 和布局风险。** - -**CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。** - -> [!NOTE] -> `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。 - -**CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。** - -**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+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`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权： +### 本地 PPTX ```bash -lark-cli auth login --domain slides +# 提取文本 +python -m markitdown presentation.pptx + +# 生成视觉总览图 +python3 scripts/thumbnail.py presentation.pptx + +# 解包查看原始 OOXML +python3 scripts/office/unpack.py presentation.pptx unpacked/ ``` -- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。 - -**执行规则**： - -1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。 -2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。 -3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。 - -## 执行前必做 - -> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。 - -高频只读： - -- [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) -- 模板：[`template-catalog.md`](references/template-catalog.md)、[`scripts/template_tool.py`](scripts/template_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 组成的抽象视觉。文本框本身不算主视觉。 - -可优先考虑这些页面形态： - -- **双栏结构**：左文右图或左图右文，视觉区域占 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`，回读确认当前状态，再继续修复或追加。 - -### 模板与脚本优先流程 - -模板细则见 [template-catalog.md](references/template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。 +### 在线 Slides ```bash -python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3 -python3 skills/lark-slides/scripts/template_tool.py summarize --template --label <封面|目录|分节|内容|结尾> -python3 skills/lark-slides/scripts/template_tool.py extract --template --label <页型> --out /tmp/template-slice.xml +# 读取完整 XML 内容，优先保存到文件再分析 +lark-cli slides +xml-get --as user --presentation --output presentation.xml --json + +# 获取页面截图；必须指定 --slide-number 或 --slide-id，多个页面可重复传 --slide-number +lark-cli slides +screenshot --as user --presentation --slide-number 1 --output-dir screenshots --json ``` -```text -Step 1: 需求澄清 & 读取知识 - - 澄清主题、受众、页数、风格；模板需求按“模板与脚本优先流程”处理 - - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md +在线 Slides 的截图参数和页码语义详见 [`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)；需要继续编辑在线 Slides 时，按 `lark-slides-create-workflows.md` / `lark-slides-replace-workflows.md` 选择创建或替换流程。 -Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json - - 生成结构化大纲供用户确认；如使用模板，标明基于哪个模板改写 - - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan//slide_plan.json` - - plan 字段、路径命名、模板边界和 `asset_need` 结构按 planning-layer.md / asset-planning.md 执行 +## 编辑 PPTX 工作流 -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 执行 +**完整流程先读 [`lark-slides-pptx-template-workflows.md`](references/lark-slides-pptx-template-workflows.md)。** -Step 4: 审查 & 交付 - - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查 - - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正 - - 没问题 → 交付：告知用户演示文稿 ID 和访问方式 -``` +1. 用 `thumbnail.py` 和 `markitdown` 分析模板。 +2. 解包 -> 调整页面结构 -> 编辑内容 -> 清理 -> 打包。 +3. 交付前完成必需 QA。 -### jq 命令模板（编辑已有 PPT 时使用） +## 从零创建 -新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号： +**完整流程先读 [`lark-slides-create-workflows.md`](references/lark-slides-create-workflows.md)。** -```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 标题] — [定位描述]，面向 [目标受众] - -模板：[未使用模板 / /