pptx-skill

April 12, 2026 · View on GitHub

这个项目是做什么的

这是一个 AI-first 的 pptx 操作工具,目标是让人和 AI 共享同一套 Python library 和 CLI,可靠地读、改、渲染 pptx 文件,并贯彻 aggressive transparency 原则 —— 每一步操作都明确、可审计、可重复。

Phase 1 的最小可用能力:

  • 读 deck 结构(list slides / shapes / runs / notes)
  • 导出结构化 dump(JSON / Markdown)
  • 修改文字 / 颜色 / 位置(最常用的简单编辑操作)
  • 用 LibreOffice headless 渲染 slide 成 PNG(多模态 review)
  • 字体度量 heuristic 检查 overflow(不依赖渲染)
  • 字体归一化(Calibri → Inter 等跨平台字体)

这个项目不是:PowerPoint 前端 / 一键 markdown 转 deck 生成器 / 通用 Office 自动化框架。

工作环境

优先通过项目根目录的 .venv 运行。Python 依赖用 uv 管理:

cd pptx_skill
uv venv .venv
.venv/bin/python -m pip install -e '.[dev]'

常用命令:

.venv/bin/python -m pptx_skill.cli --help
.venv/bin/python -m pptx_skill.cli doctor
.venv/bin/python -m pptx_skill.cli list-slides deck.pptx
.venv/bin/python -m pptx_skill.cli dump-slide deck.pptx 3 --format json
.venv/bin/python -m pptx_skill.cli render-slide deck.pptx 3 --out /tmp/slide3.png

或通过 scripts entrypoint:

scripts/pptx-skill --help

代码边界

src/pptx_skill/ 是唯一真实逻辑层。所有操作 —— 读、写、渲染、度量、序列化 —— 都放在包里。CLI 只做 argparse 和 library 调用之间的胶水,不写业务逻辑。这一条的例外是参数默认值处理,但只要变成实际的 pptx 操作,一定回到 library。

Aggressive transparency 的实施细节

每一个修改操作都遵循三个 invariant:

  1. Before state 可见: 任何 write 命令在改之前先打印 (to stderr) 它即将修改的目标的当前值。例如 set-text 先打印 before: "Old title",再改,然后打印 after: "New title"
  2. 错误透传: 不要包装底层错误。python-pptx 的 KeyError、libreoffice 的 stderr、XML 解析的 Exception,全部保留原始 traceback 或 stderr 信息
  3. 操作日志: 每次写操作在 stderr 打印一行 [pptx-skill] <op> <target> <summary>,便于 shell 管道里 tee 留痕

安全

不会访问网络、不会调用外部 API、不会读 secret。如果未来加了功能需要调用外部服务,secret 走 op read op://dev/... 模式,不硬编码。

测试与文档维护

修改 library 或 CLI 后至少运行默认 pytest:

.venv/bin/python -m pytest

涉及渲染的测试打了 @pytest.mark.libreoffice marker,默认 skip。跑渲染测试需要 LibreOffice 装好:

.venv/bin/python -m pytest -m libreoffice

重要改动同步更新 docs/working.md,特别记录:

  • CLI contract 变化
  • LibreOffice 的真实坑(版本差异、字体 fallback、render 超时等)
  • python-pptx 边界问题(哪些操作 API 覆盖、哪些要走 raw_xml_patch)
  • 字体度量 heuristic 的准确率观察

永远不要做的事

  1. 不要让 CLI "做用户没明确说的事"。比如 set-text 只改目标 shape,不自动 re-layout 其他 shape
  2. 不要 silently 修改 deck。任何写操作都 in-place 保存,但保存前在 stderr 宣告
  3. 不要用 format/layout autofix 策略。AI 和人都应该能 predict 每一个命令的确切结果
  4. 不要在 CLI 里 try/except 吞掉底层错误把它变成 "oops something went wrong"