AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
docs: answer the questions users actually asked
hugohe344dae87e409c
diff --git a/docs/faq.md b/docs/faq.mdindex 667a8d20..0456123c 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -8,6 +8,22 @@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: What happens to images embedded in a DOCX?++DOCX conversion extracts embedded image assets into a companion asset directory and records an image manifest; when the source exposes the information, that record includes displayed dimensions, pixel dimensions, and aspect ratios. Project import makes those companion assets available to the active project. Planning uses source position, surrounding text, captions, alt text, filenames, and geometry to decide whether an extracted asset is used; it does not have to inspect or use every extracted image. A selected image may be shown complete or placed with a focal-safe crop. Extraction and registration do **not** mean that the image is regenerated.++See the [source-conversion output contract](../skills/ppt-master/scripts/docs/conversion.md) for companion assets and the [image-planning contract](../skills/ppt-master/references/strategist-image.md) for selection and geometry evidence.++## Q: Can PPT Master batch-redraw every image in a DOCX to one ratio and style?++No. There is currently no user-facing Generate route that reference-redraws every embedded DOCX image as a batch and automatically replaces the originals. Manifest mode can batch **new** image jobs from prompts, but the built-in CLI's `--reference-image` editing is a narrow single-image path, is not manifest mode, and is available only through supported image backends. The Image to PPTX profile does not fill this gap: it applies when raster inputs represent whole slide pages to reconstruct, not when ordinary photos or illustrations are source assets inside a Word document.++These boundaries are defined by the [image-generation contract](../skills/ppt-master/references/image-generator.md), [Generate Step 5](../skills/ppt-master/workflows/generate-pptx.md), and the [Image to PPTX profile](../skills/ppt-master/workflows/profiles/image-to-pptx.md).++## Q: What is the difference between cropping an image and generating one at a requested aspect ratio?++They change different things. `crop=adaptive` permits but never requires cropping. Executor may use `meet` to show the complete source or a focal-safe `slice` to fill the chosen container; both reuse source pixels. An AI job's `aspect_ratio` requests a newly generated canvas. A reference edit transforms one supplied image through the separate single-image path; it is not a manifest batch operation. See the [image resource-list rules](../skills/ppt-master/references/strategist-image.md), [Executor crop policy](../skills/ppt-master/references/executor-image.md), [SVG image placement contract](../skills/ppt-master/references/svg-image-embedding.md), and [image manifest schema](../skills/ppt-master/references/image-generator.md).+## 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 Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Project import does not bulk-fetch the adopted webpage URLs recorded in provenance. After normal image search fails, one relevant page may be fetched with its companion images for review, and only selected files enter the deck's image pool.@@ -30,7 +46,7 @@ Just specify the format when starting a project (e.g., `--format xhs`). The outp## Q: What AI tools work with PPT Master?-PPT Master works inside any agent-capable AI tool 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.+PPT Master works inside any agent-capable AI tool that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. Installation and authentication are handled by the selected host; the [Getting Started guide](./getting-started.md) defines the working-folder model used after installation.## Q: I downloaded an old version. How do I update to the latest?@@ -59,16 +75,48 @@ Yes. The full repository is large (Git history plus bundled example decks and th- **Marketplace CLI**: `npx skills add hugohe3/ppt-master` or Claude Code's `/plugin install` fetch the skill files only (see the Set Up section of the README).- **Manual download**: grab `ppt-master-skill-*.zip` from the [Releases](https://github.com/hugohe3/ppt-master/releases) page — the skill files only (~56 MB), no full-repo clone.-Either way, run `pip install -r requirements.txt` from the installed location so the post-processing scripts work.+For either skill-only path, locate the installed skill directory that contains `SKILL.md` and `requirements.txt`, then run `python3 -m pip install -r "<installed-skill-dir>/requirements.txt"` so the post-processing scripts work.Neither path carries a `.git` directory, so `git describe` cannot report the version. The installed release is recorded in the `metadata.version` field of the skill's own `SKILL.md` frontmatter.For users in mainland China who cannot reach GitHub reliably, the complete repository is also mirrored on [AtomGit](https://atomgit.com/hugohe3/ppt-master); clone it or download its ZIP there.+## Q: I installed from a skill marketplace. What prerequisites and working directory do I need?++All installation paths require Python 3.10+ and an installed, authenticated agent host that can read and write files and run shell commands. The `npx skills add hugohe3/ppt-master` path additionally requires a working `npx` command, normally supplied with Node.js/npm; the repository does not declare a Node/npm minimum version. A host's own `/plugin install` command does not use that `npx` path.++The installed skill directory and your working folder are different roles. Install Python dependencies from the directory that contains the installed skill's `SKILL.md` and `requirements.txt`, but start the agent in a separate persistent, writable working folder of your choice. The agent creates that folder's `projects/` directory as needed; you do not need to run it from the host-managed skill cache. See [Getting Started: Set up the installation and working folders](./getting-started.md#set-up-the-installation-and-working-folders) and the skill's [execution entry point](../skills/ppt-master/SKILL.md).++## Q: How can I run the same minimal installation check on macOS or Linux?++After installing the Python dependencies, run the same core import check used by the Windows guide:++```bash+python3 -c "import pptx; import fitz; print('All core dependencies OK')"+```++Then ask the agent for a three-slide "Hello World" deck in Quick mode, with no source file. The import command checks the core Python packages; the Quick run checks project initialization, SVG authoring, validation, and export together. Success means a PPTX appears in the active project's `exports/` directory and the file opens in a presentation application. See the [Windows installation smoke test](./windows-installation.md) and the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md).++## Q: Do I need to create `projects/<name>` manually, and which `exports/` contains my deck?++No. In an agent-driven run, Default Generate Step 2 or Quick initialization creates the active project, normally under `<working-folder>/projects/<generated-project-name>/`, and reports its exact path. With the default exporter path, the deck belongs to that project:++```text+<active-project>/exports/<project-name>_<timestamp>.pptx+```++That is not an unqualified `exports/` at the repository root. An explicitly supplied output path is the exception. See [Generate project initialization and export](../skills/ppt-master/workflows/generate-pptx.md), the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md), and the [working-folder explanation](./getting-started.md#set-up-the-installation-and-working-folders).+## Q: Can I use AI-generated images in my presentation?Yes. When the agent host exposes a native image tool, PPT Master can use it without a separate provider image-generation API key. It can also use the built-in `image_gen.py` through a configured provider. Choose "AI generation" for the image approach; you can explicitly ask the agent to use its own image tool. You can also place your own images in the project's `images/` folder.+## Q: Why are there no icons? Are icons supposed to appear on every slide?++No per-slide icon coverage is required. In Default, `No base icons` is a valid confirmed choice alongside emoji, bundled SVG icons, and custom project icons. Default's `icons.inventory` indexes its curated prepared pool without assigning icons to pages. Both profiles may use project-local prepared icons; Quick creates neither a general resource roster nor an icon-to-page assignment. The author uses an icon only when it serves that page's communication task, so a deck or page may use none. AI-generated illustrated-icon slices are image assets under a separate path and are also optional.++See the [Strategist icon choice](../skills/ppt-master/references/strategist.md), [Executor icon usage](../skills/ppt-master/references/executor-base.md), and [Quick resource preparation](../skills/ppt-master/workflows/profiles/quick-generate.md).+## Q: I don't have an image-generation API key — can I still get images?Yes. If the agent host exposes native image generation, choose "AI generation" and ask it to use its own image tool; this needs no provider image API key. Otherwise, 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. Zero-config search is a fallback: it works immediately, but quality can be uneven because many results are ordinary user uploads.@@ -85,7 +133,7 @@ Ordinary visible text is rebuilt as native editable text. Logos, icons, badges,## Q: Can I edit the generated presentations?-Yes. The only PPTX converter in the SVG pipeline is PPT Master's own `svg_output/` → DrawingML conversion. It saves a timestamped native PowerPoint deck to `exports/`, with text, graphics, and colors directly editable as PowerPoint objects. With the default output path, both Default Generate and Quick Generate copy the authored `svg_output/` to `backup/<timestamp>/svg_output/`, so the same authored deck can be re-exported without re-running the LLM. For Quick this is package reconstruction, not a recoverable record of the AI's design decisions.+Yes. The only PPTX converter in the SVG pipeline is PPT Master's own `svg_output/` → DrawingML conversion. It saves a timestamped native PowerPoint deck to the active project's `exports/`, with text, graphics, and colors directly editable as PowerPoint objects. With the default output path, both Default Generate and Quick Generate copy the authored `svg_output/` to `backup/<timestamp>/svg_output/`, so the same authored deck can be re-exported without re-running the LLM. For Quick this is package reconstruction, not a recoverable record of the AI's design decisions.`finalize_svg.py` remains a mandatory Step 7 operation in the default Generate flow even though native PPTX export reads `svg_output/`. It produces self-contained files in `svg_final/` for visual inspection and for manual insertion into another deck as SVG pictures. The explicit quick-generate profile skips this preview artifact, but still retains the normal postflight report and default-path backup after its lockless final quality check. PowerPoint's manual **Convert to Shape** command is not a supported round-trip path; use the generated native PPTX when you need editable shapes.@@ -134,19 +182,23 @@ Two independent choices, locked at confirmation `d`:Any mode pairs with any visual style.-## Q: Is PPT Master expensive to use?+## Q: The result looks like only boxes and lines. What run facts should I check first?-PPT Master itself is free and open source. The only cost is your own AI model usage.+PPT Master has no documented `wireframe` runtime mode and no documented visual-equivalence guarantee between releases, so appearance alone does not identify a version regression. First record whether the run used Default or Quick, plus the actual mode, visual style, image-usage choice, base-icon choice, Custom Animations setting, and prepared-resource state. Quick keeps these decisions in the active agent context rather than writing `design_spec.md` or `spec_lock.md`.-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.+Next compare the same page in the active project's `svg_output/` with the exported PPTX. If the SVG is already sparse, inspect the planning, resource, and SVG-authoring layers. If the SVG contains the intended objects but the PPTX loses or changes them, inspect the conversion or rendering layer. This boundary follows [Materials → Plan → Realization](./technical-design.md), the [Default Generate workflow](../skills/ppt-master/workflows/generate-pptx.md), and the [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md).-And because it runs inside a coding agent, a flat subscription plan lets you make many decks at no extra per-deck cost, while a direct per-token API is simply a different price structure — the choice is yours. Either way, PPT Master adds no cost of its own on top of your AI spend.+## Q: How is PPT Master priced, and does template reuse reduce token usage?++You pay according to your AI usage; PPT Master adds no subscription fee.++The repository documents template reuse as reuse of identity, method, structure, or a recurring application contract. It contains no measured or guaranteed relationship between template reuse and token usage. See the [product positioning](../README.md#product-positioning) and [template boundaries](./templates-guide.md).## Q: Are the charts in the generated PPTX editable?By default, 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 default 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, and they render pixel-consistently across PowerPoint / Keynote / LibreOffice / WPS.-If your workflow specifically requires Excel-driven data editing or PowerPoint's chart/table-specific controls, export with `--native-charts-and-tables`: supported data charts and pure text-grid tables then ship as **PowerPoint-native Chart / Table objects backed by data** (saved as `exports/<name>_<timestamp>_native_charts_tables.pptx`, keeping the deck's own colors instead of PowerPoint's default theme). The default SVG fallback also becomes editable DrawingML shapes, but it has no chart data workbook or table/chart object model. Native objects may look slightly different across PowerPoint / Keynote / LibreOffice / WPS, so the shape-based route remains the visual-stability default.+If your workflow specifically requires Excel-driven data editing or PowerPoint's chart/table-specific controls, export with `--native-charts-and-tables`: supported data charts and pure text-grid tables then ship as **PowerPoint-native Chart / Table objects backed by data** (saved as `<active-project>/exports/<name>_<timestamp>_native_charts_tables.pptx`, keeping the deck's own colors instead of PowerPoint's default theme). The default SVG fallback also becomes editable DrawingML shapes, but it has no chart data workbook or table/chart object model. Native objects may look slightly different across PowerPoint / Keynote / LibreOffice / WPS, so the shape-based route remains the visual-stability default.## Q: Are formulas editable?@@ -192,9 +244,9 @@ settings are not authored. See the [PowerPoint ↔ SVG MappingGuide](./powerpoint-svg-mapping.md#10-powerpoint-playback-and-package-features)for the carrier and preservation boundaries.-## Q: Can I change page transitions and element animations?+## Q: Why are there no element animations? Were animations removed?-Yes. Page transitions are on by default (`fade` 0.4s); per-element object+Animations were not removed. Page transitions are on by default (`fade` 0.4s); per-element objectanimation is **off by default**—a page appears as a whole instead of havingelements auto-cascade in one by one. Both are controlled by `svg_to_pptx.py`flags: `-t/--transition` for page-level and `-a/--animation` for element-level.@@ -203,6 +255,8 @@ The object registry includes entrance, emphasis, motion-path, and exit effects.finite exact-duration object-animation rows into `animations.json`;unsupported source timing remains an explicit diagnostic.+Use `-a auto` for deck-wide automatic entrances, a canonical effect for one deck-wide effect, or a project-level `animations.json` for explicit page/object timing. Default runs the custom stage for an existing sidecar, an explicit per-slide/per-object request, or an enabled effective Custom Animations outcome. Quick runs it when a sidecar or its active-context motion decision requires object-level work; recorded, self-running, or video-directed Quick delivery requires that stage unless the user explicitly requests static or page-transition-only playback. A deck-wide-only request can remain exporter flags. If none of these triggers applies, the `fade`/`none` defaults remain. The [Generate workflow](../skills/ppt-master/workflows/generate-pptx.md) and [Quick profile](../skills/ppt-master/workflows/profiles/quick-generate.md) define those triggers.+```bashpython3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transitionpython3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions@@ -257,10 +311,10 @@ A typical 10–15 page presentation takes about **10–20 minutes** with a fastIf generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts.If what you want is less process rather than a different model, explicitly ask-for quick generation: it skips the Strategist analysis and the confirmation-stop, so the planning phase costs nothing, but per-page SVG authoring takes the-same time. See the next question, "I don't want to confirm a design spec first-— can I generate directly?".+for quick generation: it omits the Strategist analysis and the confirmation+stop, while per-page SVG authoring remains. The repository does not promise a+fixed time reduction for Quick. See the next question, "I don't want to confirm+a design spec first — can I generate directly?".## Q: I don't want to confirm a design spec first — can I generate directly?@@ -299,9 +353,9 @@ default-path export writes the normal postflight report and snapshotsno-backup behavior. Page count alone neither activates nor blocks quickgeneration.-Because the whole planning phase no longer happens, token usage is materially-lower than the default flow; per-page SVG authoring is the dominant cost of a-run and it does not shrink. Quick keeps the same page-level visual and+Quick omits the separate planning phase, but the repository does not document+a measured or guaranteed token reduction; per-page SVG authoring remains.+Quick keeps the same page-level visual andresource-authoring capabilities and the shared SVG/resource blockingstandards. It does not run Spec Lock alignment checks; its package keepsconverter-default Theme scaffolding instead of deriving Theme colors, fonts,@@ -380,6 +434,27 @@ Note that Create Template produces a reusable template workspace, not a filled d---+## Q: Can I turn a company `.pptx` into a reusable workspace? Which kind should I choose?++Yes, through an explicit `/create-template` request. A complete source deck does not by itself imply `Deck`; choose the kind by what must remain reusable:++| Kind | Reusable contract |+|---|---|+| **Brand** | Identity only: colors, type, logo, voice, and icon language; no page roster |+| **Style** | Communication method and visual defaults without identity truth, page prototypes, or native structure |+| **Layout** | Brand-neutral and application-neutral Master/Layout/slot structure |+| **Deck** | A recurring application or branded structure that integrates identity, structure, and an SVG roster |++Create Template confirms the brief before writing either an indexed `library` workspace or a non-registered initialized `project` workspace. For later Generate runs, pass the resulting workspace root—not the source `.pptx` or its inner `templates/` directory. See the [Create Template route](../skills/ppt-master/workflows/create-template.md) and [Templates Guide](./templates-guide.md).++---++## Q: Does registering a template make every future deck use it automatically?++No. Registration makes a workspace discoverable; it does not select it. In Default Generate, the template must still be confirmed in Stage 1. Supplying exactly one workspace root can preselect it there, but does not bypass confirmation; supplying several roots leaves them as unselected candidates. Quick has no template selector, so an exact root is validated and used directly, while no exact root means free design. A raw `.pptx`, an inner `templates/` directory, a bare template name, or a style phrase is not a workspace selection. See [How template selection works](./templates-guide.md) and the [Quick template boundary](../skills/ppt-master/workflows/profiles/quick-generate.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:diff --git a/docs/getting-started.md b/docs/getting-started.mdindex 02a8f4f8..64157967 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -6,6 +6,7 @@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.+- [Set up the installation and working folders](#set-up-the-installation-and-working-folders)- [Start from a template](#start-from-a-template)- [Generate your first deck](#generate-your-first-deck)- [Live preview & visual edits](#live-preview--visual-edits)@@ -16,6 +17,32 @@ The short path to your first deck, how to use everything around it — templates---+## Set up the installation and working folders++Before starting the agent, keep these three directories separate:++| Directory | What it is | Where it comes from |+|---|---|---|+| **Installed skill directory** | The PPT Master package containing `SKILL.md`, `requirements.txt`, workflows, and scripts | In a full-repository clone or repository ZIP, this is `skills/ppt-master/`; a marketplace/plugin installation or skill-only release ZIP has its own installed or extracted location |+| **Working folder** | A persistent, writable folder that you open in the agent | For a full-repository clone or repository ZIP, normally the repository root; for skill-only installation, choose your own folder—it does not have to be the installed skill directory |+| **Active project** | One generation run's sources, authored SVG, reports, backups, and exports | The agent initializes it under `<working-folder>/projects/<generated-project-name>/` and reports the exact path |++Every installation path needs Python 3.10+ and an installed, authenticated agent host that can read and write the working folder and run shell commands. For a full-repository clone or repository ZIP, install dependencies from the repository root:++```bash+python3 -m pip install -r requirements.txt+```++For a skill-only installation, first locate the installed or extracted directory that contains the skill's `SKILL.md` and `requirements.txt`, then install from that path:++```bash+python3 -m pip install -r "<installed-skill-dir>/requirements.txt"+```++The `npx skills add hugohe3/ppt-master` installation path also requires a working `npx` command, normally supplied with Node.js/npm; the repository does not specify a Node/npm minimum version. A host's own `/plugin install` command does not use that `npx` path. After installation, start the agent in the **working folder**, not in the host-managed skill cache. The execution entry point resolves the installed skill separately. Installation choices are listed in [Quick Start](../README.md#quick-start); runtime discipline is defined in [`SKILL.md`](../skills/ppt-master/SKILL.md).++---+## 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 when a deck must reuse a brand identity, a communication/design method, a fixed layout set, or a recurring deck application.@@ -58,17 +85,17 @@ 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).+Once the environment and working folder above are ready, the whole loop is three steps:-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. Stage 1 then lets you confirm the communication contract together with free design or template use; add one exact workspace root when you want template mode and that path preselected:+1. **Give the agent source material it can read** — a PDF, DOCX, Markdown file, a URL, or text pasted into chat. A folder such as `<working-folder>/inputs/` is fine; you do not need to pre-create the final `projects/<name>/` directory.+2. **Tell the AI in chat** what to turn into a deck. [Default Generate Step 2](../skills/ppt-master/workflows/generate-pptx.md) or [Quick initialization](../skills/ppt-master/workflows/profiles/quick-generate.md) creates the active project under the working folder's `projects/` directory and reports its exact path. File-based material is imported when present; pasted text stays in the conversation context and needs no import. Default then opens Stage 1 to confirm the communication contract together with free design or template use; Quick skips those confirmation stages. For Default, add one exact workspace root when you want template mode and that path preselected:```- You: Make a deck from projects/q3-report/sources/report.pdf+ You: Make a deck from <path-to-report.pdf>You: Turn this text into a deck: <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.+3. **Get an editable `.pptx`** at `<active-project>/exports/<project-name>_<timestamp>.pptx` unless you explicitly requested another output path. For a full-repository clone or repository ZIP this is commonly `<repository-root>/projects/<generated-project-name>/exports/...`; for skill-only installation it is `<working-folder>/projects/<generated-project-name>/exports/...`. Use the exact active-project path reported by the agent rather than looking for an unqualified repository-root `exports/`.-Before generation, Stage 1 confirms the communication contract, canvas/format, and free-design/template choice together. The AI then installs any selected workspace; final Stage 2 reads that installed state and confirms page count, the visual system, template application, and production choices. From there it handles content analysis, layout, image acquisition, SVG generation, and export — the core loop everything else builds on. To skip interactive confirmation, see [Quick mode](#quick-mode) below.+The terms in that flow are not extra folders you must create. **Stage 1** confirms the communication contract—purpose, audience, reading situation, canvas/format—and the free-design/template choice. A **workspace root** is the root directory of an optional reusable Brand, Style, Layout, or Deck package; it is not the active project. The AI installs any selected workspace, then **Stage 2** confirms page count, the visual system, template application, and production choices. From there it handles content analysis, layout, image acquisition, SVG generation, and export. To skip interactive confirmation, see [Quick mode](#quick-mode) below.---diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 327eb04d..40b2bbea 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -8,6 +8,22 @@几乎所有常见格式都支持:**PDF**、**DOCX**、**PPTX**、**EPUB**、**HTML**、**LaTeX**、**RST**、**网页链接**(包括微信公众号文章)、**Markdown**,或者直接在对话中粘贴文字内容。AI 代理会自动将源材料转换为 Markdown 后再生成幻灯片。+## Q: DOCX 里的内嵌图片会怎样处理?++DOCX 转换会把内嵌图片素材抽取到配套素材目录,并写入图片清单;来源能提供相应信息时,清单会记录显示尺寸、像素尺寸与宽高比。项目导入会让活动项目可以使用这些配套素材。规划会根据图片在来源中的位置、上下文、caption、alt text、文件名与几何信息,决定某个抽取素材是否使用;不要求查看或使用每一张抽取图片。选中的图片可以完整显示,也可以做保护焦点内容的安全裁剪。抽取和登记**不等于**重新生成图片。++配套素材的输出见[来源转换输出合同](../../skills/ppt-master/scripts/docs/conversion.md),选用与几何依据见[图片规划合同](../../skills/ppt-master/references/strategist-image.md)。++## Q: 能把 DOCX 里的所有图片批量重画成统一比例和风格吗?++当前没有。现行 Generate 路线没有面向用户的入口,可以批量按参考图重画全部 DOCX 内嵌图片并自动替换原图。Manifest 模式可以根据提示词批量生成**新图**;内置 CLI 的 `--reference-image` 编辑则是独立的单图窄路径,不属于 manifest 模式,而且只适用于受支持的生图后端。图片还原为 PPTX 也不能补上这项能力:它只在栅格输入代表待还原的整页幻灯片画面时触发,普通 Word 照片或插图仍属于来源素材。++这些边界见[图片生成合同](../../skills/ppt-master/references/image-generator.md)、[Generate Step 5](../../skills/ppt-master/workflows/generate-pptx.md)与[图片还原为 PPTX profile](../../skills/ppt-master/workflows/profiles/image-to-pptx.md)。++## Q: 把原图裁成指定比例,与按指定比例生成新图有什么区别?++两者改变的对象不同。`crop=adaptive` 允许但不强制裁剪。Executor 可用 `meet` 完整显示原图,或用保护焦点内容的 `slice` 填满所选容器;两者都复用来源像素。AI 任务的 `aspect_ratio` 是新生成画布的要求。参考图编辑则通过独立的单图路径变换一张给定图片,不是 manifest 批处理。详见[图片资源清单规则](../../skills/ppt-master/references/strategist-image.md)、[Executor 裁剪政策](../../skills/ppt-master/references/executor-image.md)、[SVG 图片放置合同](../../skills/ppt-master/references/svg-image-embedding.md)与[图片 manifest schema](../../skills/ppt-master/references/image-generator.md)。+## Q: 只有一个主题或想法、没有任何资料,也能生成吗?可以。直接告诉 AI 你想做的主题或场景(如"做一个关于宫崎骏的 PPT"、"介绍我们公司新产品"),Generate PPTX 路线会运行 **topic-research 阶段**,补齐规划所需的事实基础与来源记录。已有部分材料时,只补实现用户目标仍缺少的事实;如果用户要求只使用原材料,则不做外部补充。项目导入不会根据来源记录中的网页 URL 批量抓取材料;常规搜图失败后,才会按需获取一个相关网页及其图片资源包,审阅后只把选中的图片加入项目图池。@@ -30,7 +46,7 @@## Q: PPT Master 支持哪些 AI 工具?-PPT Master 可以在任何能读取文件和执行命令、支持 Agent 的 AI 工具中运行——**Claude Code**(CLI / VS Code / JetBrains / Web)、**VS Code Copilot**、**Codex** 等均可使用。不同工具的使用成本可参考下方的费用对比。+PPT Master 可以在任何能读取文件和执行命令、支持 Agent 的 AI 工具中运行——**Claude Code**(CLI / VS Code / JetBrains / Web)、**VS Code Copilot**、**Codex** 等均可使用。所选 host 负责自身的安装与鉴权;安装后的工作目录模型见[快速入门](./getting-started.md)。## Q: 我下载过旧版本,怎么更新到最新版?@@ -59,16 +75,48 @@ python3 skills/ppt-master/scripts/update_repo.py- **Marketplace CLI**:`npx skills add hugohe3/ppt-master`,或 Claude Code 里的 `/plugin install`,都只拉取 skill 文件(见 README 的「开始设置」一节)。- **手动下载**:到 [Releases](https://github.com/hugohe3/ppt-master/releases) 页面下载 `ppt-master-skill-*.zip`——只含 skill 文件(约 56 MB),无需 clone 完整仓库。-两种方式装好后,都要在安装目录跑 `pip install -r requirements.txt`,后处理脚本才能工作。+两种 skill-only 方式装好后,找到同时包含 `SKILL.md` 与 `requirements.txt` 的 skill 安装目录,再运行 `python3 -m pip install -r "<installed-skill-dir>/requirements.txt"`,后处理脚本才能工作。这两条路径都不带 `.git` 目录,`git describe` 查不到版本。已安装的版本记录在 skill 自身 `SKILL.md` frontmatter 的 `metadata.version` 字段里。中国大陆地区访问 GitHub 下载不便时,可以从 [AtomGit](https://atomgit.com/hugohe3/ppt-master) 的完整仓库镜像 clone 或下载 ZIP。+## Q: 通过 Skill marketplace 安装后,还需要什么环境,应该在哪个目录运行?++所有安装方式都需要 Python 3.10+,以及一个已安装、已鉴权、能够读写文件并执行 shell 命令的 Agent host。使用 `npx skills add hugohe3/ppt-master` 还要求本机有可用的 `npx` 命令,通常由 Node.js/npm 提供;仓库没有声明 Node/npm 的最低版本。Host 自带的 `/plugin install` 不走这条 `npx` 路径。++Skill 安装目录与工作目录承担不同角色。Python 依赖从包含已安装 skill 的 `SKILL.md` 和 `requirements.txt` 的目录安装;Agent 则应从你自行选择的、可持久保存且可写的工作目录启动。Agent 会按需在这个工作目录下创建 `projects/`,不需要从 host 管理的 skill 缓存目录运行。详见[快速入门:配置安装目录与工作目录](./getting-started.md#配置安装目录与工作目录)和 skill 的[执行入口](../../skills/ppt-master/SKILL.md)。++## Q: macOS 或 Linux 怎样做与 Windows 相同的最小安装验证?++安装 Python 依赖后,运行 Windows 指南使用的同一条核心导入检查:++```bash+python3 -c "import pptx; import fitz; print('All core dependencies OK')"+```++然后让 Agent 用 Quick 模式生成一份无来源文件的 3 页 “Hello World” deck。导入命令只检查核心 Python 包;Quick 运行会连同项目初始化、SVG 创作、校验和导出一起检查。成功标志是活动项目的 `exports/` 目录出现 PPTX,并且该文件能在演示文稿应用中打开。依据见 [Windows 安装 smoke](./windows-installation.md)和[快速模式 profile](../../skills/ppt-master/workflows/profiles/quick-generate.md)。++## Q: 需要手工创建 `projects/<name>` 吗?最终文件在哪个 `exports/`?++不需要。由 Agent 执行时,Default Generate Step 2 或 Quick 初始化会创建活动项目,通常位于 `<工作目录>/projects/<生成的项目名>/`,并报告它的精确路径。使用默认导出路径时,PPTX 属于这个活动项目:++```text+<活动项目>/exports/<项目名>_<时间戳>.pptx+```++它不是仓库根目录下一个没有项目上下文的 `exports/`;只有显式指定输出路径时例外。依据见 [Generate 的项目初始化与导出](../../skills/ppt-master/workflows/generate-pptx.md)、[快速模式 profile](../../skills/ppt-master/workflows/profiles/quick-generate.md)和[工作目录说明](./getting-started.md#配置安装目录与工作目录)。+## Q: 能用 AI 生成配图吗?可以。Agent host 提供原生生图工具时,PPT Master 可直接使用,不需要另配供应商生图 API Key;也可以通过内置 `image_gen.py` 使用已配置的供应商后端。图片方案选择"AI 生图"即可,也可明确要求 Agent 使用自身生图工具。你还可以把自己的图片放到项目的 `images/` 目录下。+## Q: 为什么没有图标?图标应该默认出现在每一页吗?++不要求逐页使用图标。Default 中的 `No base icons` 与 Emoji、内置 SVG 图标、自定义项目图标一样,都是合法的确认选项。Default 的 `icons.inventory` 只索引其精选的已备素材池,不会把图标分配到页面。两种 profile 都可以使用项目内已备图标;Quick 不创建通用资源 roster,也不创建逐页图标分配表。只有页面沟通任务需要时才会使用图标,因此整份 deck 或某一页可以不用。AI 生成的插画图标切片属于另一条图片素材路径,同样不是必选项。++依据见[策略师的图标选择](../../skills/ppt-master/references/strategist.md)、[执行器的图标用法](../../skills/ppt-master/references/executor-base.md)与[Quick 资源准备](../../skills/ppt-master/workflows/profiles/quick-generate.md)。+## Q: 没有生图 API Key,还能配图吗?可以。Agent host 提供原生生图能力时,选择"AI 生图"并要求它使用自身生图工具,不需要供应商生图 API Key。否则可在策略师的"图片方案"步骤选择"网络图片";PPT Master 内置零配置的 `image_search.py`,在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片。零配置搜索适合作为兜底:能直接用,但图片质量不稳定,容易出现普通用户上传、构图随意、清晰度一般的素材。@@ -85,7 +133,7 @@ python3 skills/ppt-master/scripts/update_repo.py## Q: 生成的 PPT 可以编辑吗?-可以。SVG 管线统一由项目转换器读取 `svg_output/` 并生成原生 DrawingML `.pptx`;文字、图形和颜色无需额外转换即可编辑,文件以时间戳命名保存至 `exports/`。使用默认输出路径时,Default Generate 与 Quick Generate 都会把作者源 `svg_output/` 镜像到 `backup/<timestamp>/svg_output/`,便于归档或基于该版重新导出 PPTX,无需再走 LLM。对 Quick 而言,这只是包重建,不是可恢复的 AI 设计决策记录。+可以。SVG 管线统一由项目转换器读取 `svg_output/` 并生成原生 DrawingML `.pptx`;文字、图形和颜色无需额外转换即可编辑,文件以时间戳命名保存至活动项目的 `exports/`。使用默认输出路径时,Default Generate 与 Quick Generate 都会把作者源 `svg_output/` 镜像到 `backup/<timestamp>/svg_output/`,便于归档或基于该版重新导出 PPTX,无需再走 LLM。对 Quick 而言,这只是包重建,不是可恢复的 AI 设计决策记录。默认 Generate 流程的 Step 7 仍会强制生成 `svg_final/`。其中每页都是自包含的视觉预览 SVG,可直接在浏览器或 IDE 中打开,也可作为 SVG 图片手动插入 PowerPoint;显式快速生成会跳过这项预览产物,但在无锁最终质量检查通过后,仍保留普通 postflight 报告和默认输出路径下的备份。项目只保证 `svg_final/` 作为预览或图片显示,不保证 PowerPoint 手工“转换为形状”后的结果。需要可编辑形状时,请使用 `exports/` 中由项目转换器生成的原生 PPTX。@@ -134,19 +182,23 @@ PowerPoint 最终显示的是 pt,所以**导出时**自动把 px 换成 pt(`任意 mode 可与任意 visual style 自由组合。-## Q: 用 PPT Master 做 PPT 贵吗?+## Q: 结果看起来只有框和线,应该先核对哪些运行事实?-PPT Master 本身免费开源,唯一的成本来自你自己的 AI 模型用量。+PPT Master 没有文档化的 `wireframe` 运行模式,也没有跨版本视觉等价保证,因此不能只凭观感判定版本回归。先记录本次使用 Default 还是 Quick,以及实际的 mode、visual style、图片方案、基础图标选择、Custom Animations 设置和资源备妥状态。Quick 不写 `design_spec.md` 或 `spec_lock.md`,这些决定只保留在 Agent 的当前上下文。-目前主流 AI 工具都已转向按量计费——用多少付多少。PPT Master 天然契合这一模型:不需要额外订阅 PPT 平台、没有专有积分、没有按人头收费的演示工具费用。+再比较活动项目 `svg_output/` 中的同一页与导出的 PPTX。SVG 本身已经稀疏时,应检查规划、资源与 SVG 创作层;SVG 中存在预期对象、PPTX 却丢失或改变时,才检查转换或渲染层。这个分界依据 [Materials → Plan → Realization](./technical-design.md)、[Default Generate 工作流](../../skills/ppt-master/workflows/generate-pptx.md)与[快速模式 profile](../../skills/ppt-master/workflows/profiles/quick-generate.md)。-而且它跑在编程 agent 里:走固定月费的订阅套餐,就能在套餐额度内多做 deck 而不额外多花钱;走 API 直连、按 token 计费则是另一种价格结构——由你选。无论走哪条,PPT Master 都不会在你的 AI 支出之外再加一层自己的费用。+## Q: PPT Master 如何计费?复用模板会降低 token 用量吗?++按你的 AI 用量计费,不额外收订阅费。++仓库所说的模板复用,是复用身份、方法、结构或重复应用合同;当前没有文档化的测量或保证表明模板复用会改变 token 用量。依据见[产品定位](../../README_CN.md#产品定位)与[模板边界](./templates-guide.md)。## Q: 生成的图表可以编辑数据吗?默认情况下,图表以**自定义设计的 SVG 图形**形式渲染,转换为原生 PowerPoint 形状——形状级别完全可编辑(移动、改色、改文字、调样式)。默认不用 Excel 驱动的图表对象是有意为之:PowerPoint 默认图表样式陈旧、视觉受限于固定模板。SVG 图表则提供出版物级的视觉质量,可以在 PowerPoint 中直接精修,且在 PowerPoint / Keynote / LibreOffice / WPS 间像素一致。-如果你的工作流明确需要 Excel 驱动的数据编辑或 PowerPoint 的图表/表格专属控制,导出时加 `--native-charts-and-tables`:受支持的数据图表和纯文本表格会以**带数据源的 PowerPoint 原生 Chart / Table 对象**形式导出(保存为 `exports/<name>_<timestamp>_native_charts_tables.pptx`,并保留这份 deck 自己的配色,而不是套用 PowerPoint 默认主题)。默认 SVG fallback 同样会转换成可编辑 DrawingML shape,但不具备图表数据工作簿或图表/表格对象模型。原生对象在 PowerPoint / Keynote / LibreOffice / WPS 间可能略有差异,因此形状路线仍是视觉稳定性的默认选择。+如果你的工作流明确需要 Excel 驱动的数据编辑或 PowerPoint 的图表/表格专属控制,导出时加 `--native-charts-and-tables`:受支持的数据图表和纯文本表格会以**带数据源的 PowerPoint 原生 Chart / Table 对象**形式导出(保存为 `<活动项目>/exports/<name>_<timestamp>_native_charts_tables.pptx`,并保留这份 deck 自己的配色,而不是套用 PowerPoint 默认主题)。默认 SVG fallback 同样会转换成可编辑 DrawingML shape,但不具备图表数据工作簿或图表/表格对象模型。原生对象在 PowerPoint / Keynote / LibreOffice / WPS 间可能略有差异,因此形状路线仍是视觉稳定性的默认选择。## Q: 公式可以编辑吗?@@ -183,15 +235,17 @@ relationship,受支持的 PPTX 回导也会重建同一种 SVG 表达。导航命令、程序 / macro / OLE / file 以及任意 action setting 不会被创作。carrier 与保留边界见 [PowerPoint ↔ SVG 映射指南](./powerpoint-svg-mapping.md)。-## Q: 页面切换和元素动画可以调吗?+## Q: 为什么没有页内元素动画?动画被移除了吗?-可以。页间转场默认开(`fade` 0.4s),页内元素对象动画**默认关**——翻到+动画没有被移除。页间转场默认开(`fade` 0.4s),页内元素对象动画**默认关**——翻到一页时整页一次性呈现,不会自动逐个级联。两者都通过 `svg_to_pptx.py` 的参数控制:`-t/--transition` 控制页级,`-a/--animation` 控制元素级。对象注册表已经包含进入、强调、动作路径和退出效果。`pptx_to_svg.py` 也会把当前注册表内可精确读回的页面切换和具有精确时长的有限对象动画记录重建到 `animations.json`;不支持的来源 timing 会保留明确诊断。+整份 deck 的自动入场可用 `-a auto`,统一效果可传规范效果名,逐页 / 逐对象时序则使用项目级 `animations.json`。Default 在已有 sidecar、显式逐页 / 逐对象请求,或有效的 Custom Animations 结果已启用时运行自定义阶段。Quick 在 sidecar 或当前上下文的动效决定需要对象级工作时运行;录制、自运行或视频导向的 Quick 交付必须进入该阶段,除非用户显式要求静态或只用页间转场。只涉及整份 deck 的要求可以保留为导出参数。所有触发都不成立时,保留 `fade` / `none` 默认值。触发边界见 [Generate 工作流](../../skills/ppt-master/workflows/generate-pptx.md)与[快速模式 profile](../../skills/ppt-master/workflows/profiles/quick-generate.md)。+```bashpython3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # 换转场效果python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # 关闭转场@@ -245,7 +299,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t如果感觉生成很慢,检查一下模型的 token 吞吐速度。瓶颈通常在模型的输出速度,而不是脚本本身。-如果你想要的是少走流程、而不是换模型,可以显式要求快速生成:它跳过策略师分析与确认停顿,规划阶段的开销随之消失,但逐页 SVG 生成的时间不变。见下一问「不想先确认设计规格,能直接生成吗?」。+如果你想要的是少走流程、而不是换模型,可以显式要求快速生成:它省略策略师分析与确认停顿,但仍需逐页创作 SVG。仓库不承诺 Quick 会固定缩短多少时间。见下一问「不想先确认设计规格,能直接生成吗?」。## Q: 不想先确认设计规格,能直接生成吗?@@ -257,7 +311,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t原生图表 / 表格替换、讲稿、动效、旁白和诊断等普通导出能力仍可按需使用;讲稿、自定义对象动画和旁白默认关闭,Agent 可在用户要求或 deck 确有需要时自动启用,不会打开确认流程。使用默认输出路径时会生成普通 postflight 报告,并把 `svg_output/` 备份到 `backup/`;显式指定输出路径时沿用普通流程不创建备份的行为。页数本身既不会自动触发,也不会阻止快速生成。-由于整个规划阶段不再发生,token 消耗明显低于默认流程;逐页 SVG 生成是一次 run 的主要开销,这部分并不减少。Quick 保留同一套页面级视觉与资源创作能力,以及共享的 SVG / 资源阻塞标准;它不运行 Spec Lock 对齐检查,包内保留转换器默认 Theme 脚手架,而不是从 lock 派生主题色、字体与 Master 标题/正文默认字号。由于没有已确认的设计契约、首屏校准或可恢复的决策历史,它不承诺与 Default 作出相同设计,也不承诺具体耗时。+Quick 省略独立规划阶段,但仓库没有文档化的测量或保证表明它会降低多少 token;逐页 SVG 创作仍然存在。Quick 保留同一套页面级视觉与资源创作能力,以及共享的 SVG / 资源阻塞标准;它不运行 Spec Lock 对齐检查,包内保留转换器默认 Theme 脚手架,而不是从 lock 派生主题色、字体与 Master 标题/正文默认字号。由于没有已确认的设计契约、首屏校准或可恢复的决策历史,它不承诺与 Default 作出相同设计,也不承诺具体耗时。## Q: 长 PPT 一次生成会不会上下文爆掉?@@ -330,6 +384,27 @@ python3 skills/ppt-master/scripts/pptx_template_import.py <deck.pptx> --manifest---+## Q: 能把企业 `.pptx` 提炼成可复用工作区吗?应该选哪一种 kind?++可以,但必须显式请求 `/create-template`。一份完整的来源 deck 本身不自动等于 `Deck`;应按真正要复用的合同选择:++| Kind | 要复用的合同 |+|---|---|+| **Brand** | 只复用身份:颜色、字体、Logo、语调和图标语言;没有页面 roster |+| **Style** | 复用沟通方法和视觉默认值,不携带身份真值、页面原型或原生结构 |+| **Layout** | 复用品牌中立、应用中立的 Master / Layout / slot 结构 |+| **Deck** | 复用反复出现的演示应用,或把企业身份与结构整合在一起;同时拥有身份、结构和 SVG roster |++Create Template 会先确认简报,再写入已注册、可发现的 `library` 工作区,或一个不注册的已初始化 `project` 工作区。后续 Generate 应传产出的工作区根目录,而不是来源 `.pptx` 或其内层 `templates/` 目录。详见 [Create Template 路线](../../skills/ppt-master/workflows/create-template.md)与[模板指南](./templates-guide.md)。++---++## Q: 模板注册后,以后每次生成都会自动使用吗?++不会。注册只让工作区可被发现,不会自动选中。Default Generate 每次仍需在 Stage 1 确认;只提供一个精确工作区 root 时可在页面中预选,但不会跳过确认,提供多个 root 时则都只作为未选候选。Quick 没有模板选择页,因此精确 root 会被直接校验并使用;没有精确 root 就走自由设计。原始 `.pptx`、内层 `templates/` 目录、裸模板名或风格词都不算选中工作区。详见[模板选择机制](./templates-guide.md)与[Quick 模板边界](../../skills/ppt-master/workflows/profiles/quick-generate.md)。++---+## Q: 如何制作自定义模板?想把自己喜欢的 PPT 模板制作成 PPT Master 可调用的模板?按以下步骤操作:diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.mdindex 9dd6b9c0..a8ba0909 100644--- a/docs/zh/getting-started.md+++ b/docs/zh/getting-started.md@@ -6,6 +6,7 @@最快做出第一份 deck 的路径、围绕它的各项能力——模板、实时预览、动画、旁白、声音复刻——以及出问题时去哪里查。章节大致按你真实使用时遇到它们的顺序排列。每节都是精简版,需要细节就点 **完整说明 →** 链接。+- [配置安装目录与工作目录](#配置安装目录与工作目录)- [用模板](#用模板)- [做出第一份 deck](#做出第一份-deck)- [实时预览与可视化修改](#实时预览与可视化修改)@@ -16,6 +17,32 @@---+## 配置安装目录与工作目录++启动 Agent 前,先分清三个目录:++| 目录 | 它是什么 | 怎样产生 |+|---|---|---|+| **Skill 安装目录** | 包含 `SKILL.md`、`requirements.txt`、工作流与脚本的 PPT Master 包 | 完整仓库 clone 或仓库 ZIP 中是 `skills/ppt-master/`;marketplace/plugin 安装或 skill-only release ZIP 则使用自己的安装或解压位置 |+| **工作目录** | 你在 Agent 中打开的、可持久保存且可写的目录 | 完整仓库 clone 或仓库 ZIP 通常使用仓库根目录;skill-only 安装则自行选择,不必是 skill 安装目录 |+| **活动项目** | 一次生成任务的来源、SVG、报告、备份与导出物所在目录 | Agent 会在 `<工作目录>/projects/<生成的项目名>/` 下初始化,并报告精确路径 |++所有安装方式都需要 Python 3.10+,以及一个已经安装和鉴权、能够读写工作目录并执行 shell 命令的 Agent host。完整仓库 clone 或仓库 ZIP 从仓库根目录安装依赖:++```bash+python3 -m pip install -r requirements.txt+```++Skill-only 安装应先找到同时包含 skill 的 `SKILL.md` 与 `requirements.txt` 的安装或解压目录,再从该路径安装:++```bash+python3 -m pip install -r "<installed-skill-dir>/requirements.txt"+```++使用 `npx skills add hugohe3/ppt-master` 还要求本机有可用的 `npx` 命令,通常由 Node.js/npm 提供;仓库没有规定 Node/npm 的最低版本。Host 自带的 `/plugin install` 不走这条 `npx` 路径。安装完成后,从**工作目录**启动 Agent,不要从 host 管理的 skill 缓存目录启动;执行入口会单独解析已安装 skill。安装方式见[快速开始](../../README_CN.md#快速开始),运行规范见 [`SKILL.md`](../../skills/ppt-master/SKILL.md)。++---+## 用模板**可选。** 默认走**自由设计**——不需要模板,可以直接跳到下一节。只有当 deck 必须复用品牌身份、沟通与设计方法、固定版式或重复使用的 Deck 应用时,才需要模板。@@ -58,17 +85,17 @@ Default Generate 把模板选择放在 Stage 1,与沟通契约同屏确认;## 做出第一份 deck-整个流程就三步。先装好环境——只需要 Python,见 [快速开始](../../README_CN.md#快速开始)。+准备好上面的环境和工作目录后,整个流程就三步:-1. **把源材料放进** `projects/` —— PDF、DOCX、Markdown、一个网址,或直接要粘贴的文字。-2. **在对话里告诉 AI** 要把什么做成 deck。Stage 1 会让你同时确认沟通契约与自由设计/模板使用;只附上一个精确工作区 root 时,页面可默认进入模板模式并预选该路径:+1. **把 Agent 可读取的源材料交给它**——PDF、DOCX、Markdown、网址,或直接粘贴的文字都可以。放在 `<工作目录>/inputs/` 之类的目录即可,不需要先手工创建最终的 `projects/<name>/`。+2. **在对话里告诉 AI** 要把什么做成 deck。[Default Generate Step 2](../../skills/ppt-master/workflows/generate-pptx.md)或[Quick 初始化](../../skills/ppt-master/workflows/profiles/quick-generate.md)会在工作目录的 `projects/` 下创建活动项目,并报告精确项目路径。存在文件型材料时才导入;直接粘贴的文字保留在对话上下文,不需要导入。Default 随后进入 Stage 1,同时确认沟通契约与自由设计/模板使用;Quick 会跳过这些确认阶段。Default 只附上一个精确工作区 root 时,页面可默认进入模板模式并预选该路径:```- 你:用 projects/q3-report/sources/report.pdf 做一份 PPT+ 你:用 <报告文件路径.pdf> 做一份 PPT你:把这份内容做成 PPT:<粘贴你的文字>```-3. **拿回可编辑的 `.pptx`**,位于 `exports/<名称>_<时间戳>.pptx` —— 真正的 DrawingML 形状、文本框、图表,在 PowerPoint / Keynote / WPS / LibreOffice 里点开就能改。+3. **拿回可编辑的 `.pptx`**。除非显式指定其他输出路径,文件位于 `<活动项目>/exports/<项目名>_<时间戳>.pptx`。完整仓库 clone 或仓库 ZIP 通常对应 `<仓库根目录>/projects/<生成的项目名>/exports/...`;skill-only 安装则对应 `<工作目录>/projects/<生成的项目名>/exports/...`。应以 Agent 报告的活动项目精确路径为准,不要到仓库根目录查找一个没有项目上下文的 `exports/`。-生成前,Stage 1 同时确认沟通契约、画布/格式与自由设计/模板选择。AI 随后安装所选工作区;最终 Stage 2 读取安装结果,并确认页数、视觉系统、模板应用方式与生产选项。之后内容分析、排版、配图、SVG 生成、导出都由 AI 完成——这就是其它能力围绕的核心环节。不想走交互确认,见下方[快速模式](#快速模式)。+这些术语不是需要你另建的目录。**Stage 1** 会确认沟通契约,即用途、受众、阅读场景、画布/格式,以及自由设计/模板选择。**工作区根目录**是可选的 Brand、Style、Layout 或 Deck 可复用包的根目录,不是活动项目。AI 安装所选工作区后,**Stage 2** 再确认页数、视觉系统、模板应用方式与生产选项。之后内容分析、排版、配图、SVG 生成与导出都由 AI 完成。不想走交互确认,见下方[快速模式](#快速模式)。---