findscripter 何时使用
当用户要创建、编辑或分析 .pptx 演示文稿时使用。.pptx 本质是一个 ZIP 包，内含 XML 与媒体资源，可读可改。按四类任务分流：
- 读/分析内容：抽取正文、讲者备注、批注、版式、动画、设计配色字体。
- 从零创建（无模板）：走 html2pptx 工作流，把 HTML 幻灯片转成定位精确的 PPTX。
- 编辑现有文稿：直接改 OOXML（拆包→改 XML→校验→打包）。
- 套模板创建：复用现成模板的版式，复制重排幻灯片后替换占位文本。
不该用的边界：
- 只需纯文本、无版式/视觉要求 → 直接写 Markdown 或正文，别做 PPTX。
- 目标是 Word（
.docx）或 Excel（.xlsx）→ 用对应文档技能，不用本技能。 - 仅需把 PPTX 内容做问答/总结 → 用「读/分析」分支抽文本即可，不必生成新文件。
- 一句话回复、随手笔记不构成演示场景。
步骤 / 指令
A. 读取与分析
- 只读正文：转 Markdown
python -m markitdown path-to-file.pptx - 需要备注/批注/版式/动画/复杂格式：必须拆包读原始 XML
脚本若不在该路径，用python ooxml/scripts/unpack.py <office_file> <output_dir>find . -name "unpack.py"定位。关键结构：ppt/presentation.xml主元数据与幻灯片引用ppt/slides/slide{N}.xml单页内容ppt/notesSlides/notesSlide{N}.xml讲者备注ppt/comments/modernComment_*.xml批注ppt/slideLayouts/、ppt/slideMasters/、ppt/theme/、ppt/media/
- 仿照示例设计时先提取配色与字体：读
ppt/theme/theme1.xml的<a:clrScheme>/<a:fontScheme>；看slide1.xml实际<a:rPr>用法；用 grep 搜<a:solidFill>、<a:srgbClr>跨文件找配色字体。
B. 从零创建（html2pptx）
- 强制先读整份
html2pptx.md（不要设行数范围），掌握语法与硬规则再动手。 - 动手前先声明设计取向：分析主题/行业/受众，选 3–5 色调色板（主色+辅色+点缀，确保对比度），只用 web 安全字体（Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact）。
- 每页一个 HTML，按 16:9 设
720pt × 405pt；文本用<p>/<h1>-<h6>/<ul>/<ol>；图表/表格区用class="placeholder"（灰底占位）。渐变与图标先用 Sharp 栅格化为 PNG 再引用。 - 含图表/表格的页用「整页布局」或「两栏布局（如 40%/60%）」，严禁文字上、图表下的纵向堆叠。
- 写并运行 JS，用
scripts/html2pptx.js的html2pptx()处理每页，用 PptxGenJS API 往占位区加图表/表格，pptx.writeFile()保存。 - 视觉校验：生成缩略图网格
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4，逐页查文字截断/重叠/贴边/对比度不足，有问题改 HTML 再重生成，直至无误。
C. 编辑现有文稿
- 强制先读整份
ooxml.md（约 500 行，不要设范围）。 - 拆包
python ooxml/scripts/unpack.py <office_file> <output_dir>。 - 改 XML（主要是
ppt/slides/slide{N}.xml）。 - 每改一处立即校验并修错：
python ooxml/scripts/validate.py <dir> --original <file>。 - 打包
python ooxml/scripts/pack.py <input_directory> <office_file>。
D. 套模板创建
- 抽文本 + 生成缩略图：
python -m markitdown template.pptx > template-content.md；python scripts/thumbnail.py template.pptx，整读template-content.md。 - 写
template-inventory.md盘点每页（0 起索引：首页=0，末页=count-1），逐页记版式与用途。 - 据盘点写
outline.md与模板映射：版式必须匹配真实内容数量（两栏只用于恰好 2 项，三栏只用于恰好 3 项，引用版式只用于真实带署名的引语，占位多于内容则不选）。先数内容块再选版式。 - 复制/重排/删页：
python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52（索引可重复以复制该页）。 - 抽全量文本清单：
python scripts/inventory.py working.pptx text-inventory.json，整读该 JSON（slide-N / shape-N，按视觉位置排序，含 placeholder_type 与段落属性）。 - 生成替换文本存
replacement-text.json：只引用清单中确实存在的 shape；给需要内容的 shape 加paragraphs（不是 replacement_paragraphs）；未给 paragraphs 的 shape 会被自动清空；标题/段头"bold": true，列表项"bullet": true, "level": 0（bullet 为真时 level 必填且别再设 alignment、别在文本里写 •/-/* 符号）；保留原始对齐/字体/颜色（"color":"FF0000"或"theme_color":"DARK_1"）。 - 应用：
python scripts/replace.py working.pptx replacement-text.json output.pptx（脚本会先校验 shape 存在、清空全部清单内 shape、再按 JSON 写回并保留格式；越界 shape/slide 会一次性报全部错误）。
辅助：转图做视觉分析
soffice --headless --convert-to pdf template.pptx
pdftoppm -jpeg -r 150 template.pdf slide # 生成 slide-1.jpg...，-f/-l 限定页范围
示例
最小可用——抽取演示文稿正文：
python -m markitdown deck.pptx
改某页文字（编辑分支）：
python ooxml/scripts/unpack.py deck.pptx ./unpacked
# 编辑 ./unpacked/ppt/slides/slide3.xml
python ooxml/scripts/validate.py ./unpacked --original deck.pptx
python ooxml/scripts/pack.py ./unpacked deck-edited.pptx
replacement-text.json 片段（套模板分支）：
{
"slide-0": {
"shape-0": {
"paragraphs": [
{ "text": "新标题", "alignment": "CENTER", "bold": true },
{ "text": "首条要点（无需符号）", "bullet": true, "level": 0 }
]
}
}
}
给 Agent 的提示词模板：
用
template.pptx做一份 5 页演示：先盘点模板每页版式（0 起索引），按内容块数量选匹配版式，rearrange 出 working.pptx，inventory 抽文本，生成 replacement-text.json 后 replace 出 output.pptx，最后用 thumbnail 逐页核对无截断/重叠再交付。
注意事项
- 一律用绝对路径；脚本默认在
skills/pptx/ooxml/scripts/下，路径不符先find定位。 - 编辑分支每改一处立即 validate，校验失败先修再继续，别累积错误到打包阶段才发现。
- 套模板分支索引0 起；rearrange 前核对索引在范围内（73 页模板索引为 0–72），越界会报错。
- replace 的「自动清空」是默认行为：凡清单里有、JSON 里没给
paragraphs的 shape 都会被清空，别遗漏需保留的页。 - bullet 为真时别写项目符号字符、别设 alignment，符号与左对齐由脚本自动处理。
- html2pptx 里渐变/图标必须先栅格化为 PNG 再引用，否则定位与渲染会出错；只用 web 安全字体。
- 缩略图视觉校验是必经环节，命令静默成功不代表版面正确，务必读图核对。
- 依赖须就位：
markitdown[pptx]、pptxgenjs、playwright、react-icons、sharp、LibreOffice、poppler-utils、defusedxml（安全 XML 解析）。 - 代码风格：简洁、避免冗长变量名与多余 print。处理外部来源文件前确认无加密/权限限制。
互见
- requires：无。
- related：
markdown-to-docx（目标是 Word 而非演示时改用）、doc-coauthoring（先共创文档大纲，再据此做 PPT）。 - combines_with：
pdf-form-filler（演示导出 PDF 后若需在表单字段上填写时搭配）。
采编自 sickn33/antigravity-awesome-skills（MIT）。