feat: 导出 SproutClaw .sproutclaw 配置
包含 extensions、skills、prompts、settings、auth、models、mcp 等配置。 排除 node_modules、npm 缓存、sessions 等运行时数据。
This commit is contained in:
@@ -0,0 +1,44 @@
|
||||
{
|
||||
"$schema": "https://json.schemastore.org/claude-code-marketplace.json",
|
||||
"name": "ppt-master",
|
||||
"owner": {
|
||||
"name": "Hugo He",
|
||||
"email": "heyug3@gmail.com",
|
||||
"url": "https://github.com/hugohe3"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "PPT Master skill — AI generates natively editable PPTX from any document",
|
||||
"version": "2.7.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "ppt-master",
|
||||
"source": {
|
||||
"source": "git-subdir",
|
||||
"url": "https://github.com/hugohe3/ppt-master.git",
|
||||
"path": "skills"
|
||||
},
|
||||
"description": "Generate natively editable PPTX from PDF / DOCX / URL / Markdown — real DrawingML shapes, text boxes, charts, and animations. Note: run `pip install -r requirements.txt` inside the installed plugin directory for the Python post-processing scripts to work.",
|
||||
"author": {
|
||||
"name": "Hugo He",
|
||||
"email": "heyug3@gmail.com",
|
||||
"url": "https://www.hehugo.com/"
|
||||
},
|
||||
"homepage": "https://github.com/hugohe3/ppt-master",
|
||||
"repository": "https://github.com/hugohe3/ppt-master",
|
||||
"license": "MIT",
|
||||
"category": "productivity",
|
||||
"keywords": [
|
||||
"pptx",
|
||||
"presentation",
|
||||
"powerpoint",
|
||||
"svg",
|
||||
"drawingml",
|
||||
"ai",
|
||||
"skill",
|
||||
"office",
|
||||
"document-conversion"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
214
agent/skills-disabled/ppt-master/.env.example
Normal file
214
agent/skills-disabled/ppt-master/.env.example
Normal file
@@ -0,0 +1,214 @@
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Image Generation Configuration / 图片生成配置
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
|
||||
# This file is an optional fallback config source for image_gen.py.
|
||||
# Current process environment variables take precedence over this file.
|
||||
# 当前文件是 image_gen.py 的可选 fallback 配置来源。
|
||||
# 当前进程环境变量优先于这个文件。
|
||||
#
|
||||
# Resolution order (only the FIRST existing file is read; keys are NOT merged across files):
|
||||
# 1. ./.env in your current working directory
|
||||
# 2. <skill-dir>/.env (skill install, e.g. ~/.agents/skills/ppt-master/.env)
|
||||
# 3. <repo-root>/.env (when running from a clone)
|
||||
# 4. ~/.ppt-master/.env (user-level config)
|
||||
# 查找顺序（只读第一个存在的文件，多个 .env 之间不合并）：
|
||||
# 1. 当前工作目录下的 ./.env
|
||||
# 2. skill 安装目录下的 .env（如 ~/.agents/skills/ppt-master/.env）
|
||||
# 3. 仓库根目录下的 .env（仅在 clone 模式下）
|
||||
# 4. ~/.ppt-master/.env（用户级配置）
|
||||
|
||||
# Active backend (required) / 当前启用后端（必需）
|
||||
# Recommended core backends: openai / gemini / qwen / zhipu / volcengine
|
||||
# 推荐核心后端：openai / gemini / qwen / zhipu / volcengine
|
||||
# IMAGE_BACKEND=openai
|
||||
|
||||
# Max concurrent requests in --manifest batch mode (default 3).
|
||||
# Auto-halves on rate-limit; 1 is the serial fallback.
|
||||
# --manifest 批量模式下的最大并发数（默认 3）。命中限流自动减半，最低 1（=串行）。
|
||||
# IMAGE_CONCURRENCY=3
|
||||
|
||||
# You may also provide the same variables directly via the current process environment.
|
||||
# 也可以不写 .env，而是直接通过当前运行进程的环境变量提供同样的配置。
|
||||
|
||||
# IMPORTANT:
|
||||
# - IMAGE_API_KEY / IMAGE_MODEL / IMAGE_BASE_URL are no longer supported.
|
||||
# - Use provider-specific keys only.
|
||||
# 重要：
|
||||
# - 不再支持 IMAGE_API_KEY / IMAGE_MODEL / IMAGE_BASE_URL。
|
||||
# - 请只使用各提供商自己的变量。
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: OpenAI / OpenAI 示例 (recommended / 推荐)
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=openai
|
||||
# OPENAI_API_KEY=sk-xxx
|
||||
# OPENAI_MODEL=gpt-image-2
|
||||
# OPENAI_BASE_URL=http://127.0.0.1:3000/v1
|
||||
# OpenAI-compatible providers may need these compatibility knobs.
|
||||
# OpenAI-compatible 第三方平台可按需开启以下兼容参数。
|
||||
# OPENAI_SIZE_PRESET=auto
|
||||
# OPENAI_RESPONSE_FORMAT=auto
|
||||
# OPENAI_QUALITY=auto
|
||||
# Allowed values: png / jpeg / webp
|
||||
# OPENAI_OUTPUT_FORMAT=png
|
||||
# jpeg/webp only, 0-100
|
||||
# OPENAI_OUTPUT_COMPRESSION=80
|
||||
# gpt-image-2: auto / opaque
|
||||
# OPENAI_BACKGROUND=auto
|
||||
# auto / low
|
||||
# OPENAI_MODERATION=auto
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: Gemini / Gemini 示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=gemini
|
||||
# GEMINI_API_KEY=your-gemini-api-key
|
||||
# GEMINI_MODEL=gemini-3.1-flash-image-preview
|
||||
# GEMINI_BASE_URL=https://your-proxy-url.com
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: MiniMax / MiniMax 示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=minimax
|
||||
# MINIMAX_API_KEY=your-minimax-key
|
||||
# MINIMAX_MODEL=image-01
|
||||
# Default China endpoint / 默认国内地址
|
||||
# MINIMAX_BASE_URL=https://api.minimaxi.com/v1/image_generation
|
||||
# Optional overseas endpoint / 可选海外地址
|
||||
# MINIMAX_BASE_URL=https://api.minimax.io/v1/image_generation
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: Qwen / 通义生图示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=qwen
|
||||
# QWEN_API_KEY=your-dashscope-key
|
||||
# QWEN_MODEL=qwen-image-2.0-pro
|
||||
# QWEN_BASE_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: Zhipu / 智谱生图示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=zhipu
|
||||
# ZHIPU_API_KEY=your-zhipu-key
|
||||
# ZHIPU_MODEL=glm-image
|
||||
# ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4/images/generations
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Example: Volcengine / 火山引擎示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=volcengine
|
||||
# VOLCENGINE_API_KEY=your-volcengine-key
|
||||
# VOLCENGINE_MODEL=doubao-seedream-4-5-251128
|
||||
# VOLCENGINE_BASE_URL=https://operator.las.cn-beijing.volces.com/api/v1/images/generations
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Extended / Experimental backends
|
||||
# 扩展 / 实验后端
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# STABILITY_API_KEY=your-stability-key
|
||||
# STABILITY_MODEL=stable-image-core
|
||||
# STABILITY_BASE_URL=https://api.stability.ai
|
||||
#
|
||||
# BFL_API_KEY=your-bfl-key
|
||||
# BFL_MODEL=flux-pro-1.1-ultra
|
||||
# BFL_BASE_URL=https://api.bfl.ai
|
||||
#
|
||||
# IDEOGRAM_API_KEY=your-ideogram-key
|
||||
# IDEOGRAM_MODEL=ideogram-v3
|
||||
# IDEOGRAM_BASE_URL=https://api.ideogram.ai
|
||||
#
|
||||
# MINIMAX_API_KEY=your-minimax-key
|
||||
# MINIMAX_MODEL=image-01
|
||||
# Default China endpoint / 默认国内地址
|
||||
# MINIMAX_BASE_URL=https://api.minimaxi.com/v1/image_generation
|
||||
# Optional overseas endpoint / 可选海外地址
|
||||
# MINIMAX_BASE_URL=https://api.minimax.io/v1/image_generation
|
||||
#
|
||||
# SILICONFLOW_API_KEY=your-siliconflow-key
|
||||
# SILICONFLOW_MODEL=Qwen/Qwen-Image
|
||||
# SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1/images/generations
|
||||
#
|
||||
# FAL_KEY=your-fal-key
|
||||
# FAL_MODEL=fal-ai/imagen3/fast
|
||||
# FAL_BASE_URL=https://fal.run
|
||||
#
|
||||
# REPLICATE_API_TOKEN=r8_xxx
|
||||
# REPLICATE_MODEL=black-forest-labs/flux-1.1-pro
|
||||
# REPLICATE_BASE_URL=https://api.replicate.com/v1/predictions
|
||||
#
|
||||
# OPENROUTER_API_KEY=sk-or-v1-xxx
|
||||
# OPENROUTER_MODEL=google/gemini-3.1-flash-image-preview
|
||||
# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
|
||||
#
|
||||
# OpenAI-compatible example: Agnes AI / OpenAI-compatible 示例：Agnes AI
|
||||
# IMAGE_BACKEND=openai
|
||||
# OPENAI_API_KEY=your-agnes-key
|
||||
# OPENAI_MODEL=agnes-image-2.1-flash
|
||||
# OPENAI_BASE_URL=https://apihub.agnes-ai.com/v1
|
||||
# OPENAI_SIZE_PRESET=gpt-image-2
|
||||
# OPENAI_RESPONSE_FORMAT=omit
|
||||
# OPENAI_QUALITY=omit
|
||||
#
|
||||
# IMAGE_BACKEND=modelscope
|
||||
# MODELSCOPE_API_KEY=your-modelscope-key
|
||||
# MODELSCOPE_MODEL=Tongyi-MAI/Z-Image-Turbo
|
||||
# MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Multi-provider example / 多提供商共存示例
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# IMAGE_BACKEND=openai
|
||||
# OPENAI_API_KEY=sk-xxx
|
||||
# OPENAI_MODEL=gpt-image-2
|
||||
# OPENAI_OUTPUT_FORMAT=png
|
||||
# GEMINI_API_KEY=your-gemini-api-key
|
||||
# GEMINI_MODEL=gemini-3.1-flash-image-preview
|
||||
#
|
||||
# Switch providers by changing IMAGE_BACKEND only.
|
||||
# 切换提供商时，只改 IMAGE_BACKEND 即可。
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Audio narration TTS (notes_to_audio.py) / 旁白音频 TTS
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# edge-tts is the default narration backend and needs no API key.
|
||||
# Use cloud providers only when you want high-quality or cloned voices —
|
||||
# all four (ElevenLabs / MiniMax / Qwen / CosyVoice) accept a cloned voice_id.
|
||||
# Clone the voice in the provider's console first, then pass --voice-id to
|
||||
# notes_to_audio.py. See docs/audio-narration.md "Use a cloned voice".
|
||||
# edge-tts 是默认旁白后端，无需 API Key。
|
||||
# 需要高质量云端旁白或复刻音色时再配置云端提供商——
|
||||
# ElevenLabs / MiniMax / Qwen / CosyVoice 四家都支持传入复刻 voice_id。
|
||||
# 先在 provider 控制台复刻得到 voice_id，再用 --voice-id 传给 notes_to_audio.py。
|
||||
# 详见 docs/zh/audio-narration.md "使用复刻音色"。
|
||||
#
|
||||
# ELEVENLABS_API_KEY=your-elevenlabs-api-key
|
||||
# MINIMAX_API_KEY=your-minimax-key
|
||||
# QWEN_API_KEY=your-dashscope-key
|
||||
# COSYVOICE_API_KEY=your-dashscope-key
|
||||
# DASHSCOPE_API_KEY=your-dashscope-key
|
||||
#
|
||||
# Optional provider-specific TTS endpoint overrides.
|
||||
# 可选：按提供商覆盖 TTS 接入点。
|
||||
# Default China endpoint / 默认国内地址
|
||||
# MINIMAX_TTS_BASE_URL=https://api.minimaxi.com/v1/t2a_v2
|
||||
# Optional overseas endpoint / 可选海外地址
|
||||
# MINIMAX_TTS_BASE_URL=https://api.minimax.io/v1/t2a_v2
|
||||
# QWEN_TTS_BASE_URL=https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
|
||||
# COSYVOICE_TTS_BASE_URL=https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer
|
||||
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Web image search (image_search.py) / 网络图片搜索
|
||||
# ─────────────────────────────────────────────────────────────
|
||||
# Used by scripts/image_search.py — separate from IMAGE_BACKEND above.
|
||||
# image_search.py 用，与上面的 IMAGE_BACKEND 互不影响。
|
||||
#
|
||||
# Openverse and Wikimedia work with no key, but image quality can be uneven.
|
||||
# For polished stock-style PPT images, configure Pexels and/or Pixabay.
|
||||
# Openverse 和 Wikimedia 无需 Key，但图片质量不稳定。
|
||||
# 如需更稳定的商业图库风格 PPT 配图，建议配置 Pexels 和/或 Pixabay。
|
||||
#
|
||||
# Sign up: https://www.pexels.com/api/
|
||||
# PEXELS_API_KEY=your-pexels-key
|
||||
# Sign up: https://pixabay.com/api/docs/
|
||||
# PIXABAY_API_KEY=your-pixabay-key
|
||||
2
agent/skills-disabled/ppt-master/.github/FUNDING.yml
vendored
Normal file
2
agent/skills-disabled/ppt-master/.github/FUNDING.yml
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
custom:
|
||||
- https://paypal.me/hugohe3
|
||||
91
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
91
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
@@ -0,0 +1,91 @@
|
||||
name: Bug Report
|
||||
description: Report a problem with PPT Master
|
||||
labels: ["bug"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for reporting! Please check the [FAQ](https://github.com/hugohe3/ppt-master/blob/main/docs/faq.md) first — your issue may already have a known solution.
|
||||
|
||||
- type: dropdown
|
||||
id: area
|
||||
attributes:
|
||||
label: Problem area
|
||||
options:
|
||||
- SVG generation / layout
|
||||
- PPTX export (svg_to_pptx.py)
|
||||
- Post-processing (finalize_svg.py / total_md_split.py)
|
||||
- Source conversion (PDF / DOCX / PPTX / URL to Markdown)
|
||||
- Template (create-template / template selection)
|
||||
- Image generation
|
||||
- Installation / dependencies
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: What happened?
|
||||
placeholder: Describe the problem clearly. Include error messages if any.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: Steps to reproduce
|
||||
placeholder: |
|
||||
1. ...
|
||||
2. ...
|
||||
3. ...
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: expected
|
||||
attributes:
|
||||
label: Expected behavior
|
||||
placeholder: What did you expect to happen?
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: input
|
||||
id: ai-tool
|
||||
attributes:
|
||||
label: AI editor / tool
|
||||
placeholder: "e.g. Claude Code, VS Code Copilot, Cursor, Codex"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: model
|
||||
attributes:
|
||||
label: AI model
|
||||
placeholder: "e.g. Claude Opus, Claude Sonnet, GPT-5.4, Gemini 3.1"
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: input
|
||||
id: os
|
||||
attributes:
|
||||
label: OS
|
||||
placeholder: "e.g. macOS 15, Windows 11, Ubuntu 24.04"
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: input
|
||||
id: python-version
|
||||
attributes:
|
||||
label: Python version
|
||||
placeholder: "e.g. 3.12.4"
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: screenshots
|
||||
attributes:
|
||||
label: Screenshots or files
|
||||
description: Attach screenshots, SVG files, or the generated PPTX if relevant.
|
||||
validations:
|
||||
required: false
|
||||
8
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
8
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
@@ -0,0 +1,8 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: FAQ
|
||||
url: https://github.com/hugohe3/ppt-master/blob/main/docs/faq.md
|
||||
about: Check known solutions before opening an issue
|
||||
- name: Discussions
|
||||
url: https://github.com/hugohe3/ppt-master/discussions
|
||||
about: Ask questions or share your work
|
||||
43
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
43
agent/skills-disabled/ppt-master/.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
@@ -0,0 +1,43 @@
|
||||
name: Feature Request
|
||||
description: Suggest an improvement or new feature
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: What problem does this solve?
|
||||
placeholder: Describe the pain point or use case that motivates this request.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: solution
|
||||
attributes:
|
||||
label: Proposed solution
|
||||
placeholder: How do you think this could be implemented? (optional but helpful)
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: dropdown
|
||||
id: area
|
||||
attributes:
|
||||
label: Area
|
||||
options:
|
||||
- Templates / styles
|
||||
- Charts / visualization
|
||||
- Export / post-processing
|
||||
- Source conversion
|
||||
- Image generation
|
||||
- Workflow / UX
|
||||
- Documentation
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: alternatives
|
||||
attributes:
|
||||
label: Alternatives considered
|
||||
placeholder: Any workarounds you've tried or other approaches you've considered?
|
||||
validations:
|
||||
required: false
|
||||
58
agent/skills-disabled/ppt-master/.github/workflows/deploy-pages.yml
vendored
Normal file
58
agent/skills-disabled/ppt-master/.github/workflows/deploy-pages.yml
vendored
Normal file
@@ -0,0 +1,58 @@
|
||||
# GitHub Pages 部署工作流
|
||||
# 自动将 PPT Master 示例项目部署到 GitHub Pages
|
||||
|
||||
name: Deploy to GitHub Pages
|
||||
|
||||
on:
|
||||
# 推送到 main 分支时，仅网页相关文件变更才触发
|
||||
push:
|
||||
branches: ["main"]
|
||||
paths:
|
||||
- 'index.html'
|
||||
- 'viewer.html'
|
||||
- 'examples/**'
|
||||
- '.github/workflows/deploy-pages.yml'
|
||||
# 允许手动触发（不受路径限制）
|
||||
workflow_dispatch:
|
||||
|
||||
# 设置 GITHUB_TOKEN 权限
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
# 防止并发部署
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
# 构建任务
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Pages
|
||||
uses: actions/configure-pages@v4
|
||||
with:
|
||||
enablement: true
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
# 上传整个仓库（包含 examples、templates 等）
|
||||
path: '.'
|
||||
|
||||
# 部署任务
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
186
agent/skills-disabled/ppt-master/.gitignore
vendored
Normal file
186
agent/skills-disabled/ppt-master/.gitignore
vendored
Normal file
@@ -0,0 +1,186 @@
|
||||
# Operating System Files
|
||||
# macOS
|
||||
.DS_Store
|
||||
.DS_Store?
|
||||
._*
|
||||
.Spotlight-V100
|
||||
.Trashes
|
||||
Icon
|
||||
.AppleDouble
|
||||
.LSOverride
|
||||
|
||||
# Windows
|
||||
Thumbs.db
|
||||
Thumbs.db:encryptable
|
||||
ehthumbs.db
|
||||
ehthumbs_vista.db
|
||||
Desktop.ini
|
||||
$RECYCLE.BIN/
|
||||
*.lnk
|
||||
|
||||
# Linux
|
||||
*~
|
||||
.directory
|
||||
.Trash-*
|
||||
|
||||
# Editor and IDE Files
|
||||
# VSCode
|
||||
.vscode/
|
||||
.claude/
|
||||
.spec-workflow/
|
||||
!.vscode/settings.json
|
||||
!.vscode/tasks.json
|
||||
!.vscode/launch.json
|
||||
!.vscode/extensions.json
|
||||
*.code-workspace
|
||||
|
||||
# JetBrains IDEs
|
||||
.idea/
|
||||
*.iml
|
||||
*.iws
|
||||
*.ipr
|
||||
out/
|
||||
|
||||
# Sublime Text
|
||||
*.sublime-project
|
||||
*.sublime-workspace
|
||||
|
||||
# Vim
|
||||
[._]*.s[a-v][a-z]
|
||||
[._]*.sw[a-p]
|
||||
[._]s[a-rt-v][a-z]
|
||||
[._]ss[a-gi-z]
|
||||
[._]sw[a-p]
|
||||
Session.vim
|
||||
.netrwhist
|
||||
|
||||
# Emacs
|
||||
*~
|
||||
\#*\#
|
||||
/.emacs.desktop
|
||||
/.emacs.desktop.lock
|
||||
*.elc
|
||||
auto-save-list
|
||||
tramp
|
||||
.\#*
|
||||
|
||||
# Temporary Files
|
||||
*.tmp
|
||||
*.temp
|
||||
*.bak
|
||||
*.swp
|
||||
*.swo
|
||||
*~.nib
|
||||
*.log
|
||||
|
||||
# Project Specific
|
||||
# Generated SVG files (uncomment if you don't want to commit generated files)
|
||||
# output/
|
||||
# generated/
|
||||
# *.svg
|
||||
|
||||
# Working drafts and notes (root-level only — project notes/ subdirs are tracked)
|
||||
/drafts/
|
||||
/notes/
|
||||
/scratch/
|
||||
.notes/
|
||||
|
||||
# Test files
|
||||
test_output/
|
||||
temp_files/
|
||||
|
||||
# Playwright (both MCP-side and visual-review script outputs)
|
||||
# MCP server auto-creates .playwright-mcp/ at CWD for snapshot/console logs
|
||||
.playwright-mcp/
|
||||
# Visual-review renderer writes per-project preview PNGs and the render lock
|
||||
projects/*/.preview/
|
||||
projects/*/.review/
|
||||
# Stray top-level screenshots created when MCP filename was a bare relative path
|
||||
# (the agreed convention is to always pass an absolute /tmp/... path)
|
||||
/probe-*.png
|
||||
/screenshot-*.png
|
||||
/page-*.png
|
||||
|
||||
# Large media files (if any)
|
||||
*.psd
|
||||
*.ai
|
||||
*.sketch
|
||||
*.fig
|
||||
|
||||
# Compressed files
|
||||
*.zip
|
||||
*.tar
|
||||
*.gz
|
||||
*.rar
|
||||
*.7z
|
||||
|
||||
# Documentation build outputs
|
||||
docs/_build/
|
||||
docs/.doctrees/
|
||||
site/
|
||||
|
||||
# Python (if you add Python tools later)
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
pip-wheel-metadata/
|
||||
share/python-wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
MANIFEST
|
||||
|
||||
# Node.js (if you add Node.js tools later)
|
||||
node_modules/
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
package-lock.json
|
||||
yarn.lock
|
||||
.npm
|
||||
.eslintcache
|
||||
|
||||
# Environment variables
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Database files
|
||||
*.db
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
|
||||
# Cache and locks
|
||||
.cache/
|
||||
*.lock
|
||||
.lock
|
||||
|
||||
# Live preview direct-edit history (per-project, regenerated on edit)
|
||||
.live_edits.jsonl
|
||||
|
||||
# Personal notes
|
||||
TODO.md
|
||||
PERSONAL_NOTES.md
|
||||
|
||||
# Projects directory - Work-in-progress projects (not version controlled)
|
||||
# Completed projects should be moved to examples/
|
||||
# Use cloud sync (iCloud/Dropbox) for backup and multi-device access
|
||||
projects/*
|
||||
!projects/README.md
|
||||
96
agent/skills-disabled/ppt-master/AGENTS.md
Normal file
96
agent/skills-disabled/ppt-master/AGENTS.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# AGENTS.md
|
||||
|
||||
This file is the project entry point for general AI agents.
|
||||
|
||||
**You MUST read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before any PPT generation task or repo modification.** This repository exists to generate presentations; SKILL.md is the authoritative workflow that owns project creation, role switching, serial execution, quality gates, post-processing, export, and every per-step command. The rest of this file only points to where related material lives — it never substitutes for SKILL.md.
|
||||
|
||||
## Project Overview
|
||||
|
||||
PPT Master is an AI-driven presentation generation system. Multi-role collaboration (Strategist → Image_Generator → Executor) converts source documents (PDF/DOCX/URL/Markdown) into natively editable PPTX with real PowerPoint shapes (DrawingML).
|
||||
|
||||
**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Eight Confirmations → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export PPTX`
|
||||
|
||||
> Topic-only requests with no source material: run the standalone [`topic-research`](skills/ppt-master/workflows/topic-research.md) workflow before SKILL.md Step 1 to gather web materials.
|
||||
>
|
||||
> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to reuse the original PPT design or fill content back into it (for example, "fill this deck with the new content", "fill this back into the template", or "reuse this deck's design"), run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route edits PPTX directly and must not enter the SVG generation pipeline.
|
||||
>
|
||||
> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
|
||||
>
|
||||
> Decks containing data charts: run the standalone [`verify-charts`](skills/ppt-master/workflows/verify-charts.md) workflow between the executor and post-processing steps to calibrate chart coordinates.
|
||||
>
|
||||
> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.
|
||||
>
|
||||
> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export already has global animations; do not create `animations.json` unless customization was requested.
|
||||
>
|
||||
> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.
|
||||
>
|
||||
> Brand identity setup: when the user asks to "set up brand" / "建立品牌" / "做品牌规范", provides a brand asset (logo / brand site URL / branded PPTX / brand PDF), or wants to extract a brand from existing materials, run the standalone [`create-brand`](skills/ppt-master/workflows/create-brand.md) workflow. Output goes to `skills/ppt-master/templates/brands/<id>/`. Brands apply at SKILL.md Step 3 via the same explicit-path rule as layout templates — the user supplies the brand directory path to apply it; bare brand names never trigger.
|
||||
>
|
||||
> Visual self-check: only when the user explicitly requests a per-page visual review on the generated SVGs (e.g., "跑一下视觉自检 / 视觉回看 / 视觉 rubric", "visual review", "check each page visually"), run the standalone [`visual-review`](skills/ppt-master/workflows/visual-review.md) workflow between the executor and post-processing steps. The main pipeline does NOT invoke it automatically; do not infer or recommend it from deck size, model identity, or any other signal — user request is the only trigger.
|
||||
|
||||
## Execution Requirements
|
||||
|
||||
- For standalone template creation (no source deck), read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).
|
||||
- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).
|
||||
- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).
|
||||
- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).
|
||||
|
||||
## Required Conventions
|
||||
|
||||
- **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/).
|
||||
- **Markdown language consistency** — Markdown files under `skills/ppt-master/workflows/`, `skills/ppt-master/references/`, and `docs/` are currently single-language per directory. New files mirror the language of their siblings; do not mix English scaffolding with Chinese paragraphs (or vice versa) inside one file. Chat replies are unaffected.
|
||||
|
||||
## Compatibility Boundary
|
||||
|
||||
- This repository is a workflow/skill package, not an app or service scaffold.
|
||||
- Do NOT assume generic-project conventions like `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.
|
||||
- On conflict with a generic coding skill, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) inside this repository.
|
||||
|
||||
## Command Quick Reference
|
||||
|
||||
Convenience summary only — full workflow in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).
|
||||
|
||||
```bash
|
||||
# Source content conversion
|
||||
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/excel_to_md.py <XLSX_or_XLSM_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
|
||||
|
||||
# Project management
|
||||
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
|
||||
python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
|
||||
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
|
||||
|
||||
# Image tools and SVG quality check
|
||||
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images
|
||||
# In-pipeline AI image generation — manifest mode (required, even for 1 image):
|
||||
python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json
|
||||
python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json
|
||||
# Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar):
|
||||
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
|
||||
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live
|
||||
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
|
||||
python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation
|
||||
python3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export
|
||||
|
||||
# Post-processing pipeline: run sequentially, one command at a time
|
||||
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
|
||||
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>
|
||||
# Mergeable dy-stacked paragraph blocks collapse into one editable text frame by default; add --no-merge to keep every line as its own frame (strict line fidelity). See SKILL.md Step 7.3.
|
||||
```
|
||||
|
||||
## Core Directories
|
||||
|
||||
- `skills/ppt-master/SKILL.md` — main workflow authority.
|
||||
- `skills/ppt-master/references/` — role definitions and technical specifications.
|
||||
- `skills/ppt-master/scripts/` — runnable tool scripts.
|
||||
- `skills/ppt-master/scripts/docs/` — topic-focused script docs.
|
||||
- `skills/ppt-master/templates/` — layout templates, chart templates, icon library, brand presets.
|
||||
- `skills/ppt-master/workflows/` — standalone workflow files.
|
||||
- `docs/` — user-facing documentation (FAQ, installation, technical design, templates guide, audio narration).
|
||||
- `docs/rules/` — repo-wide style rules.
|
||||
- `examples/` — example projects.
|
||||
- `projects/` — user project workspace.
|
||||
100
agent/skills-disabled/ppt-master/CLAUDE.md
Normal file
100
agent/skills-disabled/ppt-master/CLAUDE.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file is the project entry point for Claude Code.
|
||||
|
||||
**You MUST read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before any PPT generation task or repo modification.** This repository exists to generate presentations; SKILL.md is the authoritative workflow that owns project creation, role switching, serial execution, quality gates, post-processing, export, and every per-step command. The rest of this file only points to where related material lives — it never substitutes for SKILL.md.
|
||||
|
||||
## Project Overview
|
||||
|
||||
PPT Master is an AI-driven presentation generation system. Multi-role collaboration (Strategist → Image_Generator → Executor) converts source documents (PDF/DOCX/URL/Markdown) into natively editable PPTX with real PowerPoint shapes (DrawingML).
|
||||
|
||||
**Core Pipeline**: `Source Document → Create Project → [Template] → Strategist Eight Confirmations → [Image_Generator] → Executor Live Preview → Quality Check → Post-processing → Export PPTX`
|
||||
|
||||
> Topic-only requests with no source material: run the standalone [`topic-research`](skills/ppt-master/workflows/topic-research.md) workflow before SKILL.md Step 1 to gather web materials.
|
||||
>
|
||||
> Template fill: when the user provides an existing `.pptx` template plus text materials or a topic and asks to reuse the original PPT design or fill content back into it (for example, "fill this deck with the new content", "fill this back into the template", or "reuse this deck's design"), run the standalone [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md) workflow. This route edits PPTX directly and must not enter the SVG generation pipeline.
|
||||
>
|
||||
> Phase B resumption (split-mode execution): when the user opens a fresh chat and says "继续生成 projects/<x>" or similar, run the standalone [`resume-execute`](skills/ppt-master/workflows/resume-execute.md) workflow to enter Phase B (SVG generation + export) without re-running Phase A.
|
||||
>
|
||||
> Decks containing data charts: run the standalone [`verify-charts`](skills/ppt-master/workflows/verify-charts.md) workflow between the executor and post-processing steps to calibrate chart coordinates.
|
||||
>
|
||||
> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.
|
||||
>
|
||||
> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export already has global animations; do not create `animations.json` unless customization was requested.
|
||||
>
|
||||
> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.
|
||||
>
|
||||
> Brand identity setup: when the user asks to "set up brand" / "建立品牌" / "做品牌规范", provides a brand asset (logo / brand site URL / branded PPTX / brand PDF), or wants to extract a brand from existing materials, run the standalone [`create-brand`](skills/ppt-master/workflows/create-brand.md) workflow. Output goes to `skills/ppt-master/templates/brands/<id>/`. Brands apply at SKILL.md Step 3 via the same explicit-path rule as layout templates — the user supplies the brand directory path to apply it; bare brand names never trigger.
|
||||
>
|
||||
> Visual self-check: only when the user explicitly requests a per-page visual review on the generated SVGs (e.g., "跑一下视觉自检 / 视觉回看 / 视觉 rubric", "visual review", "check each page visually"), run the standalone [`visual-review`](skills/ppt-master/workflows/visual-review.md) workflow between the executor and post-processing steps. The main pipeline does NOT invoke it automatically; do not infer or recommend it from deck size, model identity, or any other signal — user request is the only trigger.
|
||||
|
||||
## Execution Requirements
|
||||
|
||||
- For standalone template creation (no source deck), read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).
|
||||
- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).
|
||||
- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).
|
||||
- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).
|
||||
|
||||
## Required Conventions
|
||||
|
||||
- **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/).
|
||||
- **Markdown language consistency** — Markdown files under `skills/ppt-master/workflows/`, `skills/ppt-master/references/`, and `docs/` are currently single-language per directory. New files mirror the language of their siblings; do not mix English scaffolding with Chinese paragraphs (or vice versa) inside one file. Chat replies are unaffected.
|
||||
|
||||
## Compatibility Boundary
|
||||
|
||||
- This repository is a workflow/skill package, not an app or service scaffold.
|
||||
- Do NOT assume generic-project conventions like `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.
|
||||
- On conflict with a generic coding skill, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) inside this repository.
|
||||
|
||||
## Command Quick Reference
|
||||
|
||||
Convenience summary only — full workflow in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).
|
||||
|
||||
```bash
|
||||
# Source content conversion
|
||||
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/excel_to_md.py <XLSX_or_XLSM_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
|
||||
python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
|
||||
|
||||
# Project management
|
||||
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
|
||||
python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
|
||||
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
|
||||
|
||||
# Image tools and SVG quality check
|
||||
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images
|
||||
# Formula rendering — manifest written by Strategist after typography confirmation:
|
||||
python3 skills/ppt-master/scripts/latex_render.py <project_path>
|
||||
python3 skills/ppt-master/scripts/latex_render.py <project_path> --dry-run
|
||||
python3 skills/ppt-master/scripts/latex_render.py <project_path> --providers codecogs,quicklatex,mathpad,wikimedia
|
||||
# In-pipeline AI image generation — manifest mode (required, even for 1 image):
|
||||
python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json
|
||||
python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json
|
||||
# Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar):
|
||||
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
|
||||
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live
|
||||
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
|
||||
python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation
|
||||
python3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export
|
||||
|
||||
# Post-processing pipeline: run sequentially, one command at a time
|
||||
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
|
||||
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>
|
||||
# Mergeable dy-stacked paragraph blocks collapse into one editable text frame by default; add --no-merge to keep every line as its own frame (strict line fidelity). See SKILL.md Step 7.3.
|
||||
```
|
||||
|
||||
## Core Directories
|
||||
|
||||
- `skills/ppt-master/SKILL.md` — main workflow authority.
|
||||
- `skills/ppt-master/references/` — role definitions and technical specifications.
|
||||
- `skills/ppt-master/scripts/` — runnable tool scripts.
|
||||
- `skills/ppt-master/scripts/docs/` — topic-focused script docs.
|
||||
- `skills/ppt-master/templates/` — layout templates, chart templates, icon library, brand presets.
|
||||
- `skills/ppt-master/workflows/` — standalone workflow files.
|
||||
- `docs/` — user-facing documentation (FAQ, installation, technical design, templates guide, audio narration).
|
||||
- `docs/rules/` — repo-wide style rules.
|
||||
- `examples/` — example projects.
|
||||
- `projects/` — user project workspace.
|
||||
90
agent/skills-disabled/ppt-master/CODE_OF_CONDUCT.md
Normal file
90
agent/skills-disabled/ppt-master/CODE_OF_CONDUCT.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our Commitment
|
||||
|
||||
We want PPT Master to be a welcoming, respectful, and professional open-source community for everyone.
|
||||
|
||||
As maintainers, contributors, and participants, we are committed to making participation in this project harassment-free for all people, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity or expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
|
||||
|
||||
We aim to build a community where people can collaborate constructively, share ideas openly, and contribute safely.
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
Examples of behavior that help create a positive community include:
|
||||
|
||||
- Showing empathy, patience, and kindness toward others
|
||||
- Respecting different opinions, experiences, and viewpoints
|
||||
- Giving and receiving constructive feedback professionally
|
||||
- Taking responsibility for mistakes and learning from them
|
||||
- Focusing on what benefits the project and its community
|
||||
|
||||
## Unacceptable Behavior
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
- Harassment, intimidation, threats, or stalking
|
||||
- Insulting, demeaning, or discriminatory comments
|
||||
- Personal attacks or hostile interactions
|
||||
- Sexualized language, imagery, or unwanted sexual attention
|
||||
- Trolling, deliberate provocation, or repeated bad-faith arguments
|
||||
- Publishing someone’s private information without permission, including physical or email addresses
|
||||
- Any other conduct that would reasonably be considered inappropriate in a professional community setting
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies in all project spaces, including but not limited to:
|
||||
|
||||
- GitHub issues
|
||||
- Pull requests
|
||||
- Discussions
|
||||
- Project documentation
|
||||
- Community chat or social spaces associated with the project
|
||||
- Public interactions where someone is representing the project
|
||||
|
||||
## Reporting
|
||||
|
||||
If you experience or witness behavior that violates this Code of Conduct, please report it to:
|
||||
|
||||
**heyug3@gmail.com**
|
||||
|
||||
Please include, when possible:
|
||||
|
||||
- A description of the incident
|
||||
- Where it happened
|
||||
- Links, screenshots, or other relevant evidence
|
||||
- Any other context that may help review the report
|
||||
|
||||
All reports will be reviewed as promptly and fairly as possible. We will make a good-faith effort to protect the privacy and safety of the reporter.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Project maintainers are responsible for interpreting and enforcing this Code of Conduct.
|
||||
|
||||
Maintainers may take any action they believe is appropriate in response to behavior that violates this policy, including:
|
||||
|
||||
- Asking for correction
|
||||
- Issuing a warning
|
||||
- Removing comments, issues, commits, or other contributions
|
||||
- Temporarily restricting participation
|
||||
- Permanently banning participation in project spaces
|
||||
|
||||
Enforcement decisions will be made with the goal of protecting the community and maintaining a healthy working environment.
|
||||
|
||||
## Enforcement Principles
|
||||
|
||||
When deciding how to respond, maintainers may consider:
|
||||
|
||||
- The seriousness of the behavior
|
||||
- Whether the behavior is repeated
|
||||
- Whether the behavior appears intentional
|
||||
- The impact on individuals and the broader community
|
||||
|
||||
Possible responses may range from a private warning to a temporary or permanent ban, depending on the circumstances.
|
||||
|
||||
## Maintainer Responsibility
|
||||
|
||||
Maintainers are expected to enforce this Code of Conduct consistently and in good faith. They should communicate moderation decisions clearly when appropriate and act in a way that supports a safe, respectful, and collaborative community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is based on the principles of Contributor Covenant version 2.1. The official Contributor Covenant materials and adoption guidance are available on the Contributor Covenant website.
|
||||
98
agent/skills-disabled/ppt-master/CONTRIBUTING.md
Normal file
98
agent/skills-disabled/ppt-master/CONTRIBUTING.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Contributing to PPT Master
|
||||
|
||||
Thank you for your interest in contributing! This guide will help you get started.
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
- **Templates** — New layout templates or visual styles
|
||||
- **Charts** — Additional chart types or SVG chart templates
|
||||
- **Icons** — Vector icons for the icon library
|
||||
- **Scripts** — Improvements to conversion or post-processing scripts
|
||||
- **Docs** — Clarifications, translations, or new guides
|
||||
- **Bug reports** — Reproducible issues with clear descriptions
|
||||
- **Ideas** — Feature requests and design suggestions
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Python 3.10+** — the only required dependency
|
||||
- **Node.js 18+** and **Pandoc** are edge-case fallbacks that 99% of contributors never need; install only if you're working on the specific paths that require them. See the [README Quick Start](./README.md#1-prerequisites) for when each applies.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hugohe3/ppt-master.git
|
||||
cd ppt-master
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Before You Open a PR
|
||||
|
||||
PPT Master is solo-maintained with limited review bandwidth. To keep things healthy for everyone:
|
||||
|
||||
- **Tiny fixes** (typos, one-line usage/doc corrections, obvious small inconsistencies) — please open an issue instead of a PR. A clear report is usually faster for the maintainer to apply directly
|
||||
- **Focused bug fixes** — PRs are welcome when the fix is self-contained, has clear reproduction steps, and includes local verification
|
||||
- **Substantial features, new backends, or new abstractions** — please open an issue first to discuss fit and direction. PRs submitted without prior discussion may be closed without detailed review
|
||||
- **Refactors, structural changes, broad cleanup, or workflow changes** — open an issue first. The project deliberately stays close to its current shape
|
||||
|
||||
This isn't gatekeeping — it protects your time. A PR should be a meaningful, independently reviewable change, not just a few lines the maintainer could patch faster from an issue report. A 500-line PR that doesn't match the project direction is worse for you than a 10-line issue comment that clarifies it upfront.
|
||||
|
||||
## What We Accept / What We Don't
|
||||
|
||||
**Welcome:**
|
||||
- Bug fixes with clear reproduction
|
||||
- New layout templates, chart templates, icons
|
||||
- Documentation clarifications and translations
|
||||
- Additional image backends that follow the existing `image_backends/` pattern
|
||||
- SVG quality improvements that stay within the declared constraints
|
||||
|
||||
**Not a fit (please don't open PRs for these):**
|
||||
- Introducing `uv`, `poetry`, or other tools as required dependencies — `pip + requirements.txt` is the only official install path
|
||||
- Adding CI, test frameworks, pre-commit hooks, or linting infrastructure — deliberately out of scope for a solo-maintained project
|
||||
- Repackaging the skill as a CLI, SaaS, desktop app, or installer — PPT Master is a chat-driven skill for AI IDEs by design
|
||||
- Architectural refactors or large-scale renames — incremental cleanup only
|
||||
- "Drive-by" cosmetic reformatting unrelated to a real fix
|
||||
|
||||
If you're unsure, open an issue to ask — that's always welcome.
|
||||
|
||||
## Contribution Workflow
|
||||
|
||||
1. **Fork** the repository and create a branch from `main`
|
||||
2. **One PR, one thing** — keep each PR focused on a single concern. If you notice unrelated improvements, open a separate PR
|
||||
3. **Write a useful PR description** — explain *what* changed and *why*, not just a diff summary. If your change fixes a bug, include reproduction steps
|
||||
4. **Test locally** before submitting — run the affected scripts and verify output
|
||||
5. **Don't overstate** — if your PR description claims tests or behavior changes, make sure the diff actually contains them
|
||||
|
||||
## Review Process
|
||||
|
||||
- Reviews are best-effort, usually within a few days. Ping the PR if it's been a week without response
|
||||
- Review feedback will be specific: what to change, and whether it's a blocker. If a PR needs more than ~2 rounds to converge, it may be closed with a note — reopening is fine once the direction is clearer
|
||||
- Focused fixes may be merged as-is; larger contributions will usually be squash-merged to keep history readable
|
||||
|
||||
## SVG Guidelines
|
||||
|
||||
If your contribution involves SVG files, follow the technical constraints documented in [CLAUDE.md](./CLAUDE.md):
|
||||
|
||||
- Do not use: `mask`, `<style>`, `class`, external CSS, `<foreignObject>`, `<animate*>`, `<script>`, `<symbol>+<use>`
|
||||
- Use `fill-opacity` / `stroke-opacity` instead of `rgba()`
|
||||
- `marker-start` / `marker-end` are conditionally allowed — see `shared-standards.md` §1.1 (must live in `<defs>`, `orient="auto"`, shape must be triangle / diamond / oval)
|
||||
- `clipPath` on `<image>` is conditionally allowed — see `shared-standards.md` §1.2 (must live in `<defs>`, single shape child, only on `<image>` elements)
|
||||
- All SVGs must use the correct `viewBox` for the target canvas format
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
Open an issue on [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) and include:
|
||||
|
||||
- A clear description of the problem
|
||||
- Steps to reproduce
|
||||
- Expected vs. actual behavior
|
||||
- Environment details (OS, Python version, AI editor used)
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Please read and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE).
|
||||
21
agent/skills-disabled/ppt-master/LICENSE
Normal file
21
agent/skills-disabled/ppt-master/LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025-2026 Hugo He
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
355
agent/skills-disabled/ppt-master/README.md
Normal file
355
agent/skills-disabled/ppt-master/README.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# PPT Master — AI generates natively editable PPTX from any document
|
||||
|
||||
[](https://github.com/hugohe3/ppt-master/releases)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/hugohe3/ppt-master/stargazers)
|
||||
[](https://atomgit.com/hugohe3/ppt-master)
|
||||
|
||||
English | [中文](./README_CN.md)
|
||||
|
||||
<p align="center">
|
||||
<sub>This project is kept free and open source with the support of <a href="https://www.packyapi.com/register?aff=ppt-master">PackyCode</a>, <a href="https://apikey.fun/register?aff=PPT-MASTER">APIKEY.FUN</a> and other sponsors.</sub>
|
||||
</p>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="180"><a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td>
|
||||
<td>Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our project users: register using <a href="https://www.packyapi.com/register?aff=ppt-master">this link</a> and enter the promo code <strong>ppt-master</strong> during recharge to get 10% off.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="180"><a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" width="150"></a></td>
|
||||
<td>Thanks to APIKEY.FUN for sponsoring this project! APIKEY.FUN is a professional enterprise-grade AI relay service committed to stable, efficient, and low-cost AI access for businesses and developers. The platform supports mainstream models including Claude, OpenAI, and Gemini, with prices as low as <strong>7% of official rates</strong>. Register through <a href="https://apikey.fun/register?aff=PPT-MASTER">our dedicated link</a> for an exclusive perk: <strong>up to 5% off on top-ups, permanently</strong>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ### This is a tool, not a wishing well
|
||||
> Don't expect it to hand you a finished, perfect deck in one shot. Its real value is taking most of the tedious work off your plate; the polishing that's left is yours — a natively editable deck exists precisely so you can keep working on it, not a flat image you can't touch. The cheaper the model, the more there is to do. How good the result turns out comes down to your skill with this project and with PowerPoint.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://hugohe3.github.io/ppt-master/"><strong>Live Demo</strong></a> ·
|
||||
<a href="https://www.hehugo.com/"><strong>About Hugo He</strong></a> ·
|
||||
<a href="./examples/"><strong>Examples</strong></a> ·
|
||||
<a href="./docs/faq.md"><strong>FAQ</strong></a> ·
|
||||
<a href="./docs/roadmap.md"><strong>Roadmap</strong></a> ·
|
||||
<a href="mailto:heyug3@gmail.com"><strong>Contact</strong></a>
|
||||
</p>
|
||||
|
||||
<h3 align="center">Download the new <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">narrated <em>Attention Is All You Need</em> deck</a> — play it in PowerPoint and every slide reads itself out loud. That's just the tip of what PPT Master can do.</h3>
|
||||
<h3 align="center">Of course, you can also download any of the six example decks below — opening the raw .pptx in PowerPoint is the fastest way to see this project's real capability ceiling.</h3>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026"><img src="docs/assets/screenshots/preview_pritzker_2026.png" alt="Editorial magazine — Pritzker 2026 architecture review" /></a><br/>
|
||||
<sub><b>Editorial Magazine</b> — architecture photography, calm typographic grid<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_pritzker_2026/exports/pritzker_2026.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026"><img src="docs/assets/screenshots/preview_global_ai_capital.png" alt="Data journalism — Global AI Capital 2026" /></a><br/>
|
||||
<sub><b>Data Journalism</b> — Bloomberg-style dark dashboard, chart-driven<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_global_ai_capital_2026/exports/global_ai_capital_2026.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems"><img src="docs/assets/screenshots/preview_swiss_grid.png" alt="Swiss typographic grid — Grid Systems primer" /></a><br/>
|
||||
<sub><b>Swiss Grid</b> — strict modular grid, restrained type, red-accent<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_swiss_grid_systems/exports/swiss_grid_systems.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo"><img src="docs/assets/screenshots/preview_glassmorphism_demo.png" alt="Glassmorphism SaaS — AI Agent engineering demo" /></a><br/>
|
||||
<sub><b>Glassmorphism SaaS</b> — translucent layers, gradient depth, product UI<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_glassmorphism_demo/exports/glassmorphism_demo.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis"><img src="docs/assets/screenshots/preview_sugar_rush_memphis.png" alt="Memphis pop — Sugar Rush festival" /></a><br/>
|
||||
<sub><b>Memphis Pop</b> — bold primaries, geometric patterns, playful energy<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_sugar_rush_memphis/exports/sugar_rush_memphis.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide"><img src="docs/assets/screenshots/preview_indie_bookstore_zine.png" alt="Risograph zine — Indie bookstore guide" /></a><br/>
|
||||
<sub><b>Risograph Zine</b> — duotone print, hand-made bookstore-culture feel<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide">Flip online</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_indie_bookstore_zine_guide/exports/indie_bookstore_zine_guide.pptx">Download .pptx</a></sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p align="center">
|
||||
<sub>Generated with Claude Opus 4.7 + <code>gpt-image-2</code>. <a href="https://hugohe3.github.io/ppt-master/">Flip through all examples online →</a> · <a href="./examples/"><code>examples/</code> directory</a> · <a href="./docs/why-ppt-master.md">Why PPT Master?</a></sub>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
Drop in your source material and get back a **real PowerPoint**: directly editable, with native slide transitions and entrance animations, speaker notes you can turn into audio narration, and the option to follow your own PPT template — a complete deck you can present as-is and keep editing. How to use each capability → [Getting Started](./docs/getting-started.md).
|
||||
|
||||
> **⚠️ PPT Master is a harness, not a complete agent.** `harness + model = agent` — the tool owns the workflow; the model sets the ceiling. To form a genuinely high-quality agent, use **Claude with a large context window (~1M tokens) + AI image generation (`gpt-image-2`)**. Other models can run the pipeline but cannot reach the same quality ceiling. If results disappoint, upgrade the model — don't blame the harness.
|
||||
|
||||
> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.
|
||||
>
|
||||
> **What you'll do**: install Python, install an AI IDE, drop in your material.
|
||||
|
||||
> **Why it's shaped this way** — knowing how to use Python and AI agents will matter more and more. This project is meant to show how far you can go with just those two things. There's a learning curve if you're starting cold, but it's the curve worth climbing. Making a deck is just the excuse — what I'm really pushing is Python and agents.
|
||||
|
||||
PPT Master is different:
|
||||
|
||||
- **Real PowerPoint** — if a file can't be opened and edited in PowerPoint, it shouldn't be called a PPT. Every element PPT Master outputs is directly clickable and editable
|
||||
- **Transparent, predictable cost** — the tool is free and open source; the only cost is your AI model usage. As AI tools move to usage-based billing, you pay exactly what you consume — no separate PPT subscription added on top
|
||||
- **Data stays local** — your files shouldn't have to be uploaded to someone else's server just to make a presentation. Apart from AI model communication, the entire pipeline runs on your machine
|
||||
- **No platform lock-in** — your workflow shouldn't be held hostage by any single company. Works with Claude Code, Cursor, VS Code Copilot, and more; supports Claude, GPT, Gemini, Kimi, and other models
|
||||
|
||||
AI presentation tools roughly fall into four categories. PPT Master only does the last one:
|
||||
|
||||
| Category | Output | Editable element-by-element in PowerPoint? |
|
||||
|---|---|:---:|
|
||||
| Template fill-in | PPTX built from a fixed template | Partially — limited by the template |
|
||||
| Image-based | One large image per slide, packed into PPTX | ❌ each slide is a picture |
|
||||
| HTML presentation | Web-based deck | ❌ not a PPTX |
|
||||
| **Native editable (PPT Master)** | **Real DrawingML shapes, text boxes, charts** | ✅ click any element to edit |
|
||||
|
||||
---
|
||||
|
||||
## The person using it matters more
|
||||
|
||||
The examples above were all made in a single pass — I didn't even refine them; spend some time polishing and it's a different story entirely. With the same PowerPoint, a designer can produce something stunning while most people only ever touch a few basic features — the difference isn't the tool, it's the person using it. If you can't get there yet, it's most likely that you haven't learned the workflow — start with [Getting Started](./docs/getting-started.md) and the example projects.
|
||||
|
||||
The best results do need Claude. Before you call it expensive, think about what it would cost to hire someone to produce a deck at the same level. The project also supports GPT, Gemini, Kimi, and other models — the results simply differ. Expecting top-tier output while paying the lowest possible cost was never reasonable to begin with.
|
||||
|
||||
---
|
||||
|
||||
## Built by Hugo He
|
||||
|
||||
I'm a finance professional (CPA · CPV · Consulting Engineer (Investment)) who regularly reviews and edits presentation decks. I wanted AI-generated slides to remain editable in PowerPoint, not flattened into images — so I built this.
|
||||
|
||||
🌐 [Personal website](https://www.hehugo.com/) · 📧 [heyug3@gmail.com](mailto:heyug3@gmail.com) · 🐙 [@hugohe3](https://github.com/hugohe3)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Prerequisites
|
||||
|
||||
**You only need Python.** Everything else is installed via `pip install -r requirements.txt`.
|
||||
|
||||
| Dependency | Required? | What it does |
|
||||
|------------|:---------:|--------------|
|
||||
| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — the only thing you actually need to install |
|
||||
|
||||
> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations.
|
||||
|
||||
<details open>
|
||||
<summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>
|
||||
|
||||
Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrote a **step-by-step guide** specifically for Windows users:
|
||||
|
||||
**📖 [Windows Installation Guide](./docs/windows-installation.md)** — from zero to a working presentation in 10 minutes.
|
||||
|
||||
Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → `pip install -r requirements.txt` → done.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>macOS / Linux</strong> — install and go</summary>
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install python
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install python3 python3-pip
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Edge-case fallback</strong> — 99% of users don't need this</summary>
|
||||
|
||||
**Pandoc** — only needed for legacy document formats: `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`, `.html`, `.epub`, `.ipynb` are handled natively by Python — no pandoc required.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install pandoc
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install pandoc
|
||||
```
|
||||
</details>
|
||||
|
||||
### 2. Pick an Agent
|
||||
|
||||
PPT Master runs in **any tool with agent capability** — read/write files, execute commands, and sustain multi-turn conversation.
|
||||
|
||||
| Type | Examples | Notes |
|
||||
|---|---|---|
|
||||
| **IDE-native agent** | • VS Code architecture ([VS Code](https://code.visualstudio.com/) itself, plus forks & derivatives): [Cursor](https://cursor.sh/), Trae, Codebuddy IDE, [Windsurf](https://codeium.com/windsurf), Void, etc.<br>• Other architectures: [Zed](https://zed.dev/), etc. | Editor with a built-in agent |
|
||||
| **IDE plugin / extension** | [GitHub Copilot](https://github.com/features/copilot), [Claude Code](https://claude.ai/code) (VS Code / JetBrains extension), [Cline](https://cline.bot/), [Continue](https://continue.dev/), Roo Code, etc. | Installed inside hosts like VS Code or JetBrains |
|
||||
| **CLI agent** | [Claude Code](https://claude.ai/code) CLI, [Codex CLI](https://github.com/openai/codex), [Aider](https://aider.chat/), Gemini CLI, etc. | Runs in the terminal; suits scripting, remote, or server use |
|
||||
|
||||
> **Model recommendation**: for the best results, use **Claude Opus** with `gpt-image-2`; **Gemini 3.5 Flash** currently offers great overall value for money — notably fast and well worth a try.
|
||||
|
||||
**🔑 Want to use Claude / GPT / Gemini but don't have access yet?** Project sponsors **[PackyCode](https://www.packyapi.com/register?aff=ppt-master)** and **[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER)** can help — both offer pay-as-you-go access to Claude, GPT, Gemini and more, no subscription required. **PackyCode**: 10% off with promo code **`ppt-master`** at top-up. **APIKEY.FUN**: prices as low as **7% of official rates**; register via our link for an exclusive permanent discount of up to 5% on top-ups.
|
||||
|
||||
### 3. Set Up
|
||||
|
||||
**Option A — Download ZIP** (no Git required): click **Code → Download ZIP** on the [GitHub page](https://github.com/hugohe3/ppt-master), then unzip.
|
||||
|
||||
**Option B — Git clone** (requires [Git](https://git-scm.com/downloads) installed):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hugohe3/ppt-master.git
|
||||
cd ppt-master
|
||||
```
|
||||
|
||||
Then install dependencies:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
To update later (Option A / B): `python3 skills/ppt-master/scripts/update_repo.py`
|
||||
|
||||
> **Option C — Skill marketplace**: the repo ships `.claude-plugin/marketplace.json`, so it can be installed through the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem:
|
||||
>
|
||||
> ```bash
|
||||
> # Cross-agent CLI (Claude Code, Cursor, Codex, etc.)
|
||||
> npx skills add hugohe3/ppt-master
|
||||
>
|
||||
> # Or inside Claude Code
|
||||
> /plugin marketplace add hugohe3/ppt-master
|
||||
> /plugin install ppt-master@ppt-master
|
||||
> ```
|
||||
>
|
||||
> Both install paths above only fetch the skill files (not the full repo); you still need to `pip install -r requirements.txt` from the installed location for the post-processing scripts to run.
|
||||
|
||||
### 4. Create
|
||||
|
||||
**Provide source materials (recommended):** Place your PDF, DOCX, images, or other files in the `projects/` directory, then tell the AI chat panel which files to use. The quickest way to get the path: right-click the file in your file manager or IDE sidebar → **Copy Path** (or **Copy Relative Path**) and paste it directly into the chat.
|
||||
|
||||
```
|
||||
You: Please create a PPT from projects/q3-report/sources/report.pdf
|
||||
```
|
||||
|
||||
**Paste content directly:** You can also paste text content straight into the chat window and the AI will generate a PPT from it.
|
||||
|
||||
```
|
||||
You: Please turn the following into a PPT: [paste your content here...]
|
||||
```
|
||||
|
||||
Either way, the AI will first confirm the design spec:
|
||||
|
||||
```
|
||||
AI: Sure. Let's confirm the design spec:
|
||||
[Template] B) Free design
|
||||
[Format] PPT 16:9
|
||||
[Pages] 8-10 pages
|
||||
...
|
||||
```
|
||||
|
||||
The AI handles everything — content analysis, visual design, SVG generation, and PPTX export.
|
||||
|
||||
> **Output:** Native-shapes `.pptx` (directly editable) saved to `exports/<name>_<timestamp>.pptx`. A copy of `svg_output/` is always snapshotted to `backup/<timestamp>/svg_output/` for re-export / archival. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` (see [FAQ](./docs/faq.md)). Requires Office 2016+.
|
||||
|
||||
> **Already have a `.pptx` you want to reuse?** Hand the AI that deck plus your material and ask it to "fill this deck with the new content" — it fills text, table, and chart data into your existing design and exports only the pages you pick, staying natively editable. See the [FAQ](./docs/faq.md) and [template-fill workflow](./skills/ppt-master/workflows/template-fill-pptx.md).
|
||||
|
||||
> **AI lost context?** Ask it to read `skills/ppt-master/SKILL.md`.
|
||||
|
||||
> **Something went wrong?** Check the **[FAQ](./docs/faq.md)** — it covers model selection, layout issues, export problems, and more. Continuously updated from real user reports.
|
||||
|
||||
### 5. Image Acquisition (Optional)
|
||||
|
||||
Two paths for non-user images, mixable per row in the same deck:
|
||||
|
||||
For API-backed features, put credentials in `.env`. Clone installs can use `cp .env.example .env`; skill marketplace installs should use a persistent user config:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.ppt-master
|
||||
cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env
|
||||
```
|
||||
|
||||
PPT Master reads the current process environment first, then the first `.env` found in this order: current working directory, skill directory (e.g. `~/.agents/skills/ppt-master/.env`), clone repo root, `~/.ppt-master/.env`.
|
||||
|
||||
**A) AI generation** — `image_gen.py`. Set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default.
|
||||
|
||||
**B) Web image search** — `image_search.py`. **Zero-config works**, but configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for higher-quality results. Without keys, search uses Openverse / Wikimedia Commons only; this is useful as a fallback, but image quality can be uneven because many results are ordinary user uploads. With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage. The default is quality-first: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line. For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search.
|
||||
|
||||
> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web).
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| | Document | Description |
|
||||
|---|----------|-------------|
|
||||
| 📘 | [Getting Started](./docs/getting-started.md) | First deck in 3 steps, plus how to use templates, live preview, animations, narration, voice cloning (**new users start here**) |
|
||||
| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools |
|
||||
| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users |
|
||||
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
|
||||
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
|
||||
| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
|
||||
| 💼 | [Examples](./examples/README.md) | All example projects |
|
||||
| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
|
||||
| ❓ | [FAQ](./docs/faq.md) | Model selection, cost, layout troubleshooting, custom templates |
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
[SVG Repo](https://www.svgrepo.com/) · [Tabler Icons](https://github.com/tabler/tabler-icons) · [Simple Icons](https://github.com/simple-icons/simple-icons) · [Phosphor Icons](https://github.com/phosphor-icons/core) · [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author)) (CRAP principles)
|
||||
|
||||
## Contact & Collaboration
|
||||
|
||||
Looking to collaborate, integrate PPT Master into your workflow, or just have questions?
|
||||
|
||||
- 💬 **Questions & sharing** — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
|
||||
- 🐛 **Bug reports & feature requests** — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
|
||||
- 🌐 **Learn more about the author** — [www.hehugo.com](https://www.hehugo.com/)
|
||||
|
||||
---
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://star-history.com/#hugohe3/ppt-master&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## Sponsors & Support
|
||||
|
||||
PPT Master is currently built and maintained primarily by me. Every new template, bug fix, and documentation update takes ongoing resources — currently shared by the sponsors and individual supporters below.
|
||||
|
||||
**Corporate sponsors**
|
||||
|
||||
<a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" height="40" /></a>
|
||||
|
||||
<a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" height="40" /></a>
|
||||
|
||||
<a href="https://m.do.co/c/547f129aabe1"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" alt="Powered by DigitalOcean" height="40" /></a>
|
||||
|
||||
**Individual support**
|
||||
|
||||
If PPT Master has been helpful to you, individual support of any amount helps keep the project moving and free.
|
||||
|
||||
<a href="https://paypal.me/hugohe3"><img src="https://img.shields.io/badge/PayPal-Sponsor-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="Sponsor via PayPal" /></a>
|
||||
|
||||
<img src="docs/assets/alipay-qr.jpg" alt="Alipay QR Code" width="220" />
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ by [Hugo He](https://www.hehugo.com/) — if this project helps you, please give it a ⭐ and consider [sponsoring](#sponsors--support).
|
||||
|
||||
<sub>Official distribution: <a href="https://github.com/hugohe3/ppt-master">GitHub</a> (primary) · <a href="https://atomgit.com/hugohe3/ppt-master">AtomGit</a> (mirror). Redistributions on other platforms are unofficial. MIT licensed — attribution required.</sub>
|
||||
|
||||
[⬆ Back to Top](#ppt-master--ai-generates-natively-editable-pptx-from-any-document)
|
||||
363
agent/skills-disabled/ppt-master/README_CN.md
Normal file
363
agent/skills-disabled/ppt-master/README_CN.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# PPT Master — AI 生成原生可编辑 PPTX，支持任意文档输入
|
||||
|
||||
[](https://github.com/hugohe3/ppt-master/releases)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/hugohe3/ppt-master/stargazers)
|
||||
[](https://atomgit.com/hugohe3/ppt-master)
|
||||
|
||||
[English](./README.md) | 中文
|
||||
|
||||
<p align="center">
|
||||
<sub>本项目由 <a href="https://www.packyapi.com/register?aff=ppt-master">PackyCode</a>、<a href="https://apikey.fun/register?aff=PPT-MASTER">APIKEY.FUN</a> 等赞助方支持，得以持续免费开源。</sub>
|
||||
</p>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="180"><a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" width="150"></a></td>
|
||||
<td>感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本项目的用户提供了特别优惠，使用<a href="https://www.packyapi.com/register?aff=ppt-master">此链接</a>注册并在充值时填写"ppt-master"优惠码，可以享受 9 折优惠。</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="180"><a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" width="150"></a></td>
|
||||
<td>感谢 APIKEY.FUN 赞助了本项目！APIKEY.FUN 是一家专业的企业级 AI 中转站，致力于为企业和开发者提供稳定、高效、低成本的 AI 中转服务。平台支持 Claude、OpenAI、Gemini 等主流热门模型，价格低至官方原价的 <strong>7%</strong>。通过<a href="https://apikey.fun/register?aff=PPT-MASTER">本项目专属链接</a>注册，还可享受最高 <strong>永久充值 95 折</strong> 专属优惠。</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ### 这是一个工具，不是一个许愿池
|
||||
> 别指望一把就给你一份完美的成品 PPT。它真正的价值是帮你把大部分枯燥的活儿干掉，剩下的打磨交给你——做原生可编辑的 PPT，本就是为了让你接着改，而不是甩给你一张改不动的图。模型越便宜，要补的人工就越多。成品好不好，最终取决于你操作这个项目和 PPT 的能力。
|
||||
|
||||
<p align="center">
|
||||
<a href="https://hugohe3.github.io/ppt-master/"><strong>在线预览</strong></a> ·
|
||||
<a href="https://www.hehugo.com/"><strong>关于何雨果</strong></a> ·
|
||||
<a href="./examples/"><strong>示例下载</strong></a> ·
|
||||
<a href="./docs/zh/faq.md"><strong>常见问题</strong></a> ·
|
||||
<a href="./docs/zh/roadmap.md"><strong>路线图</strong></a> ·
|
||||
<a href="mailto:heyug3@gmail.com"><strong>联系我</strong></a>
|
||||
</p>
|
||||
|
||||
<h3 align="center">下载这份<a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_attention_is_all_you_need/exports/attention_is_all_you_need_narrated.pptx">带音频旁白的 <em>Attention Is All You Need</em> 论文精读 deck</a>，在 PowerPoint 里直接放映，每一页都会自己"读"给你听 —— 这只是 PPT Master 能力的冰山一角。</h3>
|
||||
<h3 align="center">当然，你也可以下载下面六份示例 .pptx 中的任意一份，在 PowerPoint 里打开是最快感受这个项目能力边界的方式。</h3>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026"><img src="docs/assets/screenshots/preview_pritzker_2026.png" alt="杂志风 — 普利兹克奖 2026" /></a><br/>
|
||||
<sub><b>杂志风</b> — 建筑摄影 + 排版网格，冷静克制的编辑感<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_pritzker_2026">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_pritzker_2026/exports/pritzker_2026.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026"><img src="docs/assets/screenshots/preview_global_ai_capital.png" alt="新闻风 — 2026 全球 AI 资本格局" /></a><br/>
|
||||
<sub><b>新闻 / 财经数据风</b> — 深色仪表盘，图表驱动，彭博风<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_global_ai_capital_2026">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_global_ai_capital_2026/exports/global_ai_capital_2026.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems"><img src="docs/assets/screenshots/preview_swiss_grid.png" alt="瑞士风 — 网格系统入门" /></a><br/>
|
||||
<sub><b>瑞士风</b> — 严格栅格，克制字体，红色点缀<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_swiss_grid_systems">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_swiss_grid_systems/exports/swiss_grid_systems.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo"><img src="docs/assets/screenshots/preview_glassmorphism_demo.png" alt="毛玻璃风 — AI Agent 工程化 Demo" /></a><br/>
|
||||
<sub><b>毛玻璃 SaaS</b> — 半透明叠层，渐变景深，产品 UI 感<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_glassmorphism_demo">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_glassmorphism_demo/exports/glassmorphism_demo.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis"><img src="docs/assets/screenshots/preview_sugar_rush_memphis.png" alt="孟菲斯风 — Sugar Rush 音乐节" /></a><br/>
|
||||
<sub><b>孟菲斯波普</b> — 高饱和原色，几何图形，俏皮活力<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_sugar_rush_memphis">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_sugar_rush_memphis/exports/sugar_rush_memphis.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
<td align="center" width="33%">
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide"><img src="docs/assets/screenshots/preview_indie_bookstore_zine.png" alt="Zine 风 — 独立书店指南" /></a><br/>
|
||||
<sub><b>Risograph Zine</b> — 双色印刷质感，手作书店文化<br/>
|
||||
<a href="https://hugohe3.github.io/ppt-master/viewer.html?project=ppt169_indie_bookstore_zine_guide">在线翻页</a> · <a href="https://raw.githubusercontent.com/hugohe3/ppt-master/main/examples/ppt169_indie_bookstore_zine_guide/exports/indie_bookstore_zine_guide.pptx">下载 .pptx</a></sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p align="center">
|
||||
<sub>生成模型：Claude Opus 4.7 + <code>gpt-image-2</code>。<a href="https://hugohe3.github.io/ppt-master/">在线翻看全部示例 →</a> · <a href="./examples/"><code>examples/</code> 目录</a> · <a href="./docs/zh/why-ppt-master.md">为什么选 PPT Master？</a></sub>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
更多端到端实例：<a href="https://space.bilibili.com/111258938/lists/8144072"><strong>合集·PPT-Master 能力展示</strong></a>（B 站）
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
丢进你的原材料，拿回的是一份**真正的 PowerPoint**：可以直接修改，有 PPT 原生的转场与入场动画，演讲者备注能合成音频旁白，还能参考你自己的 PPT 模板——一份能直接拿去讲、回头还能改的真 PPT。每项能力怎么用 → [快速入门](./docs/zh/getting-started.md)。
|
||||
|
||||
> **⚠️ PPT Master 是 harness，不是完整的 agent。** `harness + model = agent`——工具负责工作流，模型决定上限。要组成真正高质量的 agent，推荐组合是：**Claude 大上下文窗口（~100 万 token）+ AI 生图（`gpt-image-2`）**。其他模型能跑流程，但达不到同等质量上限。效果不理想，请先换模型，不要质疑 harness。
|
||||
|
||||
> **运作方式** —— PPT Master 是一套在 AI IDE（Claude Code / Cursor / VS Code + Copilot / Codebuddy 等）里运行的工作流（一个 "skill"）。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT"，AI 按这套工作流在你本机生成一个真正可编辑的 `.pptx`。你不写任何代码——IDE 只是你和 AI 对话的地方。
|
||||
>
|
||||
> **你要做的**：装 Python、装一个 AI IDE、把资料放进来。
|
||||
|
||||
> **为什么是这种形态** —— 未来，使用 Python 和 AI agent 的能力会越来越重要。这个项目就是要展示：仅凭这两样，你能走多远。代价是零基础上手有一段学习曲线，但走完这段，你就接上了未来。做 PPT 只是个借口——我真正想推广的是 Python 和 agent。
|
||||
|
||||
PPT Master 不一样：
|
||||
|
||||
- **真正的 PPT** — 如果一个文件在 PowerPoint 里打不开、不能编辑，它就不应该被叫做 PPT。PPT Master 输出的每个元素都能直接点击修改
|
||||
- **成本透明可控** — 工具免费开源，唯一成本是你自己的 AI 模型用量。当前主流 AI 工具都已转向按量计费，你用多少付多少——PPT Master 不在此之外增加任何额外订阅费用
|
||||
- **数据不出本地** — 你的文件不应该为了做一份 PPT 就被上传到别人的服务器。除与 AI 模型的对话外，全流程在你的电脑上完成
|
||||
- **不锁定平台** — 你的工作流不应该被任何一家公司绑架。Claude Code、Cursor、VS Code Copilot 等均可驱动；Claude、GPT、Gemini、Kimi 等模型均可使用
|
||||
|
||||
市面上的 AI PPT 工具大致分四类，PPT Master 只做最后一类：
|
||||
|
||||
| 类型 | 产物形态 | 能在 PowerPoint 里逐元素改吗 |
|
||||
|---|---|:---:|
|
||||
| 模板填空 | 套模板的 PPTX | 部分可以，受模板限制 |
|
||||
| 图片式 | 一页一张大图拼成 PPTX | ❌ 整页是图片 |
|
||||
| HTML 演示 | 网页演示 | ❌ 不是 PPTX |
|
||||
| **原生可编辑（PPT Master）** | **真 DrawingML 形状、文本框、图表** | ✅ 每个元素都能点开改 |
|
||||
|
||||
---
|
||||
|
||||
## 会用的人，比工具更关键
|
||||
|
||||
上面这些示例都是我用它一次性做出来的，甚至都没有精修——如果再花时间精修，那就是另一番样子了。同一个 PowerPoint，设计师能做出令人惊叹的作品，多数人只用到几个基础功能——差别不在工具，在用工具的人。如果你暂时做不到，多半是还没摸熟用法，请先翻一翻 [快速入门](./docs/zh/getting-started.md) 和示例工程。
|
||||
|
||||
最好的效果确实需要 Claude。觉得贵之前，先想想同等水准的 PPT 请人做要花多少钱？项目本身也支持 GPT、Gemini、Kimi 等模型，只是效果有差异——想要顶配的产出、又只付最低的成本，本就不合常理。
|
||||
|
||||
---
|
||||
|
||||
## 关于作者
|
||||
|
||||
我是何雨果（Hugo He），投融资领域从业者（注册会计师 · 资产评估师 · 咨询工程师（投资）），工作中经常审阅和修改 PPT。我希望 AI 生成的幻灯片仍然能在 PowerPoint 里继续编辑，而不是被压成一张张图片——所以做了这个。
|
||||
|
||||
🌐 [个人网站](https://www.hehugo.com/) · 📧 [heyug3@gmail.com](mailto:heyug3@gmail.com) · 🐙 [@hugohe3](https://github.com/hugohe3)
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 前置条件
|
||||
|
||||
**只需装 Python 即可。** 其余依赖通过 `pip install -r requirements.txt` 一次装齐。
|
||||
|
||||
| 依赖 | 是否必须 | 用途 |
|
||||
|------|:--------:|------|
|
||||
| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——唯一真正需要安装的东西 |
|
||||
|
||||
> **一句话总结** — 装好 Python，跑一行 `pip install -r requirements.txt`，就可以开始生成 PPT 了。
|
||||
|
||||
<details open>
|
||||
<summary><strong>Windows</strong> — 请看专门的手把手安装指南 ⚠️</summary>
|
||||
|
||||
Windows 需要一些额外步骤（PATH 设置、执行策略等）。我们为 Windows 用户写了一份**手把手安装指南**：
|
||||
|
||||
**📖 [Windows 安装指南](./docs/zh/windows-installation.md)** — 从零到跑通第一份 PPT，10 分钟搞定。
|
||||
|
||||
简要流程：从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → `pip install -r requirements.txt` → 完成。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>macOS / Linux</strong> — 安装即用</summary>
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install python
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install python3 python3-pip
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>边缘场景备用方案</strong> — 99% 的用户用不到</summary>
|
||||
|
||||
**Pandoc** — 只在需要转小众格式时才装：`.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`、`.html`、`.epub`、`.ipynb` 已由 Python 原生处理，不需要 pandoc。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install pandoc
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install pandoc
|
||||
```
|
||||
</details>
|
||||
|
||||
### 2. 选择一个 Agent
|
||||
|
||||
PPT Master 在**任何具备 agent 能力**（可读写文件、执行命令、持续多轮对话）的工具里都能跑。
|
||||
|
||||
| 类型 | 代表工具 | 说明 |
|
||||
|---|---|---|
|
||||
| **IDE 内置 agent** | • VS Code 架构（含 [VS Code](https://code.visualstudio.com/) 本体及分支与衍生）：[Cursor](https://cursor.sh/)、Trae、Codebuddy IDE、[Windsurf](https://codeium.com/windsurf)、Void 等<br>• 其他架构：[Zed](https://zed.dev/) 等 | 编辑器原生集成 agent |
|
||||
| **IDE 插件 / 扩展** | [GitHub Copilot](https://github.com/features/copilot)、[Claude Code](https://claude.ai/code)（VS Code / JetBrains 扩展）、[Cline](https://cline.bot/)、[Continue](https://continue.dev/)、Roo Code、通义灵码、CodeGeeX 等 | 装在 VS Code / JetBrains 等宿主里使用 |
|
||||
| **CLI agent** | [Claude Code](https://claude.ai/code) CLI、[Codex CLI](https://github.com/openai/codex)、[Aider](https://aider.chat/)、Gemini CLI 等 | 终端里运行，适合脚本化 / 远程 / 服务器场景 |
|
||||
|
||||
> **模型推荐**：追求最佳效果选 **Claude Opus**，搭配 `gpt-image-2` 生图；**Gemini 3.5 Flash** 目前综合性价比很高，尤其速度很快，值得一试。
|
||||
|
||||
**🔑 想用 Claude / GPT / Gemini 但还没有渠道？** 本项目赞助商 **[PackyCode](https://www.packyapi.com/register?aff=ppt-master)** 与 **[APIKEY.FUN](https://apikey.fun/register?aff=PPT-MASTER)** 都能解决卡点——两家都支持按量调用 Claude、GPT、Gemini 等主流模型，无需订阅，支持国内支付。**PackyCode**：充值时填写优惠码 **`ppt-master`** 享 9 折。**APIKEY.FUN**：价格低至官方原价的 **7%**，通过专属链接注册可享受最高永久充值 95 折专属优惠。
|
||||
|
||||
### 3. 配置项目
|
||||
|
||||
**方式 A — 下载 ZIP**（无需安装 Git）：
|
||||
[GitHub](https://github.com/hugohe3/ppt-master) → **Code → Download ZIP** · [AtomGit](https://atomgit.com/hugohe3/ppt-master) → **克隆/下载 → 下载ZIP**（国内网速更快）
|
||||
|
||||
**方式 B — Git clone**（需先安装 [Git](https://git-scm.com/downloads)）：
|
||||
|
||||
```bash
|
||||
# GitHub
|
||||
git clone https://github.com/hugohe3/ppt-master.git
|
||||
# AtomGit（国内网速更快）
|
||||
git clone https://atomgit.com/hugohe3/ppt-master.git
|
||||
cd ppt-master
|
||||
```
|
||||
|
||||
然后安装依赖：
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
日常更新（方式 A / B）：`python3 skills/ppt-master/scripts/update_repo.py`
|
||||
|
||||
> **方式 C — Skill marketplace**：仓库已添加 `.claude-plugin/marketplace.json` 元数据，可通过 [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 生态一行安装：
|
||||
>
|
||||
> ```bash
|
||||
> # 跨 agent CLI（Claude Code、Cursor、Codex 等）
|
||||
> npx skills add hugohe3/ppt-master
|
||||
>
|
||||
> # 或在 Claude Code 内
|
||||
> /plugin marketplace add hugohe3/ppt-master
|
||||
> /plugin install ppt-master@ppt-master
|
||||
> ```
|
||||
>
|
||||
> 上述两种安装方式都只会拉取 skill 文件本身（不含完整仓库），后处理脚本仍需在安装目录跑 `pip install -r requirements.txt`。
|
||||
|
||||
### 4. 开始创作
|
||||
|
||||
**提供原始材料（推荐）：** 将 PDF、DOCX、图片等文件放入 `projects/` 目录下，在 AI 聊天面板中告诉它使用哪些文件。获取路径的最快方式：在文件管理器或 IDE 侧边栏中右键文件 → **复制路径**（Copy Path / Copy Relative Path），直接粘贴进聊天框。
|
||||
|
||||
```
|
||||
你：请用 projects/q3-report/sources/report.pdf 这份文件生成一份 PPT
|
||||
```
|
||||
|
||||
**直接输入内容：** 也可以把文字内容直接粘贴进聊天窗口，AI 会根据这些内容生成 PPT。
|
||||
|
||||
```
|
||||
你：请根据以下内容制作成 PPT：[粘贴你的文字内容...]
|
||||
```
|
||||
|
||||
两种方式下 AI 都会先确认设计规范：
|
||||
|
||||
```
|
||||
AI：好的，先确认设计规范：
|
||||
[模板] B) 自由设计
|
||||
[格式] PPT 16:9
|
||||
[页数] 8-10 页
|
||||
...
|
||||
```
|
||||
|
||||
AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。
|
||||
|
||||
> **输出说明：** 原生形状版 `.pptx`（可直接编辑）保存至 `exports/<name>_<timestamp>.pptx`；`svg_output/` 始终镜像到 `backup/<timestamp>/svg_output/`，便于归档或后续重跑。加 `--svg-snapshot` 时，额外在 `exports/` 内并排生成 SVG 快照版 pptx（详见[常见问题](./docs/zh/faq.md)）。需要 Office 2016+。
|
||||
|
||||
> **已有一份想复用的 `.pptx`？** 把那份 deck 连同素材给 AI，说「套模板」即可——它会把新内容（文字、表格、图表数据）填进你现有的设计，只导出你挑选的页面，且保持原生可编辑。详见 [常见问题](./docs/zh/faq.md) 与 [套模板工作流](./skills/ppt-master/workflows/template-fill-pptx.md)。
|
||||
|
||||
> **AI 迷失上下文？** 让它先读 `skills/ppt-master/SKILL.md`。
|
||||
|
||||
> **遇到问题？** 查看 **[常见问题](./docs/zh/faq.md)** — 涵盖模型选择、排版问题、导出异常等，基于真实用户反馈持续更新。
|
||||
|
||||
### 5. 图片获取（可选）
|
||||
|
||||
非用户自带图片有两条路径，可在同一份 deck 里按行混用：
|
||||
|
||||
需要 API 的功能统一通过 `.env` 配置。clone 安装可以用 `cp .env.example .env`；skill marketplace 安装建议使用持久的用户级配置：
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.ppt-master
|
||||
cp /path/to/installed/ppt-master/.env.example ~/.ppt-master/.env
|
||||
```
|
||||
|
||||
PPT Master 会优先读取当前进程环境变量，然后按顺序读取第一个存在的 `.env`：当前工作目录、clone 仓库根目录、`~/.ppt-master/.env`。
|
||||
|
||||
**A) AI 生图** — `image_gen.py`。设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`（`OPENAI_API_KEY`、`GEMINI_API_KEY` 等），流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。
|
||||
|
||||
**B) 网络图片搜索** — `image_search.py`。**零配置**可用，但高质量使用建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`（都免费申请）。不配置时只使用 Openverse / Wikimedia Commons，适合作为兜底，但容易出现普通用户上传、构图随意、清晰度不稳定的图片；配置后默认搜索链会追加 Pexels / Pixabay，现代商业摄影、人物、办公、生活方式和插画类图片质量会明显更稳定。默认以图片质量和匹配度优先，直接把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选；如果选中的图片需要署名，Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时，才使用 `--strict-no-attribution` 限制为免署名图片。对视觉要求高的封面、产品图、人物图和品牌场景，优先级建议是：用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索。
|
||||
|
||||
> 完整说明：[`image-generator.md`](./skills/ppt-master/references/image-generator.md)（AI）·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)（网络）。
|
||||
|
||||
---
|
||||
|
||||
## 文档导航
|
||||
|
||||
| | 文档 | 说明 |
|
||||
|---|------|------|
|
||||
| 📘 | [快速入门](./docs/zh/getting-started.md) | 三步做出第一份 deck，外加模板、实时预览、动画、旁白、声音复刻的用法（**新用户从这里开始**） |
|
||||
| 🆚 | [为什么选 PPT Master](./docs/zh/why-ppt-master.md) | 与 Gamma、Copilot 等工具的对比 |
|
||||
| 🪟 | [Windows 安装指南](./docs/zh/windows-installation.md) | Windows 用户手把手安装教程 |
|
||||
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 |
|
||||
| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |
|
||||
| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 |
|
||||
| 💼 | [示例](./examples/README.md) | 所有示例项目 |
|
||||
| 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |
|
||||
| ❓ | [常见问题](./docs/zh/faq.md) | 模型选择、费用、排版问题排查、自定义模板 |
|
||||
|
||||
---
|
||||
|
||||
## 贡献
|
||||
|
||||
详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
||||
|
||||
## 开源协议
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
## 致谢
|
||||
|
||||
[SVG Repo](https://www.svgrepo.com/) · [Tabler Icons](https://github.com/tabler/tabler-icons) · [Simple Icons](https://github.com/simple-icons/simple-icons) · [Phosphor Icons](https://github.com/phosphor-icons/core) · [Robin Williams](https://en.wikipedia.org/wiki/Robin_Williams_(author))（CRAP 设计原则）
|
||||
|
||||
## 联系与合作
|
||||
|
||||
欢迎合作交流、将 PPT Master 集成到你的工作流，或者单纯提问：
|
||||
|
||||
- 💬 **提问与分享** — [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
|
||||
- 🐛 **Bug 反馈与功能建议** — [GitHub Issues](https://github.com/hugohe3/ppt-master/issues)
|
||||
- 🌐 **了解更多** — [www.hehugo.com](https://www.hehugo.com/)
|
||||
|
||||
---
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://star-history.com/#hugohe3/ppt-master&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=hugohe3/ppt-master&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## 赞助与支持
|
||||
|
||||
PPT Master 目前主要由我开发维护。每个新模板、Bug 修复、文档更新都需要持续的资源投入，目前由以下赞助方和个人支持者共同分担。
|
||||
|
||||
**企业赞助方**
|
||||
|
||||
<a href="https://www.packyapi.com/register?aff=ppt-master"><img src="docs/assets/sponsors/packycode.png" alt="PackyCode" height="40" /></a>
|
||||
|
||||
<a href="https://apikey.fun/register?aff=PPT-MASTER"><img src="docs/assets/sponsors/apikey-fun.png" alt="APIKEY.FUN" height="40" /></a>
|
||||
|
||||
<a href="https://m.do.co/c/547f129aabe1"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" alt="Powered by DigitalOcean" height="40" /></a>
|
||||
|
||||
**个人赞助**
|
||||
|
||||
如果 PPT Master 帮到了你，任何金额的个人赞助都能帮助项目持续更新、保持免费开源。
|
||||
|
||||
<a href="https://paypal.me/hugohe3"><img src="https://img.shields.io/badge/PayPal-赞助-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="通过 PayPal 赞助" /></a>
|
||||
|
||||
<img src="docs/assets/alipay-qr.jpg" alt="支付宝收款码" width="220" />
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ by [何雨果 Hugo He](https://www.hehugo.com/) — 如果这个项目对你有帮助，请给一个 ⭐，也欢迎[赞助支持](#赞助与支持)。
|
||||
|
||||
<sub>官方发布渠道：<a href="https://github.com/hugohe3/ppt-master">GitHub</a>（主仓库）· <a href="https://atomgit.com/hugohe3/ppt-master">AtomGit</a>（镜像）。其他平台转发版本均为非官方版本。MIT 协议，使用需保留署名。</sub>
|
||||
|
||||
[⬆ 回到顶部](#ppt-master--ai-生成原生可编辑-pptx支持任意文档输入)
|
||||
45
agent/skills-disabled/ppt-master/SECURITY.md
Normal file
45
agent/skills-disabled/ppt-master/SECURITY.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We provide security updates for the latest version of PPT Master.
|
||||
|
||||
| Version | Supported |
|
||||
|---------|-----------|
|
||||
| Latest | Yes |
|
||||
| Older | No |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
**Please do not report security vulnerabilities through public GitHub Issues.**
|
||||
|
||||
If you discover a security issue, please report it privately by emailing:
|
||||
|
||||
**heyug3@gmail.com**
|
||||
|
||||
Include in your report:
|
||||
|
||||
- A description of the vulnerability
|
||||
- Steps to reproduce the issue
|
||||
- The potential impact
|
||||
- Any suggested fix, if you have one
|
||||
|
||||
We will acknowledge your report within **72 hours** and aim to provide a resolution timeline within **7 days**.
|
||||
|
||||
## Scope
|
||||
|
||||
This policy covers the PPT Master source code in this repository, including:
|
||||
|
||||
- Python scripts in `skills/ppt-master/scripts/`
|
||||
- Post-processing pipeline (`total_md_split.py`, `finalize_svg.py`, `svg_to_pptx.py`)
|
||||
- Project management utilities
|
||||
|
||||
Out of scope:
|
||||
|
||||
- Third-party AI editors or APIs (Claude, Cursor, GitHub Copilot, etc.)
|
||||
- Generated PPTX output files
|
||||
- User-provided source documents
|
||||
|
||||
## Disclosure Policy
|
||||
|
||||
We follow responsible disclosure. Once a fix is available, we will publish a GitHub Security Advisory crediting the reporter (unless they prefer to remain anonymous).
|
||||
BIN
agent/skills-disabled/ppt-master/docs/assets/alipay-qr.jpg
Normal file
BIN
agent/skills-disabled/ppt-master/docs/assets/alipay-qr.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 136 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 479 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 696 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.5 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.0 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 861 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 737 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 729 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.6 KiB |
175
agent/skills-disabled/ppt-master/docs/audio-narration.md
Normal file
175
agent/skills-disabled/ppt-master/docs/audio-narration.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Audio Narration & Video Export
|
||||
|
||||
PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices) by default, or via ElevenLabs, MiniMax, Qwen TTS, and CosyVoice when you need higher-quality cloud narration or a cloned voice. It can then embed the audio back into the PPTX and let PowerPoint export the deck as an MP4 video — with synced narration and slide transitions, no extra tools.
|
||||
|
||||
## What you get
|
||||
|
||||
- One audio file per slide under `<project_path>/audio/`, named to match the SVG (`01_cover.mp3`, `02_market_landscape.mp3`, …).
|
||||
- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.
|
||||
- The original speaker notes are preserved.
|
||||
|
||||
## How it works
|
||||
|
||||
1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.
|
||||
2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "稳重男声，适合财报"). It also recommends a speaking rate or provider defaults based on notes density.
|
||||
3. **One question, one answer.** You are asked once — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.
|
||||
4. **Generation runs.** The script writes page-level audio to `audio/`, then (if you kept embedding) re-exports the deck with audio attached. Long-audio import and automatic long-audio splitting are not supported.
|
||||
|
||||
The full step-by-step is in [`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md).
|
||||
|
||||
## Two embedding paths
|
||||
|
||||
| Command | Purpose |
|
||||
|---|---|
|
||||
| `--recorded-narration audio` | Prepare PowerPoint's recorded timings and narrations. Requires complete per-slide audio and writes page auto-advance timings. Use this for narrated/video export. |
|
||||
| `--narration-audio-dir audio` | Lower-level audio embedding. Embeds matched files and allows partial coverage. Use this for testing or manual PowerPoint finishing. |
|
||||
|
||||
## Triggering it
|
||||
|
||||
Just say so in chat after the deck has been exported:
|
||||
|
||||
```
|
||||
You: 给这个 PPT 生成音频
|
||||
You: Generate narration for this deck and re-export with audio embedded.
|
||||
You: Add Japanese voice narration; pick a calm female voice.
|
||||
```
|
||||
|
||||
The AI handles the rest.
|
||||
|
||||
## Languages
|
||||
|
||||
Anything `edge-tts` supports — roughly 90 locales including all major Chinese variants (`zh-CN` / `zh-TW` / `zh-HK` Cantonese), English (US/UK/AU/IN), Japanese, Korean, French, German, Spanish, Portuguese, Russian, Arabic, etc. List voices for any locale yourself with:
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
|
||||
```
|
||||
|
||||
## Manual usage (advanced)
|
||||
|
||||
If you want to skip the AI flow and call the script directly:
|
||||
|
||||
```bash
|
||||
# 1. Make sure speaker notes are split (post-processing Step 7.1):
|
||||
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
|
||||
|
||||
# 2A. Generate MP3s with edge-tts (default, no API key)
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--voice zh-CN-YunjianNeural --rate +0%
|
||||
|
||||
# 2B. Or generate MP3s with ElevenLabs (requires ELEVENLABS_API_KEY)
|
||||
export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider elevenlabs \
|
||||
--voice-id <elevenlabs-voice-id> \
|
||||
--elevenlabs-model eleven_multilingual_v2
|
||||
|
||||
# 2C. Or generate MP3s with MiniMax (supports system and cloned voice_id)
|
||||
export MINIMAX_API_KEY="your-minimax-api-key"
|
||||
# Defaults to the China endpoint. For overseas access, set 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
|
||||
|
||||
# 2D. Or generate audio with Qwen TTS (system voice or cloned voice)
|
||||
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
|
||||
|
||||
# 2E. Or generate MP3s with CosyVoice (system voice or cloned/designed voice_id)
|
||||
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. (Optional) Re-export PPTX with audio embedded
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
|
||||
--recorded-narration audio
|
||||
```
|
||||
|
||||
For edge, `--voice` is required. Use `--list-voices --locale <locale>` to see what's available.
|
||||
|
||||
For ElevenLabs, `--voice-id` is required. List voices from your ElevenLabs account with:
|
||||
|
||||
```bash
|
||||
export ELEVENLABS_API_KEY="your-elevenlabs-api-key"
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py --provider elevenlabs --list-voices
|
||||
```
|
||||
|
||||
For MiniMax, Qwen, and CosyVoice, pass the provider-specific system voice or cloned voice ID/name with `--voice-id`. Voice cloning itself is performed in the provider's console/API first; `notes_to_audio.py` uses the resulting voice ID to generate per-slide narration.
|
||||
|
||||
## Use a cloned voice
|
||||
|
||||
Four cloud providers — **ElevenLabs**, **MiniMax**, **Qwen**, **CosyVoice** — let you clone a voice from a short sample and then synthesize new speech in that voice. PPT Master narrates the entire deck in your cloned voice as long as you can hand it a `voice_id`. (`edge` does not support cloning.)
|
||||
|
||||
**The split of responsibilities**: voice cloning itself happens in the provider's console or API — you upload a sample (typically 10 s – a few minutes of clean audio) and the provider returns a `voice_id`. PPT Master is on the *consumption* side: it takes that `voice_id` and reads every slide's notes in that voice. PPT Master never uploads your sample anywhere.
|
||||
|
||||
| Provider | Where to clone | Sample length |
|
||||
|---|---|---|
|
||||
| ElevenLabs | [elevenlabs.io](https://elevenlabs.io) → Voices → Add Voice → Instant / Professional Voice Cloning | 1 min (Instant) / 30 min+ (Professional) |
|
||||
| MiniMax | [platform.minimaxi.com](https://platform.minimaxi.com) → 语音克隆 (Voice Clone) | ~10 s – 5 min |
|
||||
| Qwen TTS | [DashScope console](https://dashscope.console.aliyun.com) → 语音合成 → 声音复刻 | ~10 s – 5 min |
|
||||
| CosyVoice | [DashScope console](https://dashscope.console.aliyun.com) → 语音合成 → 音色复刻 | ~10 s – 5 min |
|
||||
|
||||
**How to use it after cloning** — in chat, just say so. The AI will skip the voice-recommendation step and use your `voice_id` directly:
|
||||
|
||||
```
|
||||
You: 用 MiniMax 我克隆的音色生成旁白，voice_id 是 xxxxxxx
|
||||
You: Generate the narration with my cloned ElevenLabs voice id abc123
|
||||
```
|
||||
|
||||
Or call the script directly:
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
|
||||
--provider minimax --voice-id <your-cloned-voice-id> \
|
||||
--minimax-model speech-2.8-hd
|
||||
```
|
||||
|
||||
Replace `--provider minimax` with `elevenlabs` / `qwen` / `cosyvoice` as needed; `--voice-id` accepts the cloned voice the same way it accepts a system voice.
|
||||
|
||||
**Notes**:
|
||||
|
||||
- **Authorization** — only clone voices you own or have explicit permission to use. Each provider's terms forbid impersonation.
|
||||
- **Language coverage** — the cloned voice inherits the speaker's accent. For multilingual decks (e.g. Chinese with English terms), pick a provider whose model handles your sample's language mix; ElevenLabs `eleven_multilingual_v2` and CosyVoice tend to be the most forgiving.
|
||||
- **One-time setup, reusable forever** — the `voice_id` doesn't expire. Clone once, narrate any number of decks.
|
||||
|
||||
## Dependency
|
||||
|
||||
```bash
|
||||
python3 -m pip install edge-tts
|
||||
```
|
||||
|
||||
Already listed in `skills/ppt-master/requirements.txt`. `edge-tts` calls Microsoft's online TTS service — an internet connection is required at generation time. The MP3s themselves are local files; nothing about playback or PowerPoint export depends on the network afterwards.
|
||||
|
||||
Cloud TTS providers do not require extra Python packages; they use HTTPS directly. Configure the relevant API key in the current shell or in `.env` based on `.env.example`.
|
||||
|
||||
## Tips
|
||||
|
||||
- **Pacing**: PPT Master's default speaker-notes are 2–5 sentences per slide; `+0%` rate sounds natural. If a deck is very dense (long technical paragraphs), try `-5%`.
|
||||
- **Mid-deck regeneration**: change a single slide's `notes/<page>.md`, re-run `notes_to_audio.py` (it overwrites all MP3s, so re-run for the whole deck — the cost is small).
|
||||
- **Mixed-language decks** (Chinese with English technical terms etc.): `edge-tts` neural voices handle the embedded foreign words reasonably well in most locales — pick the dominant language voice and try one slide first.
|
||||
|
||||
## Export as video
|
||||
|
||||
Once the narrated PPTX is in `exports/`, PowerPoint exports it as a video natively — no third-party tool needed. The embedded audio plays as each slide's narration, and the per-slide auto-advance timings (set from audio length when you let the AI re-export with `--recorded-narration audio`) drive the video's pacing. `--recorded-narration` rejects `on-click` object animation because it does not generate object-level click timings.
|
||||
|
||||
**PowerPoint (Windows / Mac, Office 2016+)**:
|
||||
|
||||
1. Open the narrated `.pptx` from `exports/`.
|
||||
2. **File → Export → Create a Video**.
|
||||
3. Pick a quality (4K / Full HD / HD / Standard) and "Use Recorded Timings and Narrations" — PPT Master has already set both for you.
|
||||
4. **Create Video** → save as `.mp4` (or `.wmv` on Windows).
|
||||
|
||||
**Keynote (Mac)**: open the deck → **File → Export To → Movie…** — Keynote also honors embedded audio and per-slide timings, output `.m4v` / `.mov`.
|
||||
|
||||
**Tips**:
|
||||
|
||||
- **No mic, no recording session needed** — the audio is generated, not recorded, so re-runs are deterministic.
|
||||
- **Animations are preserved** — page transitions and click-free per-element entrance animations from PPT Master are real OOXML and play correctly in the exported video. See [Animations & Transitions](../skills/ppt-master/references/animations.md).
|
||||
- **Want to tweak just one slide's audio?** Edit `notes/<page>.md`, re-run `notes_to_audio.py` and the embedding step, then re-export the video — total turnaround is usually under a minute per slide.
|
||||
- **File size**: a 20-page deck at Full HD typically lands at 30–80 MB depending on imagery. Drop to HD if you need a smaller file for sharing.
|
||||
191
agent/skills-disabled/ppt-master/docs/faq.md
Normal file
191
agent/skills-disabled/ppt-master/docs/faq.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# FAQ
|
||||
|
||||
[English](./faq.md) | [中文](./zh/faq.md)
|
||||
|
||||
---
|
||||
|
||||
## Q: What source formats does PPT Master accept?
|
||||
|
||||
Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **RST**, **URLs** (including WeChat articles), **Markdown**, or just plain text pasted into the conversation. The AI agent converts your source material to Markdown automatically before generating slides.
|
||||
|
||||
## Q: Can I generate a deck with just a topic, no source materials?
|
||||
|
||||
Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The AI will trigger the **topic-research workflow** — gathering authoritative sources via web search (Wikipedia / official sites / institutional releases), assembling them into a Markdown research document + image folder, then feeding both into the main pipeline.
|
||||
|
||||
Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone.
|
||||
|
||||
## Q: Can PPT Master produce formats other than PowerPoint?
|
||||
|
||||
Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master supports social media and marketing formats out of the box:
|
||||
|
||||
| Format | Use Case |
|
||||
|--------|----------|
|
||||
| Xiaohongshu (RED) 3:4 | Image-text sharing, knowledge posts |
|
||||
| WeChat Moments / IG 1:1 | Square posters, brand showcases |
|
||||
| Story / TikTok 9:16 | Vertical stories, short video covers |
|
||||
| WeChat Article Header | WeChat article cover images |
|
||||
| A4 Print | Print posters, flyers |
|
||||
|
||||
Just specify the format when starting a project (e.g., `--format xhs`). The output is still a `.pptx` file containing native shapes.
|
||||
|
||||
## Q: What AI tools work with PPT Master?
|
||||
|
||||
PPT Master works with any AI coding agent that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. See the cost comparison below for pricing differences.
|
||||
|
||||
## Q: Can I use AI-generated images in my presentation?
|
||||
|
||||
Yes. PPT Master includes a built-in image generation script that supports multiple providers (Gemini, OpenAI, FLUX, Qwen, Zhipu, etc.). During the Strategist phase, if you choose "AI generation" for the image approach, the pipeline will automatically generate images based on your content. You can also provide your own images — just place them in the project's `images/` folder.
|
||||
|
||||
## Q: I don't have an image-generation API key — can I still get images?
|
||||
|
||||
Yes — pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons (no API key needed). Zero-config search is a fallback: it works immediately, but quality can be uneven because many results are ordinary user uploads.
|
||||
|
||||
For better contemporary stock photography, set `PEXELS_API_KEY` and/or `PIXABAY_API_KEY` in `.env` (both are free). The search will include Pexels / Pixabay automatically, which usually improves people, workplace, lifestyle, product, and illustration images. You can mix paths in one deck (e.g. AI for hero illustrations, web for team photos). If a selected image requires attribution, Executor adds a small inline credit on the affected slide.
|
||||
|
||||
## Q: Can I edit the generated presentations?
|
||||
|
||||
Yes. The main `.pptx` (native PowerPoint shapes — all text, graphics, and colors directly editable without any conversion) is saved to `exports/` with a timestamp. A copy of `svg_output/` (the Executor's raw SVG source) is always written to `backup/<timestamp>/svg_output/` so you can rebuild via `finalize_svg → svg_to_pptx` without re-running the LLM. Pass `--svg-snapshot` to additionally emit an SVG-image preview pptx alongside the native pptx in `exports/` — handy for cross-platform distribution as a single file; off by default because live preview already serves as the SVG visual reference for day-to-day work. Requires **Office 2016** or later.
|
||||
|
||||
## Q: Why is one paragraph split into multiple text boxes? Can I get one text box per paragraph instead?
|
||||
|
||||
By default, mergeable body-text paragraphs export as one editable PowerPoint text frame with multiple paragraphs. Resizing the box reflows text inside it.
|
||||
|
||||
If you need strict line-layout fidelity, re-export with `--no-merge`:
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge
|
||||
```
|
||||
|
||||
With `--no-merge`, every visual line becomes its own PowerPoint text frame. This preserves the SVG's exact line layout pixel-for-pixel, which matters for covers, charts, tables, and any page with tight typographic alignment.
|
||||
|
||||
**Trade-off**: default paragraph merging lets PowerPoint wrap merged paragraphs to a different line count than the SVG source. Best for long-form body text (abstracts, multi-paragraph sections, reference lists); use `--no-merge` for layout-tight pages. The detection is conservative — mixed-layout `<text>` falls through to the per-line path automatically.
|
||||
|
||||
When you're chatting with the AI, you can also just ask for strict line fidelity on layout-sensitive pages — the AI will add `--no-merge` when re-exporting.
|
||||
|
||||
## Q: What's the difference between the three Executors?
|
||||
|
||||
- **Executor_General**: General scenarios, flexible layout
|
||||
- **Executor_Consultant**: General consulting, data visualization
|
||||
- **Executor_Consultant_Top**: Top consulting (MBB level), 5 core techniques
|
||||
|
||||
## Q: Is PPT Master expensive to use?
|
||||
|
||||
PPT Master itself is free and open source. The only cost is your own AI model usage.
|
||||
|
||||
AI tools across the industry are shifting to usage-based billing — you pay for what you actually consume. PPT Master works with this model naturally: there's no separate PPT subscription, no proprietary credits, no per-seat fee for a presentation platform on top of what you're already paying for AI.
|
||||
|
||||
For comparison, Gamma subscriptions run $8–20/month, Beautiful.ai $12–45/month — regardless of how much you actually use them. PPT Master adds zero cost on top of your existing AI spend.
|
||||
|
||||
## Q: Are the charts in the generated PPTX editable?
|
||||
|
||||
Charts are rendered as **custom-designed SVG graphics** converted to native PowerPoint shapes — fully editable as shapes (move, recolor, retype, restyle). This is a deliberate choice over Excel-driven chart objects: PowerPoint's default charts look generic and dated, and lock decks into rigid templates. SVG charts give you publication-quality visuals you can fine-tune directly in PowerPoint.
|
||||
|
||||
If your workflow specifically requires Excel-driven data editing, manually create a similar chart yourself in PowerPoint after export.
|
||||
|
||||
## Q: Can I change page transitions and element animations?
|
||||
|
||||
Yes. Page transitions (`fade` 0.4s by default) and per-element entrance animations (`auto` effect with `after-previous` cascade by default — effect mapped from each group's SVG id, with image-like ids cycling a visual pool for variation) are both controlled by `svg_to_pptx.py` flags — `-t/--transition` for page-level and `-a/--animation` for element-level. Common one-liners:
|
||||
|
||||
```bash
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a none # disable per-element animation
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fade # use a single effect instead of mixed
|
||||
python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger on-click # presenter-paced reveals
|
||||
```
|
||||
|
||||
`on-click` is for live presentations. Narrated/video export via `--recorded-narration` rejects it because PPT Master writes page timings, not object-level click timings; use `after-previous` or `with-previous` for narrated decks.
|
||||
|
||||
Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](../skills/ppt-master/references/animations.md).
|
||||
|
||||
## Q: Which AI model works best?
|
||||
|
||||
**Claude** (Opus / Sonnet) is the recommended and most tested model. SVG layout requires precise absolute-coordinate calculations (font size x character count x container width), and Claude handles this significantly better than alternatives.
|
||||
|
||||
**GPT series** older versions tended to produce more layout issues — text overflowing containers, misaligned elements, coordinate miscalculations. Newer versions (e.g. GPT-5.5) have improved noticeably and are usable in practice; if issues appear, tell the AI which page to fix.
|
||||
|
||||
Other models (Gemini, GLM, MiniMax, etc.) vary in quality. In general, models with stronger frontend/visual capabilities produce better results.
|
||||
|
||||
## Q: Someone said PPT Master is "just a toy" — is that fair?
|
||||
|
||||
No. PPT Master is a **harness**, not a complete agent — `harness + model = agent`, and the output ceiling is set entirely by the model, not the harness. Evaluating PPT Master with a weak or small-context model is like test-driving a sports car in first gear and concluding it's slow.
|
||||
|
||||
**The full-power combination:**
|
||||
|
||||
- **Claude with a large context window** (ideally ~1M tokens): a large context window lets the Executor see every previously generated page in the same session, maintaining visual consistency across the entire deck without splitting runs. Smaller windows force split-mode execution, which introduces visible style drift between phases.
|
||||
- **AI image generation with `gpt-image-2`** (or similar): placeholder-grade stock images are the single biggest reason decks look generic. Replacing them with on-brand AI-generated illustrations changes the perceived quality immediately.
|
||||
|
||||
If the results you've seen look mediocre, check your setup before concluding anything about the tool: What model? What context size? Was image generation enabled? PPT Master + Claude Opus at 1M context + `gpt-image-2` images is a genuinely different experience from PPT Master + a small open-source model with no image API configured.
|
||||
|
||||
> **No Claude access?** Project sponsor [PackyCode](https://www.packyapi.com/register?aff=ppt-master) provides pay-as-you-go access to Claude and other models — no subscription, no overseas card required. Use promo code **`ppt-master`** for 10% off.
|
||||
|
||||
One last thing: this is a free, solo-maintained open-source project. If it fits your needs, use it — I'm glad it helps; if it doesn't, pick another tool. Sincere feedback and suggestions are always welcome, because that's how the project gets a little better over time.
|
||||
|
||||
## Q: Text overflows or elements are misaligned — what can I do?
|
||||
|
||||
This is almost always a model capability issue, not a bug in PPT Master. SVG layout is essentially manual absolute positioning — the model must calculate coordinates, font metrics, and container sizes correctly.
|
||||
|
||||
**Fixes to try**:
|
||||
1. Switch to **Claude** (Opus or Sonnet) if you're using another model
|
||||
2. Tell the AI which specific page has the problem and describe the issue — it can regenerate individual pages
|
||||
3. Open the SVG source file directly and ask the AI to fix coordinates
|
||||
4. Remember: the generated PPTX is a **high-quality starting point**, not a final deliverable — minor adjustments in PowerPoint are expected
|
||||
|
||||
## Q: How long does a presentation take to generate?
|
||||
|
||||
A typical 10–15 page presentation takes about **10–20 minutes** with a fast model. Generation is **intentionally serial** (one page at a time) to maintain visual consistency across slides — parallel generation was tested and produced inconsistent styles.
|
||||
|
||||
If generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts.
|
||||
|
||||
## Q: Will long decks blow out the context window in one shot?
|
||||
|
||||
Default recommendation: **continuous one-shot generation**. 10–15 page decks fit comfortably in a 200K window, and cross-page visual consistency is best when the Executor can see prior pages in the same session (it actively aligns style, font sizes, and rhythm).
|
||||
|
||||
Only when signals are heavy (≥ 18 pages, thick source material, or `topic-research` ran with substantial web-fetch accumulation) does the AI surface an optional **two-stage (split mode)** hint at the Strategist phase: Phase A (eight confirmations + image acquisition) ends in the current chat; you open a fresh chat window and type `继续生成 projects/<project_name>` (or "resume execution projects/<project_name>") to enter Phase B (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there.
|
||||
|
||||
Split mode is a **compromise** — it pays ~6K tokens (re-reading SKILL.md) to drop 60–200K of Phase A noise, then reuses the freed budget in Phase B to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode.
|
||||
|
||||
## Q: Can I preview or fix individual pages before the full export?
|
||||
|
||||
Yes. You can **interrupt the workflow at any time** — after the first few pages are generated, review them and give feedback. The AI can regenerate specific pages based on your comments. You don't need to wait until the end to make corrections.
|
||||
|
||||
For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — the title overlaps the chart" and it will fix that specific SVG.
|
||||
|
||||
## Q: I already have a finished `.pptx` — can I reuse its design and just fill in new content?
|
||||
|
||||
Yes — this is the **template fill** route, separate from the SVG generation pipeline. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It treats your deck as a native slide library, lets you pick only the pages that fit the new story (reorder freely, and reuse one page for several output slides), and writes the new text — plus native table cells and chart data — straight into the original OOXML.
|
||||
|
||||
The output stays 100% native-editable PowerPoint: the original design, layouts, images, and animations are preserved, and only the selected pages are exported. It deliberately does **not** change layouts, add pages, or swap images — a deck's page structure encodes its logic (lead-then-detail, comparison, progression), so pick pages whose structure already fits your content rather than forcing it in. For a fresh structure or a different page count, use create-template (next question) instead. Full steps: [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md).
|
||||
|
||||
---
|
||||
|
||||
## Q: How do I create a custom template?
|
||||
|
||||
Want to turn a PPT you love into a reusable template for PPT Master? Here's how:
|
||||
|
||||
**Step 1 — Prepare Reference Material**
|
||||
|
||||
The simplest path is still to prepare screenshots of the key page types from your reference PPT — cover page, table of contents, chapter divider, content page, and closing page. Save them as images in a single folder with clear, descriptive filenames (e.g., `cover.png`, `toc.png`, `chapter.png`, `content.png`, `closing.png`).
|
||||
|
||||
If you already have the original `.pptx` template file, you can also provide it as a reference source. PPT Master can extract reusable background images, logos, theme colors, and font metadata from the PPTX first, then use those assets during template reconstruction.
|
||||
|
||||
**Step 2 — Let AI Create the Template**
|
||||
|
||||
Use an AI coding agent (Claude Code, Codex, etc.) and ask it to use the **PPT Master `/create-template` workflow** to convert your reference material into a template. The more context you give, the better the result — for example:
|
||||
|
||||
- Template name and intended use case (e.g., government reports, premium consulting)
|
||||
- Desired tone and color palette (e.g., "modern and restrained, dark blue primary")
|
||||
- Category preference (`brand` / `general` / `scenario` / `government` / `special`)
|
||||
- Canvas format, if not the default 16:9
|
||||
|
||||
You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (template ID, theme mode, etc.).
|
||||
|
||||
**Step 3 — Wait for the Result**
|
||||
|
||||
The AI agent will handle the rest — analyzing your screenshots, building the layout definitions, and registering the template so it appears as a selectable option in the PPT Master workflow.
|
||||
|
||||
> **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations.
|
||||
|
||||
---
|
||||
|
||||
> For more questions, see [SKILL.md](../skills/ppt-master/SKILL.md) and [AGENTS.md](../AGENTS.md)
|
||||
127
agent/skills-disabled/ppt-master/docs/getting-started.md
Normal file
127
agent/skills-disabled/ppt-master/docs/getting-started.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Getting Started
|
||||
|
||||
The short path to your first deck, how to use everything around it — templates, live preview, animations, narration, voice cloning — and where to look when something goes wrong. Sections follow roughly the order you meet them in a real run. Each is the quick version; follow the **Full guide →** link for depth.
|
||||
|
||||
- [Start from a template](#start-from-a-template)
|
||||
- [Generate your first deck](#generate-your-first-deck)
|
||||
- [Live preview & visual edits](#live-preview--visual-edits)
|
||||
- [Animations & transitions](#animations--transitions)
|
||||
- [Narration & video](#narration--video)
|
||||
- [Use a cloned voice](#use-a-cloned-voice)
|
||||
- [When something goes wrong](#when-something-goes-wrong)
|
||||
|
||||
---
|
||||
|
||||
## Start from a template
|
||||
|
||||
**Optional.** By default PPT Master uses **free design** — you don't need a template, and you can skip to the next section. Reach for one only when a deck must reuse a fixed layout set or brand identity.
|
||||
|
||||
**Two ways to reuse an existing `.pptx`, depending on what you want back:**
|
||||
|
||||
| You want… | Route | What happens |
|
||||
|---|---|---|
|
||||
| **This exact deck, with new content** | Template fill | Picks the pages that fit (a page can be reused for several output slides), swaps text / table / chart data straight in the original file. Design, layouts, images, animations preserved; output is the same deck, natively editable. Fastest; bound to the existing layouts. |
|
||||
| **A new deck in this deck's style** | create-template | Parses the `.pptx` into a reusable style bundle, then generates a fresh deck through the SVG pipeline — new structure, any page count. More flexible; full regeneration. |
|
||||
|
||||
For the first, give the AI your `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" — see the [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md). The rest of this section covers create-template.
|
||||
|
||||
**To generate a new deck in an existing PowerPoint's style, you must explicitly run the create-template flow — don't just hand over a `.pptx` and expect the AI to handle it.** The AI defaults to free design and won't switch into the template flow on its own; without an explicit trigger, generation easily goes off the rails. First turn that `.pptx` into a PPT Master template via create-template:
|
||||
|
||||
```
|
||||
You: Replicate this as a template via /create-template: projects/brand/our_deck.pptx
|
||||
```
|
||||
|
||||
That runs `pptx_template_import.py` and rebuilds the file into a reusable bundle — layout SVGs + `design_spec.md` + extracted theme colors, fonts, and images. That bundle is what you point to at generation time.
|
||||
|
||||
A created template lives in one of two places:
|
||||
|
||||
| Location | Path | Notes |
|
||||
|---|---|---|
|
||||
| **Registered in the skill library** | `skills/ppt-master/templates/layouts/<id>/` | Global, reusable across every project; run `register_template.py` so it shows up when you ask "what templates are available?" |
|
||||
| **Inside a project** | `projects/<project>/templates/` | Project-local; works by path, no registration needed |
|
||||
|
||||
Either way, you invoke it during generation by giving its **directory path** in chat — the workflow triggers on an explicit path only, never on a bare template name:
|
||||
|
||||
```
|
||||
You: Make a deck from sources/report.pdf with template skills/ppt-master/templates/layouts/academic_defense/
|
||||
```
|
||||
|
||||
Full guide → [Templates Guide](./templates-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## Generate your first deck
|
||||
|
||||
The whole loop is three steps. Install first — you only need Python; see [Quick Start](../README.md#quick-start).
|
||||
|
||||
1. **Drop your source material** into `projects/` — a PDF, DOCX, Markdown file, a URL, or just text you'll paste.
|
||||
2. **Tell the AI in chat** what to turn into a deck (add a template path if you set one up above; otherwise it's free design):
|
||||
```
|
||||
You: Make a deck from projects/q3-report/sources/report.pdf
|
||||
You: 把这份内容做成 PPT：<paste your text>
|
||||
```
|
||||
3. **Get an editable `.pptx`** at `exports/<name>_<timestamp>.pptx` — real DrawingML shapes, text boxes, and charts you can click and edit in PowerPoint, Keynote, WPS, or LibreOffice.
|
||||
|
||||
Before it starts, the AI confirms a short design spec (template, format, page count, …); from there it handles content analysis, layout, image acquisition, SVG generation, and export — the core loop everything else builds on.
|
||||
|
||||
---
|
||||
|
||||
## Live preview & visual edits
|
||||
|
||||
A browser preview opens at `http://localhost:5050` while the deck is being generated.
|
||||
|
||||
- **Watch pages render live** as the AI produces them.
|
||||
- **Edit directly, no AI** — select an element to change its text, color, font, or size in the side panel; drag it to reposition, or nudge with the arrow keys (`Shift` = 10px). `Ctrl+Z` undoes. Edits preview instantly and write to `svg_output/` when you click **Apply changes**.
|
||||
- **Or annotate for the AI** — click an element, type what you want changed, hit **Submit annotations**, then say "apply my annotations" in chat and the AI rewrites that region and re-exports the PPTX.
|
||||
|
||||
PPT Master was chat-only by design; visual editing was folded in after enough users asked for it (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85)).
|
||||
|
||||
Full guide → [Live Preview Workflow](../skills/ppt-master/workflows/live-preview.md)
|
||||
|
||||
---
|
||||
|
||||
## Animations & transitions
|
||||
|
||||
Exported decks ship **page transitions** and **per-element entrance animations** as real OOXML — not embedded video. By default, elements cascade in on slide entry with no setup, and the deck plays natively in PowerPoint and Keynote with no extra tooling. Reach for customization only when you want a specific order, effect, or timing.
|
||||
|
||||
Full guide → [Animations & Transitions](../skills/ppt-master/references/animations.md)
|
||||
|
||||
---
|
||||
|
||||
## Narration & video
|
||||
|
||||
Turn the speaker notes into per-slide voice narration, embed the audio back into the PPTX, and let PowerPoint export the deck as a synced-narration MP4 — no third-party tools.
|
||||
|
||||
```
|
||||
You: Generate narration for this deck and re-export with audio embedded.
|
||||
You: 给这个 PPT 生成音频
|
||||
```
|
||||
|
||||
Narration defaults to `edge-tts` (about 90 locales); optional cloud providers cover higher-quality voices. The AI recommends a voice for the deck's language and asks once before generating.
|
||||
|
||||
Full guide → [Audio Narration & Video Export](./audio-narration.md)
|
||||
|
||||
---
|
||||
|
||||
## Use a cloned voice
|
||||
|
||||
Bring your own cloned voice from ElevenLabs / MiniMax / Qwen / CosyVoice and have the whole deck narrated in *your* voice (or a presenter's, with permission). Clone once in the provider's console, then pass the `voice_id` — PPT Master reads every slide's notes in that voice and embeds the result back into the PPTX.
|
||||
|
||||
Full guide → [Use a cloned voice](./audio-narration.md#use-a-cloned-voice)
|
||||
|
||||
---
|
||||
|
||||
## When something goes wrong
|
||||
|
||||
The [FAQ](./faq.md) is the living troubleshooting reference — continuously updated from real user reports. Quick pointers for the most common situations:
|
||||
|
||||
| Situation | First thing to try |
|
||||
|---|---|
|
||||
| The AI drifts or forgets a step | Ask it to re-read `skills/ppt-master/SKILL.md`. |
|
||||
| Visual quality disappoints | Switch to a large-context Claude model + `gpt-image-2` — the harness sets the floor, the model sets the ceiling. |
|
||||
| Text overflows or elements overlap | Re-run that page, or fix it in live preview; see the [FAQ](./faq.md). |
|
||||
| No image-generation API key | Zero-config web search still works as a fallback; see the [FAQ](./faq.md). |
|
||||
| Animations or some effects look off in another app | The file is standard `.pptx` and opens in PowerPoint / Keynote / WPS / LibreOffice; element animations render most completely in PowerPoint 2016+ and Keynote, while older Office may downgrade some to plain Appear. |
|
||||
| A long deck might blow the context window | Generation can run in split mode; details in the [FAQ](./faq.md). |
|
||||
|
||||
For model choice, cost, chart editability, custom templates, and more, the [FAQ](./faq.md) is the place to look.
|
||||
108
agent/skills-disabled/ppt-master/docs/roadmap.md
Normal file
108
agent/skills-disabled/ppt-master/docs/roadmap.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Roadmap
|
||||
|
||||
[English](./roadmap.md) | [中文](./zh/roadmap.md)
|
||||
|
||||
---
|
||||
|
||||
> PPT Master is a solo-maintained open source project, driven by **priority rather than fixed timelines**. This roadmap is here to align expectations: what's already shipped, what's under ongoing maintenance and evolution, and what's intentionally out of scope. Priorities shift with user feedback and real usage signals — no committed delivery windows.
|
||||
>
|
||||
> **Where we are**: AI generates SVG from scratch → converts to DrawingML for natively editable PPTX. The core axis is **pixel-fidelity across four renderers** (PowerPoint / Keynote / LibreOffice / WPS) **+ real native shapes**. Every direction below serves that axis.
|
||||
|
||||
---
|
||||
|
||||
## Recent capability evolution
|
||||
|
||||
The past two months' structural capability growth. Single flags / incremental polish go to the commit log.
|
||||
|
||||
### 2026-03 — Native PPTX route takes shape
|
||||
|
||||
- **Direct export to natively editable PPTX** — `svg_to_pptx` adds glow / rotate / text-decoration / stroke-linejoin; the full SVG → DrawingML chain becomes usable
|
||||
- Chart / layout template JSON indexes ship, AI selection path connected
|
||||
|
||||
### 2026-04 — Pipeline at scale
|
||||
|
||||
- **Source-less generation**: `topic-research` workflow supports "topic only, no source files"
|
||||
- **PPTX export step-change**: SVG clipPath → DrawingML picture geometry, marker → native arrows, output consolidated to `exports/`
|
||||
- **Chart library expands to 70 templates + three icon libraries** (simple-icons / phosphor-duotone / brand-logo)
|
||||
- **`spec_lock.md` machine-readable contract**: Strategist locks the spec, Executor re-reads it before every page — cross-page consistency gets a real guarantee
|
||||
- **Per-element animation on by default** + recorded narration / video export ([`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md))
|
||||
|
||||
### 2026-05 — Visual editing + AI image systematization
|
||||
|
||||
- **Live Preview enters the main pipeline** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — browser preview, click elements to write annotations, say "apply my annotations" and the AI rewrites that region (built on [@WodenJay](https://github.com/WodenJay)'s [PR #85](https://github.com/hugohe3/ppt-master/pull/85))
|
||||
- **Replicate any PPTX as a template** ([`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md)) — PPTX → SVG reverse + OOXML theme / master / layout / asset extraction
|
||||
- **AI image three-dimension system** rendering × palette × type + Strategist h.5 lock, downstream consumes a fixed contract
|
||||
- **AI image `hero_page` dual-track** — local insert + full-canvas hero image coexist
|
||||
- **Brand identity preset subsystem** ([`workflows/create-brand.md`](../skills/ppt-master/workflows/create-brand.md)) — extract and reuse brand palette / typography / logo / voice
|
||||
- **Visual self-review workflow** ([`workflows/visual-review.md`](../skills/ppt-master/workflows/visual-review.md)) — rubric-based per-page check of AI-generated SVGs
|
||||
- **AI image: Type concept boundary clarification** — Type is now narrowed to "the internal geometric skeleton of a local infographic block" (11 real skeletons); the four pseudo-types (hero / background / portrait / typography) fold back into `page_role: hero_page` plus four composition primitives (single-subject / portrait / typographic / atmospheric); hero_page text layering rule (visual keywords embedded, editable text via SVG overlay)
|
||||
- **Brutalist AI newspaper example deck shipped** ([`examples/ppt169_brutalist_ai_newspaper_2026/`](../examples/ppt169_brutalist_ai_newspaper_2026/)) — first of the three P0 capability-backing demos: wall-to-wall small type + irregular columns + halftone monochrome + single-spot red + real native shapes; 10-page editorial annual report stressing text-position precision and cross-page consistency
|
||||
- **Kubernetes Blueprint example deck shipped** ([`examples/ppt169_kubernetes_blueprint_2026/`](../examples/ppt169_kubernetes_blueprint_2026/)) — second of the three P0 capability-backing demos: isometric technical-drawing aesthetic + blueprint cyan/amber palette + hand-authored SVG geometry (no raster images) + custom drawing-in animation; 10-page Kubernetes architecture walkthrough stressing geometric shape generalization and chart-structure extensibility
|
||||
- **AI image `custom` escape hatch** — `rendering` / `palette` / hero composition each accept `custom` + a one-paragraph `*_behavior` prose, replacing the false "default to vector-illustration / cool-corporate" fallback; end-to-end contract spans [`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 per dimension; one candidate may carry both), spec_lock fields, and Image_Generator Step 2 consumption branch
|
||||
- **Template architecture: three-kind consolidation** ([`docs/templates-architecture.md`](./templates-architecture.md)) — brand / layout / deck split into three independent dirs with per-kind schemas + segment-level fusion + git-style conflict resolution; SKILL.md Step 3 dispatches per `kind`, trigger rule remains "explicit path only"
|
||||
- **Pattern fill PPTX safety net** — `svg_quality_checker.py` now warns on `<pattern>` without `data-pptx-pattern` (silent fallback to `ltUpDiag`) and errors on values outside OOXML `ST_PresetPatternVal` (schema-failed PPTX that won't open); `shared-standards.md §7` documents the closed preset enum and the required `<rect fill="<bg>"/>` child convention
|
||||
- **LaTeX math formula rendering shipped** ([`scripts/latex_render.py`](../skills/ppt-master/scripts/latex_render.py)) — Strategist locks one of three policies (`mixed` / `render-all` / `text-only`) inside the Typography confirmation and writes an explicit `images/formula_manifest.json`; the renderer walks a codecogs → quicklatex → mathpad → wikimedia fallback chain and emits transparent PNGs that land in §VIII as `Acquire Via: formula` / `Status: Rendered` rows; formula-heavy decks (academic / engineering / educational) finally have a native rendering route. Formula selection is a Strategist decision — the renderer never scans source files for `$...$` markers
|
||||
- **Live preview direct editing — L1 / L2 / L3** ([`workflows/live-preview.md`](../skills/ppt-master/workflows/live-preview.md)) — the browser editor gains deterministic in-place edits with no AI round-trip: text content (L1), presentation attributes like fill / stroke / font-size (L2), and on-canvas geometry (L3) — drag a selected element to move it, arrow-key nudge (`Shift` = 10px), multi-select, plus a right-click overlap picker for stacked shapes. Edits stage with `Ctrl+Z` undo + coalescing and write to `svg_output/` on **Apply changes**; moves persist through finalize / export (moved text frames, promoted multi-line tspans, repositioned icons all reproduce in the PPTX). Re-export stays chat-driven; on-canvas resize handles are not yet implemented (resize via the geometry inputs)
|
||||
|
||||
---
|
||||
|
||||
## Ongoing maintenance directions
|
||||
|
||||
Long-running improvements with no committed timeline. Only real directions are listed; specific fixes / single flags go to the commit log.
|
||||
|
||||
- **Prompt slimming** — compress per-role prompt token footprint and improve cache hit rate without sacrificing quality, for indirect cost / speed gains. Complements "Pure speed optimization" below: indirect optimization yes, quality-sacrificing speedups no.
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
The directions below come up repeatedly and have been evaluated as **not on the path**. Listing them is not a value judgment on the underlying need — they simply don't fit this project's main route. If you specifically need these capabilities, consider other tools or forking.
|
||||
|
||||
### Read arbitrary PPTX templates → fill text only
|
||||
|
||||
**Issues**: [#53](https://github.com/hugohe3/ppt-master/issues/53), [#118](https://github.com/hugohe3/ppt-master/issues/118)
|
||||
|
||||
PPT Master's main route is "AI generates SVG from scratch → DrawingML", with the whole pipeline built around full control of every shape / text / layout. "Parse existing PPTX placeholders + only refill text" is a different product shape requiring handling of arbitrary master / theme / placeholder systems — orthogonal to where this architecture invests.
|
||||
|
||||
**The basic need is actually simple**: if you just need "replace Excel data into fixed positions in a PPT template", have the AI write a few lines of `python-pptx`. You don't need this pipeline.
|
||||
|
||||
### Switch to native PowerPoint charts (Excel-native chart)
|
||||
|
||||
**Issues**: [#99](https://github.com/hugohe3/ppt-master/issues/99), [#100](https://github.com/hugohe3/ppt-master/issues/100)-class
|
||||
|
||||
Pixel-fidelity across the four renderers (PowerPoint / Keynote / LibreOffice / WPS) is the project's spine. Switching to native PowerPoint charts breaks that — the same PPTX renders different chart layouts across renderers. Charts as SVG is **by design**, not a capability gap.
|
||||
|
||||
If you need data-driven native Excel charts, pick a different tool or manually replace charts in PowerPoint post-export — this project won't build that path in.
|
||||
|
||||
### uv as default / required dependency
|
||||
|
||||
**Issue**: [#111](https://github.com/hugohe3/ppt-master/issues/111)
|
||||
|
||||
`pip + requirements.txt` is the only official install path because it works in every Python environment with no extra learning cost. uv is a fine tool, but making it default raises the bar for new users. If you personally prefer uv, use it in your fork — it won't affect the main line.
|
||||
|
||||
### Pure speed optimization
|
||||
|
||||
**Issue**: [#97](https://github.com/hugohe3/ppt-master/issues/97)
|
||||
|
||||
In the cost / speed / quality triangle this project picks **quality**. ~20 minutes for a high-quality PPTX is the current reasonable point.
|
||||
|
||||
Will do: indirect improvements via prompt slimming / cache hit rate.
|
||||
Won't do: trading quality for "throw a few pages together" speed.
|
||||
|
||||
If speed-sensitive and quality-tolerant, Gamma / similar AI tools are a better fit.
|
||||
|
||||
### CLI / SaaS / desktop app form factors
|
||||
|
||||
The product form is firmly **chat-driven AI IDE skill** (Claude Code / Cursor / VS Code + Copilot / Codebuddy).
|
||||
|
||||
Won't do: standalone CLI (`ppm`-style), SaaS web service, Electron shell. Any "make it run independently of chat" proposal will be declined. Chat is the interaction core, not a wrapper.
|
||||
|
||||
---
|
||||
|
||||
## Feedback channels
|
||||
|
||||
- **Issues**: [github.com/hugohe3/ppt-master/issues](https://github.com/hugohe3/ppt-master/issues) — bugs / proposals
|
||||
- **Discussions**: [github.com/hugohe3/ppt-master/discussions](https://github.com/hugohe3/ppt-master/discussions) — usage / experience sharing
|
||||
- **Email**: heyug3@gmail.com
|
||||
|
||||
Before proposing a new direction, scan the **Non-goals** above. If your request falls there, it's unlikely to land — but we're happy to discuss other paths to your underlying need.
|
||||
15
agent/skills-disabled/ppt-master/docs/rules/README.md
Normal file
15
agent/skills-disabled/ppt-master/docs/rules/README.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Project Rules
|
||||
|
||||
Conventions and style guides for contributors and AI agents working in this repository. These rules are derived from the de facto patterns in existing code and reference documents.
|
||||
|
||||
| Rule | Scope |
|
||||
|---|---|
|
||||
| [`prompt-style.md`](./prompt-style.md) | Style guide for files under `skills/ppt-master/references/` — voice, sectioning, table-first, forbidden patterns |
|
||||
| [`code-style.md`](./code-style.md) | Style guide for Python under `skills/ppt-master/scripts/` — file headers, imports, CLI entry points, error handling, no-tests rule |
|
||||
|
||||
When adding a new rule file:
|
||||
|
||||
- One topic per file
|
||||
- File name `<topic>.md` (lowercase, hyphenated)
|
||||
- Add a row to the table above
|
||||
- The body should be **prescriptive, not descriptive** — tell readers what to do, not what the project happens to look like
|
||||
327
agent/skills-disabled/ppt-master/docs/rules/code-style.md
Normal file
327
agent/skills-disabled/ppt-master/docs/rules/code-style.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# Python Code Style Guide
|
||||
|
||||
> Style rules for Python code under `skills/ppt-master/scripts/` and any Python that ships with the skill. Derived from the de facto patterns in the existing codebase.
|
||||
|
||||
These rules are pragmatic, not exhaustive. They capture the conventions readers actually encounter — anything PEP 8 hands you for free is assumed.
|
||||
|
||||
---
|
||||
|
||||
## 1. File Header
|
||||
|
||||
Every script under `scripts/` starts with:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
PPT Master - Short Tool Name
|
||||
|
||||
One-paragraph description of what this script does.
|
||||
|
||||
Usage:
|
||||
python3 scripts/<name>.py <required_arg> [options]
|
||||
|
||||
Examples:
|
||||
python3 scripts/<name>.py projects/<project_name> -o output_dir
|
||||
|
||||
Dependencies:
|
||||
None (only uses standard library) <-- or list third-party deps
|
||||
"""
|
||||
```
|
||||
|
||||
| Element | Rule |
|
||||
|---|---|
|
||||
| Shebang | `#!/usr/bin/env python3` (always — even for non-CLI helper modules) |
|
||||
| Module docstring | Tool name + purpose + Usage + Examples + Dependencies |
|
||||
| Internal helper modules | May add an early `--help` short-circuit (see §4) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Imports
|
||||
|
||||
```python
|
||||
# 1. Standard library
|
||||
import os
|
||||
import sys
|
||||
import argparse
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
# 2. Third-party
|
||||
import requests
|
||||
|
||||
# 3. Local — sometimes need sys.path injection first (see §3)
|
||||
from image_sources.provider_common import (
|
||||
AssetCandidate,
|
||||
ImageSearchRequest,
|
||||
)
|
||||
```
|
||||
|
||||
| Rule | Note |
|
||||
|---|---|
|
||||
| Group order | std → third-party → local, blank line between groups |
|
||||
| Within a group | Sorted by length when short; alphabetical when ≥ 4 imports |
|
||||
| `from x import` lists | One name per line if ≥ 4 names, with trailing comma |
|
||||
| `from __future__ import annotations` | Add at top when the file uses `X \| Y` union syntax (PEP 604) and may run on Python < 3.10 |
|
||||
|
||||
---
|
||||
|
||||
## 3. sys.path Injection (Project Convention)
|
||||
|
||||
`scripts/` is **not a Python package** — it's a flat directory of scripts. Each entry-point script that imports a sibling module injects `scripts/` onto `sys.path` itself:
|
||||
|
||||
```python
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
_SCRIPTS_DIR = Path(__file__).resolve().parent
|
||||
if str(_SCRIPTS_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(_SCRIPTS_DIR))
|
||||
|
||||
from image_backends.backend_common import download_image # noqa: E402
|
||||
```
|
||||
|
||||
| Rule | Why |
|
||||
|---|---|
|
||||
| Inject only in entry-points | Library modules under `image_sources/` / `image_backends/` import each other normally |
|
||||
| Use `Path(__file__).resolve().parent` | Robust under symlinks and aliasing |
|
||||
| Annotate post-injection imports with `# noqa: E402` | Suppress the lint warning honestly, not via per-file noqa |
|
||||
|
||||
---
|
||||
|
||||
## 4. CLI Entry Points
|
||||
|
||||
```python
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="One-line description.",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
parser.add_argument("query", help="...")
|
||||
parser.add_argument("-o", "--output", default=".", help="...")
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: Optional[list[str]] = None) -> int:
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
# ... do the thing ...
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
```
|
||||
|
||||
| Rule | Note |
|
||||
|---|---|
|
||||
| `main(argv=None) -> int` | Returns exit code; testable by passing `argv` |
|
||||
| `raise SystemExit(main())` | Preferred over `sys.exit(main())` |
|
||||
| `formatter_class=argparse.RawDescriptionHelpFormatter` | Preserves docstring formatting in `--help` |
|
||||
| Internal helpers `--help` | Module-level: `if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]): print(__doc__); raise SystemExit(0)` |
|
||||
| Output | Progress / status to **stderr**; the script's primary output (if any) to stdout |
|
||||
|
||||
---
|
||||
|
||||
## 5. Type Hints
|
||||
|
||||
Required for all new public functions; optional for internal `_helpers`.
|
||||
|
||||
| Pattern | Use |
|
||||
|---|---|
|
||||
| `def f(x: str, *, y: int = 0) -> bool:` | Public functions |
|
||||
| `tuple[int, int] \| None` | PEP 604 unions (with `from __future__ import annotations` if needed for compat) |
|
||||
| `Optional[X]` from `typing` | Acceptable alternative to `X \| None` |
|
||||
| `list[X]`, `dict[K, V]` | Built-in generics (Python 3.9+) |
|
||||
| `Any` | Sparingly — only when interfacing with truly heterogeneous data (`raw: Any` in dataclasses for upstream JSON) |
|
||||
|
||||
**Forbidden — over-specification**:
|
||||
|
||||
- `Callable[[int, str], dict[str, list[Optional[Union[int, str]]]]]` — break this into typed dataclasses
|
||||
- `Literal["a", "b", "c"]` everywhere — use a constant + plain `str` unless the type itself is the API
|
||||
|
||||
---
|
||||
|
||||
## 6. Naming
|
||||
|
||||
| Kind | Convention | Examples |
|
||||
|---|---|---|
|
||||
| Module file | `snake_case.py` | `image_search.py`, `svg_to_pptx.py` |
|
||||
| Script entrypoint | verb or noun phrase | `finalize_svg.py`, `notes_to_audio.py` |
|
||||
| Public function | `snake_case` | `download_image`, `parse_results` |
|
||||
| Private helper | `_snake_case` | `_load_dotenv_if_available`, `_measure_actual_image` |
|
||||
| Constant | `UPPER_SNAKE_CASE` | `API_URL`, `DEFAULT_PAGE_SIZE`, `LICENSE_TIER_NO_ATTRIBUTION` |
|
||||
| Class | `PascalCase` | `AssetCandidate`, `SVGQualityChecker` |
|
||||
| Dataclass field | `snake_case` | `license_tier`, `download_url` |
|
||||
| Module-private regex | `_PATTERN_RE` (private + `_RE` suffix) | `_TAG_RE`, `HEADING_RE` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Error Handling
|
||||
|
||||
| Situation | Pattern |
|
||||
|---|---|
|
||||
| Optional dependency | `try: import x; HAS_X = True\nexcept ImportError: HAS_X = False` |
|
||||
| Optional sibling module | `try: from project_utils import CANVAS_FORMATS\nexcept ImportError: CANVAS_FORMATS = {}; print("Warning: ...")` |
|
||||
| Recoverable runtime failure | Catch specific exceptions, log to stderr, return / continue — do NOT halt the pipeline |
|
||||
| User-facing error | `print("...", file=sys.stderr); return 1` from `main()` |
|
||||
| Programming error | Raise — don't paper over a bug |
|
||||
|
||||
**Hard rule**: never bare-`except:`. Always name the exception class.
|
||||
|
||||
**Forbidden — silent fallbacks for security-relevant code**:
|
||||
|
||||
- Disabling SSL verification without a domain whitelist + WARNING
|
||||
- Catching all exceptions in a download path without logging the cause
|
||||
|
||||
---
|
||||
|
||||
## 8. Dependencies
|
||||
|
||||
| Tier | Where it can be required |
|
||||
|---|---|
|
||||
| Standard library | Anywhere |
|
||||
| `requests`, `Pillow`, `lxml` | Common dependencies; safe to require in main scripts |
|
||||
| Provider SDKs (`google-genai`, `openai`, `anthropic`, etc.) | **Lazy import inside the function that uses it**; soft-fail with `ImportError` → `RuntimeError` containing install instructions |
|
||||
| `python-dotenv` | Optional — wrap the import in try/except, no-op if unavailable |
|
||||
|
||||
```python
|
||||
def _require_api_key() -> str:
|
||||
key = os.environ.get("PEXELS_API_KEY") or ""
|
||||
if not key:
|
||||
raise RuntimeError(
|
||||
"PEXELS_API_KEY is not set. Add it to your environment or .env file. "
|
||||
"Get one at https://www.pexels.com/api/"
|
||||
)
|
||||
return key
|
||||
```
|
||||
|
||||
Error messages **must include the fix** — "what env var to set", "where to get a key", "which package to install".
|
||||
|
||||
---
|
||||
|
||||
## 9. Shared Helpers Layer
|
||||
|
||||
Common functionality lives in two designated submodules. New scripts use these, not their own copies:
|
||||
|
||||
| Module | Owns |
|
||||
|---|---|
|
||||
| [`image_backends/backend_common.py`](../skills/ppt-master/scripts/image_backends/backend_common.py) | HTTP download, retry, image format detection, save-with-Pillow-transcode |
|
||||
| [`image_sources/provider_common.py`](../skills/ppt-master/scripts/image_sources/provider_common.py) | License classification, query simplification, scoring, attribution text, dataclasses |
|
||||
| [`project_utils.py`](../skills/ppt-master/scripts/project_utils.py) | Canvas formats, project path conventions |
|
||||
| [`error_helper.py`](../skills/ppt-master/scripts/error_helper.py) | User-facing error message templates |
|
||||
|
||||
**Forbidden — duplicating logic that exists in a shared helper**. If a helper is missing a feature, extend the helper, don't fork it inside your new script.
|
||||
|
||||
---
|
||||
|
||||
## 10. Docstrings
|
||||
|
||||
Short and imperative. No Args/Returns/Raises sections unless the signature is genuinely complex.
|
||||
|
||||
```python
|
||||
def classify_license(
|
||||
license_name: str,
|
||||
license_url: str = "",
|
||||
provider: str = "",
|
||||
) -> Optional[str]:
|
||||
"""Classify a license string into one of the two tiers, or reject it.
|
||||
|
||||
Returns:
|
||||
``"no-attribution"`` / ``"attribution-required"`` / ``None``.
|
||||
|
||||
The provider hint lets us treat Pexels and Pixabay's own licenses as
|
||||
``no-attribution`` even when the upstream API only returns a short
|
||||
label like ``"Pexels"``.
|
||||
"""
|
||||
```
|
||||
|
||||
| Use a Google/Sphinx-style block | Skip the block |
|
||||
|---|---|
|
||||
| Function returns multiple branches with semantic differences | One-liner that explains itself in the function name |
|
||||
| Has more than 3 parameters with non-obvious roles | Single-purpose helper |
|
||||
| Maintains a non-trivial invariant | Pure formatter / accessor |
|
||||
|
||||
---
|
||||
|
||||
## 11. Testing
|
||||
|
||||
**Hard rule**: this repository does **not** ship automated tests.
|
||||
|
||||
**Forbidden**:
|
||||
|
||||
- `tests/` directories
|
||||
- `test_*.py` files
|
||||
- `unittest` / `pytest` imports
|
||||
- `if __name__ == "__main__":` blocks that run a self-test suite
|
||||
|
||||
**Use instead**:
|
||||
|
||||
- Inline smoke commands via `python3 -c "..."` against real project samples; show the output in the conversation / PR description
|
||||
- Manual verification steps in the runbook
|
||||
- Live-API smoke runs against `projects/_smoke_*` directories (gitignored)
|
||||
|
||||
This is a deliberate project convention. When external contributors include tests, ask them to remove tests in PR review (see [`docs/rules/prompt-style.md`](./prompt-style.md) §11 for the parallel rule on reference docs).
|
||||
|
||||
---
|
||||
|
||||
## 12. Dataclasses
|
||||
|
||||
Prefer plain `@dataclass` over `pydantic` / `attrs` for value types. Keep them simple:
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class AssetCandidate:
|
||||
provider: str
|
||||
title: str
|
||||
asset_id: str = ""
|
||||
license_tier: str = ""
|
||||
width: int = 0
|
||||
height: int = 0
|
||||
raw: Any = None
|
||||
```
|
||||
|
||||
| Rule | Note |
|
||||
|---|---|
|
||||
| `@dataclass` | Default; no need for `frozen=True` unless mutation is a real risk |
|
||||
| Fields | All required fields first, then optional with defaults |
|
||||
| `field(default_factory=...)` | Only when the default needs to be a new container per instance |
|
||||
| No legacy positional-arg shims | New dataclass = keyword-arg API. YAGNI on positional support |
|
||||
| Methods | Keep dataclasses dumb; computation goes in module-level functions |
|
||||
|
||||
---
|
||||
|
||||
## 13. File Encoding & Line Endings
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Encoding | UTF-8 |
|
||||
| Line endings | LF |
|
||||
| Final newline | Always present |
|
||||
| BOM | Forbidden |
|
||||
| Indentation | 4 spaces (no tabs) |
|
||||
| Max line length | Soft 100; hard 120. Prose in docstrings can flow longer |
|
||||
|
||||
---
|
||||
|
||||
## 14. Cross-references
|
||||
|
||||
When a Python file mirrors a reference doc, cross-link both ways:
|
||||
|
||||
- The script's docstring mentions the reference: `See references/image-searcher.md for the on-slide attribution rules.`
|
||||
- The reference doc cites the script with a backticked relative link
|
||||
|
||||
This keeps `prompt-style.md` and `code-style.md` (this file) operating as a pair — neither layer drifts away from the other.
|
||||
|
||||
---
|
||||
|
||||
## 15. When This Guide Conflicts With Existing Files
|
||||
|
||||
Existing files take precedence. If a current script contradicts a rule here, decide whether to (a) update this guide, or (b) refactor the script. The canonical exemplars to model new scripts after:
|
||||
|
||||
| If you're writing... | Model after |
|
||||
|---|---|
|
||||
| A small CLI utility | [`total_md_split.py`](../skills/ppt-master/scripts/total_md_split.py), [`gemini_watermark_remover.py`](../skills/ppt-master/scripts/gemini_watermark_remover.py) |
|
||||
| A multi-backend / dispatcher CLI | [`image_search.py`](../skills/ppt-master/scripts/image_search.py), [`image_gen.py`](../skills/ppt-master/scripts/image_gen.py) |
|
||||
| A library / shared helper | [`image_sources/provider_common.py`](../skills/ppt-master/scripts/image_sources/provider_common.py), [`image_backends/backend_common.py`](../skills/ppt-master/scripts/image_backends/backend_common.py) |
|
||||
| A class-based checker / validator | [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) |
|
||||
193
agent/skills-disabled/ppt-master/docs/rules/prompt-style.md
Normal file
193
agent/skills-disabled/ppt-master/docs/rules/prompt-style.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Reference Document Style Guide
|
||||
|
||||
> Style rules for files under `skills/ppt-master/references/`. Follow these when writing or reviewing role definitions and shared specs.
|
||||
|
||||
The reference layer drives runtime LLM behavior. Style consistency across these files matters as much as correctness — divergent voice / structure forces the model to re-interpret each file from scratch and bloats the loaded context.
|
||||
|
||||
---
|
||||
|
||||
## 1. Document Header
|
||||
|
||||
| Element | Rule |
|
||||
|---|---|
|
||||
| Top line | `> See [`xxx`](xxx.md) for ...` — one-line cross-reference, optional |
|
||||
| H1 title | `# Role: X` (for role files) or `# X Reference Manual` / `# X Specification` |
|
||||
| Opening paragraph | One sentence stating mission + trigger. Max 2 lines |
|
||||
| `## Core Mission` | Optional; if present, ≤ 3 sentences |
|
||||
|
||||
✅ Good (from `image-searcher.md`):
|
||||
```
|
||||
> See [`image-base.md`](./image-base.md) for the common framework.
|
||||
|
||||
# Image_Searcher Reference Manual
|
||||
|
||||
Role definition for the **web image acquisition path**: translate Strategist intent into keyword queries, search openly-licensed providers, download a license-cleared image into `project/images/`, and record provenance + license metadata into `image_sources.json`.
|
||||
|
||||
**Trigger**: resource list rows with `Acquire Via: web`. The role is loaded only when at least one such row exists.
|
||||
```
|
||||
|
||||
❌ Avoid: long "Core Mission" paragraphs that explain *why* the role exists, list its philosophical goals, or narrate the pipeline context.
|
||||
|
||||
---
|
||||
|
||||
## 2. Sectioning
|
||||
|
||||
| Level | Format | Notes |
|
||||
|---|---|---|
|
||||
| Main | `## N. Title` | Numbered from 1 |
|
||||
| Sub | `### N.1` / `### N.2` ... | Or `### a.` / `### b.` for confirmation flows |
|
||||
| Divider | `---` between main sections | Always |
|
||||
|
||||
`## Core Mission`, `## Pipeline Context`, `## Trigger` may appear before `## 1.` without numbering.
|
||||
|
||||
---
|
||||
|
||||
## 3. Voice — Command, Not Explanation
|
||||
|
||||
| Use | Don't use |
|
||||
|---|---|
|
||||
| `Run X.` | `You should typically run X because ...` |
|
||||
| `Output: Y` | `The role outputs Y, which is important because ...` |
|
||||
| `MUST come from Z` | `It is recommended to source from Z` |
|
||||
| `Forbidden — values outside the lock` | `Anti-pattern: using values outside the lock` |
|
||||
|
||||
**Hard rule**: if a sentence explains *why*, demote it to a single `> Note` blockquote line OR cut it. The agent does not need motivation, only behavior.
|
||||
|
||||
---
|
||||
|
||||
## 4. Bold Inline Labels
|
||||
|
||||
Begin substantive paragraphs with a bolded short label. Reuse this fixed vocabulary:
|
||||
|
||||
| Label | Use for |
|
||||
|---|---|
|
||||
| `**Hard rule**:` | Non-negotiable behavior |
|
||||
| `**Forbidden — xxx**:` | Disallowed values / actions, followed by a list |
|
||||
| `**Mandatory**:` | Required step within an optional phase |
|
||||
| `**When to run**:` / `**Trigger**:` | Activation condition |
|
||||
| `**Validation**:` | Post-step assertion |
|
||||
| `**Per-page xxx**:` / `**Per-row xxx**:` | Loop body description |
|
||||
| `**Generation pacing (mandatory)**:` | Concurrency / rate constraint |
|
||||
| `**Missing X**` → ... | Fallback behavior |
|
||||
|
||||
✅ Good (from `executor-base.md`):
|
||||
```
|
||||
**Hard rule**: Before generating **each** SVG page, `read_file <project_path>/spec_lock.md`.
|
||||
|
||||
**Forbidden — values outside the lock**:
|
||||
- Colors (fill / stroke / stop-color) MUST come from `colors`
|
||||
- Icons MUST come from `icons.inventory`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Tables First
|
||||
|
||||
Most sections need at least one table. Reach for a table whenever you would write 3+ parallel bullet points.
|
||||
|
||||
| Use case | Format |
|
||||
|---|---|
|
||||
| Enums, modes, options | Table with `Key | Behavior` |
|
||||
| Field definitions | Table with `Field | Notes` |
|
||||
| Decision matrices | Table with `Condition | Action` |
|
||||
| Cross-reference index | Table with `Term | Defined in` |
|
||||
|
||||
Bullets are fine for ≤ 3 short imperatives or a single ordered procedure.
|
||||
|
||||
---
|
||||
|
||||
## 6. Examples
|
||||
|
||||
| Form | Use |
|
||||
|---|---|
|
||||
| Fenced code block (` ``` `) | Commands, file content, ASCII diagrams |
|
||||
| Inline code (` ` `) | File paths, identifiers, env vars |
|
||||
| 2-column ✅/❌ table | Short keyword-vs-keyword contrast (one phrase per cell) |
|
||||
|
||||
❌ Avoid: 3-column ✅/❌/(why) tables. The "why" column is explanation — drop it or move to a `>` note.
|
||||
|
||||
❌ Avoid: long narrative example paragraphs. Use a code block or table.
|
||||
|
||||
---
|
||||
|
||||
## 7. Forbidden Section Types
|
||||
|
||||
These section names are not used anywhere in `references/`. Do not introduce them:
|
||||
|
||||
- `## Anti-patterns`
|
||||
- `## Best Practices`
|
||||
- `## Tips`
|
||||
- `## FAQ` (FAQ lives in `docs/faq.md`)
|
||||
- `## Why X`
|
||||
- `## Background` / `## Motivation`
|
||||
|
||||
If you have rules to communicate that would naturally land in one of these sections, integrate them into the relevant numbered section as a `**Forbidden — xxx**` block or a `> Note` line.
|
||||
|
||||
---
|
||||
|
||||
## 8. Cross-References
|
||||
|
||||
| Reference type | Format |
|
||||
|---|---|
|
||||
| Sibling reference file | `[`xxx`](./xxx.md)` |
|
||||
| Section in same file | `§N.M` (no link) |
|
||||
| Section in another file | `[`xxx`](./xxx.md) §N.M` |
|
||||
| Script doc | `[`xxx`](../scripts/docs/xxx.md)` |
|
||||
| Workflow | `[`xxx`](../workflows/xxx.md)` |
|
||||
|
||||
Always backtick-wrap the filename in the link text.
|
||||
|
||||
---
|
||||
|
||||
## 9. Annotations
|
||||
|
||||
| Symbol | Meaning |
|
||||
|---|---|
|
||||
| `🚧 **GATE**:` | Mandatory checkpoint before proceeding |
|
||||
| `⛔ **BLOCKING**:` | Must wait for explicit user confirmation |
|
||||
| `📝 **Template mapping**:` | Page-to-template declaration (Executor-specific) |
|
||||
| `> Note` blockquote | Edge case, fallback, or single-line context |
|
||||
|
||||
Use sparingly. If every paragraph has a symbol, none of them carry weight.
|
||||
|
||||
---
|
||||
|
||||
## 10. Checkpoint Output Format
|
||||
|
||||
Each phase ends with a fenced markdown block showing the agent's expected completion confirmation:
|
||||
|
||||
````markdown
|
||||
## ✅ {Phase Name} Complete
|
||||
|
||||
- [x] {evidence-driven assertion 1}
|
||||
- [x] {evidence-driven assertion 2}
|
||||
- [ ] **Next**: {next-phase pointer}
|
||||
````
|
||||
|
||||
Items are evidence-driven (`file exists at path X`, `status N is Generated`), not aspirational (`prompts are good`).
|
||||
|
||||
---
|
||||
|
||||
## 11. Forbidden Patterns Across the Whole Layer
|
||||
|
||||
- `> 重要：` / `> 注意：` Chinese exclamations (use `> Note` or omit)
|
||||
- Emoji as decoration in headings (✅ in checkpoint headings is the only sanctioned use)
|
||||
- Smiley face / sparkle / fire emoji
|
||||
- Footnotes (`[^1]`)
|
||||
- HTML in markdown body (`<details>`, `<br>`, etc.) — only the SVG embedding examples use real `<svg>`/`<image>` in code blocks, never as live markdown
|
||||
- "**Best practice**: ..." labels — use `**Hard rule**:` if it's required, or omit if it's not
|
||||
|
||||
---
|
||||
|
||||
## 12. When This Guide Conflicts With Existing Files
|
||||
|
||||
Existing files take precedence as ground truth. If a current `references/*.md` violates a rule here, decide whether to (a) update this guide to match the de facto convention, or (b) refactor that file. Don't silently apply a divergent style to one new file.
|
||||
|
||||
The canonical exemplars to model new files after:
|
||||
|
||||
| If you're writing... | Model after |
|
||||
|---|---|
|
||||
| A role reference (Image_X / Strategist-style) | [`image-searcher.md`](../skills/ppt-master/references/image-searcher.md), [`strategist.md`](../skills/ppt-master/references/strategist.md) |
|
||||
| A shared spec across roles | [`image-base.md`](../skills/ppt-master/references/image-base.md), [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md) |
|
||||
| A technical / format spec | [`canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md), [`svg-image-embedding.md`](../skills/ppt-master/references/svg-image-embedding.md), [`image-layout-spec.md`](../skills/ppt-master/references/image-layout-spec.md) |
|
||||
| Workflow runbook | [`workflows/verify-charts.md`](../skills/ppt-master/workflows/verify-charts.md) |
|
||||
299
agent/skills-disabled/ppt-master/docs/technical-design.md
Normal file
299
agent/skills-disabled/ppt-master/docs/technical-design.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Technical Design
|
||||
|
||||
[English](./technical-design.md) | [中文](./zh/technical-design.md)
|
||||
|
||||
---
|
||||
|
||||
## Design Philosophy — AI as Your Designer, Not Your Finisher
|
||||
|
||||
The generated PPTX is a **design draft**, not a finished product. Think of it like an architect's rendering: the AI handles visual design, layout, and content structure — delivering a high-quality starting point. For truly polished results, **expect to do your own finishing work** in PowerPoint: swapping shapes, refining charts, adjusting colors, replacing placeholder graphics with native objects. The goal is to eliminate 90% of the blank-page work, not to replace human judgment in the final mile. Don't expect one AI pass to do everything — that's not how good presentations are made.
|
||||
|
||||
**A tool's ceiling is your ceiling.** PPT Master amplifies the skills you already have — if you have a strong sense of design and content, it helps you execute faster. If you don't know what a great presentation looks like, the tool won't know either. The output quality is ultimately a reflection of your own taste and judgment.
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
User Input (PDF/DOCX/XLSX/URL/Markdown)
|
||||
↓
|
||||
[Source Content Conversion] → source_to_md/pdf_to_md.py / doc_to_md.py / excel_to_md.py / ppt_to_md.py / web_to_md.py
|
||||
↓
|
||||
[Create Project] → project_manager.py init <project_name> --format <format>
|
||||
↓
|
||||
[Template (optional)] — default: skip, proceed with free design
|
||||
User names a template: copy template files into the project
|
||||
Need a new global template: use /create-template workflow separately
|
||||
↓
|
||||
[Strategist] - Eight Confirmations & Design Specifications → design_spec.md + spec_lock.md
|
||||
↓
|
||||
[Image Acquisition] (when any row in the resource list needs AI generation or web search)
|
||||
↓
|
||||
[Executor]
|
||||
├── Visual construction: generate all SVG pages → svg_output/
|
||||
├── [Quality Check] svg_quality_checker.py (mandatory — must pass with 0 errors)
|
||||
└── Notes generation: complete speaker notes → notes/total.md
|
||||
↓
|
||||
[Chart calibration (optional)] → verify-charts workflow (for decks containing data charts)
|
||||
↓
|
||||
[Visual self-check (optional, opt-in)] → visual-review workflow (only when the user explicitly requests it)
|
||||
↓
|
||||
[Post-processing] → total_md_split.py (split notes) → finalize_svg.py → svg_to_pptx.py
|
||||
↓
|
||||
Output:
|
||||
exports/
|
||||
├── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here
|
||||
└── presentation_<timestamp>_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference (opt-in via --svg-snapshot)
|
||||
|
||||
# Always written in default-flow mode (no -o)
|
||||
backup/<timestamp>/
|
||||
└── svg_output/ ← Archived Executor SVG source (rerun finalize_svg → svg_to_pptx to rebuild)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Pipeline
|
||||
|
||||
**The pipeline: AI generates SVG → post-processing converts to DrawingML (PPTX).**
|
||||
|
||||
The full flow breaks into three stages:
|
||||
|
||||
**Stage 1 — Content Understanding & Design Planning**
|
||||
Source documents (PDF/DOCX/URL/Markdown) are converted to structured text. The Strategist role analyzes the content, plans the slide structure, and confirms the visual style, producing a complete design specification.
|
||||
|
||||
**Stage 2 — AI Visual Generation**
|
||||
The Executor role generates each slide as an SVG file. The output of this stage is a **design draft**, not a finished product.
|
||||
|
||||
**Stage 3 — Engineering Conversion**
|
||||
Post-processing scripts convert SVG to DrawingML. Every shape becomes a real native PowerPoint object — clickable, editable, recolorable — not an embedded image.
|
||||
|
||||
---
|
||||
|
||||
## Why SVG?
|
||||
|
||||
SVG sits at the center of this pipeline. The choice was made by elimination.
|
||||
|
||||
**Direct DrawingML generation** seems most direct — skip the intermediate format, have AI output PowerPoint's underlying XML. But DrawingML is extremely verbose; a simple rounded rectangle requires dozens of lines of nested XML. AI has far less training data for it than SVG, output is unreliable, and debugging is nearly impossible by eye.
|
||||
|
||||
**HTML/CSS** is one of the formats AI knows best. But HTML and PowerPoint have fundamentally different world views. HTML describes a *document* — headings, paragraphs, lists — where element positions are determined by content flow. PowerPoint describes a *canvas* — every element is an independent, absolutely positioned object with no flow and no context. This isn't just a layout calculation problem; it's a structural mismatch. Even if you solved the browser layout engine problem (what Chromium does in millions of lines of code), an HTML `<table>` still has no natural mapping to a set of independent shapes on a slide.
|
||||
|
||||
**WMF/EMF** (Windows Metafile) is Microsoft's own native vector graphics format and shares direct ancestry with DrawingML — the conversion loss would be minimal. But AI has essentially no training data for it, so this path is dead on arrival. Notably, even Microsoft's own format loses to SVG here.
|
||||
|
||||
**SVG as embedded images** is the simplest path — render each slide as an image and embed it. But this destroys editability entirely: shapes become pixels, text cannot be selected, colors cannot be changed. No different from a screenshot.
|
||||
|
||||
SVG wins because it shares the same world view as DrawingML: both are absolute-coordinate 2D vector graphics formats built around the same concepts:
|
||||
|
||||
| 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>` |
|
||||
|
||||
The conversion is a translation between two dialects of the same idea — not a format mismatch.
|
||||
|
||||
SVG is also the only format that simultaneously satisfies every role in the pipeline: **AI can reliably generate it, humans can preview and debug it in any browser, and scripts can precisely convert it** — all before a single line of DrawingML is written.
|
||||
|
||||
---
|
||||
|
||||
## Source Content Conversion
|
||||
|
||||
Source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized into Markdown before the pipeline starts — this is the source of truth Strategist reads from. Two design choices shape the converters:
|
||||
|
||||
**Native-Python first, external binaries as fallback.** Common formats are handled by pure-Python wheels; pandoc is only invoked for the long tail of niche formats. Forcing every user to install system binaries they may not have permission for is a usability tax that doesn't pay off when 95% of inputs are docx / pdf / html.
|
||||
|
||||
**TLS fingerprint impersonation for high-security sites.** Web fetching impersonates a Chrome TLS fingerprint by default. WeChat Official Accounts and several CDNs block Python's default `requests` handshake outright, and a single dependency that handles them is preferable to maintaining a parallel Node.js fetcher as the primary path.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure & Lifecycle
|
||||
|
||||
The non-obvious bit of the project layout is `import-sources`'s **asymmetric default**: files outside the repo are *copied* in (preserving the user's original), files inside the repo are *moved* in (so intermediate artifacts don't get committed by accident). The asymmetry tracks the natural risk profile — outside-repo files are typically user assets we shouldn't disturb, inside-repo files are typically transient artifacts that should be cleaned up. A single uniform default would get one or the other case wrong every time.
|
||||
|
||||
---
|
||||
|
||||
## Canvas Format System
|
||||
|
||||
PPT Master is not PPT-only — the same SVG → DrawingML pipeline produces square posters, 9:16 stories, A4 prints. Format-specific conventions (ratios, safe zones, brand areas) live in [`references/canvas-formats.md`](../skills/ppt-master/references/canvas-formats.md).
|
||||
|
||||
The architectural choice worth flagging: **viewBox is in pixels, not absolute units.** Pixel space makes layout reasoning unambiguous for the AI Executor (`x="100"` is unambiguously left + 100px) and inspectable in any browser. Conversion to PowerPoint's EMU happens once at export — picking pixels means the rest of the pipeline (Strategist, Executor, quality checker, post-processing) never thinks in EMU, which would be hostile both to AI generation and to human debugging.
|
||||
|
||||
---
|
||||
|
||||
## Template System & Optional Path
|
||||
|
||||
Templates are **opt-in, not default**. The default Strategist flow is free design — AI invents the visual system from the source content alone. The template path activates only on explicit user trigger.
|
||||
|
||||
**Why default to free design.** Templates are floors that easily become ceilings: they lock the deck into the template's visual idioms regardless of how the content actually wants to be presented. Free-design layouts derive structure from the source content rather than imposing it from a fixed grammar, so the visual rhythm tracks the content rather than fighting it. Constrained mode is genuinely better in narrow cases (brand-locked decks, strongly-typed scenarios like academic defense or government report), so it stays available — but the AI doesn't proactively reach for it; the user does.
|
||||
|
||||
**No proactive matching.** The AI does not suggest, hint at, or auto-map content to a template. Even when a deck looks like an obvious fit for an existing template, the AI stays silent and proceeds with free design unless the user has named the template. The reason is reliability over discoverability: matching content to templates is a judgment call that drifts as the library evolves, and a wrong "you might want X" pushes the user toward a commitment the AI cannot reliably make. Discoverability is handed to docs (the three `templates/{brands,layouts,decks}/README.md` per-kind indexes) and to the explicit query path ("what templates are available?"), not the runtime prompt.
|
||||
|
||||
**Layouts are opt-in; charts and icons are not.** The asymmetry isn't an inconsistency — *layout* is what locks visual idiom (the floor/ceiling problem above), while charts and icons are reusable primitives that don't impose deck-wide style. Same `templates/` directory, different role in the visual contract.
|
||||
|
||||
---
|
||||
|
||||
## Role System: Three Specialized Agents in a Single Pipeline
|
||||
|
||||
PPT Master uses **role switching within one main agent** rather than parallel sub-agents. The choice has three connected reasons:
|
||||
|
||||
**Why one agent, not parallel sub-agents.** Page design depends on the full upstream context — Strategist's color choices, the image resources that actually got acquired (vs failed and substituted), prior pages' visual rhythm. Sub-agents would start with a stale partial snapshot of that context and produce visually drifting decks. The same logic forbids batched page generation (e.g., five pages per turn): batching accelerates context compression and the deck's visual consistency degrades faster than the speed gain is worth.
|
||||
|
||||
**Why role-specialized references, not one mega prompt.** Strategist runs in "negotiate with user" mode (open-ended, conversational, willing to back up); Executor runs in "produce strict XML" mode (no improvisation, no missing attributes). Mixing both into one prompt forces the model to hold incompatible discipline in the same turn — every prompt-engineering pathology of mode-mixing shows up. Splitting into per-role files lets each role load only what it needs and discard the rest.
|
||||
|
||||
**Eight Confirmations as the only blocking gate.** Strategist ends with eight bundled user confirmations (canvas / page count / audience / style / color / icon / typography / image) presented as one blocking decision point. After confirmation, the pipeline runs to completion without further interrupts. The reason it's bundled and singular: design choices are correlated (color affects icon library affects typography), so resolving them together produces coherent decisions, while spreading confirmations across phases would invite contradictory user inputs and force backtracking.
|
||||
|
||||
**User-provided image analysis goes through metadata, not pixels.** When the user supplies images, Strategist runs an extractor that summarizes dimensions, EXIF orientation, dominant color, and subject — and reasons over that text. Opening image bytes directly is forbidden because the LLM doesn't need pixels to make layout decisions; it needs facts that fit on a page (aspect ratio for placement, color tone for palette compatibility, subject for slide assignment). Pixel reading would burn context for no decision-quality gain.
|
||||
|
||||
**Per-page spec_lock re-read** is the long-deck anti-drift mechanism — full rationale in § Spec Propagation below.
|
||||
|
||||
---
|
||||
|
||||
## Execution Discipline
|
||||
|
||||
The pipeline is enforced by an 8-rule set in [`SKILL.md` § Global Execution Discipline](../skills/ppt-master/SKILL.md) — that file is authoritative; the rules live there. They look bureaucratic but exist because LLMs default to "let me solve the whole problem in this turn", which is exactly the wrong shape for a serial pipeline where each step's output is bounded, checkpointed, and consumed by the next. The rules collectively close failure modes that surfaced repeatedly in practice: out-of-order execution, AI proxying user design decisions, cross-phase bundling, missing prerequisites, speculative pre-work, sub-agent context loss, page-batching drift, and long-deck color/font drift.
|
||||
|
||||
The Role Switching Protocol (mandated read of `references/<role>.md` before mode change) serves two reinforcing purposes: forcing fresh role instructions into context overrides drift from the previous mode, and the visible marker in the conversation transcript creates an audit trail so the user can see when the agent moved between modes — critical when reviewing why a particular decision was made.
|
||||
|
||||
---
|
||||
|
||||
## Spec Propagation: spec_lock.md as Execution Contract
|
||||
|
||||
The Strategist phase produces two artifacts that look redundant but serve different masters:
|
||||
|
||||
- `design_spec.md` — human-readable narrative; the "why" of the design (target audience, style objective, color rationale, page outline)
|
||||
- `spec_lock.md` — machine-readable execution contract; the "what" Executor must literally use (HEX colors, exact font family string, icon library choice, image resource list with status)
|
||||
|
||||
Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.
|
||||
|
||||
`update_spec.py` propagates a post-generation change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. For those, edit `spec_lock.md` and re-author the affected pages.
|
||||
|
||||
The tool refuses to back up: it relies on git for revert. Adding a backup mechanism would just duplicate git's job and create stale snapshots.
|
||||
|
||||
---
|
||||
|
||||
## Image Acquisition & Embedding
|
||||
|
||||
Two architectural decisions shape this phase:
|
||||
|
||||
**Provider-specific config keys, not a generic `IMAGE_API_KEY`.** Every backend takes its own `OPENAI_API_KEY` / `MINIMAX_API_KEY` / etc. and the active one is selected by an explicit `IMAGE_BACKEND=<name>`. A unified `IMAGE_API_KEY` field looks tidier on first glance but causes silent confusion when a user has multiple providers configured at once and isn't sure which one is active — the kind of fault that surfaces only as "image generation gives weird results" with no clear failure point. Forcing per-provider keys makes "which backend am I using" a config-readable fact, not an inference.
|
||||
|
||||
**Permissive-by-default license filter, with strict mode for credit-incompatible layouts.** Web image search defaults to allowing CC BY / CC BY-SA images with inline attribution — most slides have visual room for a credit element. `--strict-no-attribution` is the escape hatch for full-bleed hero images and tight composition where there's no place to put a credit without breaking the design. Non-commercial (CC BY-NC*) and no-derivatives (CC BY-ND*) licenses are auto-rejected because the typical PPT Master output is shared in commercial or modified contexts; a permissive default with that floor is the failure mode users actually want.
|
||||
|
||||
**External refs during development, two divergent embedding strategies for delivery.** While editing in `svg_output/`, images are external file references — fast iteration, single-source-of-truth replacement. The two delivery artifacts then diverge: `svg_final/` Base64-inlines (a folder of self-contained SVGs that IDE preview, browser, and the preview pptx can all open without missing the bitmap dependencies); native pptx instead copies bitmaps into the PPTX media folder and uses `<a:srcRect>` to express the cropping. The split exists because Base64 inside DrawingML works but bloats file size 3-4×, while file-referenced bitmaps are PowerPoint's native idiom for which `<a:srcRect>` is the canonical crop expression — wrong tool in either direction would cost editability or file size.
|
||||
|
||||
**Three-dimensional AI image lock at Strategist time.** When the deck includes AI-generated images, Strategist decides three orthogonal dimensions up front — `rendering` (visual style family: vector-illustration / editorial / 3d-isometric / sketch-notes / …), `palette` (how the deck's HEX values are *used*: proportion + role + temperament), `type` (per-image internal composition: background / hero / framework / comparison / …). The first two are deck-wide and written into `spec_lock.md`; Image_Generator then assembles every per-image prompt from the single locked rendering + palette plus a per-image type, instead of re-deciding style per image. Without this, every image gets its own style drift and the deck reads as a stack of unrelated illustrations. This is the visual-cohesion dual of `spec_lock`'s typography/color anti-drift mechanism, just one level upstream of pixels. Strategist surfaces ≥3 candidate `rendering × palette` combinations to the user during the Eight Confirmations — never auto-locking a single combination silently, because the choice has far-reaching deck-wide consequences and the user's taste is the only oracle for it.
|
||||
|
||||
---
|
||||
|
||||
## Image-Text Layout: Primary Structures + Modifier Layers
|
||||
|
||||
The catalog of *how an image is placed on a slide* (full vocabulary in [`references/image-layout-patterns.md`](../skills/ppt-master/references/image-layout-patterns.md)) splits 72 numbered techniques into two layers that compose freely:
|
||||
|
||||
- **Primary Structures** (container layouts / image-as-canvas + native overlay / multi-image compositions) — the page's bones. One or more per page; cross-Primary combinations like *side-by-side comparison + image-as-canvas annotation* are legitimate.
|
||||
- **Modifier Layers** (non-rectangular clips / overlays & masks / texture / special techniques) — finish. Any number per page, stacked on top of the Primary.
|
||||
|
||||
**Why explicit composition, not "one primary per page".** The AI failure mode this catalog fights isn't *over-combining*, it's *under-using*: defaulting every image page to bare `#2 left-third` or `#48 side-by-side` with no Modifier on top, producing visually flat, "AI-default" layouts. The earlier rule "one primary layout per page; modifiers compose" sounded principled but reinforced the under-use — the AI read it as permission to skip the Modifier layer entirely. The current framing flips the encouragement: combining is normal, single-Primary-no-Modifier is the case that needs justification.
|
||||
|
||||
**Why the layers are physically separated, not just tagged.** Patterns are reorganized so all Primary structures appear first, then all Modifiers — a Strategist or Executor reading the file once internalizes the two-layer mental model from the table of contents alone. Numbers are stable identifiers (`#38` is still image-as-canvas + annotation cards regardless of where it sits in the file), so existing references across `spec_lock.md`, `design_spec.md §VIII`, executor logs, and historical examples all keep resolving.
|
||||
|
||||
**Why composition flows through Strategist's resource list, not just Executor's improvisation.** The `Layout pattern` column in `§VIII Image Resource List` accepts a `#<id> + #<id> ...` expression — Primary id plus optional Modifier ids — so the composition is declared *before* SVG generation, audited by `svg_quality_checker`, and survives session re-entry. Pushing composition onto Executor alone would lose it on context compression in long decks; encoding it in the spec_lock-adjacent resource list makes it a piece of the design contract.
|
||||
|
||||
**Why true hard constraints stay upstream.** Cross-cutting technical constraints (`<clipPath>` only on `<image>`, `fill-opacity` instead of `rgba()`, no `<mask>`, alpha-effect routing) live exclusively in [`shared-standards.md`](../skills/ppt-master/references/shared-standards.md). The layout patterns file points at them with one-line references rather than restating — so when a constraint relaxes (e.g., a new DrawingML feature becomes reliable), only one file changes, and a stale duplicate in patterns can't silently keep enforcing the old rule.
|
||||
|
||||
---
|
||||
|
||||
## SVG Constraints: Banned Features and Conditional Allowances
|
||||
|
||||
PowerPoint's DrawingML is a strict subset of what SVG can express. The Executor operates inside an empirically-grown blacklist (mask, style/class, `@font-face`, foreignObject, symbol+use, textPath, animate*, script/iframe …) plus narrow conditional allowances for `marker-start`/`marker-end` and image-only `clip-path`. The authoritative list and exact per-feature constraints — including the substitute-effect routing table for `<mask>` (gradient overlays, clipPath, filter shadow, source-image bake-in) — live in [`references/shared-standards.md`](../skills/ppt-master/references/shared-standards.md).
|
||||
|
||||
The architectural reasons worth knowing here:
|
||||
|
||||
- **Why a blacklist, not a whitelist.** SVG is a wide spec; enumerating allowed features would force constant maintenance as the Executor finds new useful constructs. The blacklist captures the narrow set whose semantics have no DrawingML representation, leaving everything else implicitly available.
|
||||
- **Why empirical, not derived from spec.** The list grew from real PPT export failures, not from reading the OOXML spec. Several features (e.g., `<mask>`) are theoretically expressible in DrawingML but practically unreliable across PowerPoint versions; the blacklist reflects the actually-shippable subset.
|
||||
- **XML well-formedness traps.** Two cross-cutting gotchas independent of DrawingML: typography must use raw Unicode (`—`, `→`, `©`, NBSP) since HTML named entities (`—`) are XML-illegal in SVG, and reserved XML chars (`& < >`) must be entity-escaped or `R&D` will abort the export. These bite often enough to flag at the architecture level.
|
||||
- **The blacklist runs before post-processing.** `svg_quality_checker.py` enforces it on `svg_output/`; post-processing rewrites SVG and would mask source-level violations. Fixes are always re-authoring in the Executor — there is intentionally no auto-fix mode (see Quality Gate).
|
||||
|
||||
---
|
||||
|
||||
## Quality Gate
|
||||
|
||||
**Why a checker exists at all.** SVG generated by an LLM is not deterministic — banned features creep in over long decks and only surface when `svg_to_pptx` aborts mid-conversion or PowerPoint silently drops elements. The checker turns "PowerPoint export failed at page 14" into "the Executor used `<style>` on page 14, regenerate it" — an order-of-magnitude faster diagnosis loop, which is what makes long decks economically feasible to iterate on.
|
||||
|
||||
**Why placed before post-processing, not after.** Post-processing rewrites SVG (icon embedding, image inlining), which would mask source-level violations. Reading `svg_output/` directly catches the Executor's actual output, before any cleanup that might paper over a bug.
|
||||
|
||||
**Severity model: errors block, warnings don't, and there is intentionally no auto-fix.** Errors require the Executor to re-author the offending page in context — a banned `<style>` element isn't a mechanical patch, because the Executor used it for a reason and the substitute (e.g., inline attributes) needs the same design intent re-applied. Auto-fix would silently lose that intent and ship a worse-looking page.
|
||||
|
||||
**Why chart coordinate verification hangs off the same gate.** Chart pages have geometric correctness requirements (bar heights / pie sweep angles / axis tick positions) that aren't structural and aren't caught by SVG validity rules. The natural place to catch them is the same gate where the AI is asked to revisit its output — bundling the cognitive context "look at what you generated and fix it" into one phase, rather than splitting structural and geometric review into separate review rounds.
|
||||
|
||||
---
|
||||
|
||||
## Post-Processing Pipeline
|
||||
|
||||
> Why each artifact and module exists in the engineering conversion stage, and which workflows would break if you delete it. Read this before considering any simplification of `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py`.
|
||||
|
||||
### Four artifacts, four workflows
|
||||
|
||||
The post-processing stage produces four artifacts. Each one serves a workflow that nothing else in the pipeline can replace.
|
||||
|
||||
| Artifact | Workflow it serves | Why nothing else replaces it |
|
||||
| --- | --- | --- |
|
||||
| `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived |
|
||||
| `svg_final/` | IDE inline preview (VSCode/Cursor open `.svg` directly), browser open of a single page | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs |
|
||||
| `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint |
|
||||
| `exports/<name>_<ts>_svg.pptx` (preview, opt-in via `--svg-snapshot`) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute. Off by default — live preview already provides the SVG visual reference for dev/diagnostic work |
|
||||
| `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |
|
||||
|
||||
### The `svg_finalize/` package has TWO consumers
|
||||
|
||||
This is the key insight that's easy to miss when reading the code. The same modules under `skills/ppt-master/scripts/svg_finalize/` are used in two places, for two different products.
|
||||
|
||||
**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run. `svg_final/` then feeds IDE preview and the preview pptx.
|
||||
|
||||
**Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop), but DrawingML can't handle two SVG features inline, so the converter calls `svg_finalize` modules **in memory**:
|
||||
|
||||
| In-memory call site | Module reused | Why native pptx needs it |
|
||||
| --- | --- | --- |
|
||||
| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML doesn't recognize `<use data-icon="...">`; without expansion every icon silently drops |
|
||||
| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML text runs cannot reposition mid-paragraph; a dy-stacked block of `<tspan>`s would otherwise collapse onto one baseline, and an x-anchored tspan would render in the wrong column |
|
||||
|
||||
### Per-module consumer table
|
||||
|
||||
| Module | Disk consumer | Memory consumer | Delete impact |
|
||||
| --- | --- | --- | --- |
|
||||
| `embed_icons.py` | `finalize_svg` `embed-icons` step | `svg_to_pptx/use_expander.py` | native pptx loses all icons + `svg_final/` not self-contained |
|
||||
| `flatten_tspan.py` | `finalize_svg` `flatten-text` step | `svg_to_pptx/tspan_flattener.py` | **native pptx multi-line `dy`-stacked text collapses to one line** |
|
||||
| `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses image embedding → IDE preview / preview pptx have no images |
|
||||
| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | imported by `align_embed_images.py` | — | `align_embed_images` `ImportError`, full chain broken |
|
||||
| `svg_rect_to_path.py` | `finalize_svg` `fix-rounded` step | — | only PowerPoint's manual "Convert to Shape" loses rounded corners; browsers / IDE / PowerPoint's own SVG renderer all OK without it |
|
||||
|
||||
---
|
||||
|
||||
## Native PPTX Conversion Internals
|
||||
|
||||
**Why per-element dispatch, not whole-file translation.** SVG's hierarchical model maps cleanly onto DrawingML's group / shape / picture types — there's no need for a holistic optimizer that re-plans the slide. Each shape kind gets its own narrow translator, which keeps each translator simple enough to debug and unit-test in isolation. The output quality of a slide is the sum of independent local conversions; that property is fragile under whole-file translation but robust under element dispatch.
|
||||
|
||||
**Why Office compatibility mode is on by default.** PowerPoint versions before 2019 can't render SVG natively. The converter generates a per-slide PNG fallback and embeds it alongside the native shapes — newer Office still shows editable shapes, older Office falls back to the PNG. The default-on choice trades a moderate file-size cost for not silently shipping unopenable decks to users on legacy installs; the escape hatch exists for users who know they're on a modern stack and want the smaller file.
|
||||
|
||||
---
|
||||
|
||||
## Animation & Transition Model
|
||||
|
||||
The interesting design choice is the animation **anchor**, not the effect list.
|
||||
|
||||
**Why anchor entrance animations on top-level `<g>` groups.** PowerPoint's animation timeline is shape-keyed — each animated object needs a stable shape ID. Animating individual primitives would produce 30+ separately-flying-in atoms per slide (a kinetic mess), while animating only the slide as a whole loses visual storytelling. Top-level groups are the natural granularity: Executor is required to use `<g id="...">` to mark logical content blocks, and these blocks are exactly the units a viewer reads as "one thing arriving" — animation matches the existing logical structure rather than imposing a new one.
|
||||
|
||||
**Why page chrome is auto-skipped.** Groups named `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` represent the static slide frame, not content; flying them in would feel jarring (the page itself materializing every transition) and is virtually never what the user wants. Filtering by id-token is brittle in principle but reliable in practice because the token vocabulary is small and the Executor controls naming.
|
||||
|
||||
**Why object-level animation uses a sidecar, not SVG attributes.** SVG remains the static visual source of truth. Custom PPTX animation is export policy, so per-object overrides live in optional `animations.json` keyed by slide stem and top-level group id. This avoids polluting SVG with PowerPoint-specific metadata while still letting users tune order, effect, delay, and duration when the default global animation is not enough.
|
||||
|
||||
**Why recorded narration drives auto-advance from clip duration.** When narration is embedded, the deck targets video export — and a video has no presenter to click. Setting per-slide auto-advance timings to the audio clip's actual duration produces a deck PowerPoint exports cleanly to MP4 without manual timing work. Picking any other duration source (estimated reading speed, fixed per-slide) breaks the audio-visual sync.
|
||||
|
||||
**Why recorded narration rejects on-click object animation.** PowerPoint can record click timings during a real rehearsal, but PPT Master does not synthesize object-level click events. The recorded narration path writes page-level audio and slide auto-advance timings only, so click-driven object reveals would leave the export dependent on extra manual PowerPoint rehearsal. For narrated decks, object entrances must be click-free (`after-previous` or `with-previous`).
|
||||
|
||||
---
|
||||
|
||||
## Standalone Workflows
|
||||
|
||||
Six capabilities (`create-template`, `verify-charts`, `customize-animations`, `live-preview`, `generate-audio`, `visual-review`) live as standalone workflows rather than pipeline steps. Each is sparsely triggered — per-template, per-chart-deck, per-animation-tuning request, per-complaint, per-video-export, per explicit visual-review request — not per-deck. Folding any into the default pipeline would either run unnecessary steps for the majority of users (added latency and failure surface) or force a one-size-fits-all narrowing of the main flow. Keeping them opt-in lets the deck-generation pipeline stay tight and predictable while making the capability available when its trigger condition fires; each `workflows/<name>.md` is self-contained and loaded on demand, so paying the prompt-context cost is also opt-in.
|
||||
294
agent/skills-disabled/ppt-master/docs/templates-architecture.md
Normal file
294
agent/skills-disabled/ppt-master/docs/templates-architecture.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Template Architecture: Brand / Layout / Deck
|
||||
|
||||
> This is the **architecture alignment document**. It defines the three template kinds at the data-model layer, the field sets of each `design_spec.md`, and the multi-path fusion + conflict resolution rules. Audience: contributors and AI workflows; answers "what should / shouldn't a template directory contain; how do they combine when multiple are supplied".
|
||||
>
|
||||
> For user-facing usage (how to trigger, how to pick), see [`templates-guide.md`](./templates-guide.md); not repeated here.
|
||||
|
||||
---
|
||||
|
||||
## 1. The three kinds
|
||||
|
||||
| Kind | Physical dir | What it writes | What it does NOT write | Originating workflow |
|
||||
|---|---|---|---|---|
|
||||
| **Brand** | `templates/brands/<id>/` | Identity segment only: color / typography / logo / voice / icon style | No canvas, page structure, SVG roster | `workflows/create-brand.md` |
|
||||
| **Layout** | `templates/layouts/<id>/` | Structure segment only: canvas / page structure / page types / SVG roster | No brand identity (no logo, no locked brand color) | `workflows/create-template.md` (layout branch) |
|
||||
| **Deck** | `templates/decks/<id>/` | All segments: identity + structure + middle (template overview) | — | `workflows/create-template.md` (deck branch, default) |
|
||||
|
||||
The three are **parallel reference bundles**. The physical directory and the frontmatter `kind` field correspond one-to-one:
|
||||
|
||||
```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
|
||||
...
|
||||
---
|
||||
```
|
||||
|
||||
### Segment partition
|
||||
|
||||
To make multi-path fusion override cleanly, every field belongs to a named segment. **Default fusion granularity is whole-segment replacement**:
|
||||
|
||||
| Segment | Sections it contains | Override owner |
|
||||
|---|---|---|
|
||||
| **Identity** | Color Scheme / Typography / Logo / Voice & Tone / Icon Style | brand |
|
||||
| **Structure** | Canvas Specification / Page Structure / Page Types / SVG Roster | layout |
|
||||
| **Middle** | Template Overview (use cases / design intent / page rhythm narrative) | deck only; brand / layout don't write this |
|
||||
|
||||
### Why Deck is its own kind
|
||||
|
||||
A deck is the **full replica** of an existing PPT — the SVG geometry was drawn for that color palette and those typefaces, and identity + structure have been combat-tested together in the source deck. Its value is "validated cohesion", which a free layout + brand combo can't always reach.
|
||||
|
||||
But a deck is **not "an immutable replica"** — it's "a replica that serves as the default base, overridable by explicitly-supplied brand / layout". This gives users maximum freedom: by default you get a complete solution; when needed, swap identity or structure explicitly.
|
||||
|
||||
---
|
||||
|
||||
## 2. `design_spec.md` schema per kind
|
||||
|
||||
The schema only specifies the **required** fields. "Don't write what isn't necessary" — if a field isn't listed here, don't add it.
|
||||
|
||||
### Brand schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
brand_id: <slug>
|
||||
kind: brand
|
||||
summary: <one-line use cases, including primary color>
|
||||
primary_color: "<HEX>"
|
||||
---
|
||||
```
|
||||
|
||||
**Body sections** (full identity segment)
|
||||
|
||||
| § | Title | Required fields |
|
||||
|---|---|---|
|
||||
| I | Brand Overview | Brand Name / Use Cases / Tone |
|
||||
| II | Color Scheme | role / HEX / provenance (`fact` official truth \| `approx` derived) / notes |
|
||||
| III | Typography | role / family / weight |
|
||||
| IV | Logo | file / form / usage + clearspace and lockup rules |
|
||||
| V | Voice & Tone | formality / person / emoji / abbreviation policy |
|
||||
| VI | Icon Style | preference (stroke / filled / duotone …) + recommended libraries |
|
||||
|
||||
**Forbidden**: canvas viewBox, page types, SVG roster — those are layout's responsibility.
|
||||
|
||||
### Layout schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout_id: <slug>
|
||||
kind: layout
|
||||
summary: <one-line use cases>
|
||||
canvas_format: <ppt169 | ppt43 | a4 | ...>
|
||||
page_count: <N>
|
||||
page_types: [<cover, toc, chapter, content, ending, ...>]
|
||||
---
|
||||
```
|
||||
|
||||
**Body sections** (full structure segment + Template Overview)
|
||||
|
||||
| § | Title | Required fields |
|
||||
|---|---|---|
|
||||
| I | Template Overview | Use Cases / Design Intent / Page Rhythm suggestions |
|
||||
| II | Canvas Specification | Format / Dimensions / viewBox / Margins / Content Area |
|
||||
| III | Page Structure | General Layout Grid / Decorative DNA / Navigation rules |
|
||||
| IV | Page Types | Per-page role (cover / toc / chapter / content / ending …) + variant descriptions |
|
||||
| V | SVG Page Roster | File list + purpose, each file mapped to a III/IV role |
|
||||
|
||||
**Forbidden**: brand logo, brand voice & tone, official-truth color (`provenance: fact`) — those belong to brand. Layouts have no fallback color or typography by definition: identity segments are not written here; color and typography are decided live in Strategist's Eight Confirmations.
|
||||
|
||||
### Deck schema
|
||||
|
||||
**Frontmatter**
|
||||
|
||||
```yaml
|
||||
---
|
||||
deck_id: <slug>
|
||||
kind: deck
|
||||
summary: <one-line use cases>
|
||||
canvas_format: <ppt169 | ...>
|
||||
page_count: <N>
|
||||
primary_color: "<HEX>"
|
||||
---
|
||||
```
|
||||
|
||||
**Body sections** (full identity + full structure + middle)
|
||||
|
||||
| § | Title | Segment |
|
||||
|---|---|---|
|
||||
| I | Template Overview | Middle |
|
||||
| II | Canvas Specification | Structure |
|
||||
| III | Color Scheme (with provenance) | Identity |
|
||||
| IV | Typography | Identity |
|
||||
| V | Logo | Identity |
|
||||
| VI | Voice & Tone | Identity |
|
||||
| VII | Icon Style | Identity |
|
||||
| VIII | Page Structure | Structure |
|
||||
| IX | Page Types | Structure |
|
||||
| X | SVG Page Roster | Structure |
|
||||
|
||||
> Deck is the union of all identity + structure fields, with no optional sections. This keeps fusion's segment-level replacement granularity uniform.
|
||||
|
||||
---
|
||||
|
||||
## 3. The three index files
|
||||
|
||||
Each index maps one-to-one with its physical directory; fields are trimmed to what Strategist actually needs to pick (following the "meta + summary" pattern from `charts_index.json`, but preserving structured metadata that helps selection).
|
||||
|
||||
### `templates/brands/brands_index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"<brand_id>": {
|
||||
"summary": "Anthropic brand identity — AI/LLM tech talks, developer conferences",
|
||||
"primary_color": "#D97757"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Keep `primary_color` — Strategist needs the dominant color at first glance when picking a brand
|
||||
- Drop `keywords` — summary already carries the English equivalents; AI matches via natural language (same approach as the charts library)
|
||||
|
||||
### `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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Add `canvas_format` / `page_count` / `page_types` — Strategist needs to judge "can this skeleton hold my deck?" quickly
|
||||
- No `primary_color` — layouts have no identity
|
||||
|
||||
### `templates/decks/decks_index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"<deck_id>": {
|
||||
"summary": "China Merchants Bank transaction banking deck",
|
||||
"canvas_format": "ppt169",
|
||||
"page_count": 5,
|
||||
"primary_color": "#XXXXXX"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- Includes `primary_color` (decks carry identity) + structural metadata
|
||||
- Does not expand `page_types` — decks share the same page-type set as layouts; redundant to record
|
||||
|
||||
---
|
||||
|
||||
## 4. Multi-path fusion and conflict resolution
|
||||
|
||||
### Override priority (implicit dispatch)
|
||||
|
||||
When the user supplies a set of paths in their initial message, Step 3 fuses them into `<project>/templates/design_spec.md` per the table below:
|
||||
|
||||
| User paths | Fusion behavior |
|
||||
|---|---|
|
||||
| (none) | Skip Step 3, free design |
|
||||
| brand only | Copy brand wholesale; structure stays free design |
|
||||
| layout only | Copy layout wholesale; identity stays free design (Strategist e/f/g confirmations decide) |
|
||||
| deck only | Copy deck wholesale |
|
||||
| brand + layout | brand provides identity, layout provides structure (follows existing SKILL.md fusion table) |
|
||||
| brand + deck | brand overrides deck's identity segment at segment level; structure + middle come from deck |
|
||||
| layout + deck | layout overrides deck's structure segment at segment level; identity + middle come from deck |
|
||||
| brand + layout + deck | brand overrides identity + layout overrides structure + deck provides middle; deck's original identity/structure segments are discarded wholesale |
|
||||
|
||||
### Whole-segment replacement (default granularity)
|
||||
|
||||
Fusion defaults to **whole-segment integer replacement** — e.g. on deck + brand, the entire Color Scheme / Typography / Logo / Voice / Icon Style five sections come from brand. **No implicit field-level mixing** (you will never get "primary from brand, secondary from deck").
|
||||
|
||||
Field-level micro-adjustment goes through the existing Strategist Eight Confirmations path — the user says in chat "use the anthropic brand but change primary to #FF0000", and Strategist adjusts in confirmations e/g. Step 3 fusion does not add field-level syntax.
|
||||
|
||||
### Same-kind multiple paths = git-style conflict resolution
|
||||
|
||||
User supplies `brands/anthropic` + `brands/google` (or any same-kind permutation):
|
||||
|
||||
```
|
||||
AI: You supplied two brands. Detected segment-level conflicts:
|
||||
- Color Scheme (Anthropic orange-red vs Google multi-color)
|
||||
- Typography (Styrene/AnthropicSans vs GoogleSans/Roboto)
|
||||
- Logo (Anthropic mark vs Google mark)
|
||||
- Voice & Tone (restrained vs friendly)
|
||||
- Icon Style (stroke vs filled)
|
||||
|
||||
(a) all from Anthropic / (b) all from Google / (c) pick per segment?
|
||||
```
|
||||
|
||||
Rules:
|
||||
- No implicit ordering — every cross-source segment difference is reported as a conflict
|
||||
- Only when the user picks `(c)` does AI walk through each segment
|
||||
- Field-level conflict resolution is out of scope — segment-level only
|
||||
- `layout × 2`, `deck × 2`, `brand × 2` handled the same way
|
||||
- Max two of any one kind (more than that — ask the user to converge in chat first)
|
||||
|
||||
### Provenance
|
||||
|
||||
When fusion happens (any multi-path case), the resulting `<project>/templates/design_spec.md` carries a provenance block immediately under its H1:
|
||||
|
||||
```markdown
|
||||
> **Fused from:**
|
||||
> - deck: `templates/decks/招商银行/` (base)
|
||||
> - brand: `templates/brands/anthropic/` (identity override)
|
||||
> - layout: `templates/layouts/academic_defense/` (structure override)
|
||||
> - conflicts resolved: Color Scheme from anthropic (user picked a)
|
||||
```
|
||||
|
||||
This lets both AI and humans trace which segment came from where.
|
||||
|
||||
---
|
||||
|
||||
## 5. Relationship with SKILL.md Step 3
|
||||
|
||||
**Trigger rule unchanged** — still "explicit directory path only" (see [[feedback-template-explicit-path-only]]). The `kind` field decides **how AI handles the path after triggering**:
|
||||
|
||||
| User path's `kind` | Step 3 action (per-kind branch) |
|
||||
|---|---|
|
||||
| `kind: brand` | Copy design_spec + logos + asset subdirs to `<project>/templates/` |
|
||||
| `kind: layout` | Copy design_spec + SVG roster + assets to `<project>/templates/` |
|
||||
| `kind: deck` | Copy design_spec + SVG roster + logos + all assets to `<project>/templates/` |
|
||||
| Multi-path | Fuse into one `design_spec.md` per the table above; merge SVG / logo files from each source |
|
||||
| Same-kind multiple | Run the "git-style conflict resolution" prompt above to determine the merge |
|
||||
|
||||
### Strategist Eight Confirmations narrowing per kind
|
||||
|
||||
When a deck path is supplied, the user already has a complete solution; the Eight Confirmations narrow to "target audience / page count / outline / tone tweaks" — deck-content fields. Other fields reuse the locked values directly. The narrowing rules live in `references/strategist.md` and `spec_lock_reference.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Relationship with workflows
|
||||
|
||||
| Workflow | Produces |
|
||||
|---|---|
|
||||
| `workflows/create-brand.md` | brand directory (identity-only), reverse-engineered from brand assets |
|
||||
| `workflows/create-template.md` | layout or deck directory, internal kind branch: default to deck (user supplies an existing PPT; extract full identity + structure); when the user explicitly says "structure only / drop the brand color", go to the layout branch |
|
||||
|
||||
After production, the frontmatter `kind` field determines whether the file lands under `templates/brands/` / `templates/layouts/` / `templates/decks/`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Non-goals (rejection list paired with this framing)
|
||||
|
||||
- **No field-level override syntax in the fusion layer** — field-level adjustment uses the existing Strategist Eight Confirmations path
|
||||
- **No batch conflict resolution for three or more of the same kind** — ask the user to narrow it down in chat first
|
||||
- **No bilingual name mapping table** — templates are named in their brand / scenario's native language (Chinese templates use Chinese names; English templates use snake_case); no forced unification
|
||||
240
agent/skills-disabled/ppt-master/docs/templates-guide.md
Normal file
240
agent/skills-disabled/ppt-master/docs/templates-guide.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Templates Guide: Use, Derive, and Boundaries
|
||||
|
||||
A PPT Master "template" is a **structure + style** preset bundle: a set of page layout SVGs (cover / chapter / TOC / content / ending and their variants), a `design_spec.md` design specification, and matching assets (logos, backgrounds, decorative imagery). It is **not** a PowerPoint Slide Master, and **not** just a color palette — it is a reusable page-skeleton bundle the workflow can invoke directly.
|
||||
|
||||
This guide answers three questions:
|
||||
|
||||
1. [How do I use an existing template?](#1-use-an-existing-template)
|
||||
2. [How do I turn someone else's PPT — or my own brand — into a template? (the focus)](#2-derive-a-new-template-the-focus)
|
||||
3. [What are the limits of templates?](#3-template-boundaries)
|
||||
|
||||
---
|
||||
|
||||
## 1. Use an existing template
|
||||
|
||||
### How to trigger
|
||||
|
||||
The workflow **defaults to free design** — it will not ask whether you want a template and will not proactively suggest one. Templates are opt-in by **explicit directory path** only: name the path in your initial message.
|
||||
|
||||
### How to enter the template flow
|
||||
|
||||
Send a path to a template directory in your initial message. Anywhere in the sentence is fine; the path just has to be unambiguous:
|
||||
|
||||
> "use this template: `skills/ppt-master/templates/layouts/academic_defense/`" ✅
|
||||
> "用这个模板做汇报：`projects/last_deck/template/`" ✅
|
||||
> "做一份产品介绍，模板用 `/Users/me/Desktop/our_brand_v3/`" ✅
|
||||
|
||||
The AI copies that directory's SVGs, `design_spec.md`, and assets into your project, then proceeds to the Strategist phase. The path can point to anywhere — the built-in library under `skills/ppt-master/templates/layouts/`, a previous project's `template/` folder, or any other location on disk.
|
||||
|
||||
### What does NOT trigger the template flow
|
||||
|
||||
- **A bare template name without a path**: "use the academic_defense template" / "用 招商银行 模板" / "做一份 pixel_retro 模板的答辩" → free design. The AI does not look the name up. You must give a path.
|
||||
- **Style descriptions**: "McKinsey style" / "Google style" / "麦肯锡那种" / "极简风" / "Keynote 风" → free design. The descriptive words flow into Strategist as a style brief, but no template is copied.
|
||||
- **Vague intent**: "想用个模板" / "I want a template" with no path → free design.
|
||||
|
||||
This is intentional — the AI never makes a fuzzy / interpretive judgment about whether your wording maps to a template, and never resolves a name to a path on your behalf. If you want a template, give the path.
|
||||
|
||||
To browse what's available in the built-in library, ask "what templates are available?" — the AI lists names and paths from the discovery index. Listing alone does not enter the template flow; you still need to send back a path to trigger Step 3.
|
||||
|
||||
### Template catalog
|
||||
|
||||
Templates are organized into three kinds, each in its own directory:
|
||||
|
||||
- [`templates/brands/README.md`](../skills/ppt-master/templates/brands/README.md) — identity-only presets (color / typography / logo / voice / icon style), no SVG pages; Anthropic, Google
|
||||
- [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md) — structure-only patterns (canvas / page structure / page types / SVG roster), no identity; academic_defense, government_blue/red, ai_ops, medical_university, pixel_retro, psychology_attachment
|
||||
- [`templates/decks/README.md`](../skills/ppt-master/templates/decks/README.md) — full-PPT replicas (identity + structure + middle segments); 招商银行, 中国电建_*, 中汽研_*, 重庆大学, 中国电信
|
||||
|
||||
Full data model + fusion / conflict-resolution rules: [`docs/zh/templates-architecture.md`](./zh/templates-architecture.md) (Chinese only for now).
|
||||
|
||||
### Free design vs template
|
||||
|
||||
Free design is **not** "no style" — the AI designs a fresh visual system **for that specific deck** based on its content. A template **reuses an already-defined structure and style**. Both involve real design work; the difference is whether the style is improvised or preset.
|
||||
|
||||
> Rule of thumb: clear content direction + strong brand or scenario constraints (consulting reports, government briefings, defenses) → use a template. Essay-like content where atmosphere matters more (magazine, documentary narrative) → free design usually works better.
|
||||
|
||||
### Styles are not templates
|
||||
|
||||
A **style** is a description ("minimalist" / "Keynote-style" / "magazine 风") — a few words you type in chat. A **template** is a copy-and-paste asset bundle (SVGs + design_spec + assets) the workflow installs into your project when you give it an explicit directory path.
|
||||
|
||||
| | Template | Style |
|
||||
|---|---|---|
|
||||
| How invoked | Explicit directory path in your message | Free-form description in your message |
|
||||
| What happens | Files copied into project; layouts inherit from template SVGs | Words flow to Strategist; color / typography / tone proposed in Eight Confirmations |
|
||||
| Locked values | Yes — values come from the template's `design_spec.md` | No — Strategist invents values that fit the deck |
|
||||
| Best for | Brand-locked decks; scenarios with strong visual conventions | When you have a feel in mind but no specific brand commitment |
|
||||
|
||||
A style mention may resemble a template name (e.g., "academic style" sounds like the `academic_defense/` template directory), but they go through different machinery — a template requires a real path the AI can copy from, a style mention is interpretive language. Similar words, different paths in the most literal sense.
|
||||
|
||||
### Common styles you can describe
|
||||
|
||||
Three axes, freely combinable ("dark tech + minimalist" or "magazine + neo-Chinese"):
|
||||
|
||||
**Aesthetic direction**
|
||||
|
||||
| Style | One-line characterization |
|
||||
|---|---|
|
||||
| **Minimalist / 极简风** | High whitespace, 2-3 colors, single focal point per page |
|
||||
| **Information-dense / 信息密集** | McKinsey-style structured tables, high density, conclusion-first |
|
||||
| **Keynote-style** | Single-page hero text, premium whitespace, Apple-feel |
|
||||
| **Editorial / 杂志风** | Large hero images, asymmetric layouts, strong typography contrast |
|
||||
| **Editorial illustration / 文艺手绘** | Warm tones, hand-drawn feel, zine-like |
|
||||
|
||||
**Scenario / Industry**
|
||||
|
||||
| Style | One-line characterization |
|
||||
|---|---|
|
||||
| **Business consulting** | Data-driven, restrained, blue / grey palette |
|
||||
| **Academic defense** | Strict hierarchy, citation-heavy, clean |
|
||||
| **Government briefing** | Red / blue, formal, symmetric |
|
||||
| **Product launch** | Visually bold, marketing-driven, single hero per page |
|
||||
| **Education / training** | Clear hierarchy, friendly tone, bright palette |
|
||||
| **Pitch deck / BP** | Narrative-driven, conclusion-bold |
|
||||
|
||||
**Visual character / atmosphere**
|
||||
|
||||
| Style | One-line characterization |
|
||||
|---|---|
|
||||
| **Dark tech / 暗色科技** | Dark backgrounds, neon accents, futuristic |
|
||||
| **Pixel retro** | 8-bit, scanlines, gaming aesthetic |
|
||||
| **Neo-Chinese / 新中式** | Restrained traditional motifs, ink / vermilion |
|
||||
| **Scandinavian / 北欧极简** | Light, natural, restrained |
|
||||
| **Memphis / pop** | High-saturation blocks, geometric, 80s |
|
||||
| **Cyberpunk / vaporwave** | Neon purple-pink, grids, dreamlike |
|
||||
|
||||
When you describe a style, the AI doesn't pick a template — it interprets the words and lands them in Layer 2 of confirmation `d` (Style Objective) inside Strategist's Eight Confirmations, which then drives e (color), f (icon), g (typography), and h (image). You confirm or refine. If the style you want happens to match one of our built-in templates (e.g., `academic_defense` / `pixel_retro` / `psychology_attachment`), you have a choice: send the template's directory path for locked values, or describe the style for AI-interpreted values that adapt to your deck content.
|
||||
|
||||
---
|
||||
|
||||
## 2. Derive a new template (the focus)
|
||||
|
||||
Turn a PPT you like, a brand guideline, or an existing PPTX file into a PPT Master template. This is the core of this guide.
|
||||
|
||||
### Entry point: the `/create-template` workflow
|
||||
|
||||
Full spec in [`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md). This section is the user-facing short version — in your IDE, just say:
|
||||
|
||||
```
|
||||
Please use the /create-template workflow to generate a new template based on the reference materials below.
|
||||
```
|
||||
|
||||
The workflow will then **mandatorily** confirm a template brief with you before doing anything (this gate cannot be skipped).
|
||||
|
||||
### Step 1 — Prepare reference material
|
||||
|
||||
**Strongly recommended: hand over the original `.pptx` file.** The current PPTX import pipeline achieves near-high-fidelity reconstruction — the workflow uses [`pptx_template_import.py`](../skills/ppt-master/scripts/pptx_template_import.py) to read OOXML directly, extracting theme colors, fonts, per-master themes, master/layout structure, placeholder metadata, and reusable image assets. It emits a layered `svg/` view as the machine-readable template source plus a self-contained `svg-flat/` view for visual preview, then hands the package to Template_Designer which rebuilds clean, maintainable SVGs. Covers, chapter dividers, and decoration-heavy pages all reproduce reliably. This is by far the most dependable derivation path today.
|
||||
|
||||
You can also design from scratch from a brand guideline: provide a logo, primary color HEX, fonts, tone description, and a few mood references — the AI will design the page skeletons on the spot. This suits brands that don't yet have a finished PPT, only a VI manual.
|
||||
|
||||
> **Fallback when no source PPTX exists**: a screenshot set (`cover.png` / `chapter.png` / `content.png` / `closing.png`, ...) still works, but fidelity drops noticeably — decoration, fonts, and layout details all rely on the AI's visual inference. Use `.pptx` whenever you can. Screenshots are better used as annotation alongside a PPTX ("this is the look I want") than as the sole reference.
|
||||
|
||||
### Step 2 — The template brief (mandatory confirmation)
|
||||
|
||||
The workflow does not silently infer values — before generation it lists these items and waits for your reply:
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| **Template ID** | Directory / index key. Prefer ASCII slug like `acme_consulting`; non-ASCII names work but must be filesystem-safe |
|
||||
| **Display name** | Human-readable name for documentation |
|
||||
| **Category** | One of `brand` / `general` / `scenario` / `government` / `special` |
|
||||
| **Use cases** | Annual report / consulting / defense / government briefing / ... |
|
||||
| **Tone summary** | One line, e.g. "modern, restrained, data-driven" |
|
||||
| **Theme mode** | Light / dark / gradient / ... |
|
||||
| **Canvas format** | Default `ppt169` (16:9); specify other formats up front |
|
||||
| **Replication mode** | `standard` (default 5-page roster) / `fidelity` (one variant per visually distinct cluster from a `.pptx` source — count is driven by the source) / `mirror` (1:1 verbatim copy of every source slide, no abstraction, no placeholders) — `fidelity` and `mirror` both require a `.pptx` reference |
|
||||
| **Visual fidelity** | (required for `standard` / `fidelity` when a reference exists) `literal` (reproduce original geometry / decoration / sprite crops as-is) or `adapted` (use reference for tone and structure but allow design evolution). Cover / chapter / ending are usually `literal`. **Not asked for `mirror`** — mirror is implicitly literal |
|
||||
| **Keywords** | 3–5 tags for index lookup |
|
||||
| Theme color / design notes / asset list | Optional — can be auto-extracted from the source |
|
||||
|
||||
After confirmation the workflow echoes the finalized brief and emits the marker `[TEMPLATE_BRIEF_CONFIRMED]`. Subsequent steps only run after that marker. **This is a hard gate — no brief, no generation.**
|
||||
|
||||
> Why so strict? Because a template is a library asset that future projects will reuse. Getting it right once is far cheaper than regenerating after the fact.
|
||||
|
||||
### Step 3 — `standard`, `fidelity`, or `mirror`?
|
||||
|
||||
This is the most easily confused decision when deriving a template.
|
||||
|
||||
| | **standard** | **fidelity** | **mirror** |
|
||||
|---|---|---|---|
|
||||
| Output pages | 5 (cover / chapter / TOC / content / ending) | one variant per visually distinct cluster — count driven by the source | one page per source slide (1:1) |
|
||||
| Abstraction | High — clean, reusable skeleton | Medium — clusters preserved with cleanup | **Zero** — verbatim copy |
|
||||
| Placeholders inserted? | Yes (`{{TITLE}}`, `{{CONTENT_AREA}}`, …) | Yes | **No** — Executor edits text in place against the project content |
|
||||
| Best for | You want "tone + basic skeleton" to generate brand-new decks later | The source PPTX itself is a customized layout library and every variant matters | Someone else's polished deck is great as-is, you want every page available as a reference |
|
||||
| Typical use | Building a base brand template | Replicating a 20-variant government briefing layout set | Reusing a 50-page McKinsey-style deck verbatim |
|
||||
| Requires PPTX source? | No | **Yes** | **Yes** |
|
||||
| Decoration complexity | Usually simpler | Must preserve sprite-sheet (cropped image) structure | Inherits whatever the source had, byte-for-byte |
|
||||
|
||||
**About sprite sheets**: PPTX-exported assets are often a single large image referenced from multiple slides, each cropping a different region via nested `<svg viewBox=...>` wrappers. In `fidelity` and `mirror` modes this nesting must be preserved — you cannot flatten it to a bare `<image>`, or the crop is lost and the page misaligns. The workflow validates this automatically.
|
||||
|
||||
**How mirror is consumed**: a mirror template carries no `{{}}` placeholders, so the Strategist picks one mirror page per project page (using `design_spec.md §V Page Roster` descriptions to match content), and the Executor copies that mirror SVG and edits the text in place against the project content — preserving all decoration, sprite crops, and geometry. The library asset stays 100% verbatim; per-project edits live in `projects/<project>/svg_output/`.
|
||||
|
||||
### Step 4 — Registration and discovery
|
||||
|
||||
After generation, the workflow:
|
||||
|
||||
1. Runs [`svg_quality_checker.py`](../skills/ppt-master/scripts/svg_quality_checker.py) (hard gate — no entry without passing)
|
||||
2. Registers the template ID in [`layouts_index.json`](../skills/ppt-master/templates/layouts/layouts_index.json)
|
||||
3. Syncs the table in [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md)
|
||||
|
||||
Registration makes the template **discoverable** — when someone asks "what templates are available?", the AI lists it from the index. To use it in a new project, follow the SKILL.md Step 3 rule: name its directory path in your first message, e.g. `use this template: skills/ppt-master/templates/layouts/<your_template_id>/`.
|
||||
|
||||
### What a derived template looks like
|
||||
|
||||
```
|
||||
skills/ppt-master/templates/layouts/<your_template_id>/
|
||||
├── design_spec.md # design spec; §VI lists every page
|
||||
├── 01_cover.svg
|
||||
├── 02_chapter.svg
|
||||
├── 02_toc.svg # optional
|
||||
├── 03_content.svg
|
||||
├── 03a_content_two_col.svg # variant in fidelity mode
|
||||
├── 04_ending.svg
|
||||
├── logo.png # brand asset
|
||||
└── bg_pattern.jpg
|
||||
```
|
||||
|
||||
`standard` and `fidelity` SVGs use a unified placeholder convention (`{{TITLE}}`, `{{CHAPTER_TITLE}}`, `{{PAGE_TITLE}}`, `{{CONTENT_AREA}}`, ...) that the Strategist phase fills with content.
|
||||
|
||||
A `mirror` template emits one SVG per source slide, named by source order, with **no** placeholders inside:
|
||||
|
||||
```
|
||||
skills/ppt-master/templates/layouts/<your_template_id>/
|
||||
├── design_spec.md # frontmatter sets replication_mode: mirror; §V Page Roster describes every page in detail
|
||||
├── 001_cover.svg
|
||||
├── 002_toc.svg
|
||||
├── 003_content.svg
|
||||
├── 004_content.svg
|
||||
├── ...
|
||||
├── 049_content.svg
|
||||
├── 050_ending.svg
|
||||
└── *.png / *.jpg
|
||||
```
|
||||
|
||||
### Project-level customization vs global template
|
||||
|
||||
Don't confuse the two:
|
||||
|
||||
- **Derive a new template** = enter the global library at `skills/ppt-master/templates/layouts/`, available to all future projects
|
||||
- **Project-level customization** = edit only the SVGs under `projects/<project>/templates/` for this one deck; not registered, no impact elsewhere
|
||||
|
||||
`/create-template` is for the former. For the latter, just edit the SVGs in the project directory directly — no workflow needed.
|
||||
|
||||
---
|
||||
|
||||
## 3. Template boundaries
|
||||
|
||||
Common misconceptions to avoid:
|
||||
|
||||
- **A template is not a PowerPoint Slide Master.** PPT Master outputs native DrawingML shapes and does not depend on the PowerPoint master mechanism. The template is an SVG skeleton, translated to PPTX shapes at export time
|
||||
- **A template is not a "style skin".** It bundles structure (which blocks per page, how information is hierarchized) with style (colors, fonts, decoration). Trying to swap "skin" without structure tends to put the information architecture and the visuals at odds
|
||||
- **A template does not make content decisions for you.** The Strategist still decides per-page which layout to use and whether to extend a variant. Templates offer candidates, not predetermined results
|
||||
- **`fidelity` mode is not pixel-perfect copying.** Even with `literal` fidelity, the AI still strips noise and unnecessary repetition — geometry stays, redundancy goes
|
||||
- **`mirror` mode IS pixel-perfect copying — but it inherits the source's import limitations.** Charts, SmartArt, OLE objects, and EMF / WMF media that don't round-trip through `pptx_template_import.py` will fail the same way in mirror. The flat SVG is the source of truth; if it looks broken in `<workspace>/svg-flat/`, the mirror template will too
|
||||
|
||||
---
|
||||
|
||||
## Related docs
|
||||
|
||||
- [`workflows/create-template.md`](../skills/ppt-master/workflows/create-template.md) — full workflow spec (AI-facing)
|
||||
- [`templates/layouts/README.md`](../skills/ppt-master/templates/layouts/README.md) — current template catalog
|
||||
- [`references/template-designer.md`](../skills/ppt-master/references/template-designer.md) — Template_Designer role definition and SVG technical constraints
|
||||
- [FAQ: how do I create a custom template?](./faq.md) — short FAQ version
|
||||
88
agent/skills-disabled/ppt-master/docs/why-ppt-master.md
Normal file
88
agent/skills-disabled/ppt-master/docs/why-ppt-master.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Why PPT Master
|
||||
|
||||
[English](./why-ppt-master.md) | [中文](./zh/why-ppt-master.md)
|
||||
|
||||
---
|
||||
|
||||
There are dozens of AI presentation tools. This page explains what PPT Master does differently — and where it's not the right choice.
|
||||
|
||||
I'm [Hugo He](https://www.hehugo.com/), an investment & finance professional who builds presentations every day. PPT Master is an open-source tool I've spent extensive time refining — because I'm its most demanding user.
|
||||
|
||||
## 1. Real PowerPoint Output — Not Images, Not Web Screenshots
|
||||
|
||||
**This is the core differentiator.**
|
||||
|
||||
Most AI presentation tools take one of three approaches, each with a hard limitation:
|
||||
|
||||
- **Embed images** → Many tools render each slide as a flat image inside the PPTX. It looks polished, but text can't be selected, colors can't be changed, and scaling loses quality — it's a screenshot, not a presentation.
|
||||
- **HTML/CSS rendering** → Gamma, Tome, and similar tools look great in the browser, but HTML describes document flow while PowerPoint is a canvas. Exporting to PPTX inevitably breaks layouts and flattens elements.
|
||||
- **python-pptx / direct generation** → ChatGPT and similar tools build PPTX programmatically. Elements are editable, but AI lacks the training data to produce complex designs — the result is basic text boxes and bullet lists.
|
||||
|
||||
PPT Master takes a fourth path — **AI generates SVG, then scripts convert SVG to DrawingML**. This works because SVG and DrawingML are fundamentally the same kind of thing — both are absolute-coordinate 2D vector formats where rectangles, paths, gradients, and shadows map one-to-one. The conversion is a dialect translation, not a format mismatch.
|
||||
|
||||
In the exported PPTX, every shape, text box, gradient, and shadow is a native PowerPoint object. Click anything, edit it — just like you built it by hand.
|
||||
|
||||
> See [Technical Design](./technical-design.md) for the full rationale.
|
||||
|
||||
---
|
||||
|
||||
## 2. Transparent Cost — You Pay Your AI Provider, Not Another Subscription
|
||||
|
||||
PPT Master itself is free and open source. The only cost is your own AI model usage.
|
||||
|
||||
AI tools across the industry are shifting to usage-based billing — you pay for what you actually consume. PPT Master works with this model naturally: there's no separate PPT subscription, no proprietary credits, no per-seat fee for a presentation platform on top of what you're already paying for AI.
|
||||
|
||||
For comparison, Gamma subscriptions run $8–20/month, Beautiful.ai $12–45/month — regardless of how much you actually use them. PPT Master adds zero cost on top of your existing AI spend.
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Privacy — 100% Local
|
||||
|
||||
Your files never leave your machine. Source documents are converted locally, SVGs are generated locally, PPTX is exported locally. The only external communication is between you and your AI editor — no different from how you normally use it.
|
||||
|
||||
No third-party server stores your source documents or output. This matters for finance, government, and any organization with data residency requirements.
|
||||
|
||||
---
|
||||
|
||||
## 4. Fully Open — No Lock-in on Editors or Models
|
||||
|
||||
Your workflow shouldn't be held hostage by any single company. Today you depend on their platform; tomorrow they raise prices, change the rules, or shut down — and everything you've built on top of it is gone. That's not what open source should look like.
|
||||
|
||||
PPT Master is a framework, not a plugin for a specific IDE. **On editors:** Claude Code, VS Code Copilot, Cursor, Codebuddy IDE, and whatever comes next — they all work. **On models:** Claude produces the best results, but GPT, Gemini, Kimi, MiniMax, and others can all drive PPT Master — the difference is in layout precision, and as models improve, these gaps will narrow.
|
||||
|
||||
The choice is yours. PPT Master doesn't make that decision for you.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Consulting-Grade Design System
|
||||
|
||||
Three built-in styles: General (training, tech talks), Consultant (business reports, data visualization), and Consultant Top (MBB level — investment memos, strategic plans, government briefings).
|
||||
|
||||
The [examples/](../examples/) directory contains all example projects, spanning government fiscal analysis, AI architecture design, Zen philosophy, pixel-art gaming, editorial reports, and more.
|
||||
|
||||
### Full Source-Document Input
|
||||
|
||||
Feed it almost anything: PDF, DOCX, PPTX, EPUB, HTML, LaTeX, RST, web URLs, WeChat articles, Markdown, or plain text. Most SaaS tools only accept prompts or limited file uploads.
|
||||
|
||||
### Multi-Format Output
|
||||
|
||||
Output is not limited to standard 16:9 and 4:3 slide ratios. Xiaohongshu 3:4, WeChat/Instagram 1:1, vertical Story 9:16, A4 print — same pipeline, just specify the format.
|
||||
|
||||
---
|
||||
|
||||
## Where PPT Master Is Not the Right Choice
|
||||
|
||||
Being honest about limitations:
|
||||
|
||||
| Limitation | Detail |
|
||||
|---|---|
|
||||
| **Setup required** | Install Python, clone repo, configure AI editor. Not a "open browser and go" experience. |
|
||||
| **Slower generation** | 10–20 min for a 10-page deck (serial page-by-page for cross-slide consistency). SaaS tools take seconds. |
|
||||
| **No collaboration** | Local files, no real-time co-editing, no share links. |
|
||||
| **No full freeform canvas** | The browser live preview supports direct edits — select to change text/color/font/size, drag or arrow-key to reposition, with undo — plus click-to-annotate for AI rewrites. What it isn't is a full Gamma/Canva-style freeform canvas: no on-canvas resize handles, and re-exporting to PPTX stays a chat step. |
|
||||
|
||||
**If you want zero-setup, instant slides in a browser** — Gamma and Canva are excellent choices.
|
||||
|
||||
**If you want native editability, predictable cost, local data, and no lock-in** — that's what PPT Master is built for.
|
||||
154
agent/skills-disabled/ppt-master/docs/windows-installation.md
Normal file
154
agent/skills-disabled/ppt-master/docs/windows-installation.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# Windows Installation Guide
|
||||
|
||||
This guide walks you through installing PPT Master on Windows step by step. Follow along and you'll have a working setup in under 10 minutes.
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Install Python (Required)
|
||||
|
||||
Python is the only hard requirement.
|
||||
|
||||
1. Go to **[python.org/downloads](https://www.python.org/downloads/)** and download the latest **Python 3.10+** installer.
|
||||
|
||||
2. **⚠️ CRITICAL: Check "Add python.exe to PATH"** during installation — this is the single most common mistake on Windows. Skipping this will break every step that follows.
|
||||
|
||||
|
||||
|
||||
3. After installation, open **PowerShell** (search "PowerShell" in Start menu) and verify:
|
||||
|
||||
```powershell
|
||||
python --version
|
||||
```
|
||||
|
||||
You should see `Python 3.12.x` or similar. If you see "Python was not found" or it opens the Microsoft Store, see [Troubleshooting](#python-was-not-found-or-opens-microsoft-store) below.
|
||||
|
||||
> **💡 Tip**: Python installed via Anaconda or Miniconda works too — just make sure `python --version` shows 3.10+.
|
||||
|
||||
---
|
||||
|
||||
## Step 2 — Download the Project
|
||||
|
||||
**Option A — Download ZIP** (easiest):
|
||||
|
||||
1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)
|
||||
2. Click the green **Code** button → **Download ZIP**
|
||||
3. Unzip to `C:\Users\YourName\ppt-master`
|
||||
|
||||
**Option B — Git Clone** (requires [Git](https://git-scm.com/downloads)):
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/hugohe3/ppt-master.git
|
||||
cd ppt-master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3 — Install Dependencies
|
||||
|
||||
```powershell
|
||||
cd C:\Users\YourName\ppt-master # ← adjust to your actual path
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
> If `pip` is not recognized, try `python -m pip install -r requirements.txt`.
|
||||
|
||||
Wait for it to finish. You should see `Successfully installed ...` at the end.
|
||||
|
||||
---
|
||||
|
||||
## Step 4 — Verify Your Setup
|
||||
|
||||
```powershell
|
||||
python -c "import pptx; import fitz; print('All core dependencies OK')"
|
||||
```
|
||||
|
||||
✅ Output: `All core dependencies OK` → you're good.
|
||||
|
||||
❌ Error → see [Troubleshooting](#troubleshooting) below.
|
||||
|
||||
---
|
||||
|
||||
## Step 5 — Run a Minimal Example
|
||||
|
||||
Open your AI editor (Cursor, VS Code + Copilot, etc.), open the `ppt-master` folder, and type in the chat:
|
||||
|
||||
```
|
||||
Please create a simple 3-page test PPT with a cover, one content page, and a closing page. Topic: "Hello World".
|
||||
```
|
||||
|
||||
If a `.pptx` file appears in `exports/` that opens in PowerPoint — **you're done.**
|
||||
|
||||
---
|
||||
|
||||
## Step 6 — Optional Enhancements (most users can skip this)
|
||||
|
||||
With Python and `requirements.txt` installed, you already have everything needed to generate presentations. The items below are **edge-case fallbacks and enhancements** — install only if you hit the specific scenario.
|
||||
|
||||
| Enhancement | Install only if… | How to install | Verify |
|
||||
|-------------|-----------------|----------------|--------|
|
||||
| **CairoSVG** — higher quality PNG fallbacks | You want crisper PNG fallbacks for Office versions that don't render SVG natively. `svglib` (already installed) is fine for most cases. | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |
|
||||
| **Pandoc** — legacy document formats | You need to convert `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`/`.html`/`.epub`/`.ipynb` work natively in Python. | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `python` was not found or opens Microsoft Store
|
||||
|
||||
**Cause**: Python isn't in your system PATH.
|
||||
|
||||
**Fix 1** — Re-run the Python installer → **Modify** → check **"Add Python to environment variables"**.
|
||||
|
||||
**Fix 2** — Manually add to PATH:
|
||||
1. Run `where python` in PowerShell first to find the actual path (e.g. `C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe`)
|
||||
2. Search "Environment Variables" in Start menu
|
||||
3. Find `Path` → **Edit** → add the **directory** from step 1 and its `Scripts` subfolder:
|
||||
```
|
||||
C:\Users\YourName\AppData\Local\Programs\Python\Python312
|
||||
C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts
|
||||
```
|
||||
4. Click OK, then **restart PowerShell**
|
||||
|
||||
**Fix 3** — Try `python3` or `py` instead.
|
||||
|
||||
### A `python3` command fails (exit 49 / opens Microsoft Store)
|
||||
|
||||
The python.org installer ships `python.exe` but not `python3.exe`. **Just replace `python3` with `python` in the command** (the AI agent usually switches to `python` and continues on its own too).
|
||||
|
||||
### `pip install` fails with permission errors
|
||||
|
||||
```powershell
|
||||
pip install --user -r requirements.txt
|
||||
```
|
||||
|
||||
Or run PowerShell as Administrator.
|
||||
|
||||
### `pip install` fails due to network issues
|
||||
|
||||
```powershell
|
||||
pip install -r requirements.txt --proxy http://your-proxy:port
|
||||
```
|
||||
|
||||
### `ModuleNotFoundError`
|
||||
|
||||
`pip` installed to a different Python. Use `python -m pip install -r requirements.txt` to match.
|
||||
|
||||
### `import fitz` fails
|
||||
|
||||
1. Upgrade pip: `python -m pip install --upgrade pip`
|
||||
2. Pre-built wheel: `pip install PyMuPDF --only-binary :all:`
|
||||
3. Still failing → install [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
||||
|
||||
### PowerShell says "running scripts is disabled"
|
||||
|
||||
```powershell
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Still stuck?
|
||||
|
||||
- 📖 [FAQ](./faq.md)
|
||||
- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — include your Python version, Windows version, and full error message
|
||||
- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
|
||||
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)
|
||||
41
agent/skills-disabled/ppt-master/examples/README.md
Normal file
41
agent/skills-disabled/ppt-master/examples/README.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# PPT Master Example Projects
|
||||
|
||||
> Curated example projects generated by PPT Master.
|
||||
|
||||
**[Browse all examples online](https://hugohe3.github.io/ppt-master/)** — the canonical catalog, powered by [`examples.json`](./examples.json). The JSON file is the source of truth for project metadata, tags, and slide listings; this README only documents folder structure.
|
||||
|
||||
## Project Structure
|
||||
|
||||
Each example follows this layout:
|
||||
|
||||
```
|
||||
<project_name>/
|
||||
├── design_spec.md # Design specification (human-readable)
|
||||
├── spec_lock.md # Machine-readable execution contract
|
||||
├── images/ # Image assets
|
||||
├── notes/ # Speaker notes per page
|
||||
├── svg_output/ # Original SVGs (with placeholders)
|
||||
└── svg_final/ # Final SVGs (icons + images embedded)
|
||||
```
|
||||
|
||||
> Examples deliberately omit `sources/` (original PDFs / DOCX) and `exports/` (PPTX output) to keep repo size small. Real projects under `projects/` will have both.
|
||||
|
||||
## Preview locally
|
||||
|
||||
```bash
|
||||
python -m http.server --directory examples/<project_name>/svg_final 8000
|
||||
# visit http://localhost:8000
|
||||
```
|
||||
|
||||
Or open any `svg_final/*.svg` directly in a browser / VS Code.
|
||||
|
||||
## Contributing
|
||||
|
||||
New examples need (1) the standard structure above and (2) an entry in [`examples.json`](./examples.json) (`projects[]` array + bumped `stats`). SVGs should pass `python3 skills/ppt-master/scripts/svg_quality_checker.py`.
|
||||
|
||||
## Related
|
||||
|
||||
- [Quick Start](../README.md)
|
||||
- [Workflow](../skills/ppt-master/SKILL.md)
|
||||
- [Chart Templates](../skills/ppt-master/templates/charts/)
|
||||
- [Icon Library](../skills/ppt-master/templates/icons/)
|
||||
1831
agent/skills-disabled/ppt-master/examples/examples.json
Normal file
1831
agent/skills-disabled/ppt-master/examples/examples.json
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,13 @@
|
||||
# attention_is_all_you_need
|
||||
|
||||
- Canvas format: ppt169
|
||||
- Created: 20260524
|
||||
- Source: Vaswani et al. 2017, Attention Is All You Need
|
||||
|
||||
## Directories
|
||||
|
||||
- `svg_output/`: raw SVG output
|
||||
- `svg_final/`: finalized SVG output
|
||||
- `images/`: presentation assets
|
||||
- `notes/`: speaker notes
|
||||
- `exports/`: generated PPTX files
|
||||
@@ -0,0 +1,164 @@
|
||||
{
|
||||
"version": 1,
|
||||
"defaults": {
|
||||
"transition": { "effect": "fade", "duration": 0.35 },
|
||||
"animation": { "effect": "auto", "duration": 0.38, "stagger": 0.16, "trigger": "after-previous" }
|
||||
},
|
||||
"slides": {
|
||||
"01_cover": {
|
||||
"transition": { "effect": "fade", "duration": 0.55 },
|
||||
"animation": { "effect": "fade", "duration": 0.6, "stagger": 0.26, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"cover-marks": { "effect": "appear", "order": 1, "duration": 0.2 },
|
||||
"cover-title": { "order": 2, "duration": 0.7 },
|
||||
"cover-subtitle": { "order": 3, "duration": 0.5 },
|
||||
"cover-takeaway": { "order": 4, "delay": 0.35, "duration": 0.55 }
|
||||
}
|
||||
},
|
||||
"02_why_it_matters": {
|
||||
"transition": { "effect": "fade", "duration": 0.3 },
|
||||
"animation": { "effect": "auto", "duration": 0.34, "stagger": 0.12, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"kpi-bleu-ende": { "effect": "zoom", "order": 1, "duration": 0.42 },
|
||||
"kpi-bleu-enfr": { "effect": "zoom", "order": 2, "duration": 0.42 },
|
||||
"kpi-training": { "effect": "zoom", "order": 3, "duration": 0.38 },
|
||||
"kpi-no-rnn-cnn": { "effect": "zoom", "order": 4, "duration": 0.38 },
|
||||
"takeaway-band": { "effect": "fade", "order": 5, "delay": 0.22, "duration": 0.5 }
|
||||
}
|
||||
},
|
||||
"03_sequence_evolution": {
|
||||
"transition": { "effect": "push", "duration": 0.42 },
|
||||
"animation": { "effect": "fade", "duration": 0.48, "stagger": 0.22, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"bottom-takeaway": { "effect": "fly", "order": 1, "delay": 0.25, "duration": 0.55 }
|
||||
}
|
||||
},
|
||||
"04_rnn_cnn_limits": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.34, "stagger": 0.13, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"pillar-sequential": { "effect": "fly", "order": 1 },
|
||||
"pillar-pathlen": { "effect": "fly", "order": 2 },
|
||||
"pillar-memory": { "effect": "fly", "order": 3 },
|
||||
"rnn-visual": { "effect": "wipe", "order": 4, "delay": 0.2, "duration": 0.5 }
|
||||
}
|
||||
},
|
||||
"05_architecture_overview": {
|
||||
"transition": { "effect": "wipe", "duration": 0.35 },
|
||||
"animation": { "effect": "auto", "duration": 0.38, "stagger": 0.14, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"paper-figure": { "effect": "zoom", "order": 1, "duration": 0.55 },
|
||||
"legend-1": { "effect": "fade", "order": 2 },
|
||||
"legend-2": { "effect": "fade", "order": 3 },
|
||||
"legend-3": { "effect": "fade", "order": 4 },
|
||||
"legend-4": { "effect": "fade", "order": 5 },
|
||||
"legend-5": { "effect": "fade", "order": 6 },
|
||||
"takeaway": { "effect": "fade", "order": 7, "delay": 0.22, "duration": 0.48 }
|
||||
}
|
||||
},
|
||||
"06_encoder_decoder": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.36, "stagger": 0.16, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"card-encoder": { "effect": "fly", "order": 1, "duration": 0.42 },
|
||||
"card-decoder": { "effect": "fly", "order": 2, "duration": 0.42 }
|
||||
}
|
||||
},
|
||||
"07_scaled_dot_product": {
|
||||
"transition": { "effect": "wipe", "duration": 0.32 },
|
||||
"animation": { "effect": "fade", "duration": 0.38, "stagger": 0.16, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"formula-band": { "effect": "zoom", "order": 1, "duration": 0.5 },
|
||||
"flow-diagram": { "effect": "wipe", "order": 2, "duration": 0.5 },
|
||||
"explanation": { "effect": "fade", "order": 3, "delay": 0.2, "duration": 0.42 }
|
||||
}
|
||||
},
|
||||
"08_multi_head_attention": {
|
||||
"transition": { "effect": "wipe", "duration": 0.32 },
|
||||
"animation": { "effect": "fade", "duration": 0.38, "stagger": 0.15, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"formula-band": { "effect": "zoom", "order": 1, "duration": 0.48 },
|
||||
"paper-figure": { "effect": "wipe", "order": 2, "duration": 0.52 },
|
||||
"explanation": { "effect": "fade", "order": 3, "delay": 0.18, "duration": 0.42 }
|
||||
}
|
||||
},
|
||||
"09_three_uses": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.34, "stagger": 0.14, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"pillar-enc-self": { "effect": "fly", "order": 1 },
|
||||
"pillar-dec-masked": { "effect": "fly", "order": 2 },
|
||||
"pillar-cross": { "effect": "fly", "order": 3 }
|
||||
}
|
||||
},
|
||||
"10_ffn_residual_layernorm": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.34, "stagger": 0.12, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"sublayer-visual": { "effect": "zoom", "order": 1, "duration": 0.48 },
|
||||
"parent-frame": { "effect": "fade", "order": 2, "duration": 0.32 },
|
||||
"card-ffn": { "effect": "fly", "order": 3 },
|
||||
"card-residual": { "effect": "fly", "order": 4 },
|
||||
"card-layernorm": { "effect": "fly", "order": 5 },
|
||||
"combined-flow": { "effect": "wipe", "order": 6, "delay": 0.18, "duration": 0.5 }
|
||||
}
|
||||
},
|
||||
"11_positional_encoding": {
|
||||
"transition": { "effect": "fade", "duration": 0.42 },
|
||||
"animation": { "effect": "fade", "duration": 0.48, "stagger": 0.2, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"title": { "order": 1, "duration": 0.55 },
|
||||
"formula-band": { "effect": "zoom", "order": 2, "duration": 0.55 },
|
||||
"explanation": { "order": 3, "delay": 0.22, "duration": 0.5 }
|
||||
}
|
||||
},
|
||||
"12_complexity_table": {
|
||||
"transition": { "effect": "fade", "duration": 0.25 },
|
||||
"animation": { "effect": "auto", "duration": 0.32, "stagger": 0.12, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"table": { "effect": "wipe", "order": 1, "duration": 0.45 },
|
||||
"takeaway": { "effect": "fade", "order": 2, "delay": 0.18, "duration": 0.42 }
|
||||
}
|
||||
},
|
||||
"13_training_setup": {
|
||||
"transition": { "effect": "fade", "duration": 0.25 },
|
||||
"animation": { "effect": "auto", "duration": 0.32, "stagger": 0.11, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"card-hardware": { "effect": "fly", "order": 1 },
|
||||
"card-time": { "effect": "fly", "order": 2 },
|
||||
"card-optimizer": { "effect": "fly", "order": 3 },
|
||||
"card-regularization": { "effect": "fly", "order": 4 }
|
||||
}
|
||||
},
|
||||
"14_results": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.34, "stagger": 0.14, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"table": { "effect": "wipe", "order": 1, "duration": 0.46 },
|
||||
"takeaway": { "effect": "fade", "order": 2, "delay": 0.2, "duration": 0.46 }
|
||||
}
|
||||
},
|
||||
"15_ablations": {
|
||||
"transition": { "effect": "fade", "duration": 0.28 },
|
||||
"animation": { "effect": "auto", "duration": 0.3, "stagger": 0.1, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"track": { "effect": "wipe", "order": 1, "duration": 0.4 },
|
||||
"item-1": { "effect": "fade", "order": 2 },
|
||||
"item-2": { "effect": "fade", "order": 3 },
|
||||
"item-3": { "effect": "fade", "order": 4 },
|
||||
"item-4": { "effect": "fade", "order": 5 },
|
||||
"item-5": { "effect": "fade", "order": 6 }
|
||||
}
|
||||
},
|
||||
"16_conclusion": {
|
||||
"transition": { "effect": "fade", "duration": 0.55 },
|
||||
"animation": { "effect": "fade", "duration": 0.58, "stagger": 0.24, "trigger": "after-previous" },
|
||||
"groups": {
|
||||
"closing-marks": { "effect": "appear", "order": 1, "duration": 0.2 },
|
||||
"lineage": { "effect": "zoom", "order": 2, "duration": 0.62 },
|
||||
"closing-title": { "order": 3, "delay": 0.25, "duration": 0.7 },
|
||||
"closing-caption": { "order": 4, "delay": 0.28, "duration": 0.55 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,451 @@
|
||||
# attention_is_all_you_need — Design Spec
|
||||
|
||||
> Paper-deep-read deck for the seminal Transformer paper (Vaswani et al., 2017). Pipeline output of PPT Master; truth-of-execution lives in `spec_lock.md`.
|
||||
|
||||
## I. Project Information
|
||||
|
||||
| Item | Value |
|
||||
| ---- | ----- |
|
||||
| **Project Name** | attention_is_all_you_need |
|
||||
| **Canvas Format** | PPT 16:9 (1280×720) |
|
||||
| **Page Count** | 16 |
|
||||
| **Design Style** | B) General Consulting + academic minimalist tech (blueprint × cool-corporate) |
|
||||
| **Target Audience** | AI / NLP engineers, ML graduate students, paper-reading-group members |
|
||||
| **Use Case** | Paper deep-read / lab seminar / engineering onboarding to Transformer |
|
||||
| **Created Date** | 2026-05-24 |
|
||||
|
||||
---
|
||||
|
||||
## II. Canvas Specification
|
||||
|
||||
| Property | Value |
|
||||
| -------- | ----- |
|
||||
| **Format** | PPT 16:9 |
|
||||
| **Dimensions** | 1280×720 |
|
||||
| **viewBox** | `0 0 1280 720` |
|
||||
| **Margins** | Left/right 60px, top/bottom 50px |
|
||||
| **Content Area** | 1160×620 inside margins |
|
||||
|
||||
---
|
||||
|
||||
## III. Visual Theme
|
||||
|
||||
### Theme Style
|
||||
|
||||
- **Style**: General Consulting + academic minimalist tech (paper-precise, blueprint feel)
|
||||
- **Theme**: Light theme
|
||||
- **Tone**: Restrained, analytical, engineering-precise; reads like a Distill.pub article or Anthropic system schematic
|
||||
|
||||
### Color Scheme
|
||||
|
||||
| Role | HEX | Purpose |
|
||||
| ---- | --- | ------- |
|
||||
| **Background** | `#FFFFFF` | Page background |
|
||||
| **Secondary bg** | `#F5F7FA` | Card / region background |
|
||||
| **Primary** | `#1A365D` | Title, schematic lines, primary box stroke |
|
||||
| **Accent** | `#3182CE` | Key data, highlighted path, focus elements |
|
||||
| **Secondary accent** | `#63B3ED` | Gradient transitions, secondary emphasis |
|
||||
| **Body text** | `#1A202C` | Main body text |
|
||||
| **Secondary text** | `#4A5568` | Captions, annotations |
|
||||
| **Tertiary text** | `#A0AEC0` | Page numbers, footnotes |
|
||||
| **Border/divider** | `#E2E8F0` | Card borders, divider lines |
|
||||
| **Success** | `#2F855A` | Positive trend (BLEU improvement) |
|
||||
| **Warning** | `#C53030` | Negative trend, ablation degradation |
|
||||
|
||||
### AI Image Strategy
|
||||
|
||||
- **Image Rendering**: blueprint
|
||||
- **Image Palette**: cool-corporate
|
||||
|
||||
> Every AI image in this deck shares blueprint × cool-corporate. The rendering carries technical-schematic feel (crisp lines, near-monochrome, optional subtle grid); the palette carries restrained-corporate proportion (off-white field dominant, navy as main, accent blue under 10-15%). Cross-check: blueprint × cool-corporate is ✓✓ in the compatibility matrix.
|
||||
|
||||
### Gradient Scheme
|
||||
|
||||
```xml
|
||||
<linearGradient id="titleGradient" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" stop-color="#1A365D"/>
|
||||
<stop offset="100%" stop-color="#3182CE"/>
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="scrimBottom" x1="0%" y1="0%" x2="0%" y2="100%">
|
||||
<stop offset="0%" stop-color="#1A365D" stop-opacity="0"/>
|
||||
<stop offset="100%" stop-color="#1A365D" stop-opacity="0.7"/>
|
||||
</linearGradient>
|
||||
|
||||
<radialGradient id="bgDecor" cx="80%" cy="20%" r="50%">
|
||||
<stop offset="0%" stop-color="#3182CE" stop-opacity="0.15"/>
|
||||
<stop offset="100%" stop-color="#3182CE" stop-opacity="0"/>
|
||||
</radialGradient>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IV. Typography System
|
||||
|
||||
**Typography direction**: academic serif title + cross-platform sans body — Latin-led so Georgia carries the paper-essay tone in titles while Microsoft YaHei renders any CJK glyphs without fallback.
|
||||
|
||||
| Role | Chinese | English | Fallback tail |
|
||||
| ---- | ------- | ------- | ------------- |
|
||||
| **Title** | `"Microsoft YaHei"` | `Georgia` | `serif` |
|
||||
| **Body** | `"Microsoft YaHei", "PingFang SC"` | `Arial` | `sans-serif` |
|
||||
| **Emphasis** | `"Microsoft YaHei"` | `Georgia` | `serif` |
|
||||
| **Code** | — | `Consolas, "Courier New"` | `monospace` |
|
||||
|
||||
**Per-role font stacks**:
|
||||
|
||||
- Title: `Georgia, "Microsoft YaHei", serif`
|
||||
- Body: `Arial, "Microsoft YaHei", "PingFang SC", sans-serif`
|
||||
- Emphasis: `Georgia, "Microsoft YaHei", serif`
|
||||
- Code: `Consolas, "Courier New", monospace`
|
||||
|
||||
### Font Size Hierarchy
|
||||
|
||||
**Baseline**: Body font size = **20**px (medium-dense — paper text + data + diagram annotations).
|
||||
|
||||
| Purpose | Ratio to body | This deck @ body=20 | Weight |
|
||||
| ------- | ------------- | ------------------- | ------ |
|
||||
| Cover title (hero headline) | 2.5-5x | 64px | Bold |
|
||||
| Chapter / section opener | 2-2.5x | 44px | Bold |
|
||||
| Page title | 1.5-2x | 36px | Bold |
|
||||
| Hero number (KPI) | 1.5-2x | 40px | Bold |
|
||||
| Subtitle | 1.2-1.5x | 26px | SemiBold |
|
||||
| **Body content** | **1x** | **20px** | Regular |
|
||||
| Annotation / caption | 0.7-0.85x | 14px | Regular |
|
||||
| Page number / footnote | 0.5-0.65x | 11px | Regular |
|
||||
|
||||
### Formula Rendering Policy
|
||||
|
||||
- **Policy**: `mixed` — render formula-worthy block expressions to PNG; keep inline math (`d_model=512`, `O(n)`, single Greek letters) as editable text.
|
||||
- **Rendered formulas** (3): Scaled Dot-Product Attention (P07), Multi-Head Attention (P08), Positional Encoding (P11). Manifest at `images/formula_manifest.json`; rendered via codecogs provider, transparent, color `#1A365D`.
|
||||
|
||||
---
|
||||
|
||||
## V. Layout Principles
|
||||
|
||||
### Page Structure
|
||||
|
||||
- **Header area**: top 60-100px — page title + thin divider rule in `#3182CE`
|
||||
- **Content area**: 500-560px height — flexible per page rhythm
|
||||
- **Footer area**: bottom 40px — page number + project tag in tertiary text
|
||||
|
||||
### Layout Pattern Library (combine or break as content demands)
|
||||
|
||||
| Pattern | Suitable Scenarios |
|
||||
| ------- | ----------------- |
|
||||
| **Single column centered** | P01 cover, P16 closing |
|
||||
| **Asymmetric split (3:7 / 2:8)** | P05/P07/P08 figure-dominant pages |
|
||||
| **Symmetric split (5:5)** | P06 Encoder vs Decoder |
|
||||
| **Top-bottom split** | P02 KPI hero + sub-detail; P03 hero image + caption row |
|
||||
| **Three/four column cards** | P04 limitations, P09 three attention uses, P13 training KPIs |
|
||||
| **Full-bleed + floating text** | P01, P03, P11, P16 hero pages |
|
||||
| **Figure-text overlap** | P05 annotated architecture diagram |
|
||||
| **Centered formula + caption** | P07, P08, P11 formula blocks |
|
||||
| **Negative-space-driven** | P11 positional encoding breathing page |
|
||||
|
||||
### Spacing Specification
|
||||
|
||||
**Universal**:
|
||||
|
||||
| Element | Range | This deck |
|
||||
| ------- | ----- | --------- |
|
||||
| Safe margin from canvas edge | 40-60px | 60px |
|
||||
| Content block gap | 24-40px | 28px |
|
||||
| Icon-text gap | 8-16px | 12px |
|
||||
|
||||
**Card-based** (P02, P04, P09, P13, P15):
|
||||
|
||||
| Element | Range | This deck |
|
||||
| ------- | ----- | --------- |
|
||||
| Card gap | 20-32px | 24px |
|
||||
| Card padding | 20-32px | 24px |
|
||||
| Card border radius | 8-16px | 12px |
|
||||
| Three-column card width | 360-380px | 360px |
|
||||
| Four-column card width | — | 268px |
|
||||
| Single-row card height | 530-600px | 540px |
|
||||
|
||||
---
|
||||
|
||||
## VI. Icon Usage Specification
|
||||
|
||||
### Source
|
||||
|
||||
- **Library**: `tabler-outline` (stroke-style, weight 2px, screen-clear)
|
||||
- **Stroke width**: 2 px (deck-wide lock)
|
||||
|
||||
### Recommended Icon List
|
||||
|
||||
| Purpose | Icon Path | Page |
|
||||
| ------- | --------- | ---- |
|
||||
| Trophy / SOTA result | `tabler-outline/trophy` | P02, P14 |
|
||||
| Speed / training time | `tabler-outline/bolt` | P02, P13 |
|
||||
| Layers / stack | `tabler-outline/stack-2` | P02, P06 |
|
||||
| Brain / model | `tabler-outline/brain` | P02, P16 |
|
||||
| Refresh / recurrence | `tabler-outline/refresh` | P03, P04 |
|
||||
| Arrows-right (sequence) | `tabler-outline/arrow-right` | P03, P09 |
|
||||
| Lock / constraint | `tabler-outline/lock` | P04 |
|
||||
| Hourglass / sequential bottleneck | `tabler-outline/hourglass` | P04 |
|
||||
| Box / module | `tabler-outline/box` | P06, P10 |
|
||||
| Eye / attention | `tabler-outline/eye` | P07, P09 |
|
||||
| Grid / multi-head | `tabler-outline/grid-dots` | P08 |
|
||||
| Wave / sinusoid | `tabler-outline/wave-sine` | P11 |
|
||||
| Chart bar | `tabler-outline/chart-bar` | P14, P15 |
|
||||
| GPU / hardware | `tabler-outline/cpu` | P13 |
|
||||
| Settings / hyperparams | `tabler-outline/settings` | P13, P15 |
|
||||
| Tree / family of descendants | `tabler-outline/binary-tree` | P16 |
|
||||
|
||||
---
|
||||
|
||||
## VII. Visualization Reference List
|
||||
|
||||
Catalog read: 71 templates
|
||||
|
||||
| Page | Template | Path | Summary-quote (verbatim from `charts_index.json`) | Usage |
|
||||
| ---- | -------- | ---- | ------------------------------------------------- | ----- |
|
||||
| P02 | kpi_cards | `templates/charts/kpi_cards.svg` | "Pick for 4-8 standalone numeric metrics shown as overview cards (2x2 or 1x4) — exec summary opener, dashboard headline, quarterly recap, results-at-a-glance. Skip if metrics have target baselines (use bullet_chart) or single hero number (use gauge_chart)." | Four headline metrics: 28.4 BLEU EN-DE, 41.8 BLEU EN-FR, 3.5 days on 8 GPUs, no recurrence/convolution |
|
||||
| P04 | vertical_pillars | `templates/charts/vertical_pillars.svg` | "Pick for 1×3 / 1×4 / 1×5 vertical column layout where each pillar = one independent category with title + bullets — PEST (Political/Economic/Social/Technological), four-pillar strategy overview, side-by-side independent categories. Skip for 2×2 quadrant (use quadrant_text_bullets), pricing tiers (use comparison_columns), or 2×2 parallel aspects (use labeled_card)." | Three RNN/CNN limitations side-by-side: sequential bottleneck / long-range path length / parallelization ceiling |
|
||||
| P06 | comparison_columns | `templates/charts/comparison_columns.svg` | "Pick for 2-4 pricing/service tier cards in side-by-side columns (marketing layout). Skip for dense feature comparison (use comparison_table)." | Encoder stack vs Decoder stack — sub-layers, masking, residual+LN, output dim |
|
||||
| P09 | vertical_pillars | `templates/charts/vertical_pillars.svg` | "Pick for 1×3 / 1×4 / 1×5 vertical column layout where each pillar = one independent category with title + bullets — PEST (Political/Economic/Social/Technological), four-pillar strategy overview, side-by-side independent categories. Skip for 2×2 quadrant (use quadrant_text_bullets), pricing tiers (use comparison_columns), or 2×2 parallel aspects (use labeled_card)." | Three places attention is used: encoder self-attn / decoder masked self-attn / encoder-decoder cross-attn |
|
||||
| P10 | module_composition | `templates/charts/module_composition.svg` | "Pick for one parent container wrapping 3-N child module cards, each = title + 2-3 bullets — fits 'Feature X contains 3 parts, each with its own description'. Skip if source has only labels without descriptions (use numbered_steps or icon_grid)." | Sub-layer wrap: position-wise FFN + residual connection + layer normalization, all inside one Encoder/Decoder layer block |
|
||||
| P12 | basic_table | `templates/charts/basic_table.svg` | "Pick for plain tabular text/number grid, 3-8 columns. Skip if cells need visual bars (use consulting_table) or qualitative scores (use harvey_balls_table)." | Table 1: Per-layer complexity / sequential ops / max path length across Self-Attn, Recurrent, Convolutional, Self-Attn(restricted) |
|
||||
| P13 | kpi_cards | `templates/charts/kpi_cards.svg` | "Pick for 4-8 standalone numeric metrics shown as overview cards (2x2 or 1x4) — exec summary opener, dashboard headline, quarterly recap, results-at-a-glance. Skip if metrics have target baselines (use bullet_chart) or single hero number (use gauge_chart)." | Training config dashboard: 8× P100 GPUs / 12 h base, 3.5 d big / batch 25k tokens / Adam β=(0.9, 0.98) |
|
||||
| P14 | basic_table | `templates/charts/basic_table.svg` | "Pick for plain tabular text/number grid, 3-8 columns. Skip if cells need visual bars (use consulting_table) or qualitative scores (use harvey_balls_table)." | Table 2: BLEU on WMT'14 EN-DE / EN-FR vs prior SOTA, with training-cost FLOPs column |
|
||||
| P15 | vertical_list | `templates/charts/vertical_list.svg` | "Pick for 3-6 numbered key points each with a short description — design principles, core tenets, action items, key takeaways, recommendations, executive summary points. Skip for icon-style cards (use icon_grid) or sequential steps (use numbered_steps)." | Table 3 ablation takeaways: head count sweet-spot, key/value dim, dropout, label smoothing |
|
||||
|
||||
**Runners-up considered**:
|
||||
|
||||
- `quadrant_text_bullets` | rejected for P04: limitations are three parallel side-by-side categories, no 2×2 framework
|
||||
- `comparison_table` | rejected for P12: only 4 rows + 4 columns, no checkmark / dense matrix needed — `basic_table` is the simpler fit
|
||||
- `gauge_chart` | rejected for P02: four parallel headline metrics, not one hero goal achievement
|
||||
- `numbered_steps` | rejected for P15: ablation findings are independent takeaways, not sequential
|
||||
|
||||
---
|
||||
|
||||
## VIII. Image Resource List
|
||||
|
||||
| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Acquire Via | Status | Reference | text_policy | page_role |
|
||||
| -------- | ---------- | ----- | ------- | ---- | -------------- | ----------- | ------ | --------- | ----------- | --------- |
|
||||
| cover_bg.png | 1280×720 | 1.78 | P01 cover hero — abstract Transformer blueprint atmosphere | Background | #1 full-bleed background with floating title + #29 two-stop scrim + #38 background image + annotation cards with bezier leader lines | ai | Pending | Abstract technical-blueprint atmosphere suggesting a sequence-to-sequence neural network rebuilt around attention; six labeled rectangular module blocks arranged in two stacked rows on a near-white background, connected by thin precise lines with small arrow heads; a subtle grid pattern at 6% opacity reinforces the schematic feel; the left half is the deck's calm region reserved for a deep-navy title overlay; the right half holds the schematic; one rectangle is highlighted with accent stroke, suggesting the "self-attention" focal block; no embedded text, no labels, no equations, no numbers — every label will be overlaid as SVG text; reads as the title plate of a systems-design briefing document | none | hero_page |
|
||||
| sequence_evolution.png | 1280×720 | 1.78 | P03 hero — RNN/CNN/Self-Attention comparison as three schematic motifs, each motif carries its panel label inside the image | Diagram | #44 background image + native network/architecture diagram + #29 two-stop scrim | ai | Pending | Three side-by-side schematic motifs reading left to right as a quiet evolution: leftmost — a horizontal chain of five linked circles flowing left-to-right, each linked to the next by a single arrow, suggesting recurrent step-by-step computation; middle — a stack of three parallel horizontal bars of small circles connected by short vertical strokes, suggesting convolutional local receptive fields; rightmost — five circles arranged as a fully-connected mesh where every node connects to every other node with thin straight lines, suggesting global self-attention; all three motifs sit on a near-white field; the rightmost mesh is rendered in the accent blue while the other two are in the primary deep navy; subtle 6% grid background underneath everything; the upper third is reserved as calm scrim region for a page title in SVG; one short panel label above each motif as stable figure-internal identifier — RNN / CNN / SELF-ATTENTION — rendered in monospace technical lettering | embedded | hero_page |
|
||||
| rnn_bottleneck.png | 480×600 | 0.80 | P04 right column — sequential computation bottleneck illustration | Diagram | #3 right-third image + left text body + #21 rounded rectangle crop | ai | Pending | A vertical chain of six small rounded rectangles stacked one above the other, connected by thin arrows pointing downward; each rectangle suggests a hidden state at one time step; an hourglass-shaped marker hovers along the chain hinting at the sequential time cost; on either side of the chain, faint dashed parallel lines suggest the channels that cannot be parallelized; the background is near-white with a 6% navy grid; all linework in primary deep navy except the hourglass which is in accent blue; subtle schematic spacing between elements; no embedded text, no labels, no numbers | none | local |
|
||||
| sublayer_block.png | 480×600 | 0.80 | P10 left column — encoder/decoder sub-layer composition cross-section, conventional module labels inside the image | Diagram | #2 left-third image + right text body + #21 rounded rectangle crop | ai | Pending | A vertical schematic cross-section showing one encoder/decoder layer block: an outer rounded rectangle frame containing, top-to-bottom, two inner stacked rounded rectangles labeled visually as two sub-layers (one slightly taller, one shorter); a thin arc on the right side of each inner rectangle suggests a residual skip connection that wraps around the sub-layer and rejoins below it; a small horizontal stripe below each sub-layer suggests layer normalization; all linework in primary deep navy at uniform 1.5px stroke, accent blue used only on the two residual arcs to highlight them; near-white background with 6% navy grid; reads as a precise engineering schematic of the LayerNorm(x + Sublayer(x)) pattern; conventional architecture-paper labels inside the image — Self-Attention in the upper sub-layer, Feed Forward in the lower sub-layer, Add & Norm below each LayerNorm stripe — rendered as monospace technical lettering | embedded | local |
|
||||
| positional_encoding.png | 1280×720 | 1.78 | P11 hero — sinusoidal positional encoding visualization with textbook curve and axis labels inside the image | Diagram | #1 full-bleed background with floating title + #30 flat semi-transparent rectangle overlay + #45 background image + numbered hotspots with sidebar legend | ai | Pending | A full-width schematic showing two superimposed sinusoidal waveforms running horizontally across the canvas — one is the sine wave at low frequency (long wavelength, gentle undulation) in primary deep navy, the other is the cosine wave at higher frequency (shorter wavelength, tighter undulation) in accent blue; below the waveforms, a horizontal row of ten small evenly-spaced tick marks suggests discrete token positions on a position axis; thin vertical accent-blue guide-lines at three of the ticks drop from the waveforms down to the axis, suggesting that each token position carries a unique pair of (sin, cos) values; the left third of the canvas is reserved as a calm scrim region for a page title in SVG; near-white background with 6% navy grid; reads as a technical figure from a textbook chapter on Fourier features; three stable in-image labels rendered in monospace technical lettering — the word sin near the right end of the navy curve, cos near the right end of the accent-blue curve, position → just below the right end of the axis line; no other text, no axis numbers, no equations | embedded | hero_page |
|
||||
| transformer_family.png | 1280×720 | 1.78 | P16 hero — Transformer descendants family tree (BERT/GPT/T5/Vision Transformer abstract motifs) | Diagram | #12 faded image as backdrop with oversized overlay text + #30 flat semi-transparent rectangle overlay | ai | Pending | A symmetric top-down tree-of-descendants schematic: at the top, one single rounded rectangle (the root Transformer) in deep navy with a brighter accent-blue outline; from it, thin lines fan downward to two intermediate rounded rectangles slightly smaller (suggesting encoder-only and decoder-only families); from each intermediate, three thinner branches drop to small abstract leaf shapes of varying size (suggesting the multitude of derived models); the entire schematic is rendered at low opacity around 35% so it reads as a faded backdrop; near-white background with 6% navy grid underneath; an oversized empty calm region across the upper middle reserved for SVG closing title; reads as a quiet "what this paper started" diagram, not a busy logo wall; no embedded text, no labels, no model names — all labels overlaid as SVG text | none | hero_page |
|
||||
| attention_p3_0.png | 1520×2239 | 0.68 | P05 Transformer model architecture (Figure 1 from paper) | Diagram | #19 image floating in whitespace with thin frame and caption + #45 background image + numbered hotspots with sidebar legend | user | Existing | Original Figure 1 from the paper showing the full Encoder–Decoder Transformer architecture — Nx stacked encoder block (Multi-Head Attention → Add & Norm → Feed Forward → Add & Norm) on the left; Nx stacked decoder block (Masked Multi-Head Attention → Add & Norm → Multi-Head Attention → Add & Norm → Feed Forward → Add & Norm) on the right; positional encodings entering both stacks; final Linear + Softmax at the top right | | |
|
||||
| attention_p4_1.png | 835×1282 | 0.65 | P07 Scaled Dot-Product Attention (Figure 2 left) and P08 Multi-Head Attention (Figure 2 right) | Diagram | #46 background image + bordered "lens" rectangle highlighting a sub-region + #19 image floating in whitespace with thin frame and caption + #62 same image, two references — full view + zoom-callout | user | Existing | Original Figure 2 from the paper, two sub-figures side by side: left — Scaled Dot-Product Attention with MatMul → Scale → (Mask) → SoftMax → MatMul flow taking Q, K, V; right — Multi-Head Attention with h parallel Linear → Scaled Dot-Product Attention heads → Concat → Linear, taking V, K, Q inputs | | |
|
||||
| formula_001.png | 880×122 | 7.21 | P07 block formula — Scaled Dot-Product Attention equation | Latex Formula | formula-block | formula | Rendered | `Attention(Q, K, V) = softmax(QK^T / √d_k) V` — equation (1) from §3.2.1 | | |
|
||||
| formula_002.png | 1168×137 | 8.53 | P08 block formula — Multi-Head Attention equation | Latex Formula | formula-block | formula | Rendered | `MultiHead(Q,K,V) = Concat(head_1, …, head_h) W^O where head_i = Attention(Q W_i^Q, K W_i^K, V W_i^V)` — equations from §3.2.2 | | |
|
||||
| formula_003.png | 706×201 | 3.51 | P11 block formula — Positional Encoding equation | Latex Formula | formula-block | formula | Rendered | `PE_(pos, 2i) = sin(pos / 10000^(2i/d_model)); PE_(pos, 2i+1) = cos(pos / 10000^(2i/d_model))` — equation from §3.5 | | |
|
||||
|
||||
> Image-as-canvas coverage check: P01 uses #38, P03 uses #44, P05 / P11 use #45. Deck has ≥4 image-bearing pages and 4 of them use the #38–#46 family — coverage rule satisfied.
|
||||
|
||||
---
|
||||
|
||||
## IX. Content Outline
|
||||
|
||||
### Part 1: Opening
|
||||
|
||||
#### Slide 01 — Cover
|
||||
|
||||
- **Layout**: Full-bleed AI hero image + left-half calm region for title; #38 annotation cards with bezier leader lines + #29 two-stop scrim
|
||||
- **Title**: Attention Is All You Need
|
||||
- **Subtitle**: A paper deep-read
|
||||
- **Info**: Vaswani et al. · Google Brain / Google Research / Univ. of Toronto · NeurIPS 2017 · arXiv:1706.03762
|
||||
|
||||
#### Slide 02 — Why this paper matters
|
||||
|
||||
- **Layout**: Page title + 4-card KPI row (kpi_cards) + one-line takeaway band
|
||||
- **Title**: A simpler model, better results, less training
|
||||
- **Visualization**: kpi_cards (see §VII)
|
||||
- **Content**:
|
||||
- **28.4 BLEU** on WMT'14 EN-DE — +2.0 over previous SOTA ensembles
|
||||
- **41.8 BLEU** on WMT'14 EN-FR — new single-model SOTA
|
||||
- **3.5 days × 8 P100 GPUs** — a small fraction of prior training cost
|
||||
- **0 recurrence · 0 convolution** — only attention + feed-forward
|
||||
|
||||
### Part 2: Motivation & Background
|
||||
|
||||
#### Slide 03 — Sequence modeling so far: RNN → CNN → Self-Attention
|
||||
|
||||
- **Layout**: Hero AI image full-bleed + bottom scrim + floating title (#44 + #29)
|
||||
- **Title**: From recurrent chains to a fully-connected attention mesh
|
||||
- **Content**:
|
||||
- RNN / LSTM / GRU — strong, but inherently sequential
|
||||
- ByteNet / ConvS2S — parallelizable, but signals between distant positions still grow with distance
|
||||
- Self-attention — relates any two positions in constant operations
|
||||
|
||||
#### Slide 04 — The fundamental constraint we want to lift
|
||||
|
||||
- **Layout**: Right-third AI image (#3 + #21) + left vertical_pillars
|
||||
- **Title**: What hurts in RNN/CNN sequence models
|
||||
- **Visualization**: vertical_pillars
|
||||
- **Content**:
|
||||
- **Sequential bottleneck** — h_t depends on h_{t-1}; no within-example parallelism
|
||||
- **Long-range path length** — ConvS2S grows linearly, ByteNet logarithmically; distant tokens hard to relate
|
||||
- **Memory ceiling** — sequence length limits batch size, especially at long context
|
||||
|
||||
### Part 3: The Transformer
|
||||
|
||||
#### Slide 05 — Model architecture overview
|
||||
|
||||
- **Layout**: User-provided Figure 1 image (portrait, scaled to fit) on left + right-side numbered hotspot legend (#19 + #45)
|
||||
- **Title**: Encoder–Decoder, stacked self-attention, point-wise feed-forward
|
||||
- **Content** (sidebar legend):
|
||||
1. Input embeddings + positional encoding
|
||||
2. Nx encoder block — Multi-Head Self-Attention + FFN
|
||||
3. Nx decoder block — Masked Self-Attn + Encoder–Decoder Attn + FFN
|
||||
4. Add & Norm — residual then LayerNorm around every sub-layer
|
||||
5. Final Linear + Softmax — output token probabilities
|
||||
|
||||
#### Slide 06 — Encoder vs Decoder stacks
|
||||
|
||||
- **Layout**: comparison_columns — two parallel cards
|
||||
- **Title**: Same skeleton, three asymmetries
|
||||
- **Visualization**: comparison_columns
|
||||
- **Content**:
|
||||
- **Encoder (N=6)** — Multi-Head Self-Attention → FFN; LayerNorm(x + Sublayer(x)); d_model = 512
|
||||
- **Decoder (N=6)** — Masked Multi-Head Self-Attention → Encoder-Decoder Multi-Head Attention → FFN; same residual + LN; output offset by one position; positions attend only to earlier outputs
|
||||
|
||||
### Part 4: Attention mechanism
|
||||
|
||||
#### Slide 07 — Scaled Dot-Product Attention
|
||||
|
||||
- **Layout**: User-provided Figure 2 cropped to left half (#46 lens crop) on right + left text body + centered formula band
|
||||
- **Title**: Attention as a weighted average — keys, values, queries
|
||||
- **Visualization**: Formula block (formula_001.png)
|
||||
- **Content**:
|
||||
- Inputs: queries and keys of dim d_k, values of dim d_v
|
||||
- Compute QK^T, scale by √d_k, softmax → attention weights
|
||||
- Multiply by V — weighted sum is the output
|
||||
- Scaling matters: without √d_k, large d_k pushes softmax into low-gradient regions
|
||||
|
||||
#### Slide 08 — Multi-Head Attention
|
||||
|
||||
- **Layout**: User-provided Figure 2 cropped to right half (#46 lens crop) on right + left text body + centered formula band
|
||||
- **Title**: h parallel projections, then concatenate
|
||||
- **Visualization**: Formula block (formula_002.png)
|
||||
- **Content**:
|
||||
- Project Q, K, V into h = 8 independent subspaces via learned linear projections
|
||||
- Run scaled dot-product attention in each head in parallel; d_k = d_v = d_model / h = 64
|
||||
- Concatenate the h outputs and project once more with W^O
|
||||
- Why: attend to information from different representation subspaces at different positions
|
||||
|
||||
#### Slide 09 — Three places attention is used
|
||||
|
||||
- **Layout**: vertical_pillars — three independent columns
|
||||
- **Title**: One mechanism, three roles in the Transformer
|
||||
- **Visualization**: vertical_pillars
|
||||
- **Content**:
|
||||
- **Encoder self-attention** — Q, K, V all from the previous encoder layer; every position attends to all positions
|
||||
- **Decoder masked self-attention** — same as above but masked: position i attends only to positions ≤ i (preserve auto-regression)
|
||||
- **Encoder–decoder attention** — queries from the decoder, keys & values from the encoder output; lets every decoder position attend over the whole input sequence (the classic seq2seq attention role)
|
||||
|
||||
#### Slide 10 — Feed-Forward, Residual, LayerNorm
|
||||
|
||||
- **Layout**: Left-third AI image (#2 + #21) + right module_composition
|
||||
- **Title**: The supporting cast inside every layer
|
||||
- **Visualization**: module_composition
|
||||
- **Content**:
|
||||
- **Position-wise FFN** — two linear layers with ReLU between, applied identically at every position; inner dim 2048
|
||||
- **Residual connection** — every sub-layer output is x + Sublayer(x), enabling deeper stacks
|
||||
- **LayerNorm** — applied around each sub-layer; stabilizes training, paired with d_model = 512
|
||||
|
||||
### Part 5: Position information
|
||||
|
||||
#### Slide 11 — Positional Encoding
|
||||
|
||||
- **Layout**: AI hero image full-bleed (#1 + #30 + #45) + centered formula band + minimal SVG annotation
|
||||
- **Title**: Recovering order without recurrence — sinusoids of different frequencies
|
||||
- **Visualization**: Formula block (formula_003.png)
|
||||
- **Content**:
|
||||
- No recurrence / convolution → model has no built-in notion of token order
|
||||
- Add a deterministic sinusoidal position vector to each input embedding
|
||||
- sin / cos at geometrically increasing wavelengths from 2π to 10000·2π
|
||||
- Lets the model learn to attend by relative position via linear function of PE
|
||||
|
||||
### Part 6: Why and how well it works
|
||||
|
||||
#### Slide 12 — Complexity comparison (Table 1)
|
||||
|
||||
- **Layout**: Page title + basic_table (full-width)
|
||||
- **Title**: Complexity per layer, sequential operations, max path length
|
||||
- **Visualization**: basic_table
|
||||
- **Content**:
|
||||
- Self-Attention: O(n²·d), 1 sequential op, max path length O(1)
|
||||
- Recurrent: O(n·d²), O(n) sequential ops, max path length O(n)
|
||||
- Convolutional: O(k·n·d²), 1, max path length O(log_k n)
|
||||
- Self-Attention (restricted, window r): O(r·n·d), 1, max path length O(n/r)
|
||||
|
||||
#### Slide 13 — Training setup
|
||||
|
||||
- **Layout**: Page title + kpi_cards (2×2 or 1×4)
|
||||
- **Title**: How they trained it
|
||||
- **Visualization**: kpi_cards
|
||||
- **Content**:
|
||||
- **Hardware** — 8× NVIDIA P100 GPUs
|
||||
- **Time** — Base 12 h (100k steps) · Big 3.5 d (300k steps)
|
||||
- **Optimizer** — Adam, β₁=0.9, β₂=0.98, ε=1e-9; warm-up then 1/√step decay
|
||||
- **Regularization** — Dropout 0.1, label smoothing ε_ls = 0.1
|
||||
|
||||
#### Slide 14 — Results (Table 2)
|
||||
|
||||
- **Layout**: Page title + basic_table (full-width) + bottom takeaway band
|
||||
- **Title**: New SOTA on WMT'14 — at a fraction of the training cost
|
||||
- **Visualization**: basic_table
|
||||
- **Content**:
|
||||
- Transformer (big): EN-DE 28.4 BLEU · EN-FR 41.8 BLEU
|
||||
- vs prior best ensembles: +2.0 EN-DE; new single-model SOTA EN-FR
|
||||
- Training FLOPs (big): ~2.3 × 10¹⁹ — well below most strong baselines
|
||||
|
||||
#### Slide 15 — What matters in the architecture (Table 3 ablations)
|
||||
|
||||
- **Layout**: vertical_list (5 numbered key points)
|
||||
- **Title**: Five takeaways from the variation study
|
||||
- **Visualization**: vertical_list
|
||||
- **Content**:
|
||||
- **Head count has a sweet spot** — single-head loses 0.9 BLEU; too many (32) also degrade
|
||||
- **Key dim matters more than value dim** — reducing d_k hurts quality more than reducing d_v
|
||||
- **Bigger is better** — larger d_model and deeper stacks consistently improve BLEU
|
||||
- **Dropout is essential** — removing it loses ~0.5–1.0 BLEU; even small dropout (0.1) matters
|
||||
- **Label smoothing helps perplexity & BLEU** — slightly hurts perplexity but improves BLEU
|
||||
|
||||
### Part 7: Closing
|
||||
|
||||
#### Slide 16 — What this paper started
|
||||
|
||||
- **Layout**: AI hero image full-bleed faded (#12 + #30) + centered closing title + small caption row
|
||||
- **Title**: One paper, a generation of models
|
||||
- **Content**:
|
||||
- Transformer became the substrate for BERT, GPT, T5, Vision Transformer, AlphaFold, and most modern LLMs
|
||||
- The 2017 idea — **just attention** — turned out to be the right inductive bias for almost every modality
|
||||
- References: arXiv:1706.03762, code at github.com/tensorflow/tensor2tensor
|
||||
|
||||
---
|
||||
|
||||
## X. Speaker Notes Requirements
|
||||
|
||||
- **Filename**: one file per slide under `notes/`, matching SVG basename (e.g., `01_cover.svg` → `notes/01_cover.md`)
|
||||
- **Style**: conversational-academic (paper-reading-group register — clear, technical, no marketing copy)
|
||||
- **Total duration**: ~20 minutes presented (≈ 75 sec per slide on average; deeper slides P05/P07/P08/P11 ≈ 100 sec each)
|
||||
- **Purpose**: instruct / inform — explain the paper to an engineer who has not read it carefully
|
||||
- **Format**: master document at `notes/total.md` with `#` headings per slide; split files have no `#` heading
|
||||
|
||||
---
|
||||
|
||||
## XI. Technical Constraints Reminder
|
||||
|
||||
### SVG Generation Must Follow:
|
||||
|
||||
1. viewBox: `0 0 1280 720`
|
||||
2. Background uses `<rect>` elements
|
||||
3. Text wrapping uses `<tspan>` (`<foreignObject>` FORBIDDEN)
|
||||
4. Transparency uses `fill-opacity` / `stroke-opacity`; `rgba()` FORBIDDEN
|
||||
5. FORBIDDEN: `mask`, `<style>`, `class`, `foreignObject`, `textPath`, `animate*`, `script`
|
||||
6. Text characters: raw Unicode (`—`, `→`, NBSP, `²`, `√`, `≤`, `·`); HTML named entities FORBIDDEN; reserved chars escaped as `& < > " '`
|
||||
7. `marker-start` / `marker-end` conditionally allowed: `<marker>` in `<defs>`, `orient="auto"`, triangle / diamond / circle shape only
|
||||
8. `clipPath` only on `<image>` elements: `<clipPath>` in `<defs>`, single shape child
|
||||
|
||||
### PPT Compatibility Rules:
|
||||
|
||||
- `<g opacity="...">` FORBIDDEN — set opacity on each child element individually
|
||||
- Image transparency uses overlay mask layer (`<rect fill="bg-color" opacity="0.x"/>`)
|
||||
- Inline styles only; external CSS and `@font-face` FORBIDDEN
|
||||
Binary file not shown.
@@ -0,0 +1,3 @@
|
||||
No,Filename,Width,Height,AspectRatio,PixelAspectRatio,RatioSource,UsageCount,DisplayRatioVariants,AssetKind,SvgRenderable,PptxNativeSupported,SizeKB,Category,ImageArea_SxS,TextArea_SxS
|
||||
1,attention_p3_0.png,1520,2239,0.68,0.68,pixel,1,,bitmap,True,True,118.4,Portrait,407x600,733x600
|
||||
2,attention_p4_1.png,835,1282,0.65,0.65,pixel,1,,bitmap,True,True,42.5,Portrait,391x600,749x600
|
||||
|
Binary file not shown.
|
After Width: | Height: | Size: 218 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 127 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 677 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"providers": [
|
||||
"codecogs",
|
||||
"quicklatex",
|
||||
"mathpad",
|
||||
"wikimedia"
|
||||
],
|
||||
"items": [
|
||||
{
|
||||
"id": "formula_001",
|
||||
"latex": "\\text{Attention}(Q, K, V) = \\text{softmax}\\!\\left(\\frac{QK^{T}}{\\sqrt{d_k}}\\right) V",
|
||||
"display": "block",
|
||||
"color": "#1A365D",
|
||||
"background": "#FFFFFF",
|
||||
"transparent": true,
|
||||
"dpi": 400,
|
||||
"filename": "formula_001.png",
|
||||
"file": "images/formula_001.png",
|
||||
"providers": [
|
||||
"codecogs",
|
||||
"quicklatex",
|
||||
"mathpad",
|
||||
"wikimedia"
|
||||
],
|
||||
"transparent_tolerance": 12,
|
||||
"provider": "codecogs",
|
||||
"pixel_width": 880,
|
||||
"pixel_height": 122,
|
||||
"ratio": 7.2131,
|
||||
"status": "Rendered"
|
||||
},
|
||||
{
|
||||
"id": "formula_002",
|
||||
"latex": "\\begin{aligned}\\text{MultiHead}(Q, K, V) &= \\text{Concat}(\\text{head}_1, \\ldots, \\text{head}_h)\\,W^{O} \\\\ \\text{where}\\ \\text{head}_i &= \\text{Attention}(Q W_i^{Q},\\, K W_i^{K},\\, V W_i^{V})\\end{aligned}",
|
||||
"display": "block",
|
||||
"color": "#1A365D",
|
||||
"background": "#FFFFFF",
|
||||
"transparent": true,
|
||||
"dpi": 400,
|
||||
"filename": "formula_002.png",
|
||||
"file": "images/formula_002.png",
|
||||
"providers": [
|
||||
"codecogs",
|
||||
"quicklatex",
|
||||
"mathpad",
|
||||
"wikimedia"
|
||||
],
|
||||
"transparent_tolerance": 12,
|
||||
"provider": "codecogs",
|
||||
"pixel_width": 1168,
|
||||
"pixel_height": 137,
|
||||
"ratio": 8.5255,
|
||||
"status": "Rendered"
|
||||
},
|
||||
{
|
||||
"id": "formula_003",
|
||||
"latex": "\\begin{aligned}PE_{(pos,\\, 2i)} &= \\sin\\!\\left(\\frac{pos}{10000^{2i/d_{\\text{model}}}}\\right) \\\\ PE_{(pos,\\, 2i+1)} &= \\cos\\!\\left(\\frac{pos}{10000^{2i/d_{\\text{model}}}}\\right)\\end{aligned}",
|
||||
"display": "block",
|
||||
"color": "#1A365D",
|
||||
"background": "#FFFFFF",
|
||||
"transparent": true,
|
||||
"dpi": 400,
|
||||
"filename": "formula_003.png",
|
||||
"file": "images/formula_003.png",
|
||||
"providers": [
|
||||
"codecogs",
|
||||
"quicklatex",
|
||||
"mathpad",
|
||||
"wikimedia"
|
||||
],
|
||||
"transparent_tolerance": 12,
|
||||
"provider": "codecogs",
|
||||
"pixel_width": 706,
|
||||
"pixel_height": 201,
|
||||
"ratio": 3.5124,
|
||||
"status": "Rendered"
|
||||
}
|
||||
],
|
||||
"renderer": {
|
||||
"providers": [
|
||||
"codecogs",
|
||||
"quicklatex",
|
||||
"mathpad",
|
||||
"wikimedia"
|
||||
],
|
||||
"default_dpi": 300,
|
||||
"output_dir": "images"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
{
|
||||
"project": "attention_is_all_you_need",
|
||||
"generated_at": "2026-05-24",
|
||||
"deck_rendering": "blueprint",
|
||||
"deck_palette": "cool-corporate",
|
||||
"color_scheme": {
|
||||
"primary": "#1A365D",
|
||||
"secondary": "#F5F7FA",
|
||||
"accent": "#3182CE"
|
||||
},
|
||||
"items": [
|
||||
{
|
||||
"filename": "cover_bg.png",
|
||||
"purpose": "Cover background (Slide 01) — hero atmospheric blueprint of a generic Transformer-like module graph, calm left side reserved for SVG title overlay",
|
||||
"page_role": "hero_page",
|
||||
"text_policy": "none",
|
||||
"aspect_ratio": "16:9",
|
||||
"image_size": "2K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to essential schematic forms — rounded rectangular module blocks, connector lines, anchor dots, callout markers. Color is restrained, near-monochrome with one semantic accent. A subtle grid background at 6% opacity reinforces the schematic feel. No textures, no shading, no painterly artifacts; engineering-precise, analytical, intentional. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 65% of the canvas as calm breathing space; primary deep navy #1A365D forms the precise schematic linework (about 28% area) — outlines of module blocks, connector lines, anchor dots; accent blue #3182CE appears only as one highlighted module outline and a couple of arrowheads on the focal connector path, together under 7% of the area; no fourth color. Atmospheric blueprint backdrop with no dominant subject — a graph of six rounded rectangular module blocks arranged in two stacked horizontal rows of three (an encoder-stack row at the bottom and a decoder-stack row at the top), connected by precise straight lines with small triangular arrow heads. The blocks are deliberately small and clustered on the right side of the canvas, leaving the left third entirely calm as breathing space — that calm region must stay clear of any schematic element. One block on the upper row is highlighted by replacing its primary navy outline with an accent-blue outline, marking it as the focal self-attention module. Faint vertical and horizontal hairlines suggest a measurement grid only at 6% opacity beneath everything. Composed as a 1280×720 PPT 16:9 full-bleed cover background. Reads as the title plate of a systems-design briefing document. NO text, letters, numbers, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Abstract Transformer-like module graph rendered in technical blueprint style, calm left third reserved for title",
|
||||
"status": "Generated"
|
||||
},
|
||||
{
|
||||
"filename": "sequence_evolution.png",
|
||||
"purpose": "Slide 03 hero — three schematic motifs side by side suggesting RNN chain / convolutional local field / global self-attention mesh, each motif carries its panel label inside the image",
|
||||
"page_role": "hero_page",
|
||||
"text_policy": "embedded",
|
||||
"aspect_ratio": "16:9",
|
||||
"image_size": "2K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Elements are simplified to essential schematic forms — small filled circles for nodes, thin straight lines for connections, small triangular arrow heads on directed edges. Crisp uniform stroke around 1.5px, perfectly straight or precisely curved. No textures, no shading, no painterly artifacts. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 62% of the canvas as calm breathing space; primary deep navy #1A365D carries the bulk of the linework (about 28% area, including the leftmost and middle motifs); accent blue #3182CE appears only in the rightmost motif (under 10% area), marking it as the focus. A subtle 6% opacity navy grid sits beneath everything. Custom composition — three equal-width schematic motifs sit side by side across the lower two-thirds of the canvas, separated by 2px hairline rules in border-gray; the upper third of the canvas is deliberately calm as breathing space for a page title overlay in SVG. Leftmost motif: a horizontal chain of five small filled circles flowing left to right, connected by single arrows between adjacent circles, suggesting recurrent step-by-step computation. Middle motif: three short parallel horizontal rows of four small circles each, each circle connected to the two circles diagonally below it in the next row by short straight lines, suggesting convolutional local receptive fields. Rightmost motif: five circles arranged in a regular pentagon, every circle connected to every other circle by thin straight lines forming a fully-connected mesh, suggesting global self-attention — this entire mesh is rendered in accent blue #3182CE while the first two motifs stay in primary navy. Above each of the three motifs sits one short panel label, rendered as clean monospace technical lettering (fixed-width, sharp uppercase, no serifs), small enough to read as a discreet figure-panel header — about 28-32px high relative to the canvas. The exact label text, left to right, is: above the leftmost motif the word RNN; above the middle motif the word CNN; above the rightmost motif the words SELF-ATTENTION. Labels above the first two motifs are in primary deep navy #1A365D; the SELF-ATTENTION label above the rightmost motif is in accent blue #3182CE matching its mesh. The three panel labels are the ONLY text in the image; no other letters, no axis labels, no captions, no signs, no watermarks anywhere else. Composed as a 1280×720 PPT 16:9 hero background; the upper third (above the panel labels) must remain calm for SVG title overlay. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Three labeled schematic motifs (RNN / CNN / SELF-ATTENTION) comparing recurrent chain, convolutional local fields, and global self-attention mesh",
|
||||
"status": "Generated"
|
||||
},
|
||||
{
|
||||
"filename": "rnn_bottleneck.png",
|
||||
"purpose": "Slide 04 right-third illustration — sequential RNN computation bottleneck (vertical chain of hidden states with an hourglass cue)",
|
||||
"type": "flowchart",
|
||||
"page_role": "local",
|
||||
"text_policy": "none",
|
||||
"aspect_ratio": "3:4",
|
||||
"image_size": "1K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid, with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to schematic forms — small rounded rectangles, thin straight arrows, an hourglass marker. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise, restrained. Color behavior is restrained-corporate: secondary off-white #F5F7FA fills about 60% of the block as background breathing; primary deep navy #1A365D forms the chain of hidden-state boxes and the connecting arrows (about 32% area); accent blue #3182CE is used only for the hourglass marker and one small focus highlight (under 8% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Flowchart-style local composition: a vertical chain of six small identical rounded rectangles stacked one above the other, each connected to the next by a thin downward-pointing arrow with a small triangular arrow head; each rectangle represents a hidden state at one time step. To the right of the chain, a small hourglass marker in accent blue floats alongside the middle of the chain, suggesting sequential time cost. To the left of the chain, two faint dashed parallel vertical lines hint at the channels that cannot be parallelized — they are dashed, in primary navy at 50% opacity. The entire schematic is centered inside the block with about 14% inner padding on all sides. Composed as a 480×600 vertical local block for placement inside an SVG page region; do NOT reserve calm overlay space inside the image — the SVG layer surrounds this block, not on top of it. NO text, letters, numbers, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Vertical chain of six hidden-state boxes with downward arrows and a small hourglass marker, in blueprint schematic style",
|
||||
"status": "Generated"
|
||||
},
|
||||
{
|
||||
"filename": "sublayer_block.png",
|
||||
"purpose": "Slide 10 left-third illustration — encoder/decoder sub-layer composition: outer frame, two inner sub-layers, residual arcs, LayerNorm stripes; modules carry conventional paper-figure labels",
|
||||
"type": "framework",
|
||||
"page_role": "local",
|
||||
"text_policy": "embedded",
|
||||
"aspect_ratio": "3:4",
|
||||
"image_size": "1K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid, with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to schematic forms — rounded rectangles, thin arcs, small horizontal stripes. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise. Color behavior is restrained-corporate: secondary off-white #F5F7FA fills about 60% of the block as background breathing space; primary deep navy #1A365D draws the outer frame, the inner sub-layer rectangles, and the stripes (about 30% area); accent blue #3182CE is used only on the two residual arcs to highlight them (under 8% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Framework-style local composition: a single large outer rounded rectangle frame represents one encoder/decoder layer block. Inside that frame, top-to-bottom, two inner stacked rounded rectangles — the upper one slightly taller, the lower one slightly shorter; they are separated by a small gap. Around each inner sub-layer, a thin curved arc in accent blue starts above the sub-layer, sweeps around its right side, and rejoins below it — these two arcs are the residual skip connections, the only accent-blue elements in the image. Below each inner sub-layer, a thin short horizontal stripe in primary navy suggests layer normalization. Each inner sub-layer rectangle carries one short module label rendered as clean monospace technical lettering (fixed-width, sharp letterforms, no serifs), centered inside the rectangle and sized to read as a discreet figure label — about 18-22px relative to the block. The exact label inside the upper (taller) sub-layer is the words Self-Attention; the exact label inside the lower (shorter) sub-layer is the words Feed Forward. Below each LayerNorm stripe sits one tiny annotation in the same monospace lettering, smaller (about 12-14px), in primary navy, reading exactly Add & Norm. These four short labels (Self-Attention, Feed Forward, Add & Norm, Add & Norm) are the ONLY text in the image — no other letters, no numbers, no signs, no watermarks anywhere else. The entire schematic is centered inside the block with about 14% inner padding on all sides. Composed as a 480×600 vertical local block for placement inside an SVG page region; do NOT reserve calm overlay space inside the image — the SVG layer surrounds this block, not on top of it. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Encoder layer frame with two stacked labeled sub-layers (Self-Attention, Feed Forward), accent residual arcs, and Add & Norm stripes",
|
||||
"status": "Generated"
|
||||
},
|
||||
{
|
||||
"filename": "positional_encoding.png",
|
||||
"purpose": "Slide 11 hero — sinusoidal positional encoding visualization (two superimposed waveforms at different frequencies plus a discrete position axis below); textbook curve labels and axis label inside the image",
|
||||
"page_role": "hero_page",
|
||||
"text_policy": "embedded",
|
||||
"aspect_ratio": "16:9",
|
||||
"image_size": "2K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Curves are precisely drawn smooth sine and cosine waveforms with uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise, reads as a technical figure from a textbook chapter on Fourier features. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 58% of the canvas as breathing field; primary deep navy #1A365D draws the slower (longer wavelength, gentle undulation) sine curve and the tick marks (about 30% area); accent blue #3182CE draws the faster (shorter wavelength, tighter undulation) cosine curve and three thin vertical guide-lines that drop from the waveforms down to the position axis (under 12% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Custom composition — the left third of the canvas is deliberately calm as breathing space reserved for a page title overlay in SVG. Across the right two-thirds of the canvas, two superimposed sinusoidal waveforms run horizontally: the primary-navy sine curve has a long wavelength spanning roughly two full cycles across the available width with gentle undulation; the accent-blue cosine curve runs at higher frequency completing roughly five full cycles across the same width with tighter undulation; the two curves visibly cross several times. Below the waveforms, a horizontal row of ten small evenly-spaced tick marks in primary navy marks discrete token positions on a position axis represented by a thin horizontal line. Three thin vertical accent-blue guide lines drop from selected points on the waveforms straight down to corresponding ticks on the position axis, suggesting that each token position carries a unique pair of sine and cosine values. Curve labels and one axis label are rendered inside the image as clean monospace technical lettering (fixed-width, sharp letterforms, no serifs, about 22-26px relative to canvas). The exact text is, in three places only: near the right end of the navy sine curve, the lowercase word sin in primary navy #1A365D; near the right end of the accent-blue cosine curve, the lowercase word cos in accent blue #3182CE; just below the right end of the position-axis line, the lowercase phrase position → in primary navy. These three short labels (sin, cos, position →) are the ONLY text in the image — no other letters, no numbers, no axis tick numbers, no signs, no watermarks anywhere else. Composed as a 1280×720 PPT 16:9 hero background; the left third must remain calm for SVG title overlay. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Sine and cosine sinusoidal waveforms with sin/cos curve labels and a position arrow axis label, blueprint schematic",
|
||||
"status": "Generated"
|
||||
},
|
||||
{
|
||||
"filename": "transformer_family.png",
|
||||
"purpose": "Slide 16 hero — faded Transformer descendants tree backdrop (root + two intermediate branches + many small leaf shapes); calm middle band reserved for SVG closing title",
|
||||
"page_role": "hero_page",
|
||||
"text_policy": "none",
|
||||
"aspect_ratio": "16:9",
|
||||
"image_size": "2K",
|
||||
"prompt": "Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Elements are simplified to schematic forms — rounded rectangles and small abstract leaf shapes connected by thin straight lines. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise. The entire schematic is rendered at low opacity around 35% so it reads as a faded backdrop. Color behavior is restrained-corporate: secondary off-white #F5F7FA dominates the canvas as breathing space (about 68% area); primary deep navy #1A365D draws the root rectangle, the two intermediate rectangles, the descendant leaf shapes, and all connector lines (about 27% area, all rendered at ~35% opacity to fade); accent blue #3182CE outlines only the root rectangle and one selected leaf in full opacity (under 5% area), marking the genealogical anchor and one focal descendant; no fourth color. A subtle 6% opacity navy grid sits beneath everything. Custom composition — a symmetric top-down tree-of-descendants schematic occupies the upper third and lower third of the canvas with the middle horizontal band of the canvas (roughly 30% of canvas height across the full width) deliberately calm as breathing space reserved for a closing title overlay in SVG. Tree structure: at the top center, one single rounded rectangle slightly larger than the rest (the root Transformer) outlined in accent blue at full opacity. From the root, thin lines fan downward across the calm middle band and emerge in the lower third, branching to two intermediate rounded rectangles set symmetrically left and right (suggesting encoder-only and decoder-only families). From each intermediate, three to four thinner branches drop further down to small abstract leaf shapes of varying small sizes (suggesting the multitude of derived models). All elements other than the root and one selected leaf are rendered in primary navy at 35% opacity. Reads as a quiet 'what this paper started' diagram. Composed as a 1280×720 PPT 16:9 hero background; the middle horizontal band must remain calm for SVG closing title overlay. NO text, letters, numbers, model names, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.",
|
||||
"alt_text": "Faded blueprint tree of Transformer descendants with accent-blue root and one accent leaf, calm middle band reserved",
|
||||
"status": "Generated"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
# Image Generation Prompts
|
||||
|
||||
> Auto-generated from `image_prompts.json` by `image_gen.py --render-md`.
|
||||
> Do not hand-edit — re-run the command to refresh.
|
||||
|
||||
> Project: attention_is_all_you_need
|
||||
> Generated: 2026-05-24
|
||||
> Color scheme: Primary #1A365D | Secondary #F5F7FA | Accent #3182CE
|
||||
|
||||
---
|
||||
|
||||
### Image 1: cover_bg.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Cover background (Slide 01) — hero atmospheric blueprint of a generic Transformer-like module graph, calm left side reserved for SVG title overlay |
|
||||
| Aspect ratio | 16:9 |
|
||||
| Image size | 2K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to essential schematic forms — rounded rectangular module blocks, connector lines, anchor dots, callout markers. Color is restrained, near-monochrome with one semantic accent. A subtle grid background at 6% opacity reinforces the schematic feel. No textures, no shading, no painterly artifacts; engineering-precise, analytical, intentional. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 65% of the canvas as calm breathing space; primary deep navy #1A365D forms the precise schematic linework (about 28% area) — outlines of module blocks, connector lines, anchor dots; accent blue #3182CE appears only as one highlighted module outline and a couple of arrowheads on the focal connector path, together under 7% of the area; no fourth color. Atmospheric blueprint backdrop with no dominant subject — a graph of six rounded rectangular module blocks arranged in two stacked horizontal rows of three (an encoder-stack row at the bottom and a decoder-stack row at the top), connected by precise straight lines with small triangular arrow heads. The blocks are deliberately small and clustered on the right side of the canvas, leaving the left third entirely calm as breathing space — that calm region must stay clear of any schematic element. One block on the upper row is highlighted by replacing its primary navy outline with an accent-blue outline, marking it as the focal self-attention module. Faint vertical and horizontal hairlines suggest a measurement grid only at 6% opacity beneath everything. Composed as a 1280×720 PPT 16:9 full-bleed cover background. Reads as the title plate of a systems-design briefing document. NO text, letters, numbers, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Abstract Transformer-like module graph rendered in technical blueprint style, calm left third reserved for title
|
||||
|
||||
---
|
||||
|
||||
### Image 2: sequence_evolution.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Slide 03 hero — three schematic motifs side by side suggesting RNN chain / convolutional local field / global self-attention mesh, each motif carries its panel label inside the image |
|
||||
| Aspect ratio | 16:9 |
|
||||
| Image size | 2K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Elements are simplified to essential schematic forms — small filled circles for nodes, thin straight lines for connections, small triangular arrow heads on directed edges. Crisp uniform stroke around 1.5px, perfectly straight or precisely curved. No textures, no shading, no painterly artifacts. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 62% of the canvas as calm breathing space; primary deep navy #1A365D carries the bulk of the linework (about 28% area, including the leftmost and middle motifs); accent blue #3182CE appears only in the rightmost motif (under 10% area), marking it as the focus. A subtle 6% opacity navy grid sits beneath everything. Custom composition — three equal-width schematic motifs sit side by side across the lower two-thirds of the canvas, separated by 2px hairline rules in border-gray; the upper third of the canvas is deliberately calm as breathing space for a page title overlay in SVG. Leftmost motif: a horizontal chain of five small filled circles flowing left to right, connected by single arrows between adjacent circles, suggesting recurrent step-by-step computation. Middle motif: three short parallel horizontal rows of four small circles each, each circle connected to the two circles diagonally below it in the next row by short straight lines, suggesting convolutional local receptive fields. Rightmost motif: five circles arranged in a regular pentagon, every circle connected to every other circle by thin straight lines forming a fully-connected mesh, suggesting global self-attention — this entire mesh is rendered in accent blue #3182CE while the first two motifs stay in primary navy. Above each of the three motifs sits one short panel label, rendered as clean monospace technical lettering (fixed-width, sharp uppercase, no serifs), small enough to read as a discreet figure-panel header — about 28-32px high relative to the canvas. The exact label text, left to right, is: above the leftmost motif the word RNN; above the middle motif the word CNN; above the rightmost motif the words SELF-ATTENTION. Labels above the first two motifs are in primary deep navy #1A365D; the SELF-ATTENTION label above the rightmost motif is in accent blue #3182CE matching its mesh. The three panel labels are the ONLY text in the image; no other letters, no axis labels, no captions, no signs, no watermarks anywhere else. Composed as a 1280×720 PPT 16:9 hero background; the upper third (above the panel labels) must remain calm for SVG title overlay. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Three labeled schematic motifs (RNN / CNN / SELF-ATTENTION) comparing recurrent chain, convolutional local fields, and global self-attention mesh
|
||||
|
||||
---
|
||||
|
||||
### Image 3: rnn_bottleneck.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Slide 04 right-third illustration — sequential RNN computation bottleneck (vertical chain of hidden states with an hourglass cue) |
|
||||
| Type | flowchart |
|
||||
| Aspect ratio | 3:4 |
|
||||
| Image size | 1K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid, with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to schematic forms — small rounded rectangles, thin straight arrows, an hourglass marker. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise, restrained. Color behavior is restrained-corporate: secondary off-white #F5F7FA fills about 60% of the block as background breathing; primary deep navy #1A365D forms the chain of hidden-state boxes and the connecting arrows (about 32% area); accent blue #3182CE is used only for the hourglass marker and one small focus highlight (under 8% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Flowchart-style local composition: a vertical chain of six small identical rounded rectangles stacked one above the other, each connected to the next by a thin downward-pointing arrow with a small triangular arrow head; each rectangle represents a hidden state at one time step. To the right of the chain, a small hourglass marker in accent blue floats alongside the middle of the chain, suggesting sequential time cost. To the left of the chain, two faint dashed parallel vertical lines hint at the channels that cannot be parallelized — they are dashed, in primary navy at 50% opacity. The entire schematic is centered inside the block with about 14% inner padding on all sides. Composed as a 480×600 vertical local block for placement inside an SVG page region; do NOT reserve calm overlay space inside the image — the SVG layer surrounds this block, not on top of it. NO text, letters, numbers, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Vertical chain of six hidden-state boxes with downward arrows and a small hourglass marker, in blueprint schematic style
|
||||
|
||||
---
|
||||
|
||||
### Image 4: sublayer_block.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Slide 10 left-third illustration — encoder/decoder sub-layer composition: outer frame, two inner sub-layers, residual arcs, LayerNorm stripes; modules carry conventional paper-figure labels |
|
||||
| Type | framework |
|
||||
| Aspect ratio | 3:4 |
|
||||
| Image size | 1K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid, with deliberate geometric rigor — right angles, parallel rules, measured spacing. Elements are simplified to schematic forms — rounded rectangles, thin arcs, small horizontal stripes. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise. Color behavior is restrained-corporate: secondary off-white #F5F7FA fills about 60% of the block as background breathing space; primary deep navy #1A365D draws the outer frame, the inner sub-layer rectangles, and the stripes (about 30% area); accent blue #3182CE is used only on the two residual arcs to highlight them (under 8% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Framework-style local composition: a single large outer rounded rectangle frame represents one encoder/decoder layer block. Inside that frame, top-to-bottom, two inner stacked rounded rectangles — the upper one slightly taller, the lower one slightly shorter; they are separated by a small gap. Around each inner sub-layer, a thin curved arc in accent blue starts above the sub-layer, sweeps around its right side, and rejoins below it — these two arcs are the residual skip connections, the only accent-blue elements in the image. Below each inner sub-layer, a thin short horizontal stripe in primary navy suggests layer normalization. Each inner sub-layer rectangle carries one short module label rendered as clean monospace technical lettering (fixed-width, sharp letterforms, no serifs), centered inside the rectangle and sized to read as a discreet figure label — about 18-22px relative to the block. The exact label inside the upper (taller) sub-layer is the words Self-Attention; the exact label inside the lower (shorter) sub-layer is the words Feed Forward. Below each LayerNorm stripe sits one tiny annotation in the same monospace lettering, smaller (about 12-14px), in primary navy, reading exactly Add & Norm. These four short labels (Self-Attention, Feed Forward, Add & Norm, Add & Norm) are the ONLY text in the image — no other letters, no numbers, no signs, no watermarks anywhere else. The entire schematic is centered inside the block with about 14% inner padding on all sides. Composed as a 480×600 vertical local block for placement inside an SVG page region; do NOT reserve calm overlay space inside the image — the SVG layer surrounds this block, not on top of it. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Encoder layer frame with two stacked labeled sub-layers (Self-Attention, Feed Forward), accent residual arcs, and Add & Norm stripes
|
||||
|
||||
---
|
||||
|
||||
### Image 5: positional_encoding.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Slide 11 hero — sinusoidal positional encoding visualization (two superimposed waveforms at different frequencies plus a discrete position axis below); textbook curve labels and axis label inside the image |
|
||||
| Aspect ratio | 16:9 |
|
||||
| Image size | 2K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Curves are precisely drawn smooth sine and cosine waveforms with uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise, reads as a technical figure from a textbook chapter on Fourier features. Color behavior is restrained-corporate: secondary off-white #F5F7FA carries about 58% of the canvas as breathing field; primary deep navy #1A365D draws the slower (longer wavelength, gentle undulation) sine curve and the tick marks (about 30% area); accent blue #3182CE draws the faster (shorter wavelength, tighter undulation) cosine curve and three thin vertical guide-lines that drop from the waveforms down to the position axis (under 12% area); no fourth color. A subtle 6% opacity navy grid sits beneath everything. Custom composition — the left third of the canvas is deliberately calm as breathing space reserved for a page title overlay in SVG. Across the right two-thirds of the canvas, two superimposed sinusoidal waveforms run horizontally: the primary-navy sine curve has a long wavelength spanning roughly two full cycles across the available width with gentle undulation; the accent-blue cosine curve runs at higher frequency completing roughly five full cycles across the same width with tighter undulation; the two curves visibly cross several times. Below the waveforms, a horizontal row of ten small evenly-spaced tick marks in primary navy marks discrete token positions on a position axis represented by a thin horizontal line. Three thin vertical accent-blue guide lines drop from selected points on the waveforms straight down to corresponding ticks on the position axis, suggesting that each token position carries a unique pair of sine and cosine values. Curve labels and one axis label are rendered inside the image as clean monospace technical lettering (fixed-width, sharp letterforms, no serifs, about 22-26px relative to canvas). The exact text is, in three places only: near the right end of the navy sine curve, the lowercase word sin in primary navy #1A365D; near the right end of the accent-blue cosine curve, the lowercase word cos in accent blue #3182CE; just below the right end of the position-axis line, the lowercase phrase position → in primary navy. These three short labels (sin, cos, position →) are the ONLY text in the image — no other letters, no numbers, no axis tick numbers, no signs, no watermarks anywhere else. Composed as a 1280×720 PPT 16:9 hero background; the left third must remain calm for SVG title overlay. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Sine and cosine sinusoidal waveforms with sin/cos curve labels and a position arrow axis label, blueprint schematic
|
||||
|
||||
---
|
||||
|
||||
### Image 6: transformer_family.png
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Purpose | Slide 16 hero — faded Transformer descendants tree backdrop (root + two intermediate branches + many small leaf shapes); calm middle band reserved for SVG closing title |
|
||||
| Aspect ratio | 16:9 |
|
||||
| Image size | 2K |
|
||||
| Status | Generated |
|
||||
|
||||
**Prompt**:
|
||||
|
||||
Technical blueprint schematic style. Clean precise lines on a very subtle implied grid. Elements are simplified to schematic forms — rounded rectangles and small abstract leaf shapes connected by thin straight lines. Crisp uniform stroke around 1.5px. No textures, no shading, no painterly artifacts; engineering-precise. The entire schematic is rendered at low opacity around 35% so it reads as a faded backdrop. Color behavior is restrained-corporate: secondary off-white #F5F7FA dominates the canvas as breathing space (about 68% area); primary deep navy #1A365D draws the root rectangle, the two intermediate rectangles, the descendant leaf shapes, and all connector lines (about 27% area, all rendered at ~35% opacity to fade); accent blue #3182CE outlines only the root rectangle and one selected leaf in full opacity (under 5% area), marking the genealogical anchor and one focal descendant; no fourth color. A subtle 6% opacity navy grid sits beneath everything. Custom composition — a symmetric top-down tree-of-descendants schematic occupies the upper third and lower third of the canvas with the middle horizontal band of the canvas (roughly 30% of canvas height across the full width) deliberately calm as breathing space reserved for a closing title overlay in SVG. Tree structure: at the top center, one single rounded rectangle slightly larger than the rest (the root Transformer) outlined in accent blue at full opacity. From the root, thin lines fan downward across the calm middle band and emerge in the lower third, branching to two intermediate rounded rectangles set symmetrically left and right (suggesting encoder-only and decoder-only families). From each intermediate, three to four thinner branches drop further down to small abstract leaf shapes of varying small sizes (suggesting the multitude of derived models). All elements other than the root and one selected leaf are rendered in primary navy at 35% opacity. Reads as a quiet 'what this paper started' diagram. Composed as a 1280×720 PPT 16:9 hero background; the middle horizontal band must remain calm for SVG closing title overlay. NO text, letters, numbers, model names, signs, watermarks, or written symbols anywhere in the image. Color values (HEX codes like #1A365D) and color names are rendering guidance only — do NOT display HEX codes, color names, or palette labels as visible text anywhere in the image.
|
||||
|
||||
**Alt Text**:
|
||||
> Faded blueprint tree of Transformer descendants with accent-blue root and one accent leaf, calm middle band reserved
|
||||
|
||||
---
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 751 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 721 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 579 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 633 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 561 KiB |
@@ -0,0 +1 @@
|
||||
Today we are reading what is probably the single most influential machine learning paper of the last decade: Attention Is All You Need, by Vaswani and seven coauthors at Google Brain, Google Research, and the University of Toronto, presented at NeurIPS 2017. The title is the thesis: drop recurrence and convolution, use only attention, and you get a model that is faster to train, easier to parallelize, and stronger on machine translation than anything that came before. Over the next sixteen slides we'll walk through what the Transformer actually is, how the attention mechanism works, why the authors chose this design, and what the experiments showed.
|
||||
@@ -0,0 +1 @@
|
||||
Before we get into the architecture, let's see what the paper is actually claiming. On the WMT 2014 English to German translation task, the Transformer big model scored 28.4 BLEU, beating the previous best ensemble by two full points as a single model. On WMT 2014 English to French, it set a new single-model state of the art at 41.8 BLEU. And it did all this by training for three and a half days on eight P100 GPUs — a small fraction of the cost of the strong baselines. The architecture has no recurrence and no convolution; it is built entirely from attention and feed-forward layers. Quality up, cost down, parallelization unlocked.
|
||||
@@ -0,0 +1 @@
|
||||
To appreciate the move, it helps to look at where sequence modeling was sitting in 2017. Recurrent networks — RNNs, LSTMs, GRUs — were the default, but they compute step by step and resist parallelization. Convolutional alternatives like ByteNet and ConvS2S could parallelize, but signals between distant positions still had to travel through many layers, growing linearly or logarithmically with distance. Self-attention does something different: every position relates to every other position in one constant-time hop. Visually you can think of it as moving from a chain to a local field to a fully connected mesh — and that mesh is what the Transformer leans into.
|
||||
@@ -0,0 +1 @@
|
||||
Let's name the constraints the authors are trying to lift. First, the sequential bottleneck: in any RNN, hidden state at time t depends on hidden state at t minus one, so you cannot parallelize within a single training example. Second, long-range path length: distant tokens have to be related through many intermediate operations, which makes learning long-range dependencies hard. Third, memory ceiling: long sequences eat GPU memory, capping batch size and throughput. The Transformer attacks all three at once by replacing the entire backbone with attention.
|
||||
@@ -0,0 +1 @@
|
||||
This is figure one from the paper — the Transformer architecture. Read it from the bottom up. Inputs and outputs both come in as embeddings, with a sinusoidal positional encoding added. The encoder on the left is a stack of six identical layers; each layer has multi-head self-attention followed by a position-wise feed-forward network, with Add and Norm wrapping each sub-layer. The decoder on the right is also six layers, but inserts a third sub-layer that attends back to the encoder output, and its self-attention is masked so it cannot peek at future tokens. The whole thing ends with a linear projection and softmax to produce token probabilities. The skeleton is the same as prior seq2seq models — what is new is what fills the boxes.
|
||||
@@ -0,0 +1 @@
|
||||
Let's compare the encoder and decoder side by side. The encoder has two sub-layers per block: multi-head self-attention, then a position-wise feed-forward network. The decoder has three: masked multi-head self-attention, then encoder-decoder attention, then the feed-forward network. Around every sub-layer the same wrapper applies — output equals LayerNorm of x plus Sublayer of x, the classic residual connection plus normalization. All sub-layers and embeddings emit a 512-dimensional vector so the residual addition is well-defined. The three asymmetries on the decoder side are the third sub-layer, the causal mask that preserves auto-regression, and the one-position shift of the output embeddings.
|
||||
@@ -0,0 +1 @@
|
||||
Here is the heart of the model — scaled dot-product attention. You start with three matrices: queries Q, keys K, and values V. You compute the dot product of every query with every key, scale by the square root of the key dimension, apply a row-wise softmax to get attention weights, and then multiply by V to produce the output. The scaling factor matters. For large key dimensions the dot products grow in magnitude, pushing the softmax into regions with vanishingly small gradients. Dividing by root d sub k counteracts that. Once you have the weights, the output is just a weighted average of the value vectors — that's all attention is.
|
||||
@@ -0,0 +1 @@
|
||||
Multi-head attention is the next move. Instead of running one attention function over the full 512-dimensional vectors, the authors split into h equals eight independent heads, each operating on 64-dimensional projections of Q, K, and V. The projections are learned, so each head can specialize on a different kind of relationship. The heads run in parallel, their outputs are concatenated, and a final linear projection maps back to 512. The total compute is roughly the same as a single full-dimensional head, but the model gains the ability to attend to different representation subspaces at different positions simultaneously.
|
||||
@@ -0,0 +1 @@
|
||||
The same attention mechanism shows up in three places in the Transformer, with three slightly different roles. In encoder self-attention, queries, keys, and values all come from the previous encoder layer; every source position attends to every other. In decoder masked self-attention, the same setup applies, but illegal future positions are set to minus infinity before the softmax, so position i attends only to positions less than or equal to i — that's how auto-regression is preserved. In encoder-decoder attention, queries come from the decoder while keys and values come from the encoder output, letting every decoder position retrieve relevant information from anywhere in the source sequence. One mechanism, three roles.
|
||||
@@ -0,0 +1 @@
|
||||
The supporting cast inside every layer is just three small ideas. The position-wise feed-forward network is two linear layers with a ReLU between, applied identically at every position, with an inner dimension of 2048. The residual connection adds the sub-layer's input back to its output, which keeps the gradient signal flowing through deep stacks. Layer normalization then standardizes across the feature dimension. Put them together and the output of every sub-layer is LayerNorm of x plus Sublayer of x. Nothing here is novel by itself — but composing them around attention is what makes the architecture trainable at depth.
|
||||
@@ -0,0 +1 @@
|
||||
Because there is no recurrence and no convolution, the model has no built-in notion of token order. The authors recover order with a deterministic sinusoidal positional encoding added to each input embedding. Even dimensions use a sine wave, odd dimensions use a cosine wave, and the wavelengths form a geometric progression from two pi up to ten thousand times two pi. The neat property is that for any fixed offset k, the encoding at position pos plus k is a linear function of the encoding at pos — so the model can easily learn to attend by relative position via a simple linear combination. Order is injected, not learned.
|
||||
@@ -0,0 +1 @@
|
||||
This is table one from the paper, and it is the strongest argument for self-attention. A self-attention layer pays O of n squared times d in compute, but in exchange every pair of positions is exactly one operation apart. A recurrent layer pays O of n times d squared, but it takes O of n sequential operations and the maximum path length between two positions is O of n. Convolutional layers fall in between. For typical NLP workloads where the sequence length is shorter than the representation dimension, self-attention is actually faster than recurrence — and the constant path length makes long-range dependencies far easier to learn.
|
||||
@@ -0,0 +1 @@
|
||||
A quick word on how this was trained. The base model trains in twelve hours on eight P100 GPUs in one machine; the big model trains in three and a half days on the same hardware. Batches were grouped by similar sequence length to keep about twenty-five thousand source and twenty-five thousand target tokens per batch. The optimizer is Adam with beta two pushed up to 0.98, and a custom learning rate schedule that warms up linearly for four thousand steps then decays as one over the square root of the step count. Regularization is dropout at 0.1 applied to every sub-layer output and to the sum of embedding and positional encoding, plus label smoothing of 0.1.
|
||||
@@ -0,0 +1 @@
|
||||
Here are the headline results — table two from the paper. The Transformer big scores 28.4 BLEU on English to German, beating the previous best ensemble by two full BLEU points as a single model. On English to French it scores 41.8, a new single-model state of the art. And it does all this with about 2.3 times 10 to the 19 training floating-point operations, which is well below most strong baselines. The base model alone, trained in twelve hours, already beats almost every prior published model. The combination of better quality and lower training cost is what made this paper land so hard.
|
||||
@@ -0,0 +1 @@
|
||||
The variation study in table three gives us five takeaways worth remembering. First, head count has a sweet spot: a single head loses about 0.9 BLEU compared to eight heads, but going to thirty-two also degrades. Second, the key dimension matters more than the value dimension — determining compatibility is the harder learning problem. Third, scaling up the model dimension and the depth consistently improves quality, so the architecture scales monotonically with capacity. Fourth, dropout is essential — removing it loses roughly half a BLEU to a full BLEU point even at p equals 0.1. Fifth, label smoothing slightly hurts perplexity but improves BLEU, which is a reminder to optimize for the metric you actually ship on.
|
||||
@@ -0,0 +1 @@
|
||||
To close — this 2017 paper turned out to be one of the most consequential architectural ideas in modern machine learning. The Transformer became the substrate for BERT, for GPT, for T5, for the Vision Transformer, for AlphaFold, for CLIP, for almost every large language model in production today, including the one talking to you right now. The core insight — that just attention, with no recurrence and no convolution, is the right inductive bias for sequence modeling — turned out to generalize far beyond translation, to almost every modality we work with. One paper, a generation of models.
|
||||
@@ -0,0 +1,93 @@
|
||||
# 01_cover
|
||||
|
||||
Today we are reading what is probably the single most influential machine learning paper of the last decade: Attention Is All You Need, by Vaswani and seven coauthors at Google Brain, Google Research, and the University of Toronto, presented at NeurIPS 2017. The title is the thesis: drop recurrence and convolution, use only attention, and you get a model that is faster to train, easier to parallelize, and stronger on machine translation than anything that came before. Over the next sixteen slides we'll walk through what the Transformer actually is, how the attention mechanism works, why the authors chose this design, and what the experiments showed.
|
||||
|
||||
---
|
||||
|
||||
# 02_why_it_matters
|
||||
|
||||
Before we get into the architecture, let's see what the paper is actually claiming. On the WMT 2014 English to German translation task, the Transformer big model scored 28.4 BLEU, beating the previous best ensemble by two full points as a single model. On WMT 2014 English to French, it set a new single-model state of the art at 41.8 BLEU. And it did all this by training for three and a half days on eight P100 GPUs — a small fraction of the cost of the strong baselines. The architecture has no recurrence and no convolution; it is built entirely from attention and feed-forward layers. Quality up, cost down, parallelization unlocked.
|
||||
|
||||
---
|
||||
|
||||
# 03_sequence_evolution
|
||||
|
||||
To appreciate the move, it helps to look at where sequence modeling was sitting in 2017. Recurrent networks — RNNs, LSTMs, GRUs — were the default, but they compute step by step and resist parallelization. Convolutional alternatives like ByteNet and ConvS2S could parallelize, but signals between distant positions still had to travel through many layers, growing linearly or logarithmically with distance. Self-attention does something different: every position relates to every other position in one constant-time hop. Visually you can think of it as moving from a chain to a local field to a fully connected mesh — and that mesh is what the Transformer leans into.
|
||||
|
||||
---
|
||||
|
||||
# 04_rnn_cnn_limits
|
||||
|
||||
Let's name the constraints the authors are trying to lift. First, the sequential bottleneck: in any RNN, hidden state at time t depends on hidden state at t minus one, so you cannot parallelize within a single training example. Second, long-range path length: distant tokens have to be related through many intermediate operations, which makes learning long-range dependencies hard. Third, memory ceiling: long sequences eat GPU memory, capping batch size and throughput. The Transformer attacks all three at once by replacing the entire backbone with attention.
|
||||
|
||||
---
|
||||
|
||||
# 05_architecture_overview
|
||||
|
||||
This is figure one from the paper — the Transformer architecture. Read it from the bottom up. Inputs and outputs both come in as embeddings, with a sinusoidal positional encoding added. The encoder on the left is a stack of six identical layers; each layer has multi-head self-attention followed by a position-wise feed-forward network, with Add and Norm wrapping each sub-layer. The decoder on the right is also six layers, but inserts a third sub-layer that attends back to the encoder output, and its self-attention is masked so it cannot peek at future tokens. The whole thing ends with a linear projection and softmax to produce token probabilities. The skeleton is the same as prior seq2seq models — what is new is what fills the boxes.
|
||||
|
||||
---
|
||||
|
||||
# 06_encoder_decoder
|
||||
|
||||
Let's compare the encoder and decoder side by side. The encoder has two sub-layers per block: multi-head self-attention, then a position-wise feed-forward network. The decoder has three: masked multi-head self-attention, then encoder-decoder attention, then the feed-forward network. Around every sub-layer the same wrapper applies — output equals LayerNorm of x plus Sublayer of x, the classic residual connection plus normalization. All sub-layers and embeddings emit a 512-dimensional vector so the residual addition is well-defined. The three asymmetries on the decoder side are the third sub-layer, the causal mask that preserves auto-regression, and the one-position shift of the output embeddings.
|
||||
|
||||
---
|
||||
|
||||
# 07_scaled_dot_product
|
||||
|
||||
Here is the heart of the model — scaled dot-product attention. You start with three matrices: queries Q, keys K, and values V. You compute the dot product of every query with every key, scale by the square root of the key dimension, apply a row-wise softmax to get attention weights, and then multiply by V to produce the output. The scaling factor matters. For large key dimensions the dot products grow in magnitude, pushing the softmax into regions with vanishingly small gradients. Dividing by root d sub k counteracts that. Once you have the weights, the output is just a weighted average of the value vectors — that's all attention is.
|
||||
|
||||
---
|
||||
|
||||
# 08_multi_head_attention
|
||||
|
||||
Multi-head attention is the next move. Instead of running one attention function over the full 512-dimensional vectors, the authors split into h equals eight independent heads, each operating on 64-dimensional projections of Q, K, and V. The projections are learned, so each head can specialize on a different kind of relationship. The heads run in parallel, their outputs are concatenated, and a final linear projection maps back to 512. The total compute is roughly the same as a single full-dimensional head, but the model gains the ability to attend to different representation subspaces at different positions simultaneously.
|
||||
|
||||
---
|
||||
|
||||
# 09_three_uses
|
||||
|
||||
The same attention mechanism shows up in three places in the Transformer, with three slightly different roles. In encoder self-attention, queries, keys, and values all come from the previous encoder layer; every source position attends to every other. In decoder masked self-attention, the same setup applies, but illegal future positions are set to minus infinity before the softmax, so position i attends only to positions less than or equal to i — that's how auto-regression is preserved. In encoder-decoder attention, queries come from the decoder while keys and values come from the encoder output, letting every decoder position retrieve relevant information from anywhere in the source sequence. One mechanism, three roles.
|
||||
|
||||
---
|
||||
|
||||
# 10_ffn_residual_layernorm
|
||||
|
||||
The supporting cast inside every layer is just three small ideas. The position-wise feed-forward network is two linear layers with a ReLU between, applied identically at every position, with an inner dimension of 2048. The residual connection adds the sub-layer's input back to its output, which keeps the gradient signal flowing through deep stacks. Layer normalization then standardizes across the feature dimension. Put them together and the output of every sub-layer is LayerNorm of x plus Sublayer of x. Nothing here is novel by itself — but composing them around attention is what makes the architecture trainable at depth.
|
||||
|
||||
---
|
||||
|
||||
# 11_positional_encoding
|
||||
|
||||
Because there is no recurrence and no convolution, the model has no built-in notion of token order. The authors recover order with a deterministic sinusoidal positional encoding added to each input embedding. Even dimensions use a sine wave, odd dimensions use a cosine wave, and the wavelengths form a geometric progression from two pi up to ten thousand times two pi. The neat property is that for any fixed offset k, the encoding at position pos plus k is a linear function of the encoding at pos — so the model can easily learn to attend by relative position via a simple linear combination. Order is injected, not learned.
|
||||
|
||||
---
|
||||
|
||||
# 12_complexity_table
|
||||
|
||||
This is table one from the paper, and it is the strongest argument for self-attention. A self-attention layer pays O of n squared times d in compute, but in exchange every pair of positions is exactly one operation apart. A recurrent layer pays O of n times d squared, but it takes O of n sequential operations and the maximum path length between two positions is O of n. Convolutional layers fall in between. For typical NLP workloads where the sequence length is shorter than the representation dimension, self-attention is actually faster than recurrence — and the constant path length makes long-range dependencies far easier to learn.
|
||||
|
||||
---
|
||||
|
||||
# 13_training_setup
|
||||
|
||||
A quick word on how this was trained. The base model trains in twelve hours on eight P100 GPUs in one machine; the big model trains in three and a half days on the same hardware. Batches were grouped by similar sequence length to keep about twenty-five thousand source and twenty-five thousand target tokens per batch. The optimizer is Adam with beta two pushed up to 0.98, and a custom learning rate schedule that warms up linearly for four thousand steps then decays as one over the square root of the step count. Regularization is dropout at 0.1 applied to every sub-layer output and to the sum of embedding and positional encoding, plus label smoothing of 0.1.
|
||||
|
||||
---
|
||||
|
||||
# 14_results
|
||||
|
||||
Here are the headline results — table two from the paper. The Transformer big scores 28.4 BLEU on English to German, beating the previous best ensemble by two full BLEU points as a single model. On English to French it scores 41.8, a new single-model state of the art. And it does all this with about 2.3 times 10 to the 19 training floating-point operations, which is well below most strong baselines. The base model alone, trained in twelve hours, already beats almost every prior published model. The combination of better quality and lower training cost is what made this paper land so hard.
|
||||
|
||||
---
|
||||
|
||||
# 15_ablations
|
||||
|
||||
The variation study in table three gives us five takeaways worth remembering. First, head count has a sweet spot: a single head loses about 0.9 BLEU compared to eight heads, but going to thirty-two also degrades. Second, the key dimension matters more than the value dimension — determining compatibility is the harder learning problem. Third, scaling up the model dimension and the depth consistently improves quality, so the architecture scales monotonically with capacity. Fourth, dropout is essential — removing it loses roughly half a BLEU to a full BLEU point even at p equals 0.1. Fifth, label smoothing slightly hurts perplexity but improves BLEU, which is a reminder to optimize for the metric you actually ship on.
|
||||
|
||||
---
|
||||
|
||||
# 16_conclusion
|
||||
|
||||
To close — this 2017 paper turned out to be one of the most consequential architectural ideas in modern machine learning. The Transformer became the substrate for BERT, for GPT, for T5, for the Vision Transformer, for AlphaFold, for CLIP, for almost every large language model in production today, including the one talking to you right now. The core insight — that just attention, with no recurrence and no convolution, is the right inductive bias for sequence modeling — turned out to generalize far beyond translation, to almost every modality we work with. One paper, a generation of models.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Execution Lock
|
||||
|
||||
## canvas
|
||||
- viewBox: 0 0 1280 720
|
||||
- format: PPT 16:9
|
||||
|
||||
## colors
|
||||
- bg: #FFFFFF
|
||||
- bg_secondary: #F5F7FA
|
||||
- primary: #1A365D
|
||||
- accent: #3182CE
|
||||
- secondary_accent: #63B3ED
|
||||
- text: #1A202C
|
||||
- text_secondary: #4A5568
|
||||
- text_tertiary: #A0AEC0
|
||||
- border: #E2E8F0
|
||||
- accent_tint: #EBF4FB
|
||||
- success: #2F855A
|
||||
- warning: #C53030
|
||||
- image_rendering: blueprint
|
||||
- image_palette: cool-corporate
|
||||
|
||||
## typography
|
||||
- font_family: Arial, "Microsoft YaHei", "PingFang SC", sans-serif
|
||||
- title_family: Georgia, "Microsoft YaHei", serif
|
||||
- body_family: Arial, "Microsoft YaHei", "PingFang SC", sans-serif
|
||||
- emphasis_family: Georgia, "Microsoft YaHei", serif
|
||||
- code_family: Consolas, "Courier New", monospace
|
||||
- body: 20
|
||||
- title: 36
|
||||
- subtitle: 26
|
||||
- annotation: 14
|
||||
- footnote: 11
|
||||
- cover_title: 64
|
||||
- chapter_title: 44
|
||||
- hero_number: 40
|
||||
|
||||
## icons
|
||||
- library: tabler-outline
|
||||
- stroke_width: 2
|
||||
- inventory: trophy, bolt, stack-2, brain, refresh, arrow-right, lock, hourglass, box, eye, grid-dots, wave-sine, chart-bar, cpu, settings, binary-tree
|
||||
|
||||
## images
|
||||
- cover_bg: images/cover_bg.png
|
||||
- sequence_evolution: images/sequence_evolution.png
|
||||
- rnn_bottleneck: images/rnn_bottleneck.png
|
||||
- sublayer_block: images/sublayer_block.png
|
||||
- positional_encoding: images/positional_encoding.png
|
||||
- transformer_family: images/transformer_family.png
|
||||
- attention_p3_0: images/attention_p3_0.png | no-crop
|
||||
- attention_p4_1: images/attention_p4_1.png | no-crop
|
||||
- formula_001: images/formula_001.png | no-crop
|
||||
- formula_002: images/formula_002.png | no-crop
|
||||
- formula_003: images/formula_003.png | no-crop
|
||||
|
||||
## page_rhythm
|
||||
- P01: anchor
|
||||
- P02: dense
|
||||
- P03: breathing
|
||||
- P04: dense
|
||||
- P05: dense
|
||||
- P06: dense
|
||||
- P07: dense
|
||||
- P08: dense
|
||||
- P09: dense
|
||||
- P10: dense
|
||||
- P11: breathing
|
||||
- P12: dense
|
||||
- P13: dense
|
||||
- P14: dense
|
||||
- P15: dense
|
||||
- P16: anchor
|
||||
|
||||
## page_charts
|
||||
- P02: kpi_cards
|
||||
- P04: vertical_pillars
|
||||
- P06: comparison_columns
|
||||
- P09: vertical_pillars
|
||||
- P10: module_composition
|
||||
- P12: basic_table
|
||||
- P13: kpi_cards
|
||||
- P14: basic_table
|
||||
- P15: vertical_list
|
||||
|
||||
## forbidden
|
||||
- Mixing icon libraries
|
||||
- rgba()
|
||||
- `<style>`, `class`, `<foreignObject>`, `textPath`, `@font-face`, `<animate*>`, `<script>`, `<iframe>`, `<symbol>`+`<use>`
|
||||
- `<g opacity>` (set opacity on each child element individually)
|
||||
- HTML named entities in text — write as raw Unicode; XML reserved chars `& < > " '` escaped as `& < > " '`
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 905 KiB |
@@ -0,0 +1,132 @@
|
||||
<?xml version='1.0' encoding='UTF-8'?>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" width="1280" height="720">
|
||||
<defs>
|
||||
<filter id="cardShadow" x="-10%" y="-10%" width="120%" height="120%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="4" />
|
||||
<feOffset dx="0" dy="3" />
|
||||
<feFlood flood-color="#1A365D" flood-opacity="0.07" />
|
||||
<feComposite in2="SourceAlpha" operator="in" />
|
||||
<feMerge><feMergeNode /><feMergeNode in="SourceGraphic" /></feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<g id="bg">
|
||||
<rect width="1280" height="720" fill="#FFFFFF" />
|
||||
</g>
|
||||
|
||||
<g id="header">
|
||||
<rect x="60" y="56" width="6" height="40" fill="#3182CE" />
|
||||
<text x="84" y="88" font-family="Georgia, "Microsoft YaHei", serif" font-size="36" font-weight="700" fill="#1A365D">A simpler model, better results, less training</text>
|
||||
<text x="84" y="118" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1.5">WHY THIS PAPER MATTERS · 2017 SOTA ON WMT'14 TRANSLATION</text>
|
||||
</g>
|
||||
|
||||
<g id="kpi-bleu-ende">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M72,160 H333 A12,12 0 0 1 345,172 V388 A12,12 0 0 1 333,400 H72 A12,12 0 0 1 60,388 V172 A12,12 0 0 1 72,160 Z" />
|
||||
<path fill="#1A365D" d="M63,160 H63 A3,3 0 0 1 66,163 V397 A3,3 0 0 1 63,400 H63 A3,3 0 0 1 60,397 V163 A3,3 0 0 1 63,160 Z" />
|
||||
|
||||
<g transform="translate(80.0, 184.0) scale(1.3333333333333333)" fill="none" stroke="#1A365D" stroke-width="2">
|
||||
<path d="M8 21l8 0" />
|
||||
<path d="M12 17l0 4" />
|
||||
<path d="M7 4l10 0" />
|
||||
<path d="M17 4v8a5 5 0 0 1 -10 0v-8" />
|
||||
<path d="M3 9a2 2 0 1 0 4 0a2 2 0 1 0 -4 0" />
|
||||
<path d="M17 9a2 2 0 1 0 4 0a2 2 0 1 0 -4 0" />
|
||||
</g>
|
||||
<text x="80" y="246" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1">EN → DE</text>
|
||||
<text x="80" y="270" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#4A5568">BLEU on WMT'14</text>
|
||||
<text x="80" y="336" font-family="Georgia, "Microsoft YaHei", serif" font-size="64" font-weight="700" fill="#1A365D">28.4</text>
|
||||
|
||||
<g transform="translate(80.0, 354.0) scale(0.8333333333333334)" fill="none" stroke="#2F855A" stroke-width="2">
|
||||
<path d="M17 7l-10 10" />
|
||||
<path d="M8 7l9 0l0 9" />
|
||||
</g>
|
||||
<text x="106" y="370" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="16" font-weight="700" fill="#2F855A">+2.0</text>
|
||||
<text x="150" y="370" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">over prior ensembles</text>
|
||||
</g>
|
||||
|
||||
<g id="kpi-bleu-enfr">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M377,160 H638 A12,12 0 0 1 650,172 V388 A12,12 0 0 1 638,400 H377 A12,12 0 0 1 365,388 V172 A12,12 0 0 1 377,160 Z" />
|
||||
<path fill="#3182CE" d="M368,160 H368 A3,3 0 0 1 371,163 V397 A3,3 0 0 1 368,400 H368 A3,3 0 0 1 365,397 V163 A3,3 0 0 1 368,160 Z" />
|
||||
|
||||
<g transform="translate(385.0, 184.0) scale(1.3333333333333333)" fill="none" stroke="#3182CE" stroke-width="2">
|
||||
<path d="M8 21l8 0" />
|
||||
<path d="M12 17l0 4" />
|
||||
<path d="M7 4l10 0" />
|
||||
<path d="M17 4v8a5 5 0 0 1 -10 0v-8" />
|
||||
<path d="M3 9a2 2 0 1 0 4 0a2 2 0 1 0 -4 0" />
|
||||
<path d="M17 9a2 2 0 1 0 4 0a2 2 0 1 0 -4 0" />
|
||||
</g>
|
||||
<text x="385" y="246" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1">EN → FR</text>
|
||||
<text x="385" y="270" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#4A5568">BLEU on WMT'14</text>
|
||||
<text x="385" y="336" font-family="Georgia, "Microsoft YaHei", serif" font-size="64" font-weight="700" fill="#3182CE">41.8</text>
|
||||
|
||||
<g transform="translate(385.0, 354.0) scale(0.8333333333333334)" fill="none" stroke="#2F855A" stroke-width="2">
|
||||
<path d="M12 17.75l-6.172 3.245l1.179 -6.873l-5 -4.867l6.9 -1l3.086 -6.253l3.086 6.253l6.9 1l-5 4.867l1.179 6.873l-6.158 -3.245" />
|
||||
</g>
|
||||
<text x="411" y="370" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#2F855A">new single-model SOTA</text>
|
||||
</g>
|
||||
|
||||
<g id="kpi-training">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M682,160 H943 A12,12 0 0 1 955,172 V388 A12,12 0 0 1 943,400 H682 A12,12 0 0 1 670,388 V172 A12,12 0 0 1 682,160 Z" />
|
||||
<path fill="#1A365D" d="M673,160 H673 A3,3 0 0 1 676,163 V397 A3,3 0 0 1 673,400 H673 A3,3 0 0 1 670,397 V163 A3,3 0 0 1 673,160 Z" />
|
||||
|
||||
<g transform="translate(690.0, 184.0) scale(1.3333333333333333)" fill="none" stroke="#1A365D" stroke-width="2">
|
||||
<path d="M13 3l0 7l6 0l-8 11l0 -7l-6 0l8 -11" />
|
||||
</g>
|
||||
<text x="690" y="246" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1">TRAINING TIME</text>
|
||||
<text x="690" y="270" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#4A5568">Transformer (big)</text>
|
||||
<text x="690" y="336" font-family="Georgia, "Microsoft YaHei", serif" font-size="48" font-weight="700" fill="#1A365D">3.5 days</text>
|
||||
|
||||
<g transform="translate(690.0, 354.0) scale(0.8333333333333334)" fill="none" stroke="#4A5568" stroke-width="2">
|
||||
<path d="M5 6a1 1 0 0 1 1 -1h12a1 1 0 0 1 1 1v12a1 1 0 0 1 -1 1h-12a1 1 0 0 1 -1 -1l0 -12" />
|
||||
<path d="M9 9h6v6h-6l0 -6" />
|
||||
<path d="M3 10h2" />
|
||||
<path d="M3 14h2" />
|
||||
<path d="M10 3v2" />
|
||||
<path d="M14 3v2" />
|
||||
<path d="M21 10h-2" />
|
||||
<path d="M21 14h-2" />
|
||||
<path d="M14 21v-2" />
|
||||
<path d="M10 21v-2" />
|
||||
</g>
|
||||
<text x="716" y="370" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">on 8× P100 GPUs</text>
|
||||
</g>
|
||||
|
||||
<g id="kpi-no-rnn-cnn">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M987,160 H1208 A12,12 0 0 1 1220,172 V388 A12,12 0 0 1 1208,400 H987 A12,12 0 0 1 975,388 V172 A12,12 0 0 1 987,160 Z" />
|
||||
<path fill="#3182CE" d="M978,160 H978 A3,3 0 0 1 981,163 V397 A3,3 0 0 1 978,400 H978 A3,3 0 0 1 975,397 V163 A3,3 0 0 1 978,160 Z" />
|
||||
|
||||
<g transform="translate(995.0, 184.0) scale(1.3333333333333333)" fill="none" stroke="#3182CE" stroke-width="2">
|
||||
<path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" />
|
||||
<path d="M21 12c-2.4 4 -5.4 6 -9 6c-3.6 0 -6.6 -2 -9 -6c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6" />
|
||||
</g>
|
||||
<text x="995" y="246" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1">ARCHITECTURE</text>
|
||||
<text x="995" y="270" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#4A5568">building blocks</text>
|
||||
<text x="995" y="316" font-family="Georgia, "Microsoft YaHei", serif" font-size="40" font-weight="700" fill="#1A365D">Attention</text>
|
||||
<text x="995" y="346" font-family="Georgia, "Microsoft YaHei", serif" font-size="22" font-style="italic" fill="#4A5568">only</text>
|
||||
<text x="995" y="376" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">no recurrence · no convolution</text>
|
||||
</g>
|
||||
|
||||
<g id="takeaway-band">
|
||||
<path fill="#F5F7FA" stroke="#E2E8F0" stroke-width="1" d="M72,450 H1208 A12,12 0 0 1 1220,462 V598 A12,12 0 0 1 1208,610 H72 A12,12 0 0 1 60,598 V462 A12,12 0 0 1 72,450 Z" />
|
||||
<path fill="#1A365D" d="M63,450 H63 A3,3 0 0 1 66,453 V607 A3,3 0 0 1 63,610 H63 A3,3 0 0 1 60,607 V453 A3,3 0 0 1 63,450 Z" />
|
||||
<text x="100" y="490" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#3182CE" letter-spacing="1.5">THE HEADLINE</text>
|
||||
<text x="100" y="520" font-family="Georgia, "Microsoft YaHei", serif" font-size="22" font-weight="700" fill="#1A365D">
|
||||
The Transformer reaches <tspan fill="#3182CE">new translation SOTA</tspan> while training
|
||||
</text>
|
||||
<text x="100" y="548" font-family="Georgia, "Microsoft YaHei", serif" font-size="22" font-weight="700" fill="#1A365D">
|
||||
in <tspan fill="#3182CE">a fraction of the time</tspan> of strong baselines.
|
||||
</text>
|
||||
<text x="100" y="580" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="16" fill="#4A5568">
|
||||
Quality up · cost down · parallelization unlocked. The whole rest of the paper explains
|
||||
</text>
|
||||
<text x="100" y="602" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="16" fill="#4A5568">
|
||||
how attention alone makes this possible — and why nothing else is needed.
|
||||
</text>
|
||||
</g>
|
||||
|
||||
<g id="footer">
|
||||
<text x="60" y="694" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="11" fill="#A0AEC0">Source: Vaswani et al. 2017, Table 2 (BLEU) and §5.2 (training cost)</text>
|
||||
<text x="1220" y="694" text-anchor="end" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="11" fill="#A0AEC0">02</text>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.0 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 774 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 662 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 297 KiB |
@@ -0,0 +1,95 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" width="1280" height="720">
|
||||
<defs>
|
||||
<filter id="cardShadow" x="-10%" y="-10%" width="120%" height="120%">
|
||||
<feGaussianBlur in="SourceAlpha" stdDeviation="6" />
|
||||
<feOffset dx="0" dy="3" />
|
||||
<feFlood flood-color="#1A365D" flood-opacity="0.07" />
|
||||
<feComposite in2="SourceAlpha" operator="in" />
|
||||
<feMerge><feMergeNode /><feMergeNode in="SourceGraphic" /></feMerge>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<g id="bg">
|
||||
<rect width="1280" height="720" fill="#FFFFFF" />
|
||||
</g>
|
||||
|
||||
<g id="header">
|
||||
<rect x="60" y="56" width="6" height="40" fill="#3182CE" />
|
||||
<text x="84" y="88" font-family="Georgia, "Microsoft YaHei", serif" font-size="36" font-weight="700" fill="#1A365D">Same skeleton, three asymmetries</text>
|
||||
<text x="84" y="118" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#4A5568" letter-spacing="1.5">ENCODER STACK · DECODER STACK · N = 6 · d_model = 512</text>
|
||||
</g>
|
||||
|
||||
<g id="card-encoder">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M94,160 H621 A14,14 0 0 1 635,174 V646 A14,14 0 0 1 621,660 H94 A14,14 0 0 1 80,646 V174 A14,14 0 0 1 94,160 Z" />
|
||||
<path d="M 94 160 h 527 a 14 14 0 0 1 14 14 v 90 h -555 v -90 a 14 14 0 0 1 14 -14 Z" fill="#1A365D" />
|
||||
<text x="357" y="212" text-anchor="middle" font-family="Georgia, "Microsoft YaHei", serif" font-size="28" font-weight="700" fill="#FFFFFF">Encoder</text>
|
||||
<text x="357" y="240" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" font-weight="600" fill="#FFFFFF" fill-opacity="0.85" letter-spacing="1">N = 6 IDENTICAL LAYERS</text>
|
||||
|
||||
<g id="enc-sublayer-1">
|
||||
<path fill="#F5F7FA" stroke="#1A365D" stroke-width="1.5" d="M118,300 H597 A8,8 0 0 1 605,308 V348 A8,8 0 0 1 597,356 H118 A8,8 0 0 1 110,348 V308 A8,8 0 0 1 118,300 Z" />
|
||||
<circle cx="138" cy="328" r="14" fill="#1A365D" />
|
||||
<text x="138" y="334" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#FFFFFF">1</text>
|
||||
<text x="166" y="324" font-family="Georgia, "Microsoft YaHei", serif" font-size="17" font-weight="700" fill="#1A365D">Multi-Head Self-Attention</text>
|
||||
<text x="166" y="346" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">Every position attends to every position</text>
|
||||
</g>
|
||||
|
||||
<g id="enc-sublayer-2">
|
||||
<path fill="#F5F7FA" stroke="#1A365D" stroke-width="1.5" d="M118,372 H597 A8,8 0 0 1 605,380 V420 A8,8 0 0 1 597,428 H118 A8,8 0 0 1 110,420 V380 A8,8 0 0 1 118,372 Z" />
|
||||
<circle cx="138" cy="400" r="14" fill="#1A365D" />
|
||||
<text x="138" y="406" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#FFFFFF">2</text>
|
||||
<text x="166" y="396" font-family="Georgia, "Microsoft YaHei", serif" font-size="17" font-weight="700" fill="#1A365D">Position-wise Feed Forward</text>
|
||||
<text x="166" y="418" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">Two linear layers, ReLU between</text>
|
||||
</g>
|
||||
|
||||
<text x="110" y="466" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="12" font-weight="700" fill="#3182CE" letter-spacing="1.5">WRAPPER AROUND EACH SUB-LAYER</text>
|
||||
<text x="110" y="492" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="15" fill="#1A202C">Output = LayerNorm( x + Sublayer(x) )</text>
|
||||
<text x="110" y="514" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#4A5568">— residual connection then layer normalization.</text>
|
||||
|
||||
<path fill="#F5F7FA" d="M118,544 H597 A8,8 0 0 1 605,552 V616 A8,8 0 0 1 597,624 H118 A8,8 0 0 1 110,616 V552 A8,8 0 0 1 118,544 Z" />
|
||||
<text x="124" y="568" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="12" font-weight="700" fill="#1A365D" letter-spacing="1.5">SHAPE CONTRACT</text>
|
||||
<text x="124" y="592" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#1A202C">All sub-layers and embeddings emit dimension <tspan font-family="Consolas, monospace" fill="#3182CE" font-weight="700">d_model = 512</tspan></text>
|
||||
<text x="124" y="612" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#1A202C">so residual addition is well-defined.</text>
|
||||
</g>
|
||||
|
||||
<g id="card-decoder">
|
||||
<path fill="#FFFFFF" stroke="#E2E8F0" stroke-width="1.5" filter="url(#cardShadow)" d="M669,160 H1196 A14,14 0 0 1 1210,174 V646 A14,14 0 0 1 1196,660 H669 A14,14 0 0 1 655,646 V174 A14,14 0 0 1 669,160 Z" />
|
||||
<path d="M 669 160 h 527 a 14 14 0 0 1 14 14 v 90 h -555 v -90 a 14 14 0 0 1 14 -14 Z" fill="#3182CE" />
|
||||
<text x="932" y="212" text-anchor="middle" font-family="Georgia, "Microsoft YaHei", serif" font-size="28" font-weight="700" fill="#FFFFFF">Decoder</text>
|
||||
<text x="932" y="240" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" font-weight="600" fill="#FFFFFF" fill-opacity="0.9" letter-spacing="1">N = 6 IDENTICAL LAYERS · INSERTS A THIRD SUB-LAYER</text>
|
||||
|
||||
<g id="dec-sublayer-1">
|
||||
<path fill="#FFFFFF" stroke="#3182CE" stroke-width="1.5" d="M693,300 H1172 A8,8 0 0 1 1180,308 V348 A8,8 0 0 1 1172,356 H693 A8,8 0 0 1 685,348 V308 A8,8 0 0 1 693,300 Z" />
|
||||
<circle cx="713" cy="328" r="14" fill="#3182CE" />
|
||||
<text x="713" y="334" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#FFFFFF">1</text>
|
||||
<text x="741" y="324" font-family="Georgia, "Microsoft YaHei", serif" font-size="17" font-weight="700" fill="#1A365D"><tspan fill="#3182CE">Masked</tspan> Multi-Head Self-Attention</text>
|
||||
<text x="741" y="346" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">Position i attends only to positions ≤ i</text>
|
||||
</g>
|
||||
|
||||
<g id="dec-sublayer-2">
|
||||
<path fill="#FFFFFF" stroke="#3182CE" stroke-width="2.5" d="M693,372 H1172 A8,8 0 0 1 1180,380 V420 A8,8 0 0 1 1172,428 H693 A8,8 0 0 1 685,420 V380 A8,8 0 0 1 693,372 Z" />
|
||||
<circle cx="713" cy="400" r="14" fill="#3182CE" />
|
||||
<text x="713" y="406" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#FFFFFF">2</text>
|
||||
<text x="741" y="396" font-family="Georgia, "Microsoft YaHei", serif" font-size="17" font-weight="700" fill="#1A365D"><tspan fill="#3182CE">Encoder-Decoder</tspan> Attention</text>
|
||||
<text x="741" y="418" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">Q from decoder · K, V from encoder output</text>
|
||||
</g>
|
||||
|
||||
<g id="dec-sublayer-3">
|
||||
<path fill="#F5F7FA" stroke="#3182CE" stroke-width="1.5" d="M693,444 H1172 A8,8 0 0 1 1180,452 V492 A8,8 0 0 1 1172,500 H693 A8,8 0 0 1 685,492 V452 A8,8 0 0 1 693,444 Z" />
|
||||
<circle cx="713" cy="472" r="14" fill="#3182CE" />
|
||||
<text x="713" y="478" text-anchor="middle" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" font-weight="700" fill="#FFFFFF">3</text>
|
||||
<text x="741" y="468" font-family="Georgia, "Microsoft YaHei", serif" font-size="17" font-weight="700" fill="#1A365D">Position-wise Feed Forward</text>
|
||||
<text x="741" y="490" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="13" fill="#4A5568">Same shape as encoder FFN</text>
|
||||
</g>
|
||||
|
||||
<path fill="#EBF4FB" d="M693,528 H1172 A8,8 0 0 1 1180,536 V616 A8,8 0 0 1 1172,624 H693 A8,8 0 0 1 685,616 V536 A8,8 0 0 1 693,528 Z" />
|
||||
<text x="699" y="552" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="12" font-weight="700" fill="#3182CE" letter-spacing="1.5">THREE ASYMMETRIES VS ENCODER</text>
|
||||
<text x="699" y="578" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#1A202C">· third sub-layer attends to encoder output</text>
|
||||
<text x="699" y="598" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#1A202C">· self-attention is masked (no peeking at future)</text>
|
||||
<text x="699" y="618" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="14" fill="#1A202C">· output embeddings are offset by one position</text>
|
||||
</g>
|
||||
|
||||
<g id="footer">
|
||||
<text x="60" y="694" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="11" fill="#A0AEC0">Source: Vaswani et al. 2017, §3.1 Encoder and Decoder Stacks</text>
|
||||
<text x="1220" y="694" text-anchor="end" font-family="Arial, "Microsoft YaHei", sans-serif" font-size="11" fill="#A0AEC0">06</text>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 8.7 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 25 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user