PowerPoint 默认启用

.pptx 创建、编辑、分析 — 从单页幻灯片修复到包含变体过渡和数据驱动生成的完整投资者演示文稿。

触发关键词

快速参考

"~해줘" 示例

激活此技能的自然语言请求。支持韩语、英语或混合使用。

主要工具：OfficeCLI

officecli 可处理约 80% 的 PPTX 任务：幻灯片的添加/设置/删除、验证、查询和视觉检查。它是主要接口 — 在升级到其他工具之前，请始终先尝试 OfficeCLI。

发现规则

officecli --help
officecli help pptx
officecli help pptx add slide --json       # exact property list
officecli help pptx add shape --json
officecli help pptx set slide --json
officecli help pptx set shape --json
officecli view --help                      # all view modes
officecli help pptx query

核心工作流

读取与分析

# Text extraction
officecli view slides.pptx text
officecli view slides.pptx text --start 1 --end 5

# Structural views
officecli view slides.pptx outline
officecli view slides.pptx annotated
officecli view slides.pptx stats

元素检查（PATH 语法）

路径从 1 开始：/slide[1]、/shape[1]。在 zsh 中始终用引号包裹路径，以防止通配符展开。

officecli get slides.pptx '/slide[1]' --depth 1
officecli get slides.pptx '/slide[1]/shape[1]'
officecli get slides.pptx '/slide[1]/chart[1]'
officecli get slides.pptx '/slide[1]/table[1]' --depth 3

类 CSS 查询

officecli query slides.pptx 'shape:contains("Revenue")'
officecli query slides.pptx "picture:no-alt"
officecli query slides.pptx 'shape[fill=#4472C4]'
officecli query slides.pptx "shape[width>=10cm]"

视觉检查

officecli view slides.pptx html --browser    # recommended
officecli view slides.pptx svg --start 1 --end 1 --browser

常驻模式

常驻模式将文件作为后台守护进程保持打开状态，以加快连续编辑速度。open 命令会立即返回 — 不要将其作为后台 shell 作业运行。

officecli open slides.pptx      # returns IMMEDIATELY; daemon in bg
officecli add slides.pptx ...
officecli set slides.pptx ...
officecli close slides.pptx     # always close explicitly

批处理模式

使用 JSON 在单次调用中执行多个操作。使用带单引号分隔符的 heredoc 来防止 shell 语法泄漏到 JSON 中。

cat <<'EOF' | officecli batch slides.pptx
[
  {"command":"add","parent":"/slide[1]","type":"shape","props":{"text":"Title","x":"2cm","y":"2cm","width":"20cm","height":"3cm","size":"36","bold":"true"}},
  {"command":"add","parent":"/slide[1]","type":"shape","props":{"text":"Body","x":"2cm","y":"6cm","width":"20cm","height":"10cm","size":"16"}}
]
EOF

批处理支持：add、set、get、query、remove、move、swap、view、raw、raw-set、validate。

基于参考的编辑

当用户提供源文件或说"按照 X.pptx 的格式" — 始终从源文件开始。绝不从头重建主题。

为什么这很重要

幻灯片母版和主题定义（字体、颜色、占位符几何形状）是文档特有的。从头重建会丢失幻灯片间一致的品牌形象，破坏现有占位符位置，并且耗时是修改副本的 5-10 倍。

工作流

1. 复制源文件： cp source.pptx target.pptx — 继承主题、幻灯片母版、布局、字体、颜色
2. 打开： officecli open target.pptx — 守护进程立即返回
3. 删除幻灯片内容，但保留 /slideMaster、/slideLayout、/theme
4. 添加新幻灯片，使用现有布局（--prop layout=Title+Content）— 它们会自动继承主题

模板来源（优先级顺序）

示例 — 继承现有品牌

# CORRECT: inherit theme and layouts
cp CompanyBrand.pptx Q4Report.pptx
officecli open Q4Report.pptx
officecli remove Q4Report.pptx "/slide[1]"
officecli add Q4Report.pptx / --type slide --prop layout=Title
officecli add Q4Report.pptx '/slide[1]' --type textbox \
  --prop text="Q4 Report" --prop placeholder=title
officecli close Q4Report.pptx

# WRONG: recreate theme (loses brand)
officecli create Q4Report.pptx
# ... add all fonts, colors, masters from scratch ...

创建工作流

# 1. Work in /tmp/ with ASCII filenames (Korean filenames cause resident corruption)
officecli create /tmp/deck_work.pptx --type pptx

# 2. Add slide, set background, add shapes/textboxes/charts
officecli add /tmp/deck_work.pptx /slide --type slide
officecli set /tmp/deck_work.pptx '/slide[1]' --prop background=1E2761
officecli add /tmp/deck_work.pptx '/slide[1]' --type textbox \
  --prop 'text=Title Here' --prop x=2cm --prop y=3cm --prop w=30cm --prop h=4cm \
  --prop fontsize=44 --prop bold=true --prop color=FFFFFF --prop fontFamily=Pretendard

# 3. Explicitly close resident after edits
officecli close /tmp/deck_work.pptx

# 4. Copy to final filename (Korean OK for final output)
python3 -c "import shutil; shutil.copy2('/tmp/deck_work.pptx', 'final.pptx')"

升级梯度

当 OfficeCLI 无法完成任务时，按顺序升级。大多数任务停留在 L1。

升级信号

• officecli 显示 "silently ignored" 或不支持的属性 → L2
• 需要超出高级接口能力的变体/自定义过渡 → L4
• 从数据批量生成（50+ 页幻灯片）→ L5 (pptxgenjs)
• 用于清理/重组的解包工作流 → L3 (pptx_cli.py clean)
• 设计选择（颜色、字体、样式）→ 先阅读 references/design-system.md + morph-ppt/reference/styles/INDEX.md

元素类型与命令

OfficeCLI 支持丰富的元素类型。请积极使用 — 纯文本幻灯片毫无记忆点。

形状作为内容容器

officecli add deck.pptx '/slide[1]' --type shape --prop geometry=roundRect \
  --prop fill=1E2761 --prop x=1cm --prop y=4cm --prop w=15cm --prop h=12cm

表格

officecli add deck.pptx '/slide[2]' --type table \
  --prop rows=4 --prop cols=3 --prop x=1cm --prop y=3cm \
  --prop width=24cm --prop height=6cm

图表

officecli add deck.pptx '/slide[3]' --type chart \
  --prop chartType=column --prop title='Revenue' \
  --prop 'data=Q1:12,Q2:15,Q3:18,Q4:20'

图片

officecli add deck.pptx '/slide[1]' --type picture \
  --prop path=photo.png --prop x=14cm --prop y=3cm \
  --prop width=8cm --prop height=5cm --prop alt='Team photo'

视频/音频

officecli add deck.pptx '/slide[4]' --type video --prop path=demo.mp4 \
  --prop x=2cm --prop y=3cm --prop width=20cm --prop height=12cm --prop autoplay=true

OLE 嵌入（Excel、Word、PDF）

officecli add deck.pptx '/slide[5]' --type ole --prop path=data.xlsx \
  --prop x=2cm --prop y=3cm --prop width=20cm --prop height=12cm

连接线/箭头

officecli add deck.pptx '/slide[2]' --type connector \
  --prop startShape=1 --prop endShape=2 --prop lineColor=4472C4 --prop tailEnd=arrow

演讲者备注

officecli add deck.pptx '/slide[1]' --type notes --prop 'text=Key talking point here.'

动画

officecli set deck.pptx '/slide[1]/shape[2]' --prop animation=fadeIn --prop delay=500

主题颜色

# Use theme tokens instead of hex for theme-aware decks
officecli set deck.pptx '/slide[1]/shape[1]' --prop fill=accent1
# Available: accent1..accent6, dk1, dk2, lt1, lt2, tx1, tx2, bg1, bg2

其他操作

# Hyperlinks
officecli set deck.pptx '/slide[1]/shape[2]' --prop link='https://example.com'

# Flip / rotate
officecli set deck.pptx '/slide[1]/shape[2]' --prop flipH=true
officecli set deck.pptx '/slide[1]/shape[2]' --prop rotation=45

# Slide master / layout editing
officecli set deck.pptx '/slideMaster[1]/shape[2]' --prop text='Company Name'
officecli set deck.pptx '/slideLayout[2]/shape[1]' --prop fill=1E2761

# Template merge with data
officecli merge template.pptx output.pptx --data '{"title":"Q4 Report","revenue":"$5.1M"}'

# Watch mode (live preview)
officecli watch deck.pptx --port 3000

# Slideshow settings
officecli set deck.pptx / --prop show.loop=true --prop show.narration=false

设计系统

设计旋钮

创建之前，先确定以下三个参数。如有歧义，请向用户确认。

按演示文稿类型的预设

推荐调色板

选择与主题匹配的颜色 — 不要默认使用通用蓝色。

在浅色背景上使用文本色作为正文，次要文本色用于说明文字、标签和坐标轴文本。在深色背景（亮度 < 30%）上，所有正文文本必须为白色（FFFFFF）或近白色。非纯黑：使用 0A0A0A 而非 000000。

排版

韩语：Pretendard、Noto Sans KR、Wanted Sans。避免将 Malgun Gothic 作为唯一字体 — 仅可作为 a:ea 字体栈中的 CJK 回退字体。

幻灯片节奏

一个 10 页的演示文稿应至少包含 4 种不同的布局类型：

1. 全出血主视觉 — 标题或关键指标
2. 分栏布局 — 文本 + 视觉元素
3. 网格或对比 — 2–3 项内容
4. 数据可视化 — 图表、图解或信息图

内容到布局指南

子技能

仅加载与您任务匹配的子技能。不要全部加载。

参考资料

设计参考

Python 脚本（scripts/）

QA（必需）

步骤 1 — 机器 QA

officecli validate output.pptx
officecli view output.pptx issues
officecli view output.pptx text | grep -iE 'xxxx|lorem|ipsum|placeholder|TODO|click to'
officecli view output.pptx stats

步骤 2 — 视觉 QA

officecli view output.pptx html --browser

# Thumbnail grid for quick scan
python3 scripts/thumbnail.py output.pptx grid.png

使用子代理进行视觉检查 — 即使只有 2–3 页幻灯片。你会看到你期望的内容，而非实际的内容。新鲜的眼光能发现更多问题。

视觉 QA 检查清单

• 元素重叠（文本穿过形状、元素堆叠）
• 文本溢出或在文本框边界处被截断
• 元素间距过小（间隙 < 0.3 英寸）或几乎接触
• 间距不均匀（大面积空白 vs 拥挤区域）
• 距幻灯片边缘留白不足（< 0.5 英寸）
• 列或相似元素未对齐
• 低对比度的文本或图标
• 残留的占位符内容
• 文本框过窄导致过度换行

步骤 3 — 修复并重新验证

使用 officecli set 修复，重新运行 QA。在至少完成一轮修复-验证循环之前，不要宣布成功。

交付前检查清单

• 所有内容幻灯片都有演讲者备注
• 至少应用了一种过渡样式
• 所有图片都有替代文本：officecli query deck.pptx 'picture:no-alt'
• 布局多样性 ≥ 3 种类型
• 无溢出：y + height ≤ 19.05cm，x + width ≤ 33.87cm
• 无残留占位符文本
• 正文文本 ≥ 16pt
• 图表标题包含实际数值（无 TBD、空括号）

常见陷阱

反模式

• 绝不使用子技能文件中的示例数据（FitPulse、LearnFlow 等）
• 绝不留下占位符文本：lorem、ipsum、XXXX、TODO
• 每页幻灯片必须有标题（无障碍要求）
• 所有内容幻灯片都需要演讲者备注
• 每个演示文稿最多 2 种字体族
• Malgun Gothic 作为唯一字体 = 被拒绝
• view issues 中空白布局显示 "(untitled)" 是正常的，不是缺陷
• 标题下方的强调线 — AI 生成幻灯片的典型特征；应使用留白替代
• 装饰性网页 UI 元素（细侧边线、装饰性圆圈）— PPT 是投影介质，不是 Web 应用
• 每页使用相同布局 — 应变换列、卡片、标注
• 正文居中对齐 — 段落应左对齐；仅标题居中
• 尺寸对比不足 — 标题 36pt+ vs 正文 16pt
• 纯文本幻灯片 — 应添加形状、图表、色块、图片

无障碍（WCAG 2.1 AA）

• 每页幻灯片都有标题：officecli view deck.pptx outline
• 图片有替代文本：officecli query deck.pptx 'picture:no-alt'
• 阅读顺序 = 形状顺序（标题优先）
• 对比度 ≥ 4.5:1（正常文本），≥ 3:1（大号文本）
• 信息不仅通过颜色传达

CJK/韩语支持

cli-jaw 分支会自动检测韩语内容并应用语言标签和默认字体。在常驻模式编辑期间使用 ASCII 文件名以避免 UTF-8 损坏；最后一步再复制为韩语文件名。

前置条件

# Check prerequisites
python3 -c "import pptx" || echo "MISSING: pip install python-pptx"
which officecli >/dev/null 2>&1 || echo "INFO: OfficeCLI not installed"
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed (optional)"