From 09e986d0fd4041e7c19ce9cce0969ced96b3a3aa Mon Sep 17 00:00:00 2001 From: zhanghuanxu Date: Thu, 7 May 2026 18:01:19 +0800 Subject: [PATCH] feat(slides): improve slide planning and validation guidance refactor(slides): rename slide layout lint scope Change-Id: I1b0e42b6508ec2c5f6ae6dc0d1b7ac23c5bbe2e3 feat(slides): improve lark slides skill guidance Change-Id: I49563da4ca623a89f5391f36ceb8f5a31417e321 feat(slides): strengthen lark slides planning guidance Change-Id: If49330e1f9b779bc76a919565ed61a31c255f508 feat(slides): remove lark slides layout lint rules Change-Id: I64f1fc3b33d05c069c9ef58e61d00aa57ac18ecd refactor(slides): streamline skill guidance Change-Id: I3b39faaab7dcac52fac1572590fc5d8934428da5 feat(slides): add slides asset planning guidance Change-Id: I37303043f7704e4ba484552158390a4e24bf9c42 feat(slides): add visual planning guidance Change-Id: Idee7c392d41ff02124313d572c547d0a086d9c35 feat(slides): add lark slides planning layer Change-Id: I3f0765aa53656070d9ba9b388dade19355e7bc6f --- .gitignore | 1 + skills/lark-slides/SKILL.md | 431 ++++-------------- .../lark-slides/references/asset-planning.md | 124 +++++ ...rk-slides-xml-presentation-slide-create.md | 5 +- .../lark-slides/references/planning-layer.md | 219 +++++++++ .../references/template-catalog.md | 1 - .../lark-slides/references/troubleshooting.md | 63 +++ .../references/validation-checklist.md | 102 +++++ .../lark-slides/references/visual-planning.md | 250 ++++++++++ ...ayout_lint.py => xml_text_overlap_lint.py} | 182 ++++---- ..._test.py => xml_text_overlap_lint_test.py} | 140 +++++- 11 files changed, 1084 insertions(+), 434 deletions(-) create mode 100644 skills/lark-slides/references/asset-planning.md create mode 100644 skills/lark-slides/references/planning-layer.md create mode 100644 skills/lark-slides/references/troubleshooting.md create mode 100644 skills/lark-slides/references/validation-checklist.md create mode 100644 skills/lark-slides/references/visual-planning.md rename skills/lark-slides/scripts/{layout_lint.py => xml_text_overlap_lint.py} (70%) rename skills/lark-slides/scripts/{layout_lint_test.py => xml_text_overlap_lint_test.py} (51%) diff --git a/.gitignore b/.gitignore index 90313e480..b0b9f579a 100644 --- a/.gitignore +++ b/.gitignore @@ -34,6 +34,7 @@ tests/mail/reports/ # Generated / test artifacts .hammer/ +.lark-slides/ internal/registry/meta_data.json cmd/api/download.bin app.log diff --git a/skills/lark-slides/SKILL.md b/skills/lark-slides/SKILL.md index 095a95f25..3adc795ec 100644 --- a/skills/lark-slides/SKILL.md +++ b/skills/lark-slides/SKILL.md @@ -10,16 +10,38 @@ metadata: # slides (v1) +## Quick Reference + +| 用户需求 | 优先动作 | 关键文档 / 命令 | +|----------|----------|-----------------| +| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` | +| 大幅改写页面 | 先回读现有 XML，写入新 plan，再替换或重建相关页面 | `xml_presentations.get`、`+replace-slide`、`lark-slides-edit-workflows.md` | +| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` | +| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` | +| 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 | +| 用户提到模板、主题、版式 | 先检索模板，再摘要，必要时裁切骨架 | `template_tool.py search → summarize → extract` | +| 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` | + **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理** **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。** +**CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan//slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。** + +**CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。** + +**CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。** + +**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。** + +**CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。** + **CRITICAL — 如果用户提到“模板”“套用模板”“参考某种主题/风格/版式”，或用户需求明显落在已有场景模板内（如工作汇报、产品介绍、商业计划书、培训、晋升汇报等），MUST 先用 [`scripts/template_tool.py`](scripts/template_tool.py) 的 `search` 做模板检索；默认给出 2-3 个最匹配模板候选供用户选择。锁定模板后用 `summarize` 获取主题和布局摘要；只有需要布局骨架时才用 `extract` 裁切目标页型 XML。不要直接读取完整模板 XML。** > [!NOTE] > `scripts/template_tool.py` 需要 Python 3。`references/template-index.json` 是脚本缓存/轻量路由索引，不是默认给 agent 阅读的文档；`assets/templates/*.xml` 是机器资源，只应通过脚本摘要或裁切，不要全文读取。 -**CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。生成本地 XML 后，如可运行 Python，MUST 先用 [`scripts/layout_lint.py`](scripts/layout_lint.py) 检查 XML well-formed、重叠/越界/文本高度风险，再创建或追加页面。它不是完整 XSD schema 校验。** +**CRITICAL — 使用模板生成或改写页面时，MUST 先 `summarize` 目标页型；只有需要具体布局骨架时才 `extract`。** **编辑已有幻灯片页面**：优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。 @@ -41,54 +63,68 @@ lark-cli auth login --domain slides 2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。 3. 只有在用户明确要求"用应用身份 / bot 身份操作"，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。 -## 快速开始 +## 执行前必做 -一条命令创建包含页面内容的 PPT（推荐）： +> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。 -```bash -lark-cli slides +create --title "演示文稿标题" --slides '[ - "

页面标题

正文内容

  • 要点一

  • 要点二

" -]' -``` +高频只读： -也可以分两步（先创建空白 PPT，再逐页添加），详见 [+create 参考文档](references/lark-slides-create.md)。 +- [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) +- [planning-layer.md](references/planning-layer.md)（新建 / 大幅改写） +- [visual-planning.md](references/visual-planning.md)（新建 / 大幅改写） +- [asset-planning.md](references/asset-planning.md)（新建 / 大幅改写） +- [validation-checklist.md](references/validation-checklist.md)（创建 / 大幅改写后） -> [!WARNING] -> `--slides '[...]'` 适合简单页面批量创建，但并不等同于“10 页以内都安全”。如果 slide XML 含中文、大段文本、复杂布局、嵌套引号或较多特殊字符，shell 传参时可能出现转义或截断问题，导致内容丢失、页面空白或布局异常。遇到复杂页面时，优先改用“两步创建法”。 +按需再读： -> [!IMPORTANT] -> `slides +create --slides` 底层是“先创建空白 PPT，再逐页调用 `xml_presentation.slide.create`”。这不是原子操作；中途某一页失败时，前面已创建成功的页面会保留。skill 必须把这种“部分成功”风险提前告诉用户，并在失败后先记录 `xml_presentation_id`，回读确认当前状态，再决定是否在现有 PPT 上继续修复或追加。 +- 创建：[`lark-slides-create.md`](references/lark-slides-create.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-media-upload.md`](references/lark-slides-media-upload.md) +- 模板：[`template-catalog.md`](references/template-catalog.md)、[`scripts/template_tool.py`](scripts/template_tool.py) +- 排障：[`troubleshooting.md`](references/troubleshooting.md) +- 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml) -> 以上是最小可用示例。更丰富的页面效果（渐变背景、卡片、图表、表格等），参考下方 Workflow 和 XML 模板。 +## Workflow -## 执行前必做 +> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。 -> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。 +### Design Ideas -### 必读（每次创建前） +不要生成无设计感的幻灯片。纯白背景 + 标题 + bullets 只能作为极简临时稿，不能作为正式交付。 -| 文档 | 说明 | -|------|------| -| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML 元素和属性速查，必读** | +开始写 XML 前，先在 `slide_plan.json` 里确定 deck 级视觉策略： -### 选读（需要时查阅） +- **主题化配色**：配色必须服务本次主题、行业和受众，不要默认蓝色商务风。如果把同一套颜色换到另一个完全不同主题仍然成立，说明配色不够具体。 +- **主次比例**：选择 1 个主色承担约 60-70% 视觉权重，1-2 个辅助色承担结构和分区，1 个强调色只用于关键数字、结论或行动点。不要让所有颜色权重相同。 +- **背景一致性**：先确定全 deck 的背景策略，默认保持同一明暗基调和底色体系；只有分节、转场或强调页才有意改变背景，并必须通过相同主色、纹理、边栏或 motif 让变化看起来属于同一套设计。无论深浅，都要保证正文、图标和线条对比充足。 +- **统一 motif**：选择一个可复用视觉母题贯穿全文，例如粗侧边栏、圆形图标底、半出血图片区、编号节点、卡片左上角色块或大号数字。不要每页换一套装饰语言。 -| 场景 | 文档 | -|------|------| -| 需要了解详细 XML 结构 | [xml-format-guide.md](references/xml-format-guide.md) | -| 需要快速筛模板、做低成本路由 | [`scripts/template_tool.py search`](scripts/template_tool.py) | -| 需要匹配 PPT 模板/主题风格 | [template-catalog.md](references/template-catalog.md) | -| 需要按页型抽摘要或裁切 XML 片段 | [`scripts/template_tool.py`](scripts/template_tool.py) | -| 需要做本地布局风险检查 | [`scripts/layout_lint.py`](scripts/layout_lint.py) | -| 需要 CLI 调用示例 | [examples.md](references/examples.md) | -| 需要参考真实 PPT 的 XML | [slides_demo.xml](references/slides_demo.xml) | -| 需要用 table/chart 等复杂元素 | [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml)（完整 Schema） | -| 需要编辑已有 PPT 的单个页面 | [lark-slides-edit-workflows.md](references/lark-slides-edit-workflows.md) | -| 需要了解某个命令的详细参数 | 对应命令的 reference 文档（见下方参考文档章节） | +每页至少要有一个视觉元素：图片、图标、图表、表格、流程、对比结构、大号数字、示意图或由 shape 组成的抽象视觉。文本框本身不算主视觉。 -## Workflow +可优先考虑这些页面形态： -> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。 +- **双栏结构**：左文右图或左图右文，视觉区域占 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 视觉。 +- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。 ### 创建方式选择 @@ -101,156 +137,40 @@ lark-cli slides +create --title "演示文稿标题" --slides '[ > [!WARNING] > `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。 +> [!IMPORTANT] +> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。 + ### 模板与脚本优先流程 +模板细则见 [template-catalog.md](references/template-catalog.md)。主流程只记住：先 `search`，锁定后 `summarize`，需要骨架时才 `extract`；不要直接读取完整模板 XML 或照搬占位文案。 + ```bash -# 1. 搜索候选：把用户原始需求整句放进 --query，不要只放手动提炼的短词 python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3 - -# 2. 锁定模板后先看页型摘要 python3 skills/lark-slides/scripts/template_tool.py summarize --template --label <封面|目录|分节|内容|结尾> - -# 3. 只有需要复用布局骨架时才裁切 XML python3 skills/lark-slides/scripts/template_tool.py extract --template --label <页型> --out /tmp/template-slice.xml - -# 4. 生成待创建 XML 后先做布局风险检查 -python3 skills/lark-slides/scripts/layout_lint.py --input /tmp/presentation.xml ``` -执行规则： - -1. `search --query` 使用用户原始描述；如用户明确风格，再额外加 `--tone light|dark|colorful` 或 `--formality formal|casual|creative`。 -2. 候选展示只给 2-3 个，包含模板名、适用场景、风格/色调、推荐理由；不要把完整目录贴给用户。 -3. 锁定模板后，复用 ``、配色、页面流、布局骨架；所有占位文案都必须改写为用户真实内容。 -4. `layout_lint.py` 有 error 时先修 XML，不要提交创建；只有 warning 时，检查是否是可接受的装饰/背景误报。 - ```text Step 1: 需求澄清 & 读取知识 - - 澄清用户需求：主题、受众、页数、风格偏好 - - 如果需求明显落在已有模板场景内，主动提示用户“可以直接基于现成模板生成”，并给出 2-3 个最匹配模板候选（模板名 + 适用场景 + 风格/色调 + 简短推荐理由） - - 默认不要把完整模板目录直接贴给用户；除非用户明确要求看更多，否则只展示 2-3 个候选 - - 候选优先选场景强相关模板；只有没有明显场景模板时，才用 `light_general.xml` / `dark_general.xml` 这类通用模板兜底 - - 如果用户没有明确风格，根据主题推荐（见下方风格判断表） - - 如果用户要求“模板/主题/风格参考”，或主题属于常见模板场景： - · 优先运行 `python3 skills/lark-slides/scripts/template_tool.py search --query "<用户需求原文>" --limit 3` 做低成本模板匹配 - · 需要人类可读说明时，再读 template-catalog.md 组织候选文案 - · 锁定模板后，优先运行 `template_tool.py summarize` 看 `` / 页型摘要；需要具体布局时，再用 `template_tool.py extract` - · 复用模板的 theme、配色、页面流、布局骨架，不要照搬占位文案 - · `references/template-index.json` 只是脚本缓存/轻量路由索引，`assets/templates/*.xml` 是机器资源；除非用户明确要求审计原始模板，否则不要直接读取 - - 读取 XML Schema 参考： - · xml-schema-quick-ref.md — 元素和属性速查 - · xml-format-guide.md — 详细结构与示例 - · slides_demo.xml — 真实 XML 示例 - -Step 2: 生成大纲 → 用户确认 → 创建 - - 生成大纲前，先确认用户是否采用推荐模板；轻量任务且候选中有明显最佳匹配时，可在大纲里声明“默认基于 改写”并继续，但正式创建前必须给用户改选机会 - - 生成结构化大纲（每页标题 + 要点 + 布局描述），交给用户确认 - - 如果已选模板，大纲和页面布局要明确标注“基于哪个模板/哪些模板改写” - - 如果用户明确不要模板，直接按自定义风格继续，不要重复推动模板选择 - - 先判断创建方式： - · 简单 XML：可用 `slides +create --slides '[...]'` 一步创建 - · 复杂 XML：优先先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加 - · 超过 10 页：默认使用两步创建，避免单次输入过长 - - 含本地图片： - · 新建带图 PPT —— 在 slide XML 里写 ， - +create 会自动上传并替换为 file_token（详见 lark-slides-create.md） - · 给已有 PPT 加带图新页 —— 先 `slides +media-upload --file ./pic.png --presentation $PID` - 拿到 file_token，再用它写进 slide XML 调 xml_presentation.slide.create - · 给已有页加图 —— 两步：① `slides +media-upload` 拿 file_token - ② `slides +replace-slide --parts '[{"action":"block_insert","insertion":"\" .../>"}]'` - 不动其他元素，不要再整页重建（完整示例见 lark-slides-edit-workflows.md 的 block_insert 章节） - · 路径必须是 CWD 内的相对路径（如 ./pic.png 或 ./assets/x.png）； - 绝对路径会被 CLI 拒绝，先 cd 到素材所在目录再执行 - - 每页 slide 需要完整的 XML：背景、文本、图形、配色 - - 复杂元素（table、chart）需参考 XSD 原文 - - 创建前必须做 XML 自检： - · 检查特殊字符是否按 XML 规则转义：文本节点和属性值里的裸 `& -> &`；文本里的 `< -> <`、`> -> >`。例如 `Q&A -> Q&A`，URL 属性 `a=1&b=2 -> a=1&b=2` - · 属性值里的双引号必须转义或改为外层安全包装，避免 shell 和 JSON 双重截断 - · 确认所有标签闭合，且 `` 直接子元素只包含 `