SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsopen-pptd

open-pptd

Office & productivity

View repository

Updated 10-19 16:42

About this skill

open-pptd: Native Declarative Presentation Engine

open-pptd is an open-source presentation toolchain built around the PPTD (Declarative Presentation Language) specification and the high-performance pptd native Rust compiler. It provides AI coding agents with a clean, modular YAML abstraction over OOXML and produces real, fully editable .pptx presentations offline in milliseconds.

⚡ Agent Quickstart (fast closed loop and failure handling)

Path notes: In the following, <SKILL_DIR> refers to the installation directory of this Skill (usually ~/.agents/skills/open-pptdfor global installs, or skills/open-pptd）。

After receiving any PPT creation or modification task, the Agent must follow this closed-loop command chain:

# 1. 安装与就绪检查 (已安装即刻返回)
python3 <SKILL_DIR>/scripts/install_binary.py
# ➔ 若网络受限导致下载失败：脚本会自动回退至 cargo 源码编译；若仍失败，请根据终端提示手动下载放置
# ➔ 若提示 command not found，执行 export PATH="$HOME/.local/bin:$PATH"
2. Strict semantic and structural validation

pptd check <project_dir>/deck.pptd

➔ If check reports an error: use the error messages to investigate spelling errors, illegal shapeName, undefined $color, or missing image paths one by one 3. Ultra-fast compilation to native PPTX

pptd build <project_dir>/deck.pptd -o <output.pptx> [--force]

➔ If it exits with an error due to the .sync.hash overwrite guard (exit code 2): output.pptx has been modified externally. If you confirm you want to overwrite it with the PPTD source, append the --force flag: pptd build <project_dir>/deck.pptd -o <output.pptx> --force 4. Comprehensive validation and quality inspection of the finished product

python3 <SKILL_DIR>/scripts/validate_pptx.py <output.pptx> --expected-pages --check-notes

➔ If it reports leaked HTML tag: check whether the source contains unconverted // tags, and replace them with plain text paragraphs and numbering 5. Render preview and visual layout review (visual quality inspection)

python3 <SKILL_DIR>/scripts/validate_pptx.py <output.pptx> --render-images

➔ Export per-page slide-NN.png and an overview contact-sheet.jpg, making it easy to check whether connections pass through text, whether labels go out of bounds, and whether whitespace is balanced 
---

## 📚 Agent 必读顺序 (Document Reading Order)

在动手编写 PPTD 代码前，建议严格按照以下顺序查阅相关规范：
1. **场景判断**：阅读 `reference/slides_categories.md`，判断文稿归属的业务场景（咨询/汇报/学术/技术等）与核心叙事目标。
2. **版式与密度红线**：根据场景阅读 `reference/slides_categories/<scenario>.md`，掌握信息密度、禁止项与推荐版式结构。
3. **预设主题选择**：查阅本 Skill 目录下的 `theme.md`（英文参见 `theme_EN.md`），直接点名或参考其中 30 余种精美的主题调色盘与版式规范。
4. **跨平台字体回退**：查阅 `reference/fonts.md`，了解 Windows / macOS / Linux 字体映射机制，避免字体缺失导致错乱。
5. **语法与能力边界**：查阅下文的【功能支持矩阵】以及 `reference/pptd.md`（注意：仅使用编译器已支持的能力）。

---

## 📋 功能支持矩阵 (Supported Feature Matrix)

在生成 PPTD 时，**严格遵守以下能力边界**。不支持的标签和元素会在 `check` 和 `build` 时被拦截报错，切勿猜测或硬套 Web HTML 语法：

| 功能类别 | 支持状态 | 规范与说明 / 替代指引 |
|---|---|---|
| **文本与排版** | ✅ 完全支持 | `fontSize`, `color`, `bold`, `italic`, `lineHeight`, `lineHeightPx`, `align` (支持 `[水平, 垂直]`), `letterSpacing` (编译为 `spc`), `textDirection` (编译为 `vert`), `marginTop`, `marginLeft`, `marginRight`, `marginBottom`, `wrap`, `autofit` |
| **富文本标签** | ✅ 完全支持 | `<p>`, `<span>`, `<b>`/`<strong>`, `<i>`/`<em>`, `<u>` (下划线), `<s>`/`<del>`/`<strike>` (删除线), `<code>` (等宽), `<latex>` / `\( ... \)` (原生 OOXML 公式，生成真实可编辑分数线、根号、大运算符、矩阵与多行方程数组 `<m:eqArr>`（`\begin{align}`/`aligned`/`gather`/`split`）；支持公式内宏定义 `\newcommand`/`\def`；整段独占自动居中，混合段落内联显示；不支持命令硬报错拦截) |
| **非支持标签** | ❌ **严禁使用** | `<ul>`, `<ol>`, `<li>`, `<a>`, `<sup>`, `<sub>` **不受支持**！编译器与校验器会**直接拦截报错**。列表必须写成常规段落并手写序号（如 `1. 第一点` 或 `• 第一点`）；上标下标使用原生 LaTeX 数学公式（如 `<latex>x^2</latex>`、`\( x_i \)`） |
| **演讲者备注 (Notes)** | ✅ 完全支持 | 页面根级属性 `notes: "备注内容..."`，自动生成原生 PowerPoint 演讲者备注 (`notesSlide`) |
| **图表 / Charts** | ❌ **编译器尚未支持** | `elementType: chart` 会在 `check` 和 `build` 时被**直接报错拦截**。替代方案：使用原生表格 (`elementType: table`) 呈现数据，或使用脚本将图表导出为图片 (`elementType: image`) |
| **动画效果** | 🟡 **仅解析不报错** | 编译器支持 `animations` 节点语法解析，但当前版本生成的 OOXML 暂缓写入时序动画，文稿以纯静态排版完整呈现 |
| **矢量形状 / Shapes** | ✅ 完全支持 | `rect`, `roundRect`, `ellipse`, `triangle`, `diamond`, `rightArrow`, `pentagon`, `hexagon`, `callout` 等 DrawingML 预设形状（支持纯色与渐变填充；⚠️ 形状不支持图片填充 `fill.type: image`，仅背景支持） |
| **线条与箭头** | ✅ 完全支持 | `elementType: line`，支持相对坐标 `points: "0,0 dx,dy"`，以及两端箭头 `arrow: [start, end]` (可选: `triangle`, `stealth`, `arrow`, `diamond`, `oval`, `none`) |
| **表格 / Tables** | ✅ 完全支持 | 原生 PowerPoint 表格 (`<a:tbl>`)，支持 `columnWidths`、`rowHeights`、单元格跨行跨列、边框样式、底色填充 |
| **图片与媒体** | ✅ 完全支持 | 统一存放在 `assets/` 目录；支持透明通道、裁切 `crop`、填充模式 `fit: {mode: cover/contain}`、边框与阴影 |
| **主题色彩与继承** | ✅ 完全支持 | `theme.colors` 统一声明命名色，元素中通过 `"$colorKey"` 引用；引用未定义颜色会在 `check` 阶段拦截 |
| **静态质检与校验** | ✅ 严格校验 | `pptd check` 自动拦截拼写错误、非法形状名、无效色彩引用、缺失的媒体文件以及潜在文字溢出 |

---

## 🔒 `.sync.hash` 机制与双向同步注意

`pptd` 在项目根目录使用旁车文件 `.sync.hash` 记录项目合法写入时各文件的 SHA-256 哈希：

1. **防覆盖守卫 (Overwrite Guard)**：
   - 执行 `pptd build deck.pptd -o presentation.pptx` 时，若输出文件 `presentation.pptx` 已存在，编译器会比对当前文件的实时哈希与 `.sync.hash` 的记录。
   - **若文件被外部程序或人类手工编辑过**，编译器会**拒绝覆写**（退出码 2，提示 `changed after its last recorded sync point`），防止破坏未知修改。
   - **如何解决**：若确认需要以 PPTD 源码强制覆盖，在命令中追加 `--force`（或 `-f`）参数即可：`pptd build deck.pptd -o presentation.pptx --force`
2. **跳过未变更的 Convert**：
   - 执行 `pptd convert presentation.pptx output_dir/` 时，若源 PPTX 的 SHA-256 与上次记录一致，编译器将自动输出 `unchanged → skipped convert` 并跳过，保护本地已有的 PPTD 源码不被重复覆写。

---

## 交付规范 (Deliverables Contract)

除非用户明确声明不需要，每个 PPT 制作或修改任务必须交付：
1. **可编辑的 PPTD 源码工程**：包含 `deck.pptd` 清单文件、`pages/*.page` 页面描述、以及 `assets/` 资源目录。
2. **编译出的原生 `.pptx` 成品**：通过 `pptd build` 生成。
3. **质检通过报告**：通过 `validate_pptx.py` 验证无遗漏标签和结构异常。

---

## PPTD 工程目录结构

```text
my_presentation/
├── deck.pptd            # 演示文稿清单：画幅比例、主题色、全局文本样式、页面清单
├── pages/
│   ├── 01_cover.page    # 单页声明式 AST (YAML 格式)
│   ├── 02_intro.page
│   └── ...
└── assets/              # 本地引用的图片/多媒体文件 (统一命名为 assets/，禁止使用 media/)

1. Manifest file (deck.pptd) example

version: v2
title: "Emby 家庭影音库搭建与调优"
size: [960, 540]         # 16:9 标准画布尺寸 (像素坐标体系)
theme:
  colors:
    ink: "#1A1A1A"
    paper: "#F7F5EE"
    primary: "#2563EB"
    accent: "#52B788"
  textStyles:
    title:
      fontFamily: "思源宋体"
      fontSize: 28
      bold: true
      color: "$ink"
    body:
      fontFamily: "思源黑体"
      fontSize: 15
      lineHeight: 1.45
      color: "$ink"
pages:
  - pages/01_cover.page
  - pages/02_intro.page

2. Single-page file (pages/01_cover.page) example

pageType: cover
background: { type: solid, color: "$paper" }
notes: |
  各位好，今天为大家分享家庭影音库的搭建方案，核心关注网络直连与硬件转码。
elements:
  - elementId: heading
    elementType: text
    bounds: [60, 120, 840, 80]
    content:
      style: "$title"
      text: "Emby 家庭影音库搭建与调优"
  - elementId: sep-line
    elementType: line
    bounds: [60, 210, 180, 2]
    points: "0,0 180,0"
    arrow: [null, "triangle"]
    border: { style: solid, width: 2, color: "$primary" }

Common toolchain commands

1. Install / ensure the compiler is ready

python3 <SKILL_DIR>/scripts/install_binary.py
# 如需强制重新下载: python3 <SKILL_DIR>/scripts/install_binary.py --force

2. Strict semantic check (Check)

pptd check deck.pptd

3. Compile the project to PPTX (Build)

# 推荐直接使用 pptd:
pptd build deck.pptd -o output.pptx

# 或通过 Python 包装脚本:
python3 <SKILL_DIR>/scripts/export_pptx.py deck.pptd -o output.pptx [--pdf]

4. Reverse-decompile PPTX to a PPTD project (Convert)

Note:pptd convert takes two positional arguments,do not add the -o parameter：

# 原生命令格式: pptd convert <INPUT.pptx> <OUTPUT_DIR>
pptd convert input.pptx my_project_dir/

# 或通过 Python 包装脚本:
python3 <SKILL_DIR>/scripts/convert_pptx.py input.pptx -o my_project_dir/

5. Comprehensive validation and visual quality inspection of the finished product (Validate)

python3 <SKILL_DIR>/scripts/validate_pptx.py output.pptx --expected-pages 8 --check-notes

Layout and design best practices

  1. Fonts and cross-platform fallback：
    • Rigorous/academic/publishing style: the main title uses 思源宋体 (automatically mapped to Western Georgia / East Asian SimSun)。
    • Business/modern tech style: use PingFang SC / Microsoft YaHei (automatically mapped to Western Arial)。
  2. Connectors and arrows (Line & Arrow)：
    • Lines are defined using relative coordinates points: "0,0 dx,dy", the start point is usually 0,0。
    • Arrows use a two-element array arrow: [startArrow, endArrow], for example arrow: [null, "triangle"] or arrow: ["stealth", null]。
  3. Tables (Table)：
    • You must provide columnWidths (the relative proportion of each column; the sum must be 1.0) and rowHeights。
    • Text within cells uses text: "内容", supporting multi-line text and background colors.
  4. Multimedia and images (Assets)：
    • All images should be placed in the project's assets/ folder; they must not be scattered directly in the root directory.
    • It is strictly forbidden to write image paths as absolute paths in page files; always write them as paths relative to the project root directory (e.g., assets/banner.png）。

💻 Runtime environment and dependency declaration

  1. Python environment requirements：
    • Python ≥ 3.9。
    • Core building has no hard dependency on external Python libraries (the standard library is sufficient).
    • For optional advanced feature dependencies, see <SKILL_DIR>/scripts/requirements.txt：
      • Pillow: used for multi-page panoramic preview image stitching (export_images.py)。
      • System-level libreoffice / soffice / pdftoppm: used for headless rendering of PPTX to PDF and high-resolution PNG in environments without a macOS window server.
  2. Notes on rendering font substitution under Linux：
    • When exporting images with LibreOffice in a Linux headless server environment, if Chinese fonts (such as Source Han Serif or Microsoft YaHei) are not installed on the system, LibreOffice will fall back to local generic fonts, which may cause minor differences in CJK-Latin spacing and text line breaks. It is recommended to view the actual result on the final reading end (Windows Office / macOS Keynote).