From eeaf2910b3a76d6181142d21f69346981b6a9990 Mon Sep 17 00:00:00 2001 From: "caichengjie.viper" Date: Fri, 29 May 2026 15:19:31 +0800 Subject: [PATCH 1/5] docs(lark-slides): tighten SKILL.md routing and trim always-loaded content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on the CCM skill-quality audit, apply the high-value, low-risk findings: - description: drop the implementation detail ("接口通过 XML 协议通信") and add a NOT segment so "做演示文稿" / "画架构图" don't mis-route to lark-doc / lark-whiteboard - add a "不在本 skill 范围" routing table (doc / whiteboard / drive / sheets / base) - move the design spec (color strategy, page forms, alignment, common errors) into visual-planning.md (already a CRITICAL forced read on create/large-edit); SKILL.md keeps only the core gate + a pointer. No content lost - relocate the per-method scope table to references/lark-slides-permissions.md, leaving a one-line pointer - de-duplicate and de-emphasize the wiki-token handling section Pushed back on the audit's lower-value items (schema-note "duplication", bulk reference renames) and relocated rather than deleted the permission table. --- skills/lark-slides/SKILL.md | 74 +++++-------------- .../references/lark-slides-permissions.md | 14 ++++ .../lark-slides/references/visual-planning.md | 22 ++++++ 3 files changed, 54 insertions(+), 56 deletions(-) create mode 100644 skills/lark-slides/references/lark-slides-permissions.md diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 9767c6583..456cf3167 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"] @@ -90,41 +90,9 @@ lark-cli auth login --domain slides ### Design Ideas -不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。 +不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。**每页至少要有一个视觉元素**（图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉）；文本框本身不算主视觉。 -开始写 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 视觉。 -- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 +完整的设计规范——deck 级配色策略、背景与 motif 一致性、各 `layout_type` 的几何与页面形态、字体间距和文本贴合（text-fit）护栏、常见错误清单——都在 [visual-planning.md](references/visual-planning.md)。新建或大幅改写时该文件已是 CRITICAL 强制读取项，按其规则规划后再写 XML。 ### 创建方式选择 @@ -226,17 +194,11 @@ N. 结尾页：[结尾文案] | `/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-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。 - -### Wiki 链接特殊处理（关键！） - -知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先查询 wiki 节点，确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为真实 presentation ID。 - -```bash -lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}' -``` - -Shortcut `+replace-slide` 和 `+media-upload` 会自动解析 `/wiki/` URL；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。 +> `+replace-slide` 和 `+media-upload` 会自动解析以上两种 URL。**只有直接调用原生 API（`xml_presentations.*` / `xml_presentation.slide.*`）时**才需手动解析 wiki 链接：先查询节点确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为 `xml_presentation_id`。 +> +> ```bash +> lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}' +> ``` ### 资源关系 @@ -280,17 +242,17 @@ 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 不支持分片上传）。 +## 不在本 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) | + ## 权限速查 -| 方法 | 所需 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` | +各方法所需 scope 见 [`lark-slides-permissions.md`](references/lark-slides-permissions.md)；权限不足的处理流程见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides..` 输出不一致，以后两者为准。 diff --git a/skills/lark-slides/references/lark-slides-permissions.md b/skills/lark-slides/references/lark-slides-permissions.md new file mode 100644 index 000000000..cb9a93e6b --- /dev/null +++ b/skills/lark-slides/references/lark-slides-permissions.md @@ -0,0 +1,14 @@ +# slides 权限速查 + +各方法所需 scope。遇到权限不足时按 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 的流程处理（user 身份用 `auth login --domain slides`，bot 身份去开发者后台开通对应 scope）。 + +| 方法 | 所需 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` | diff --git a/skills/lark-slides/references/visual-planning.md b/skills/lark-slides/references/visual-planning.md index 84ffcbd6d..e5463feaf 100644 --- a/skills/lark-slides/references/visual-planning.md +++ b/skills/lark-slides/references/visual-planning.md @@ -30,6 +30,22 @@ Decks can vary page backgrounds, but variation must be intentional and legible: - Reuse a small number of visual devices: side bar, card radius, node style, line weight, icon container, or footer treatment. Do not introduce a new decorative language on each page. - Insert background and motif shapes before content elements so they do not cover text, images, or diagrams. +## 配色策略 + +在生成 XML 前先在 `slide_plan.json` 的 `visual_system` 里定下 deck 级配色，全 deck 复用同一套，不要逐页换色： + +- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。 +- **主次比例**：选 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 +- **对比充足**：无论深浅背景，都要保证正文、图标和线条对比充足。不要用低对比文字或低对比图标（例如浅灰字压在浅色背景上）。 +- **每页一个主视觉**：每页至少要有一个视觉元素（图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉）。文本框本身不算主视觉。 + +常见错误必须避免： + +- 不要所有页面复用同一种「标题 + 三 bullets」版式。 +- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。 +- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。 +- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 + ## Text Fit Guardrails Use these as conservative minimums on a 960 x 540 canvas. Increase height when using bold text, Chinese text, mixed Chinese/English, or line spacing above default. @@ -52,9 +68,15 @@ Additional rules: - Diagram labels should be short enough to fit the shape. Prefer two short lines over one cramped long line. - When a text block has more than one `

`, size the box for multiple lines explicitly. Do not assume the renderer will auto-expand. - If a line contains mixed Chinese and English, budget more width than either language alone; mixed text wraps less predictably. +- 正文默认左对齐；只在封面、结尾或大号数字（`big-number`）场景才使用居中。 ## Layout Types +下列是合法的 `layout_type` 取值（与 `planning-layer.md` 的枚举一致）。除此之外还有两个常见的**页内组合结构**，它们不是 `layout_type` 取值，而是在合适的 layout 内实现的排布方式： + +- **图标行**：图标置于色块或圆形底中，右侧配短标题和一句解释，适合罗列能力、特性或模块。 +- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级；通常落在 `comparison` 或 `high` 文本密度的内容页里。 + ### `title-cover` Purpose: introduce the deck's point of view. From 2eaa367c2dea6116798222f5f53394f47a3d3c5b Mon Sep 17 00:00:00 2001 From: "caichengjie.viper" Date: Fri, 29 May 2026 15:46:49 +0800 Subject: [PATCH 2/5] docs(lark-slides): delegate generic guidance to lark-shared, keep native-API guardrail local MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - trim 身份选择 / wiki / lark-shared CRITICAL to delegate auth, permissions and global params to lark-shared (which actually owns them) - drop the standalone permission table (CLI errors already return the missing scopes + console_url), removing references/lark-slides-permissions.md - keep the schema-first native-API guardrail inline, matching the wording used by all 12 sibling skills — lark-shared does not document a native-API call flow, so delegating it there would dangle and lose the "run schema first, don't guess fields" rule --- skills/lark-slides/SKILL.md | 34 +++++-------------- .../references/lark-slides-permissions.md | 14 -------- 2 files changed, 9 insertions(+), 39 deletions(-) delete mode 100644 skills/lark-slides/references/lark-slides-permissions.md diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 456cf3167..a70549cee 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -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 结构。** @@ -47,21 +47,11 @@ metadata: ## 身份选择 -飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。 +飞书幻灯片通常是用户自己的内容资源，执行 slides 操作时始终显式指定身份。 -- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权： - -```bash -lark-cli auth login --domain slides -``` - -- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。 - -**执行规则**： - -1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。 -2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。 -3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。 +1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认使用 `--as user`。 +2. 只有在用户明确要求应用身份，或当前工作流要求 bot 持有/创建资源时，才使用 `--as bot`。 +3. 如果出现权限不足，先检查是否误用了身份；认证和授权修复流程按 lark-shared 执行。 ## 执行前必做 @@ -194,11 +184,7 @@ N. 结尾页：[结尾文案] | `/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-upload` 会自动解析以上两种 URL。**只有直接调用原生 API（`xml_presentations.*` / `xml_presentation.slide.*`）时**才需手动解析 wiki 链接：先查询节点确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为 `xml_presentation_id`。 -> -> ```bash -> lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}' -> ``` +> `+replace-slide` 和 `+media-upload` 会自动解析以上两种 URL。**只有直接调用原生 API（`xml_presentations.*` / `xml_presentation.slide.*`）时**才需手动解析 wiki 链接：先用 wiki node 查询确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为 `xml_presentation_id`。 ### 资源关系 @@ -224,12 +210,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` 参数结构，不要猜测字段格式。 ## 核心规则 @@ -251,8 +239,4 @@ lark-cli slides [flags] # 调用 API | 上传、下载、移动、删除普通文件，管理云空间 | [lark-drive](../lark-drive/SKILL.md) | | 操作幻灯片内嵌的表格 / 多维表格数据 | [lark-sheets](../lark-sheets/SKILL.md) / [lark-base](../lark-base/SKILL.md) | -## 权限速查 - -各方法所需 scope 见 [`lark-slides-permissions.md`](references/lark-slides-permissions.md)；权限不足的处理流程见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。 - > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides..` 输出不一致，以后两者为准。 diff --git a/skills/lark-slides/references/lark-slides-permissions.md b/skills/lark-slides/references/lark-slides-permissions.md deleted file mode 100644 index cb9a93e6b..000000000 --- a/skills/lark-slides/references/lark-slides-permissions.md +++ /dev/null @@ -1,14 +0,0 @@ -# slides 权限速查 - -各方法所需 scope。遇到权限不足时按 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 的流程处理（user 身份用 `auth login --domain slides`，bot 身份去开发者后台开通对应 scope）。 - -| 方法 | 所需 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` | From 7795d80810a690ca750117528624ffbe42659a24 Mon Sep 17 00:00:00 2001 From: "caichengjie.viper" Date: Fri, 29 May 2026 15:50:11 +0800 Subject: [PATCH 3/5] =?UTF-8?q?docs(lark-slides):=20revert=20=E8=BA=AB?= =?UTF-8?q?=E4=BB=BD=E9=80=89=E6=8B=A9=20section=20to=20original?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill audit did not flag 身份选择; trimming it was an optional cleanup that dropped the concrete `auth login --domain slides` command and the slides-specific "verify the bot actually has access to the target deck" caveat (which lark-shared does not cover). Keep the section self-contained. --- skills/lark-slides/SKILL.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index a70549cee..02f8d006a 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -47,11 +47,21 @@ metadata: ## 身份选择 -飞书幻灯片通常是用户自己的内容资源，执行 slides 操作时始终显式指定身份。 +飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。 -1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认使用 `--as user`。 -2. 只有在用户明确要求应用身份，或当前工作流要求 bot 持有/创建资源时，才使用 `--as bot`。 -3. 如果出现权限不足，先检查是否误用了身份；认证和授权修复流程按 lark-shared 执行。 +- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权： + +```bash +lark-cli auth login --domain slides +``` + +- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。 + +**执行规则**： + +1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。 +2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。 +3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。 ## 执行前必做 From 094a5a5ddedd41a407b149d5957c1394c9571cc9 Mon Sep 17 00:00:00 2001 From: "caichengjie.viper" Date: Fri, 29 May 2026 15:59:39 +0800 Subject: [PATCH 4/5] docs(lark-slides): keep Design Ideas inline, revert visual-planning.md Drop the Design Ideas -> visual-planning.md move (audit #6/#10, Warning-level token optimization). It was optional and not required; keeping the design spec inline minimizes the diff. visual-planning.md is restored to its original state. --- skills/lark-slides/SKILL.md | 36 +++++++++++++++++-- .../lark-slides/references/visual-planning.md | 22 ------------ 2 files changed, 34 insertions(+), 24 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 02f8d006a..dc95e37bb 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -90,9 +90,41 @@ lark-cli auth login --domain slides ### Design Ideas -不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。**每页至少要有一个视觉元素**（图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉）；文本框本身不算主视觉。 +不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。 -完整的设计规范——deck 级配色策略、背景与 motif 一致性、各 `layout_type` 的几何与页面形态、字体间距和文本贴合（text-fit）护栏、常见错误清单——都在 [visual-planning.md](references/visual-planning.md)。新建或大幅改写时该文件已是 CRITICAL 强制读取项，按其规则规划后再写 XML。 +开始写 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 视觉。 +- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 ### 创建方式选择 diff --git a/skills/lark-slides/references/visual-planning.md b/skills/lark-slides/references/visual-planning.md index e5463feaf..84ffcbd6d 100644 --- a/skills/lark-slides/references/visual-planning.md +++ b/skills/lark-slides/references/visual-planning.md @@ -30,22 +30,6 @@ Decks can vary page backgrounds, but variation must be intentional and legible: - Reuse a small number of visual devices: side bar, card radius, node style, line weight, icon container, or footer treatment. Do not introduce a new decorative language on each page. - Insert background and motif shapes before content elements so they do not cover text, images, or diagrams. -## 配色策略 - -在生成 XML 前先在 `slide_plan.json` 的 `visual_system` 里定下 deck 级配色，全 deck 复用同一套，不要逐页换色： - -- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。 -- **主次比例**：选 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 -- **对比充足**：无论深浅背景，都要保证正文、图标和线条对比充足。不要用低对比文字或低对比图标（例如浅灰字压在浅色背景上）。 -- **每页一个主视觉**：每页至少要有一个视觉元素（图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉）。文本框本身不算主视觉。 - -常见错误必须避免： - -- 不要所有页面复用同一种「标题 + 三 bullets」版式。 -- 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。 -- 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。 -- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 - ## Text Fit Guardrails Use these as conservative minimums on a 960 x 540 canvas. Increase height when using bold text, Chinese text, mixed Chinese/English, or line spacing above default. @@ -68,15 +52,9 @@ Additional rules: - Diagram labels should be short enough to fit the shape. Prefer two short lines over one cramped long line. - When a text block has more than one `

`, size the box for multiple lines explicitly. Do not assume the renderer will auto-expand. - If a line contains mixed Chinese and English, budget more width than either language alone; mixed text wraps less predictably. -- 正文默认左对齐；只在封面、结尾或大号数字（`big-number`）场景才使用居中。 ## Layout Types -下列是合法的 `layout_type` 取值（与 `planning-layer.md` 的枚举一致）。除此之外还有两个常见的**页内组合结构**，它们不是 `layout_type` 取值，而是在合适的 layout 内实现的排布方式： - -- **图标行**：图标置于色块或圆形底中，右侧配短标题和一句解释，适合罗列能力、特性或模块。 -- **2x2 / 2x3 网格**：适合能力、模块、风险、行动项，每格内容保持同等层级；通常落在 `comparison` 或 `high` 文本密度的内容页里。 - ### `title-cover` Purpose: introduce the deck's point of view. From a633ada85aea650a173be707de96e6f9454204aa Mon Sep 17 00:00:00 2001 From: "caichengjie.viper" Date: Fri, 29 May 2026 16:01:50 +0800 Subject: [PATCH 5/5] =?UTF-8?q?docs(lark-slides):=20revert=20Wiki=20?= =?UTF-8?q?=E9=93=BE=E6=8E=A5=E7=89=B9=E6=AE=8A=E5=A4=84=E7=90=86=20sectio?= =?UTF-8?q?n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the dedicated section and its concrete `wiki spaces get_node` command. The audit's "duplicates other skills" claim doesn't hold here — the get_node call is the actionable key step for resolving a wiki token to a presentation id, and condensing it dropped the command. Keep it inline. --- skills/lark-slides/SKILL.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index dc95e37bb..e7615614c 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -226,7 +226,17 @@ N. 结尾页：[结尾文案] | `/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-upload` 会自动解析以上两种 URL。**只有直接调用原生 API（`xml_presentations.*` / `xml_presentation.slide.*`）时**才需手动解析 wiki 链接：先用 wiki node 查询确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为 `xml_presentation_id`。 +> `+replace-slide` 和 `+media-upload` shortcut 会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。 + +### Wiki 链接特殊处理（关键！） + +知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先查询 wiki 节点，确认 `node.obj_type == "slides"`，再用 `node.obj_token` 作为真实 presentation ID。 + +```bash +lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}' +``` + +Shortcut `+replace-slide` 和 `+media-upload` 会自动解析 `/wiki/` URL；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。 ### 资源关系