diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 9767c6583..e7615614c 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-slides version: 1.0.0 -description: "飞书幻灯片：创建和编辑幻灯片，接口通过 XML 协议通信。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。" +description: "飞书幻灯片：创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面（创建、删除、读取、局部替换）。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：云文档内容编辑（走 lark-doc）、画板绘图（走 lark-whiteboard）、上传或下载普通文件（走 lark-drive）。" metadata: requires: bins: ["lark-cli"] @@ -22,7 +22,7 @@ metadata: | 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` | | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | -**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.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 结构。** @@ -262,12 +262,14 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides + [flags]` | [`+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 和 ``，不改变页序 | +没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。 + ```bash lark-cli schema slides.. # 调用 API 前必须先查看参数结构 lark-cli slides [flags] # 调用 API ``` -原生 API 高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜字段。 +> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 ## 核心规则 @@ -280,17 +282,13 @@ lark-cli slides [flags] # 调用 API 7. **编辑已有页面优先块级替换**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；只有需要替换整页结构时才用 `slide.delete` + `slide.create` 8. **`` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传或 `+create --slides` 的 `@./path` 占位符自动上传 → 拿 `file_token` 写进 ``」。如果用户给了网图链接，先 `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` | +## 不在本 skill 范围 + +| 需求 | 正确去向 | +|------|----------| +| 编辑云文档（docx / wiki 文档）正文内容 | [lark-doc](../lark-doc/SKILL.md) | +| 画板 / 架构图 / 流程图等画板绘图 | [lark-whiteboard](../lark-whiteboard/SKILL.md) | +| 上传、下载、移动、删除普通文件，管理云空间 | [lark-drive](../lark-drive/SKILL.md) | +| 操作幻灯片内嵌的表格 / 多维表格数据 | [lark-sheets](../lark-sheets/SKILL.md) / [lark-base](../lark-base/SKILL.md) | > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides..` 输出不一致，以后两者为准。