| 1 | # 常见问题 |
| 2 | |
| 3 | [English](../faq.md) | [中文](./faq.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Q: PPT Master 支持哪些源文件格式？ |
| 8 | |
| 9 | 几乎所有常见格式都支持：**PDF**、**DOCX**、**PPTX**、**EPUB**、**HTML**、**LaTeX**、**RST**、**网页链接**（包括微信公众号文章）、**Markdown**，或者直接在对话中粘贴文字内容。AI 代理会自动将源材料转换为 Markdown 后再生成幻灯片。 |
| 10 | |
| 11 | ## Q: 只有一个主题或想法、没有任何资料，也能生成吗？ |
| 12 | |
| 13 | 可以。直接告诉 AI 你想做的主题或场景（如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"），Generate PPTX 路线会运行 **topic-research 阶段**，补齐规划所需的事实基础与来源记录。已有部分材料时，只补实现用户目标仍缺少的事实；如果用户要求只使用原材料，则不做外部补充。图片由 Strategist 在规划中选定，并且只在最终确认后获取。 |
| 14 | |
| 15 | 效果取决于公开网页的覆盖度。如果你已有专业资料（论文、内部文档），直接把文件给 AI 比联网检索更准。 |
| 16 | |
| 17 | ## Q: 除了 PPT 还能生成其他格式吗？ |
| 18 | |
| 19 | 可以。除了标准的 **16:9** 和 **4:3** 演示文稿格式，PPT Master 还内置了社交媒体和营销类格式： |
| 20 | |
| 21 | | 格式 | 适用场景 | |
| 22 | |------|----------| |
| 23 | | 小红书 3:4 | 图文分享、知识帖 | |
| 24 | | 微信朋友圈 / IG 1:1 | 方形海报、品牌展示 | |
| 25 | | Story / 抖音 9:16 | 竖版故事、短视频封面 | |
| 26 | | 微信文章头图 | 公众号文章封面 | |
| 27 | | A4 印刷 | 印刷海报、传单 | |
| 28 | |
| 29 | 创建项目时指定格式即可（如 `--format xhs`）。输出仍然是包含原生形状的 `.pptx` 文件。 |
| 30 | |
| 31 | ## Q: PPT Master 支持哪些 AI 工具？ |
| 32 | |
| 33 | PPT Master 可以在任何能读取文件和执行命令、支持 Agent 的 AI 工具中运行——**Claude Code**（CLI / VS Code / JetBrains / Web）、**VS Code Copilot**、**Codex** 等均可使用。不同工具的使用成本可参考下方的费用对比。 |
| 34 | |
| 35 | ## Q: 我下载过旧版本，怎么更新到最新版？ |
| 36 | |
| 37 | 看你当时怎么安装： |
| 38 | |
| 39 | | 安装方式 | 更新方式 | |
| 40 | |---|---| |
| 41 | | Git clone | 在 `ppt-master` 目录运行 `python3 skills/ppt-master/scripts/update_repo.py` | |
| 42 | | Download ZIP | 重新下载最新版 ZIP，解压到新目录；把旧目录里的 `.env` 和 `projects/` 复制过去；再运行 `pip install -r requirements.txt` | |
| 43 | | Skill marketplace | 用对应的 marketplace / skills 工具重新安装或更新 | |
| 44 | |
| 45 | 长期使用建议用 Git clone。ZIP 适合快速体验，但没有 Git 历史，不能自动 `git pull`。 |
| 46 | |
| 47 | 如果不确定自己是哪种安装方式，可以让 AI 在项目目录里运行： |
| 48 | |
| 49 | ```bash |
| 50 | python3 skills/ppt-master/scripts/update_repo.py |
| 51 | ``` |
| 52 | |
| 53 | 如果当前目录不是 Git clone 版本，脚本会提示你按 ZIP 方式迁移。 |
| 54 | |
| 55 | ## Q: 仓库超过 1 GB，skills 工具下载直接失败——能只拿 skill 吗？ |
| 56 | |
| 57 | 可以。完整仓库确实很大（Git 历史，加上内置的示例 deck 及其素材），而且这个体积是写进历史里的——在不破坏已有大量 fork 的前提下没法瘦身。如果你只想要 skill、不需要完整仓库，用下面的轻量方式： |
| 58 | |
| 59 | - **Marketplace CLI**：`npx skills add hugohe3/ppt-master`，或 Claude Code 里的 `/plugin install`，都只拉取 skill 文件（见 README 的「开始设置」一节）。 |
| 60 | - **手动下载**：到 [Releases](https://github.com/hugohe3/ppt-master/releases) 页面下载 `ppt-master-skill-*.zip`——只含 skill 文件（约 50 MB），无需 clone 完整仓库。 |
| 61 | |
| 62 | 两种方式装好后，都要在安装目录跑 `pip install -r requirements.txt`，后处理脚本才能工作。 |
| 63 | |
| 64 | 这两条路径都不带 `.git` 目录，`git describe` 查不到版本。已安装的版本记录在 skill 自身 `SKILL.md` frontmatter 的 `metadata.version` 字段里。 |
| 65 | |
| 66 | 中国大陆地区访问 GitHub 下载不便的话，完整仓库在 [AtomGit](https://atomgit.com/hugohe3/ppt-master) 也有镜像（clone 或下载 ZIP）；1 GB 出头的体积在中国大陆地区网络下载一般没问题。 |
| 67 | |
| 68 | ## Q: 能用 AI 生成配图吗？ |
| 69 | |
| 70 | 可以。PPT Master 内置了图片生成脚本，支持多个供应商（Gemini、OpenAI、FLUX、通义千问、智谱等）。在策略师阶段选择"AI 生图"方案后，流程会根据内容自动生成配图。你也可以使用自己的图片——只需放到项目的 `images/` 目录下即可。 |
| 71 | |
| 72 | ## Q: 没有生图 API Key，还能配图吗？ |
| 73 | |
| 74 | 可以——在策略师的"图片方案"步骤选择"网络图片"。PPT Master 内置了零配置的 `image_search.py`，在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片（无需 API Key）。零配置搜索适合作为兜底：能直接用，但图片质量不稳定，容易出现普通用户上传、构图随意、清晰度一般的素材。 |
| 75 | |
| 76 | 如果想要更现代的商业风照片，建议在 `.env` 里设置 `PEXELS_API_KEY` 和/或 `PIXABAY_API_KEY`（都是免费申请）。搜索会自动纳入 Pexels / Pixabay，人物、办公、生活方式、产品和插画类图片质量通常会明显更稳定。两种路径可以在同一份 deck 里混用（比如 hero 图用 AI 生成、团队照片用网络搜索）；如果选中的图片需要署名，Executor 会在该幻灯片自动添加就地小字署名。 |
| 77 | |
| 78 | 要清楚一点：**网络搜索只负责「找到一张相关、可下载、授权合规的图」，并不保证它在这一页里好看或贴切**——排序只看文字元数据，看不到画面。生成时多模态模型会读一份缩略图自查、不合适会重搜；但**要真正高质量，最可靠的还是你自己去搜**：在任何来源找到更合适的图，把链接给 AI，它会用 `image_search.py --from-url <链接>` 直接下载替换（记为手动来源、版权由你把关）。换图随时能做——生成途中或在实时预览里都行，不会打断流程。简而言之：把网络搜索当「兜底占位」，把人工挑图当「精修」。 |
| 79 | |
| 80 | ## Q: 生成的 PPT 可以编辑吗？ |
| 81 | |
| 82 | 可以。SVG 管线统一由项目转换器读取 `svg_output/` 并生成原生 DrawingML `.pptx`；文字、图形和颜色无需额外转换即可编辑，文件以时间戳命名保存至 `exports/`。使用默认输出路径时，Default Generate 与 Quick Generate 都会把作者源 `svg_output/` 镜像到 `backup/<timestamp>/svg_output/`，便于归档或基于该版重新导出 PPTX，无需再走 LLM。对 Quick 而言，这只是包重建，不是可恢复的 AI 设计决策记录。 |
| 83 | |
| 84 | 默认 Generate 流程的 Step 7 仍会强制生成 `svg_final/`。其中每页都是自包含的视觉预览 SVG，可直接在浏览器或 IDE 中打开，也可作为 SVG 图片手动插入 PowerPoint；显式快速生成会跳过这项预览产物，但在无锁最终质量检查通过后，仍保留普通 postflight 报告和默认输出路径下的备份。项目只保证 `svg_final/` 作为预览或图片显示，不保证 PowerPoint 手工“转换为形状”后的结果。需要可编辑形状时，请使用 `exports/` 中由项目转换器生成的原生 PPTX。 |
| 85 | |
| 86 | ## Q: 多行文本会怎样导出？可以让 PowerPoint 自动重排吗？ |
| 87 | |
| 88 | 默认会把可合并的多行文本块导出成一个可编辑的 PowerPoint 文本框，保留作者断行并禁用 PowerPoint 自动换行，因此拉伸文本框不会重写作者排好的行。普通生成文本框使用 PowerPoint 原生的“根据文字调整形状大小”：删除保留的换行后，文本框会随文字扩展，不会让文字留在框外。导入的精确文本框和结构化多行占位符 carrier 保持原有的固定尺寸行为。 |
| 89 | |
| 90 | 如果需要让 PowerPoint 自动重排适合流动的正文，请使用 `--reflow-text`： |
| 91 | |
| 92 | ```bash |
| 93 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --reflow-text |
| 94 | ``` |
| 95 | |
| 96 | 该模式会恢复段落自动重排，最终行数可能改变。旧参数 `--merge-paragraphs` 是 `--reflow-text` 的兼容别名。 |
| 97 | |
| 98 | 只有每一视觉行都必须成为独立的 PowerPoint 文本框时，才使用 `--no-merge`： |
| 99 | |
| 100 | ```bash |
| 101 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge |
| 102 | ``` |
| 103 | |
| 104 | 该模式保留逐行独立的对象位置，但 12 行正文会变成 12 个文本框。与 AI 对话时，可以直接说“允许文字自动重排”或“每一视觉行使用独立文本框”，由它选择对应的导出模式。 |
| 105 | |
| 106 | ## Q: 字号为什么用 px 不是 pt？导出后字号会变吗？ |
| 107 | |
| 108 | PPT Master 内部**全程只用 px**（无单位像素）——确认页、`spec_lock.md`、SVG 都是 px，没有 pt 这一层。原因是 SVG 画布本身就是 1280×720 px，px 是真正的排版/执行单位；只用一个单位，能避免「确认时说 20pt、写进 SVG 又变成另一个数」这类单位混淆导致整套字号偏差。 |
| 109 | |
| 110 | PowerPoint 最终显示的是 pt，所以**导出时**自动把 px 换成 pt（`pt = px × 0.75`，保留 1 位小数）。例如正文 `24px` 导出后是 `18pt`、标题 `42px` 是 `31.5pt`。所以你在 PowerPoint 里看到 `13.5pt`、`31.5pt` 这种非整数是**正常的、有意的**，不是 bug——字号算出来是多少就是多少，不再强行凑成整数或半磅。 |
| 111 | |
| 112 | 正文基准按**阅读模式**固定取值（不是区间）。它控制阅读距离与信息密度，与开放式沟通意图是两条独立轴： |
| 113 | |
| 114 | | 阅读模式 | 正文 px | ≈ 导出 pt | |
| 115 | |---|---|---| |
| 116 | | `text` 文字型（近读：报告 / 资料） | 20px | 15pt | |
| 117 | | `balanced` 均衡（默认：路演 / 评审） | 24px | 18pt | |
| 118 | | `presentation` 展示型（投影 / 发布） | 32px | 24pt | |
| 119 | |
| 120 | 标题、副标题、脚注等其它角色按比例从正文派生，并取整洁偶数 px。你在确认页可以手动覆盖任何角色的 px 值。 |
| 121 | |
| 122 | ## Q: PPT Master 怎么确定演示的风格？ |
| 123 | |
| 124 | 在第 d 项确认时锁定两个独立维度： |
| 125 | |
| 126 | - **Mode（怎么讲）**：`pyramid` / `narrative` / `instructional` / `showcase` / `briefing` —— 见 `references/modes/` |
| 127 | - **Visual style（长什么样）**：`swiss-minimal` / `editorial` / `soft-rounded` / `dark-tech` … + `custom` —— 见 `references/visual-styles/` |
| 128 | |
| 129 | 任意 mode 可与任意 visual style 自由组合。 |
| 130 | |
| 131 | ## Q: 用 PPT Master 做 PPT 贵吗？ |
| 132 | |
| 133 | PPT Master 本身免费开源，唯一的成本来自你自己的 AI 模型用量。 |
| 134 | |
| 135 | 目前主流 AI 工具都已转向按量计费——用多少付多少。PPT Master 天然契合这一模型：不需要额外订阅 PPT 平台、没有专有积分、没有按人头收费的演示工具费用。 |
| 136 | |
| 137 | 而且它跑在编程 agent 里：走固定月费的订阅套餐，就能在套餐额度内多做 deck 而不额外多花钱；走 API 直连、按 token 计费则是另一种价格结构——由你选。无论走哪条，PPT Master 都不会在你的 AI 支出之外再加一层自己的费用。 |
| 138 | |
| 139 | ## Q: 生成的图表可以编辑数据吗？ |
| 140 | |
| 141 | 默认情况下，图表以**自定义设计的 SVG 图形**形式渲染，转换为原生 PowerPoint 形状——形状级别完全可编辑（移动、改色、改文字、调样式）。默认不用 Excel 驱动的图表对象是有意为之：PowerPoint 默认图表样式陈旧、视觉受限于固定模板。SVG 图表则提供出版物级的视觉质量，可以在 PowerPoint 中直接精修，且在 PowerPoint / Keynote / LibreOffice / WPS 间像素一致。 |
| 142 | |
| 143 | 如果你的工作流明确需要 Excel 驱动的数据编辑或 PowerPoint 的图表/表格专属控制，导出时加 `--native-charts-and-tables`：受支持的数据图表和纯文本表格会以**带数据源的 PowerPoint 原生 Chart / Table 对象**形式导出（保存为 `exports/<name>_<timestamp>_native_charts_tables.pptx`，并保留这份 deck 自己的配色，而不是套用 PowerPoint 默认主题）。默认 SVG fallback 同样会转换成可编辑 DrawingML shape，但不具备图表数据工作簿或图表/表格对象模型。原生对象在 PowerPoint / Keynote / LibreOffice / WPS 间可能略有差异，因此形状路线仍是视觉稳定性的默认选择。 |
| 144 | |
| 145 | ## Q: 页面切换和元素动画可以调吗？ |
| 146 | |
| 147 | 可以。页间转场默认开（`fade` 0.4s），页内元素对象动画**默认关**——翻到 |
| 148 | 一页时整页一次性呈现，不会自动逐个级联。两者都通过 `svg_to_pptx.py` 的 |
| 149 | 参数控制：`-t/--transition` 控制页级，`-a/--animation` 控制元素级。对象 |
| 150 | 注册表已经包含进入、强调、动作路径和退出效果。 |
| 151 | |
| 152 | ```bash |
| 153 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果 |
| 154 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # 关闭转场 |
| 155 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto # 开启页内元素入场（按 group id 自动映射效果） |
| 156 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade # 开启并改用单一规范效果 |
| 157 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin # 原生强调效果 |
| 158 | python3 skills/ppt-master/scripts/pptx_animations.py --list # 完整分类效果清单 |
| 159 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click # 单击触发，演讲者控制节奏 |
| 160 | ``` |
| 161 | |
| 162 | `on-click` 适合现场演示。通过 `--recorded-narration` 做旁白/视频导出时会拒绝它，因为 PPT Master 只写页面级计时，不生成对象级点击计时；带旁白的 deck 请使用 `after-previous` 或 `with-previous`。 |
| 163 | |
| 164 | 常用命令、Start 模式选择与对象级自定义见[转场与动画](./animations.md)；精确效果与校验行为由其中链接的执行规范维护。 |
| 165 | |
| 166 | ## Q: 推荐用什么 AI 模型？ |
| 167 | |
| 168 | **Claude**（Opus / Sonnet）是推荐且测试最充分的模型。SVG 排版本质上是在绝对坐标系中做精确的数学计算（字号 x 字数 x 容器宽度），Claude 在这方面表现明显优于其他模型。 |
| 169 | |
| 170 | **GPT 系列**早期版本排版问题较多——文字超出容器、元素错位、坐标计算失误。较新的版本（如 GPT-5.5）在这方面已有明显进步，实际效果可以接受；如果遇到问题，可以告知 AI 修正具体页面。 |
| 171 | |
| 172 | 其他模型（Gemini、GLM、MiniMax 等）效果参差不齐。总体来说，前端/视觉能力越强的模型，生成效果越好。 |
| 173 | |
| 174 | ## Q: 有人说 PPT Master "只是个玩具"——这个评价准确吗？ |
| 175 | |
| 176 | 不准确。PPT Master 是演示文稿工作流，不是模型，也不是完整 agent。它提供演示文稿专用的推理、合同、项目状态、确定性转换与质量门；最终质量上限仍由所选模型决定。用弱模型或小上下文窗口来评价这套工作流，就好比挂着一档开跑车然后说它跑不快。 |
| 177 | |
| 178 | **发挥完整实力的组合：** |
| 179 | |
| 180 | - **Claude 大上下文窗口**（推荐 ~100 万 token 级别）：大上下文让 Executor 在同一个会话里看到全部已生成页面，在不拆分运行的前提下保持整份 deck 的视觉一致性。上下文不足时被迫走拆分模式，两段之间会出现明显的风格漂移。 |
| 181 | - **AI 生图，推荐 `gpt-image-2`**（或同等质量）：配图水平是 deck 整体观感的最大变量。用占位级的网络图片和用真正贴合内容的 AI 生成图，视觉效果完全是两个量级。 |
| 182 | |
| 183 | 如果你看到的效果差强人意，先对照以下几点检查你的配置，再下结论：用的什么模型？上下文开了多大？有没有接入图片生成 API？同样的工作流，Claude Opus 配 100 万 token 上下文配 `gpt-image-2` 的结果，和小参数开源模型配零配置的结果，是截然不同的体验。 |
| 184 | |
| 185 | > **没有 Claude 渠道？** 本项目赞助商 [PackyCode](https://www.packyapi.ai/register?aff=ppt-master) 提供 Claude 及其他主流模型的按量付费接入——无需订阅，无需境外信用卡，支持国内支付，开箱即用。充值时填写优惠码 **`ppt-master`** 享 9 折。 |
| 186 | |
| 187 | 最后再说一句：这是一个免费、个人维护的开源项目。合用就用，能帮到你我很高兴；不合用，换个工具就好。真诚的反馈与建议始终欢迎——这也是项目一点点变好的方式。 |
| 188 | |
| 189 | ## Q: 文字超出边框 / 元素错位怎么办？ |
| 190 | |
| 191 | 原因取决于偏差出现在哪一层。如果源 SVG 本身已经溢出或错位，通常属于创作 / 排版问题：模型需要准确计算坐标、字体度量和容器尺寸。如果 SVG 预览正确、导出的 PPTX 却不同，则可能是转换器或渲染器问题，应连同两份产物一起反馈。 |
| 192 | |
| 193 | **解决办法**： |
| 194 | 1. 对比 `svg_output/` 中的页面与导出 PPTX，先区分创作问题和转换问题 |
| 195 | 2. 告诉 AI 哪一页有问题、具体是什么问题——它可以单独重新生成某一页 |
| 196 | 3. 如果 SVG 本身持续出错，换更强的模型，或让 AI 直接修正坐标 |
| 197 | 4. 记住：生成的 PPTX 是**高质量、可编辑的草稿**，不是封闭的最终成品——在 PowerPoint 中做少量收尾是正常的 |
| 198 | |
| 199 | ## Q: 生成一份 PPT 要多久？ |
| 200 | |
| 201 | 一份典型的 10–15 页 PPT 大约需要 **10–20 分钟**（使用吞吐较快的模型）。生成流程是**故意串行的**（逐页生成），这样才能保持前后页面的视觉一致性——并行生成方案曾经测试过，结果是各画各的、缺乏整体观。 |
| 202 | |
| 203 | 如果感觉生成很慢，检查一下模型的 token 吞吐速度。瓶颈通常在模型的输出速度，而不是脚本本身。 |
| 204 | |
| 205 | 如果你想要的是少走流程、而不是换模型，可以显式要求快速生成：它跳过策略师分析与确认停顿，规划阶段的开销随之消失，但逐页 SVG 生成的时间不变。见下一问「不想先确认设计规格，能直接生成吗？」。 |
| 206 | |
| 207 | ## Q: 不想先确认设计规格，能直接生成吗？ |
| 208 | |
| 209 | 可以。请显式要求**快速生成**，Generate 路线会启用 [`quick-generate` profile](../../skills/ppt-master/workflows/profiles/quick-generate.md)。 |
| 210 | |
| 211 | **它跳过的是策略师分析、`design_spec.md` / `spec_lock.md` 落盘和分步确认停顿：你明确提出的要求照做；你没提的，当前 Agent 直接决定并继续，不再回来征求同意。** 什么都不提，才是全部由 Agent 决定。它同时跳过 `finalize_svg.py`，因此不生成 `svg_final/` 预览。 |
| 212 | |
| 213 | 它不跳过备料或设计能力：来源转换、已识别事实缺口的研究、共享美学参考，以及生成 deck 所需的资源仍按需准备——用户提供或源文件抽取的图片、AI / 网络 / 切片图片、项目图标、原生形状、图表 / 表格、渲染公式，以及对应的必要运行 manifest 或来源记录。必需素材未就绪时它仍会停下来跟你要，不会拿无关材料顶替。备料完成后，当前 Agent 按共享规范手写 `svg_output/`，运行无锁的 Quick 最终质量检查并修复所有阻塞错误，之后才导出最终 PPTX。 |
| 214 | |
| 215 | 原生图表 / 表格替换、讲稿、动效、旁白和诊断等普通导出能力仍可按需使用；讲稿、自定义对象动画和旁白默认关闭，Agent 可在用户要求或 deck 确有需要时自动启用，不会打开确认流程。使用默认输出路径时会生成普通 postflight 报告，并把 `svg_output/` 备份到 `backup/`；显式指定输出路径时沿用普通流程不创建备份的行为。页数本身既不会自动触发，也不会阻止快速生成。 |
| 216 | |
| 217 | 由于整个规划阶段不再发生，token 消耗明显低于默认流程；逐页 SVG 生成是一次 run 的主要开销，这部分并不减少。Quick 保留同一套视觉 / 资源创作能力和最终阻塞标准，但没有已确认的设计契约、首屏校准或可恢复的决策历史，因此不承诺与 Default 作出相同设计，也不承诺具体耗时。 |
| 218 | |
| 219 | ## Q: 长 PPT 一次生成会不会上下文爆掉？ |
| 220 | |
| 221 | 默认推荐**一次性连续生成**——10–15 页的 deck 在 200K 上下文窗口下完全够用，跨页视觉一致性也最好（Executor 看到前几页 SVG 后会主动对齐风格、字号、节奏）。 |
| 222 | |
| 223 | 当前 AI 编辑器若支持隔离研究子代理，`topic-research` 会把原始网页抓取留在该上下文，主会话只读取落盘的研究摘要和事实来源文件。 |
| 224 | |
| 225 | 只有信号偏重的场景（页数 ≥ 18 / 源材料很厚 / 本地回退研究后主会话仍保留大量研究材料，或导入的研究摘要本身异常庞大），AI 才会在策略师阶段给出**拆分模式**的可选提示：规划会话（策略师确认阶段 + 图片获取）结束后停止当前对话；你新开聊天窗口，输入 `继续生成 projects/<项目名>` 进入执行会话（SVG 生成 + 导出）。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。 |
| 226 | |
| 227 | 两段式是**折中方案**——新会话需付出重载 Generate 权威文档与必需执行引用的固定成本，但可丢弃规划会话噪声，并把节省下来的窗口空间用于主动重读 `sources/` 做内容增稠。**信号正常时不需要**，提示也不会出现；用户随时可以忽略提示，走默认连续模式。 |
| 228 | |
| 229 | ## Q: 能在导出前预览或修正某一页吗？ |
| 230 | |
| 231 | 可以。你可以**随时中断工作流**——前几页生成后就可以查看并反馈意见。AI 可以根据你的意见重新生成特定页面，不需要等到全部完成再修改。 |
| 232 | |
| 233 | 生成后的修正也一样简单，直接告诉 AI："第 3 页布局有问题——标题和图表重叠了"，它会修正那个特定的 SVG。 |
| 234 | |
| 235 | ## Q: 我手上有一份现成的 PPT，想基于它做东西，该走哪条路？ |
| 236 | |
| 237 | 把「用一份已有 PPT」拆成两个问题：**留不留它的内容**、**留不留它的设计（版式 + 视觉）**。四种组合对应三种生成路径，以及直接保留原文件这一种无需生成的结果： |
| 238 | |
| 239 | | 意图 | 路线 | 固定不变的东西 | |
| 240 | |---|---|---| |
| 241 | | 留内容 + 重做版式 | **Generate PPTX + beautify profile** | 页数、页序、每页文字、图表/表格数据 | |
| 242 | | 换内容 + 留设计 | **Fill Native PPTX** | 原生页面设计；可选择、乱序、复用源页 | |
| 243 | | 只留内容，设计与分页都重来 | **Generate PPTX** | 源事实；故事结构和页数都可重构 | |
| 244 | | 留内容 + 留设计 | 不必生成 | 直接用原文件 | |
| 245 | |
| 246 | 使用 **beautify profile** 的前提是：原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留，只重排版式、层级和留白，并继承原配色字体。典型说法是「把这份 PPT 美化一下 / 重新排版，内容别动」。见 [beautify profile](../../skills/ppt-master/workflows/profiles/beautify-pptx.md)。 |
| 247 | |
| 248 | 用 **主管线** 的前提是：原 PPT 只是内容材料。流程会用 `ppt_to_md` 抽成 Markdown，并读取 `analysis/` 里的 PPTX intake 事实，再由 Strategist 自由重构大纲（合页 / 拆页 / 换序）。典型说法是「用这份 PPT 的内容重做一份更好的」或「提炼成 10 页高管汇报」。 |
| 249 | |
| 250 | beautify 和主管线的一句话判别：**原来的分页是要保留的信息，还是只是前一作者的结构、可以推翻？** 保留 → beautify；推翻 → 主管线。落到硬判据就是**页数 / 页序**：只要它有任何变化——拆页、合页、删页、换序，乃至「一字不改、只把某张太挤的页拆开排得更好看」——都属于重分页，走主管线。beautify 严格 1:1。 |
| 251 | |
| 252 | 如果用户说法含糊，比如「把这份 PPT 做得更专业一点」「优化一下这个 deck」，AI 应先问一句：**要保留原页数、页序和每页文字，只做美化；还是把 PPT 当素材，重新梳理成一份新故事？** |
| 253 | |
| 254 | 还有一条正交的路：如果你不是要现在产出一份 deck，而是想把这套设计**收成可复用模板**供以后反复用，走 **create-template**（见下面「如何制作自定义模板」）。 |
| 255 | |
| 256 | --- |
| 257 | |
| 258 | ## Q: 我已经有一份做好的 `.pptx`，能不能复用它的设计、只填新内容？ |
| 259 | |
| 260 | 可以——这就是 **套模板（template fill）** 路径，独立于 SVG 生成管线。把你现成的 `.pptx` 连同素材（或一个主题）给 AI，说「套模板 / 把这些填回去」。它会把你的 deck 当作原生页面库，只挑适合新内容的页面（可乱序、可重复），把新文字——以及原生表格单元格、图表数据——直接写回原始 OOXML。 |
| 261 | |
| 262 | 输出仍是 100% 原生可编辑的 PowerPoint：原设计、母版、图片、动画都保留，且只导出选中的页面。它刻意**不**改版式、不加页、不换图——一份 deck 的页面结构本身承载着逻辑（总分、对比、递进），所以应挑选结构本就契合内容的页面，而不是硬塞进去。若需要全新结构或不同页数，请改用 create-template（见下一问）。完整步骤：[套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。 |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## Q: 如何制作自定义模板？ |
| 267 | |
| 268 | 想把自己喜欢的 PPT 模板制作成 PPT Master 可调用的模板？按以下步骤操作： |
| 269 | |
| 270 | **第一步 — 准备参考材料** |
| 271 | |
| 272 | **最推荐的方式是直接给原始 `.pptx` 文件**。PPT Master 会提取包内实际存在且受支持的主题色、字体、Master/Layout、placeholder type/idx、原生形状信息和可复用图片资源。`standard` 与 `fidelity` 把来源当作视觉参考，重新设计 SVG roster 和新的 Master/Layout/slot 系统，不保留、也不蒸馏来源拓扑。`mirror` 则把这些已验证的来源事实物化到新工作区，不做语义归纳或缺口补造。由于结构层禁止 `<g>`，来源 Master/Layout 的 group wrapper 只允许机械展开成直接原子。 |
| 273 | |
| 274 | 完整导入 SVG 可以保留高级 PowerPoint 形状所需的 metadata、隐藏 carrier 和预览指纹，并作为载荷后备留在临时分析工作区且保持不可变。模板创建使用带文档内 source ref 和紧凑路径/hash manifest 的轻量可编辑 IR。`standard` / `fidelity` 创作项目规范化 SVG，只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板，只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已经支持的载荷；不支持或已修改的对象保留当前 SVG fallback。 |
| 275 | |
| 276 | 没有源 PPTX 时，截图集也能跑（`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`），但保真度会明显下降。建议优先找原始 PPTX。 |
| 277 | |
| 278 | **第二步 — 让 AI 创建模板** |
| 279 | |
| 280 | 使用支持 Agent 的 AI 工具（Claude Code、Codex 等），要求它使用 **PPT Master 的 `/create-template` 工作流**，将这些参考材料转换成模板。提供的信息越详细，效果越好，例如： |
| 281 | |
| 282 | - 模板名称和适用场景（如政府汇报、高端咨询、产品宣讲等） |
| 283 | - 期望的风格基调和配色（如"现代克制、深蓝主色调"） |
| 284 | - 类别偏好（`brand` 品牌 / `general` 通用 / `scenario` 场景 / `government` 政务 / `special` 特殊） |
| 285 | - 画布格式（默认 16:9，如需其他格式请注明） |
| 286 | - 输出范围：进入索引的 `library`（默认）或一个已经初始化的 `project`；两者使用相同路由并省略空的可选目录 |
| 287 | |
| 288 | 不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息（输出范围、模板 ID、主题模式等）。 |
| 289 | |
| 290 | **第三步 — 等待完成** |
| 291 | |
| 292 | AI 代理会自动完成后续工作——分析参考、写入 kind 专属规范，仅为 Layout/Deck 构建结构定义，并验证工作区。Brand/Style 不生成预览 PPTX；Layout/Deck 可按请求生成 `exports/<id>_template_preview.pptx`，多 Master 时必须生成。两种范围都要求 `templates/`；Brand/Layout/Deck 可使用包自有 `images/` 和 `icons/`，Style 则只包含 `templates/design_spec.md`。`library` 写入 `skills/ppt-master/templates/<kind>/<id>/` 并完成全局注册；`project` 写入 `projects/<name>/` 并跳过注册；空的可选目录直接省略。把这个工作区根目录交给 Step 3 即可，Step 3 不会复制 `exports/`，全局库的预览导出也由 Git 忽略。兼容的旧平铺 Brand/Layout/Deck 工作区只有在满足当前 kind 合同时才可读取，Layout/Deck 还必须满足当前 structured SVG 合同；Style 不存在旧平铺形态，语义旧包必须通过 `create-template` 替换，不能原地升级。 |
| 293 | |
| 294 | > **提示**：对风格和使用场景描述得越具体，生成的模板就越符合你的预期。 |
| 295 | |
| 296 | --- |
| 297 | |
| 298 | > 更多问题可先查看 [skills/ppt-master/SKILL.md](../../skills/ppt-master/SKILL.md) 与 [AGENTS.md](../../AGENTS.md) |
| 299 |