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.mdindex 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 aboutTo 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 likeLibrary 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.mdindex 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>/` 即可: