Skill v1.0.6
currentAutomated scanfeat(contact +search-user): add --queries multi-name fanout (#707)
name: lark-slides version: 1.0.0 description: "飞书幻灯片:创建和编辑幻灯片,接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli slides --help"
slides (v1)
Quick Reference
| 用户需求 | 优先动作 | 关键文档 / 命令 | |
|---|---|---|---|
| 新建 PPT | 先规划 slide_plan.json,再按复杂度选择一步或两步创建 | planning-layer.md、visual-planning.md、asset-planning.md、slides +create | |
| 大幅改写页面 | 先回读现有 XML,写入新 plan,再替换或重建相关页面 | xml_presentations.get、+replace-slide、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 | |
| 上传或使用图片 | 先上传为 file_token,禁止直接写 http(s) 外链 | slides +media-upload,或 +create --slides 的 @./path 占位符 | |
| 用户提到模板、主题、版式 | 先检索模板,再摘要,必要时裁切骨架 | template_tool.py search → summarize → extract | |
| 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | troubleshooting.md、validation-checklist.md |
CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md),其中包含认证、权限处理
CRITICAL — 生成任何 XML 之前,MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md),禁止凭记忆猜测 XML 结构。
CRITICAL — 新建演示文稿或大幅改写页面时,MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/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`(块级替换/插入,不动页序);选择 action 和完整读-改-写流程见 `lark-slides-edit-workflows.md`。
身份选择
飞书幻灯片通常是用户自己的内容资源。默认应优先显式使用 `--as user`(用户身份)执行 slides 相关操作,始终显式指定身份。
- `--as user`(推荐):以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权:
lark-cli auth login --domain slides
- `--as bot`:仅在用户明确要求以应用身份操作,或需要让 bot 持有/创建资源时使用。使用 bot 身份时,要额外确认 bot 是否真的有目标演示文稿的访问权限。
执行规则:
- 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT,默认都先用
--as user。 - 如果出现权限不足,先检查当前是否误用了 bot 身份;不要默认回退到 bot。
- 只有在用户明确要求"用应用身份 / bot 身份操作",或当前工作流就是 bot 创建资源后再做协作授权时,才切换到
--as bot。
执行前必做
重要:references/slides_xml_schema_definition.xml是此 skill 唯一正确的 XML 协议来源;其他 md 仅是对它和 CLI schema 的摘要。
高频只读:
- xml-schema-quick-ref.md
- planning-layer.md(新建 / 大幅改写)
- visual-planning.md(新建 / 大幅改写)
- asset-planning.md(新建 / 大幅改写)
- validation-checklist.md(创建 / 大幅改写后)
按需再读:
- 创建:`lark-slides-create.md`
- 编辑:`lark-slides-edit-workflows.md`、`lark-slides-replace-slide.md`
- 图片:`lark-slides-media-upload.md`
- 模板:`template-catalog.md`、`scripts/template_tool.py`
- 排障:`troubleshooting.md`
- 完整协议:`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。主流程只记住:先 search,锁定后 summarize,需要骨架时才 extract;不要直接读取完整模板 XML 或照搬占位文案。
python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3python3 skills/lark-slides/scripts/template_tool.py summarize --template <template-id> --label <封面|目录|分节|内容|结尾>python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <页型> --out /tmp/template-slice.xml
Step 1: 需求澄清 & 读取知识- 澄清主题、受众、页数、风格;模板需求按“模板与脚本优先流程”处理- 读取 xml-schema-quick-ref.md;新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.mdStep 2: 生成大纲 → 用户确认 → 写入 slide_plan.json- 生成结构化大纲供用户确认;如使用模板,标明基于哪个模板改写- 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan/<deck-or-task-id>/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 模板适用于向已有演示文稿追加页面的场景,可以避免手动转义双引号:
# 追加到末尾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 标题] — [定位描述],面向 [目标受众]模板:[未使用模板 / <category>/<template>.xml(推荐原因)]页面结构(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-uploadshortcut 会自动解析以上两种 URL;直接调用原生 API 时仍需手动解析 wiki 链接。
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_idSlides (演示文稿)├── xml_presentation_id (演示文稿唯一标识)├── revision_id (版本号)└── Slide (幻灯片页面)└── slide_id (页面唯一标识)
Shortcuts 与 API
Shortcut 是对常用操作的高级封装(lark-cli slides +<verb> [flags])。有 Shortcut 的操作优先使用。
| Shortcut | 说明 | |
|---|---|---|
| `+create` | 创建 PPT(可选 --slides 一步添加页面,支持 <img src="@./local.png"> 占位符自动上传) | |
| `+media-upload` | 上传本地图片到指定演示文稿,返回 file_token(用作 <img src="...">),最大 20 MB | |
| `+replace-slide` | 对已有幻灯片页面进行块级替换/插入(block_replace / block_insert),自动注入 id 和 <content/>,不改变页序 |
lark-cli schema slides.<resource>.<method> # 调用 API 前必须先查看参数结构lark-cli slides <resource> <method> [flags] # 调用 API
原生 API 高频资源:xml_presentations.get 读取全文;xml_presentation.slide.create/delete/get/replace 管理单页。使用原生 API 时,必须先运行 schema 查看 --data / --params 参数结构,不要猜字段。
核心规则
- 先规划再写 XML:新建演示文稿或大幅改写页面时,必须先写入
.lark-slides/plan/<deck-or-task-id>/slide_plan.json;模板、风格和大纲只能作为规划输入,不能绕过规划层 - 创建流程:简单短 XML(1-3 页、结构简单、特殊字符少)可用
slides +create --slides '[...]'一步创建;复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符,或超过 10 页时,默认先slides +create创建空白 PPT,再用xml_presentation.slide.create逐页添加 - `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`:文本和图形必须放在
<data>内 - 文本通过 `<content>` 表达:必须用
<content><p>...</p></content>,不能把文字直接写在 shape 内 - 保存关键 ID:后续操作需要
xml_presentation_id、slide_id、revision_id - 删除谨慎:删除操作不可逆,且至少保留一页幻灯片
- 编辑已有页面优先块级替换:修改单个 shape/img 用
+replace-slide(block_replace/block_insert),不要整页重建;只有需要替换整页结构时才用slide.delete+slide.create - `<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 不支持分片上传)。
权限速查
| 方法 | 所需 scope | |
|---|---|---|
slides +create | slides:presentation:create, slides:presentation:write_only(含 @ 占位符时还需 docs:document.media:upload) | |
slides +media-upload | docs:document.media:upload(wiki URL 解析还需 wiki:node:read) | |
slides +replace-slide | slides:presentation:update(wiki URL 解析还需 wiki:node:read) | |
xml_presentations.get | slides:presentation:read | |
xml_presentation.slide.create | slides:presentation:update 或 slides:presentation:write_only | |
xml_presentation.slide.delete | slides:presentation:update 或 slides:presentation:write_only | |
xml_presentation.slide.get | slides:presentation:read | |
xml_presentation.slide.replace | slides:presentation:update |
注意:如果 md 内容与slides_xml_schema_definition.xml或lark-cli schema slides.<resource>.<method>输出不一致,以后两者为准。