powerpoint-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PowerPoint Automation

PowerPoint自动化

AI-powered PPTX generation using Orchestrator-Workers pattern.

基于Orchestrator-Workers模式的AI驱动PPTX生成工具。

When to Use

适用场景

PowerPoint, PPTX, create presentation, slides
Convert web articles/blog posts to presentations
Translate English PPTX to Japanese
Create presentations using custom templates

PowerPoint、PPTX、创建演示文稿、幻灯片
将网页文章/博客文章转换为演示文稿
将英文PPTX翻译为日语
使用自定义模板创建演示文稿

Quick Start

快速开始

From Web Article:

Create a 15-slide presentation from: https://zenn.dev/example/article

From Existing PPTX:

Translate this presentation to Japanese: input/presentation.pptx

从网页文章创建：

Create a 15-slide presentation from: https://zenn.dev/example/article

从现有PPTX创建：

Translate this presentation to Japanese: input/presentation.pptx

Workflow

工作流

TRIAGE → PLAN → PREPARE_TEMPLATE → EXTRACT → TRANSLATE → BUILD → REVIEW → DONE

Phase	Script/Agent	Description
EXTRACT	`extract_images.py`	Content → content.json
BUILD	`create_from_template.py`	Generate PPTX
REVIEW	PPTX Reviewer	Quality check

TRIAGE → PLAN → PREPARE_TEMPLATE → EXTRACT → TRANSLATE → BUILD → REVIEW → DONE

阶段	脚本/Agent	描述
EXTRACT	`extract_images.py`	内容转换为content.json
BUILD	`create_from_template.py`	生成PPTX文件
REVIEW	PPTX Reviewer	质量检查

Key Scripts

核心脚本

→ references/SCRIPTS.md for complete reference

Script	Purpose
`create_from_template.py`	Generate PPTX from content.json (main)
`reconstruct_analyzer.py`	Convert PPTX → content.json
`extract_images.py`	Extract images from PPTX/web
`validate_content.py`	Validate content.json schema
`validate_pptx.py`	Detect text overflow

→ references/SCRIPTS.md 查看完整参考文档

脚本名称	用途
`create_from_template.py`	从content.json生成PPTX（主脚本）
`reconstruct_analyzer.py`	将PPTX转换为content.json
`extract_images.py`	从PPTX/网页提取图片
`validate_content.py`	验证content.json的 schema
`validate_pptx.py`	检测文本溢出

content.json (IR)

content.json（中间格式）

All agents communicate via this intermediate format:

json

{
  "slides": [
    { "type": "title", "title": "Title", "subtitle": "Sub" },
    { "type": "content", "title": "Topic", "items": ["Point 1"] }
  ]
}

→ references/schemas/content.schema.json

所有Agent通过该中间格式进行通信：

json

{
  "slides": [
    { "type": "title", "title": "Title", "subtitle": "Sub" },
    { "type": "content", "title": "Topic", "items": ["Point 1"] }
  ]
}

→ references/schemas/content.schema.json

Templates

模板

Template	Purpose	Layouts
`assets/template.pptx`	デフォルト (Japanese, 16:9)	4 layouts

模板名称	用途	布局数量
`assets/template.pptx`	默认模板（日语，16:9）	4种布局

template レイアウト詳細

模板布局详情

Index	Name	Category	用途
0	タイトルスライド	title	プレゼン冒頭
1	タイトルとコンテンツ	content	標準コンテンツ
2	1_タイトルとコンテンツ	content	標準コンテンツ（別版）
3	セクション見出し	section	セクション区切り

使用例:

bash

python scripts/create_from_template.py assets/template.pptx content.json output.pptx --config assets/template_layouts.json

索引	名称	分类	用途
0	标题幻灯片	title	演示文稿开头
1	标题与内容	content	标准内容展示
2	标题与内容（替代版）	content	标准内容展示（替代版）
3	章节标题	section	章节分隔

使用示例:

bash

python scripts/create_from_template.py assets/template.pptx content.json output.pptx --config assets/template_layouts.json

テンプレート管理のベストプラクティス

模板管理最佳实践

複数デザイン（スライドマスター）の整理

多设计（幻灯片母版）整理

テンプレートPPTXに複数のスライドマスターが含まれている場合、出力が不安定になることがあります。

確認方法:

bash

python scripts/create_from_template.py assets/template.pptx --list-layouts

対処法:

PowerPointでテンプレートを開く
[表示] → [スライドマスター] を選択
不要なスライドマスターを削除
保存後、
```
template_layouts.json
```
を再生成

bash

python scripts/analyze_template.py assets/template.pptx

如果模板PPTX中包含多个幻灯片母版，可能会导致输出不稳定。

检查方法:

bash

python scripts/create_from_template.py assets/template.pptx --list-layouts

解决方法:

用PowerPoint打开模板文件
选择[视图] → [幻灯片母版]
删除不需要的幻灯片母版
保存后，重新生成template_layouts.json

bash

python scripts/analyze_template.py assets/template.pptx

content.json の階層構造

content.json的层级结构

箇条書きに階層構造（インデント）を持たせる場合は

items

ではなく

bullets

形式を使用：

json

// ❌ フラットな表示になる
{"type": "content", "items": ["項目1", "  詳細1", "項目2"]}

// ✅ 階層構造が効く
{"type": "content", "bullets": [
  {"text": "項目1", "level": 0},
  {"text": "詳細1", "level": 1},
  {"text": "項目2", "level": 0}
]}

如果要让项目符号带有层级结构（缩进），请使用

bullets

格式而非

items

：

json

// ❌ 会显示为扁平结构
{"type": "content", "items": ["项目1", "  详情1", "项目2"]}

// ✅ 层级结构生效
{"type": "content", "bullets": [
  {"text": "项目1", "level": 0},
  {"text": "详情1", "level": 1},
  {"text": "项目2", "level": 0}
]}

テンプレート管理のベストプラクティス

模板管理最佳实践

複数デザイン（スライドマスター）の整理

多设计（幻灯片母版）整理

テンプレートPPTXに複数のスライドマスターが含まれている場合、出力が不安定になることがあります。

確認方法:

bash

python scripts/create_from_template.py assets/template.pptx --list-layouts

対処法:

PowerPointでテンプレートを開く
[表示] → [スライドマスター] を選択
不要なスライドマスターを削除
保存後、template_layouts.json を再生成

bash

python scripts/analyze_template.py assets/template.pptx

如果模板PPTX中包含多个幻灯片母版，可能会导致输出不稳定。

检查方法:

bash

python scripts/create_from_template.py assets/template.pptx --list-layouts

解决方法:

用PowerPoint打开模板文件
选择[视图] → [幻灯片母版]
删除不需要的幻灯片母版
保存后，重新生成template_layouts.json

bash

python scripts/analyze_template.py assets/template.pptx

content.json の階層構造

content.json的层级结构

箇条書きに階層構造（インデント）を持たせる場合は items ではなく bullets 形式を使用：

json

// ❌ フラットな表示になる
{"type": "content", "items": ["項目1", "  詳細1", "項目2"]}

// ✅ 階層構造が効く
{"type": "content", "bullets": [
  {"text": "項目1", "level": 0},
  {"text": "詳細1", "level": 1},
  {"text": "項目2", "level": 0}
]}

如果要让项目符号带有层级结构（缩进），请使用bullets格式而非items：

json

// ❌ 会显示为扁平结构
{"type": "content", "items": ["项目1", "  详情1", "项目2"]}

// ✅ 层级结构生效
{"type": "content", "bullets": [
  {"text": "项目1", "level": 0},
  {"text": "详情1", "level": 1},
  {"text": "项目2", "level": 0}
]}

Agents

→ references/agents/ for definitions

Agent	Purpose
Orchestrator	Pipeline coordination
Localizer	Translation (EN ↔ JA)
PPTX Reviewer	Final quality check

→ references/agents/ 查看定义

Agent	用途
Orchestrator	流水线协调
Localizer	翻译（英 ↔ 日）
PPTX Reviewer	最终质量检查

Design Principles

设计原则

SSOT: content.json is canonical
SRP: Each agent/script has one purpose
Fail Fast: Max 3 retries per phase
Human in Loop: User confirms at PLAN phase

SSOT: content.json为唯一权威来源
SRP: 每个Agent/脚本仅负责一项功能
快速失败: 每个阶段最多重试3次
人工介入: 在PLAN阶段需要用户确认

URL Format in Slides

幻灯片中的URL格式

Reference URLs must use "Title - URL" format for APPENDIX slides:

VPN Gateway の新機能 - https://learn.microsoft.com/ja-jp/azure/vpn-gateway/whats-new

→ references/content-guidelines.md for details

附录幻灯片中的参考URL必须使用**“标题 - URL”**格式：

VPN Gateway の新機能 - https://learn.microsoft.com/ja-jp/azure/vpn-gateway/whats-new

→ references/content-guidelines.md 查看详情

References

参考文档

File	Content
SCRIPTS.md	Script documentation
USE_CASES.md	Workflow examples
content-guidelines.md	URL format, bullets
agents/	Agent definitions
schemas/	JSON schemas

文件路径	内容
SCRIPTS.md	脚本文档
USE_CASES.md	工作流示例
content-guidelines.md	URL格式、项目符号规范
agents/	Agent定义
schemas/	JSON schema

Technical Content Addition (Azure/MS Topics)

技术内容添加（Azure/MS主题）

When adding Azure/Microsoft technical content to slides, follow the same verification workflow as QA:

当在幻灯片中添加Azure/Microsoft相关技术内容时，请遵循与QA相同的验证流程：

Workflow

工作流

[Content Request] → [Researcher] → [Reviewer] → [PPTX Update]
                         ↓              ↓
                   Docs MCP 検索    内容検証

[内容请求] → [研究员] → [审核员] → [PPTX更新]
                         ↓              ↓
                   搜索MCP文档    内容验证

Required Steps

必要步骤

Research Phase: Use
```
microsoft_docs_search
```
/
```
microsoft_docs_fetch
```
to gather official information
Review Phase: Verify the accuracy of content before adding to slides
Build Phase: Update content.json and regenerate PPTX

研究阶段: 使用

microsoft_docs_search

microsoft_docs_fetch

收集官方信息

审核阶段: 在添加到幻灯片前验证内容的准确性
构建阶段: 更新content.json并重新生成PPTX

Forbidden

禁止操作

❌ Adding technical content without MCP verification
❌ Skipping review for "simple additions"
❌ Generating PPTX while PowerPoint has the file open

❌ 未经过MCP验证就添加技术内容
❌ 因“简单添加”而跳过审核步骤
❌ 在PowerPoint打开文件的情况下生成PPTX

File Lock Prevention

文件锁定预防

Before generating PPTX, check if the file is locked:

powershell

undefined

生成PPTX前，请检查文件是否被锁定：

powershell

undefined

Check if file is locked

$path = "path/to/file.pptx" try { [IO.File]::OpenWrite($path).Close(); "File is writable" } catch { "File is LOCKED - close PowerPoint first" }

undefined

$path = "path/to/file.pptx" try { [IO.File]::OpenWrite($path).Close(); "File is writable" } catch { "File is LOCKED - close PowerPoint first" }

undefined

Post-Processing (URL Linkification)

后期处理（URL链接化）

⚠️
create_from_template.py
does not process
footer_url
. Post-processing required.

⚠️
create_from_template.py
不处理
footer_url
，需要进行后期处理。

Items Requiring Post-Processing

需要后期处理的项

Item	Processing
`footer_url`	Add linked textbox at slide bottom
URLs in bullets	Convert to hyperlinks
Reference URLs	Linkify URLs in Appendix

项	处理方式
`footer_url`	在幻灯片底部添加带链接的文本框
项目符号中的URL	转换为超链接
参考URL	为附录中的URL添加链接

Save with Different Name (File Lock Workaround)

另存为不同名称（文件锁定解决方法）

PowerPoint locks open files. Always save with a different name:

python

undefined

PowerPoint会锁定打开的文件，请始终另存为不同名称：

python

undefined

❌ Fails if file is open

❌ 如果文件已打开会失败

prs.save('file.pptx') # PermissionError

✅ Save with different name

✅ 另存为不同名称

prs.save('file_withURL.pptx')


| Processing    | Suffix     |
| ------------- | ---------- |
| URL added     | `_withURL` |
| Final version | `_final`   |
| Fixed version | `_fixed`   |

prs.save('file_withURL.pptx')


| 处理类型    | 后缀     |
| ------------- | ---------- |
| 添加URL后     | `_withURL` |
| 最终版本     | `_final`   |
| 修复版本     | `_fixed`   |

Done Criteria

完成标准

```
content.json
```
generated and validated
PPTX file created successfully
No text overflow detected
User confirmed output quality

已生成并验证
```
content.json
```
成功创建PPTX文件
未检测到文本溢出
用户已确认输出质量