feat: 导出 SproutClaw .sproutclaw 配置
包含 extensions、skills、prompts、settings、auth、models、mcp 等配置。 排除 node_modules、npm 缓存、sessions 等运行时数据。
This commit is contained in:
163
agent/skills-disabled/ppt-master/docs/zh/animations.md
Normal file
163
agent/skills-disabled/ppt-master/docs/zh/animations.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 页间转场与页内元素动画
|
||||
|
||||
PPT Master 导出的 PPTX 同时支持**页间转场**（page transition）与**页内元素入场动画**（per-element entrance animation）。两者都通过 `svg_to_pptx.py` 的 CLI 参数控制，输出为真正的 OOXML 动画——在 PowerPoint 和 Keynote 中原生播放，不是嵌入视频。
|
||||
|
||||
## 默认行为
|
||||
|
||||
| 层级 | 默认 | 原因 |
|
||||
|---|---|---|
|
||||
| 页间转场 | `fade`，0.4 秒 | 适合大多数 deck 的中性基线 |
|
||||
| 页内元素动画 | `auto` 效果 + `after-previous` 触发，0.4 秒时长 + 0.5 秒间隔 | 根据每个 group 的 SVG id 映射效果：信息密集元素稳定映射（chart→wipe、card-/step-/pillar-→fly、title/takeaway→fade），图片类 id（`hero` / `figure-` / `image` / `img-` / `kpi`）在更丰富的视觉池（zoom / dissolve / circle / box / diamond / wheel）中循环以产生 deck 内变化，未命中的 id 在 fade/wipe/fly/zoom 间循环。进入页面后元素自动级联入场，零交互即可看到完整动画过程 |
|
||||
|
||||
修改设置只需对同一份 `svg_output/`（或 `svg_final/`）重跑 `svg_to_pptx.py`，无需重新跑 LLM。如要彻底关闭页内动画，加 `-a none`。
|
||||
|
||||
## 对象级自定义动画
|
||||
|
||||
默认动画是全局策略。若需要更具体的演示节奏，例如标题先淡入、图表第二个出现、关键注释最后飞入，可以使用可选的 `animations.json` sidecar。SVG 仍然只保存静态视觉结构；sidecar 只控制 PPTX 导出动画。
|
||||
|
||||
当用户要求调整动画顺序、效果、时长或具体对象出现方式时，运行独立 [`customize-animations`](../../skills/ppt-master/workflows/customize-animations.md) 工作流。
|
||||
|
||||
```bash
|
||||
# 从真实顶层 <g id> 锚点生成可编辑模板
|
||||
python3 skills/ppt-master/scripts/animation_config.py scaffold <project>
|
||||
|
||||
# 导出前校验引用是否存在
|
||||
python3 skills/ppt-master/scripts/animation_config.py validate <project>
|
||||
|
||||
# 导出时会自动读取 <project>/animations.json
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
|
||||
```
|
||||
|
||||
最小 sidecar：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"slides": {
|
||||
"03_market": {
|
||||
"groups": {
|
||||
"title": { "effect": "fade", "order": 1 },
|
||||
"chart": { "effect": "wipe", "order": 2, "duration": 0.6 },
|
||||
"insight": { "effect": "fly", "order": 3, "delay": 0.2 },
|
||||
"footer": { "effect": "none" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- `slides` key 匹配 SVG 文件 stem（`03_market.svg` → `03_market`）。
|
||||
- `groups` key 匹配顶层 `<g id="...">` 锚点。
|
||||
- `effect: none` 会把该组移出入场动画序列。
|
||||
- `order` 只改变动画顺序，不改变页面图层顺序。
|
||||
- `delay` 是 `after-previous` 模式下该组开始前的秒数。
|
||||
- `duration` 覆盖该组的入场时长。
|
||||
- `--animation none` 覆盖 sidecar，强制关闭所有页内动画。
|
||||
|
||||
## 页间转场
|
||||
|
||||
```bash
|
||||
# 换效果
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push --transition-duration 0.6
|
||||
|
||||
# 关闭转场
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none
|
||||
|
||||
# 每 5 秒自动翻页（展厅 / 自动循环）
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5
|
||||
```
|
||||
|
||||
可选效果：`fade`、`push`、`wipe`、`split`、`strips`、`cover`、`random`。
|
||||
|
||||
参数：
|
||||
|
||||
- `-t/--transition` — 效果名，或 `none` 禁用。默认 `fade`。
|
||||
- `--transition-duration` — 秒数，默认 `0.4`。
|
||||
- `--auto-advance` — 秒数；不写则由演示者手动翻页。
|
||||
|
||||
## 页内元素动画
|
||||
|
||||
默认开启（`auto` 效果 + `after-previous` 触发）。共有三种 Start 模式，**与 PowerPoint 动画窗格的 Start 下拉菜单一一对应**：
|
||||
|
||||
- **`on-click`**（单击时）—— 进入页面 → 第一次点击显示第一个语义组，后续每次点击按 z-order 显示下一个组。适合现场演讲，演讲者控制节奏。与 `--recorded-narration` 互斥，因为带旁白的视频导出需要无点击播放。
|
||||
- **`with-previous`**（与上一动画同时）—— 所有组在进入页面时一起入场，并行播放各自的入场动画。`--animation-stagger` 不生效。
|
||||
- **`after-previous`**（默认，在上一动画之后）—— 第一组进入页面时入场，后续组在前一个结束后接着出现，并按 `--animation-stagger` 增加额外间隔。适合展厅循环、录屏走查，或者只是想看流动效果不想点击。
|
||||
|
||||
```bash
|
||||
# 默认即开启：auto 效果 + after-previous 触发，无需任何参数
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project>
|
||||
|
||||
# 关闭页内动画
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a none
|
||||
|
||||
# 改用单一效果（仍走默认的 after-previous 自动级联）
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade
|
||||
|
||||
# 改为单击触发（演讲者控制节奏）
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger on-click
|
||||
|
||||
# 自定义节奏
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation mixed \
|
||||
--animation-stagger 0.6 --animation-duration 0.5
|
||||
|
||||
# 所有组进入页面时同时入场
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger with-previous
|
||||
```
|
||||
|
||||
22 种单一效果：`appear`、`fade`、`fly`、`cut`、`zoom`、`wipe`、`split`、`blinds`、`checkerboard`、`dissolve`、`random_bars`、`peek`、`wheel`、`box`、`circle`、`diamond`、`plus`、`strips`、`wedge`、`stretch`、`expand`、`swivel`。再加三种自动模式：
|
||||
|
||||
- `auto`（默认）—— 按 group 的 SVG id 映射效果。信息密集元素稳定映射：`chart` / `table` / `legend` / `timeline` / `track` → `wipe`；`card-*` / `pillar-*` / `item-*` / `step-*` / `stage-*` / `tier-*` / `principle-*` → `fly`；`title` / `chapter-*` / `section-*` / `cover-*` / `tagline` / `subtitle` → `fade`；`takeaway` / `callout` / `quote` / `source` / `conclusion` / `note` → `fade`。图片类 id `hero` / `figure-*` / `image` / `img-*` / `kpi` 则在更丰富的视觉池（`zoom` / `dissolve` / `circle` / `box` / `diamond` / `wheel`）中循环，使多张图片在 deck 内呈现不同入场。未命中的 id 在 `fade` / `wipe` / `fly` / `zoom` 之间循环。
|
||||
- `mixed`（旧逻辑）—— 确定性轮换。每页第一个动画组使用 `fade`，后续组在整份 deck 范围内按 16 效果池（`blinds` / `checkerboard` / `dissolve` / `fly` / `cut` / `random_bars` / `box` / `split` / `strips` / `wedge` / `wheel` / `wipe` / `expand` / `fade` / `swivel` / `zoom`）连续轮换。保留以兼容旧配置。
|
||||
- `random` —— 在旧的 16 效果池中随机抽取。
|
||||
|
||||
所有轮换池都排除了 `appear`，因为它没有可见动画过程。
|
||||
|
||||
参数：
|
||||
|
||||
- `-a/--animation` — 效果名、`auto`、`mixed`、`random` 或 `none`。默认 `auto`。
|
||||
- `--animation-trigger` — Start 模式（与 PowerPoint 一致）：`on-click`、`with-previous`、`after-previous`（默认）。
|
||||
- `--animation-duration` — 单个元素入场秒数，默认 `0.4`。
|
||||
- `--animation-stagger` — `after-previous` 模式下两组之间的额外间隔（秒，默认 `0.5`）。其他模式忽略。
|
||||
- `--animation-config` — sidecar 路径。默认自动读取 `<project>/animations.json`（如果存在）。
|
||||
|
||||
> Note: `--recorded-narration` 会拒绝 `on-click`；带旁白的视频导出请使用 `after-previous` 或 `with-previous`。
|
||||
|
||||
## 锚点机制 — 顶层 `<g id="...">`
|
||||
|
||||
页内动画锚定在 SVG 的**顶层 `<g id="...">` 内容组**上（如 `<g id="cover-title">`、`<g id="card-1">`），一个组对应一次点击入场。
|
||||
|
||||
每页建议 **3–8 个内容组**。这同时也是 PowerPoint 框选 / 整体移动的颗粒度，与是否启用动画无关，都能改善编辑体验。
|
||||
|
||||
**装饰类分组自动跳过。** 顶层中看起来属于页面装饰的组（背景、页头页脚、装饰元素、水印、页码、导航、logo、分隔线）会被排除在点击序列外，跟随页面立即显示。识别基于 `id`：按 `-` 和 `_` 切分后，若任一 token 命中 `background` / `bg` / `decoration` / `decorations` / `decor` / `header` / `footer` / `chrome` / `watermark` / `pagenumber` / `pagenum` / `nav` / `logo` / `rule`，则视为装饰类。会自动跳过的例子：`<g id="background">`、`<g id="bg-texture">`、`<g id="cover-footer">`、`<g id="p03-header">`、`<g id="bottom-decor">`、`<g id="watermark">`、`<g id="nav">`、`<g id="logo-area">`、`<g id="column-rule">`。仍会动画的例子：`<g id="card-1">`、`<g id="cover-title">`、`<g id="step-discover">`、`<g id="timeline-track">`。**不要为了规避动画去掉 `<g>` 包裹**——保留分组（PowerPoint 框选需要），只要给个合适的 id 即可。
|
||||
|
||||
**扁平 SVG 的回退逻辑**（顶层没有 `<g>`，只有裸 `<rect>` / `<text>` / `<path>`）：
|
||||
|
||||
- 顶层可见图元 ≤ 8 → 每个图元作为一个锚点（设上限以避免密集页面出现 70+ 次点击）。
|
||||
- 顶层可见图元 > 8 → 该页跳过页内动画。页面照常显示，只是不带入场。
|
||||
|
||||
无论是否打算开启动画，Executor 都应该把逻辑分块包进 `<g id>`。`skills/ppt-master/references/shared-standards.md` 已将这一点列为强制要求。
|
||||
|
||||
## 限制
|
||||
|
||||
- **仅原生形状模式生效。** 页内动画需要可编辑形状作为锚点。`--only legacy` 模式每页一张大图，没有元素粒度，因此不响应 `-a/--animation`，只受 `-t/--transition` 影响。
|
||||
- **不同 Office 版本对元素动画存在轻微差异。** 实现走 `<p:animEffect filter=...>` 路径（而非 `presetID` 查找表），在 PowerPoint 2016+ 上表现一致；更老的 Office 可能把部分效果降级为 Appear。
|
||||
- **兼容模式的 PNG fallback 只用于显示。** 转场与动画都在 slide XML 里，不在 PNG 中；关掉兼容模式不影响两个动画层。
|
||||
|
||||
## 常用速查
|
||||
|
||||
| 目标 | 命令 |
|
||||
|---|---|
|
||||
| 关闭转场 | `-t none` |
|
||||
| 切换转场效果 | `-t push`（或上文列表中任一） |
|
||||
| 转场放慢 | `--transition-duration 0.8` |
|
||||
| 自动播放 | `--auto-advance 5` |
|
||||
| 关闭页内动画 | `-a none` |
|
||||
| 改为单击触发 | `--animation-trigger on-click` |
|
||||
| 切换为单一效果 | `--animation fade` |
|
||||
| 所有组同时入场 | `--animation-trigger with-previous` |
|
||||
| 元素入场放慢 | `--animation-duration 0.5` |
|
||||
| after-previous 拉大间隔 | `--animation-stagger 0.8` |
|
||||
|
||||
完整 `svg_to_pptx.py` 参考：[`scripts/docs/svg-pipeline.md`](../../skills/ppt-master/scripts/docs/svg-pipeline.md)。
|
||||
161
agent/skills-disabled/ppt-master/docs/zh/audio-narration.md
Normal file
161
agent/skills-disabled/ppt-master/docs/zh/audio-narration.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 音频旁白与视频导出
|
||||
|
||||
PPT Master 可以把演讲者备注转成逐页音频旁白（默认基于 [`edge-tts`](https://github.com/rany2/edge-tts) —— 微软 Edge 的在线神经网络语音；也可配置 ElevenLabs、MiniMax、Qwen TTS、CosyVoice 使用高质量或复刻音色），再把音频嵌入回 PPTX，由 PowerPoint 自带的"导出视频"一键产出带旁白和转场的 MP4，全程无需第三方工具。
|
||||
|
||||
## 你会得到什么
|
||||
|
||||
- 每页一个音频文件，存放于 `<project_path>/audio/`，文件名与 SVG 对齐（`01_cover.mp3`、`02_market_landscape.mp3` …）。
|
||||
- 可选重新导出：在 `exports/` 生成新版 PPTX，每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页，且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。
|
||||
- 演讲者备注原样保留。
|
||||
|
||||
## 它是怎么做到的
|
||||
|
||||
1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记，也没有 `要点：` / `时长：` 这种 meta 行——念出来的内容就是页面上的内容。
|
||||
2. **AI 替你选音色**。当你提出生成旁白时，AI 根据 deck 的主语言（`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …）和所选 provider 拉取或解释可用音色，挑出候选并给每个写一句中文调性说明（如"稳重男声·适合财报"）。语速/风格也会基于 notes 信息密度给出推荐值。
|
||||
3. **一次问完，一次回答**。AI 在一条消息里同时问三件事——生成模式、音色、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认，或者只说要改的部分（如"音色 2，语速 -5%"）。
|
||||
4. **执行**。脚本写出逐页音频到 `audio/`，再（如果你保留嵌入）重新导出带音频的 PPTX。不支持长音频导入或自动拆分。
|
||||
|
||||
完整流程见 [`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md)。
|
||||
|
||||
## 两条嵌入路径
|
||||
|
||||
| 命令 | 用途 |
|
||||
|---|---|
|
||||
| `--recorded-narration audio` | 准备 PowerPoint 的"录制的计时和旁白"。要求每页都有音频，并写入页面自动推进时间。用于旁白视频导出。 |
|
||||
| `--narration-audio-dir audio` | 底层音频嵌入能力。只嵌入匹配到的文件，允许部分页面有音频。用于测试或后续手工整理。 |
|
||||
|
||||
## 怎么触发
|
||||
|
||||
deck 导出后，在聊天里直接说就行：
|
||||
|
||||
```
|
||||
你: 给这个 PPT 生成音频
|
||||
你: 帮我用日语给这个 deck 配一个温柔女声的旁白
|
||||
你: Generate narration for this deck and re-export with audio embedded.
|
||||
```
|
||||
|
||||
剩下的 AI 全包。
|
||||
|
||||
## 支持的语言
|
||||
|
||||
凡是 `edge-tts` 支持的 locale 都行——大约 90 个，覆盖中文全部主要变体（`zh-CN` 普通话 / `zh-TW` 台湾普通话 / `zh-HK` 粤语）、英文（美/英/澳/印）、日语、韩语、法语、德语、西班牙语、葡萄牙语、俄语、阿拉伯语等。任何 locale 的全量音色清单都可以这样查：
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
|
||||
```
|
||||
|
||||
## 进阶：手动调用脚本
|
||||
|
||||
如果你想跳过 AI 流程直接跑命令：
|
||||
|
||||
```bash
|
||||
# 1. 确保备注已切分（后处理 Step 7.1）
|
||||
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
|
||||
|
||||
# 2A. 用 edge-tts 生成 MP3（默认，无需 API Key）
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--voice zh-CN-YunjianNeural --rate +0%
|
||||
|
||||
# 2B. 用 MiniMax 生成 MP3（支持系统音色或复刻 voice_id）
|
||||
export MINIMAX_API_KEY="your-minimax-api-key"
|
||||
# 默认使用国内地址；海外访问可设置 MINIMAX_TTS_BASE_URL=https://api.minimax.io/v1/t2a_v2
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider minimax \
|
||||
--voice-id <minimax-voice-id> \
|
||||
--minimax-model speech-2.8-hd
|
||||
|
||||
# 2C. 用 Qwen TTS 生成音频（系统音色或复刻音色）
|
||||
export DASHSCOPE_API_KEY="your-dashscope-api-key"
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider qwen \
|
||||
--voice-id <qwen-voice> \
|
||||
--qwen-model qwen3-tts-flash \
|
||||
--qwen-language-type Chinese
|
||||
|
||||
# 2D. 用 CosyVoice 生成 MP3（系统音色或复刻/设计音色）
|
||||
export COSYVOICE_API_KEY="your-dashscope-api-key"
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider cosyvoice \
|
||||
--voice-id <cosyvoice-voice> \
|
||||
--cosyvoice-model cosyvoice-v3-flash
|
||||
|
||||
# 3.（可选）重新导出 PPTX 嵌入音频
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
|
||||
--recorded-narration audio
|
||||
```
|
||||
|
||||
edge 模式下 `--voice` 是必填项。云端 provider 使用 `--voice-id` 传入对应平台的系统音色或复刻音色 ID。声音复刻本身先在对应平台控制台/API 中完成，`notes_to_audio.py` 使用得到的 voice ID 生成逐页旁白。
|
||||
|
||||
进入 PPTX 的旁白音频必须是 PowerPoint 可靠格式：`m4a`（AAC）、`mp3` 或 `wav`。内置生成路径默认使用 `mp3`；如果 provider 产出 `pcm`、`opus` 或 `flac`，需要先转码再嵌入。
|
||||
|
||||
## 使用复刻音色
|
||||
|
||||
四个云端 provider —— **ElevenLabs**、**MiniMax**、**Qwen**、**CosyVoice** —— 都支持用一段较短的音频样本复刻一个新音色，再用这个音色合成新语音。只要你能拿到 `voice_id`，PPT Master 就能用这个音色把整份 deck 念出来。（`edge` 不支持复刻。）
|
||||
|
||||
**职责切分**：声音复刻本身在 provider 的控制台或 API 完成——你上传一段样本（一般 10 秒到几分钟的干净录音），平台给你返回一个 `voice_id`。PPT Master 在*消费*侧：拿到 `voice_id` 后用这个音色逐页朗读备注。PPT Master 不会把你的样本上传到任何地方。
|
||||
|
||||
| Provider | 复刻入口 | 样本时长 |
|
||||
|---|---|---|
|
||||
| ElevenLabs | [elevenlabs.io](https://elevenlabs.io) → Voices → Add Voice → Instant / Professional Voice Cloning | 1 分钟（Instant）/ 30 分钟以上（Professional） |
|
||||
| MiniMax | [platform.minimaxi.com](https://platform.minimaxi.com) → 语音克隆 | 10 秒 – 5 分钟 |
|
||||
| Qwen TTS | [DashScope 控制台](https://dashscope.console.aliyun.com) → 语音合成 → 声音复刻 | 10 秒 – 5 分钟 |
|
||||
| CosyVoice | [DashScope 控制台](https://dashscope.console.aliyun.com) → 语音合成 → 音色复刻 | 10 秒 – 5 分钟 |
|
||||
|
||||
**复刻完之后怎么用** —— 在聊天里告诉 AI 即可，AI 会跳过音色推荐环节直接用你的 `voice_id`：
|
||||
|
||||
```
|
||||
你: 用 MiniMax 我克隆的音色生成旁白，voice_id 是 xxxxxxx
|
||||
你: 用我在 ElevenLabs 复刻的 voice id abc123 生成
|
||||
```
|
||||
|
||||
也可以直接跑脚本：
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider minimax --voice-id <你的复刻 voice id> \
|
||||
--minimax-model speech-2.8-hd
|
||||
```
|
||||
|
||||
把 `--provider minimax` 换成 `elevenlabs` / `qwen` / `cosyvoice` 就能切到对应平台；`--voice-id` 接收复刻音色和接收系统音色的方式完全一样。
|
||||
|
||||
**注意**：
|
||||
|
||||
- **授权** —— 只复刻你自己拥有的、或拿到了明确授权的声音。每个 provider 的服务条款都禁止冒用他人声音。
|
||||
- **语言覆盖** —— 复刻出来的音色会继承说话人的口音。对中英混合等多语 deck，建议挑一个对你样本语言组合处理较好的 provider；ElevenLabs `eleven_multilingual_v2` 和 CosyVoice 通常最宽容。
|
||||
- **一次复刻、长期复用** —— `voice_id` 不过期。复刻一次，可以给任意多份 deck 配旁白。
|
||||
|
||||
## 依赖
|
||||
|
||||
```bash
|
||||
python3 -m pip install edge-tts
|
||||
```
|
||||
|
||||
已写入 `skills/ppt-master/requirements.txt`。`edge-tts` 调用微软的在线 TTS 服务，**生成时**需要联网；生成后的音频是本地文件，PowerPoint 播放和视频导出都不依赖网络。云端 TTS provider 不需要额外 Python 包，直接通过 HTTPS 调用；按 `.env.example` 配置对应 API Key 即可。
|
||||
|
||||
## 经验值
|
||||
|
||||
- **语速**：PPT Master 默认每页 2–5 句备注，`+0%` 听感最自然。如果某页特别密集（长技术段落），可以试 `-5%`。
|
||||
- **改某一页**：改对应的 `notes/<page>.md`，再跑一次 `notes_to_audio.py`（脚本会重新生成全量 MP3，整套 deck 跑一遍成本很低）。
|
||||
- **混合语言 deck**（中文里夹英文术语等）：主流 locale 的神经语音对嵌入的外语词处理得不错——按主语言挑音色，先用一页试听再批量。
|
||||
|
||||
---
|
||||
|
||||
## 导出为视频
|
||||
|
||||
带旁白的 PPTX 在 `exports/` 里就绪后，PowerPoint 自带"创建视频"功能可以直接把它导出成 MP4——不需要任何第三方工具。嵌入的音频会作为每页旁白播放；页间切换时间已经由 PPT Master 在嵌入时按音频长度自动设好（用 `--recorded-narration audio` 重新导出时），所以视频节奏和旁白完全同步。`--recorded-narration` 会拒绝 `on-click` 对象动画，因为 PPT Master 不生成对象级点击计时。
|
||||
|
||||
**PowerPoint（Windows / Mac，Office 2016+）**：
|
||||
|
||||
1. 打开 `exports/` 里那份带旁白的 `.pptx`。
|
||||
2. **文件 → 导出 → 创建视频**。
|
||||
3. 选清晰度（4K / 全高清 / 高清 / 标准）以及"使用录制的计时和旁白"——PPT Master 已经替你录好了。
|
||||
4. **创建视频** → 保存为 `.mp4`（Windows 也支持 `.wmv`）。
|
||||
|
||||
**Keynote（Mac）**：打开 deck → **文件 → 导出到 → 影片…** ——Keynote 同样会读取嵌入的音频和分页计时，输出 `.m4v` / `.mov`。
|
||||
|
||||
**经验值**：
|
||||
|
||||
- **不需要麦克风、不需要录制环节**——音频是合成的，重跑可重现。
|
||||
- **动画保留**：PPT Master 的页间转场和无点击页内元素入场动画是真正的 OOXML 动画，导出视频后正常播放。详见 [转场与动画](./animations.md)。
|
||||
- **单页改音频**：改对应 `notes/<page>.md`，再跑一遍 `notes_to_audio.py` + 嵌入步骤，再重新导出视频——单页迭代通常不到一分钟。
|
||||
- **文件大小**：20 页全高清 deck 通常是 30–80 MB，取决于图片量。需要小文件分享时降到高清就行。
|
||||
193
agent/skills-disabled/ppt-master/docs/zh/faq.md
Normal file
193
agent/skills-disabled/ppt-master/docs/zh/faq.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 常见问题
|
||||
|
||||
[English](../faq.md) | [中文](./faq.md)
|
||||
|
||||
---
|
||||
|
||||
## Q: PPT Master 支持哪些源文件格式？
|
||||
|
||||
几乎所有常见格式都支持：**PDF**、**DOCX**、**PPTX**、**EPUB**、**HTML**、**LaTeX**、**RST**、**网页链接**（包括微信公众号文章）、**Markdown**，或者直接在对话中粘贴文字内容。AI 代理会自动将源材料转换为 Markdown 后再生成幻灯片。
|
||||
|
||||
## Q: 只有一个主题或想法、没有任何资料，也能生成吗？
|
||||
|
||||
可以。直接告诉 AI 你想做的主题或场景（如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"），AI 会自动启动 **topic-research 工作流**——通过网页搜索抓取权威来源（Wikipedia / 官网 / 机构发布），整理成 Markdown 资料文档 + 配图集后再走主流程生成幻灯片。
|
||||
|
||||
效果取决于公开网页的覆盖度。如果你已有专业资料（论文、内部文档），直接把文件给 AI 比联网检索更准。
|
||||
|
||||
## Q: 除了 PPT 还能生成其他格式吗？
|
||||
|
||||
可以。除了标准的 **16:9** 和 **4:3** 演示文稿格式，PPT Master 还内置了社交媒体和营销类格式：
|
||||
|
||||
| 格式 | 适用场景 |
|
||||
|------|----------|
|
||||
| 小红书 3:4 | 图文分享、知识帖 |
|
||||
| 微信朋友圈 / IG 1:1 | 方形海报、品牌展示 |
|
||||
| Story / 抖音 9:16 | 竖版故事、短视频封面 |
|
||||
| 微信文章头图 | 公众号文章封面 |
|
||||
| A4 印刷 | 印刷海报、传单 |
|
||||
|
||||
创建项目时指定格式即可（如 `--format xhs`）。输出仍然是包含原生形状的 `.pptx` 文件。
|
||||
|
||||
## Q: PPT Master 支持哪些 AI 工具？
|
||||
|
||||
PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中运行——**Claude Code**（CLI / VS Code / JetBrains / Web）、**VS Code Copilot**、**Codex** 等均可使用。不同工具的使用成本可参考下方的费用对比。
|
||||
|
||||
## Q: 能用 AI 生成配图吗？
|
||||
|
||||
可以。PPT Master 内置了图片生成脚本，支持多个供应商（Gemini、OpenAI、FLUX、通义千问、智谱等）。在策略师阶段选择"AI 生图"方案后，流程会根据内容自动生成配图。你也可以使用自己的图片——只需放到项目的 `images/` 目录下即可。
|
||||
|
||||
## Q: 没有生图 API Key，还能配图吗？
|
||||
|
||||
可以——在策略师的"图片方案"步骤选择"网络图片"。PPT Master 内置了零配置的 `image_search.py`，在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片（无需 API Key）。零配置搜索适合作为兜底：能直接用，但图片质量不稳定，容易出现普通用户上传、构图随意、清晰度一般的素材。
|
||||
|
||||
如果想要更现代的商业风照片，建议在 `.env` 里设置 `PEXELS_API_KEY` 和/或 `PIXABAY_API_KEY`（都是免费申请）。搜索会自动纳入 Pexels / Pixabay，人物、办公、生活方式、产品和插画类图片质量通常会明显更稳定。两种路径可以在同一份 deck 里混用（比如 hero 图用 AI 生成、团队照片用网络搜索）；如果选中的图片需要署名，Executor 会在该幻灯片自动添加就地小字署名。
|
||||
|
||||
## Q: 生成的 PPT 可以编辑吗？
|
||||
|
||||
可以。主 `.pptx`（原生 PowerPoint 形状，文字、图形、颜色均可直接编辑，无需转换）以时间戳命名保存至 `exports/`。Executor 的原始 SVG 源（`svg_output/` 副本）始终镜像到 `backup/<timestamp>/svg_output/`，便于归档或基于该版重跑 `finalize_svg → svg_to_pptx` 重建 pptx，无需再走 LLM。加 `--svg-snapshot` 会额外在 `exports/` 内并排生成 SVG 快照版 pptx，便于跨平台单文件分发；默认关闭——日常开发/诊断场景中 live preview 已经提供了 SVG 视觉参考。需要 **Office 2016** 或更高版本。
|
||||
|
||||
## Q: 为什么一段正文被拆成了好几个文本框？能不能一段一个文本框？
|
||||
|
||||
默认会把可合并的正文段落导出成一个可编辑的 PowerPoint 文本框，内部保留多个段落。**拉伸框时文字会在框内自动重排**。
|
||||
|
||||
如果你需要严格保持逐行版式，重新导出时加上 `--no-merge`：
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge
|
||||
```
|
||||
|
||||
使用 `--no-merge` 时，SVG 里的每一视觉行都会变成一个独立的 PowerPoint 文本框。这样能**逐像素保留 SVG 的版式**，适合封面、图表、表格、以及任何对版式精度敏感的页面。
|
||||
|
||||
**代价**：默认段落合并后，PowerPoint 自动换行的行数可能与原 SVG 不一致。默认更适合正文密集型页面（abstract、多段落章节、参考文献等）；版式敏感页面使用 `--no-merge`。判定足够保守——非段落型 `<text>` 会自动落回按行拆框路径。
|
||||
|
||||
跟 AI 对话时也可以直接说："这个页面要严格保持逐行版式" —— AI 重新导出时会加上 `--no-merge`。
|
||||
|
||||
## Q: 三种执行师有什么区别？
|
||||
|
||||
- **Executor_General**: 通用场景，灵活布局
|
||||
- **Executor_Consultant**: 一般咨询，数据可视化
|
||||
- **Executor_Consultant_Top**: 顶级咨询（MBB 级），5 大核心技巧
|
||||
|
||||
## Q: 用 PPT Master 做 PPT 贵吗？
|
||||
|
||||
PPT Master 本身免费开源，唯一的成本来自你自己的 AI 模型用量。
|
||||
|
||||
目前主流 AI 工具都已转向按量计费——用多少付多少。PPT Master 天然契合这一模型：不需要额外订阅 PPT 平台、没有专有积分、没有按人头收费的演示工具费用。
|
||||
|
||||
作为对比，Gamma 订阅 $8–20/月，Beautiful.ai $12–45/月——无论用多少都得付这个底价。PPT Master 在你现有 AI 支出之外不增加任何额外成本。
|
||||
|
||||
## Q: 生成的图表可以编辑数据吗？
|
||||
|
||||
图表以**自定义设计的 SVG 图形**形式渲染，转换为原生 PowerPoint 形状——形状级别完全可编辑（移动、改色、改文字、调样式）。这是一个有意为之的选择，而不是 Excel 驱动的图表对象：PowerPoint 默认图表样式陈旧、视觉受限于固定模板。SVG 图表则提供出版物级的视觉质量，并且可以在 PowerPoint 中直接精修。
|
||||
|
||||
如果你的工作流明确需要 Excel 驱动的数据编辑，可以在导出后自己手动在 PowerPoint 里制作一张类似的原生图表。
|
||||
|
||||
## Q: 页面切换和元素动画可以调吗？
|
||||
|
||||
可以。页间转场（默认 `fade` 0.4s）和页内元素入场动画（默认 `auto` 效果 + `after-previous` 自动级联，根据每个 group 的 SVG id 自动映射效果——图片类 id 在视觉池中循环以产生 deck 内变化）都通过 `svg_to_pptx.py` 的参数控制——`-t/--transition` 控制页级，`-a/--animation` 控制元素级。常用一行命令：
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # 关闭转场
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a none # 关闭页内动画
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # 改用单一效果（仍是默认级联）
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger on-click # 改为单击触发，演讲者控制节奏
|
||||
```
|
||||
|
||||
`on-click` 适合现场演示。通过 `--recorded-narration` 做旁白/视频导出时会拒绝它，因为 PPT Master 只写页面级计时，不生成对象级点击计时；带旁白的 deck 请使用 `after-previous` 或 `with-previous`。
|
||||
|
||||
完整效果列表、`<g id="...">` 锚点机制、降级行为、限制：见 [转场与动画](./animations.md)。
|
||||
|
||||
## Q: 推荐用什么 AI 模型？
|
||||
|
||||
**Claude**（Opus / Sonnet）是推荐且测试最充分的模型。SVG 排版本质上是在绝对坐标系中做精确的数学计算（字号 x 字数 x 容器宽度），Claude 在这方面表现明显优于其他模型。
|
||||
|
||||
**GPT 系列**早期版本排版问题较多——文字超出容器、元素错位、坐标计算失误。较新的版本（如 GPT-5.5）在这方面已有明显进步，实际效果可以接受；如果遇到问题，可以告知 AI 修正具体页面。
|
||||
|
||||
其他模型（Gemini、GLM、MiniMax 等）效果参差不齐。总体来说，前端/视觉能力越强的模型，生成效果越好。
|
||||
|
||||
## Q: 有人说 PPT Master "只是个玩具"——这个评价准确吗？
|
||||
|
||||
不准确。PPT Master 是一个 **harness**，不是完整的 agent——`harness + model = agent`，输出上限完全由模型决定，而不是由 harness 本身决定。用弱模型或小上下文窗口来评价 PPT Master，就好比挂着一档开跑车然后说它跑不快。
|
||||
|
||||
**发挥完整实力的组合：**
|
||||
|
||||
- **Claude 大上下文窗口**（推荐 ~100 万 token 级别）：大上下文让 Executor 在同一个会话里看到全部已生成页面，在不拆分运行的前提下保持整份 deck 的视觉一致性。上下文不足时被迫走拆分模式，两段之间会出现明显的风格漂移。
|
||||
- **AI 生图，推荐 `gpt-image-2`**（或同等质量）：配图水平是 deck 整体观感的最大变量。用占位级的网络图片和用真正贴合内容的 AI 生成图，视觉效果完全是两个量级。
|
||||
|
||||
如果你看到的效果差强人意，先对照以下几点检查你的配置，再下结论：用的什么模型？上下文开了多大？有没有接入图片生成 API？同样的工作流，Claude Opus 配 100 万 token 上下文配 `gpt-image-2` 的结果，和小参数开源模型配零配置的结果，是截然不同的体验。
|
||||
|
||||
**harness 决定工作流上限，model 决定质量上限。** 如果 agent 能力不达预期，请先升级模型，再来评价 harness。
|
||||
|
||||
> **没有 Claude 渠道？** 本项目赞助商 [PackyCode](https://www.packyapi.com/register?aff=ppt-master) 提供 Claude 及其他主流模型的按量付费接入——无需订阅，无需境外信用卡，支持国内支付，开箱即用。充值时填写优惠码 **`ppt-master`** 享 9 折。
|
||||
|
||||
最后再说一句：这是一个免费、个人维护的开源项目。合用就用，能帮到你我很高兴；不合用，换个工具就好。真诚的反馈与建议始终欢迎——这也是项目一点点变好的方式。
|
||||
|
||||
## Q: 文字超出边框 / 元素错位怎么办？
|
||||
|
||||
这几乎都是模型能力问题，不是 PPT Master 的 bug。SVG 排版是纯手动绝对定位——模型必须准确计算坐标、字体度量和容器尺寸。
|
||||
|
||||
**解决办法**：
|
||||
1. 切换到 **Claude**（Opus 或 Sonnet），如果你用的是其他模型
|
||||
2. 告诉 AI 哪一页有问题、具体是什么问题——它可以单独重新生成某一页
|
||||
3. 直接打开 SVG 源文件，让 AI 修正坐标
|
||||
4. 记住：生成的 PPTX 是**高质量起点**，不是最终成品——在 PowerPoint 中做少量调整是正常的
|
||||
|
||||
## Q: 生成一份 PPT 要多久？
|
||||
|
||||
一份典型的 10–15 页 PPT 大约需要 **10–20 分钟**（使用吞吐较快的模型）。生成流程是**故意串行的**（逐页生成），这样才能保持前后页面的视觉一致性——并行生成方案曾经测试过，结果是各画各的、缺乏整体观。
|
||||
|
||||
如果感觉生成很慢，检查一下模型的 token 吞吐速度。瓶颈通常在模型的输出速度，而不是脚本本身。
|
||||
|
||||
## Q: 长 PPT 一次生成会不会上下文爆掉？
|
||||
|
||||
默认推荐**一次性连续生成**——10–15 页的 deck 在 200K 上下文窗口下完全够用，跨页视觉一致性也最好（Executor 看到前几页 SVG 后会主动对齐风格、字号、节奏）。
|
||||
|
||||
只有信号偏重的场景（页数 ≥ 18 / 源材料很厚 / 走过 topic-research 累积大量 web 抓取），AI 才会在策略师阶段给出**两段式（拆分模式）**的可选提示：第一阶段（八项确认 + 图片获取）结束后停止当前对话；你新开聊天窗口，输入 `继续生成 projects/<项目名>` 进入第二阶段（SVG 生成 + 导出）。新会话从磁盘重新加载 `design_spec` / `spec_lock` / `sources` / `images` 继续执行。
|
||||
|
||||
两段式是**折中方案**——付出约 6K tokens 的 SKILL.md 重读成本，换得 60–200K 的 Phase A 噪声丢弃，并把节省下来的窗口空间用于 Phase B 主动重读 `sources/` 做内容增稠。**信号正常时不需要**，提示也不会出现；用户随时可以忽略提示，走默认连续模式。
|
||||
|
||||
## Q: 能在导出前预览或修正某一页吗？
|
||||
|
||||
可以。你可以**随时中断工作流**——前几页生成后就可以查看并反馈意见。AI 可以根据你的意见重新生成特定页面，不需要等到全部完成再修改。
|
||||
|
||||
生成后的修正也一样简单，直接告诉 AI："第 3 页布局有问题——标题和图表重叠了"，它会修正那个特定的 SVG。
|
||||
|
||||
## Q: 我已经有一份做好的 `.pptx`，能不能复用它的设计、只填新内容？
|
||||
|
||||
可以——这就是 **套模板（template fill）** 路径，独立于 SVG 生成管线。把你现成的 `.pptx` 连同素材（或一个主题）给 AI，说「套模板 / 把这些填回去」。它会把你的 deck 当作原生页面库，只挑适合新内容的页面（可乱序、可重复），把新文字——以及原生表格单元格、图表数据——直接写回原始 OOXML。
|
||||
|
||||
输出仍是 100% 原生可编辑的 PowerPoint：原设计、母版、图片、动画都保留，且只导出选中的页面。它刻意**不**改版式、不加页、不换图——一份 deck 的页面结构本身承载着逻辑（总分、对比、递进），所以应挑选结构本就契合内容的页面，而不是硬塞进去。若需要全新结构或不同页数，请改用 create-template（见下一问）。完整步骤：[套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。
|
||||
|
||||
---
|
||||
|
||||
## Q: 如何制作自定义模板？
|
||||
|
||||
想把自己喜欢的 PPT 模板制作成 PPT Master 可调用的模板？按以下步骤操作：
|
||||
|
||||
**第一步 — 准备参考材料**
|
||||
|
||||
**最推荐的方式是直接给原始 `.pptx` 文件**。当前的 PPTX 导入管线能做到接近高保真还原——PPT Master 会从 PPTX 中提取主题色、字体、母版/版式结构、可复用图片资源（包括精灵图裁剪关系），再用这些素材重建出干净可维护的模板。封面、章节、装饰繁复的页面都能稳定还原，这是目前最靠谱的派生路径。
|
||||
|
||||
没有源 PPTX 时，截图集也能跑（`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`），但保真度会明显下降。建议优先找原始 PPTX。
|
||||
|
||||
**第二步 — 让 AI 创建模板**
|
||||
|
||||
使用 AI 编程代理（Claude Code、Codex 等），要求它使用 **PPT Master 的 `/create-template` 工作流**，将这些参考材料转换成模板。提供的信息越详细，效果越好，例如：
|
||||
|
||||
- 模板名称和适用场景（如政府汇报、高端咨询、产品宣讲等）
|
||||
- 期望的风格基调和配色（如"现代克制、深蓝主色调"）
|
||||
- 类别偏好（`brand` 品牌 / `general` 通用 / `scenario` 场景 / `government` 政务 / `special` 特殊）
|
||||
- 画布格式（默认 16:9，如需其他格式请注明）
|
||||
|
||||
不需要一次提供所有细节——AI 代理会通过对话追问补齐缺失信息（模板 ID、主题模式等）。
|
||||
|
||||
**第三步 — 等待完成**
|
||||
|
||||
AI 代理会自动完成后续工作 — 分析截图、构建布局定义、注册模板，使其出现在 PPT Master 工作流的模板选项中。
|
||||
|
||||
> **提示**：对风格和使用场景描述得越具体，生成的模板就越符合你的预期。
|
||||
|
||||
---
|
||||
|
||||
> 更多问题可先查看 [skills/ppt-master/SKILL.md](../../skills/ppt-master/SKILL.md) 与 [AGENTS.md](../../AGENTS.md)
|
||||
127
agent/skills-disabled/ppt-master/docs/zh/getting-started.md
Normal file
127
agent/skills-disabled/ppt-master/docs/zh/getting-started.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# 快速入门
|
||||
|
||||
最快做出第一份 deck 的路径、围绕它的各项能力——模板、实时预览、动画、旁白、声音复刻——以及出问题时去哪里查。章节大致按你真实使用时遇到它们的顺序排列。每节都是精简版,需要细节就点 **完整说明 →** 链接。
|
||||
|
||||
- [用模板](#用模板)
|
||||
- [做出第一份 deck](#做出第一份-deck)
|
||||
- [实时预览与可视化修改](#实时预览与可视化修改)
|
||||
- [转场与动画](#转场与动画)
|
||||
- [旁白与视频](#旁白与视频)
|
||||
- [使用复刻音色](#使用复刻音色)
|
||||
- [遇到问题怎么办](#遇到问题怎么办)
|
||||
|
||||
---
|
||||
|
||||
## 用模板
|
||||
|
||||
**可选。** 默认走**自由设计**——不需要模板,可以直接跳到下一节。只有当 deck 必须复用一套固定版式或品牌时,才需要模板。
|
||||
|
||||
**复用现成 `.pptx` 有两条路,取决于你想要什么结果:**
|
||||
|
||||
| 你想要… | 路径 | 会发生什么 |
|
||||
|---|---|---|
|
||||
| **就要这份 deck,换成新内容** | 套模板(template fill) | 挑出合适的页面,把文字 / 表格 / 图表数据直接写回原文件。设计、版式、图片、动画都保留;输出就是同一份 deck,原生可编辑。最快;但受限于现有页面。 |
|
||||
| **基于这份 deck 的风格生成新 deck** | create-template | 把 `.pptx` 解析成可复用的风格资产包,再走 SVG 管线**重新生成**——结构自由、页数任意。更灵活;完整重建。 |
|
||||
|
||||
前者:把 `.pptx` 连同素材(或一个主题)给 AI,说「套模板」——见 [套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。本节其余部分讲 create-template。
|
||||
|
||||
**想基于某份现成 PPT 的风格重新生成 deck,必须显式走 create-template 流程——别直接丢个 `.pptx` 指望 AI 自动处理。** AI 默认走自由设计,不会主动切进创建模板的流程;不显式启动它,生成过程就容易错乱。先用 create-template 把那份 `.pptx` 复刻成 PPT Master 模板:
|
||||
|
||||
```
|
||||
你：用 /create-template 把这个复刻成模板：projects/brand/our_deck.pptx
|
||||
```
|
||||
|
||||
这会跑 `pptx_template_import.py`,把文件重建成可复用的资产包——版式 SVG + `design_spec.md` + 抽取出的主题色、字体、图片。生成时引用的就是这个资产包。
|
||||
|
||||
复刻出的模板可以放在两个位置之一:
|
||||
|
||||
| 位置 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
| **注册进 skill 库** | `skills/ppt-master/templates/layouts/<id>/` | 全局,所有项目可复用;跑 `register_template.py` 后,问"有哪些模板"时会被列出来 |
|
||||
| **放进项目里** | `projects/<project>/templates/` | 项目本地;给路径即用,无需注册 |
|
||||
|
||||
无论放哪,生成时都靠在对话里给出它的**目录路径**来引用——工作流只认显式路径,绝不认裸模板名:
|
||||
|
||||
```
|
||||
你：用 sources/report.pdf 做 deck,模板用 skills/ppt-master/templates/layouts/academic_defense/
|
||||
```
|
||||
|
||||
完整说明 → [模板指南](./templates-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 做出第一份 deck
|
||||
|
||||
整个流程就三步。先装好环境——只需要 Python,见 [快速开始](../../README_CN.md#快速开始)。
|
||||
|
||||
1. **把源材料放进** `projects/` —— PDF、DOCX、Markdown、一个网址,或直接要粘贴的文字。
|
||||
2. **在对话里告诉 AI** 要把什么做成 deck(如果上面准备了模板,把它的路径一起给;否则就是自由设计):
|
||||
```
|
||||
你：用 projects/q3-report/sources/report.pdf 做一份 PPT
|
||||
你：把这份内容做成 PPT：<粘贴你的文字>
|
||||
```
|
||||
3. **拿回可编辑的 `.pptx`**,位于 `exports/<名称>_<时间戳>.pptx` —— 真正的 DrawingML 形状、文本框、图表,在 PowerPoint / Keynote / WPS / LibreOffice 里点开就能改。
|
||||
|
||||
开始前 AI 会先确认一份简短的设计规格(模板、格式、页数……);之后内容分析、排版、配图、SVG 生成、导出都由它完成——这就是其它能力围绕的核心环节。
|
||||
|
||||
---
|
||||
|
||||
## 实时预览与可视化修改
|
||||
|
||||
生成过程中会自动打开浏览器预览 `http://localhost:5050`。
|
||||
|
||||
- **实时看着每页渲染**出来。
|
||||
- **直接改,无需 AI** —— 选中元素后在右栏改文字、颜色、字体、字号;拖拽即可移动,或用方向键微调(`Shift` = 10px),`Ctrl+Z` 撤销。改动即时预览,点 **Apply changes** 写回 `svg_output/`。
|
||||
- **或写注解交给 AI** —— 点选元素写一句要改成什么,点 **Submit annotations**,再回对话说"应用注解"(或 "apply my annotations"),AI 会改写那块区域并重新导出 PPTX。
|
||||
|
||||
PPT Master 最初是纯对话设计;可视化编辑是在很多用户提出后融入的(建立在 [@WodenJay](https://github.com/WodenJay) 的 [PR #85](https://github.com/hugohe3/ppt-master/pull/85) 之上)。
|
||||
|
||||
完整说明 → [实时预览工作流](../../skills/ppt-master/workflows/live-preview.md)
|
||||
|
||||
---
|
||||
|
||||
## 转场与动画
|
||||
|
||||
导出的 deck 自带**页间转场**和**页内元素入场动画**,输出为真正的 OOXML——不是嵌入视频。默认元素进入页面时自动级联入场,无需设置,在 PowerPoint 和 Keynote 中原生播放,无需额外工具。只有当你想要特定顺序、效果或时序时,才需要定制。
|
||||
|
||||
完整说明 → [转场与动画](./animations.md)
|
||||
|
||||
---
|
||||
|
||||
## 旁白与视频
|
||||
|
||||
把演讲者备注按页生成语音旁白,把音频嵌回 PPTX,再用 PowerPoint 导出带旁白和转场的 MP4——无需第三方工具。
|
||||
|
||||
```
|
||||
你：给这个 PPT 生成音频,并把音频嵌回重新导出
|
||||
你：给这个 PPT 生成音频
|
||||
```
|
||||
|
||||
旁白默认用 `edge-tts`(约 90 种语区);需要更高质量音色可配置云端 provider。AI 会按 deck 语言推荐音色,生成前只问你一次。
|
||||
|
||||
完整说明 → [音频旁白与视频导出](./audio-narration.md)
|
||||
|
||||
---
|
||||
|
||||
## 使用复刻音色
|
||||
|
||||
用 ElevenLabs / MiniMax / Qwen / CosyVoice 复刻你自己的声音(或在授权前提下复刻演讲者的声音),让整份 deck 用 *你的声音* 念出来。在 provider 控制台复刻一次,把得到的 `voice_id` 传进来,PPT Master 就会用这个音色逐页朗读备注并嵌回 PPTX。
|
||||
|
||||
完整说明 → [使用复刻音色](./audio-narration.md#使用复刻音色)
|
||||
|
||||
---
|
||||
|
||||
## 遇到问题怎么办
|
||||
|
||||
[常见问题(FAQ)](./faq.md) 是持续更新的排查真值——来自真实用户反馈。最常见情况的快速指引:
|
||||
|
||||
| 情况 | 先试这个 |
|
||||
|---|---|
|
||||
| AI 跑偏或漏了步骤 | 让它重新读 `skills/ppt-master/SKILL.md`。 |
|
||||
| 视觉质量不理想 | 换成大上下文 Claude 模型 + `gpt-image-2`——harness 决定下限,模型决定上限。 |
|
||||
| 文字溢出或元素重叠 | 重跑那一页,或用实时预览修;详见 [FAQ](./faq.md)。 |
|
||||
| 没有生图 API key | 零配置的网络图片搜索仍可作为兜底;见 [FAQ](./faq.md)。 |
|
||||
| 动画或部分效果在别的软件里不对 | 文件是标准 `.pptx`,PowerPoint / Keynote / WPS / LibreOffice 都能打开;元素动画在 PowerPoint 2016+ 和 Keynote 还原最完整,更老的 Office 会把部分效果降级为 Appear。 |
|
||||
| 担心长 deck 撑爆上下文 | 生成可走分段模式;详见 [FAQ](./faq.md)。 |
|
||||
|
||||
模型选择、费用、图表可编辑性、自定义模板等,都在 [FAQ](./faq.md) 里。
|
||||
108
agent/skills-disabled/ppt-master/docs/zh/roadmap.md
Normal file
108
agent/skills-disabled/ppt-master/docs/zh/roadmap.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Roadmap
|
||||
|
||||
[English](../roadmap.md) | [中文](./roadmap.md)
|
||||
|
||||
---
|
||||
|
||||
> PPT Master 是单人维护的开源项目，按**优先级**而非时间表推进。这份 roadmap 用来统一对外预期：已经做了什么、在持续维护演进什么、暂时不打算做什么。优先级会随用户反馈和实际使用信号调整，不承诺时间窗口。
|
||||
>
|
||||
> 项目当前定位：**AI 从零生成 SVG → DrawingML 原生可编辑 PPTX**。这条路线的核心是「跨四渲染器的位置保真 + 真原生形状」，所有方向都围绕这条主轴展开。
|
||||
|
||||
---
|
||||
|
||||
## 近期能力演进
|
||||
|
||||
近两个月的能力面扩张。只列结构性的，单 flag / 增量优化看 commit log。
|
||||
|
||||
### 2026-03（真原生 PPTX 路线成型）
|
||||
|
||||
- **直接导出原生可编辑 PPTX** — `svg_to_pptx` 补齐 glow / rotate / text-decoration / stroke-linejoin，整条 SVG → DrawingML 链路开始可用
|
||||
- 图表 / 布局模板 JSON 索引上线，AI 选型路径打通
|
||||
|
||||
### 2026-04（管线规模化）
|
||||
|
||||
- **无源生成**：`topic-research` 工作流支持「只给主题、不给源文件」
|
||||
- **PPTX 导出质变**：SVG clipPath → DrawingML picture geometry、marker → 原生箭头、输出归集到 `exports/`
|
||||
- **图表库 70 个 + 图标三库**（simple-icons / phosphor-duotone / brand-logo）
|
||||
- **`spec_lock.md` 机器可读契约**：Strategist 锁定后 Executor 每页强制重读，跨页一致性有了保证
|
||||
- **元素级动画默认开启** + 旁白音频 / 视频导出([`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md))
|
||||
|
||||
### 2026-05（视觉编辑 + AI 图系统化）
|
||||
|
||||
- **Live Preview 进入主流程**（[`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)） — 浏览器实时预览 + 点选元素写要求 + 「apply my annotations」让 AI 重做该区域（基于 [@WodenJay](https://github.com/WodenJay) [PR #85](https://github.com/hugohe3/ppt-master/pull/85)）
|
||||
- **任意 PPTX 复刻为模板**（[`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)） — PPTX → SVG 逆向 + OOXML 主题 / 母版 / 版式 / 资源提取
|
||||
- **AI 图三维系统** rendering × palette × type + Strategist h.5 锁定，下游消费固定契约
|
||||
- **AI 图 `hero_page` 双档** — 局部插图 + 整页主角图共存
|
||||
- **品牌身份预设子系统**（[`workflows/create-brand.md`](../../skills/ppt-master/workflows/create-brand.md)） — 提取并复用品牌色板 / 字体 / Logo / 语调
|
||||
- **视觉自检工作流**（[`workflows/visual-review.md`](../../skills/ppt-master/workflows/visual-review.md)） — 按 rubric 逐页自查 AI 生成的 SVG
|
||||
- **AI 图 Type 概念边界澄清** — Type 收窄回「local 信息图的内部几何骨架」(11 个真骨架);原 4 个伪 type (hero/background/portrait/typography) 折回 `page_role: hero_page` + 4 条构图通则(single-subject / portrait / typographic / atmospheric);hero_page 文字分层规则(关键视觉词 embedded、可改文字走 SVG)
|
||||
- **Brutalist AI 报章示例 deck 交付**（[`examples/ppt169_brutalist_ai_newspaper_2026/`](../../examples/ppt169_brutalist_ai_newspaper_2026/)） — P0 三档第一档落地：满版小字 + 不规则栏宽 + halftone 黑白图 + 单点红 + 真原生 shape，10 页编辑部年报实压「文字位置精度 + 跨页一致性」
|
||||
- **Kubernetes Blueprint 示例 deck 交付**（[`examples/ppt169_kubernetes_blueprint_2026/`](../../examples/ppt169_kubernetes_blueprint_2026/)） — P0 三档第二档落地：等距工程图美学 + 蓝图青/琥珀色板 + 全手写 SVG 几何（无 raster 图）+ 自定义"逐笔绘制"动画，10 页 Kubernetes 架构走读实压「几何形状泛化 + chart 结构扩展性」
|
||||
- **AI 图 `custom` 兜底出口** — `rendering` / `palette` / hero 构图三处允许声明 `custom` + 一段 `*_behavior` prose，替换原"找不到匹配就硬塞 vector-illustration / cool-corporate"的假兜底；端到端契约：[`image-renderings/_index.md`](../../skills/ppt-master/references/image-renderings/_index.md) §1.5 + [`image-palettes/_index.md`](../../skills/ppt-master/references/image-palettes/_index.md) §2 + Strategist h.5 hard-rule（每维 ≤1 custom，单候选可双 custom）+ spec_lock 字段 + Image_Generator Step 2 消费分支
|
||||
- **Template 架构三分类收口**（[`docs/zh/templates-architecture.md`](./templates-architecture.md)） — brand / layout / deck 三独立目录 + 每类独立 schema + 段级合成 + git-style 冲突解决；SKILL.md Step 3 按 kind 分支处理，触发规则仍是「显式路径才触发」
|
||||
- **Pattern 填充 PPTX 安全网** — `svg_quality_checker.py` 现在对未标 `data-pptx-pattern` 的 `<pattern>` 元素发 warning（会静默回退 `ltUpDiag` 斜纹）、对超出 OOXML `ST_PresetPatternVal` 枚举的值发 error（schema 校验失败 PPT 无法打开）；`shared-standards.md §7` 落地了完整 preset 清单和 `<rect fill="<bg>"/>` 子元素约定
|
||||
- **LaTeX 数学公式渲染上线**（[`scripts/latex_render.py`](../../skills/ppt-master/scripts/latex_render.py)） — Strategist 在 Typography 确认中锁定 `mixed` / `render-all` / `text-only` 三档策略，显式写 `images/formula_manifest.json`；脚本走 codecogs → quicklatex → mathpad → wikimedia 四源 fallback chain，输出透明 PNG 进 §VIII 表的 `Acquire Via: formula` / `Status: Rendered` 行；公式密集型 deck（学术 / 工程 / 教学）首次拥有原生渲染路径，规则面禁止扫源文件 `$...$` 自动渲染（公式选取是 Strategist 决策）
|
||||
- **实时预览直接编辑 — L1 / L2 / L3**（[`workflows/live-preview.md`](../../skills/ppt-master/workflows/live-preview.md)） — 浏览器编辑器新增无需 AI 往返的确定性就地编辑：文字内容（L1）、fill / stroke / font-size 等样式属性（L2）、以及画布上的几何操作（L3）——在选中元素上拖拽即移动、方向键微调（`Shift` = 10px）、多选、加右键重叠选择器选取堆叠元素。编辑支持 `Ctrl+Z` 撤销 + 合并，点 **Apply changes** 写回 `svg_output/`；移动经 finalize / 导出保位（移动的 text、提升的多行 tspan、重定位的 icon 都在 PPTX 中如实再现）。重新导出仍由对话触发；画布上的缩放手柄尚未实现（缩放走几何输入框）
|
||||
|
||||
---
|
||||
|
||||
## 持续维护方向
|
||||
|
||||
不承诺时间窗口的长期改进项。只列真方向，具体修复 / 单 flag 看 commit log。
|
||||
|
||||
- **Prompt 精简** — 在不降质量的前提下压缩各角色 prompt 的 token 占用、提升缓存命中率，带来间接的成本 / 速度改善。与下面「纯速度优化」一节互补：做间接优化，不做牺牲质量的提速。
|
||||
|
||||
---
|
||||
|
||||
## 明确不做（Non-goals）
|
||||
|
||||
下面这些方向被多次提过，已经评估并决定**不做**。列出来不是否定需求价值，而是说明它们与本项目主路线不匹配；如果你刚好需要这些能力，建议看其他工具或 fork 本项目走自己的路。
|
||||
|
||||
### 读取任意 PPTX 模板 → 仅填充文字
|
||||
|
||||
**对应 Issue**：[#53](https://github.com/hugohe3/ppt-master/issues/53)、[#118](https://github.com/hugohe3/ppt-master/issues/118)
|
||||
|
||||
PPT Master 主路线是「AI 从零生成 SVG → DrawingML」，整条管线围绕完全可控的形状/文字/版式构建。「解析既有 PPTX 占位符 + 仅回填文字」是另一种产品形态，需要处理任意来源的母版 / 主题 / 占位符体系，与现有架构发力点正交。
|
||||
|
||||
**基础诉求其实很简单**：如果只是「固定位置替换 Excel 数据到 PPT 模板」，直接让 AI 写一段 `python-pptx` 脚本即可，几行代码搞定，不需要本项目这套管线。
|
||||
|
||||
### 改用原生 PowerPoint 图表（Excel-native chart）
|
||||
|
||||
**对应 Issue**：[#99](https://github.com/hugohe3/ppt-master/issues/99)、[#100](https://github.com/hugohe3/ppt-master/issues/100) 类
|
||||
|
||||
跨四渲染器（PowerPoint / Keynote / LibreOffice / WPS）的位置保真是项目主轴。改用 PowerPoint 原生图表会让「像素级一致性」破功——同一个 PPTX 在不同渲染器里图表会显示不同布局。图表用 SVG 是 **by design**，不是能力缺失。
|
||||
|
||||
如果需要数据驱动的原生 Excel 图表，建议另选工具或在导出后用 PowerPoint 手动替换；本项目不会内置这条路径。
|
||||
|
||||
### uv 作为默认 / 必需依赖
|
||||
|
||||
**对应 Issue**：[#111](https://github.com/hugohe3/ppt-master/issues/111)
|
||||
|
||||
`pip + requirements.txt` 是唯一官方安装路径，因为它在所有 Python 环境下都可用、不需要额外学习成本。uv 是好工具，但「让 uv 成为默认」会抬高新用户的入门门槛。如果你个人偏好 uv，完全可以在 fork 里用，不影响主线。
|
||||
|
||||
### 纯速度优化
|
||||
|
||||
**对应 Issue**：[#97](https://github.com/hugohe3/ppt-master/issues/97)
|
||||
|
||||
成本 / 速度 / 质量三角下，本项目选择**质量优先**。20 分钟生成一个高质量 PPTX 是当前的合理点。
|
||||
|
||||
会做：通过 prompt 精简 / 缓存命中率提升带来的间接改善；
|
||||
不会做：以牺牲质量为代价的「随便几页应付交差」式提速。
|
||||
|
||||
如果对速度敏感且能接受质量下降，Gamma / 美图 AI 等竞品更合适。
|
||||
|
||||
### CLI / SaaS / 桌面 App 形态
|
||||
|
||||
产品形态明确为 **chat-driven AI IDE skill**（Claude Code / Cursor / VS Code + Copilot / Codebuddy）。
|
||||
|
||||
不会做：独立 CLI（`ppm` 之类）、SaaS Web 服务、Electron 桌面壳。所有「让它脱离 chat 独立运行」的提案都会被拒。chat 是交互核心，不是包装层。
|
||||
|
||||
---
|
||||
|
||||
## 反馈渠道
|
||||
|
||||
- **Issues**：[github.com/hugohe3/ppt-master/issues](https://github.com/hugohe3/ppt-master/issues) — 报告 Bug / 提建议
|
||||
- **Discussions**：[github.com/hugohe3/ppt-master/discussions](https://github.com/hugohe3/ppt-master/discussions) — 用法讨论 / 经验分享
|
||||
- **邮箱**：heyug3@gmail.com
|
||||
|
||||
提需求前先扫一眼上面的 **Non-goals**；如果你的需求落在那一节，多半不会被采纳，但欢迎讨论是否还有别的路径解决你的真实问题。
|
||||
299
agent/skills-disabled/ppt-master/docs/zh/technical-design.md
Normal file
299
agent/skills-disabled/ppt-master/docs/zh/technical-design.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# 技术路线
|
||||
|
||||
[English](../technical-design.md) | [中文](./technical-design.md)
|
||||
|
||||
---
|
||||
|
||||
## 设计哲学 —— AI 是你的设计师，不是完工师
|
||||
|
||||
生成的 PPTX 是一份**设计稿**，而非成品。把它理解成建筑师的效果图：AI 负责视觉设计、排版布局和内容结构，交付给你一个高质量的起点。要想获得真正精良的成品，**需要你自己在 PowerPoint 里做精装修**：换掉形状、细化图表、调整配色、把占位图形替换成原生对象。这个工具的目标是消除 90% 的从零开始的工作量，而不是替代人在最后一公里的判断。不要指望 AI 一遍搞定所有——好的演示文稿从来不是这样做出来的。
|
||||
|
||||
**工具的上限是你的上限。** PPT Master 放大的是你已有的能力——你有设计感和内容判断力，它帮你快速落地；你不知道一个好的演示文稿应该长什么样，它也没法替你知道。输出的质量，归根结底是你自身品味与判断力的映射。
|
||||
|
||||
---
|
||||
|
||||
## 系统架构
|
||||
|
||||
```
|
||||
用户输入 (PDF/DOCX/XLSX/URL/Markdown)
|
||||
↓
|
||||
[源内容转换] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py
|
||||
↓
|
||||
[创建项目] → project_manager.py init <项目名> --format <格式>
|
||||
↓
|
||||
[模板处理（可选）] — 默认跳过，直接自由设计
|
||||
用户主动点名模板时：复制模板文件到项目目录
|
||||
需要新建全局模板：使用 /create-template 工作流单独完成
|
||||
↓
|
||||
[Strategist] 策略师 - 八项确认与设计规范 → design_spec.md + spec_lock.md
|
||||
↓
|
||||
[Image Acquisition] 图片获取（当资源列表中有需要 AI 生成或网络搜索的图片时）
|
||||
↓
|
||||
[Executor] 执行师
|
||||
├── 视觉构建：连续生成所有 SVG 页面 → svg_output/
|
||||
├── [Quality Check] svg_quality_checker.py（强制通过，0 错误）
|
||||
└── 讲稿生成：完整讲稿 → notes/total.md
|
||||
↓
|
||||
[图表校准（可选）] → verify-charts 工作流（含数据图表的幻灯片在此步骤校准坐标）
|
||||
↓
|
||||
[视觉自检（可选，opt-in）] → visual-review 工作流（仅在用户明确请求时触发）
|
||||
↓
|
||||
[后处理] → total_md_split.py（拆分讲稿）→ finalize_svg.py → svg_to_pptx.py
|
||||
↓
|
||||
输出：
|
||||
exports/
|
||||
├── presentation_<timestamp>.pptx ← 原生形状版（DrawingML）— 唯一标准产物，编辑/交付从这里走
|
||||
└── presentation_<timestamp>_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考（加 --svg-snapshot 时生成）
|
||||
|
||||
# 默认流程（未指定 -o）始终写入
|
||||
backup/<timestamp>/
|
||||
└── svg_output/ ← Executor 原始 SVG 备份（重跑 finalize_svg → svg_to_pptx 即可重建 pptx）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技术流程
|
||||
|
||||
**核心流程：AI 生成 SVG → 后处理转换为 DrawingML（PPTX）。**
|
||||
|
||||
整个流程分为三个阶段：
|
||||
|
||||
**第一阶段：内容理解与设计规划**
|
||||
源文档（PDF/DOCX/URL/Markdown）经过转换变为结构化文本，由 Strategist 角色完成内容分析、页面规划和设计风格确认，输出完整的设计规格。
|
||||
|
||||
**第二阶段：AI 视觉生成**
|
||||
Executor 角色逐页生成演示文稿的视觉内容，输出为 SVG 文件。这个阶段的产物是**设计稿**，而非成品。
|
||||
|
||||
**第三阶段：工程化转换**
|
||||
后处理脚本将 SVG 转换为 DrawingML，每一个形状都变成真正的 PowerPoint 原生对象——可点击、可编辑、可改色，而不是嵌入的图片。
|
||||
|
||||
---
|
||||
|
||||
## 为什么是 SVG？
|
||||
|
||||
SVG 是这套流程的核心枢纽。这个选择是通过逐一排除其他方案得出的。
|
||||
|
||||
**直接生成 DrawingML** 看起来最直接——跳过中间格式，AI 直接输出 PowerPoint 的底层 XML。但 DrawingML 极其繁琐，一个简单的圆角矩形就需要数十行嵌套 XML，AI 的训练数据中远少于 SVG，生成质量不稳定，调试几乎无法肉眼完成。
|
||||
|
||||
**HTML/CSS** 是 AI 最熟悉的格式之一，但 HTML 和 PowerPoint 有根本不同的世界观。HTML 描述的是**文档**——标题、段落、列表，元素的位置由内容流动决定。PowerPoint 描述的是**画布**——每个元素都是独立的、绝对定位的对象，没有流，没有上下文关系。这不只是排版计算的问题，而是两种完全不同的内容组织方式之间的鸿沟。就算解决了浏览器排版引擎的问题（Chromium 用数百万行代码做这件事），HTML 里的一个 `<table>` 也没法自然地变成 PPT 里的几个独立形状。
|
||||
|
||||
**WMF/EMF**（Windows 图元文件）是微软自家的原生矢量图形格式，与 DrawingML 有直接的血缘关系——理论上转换损耗最小。但 AI 对它几乎没有训练数据，这条路死在起点。值得注意的是：连微软自家的格式在这里都输给了 SVG。
|
||||
|
||||
**SVG 作为嵌入图片** 是最简单的路线——把整张幻灯片渲染成图片塞进 PPT。但这样完全丧失可编辑性，形状变成像素，文字无法选中，颜色无法修改，和截图没有本质区别。
|
||||
|
||||
SVG 胜出，因为它与 DrawingML 拥有相同的世界观：两者都是绝对坐标的二维矢量图形格式，共享同一套概念体系：
|
||||
|
||||
| SVG | DrawingML |
|
||||
|---|---|
|
||||
| `<path d="...">` | `<a:custGeom>` |
|
||||
| `<rect rx="...">` | `<a:prstGeom prst="roundRect">` |
|
||||
| `<circle>` / `<ellipse>` | `<a:prstGeom prst="ellipse">` |
|
||||
| `transform="translate/scale/rotate"` | `<a:xfrm>` |
|
||||
| `linearGradient` / `radialGradient` | `<a:gradFill>` |
|
||||
| `fill-opacity` / `stroke-opacity` | `<a:alpha>` |
|
||||
|
||||
转换不是格式错配，而是两种方言之间的精确翻译。
|
||||
|
||||
SVG 也是唯一同时满足流程中所有角色需要的格式：**AI 能可靠地生成它，人能在任意浏览器里直接预览和调试，脚本能精确地转换它**——在生成任何 DrawingML 之前，设计稿就已经完全透明可见。
|
||||
|
||||
---
|
||||
|
||||
## 源内容转换
|
||||
|
||||
源文档（PDF / DOCX / EPUB / XLSX / PPTX / 网页）在流水线启动前先被归一化为 Markdown——这是 Strategist 阅读的事实源。两个设计选择塑造了转换器：
|
||||
|
||||
**Native-Python 优先，外部二进制兜底。** 常见格式由纯 Python wheel 处理，pandoc 仅在长尾的小众格式时才被调用。让每个用户都去装一份可能没有权限装的系统级二进制是一种可用性税，而 95% 的输入是 docx / pdf / html，付这种税不划算。
|
||||
|
||||
**TLS 指纹模拟应对高安全站点。** 网页抓取默认模拟 Chrome TLS 指纹。微信公众号和不少 CDN 直接屏蔽 Python 默认 `requests` 握手；用一个依赖把这事一并解决，比维持一份 Node.js 抓取器作为主路径更划算。
|
||||
|
||||
---
|
||||
|
||||
## 项目结构与生命周期
|
||||
|
||||
项目布局里非显然的一点是 `import-sources` 的**非对称默认**：仓库**外**的文件默认 *copy*（保留用户原件），仓库**内**的文件默认 *move*（避免中间产物被误提交）。这种不对称恰好对应自然的风险画像——仓库外的文件一般是用户资产、不该动；仓库内的文件一般是临时产物、应该清理。一个统一默认无论选 copy 还是 move，每次都会在另一种场景出错。
|
||||
|
||||
---
|
||||
|
||||
## Canvas 格式系统
|
||||
|
||||
PPT Master 不只服务 PPT——同一套 SVG → DrawingML 流水线还能产出方形海报、9:16 故事、A4 印刷品。各格式特定的约定（比例、安全区、品牌区等）住在 [`references/canvas-formats.md`](../../skills/ppt-master/references/canvas-formats.md)。
|
||||
|
||||
值得标注的架构选择：**viewBox 是像素，不是绝对单位。** 像素空间让 AI Executor 思考布局没有歧义（`x="100"` 就是左缘 +100px），人类在浏览器里检查也直接。到 EMU 的换算只在导出时发生一次——选像素意味着流水线的其余环节（Strategist、Executor、质量检查、后处理）永远不需要在 EMU 思维下工作，那对 AI 生成和人类调试都是敌对的。
|
||||
|
||||
---
|
||||
|
||||
## 模板系统与可选路径
|
||||
|
||||
模板是**可选项，不是默认**。Strategist 默认走自由设计——AI 完全凭源内容创造视觉系统。模板路径只在用户显式触发时启用。
|
||||
|
||||
**为什么默认自由设计。** 模板是地板，但很容易变成天花板：它会把整个 deck 锁进模板自有的视觉惯用语，无视内容本身想要怎样被呈现。自由设计的布局从源内容的结构推导而来，而不是从一套固定语法套上去——视觉节奏跟着内容走，而不是跟内容打架。约束模式在窄场景里确实更好（品牌锁定的 deck、强类型场景如学术答辩或政府报告），所以它一直在；但 AI 不主动去抓，是用户去抓。
|
||||
|
||||
**不主动匹配。** AI 不会基于内容向用户推荐、暗示或自动映射模板。即便某份 deck 看起来"明显适合"库里某个模板，没有用户点名，AI 也保持沉默，按自由设计走。理由是可靠性优先于发现性：把内容与模板做匹配是会随库演进而漂移的判断，一句错误的"或许你想用 X"会把用户推向 AI 本就无法可靠承诺的选择。发现性交给文档（三类各自的 `templates/{brands,layouts,decks}/README.md`）和显式查询路径（"有哪些模板可以用？"）承担，不放进运行时 prompt。
|
||||
|
||||
**布局是 opt-in，图表和图标不是。** 这种不对称不是矛盾——*布局*正是锁定视觉惯用语的那一层（地板/天花板问题），而图表和图标是不会施加 deck 级风格约束的复用原语。同一个 `templates/` 目录，但在视觉契约里扮演的角色不同。
|
||||
|
||||
---
|
||||
|
||||
## 角色系统：单一流水线中的三个专业代理
|
||||
|
||||
PPT Master 用的是**单主代理内的角色切换**，不是并行子代理。这个选择有三条互相支撑的理由：
|
||||
|
||||
**为什么是单代理而非并行子代理。** 页面设计依赖完整的上游上下文——Strategist 的色彩选择、图片资源是否成功获取（还是失败被替代）、之前几页的视觉节奏。子代理拿到的只能是这个上下文的过期局部快照，产出的 deck 视觉会逐页漂。同一逻辑也禁止分批生成（比如一次 5 页）：分批加速上下文压缩，deck 的视觉一致性下降速度比节省的速度更快——不划算。
|
||||
|
||||
**为什么是角色专属 reference 而不是一个超大 prompt。** Strategist 跑的是「跟用户协商」模式（开放式、对话式、可以回退），Executor 跑的是「产出严格 XML」模式（不准即兴、不准漏属性）。把两者塞进同一个 prompt，强迫模型在同一个 turn 里持守相互矛盾的纪律——所有混合模式的 prompt 工程病灶都会出现。按角色拆开，每个角色只加载它需要的、扔掉其他。
|
||||
|
||||
**Eight Confirmations 是唯一的阻塞 gate。** Strategist 阶段以八项打包确认（画布 / 页数 / 受众 / 风格 / 配色 / 图标 / 排版 / 图像）作为单一阻塞决策点呈现给用户。确认后，流水线一路跑到结束，不再有用户中断点。打包且单一的理由：设计选项之间是相关的（配色影响图标库、影响排版），一起决能产出一致的决策；分散到各阶段确认会引入互相矛盾的用户输入，最后被迫回退重做。
|
||||
|
||||
**用户已有图片走元数据，不读像素。** 用户自带图片时，Strategist 跑的是一个抽取器，把尺寸、EXIF 方向、主色调、主体内容总结成文本，然后基于这份文本推理。直接读图片字节是被禁的，因为 LLM 做布局决策不需要像素，需要的是能塞进一页的事实（用宽高比定位置、用色调判定调色板兼容、用主体决定哪页放）。读像素只会消耗上下文而不带来决策质量收益。
|
||||
|
||||
**逐页 spec_lock 重读** 是长 deck 的抗漂移机制——完整理由见下面的 § 设计规范的传播。
|
||||
|
||||
---
|
||||
|
||||
## 执行纪律
|
||||
|
||||
流水线由 [`SKILL.md` § 全局执行纪律](../../skills/ppt-master/SKILL.md) 中的 8 条规则强制——那份文件是权威，规则住在那里。它们看起来很官僚，但存在的理由是：LLM 默认行为是「让我在这一 turn 里把整个问题搞定」，而这恰好是串行流水线最不该有的形状——串行流水线要求每一步的输出都是有界、过 checkpoint、被下一步消费的。这套规则共同关闭了实际反复出现的失败模式：乱序执行、AI 代为做用户设计决策、跨阶段打包、前置条件未满足、投机预先准备、子代理上下文丢失、分批漂移、长 deck 色彩字体漂移。
|
||||
|
||||
角色切换协议（切换模式前必须 `read_file references/<role>.md`）有两个互相支撑的作用：把新鲜的角色指令载入上下文，覆盖前一模式的漂移；对话 transcript 中的可见标记构成审计轨迹，让用户能看到 agent 何时切换了模式——回看一个具体决策为什么这样做时，这条线索很关键。
|
||||
|
||||
---
|
||||
|
||||
## 设计规范的传播：spec_lock.md 作为执行契约
|
||||
|
||||
Strategist 阶段产出两份看起来冗余但服务不同对象的产物：
|
||||
|
||||
- `design_spec.md` —— 人类可读叙述；设计的「为什么」（目标受众、风格目标、配色理由、页面大纲）
|
||||
- `spec_lock.md` —— 机器可读执行契约；Executor 必须**字面照搬**的「是什么」（HEX 颜色、确切的 font family 字符串、图标库选择、带状态的图片资源列表）
|
||||
|
||||
为什么两份都要？没有 `spec_lock.md` 的话，Executor 在长 deck 里会逐页重读 `design_spec.md`，LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`，让数值在 20+ 页里保持字面一致。
|
||||
|
||||
`update_spec.py` 把生成后的修改用两个协调步骤传播：把新值写入 `spec_lock.md`，然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`（HEX 值，大小写不敏感替换）和 `typography.font_family`（属性级）。其他字段（字号、图标、图片、画布）**有意不支持**——它们的替换需要属性级或语义级理解，风险/收益不值得做批量传播。这些情况手动改 `spec_lock.md` 然后重做受影响的页面。
|
||||
|
||||
工具拒绝做备份：依赖 git 回滚。加备份机制只是重复 git 的工作，还会留下过时快照。
|
||||
|
||||
---
|
||||
|
||||
## 图片获取与嵌入
|
||||
|
||||
这一阶段有三个架构层面的决策：
|
||||
|
||||
**provider 专属 config key，不用通用 `IMAGE_API_KEY`。** 每个 backend 用自己的 `OPENAI_API_KEY` / `MINIMAX_API_KEY` 等等，当前 backend 由显式的 `IMAGE_BACKEND=<name>` 选定。统一的 `IMAGE_API_KEY` 字段第一眼看着干净，但当用户同时配了多个 provider 又不确定哪个在生效时会造成静默混乱——这种 fault 通常只表现为「图像生成结果怪怪的」，找不到清晰失败点。强制 per-provider key 让「我现在用的是哪个 backend」从推理变成可读配置。
|
||||
|
||||
**默认宽松 license 过滤，配以严格模式应对没法放致谢的版面。** 网络图片搜索默认允许 CC BY / CC BY-SA 加内联致谢——大部分幻灯片都有视觉空间放一个致谢元素。`--strict-no-attribution` 是给全屏 hero image 和紧凑构图的逃生口，那些场景没法放致谢又不打破设计。NC（CC BY-NC*）和 ND（CC BY-ND*）自动拒绝，因为 PPT Master 的典型产物会用于商用或修改场景；宽松默认 + 这个底线正好对应用户实际想要的 fail-mode。
|
||||
|
||||
**开发期外部引用，交付期分叉成两套嵌入策略。** 在 `svg_output/` 里编辑时，图片是外部文件引用——快速迭代、单点替换。两份交付产物随后分叉：`svg_final/` 走 Base64 内联（产出一组自包含 SVG，IDE 预览、浏览器、preview pptx 都能开而不丢位图依赖）；native pptx 反过来把位图复制进 PPTX 的 media 文件夹，用 `<a:srcRect>` 表达裁剪。分叉的理由：在 DrawingML 里塞 Base64 能跑但文件膨胀 3-4 倍；文件引用的位图是 PowerPoint 原生表达方式，配 `<a:srcRect>` 的裁剪也是 DrawingML 的规范写法——任一方向用错工具都要付出可编辑性或文件大小的代价。
|
||||
|
||||
**AI 图片三维系统：Strategist 阶段就锁定。** 当 deck 包含 AI 生成图片时，Strategist 在前置阶段一次性确定三个正交维度——`rendering`（视觉风格家族：vector-illustration / editorial / 3d-isometric / sketch-notes / ……）、`palette`（deck 的 HEX 在图里**怎么用**：比例 + 角色 + 气质）、`type`（每张图的内部构图：background / hero / framework / comparison / ……）。前两个是 deck 级、写进 `spec_lock.md`；Image_Generator 此后每张图的 prompt 都从同一份锁定的 rendering + palette 加上该图的 type 组装出来，而不是逐图重决风格。没有这层锁定，每张图都会自己风格漂移，整套 deck 读起来就是一摞互不相关的插画。这是 `spec_lock` 字体/色彩抗漂移机制在像素上游的对偶——同一思路，往前推一层。Strategist 在八项确认阶段会向用户呈现 **≥3 个 `rendering × palette` 候选**，绝不静默地自动锁定单一组合，因为这是一个会牵动全 deck 视觉的选择，唯一权威只有用户的品味。
|
||||
|
||||
---
|
||||
|
||||
## 图文版式：Primary 主结构 + Modifier 修饰层
|
||||
|
||||
「图片**怎么放上幻灯片**」的词表（完整词汇在 [`references/image-layout-patterns.md`](../../skills/ppt-master/references/image-layout-patterns.md)）把 72 条编号技法拆成两层、自由组合：
|
||||
|
||||
- **Primary 主结构**（容器布局 / 图作画布 + 原生覆盖 / 多图组合）—— 页面的骨架。一页可一个也可多个；跨 Primary 的组合，如「侧边对比 + 图作画布的注解卡」，是合规的。
|
||||
- **Modifier 修饰层**（非矩形裁剪 / 遮罩与叠加 / 纹理 / 特殊技法）—— 装饰层。一页可叠任意多个，附着在 Primary 之上。
|
||||
|
||||
**为什么显式鼓励复合，而不是「一页一个 primary」。** 这份词表对抗的 AI 失败模式不是「叠太多」，而是「用得太少」——把每页图片默认堆成裸的 `#2 左三分` 或 `#48 侧边对比`，Modifier 层完全不动，产出视觉扁平的「AI 默认感」版式。早先的规则「一页一个 primary，modifier 可叠」听起来有原则，实际上加剧了 Modifier 层的弃用——AI 把它读作「可以不叠」的许可。现在的措辞反过来：组合是常态，单 Primary + 无 Modifier 才需要解释。
|
||||
|
||||
**为什么物理拆分两层，而不是只打标签。** 词表被重排成「Primary 全部在前，Modifier 全部在后」——Strategist 或 Executor 读一次目录，就能从结构上内化「两层」心智模型。编号是稳定 id（`#38` 永远是「图作画布 + 注解卡」，不论它在文件里的物理位置），所以 `spec_lock.md`、`design_spec.md §VIII`、历史 executor 输出、过往示例里所有 `#<id>` 引用照样解析。
|
||||
|
||||
**为什么组合走 Strategist 资源列表，不只交给 Executor 临场发挥。** `§VIII 图片资源列表` 的 `Layout pattern` 列接受 `#<id> + #<id> ...` 表达式——Primary id 加可选 Modifier id——所以组合在 SVG 生成**之前**就被声明、被 `svg_quality_checker` 审计、并能在 session 重入后存活。把组合责任只压在 Executor 身上，长 deck 上下文压缩时就会丢；把它编码进 spec_lock 旁的资源列表，组合就成为设计契约的一部分。
|
||||
|
||||
**为什么真正的硬约束留在上游。** 跨切的技术硬约束（`<clipPath>` 只能用在 `<image>` 上、用 `fill-opacity` 而非 `rgba()`、禁 `<mask>`、alpha 效果的路由表）独家住在 [`shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)。版式词表只用一行指针指向它们，不复述——这样某条约束放开时（比如某个 DrawingML 特性变得可靠），只有一个文件要改，词表里也不会留下一份过期副本继续暗中强制旧规则。
|
||||
|
||||
---
|
||||
|
||||
## SVG 约束：禁用特性与条件允许
|
||||
|
||||
PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份经验生长起来的黑名单（mask、style/class、`@font-face`、foreignObject、symbol+use、textPath、animate*、script/iframe ……）里运行，外加对 `marker-start`/`marker-end` 和仅 `<image>` 上的 `clip-path` 的窄条件允许。权威清单和每条特性的具体约束——包括 `<mask>` 的替代效果路由表（渐变叠加、clipPath、filter shadow、源图烘焙）——住在 [`references/shared-standards.md`](../../skills/ppt-master/references/shared-standards.md)。
|
||||
|
||||
值得在架构层标记的理由：
|
||||
|
||||
- **为什么是黑名单，不是白名单。** SVG 是个宽规范；穷举允许特性会随着 Executor 不断发现新的有用构造而要持续维护。黑名单只圈住语义上没有 DrawingML 表达的窄集合，其余隐式可用。
|
||||
- **为什么是经验性，不是从规范推导。** 这份清单从真实的 PPT 导出失败长出来，不是读 OOXML 规范读出来的。有几个特性（如 `<mask>`）理论上能在 DrawingML 表达，但跨 PowerPoint 版本不可靠；黑名单反映的是实际能交付的子集。
|
||||
- **XML 良构性陷阱。** 两个独立于 DrawingML 的跨切陷阱：排版字符必须用裸 Unicode（`—`、`→`、`©`、NBSP），HTML 命名实体（`—`）在 SVG 里是非法 XML；XML 保留字符（`& < >`）必须实体转义，否则 `R&D` 直接终止导出。这两个坑出现频率高到值得在架构层 flag 一下。
|
||||
- **黑名单在后处理之前执行。** `svg_quality_checker.py` 在 `svg_output/` 上执行；后处理会重写 SVG，会掩盖源级别违规。修复永远是 Executor 重新写——有意没有 auto-fix 模式（见 § 质量门）。
|
||||
|
||||
---
|
||||
|
||||
## 质量门
|
||||
|
||||
**为什么需要这道检查器。** LLM 生成的 SVG 不是确定性的——禁用特性会在长 deck 中悄悄混入，只在 `svg_to_pptx` 中途崩或 PowerPoint 静默丢元素时才暴露。检查器把「PowerPoint 在第 14 页导出失败」转化为「Executor 在第 14 页用了 `<style>`，重新生成它」，诊断速度提升一个数量级——这正是让长 deck 在经济上可迭代的关键。
|
||||
|
||||
**为什么放在后处理之前，而不是之后。** 后处理会重写 SVG（图标嵌入、图片内联），会掩盖源级别违规。直接读 `svg_output/` 抓的是 Executor 的实际输出，先于任何可能掩盖 bug 的清理动作。
|
||||
|
||||
**严重性模型：error 阻塞、warning 不阻塞，且有意没有 auto-fix。** error 要求 Executor 在上下文里重新写出错的页面——一个被禁的 `<style>` 元素不是机械 patch，因为 Executor 用它是有原因的，替代方案（比如改成内联属性）需要带着同样的设计意图重新落地。Auto-fix 会静默丢失这份意图，交付一个更难看的页面。
|
||||
|
||||
**为什么图表坐标验证挂在同一道 gate。** 图表页面有几何正确性需求（柱高、饼图扇角、坐标轴刻度位置），这些不是结构问题，SVG 合法性规则也抓不到。最自然的捕捉位置就是已经要求 AI 回看自己输出的那道 gate——把「看一眼你刚生成的东西然后修」的认知上下文打包到一个阶段，比把结构和几何审查分到两轮 review 更高效。
|
||||
|
||||
---
|
||||
|
||||
## 后处理流水线
|
||||
|
||||
> 工程化转换阶段中每一份产物和每一个模块为何存在，删除它会破坏哪些工作流。在考虑简化 `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py` 之前，先读这一节。
|
||||
|
||||
### 四份产物，四种工作流
|
||||
|
||||
后处理阶段产生四份产物。每一份都服务于一种流水线中无法替代的工作流。
|
||||
|
||||
| 产物 | 服务的工作流 | 为何无可替代 |
|
||||
| --- | --- | --- |
|
||||
| `svg_output/` | 唯一源、手工编辑入口、`update_spec.py`、`svg_quality_checker.py` | 流水线中唯一**手写**而非派生的目录 |
|
||||
| `svg_final/` | IDE 内即时预览（VSCode/Cursor 直接打开 `.svg`）、浏览器单页预览 | `.pptx` 在 IDE 里打不开；`svg_output/` 因图标 / 图片是外部引用，IDE 中渲染不完整 |
|
||||
| `exports/<name>_<ts>.pptx`（native） | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 |
|
||||
| `exports/<name>_<ts>_svg.pptx`（preview，需 `--svg-snapshot` 显式开启） | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开；`svg_final/` 是文件夹，分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 |
|
||||
| `backup/<ts>/svg_output/`（默认流程下始终生成） | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后，Executor 原始 SVG 唯一的留存副本 |
|
||||
|
||||
### `svg_finalize/` 包有**两种**消费者
|
||||
|
||||
这是读代码时容易忽略的关键事实。同一组 `skills/ppt-master/scripts/svg_finalize/` 下的模块，在两个地方被使用，服务两份不同的产物。
|
||||
|
||||
**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次。`svg_final/` 随后供 IDE 预览和 preview pptx 使用。
|
||||
|
||||
**内存消费者** —— native pptx 直接读 `svg_output/`（不经磁盘中转），但 DrawingML 无法内联处理两种 SVG 特性，所以转换器在内存中调用 `svg_finalize` 模块：
|
||||
|
||||
| 内存调用点 | 复用的模块 | native pptx 为何需要 |
|
||||
| --- | --- | --- |
|
||||
| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML 不识别 `<use data-icon="...">`；不展开图标会静默丢失 |
|
||||
| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML 文本块无法在段落中跳位置；`dy` 堆叠的多行 `<tspan>` 会塌成一行，`x` 锚定的 tspan 会跑到错误的列 |
|
||||
|
||||
### 各模块消费者一览
|
||||
|
||||
| 模块 | 写盘消费者 | 内存消费者 | 删除影响 |
|
||||
| --- | --- | --- | --- |
|
||||
| `embed_icons.py` | `finalize_svg` 的 `embed-icons` 步骤 | `svg_to_pptx/use_expander.py` | native pptx 丢失全部图标 + `svg_final/` 不再自包含 |
|
||||
| `flatten_tspan.py` | `finalize_svg` 的 `flatten-text` 步骤 | `svg_to_pptx/tspan_flattener.py` | **native pptx 中 `dy` 堆叠的多行文本塌成一行** |
|
||||
| `align_embed_images.py` | `finalize_svg` 的 `align-images` 步骤 | — | `svg_final/` 失去图片嵌入 → IDE 预览 / preview pptx 都没图 |
|
||||
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | 被 `align_embed_images.py` import | — | `align_embed_images` `ImportError`，整条链路 broken |
|
||||
| `svg_rect_to_path.py` | `finalize_svg` 的 `fix-rounded` 步骤 | — | 只影响 PowerPoint 内手动「Convert to Shape」时圆角丢失；浏览器 / IDE / PowerPoint 自带的 SVG 渲染器都正常 |
|
||||
|
||||
---
|
||||
|
||||
## Native PPTX 转换器内部
|
||||
|
||||
**为什么是逐元素派发而不是整体翻译。** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型——不需要一个全局优化器去重新规划幻灯片。每种形状都有自己窄的翻译器，简单到能单独调试和单元测试。一张幻灯片的最终质量等于这些独立局部转换之和；这个性质在整体翻译下脆弱，在元素派发下稳健。
|
||||
|
||||
**为什么 Office 兼容模式默认开启。** 2019 之前的 PowerPoint 不能原生渲染 SVG。转换器为每页生成 PNG 兜底，与原生形状并存——新版 Office 仍显示可编辑形状，旧版回退到 PNG。默认开启的取舍是：用适度的文件大小代价换取「不会静默地把打不开的 deck 交给跑老版本的用户」；逃生口给那些明确知道自己在新栈上、想要更小文件的用户。
|
||||
|
||||
---
|
||||
|
||||
## 动画与转场模型
|
||||
|
||||
值得讲的设计选择是动画**锚点**，不是效果列表。
|
||||
|
||||
**为什么把入场动画锚在顶层 `<g>` group。** PowerPoint 的动画时序基于形状 ID——每个被动画的对象需要稳定的 shape ID。给单个原语做动画会产出每页 30+ 个分别飞入的原子（动感泛滥），只给整页做动画又损失视觉叙事。顶层 group 是自然粒度：Executor 本来就被强制要求用 `<g id="...">` 标记逻辑内容块，而这些块正是观众读作「一个东西到达」的单位——动画对齐了已有的逻辑结构，而不是另立门户。
|
||||
|
||||
**为什么页面装饰自动跳过。** 名为 `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` 的 group 代表静态页面框架，不是内容；让它们飞入会让人出戏（页面本身在每次切换时具象化），几乎不会是用户想要的。按 id token 过滤原则上脆弱，实际上可靠——因为 token 词表很小，命名权又掌握在 Executor 手里。
|
||||
|
||||
**为什么对象级动画用 sidecar，而不是 SVG 属性。** SVG 继续作为静态视觉源。自定义 PPTX 动画属于导出策略，所以对象级覆盖放在可选的 `animations.json`，按 slide stem 和顶层 group id 关联。这样不会把 PowerPoint 专用元数据塞进 SVG，同时仍能在默认全局动画不够用时调整顺序、效果、延迟和时长。
|
||||
|
||||
**为什么录制旁白让自动推进时长跟着片段时长走。** 嵌入旁白意味着 deck 目标是视频导出——视频里没有演讲者去点击。把每页自动推进时长设为该页音频片段的实际时长，PowerPoint 能干净地导出为 MP4，无需人工配时。任何其他时长来源（估算朗读速度、固定每页时长）都会破坏音画同步。
|
||||
|
||||
**为什么录制旁白拒绝 on-click 对象动画。** PowerPoint 可以在真实排练时记录点击计时，但 PPT Master 不合成对象级点击事件。录制旁白路径只写页面级音频和页面自动推进计时，所以单击触发的对象入场会让导出依赖额外的 PowerPoint 人工排练。带旁白的 deck 必须使用无点击入场（`after-previous` 或 `with-previous`）。
|
||||
|
||||
---
|
||||
|
||||
## Standalone Workflows（独立工作流）
|
||||
|
||||
六个能力（`create-template`、`verify-charts`、`customize-animations`、`live-preview`、`generate-audio`、`visual-review`）作为独立工作流存在，而不是流水线步骤。每个都是稀疏触发的——按模板、按含图表的 deck、按一次动画微调、按一次具体抱怨、按一次视频导出、按用户明确请求的一次视觉自检，而不是按每个 deck。把任何一个塞进默认流水线，要么对大多数用户运行无意义的步骤（增加延迟和失败面），要么强制一刀切收窄主流程。保持 opt-in 让 deck 生成主流水线保持紧凑、可预期，同时在触发条件命中时仍提供这些能力；每个 `workflows/<name>.md` 是自包含的、按需加载——所以 prompt context 的开销也是 opt-in。
|
||||
@@ -0,0 +1,292 @@
|
||||
# 模板架构：Brand / Layout / Deck 三分类
|
||||
|
||||
> 本文是**架构对齐文档**，定义"模板"在数据模型层面的三种身份、各自的 `design_spec.md` 字段集、以及多路径合成与冲突解决规则。面向贡献者与 AI 工作流，回答"一个模板目录里应该写什么、不写什么；多个模板同时给时怎么合成"。
|
||||
>
|
||||
> 用户视角的用法（怎么触发、怎么选）见 [`templates-guide.md`](./templates-guide.md)；本文不重复。
|
||||
|
||||
---
|
||||
|
||||
## 一、三分类
|
||||
|
||||
| 分类 | 物理目录 | 写什么 | 不写什么 | 出处工作流 |
|
||||
|---|---|---|---|---|
|
||||
| **Brand** | `templates/brands/<id>/` | 仅身份段：color / typography / logo / voice / icon style | 不写 canvas、page structure、SVG roster | `workflows/create-brand.md` |
|
||||
| **Layout** | `templates/layouts/<id>/` | 仅结构段：canvas / page structure / page types / SVG roster | 不写品牌身份（无 logo、无品牌色硬约束） | `workflows/create-template.md`（layout 分支）|
|
||||
| **Deck** | `templates/decks/<id>/` | 全段：身份段 + 结构段 + 中间段（template overview） | —— | `workflows/create-template.md`（deck 分支，默认）|
|
||||
|
||||
三者是**三种并列的 reference bundle**，物理目录与 frontmatter `kind` 字段双向对齐：
|
||||
|
||||
```yaml
|
||||
# templates/brands/anthropic/design_spec.md
|
||||
---
|
||||
kind: brand
|
||||
...
|
||||
---
|
||||
|
||||
# templates/layouts/academic_defense/design_spec.md
|
||||
---
|
||||
kind: layout
|
||||
...
|
||||
---
|
||||
|
||||
# templates/decks/招商银行/design_spec.md
|
||||
---
|
||||
kind: deck
|
||||
...
|
||||
---
|
||||
```
|
||||
|
||||
### 三段的字段切分
|
||||
|
||||
为了让多路径合成能干净覆盖，所有字段按段归属，**段级整段替换是默认粒度**：
|
||||
|
||||
| 段 | 包含的章节 | 归属（覆盖优先级）|
|
||||
|---|---|---|
|
||||
| **身份段** | Color Scheme / Typography / Logo / Voice & Tone / Icon Style | brand 覆盖 |
|
||||
| **结构段** | Canvas Specification / Page Structure / Page Types / SVG Roster | layout 覆盖 |
|
||||
| **中间段** | Template Overview（use cases / design intent / page rhythm 等叙事字段）| deck 独有；brand / layout 不写 |
|
||||
|
||||
### 为什么需要 Deck 这一类
|
||||
|
||||
Deck 是一份现存 PPT 的"复刻全息"——SVG 几何为该套配色和字体画的，身份与结构在原 PPT 里已经实战搭配。它的价值是「已验证的整体感」，是 layout + brand 自由拼合未必能达到的成品。
|
||||
|
||||
但 Deck **不是"不可篡改的复刻"**——它是"作为默认底图的复刻，可被显式 brand / layout 覆盖"。这给了用户最大自由度：默认拿到一份完整方案，需要时显式换身份或换结构。
|
||||
|
||||
---
|
||||
|
||||
## 二、各分类的 `design_spec.md` Schema
|
||||
|
||||
字段集只规定**必须写**的部分。「非必要不表明」——当前 schema 没列出的字段，不写。
|
||||
|
||||
### Brand schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
brand_id: <slug>
|
||||
kind: brand
|
||||
summary: <一句话描述用途，含主色>
|
||||
primary_color: "<HEX>"
|
||||
---
|
||||
```
|
||||
|
||||
**正文章节**（身份段全集）
|
||||
|
||||
| 节 | 标题 | 必写字段 |
|
||||
|---|---|---|
|
||||
| I | Brand Overview | Brand Name / Use Cases / Tone |
|
||||
| II | Color Scheme | role / HEX / provenance（`fact` 官方真值 \| `approx` 推导）/ notes |
|
||||
| III | Typography | role / family / weight |
|
||||
| IV | Logo | file / form / usage + clearspace 与组合规则 |
|
||||
| V | Voice & Tone | formality / person / emoji / abbreviation 策略 |
|
||||
| VI | Icon Style | preference（stroke / filled / duotone …）+ 推荐字库 |
|
||||
|
||||
**不允许出现**：canvas viewBox、page types、SVG roster——这些是 layout 的职责。
|
||||
|
||||
### Layout schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout_id: <slug>
|
||||
kind: layout
|
||||
summary: <一句话描述用途>
|
||||
canvas_format: <ppt169 | ppt43 | a4 | ...>
|
||||
page_count: <N>
|
||||
page_types: [<cover, toc, chapter, content, ending, ...>]
|
||||
---
|
||||
```
|
||||
|
||||
**正文章节**（结构段全集 + Template Overview）
|
||||
|
||||
| 节 | 标题 | 必写字段 |
|
||||
|---|---|---|
|
||||
| I | Template Overview | Use Cases / Design Intent / Page Rhythm 建议 |
|
||||
| II | Canvas Specification | Format / Dimensions / viewBox / Margins / Content Area |
|
||||
| III | Page Structure | General Layout Grid / Decorative DNA / Navigation 规则 |
|
||||
| IV | Page Types | 每种页面的角色（cover / toc / chapter / content / ending …）与变体说明 |
|
||||
| V | SVG Page Roster | 文件清单 + 用途，每个文件对应 III/IV 哪一类 |
|
||||
|
||||
**不允许出现**：品牌 logo、品牌 voice & tone、官方真值色（`provenance: fact`）——这些是 brand 的职责。Layout 自身没有兜底色/字体（这是定义：layout 不写身份段；色彩与字体在 Strategist 八项确认现场决策）。
|
||||
|
||||
### Deck schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
deck_id: <slug>
|
||||
kind: deck
|
||||
summary: <一句话描述用途>
|
||||
canvas_format: <ppt169 | ...>
|
||||
page_count: <N>
|
||||
primary_color: "<HEX>"
|
||||
---
|
||||
```
|
||||
|
||||
**正文章节**（身份段全部 + 结构段全部 + 中间段）
|
||||
|
||||
| 节 | 标题 | 归属段 |
|
||||
|---|---|---|
|
||||
| I | Template Overview | 中间段 |
|
||||
| II | Canvas Specification | 结构段 |
|
||||
| III | Color Scheme（含 provenance）| 身份段 |
|
||||
| IV | Typography | 身份段 |
|
||||
| V | Logo | 身份段 |
|
||||
| VI | Voice & Tone | 身份段 |
|
||||
| VII | Icon Style | 身份段 |
|
||||
| VIII | Page Structure | 结构段 |
|
||||
| IX | Page Types | 结构段 |
|
||||
| X | SVG Page Roster | 结构段 |
|
||||
|
||||
> Deck 是身份段 + 结构段全字段的并集，无可选段。这样合成时段级替换粒度统一。
|
||||
|
||||
---
|
||||
|
||||
## 三、三套 index 文件
|
||||
|
||||
每个 index 跟物理目录一一对应，字段按需精简（参照 [[project-charts-index-full-read-intentional]] 的"meta + summary"模式，但保留对 Strategist 选型有用的结构化元数据）。
|
||||
|
||||
### `templates/brands/brands_index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"<brand_id>": {
|
||||
"summary": "Anthropic brand identity — AI/LLM tech talks, developer conferences",
|
||||
"primary_color": "#D97757"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 保留 `primary_color` —— Strategist 选 brand 时第一眼就要知道主色
|
||||
- 去掉 keywords —— summary 自带英文等价词，AI 用自然语言匹配（沿用 charts 经验）
|
||||
|
||||
### `templates/layouts/layouts_index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"<layout_id>": {
|
||||
"summary": "Standard academic defense layout — cover/toc/chapter/content/ending",
|
||||
"canvas_format": "ppt169",
|
||||
"page_count": 5,
|
||||
"page_types": ["cover", "toc", "chapter", "content", "ending"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 加 `canvas_format` / `page_count` / `page_types` —— Strategist 选 layout 时要快速判断"页面骨架能不能装下我的 deck"
|
||||
- 无 `primary_color` —— layout 无身份
|
||||
|
||||
### `templates/decks/decks_index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"<deck_id>": {
|
||||
"summary": "China Merchants Bank transaction banking deck",
|
||||
"canvas_format": "ppt169",
|
||||
"page_count": 5,
|
||||
"primary_color": "#XXXXXX"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 含 `primary_color`（deck 自带身份）+ 结构元数据
|
||||
- 不展开 `page_types` —— deck 的页面类型与 layout 的相同集合，不冗余记录
|
||||
|
||||
---
|
||||
|
||||
## 四、多路径合成与冲突解决
|
||||
|
||||
### 合成优先级（隐式触发）
|
||||
|
||||
用户在第一条消息里给出一组路径，Step 3 按以下表合成 `<project>/templates/design_spec.md`：
|
||||
|
||||
| 用户路径 | 合成行为 |
|
||||
|---|---|
|
||||
| 无 | 跳过 Step 3，走自由设计 |
|
||||
| 只 brand | 复制 brand 全部，结构走自由设计 |
|
||||
| 只 layout | 复制 layout 全部，身份走自由设计（Strategist 八项确认 e/f/g 决策） |
|
||||
| 只 deck | 复制 deck 全部 |
|
||||
| brand + layout | brand 提供身份段 + layout 提供结构段，沿用 SKILL.md 现有 fusion 表 |
|
||||
| brand + deck | brand 段级覆盖 deck 的身份段，结构段与中间段从 deck 拿 |
|
||||
| layout + deck | layout 段级覆盖 deck 的结构段，身份段与中间段从 deck 拿 |
|
||||
| brand + layout + deck | brand 覆盖身份 + layout 覆盖结构 + deck 提供中间段；身份/结构段的 deck 原值整段丢弃 |
|
||||
|
||||
### 段级整段替换（默认粒度）
|
||||
|
||||
合成默认是**段级整段替换**——例如 deck + brand 时，整个 Color Scheme / Typography / Logo / Voice / Icon Style 五段从 brand 拿，**不做字段级混搭**（即不会发生"primary 从 brand 拿、secondary 从 deck 拿"这类隐式混合）。
|
||||
|
||||
字段级微调走 Strategist 八项确认这条已有路径——用户在 chat 里说"用 anthropic brand，但 primary 改成 #FF0000"，由 Strategist 在 e/g 现场调整，不在 Step 3 的 fusion 层加字段级语法。
|
||||
|
||||
### 同类多份 = git 冲突解决
|
||||
|
||||
用户给 `brands/anthropic` + `brands/google`（同类多份的任意排列组合）：
|
||||
|
||||
```
|
||||
AI: 你给了两个 brand，检测到段级冲突：
|
||||
- Color Scheme（Anthropic 橙红 vs Google 多色）
|
||||
- Typography（Styrene/AnthropicSans vs GoogleSans/Roboto）
|
||||
- Logo（Anthropic 标 vs Google 标）
|
||||
- Voice & Tone（restrained vs friendly）
|
||||
- Icon Style（stroke vs filled）
|
||||
|
||||
要 (a) 全部按 Anthropic / (b) 全部按 Google / (c) 逐段挑？
|
||||
```
|
||||
|
||||
- 默认无隐式顺序，所有冲突都问
|
||||
- 仅在用户选 (c) 才进入逐段问答；不做字段级冲突解决
|
||||
- `layout × 2`、`deck × 2`、`brand × 2` 同处理
|
||||
- 三类各最多两份（再多让用户先在 chat 里收敛）
|
||||
|
||||
### Provenance 记录
|
||||
|
||||
合成后的 `<project>/templates/design_spec.md` 顶部必须加：
|
||||
|
||||
```markdown
|
||||
> **Fused from:**
|
||||
> - deck: `templates/decks/招商银行/` （base）
|
||||
> - brand: `templates/brands/anthropic/` （identity 段覆盖）
|
||||
> - layout: `templates/layouts/academic_defense/` （structure 段覆盖）
|
||||
> - conflicts resolved: Color Scheme from anthropic（用户选 a）
|
||||
```
|
||||
|
||||
让 AI 和人类都能回溯每段来自哪。
|
||||
|
||||
---
|
||||
|
||||
## 五、与 SKILL.md Step 3 的关系
|
||||
|
||||
**触发规则不变** —— 仍然是「显式目录路径才触发」（见 [[feedback-template-explicit-path-only]]）。`kind` 字段决定**触发后 AI 怎么处理**：
|
||||
|
||||
| 用户路径指向 | Step 3 行为（按 kind 分支）|
|
||||
|---|---|
|
||||
| `kind: brand` | 复制 design_spec + logos + asset 子目录到 `<project>/templates/` |
|
||||
| `kind: layout` | 复制 design_spec + SVG roster + assets 到 `<project>/templates/` |
|
||||
| `kind: deck` | 复制 design_spec + SVG roster + logos + 全部 assets 到 `<project>/templates/` |
|
||||
| 多路径 | 按上表合成单份 `design_spec.md` + 各源的 SVG/logo 合并复制 |
|
||||
| 同类多份 | 按上节"git 冲突解决"问答，得到合成结果 |
|
||||
|
||||
### Strategist 八项确认在不同 kind 下的收窄
|
||||
|
||||
Deck 路径下用户已经拿到完整方案，八项确认收窄到"目标受众 / 页数 / 大纲 / 调性微调"等 deck 内容相关字段；其他字段直接从锁定值复用。具体收窄规则落在 `references/strategist.md` 与 `spec_lock_reference.md`。
|
||||
|
||||
---
|
||||
|
||||
## 六、与 workflows 的关系
|
||||
|
||||
| 工作流 | 产出 |
|
||||
|---|---|
|
||||
| `workflows/create-brand.md` | brand 目录（identity-only），从品牌资产逆向提取 |
|
||||
| `workflows/create-template.md` | layout 或 deck 目录，内部按 kind 分支：默认走 deck（用户给了一份现存 PPT，提取完整身份 + 结构）；用户明说"只要结构 / 丢掉品牌色"时走 layout |
|
||||
|
||||
产出后 frontmatter `kind` 字段决定文件落到 `templates/brands/` / `templates/layouts/` / `templates/decks/`。
|
||||
|
||||
---
|
||||
|
||||
## 七、不做（与本文 framing 配套的拒绝列表）
|
||||
|
||||
- **不在 fusion 层支持字段级覆盖语法** —— 字段级微调走 Strategist 八项确认这条已有路径
|
||||
- **不为同类三份及以上设计批量冲突解决** —— 用户先在 chat 里收敛到两份
|
||||
- **不引入双名映射表** —— 模板命名按其品牌/场景母语（中文模板用中文名，英文模板用 snake_case），不强制统一
|
||||
240
agent/skills-disabled/ppt-master/docs/zh/templates-guide.md
Normal file
240
agent/skills-disabled/ppt-master/docs/zh/templates-guide.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 模板指南：选用、派生与边界
|
||||
|
||||
PPT Master 的"模板"是一份**结构 + 风格**的预设包：包含若干页面布局 SVG（封面/章节/目录/内容/结尾及其变体）、`design_spec.md` 设计规范，以及配套素材（logo、背景、装饰图）。它不是 PPTX 母版，也不是单纯的配色方案——而是一组可被工作流直接复用的页面骨架。
|
||||
|
||||
本文回答三个问题：
|
||||
|
||||
1. [怎么用已有模板？](#一选用已有模板)
|
||||
2. [怎么把别人的 PPT / 自己的品牌做成模板？（重点）](#二派生新模板重点)
|
||||
3. [模板的边界是什么？](#三模板的边界)
|
||||
|
||||
---
|
||||
|
||||
## 一、选用已有模板
|
||||
|
||||
### 触发方式
|
||||
|
||||
工作流**默认走自由设计**——不会主动问你要不要用模板，也不会基于内容主动推荐模板。模板是 opt-in 的，**只接受显式目录路径**：你在第一条消息里把模板目录的路径写出来。
|
||||
|
||||
### 怎么触发模板流程
|
||||
|
||||
在对话里把模板目录的路径写进去（位置不重要，只要明确即可）：
|
||||
|
||||
> "用这个模板做：`skills/ppt-master/templates/layouts/academic_defense/`" ✅
|
||||
> "用上次那个模板：`projects/last_deck/template/`" ✅
|
||||
> "做一份产品介绍，模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
|
||||
|
||||
AI 会把这个目录里的 SVG、`design_spec.md` 和素材复制到项目目录，然后进入 Strategist 阶段。路径可以是任意位置——内置库的 `skills/ppt-master/templates/layouts/` 下、上一个项目的 `template/` 文件夹、或者磁盘上其他任何地方都行。
|
||||
|
||||
### 什么**不会**触发模板流程
|
||||
|
||||
- **只写模板名、不给路径**："用 academic_defense 模板" / "做一份 招商银行 模板的产品介绍" → 走自由设计。AI 不会替你把名字解析成路径。要用模板，请直接给路径。
|
||||
- **风格描述**："麦肯锡风格" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" → 走自由设计。这些描述会顺着对话流到 Strategist 那边作为风格说明使用，但**不会复制任何模板文件**。
|
||||
- **模糊意图**："想用个模板" / "选一个吧"——没给路径 → 走自由设计。
|
||||
|
||||
这是有意的——AI 永远**不做模糊 / 解释性判断**，不替你把名字解析成路径。要用模板，直接给路径。
|
||||
|
||||
想知道内置库里有哪些模板，问一句"有哪些模板可以用？"——AI 会从发现索引里列出名字和对应路径。单纯列出并不进入模板流程，需要你**把其中一条路径**再发回来才会触发 Step 3。
|
||||
|
||||
### 现有模板一览
|
||||
|
||||
模板按三种身份分目录：
|
||||
|
||||
- [`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），无身份；academic_defense、government_blue/red、ai_ops、medical_university、pixel_retro、psychology_attachment
|
||||
- [`templates/decks/README.md`](../../skills/ppt-master/templates/decks/README.md) — 完整 PPT 复刻（身份 + 结构 + 中间段）；招商银行、中国电建_*、中汽研_*、重庆大学、中国电信
|
||||
|
||||
完整数据模型与三类的合成 / 冲突解决规则见 [`templates-architecture.md`](./templates-architecture.md)。
|
||||
|
||||
### 自由设计 vs 模板
|
||||
|
||||
自由设计不是"没有风格"，而是 AI 根据你的内容**为这一份 deck 现场设计**视觉系统；模板则是**沿用一套已经定型的结构和风格**。两条路都不会少做"设计"，区别只在于风格是即兴还是预设。
|
||||
|
||||
> 经验：内容方向明确、品牌或场景有强约束（咨询报告、政府汇报、答辩）→ 用模板。内容偏散文式、视觉氛围更重要（杂志风、纪录式叙事）→ 自由设计往往效果更好。
|
||||
|
||||
### 风格不是模板
|
||||
|
||||
**风格**是一种描述（"极简风" / "Keynote 风" / "杂志风"）——你在对话里打几个字。**模板**是一份要复制粘贴的资产包（SVG + design_spec + 素材），只在你给出**显式目录路径**时由工作流安装到项目里。
|
||||
|
||||
| | 模板 | 风格 |
|
||||
|---|---|---|
|
||||
| 怎么触发 | 消息里给出明确的目录路径 | 消息里写自由描述 |
|
||||
| 发生什么 | 文件复制到项目；layouts 继承自模板 SVG | 描述流到 Strategist；色彩 / 字体 / 调性在八项确认里推荐 |
|
||||
| 数值锁定 | 是 — 来源于模板的 `design_spec.md` | 否 — Strategist 现场推适合 deck 的具体值 |
|
||||
| 适用场景 | 品牌锁定的 deck；强视觉约定的场景 | 心里有感觉但没有具体品牌承诺 |
|
||||
|
||||
风格描述可能看起来像模板名（比如 "学术风" 听上去像 `academic_defense/` 模板目录），但走的是**两套机制**——模板需要你给一个真实可复制的路径，风格描述是解释性语言。字面接近，落地完全是两条路。
|
||||
|
||||
### 常见风格描述
|
||||
|
||||
三条轴自由组合（"暗色科技 + 极简" 或 "杂志风 + 新中式" 都行）：
|
||||
|
||||
**美学路线**
|
||||
|
||||
| 风格 | 一句话特征 |
|
||||
|---|---|
|
||||
| **极简风 / Minimalist** | 高留白、2-3 色、单焦点、几乎零装饰 |
|
||||
| **信息密集 / Information-dense** | 麦肯锡派结构化表格、密度高、conclusion-first |
|
||||
| **Keynote 风** | 单页 Hero 文字、premium 留白、Apple 感 |
|
||||
| **杂志风 / Editorial** | 大图当主体、不对称版式、字体反差强 |
|
||||
| **文艺手绘** | 暖色、手绘质感、像 zine |
|
||||
|
||||
**行业 / 场景**
|
||||
|
||||
| 风格 | 一句话特征 |
|
||||
|---|---|
|
||||
| **商务咨询风** | 数据驱动、专业克制、蓝/灰主调 |
|
||||
| **学术答辩风** | 严谨层级、citation-heavy、清晰朴素 |
|
||||
| **政府汇报风** | 红/蓝、庄重对称、标题加粗 |
|
||||
| **产品发布风** | 视觉冲击、营销大胆、Hero 单图 |
|
||||
| **教学课件风** | 清晰层级、友好亲和、配色明亮 |
|
||||
| **路演/BP 风** | 叙事驱动、金句配图、conclusion-bold |
|
||||
|
||||
**视觉调性**
|
||||
|
||||
| 风格 | 一句话特征 |
|
||||
|---|---|
|
||||
| **暗色科技风** | 深蓝/黑底、霓虹强调、未来感 |
|
||||
| **像素复古** | 8-bit、扫描线、游戏机美学 |
|
||||
| **新中式** | 留白、传统纹样克制使用、墨色/朱砂 |
|
||||
| **北欧极简** | 浅色、原木自然、字号克制 |
|
||||
| **孟菲斯/波普风** | 高饱和大色块、几何图形、80 年代 |
|
||||
| **赛博朋克/蒸汽波** | 霓虹紫粉、网格、迷幻 |
|
||||
|
||||
你描述风格时，AI **不会基于这些词去挑模板**——它把这些词解释为对应的色彩 / 字体 / 版式建议，放到 Strategist 八项确认里 `d` 项的第二层（视觉风格），然后驱动 e/f/g/h（色彩 / 图标 / 字体 / 图片）。你可以确认或调整。如果你想要的风格刚好对上库里某个模板（如 `academic_defense` / `pixel_retro` / `psychology_attachment`），有两条路可选：把模板的目录路径发出来锁定值，或描述风格让 AI 现场推适配你内容的值。
|
||||
|
||||
---
|
||||
|
||||
## 二、派生新模板（重点）
|
||||
|
||||
把你自己喜欢的 PPT、品牌指南、或一份现成的 PPTX，做成 PPT Master 可调用的模板。这是本文的核心。
|
||||
|
||||
### 入口：`/create-template` 工作流
|
||||
|
||||
完整规范见 [`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md)。本节是面向用户的简要版本——你只需要在 IDE 对话里说：
|
||||
|
||||
```
|
||||
请用 /create-template 工作流，基于下面的参考材料生成一个新模板。
|
||||
```
|
||||
|
||||
接下来工作流会**强制**先和你确认一份模板简报（不允许跳过）。
|
||||
|
||||
### 第一步：准备参考材料
|
||||
|
||||
**强烈推荐：直接给原始 `.pptx` 文件。** 当前的 PPTX 导入管线已经做到接近高保真还原——工作流会用 [`pptx_template_import.py`](../../skills/ppt-master/scripts/pptx_template_import.py) 直接读取 OOXML，提取主题色、字体、每个 master 的主题摘要、母版/版式结构、placeholder 元数据和可复用图片资源。它会输出作为机器事实源的 layered `svg/`，以及用于视觉预览的自包含 `svg-flat/`，再交给 Template_Designer 重建出干净可维护的 SVG。封面、章节、装饰繁复的页面都能稳定还原，这是目前最靠谱的派生路径。
|
||||
|
||||
也可以基于品牌指南从零设计：提供 logo、主色 HEX、字体、调性描述、几张氛围参考图，AI 会现场设计页面骨架。适合品牌方还没有成型 PPT、只有 VI 手册的场景。
|
||||
|
||||
> **没有源 PPTX 时的兜底**：截图集（`cover.png` / `chapter.png` / `content.png` / `closing.png` 等）也能跑，但保真度会明显下降——装饰、字体、版式细节都靠 AI 视觉推断。能拿到 `.pptx` 就尽量用 `.pptx`。截图更适合作为标注辅助（"这页是我想要的样子"）混进 PPTX 一起给。
|
||||
|
||||
### 第二步：模板简报（强制确认环节）
|
||||
|
||||
工作流不会偷偷推断——它会在动手前向你列出以下条目，等你确认或补全：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| **模板 ID** | 目录名 / 索引键。优先 ASCII slug，如 `acme_consulting`；中文品牌名也行，但要文件系统安全 |
|
||||
| **显示名称** | 文档中的人类可读名 |
|
||||
| **类别** | `brand` / `general` / `scenario` / `government` / `special` 五选一 |
|
||||
| **适用场景** | 年报 / 咨询 / 答辩 / 政府汇报…… |
|
||||
| **调性概要** | 一句话，如"现代克制、数据驱动" |
|
||||
| **主题模式** | 浅色 / 深色 / 渐变…… |
|
||||
| **画布格式** | 默认 `ppt169`（16:9），其他格式需提前指定 |
|
||||
| **复刻模式** | `standard`（默认 5 页基本套）/ `fidelity`（按 PPTX 源里"视觉上真正不同"的版式簇各开一个变体——数量由源决定）/ `mirror`（每张源页 1:1 原样复制，零抽象、不插占位符）—— `fidelity` 和 `mirror` 都必须有 `.pptx` 源 |
|
||||
| **保真级别** | （`standard` / `fidelity` 有源时必填）`literal`（按原样复刻几何/装饰/精灵图裁剪）/ `adapted`（借结构和调性、允许设计演化）。封面 / 章节 / 结尾通常用 `literal`。**`mirror` 模式不询问**——隐含 literal |
|
||||
| **关键词** | 3–5 个标签，用于索引检索 |
|
||||
| 主题色 / 设计风格 / 素材清单 | 可选，可让 AI 从源里自动提取 |
|
||||
|
||||
确认后，工作流会回显一份完整简报并写入标记 `[TEMPLATE_BRIEF_CONFIRMED]`，从这一刻起后续步骤才会启动。**这是一个硬门——简报没确认，不会开始生成**。
|
||||
|
||||
> 为什么这么严？因为模板是入库资产，未来会被复用。一次说清楚，比生成完再返工便宜得多。
|
||||
|
||||
### 第三步：选 standard、fidelity 还是 mirror？
|
||||
|
||||
这是派生模板里最容易混淆的决策。
|
||||
|
||||
| | **standard** | **fidelity** | **mirror** |
|
||||
|---|---|---|---|
|
||||
| 输出页数 | 5 页（封面/章节/目录/内容/结尾） | 视觉上真正不同的版式簇各一个变体——数量由源决定 | 每张源页 1:1 一页 |
|
||||
| 抽象程度 | 高 —— 干净可复用骨架 | 中 —— 聚类后清理 | **零** —— 原样复制 |
|
||||
| 是否插占位符 | 是（`{{TITLE}}`、`{{CONTENT_AREA}}` 等） | 是 | **否** —— Executor 直接在 SVG 里就地编辑文字 |
|
||||
| 适合场景 | 你只需要"调性 + 基本骨架"，未来用模板生成全新 deck | 源 PPTX 本身就是高度定制的版式库 | 别人的精装 deck 直接好用、想把每页都当参考页 |
|
||||
| 典型例子 | 给品牌做基础模板 | 复刻一套政府汇报的 20 种章节版式 | 把一份 50 页的麦肯锡风格 deck 整套用作模板 |
|
||||
| 必须有 PPTX 源吗 | 否 | **是** | **是** |
|
||||
| 装饰复杂度 | 通常较简洁 | 需要保留精灵图（sprite sheet）裁剪等结构 | 源页啥样就啥样，逐字节继承 |
|
||||
|
||||
**关于精灵图**：PPTX 导出的素材常常是**一张大图 + 多页通过 viewBox 裁剪不同区域**。`fidelity` 和 `mirror` 模式下必须保留这层嵌套 `<svg viewBox=...>` 包装，不能扁平化为单张 `<image>`——否则裁剪信息丢失，画面会错位。工作流会自动校验这一点。
|
||||
|
||||
**`mirror` 模板怎么消费**：mirror 模板里没有 `{{}}` 占位符——Strategist 根据 `design_spec.md §V Page Roster` 的逐页描述为每个项目页选一张参考页，Executor 把那张参考 SVG 拷过去，**仅在原位修改文字内容**，所有装饰、精灵图裁剪、几何坐标全部保留。库资产保持 100% 原样；针对项目的修改只存在于 `projects/<project>/svg_output/`。
|
||||
|
||||
### 第四步：注册与发现
|
||||
|
||||
模板生成完，工作流会：
|
||||
|
||||
1. 跑 [`svg_quality_checker.py`](../../skills/ppt-master/scripts/svg_quality_checker.py) 验证（硬门，不通过不入库）
|
||||
2. 把模板 ID 注册到 [`layouts_index.json`](../../skills/ppt-master/templates/layouts/layouts_index.json)
|
||||
3. 同步 [`templates/layouts/README.md`](../../skills/ppt-master/templates/layouts/README.md) 表格
|
||||
|
||||
注册让模板**可被发现**——下次有人问"有哪些模板可用？"时，AI 会从索引里把它列出来。要在新项目里用它，仍然按 SKILL.md Step 3 的规则：在第一条消息里把目录路径写出来，例如 `用这个模板：skills/ppt-master/templates/layouts/<your_template_id>/`。
|
||||
|
||||
### 派生后的目录长什么样
|
||||
|
||||
```
|
||||
skills/ppt-master/templates/layouts/<your_template_id>/
|
||||
├── design_spec.md # 设计规范，§VI 列出全部页面
|
||||
├── 01_cover.svg
|
||||
├── 02_chapter.svg
|
||||
├── 02_toc.svg # 可选
|
||||
├── 03_content.svg
|
||||
├── 03a_content_two_col.svg # fidelity 模式下的变体
|
||||
├── 04_ending.svg
|
||||
├── logo.png # 品牌素材
|
||||
└── bg_pattern.jpg
|
||||
```
|
||||
|
||||
`standard` 和 `fidelity` 模式下的页面 SVG 里使用统一的占位符约定（`{{TITLE}}`、`{{CHAPTER_TITLE}}`、`{{PAGE_TITLE}}`、`{{CONTENT_AREA}}` 等），策略师阶段会按内容填充。
|
||||
|
||||
`mirror` 模板按源页序号每页一张 SVG，**SVG 内部没有占位符**：
|
||||
|
||||
```
|
||||
skills/ppt-master/templates/layouts/<your_template_id>/
|
||||
├── design_spec.md # frontmatter 设 replication_mode: mirror；§V Page Roster 逐页描述
|
||||
├── 001_cover.svg
|
||||
├── 002_toc.svg
|
||||
├── 003_content.svg
|
||||
├── 004_content.svg
|
||||
├── ...
|
||||
├── 049_content.svg
|
||||
├── 050_ending.svg
|
||||
└── *.png / *.jpg
|
||||
```
|
||||
|
||||
### 项目级一次性定制 vs 全局模板
|
||||
|
||||
二者别搞混：
|
||||
|
||||
- **派生新模板** = 入全局库，在 `skills/ppt-master/templates/layouts/` 下，未来所有项目都能调用
|
||||
- **项目级定制** = 只在 `projects/<project>/templates/` 里改这一份 deck 的页面，不入库、不影响其他项目
|
||||
|
||||
`/create-template` 工作流只做前者。后者直接在项目目录里改 SVG 即可，不需要走这个流程。
|
||||
|
||||
---
|
||||
|
||||
## 三、模板的边界
|
||||
|
||||
避免常见误解：
|
||||
|
||||
- **模板 ≠ 母版（Slide Master）**。PPT Master 的输出是原生 DrawingML 形状，不依赖 PowerPoint 母版机制。模板是 SVG 骨架，最终在导出阶段被翻译为 PPTX 形状
|
||||
- **模板不是"风格皮肤"**。它包含结构（页面有几块、信息层级如何分布）+ 风格（配色、字体、装饰），两者不可分割。试图只换"皮肤"不换结构，往往会让信息架构和视觉打架
|
||||
- **模板不会替你做内容决策**。策略师仍然会按内容判断每页用哪个版式、要不要扩展为变体，模板提供候选，不预设结果
|
||||
- **`fidelity` 模式不等于像素级搬运**。即便是 `literal` 保真，AI 仍会把杂质和不必要的重复结构清理掉——载体保留几何，但不照抄冗余
|
||||
- **`mirror` 模式确实是像素级搬运——但它继承源 PPT 的导入限制**。图表、SmartArt、OLE 对象、EMF / WMF 媒体如果在 `pptx_template_import.py` 里 round-trip 失败，mirror 也会同样失败。flat SVG 是事实源——`<workspace>/svg-flat/` 里看着断了，mirror 模板也会断
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [`workflows/create-template.md`](../../skills/ppt-master/workflows/create-template.md) — 完整工作流规范（面向 AI 执行）
|
||||
- [`templates/layouts/README.md`](../../skills/ppt-master/templates/layouts/README.md) — 现有模板一览
|
||||
- [`references/template-designer.md`](../../skills/ppt-master/references/template-designer.md) — 模板设计师角色定义和 SVG 技术约束
|
||||
- [常见问题：如何制作自定义模板](./faq.md#q-如何制作自定义模板) — FAQ 简版
|
||||
88
agent/skills-disabled/ppt-master/docs/zh/why-ppt-master.md
Normal file
88
agent/skills-disabled/ppt-master/docs/zh/why-ppt-master.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 为什么选 PPT Master
|
||||
|
||||
[English](../why-ppt-master.md) | [中文](./why-ppt-master.md)
|
||||
|
||||
---
|
||||
|
||||
市面上有几十款 AI PPT 工具。这个页面说清楚 PPT Master 到底哪里不一样——以及它在哪些场景下不是最佳选择。
|
||||
|
||||
我是[何雨果](https://www.hehugo.com/)，一个每天都在做 PPT 的投融资从业者。PPT Master 是我花了大量时间打磨的开源工具——因为我自己就是最挑剔的用户。
|
||||
|
||||
## 1. 生成真正的 PPT——不是图片，不是网页截图
|
||||
|
||||
**这是最核心的差异化。**
|
||||
|
||||
市面上的 AI PPT 工具大致走三条路，每条都有硬伤：
|
||||
|
||||
- **贴图片** → 很多工具把每页渲染成图片嵌入 PPTX。看起来精美，但文字不可选、颜色不可改、缩放就糊——本质上是截图，不是演示文稿。
|
||||
- **HTML/CSS 渲染** → Gamma、Tome 等在浏览器里做得好看，但 HTML 是文档流，PPT 是画布，导出 PPTX 时布局走样、字体丢失、元素被扁平化。
|
||||
- **python-pptx 直接生成** → ChatGPT 等用代码直接构建 PPTX，元素可编辑，但 AI 缺乏训练数据来生成复杂设计，只能做基础文本框+列表。
|
||||
|
||||
PPT Master 走第四条路——**AI 生成 SVG，脚本将 SVG 转换为 DrawingML**。这条路走得通，是因为 SVG 和 DrawingML 本质上是同一类东西——都是基于绝对坐标的 2D 矢量格式，矩形、路径、渐变、阴影的概念一一对应。转换是「方言翻译」，不是格式代沟。
|
||||
|
||||
导出的 PPTX 中，每个形状、文本框、渐变、阴影都是原生 PowerPoint 对象。点哪改哪，就像手工做的一样。
|
||||
|
||||
> 完整技术论述参见 [技术设计](./technical-design.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 成本透明——只向你自己的 AI 服务商付费
|
||||
|
||||
PPT Master 本身免费开源，唯一的成本来自你自己的 AI 模型用量。
|
||||
|
||||
目前主流 AI 工具都已转向按量计费——用多少付多少。PPT Master 天然契合这一模型：不需要额外订阅一个 PPT 平台，没有专有积分，没有按人头收费的演示工具费用。
|
||||
|
||||
作为对比，Gamma 订阅 $8–20/月，Beautiful.ai $12–45/月——无论你用多少都得付这个底价。PPT Master 在你现有 AI 支出之外不增加任何额外成本。
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据隐私——100% 本地
|
||||
|
||||
你的文件不会离开你的电脑。源文档在本地转换，SVG 在本地生成，PPTX 在本地导出。唯一的外部通信是你和 AI 编辑器之间的对话——这和你正常使用编辑器没有区别。
|
||||
|
||||
没有第三方服务器存储你的源文档或输出结果。对金融、政府以及任何有数据驻留要求的组织来说，这一点至关重要。
|
||||
|
||||
---
|
||||
|
||||
## 4. 极度开放——不绑定编辑器，不绑定模型
|
||||
|
||||
你的工作流不应该被任何一家公司绑架。今天用这个平台，明天它涨价、改规则、关停服务，你的积累就归零了。这不是开源该有的样子。
|
||||
|
||||
PPT Master 是一个框架，不是某个 IDE 的插件。**编辑器方面**，Claude Code、VS Code Copilot、Cursor、Codebuddy IDE，以及未来出现的任何新工具，都能用。**模型方面**，Claude 系列效果最好，但 GPT、Gemini、Kimi、MiniMax 等模型同样可以驱动，只是布局精度有差异——随着模型能力提升，这些差异会进一步缩小。
|
||||
|
||||
选择权在你手里，PPT Master 不替你做这个决定。
|
||||
|
||||
---
|
||||
|
||||
## 特点
|
||||
|
||||
### 咨询级设计体系
|
||||
|
||||
内建三套风格：通用灵活（培训分享、技术演示）、咨询风（商业报告、数据可视化）、顶级咨询风（MBB 级，投资尽调、战略规划、政府汇报）。
|
||||
|
||||
[examples/](../../examples/) 目录包含所有示例项目，涵盖政府财政分析、AI 架构设计、禅学研究、像素游戏风、杂志编辑风等不同设计风格。
|
||||
|
||||
### 全格式源文档输入
|
||||
|
||||
几乎什么都能喂：PDF、DOCX、PPTX、EPUB、HTML、LaTeX、RST、网页链接、微信公众号文章、Markdown、纯文本。大部分 SaaS 工具只接受提示词或有限的文件上传。
|
||||
|
||||
### 多尺寸输出
|
||||
|
||||
输出不局限于 16:9 和 4:3 的标准演示比例。小红书 3:4、朋友圈 1:1、竖版 Story 9:16、A4 打印——同一套流水线，指定格式即可。
|
||||
|
||||
---
|
||||
|
||||
## PPT Master 不适合的场景
|
||||
|
||||
诚实地说清楚短板：
|
||||
|
||||
| 短板 | 说明 |
|
||||
|---|---|
|
||||
| **需要配置** | 安装 Python、克隆仓库、配置 AI 编辑器。不是打开浏览器就能用的体验。 |
|
||||
| **生成较慢** | 10 页约 10–20 分钟（逐页串行保证跨页一致性）。SaaS 工具只需几秒。 |
|
||||
| **无协作功能** | 本地文件，无实时共编，无分享链接。 |
|
||||
| **非完整自由画布** | 浏览器实时预览支持直接编辑——选中改文字/颜色/字体/字号，拖拽或方向键移动，可撤销——也保留点选注解交给 AI 改写。它不是 Gamma/Canva 那种完整自由画布：画布上没有缩放手柄，重新导出 PPTX 仍由对话触发。 |
|
||||
|
||||
**如果你要零配置、浏览器里秒出幻灯片**——Gamma 和 Canva 是很好的选择。
|
||||
|
||||
**如果你要原生可编辑、成本可控、数据本地化、不被锁定**——这就是 PPT Master 做的事。
|
||||
161
agent/skills-disabled/ppt-master/docs/zh/windows-installation.md
Normal file
161
agent/skills-disabled/ppt-master/docs/zh/windows-installation.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Windows 安装指南
|
||||
|
||||
本指南将手把手教你在 Windows 上安装 PPT Master。按顺序操作，10 分钟内即可跑通第一份 PPT。
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — 安装 Python（必须）
|
||||
|
||||
Python 是唯一的硬性要求。
|
||||
|
||||
1. 前往 **[python.org/downloads](https://www.python.org/downloads/)**，下载最新的 **Python 3.10+** 安装包。
|
||||
|
||||
2. **⚠️ 关键步骤：安装时务必勾选 "Add python.exe to PATH"** — 这是 Windows 上最常见的安装失误，不勾的话后面每一步都会出问题。
|
||||
|
||||
|
||||
|
||||
3. 安装完成后，打开 **PowerShell**（在开始菜单搜索「PowerShell」）并验证：
|
||||
|
||||
```powershell
|
||||
python --version
|
||||
```
|
||||
|
||||
应该看到 `Python 3.12.x` 之类的输出。如果提示「未找到」或弹出 Microsoft Store，见下方[常见问题](#python-未找到或弹出-microsoft-store)。
|
||||
|
||||
> **💡 提示**：Anaconda / Miniconda 安装的 Python 也可以用，只要 `python --version` 显示 3.10+ 即可。
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — 下载项目
|
||||
|
||||
**方式 A — 下载 ZIP**（最简单）：
|
||||
|
||||
1. 打开 [GitHub](https://github.com/hugohe3/ppt-master)（或 [AtomGit 镜像](https://atomgit.com/hugohe3/ppt-master)，国内更快）
|
||||
2. 点击绿色 **Code** 按钮 → **Download ZIP**
|
||||
3. 解压到 `C:\Users\你的用户名\ppt-master`
|
||||
|
||||
**方式 B — Git Clone**（需要 [Git](https://git-scm.com/downloads)）：
|
||||
|
||||
```powershell
|
||||
# GitHub
|
||||
git clone https://github.com/hugohe3/ppt-master.git
|
||||
# AtomGit（国内更快）
|
||||
git clone https://atomgit.com/hugohe3/ppt-master.git
|
||||
cd ppt-master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — 安装依赖
|
||||
|
||||
```powershell
|
||||
cd C:\Users\你的用户名\ppt-master # ← 替换为你的实际路径
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
> 如果 `pip` 无法识别，用 `python -m pip install -r requirements.txt`。
|
||||
|
||||
等待安装完成，最后看到 `Successfully installed ...` 就行。
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — 验证安装
|
||||
|
||||
```powershell
|
||||
python -c "import pptx; import fitz; print('All core dependencies OK')"
|
||||
```
|
||||
|
||||
✅ 输出 `All core dependencies OK` → 核心环境没问题。
|
||||
|
||||
❌ 报错 → 见下方[常见问题](#常见问题)。
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — 跑一个最小示例
|
||||
|
||||
打开你的 AI 编辑器（Cursor、VS Code + Copilot 等），打开 `ppt-master` 目录，在聊天面板输入：
|
||||
|
||||
```
|
||||
请创建一个 3 页测试 PPT，封面 + 内容页 + 封底，主题"Hello World"
|
||||
```
|
||||
|
||||
`exports/` 下出现 `.pptx` 且能在 PowerPoint 中打开 → **搞定了。**
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — 可选增强（大多数用户可以跳过）
|
||||
|
||||
装好 Python 和 `requirements.txt` 后，生成 PPT 的全部功能已经就绪。下面是**边缘场景的备用方案和增强项**——只有遇到对应的具体场景才需要装。
|
||||
|
||||
| 增强项 | 只在以下情况才装 | 安装方式 | 验证 |
|
||||
|--------|-----------------|---------|------|
|
||||
| **CairoSVG** — 更高质量 PNG 后备图 | 你希望在不原生支持 SVG 的 Office 版本下获得更清晰的 PNG 后备图。`svglib`（已默认安装）足够大多数场景。 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |
|
||||
| **Pandoc** — 旧格式文档 | 你需要转 `.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`/`.html`/`.epub`/`.ipynb` 已由 Python 原生处理。 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### `python` 未找到或弹出 Microsoft Store
|
||||
|
||||
**原因：** Python 没有加入系统 PATH。
|
||||
|
||||
**方法 1** — 重新运行 Python 安装程序，选择 **Modify**，确保勾选 **"Add Python to environment variables"**。
|
||||
|
||||
**方法 2** — 手动添加 PATH：
|
||||
1. 先在 PowerShell 中运行 `where python`，记下输出的路径（如 `C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe`）
|
||||
2. 开始菜单搜索「环境变量」
|
||||
3. 找到 `Path` → **编辑** → 新增上面路径的**目录部分**及其 `Scripts` 子目录：
|
||||
```
|
||||
C:\Users\你的用户名\AppData\Local\Programs\Python\Python312
|
||||
C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\Scripts
|
||||
```
|
||||
4. 确定，**重启 PowerShell**
|
||||
|
||||
**方法 3** — 试试 `python3` 或 `py` 命令。
|
||||
|
||||
### 命令里的 `python3` 报错（exit 49 / 弹 Microsoft Store）
|
||||
|
||||
python.org 安装包只装了 `python.exe`，没有 `python3.exe`。**把命令里的 `python3` 换成 `python` 即可**（AI 通常也会自动改用 `python` 继续）。
|
||||
|
||||
### `pip install` 报权限错误
|
||||
|
||||
```powershell
|
||||
pip install --user -r requirements.txt
|
||||
```
|
||||
|
||||
或以管理员身份运行 PowerShell。
|
||||
|
||||
### `pip install` 网络问题
|
||||
|
||||
```powershell
|
||||
# 清华镜像（国内推荐）
|
||||
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||||
|
||||
# 代理
|
||||
pip install -r requirements.txt --proxy http://your-proxy:port
|
||||
```
|
||||
|
||||
### `ModuleNotFoundError`
|
||||
|
||||
`pip` 装到了另一个 Python 环境。用 `python -m pip install -r requirements.txt` 确保对应同一个。
|
||||
|
||||
### `import fitz` 失败
|
||||
|
||||
1. 升级 pip：`python -m pip install --upgrade pip`
|
||||
2. 预编译包：`pip install PyMuPDF --only-binary :all:`
|
||||
3. 仍失败 → 安装 [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
||||
|
||||
### PowerShell「脚本运行被禁用」
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 还是搞不定？
|
||||
|
||||
- 📖 [常见问题 (FAQ)](./faq.md)
|
||||
- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — 附上 Python 版本、Windows 版本和完整报错
|
||||
- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
|
||||
Reference in New Issue
Block a user