From c605ea7c481c890b361e84c006f6b6aa2b77c7a2 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Fri, 17 Jul 2026 18:04:00 +0800 Subject: [PATCH 01/11] chore(slides): update lark-slides skill to 0715 snapshot --- skills/lark-slides/SKILL.md | 150 +- .../lark-slides/references/asset-planning.md | 10 +- skills/lark-slides/references/examples.md | 91 -- skills/lark-slides/references/iconpark.md | 4 +- .../references/lark-slides-create.md | 13 +- .../references/lark-slides-media-upload.md | 3 +- .../lark-slides-pptx-template-workflows.md | 18 +- .../references/lark-slides-replace-slide.md | 3 - .../references/lark-slides-screenshot.md | 2 +- .../references/lark-slides-whiteboard.md | 331 ---- .../references/lark-slides-xml-get.md | 100 -- ...rk-slides-xml-presentation-slide-create.md | 219 +++ ...rk-slides-xml-presentation-slide-delete.md | 11 +- .../lark-slides-xml-presentation-slide-get.md | 4 +- ...k-slides-xml-presentation-slide-replace.md | 5 +- .../lark-slides-xml-presentations-get.md | 95 +- .../lark-slides/references/planning-layer.md | 21 +- .../lark-slides/references/slide-templates.md | 201 --- .../references/slides_chart_demo.xml | 1417 ++++++++++++++++- skills/lark-slides/references/slides_demo.xml | 226 --- .../slides_xml_schema_definition.xml | 46 +- .../lark-slides/references/troubleshooting.md | 32 +- .../references/validation-checklist.md | 46 +- .../lark-slides/references/visual-planning.md | 47 +- .../references/xml-schema-quick-ref.md | 265 ++- 25 files changed, 2146 insertions(+), 1214 deletions(-) delete mode 100644 skills/lark-slides/references/examples.md delete mode 100644 skills/lark-slides/references/lark-slides-whiteboard.md delete mode 100644 skills/lark-slides/references/lark-slides-xml-get.md create mode 100644 skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md delete mode 100644 skills/lark-slides/references/slide-templates.md delete mode 100644 skills/lark-slides/references/slides_demo.xml diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 435acb739c..25a9738a81 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: "飞书幻灯片:创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时,也应直接使用本 skill,不要因为域名不是飞书而回退到 WebFetch;路由依据是 URL 路径模式和 token,而不是域名。不负责:云文档内容编辑(走 lark-doc)、云文档里的独立画板对象(走 lark-whiteboard,注意 slide 内嵌的流程图/架构图仍属本 skill)、上传或下载普通文件(走 lark-drive)。" +description: "飞书幻灯片:创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。当用户给出 doubao.com 的 /slides/ URL/token 时,也应直接使用本 skill,不要因为域名不是飞书而回退到 WebFetch;路由依据是 URL 路径模式和 token,而不是域名。不负责:云文档内容编辑(走 lark-doc)、云文档里的独立画板对象(走 lark-whiteboard)、上传或下载普通文件(走 lark-drive)。" metadata: requires: bins: ["lark-cli"] @@ -10,45 +10,101 @@ metadata: # slides (v1) -**CRITICAL — 全局硬约束:PPT 的尺寸是 960x540,确保主体内容在页面边界内。** - -**CRITICAL — 图片至关重要:必须有意识的主动多用图片!素材图使用生图工具和搜图工具,缺图时用生图工具生成配图补足;背景图必须使用生图工具,且生图指令中必须明确要求不要出现任何文字。** - -**CRITICAL — 防文本溢出:所有承载突出信息和密集文字的 `` 必须设置 `autoFit="normal-auto-fit"`,字号会在框内自动缩排以防溢出。** +> 本技能文档较长,务必使用 Read 工具阅读两次,必须阅读完整全文。 + +## 权威经验 + +**权威经验是全局硬约束和高频易错点,必须牢记并严格遵守。** + +- 你有充足的时间完成这个 PPT,质量永远比速度重要。 +- PPT 的尺寸是 960x540,必须严格确保主体内容在页面边界内。 +- !!!禁止交付无图产物!!! 必须使用大量图片增强视觉效果!!! 禁止重复使用同一张图!!! +- 封面页的主视觉必须是 ``(来自生图工具或搜图工具),不要使用 `` 或 `` 拼出封面视觉。 +- 禁止用 `` 和 `` 拟形具体物项,必须使用生图工具生成的 ``。 +- 禁止在 `headline` 或 `title` 下方放置用于分隔或装饰的 `rect` 或 ``。 +- 禁止在任何页面内部使用无意义的装饰线条或色块条带,页面任何一边都不要使用贴边窄条。 +- 生图工具的指令参数必须以“不要出现任何文字和颜色色号”结尾,避免生成的图片上出现干扰文字。 +- 禁止使用 emoji 图标,任何位置都不能出现。 +- 字号必须显式设置 `` 的 `fontSize` 属性,不要依赖 `textType` 的默认字号兜底,这些兜底值明显偏大。 +- 大数字、字号大或字数多的 `` 必须设置 `wrap="true" autoFit="normal-auto-fit"` 属性自动换行和缩排,避免文字溢出。 +- 文字颜色必须用 `` 的 `color` 属性而不是 `fontColor` 属性。 +- 文字行间距必须设置 `` 的 `lineSpacing="multiple:xx"` 或 `lineSpacing="fixed:xx"` 而不是 `lineSpacing="xx"`。 +- 图片必须用 `` 而不是 ``。 +- IconPark 图标必须填充颜色(设置 ``)并和背景有足够对比。 +- 绘制图表时原生图表(柱状、条形、折线、面积、饼(环)、雷达、组合图)用 ``,其他(漏斗图、金字塔图、象限图、矩阵图等)用 `` + `` 模拟。 +- 隐藏 `` 的图例只能通过不写或删除 `` 实现,`` 不支持 `position="none"`。 +- 表格优先用 `rect` 和 `text` 模拟,其他用 ``,没有 ``。 +- 必须设置 `
` 的 `width` 和 `height` 固定表格大小,同时设置需要保留列宽或行高的 `` 的 `width` 和 `` 的 `height`,其余自动分配。 +- `
` 直接子元素只有 ``(背景)、``(文字)和边框配置(一般不用),不能嵌套 ``、``、``。 +- `` 只是形状不是容器,``、``、`` 和其他 `` 必须与它平级靠坐标叠放。 +- 填充渐变颜色必须用 ``。 +- 必须使用 NotifyHuman 工具交付 PPT 链接;编辑已有 PPT 也必须交付 PPT 链接,无论之前是否交付过相同链接。 +- 编辑页面前必须阅读 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。 +- 绘制图表前必须阅读 [`slides_chart_demo.xml`](references/slides_chart_demo.xml)。 +- 当用户要求无损复述历史上下文时,必须无损复述以上权威经验、必读的技能文档(需要重新阅读)和易错元素语法(尤其是 `` 和 ``)。 + +## 豆包设计原则 + +适用范围: + +- 普通内容页的设计必须以豆包设计原则为最高准则,除非用户要求使用模板或直接提供设计方案。 +- 不适用于 `title-cover`、`section-divider`、`conclusion`、`quote-highlight` 和 `big-number`。 + +核心要求: + +- 必须采用信息密度极高的图文卡片布局,追求充实饱满、图文丰富、可逐行细读的版面,宁可密而满,不要空而疏。 +- **!!!信息密度极高!!! 图多!!! 卡多!!! 字多!!!** + +排版布局: + +- 卡片布局:卡片按多行网格铺满页面,版面对称、均衡、不留白。网格数、图文比例按内容变化,避免每页雷同。使用更多卡片做细分承载,避免在单张卡片里堆砌大量文字(例如 8 张 50 字卡片优于 2 张 200 字卡片),多个要点必须拆分为多张子卡片。 +- 卡片样式:方角卡片 + 半透明填充 + 无边框 + 卡片贴边窄条(可选);所有卡片必须使用相同的配色方案(少量需强调的卡片除外),禁止同页出现彩虹卡片(卡片颜色超过 3 种)。 +- 卡片结构:视觉锚点(关键词、编号或 IconPark 图标)+ 标题 + 内容(包括文字、图片、图表、子卡片)。 +- 文字卡片:多数页面必须满足 6-8 张文字卡片、200-400 文字数量,字数不足时必须扩写成长句或段落,文字卡片不要留白,必须充实饱满。文字卡片不是短标签,而是“标题 + 完整说明”,像浓缩的分析文稿。文字内容不得不用列表、分栏、关键词或短句时,必须保证层次清晰,更建议拆分为多张子卡片。 +- 图片卡片:多数页面必须满足 1-3 张图片卡片,缺少图片时必须用生图工具补充配图,图片卡片与文字卡片组成网格,确保图文丰富。 +- 图表卡片:数据信息不要在文字卡片中罗列,必须在图表卡片中可视化(包括表格、图表、时间线、流程图等),图表卡片与其他卡片组成网格,展现数据驱动。 +- 间距要求:所有边距都要左右对称,页面和内部内容的边距至少 40px(内容不要贴边),卡片和内部文字的边距至少 5px(文字不要贴边),卡片之间保持 20-40px 的间距。 +- 文字对齐:正文默认左对齐,只在封面、结尾或大号数字场景中使用居中;表格里的文字左对齐、数字右对齐、仅关键词或短句时居中对齐。 + +视觉风格: + +- 美学:干净、明亮、清爽但信息饱满;靠卡片和对齐网格在高密度下维持秩序感;同排卡片文字数量应相近以保持观感整齐。 +- 字体:全篇以无衬线体(思源黑体)为主,封面或关键强调可少量使用衬线体。 +- 字号:标题 28-36pt、正文 12-14pt、注释 10-12pt,常规关键指标 16-32pt、核心指标用 36-52pt 数字,下面配 10-14pt 标签与简短解读,需要容纳更多文字时允许使用更小的字号。 +- 图标:内嵌 IconPark 图标(可用关键词或编号替代)作为视觉锚点,让高密度文字也有图形节奏,而不是成片纯文字块。 +- 配色:克制颜色数量,确保所有页面都只使用同样的 1 个背景色(偏好浅米白)、1 个主色、1 个强调色和 1 个辅助色;偏好莫兰迪配色,禁止彩虹配色(比如蓝配橙)。 ## Quick Reference | 用户需求 | 优先动作 | 关键文档 / 命令 | |----------|----------|-----------------| | 新建 PPT | 先规划 `slide_plan.json`,再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` | -| 从模板创建或编辑已有本地 PPTX | 导入 PPTX 为 Slides | `lark-slides-pptx-template-workflows.md` | +| 用户要求使用模板 | 将模板导入为 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` | +| 读取或分析已有 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` | | 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | -| 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`,或 `+create --slides` 的 `@./path` 占位符 | -| 绘制图表 | 原生图表用 ``,其他用 `` + ``,只有复杂 Mermaid、SVG 用 `` | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | +| 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`、`lark-slides-media-upload.md`,或 `+create --slides` 的 `@./path` 占位符 | +| 绘制图表 | 原生图表(柱状、条形、折线、面积、饼(环)、雷达、组合图)用 ``,其他(漏斗图、金字塔图、象限图、矩阵图等)用 `` + `` 模拟 | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | | 绘制表格 | 优先用 `rect` 和 `text` 模拟,其他用 `
` | `xml-schema-quick-ref.md` | -| 使用图标 | 禁止盲猜 `iconType`,必须先检索 IconPark,再写 ``,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` | +| 使用图标 | 禁止盲猜 iconType,必须先检索 IconPark,再写 ``,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` | | 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.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 结构。** **CRITICAL — 新建演示文稿或大幅改写页面时,MUST 先生成 `.lark-slides/plan//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)。** +**CRITICAL — 新建演示文稿或大幅改写页面时,规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md):只做元数据规划,必须有 `fallback_if_missing`,不得要求真实搜索、下载或上传素材。** -**CRITICAL — 将完整 `` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前,MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);`summary.error_count` 必须为 0 才能调用接口。** - -**CRITICAL — 创建或大幅改写后,MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证:回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险。** +**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 和布局风险。** **编辑已有幻灯片页面**:单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)(块级替换/插入,不动页序);已有 Slides 的多页大改优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内批量重建页面,避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。 +**用户要求使用模板**:按 [lark-slides-pptx-template-workflows.md](references/lark-slides-pptx-template-workflows.md) 处理。 + ## 身份选择 飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`(用户身份)执行 slides 相关操作**,始终显式指定身份。 @@ -82,16 +138,17 @@ lark-cli auth login --domain slides 按需再读: - 创建:[`lark-slides-create.md`](references/lark-slides-create.md) +- 阅读:[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.md) - 编辑:[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md) - 截图:[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md) - 图片:[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md) +- 图表:[`slides_chart_demo.xml`](references/slides_chart_demo.xml) - 图标:[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py) - 排障:[`troubleshooting.md`](references/troubleshooting.md) - 完整协议:[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml) -## Workflow -> **这是演示文稿,不是文档。** 每页 slide 是独立的视觉画面,信息密度要适当,排版要留白。 +## Workflow ### Design Ideas @@ -100,38 +157,30 @@ lark-cli auth login --domain slides 开始写 XML 前,先在 `slide_plan.json` 里确定 deck 级视觉策略: - **主题化配色**:配色必须服务本次主题、行业和受众,不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立,说明配色不够具体。 -- **主次比例**:选择 1 个主色承担约 60-70% 视觉权重,1-2 个辅助色承担结构和分区,1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 -- **背景一致性**:先确定全 deck 的背景策略,默认保持同一明暗基调和底色体系;只有分节、转场或强调页才有意改变背景,并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅,都要保证正文、图标和线条对比充足。 -- **统一 motif**:选择一个可复用视觉母题贯穿全文,例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。 +- **主次比例**:选择 1 个主色承担约 60-70% 视觉权重,1 个辅助色承担结构和分区,1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 +- **背景一致性**:先确定全 deck 的背景策略,默认保持同一明暗基调和底色体系;无论深浅,都要保证内容和背景对比充足。 +- **统一 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 视觉。 -- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 -- 不要使用 emoji。 -- 不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。 +- 不要把素材缺失表现为空白图片框;必须按 `fallback_if_missing` 生成替代图片。 +- 不要在任何位置使用 emoji 图标。 + ### 创建方式选择 @@ -150,25 +199,26 @@ lark-cli auth login --domain slides ### 生成流程 ```text -Step 1: 需求澄清 & 读取知识 - - 澄清主题、受众、页数、风格;若用户上传 PPTX 作为模板,按顶部『用户自定义模板』规则处理 +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 - - 生成结构化大纲供用户确认 - - 新建 / 大幅改写必须先创建目录并写入 `.lark-slides/plan//slide_plan.json` +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-native 兜底视觉;不要留空 - - 调用创建或整页替换接口前,先保存待提交 XML 并运行 xml_text_overlap_lint.py;error_count 不为 0 必须先修 + - 缺少真实素材时必须用 `fallback_if_missing` 生成替代图片,不要留空 - 创建方式按“创建方式选择”判断;图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行 Step 4: 审查 & 交付 - - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录 + - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录,包括 XML 文本重叠检查 - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正 - - 没问题 → 交付:告知用户演示文稿 ID 和访问方式 + - 没问题 → 交付:使用 NotifyHuman 工具交付 PPT 链接 ``` ### jq 命令模板(编辑已有 PPT 时使用) @@ -183,7 +233,7 @@ lark-cli slides xml_presentation.slide create \ --data "$(jq -n --arg content ' - + 在这里放置 shape、line、table、chart 等元素 ' '{slide:{content:$content}}')" @@ -200,7 +250,7 @@ lark-cli slides xml_presentation.slide create \ ### 大纲模板 -生成大纲时使用以下格式,交给用户确认: +生成大纲时使用以下格式: ```text [PPT 标题] — [定位描述],面向 [目标受众] @@ -257,7 +307,7 @@ Shortcut 是对常用操作的高级封装(`lark-cli slides + [flags]` | Shortcut | 说明 | |----------|------| | [`+create`](references/lark-slides-create.md) | 创建 PPT(可选 `--slides` 一步添加页面,支持 `` 占位符自动上传) | -| [`+xml-get`](references/lark-slides-xml-get.md) | 读取全文或单页 XML,并可保存到本地文件,避免终端输出被截断 | +| [`+xml-get`](references/lark-slides-xml-presentations-get.md) | 读取全文 XML 并保存到本地文件,避免终端输出被截断 | | [`+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 和 ``,不改变页序 | | [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面:先创建新页到旧页前,再删除旧页;适合已有 Slides 的多页大改,不新建链接 | diff --git a/skills/lark-slides/references/asset-planning.md b/skills/lark-slides/references/asset-planning.md index bf7e682e27..0effa9b3d3 100644 --- a/skills/lark-slides/references/asset-planning.md +++ b/skills/lark-slides/references/asset-planning.md @@ -6,7 +6,8 @@ ## Core Rules -- Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, whiteboard diagrams, placeholder regions, or XML shapes, text, and arrows as appropriate. +- `asset_need` is metadata only. It can guide page design. +- Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, placeholder regions, or XML shapes, text, and arrows as appropriate. - Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page. - Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows. - If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan. @@ -42,7 +43,7 @@ For a page without a meaningful asset need, use: - `architecture_diagram`: system components, data flow, dependency map, or model structure. - `icon`: small semantic symbol for a concept, step, role, or status. - `logo`: brand, product, team, or customer mark. -- `chart`: column, bar, line, area, radar, pie, doughnut/ring, or combo data visual. Note: `` does not support funnel or scatter — map those to `` SVG at generation time. +- `chart`: column, bar, line, area, radar, pie, doughnut/ring, or combo data visual. Note: `` does not support funnel or scatter. - `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes. - `screenshot`: product UI, terminal output, workflow state, or page capture. - `flow_diagram`: process, sequence, decision tree, or mechanism diagram. @@ -66,7 +67,7 @@ Match asset type to slide role: For `asset_type: "chart"`: - If the visual is a supported standard data chart — column, bar, line, area, radar, pie, doughnut/ring, or combo — `fallback_if_missing` must still render as a native ``. -- Do not imitate supported standard data visuals with manual drawing primitives or ``. +- Do not imitate supported standard data visuals with manual drawing primitives. - Choose the data source explicitly: - `user_provided`: when the user provides concrete values, tables, CSV, or metric lists, use those values and do not replace them with mock data. - `mock_placeholder`: when the user asks for a placeholder, template, example, or chart position to replace later, use mock data in a native ``. @@ -129,7 +130,8 @@ Business comparison page: When generating XML: 1. If an asset exists and the workflow supports it, place it in the planned visual region. -2. If no asset exists, immediately render `fallback_if_missing` with the planned XML-native element type. Supported standard data visuals still use native ``; other fallbacks may use shapes, text, lines, arrows, tables, whiteboard diagrams, or placeholder panels. +2. If no asset exists, immediately render `fallback_if_missing` with the planned generated close-enough image. Supported standard data visuals still use native ``; other fallbacks may use the image generation tool to create an approximate image. 3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration. 4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text. 5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used. +6. If the image generation tool is unavailable or fails, degrade to an XML-native fallback instead of leaving a blank: native `` for data, otherwise a simple in-card shape/text placeholder sized to fill `visual_focus`. diff --git a/skills/lark-slides/references/examples.md b/skills/lark-slides/references/examples.md deleted file mode 100644 index e15bc4173a..0000000000 --- a/skills/lark-slides/references/examples.md +++ /dev/null @@ -1,91 +0,0 @@ -# 完整操作示例 - -本文档提供与 CLI schema 一致的调用示例,XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。 - -> **重要**:新建 PPT 请使用 `slides +create --slides`,传入由 `` XML 字符串组成的 JSON 数组;每个元素必须是一页完整的 ``。复杂内容建议先创建空白 PPT,再通过 `xml_presentation.slide.create` 逐页添加。完整 `` XML 可用于本地 lint 或读取,但不能直接作为 `+create` 的提交参数。 - -## 目录 - -- [示例 1:可靠创建 6 页 PPT](#示例-1可靠创建-6-页-ppt) -- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图) -- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块) - -## 示例 1:可靠创建 6 页 PPT - -### 1. 写入规划文件 - -```bash -DECK_DIR=".lark-slides/plan/reliable-six-page-ppt" -mkdir -p "$DECK_DIR" - -# 按 planning-layer.md 写入 "$DECK_DIR/slide_plan.json", -# 至少记录 6 页的顺序和标题。 -``` - -### 2. 为每页保存独立 XML - -每个文件都是完整的 ``。下面的循环会生成 6 个独立 XML 文件;实际项目中可将每页主体替换为规划内容。 - -```bash -titles=("主题与结论" "问题背景" "核心方法" "关键数据" "执行计划" "总结与行动") -for i in {1..6}; do - printf -v page '%02d' "$i" - cat > "$DECK_DIR/slide-$page.xml" <

${titles[$((i-1))]}

页面主体内容。

-XML -done -``` - -### 3. 逐页运行 lint - -提交前检查每个独立 XML。`summary.error_count` 必须为 `0`,否则先修复 XML 或布局问题。 - -```bash -for slide_xml in "$DECK_DIR"/slide-0{1,2,3,4,5,6}.xml; do - python3 skills/lark-slides/scripts/xml_text_overlap_lint.py \ - --input "$slide_xml" | tee "${slide_xml%.xml}.lint.json" -done - -test "$(jq -s 'map(.summary.error_count) | add' "$DECK_DIR"/slide-0{1,2,3,4,5,6}.lint.json)" = "0" -``` - -### 4. 使用 `+create` 创建 6 页 PPT - -`--slides` 接收由 6 个完整 `` XML 字符串组成的 JSON 数组;使用 `jq --rawfile` 避免手动处理 XML 引号和换行。 - -```bash -lark-cli slides +create --as user \ - --title "可靠创建 6 页 PPT" \ - --slides "$(jq -n \ - --rawfile s1 "$DECK_DIR/slide-01.xml" \ - --rawfile s2 "$DECK_DIR/slide-02.xml" \ - --rawfile s3 "$DECK_DIR/slide-03.xml" \ - --rawfile s4 "$DECK_DIR/slide-04.xml" \ - --rawfile s5 "$DECK_DIR/slide-05.xml" \ - --rawfile s6 "$DECK_DIR/slide-06.xml" \ - '[$s1, $s2, $s3, $s4, $s5, $s6]')" \ - > "$DECK_DIR/create.json" -create_status=$? - -if [ "$create_status" -ne 0 ]; then - exit "$create_status" -fi - -if ! PRESENTATION_ID=$(jq -er '.data.xml_presentation_id | strings | select(length > 0)' "$DECK_DIR/create.json"); then - echo "missing non-empty data.xml_presentation_id in $DECK_DIR/create.json" >&2 - exit 1 -fi -echo "$PRESENTATION_ID" > "$DECK_DIR/xml_presentation_id" -``` - -如果创建中途失败,先保存已经返回的 `xml_presentation_id`,再回读确认实际已创建页数。 - -### 5. 用 `+xml-get` 回读全文 XML - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PRESENTATION_ID" \ - --output "$DECK_DIR/readback.xml" \ - --json | tee "$DECK_DIR/readback.json" -``` - diff --git a/skills/lark-slides/references/iconpark.md b/skills/lark-slides/references/iconpark.md index ff0e7640b0..a3f0939426 100644 --- a/skills/lark-slides/references/iconpark.md +++ b/skills/lark-slides/references/iconpark.md @@ -25,8 +25,8 @@ python3 skills/lark-slides/scripts/iconpark_tool.py list-categories - 默认先检索:语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`,让 agent 从候选里结合版面语义二次判断;不要阅读全文索引,也不要编造不存在的 `iconType`。 - 图标用于概念提示、步骤、状态、指标、角色和导航;不要用无关装饰图标填充版面。 - 常用尺寸:行内状态图标 16-24px,卡片标题图标 28-40px,主视觉图标 56-96px。 -- 视觉规范要求图标设置非透明 `fillColor`,显式指定颜色并和背景有足够对比;深色背景优先放在浅色圆形/方形底上,或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。 -- 查不到合适图标时,用 shape、line、text 画 XML-native fallback,不留空图标位。 +- 图标必须填充颜色并和背景有足够对比;深色背景优先放在浅色圆形/方形底上,或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。 +- 查不到合适图标时,从高频示例里选择替代图标(随机选择,不要千篇一律),不留空图标位。 ## 高频示例 diff --git a/skills/lark-slides/references/lark-slides-create.md b/skills/lark-slides/references/lark-slides-create.md index 6620af97c6..13779ef8ab 100644 --- a/skills/lark-slides/references/lark-slides-create.md +++ b/skills/lark-slides/references/lark-slides-create.md @@ -1,18 +1,8 @@ # slides +create(创建飞书幻灯片) -> **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - 创建一个新的飞书幻灯片演示文稿,可选一步添加页面内容。 -- 禁止:从完整 XML 解析/拆分/重序列化生成提交 payload。 -- 推荐:提交源直接就是单页 XML;+create --slides 只接受已经人工/程序直接生成的 slide 数组,不接受由 - presentation 动态拆出来的数组。 - -- 最稳:复杂 deck 默认空 deck + 单页 slide create,每次只提交一个 。 - -- 注意:复杂 XML 不适合直接塞命令行,中文、引号、特殊字符较多时,直接拼接 --slides 容易发生 shell 转义或截断。建议将每页 XML 保存为独立文件,使用 `jq --rawfile` 组装 JSON 数组,避免手动处理 XML 引号和换行。 - ## 命令 ```bash @@ -153,4 +143,5 @@ lark-cli slides xml_presentation.slide create --as user \ ## 相关命令 -- [slides +xml-get](lark-slides-xml-get.md) — 读取 PPT 内容并保存到本地文件 +- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面 +- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容并保存到本地文件 diff --git a/skills/lark-slides/references/lark-slides-media-upload.md b/skills/lark-slides/references/lark-slides-media-upload.md index 8fbe5fd7f0..0031000da5 100644 --- a/skills/lark-slides/references/lark-slides-media-upload.md +++ b/skills/lark-slides/references/lark-slides-media-upload.md @@ -1,8 +1,6 @@ # slides +media-upload(上传本地图片到飞书幻灯片) -> **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - 把本地图片上传到指定演示文稿的 drive 媒体库,返回 `file_token`。**返回的 token 作为 `` 的值塞进 slide XML 即可显示图片。** ## 命令 @@ -125,3 +123,4 @@ lark-cli slides +replace-slide --as user \ - [+create](lark-slides-create.md) — 新建 PPT(支持 `@` 占位符自动上传图片) - [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图(`block_insert` / `block_replace`) +- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 创建 slide 页面(拿到 file_token 后塞进 XML) diff --git a/skills/lark-slides/references/lark-slides-pptx-template-workflows.md b/skills/lark-slides/references/lark-slides-pptx-template-workflows.md index 1d678eff48..da452a5ca7 100644 --- a/skills/lark-slides/references/lark-slides-pptx-template-workflows.md +++ b/skills/lark-slides/references/lark-slides-pptx-template-workflows.md @@ -1,12 +1,12 @@ # PPT Template Rewrite Principles -本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides,并要求基于它二次创作”的场景。核心原则:模板不是风格参考,而是必须沿用的编辑底稿。 +核心原则:模板不是风格参考,而是必须沿用的编辑底稿。 ## Import First -用户指定 PPT 模板时,先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides,不是新建一个脱离模板的 deck,也不是先在本地重画 PPTX 再导入。 +如果用户提供的模板是 PPTX 格式,先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides,不是新建一个脱离模板的 deck,也不是先在本地重画 PPTX 再导入。 -直接使用以下命令,不需要先加载 `lark-drive` skill: +直接使用以下命令,不需要先加载 `lark-drive` Skill: ```bash lark-cli drive +import --as user --file "" --type slides --json @@ -18,13 +18,9 @@ lark-cli drive +import --as user --file "" --type slides --json lark-cli drive +task_result --scenario import --ticket ``` -导入后必须回读 Slides 内容,理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。 - ## Read Before Editing -编辑任何 PPT 页面前,必须先阅读该页面。 - -如果当前上下文中没有该页内容,必须重新读取页面;这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。 +导入后必须阅读 Slides 内容,理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。阅读结果是后续编辑的事实来源。 阅读页面时至少判断: @@ -47,7 +43,7 @@ lark-cli drive +task_result --scenario import --ticket ## Preserve Design -模板二创必须严格沿用原版式和字体,只改内容,不做设计。 +编辑必须严格沿用原版式和字体,只改内容,不做设计。 默认保留: @@ -56,7 +52,7 @@ lark-cli drive +task_result --scenario import --ticket - 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。 - 模板中不同页型之间的差异。 -不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。 +不要把模板页改造成统一的通用卡片、空白板式布局、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。 ## Content Only @@ -86,4 +82,4 @@ lark-cli drive +task_result --scenario import --ticket 发现文字溢出时,优先凝练文字或缩减字号。发现遮挡时,调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时,才做局部新增或删除。 -模板二创的完成标准不是“生成了一套看起来统一的新 PPT”,而是“原模板的版式、字体和视觉结构仍清晰存在,内容已经被准确替换,并且回读后没有溢出和遮挡”。 +完成标准是“原模板的版式、字体和视觉结构仍清晰存在,内容已经被准确替换,并且回读后没有溢出和遮挡”。 diff --git a/skills/lark-slides/references/lark-slides-replace-slide.md b/skills/lark-slides/references/lark-slides-replace-slide.md index f9d4b5b372..aab572d8d1 100644 --- a/skills/lark-slides/references/lark-slides-replace-slide.md +++ b/skills/lark-slides/references/lark-slides-replace-slide.md @@ -1,7 +1,5 @@ # slides +replace-slide(块级替换 / 插入) -> **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - 对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。 相比直接调 `xml_presentation.slide.replace`,这个 shortcut 的四个额外价值: @@ -88,7 +86,6 @@ lark-cli slides +replace-slide --as user \ | `
` | 表格 | 整表替换会**重建内部 td id**,旧 td block_id 立即失效 | | `
` | 单元格局部替换 | 只能 `block_replace`,不能 `block_insert`;`block_id` 必须是最新 `slide.get` 拿到的 td id | | `` | 图表(line/bar/column/pie/area/radar/combo) | 必须嵌 `` + `` + `//` | -| `` | 画板(SVG 或 Mermaid) | 内嵌 `` 或 ``;`slide.get` 返回结构不含内部数据,但可直接写完整新 XML 做 `block_replace` 覆盖;详见 [`lark-slides-whiteboard.md`](lark-slides-whiteboard.md) | **不可作为根元素**: diff --git a/skills/lark-slides/references/lark-slides-screenshot.md b/skills/lark-slides/references/lark-slides-screenshot.md index 1ae9a41243..74d8c69070 100644 --- a/skills/lark-slides/references/lark-slides-screenshot.md +++ b/skills/lark-slides/references/lark-slides-screenshot.md @@ -4,7 +4,7 @@ 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图;传入 `--content` 时用于直接渲染单个 `` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件,stdout 只返回文件路径、大小、页面 ID 等元信息,避免把图片 Base64 输出给模型。 -注意:该截图能力受应用白名单限制,绝大多数应用不可用。若截图失败,记录错误即可;不要引导用户申请 `slides:presentation:screenshot` 权限。后续按 `validation-checklist.md` 走非截图验证,不要声称已完成截图验收。 +注意:该截图能力受应用白名单限制,绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限;记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。 ## 命令 diff --git a/skills/lark-slides/references/lark-slides-whiteboard.md b/skills/lark-slides/references/lark-slides-whiteboard.md deleted file mode 100644 index 8d8b27579a..0000000000 --- a/skills/lark-slides/references/lark-slides-whiteboard.md +++ /dev/null @@ -1,331 +0,0 @@ -# Whiteboard 画板元素 - -`` 放在 `` 内,内部可放 **SVG** 或 **Mermaid**,用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `` 和 `` 难以覆盖的视觉内容。 - -普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 ``。除非用户明确要求像素级自定义,或图表类型确实不受 `` 支持,否则不要用 `` + SVG / Mermaid 重画这些标准图表。 - -> 前置条件:使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。 - ---- - -## `` 还是 ``? - -**先判断内容类型,再进入本文档:** - -| 场景 | 推荐元素 | -|------|---------| -| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `` — 原生渲染,支持 legend / tooltip / 系列配色 | -| 散点图、漏斗图(`` 不支持)或其他非原生数据视觉 | `` SVG | -| 流程图、时序图、架构图、类图、ER 图等拓扑图 | `` Mermaid 或 SVG | -| 自定义图标、徽标、示意性图形(需要 path/polygon 精确控制) | `` SVG | -| 进度条、波浪背景、装饰图案、像素级自定义可视化 | `` SVG | - -> 适合 `` 的内容就用 ``,不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定,也更容易被回读和后续编辑。 - ---- - -## whiteboard 公共属性 - -| 属性 | 必需 | 说明 | -|------|------|------| -| `topLeftX` | 是 | 左上角 X 坐标(slide 坐标系,slide 默认宽 960) | -| `topLeftY` | 是 | 左上角 Y 坐标(slide 坐标系,slide 默认高 540) | -| `width` | 是 | 画板宽度(像素) | -| `height` | 是 | 画板高度(像素) | - -> SVG 模式下 `` 需声明 `xmlns="http://www.w3.org/2000/svg"`;内容大小由子元素包围盒决定,`width`/`height`/`viewBox` 不影响渲染(仅当元素属性使用百分比值时需要 `viewBox` 提供计算基准)。Mermaid 模式不需要额外属性。 - -SVG 内的坐标相对于 whiteboard 自身左上角(0,0),与 slide 坐标系无关。 - ---- - -## SVG 还是 Mermaid? - -选择分三步:**先排除原生 ``,再判断 whiteboard 类型,最后看当前模型身份**。 - -### 第一步:先确认是否应该使用 `` - -如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图,返回使用原生 ``,不要继续套用本文档的 SVG / Mermaid 路径。 - -### 第二步:whiteboard 类型优先判断 - -以下类型**推荐 Mermaid**,自动布局、代码简洁;如需精确匹配品牌配色或自定义节点样式,可改用 SVG: - -| 图表类型 | Mermaid 关键字 | -|----------|--------------| -| 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` | -| 时序图 | `sequenceDiagram` | -| 类图 | `classDiagram` | -| 甘特图 | `gantt` | -| 状态图 | `stateDiagram-v2` | -| 思维导图 | `mindmap` | -| ER 图 | `erDiagram` | - -### 第三步:非原生图表与装饰元素按模型身份选路径 - -上表以外的场景(散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等)需要精确控制坐标和配色,SVG 表达力更强,但各模型生成 SVG 的能力有差异: - -| 模型身份 | 路径 | -|----------|------| -| Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 | -| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达;确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 | - -> **先自报身份再选路径**:在决定使用 SVG 之前,确认当前模型属于哪一类。不要跳过这一步。 - ---- - -## 模式一:SVG - -### ⚠️ 设计品质要求 - -在 slide 里嵌入 `` 的目的是**表达原生 `` 或基础 `` 难以覆盖的视觉关系**,不是把标准数据图表手绘一遍。 - -- **不要只用矩形加文字应付**:通篇纯白底色 + 方块 + 黑字等于白做,这是不及格输出 -- **非原生数据视觉必须有坐标系**:散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明,不要只画点或色块 -- **字号必须有层级**:标题 ≠ 标签 ≠ 数值,混用同一字号会消灭视觉焦点 -- **配色要与 slide 主题呼应**:深色 slide 背景下图表用透明底或深色卡片;浅色背景下避免再加纯白底块 -- **每个 whiteboard 都是设计机会**:主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距 -- **写 SVG 前先判断背景亮度**:背景亮度 < 30% 时,装饰元素"对比不足"比"过强"危害更大,宁重勿轻; -- **装饰层次用亮度跳跃,不用线性叠透明度**:`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异(相邻层亮度差 ≈20);正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`,相邻层亮度差 ≥60。 - -### 语法 - -```xml - - - - ABC - - -``` - -`` 需声明 `xmlns="http://www.w3.org/2000/svg"`;`width`/`height`/`viewBox` 无需填写,若元素属性使用百分比值则需额外声明 `viewBox`。 - -### ⚠️ 渲染包围盒规则 - -whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内容区域,自适应缩放到容器。 - -`` 上的 `width`、`height`、`viewBox` 不影响内容区域的计算,但 `viewBox` 有一个实际用途:**为百分比属性提供计算基准**。若元素使用 `width="50%"` 等百分比值,必须声明 `viewBox` 才能正确解析;绝对坐标元素则无需关心。推荐统一使用绝对坐标,避免引入百分比依赖。 - -### 支持的 SVG 元素 - -| 元素 | 说明 | 典型用途 | -|------|------|---------| -| `` | 矩形,支持 `rx` 圆角 | 卡片、进度条、分段色块 | -| `` | 圆 | 节点、装饰点、环形图 | -| `` | 椭圆 | 自定义轮廓图形 | -| `` | 直线 | 轴线、分隔线、连接线 | -| `` | 任意路径(支持 Q/C 曲线) | 波浪、曲线、弧形 | -| `` | 文本,支持中文 | 标签、数值 | -| `` | 多边形 | 箭头、星形、面积填充 | -| `` | 分组 | 批量变换、语义分组 | -| `` | 线性渐变定义,配合 `fill="url(#id)"` 使用 | 渐变背景、渐变填充 | - -**颜色:** 统一用 `rgba(R,G,B,A)`,对深浅背景都友好。 -**虚线:** `stroke-dasharray="4,4"` 用于网格线 / 坐标轴。 -**变换:** `transform="translate(x,y)"` / `rotate(deg cx cy)` / `scale(n)` 均支持。 - ---- -### 元素计算 - -SVG 中只要涉及批量定位、等间距排布或数据映射,**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**,而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等;普通柱状图、折线图、饼图仍应回到原生 ``。 - -> **主动去算**:写 SVG 之前先运行脚本,把输出当注释贴在 `` 开头,再照着填坐标。估值几乎每次都需要反复调整,跳过这步反而更慢。 - -**散点图 / 装饰性点阵范式** - -```python -W, H = 360, 260 -origin_x, origin_y = 50, 216 # 左下角,SVG Y 轴向下 -cw, ch = 290, 184 - -points = [(12, 40), (28, 80), (45, 65)] -x_min, x_max, y_min, y_max = 0, 50, 0, 100 -for i, (xv, yv) in enumerate(points): - x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw) - y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch) - print(f"point-{i}: cx={x} cy={y}") -``` - -**装饰性元素(等间距范式)** - -```python -n, total_w, cy, r = 8, 340, 40, 4 -step = total_w / (n - 1) -for i in range(n): - print(f"circle-{i}: cx={round(i * step)} cy={cy} r={r}") -``` - -**最大包围盒 → whiteboard 尺寸** - -所有元素坐标算完后,汇总出整体包围盒,直接作为 whiteboard 的 `width`/`height`: - -```python -# 每个元素登记 (x, y, w, h),含 stroke 外扩 -elements = [ - (10, 20, 80, 160), # item-0 - (107, 10, 80, 170), # item-1 - (204, 40, 80, 140), # item-2 - (0, 0, 300, 1), # x-axis -] - -xs = [x for x, y, w, h in elements] -ys = [y for x, y, w, h in elements] -x2 = [x + w for x, y, w, h in elements] -y2 = [y + h for x, y, w, h in elements] - -wb_w = max(x2) - min(xs) -wb_h = max(y2) - min(ys) -print(f"whiteboard width={wb_w} height={wb_h}") -``` - -输出即 `` 的值,无需手动估算。 - ---- -### 布局模式 - -**全屏装饰层** -```xml - - - ... - - -``` - -> ⚠️ 全屏装饰 whiteboard 必须放在所有 `` / `` / `` 之前,否则会遮挡文字内容。XML 中元素位置越靠后,渲染层级越高。 - -**侧栏图表(与文字 shape 并排)** -```xml - -... - - - - ... - - -``` - -**底部装饰条** -```xml - - - ... - - -``` - ---- - -### 禁止使用的 SVG 特性 - -以下特性在 slide `` 渲染端不支持或行为不可预测,必须避免: - -| 禁止 | 原因 | 替代方案 | -|------|------|---------| -| `` | 渲染失败 | 用 `` 或 `rgba()` 透明度模拟深浅层次 | -| ``(阴影、模糊等) | 渲染失败 | 用半透明 `` 叠加模拟阴影 | -| `` / `` | 渲染失败 | 调整元素坐标和尺寸自然裁切 | -| `` | 渲染失败 | 手动铺 `` / `` 点阵 | -| `skewX` / `skewY` / `matrix(...)` | 空间扭曲,降级渲染 | 用 `rotate` + `translate` 替代 | -| `` 外链 URL | 不支持外链 | 先上传得到 file_token,再用 `` 元素 | - ---- - - -## 模式二:Mermaid - -### 语法 - -```xml - - - B[编写每页 slide XML] - B --> C[通过 jq 生成 slides JSON] - C --> D[执行 slides +create] - D --> E[读取 xml_presentation_id] - E --> F[回读并验证创建结果] - ]]> - - -``` - -**关键点:** -- 内容用 `` 包裹——Mermaid 语法里的 `[`、`>`、`-->` 是 XML 特殊字符,CDATA 避免转义问题 -- whiteboard 只需 `topLeftX`、`topLeftY`、`width`、`height` - -### 支持的 Mermaid 图表类型 - -| 类型 | 关键字 | 适用场景 | -|------|--------|---------| -| 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 | -| 时序图 | `sequenceDiagram` | 系统交互、API 调用链 | -| 甘特图 | `gantt` | 项目计划、里程碑 | -| 类图 | `classDiagram` | 对象关系、架构设计 | -| ER 图 | `erDiagram` | 数据库结构 | -| 状态图 | `stateDiagram-v2` | 状态机、生命周期 | -| 思维导图 | `mindmap` | 主题梳理、知识架构 | -| 用户旅程 | `journey` | 用户体验路径 | - -### Mermaid 布局建议 - -Mermaid 图表会自动撑满 whiteboard 区域。建议: -- 流程图留足高度,节点较多时适当增加 height(比如 400-480) -- 避免一页放超过 15 个节点,内容太密时考虑分页 -- 推荐尺寸参考: - -| 图表类型 | 建议 width | 建议 height | -|---------|-----------|------------| -| 流程图(5-8 节点) | 720-816 | 300-400 | -| 时序图(3-5 参与者) | 720-816 | 320-420 | -| 甘特图 | 816 | 280-360 | -| 思维导图 | 816 | 380-480 | - ---- - -## 注意事项 & 已知问题 - -### z-order(SVG 模式) - -whiteboard 在 XML 中的位置决定渲染层级:在 shape 前 → 在下层;在 shape 后 → 在上层。全屏装饰 whiteboard 应放在所有 shape 之前。 - -### Mermaid CDATA 必要性 - -Mermaid 语法包含 `[`、`>`、`-->`,不用 CDATA 直接写会破坏 XML 解析。始终使用 ``。 - ---- - -## 快速自检清单 - -**SVG 模式——结构检查:** -- [ ] `` 声明了 `xmlns="http://www.w3.org/2000/svg"` -- [ ] whiteboard 的 `width`/`height` 由所有元素的最大包围盒(含 stroke 外扩)计算得出,不手动估值 -- [ ] `topLeftX + width ≤ 960`,`topLeftY + height ≤ 540` -- [ ] 无 `` / `` / `` -- [ ] 文字 `y` 坐标为 baseline 位置,最小值 ≥ font-size(避免被裁切) - -**SVG 模式——视觉品质检查:** -- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明,没有"裸点"或无解释色块 -- [ ] 字号有层级:标题 > 数值 > 轴标签,非全部相同 -- [ ] 单一数据系列用同一颜色,多系列用不同颜色且对比充足 -- [ ] 轴标签与图表元素互不遮挡,留有足够空间 -- [ ] 坐标推导有注释(写明 originX/Y、chartW/H、数据映射公式) - -**Mermaid 模式:** -- [ ] 内容包在 `...` 内 -- [ ] CDATA 结束符 `]]>` 不出现在 Mermaid 代码本身中 -- [ ] `topLeftX + width ≤ 960`,`topLeftY + height ≤ 540` -- [ ] 节点数量合理(单图不超过 15-20 个节点) - -**通用:** -- [ ] XML 标签全部闭合,属性引号完整 -- [ ] 如果失败,检查是否是偶发 5001000,重试一次 - ---- - -## 参考 - -- [lark-slides SKILL.md](../SKILL.md) diff --git a/skills/lark-slides/references/lark-slides-xml-get.md b/skills/lark-slides/references/lark-slides-xml-get.md deleted file mode 100644 index d4369efd44..0000000000 --- a/skills/lark-slides/references/lark-slides-xml-get.md +++ /dev/null @@ -1,100 +0,0 @@ -# slides +xml-get(读取 XML) - -读取已有演示文稿的完整 XML,或按 `slide_id` / 页码读取单页 XML。适合创建后验收、编辑前备份、获取 `slide_id` / `revision_id`,以及排查空白页、破图、文本溢出等问题。相比直接调用底层 `xml_presentations.get` / `xml_presentation.slide.get`,本 shortcut 会自动解析 Slides URL / Wiki URL,并可把 XML 保存到本地文件,避免终端输出被截断。 - -## 命令 - - -```bash -lark-cli slides +xml-get \ - --as user \ - --presentation \ - --output .lark-slides/plan//readback.xml -``` - -## 参数 - -| 参数 | 必需 | 说明 | -|------|------|------| -| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL | -| `--output` | 否 | 本地 XML 保存路径,必须是当前工作目录内的相对路径,不能传绝对路径。传入时 XML 内容保存到文件,stdout 只返回保存后的绝对路径、大小等简短元信息;省略时默认返回 JSON envelope | -| `--slide-id` | 否 | 页面 short ID;传入后只读取该页 XML。不能和 `--slide-number` 同时使用 | -| `--slide-number` | 否 | 1-based 页码;传入后只读取该页 XML。不能和 `--slide-id` 同时使用 | -| `--revision-id` | 否 | 读取指定版本;默认 `-1`,表示最新版本 | -| `--remove-attr-id` | 否 | 仅全文读取可用。移除返回 XML 中的 `id` 属性;适合只读检查,不适合精确块级编辑 | -| `--raw` | 否 | 省略 `--output` 时直接把 XML 原文写到 stdout,不包 JSON envelope。不能和 `--output` / `--jq` / 非 json `--format` 同时使用 | -| `--dry-run` | 否 | 预览将调用的 API 和输出方式,不读取真实 XML | - -## 输出到文件 - -推荐普通工作流都传 `--output`,尤其是中大型 PPT。`--output` 必须是当前工作目录内的相对路径,例如 `.lark-slides/plan/$PID/readback.xml`,不要传 `/tmp/readback.xml` 这类绝对路径。XML 会写入本地文件,stdout 只保留元信息,便于后续脚本读取。 - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PID" \ - --output .lark-slides/plan/$PID/readback.xml -``` - -成功输出中的 `data` 类似: - -```json -{ - "xml_presentation_id": "slides_example_presentation_id", - "path": "/abs/path/.lark-slides/plan/slides_example_presentation_id/readback.xml", - "size": 123456, - "content_saved": true, - "revision_id": 12 -} -``` - -其中 `path` 是 CLI 解析后的绝对路径。 - -如果传入 `--remove-attr-id`,返回元信息中会包含 `"remove_attr_id": true`。 - -## 读取单页 - -已知页面 short ID 时,用 `--slide-id`: - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PID" \ - --slide-id "$SID" \ - --output .lark-slides/plan/$PID/slide-$SID.xml -``` - -已知页码时,用 `--slide-number`(页码从 1 开始): - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PID" \ - --slide-number 2 \ - --output .lark-slides/plan/$PID/slide-2.xml -``` - -单页模式底层调用 `xml_presentation.slide.get`,返回或保存的是单个 `` XML 片段。`--slide-id` 和 `--slide-number` 不能同时传;`--remove-attr-id` 只支持全文读取。 - -## 输出到终端 - -省略 `--output` 时,CLI 默认输出 JSON envelope,XML 位于 `data.xml_presentation.content`(全文)或 `data.slide.content`(单页)。这个模式适合配合 `--jq` 临时提取: - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PID" \ - --jq '.data.xml_presentation.content' -``` - -需要把 XML 原文直接写到 stdout 时,加 `--raw`: - -```bash -lark-cli slides +xml-get --as user \ - --presentation "$PID" \ - --slide-number 2 \ - --raw -``` - -## 相关命令 - -- [slides +screenshot](lark-slides-screenshot.md) - 获取页面截图做视觉验证 -- [slides +replace-slide](lark-slides-replace-slide.md) - 局部替换或插入页面元素 -- [slides +replace-pages](lark-slides-replace-pages.md) - 多页整页重建 -- [xml_presentations get](lark-slides-xml-presentations-get.md) - 底层原生 API 参考 diff --git a/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md b/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md new file mode 100644 index 0000000000..2cafbd0880 --- /dev/null +++ b/skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md @@ -0,0 +1,219 @@ +# lark-slides xml_presentation.slide create + +## 用途 + +在指定的 XML 演示文稿中创建新的幻灯片页面,通常用于给 `slides +create` 创建出的空白 PPT 逐页补充内容。 + +## 命令 + +```bash +lark-cli slides xml_presentation.slide create --as user --params '' --data '' +``` + +## 参数说明 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `--params` | JSON string | 是 | 路径参数与查询参数 | +| `--data` | JSON string | 是 | 请求体,包含新页面内容 | + +### params JSON 结构 + +```json +{ + "xml_presentation_id": "slides_example_presentation_id", + "revision_id": -1, + "tid": "idMock" +} +``` + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `xml_presentation_id` | string | 是 | 目标演示文稿的唯一标识符 | +| `revision_id` | integer | 否 | 演示文稿版本号,`-1` 表示最新版本 | +| `tid` | string | 否 | 锁的事务 ID | + +### data JSON 结构 + +```json +{ + "slide": { + "slide_id": "slide_example_id", + "content": "..." + }, + "before_slide_id": "slide_before_target" +} +``` + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `slide.slide_id` | string | 否 | 幻灯片页面 short ID | +| `slide.content` | string | 否 | 新幻灯片的 XML 内容 | +| `before_slide_id` | string | 否 | 插入到指定页面之前 | + +## slide XML 结构 + +`slide.content` 是一个完整的 `` 元素,遵循 SML 2.0 Schema: + +```xml + + + + +

标题

+ + + + +``` + +详细格式请参考 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。 + +## 使用示例 + +### 在末尾添加幻灯片 + +```bash +lark-cli slides xml_presentation.slide create --as user --params '{ + "xml_presentation_id": "slides_example_presentation_id" +}' --data '{ + "slide": { + "content": "

新页面标题

内容文本

" + } +}' +``` + +### 在指定页面前插入幻灯片 + +```bash +lark-cli slides xml_presentation.slide create --as user --params '{ + "xml_presentation_id": "slides_example_presentation_id" +}' --data '{ + "slide": { + "content": "

插入的标题页

" + }, + "before_slide_id": "slide_before_target" +}' +``` + +### 带图形元素的幻灯片 + +```bash +lark-cli slides xml_presentation.slide create --as user --params '{ + "xml_presentation_id": "slides_example_presentation_id" +}' --data '{ + "slide": { + "content": "

数据展示

" + } +}' +``` + +### 从文件读取 XML + +```bash +# 先创建 slide.xml 文件 +cat > slide.xml << 'EOF' + + + + +

从文件加载

+
+
+ + +

这是从文件读取的幻灯片内容

+
+
+
+
+EOF + +# 然后创建幻灯片 +lark-cli slides xml_presentation.slide create --as user \ + --params '{"xml_presentation_id":"slides_example_presentation_id"}' \ + --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')" +``` + +## 返回值 + +成功时返回创建的幻灯片信息: + +```json +{ + "code": 0, + "data": { + "slide_id": "slide_example_id", + "revision_id": 100 + }, + "msg": "success" +} +``` + +### 返回字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `data.slide_id` | string | 新幻灯片的唯一标识 | +| `data.revision_id` | integer | 演示文稿最新版本号 | + +## slide 元素可用子元素 + +| 元素 | 说明 | +|------|------| +| ` - - -

主标题

-
- -

副标题

-
- -

底部信息

-
-
- -``` - -## 浅色内容页 - -```xml - - - - - - - -

页面标题

-
- - -

正文段落

-
    -
  • 要点一

  • -
  • 要点二

  • -
  • 要点三

  • -
-
-
-
-
-``` - -## 数据卡片页(横排指标) - -```xml - - - - -

数据概览

-
- - - - - - -

数值

-
- -

指标名称

-
- - -
-
-``` - -## 带图版式 - -> **关键提醒**:`` 的 `width:height` = 原图比例时才不会被裁剪。每个模板都标注了图框比例和建议原图比例,**选模板前先对照你的素材比例**,不要硬塞(如把横图放进竖框,会被左右裁掉大半)。把 `@./your-image.jpg` 替换为实际路径(仅 `+create --slides` 支持 `@` 占位符;其他场景需先用 `slides +media-upload` 拿 `file_token`)。 - -### 封面右图(左字右图) - -图框 400×225(**16:9**),建议原图:横幅 16:9(桌面壁纸、产品 banner、landscape 照片) - -```xml - - - - -

主标题

-
- -

副标题

-
- - - - -

底部信息

-
- - -
-
-``` - -### 三卡片带图(上图下文) - -每个图框 240×180(**4:3**),建议原图:4:3 或接近正方形的图(产品照、截图、icon 类) - -```xml - - - - -

核心亮点

-
- - - - - - - - - - - - -

特性一

-
- -

简短描述文案,控制在两行以内。

-
- - - -
-
-``` - -### 左右分栏(图在左,文在右) - -图框 360×540(**2:3 竖幅**),建议原图:2:3 或 3:4 竖幅(人像照、产品竖拍、海报) - -> 如果你只有横幅图,不要硬塞进这个竖框 —— 改用"顶部横幅图 + 下方文字"的版式(把这里的图框改成 960×240 横条放在顶部)。 - -```xml - - - - - - - -

场景标题

-
- - - - -

一句话描述这个场景的价值。

-
- - -
    -
  • 要点一

  • -
  • 要点二

  • -
  • 要点三

  • -
-
-
-
-
-``` - -## 深色结尾页 - -```xml - - - - -

感谢语或行动号召

-
- - - - -

补充说明

-
-
-
-``` diff --git a/skills/lark-slides/references/slides_chart_demo.xml b/skills/lark-slides/references/slides_chart_demo.xml index 21e9eb8053..53fcdb3952 100644 --- a/skills/lark-slides/references/slides_chart_demo.xml +++ b/skills/lark-slides/references/slides_chart_demo.xml @@ -1 +1,1416 @@ -全球消费电子市场洞察 · 图表可视化 Demo

CONSULTING INSIGHTS · MARKET SERIES 2026 / Q3

全球消费电子市场洞察

数据可视化图谱 · Chart Library Demo

覆盖柱状 · 折线 · 饼图 · 条形 · 面积 · 散点 · 组合 · 雷达 · 其他 九大类

Prepared by Consulting Insights · July 2026

Strictly Private & Confidential

目录 · 图表类型索引

CHART LIBRARY OVERVIEW · 9 CATEGORIES

SECTION 00 / OVERVIEW

数据比较类

01

柱状图 Column

分组 / 堆叠 / 百分比堆叠

02

条形图 Bar

分组 / 堆叠 / 百分比堆叠

03

饼图 Pie

饼图 / 环形图

趋势与结构类

04

折线图 Line

直线 / 平滑 / 阶梯

05

面积图 Area

分组 / 堆叠 / 百分比堆叠

关系与多维类

06

散点图 Scatter

散点图 / 气泡图

07

组合图 Combo

柱状 + 折线 双轴组合

08

雷达图 Radar

多边形 / 圆形 / 无填充

其他

09

其他 Others

词云 / 漏斗 / 帕累托

Consulting Insights © 2026 · CE Market Series

02 / 12

柱状图 · Column Chart

季度出货量对比 · GROUPED / STACKED / 100% STACKED

SECTION 01 / COLUMN

① 分组柱状图 · Grouped

2024Q1,2024Q2,2024Q3,2024Q452,48,55,6860,58,63,72智能手机季度出货(百万台)

② 堆叠柱状图 · Stacked

2024Q1,2024Q2,2024Q3,2024Q480,85,92,10545,52,58,66收入结构(亿美元)

③ 百分比堆叠 · 100% Stacked

北美,欧洲,亚太,拉美0.55,0.42,0.3,0.280.45,0.58,0.7,0.72区域市场份额构成

Source: Consulting Insights Research · 数据仅用于示意

03 / 12

折线图 · Line Chart

用户规模趋势 · STRAIGHT / SMOOTH / STEP

SECTION 02 / LINE

① 直线折线图 · Straight

1月,2月,3月,4月,5月,6月120,135,128,152,168,180200,215,232,228,250,265MAU 月活跃用户(百万)

② 平滑折线图 · Smooth

1月,2月,3月,4月,5月,6月42,58,55,72,88,9678,82,96,102,118,132DAU 日活跃用户(百万)

③ 阶梯折线图 · Step

1月,2月,3月,4月,5月,6月999,999,899,899,799,799699,699,649,599,599,549定价调整轨迹(美元)

Source: Consulting Insights Research · 数据仅用于示意

04 / 12

饼图 · Pie Chart

市场份额结构 · PIE / DONUT

SECTION 03 / PIE

① 饼图 · Pie

Apple,Samsung,Xiaomi,Huawei,Others28,24,15,12,21全球智能手机品牌份额 2026H1

② 环形图 · Donut

硬件,服务,可穿戴,其他52,26,15,7收入结构(按业务线)

Source: Consulting Insights Research · 数据仅用于示意

05 / 12

条形图 · Bar Chart

横向排名对比 · GROUPED / STACKED / 100% STACKED

SECTION 04 / BAR

① 分组条形图 · Grouped

手机,平板,手表,耳机180,68,42,96210,82,58,132品类销售对比(万台)

② 堆叠条形图 · Stacked

手机,平板,手表,耳机125,45,32,7885,37,26,54渠道构成(万台)

③ 百分比堆叠 · 100% Stacked

手机,平板,手表,耳机1.25,0.45,0.32,0.780.85,0.37,0.26,0.54渠道占比结构

Source: Consulting Insights Research · 数据仅用于示意

06 / 12

面积图 · Area Chart

体量与结构演进 · OVERLAY / STACKED / 100% STACKED

SECTION 05 / AREA

① 重叠面积图 · Overlay

2021,2022,2023,2024,2025,2026180,210,245,268,295,322120,155,180,220,258,296全年营收走势(亿美元)

② 堆叠面积图 · Stacked

2021,2022,2023,2024,2025,2026180,210,245,268,295,322120,155,180,220,258,296总营收堆叠视图

③ 百分比堆叠 · 100% Stacked

2021,2022,2023,2024,2025,2026180,210,245,268,295,322120,155,180,220,258,296区域营收占比演进

Source: Consulting Insights Research · 数据仅用于示意

07 / 12

散点图 · Scatter & Bubble

价格-口碑二维分布 & 三维气泡 · SCATTER / BUBBLE

SECTION 06 / SCATTER

① 散点图 · Scatter

② 气泡图 · Bubble

Source: Consulting Insights Research · 数据仅用于示意

08 / 12

组合图 · Combo Chart

营收规模 & 增长率双轴视图 · COLUMN + LINE

SECTION 07 / COMBO

八季度营收与同比增速

24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4180,195,210,245,220,238,258,2960.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21营收(亿美元, 左轴) · 同比增速(%, 右轴)

KEY TAKEAWAY

营收连续 6 季度双位数增长

24Q4 - 25Q4 期间同比增速稳定在 18-23%,营收规模从 245 亿扩张至 296 亿美元。

WHAT TO WATCH

· 25Q4 增速首次微降 2pp

· 高基数效应即将显现

· 需关注亚太区库存周期

Source: Consulting Insights Research · 数据仅用于示意

09 / 12

雷达图 · Radar Chart

产品能力多维对比 · POLYGON / CIRCLE / OUTLINE

SECTION 08 / RADAR

① 多边形雷达 · Polygon

性能,续航,拍照,屏幕,系统,生态9,7,8,9,8,97,9,9,7,8,6旗舰机型能力评估

② 圆形雷达 · Circle

性能,续航,拍照,屏幕,系统,生态7,8,6,8,7,78,6,7,7,8,8中端机型能力评估

③ 无填充雷达 · Outline

性能,续航,拍照,屏幕,系统,生态6,7,5,6,6,55,6,6,5,7,6入门机型能力评估

Source: Consulting Insights Research · 数据仅用于示意

10 / 12

其他 · Word Cloud · Funnel · Pareto

词云 / 漏斗 / 帕累托 · 补充可视化视角

SECTION 09 / OTHERS

① 词云图 · Word Cloud

② 漏斗图 · Funnel

③ 帕累托图 · Pareto

Source: Consulting Insights Research · 数据仅用于示意

11 / 12

+ + + 原生图表 Chart Demo + + + + + +
+ + + + + + + + + + + + + + + + + + + +

柱状图 · Column Chart

+
+
+ + +

季度出货量对比 · GROUPED / STACKED / 100% STACKED

+
+
+ + +

SECTION 01 / COLUMN

+
+
+ + + + + + + + + + + + + + + +

① 分组柱状图 · Grouped

+
+
+ + + + + + + + + + + + + + + + + + + 2024Q1,2024Q2,2024Q3,2024Q4 + + + 52,48,55,68 + 60,58,63,72 + + + 智能手机季度出货(百万台) + + + + + + + + + + + + + + + + + + + + + + + + +

② 堆叠柱状图 · Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + 2024Q1,2024Q2,2024Q3,2024Q4 + + + 80,85,92,105 + 45,52,58,66 + + + 收入结构(亿美元) + + + + + + + + + + + + + + + + + + + + + + + + +

③ 百分比堆叠 · 100% Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + 北美,欧洲,亚太,拉美 + + + 0.55,0.42,0.3,0.28 + 0.45,0.58,0.7,0.72 + + + 区域市场份额构成 + + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

03 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

折线图 · Line Chart

+
+
+ + +

用户规模趋势 · STRAIGHT / SMOOTH / STEP

+
+
+ + +

SECTION 02 / LINE

+
+
+ + + + + + + + + + + + + + + +

① 直线折线图 · Straight

+
+
+ + + + + + + + + + + + + + + + + + + 1月,2月,3月,4月,5月,6月 + + + 120,135,128,152,168,180 + 200,215,232,228,250,265 + + + MAU 月活跃用户(百万) + + + + + + + + + + + + + + + + + + + + + + + + +

② 平滑折线图 · Smooth

+
+
+ + + + + + + + + + + + + + + + + + + + + 1月,2月,3月,4月,5月,6月 + + + 42,58,55,72,88,96 + 78,82,96,102,118,132 + + + DAU 日活跃用户(百万) + + + + + + + + + + + + + + + + + + + + + + + + +

③ 阶梯折线图 · Step

+
+
+ + + + + + + + + + + + + + + + + + + + + 1月,2月,3月,4月,5月,6月 + + + 999,999,899,899,799,799 + 699,699,649,599,599,549 + + + 定价调整轨迹(美元) + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

04 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

饼图 · Pie Chart

+
+
+ + +

市场份额结构 · PIE / DONUT

+
+
+ + +

SECTION 03 / PIE

+
+
+ + + + + + + + + + + + + + + +

① 饼图 · Pie

+
+
+ + + + + + + + + + + Apple,Samsung,Xiaomi,Huawei,Others + + + 28,24,15,12,21 + + + 全球智能手机品牌份额 2026H1 + + + + + + + + + + + + + + + + + + + + + + + + + + + +

② 环形图 · Donut

+
+
+ + + + + + + + + + + + + + + 硬件,服务,可穿戴,其他 + + + 52,26,15,7 + + + 收入结构(按业务线) + + + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

05 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

条形图 · Bar Chart

+
+
+ + +

横向排名对比 · GROUPED / STACKED / 100% STACKED

+
+
+ + +

SECTION 04 / BAR

+
+
+ + + + + + + + + + + + + + + +

① 分组条形图 · Grouped

+
+
+ + + + + + + + + + + + + + + + + + + 手机,平板,手表,耳机 + + + 180,68,42,96 + 210,82,58,132 + + + 品类销售对比(万台) + + + + + + + + + + + + + + + + + + + + + + + + +

② 堆叠条形图 · Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + 手机,平板,手表,耳机 + + + 125,45,32,78 + 85,37,26,54 + + + 渠道构成(万台) + + + + + + + + + + + + + + + + + + + + + + + + +

③ 百分比堆叠 · 100% Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + 手机,平板,手表,耳机 + + + 1.25,0.45,0.32,0.78 + 0.85,0.37,0.26,0.54 + + + 渠道占比结构 + + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

06 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

面积图 · Area Chart

+
+
+ + +

体量与结构演进 · OVERLAY / STACKED / 100% STACKED

+
+
+ + +

SECTION 05 / AREA

+
+
+ + + + + + + + + + + + + + + +

① 重叠面积图 · Overlay

+
+
+ + + + + + + + + + + + + + + + + + + 2021,2022,2023,2024,2025,2026 + + + 180,210,245,268,295,322 + 120,155,180,220,258,296 + + + 全年营收走势(亿美元) + + + + + + + + + + + + + + + + + + + + + + + + +

② 堆叠面积图 · Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + 2021,2022,2023,2024,2025,2026 + + + 180,210,245,268,295,322 + 120,155,180,220,258,296 + + + 总营收堆叠视图 + + + + + + + + + + + + + + + + + + + + + + + + +

③ 百分比堆叠 · 100% Stacked

+
+
+ + + + + + + + + + + + + + + + + + + + + 2021,2022,2023,2024,2025,2026 + + + 180,210,245,268,295,322 + 120,155,180,220,258,296 + + + 区域营收占比演进 + + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

07 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

组合图 · Combo Chart

+
+
+ + +

营收规模 & 增长率双轴视图 · COLUMN + LINE

+
+
+ + +

SECTION 07 / COMBO

+
+
+ + + + + + + + + + + + + + + +

八季度营收与同比增速

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + 24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4 + + + 180,195,210,245,220,238,258,296 + 0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21 + + + 营收(亿美元, 左轴) · 同比增速(%, 右轴) + + + + + + + + + + + + + + + + + + + + + + + +

KEY TAKEAWAY

+
+
+ + +

营收连续 6 季度双位数增长

+
+
+ + +

24Q4 - 25Q4 期间同比增速稳定在 18-23%,营收规模从 245 亿扩张至 296 亿美元。

+
+
+ + + + + +

WHAT TO WATCH

+
+
+ + +

· 25Q4 增速首次微降 2pp

+

· 高基数效应即将显现

+

· 需关注亚太区库存周期

+
+
+ + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

09 / 12

+
+
+
+ + + +
+ + + + + + + + + + + + + + + + + +

雷达图 · Radar Chart

+
+
+ + +

产品能力多维对比 · POLYGON / CIRCLE / OUTLINE

+
+
+ + +

SECTION 08 / RADAR

+
+
+ + + + + + + + + + + + + + + +

① 多边形雷达 · Polygon

+
+
+ + + + + + + + + + + + + + + + + + + + + + 性能,续航,拍照,屏幕,系统,生态 + + + 9,7,8,9,8,9 + 7,9,9,7,8,6 + + + 旗舰机型能力评估 + + + + + + + + + + + + + + + + + + + + + + + + +

② 圆形雷达 · Circle

+
+
+ + + + + + + + + + + + + + + + + + + + + + + 性能,续航,拍照,屏幕,系统,生态 + + + 7,8,6,8,7,7 + 8,6,7,7,8,8 + + + 中端机型能力评估 + + + + + + + + + + + + + + + + + + + + + + + + +

③ 无填充雷达 · Outline

+
+
+ + + + + + + + + + + + + + + + + + + + + 性能,续航,拍照,屏幕,系统,生态 + + + 6,7,5,6,6,5 + 5,6,6,5,7,6 + + + 入门机型能力评估 + + + + + + + + + + + + + + +

Source: Consulting Insights Research · 数据仅用于示意

+
+
+ + +

10 / 12

+
+
+
+ + + +
+ diff --git a/skills/lark-slides/references/slides_demo.xml b/skills/lark-slides/references/slides_demo.xml deleted file mode 100644 index 1c291c5c9b..0000000000 --- a/skills/lark-slides/references/slides_demo.xml +++ /dev/null @@ -1,226 +0,0 @@ - - - 制造端智能升级 - - - - - - - - - - - - -

- - 时代背景 - -

-
-
- - - - - - 十月革命场景 - - - 列宁演讲油画 - - - 十月革命战斗场面 - - - - - - - - - - - - - - - -

- - 1917 - -

-
-
- - -

- 十月革命 -

-
-
- - -

- 沙皇专制终结,苏维埃政权建立 -

-
-
- - - - - - - - -

- - 1920s - -

-
-
- - -

- 国内战争 -

-
-
- - -

- 革命与反革命的残酷斗争 -

-
-
- - - - - - - - -

- - 1930s - -

-
-
- - -

- 社会主义建设 -

-
-
- - -

- 新经济政策与工业化探索 -

-
-
- - - - - - - -

- 作者:奥斯特洛夫斯基 -

-
-
- - - - - - - -

- 工人家庭出身,投身革命浪潮 -

-
-
- - - - - - - -

- 战场负伤致残,生命陷入黑暗 -

-
-
- - - - - - - -

- 全身瘫痪、双目失明 -

-
-
- - - - - - - -

- 以文学为武器,口述完成创作 -

-
-
- 奥斯特洛夫斯基青年时期 - - - - - -

- 创作动机 -

-
-
- - - - - - - -

- 在双目失明、全身瘫痪的逆境中,奥斯特洛夫斯基以自身经历为蓝本,用顽强的意志口述完成了这部不朽巨著。他将文学创作视为生命的延续和战斗的武器,旨在通过保尔·柯察金的形象,向青年一代传递坚不可摧的革命信念和超越个人痛苦的崇高人生价值观。 -

-
-
-
- - -

各位好,这一页将我们带回《钢铁是怎样炼成的》这部巨著诞生的波澜壮阔的时代。

-

上半部分展示了从1917年十月革命到1930年代苏联社会主义建设的宏大历史画卷。这是一个充满剧烈社会变革和残酷斗争的年代,也是英雄主义和理想主义精神熊熊燃烧的年代。正是这样的背景,孕育了小说的灵魂。

-

下半部分,我们聚焦于作者奥斯特洛夫斯基的个人经历。他的一生,本身就是一部比小说更震撼人心的传奇。从投身革命的青年,到因伤致残的战士,再到与命运抗争的文学巨匠。他的创作动机源于自身不屈的战斗精神,他希望用保尔的故事激励后人,在任何困境中都不要放弃理想,要将有限的生命投入到无限的为人类解放而斗争的事业中去。

-

通过了解这段历史和作者的生平,我们能更深刻地理解《钢铁是怎样炼成的》这部作品的伟大之处。

-
-
-
-
diff --git a/skills/lark-slides/references/slides_xml_schema_definition.xml b/skills/lark-slides/references/slides_xml_schema_definition.xml index b8090ee095..79fb27dd22 100644 --- a/skills/lark-slides/references/slides_xml_schema_definition.xml +++ b/skills/lark-slides/references/slides_xml_schema_definition.xml @@ -935,7 +935,7 @@ 单页幻灯片结构 子元素: - style: 页面样式(背景色等), style的fill默认颜色为白色rgba(255, 255, 255, 1) - - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/whiteboard/undefined) + - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined) - note: 演讲者备注 @@ -960,7 +960,6 @@ - @@ -3008,47 +3007,4 @@ - - - - - 画板元素, 用于在幻灯片中嵌入 Mermaid 或 SVG 绘制内容。 - - 属性说明: - - id: 画板唯一标识符(可选) - - topLeftX/topLeftY: 左上角坐标, 必须 - - width/height: 宽高尺寸, 必须 - - flipX/flipY: 水平/垂直翻转 - - alpha: 不透明度[0,1] - - 子元素(mermaid 与 svg 二选一): - - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹 - 适用场景: 流程图、时序图、思维导图、类图、甘特图、ER 图、用户旅程等结构图 - 特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标 - 示例: <mermaid><![CDATA[flowchart TD\n A[开始] --> B[结束]]]></mermaid> - - svg: SVG 内容 - 适用场景: 需要精确控制坐标、配色、路径的自定义图形 - 特点: 像素级精确定位,支持 rect/circle/path/text/polygon/g/linearGradient 等元素;radialGradient/filter/clipPath/mask/pattern 不支持,需手动计算所有坐标 - 示例: <svg xmlns="http://www.w3.org/2000/svg">...</svg>(xmlns 必填;width/height/viewBox 不影响渲染,仅百分比属性值场景需声明 viewBox) - - border: 边框样式, 可选, 无border标签代表无边框, 空border标签代表使用默认样式 - - - - - - - - - - - - - - - - - - - - diff --git a/skills/lark-slides/references/troubleshooting.md b/skills/lark-slides/references/troubleshooting.md index 22c231a1d0..62ea6f3f16 100644 --- a/skills/lark-slides/references/troubleshooting.md +++ b/skills/lark-slides/references/troubleshooting.md @@ -1,16 +1,27 @@ # Troubleshooting -本文件覆盖 lark-slides 的 XML 排障和常见失败处理。 +本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference,例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。 + +## XML Preflight + +在真正创建或替换前,至少检查: + +- 特殊字符已转义:正文和标题里的 `&`、`<`、`>` 不能裸写;属性值里的裸 `&` 也必须写成 `&`。 +- 属性引号安全:XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。 +- 结构合法:`` 下只放 ` + + + +

2024 年第一季度报告

+
+
+ + +

核心指标

+
    +
  • 用户增长:+25%

  • +
  • 收入增长:+30%

  • +
  • 市场份额:15%

  • +
+
+
+ + + + + + +
+ + +

讲到增长率时补充样本范围。

+
+
+
+ +``` + +## 最佳实践 + +1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"` +2. 用 `shape type="text"` + `content` 表达页面文本 +3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名 +4. 优先使用 `rgb` / `rgba` 颜色格式;渐变必须使用 `rgba()` 且带百分比停靠点 +5. 特殊字符按 XML 规则转义 +6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"` + ## 详细参考 - [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) -- [xml-format-guide.md](xml-format-guide.md) -- [examples.md](examples.md) -- [slides_demo.xml](slides_demo.xml) +- [slides_chart_demo.xml](slides_chart_demo.xml) ## Schema 版本信息 From bd57b360433eca584d3b06e0905e3d3813b059a5 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Fri, 17 Jul 2026 18:10:13 +0800 Subject: [PATCH 02/11] =?UTF-8?q?fix:=20=E8=A1=A5=E5=9B=9Elark-share=20?= =?UTF-8?q?=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 25a9738a81..263caa8a2a 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -89,6 +89,8 @@ metadata: | 使用图标 | 禁止盲猜 iconType,必须先检索 IconPark,再写 ``,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` | | 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.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 结构。** **CRITICAL — 新建演示文稿或大幅改写页面时,MUST 先生成 `.lark-slides/plan//slide_plan.json`,再生成 XML。先创建对应目录,规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。** From 9881acf38fd51f32bff89fd99fefd1eec4e4c1a0 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Fri, 17 Jul 2026 18:27:28 +0800 Subject: [PATCH 03/11] =?UTF-8?q?fix:=20=E8=A1=A5=E5=9B=9E=E4=B8=80?= =?UTF-8?q?=E4=BA=9B=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/SKILL.md | 2 ++ skills/lark-slides/references/lark-slides-create.md | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 263caa8a2a..0a2b299ff7 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -99,6 +99,8 @@ metadata: **CRITICAL — 新建演示文稿或大幅改写页面时,规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md):只做元数据规划,必须有 `fallback_if_missing`,不得要求真实搜索、下载或上传素材。** +**CRITICAL — 将完整 `` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前,MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);`summary.error_count` 必须为 0 才能调用接口。** + **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 和布局风险。** diff --git a/skills/lark-slides/references/lark-slides-create.md b/skills/lark-slides/references/lark-slides-create.md index 13779ef8ab..0fe870f6bc 100644 --- a/skills/lark-slides/references/lark-slides-create.md +++ b/skills/lark-slides/references/lark-slides-create.md @@ -3,6 +3,14 @@ 创建一个新的飞书幻灯片演示文稿,可选一步添加页面内容。 +- 禁止:从完整 XML 解析/拆分/重序列化生成提交 payload。 +- 推荐:提交源直接就是单页 XML;+create --slides 只接受已经人工/程序直接生成的 slide 数组,不接受由 + presentation 动态拆出来的数组。 + +- 最稳:复杂 deck 默认空 deck + 单页 slide create,每次只提交一个 。 + +- 注意:复杂 XML 不适合直接塞命令行,中文、引号、特殊字符较多时,直接拼接 --slides 容易发生 shell 转义或截断。建议将每页 XML 保存为独立文件,使用 `jq --rawfile` 组装 JSON 数组,避免手动处理 XML 引号和换行。 + ## 命令 ```bash From 6d4d3b1ac0db3f9c29de03cc59faa95bdd226c90 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Mon, 20 Jul 2026 15:10:20 +0800 Subject: [PATCH 04/11] =?UTF-8?q?fix:=20=E7=A7=BB=E9=99=A4=E8=B1=86?= =?UTF-8?q?=E5=8C=85=E7=89=B9=E6=9C=89=E5=B7=A5=E5=85=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 0a2b299ff7..5d430772ba 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -38,7 +38,6 @@ metadata: - `
` 直接子元素只有 ``(背景)、``(文字)和边框配置(一般不用),不能嵌套 ``、``、``。 - `` 只是形状不是容器,``、``、`` 和其他 `` 必须与它平级靠坐标叠放。 - 填充渐变颜色必须用 ``。 -- 必须使用 NotifyHuman 工具交付 PPT 链接;编辑已有 PPT 也必须交付 PPT 链接,无论之前是否交付过相同链接。 - 编辑页面前必须阅读 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。 - 绘制图表前必须阅读 [`slides_chart_demo.xml`](references/slides_chart_demo.xml)。 - 当用户要求无损复述历史上下文时,必须无损复述以上权威经验、必读的技能文档(需要重新阅读)和易错元素语法(尤其是 `` 和 ``)。 From c4ef05df4a4f50f68e7559e59a927686c8c58e29 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Mon, 20 Jul 2026 15:23:09 +0800 Subject: [PATCH 05/11] =?UTF-8?q?fix:=20=E7=A7=BB=E9=99=A4=E5=A4=9A?= =?UTF-8?q?=E4=BD=99=E7=9A=84xml=E7=89=88=E6=9C=AC=E5=A4=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/references/slides_chart_demo.xml | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/lark-slides/references/slides_chart_demo.xml b/skills/lark-slides/references/slides_chart_demo.xml index 53fcdb3952..35766da118 100644 --- a/skills/lark-slides/references/slides_chart_demo.xml +++ b/skills/lark-slides/references/slides_chart_demo.xml @@ -1,4 +1,3 @@ - 原生图表 Chart Demo From c589e4c195d785d305373391904c41a25adbcff2 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Mon, 20 Jul 2026 15:56:18 +0800 Subject: [PATCH 06/11] =?UTF-8?q?fix:=20=E8=A1=A5=E5=9B=9E=E7=A4=BA?= =?UTF-8?q?=E4=BE=8Bxml=E5=A4=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/references/slides_chart_demo.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/lark-slides/references/slides_chart_demo.xml b/skills/lark-slides/references/slides_chart_demo.xml index 35766da118..53fcdb3952 100644 --- a/skills/lark-slides/references/slides_chart_demo.xml +++ b/skills/lark-slides/references/slides_chart_demo.xml @@ -1,3 +1,4 @@ + 原生图表 Chart Demo From d16269110af17109a813cfde15f2d872e59a70cf Mon Sep 17 00:00:00 2001 From: "dengzilong.zero" Date: Thu, 16 Jul 2026 18:47:29 +0800 Subject: [PATCH 07/11] feat: add slide screenshot visual review --- skills/lark-slides/SKILL.md | 17 ++++++- .../references/lark-slides-screenshot.md | 33 +++++++----- .../references/validation-checklist.md | 51 +++++++++++++++---- 3 files changed, 76 insertions(+), 25 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 5d430772ba..f213b96f57 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -80,10 +80,17 @@ metadata: | 新建 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` | +<<<<<<< HEAD | 读取或分析已有 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` | | 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | | 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`、`lark-slides-media-upload.md`,或 `+create --slides` 的 `@./path` 占位符 | | 绘制图表 | 原生图表(柱状、条形、折线、面积、饼(环)、雷达、组合图)用 ``,其他(漏斗图、金字塔图、象限图、矩阵图等)用 `` + `` 模拟 | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | +======= +| 读取或分析已有 PPT | 解析 slides/wiki token,用 shortcut 回读全文 XML 或读取单页 XML,保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get` | +| 获取幻灯片页面截图 | 用 `slide_id` 指定页面;页号仅用于人工定位 fallback,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | +| 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`,或 `+create --slides` 的 `@./path` 占位符 | +| 绘制图表 | 原生图表用 ``,其他用 `` + ``,只有复杂 Mermaid、SVG 用 `` | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | +>>>>>>> b8f87e8d (feat: add slide screenshot visual review) | 绘制表格 | 优先用 `rect` 和 `text` 模拟,其他用 `
` | `xml-schema-quick-ref.md` | | 使用图标 | 禁止盲猜 iconType,必须先检索 IconPark,再写 ``,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` | | 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | @@ -100,7 +107,7 @@ metadata: **CRITICAL — 将完整 `` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前,MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);`summary.error_count` 必须为 0 才能调用接口。** -**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 按 [validation-checklist.md](references/validation-checklist.md) 完成回读、静态检查和逐页截图视觉验收:回读全文 XML,核对页数、关键元素及空白/破损/溢出等布局风险;运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);再以当前 `slide_id` 清单逐页截图并记录 review 结果。** **CRITICAL — 创建前自检或失败排障时,MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。** @@ -219,9 +226,17 @@ Step 3: 按 slide_plan.json 生成 XML → 创建 - 创建方式按“创建方式选择”判断;图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行 Step 4: 审查 & 交付 +<<<<<<< HEAD - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录,包括 XML 文本重叠检查 - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正 - 没问题 → 交付:使用 NotifyHuman 工具交付 PPT 链接 +======= + - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录 + - 静态检查通过后,使用当前回读得到的 `slide_ids` 调用 `slides +screenshot`;首次新建且页集合未变时可复用创建响应。每批最多 10 页,保存到 `.lark-slides/review//screenshots/`,然后实际查看生成的图片 + - 对每页按「可读性、布局、视觉层级、内容完整性、图表精确可读性(有图表时)」记录 pass / fix;只有所有页 pass 才能写“已完成视觉 review” + - 发现问题时,局部问题优先用 `+replace-slide` 修正;修正后必须重新截图并复验该页。 + - 没问题 → 交付:告知用户演示文稿 ID 和访问方式 +>>>>>>> b8f87e8d (feat: add slide screenshot visual review) ``` ### jq 命令模板(编辑已有 PPT 时使用) diff --git a/skills/lark-slides/references/lark-slides-screenshot.md b/skills/lark-slides/references/lark-slides-screenshot.md index 74d8c69070..ba0d9dbda3 100644 --- a/skills/lark-slides/references/lark-slides-screenshot.md +++ b/skills/lark-slides/references/lark-slides-screenshot.md @@ -11,7 +11,7 @@ ```bash lark-cli slides +screenshot --as user \ --presentation '' \ - --slide-number 1 + --slide-id 'SLIDE_ID' ``` 渲染本地 XML 内容: @@ -26,8 +26,8 @@ lark-cli slides +screenshot --as user \ | 参数 | 必需 | 说明 | |------|------|------| | `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL,或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 | -| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID;多页截图时重复传入;一次最多 10 页(`--slide-id` + `--slide-number` 合计小于等于 10) | -| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号;多页截图时重复传入;一次最多 10 页(`--slide-id` + `--slide-number` 合计小于等于 10) | +| `--slide-id` | list 模式标准入参 | 页面 short ID;截图、修复和 review 状态均以它关联;多页截图时重复传入;一次最多 10 页 | +| `--slide-number` | 用户只提供“第 N 页”或旧 deck 暂未取得 `slide_id` 时使用;成功定位后必须取得对应 `slide_id`,后续不再用页号关联截图或 review 状态 | | `--content` | render 模式必需 | 要直接渲染的 `` XML 片段;支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` | | `--output-dir` | 否 | 输出目录,默认 `.lark-slides/screenshots`;必须是当前目录内的相对路径 | | `--output-name` | 否 | render 模式的输出文件名 stem;未指定时优先用返回的 `slide_id`,否则用 `rendered-slide`。若目标文件已存在,会自动追加递增后缀避免覆盖 | @@ -39,21 +39,25 @@ lark-cli slides +screenshot --as user \ ```bash lark-cli slides +screenshot --as user \ --presentation slides_example_presentation_id \ - --slide-number 1 + --slide-id 'SLIDE_ID' ``` -### 多页截图 +### 按 `slide_id` 截图与创建后视觉 review(推荐) -一次不要超过 10 页;如需更多页面,分批调用。 +视觉 review 以当前回读得到的 `slide_ids` 为页清单。单页传一个 `--slide-id`;多页可重复传入,单次最多 10 页,超过时按批次串行执行。 + +首次新建且之后没有增删页、整页替换或重排时,可复用创建响应中的 `slide_ids`。发生上述页面集合变化后,必须先回读并刷新清单;不能用页码或旧响应中的页列表绑定 review 状态。 ```bash lark-cli slides +screenshot --as user \ - --presentation slides_example_presentation_id \ - --slide-number 1 \ - --slide-number 2 \ - --output-dir .lark-slides/screenshots/demo + --presentation 'YOUR_PRESENTATION_ID' \ + --slide-id 'SLIDE_ID_1' \ + --slide-id 'SLIDE_ID_2' \ + --output-dir .lark-slides/review//screenshots ``` +随后必须用具备图像查看能力的工具打开每个返回的 `path`,逐页记录 `pass/fix`。截图落盘或批量请求成功都不等于已完成视觉 review。 + ### 渲染 XML 预览 ```bash @@ -89,9 +93,10 @@ lark-cli slides +screenshot --as user \ ## 注意事项 1. 优先使用 `slides +screenshot` 保存本地图片,不要把图片 Base64 打到 stdout。 -2. 已存在 PPT 页面截图时,不传 `--content`,用 `--presentation` + `--slide-id` 或 `--slide-number`。 +2. 已存在 PPT 页面截图时,不传 `--content`,用 `--presentation` + `--slide-id`。 3. 本地 XML 预览时,传 `--content @file` 或 `--content -`,内容应为单个 `` XML 片段;此时不要传 `--presentation` / `--slide-id` / `--slide-number`。 -4. `slide_id` 是页面 short ID,页码请用 `--slide-number`。 -5. list 模式一次最多传 10 页(`--slide-id` + `--slide-number` 合计小于等于 10);更多页面请分批截图。 +4. `slide_id` 是页面 short ID,也是截图、修复和 review 状态的唯一关联键;页码仅作为用户可读的瞬时展示信息。 +5. list 模式一次最多传 10 个 `--slide-id`;更多页面请分批截图,每页仍要独立记录 review 结论。 6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID;文件已存在时自动追加 `_2`、`_3` 等后缀,避免覆盖旧截图。 -7. 截图来自服务端渲染结果,适合创建/替换后验证页面是否为空白、破图或布局明显异常。 +7. 截图来自服务端渲染结果,适合创建/替换后验证页面是否为空白、破图或布局明显异常;与 `validation-checklist.md` 的逐页 rubric 一起使用。 +8. 如果因用户只给页号而使用 `--slide-number`,截图后立即回读或从响应取得 `slide_id`,后续改用 `--slide-id`;如果收到频率限制,停止扩大发送并在短暂退避后逐批重试。截图 API 白名单失败时记录原始错误,继续完成 XML 静态检查,并把视觉状态标为 `not_verified`。 diff --git a/skills/lark-slides/references/validation-checklist.md b/skills/lark-slides/references/validation-checklist.md index ffd337369c..88e124e444 100644 --- a/skills/lark-slides/references/validation-checklist.md +++ b/skills/lark-slides/references/validation-checklist.md @@ -6,15 +6,14 @@ ## Required Flow -1. 记录创建或编辑返回的 `xml_presentation_id`,以及已知的 `slide_id` / `revision_id`。 -2. 用 `slides +xml-get` 回读全文 XML 到本地文件。 -3. 检查实际页数是否符合计划或用户要求。 -4. 检查每页 `` 内是否有预期主要元素。 -5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。 -6. 检查页面不是全部退化为标题加 bullet list。 -7. 检查视觉层级:标题、主视觉、支撑信息三者可区分。 -8. 检查明显溢出和布局风险:重叠、越界、底部拥挤、长文本框。 -9. 在最终回复中给出简短验证记录。 +1. 记录创建或编辑返回的 `xml_presentation_id`,以及已知的 `slide_id` / `revision_id`。`slide_id` 是 review 状态唯一关联键;页码仅可作为展示信息。 +2. 用 `slides +xml-get` 回读全文 XML 到本地文件,并以当前结果建立本次 review 的 `slide_ids` 页清单。首次新建且页集合未变时,可复用创建响应;增删页、整页替换或重排后必须刷新清单。 +3. 运行 XML 静态检查,检查实际页数、主要元素、空白/破损页、主视觉和布局风险。 +4. 静态检查通过后,用 `slides +screenshot` 对第 1 步的全部 `slide_ids` 截图。每批最多 10 页,输出到 `.lark-slides/review//screenshots/`。 +5. 实际打开每张截图,按下方 rubric 逐页标记 `pass` 或 `fix`;截图文件存在但未被查看时,状态必须为 `not_reviewed`。 +6. `fix` 页用 `+replace-slide` 或对应写入操作修复后,重新回读并重新截图该页;不要沿用修复前的截图结论。 +7. 截图白名单或服务端限制导致无法获取图片时,记录错误和受影响页,完成其余 XML 静态检查,并将视觉状态标记为 `not_verified`。 +8. 在最终回复中给出简短验证记录,明确区分静态检查和真实视觉 review。 回读命令: @@ -119,11 +118,42 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input /visual-review.md`: + +```text +| slide_id | screenshot | status | findings | action | +|---|---|---|---|---| +| p001 | screenshots/p001.png | pass | hierarchy and contrast clear | - | +| p002 | screenshots/p002.png | fix | bottom labels are clipped | enlarge text box, then rescreenshot | +``` + +只有所有目标页均为 `pass` 才能写“已完成视觉 review”。截图不可用时沿用上文的 `not_verified` 状态,并说明原因。 + ## Verification Record 最终回复必须包含简短验证记录,建议格式: @@ -133,7 +163,8 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input Date: Mon, 20 Jul 2026 15:19:34 +0800 Subject: [PATCH 08/11] feat: strengthen slide screenshot visual review workflow --- skills/lark-slides/SKILL.md | 21 ++++--------------- .../references/lark-slides-screenshot.md | 12 +++++------ .../references/validation-checklist.md | 8 +++---- .../scripts/xml_text_overlap_lint.py | 2 +- 4 files changed, 15 insertions(+), 28 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index f213b96f57..bb86112294 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -80,17 +80,10 @@ metadata: | 新建 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` | -<<<<<<< HEAD | 读取或分析已有 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` | -| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | +| 获取幻灯片页面截图 | 用 `slide_id` 指定页面;页号仅用于人工定位 fallback,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | | 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`、`lark-slides-media-upload.md`,或 `+create --slides` 的 `@./path` 占位符 | | 绘制图表 | 原生图表(柱状、条形、折线、面积、饼(环)、雷达、组合图)用 ``,其他(漏斗图、金字塔图、象限图、矩阵图等)用 `` + `` 模拟 | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | -======= -| 读取或分析已有 PPT | 解析 slides/wiki token,用 shortcut 回读全文 XML 或读取单页 XML,保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get` | -| 获取幻灯片页面截图 | 用 `slide_id` 指定页面;页号仅用于人工定位 fallback,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` | -| 上传或使用图片 | 先上传为 `file_token`,禁止直接写 http(s) 外链 | `slides +media-upload`,或 `+create --slides` 的 `@./path` 占位符 | -| 绘制图表 | 原生图表用 ``,其他用 `` + ``,只有复杂 Mermaid、SVG 用 `` | `xml-schema-quick-ref.md`、`slides_chart_demo.xml` | ->>>>>>> b8f87e8d (feat: add slide screenshot visual review) | 绘制表格 | 优先用 `rect` 和 `text` 模拟,其他用 `
` | `xml-schema-quick-ref.md` | | 使用图标 | 禁止盲猜 iconType,必须先检索 IconPark,再写 ``,图标必须填充颜色并和背景有足够对比,禁止使用 emoji 图标 | `iconpark_tool.py search → resolve`、`iconpark.md` | | 创建失败、空白页、3350001、布局异常 | 先回读状态,再按排障清单修复,不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | @@ -226,17 +219,11 @@ Step 3: 按 slide_plan.json 生成 XML → 创建 - 创建方式按“创建方式选择”判断;图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行 Step 4: 审查 & 交付 -<<<<<<< HEAD - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录,包括 XML 文本重叠检查 - - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正 + - 静态检查通过后,使用当前回读得到的 `slide_ids` 调用 `slides +screenshot`;首次新建且页集合未变时可复用创建响应。每批最多 10 页,保存到 `.lark-slides/review//screenshots/`,然后实际查看生成的图片。**截图使用 `--presentation`、重复的 `--slide-id` 和可选 `--output-dir`;不要迁移 `--output`、`--params`、`--slides`、`--pages` 或 `--presentation-id`。** + - 先为当前 `slide_ids` 建立逐页 review 记录,初始均为 `not_reviewed`;实际打开每张截图后,按「可读性、布局、视觉层级、内容完整性、图表精确可读性(有图表时)」更新为 pass / fix。**只截图或查看关键页属于抽查,不是视觉 review;只要存在 `not_reviewed` / `fix`,就不得写“已完成视觉 review”。** + - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正,修正后必须重新截图并复验该页 - 没问题 → 交付:使用 NotifyHuman 工具交付 PPT 链接 -======= - - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录 - - 静态检查通过后,使用当前回读得到的 `slide_ids` 调用 `slides +screenshot`;首次新建且页集合未变时可复用创建响应。每批最多 10 页,保存到 `.lark-slides/review//screenshots/`,然后实际查看生成的图片 - - 对每页按「可读性、布局、视觉层级、内容完整性、图表精确可读性(有图表时)」记录 pass / fix;只有所有页 pass 才能写“已完成视觉 review” - - 发现问题时,局部问题优先用 `+replace-slide` 修正;修正后必须重新截图并复验该页。 - - 没问题 → 交付:告知用户演示文稿 ID 和访问方式 ->>>>>>> b8f87e8d (feat: add slide screenshot visual review) ``` ### jq 命令模板(编辑已有 PPT 时使用) diff --git a/skills/lark-slides/references/lark-slides-screenshot.md b/skills/lark-slides/references/lark-slides-screenshot.md index ba0d9dbda3..32a4752fb7 100644 --- a/skills/lark-slides/references/lark-slides-screenshot.md +++ b/skills/lark-slides/references/lark-slides-screenshot.md @@ -25,12 +25,12 @@ lark-cli slides +screenshot --as user \ | 参数 | 必需 | 说明 | |------|------|------| -| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL,或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 | -| `--slide-id` | list 模式标准入参 | 页面 short ID;截图、修复和 review 状态均以它关联;多页截图时重复传入;一次最多 10 页 | -| `--slide-number` | 用户只提供“第 N 页”或旧 deck 暂未取得 `slide_id` 时使用;成功定位后必须取得对应 `slide_id`,后续不再用页号关联截图或 review 状态 | +| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL,或解析后为 slides 的 `/wiki/` URL;只标识演示文稿,不会默认截图全部页面。传 `--content` 时不能使用 | +| `--slide-id` | list 模式标准入参 | 页面 short ID;截图、修复和 review 状态均以它关联;多页截图时重复传入;一次最多 10 页。先从创建响应或 `slides +xml-get` 取得当前 `slide_ids` | +| `--slide-number` | 用户只提供“第 N 页”或旧 deck 暂未取得 `slide_id` 时使用;成功定位后必须取得对应 `slide_id`,后续不再用页号关联截图或 review 状态。不能省略 `--slide-id` 和 `--slide-number` 两者 | | `--content` | render 模式必需 | 要直接渲染的 `` XML 片段;支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` | -| `--output-dir` | 否 | 输出目录,默认 `.lark-slides/screenshots`;必须是当前目录内的相对路径 | -| `--output-name` | 否 | render 模式的输出文件名 stem;未指定时优先用返回的 `slide_id`,否则用 `rendered-slide`。若目标文件已存在,会自动追加递增后缀避免覆盖 | +| `--output-dir` | 否 | 输出目录,默认 `.lark-slides/screenshots`;必须是当前目录内的相对路径。截图可能返回多张图片,使用目录而不是 `--output` 文件路径 | +| `--output-name` | 否 | 仅 render 模式(`--content`)的输出文件名 stem;未指定时优先用返回的 `slide_id`,否则用 `rendered-slide`。若目标文件已存在,会自动追加递增后缀避免覆盖 | ## 示例 @@ -56,7 +56,7 @@ lark-cli slides +screenshot --as user \ --output-dir .lark-slides/review//screenshots ``` -随后必须用具备图像查看能力的工具打开每个返回的 `path`,逐页记录 `pass/fix`。截图落盘或批量请求成功都不等于已完成视觉 review。 +随后必须用具备图像查看能力的工具打开每个返回的 `path`,逐页记录 `pass/fix`。截图落盘、批量请求成功或只查看关键页,都不等于已完成视觉 review。 ### 渲染 XML 预览 diff --git a/skills/lark-slides/references/validation-checklist.md b/skills/lark-slides/references/validation-checklist.md index 88e124e444..9605f265c5 100644 --- a/skills/lark-slides/references/validation-checklist.md +++ b/skills/lark-slides/references/validation-checklist.md @@ -9,8 +9,8 @@ 1. 记录创建或编辑返回的 `xml_presentation_id`,以及已知的 `slide_id` / `revision_id`。`slide_id` 是 review 状态唯一关联键;页码仅可作为展示信息。 2. 用 `slides +xml-get` 回读全文 XML 到本地文件,并以当前结果建立本次 review 的 `slide_ids` 页清单。首次新建且页集合未变时,可复用创建响应;增删页、整页替换或重排后必须刷新清单。 3. 运行 XML 静态检查,检查实际页数、主要元素、空白/破损页、主视觉和布局风险。 -4. 静态检查通过后,用 `slides +screenshot` 对第 1 步的全部 `slide_ids` 截图。每批最多 10 页,输出到 `.lark-slides/review//screenshots/`。 -5. 实际打开每张截图,按下方 rubric 逐页标记 `pass` 或 `fix`;截图文件存在但未被查看时,状态必须为 `not_reviewed`。 +4. 先在 `.lark-slides/review//visual-review.md` 为全部 `slide_ids` 建立记录,初始状态均为 `not_reviewed`;静态检查通过后再用 `slides +screenshot` 截图。每批最多 10 页,输出到 `.lark-slides/review//screenshots/`。 +5. 实际打开每张截图,按下方 rubric 逐页标记 `pass` 或 `fix`;截图文件存在但未被查看时,状态必须保留为 `not_reviewed`。**关键页抽查只可作为排障/预览,不能缩小本次 review 页清单,也不能支持“全部通过”的结论。** 6. `fix` 页用 `+replace-slide` 或对应写入操作修复后,重新回读并重新截图该页;不要沿用修复前的截图结论。 7. 截图白名单或服务端限制导致无法获取图片时,记录错误和受影响页,完成其余 XML 静态检查,并将视觉状态标记为 `not_verified`。 8. 在最终回复中给出简短验证记录,明确区分静态检查和真实视觉 review。 @@ -26,7 +26,7 @@ lark-cli slides +xml-get --as user \ ## Automated XML Text Overlap Lint -`slides +xml-get` 保存 XML 到本地文件后,优先运行 XML 语法和文本重叠静态检查: +slides +xml-get 保存 XML 到本地文件后,必须运行 XML 语法和文本重叠静态检查;输入可以是单个 或完整 。 ```bash python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input @@ -152,7 +152,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input dict[str, Any]: def print_usage() -> None: - print("Usage:\n python3 xml_text_overlap_lint.py --input ", file=sys.stderr) + print("Usage:\n python3 xml_text_overlap_lint.py --input ", file=sys.stderr) def run_cli(argv: list[str] | None = None) -> None: From e8930d7be2616bd4fbea7bfae937fcaedfd9d8f4 Mon Sep 17 00:00:00 2001 From: "zhuyuanbin.gdut" Date: Mon, 20 Jul 2026 17:07:43 +0800 Subject: [PATCH 09/11] fix: remove xml-format-guide --- .../references/xml-format-guide.md | 433 ------------------ 1 file changed, 433 deletions(-) delete mode 100644 skills/lark-slides/references/xml-format-guide.md diff --git a/skills/lark-slides/references/xml-format-guide.md b/skills/lark-slides/references/xml-format-guide.md deleted file mode 100644 index 6c0b8383f4..0000000000 --- a/skills/lark-slides/references/xml-format-guide.md +++ /dev/null @@ -1,433 +0,0 @@ -# XML 格式指南 - -本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理,说明飞书 Slides XML Schema(SML 2.0)的核心结构和常用写法。 - -## 基本结构 - -```xml - - - 演示文稿标题 - - - - - -

主标题

-
-
-
- - -

这是演讲者备注。

-
-
-
-
-``` - -## 根元素 - -### `` - -协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`;当前服务端实现可能兼容不带 `xmlns` 的输入,但不作为协议保证。 - -**属性:** - -| 属性 | 类型 | 必需 | 说明 | -|------|------|------|------| -| `width` | positiveInteger | 是 | 演示文稿宽度,如 `960` | -| `height` | positiveInteger | 是 | 演示文稿高度,如 `540` | -| `id` | string | 否 | 演示文稿标识 | - -**子元素:** - -| 元素 | 必需 | 说明 | -|------|------|------| -| `` | 否 | 演示文稿标题 | -| `<theme>` | 否 | 全局主题 | -| `<slide>` | 是 | 幻灯片页面,至少 1 页,最多 100 页 | - -## 主题 - -### `<theme>` - -`<theme>` 当前包含两部分: - -- `<background>`:演示文稿级背景填充 -- `<textStyles>`:主题文本样式集合 - -`<textStyles>` 下可选子元素: - -- `<title>` -- `<headline>` -- `<sub-headline>` -- `<body>` -- `<caption>` - -这些元素定义的是主题默认样式,不是页面结构。常用属性: - -| 属性 | 说明 | -|------|------| -| `fontFamily` | 字体 | -| `fontSize` | 字号 | -| `fontColor` | 字体颜色 | - -## 幻灯片元素 - -### `<slide>` - -单张幻灯片的结构比较严格。 - -**属性:** - -| 属性 | 类型 | 必需 | 说明 | -|------|------|------|------| -| `id` | string | 否 | 幻灯片标识 | - -**直接子元素只有:** - -| 元素 | 必需 | 说明 | -|------|------|------| -| `<style>` | 否 | 页面样式 | -| `<data>` | 否 | 页面元素容器 | -| `<note>` | 否 | 演讲者备注 | - -这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。 - -## 文本内容模型 - -### `<content>` - -实际页面文本通常通过 `<content>` 表达,常见位置有: - -- `shape` 内部 -- `table/td` 内部 -- `note` 内部 - -**常用属性:** - -| 属性 | 说明 | -|------|------| -| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` | -| `verticalAlign` | 垂直对齐 | -| `textAlign` | 水平对齐 | -| `lineSpacing` | 行间距 | -| `fontSize` | 字号 | -| `fontFamily` | 字体 | -| `color` | 字体颜色 | -| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 | -| `wrap` | 是否自动换行 | - -**可包含的子元素:** - -- `<p>` -- `<ul>` -- `<ol>` - -### `<p>` - -`<p>` 是段落元素,可混排纯文本和内联标签: - -- `<br/>` -- `<strong>` -- `<em>` -- `<u>` -- `<span>` -- `<del>` -- `<a>` -- `<shadow>` -- `<outline>` - -示例: - -```xml -<content textType="body" textAlign="left"> - <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p> - <ul> - <li><p>列表项 1</p></li> - <li><p>列表项 2</p></li> - </ul> -</content> -``` - -## 常用页面元素 - -所有页面元素都放在 `<data>` 中。 - -### `<shape>` - -`shape` 可表示普通形状,也可表示文本框。文本框推荐使用 `type="text"`。 - -```xml -<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> - <content textType="title"> - <p>主标题</p> - </content> -</shape> -``` - -```xml -<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120"> - <fill> - <fillColor color="rgba(100, 149, 237, 0.25)"/> - </fill> - <border color="rgb(100, 149, 237)" width="2"/> -</shape> -``` - -**属性:** - -| 属性 | 必需 | 说明 | -|------|------|------| -| `type` | 是 | 形状类型,`text` 表示文本框 | -| `topLeftX` | 是 | 左上角 X 坐标 | -| `topLeftY` | 是 | 左上角 Y 坐标 | -| `width` | 是 | 宽度 | -| `height` | 是 | 高度 | -| `rotation` | 否 | 旋转角度 | -| `flipX` / `flipY` | 否 | 翻转 | -| `alpha` | 否 | 透明度 | - -**可选子元素:** - -- `<fill>` -- `<border>` -- `<reflection>` -- `<shadow>` -- `<content>` - -### `<line>` - -```xml -<line startX="100" startY="200" endX="420" endY="200"> - <border color="rgb(43, 47, 54)" width="2"/> -</line> -``` - -`line` 使用的是 `startX` / `startY` / `endX` / `endY`,不是 `x1` / `y1` / `x2` / `y2`。 - -### `<img>` - -```xml -<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/> -``` - -`img` 使用 `topLeftX` / `topLeftY`,不是 `x` / `y`。 - -`src` 只接受两种值: - -| `src` 形式 | 说明 | -|---|---| -| `file_token`(如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`) | 通过 `slides +media-upload` 上传后返回的 token | -| `@<本地路径>`(如 `@./assets/chart.png`) | **仅在 `slides +create --slides` 中可用**:CLI 会自动上传该文件并替换为 file_token | - -> **禁止使用 http(s) 外链 URL**:飞书 slides 渲染端不会代理外链图片,`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内,再走上传流程拿 `file_token`。 - -本地图片的两种姿势: - -- **新建带图 PPT**:`+create --slides` 里直接写 `src="@./pic.png"`,CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token -- **给已有 PPT 加带图新页**:先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token,再用 token 写进 `xml_presentation.slide create` 的 XML - -### `<icon>` - -```xml -<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/> -``` - -### `<table>` - -表格结构为: - -- `<table>` -- `<colgroup>` / `<tr>` -- `<tr>` 内为 `<td>` -- `<td>` 内可放 `<content>` - -`<table>` 可选设置 `width` 和 `height`,分别表示表格的目标总宽度和总高度: - -```xml -<table topLeftX="80" topLeftY="120" width="800" height="300"> - <colgroup> - <col width="240"/> - <col/> - </colgroup> - <tr height="80"> - <td><content textType="body"><p>表头 1</p></content></td> - <td><content textType="body"><p>表头 2</p></content></td> - </tr> -</table> -``` - -### `<chart>` - -图表元素必须至少包含: - -- `<chartPlotArea>` -- `<chartData>` - -同时还可以包含: - -- `<chartTitle>` -- `<chartSubTitle>` -- `<chartStyle>` -- `<chartLegend>` -- `<chartTooltip>` - -完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml),其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例,以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。 - -组合图示例(来自 [slides_chart_demo.xml](slides_chart_demo.xml)): - -```xml -<chart width="556" height="350" topLeftX="42" topLeftY="132"> - <chartPlotArea> - <chartPlot type="combo"> - <chartExtra/> - <chartSeriesList> - <chartSeries index="1" comboType="column"/> - <chartSeries index="2" comboType="line" yAxisPosition="right"> - <chartTooltip format="0%"/> - </chartSeries> - </chartSeriesList> - </chartPlot> - <chartAxes> - <chartAxis type="x"> - <chartLabel fontSize="10"/> - </chartAxis> - <chartAxis type="y" position="left"> - <chartGridLine color="rgb(226, 232, 240)"/> - <chartLabel fontSize="10"/> - </chartAxis> - <chartAxis type="y" position="right"> - <chartLabel fontSize="10" format="0%"/> - </chartAxis> - </chartAxes> - </chartPlotArea> - <chartLegend position="bottom" fontSize="11"/> - <chartData> - <dim1> - <chartField name="季度">24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4</chartField> - </dim1> - <dim2> - <chartField name="营收">180,195,210,245,220,238,258,296</chartField> - <chartField name="增速">0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21</chartField> - </dim2> - </chartData> - <chartTitle fontSize="12" color="rgba(15, 30, 58, 1)" bold="true">营收(亿美元, 左轴) · 同比增速(%, 右轴)</chartTitle> - <chartStyle> - <chartBackground color="rgba(0, 0, 0, 0)"/> - <chartBorder color="rgb(222, 224, 227)" width="0"/> - <chartColorTheme> - <color value="rgb(28, 71, 120)"/> - <color value="rgb(240, 129, 54)"/> - </chartColorTheme> - </chartStyle> -</chart> -``` - -## 样式元素 - -### `<fill>` - -```xml -<fill> - <fillColor color="rgb(100, 149, 237)"/> -</fill> -``` - -### `<border>` - -```xml -<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/> -``` - -### 颜色格式 - -```xml -<fillColor color="rgb(255, 0, 0)"/> -<fillColor color="rgba(255, 0, 0, 0.5)"/> -<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/> -<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/> -``` - -## 演讲者备注 - -### `<note>` - -```xml -<note> - <content textType="body"> - <p>这是演讲者备注内容。</p> - </content> -</note> -``` - -## 完整示例 - -```xml -<?xml version="1.0" encoding="UTF-8"?> -<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540"> - <title>季度报告 - - - - <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/> - </textStyles> - </theme> - <slide> - <style> - <fill> - <fillColor color="rgb(245, 245, 245)"/> - </fill> - </style> - <data> - <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100"> - <content textType="title"> - <p>2024 年第一季度报告</p> - </content> - </shape> - <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180"> - <content textType="body"> - <p>核心指标</p> - <ul> - <li><p>用户增长:+25%</p></li> - <li><p>收入增长:+30%</p></li> - <li><p>市场份额:15%</p></li> - </ul> - </content> - </shape> - <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140"> - <fill> - <fillColor color="rgba(100, 149, 237, 0.25)"/> - </fill> - <border color="rgb(100, 149, 237)" width="2"/> - </shape> - </data> - <note> - <content textType="body"> - <p>讲到增长率时补充样本范围。</p> - </content> - </note> - </slide> -</presentation> -``` - -## 最佳实践 - -1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"` -2. 用 `shape type="text"` + `content` 表达页面文本 -3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名 -4. 优先使用 `rgb` / `rgba` 颜色格式 -5. 特殊字符按 XML 规则转义 -6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"` - -## 参考文档 - -- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) -- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) -- [examples.md](examples.md) -- [slides_demo.xml](slides_demo.xml) From f05c39f03d08e2d33245a2ea2c36e496b57386ed Mon Sep 17 00:00:00 2001 From: "dengzilong.zero" <dengzilong.zero@bytedance.com> Date: Mon, 20 Jul 2026 18:20:11 +0800 Subject: [PATCH 10/11] =?UTF-8?q?fix:=20=E8=A1=A5=E5=85=85=20validation-ch?= =?UTF-8?q?ecklist=20=E4=B8=AD=E5=91=BD=E4=BB=A4=E4=B8=8E=E6=A0=87?= =?UTF-8?q?=E7=AD=BE=E7=9A=84=E8=A1=8C=E5=86=85=E4=BB=A3=E7=A0=81=E6=A0=BC?= =?UTF-8?q?=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-slides/references/validation-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/lark-slides/references/validation-checklist.md b/skills/lark-slides/references/validation-checklist.md index 9605f265c5..f68beacb7b 100644 --- a/skills/lark-slides/references/validation-checklist.md +++ b/skills/lark-slides/references/validation-checklist.md @@ -26,7 +26,7 @@ lark-cli slides +xml-get --as user \ ## Automated XML Text Overlap Lint -slides +xml-get 保存 XML 到本地文件后,必须运行 XML 语法和文本重叠静态检查;输入可以是单个 <slide> 或完整 <presentation>。 +`slides +xml-get` 保存 XML 到本地文件后,必须运行 XML 语法和文本重叠静态检查;输入可以是单个 `<slide>` 或完整 `<presentation>`。 ```bash python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation.xml> From 4263fae5df12a6d271f5efcc04bb3f9e7e4d4450 Mon Sep 17 00:00:00 2001 From: R0bynZhu <zhuyuanbin.gdut@bytedance.com> Date: Mon, 20 Jul 2026 18:57:57 +0800 Subject: [PATCH 11/11] Revert "feat/tune slides screenshot review" --- skills/lark-slides/SKILL.md | 8 ++- .../references/lark-slides-screenshot.md | 39 ++++++-------- .../references/validation-checklist.md | 53 ++++--------------- .../scripts/xml_text_overlap_lint.py | 2 +- 4 files changed, 32 insertions(+), 70 deletions(-) diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index bb86112294..5d430772ba 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -81,7 +81,7 @@ metadata: | 用户要求使用模板 | 将模板导入为 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` | -| 获取幻灯片页面截图 | 用 `slide_id` 指定页面;页号仅用于人工定位 fallback,一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.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` | @@ -100,7 +100,7 @@ metadata: **CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前,MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);`summary.error_count` 必须为 0 才能调用接口。** -**CRITICAL — 创建或大幅改写后,MUST 按 [validation-checklist.md](references/validation-checklist.md) 完成回读、静态检查和逐页截图视觉验收:回读全文 XML,核对页数、关键元素及空白/破损/溢出等布局风险;运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py);再以当前 `slide_id` 清单逐页截图并记录 review 结果。** +**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 和布局风险。** @@ -220,9 +220,7 @@ Step 3: 按 slide_plan.json 生成 XML → 创建 Step 4: 审查 & 交付 - 创建完成后,必须用 `slides +xml-get` 读取全文 XML,并按 validation-checklist.md 做显式验证记录,包括 XML 文本重叠检查 - - 静态检查通过后,使用当前回读得到的 `slide_ids` 调用 `slides +screenshot`;首次新建且页集合未变时可复用创建响应。每批最多 10 页,保存到 `.lark-slides/review/<deck-or-task-id>/screenshots/`,然后实际查看生成的图片。**截图使用 `--presentation`、重复的 `--slide-id` 和可选 `--output-dir`;不要迁移 `--output`、`--params`、`--slides`、`--pages` 或 `--presentation-id`。** - - 先为当前 `slide_ids` 建立逐页 review 记录,初始均为 `not_reviewed`;实际打开每张截图后,按「可读性、布局、视觉层级、内容完整性、图表精确可读性(有图表时)」更新为 pass / fix。**只截图或查看关键页属于抽查,不是视觉 review;只要存在 `not_reviewed` / `fix`,就不得写“已完成视觉 review”。** - - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正,修正后必须重新截图并复验该页 + - 失败或部分成功按 troubleshooting.md 处理;局部问题优先用 `+replace-slide` 修正 - 没问题 → 交付:使用 NotifyHuman 工具交付 PPT 链接 ``` diff --git a/skills/lark-slides/references/lark-slides-screenshot.md b/skills/lark-slides/references/lark-slides-screenshot.md index 32a4752fb7..74d8c69070 100644 --- a/skills/lark-slides/references/lark-slides-screenshot.md +++ b/skills/lark-slides/references/lark-slides-screenshot.md @@ -11,7 +11,7 @@ ```bash lark-cli slides +screenshot --as user \ --presentation '<xml_presentation_id 或 slides/wiki URL>' \ - --slide-id 'SLIDE_ID' + --slide-number 1 ``` 渲染本地 XML 内容: @@ -25,12 +25,12 @@ lark-cli slides +screenshot --as user \ | 参数 | 必需 | 说明 | |------|------|------| -| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL,或解析后为 slides 的 `/wiki/` URL;只标识演示文稿,不会默认截图全部页面。传 `--content` 时不能使用 | -| `--slide-id` | list 模式标准入参 | 页面 short ID;截图、修复和 review 状态均以它关联;多页截图时重复传入;一次最多 10 页。先从创建响应或 `slides +xml-get` 取得当前 `slide_ids` | -| `--slide-number` | 用户只提供“第 N 页”或旧 deck 暂未取得 `slide_id` 时使用;成功定位后必须取得对应 `slide_id`,后续不再用页号关联截图或 review 状态。不能省略 `--slide-id` 和 `--slide-number` 两者 | +| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL,或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 | +| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID;多页截图时重复传入;一次最多 10 页(`--slide-id` + `--slide-number` 合计小于等于 10) | +| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号;多页截图时重复传入;一次最多 10 页(`--slide-id` + `--slide-number` 合计小于等于 10) | | `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段;支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` | -| `--output-dir` | 否 | 输出目录,默认 `.lark-slides/screenshots`;必须是当前目录内的相对路径。截图可能返回多张图片,使用目录而不是 `--output` 文件路径 | -| `--output-name` | 否 | 仅 render 模式(`--content`)的输出文件名 stem;未指定时优先用返回的 `slide_id`,否则用 `rendered-slide`。若目标文件已存在,会自动追加递增后缀避免覆盖 | +| `--output-dir` | 否 | 输出目录,默认 `.lark-slides/screenshots`;必须是当前目录内的相对路径 | +| `--output-name` | 否 | render 模式的输出文件名 stem;未指定时优先用返回的 `slide_id`,否则用 `rendered-slide`。若目标文件已存在,会自动追加递增后缀避免覆盖 | ## 示例 @@ -39,25 +39,21 @@ lark-cli slides +screenshot --as user \ ```bash lark-cli slides +screenshot --as user \ --presentation slides_example_presentation_id \ - --slide-id 'SLIDE_ID' + --slide-number 1 ``` -### 按 `slide_id` 截图与创建后视觉 review(推荐) +### 多页截图 -视觉 review 以当前回读得到的 `slide_ids` 为页清单。单页传一个 `--slide-id`;多页可重复传入,单次最多 10 页,超过时按批次串行执行。 - -首次新建且之后没有增删页、整页替换或重排时,可复用创建响应中的 `slide_ids`。发生上述页面集合变化后,必须先回读并刷新清单;不能用页码或旧响应中的页列表绑定 review 状态。 +一次不要超过 10 页;如需更多页面,分批调用。 ```bash lark-cli slides +screenshot --as user \ - --presentation 'YOUR_PRESENTATION_ID' \ - --slide-id 'SLIDE_ID_1' \ - --slide-id 'SLIDE_ID_2' \ - --output-dir .lark-slides/review/<deck-or-task-id>/screenshots + --presentation slides_example_presentation_id \ + --slide-number 1 \ + --slide-number 2 \ + --output-dir .lark-slides/screenshots/demo ``` -随后必须用具备图像查看能力的工具打开每个返回的 `path`,逐页记录 `pass/fix`。截图落盘、批量请求成功或只查看关键页,都不等于已完成视觉 review。 - ### 渲染 XML 预览 ```bash @@ -93,10 +89,9 @@ lark-cli slides +screenshot --as user \ ## 注意事项 1. 优先使用 `slides +screenshot` 保存本地图片,不要把图片 Base64 打到 stdout。 -2. 已存在 PPT 页面截图时,不传 `--content`,用 `--presentation` + `--slide-id`。 +2. 已存在 PPT 页面截图时,不传 `--content`,用 `--presentation` + `--slide-id` 或 `--slide-number`。 3. 本地 XML 预览时,传 `--content @file` 或 `--content -`,内容应为单个 `<slide>` XML 片段;此时不要传 `--presentation` / `--slide-id` / `--slide-number`。 -4. `slide_id` 是页面 short ID,也是截图、修复和 review 状态的唯一关联键;页码仅作为用户可读的瞬时展示信息。 -5. list 模式一次最多传 10 个 `--slide-id`;更多页面请分批截图,每页仍要独立记录 review 结论。 +4. `slide_id` 是页面 short ID,页码请用 `--slide-number`。 +5. list 模式一次最多传 10 页(`--slide-id` + `--slide-number` 合计小于等于 10);更多页面请分批截图。 6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID;文件已存在时自动追加 `_2`、`_3` 等后缀,避免覆盖旧截图。 -7. 截图来自服务端渲染结果,适合创建/替换后验证页面是否为空白、破图或布局明显异常;与 `validation-checklist.md` 的逐页 rubric 一起使用。 -8. 如果因用户只给页号而使用 `--slide-number`,截图后立即回读或从响应取得 `slide_id`,后续改用 `--slide-id`;如果收到频率限制,停止扩大发送并在短暂退避后逐批重试。截图 API 白名单失败时记录原始错误,继续完成 XML 静态检查,并把视觉状态标为 `not_verified`。 +7. 截图来自服务端渲染结果,适合创建/替换后验证页面是否为空白、破图或布局明显异常。 diff --git a/skills/lark-slides/references/validation-checklist.md b/skills/lark-slides/references/validation-checklist.md index f68beacb7b..ffd337369c 100644 --- a/skills/lark-slides/references/validation-checklist.md +++ b/skills/lark-slides/references/validation-checklist.md @@ -6,14 +6,15 @@ ## Required Flow -1. 记录创建或编辑返回的 `xml_presentation_id`,以及已知的 `slide_id` / `revision_id`。`slide_id` 是 review 状态唯一关联键;页码仅可作为展示信息。 -2. 用 `slides +xml-get` 回读全文 XML 到本地文件,并以当前结果建立本次 review 的 `slide_ids` 页清单。首次新建且页集合未变时,可复用创建响应;增删页、整页替换或重排后必须刷新清单。 -3. 运行 XML 静态检查,检查实际页数、主要元素、空白/破损页、主视觉和布局风险。 -4. 先在 `.lark-slides/review/<deck-or-task-id>/visual-review.md` 为全部 `slide_ids` 建立记录,初始状态均为 `not_reviewed`;静态检查通过后再用 `slides +screenshot` 截图。每批最多 10 页,输出到 `.lark-slides/review/<deck-or-task-id>/screenshots/`。 -5. 实际打开每张截图,按下方 rubric 逐页标记 `pass` 或 `fix`;截图文件存在但未被查看时,状态必须保留为 `not_reviewed`。**关键页抽查只可作为排障/预览,不能缩小本次 review 页清单,也不能支持“全部通过”的结论。** -6. `fix` 页用 `+replace-slide` 或对应写入操作修复后,重新回读并重新截图该页;不要沿用修复前的截图结论。 -7. 截图白名单或服务端限制导致无法获取图片时,记录错误和受影响页,完成其余 XML 静态检查,并将视觉状态标记为 `not_verified`。 -8. 在最终回复中给出简短验证记录,明确区分静态检查和真实视觉 review。 +1. 记录创建或编辑返回的 `xml_presentation_id`,以及已知的 `slide_id` / `revision_id`。 +2. 用 `slides +xml-get` 回读全文 XML 到本地文件。 +3. 检查实际页数是否符合计划或用户要求。 +4. 检查每页 `<data>` 内是否有预期主要元素。 +5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。 +6. 检查页面不是全部退化为标题加 bullet list。 +7. 检查视觉层级:标题、主视觉、支撑信息三者可区分。 +8. 检查明显溢出和布局风险:重叠、越界、底部拥挤、长文本框。 +9. 在最终回复中给出简短验证记录。 回读命令: @@ -26,7 +27,7 @@ lark-cli slides +xml-get --as user \ ## Automated XML Text Overlap Lint -`slides +xml-get` 保存 XML 到本地文件后,必须运行 XML 语法和文本重叠静态检查;输入可以是单个 `<slide>` 或完整 `<presentation>`。 +`slides +xml-get` 保存 XML 到本地文件后,优先运行 XML 语法和文本重叠静态检查: ```bash python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation.xml> @@ -118,42 +119,11 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio - 正文或标签框高度不足,文本很可能被截断。 - 多个主体元素在同一区域重叠,而不是有意叠加背景。 -- 标题、标签、关键数字或相邻文本虽未几何重叠,但视觉间距过近,显得粘连、像重叠或破坏层级。 - 重要内容越过画布边界,或贴近底部超过 `y=500`。 - 高密度页使用单个长 bullet list,没有分栏、表格或分组。 - 标题、主视觉、正文的字号和颜色差异太弱,视觉层级不清。 - 所有内容页都是同一套标题加 bullets 坐标。 -## Screenshot Visual Review - -截图 review 是静态 XML 检查之后的第二道门。它用服务端真实渲染结果发现 XML 无法可靠判断的问题,例如文字截断、图片裁切、图表压盖和弱对比。 - -每页按以下检查项记录结论;页面含图表时,额外检查图表精确可读性: - -| 项目 | Pass 标准 | Fix 信号 | -|---|---|---| -| 可读性 | 标题、正文、标签和关键数字可读;对比度足够,文本层级之间有清楚的视觉间距 | 文字截断、字号过小、低对比、关键标签不可读,或相邻文字间距过近而视觉粘连 | -| 布局 | 主体未被意外遮挡,页边距和底部留白合理 | 重叠、越界、图片裁切、元素贴边、底部拥挤,或文字虽未相交但视觉上像碰撞 | -| 视觉层级 | 主结论、主视觉、支撑信息一眼可区分 | 所有元素同权重、主视觉过小、页面退化为文字堆叠 | -| 内容完整性 | 无空白、破图、占位符或错误页序;图示表达与页面角色匹配 | 空白/破损页、缺失图片、遗留模板文案或与计划不符 | -| 图表精确可读性(有图表时) | 若页面结论依赖精确比较、排序或阈值判断,读者可直接获得每个关键数据点的值:柱/线/饼图有直接数据标签,或有与图表一一对应的等价数据表/注释 | 只能靠坐标轴估读关键数值、缺少决定结论的数据标签、图例与系列无法对应;仅用于展示趋势且不承载精确结论的图表可不强制逐点标签 | - -图表检查先问“页面是否要求读者作精确判断”: - -- **需要**:比较群体得分、排名、是否达到阈值、预算/目标差异、需要从图中选方案。没有直接数值或等价数据表即为 `fix`。 -- **不需要**:只表达上升/下降趋势、定性分布或结构关系,且标题/正文已经明确结论;可不逐点展示数值,但仍须检查轴、图例、系列和关键标注是否可读。 - -推荐把记录保存在 `.lark-slides/review/<deck-or-task-id>/visual-review.md`: - -```text -| slide_id | screenshot | status | findings | action | -|---|---|---|---|---| -| p001 | screenshots/p001.png | pass | hierarchy and contrast clear | - | -| p002 | screenshots/p002.png | fix | bottom labels are clipped | enlarge text box, then rescreenshot | -``` - -只有记录中的每个目标 `slide_id` 都是 `pass`,且记录数等于当前页清单数,才可写“已完成视觉 review”。截图不可用时沿用上文的 `not_verified` 状态,并说明原因。 - ## Verification Record 最终回复必须包含简短验证记录,建议格式: @@ -163,8 +133,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio - 回读:已执行 slides +xml-get,实际页数 N / 预期 N。 - 关键页:架构解释 / Self-Attention / 对比或演进 / 总结页均存在。 - 结构:检查了主要 shape/img/table/chart 元素,无明显空白页或破损页。 -- 静态检查:xml_text_overlap_lint error_count=0;已检查标题层级、主视觉、重叠/越界/文本溢出风险。 -- 视觉 review:已查看 N/N 张服务端截图,全部 pass;或 `not_verified`(截图不可用,原因:...)。 +- 布局:检查了标题层级、主视觉、重叠/越界/文本溢出风险。 ``` 不要声称完成了人工视觉验收,除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论,应表述为“静态检查未发现明显问题”。 diff --git a/skills/lark-slides/scripts/xml_text_overlap_lint.py b/skills/lark-slides/scripts/xml_text_overlap_lint.py index b9619aca77..e87ecee247 100644 --- a/skills/lark-slides/scripts/xml_text_overlap_lint.py +++ b/skills/lark-slides/scripts/xml_text_overlap_lint.py @@ -1194,7 +1194,7 @@ def lint_xml(xml: str, source_path: str | None = None) -> dict[str, Any]: def print_usage() -> None: - print("Usage:\n python3 xml_text_overlap_lint.py --input <presentation-or-slide.xml>", file=sys.stderr) + print("Usage:\n python3 xml_text_overlap_lint.py --input <presentation.xml>", file=sys.stderr) def run_cli(argv: list[str] | None = None) -> None: