pptgen-drawio

PPT 多页 Draw.io 生成（论文答辩 + 通用汇报）

本 skill 支持两种模式，共用 ppt_template/、scripts/、reference/ 目录，以及 Step 0 自定义模板、Step 1 确定内容与风格、Step 3 & 4 输出与导出 全流程。

---

模式识别

模式	使用时机	内容来源	默认页序	输出文件
论文答辩	学位论文答辩、开题、预答辩	paper-write 结构化提取	封面→目录→背景→现状→方法→创新点→实验→结论→致谢→Q&A	paper-defense.drawio
通用汇报	工作汇报、产品介绍、演讲	用户消息提取/生成	封面→目录→节标题→内容页→总结→致谢→Q&A	general-presentation.drawio

---

Step 0：用户自定义模板（可选，两种模式共用）

若用户提供了自己的 .pptx 模板文件：

1. 模板放置：将 .pptx 放入 ppt_template/ 目录
2. 运行样式提取：在 skill 根目录下执行：

   python scripts/analyze_pptx.py ppt_template/xxx.pptx reference/style-custom.md
   

3. 读取 reference/style-custom.md 作为「自定义风格」继续

目录约定：ppt_template/ 存放模板、scripts/analyze_pptx.py 样式提取、reference/ 风格文件

---

Step 1：确定内容与风格（两种模式共用）

1.1 确定内容

• 论文答辩：若用户只有论文全文：先调用 paper-write 的「结构化信息提取」；若已提供结构化信息：从消息中提取【论文题目】【学科方向】【答辩时长】【论文结构/目录】【各章核心内容】【创新点/贡献】等，缺失则追问
• 通用汇报：从用户消息中提取幻灯片大纲及内容，或根据核心需求扩展为完整结构

1.2 选择风格

两种模式均可选择以下风格之一，读取对应 reference 文件获取配色、字体、版式规则与 XML 样式片段：

#	风格	主色	强调色	有无顶栏装饰	reference 文件
1	经典学术 / 商务严谨	#1B2A4A	#C9A84C	有：顶栏 150px + 金线 8px	reference/style1-classic-academic.md
2	现代极简 / 大字报感	#231F20	#F5C638	无，靠留白和字号差	reference/style2-minimal-bigtype.md
3	暖色学术 / 亲和力	#2C5160	#B7472A	有，同风格一结构	reference/style3-warm-academic.md
4	科技明快 / 现代前沿	#0170C1	同主色	有	reference/style4-tech-modern.md
5	自定义	从 style-custom.md 提取		看模板	reference/style-custom.md

• 论文答辩：用户未指定时默认风格 1
• 通用汇报：用户选择或根据语境自动推荐
• 风格 1 / 3 / 4 是同一套版式换配色（顶栏 + 细线 + 页脚），只有风格 2 是真正不同的版式。用户想要「看起来不一样」时推风格 2；传统工科院校答辩推风格 1

---

Step 2：生成多页 Draw.io XML

必须先读取所选风格的 reference 文件，基于该风格生成 XML。

• 画布：16:9（pageWidth=1920，pageHeight=1080）
• 页序：按模式识别表中的默认页序
• 页数：由 Step 1.1 拿到的答辩时长决定，见下面 2.1

2.1 论文答辩模式页序（按时长换算）

页数由三部分相加：

封面 · 目录 · 已有成果 · 致谢/Q&A            → 4 页，任何时长都有
每章一个节标题过渡页                          → 章数 × 1 页
各章内容页                                    → 按下表分配

按时长选一列，表里的数字是「各章内容页数」：

章节	10 分钟	15 分钟	20 分钟
01 研究背景与意义	1	2	3
02 国内外研究现状	1	1	2
03 方法（含创新点）	2	3	3
04 实验结果	1	2	2
05 系统设计与实现	1	1	2
06 总结与展望	1	1	1
内容页小计	7	10	13
总页数（+4 固定 +6 节标题）	17	20	23

时长不在表里就按 每页 45 秒估：总页数 ≈ 时长(分) × 60 ÷ 45，再按上表比例分配到各章。

方法章占比是硬要求：方法 + 实验合起来不少于内容页的 40%。这是答辩评委真正听的部分，背景和现状讲长了会被打断。

用户点名要几页就按用户的，上表只在用户没说页数时用。

原先固定 23 页的写法已废弃——那个数来自 style1 的源文件 答辩PPT.pptx，是一份 20 分钟以上答辩的真实页数，不适用于 10–15 分钟。

各 reference/styleX-*.md 只定义样式与版式（颜色、字体、组件布局），不定义页序和页数。

2.2 文件命名与交付（建议，Windows 兼容）

• 推荐命名（生成/导出阶段）：优先使用 ASCII 文件名（英文字母/数字/中划线），减少 PowerShell/编码环境下中文文件名乱码、命令找不到文件等问题。
  • 推荐：defense-style4-tech.drawio、defense-style4-tech.pptx
  • 如必须中文名：建议先用 ASCII 名完成导出，再在资源管理器里重命名为中文
• 交付顺序（推荐流程）：先提供 .drawio（源文件）→ 执行命令导出 .pptx（交付文件）→ 校验页数
• 交付依赖：接收方只需打开 .pptx（必要时附 .drawio），不需要安装 Python；脚本/代码仅用于生成端自动写 XML（可选）。

⚠️ 已知坑清单（生成前逐条过）

✅ 必过 checklist（7 条）

1. 多页结构：根节点必须是 <mxfile>，且每页一个 <diagram>（否则导出会变 1 页）。

2. 每页坐标系：每个 <diagram> 内 x 从 0 开始；背景矩形 x=0,y=0,w=1920,h=1080；每页都有 mxCell id="0" 与 mxCell id="1" parent="0"。

3. ID 唯一：全文件内所有 mxCell id 必须唯一；每个 <diagram id="..."> 也必须唯一。

4. 一次性写入：.drawio 必须一次写完整（不要多次覆盖/拼接 XML）。

5. 换行用 
，不要用真实换行符。XML 规范规定属性值里的字面换行会被规范化成空格，所以 value="第一行\n第二行" 导出后是一行，中间多个空格。实测（drawio2pptx 0.0.7 + PowerPoint）：

   写法	导出结果
   value="A
B"	✅ 两行
   value="A<br>B"	✅ 两行（拆成两个段落）
   value="A 真实换行 B"	❌ 一行，换行变空格

   多行正文用 
；需要拆成独立段落（比如列表项各自成段）用 <br>。文本 style 必含 whiteSpace=wrap;html=1;。

6. 白字不要误替换：顶栏/深色块文字保持 fontColor=#FFFFFF；背景色替换优先改 fillColor，不要全局替换所有 #FFFFFF。

7. 遮挡检查：带底色的装饰块不要跨越正文区域；两列卡片之间不要放有底色标签（会压住字）。

原先还有三条「每页 cell 数 ≥ N」「高度按 1.4 倍字号预算」「页数校验」——前两条是在猜渲染结果，第三条只能验证页数。都已被 Step 5 的 render_check.py 取代：那个脚本用真实字体文件量宽度，直接告诉你哪一页第几个框会裁字。不要再靠加 cell 凑数或按系数估行高。

最小可用多页模板（仅示意结构）

<mxfile host="app.diagrams.net">
  <diagram id="p1" name="封面">
    <mxGraphModel page="1" pageWidth="1920" pageHeight="1080">
      <root>
        <mxCell id="0"/><mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
  <diagram id="p2" name="目录">
    <mxGraphModel page="1" pageWidth="1920" pageHeight="1080">
      <root>
        <mxCell id="0"/><mxCell id="1" parent="0"/>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

---

Step 3 & 4 & 4.5 & 5：Draw.io ファイルの出力、PPT のエクスポート、修正、レンダリングの検証（両方のモードで共通）

Step 3：Draw.io ファイルを出力する

生成した XML を、ワークスペース内の .drawio ファイルに一度に書き込みます（論文発表用は paper-defense.drawio、一般プレゼンテーション用は general-presentation.drawio）。各ページの概要も簡潔に説明してください。

書き込み方法は、checklist の第 4 項「一度に書き込む」と第 5 項「改行には 
 を使う」の要件を満たす必要があります。

Step 4：PPT をエクスポートする（必須）

1. 未インストールの場合：pip install drawio2pptx -q

2. 先に .drawio があるディレクトリに移動してください。移動しないとファイルが見つかりません。

   cd /d/你的项目目录          # bash / zsh
   drawio2pptx paper-defense.drawio paper-defense.pptx
   

   Set-Location "D:\你的项目目录"   # PowerShell
   drawio2pptx paper-defense.drawio paper-defense.pptx
   

3. 出力に Saved xxx.pptx (N slides) が表示されるはずです。N は <diagram> の数と一致します。ページ数が一致していても、ページが欠落していないことしか確認できず、レイアウトが正しいことは確認できません。Step 4.5 に進んでください。

Step 4.5：pptx を修正する（必須。中国語 PPT では特に省略できません）

python scripts/postprocess_pptx.py paper-defense.pptx

実行が必須である理由：drawio2pptx 0.0.7 の io/drawio_loader.py には「nowrap ヒューリスティック」があります。テキストボックス内のすべての段落に空白文字が含まれない場合、whiteSpace=wrap を wrap="none" で上書きします。中国語の文には空白がないため、中国語のみのテキストボックスはすべて折り返しなしと判定され、テキストが一行のまま無限に右へ流れ、右側の欄を突き抜けてキャンバスの外にはみ出します。

フォントサイズが小さければ一行に収まるため気づきませんが、上記の 40 pt ルールでレイアウトすると、すべて崩れてしまいます。このスクリプトは、すべてのテキストボックスの word_wrap を強制的に True に設定します。

順序に注意：render_check.py のスキャンは「折り返す」前提で行われるため、先に修正してからスキャンしてください。そうしないと、スキャン結果と実際のレンダリング結果が一致しません。

論文発表モードでは、Step 6 の発表原稿を書き終えた後、原稿付きのバージョンをもう一度実行し、原稿をノート欄に書き込みます。

python scripts/postprocess_pptx.py paper-defense.pptx --notes paper-defense-script.md

Step 5：レンダリングを検証する（必須）

python scripts/render_check.py paper-defense.pptx

スクリプトは次の 2 つを行います。

• テキストのはみ出しを計測する —— ローカルにある実際のフォントファイルを使って各行のピクセル幅を計測し、テキストボックスに必要な高さを算出して、ボックスの高さと比較します。❌ OVERFLOW があれば Step 2 に戻り、そのページのボックスの高さを変更するか、文字数を減らしてください。修正後に再実行し、⚠️ TIGHT のみ、または警告がすべてなくなるまで続けます。終了コードが 0 以外の場合は、はみ出しがあります。
• 各ページを PNG としてエクスポートする —— Windows では PowerPoint COM を使用し、それ以外のプラットフォームでは LibreOffice + pdftoppm を使用します。エクスポート後は、必ず各ページの画像を実際に確認してください。文字が枠からはみ出していないか、装飾ブロックが文字に重なっていないかを優先して確認します。どちらのエンジンも使用できない場合は、スキャン結果のみが出力されます。その場合は、ユーザーに「視覚的な検証は行っていません」と伝えてください。

フォントがインストールされていない場合、スクリプトは「計測した幅はあくまで推定値です」と表示します。その場合、スキャン結果は参考としてのみ扱い、必ず画像を確認してください。

Step 6：発表原稿を出力する（論文発表モードでは必須）

発表は口頭で行うものです。同時に paper-defense-script.md も作成してください。

## 第 N 页 · <页面标题>       ⏱ 约 XX 秒
<这一页要说的话，口语，能照着念>

• 1 分あたり 200 字で秒数を換算し、合計時間とユーザー指定の発表時間との差が ±1 分以内であることを最後に確認します。差が大きすぎる場合は Step 2 に戻り、ページ数を調整してください。
• 表紙は 15 秒、目次は 20 秒、章タイトルページは 5 秒程度とし、残りの時間を内容ページに割り当てます。
• Draw.io にはノートという概念がないため、発表原稿は独立した .md ファイルです。書き終えたら Step 4.5 に戻り、--notes を使って pptx のノート欄に書き込みます。 python scripts/postprocess_pptx.py xxx.pptx --notes xxx-script.md

エクスポートに失敗した場合のトラブルシューティング（よくあるケース）

• Permission denied / アクセス拒否：出力先の .pptx が PowerPoint で使用中です。
  • 対処方法：別のファイル名（例：*-v2.pptx）にエクスポートするか、PPT を閉じてから上書きエクスポートしてください。
• 中国語のファイル名が文字化けする／ファイルが見つからない：ターミナルの文字コードが原因で、パスの解析に問題が発生しています。
  • 対処方法：ASCII のファイル名を使って生成・エクスポートしてください（2.2 を参照）。
• pip install で SSLError が発生する／バージョンが見つからない：ネットワークの問題です。
  • 対処方法：ミラーを変更して pip install drawio2pptx -i https://pypi.tuna.tsinghua.edu.cn/simple を実行するか、PyPI から wheel を直接ダウンロードして pip install --no-deps xxx.whl を実行した後、python-pptx lxml を個別にインストールしてください（cairosvg が必要なのは、図に SVG が含まれている場合のみです）。

その他の注意事項

• フォントサイズのルール（すべてのスタイル共通）：キャンバスは 1920×1080 px で、エクスポート後は幅 20 インチになります。標準の 16:9 スライドの幅は 13.33 インチです。キャンバス上の pt 値を 1.5 で割った値が、通常の PPT での見た目のサイズになります。

  用途	キャンバス上の指定	通常の PPT に換算
  内容ページの本文／箇条書き	40 pt	27 pt
  ページ内の小見出し	48 pt	32 pt
  内容ページの上部バーのタイトル	54 pt	36 pt
  図のタイトル／表のタイトル	30 pt	20 pt
  フッター／ページ番号／日付	24 pt	16 pt

  章タイトルページの大きな数字と章名は、各 styleX の例に従ってください（数字は 120–140 pt、章名は 66–72 pt）。

  以前記載されていた「本文は一律 18 pt」は、単位の換算ミスでした。18 ÷ 1.5 = 12 pt となるため、発表会場の後方からはまったく読めません。実測に基づいて修正済みです。

• 40 pt にすると、1 ページあたりの文字数を減らす必要があります。これは推奨ではなく、必須の制約です。

  テキストボックスの幅	1 行に収まる漢字の数
  800 px（2 列）	14
  1680 px（全幅）	30

  したがって、2 列の要点は 14 字以下の短いフレーズにし、全幅の文は 30 字以下にしてください。収まらない場合は、内容を削るかレイアウトを変更してください（例：横長カード 4 枚を 2×2 のグリッドに変更）。フォントサイズを小さくして無理に詰め込まないでください。生成スクリプトでは、ファイルへの書き込み前に scripts/textmetrics.py を使って高さを計算し、収まらない場合は警告を出す必要があります。

• 推奨フォント：中国語のタイトル／本文には 微软雅黑 または 宋体 を優先して使用します。数字、英語、数式には Times New Roman を使用します。各スタイルの reference は、この方針に沿って調整できます（例：英語のタイトルには Georgia を使用）。

• XML タグを正しく閉じ、特殊文字をエスケープします（&→&、<→<）。

• 各ページのレイアウト：背景にはキャンバス全体を覆う長方形を配置し、タイトル領域の上部バーは 150 px、本文領域は y=230..990 の範囲に収め、余白を十分に確保します。

• シェルによる違い：この skill のコマンドは bash 用です。PowerShell では、cd を Set-Location に、tail -n N を Select-Object -Last N に、head -N を Select-Object -First N に置き換えてください。