视觉画布设计
canvas-design
基于设计原则创作静态视觉作品,用于海报与品牌图形。
lark-slides【文档与办公】飞书幻灯片:创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时,也应直接使用本 skill,不要因为域名不是飞书而回退到 WebFetch;路由依据是 URL 路径模式和 token,而不是域名。不负责:云文档内容编辑(走 lark-doc)、云文档里的独立画板对象(走 lark-whiteboard)、上传或下载普通文件(走 lark-drive)。
独立 GitHub 快照 · 自动分类 · 以原作者文档为准
本技能文档较长,务必使用 Read 工具阅读两次,必须阅读完整全文。
权威经验是全局硬约束和高频易错点,必须牢记并严格遵守。
<img>(来自生图工具或搜图工具),不要使用 <shape> 或 <icon> 拼出封面视觉。<shape> 和 <line> 拟形具体物项,必须使用生图工具生成的 <img>。headline 或 title 下方放置用于分隔或装饰的 rect 或 <line>。<content> 的 fontSize 属性,不要依赖 textType 的默认字号兜底,这些兜底值明显偏大。<content> 必须设置 wrap="true" autoFit="normal-auto-fit" 属性自动换行和缩排,避免文字溢出。<content> 的 color 属性而不是 fontColor 属性。<content> 的 lineSpacing="multiple:xx" 或 lineSpacing="fixed:xx" 而不是 lineSpacing="xx"。<img> 而不是 <image>。<fill><fillColor color="rgba(R,G,B,A)"/></fill>)并和背景有足够对比。<chart>,其他(漏斗图、金字塔图、象限图、矩阵图等)用 <shape> + <line> 模拟。<chart> 的图例只能通过不写或删除 <chartLegend> 实现,<chartLegend> 不支持 position="none"。rect 和 text 模拟,其他用 <table>,没有 <shape type="table">。<table> 的 width 和 height 固定表格大小,同时设置需要保留列宽或行高的 <col> 的 width 和 <tr> 的 height,其余自动分配。<td> 直接子元素只有 <fill>(背景)、<content>(文字)和边框配置(一般不用),不能嵌套 <shape>、<img>、<icon>。<shape type="rect"> 只是形状不是容器,<icon>、<img>、<shape type="text"> 和其他 <shape> 必须与它平级靠坐标叠放。<fill><fillColor color="linear-gradient(135deg, rgba(R,G,B,A) 0%, rgba(R,G,B,A) 100%)"/></fill>。lark-slides-edit-workflows.md。slides_chart_demo.xml。<table> 和 <chart>)。适用范围:
title-cover、section-divider、conclusion、quote-highlight 和 big-number。核心要求:
排版布局:
视觉风格:
| 用户需求 | 优先动作 | 关键文档 / 命令 |
|---|---|---|
| 新建 PPT | 先规划 slide_plan.json,再按复杂度选择一步或两步创建 | planning-layer.md、visual-planning.md、asset-planning.md、slides +create |
| 用户要求使用模板 | 将模板导入为 Slides 再编辑 | lark-slides-pptx-template-workflows.md |
| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入,不改页序 | slides +replace-slide、lark-slides-replace-slide.md |
| 读取或分析已有 PPT | 解析 slides/wiki token,用 shortcut 回读全文 XML 或读取单页 XML,保存 xml_presentation_id、slide_id、revision_id | slides +xml-get、xml_presentation.slide.get、lark-slides-xml-presentations-get.md |
| 查看或回滚历史版本 | 先用 +history-list 找 history_version_id,再 +history-revert,必要时 +history-revert-status 轮询 | lark-slides-history.md |
| 获取幻灯片页面截图 | 用 slide_id 或页号指定页面,一次不超过 10 页 | slides +screenshot、lark-slides-screenshot.md |
| 上传或使用图片 | 先上传为 file_token,禁止直接写 http(s) 外链 | slides +media-upload、lark-slides-media-upload.md,或 +create --slides 的 @./path 占位符 |
| 绘制图表 | 原生图表(柱状、条形、折线、面积、饼(环)、雷达、组合图)用 <chart>,其他(漏斗图、金字塔图、象限图、矩阵图等)用 <shape> + <line> 模拟 | xml-schema-quick-ref.md、slides_chart_demo.xml |
| 绘制表格 | 优先用 rect 和 text 模拟,其他用 <table> | xml-schema-quick-ref.md |
| 使用图标 | 禁止盲猜 iconType,必须先检索 IconPark,再写 <icon iconType="...">,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | iconpark_tool.py search → resolve、iconpark.md |
| 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | troubleshooting.md、validation-checklist.md |
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md,认证、权限和全局参数均以 lark-shared 为准。
CRITICAL — 查看或回滚历史版本前,MUST 先读取 lark-slides-history.md。回滚接口只接受 history_version_id,不要把 revision_id 直接传给 +history-revert。
CRITICAL — 生成任何 XML 之前,MUST 先用 Read 工具读取 xml-schema-quick-ref.md,禁止凭记忆猜测 XML 结构。
CRITICAL — 新建演示文稿或大幅改写页面时,MUST 先生成 .lark-slides/plan/<deck-or-task-id>/slide_plan.json,再生成 XML。先创建对应目录,规划层规则和中间产物生命周期见 planning-layer.md。仅替换一个标题、插入一个块等小型已有页编辑可豁免。
CRITICAL — 新建演示文稿或大幅改写页面时,生成 XML 前 MUST 读取 visual-planning.md,确保 layout_type、visual_focus、text_density 实际改变页面几何、主视觉和文本量。
CRITICAL — 新建演示文稿或大幅改写页面时,规划 asset_need MUST 遵循 asset-planning.md:只做元数据规划,必须有 fallback_if_missing,不得要求真实搜索、下载或上传素材。
CRITICAL — 将完整 <slide> XML 提交给 slides +create --slides、xml_presentation.slide create 或 slides +replace-pages 之前,MUST 先把待提交 XML 保存到本地文件并运行 scripts/xml_text_overlap_lint.py;summary.error_count 必须为 0 才能调用接口。
CRITICAL — 创建或大幅改写后,MUST 按 validation-checklist.md 做显式验证:回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险;XML 语法和文本重叠静态检查优先使用 scripts/xml_text_overlap_lint.py。
CRITICAL — 创建前自检或失败排障时,MUST 按 troubleshooting.md 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。
编辑已有幻灯片页面:单个标题、文本块、图片或局部元素优先用 +replace-slide(块级替换/插入,不动页序);已有 Slides 的多页大改优先用 +replace-pages 在原 presentation 内批量重建页面,避免 slides +create 生成新链接。选择 action 和完整读-改-写流程见 lark-slides-edit-workflows.md。
用户要求使用模板:按 lark-slides-pptx-template-workflows.md 处理。
飞书幻灯片通常是用户自己的内容资源。默认应优先显式使用 --as user(用户身份)执行 slides 相关操作,始终显式指定身份。
--as user(推荐):以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权:lark-cli auth login --domain slides
--as bot:仅在用户明确要求以应用身份操作,或需要让 bot 持有/创建资源时使用。使用 bot 身份时,要额外确认 bot 是否真的有目标演示文稿的访问权限。执行规则:
--as user。--as bot。重要:
references/slides_xml_schema_definition.xml是此 skill 唯一正确的 XML 协议来源;其他 md 仅是对它和 CLI schema 的摘要。
高频只读:
按需再读:
lark-slides-create.mdlark-slides-xml-presentations-get.mdlark-slides-edit-workflows.md、lark-slides-replace-slide.md、lark-slides-replace-pages.mdlark-slides-history.mdlark-slides-screenshot.mdlark-slides-media-upload.mdslides_chart_demo.xmliconpark.md、scripts/iconpark_tool.pytroubleshooting.mdslides_xml_schema_definition.xml不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿,不能作为正式交付。
开始写 XML 前,先在 slide_plan.json 里确定 deck 级视觉策略:
每页至少要有一个视觉元素:图片、图标、图表、表格、流程、对比结构或大号数字。文本框本身不算主视觉。
常见页面形态:
常见错误必须避免:
fallback_if_missing 生成替代图片。| 场景 | 推荐方式 |
|---|---|
| 简单 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,回读确认当前状态,再继续修复或追加。
Step 1: 需求分析 & 读取知识
- 分析主题、受众、页数、风格;
- 若用户要求使用模板,按 lark-slides-pptx-template-workflows.md 处理
- 读取 xml-schema-quick-ref.md;新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
- 涉及图表读取 slides_chart_demo.xml
Step 2: 生成大纲 → 写入 slide_plan.json
- 生成结构化大纲
- 新建 / 大幅改写必须先创建目录并写入 `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、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
Step 4: 审查 & 交付
- 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录,包括 XML 文本重叠检查
- 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正
- 没问题 → 交付:使用 NotifyHuman 工具交付 PPT 链接
新建 PPT 推荐用 +create --slides。以下 jq 模板适用于向已有演示文稿追加页面的场景,可以避免手动转义双引号:
# 追加到末尾
lark-cli slides xml_presentation.slide create \
--as user \
--params '{"xml_presentation_id":"YOUR_ID"}' \
--data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
<style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
<data>
在这里放置 shape、line、table、chart 等元素
</data>
</slide>' '{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 '<slide ...>...</slide>' --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()或省略停靠点会导致服务端回退为白色。
生成大纲时使用以下格式:
[PPT 标题] — [定位描述],面向 [目标受众]
页面结构(N 页):
1. 封面页:[标题文案]
2. [页面主题]:[要点1]、[要点2]、[要点3]
3. [页面主题]:[要点描述]
...
N. 结尾页:[结尾文案]
风格:[配色方案],[排版风格]
| 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-uploadshortcut 会自动解析以上两种 URL;直接调用原生 API 时仍需手动解析 wiki 链接。
知识库链接(/wiki/TOKEN)不能直接当 xml_presentation_id。直接调用原生 API 前,先查询 wiki 节点,确认 node.obj_type == "slides",再用 node.obj_token 作为真实 presentation ID。
lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
Shortcut +replace-slide 和 +media-upload 会自动解析 /wiki/ URL;手动调用 xml_presentations.* / xml_presentation.slide.* 时才需要自己做这一步。
Wiki Space (知识空间)
└── Wiki Node (知识库节点, obj_type: slides)
└── obj_token → xml_presentation_id
Slides (演示文稿)
├── xml_presentation_id (演示文稿唯一标识)
├── revision_id (版本号)
└── Slide (幻灯片页面)
└── slide_id (页面唯一标识)
Shortcut 是对常用操作的高级封装(lark-cli slides +<verb> [flags])。有 Shortcut 的操作优先使用。
| Shortcut | 说明 |
|---|---|
+create | 创建 PPT(可选 --slides 一步添加页面,支持 <img src="@./local.png"> 占位符自动上传) |
+xml-get | 读取全文 XML 并保存到本地文件,避免终端输出被截断 |
+media-upload | 上传本地图片到指定演示文稿,返回 file_token(用作 <img src="...">),最大 20 MB |
+replace-slide | 对已有幻灯片页面进行块级替换/插入(block_replace / block_insert),自动注入 id 和 <content/>,不改变页序 |
+replace-pages | 在原演示文稿内批量重建多个页面:先创建新页到旧页前,再删除旧页;适合已有 Slides 的多页大改,不新建链接 |
没有 Shortcut 覆盖时使用原生 API。高频资源:slides +xml-get 读取全文;xml_presentation.slide.create/delete/get/replace 管理单页。
lark-cli schema slides.<resource>.<method> # 调用 API 前必须先查看参数结构
lark-cli slides <resource> <method> [flags] # 调用 API
重要:使用原生 API 时,必须先运行
schema查看--data/--params参数结构,不要猜测字段格式。
.lark-slides/plan/<deck-or-task-id>/slide_plan.json;模板、风格和大纲只能作为规划输入,不能绕过规划层slides +create --slides '[...]' 一步创建;复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符,或超过 10 页时,默认先 slides +create 创建空白 PPT,再用 xml_presentation.slide.create 逐页添加<slide> 直接子元素只有 <style>、<data>、<note>:文本和图形必须放在 <data> 内<content> 表达:必须用 <content><p>...</p></content>,不能把文字直接写在 shape 内xml_presentation_id、slide_id、revision_id+replace-slide(block_replace / block_insert),不要整页重建;已有 Slides 的多页整页重建用 +replace-pages,不要用 slides +create 新建整份 PPT;只有没有 shortcut 覆盖的特殊单页整页操作才手动 slide.create + slide.delete<img src> 只能用上传到飞书 drive 的 file_token,禁止使用 http(s) 外链 URL:飞书 slides 渲染端不会代理外链图片,外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 slides +media-upload 上传或 +create --slides 的 @./path 占位符自动上传 → 拿 file_token 写进 <img src>」。如果用户给了网图链接,先 curl/下载到 CWD 内再走上传流程,不要直接把外链 URL 塞进 src。图片最大 20 MB(slides upload API 不支持分片上传)。注意:如果 md 内容与
slides_xml_schema_definition.xml或lark-cli schema slides.<resource>.<method>输出不一致,以后两者为准。