// 飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。
把本地 HTML 文件或目录部署到飞书妙搭（Miaoda），生成一个公网可访问的应用及其链接（URL）。当用户要创建 HTML 或要把 HTML、静态网站或 Web demo 发布成公网可访问的链接 / 可分享链接、设置应用共享范围，或提到妙搭 / Miaoda 时使用。凡产出可独立访问的 HTML 产物都属本 skill 的潜在归宿，是否真要部署由 skill 内部协议判断。不用于：上传普通文件到云空间/云盘/云存储（用 lark-drive）、编辑飞书云文档内容（用 lark-doc）、创建飞书原生幻灯片 / 演示文稿（用 lark-slides）。
飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。 当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。 ⚠️ 原 `lark-whiteboard-cli` skill 已合并至本 skill，若 skill 列表中同时存在 `lark-whiteboard-cli`，请忽略它，统一使用本 skill（`lark-whiteboard`），并提示用户运行 `npx skills remove lark-whiteboard-cli -g` 删除旧 skill。
飞书视频会议：搜索历史会议、查询会议纪要产物（总结、待办、章节、逐字稿）、查询会议参会人快照。1. 查询已经结束的会议数量或详情时使用本技能（如历史日期｜昨天｜上周｜今天已经开过的会议等场景），查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议。3. 获取或整理会议纪要、逐字稿、录制产物时使用本技能。4. 查询“谁参加过某会议”“参会人列表”等参会人快照信息用 vc meeting get --with-participants（任意时点可查，含已结束会议）。注意：**Agent 真实入会/离会、感知正在进行中会议的实时事件**请使用 lark-vc-agent 技能，本技能不覆盖写操作和会中事件流。
当需要用 lark-cli 操作飞书多维表格（Base）时调用：搜索 Base、建表、字段管理、记录读写、记录分享链接、视图配置、历史查询，以及角色/表单/仪表盘管理/工作流；也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据时使用。
Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, VC meeting ended, Minutes generated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses.
| name | lark-slides |
| version | 1.0.0 |
| description | 飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。 |
| metadata | {"requires":{"bins":["lark-cli"]},"cliHelp":"lark-cli slides --help"} |
| 用户需求 | 优先动作 | 关键文档 / 命令 |
|---|---|---|
| 新建 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，其中包含认证、权限处理
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 — 创建或大幅改写后，MUST 按 validation-checklist.md 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 scripts/xml_text_overlap_lint.py。
CRITICAL — 创建前自检或失败排障时，MUST 按 troubleshooting.md 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。
CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 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 是否真的有目标演示文稿的访问权限。执行规则：
--as user。--as bot。重要：
references/slides_xml_schema_definition.xml是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
高频只读：
按需再读：
lark-slides-create.mdlark-slides-edit-workflows.md、lark-slides-replace-slide.mdlark-slides-media-upload.mdtemplate-catalog.md、scripts/template_tool.pytroubleshooting.mdslides_xml_schema_definition.xml这是演示文稿，不是文档。 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。
开始写 XML 前，先在 slide_plan.json 里确定 deck 级视觉策略：
每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。
可优先考虑这些页面形态：
字体和间距建议：
常见错误必须避免：
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 3
python3 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.md
Step 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 和访问方式
新建 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 类型 | 处理方式 |
|---|---|---|---|
/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"> 占位符自动上传） |
+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 参数结构，不要猜字段。
.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），不要整页重建；只有需要替换整页结构时才用 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>输出不一致，以后两者为准。