pengfeiqiao/kunpeng/lark-slides

lark-cli auth login --domain slides

lark-cli slides +create --title "演示文稿标题" --slides '[
  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245,245,245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"100\"><content textType=\"title\"><p>页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"200\"><content textType=\"body\"><p>正文内容</p><ul><li><p>要点一</p></li><li><p>要点二</p></li></ul></content></shape></data></slide>"
]'

# 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 <template-id> --label <封面|目录|分节|内容|结尾>
 
# 3. 只有需要复用布局骨架时才裁切 XML
python3 skills/lark-slides/scripts/template_tool.py extract --template <template-id> --label <页型> --out /tmp/template-slice.xml
 
# 4. 生成待创建 XML 后先做布局风险检查
python3 skills/lark-slides/scripts/layout_lint.py --input /tmp/presentation.xml

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` 看 `<theme>` / 页型摘要；需要具体布局时，再用 `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: 生成大纲 → 用户确认 → 创建
  - 生成大纲前，先确认用户是否采用推荐模板；轻量任务且候选中有明显最佳匹配时，可在大纲里声明“默认基于 <template-id> 改写”并继续，但正式创建前必须给用户改选机会
  - 生成结构化大纲（每页标题 + 要点 + 布局描述），交给用户确认
  - 如果已选模板，大纲和页面布局要明确标注“基于哪个模板/哪些模板改写”
  - 如果用户明确不要模板，直接按自定义风格继续，不要重复推动模板选择
  - 先判断创建方式：
    · 简单 XML：可用 `slides +create --slides '[...]'` 一步创建
    · 复杂 XML：优先先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
    · 超过 10 页：默认使用两步创建，避免单次输入过长
  - 含本地图片：
    · 新建带图 PPT —— 在 slide XML 里写 <img src="@./pic.png" .../>，
      +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":"<img src=\"<file_token>\" .../>"}]'`
      不动其他元素，不要再整页重建（完整示例见 lark-slides-edit-workflows.md 的 block_insert 章节）
    · 路径必须是 CWD 内的相对路径（如 ./pic.png 或 ./assets/x.png）；
      绝对路径会被 CLI 拒绝，先 cd 到素材所在目录再执行
  - 每页 slide 需要完整的 XML：背景、文本、图形、配色
  - 复杂元素（table、chart）需参考 XSD 原文
  - 创建前必须做 XML 自检：
    · 检查特殊字符是否按 XML 规则转义：文本节点和属性值里的裸 `& -> &amp;`；文本里的 `< -> &lt;`、`> -> &gt;`。例如 `Q&A -> Q&amp;A`，URL 属性 `a=1&b=2 -> a=1&amp;b=2`
    · 属性值里的双引号必须转义或改为外层安全包装，避免 shell 和 JSON 双重截断
    · 确认所有标签闭合，且 `<slide>` 直接子元素只包含 `<style>`、`<data>`、`<note>`
    · 如果内容里同时出现中文、大段文本、复杂布局、较多特殊字符，默认不要走 `--slides '[...]'`，直接改用两步创建法
    · 如果 XML 已落到本地文件且可运行 Python，先执行 `layout_lint.py --input <file>`；它会先检查 XML well-formed 再检查布局风险，但不等价于完整 XSD schema 校验；有 error 先修复再创建
  - 如果使用模板生成页面，先复用模板骨架再填内容，不要直接复制模板中的长段占位文本
 
Step 3: 审查 & 交付
  - 创建完成后，必须用 xml_presentations.get 读取全文 XML 做创建后验证，确认：
    · 页数是否正确？
    · 每页 `<data>` 是否包含预期的 `<shape>` / `<img>` / 其他元素？
    · 文本内容是否完整，是否有被截断、丢失、空白区域？
    · 关键布局坐标和尺寸是否合理，是否出现明显重叠？
    · 配色是否统一？字号层级是否合理？
  - 如果本地有 Python 3，运行
    `python3 skills/lark-slides/scripts/layout_lint.py --input presentation.xml`
    做重叠、越界、页脚碰撞、文本高度风险检查；有 error 先修复再交付
  - 如果创建过程中失败：
    · 先保留并记录 `xml_presentation_id`，不要假设失败代表什么都没创建
    · 先判断是否已有部分页面写入，再决定是否在现有 PPT 上修复后继续追加
    · 优先排查当前失败页：先看该页 XML，再检查是否存在未转义 `&`、错误引号、标签未闭合、shell 传参截断
  - 局部问题 → 用 `+replace-slide` 块级修正；整页结构要改 → `slide.delete` 旧页 + `slide.create` 新页
  - 没问题 → 交付：告知用户演示文稿 ID 和访问方式

lark-cli slides xml_presentations get --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}'

# 创建
lark-cli slides +create --as user --title "Demo" --slides '[...]'
 
# 立即回读
lark-cli slides xml_presentations get --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}'

# 追加到末尾
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
  <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
  <data>
    在这里放置 shape、line、table、chart 等元素
  </data>
</slide>' '{slide:{content:$content}}')"
 
# 插到指定页之前：before_slide_id 必须在 --data body 里，与 slide 同级
# ⚠️ 不要把 before_slide_id 写进 --params —— CLI 会当未知 query 参数静默下发，服务端忽略，新页跑到末尾
lark-cli slides xml_presentation.slide create \
  --as user \
  --params '{"xml_presentation_id":"YOUR_ID"}' \
  --data "$(jq -n --arg content '<slide ...>...</slide>' --arg before 'TARGET_SLIDE_ID' \
    '{slide:{content:$content}, before_slide_id:$before}')"

[PPT 标题] — [定位描述]，面向 [目标受众]
 
模板：[未使用模板 / <category>/<template>.xml（推荐原因）]
 
页面结构（N 页）：
1. 封面页：[标题文案]
2. [页面主题]：[要点1]、[要点2]、[要点3]
3. [页面主题]：[要点描述]
...
N. 结尾页：[结尾文案]
 
风格：[配色方案]，[排版风格]