Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(templates): add practical template usage and validation guidance

hugohe3845df17435d9
diff --git a/docs/templates-guide.md b/docs/templates-guide.md
index c4c479d0..a52683d2 100644
--- a/docs/templates-guide.md
+++ b/docs/templates-guide.md
@@ -12,6 +12,31 @@ This guide answers three questions:
2. [How do I turn someone else's PPT — or my own brand — into a template? (the focus)](#2-derive-a-new-template-the-focus)
3. [What are the limits of templates?](#3-template-boundaries)
+## 60-second template path
+
+Choose the route by the artifact you already have and the result you want:
+
+| Starting point and goal | Route | Copy-ready request |
+|---|---|---|
+| A raw `.pptx`; keep its existing slide shells and replace content | **Fill Native PPTX** | `Fill projects/source/template.pptx with projects/source/content.md.` |
+| A reusable Brand/Layout/Deck workspace; generate a fresh deck | **Generate PPTX with an explicit workspace path** | `Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/presentation_core/.` |
+| A PPTX, SVG set, brand guide, website, images, or mixed references; first build a reusable system | **Create Template → Generate PPTX** | `Use /create-template to create a reusable Deck workspace from projects/brand/our_deck.pptx.` |
+
+Do not pass a raw `.pptx` as a Generate PPTX template path. Fill it directly when you want its existing pages, or run Create Template first when you want a reusable system.
+
+Choose the workspace kind by what must be reused:
+
+| Kind | Reuses | Native PowerPoint result |
+|---|---|---|
+| **Brand** | Color, typography, logo, voice, icon style | Identity constraints only. Generated pages remain Slide-local under one clean project Master and Blank Layout. |
+| **Layout** | Page grammar, Master/Layout identities, slots, and layout roster | A structured deck with reusable native Masters, named Layouts, and placeholders; identity is chosen separately. |
+| **Deck** | Brand identity and page structure together | A structured deck with the template's complete identity plus reusable native Masters, named Layouts, and placeholders. |
+
+The two rules that prevent most mistakes:
+
+1. Supply the **workspace root**, not its `templates/` subdirectory and not a bare template name.
+2. Put the explicit workspace path in the initial generation request. The only exception is a Create Template run that immediately hands its validated workspace to Generate PPTX in the same conversation.
+
---
## 1. Use an existing template
@@ -42,15 +67,41 @@ This is intentional — the AI never makes a fuzzy / interpretive judgment about
To browse what's available in the built-in library, ask "what templates are available?" — the AI lists names and paths from the discovery index. Listing alone does not enter the template flow; you still need to send back a path to trigger Step 3.
+### Copy-ready examples
+
+Use one workspace:
+
+```text
+Make a deck from projects/q3-report/sources/report.pdf.
+Template workspace: skills/ppt-master/templates/layouts/presentation_core/
+```
+
+Combine identity and structure:
+
+```text
+Make a product-launch deck from projects/launch/sources/brief.md.
+Brand workspace: skills/ppt-master/templates/brands/anthropic/
+Layout workspace: skills/ppt-master/templates/layouts/presentation_core/
+```
+
+Use a project-scoped template created earlier:
+
+```text
+Make a deck from projects/annual-report/sources/report.md.
+Template workspace: projects/acme_template/
+```
+
+The path labels are optional; the paths themselves are mandatory. If two paths have the same kind, the workflow stops at the existing conflict-resolution gate instead of choosing one silently.
+
### Template catalog
-Templates are organized into three kinds, each in its own directory:
+Templates are organized into three kinds, each with a discovery index:
-- [`templates/brands/README.md`](../skills/ppt-master/templates/brands/README.md) — identity-only presets (color / typography / logo / voice / icon style), no SVG pages; Anthropic, Google
-- [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md) — structure-only patterns (canvas / page structure / page types / SVG roster), no identity; presentation_core
-- [`templates/decks/README.md`](../skills/ppt-master/templates/decks/README.md) — full identity + structure references (including the middle segment); CATARC and China Telecom
+- [`brands_index.json`](../skills/ppt-master/templates/brands/brands_index.json) — identity-only workspaces: color / typography / logo / voice / icon style, with no SVG page roster
+- [`layouts_index.json`](../skills/ppt-master/templates/layouts/layouts_index.json) — structure-only workspaces: canvas / page grammar / page types / SVG roster, with identity selected downstream
+- [`decks_index.json`](../skills/ppt-master/templates/decks/decks_index.json) — complete identity + structure workspaces, including deck-specific overview context
-Full data model + fusion / conflict-resolution rules: [`templates-architecture.md`](./templates-architecture.md).
+Ask "what templates are available?" for a readable list with workspace paths. The indexes are the current source of truth; the kind-specific READMEs define their contracts. Full data model + fusion / conflict-resolution rules: [`templates-architecture.md`](./templates-architecture.md).
### Free design vs template
@@ -188,6 +239,24 @@ When a deck/layout template is selected, the Strategist confirmation stage asks
- **adaptive** — choose one template SVG per page; keep its Master and assign a new explicit Layout key during authoring when fixed Layout atoms or slot topology/bounds must change
- **strict** — choose one template SVG per page and keep its Master/Layout/slot contract unchanged
+### Verify that Master and Layout were really applied
+
+For a generated deck that used a Layout or Deck workspace, verify the release artifact in Microsoft PowerPoint:
+
+| Check | Expected result |
+|---|---|
+| **View → Slide Master** | The declared Master(s) and named Layouts are present. |
+| **Home → New Slide** | The reusable Layout names appear in the layout picker under the intended Master. |
+| Select a generated slide and inspect **Layout** | The slide is bound to its declared Layout, not a generic inferred layout. |
+| Click a reusable content region | Template slots behave as native placeholders with the declared type and frame. |
+| Add a new slide from one of the emitted Layouts | Master/Layout visuals and placeholder geometry appear without copying a finished content slide. |
+
+Brand-only use is intentionally different: it applies identity while keeping authored content Slide-local, so do not expect a reusable template Layout roster beyond the clean package scaffold.
+
+`exports/<id>_template_preview.pptx` is review evidence created by Create Template when requested or required. It is not the template input; generation always consumes the workspace root.
+
+Microsoft PowerPoint is the acceptance target for Master/Layout behavior. Keynote, WPS, and LibreOffice can open PPTX files but may normalize template structure or load a large mirror roster of unused Layouts more slowly.
+
### What a derived template workspace looks like
Library and project scopes use the same core structure; substitute either `skills/ppt-master/templates/<kind>/<id>/` or `projects/<name>/` for `<template_workspace>`:
diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.md
index 598904e2..83a2f8f5 100644
--- a/docs/zh/templates-guide.md
+++ b/docs/zh/templates-guide.md
@@ -12,6 +12,31 @@ PPT Master 模板是一种可复用工作区,明确分为三类:**Brand**
2. [怎么把别人的 PPT / 自己的品牌做成模板?(重点)](#二派生新模板重点)
3. [模板的边界是什么?](#三模板的边界)
+## 60 秒选对模板路线
+
+先看你手里有什么,以及最终想得到什么:
+
+| 起点与目标 | 路线 | 可直接复制的请求 |
+|---|---|---|
+| 手里是原始 `.pptx`,想保留现有页面壳并替换内容 | **Fill Native PPTX** | `用 projects/source/template.pptx 套入 projects/source/content.md 的内容。` |
+| 已有可复用 Brand/Layout/Deck 工作区,想生成一份全新 deck | **Generate PPTX + 显式工作区路径** | `用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/presentation_core/。` |
+| 手里是 PPTX、SVG、品牌手册、网站、图片或混合参考,想先建立可复用系统 | **Create Template → Generate PPTX** | `用 /create-template 从 projects/brand/our_deck.pptx 创建一个可复用 Deck 工作区。` |
+
+不要把原始 `.pptx` 当作 Generate PPTX 的模板路径。想沿用它的现有页面就直接回填;想建立可复用系统,就先运行 Create Template。
+
+再按需要复用的内容选择工作区 kind:
+
+| Kind | 复用什么 | 原生 PowerPoint 结果 |
+|---|---|---|
+| **Brand** | 颜色、字体、Logo、语调、图标风格 | 只提供身份约束。生成页面保持 Slide 本地,文件只有干净的项目 Master 与 Blank Layout 脚手架。 |
+| **Layout** | 页面语法、Master/Layout 身份、槽位与版式 roster | 结构化 deck,包含可复用原生 Master、具名 Layout 与 placeholder;身份系统另行选择。 |
+| **Deck** | 品牌身份与页面结构一起复用 | 结构化 deck,同时带完整身份系统和可复用原生 Master、具名 Layout 与 placeholder。 |
+
+最容易避免误用的两条规则:
+
+1. 提供**工作区根目录**,不要只给它的 `templates/` 子目录,也不要只写模板名。
+2. 在首次生成请求里写明工作区路径。唯一例外是同一对话刚完成 Create Template,可立即把已验证工作区交给 Generate PPTX。
+
---
## 一、选用已有模板
@@ -42,15 +67,41 @@ PPT Master 模板是一种可复用工作区,明确分为三类:**Brand**
想知道内置库里有哪些模板,问一句"有哪些模板可以用?"——AI 会从发现索引里列出名字和对应路径。单纯列出并不进入模板流程,需要你**把其中一条路径**再发回来才会触发 Step 3。
+### 可直接复制的用法
+
+使用一个工作区:
+
+```text
+用 projects/q3-report/sources/report.pdf 做一份 deck。
+模板工作区:skills/ppt-master/templates/layouts/presentation_core/
+```
+
+组合身份与结构:
+
+```text
+用 projects/launch/sources/brief.md 做产品发布 deck。
+Brand 工作区:skills/ppt-master/templates/brands/anthropic/
+Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/
+```
+
+使用之前创建的项目级模板:
+
+```text
+用 projects/annual-report/sources/report.md 做一份 deck。
+模板工作区:projects/acme_template/
+```
+
+“模板工作区”这些标签可以不写,但路径本身必须明确。如果给出两个相同 kind 的路径,工作流会进入既有冲突解决门,不会静默替你选一个。
+
### 现有模板一览
-模板按三种身份分目录:
+模板按三种 kind 分目录,并分别由发现索引维护:
-- [`templates/brands/README.md`](../../skills/ppt-master/templates/brands/README.md) — 仅身份预设(color / typography / logo / voice / icon style),无 SVG 页面;Anthropic、Google
-- [`templates/layouts/README.md`](../../skills/ppt-master/templates/layouts/README.md) — 仅结构样板(canvas / page structure / page types / SVG roster),无身份;presentation_core
-- [`templates/decks/README.md`](../../skills/ppt-master/templates/decks/README.md) — 完整身份 + 结构参考(含中间段);中汽研、中国电信
+- [`brands_index.json`](../../skills/ppt-master/templates/brands/brands_index.json) — 仅身份工作区:color / typography / logo / voice / icon style,不含 SVG 页面 roster
+- [`layouts_index.json`](../../skills/ppt-master/templates/layouts/layouts_index.json) — 仅结构工作区:canvas / 页面语法 / page types / SVG roster,身份系统下游再选
+- [`decks_index.json`](../../skills/ppt-master/templates/decks/decks_index.json) — 完整身份 + 结构工作区,包含 deck 专属概览信息
-完整数据模型与三类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
+直接问“有哪些模板可以用?”即可得到带工作区路径的可读清单。索引是当前安装内容的真值,三类 README 负责定义合同。完整数据模型与三类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
### 自由设计 vs 模板
@@ -186,6 +237,24 @@ python3 skills/ppt-master/scripts/mirror_template_materialize.py \
- **适应性使用(adaptive)**——每页都选择一张模板 SVG;没有合适 Layout 时沿用同一 Master 创建新的显式 Layout
- **严格套用(strict)**——每页都选择一张模板 SVG,并保持其 Master/Layout/Placeholder 契约不变
+### 如何确认母版与版式真的生效
+
+使用 Layout 或 Deck 工作区生成后,在 Microsoft PowerPoint 中检查发布文件:
+
+| 检查位置 | 预期结果 |
+|---|---|
+| **视图 → 幻灯片母版** | 能看到模板声明的 Master 与具名 Layout。 |
+| **开始 → 新建幻灯片** | 版式选择器中能在预期 Master 下看到可复用 Layout 名称。 |
+| 选中生成页并查看 **版式** | 页面绑定到声明的 Layout,而不是导出器猜出的通用版式。 |
+| 点击可复用内容区域 | 模板槽位表现为带声明类型与边界的原生 placeholder。 |
+| 从某个已导出 Layout 新建一页 | 不复制成品内容页,也能得到该 Master/Layout 的固定视觉与 placeholder 几何。 |
+
+Brand-only 的目标不同:它只施加身份约束,创作内容仍保持 Slide 本地,因此不应期待除干净包脚手架之外的可复用 Layout roster。
+
+`exports/<id>_template_preview.pptx` 是 Create Template 按需或按规则生成的审阅证据,不是模板输入;真正生成时始终传工作区根目录。
+
+Master/Layout 行为以 Microsoft PowerPoint 为验收目标。Keynote、WPS 与 LibreOffice 可以打开 PPTX,但可能归一化模板结构,或在加载包含大量未使用 Layout 的 mirror roster 时明显更慢。
+
### 派生后的模板工作区长什么样
全局库与项目范围使用相同的核心结构。把下面的 `<template_workspace>` 替换为 `skills/ppt-master/templates/<kind>/<id>/` 或 `projects/<name>/` 即可: