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: repair broken procedures and align statements with the code
hugohe3eadf019fbe47
diff --git a/docs/faq.md b/docs/faq.mdindex 42eb4f72..667a8d20 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -63,6 +63,8 @@ Either way, run `pip install -r requirements.txt` from the installed location soNeither 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: 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.@@ -278,11 +280,15 @@ deck needs still run when required: supplied or extracted images,AI/web/sliced images, project icons, native shapes, charts/tables, and therequired operational manifests or provenance records. Formulas are authoreddirectly as PowerPoint-native markers in the affected SVG, not prepared as-image assets. If a required asset is not ready, it still stops and asks you for-it instead of substituting unrelated material. After preparation, the current agent-hand-authors `svg_output/` to the shared standards, runs the lockless Quick-final quality checker, fixes every blocking error, and only then exports the-final PPTX.+image assets. An explicitly selected manual path or another irreplaceable file+dependency still blocks until you provide the required file. If automated AI+generation or its required slicing is exhausted, Quick instead removes the+failed jobs and stale manifest entries, replans their communication role with+native editable text/SVG or already-prepared non-AI assets, continues the same+run, and discloses the replacement in the final handoff. It never fills the gap+with unrelated material. After preparation, the current agent hand-authors+`svg_output/` to the shared standards, runs the lockless Quick final quality+checker, fixes every blocking error, and only then exports the final PPTX.Ordinary exporter capabilities remain available as needed, including nativechart/table replacement, notes, motion, narration, and diagnostics. Notes,@@ -330,7 +336,7 @@ Think of "using an existing PPT" as two questions: **keep its content or not**,| Keep only content, redo design and pagination | **Generate PPTX** | Source facts; story structure and page count may change || Keep content + keep design | No generation needed | Use the original file |-Use the **beautify profile** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, only layout / hierarchy / whitespace are redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify profile](../skills/ppt-master/workflows/profiles/beautify-pptx.md).+Use the **beautify profile** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, and layout / hierarchy / whitespace are redone. The source palette and fonts are the recommended, preselected defaults; an explicit request or final confirmation can override visual fields, but Beautify never departs from the source identity silently. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify profile](../skills/ppt-master/workflows/profiles/beautify-pptx.md).Use the **main pipeline** when the source PPT is just material: extract it to Markdown with `ppt_to_md`, read PPTX intake facts from `analysis/`, then let Strategist re-architect the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content" or "turn this into a 10-page executive briefing".@@ -346,7 +352,7 @@ There is also one orthogonal route: if you don't want to produce a deck right noYes — 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).+The output stays 100% native-editable PowerPoint: the original design, layouts, images, and animations are preserved, and only the planned pages are exported. It deliberately does **not** author a new layout topology or swap source images. The ordered `slides` roster in `fill_plan.json` may omit, reorder, or repeat source slide shells, so the output page count can differ from the source. 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. When the source library lacks a required new structure, use ordinary Generate, or run Create Template first and then Generate from the resulting workspace. Full steps: [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md).---diff --git a/docs/getting-started.md b/docs/getting-started.mdindex e95a13dc..02a8f4f8 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -90,7 +90,7 @@ A bare template name or style phrase is still only a design brief. Quick keepsits lockless flat export, so Layout / Deck prototypes guide the authored pagesbut do not compile into reusable native Master / Layout objects.-It does not skip capabilities: source conversion, research on identified factual gaps, shared aesthetic guidance, image / icon preparation, and native-shape / chart / table authoring still run as needed. Structural formulas are authored directly as native PowerPoint markers rather than prepared as image assets. If a required asset is missing, it still stops and asks you for it instead of substituting unrelated material.+It does not skip capabilities: source conversion, research on identified factual gaps, shared aesthetic guidance, image / icon preparation, and native-shape / chart / table authoring still run as needed. Structural formulas are authored directly as native PowerPoint markers rather than prepared as image assets. A missing explicitly selected manual asset or other irreplaceable file dependency blocks until you provide it. If automated AI generation or required dependent slicing is exhausted, Quick removes the failed jobs and stale manifest entries, replans with native editable text/SVG or already-prepared non-AI assets, continues the same run, and reports the replacement in its final handoff.Quick is a one-pass profile, not a shortened resumable workflow. It creates no Strategist record, `design_spec.md`, `spec_lock.md`, or substitute page plan; its content/design/resource decisions exist only in the active AI context. If that context is lost before delivery, start Quick again. Operational manifests, quality reports, postflight, and the cold Python audit log may remain, but they cannot reconstruct why the AI designed the deck that way. The profile reduces interaction and durable planning, not the available presentation toolbox or the intended quality bar.@@ -104,7 +104,7 @@ A browser preview opens at the URL reported by the launcher while the deck is be- **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.+- **Or annotate for the AI** — click an element, type what you want changed, click **Add annotation** to stage it, then click **Apply changes** to write the annotation markers to `svg_output/`. Return to chat and say "apply my annotations"; 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)).diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 383c2a93..0839b275 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -496,8 +496,8 @@ PPT Master keeps deck-state roles—Strategist, Image_Generator, and Executor—without interaction, while the Stage-1 communication recommendation is authoredwithout reading those candidates or any template content. The UI confirms thatcommunication contract and the switchable free-design/template choice together;-only afterward does the agent install/fuse a non-free selection. Strategist uses-one dependency-ordered two-stage gate. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Final Stage 2 is authored once from that contract. Strategist first creates exactly three complete, viable, project-fit solutions, then projects each into a custom mode, custom visual style, color, typography, icon, and custom generated-image rendering; the fixed catalogs remain conservative lower-level single-select alternatives. Each direction is one complete design authored top-down within the confirmed contract rather than assembled from catalog picks, and three exist so a single recommendation cannot lock the user in; the fixed catalogs stay the manual lower layer. `custom` has no required relationship to the catalogs, and one selected preset may be carried unchanged. The three bundles are plainly different designs at the whole-deck level, decided before any field is written and only then projected onto mode, visual style, rendering, color, typography, and icons; that difference lives in the solutions rather than in one designated field, so whichever components a direction requires carry it and any component may coincide. A different name, note, or reference count alone is not a difference, and bundles identical on every component are not three solutions. Where authoritative user/template truth fixes some components, the remaining open ones carry the difference; identical projections are valid only when nothing is open, and the plan states that boundary instead of inventing variation. It does not assemble the three solutions afterward from independent component picks or force them into safe / shifted / bold archetypes. After all three bundles are complete, it compares them against the confirmed contract and source, records the strongest overall fit as zero-based `design_directions.selected`, and gives array order no preference meaning. Before reference selection it reads only the three catalog indexes; after each solution's bases are frozen, it reads only the deduplicated selected detail files and completes the custom behaviors. Image source remains an independent judgment, so every solution already has a rendering candidate even when AI imagery is initially not recommended. The preferred top card is marked and applied initially. An inactive top card applies its immutable bundle, each projected custom card becomes editable in place after selection, and all lower controls may diverge; the adjusted active card exposes an explicit restore action, while final state stores only the edited current components. The same stage confirms reading mode, page count, conditional AI acquisition, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Formula handling is not a user-selectable production policy: structural mathematics becomes a native formula marker during authoring. Only after Stage 1 is confirmed, when a template is installed, does Strategist read the project-local workspace and current content, derive **how to apply it**, and expose that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. The three proactive values are fallback policies, not capability bans: the latest explicit user instruction wins, then final Stage 2, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.+only afterward does the agent install every selected spec separately into the+project. Strategist uses one dependency-ordered two-stage gate. Its `delivery_context` recommendation distinguishes presenter-led, reader-led, hybrid, and recorded/self-running use in one prose field, names the primary context, and records any secondary use; hybrid never stands alone without its lead mode. The prose boxes remain editable and none requires a non-empty answer: confirmation persists the current text exactly, and a cleared value stays empty instead of falling back to the recommendation. Final Stage 2 is authored once from that contract. Strategist first creates exactly three complete, viable, project-fit solutions, then projects each into a custom mode, custom visual style, color, typography, icon, and custom generated-image rendering; the fixed catalogs remain conservative lower-level single-select alternatives. Each direction is one complete design authored top-down within the confirmed contract rather than assembled from catalog picks, and three exist so a single recommendation cannot lock the user in; the fixed catalogs stay the manual lower layer. `custom` has no required relationship to the catalogs, and one selected preset may be carried unchanged. The three bundles are plainly different designs at the whole-deck level, decided before any field is written and only then projected onto mode, visual style, rendering, color, typography, and icons; that difference lives in the solutions rather than in one designated field, so whichever components a direction requires carry it and any component may coincide. A different name, note, or reference count alone is not a difference, and bundles identical on every component are not three solutions. Where authoritative user/template truth fixes some components, the remaining open ones carry the difference; identical projections are valid only when nothing is open, and the plan states that boundary instead of inventing variation. It does not assemble the three solutions afterward from independent component picks or force them into safe / shifted / bold archetypes. After all three bundles are complete, it compares them against the confirmed contract and source, records the strongest overall fit as zero-based `design_directions.selected`, and gives array order no preference meaning. Before reference selection it reads only the three catalog indexes; after each solution's bases are frozen, it reads only the deduplicated selected detail files and completes the custom behaviors. Image source remains an independent judgment, so every solution already has a rendering candidate even when AI imagery is initially not recommended. The preferred top card is marked and applied initially. An inactive top card applies its immutable bundle, each projected custom card becomes editable in place after selection, and all lower controls may diverge; the adjusted active card exposes an explicit restore action, while final state stores only the edited current components. The same stage confirms reading mode, page count, conditional AI acquisition, generation mode, the Design Spec review toggle, and whether the agent should proactively generate speaker notes, custom animations, or narration audio. Formula handling is not a user-selectable production policy: structural mathematics becomes a native formula marker during authoring. Only after Stage 1 is confirmed, when a template is installed, does Strategist read the project-local workspace and current content, derive **how to apply it**, and expose that plan as editable `template_application` prose; Stage 2 never reselects a template, and the internal reuse/adherence modes stay hidden. Reading mode decides how meaning is carried by page, visuals, presenter, and notes; its cards do not present px values. The browser may apply the deterministic `reading mode → body baseline → unpinned role sizes` dependency locally, while manual size edits pin visible values. It never regenerates Stage 2. The three proactive values are fallback policies, not capability bans: the latest explicit user instruction wins, then final Stage 2, then the fixed defaults `true / false / false`. Strategist still records non-binding Motion suggestions when useful; a suggestion alone does not activate custom-animation execution. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. Final state has two equivalent carriers: the default UI path reads `confirm_ui/result.json` exactly once after the final wait, while an explicit chat-only or delegated path retains an equivalent final confirmation summary and may produce no `result.json`. Both paths first resolve and persist every effective production outcome into one `design_spec.md` and complete Gate 1 fidelity. With refinement off, lock authoring proceeds immediately. With `refine_spec: true`, the pipeline stops before `spec_lock.md`; the user may revise any part of that same Design Spec through normal chat for any number of rounds, and explicit approval then releases Gate 2 lock authoring. No second Design Spec or parallel lock is maintained. Normal lock authoring and downstream execution do not reread either confirmation channel. Required manual assets may still introduce their own conditional blocking points, so this is not an exclusive claim over every runtime gate. Project validation requires the compact `audience` / `objective` / `core_message` anchor set under `spec_lock.md ## communication` plus an `Audience move` in every §IX Slide block.The three proactive values confirmed in final Stage 2 remain independent rawevidence. In particular, enabling narration may enable the effective Speaker@@ -641,7 +641,7 @@ Several architectural decisions shape this phase:**Manifest-first acquisition.** In-pipeline AI generation always writes `images/image_prompts.json` and renders the sidecar `image_prompts.md`, even for one image. The positional `image_gen.py "prompt"` form is intentionally limited to one-off debugging because it leaves no manifest/sidecar audit trail. Web acquisition mirrors this with `images/image_queries.json` for multi-row batches and `image_sources.json` for attribution/source tracking.-**The Design Spec owns the image-execution path.** Final confirmation from either the UI or chat is first persisted as `AI Image Acquisition Path` in `design_spec.md §I`; Image_Generator selects API, host-native, or manual from that value and may not reopen the decision during execution. `image_gen.py --manifest` belongs only to API Path A. The current CLI still contains a defensive guard that reads UI `result.json` and blocks an accidental Path A call when that file explicitly records `host-native` or `manual`. That guard is not an authority source, does not cover chat-only confirmation, and cannot replace Design Spec routing. It is a remaining implementation mismatch in the upstream authority chain, not a normal consumer path.+**The Design Spec owns the image-execution path.** Final confirmation from either the UI or chat is first persisted as `AI Image Acquisition Path` in `design_spec.md §I`; Image_Generator selects API, host-native, or manual from that value and may not reopen the decision during execution. `image_gen.py --manifest` belongs only to API Path A. For a manifest under `<project>/images/` when `<project>/design_spec.md` exists, the CLI guard reads that persisted value directly: `api` / `auto` permit Path A, while `host-native` / `manual` and a missing or invalid value block it. The guard does not reopen or consume either confirmation channel.**One coherent sheet per compatible visual family.** AI sheets prepare transparent illustration or lettering elements rather than complete page layouts. A family may include repeated title/corner chrome, dominant anchors, supporting figures, and accents with different silhouettes and visual weights; compatible elements share a sheet and split only when cell geometry, detail, quality, or semantic needs conflict. SVG may combine the slices with backgrounds, native shapes, editable text, photos, other slices, and lettering on any suitable page, and one slice may recur across several pages. Decorative lettering remains grouped by visual identity, with controlled glyph-native expression by default and strong or lettering-plus-illustration expression only after an explicit request or confirmed direction. Every sheet uses an explicit flat pure-red/green/blue chroma key whose active channel does not dominate its elements; the same HEX is passed to `slice_images.py --bg`, whose chroma path removes key spill and recovers partial effect alpha. `--strict-alpha` then rejects any nontransparent cell boundary or edge-crossing effect before writing derived files. Successful transparent slices join `images/`, then `analyze_images.py` refreshes their dimensions.diff --git a/docs/templates-architecture.md b/docs/templates-architecture.mdindex c0eb9304..e76175d3 100644--- a/docs/templates-architecture.md+++ b/docs/templates-architecture.md@@ -32,7 +32,7 @@ kind: brand...----# templates/styles/consulting_analytical/templates/design_spec.md+# templates/styles/consulting-decision/templates/design_spec.md---kind: style...diff --git a/docs/windows-installation.md b/docs/windows-installation.mdindex a256ca6c..ba8701fe 100644--- a/docs/windows-installation.md+++ b/docs/windows-installation.md@@ -32,14 +32,25 @@ Python is the only hard requirement.**Option A — Download ZIP** (easiest):-1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)+1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master), or use the [AtomGit mirror](https://atomgit.com/hugohe3/ppt-master) in mainland China2. 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)):+**Option B — Git Clone** (requires [Git](https://git-scm.com/downloads)). Run one of these clone commands:```powershell+# GitHubgit clone https://github.com/hugohe3/ppt-master.git+```++```powershell+# AtomGit mirror+git clone https://atomgit.com/hugohe3/ppt-master.git+```++Then enter the cloned folder:++```powershellcd ppt-master```@@ -133,6 +144,10 @@ Or run PowerShell as Administrator.### `pip install` fails due to network issues```powershell+# Tsinghua PyPI mirror+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple++# Proxypip install -r requirements.txt --proxy http://your-proxy:port```diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex ecbbee0b..435204da 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -21,7 +21,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg## 它是怎么做到的1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。-2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。+2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出 3–6 个候选,并用当前聊天语言为每个写一句调性说明(如“稳重男声·适合财报”)。语速/风格也会基于 notes 信息密度给出推荐值。3. **配置一次确定**。Default Generate 和 Enhance Native 会一次确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频。Quick 直接采用明确值,并自动补齐未指定的 provider、音色、语速和嵌入方式;只有明确要求直接交付视频时才开启视频导出。4. **执行**。Edge、ElevenLabs、MiniMax,以及支持时间戳的 CosyVoice 音色,会依据同一次合成返回的 provider 计时,把每页音频和 SRT 一起写入 `audio/`;Qwen 和显式 CosyVoice 纯音频模式只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于选择旁白 cue 同步的 Generate PPTX,逐页 SRT 与规范自定义动画会让 AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;与旁白无关的自定义动画保留规范计时,没有动画 sidecar 时则继承基础导出的已解析 motion。随后再导出带音频的 PPTX;存在逐页 SRT 时,才从该 PPTX 读回实际计时并合并。自动视频交付继续调用 PowerPoint 原生编码器,存在 cue 时再完成验收后的混音;显式选择实时放映录制时,则捕获 PowerPoint 实际全屏画面与系统音频、跳过混音,并将交付字幕对齐到验收后的录屏。不支持长音频导入或自动拆分。@@ -177,9 +177,9 @@ CosyVoice 的时间戳能力取决于模型和音色组合:`cosyvoice-v3.5-pluQwen 当前 TTS 的 HTTP 与实时响应都只返回音频,不含词级或字符级对齐。PPT Master 因此保留 Qwen 纯音频路径,不用理论时长估算 SRT。需要逐页字幕时,请选择 Edge、ElevenLabs、MiniMax 或支持时间戳的 CosyVoice 音色。-### Provider 能力与参数选择+### 服务商能力与参数选择-| Provider | 逐页 SRT | 原始计时 | 当前默认裁决 |+| 服务商 | 逐页 SRT | 原始计时 | 当前默认裁决 ||---|---|---|---|| Edge | 支持 | 词级 | 保留所选神经网络音色与 `+0%`;只有 notes 密度确实需要时才小幅调速。 || ElevenLabs | 支持 | 原文字符级对齐 | 保留 `eleven_multilingual_v2` 与 `mp3_44100_128`,适合稳定长文旁白。显式调速使用 `--elevenlabs-speed 0.7-1.2`;`eleven_v3` 表现力更强但波动更大,Flash v2.5 更偏延迟与成本。 |@@ -235,7 +235,7 @@ MiniMax、Qwen 与 CosyVoice 使用 `--voice-id` 传入对应平台的系统音**职责切分**:声音复刻本身在 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 分钟 |@@ -264,7 +264,7 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \- **授权** —— 只复刻你自己拥有的、或拿到了明确授权的声音。每个 provider 的服务条款都禁止冒用他人声音。- **语言覆盖** —— 复刻出来的音色会继承说话人的口音。对中英混合等多语 deck,建议挑一个对你样本语言组合处理较好的 provider;ElevenLabs `eleven_multilingual_v2` 和 CosyVoice 通常最宽容。- **字幕能力** —— ElevenLabs 复刻音色和受支持的 CosyVoice 复刻音色可以生成 provider 原生计时 SRT;Qwen 复刻音色在当前 API 下仍只生成音频。-- **Provider 保留策略** —— 只要该音色仍存在于你的 provider 账户中,就可以继续复用对应 `voice_id`;保留、删除与过期规则以各平台政策为准。+- **服务商保留策略** —— 只要该音色仍存在于你的 provider 账户中,就可以继续复用对应 `voice_id`;保留、删除与过期规则以各平台政策为准。## 依赖@@ -272,7 +272,7 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \python3 -m pip install edge-tts```-已写入 `skills/ppt-master/requirements.txt`。`edge-tts` 调用微软的在线 TTS 服务,**生成时**需要联网;生成后的音频是本地文件,PowerPoint 播放和视频导出都不依赖网络。云端 TTS provider 不需要额外 Python 包,直接通过 HTTPS 调用;按 `.env.example` 配置对应 API Key 即可。+已写入 `skills/ppt-master/requirements.txt`。`edge-tts` 调用微软的在线 TTS 服务,**生成时**需要联网;生成后的音频是本地文件,PowerPoint 播放和视频导出都不依赖网络。云端 TTS provider 不需要额外 Python 包,直接通过 HTTPS 调用;API Key 可以设在当前 shell 环境中,也可以按 `.env.example` 写入 `.env`。自动 MP4 导出不增加 Python 依赖,但要求 Windows PowerPoint 2016+ 与 Windows PowerShell;macOS 或没有兼容 PowerPoint 的机器保留带旁白 PPTX,改用手动导出。diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex f87a8275..327eb04d 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -63,7 +63,7 @@ python3 skills/ppt-master/scripts/update_repo.py这两条路径都不带 `.git` 目录,`git describe` 查不到版本。已安装的版本记录在 skill 自身 `SKILL.md` frontmatter 的 `metadata.version` 字段里。-中国大陆地区访问 GitHub 下载不便的话,完整仓库在 [AtomGit](https://atomgit.com/hugohe3/ppt-master) 也有镜像(clone 或下载 ZIP);1 GB 出头的体积在中国大陆地区网络下载一般没问题。+中国大陆地区访问 GitHub 下载不便时,可以从 [AtomGit](https://atomgit.com/hugohe3/ppt-master) 的完整仓库镜像 clone 或下载 ZIP。## Q: 能用 AI 生成配图吗?@@ -253,7 +253,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t**它跳过的是策略师分析、`design_spec.md` / `spec_lock.md` 落盘和分步确认停顿:你明确提出的要求照做;你没提的,当前 Agent 直接决定并继续,不再回来征求同意。** 什么都不提,才是全部由 Agent 决定。它同时跳过 `finalize_svg.py`,因此不生成 `svg_final/` 预览。-它不跳过备料或设计能力:来源转换、已识别事实缺口的研究、共享美学参考,以及生成 deck 所需的资源仍按需准备——用户提供或源文件抽取的图片、AI / 网络 / 切片图片、项目图标、原生形状、图表 / 表格,以及对应的必要运行 manifest 或来源记录。公式由当前 Agent 直接写成受影响 SVG 中的 PowerPoint 原生 marker,不再作为图片资源准备。必需素材未就绪时它仍会停下来跟你要,不会拿无关材料顶替。备料完成后,当前 Agent 按共享规范手写 `svg_output/`,运行无锁的 Quick 最终质量检查并修复所有阻塞错误,之后才导出最终 PPTX。+它不跳过备料或设计能力:来源转换、已识别事实缺口的研究、共享美学参考,以及生成 deck 所需的资源仍按需准备——用户提供或源文件抽取的图片、AI / 网络 / 切片图片、项目图标、原生形状、图表 / 表格,以及对应的必要运行 manifest 或来源记录。公式由当前 Agent 直接写成受影响 SVG 中的 PowerPoint 原生 marker,不再作为图片资源准备。显式选择的 manual 路径或其他不可替代的文件依赖未就绪时,Quick 会阻塞并索取文件。自动 AI 生成或其必需切片路径耗尽时,Quick 则会移除失败任务与过期 manifest 条目,改用原生可编辑文字 / SVG 或已经备好的非 AI 素材承载原沟通任务,继续本次运行,并在最终交接中披露替代结果;它不会拿无关材料顶替。备料完成后,当前 Agent 按共享规范手写 `svg_output/`,运行无锁的 Quick 最终质量检查并修复所有阻塞错误,之后才导出最终 PPTX。原生图表 / 表格替换、讲稿、动效、旁白和诊断等普通导出能力仍可按需使用;讲稿、自定义对象动画和旁白默认关闭,Agent 可在用户要求或 deck 确有需要时自动启用,不会打开确认流程。使用默认输出路径时会生成普通 postflight 报告,并把 `svg_output/` 备份到 `backup/`;显式指定输出路径时沿用普通流程不创建备份的行为。页数本身既不会自动触发,也不会阻止快速生成。@@ -286,7 +286,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-t| 只留内容,设计与分页都重来 | **Generate PPTX** | 源事实;故事结构和页数都可重构 || 留内容 + 留设计 | 不必生成 | 直接用原文件 |-使用 **beautify profile** 的前提是:原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留,只重排版式、层级和留白,并继承原配色字体。典型说法是「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify profile](../../skills/ppt-master/workflows/profiles/beautify-pptx.md)。+使用 **beautify profile** 的前提是:原 PPT 的分页本身就是输出要求的一部分。文字逐字不动、页数页序 1:1 保留,并重排版式、层级和留白。源配色与字体是推荐且预选的默认值;用户显式要求或最终确认可以覆盖视觉字段,但 Beautify 不会在未经确认时静默偏离源身份。典型说法是「把这份 PPT 美化一下 / 重新排版,内容别动」。见 [beautify profile](../../skills/ppt-master/workflows/profiles/beautify-pptx.md)。用 **主管线** 的前提是:原 PPT 只是内容材料。流程会用 `ppt_to_md` 抽成 Markdown,并读取 `analysis/` 里的 PPTX intake 事实,再由 Strategist 自由重构大纲(合页 / 拆页 / 换序)。典型说法是「用这份 PPT 的内容重做一份更好的」或「提炼成 10 页高管汇报」。@@ -302,7 +302,7 @@ beautify 和主管线的一句话判别:**原来的分页是要保留的信息可以——这就是 **套模板(template fill)** 路径,独立于 SVG 生成管线。把你现成的 `.pptx` 连同素材(或一个主题)给 AI,说「套模板 / 把这些填回去」。它会把你的 deck 当作原生页面库,只挑适合新内容的页面(可乱序、可重复),把新文字——以及原生表格单元格、图表数据——直接写回原始 OOXML。-输出仍是 100% 原生可编辑的 PowerPoint:原设计、母版、图片、动画都保留,且只导出选中的页面。它刻意**不**改版式、不加页、不换图——一份 deck 的页面结构本身承载着逻辑(总分、对比、递进),所以应挑选结构本就契合内容的页面,而不是硬塞进去。若需要全新结构或不同页数,请改用 create-template(见下一问)。完整步骤:[套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。+输出仍是 100% 原生可编辑的 PowerPoint:原设计、母版、图片、动画都保留,且只导出计划中的页面。它刻意**不**创作新的版式拓扑,也不替换源图。`fill_plan.json` 中有序的 `slides` 清单可以省略、乱序或重复源页面壳,因此输出页数可以不同于源文件。一份 deck 的页面结构本身承载着逻辑(总分、对比、递进),所以应挑选结构本就契合内容的页面,而不是硬塞进去。若源页面库缺少所需的新结构,请走普通 Generate,或先 Create Template、再从产出的工作区 Generate。完整步骤:[套模板工作流](../../skills/ppt-master/workflows/template-fill-pptx.md)。---@@ -340,7 +340,7 @@ python3 skills/ppt-master/scripts/pptx_template_import.py <deck.pptx> --manifest完整导入 SVG 可以保留高级 PowerPoint 形状所需的 metadata、隐藏 carrier 和预览指纹,并作为载荷后备留在临时分析工作区且保持不可变。模板创建使用带文档内 source ref 和紧凑路径/hash manifest 的轻量可编辑 IR。`standard` / `fidelity` 创作项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化最终模板,只为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已经支持的载荷;不支持或已修改的对象保留当前 SVG fallback。-没有源 PPTX 时,截图集也能跑(`cover.png` / `toc.png` / `chapter.png` / `content.png` / `closing.png`),但保真度会明显下降。建议优先找原始 PPTX。这里提取的是可复用模板系统;如果目标是把每个页面画面还原成分层可编辑输出页,应改用图片还原为 PPTX(`image-to-pptx`)。+没有源 PPTX 时,也可以提供关键页面类型的截图——封面、目录、章节、内容和结尾——但此时几何、字体和继承关系只能根据画面推断。这里提取的是可复用模板系统;如果目标是把每个页面画面还原成分层可编辑输出页,应改用图片还原为 PPTX(`image-to-pptx`)。**第二步 — 让 AI 创建模板**diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.mdindex 88f43ee8..9dd6b9c0 100644--- a/docs/zh/getting-started.md+++ b/docs/zh/getting-started.md@@ -89,7 +89,7 @@ Brand / Style / Layout / Deck 工作区 root,它会直接校验、安装并使Quick 保持无锁 flat 导出,因此 Layout / Deck 原型会指导页面创作,但不会编译成可复用的原生 Master / Layout 对象。-它不跳过能力:来源转换、事实缺口研究、共享美学规范、图片 / 图标准备,以及原生形状 / 图表 / 表格创作仍按需运行。结构性公式直接写成 PowerPoint 原生 marker,不再作为图片素材准备。必需素材缺失时它会停下来跟你要,不会拿无关材料顶替。+它不跳过能力:来源转换、事实缺口研究、共享美学规范、图片 / 图标准备,以及原生形状 / 图表 / 表格创作仍按需运行。结构性公式直接写成 PowerPoint 原生 marker,不再作为图片素材准备。显式选择的 manual 素材或其他不可替代的文件依赖缺失时,Quick 会阻塞并索取文件;自动 AI 生成或其必需切片路径耗尽时,Quick 会移除失败任务与过期 manifest 条目,改用原生可编辑文字 / SVG 或已经备好的非 AI 素材,继续本次运行,并在最终交接中披露替代结果。快速模式是一次性生成,不是缩短后的可续接流程。它不产生 Strategist 记录、`design_spec.md`、`spec_lock.md` 或替代性的页面计划;内容、设计和资源决策只存在于 AI 的当前上下文。交付前一旦丢失该上下文,就重新运行 Quick。资源 manifest、质量报告、postflight 与冷 Python 审计日志可以保留,但无法还原 AI 为什么这样设计。该 profile 省掉的是交互和持久规划,不是 PPT 能力或预期质量标准。@@ -103,7 +103,7 @@ Quick 保持无锁 flat 导出,因此 Layout / Deck 原型会指导页面创- **实时看着每页渲染**出来。- **直接改,无需 AI** —— 选中元素后在右栏改文字、颜色、字体、字号;拖拽即可移动,或用方向键微调(`Shift` = 10px),`Ctrl+Z` 撤销。改动即时预览,点 **Apply changes** 写回 `svg_output/`。-- **或写注解交给 AI** —— 点选元素写一句要改成什么,点 **Submit annotations**,再回对话说"应用注解"(或 "apply my annotations"),AI 会改写那块区域并重新导出 PPTX。+- **或写注解交给 AI** —— 点选元素写一句要改成什么,点 **Add annotation** 暂存,再点 **Apply changes** 把注解标记写入 `svg_output/`;回到对话说“应用注解”(或 “apply my annotations”),AI 会改写那块区域并重新导出 PPTX。PPT Master 最初是纯对话设计;可视化编辑是在很多用户提出后融入的(建立在 [@WodenJay](https://github.com/WodenJay) 的 [PR #85](https://github.com/hugohe3/ppt-master/pull/85) 之上)。diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex 929c180c..9403f892 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -116,12 +116,13 @@ PowerPoint 意图| 行内混合格式 | 不带定位的 `<tspan>` run | 同一文本框内的 DrawingML run | `Native-normalized`;已登记 run 格式仍可编辑 | 改变文本框几何的定位可能会拆分结果 || 作者断行与多段落文本 | 一个 `<text>` 加直接定位的 `<tspan>` 行 | 默认在一个禁用自动换行的文本框中保留作者断行;普通生成文本框会随后续编辑调整大小,精确框和结构化多行占位符 carrier 保持原有固定尺寸行为;语义段落边界仍为 `a:p` | `Native-normalized` | `--reflow-text` 允许 PowerPoint 重排;`--no-merge` 为每一视觉行生成一个形状 || 有意义的文本空白 | `<text>`/`<tspan>` 上精确的 `xml:space="default"` 或 `xml:space="preserve"` | 可编辑 DrawingML run 中归一化或保留的 U+0020 文本 | `Native-normalized`;保留行内 run 所有权 | 使用项目 Chromium/SVG2 合同:LF/TAB 转为空格,`default` 跨 run 折叠,`preserve` 全部保留,Unicode 间隔字符保持字面值;CSS `white-space` 与 SVG 1.1 遗留换行删除不在映射内 |-| 字体 | 根据项目 lock 解析的规范 `font-family` | 直接 typeface 或已登记 theme font | 在安装字体/替换边界内为 `Native-stable` | 校验会报告未锁定或不可用字体 |+| 字体 | 解析为 `spec_lock` 结构角色或可安全导出的上下文选择的规范 `font-family` | 直接 typeface 或已登记 theme font | 在安装字体/替换边界内为 `Native-stable` | 报告不可用或不安全的字体;安全的上下文字体只记录信息,不构成 lock 失败 || 字号 | 有限、无单位的 SVG px,例如 `font-size="24"` | DrawingML 百分之一磅;`1 px = 0.75 pt` | 单位转换后为 `Native-stable` | 生成创作只使用无单位 px;已登记历史单位是会产生 warning 的兼容输入,未知单位为 error;DrawingML 下限为 1 pt || 字重 | `<text>`/`<tspan>` 上已登记的 `font-weight` | DrawingML 常规/粗体 run 开关 | `Native-normalized`;数值字重会折叠到 DrawingML 布尔边界 | 精确取值语法与别名属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 斜体、下划线与删除线 | `<text>`/`<tspan>` 上已登记的 `font-style` / `text-decoration` | DrawingML 斜体、下划线与删除线 run 属性 | 已登记 token 为 `Native-stable` | 拒绝未知 token;精确语法属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 普通文本上标与下标 | `<tspan>` 上精确的直接属性 `baseline-shift="super|sub"`;显式 run `font-size` 与之独立 | 可编辑普通文本 `a:rPr@baseline`,取值为 `30000` / `-25000`;不会自动缩小字号 | 前向导出为原生能力。PPTX-to-SVG 不在可见 SVG 中重建 baseline shift;未修改的导入 `txBody` metadata 与源保留型原生工作流仍可保留来源 run | 拒绝 inline style、其他元素、数值偏移及与行内公式 marker 组合;结构化数学使用可编辑 OMML,Unicode 字形仍是字面文字 |-| 文本填充与透明度 | 规范 fill 加 run alpha | DrawingML run fill 与 alpha | `Native-normalized` | 使用语义 alpha 通道,不使用未登记 CSS 效果 |+| 纯色/渐变文本填充与透明度 | 规范纯色/渐变 fill 加 run alpha | DrawingML run fill 与 alpha | `Native-normalized` | 使用语义 alpha 通道,不使用未登记 CSS 效果 |+| 图片或纹理文本填充 | `<text>` / 不带定位的 `<tspan>` 的 fill 引用一个带注解的单图 `pattern` | 可编辑 DrawingML run `a:blipFill`,使用原生 `stretch` 或 `tile` | 正向导出为原生能力;`stretch` 为 `Native-normalized`,`tile` 的缩放/相位可能归一化;回导暂不重建该填充 | 要求 `data-pptx-text-image-fill="stretch|tile"`、一个直接有效的 `<image>`,且 `<image>` 不带 `clip-path` / `filter` / `mask` / `transform`;见 [`svg-effects.md` §6.3](../../skills/ppt-master/references/svg-effects.md#63-gradients-and-paint-effects) || 文本轮廓 | 文本上已登记 stroke | DrawingML run outline | `Native-normalized` | 轮廓承载精细视觉意义时需复核 || 文本对齐 | 已登记的 `text-anchor` 与段落语义 | 段落对齐加归一化文本框位置 | `Native-normalized` | 不支持 run 级锚定与浏览器 baseline 启发式;精确放置属于 [`svg-effects.md` §6.7](../../skills/ppt-master/references/svg-effects.md#67-advanced-text-treatments) || 文本框垂直对齐 | 无规范生成 SVG 控制;生成文本框使用顶部对齐 | 顶部对齐的 DrawingML text body | 导入的文本框垂直锚定可能被归一化,但主路线不公开通用创作控制 | 不得从 SVG baseline 或浏览器排版行为推断垂直对齐 |@@ -152,7 +153,7 @@ PowerPoint 意图| PowerPoint 功能 | 项目表达 | PPTX 结果 | 回导与保真度 | 校验边界 ||---|---|---|---|---|| 无填充 | `fill="none"` | `a:noFill` | `Native-stable` | 生成 SVG 使用小写规范拼法 |-| 纯色填充 | 已锁定规范 `fill="#RRGGBB"` | `a:solidFill`;当锁定角色可精确复用时使用 theme token | `Native-stable` | 兼容颜色拼法可产生 warning;格式错误或生成未锁定值失败 |+| 纯色填充 | 规范 `fill="#RRGGBB"`,可以是具名 lock 锚点或上下文页面颜色 | `a:solidFill`;当锚点角色可精确复用时使用 theme token | `Native-stable` | 兼容颜色拼法可产生 warning;格式错误会失败,合法的上下文颜色只记录信息 || 填充透明度 | 不透明 fill 加 `fill-opacity` | 原生 alpha | `Native-stable` | 生成值为 0 到 1 的有限无单位数 || 线性渐变填充 | `<defs>` 中已登记 `<linearGradient>` | 原生 `a:gradFill` | `Native-normalized` | stop、坐标、transform 与引用必须遵循封闭合同 || 径向渐变填充 | 已登记 `<radialGradient>` | 可偏心单点焦点的圆形 DrawingML 渐变 | `Approximate`;位于规范圆内的有效焦点可往返,外圆中心与半径会归一化 | 有效焦点必须落在中心 `(0.5,0.5)`、半径 `0.5` 的规范圆内;回导会居中越界焦点并记录诊断;对半径或外圆中心敏感的设计需复核 |diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.mdindex d7dcfeea..d861d92d 100644--- a/docs/zh/roadmap.md+++ b/docs/zh/roadmap.md@@ -20,7 +20,7 @@一份演示文稿由四层构成:页面上有什么、如何组织、如何行动、文档自身如何结构化。下面的表把每一层与 PPT Master 今天的实现对应起来。-**这是地图,不是待办清单。**「有意边界」与「有意的不对称」是**已定形态**而非未完成的格子——那里的空白是决定,不是欠账。「暂不考虑」的行会在该行内写明为什么现在不做。只有「信号驱动」的行偏开放,其理由留在下面的[未来方向](#未来方向信号驱动)一节,不在此重复。真正被论证过的立场放在 [Non-goals](#明确不做non-goals);这张地图只描述,不做裁决。+**这是地图,不是待办清单。**「有意边界」与「有意的不对称」是**已定形态**而非未完成的格子——那里的空白是决定,不是欠账。「暂不考虑」的行会在该行内写明为什么现在不做。只有「信号驱动」的行偏开放,其理由留在下面的[未来方向](#未来方向信号驱动)一节,不在此重复。真正被论证过的立场放在[明确不做](#明确不做);这张地图只描述,不做裁决。| 状态 | 含义 ||---|---|@@ -133,7 +133,7 @@----## 明确不做(Non-goals)+## 明确不做下面这些方向被多次提过,已经评估并决定**不做**。列出来不是否定需求价值,而是说明它们与本项目产品方向不匹配;如果你刚好需要这些能力,建议看其他工具或 fork 本项目走自己的路。@@ -187,4 +187,4 @@ Generate PPTX 路线围绕完全可控的新形状、文字与版式创作。结- **Discussions**:[github.com/hugohe3/ppt-master/discussions](https://github.com/hugohe3/ppt-master/discussions) — 用法讨论 / 经验分享- **邮箱**:[email protected]-提需求前先扫一眼上面的 **Non-goals**;如果你的需求落在那一节,多半不会被采纳,但欢迎讨论是否还有别的路径解决你的真实问题。+提需求前先扫一眼上面的**明确不做**;如果你的需求落在那一节,多半不会被采纳,但欢迎讨论是否还有别的路径解决你的真实问题。diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 693ce2ab..cd190517 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -381,8 +381,9 @@ Style 只贡献自己的 Design Spec,不携带素材或审阅 payload;项目`<template_workspace>` 可以是 `skills/ppt-master/templates/<kind>/<id>/`,也可以是 `projects/<name>/` 等其他精确 root。Step 3 只把它记录为候选输入,-不读取模板内容;Stage 1 选中后,apply 阶段才把它校验、合成并安装到当前项目-的 `templates/`、`images/`、`icons/`,且不复制 `exports/`。模板感知的+不读取模板内容;Stage 1 选中后,apply 阶段才逐个校验 root,把每份选中 `spec`+作为独立的项目本地贡献安装到当前项目的 `templates/`,并把对应的真实素材+安装到 `images/`、`icons/`,且不复制 `exports/`、不合并 `spec` 正文。模板感知的Strategist 及后续角色只读该项目本地副本。Project root 可直接被其他项目复用;把其中一项迁入 library 时保留 spec schema 与素材,但要把限定名改为单 kind 库路径下的裸 spec,再由全局索引注册决定它是否作为 library 选项出现。@@ -394,7 +395,7 @@ Strategist 及后续角色只读该项目本地副本。Project root 可直接| Kind | 拥有的片段 | 典型内容 | 对 Strategist 的影响 ||---|---|---|---|| `brand` | 身份片段 | 配色、字体、logo、语气、图标风格 | 锁定身份;结构保持自由 |-| `style` | 方向/方法片段 | 沟通方法、开放页面角色、证据/数据规则、视觉默认值、图片/图标方向、审阅关注点 | 作为 Stage 2 起点;Style-only 保持 flat,与 Layout/Deck 合成时沿用所选结构;不升级为身份真值,也不触发 visual review |+| `style` | 方向/方法片段 | 沟通方法、开放页面角色、证据/数据规则、视觉默认值、图片/图标方向、审阅关注点 | 作为 Stage 2 起点;Style-only 保持 flat,存在已安装的 Layout/Deck 时遵循其结构计划;不升级为身份真值,也不触发 visual review || `layout` | 品牌中立的结构片段 | 画布、页面结构、语义文字角色/空间行为、页面类型、SVG roster | 提供结构能力;身份与沟通应用仍由下游决定 || `deck` | 应用段 + 一体化身份/结构 | 重复场景、受众与结果、代表性页面角色、身份和真实 SVG roster | 提供描述性语境和身份;没有 Layout 覆盖结构时才提供原型 |@@ -418,10 +419,9 @@ PPT Master 把拥有 deck 状态的 Strategist、Image_Generator 和 Executor**模板选择与沟通契约在 Stage 1 同时确认。** Step 3 只在内部准备候选;Stage-1 沟通推荐的编写不得读取这些候选或任何模板内容。UI 在同一次提交中-确认沟通契约与可切换的自由设计/使用模板选择;只有确认后,Agent 才安装或-合成非自由设计选择。Strategist 采用一个按依赖排序的两阶段 gate。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。最终 Stage 2 只从该契约计算一次,同时确认完整 PPT 方案与生产机制:阅读模式、叙事 mode、页数、成套视觉系统、图片来源、生成图渲染、条件式 AI 图片获取路径、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。公式处理不是用户选择的生产策略:结构性数学内容在创作时直接成为原生公式 marker。仅在 Stage 1 确认后,存在已安装模板时,Strategist 才读取项目本地工作区和当前内容,推导**如何应用**并以可编辑的 `template_application` 自然语言展示;Stage 2 不会重新选模板,内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算 Stage 2。三个主动执行值是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → 最终 Stage 2 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。+确认沟通契约与可切换的自由设计/使用模板选择;只有确认后,Agent 才把非自由设计选择安装成彼此独立的项目本地 `spec`。Strategist 采用一个按依赖排序的两阶段 gate。`delivery_context` 在同一个开放文本字段中区分演讲者主导、读者主导、混合、录制/自动播放,明确主要场景并记录可选的次要用途;混合场景不能只写“混合”而不说明由哪一种主导。其中的文本框仍承载可编辑推荐,且没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。最终 Stage 2 只从该契约计算一次,同时确认完整 PPT 方案与生产机制:阅读模式、叙事 mode、页数、成套视觉系统、图片来源、生成图渲染、条件式 AI 图片获取路径、生成模式、Design Spec 审核开关,以及 Agent 是否主动生成讲稿、自定义动画和旁白音频。公式处理不是用户选择的生产策略:结构性数学内容在创作时直接成为原生公式 marker。仅在 Stage 1 确认后,存在已安装模板时,Strategist 才读取项目本地工作区和当前内容,推导**如何应用**并以可编辑的 `template_application` 自然语言展示;Stage 2 不会重新选模板,内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算 Stage 2。三个主动执行值是用户未明确要求时的兜底策略,不是能力禁用开关;优先级固定为「用户最新明确指令 → 最终 Stage 2 → `true / false / false` 默认值」。Strategist 仍可按内容给出非绑定的 Motion suggestion,建议本身不会启动自定义动画执行。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终状态有两个等价载体:默认 UI 路径在最终等待返回后只读取一次 `confirm_ui/result.json`;显式 chat-only 或委托路径保留等价的最终确认摘要,并可不产生 `result.json`。两条路径都会先解析并把生产流程的最终有效结果固化到同一份 `design_spec.md`,再完成 Gate 1 fidelity。未开启 refine 时立即进入 lock 编写;`refine_spec: true` 时,流程会在 `spec_lock.md` 之前暂停,用户可以通过正常聊天任意修改这同一份 Design Spec、迭代任意轮次,明确批准后才释放 Gate 2 并编写 lock。流程不会维护第二份 Design Spec 或并行 lock。正常的 lock 编写与下游执行不再回读确认通道。必需人工素材未就绪仍可能引入条件式阻塞点,因此这里不是对所有 runtime gate 的排他声明。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。-三套成套方向仍把 mode、visual style 与生成图 rendering 投影为可编辑的 `custom`。每套方向都是在已确认契约内自顶向下完成的一套完整设计,而不是自下而上从目录里拼选出来的;给三套是为了不让单一推荐把用户锁死,固定 preset 目录始终是供用户手动选择的下层。其 custom 投影不受“与 preset 是什么关系”的约束,可以原样承接一个 preset。`custom` 与 preset 目录没有固定关系,一个最合适的 preset 也可以原样成为完整基础。三套方案在整份 deck 的层面本身就显著不同:先定下三个大方案,再补全各自细节,最后才映射到 mode、visual style、rendering、色彩、字体和图标等具体选项。差异存在于方案本身,而不是由某个指定字段来证明——由该方案设计真正需要的组件承担,任何组件都可以承担,也任何组件都允许一致。仅换名称、note 或参考数量不构成差异;所有组件都完全相同的三项也不成其为三套方案。当用户或模板的真值锁定了部分组件时,由其余开放组件承担差异;只有在没有任何开放组件时投影才可以完全相同,并须如实说明边界而不是强行制造差异。+三套成套方向仍把 mode、visual style 与生成图 rendering 投影为可编辑的 `custom`。每套方向都是在已确认契约内自顶向下完成的一套完整设计,而不是自下而上从目录里拼选出来的;给三套是为了不让单一推荐把用户锁死,固定 preset 目录始终是供用户手动选择的下层。其 custom 投影不受“与 preset 是什么关系”的约束,可以原样承接一个 preset。`custom` 与 preset 目录没有固定关系,一个最合适的 preset 也可以原样成为完整基础。三套方案在整份 deck 的层面本身就显著不同:先定下三个大方案,再补全各自细节,最后才映射到 mode、visual style、rendering、色彩、字体和图标等具体选项。差异存在于方案本身,而不是由某个指定字段来证明——由该方案设计真正需要的组件承担,任何组件都可以承担,也任何组件都允许一致。仅换名称、note 或参考数量不构成差异;所有组件都完全相同的三项也不成其为三套方案。当用户或模板的真值锁定了部分组件时,由其余开放组件承担差异;只有在没有任何开放组件时投影才可以完全相同,并须如实说明边界而不是强行制造差异。三套成套方案全部完成后,Strategist 才按已确认契约与来源比较整体适配度,把首选方案的实际零基索引写入 `design_directions.selected`;数组顺序不表示偏好。选择参考前只读取 mode、visual style 与 rendering 的三个目录索引;各方向的基础冻结后,只读取去重后的已选细节文件并完成 `custom` 行为。图片来源是独立判断,所以即使最初不推荐 AI 图片,每套方向也已包含 `rendering` 候选。首选方向卡片会被标记并在初始时应用;点击未激活的方向卡片会应用其不可变的整套方案,选中的 `custom` 投影卡片随后可原位编辑,下层控件也可彼此分离。已调整的活动卡片提供显式恢复操作,最终状态只保存编辑后的当前组件值,不把方向 `id` 当作执行权威。最终 Stage 2 确认的三个主动执行值始终保留为相互独立的原始证据。尤其是,启用旁白可以在 Design Spec 中启用 Speaker Notes 的最终有效结果,@@ -487,7 +487,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge该视图省略 Executor core 已经恒定加载的通用 SVG/图标禁令,只保留项目专属 forbidden 行。图片从当前页 brief、图片资源表中的显式页分配和 mirror 原型引用中选择;已分配给其他页面的图片会被排除,仍无法归属的 legacy 图片保留在兼容子集中,只有所有锁定图片都能确定归属到其他页面时才记录 `confirmed-none`。-这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_visualizations`(某页选中的 `chart|table/<key>` 页面级参考;它只触发读取对应 family SVG 与 §VII Usage,不锁定最终信息模型、类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。每个决策所有者会先读取自己完整而紧凑的能力地图:Chart 规划读取客观的 33 项表达词汇表,而不是制作说明;Table 规划读取其小型 registry;Executor 在局部轮廓选择前读取完整 187 项 preset shape 词汇表。选中参考后,只有对应的精确细节或实现来源进入职责上下文。定性 Structure 直接在 §IX 描述并根据这些关系现场生成,没有 §VII 行、`page_visualizations` key 或 catalog SVG。旧 `page_charts` 仍可读取,但新规划不再写入;历史 Structure bare key 只保留为不带 SVG reference 的语义意图。选定 custom 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`;当它使用已有目录项时,再用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 id。执行阶段对单个参考按 behavior 直接应用;只有多个参考才按各自贡献综合。未使用目录项的 custom 不写参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有 catalog 参考、没有图片,很多时候是设计选择,而不是漏填。+这份 lock 同时也是逐页路由表。除了全局配色和字体,它还承载 `page_rhythm`(`anchor` / `dense` / `breathing`)、`page_visualizations`(某页选中的 `chart|table/<key>` 页面级参考;它只触发读取对应 family SVG 与 §VII Usage,不锁定最终信息模型、类型或几何)、带放置/裁剪契约的图片行,以及决定加载哪些执行规则文件的 `mode` / `visual_style`。每个决策所有者会先读取自己完整而紧凑的能力地图:Chart 规划读取客观的 33 项表达词汇表,而不是制作说明;Table 规划读取其小型 registry;Executor 在局部轮廓选择前读取完整 187 项 preset shape 词汇表。选中参考后,只有对应的精确细节或实现来源进入职责上下文。定性 Structure 直接在 §IX 描述并根据这些关系现场生成,没有 §VII 行、`page_visualizations` key 或 catalog SVG。旧 `page_charts` 仍可读取,但新规划不再写入;历史 Structure bare key 只保留为不带 SVG reference 的语义意图。选定 `custom` 方向时,lock 还承载已消解的 `mode_behavior` / `visual_style_behavior`。每个 `custom` 可以使用零个、一个或多个目录基础,参考数量没有固定上限;只要实际使用了目录内容,就用可选的 `mode_references` / `visual_style_references` / `image_rendering_references` 记录全部精确 `id`。单个 `id` 可以原样承担完整 `preset` 行为;多个 `id` 则必须各自承担不同的可执行职责。这些 `id` 保留来源、约束实现并限定唯一允许读取的细节文件;真正全新的 `custom` 省略对应参考字段。`template_reuse_scope: mirror|layout` 项目的 lock 还承载 `page_layouts`(每页继承哪个输入模板 SVG)、唯一的 `pptx_masters` / `pptx_layouts` 定义,以及 `page_pptx_layouts` 页面分配;`template_reuse_scope: style`、自由设计和 brand-only 项目使用 `pptx_structure.mode: flat`,那些段整段省略,而不是写成空值。其余字段的空值本身仍是信号:没有 catalog 参考、没有图片,很多时候是设计选择,而不是漏填。`page-context v2` 保留为按需投影器。每次调用都会输出绑定 `lock_source.sha256` 的紧凑全局锚点、当前 §IX/资源/路由 delta,以及大型引用的带 scope 路径/SHA 指纹;该投影既不是颜色/字体白名单,也不是替代权威。只有明确的诊断/统计需求,或页面/模板/可视化参考的路径-SHA 问题仍未解决时才调用。有效且未压缩的上下文中做有界精确回修,可以只回读修改片段并校验;fresh、已压缩、外部、来源不明、结构性或投影不符的修改必须完整读取 Design Spec 与 lock。flat 页面没有原型引用;structured 页面使用权威完整 SVG。manifest 与 text-slot sidecar 只保留为派生工具诊断,不注入页面创作上下文。@@ -538,7 +538,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge**Manifest-first 获取。** 流水线内的 AI 图片生成永远先写 `images/image_prompts.json`,并渲染旁路 `image_prompts.md`,哪怕只有一张图。`image_gen.py "prompt"` 这种位置参数形式只保留给一次性调试,因为它没有 manifest / sidecar 审计轨迹。网络图片获取也类似:多行 web 资源写入 `images/image_queries.json` 批量执行,并用 `image_sources.json` 追踪来源和致谢信息。-**图片执行路径以 Design Spec 为权威。** UI 或聊天中的最终确认都先固化为 `design_spec.md §I` 的 `AI Image Acquisition Path`;Image_Generator 根据该值选择 API、host-native 或 manual,不能在执行阶段重新决定。`image_gen.py --manifest` 只属于 API Path A。当前 CLI 仍保留一个读取 UI `result.json` 的防误调用 guard,用于在该文件明确记录 `host-native` / `manual` 时阻止误跑 Path A;它不是权威来源,不覆盖 chat-only,也不能替代 Design Spec 的路线判断。这是当前代码与上游权威链尚未闭合的实现差异,不能当作正常消费路径。+**图片执行路径以 Design Spec 为权威。** UI 或聊天中的最终确认都先固化为 `design_spec.md §I` 的 `AI Image Acquisition Path`;Image_Generator 根据该值选择 API、host-native 或 manual,不能在执行阶段重新决定。`image_gen.py --manifest` 只属于 API Path A。当 manifest 位于 `<project>/images/` 且 `<project>/design_spec.md` 存在时,CLI 防误调用检查直接读取该持久值:`api` / `auto` 允许 Path A,`host-native` / `manual` 以及缺失或非法值都会阻止执行。该检查不会重新打开或消费任一确认通道。**每个兼容视觉家族尽量共用一张 sheet。** AI sheet 准备的是透明插图或艺术字元素,而不是完整页面。一个家族可以同时包含重复使用的标题 / 四角装饰、大型视觉锚点、辅助人物和点缀元素;轮廓与视觉重量可以不同,只在 cell 几何、细节、质量或语义需求冲突时拆分。SVG 可以在任何合适的页面上把这些切片与背景、原生形状、可编辑文字、照片、其他切片和艺术字组合起来,同一元素也可以跨页复用。艺术字仍按视觉身份分组,默认采用克制的字形内生表达,只有用户明确要求或确认了强表现 / 艺术字加插画组合方向才提高强度或加入外部元素。每张 sheet 使用一个有效通道不主导元素色彩的显式纯红、纯绿或纯蓝键,并把同一 HEX 传给 `slice_images.py --bg`;chroma 路径会去除键色污染并恢复效果的半透明度,随后 `--strict-alpha` 在写入派生文件前拒绝任何未透明的 cell 边界或越界效果。成功切出的透明元素进入 `images/`,随后重跑 `analyze_images.py` 刷新尺寸。@@ -546,7 +546,7 @@ Generate 路由会在加载流程前选定一份运行时权威:[`workflows/ge**开发期外部引用,下游分叉成预览与原生导出两套嵌入策略。** 在 `svg_output/` 里编辑时,图片是外部文件引用——快速迭代、单点替换。随后分成两种表达:`svg_final/` 对普通位图和受支持的 SVG 资源执行 Base64 内联,EMF/WMF 则保留外部引用供 native PPTX passthrough;个别资源内联失败会计入处理错误,但不会回写作者源或让 finalizer 整体失败。native PPTX 则把位图或 Office vector 复制进 PPTX 的 media 文件夹,用 `<a:srcRect>` 表达受支持的位图裁剪。分叉的理由是职责不同:前者服务视觉预览,后者服务项目转换器生成的可编辑 DrawingML。`svg_final/` 不是无条件脱离项目资产即可搬运的交换格式,也不作为 PowerPoint 手工“转换为形状”的兼容源。-**一份渲染锁、继承 PPT 色彩锚点、逐图确定构图。** 当 deck 包含 AI 生成图片时,Stage 2 会在每套成套设计方向中确认 deck 级 `rendering`;一个选定的 rendering preset 可以不加人为差异地提供完整处理。图片颜色不再形成第二次用户决策:Image_Generator 从 `spec_lock.md colors` 的核心 HEX 角色出发,再结合完整 Design Spec 与每项资源按用途推导的 `type` 或 hero-page 构图。渲染可以在不改变核心角色语义的前提下,按上下文派生色阶、材质色、明暗过渡与氛围色;不得用一套无关的图片专属调色替换 deck 身份。重复使用的派生色可以提升为具名 lock 角色。+**一份渲染锁、继承 PPT 色彩锚点、逐图确定构图。** 在决定是否推荐 AI 图片之前,Stage 2 就会在三套成套设计方向中各自准备一份完整的 deck 级 `custom` `rendering` 候选:先用 `rendering` 索引冻结所需基础,再只读取那些已选细节文件;一个选定的 `rendering` `preset` 可以不加人为差异地提供完整处理。图片来源是另一项独立判断:未选择 AI 时 UI 隐藏 `rendering` 控件,选择 AI 后直接显示已经准备好的三份可编辑 `custom` 候选与固定 `rendering` 目录,不再触发一次推荐。只有最终确认使用 AI,当前选中的 `rendering` 才进入执行契约。图片颜色不再形成第二次用户决策:Image_Generator 从 `spec_lock.md colors` 的核心 HEX 角色出发,只读取已选 `rendering` 项或 `custom` 的精确基础,再结合完整 Design Spec 与每项资源按用途推导的 `type` 或 hero-page 构图。渲染可以在不改变核心角色语义的前提下,按上下文派生色阶、材质色、明暗过渡与氛围色;不得用一套无关的图片专属调色替换 deck 身份。重复使用的派生色可以提升为具名 lock 角色。---@@ -698,7 +698,7 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“**为什么内部应用计划保留两个字段。** Strategist 推导 `template_reuse_scope`,记录字面镜像复用、结构化版式复用或 flat 风格参考;structured 计划再推导 `template_adherence: strict|adaptive`。`page_layouts` 记录完整创作原型,`pptx_masters` / `pptx_layouts` 记录唯一可复用定义,`page_pptx_layouts` 记录页面分配。strict 保持声明的原型合同;adaptive 保持原型 Master,只有固定 Layout 原子或槽位 topology/bounds 改变时,Strategist 才可声明新 Layout。若制作过程暴露出这一需求,执行必须退回上游,待 Strategist 更新、回读并校验定义与分配后才能继续;导出器不会事后推断。这些是导出器内部值,不是用户确认选项。模板定义即使暂时没有页面使用,也能注册进最终文件。layout 的皮肤由项目控制;mirror 还要保持字面视觉与文字节点拓扑。`style` 不带 adherence 或结构 mapping。-**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把锁定的 title 字号和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。+**为什么显式版式把文字默认值分在 Master 与 Layout 两层。** Flat 与 structured 导出都会把声明的 `title` 锚点和确定性的九级 body 层级写入 Master 文本默认值,同时保留原有缩进与项目符号设置;在 structured 路线上,每个 Layout 文字槽位还会把 carrier 首个 run 的字号写入一级默认值,同时保留提示文字的直接字号。这样,插入或重置 placeholder 时仍能继承 Layout 特定尺度,而生成 Slide 上的直接 run 不变。**为什么 structured 输出要在发布前回读。** 元数据预检不能证明 package 序列化保留了所有 relationship 与注册信息。导出器会重新打开临时 PPTX,把已发布 Slide 与完整 Master/Layout roster 分开校验,包括没有任何 Slide 使用的定义;同时核对 Presentation → Master → Layout → Slide 注册链、物理 part/content-type roster、选择器身份、固定对象顺序、placeholder 类型/有效索引/bounds、carrier 绑定、隐藏 proxy 与零槽 Layout,只有通过后才发布。diff --git a/docs/zh/templates-architecture.md b/docs/zh/templates-architecture.mdindex bdb31590..0fcbadf0 100644--- a/docs/zh/templates-architecture.md+++ b/docs/zh/templates-architecture.md@@ -21,7 +21,7 @@每张新建的 Layout/Deck SVG 都是完整预览,并在根节点声明 Master/Layout key 与选择器名称;固定 Master/Layout 视觉是直接原子元素;语义槽位是顶层 group。普通槽位必须有正数设计区域 bounds 和恰好一个兼容 carrier;复合 `object` 区域走显式 proxy 绑定,零槽 Layout 也合法。这些专用标记具有最高优先级;最小 `data-pptx-role` 只补充它们无法表达的页面框架行为。Create Template 根据自然语言意图与来源证据在内部推导 `standard` / `fidelity` / `mirror`;Strategist 再根据真实原型与当前内容推导 strict/adaptive 导出行为。这些实现值都不是用户必选项。仅 Brand/Layout/Deck 的旧式平铺目录可在满足当前 kind 合同时继续读取;Style 没有平铺兼容形态。带旧结构语义的包必须替换为新建模板工作区,不能原地升级。-四者是**四种并列的可复用规则包**,不是 PowerPoint 包对象类型。在全局库范围内,物理目录与 frontmatter `kind` 字段双向对齐:+四者是**四种并列的可复用规则包**,不是 PowerPoint 包对象类型。在全局库范围内,物理目录与前置元数据中的 `kind` 字段双向对齐:每份已装 spec 各自保留自己的 `kind` 与 id;不存在合并后的项目 spec,也没有组合出来的能力标签。路由结果在读取时推导:结构优先来自 Layout,没有 Layout 时才来自 Deck;身份来自 Brand 或 Deck,方向来自 Style。项目内临时组合的 Brand + Layout 因此只是“两种能力都已安装”,不会被自动提升为可注册的 Deck,也不会凭空生成应用语境;当前项目的 Stage 1 沟通契约负责提供场景。Strategist 在内部生成模板应用计划,确认页不显示模板模式控件。@@ -32,7 +32,7 @@ kind: brand...----# templates/styles/consulting_analytical/templates/design_spec.md+# templates/styles/consulting-decision/templates/design_spec.md---kind: style...@@ -99,7 +99,7 @@ native_structure_mode: structured原生形状 metadata 采用两级模型。完整导入 SVG 保存 native metadata、隐藏 carrier 和预览证据,并作为不可变原生载荷后备;`svg_authoring_view.py` 生成可编辑 authoring IR,其中轻量 SVG 使用文档内 source ref 标识对象,manifest 只保存路径和初始 hash。创作模式使用项目规范化 SVG,只有精确匹配已登记 preset 时才使用 compact authored-preset 组。Mirror 从 IR 物化模板,仅为未改且 hash 匹配的 Slide-local/slot ref 重新接入转换器已支持的载荷;固定结构层保持直接原子,不支持或已修改的对象保留 SVG fallback,最终模板不包含 IR 专用 ref。导出只编译声明的结构,不推断归属。-两种范围都在可移植 frontmatter 中保留所选 `kind`。`output_scope` 与 `target_project` 只属于工作流简报,不写入 `design_spec.md`。+两种范围都在可移植前置元数据中保留所选 `kind`。`output_scope` 与 `target_project` 只属于工作流简报,不写入 `design_spec.md`。任何范围第一次写最终文件前,都必须解析 Design Spec 和全部真实目标。Library 范围要求 `templates/` 为空。Project 范围要求目标项目已初始化,并拒绝裸名、同 kind spec 或无效的限定名集合;不同 kind 可以共存。Layout 与 Deck 同时存在时,Layout 拥有有效 roster:新增 Deck 不改变已有 Layout roster,新增 Layout 则先隔离校验,再原子替换已有 Deck 结构载荷。两种范围都会检查计划素材和预览目标冲突。任一失败都在写入前停止,不覆盖、不留下半套输出。@@ -124,13 +124,13 @@ Deck 编码的是**一类可重复演示**,而不只是预先组合好的 Bran----## 二、各分类的 `design_spec.md` Schema+## 二、各分类的 `design_spec.md` 结构定义-字段集只规定**必须写**的部分。「非必要不表明」——当前 schema 没列出的字段,不写。+字段集只规定**必须写**的部分。「非必要不表明」——当前结构定义没列出的字段,不写。-### Brand schema+### Brand 结构定义-**Frontmatter**+**前置元数据**```yaml---@@ -154,9 +154,9 @@ primary_color: "<HEX>"**不允许出现**:canvas viewBox、page types、SVG roster——这些是 layout 的职责。-### Style schema+### Style 结构定义-**Frontmatter**+**前置元数据**```yaml---@@ -185,9 +185,9 @@ fallback:用户最终确认及 Brand/Deck 身份优先。Review Focus 不能visual review。`kind: style` 表示可复用包类型,区别于最终 Stage 2 的`visual_style` 选择和内部 flat 导出值 `template_reuse_scope: style`。-### Layout schema+### Layout 结构定义-**Frontmatter**+**前置元数据**```yaml---@@ -217,16 +217,16 @@ page_types: [<cover, toc, chapter, content, ending, ...>]| IV | Signature Design Elements | 该 Layout 特有的网格、区域、图片行为、密度节奏、中性框架、语义文字角色、对齐/换行/容量行为和 slot 约定 || V | Page Roster | 每个 SVG 文件、Layout key、picker name、适用内容与 slot 行为 |-只有 Layout 改写规范占位词汇时才增加 `Placeholder Overrides`。frontmatter+只有 Layout 改写规范占位词汇时才增加 `Placeholder Overrides`。前置元数据`summary` 承担简短的选型语境;Layout 不写 deck 独有的 Template Overview。`category: scenario` 只表示发现时的适配标签。Layout 可以针对某种内容形态或交付环境优化几何,但不能规定沟通目的、受众结果、必需叙事顺序、固定措辞或示例内容;如果这些规则也要重复使用,应创建 Deck。**不允许出现**:Color Scheme、品牌字体家族/字重身份、最终字号体系、品牌 logo、品牌 voice & tone、Icon Style 或官方真值色(`provenance: fact`)。Layout 可以保留语义文字角色、对齐、换行与容量规则,因为它们属于结构;SVG 中性 paint、字体和字号只用于审阅。最终色彩与字体由策略师确认阶段或其他模板 kind 解析。-### Deck schema+### Deck 结构定义-**Frontmatter**+**前置元数据**```yaml---@@ -447,22 +447,22 @@ apply 阶段解析一份 library 裸 spec 或全部 project 限定名 spec;为| `workflows/create-template/create-layout.md` | 品牌中立、带结构化 SVG roster 的 Layout 工作区 || `workflows/create-template/create-deck.md` | 应用契约与身份/结构一体化、带结构化 SVG roster 的 Deck 工作区;可复用成果带品牌身份或场景语义时选择,不能只因来源是一份完整 PPTX 就默认选择 |-**一套 schema,两个落点。** 模板是同一份合同落在两个层面,唯一的差别是 Design Spec 叫什么:+**一套结构定义,两个落点。** 模板是同一份合同落在两个层面,唯一的差别是 Design Spec 叫什么:| 层 | 容器 | Design Spec ||---|---|---|| skill 库 | `templates/<kind_dir>/<template_id>/` 已经说明了 kind 和 id | `templates/design_spec.md` || 项目 | 一个平铺、多 kind 共用的 `templates/` | `templates/design_spec.<kind>.<id>.md` |-消歧责任归容器,容器给不了的才写进文件名。因此一个项目根同一 kind 至多一份 spec,四种 kind 可以共存,且文件名里的 kind/id 必须分别与 frontmatter 的 `kind` 及对应 `<kind>_id` 一致;裸名与限定名不得在同一目录混用。一个 `templates/` 只保留一份有效 SVG roster:有 Layout 时用 Layout,否则用 Deck;Deck 的其他片段不会因结构被覆盖而丢失。由于 schema 不随层面变化,项目里的 spec 进库不需要补字段、出库也不需要删字段,安装进来的与就地创作的在形态上不可区分。+消歧责任归容器,容器给不了的才写进文件名。因此一个项目根同一 kind 至多一份 spec,四种 kind 可以共存,且文件名里的 kind/id 必须分别与前置元数据中的 `kind` 及对应 `<kind>_id` 一致;裸名与限定名不得在同一目录混用。一个 `templates/` 只保留一份有效 SVG roster:有 Layout 时用 Layout,否则用 Deck;Deck 的其他片段不会因结构被覆盖而丢失。由于结构定义不随层面变化,项目里的 spec 进库不需要补字段、出库也不需要删字段,安装进来的与就地创作的在形态上不可区分。选择遵循同一条原则:单位是工作区 **root**,不是 kind。一个 root 会贡献它暴露的全部 kind,所以指向一个同时装了 Brand 和 Style 的项目,两者都会生效。按 kind 浏览全局库只是找到 root 的一种方式——`library` 与 `explicit` 记录的是 root 如何被发现,而不是它拥有什么。-在全局库范围,frontmatter `kind` 字段决定工作区父目录位于 `templates/brands/` / `templates/styles/` / `templates/layouts/` / `templates/decks/`。项目范围在项目工作区根目录保留同一 kind 语义。项目到项目复用保持完整 root;单项进出全局库时保留 spec schema 与素材,但会改变 spec 文件名落点及索引注册。+在全局库范围,前置元数据中的 `kind` 字段决定工作区父目录位于 `templates/brands/` / `templates/styles/` / `templates/layouts/` / `templates/decks/`。项目范围在项目工作区根目录保留同一 kind 语义。项目到项目复用保持完整 root;单项进出全局库时保留 spec 的结构定义与素材,但会改变 spec 文件名落点及索引注册。----## 七、不做(与本文 framing 配套的拒绝列表)+## 七、不做(与本文叙述框架配套的拒绝列表)- **不在安装层支持字段级覆盖语法** —— 字段级微调走 策略师确认阶段这条已有路径- **不接受同 kind 重复** —— 安装前先缩小 root 集合;Layout + Deck 按结构优先级解析diff --git a/docs/zh/templates-guide.md b/docs/zh/templates-guide.mdindex b6b48f7f..10f8e26f 100644--- a/docs/zh/templates-guide.md+++ b/docs/zh/templates-guide.md@@ -63,8 +63,8 @@ root 时会预选,多 root 仍只作为未选候选。系统不会根据主题Stage-1 页面先让用户选择自由设计或使用模板;只有选择使用模板,才展开五个紧凑下拉框:Brand、Style、Layout、Deck 各一个已注册工作区单选框,再加-一个本次运行指定地址单选框。每个下拉框都有“无”;完整选择可以跨类型组合,-四种 kind 均可参与,但每个 kind 最多一份。Layout 与 Deck 同时存在时由+一个本次运行指定地址单选框。每个下拉框都有“无”;完整选择可以分别选用+四种 kind,但每个 kind 最多一份。Layout 与 Deck 同时存在时由Layout 提供结构。指定地址最多选一个,并原子携带该 root 暴露的全部 kind。已注册列表只来自四类索引,工作流不会扫描模板目录。需要默认展开模板模式并预选某个 Brand/Style/Layout/Deck 工作区时,@@ -79,7 +79,7 @@ Layout 提供结构。指定地址最多选一个,并原子携带模板选择与 Stage 1 共用页面和提交动作,但仍作为独立 sidecar 决策保存。沟通推荐只使用当前请求、源材料事实、对话约束和项目初始化状态;候选元数据、所选 root、已安装内容及模板画布均不得影响它。合并确认后,非自由设计选择才-运行统一 apply 阶段,把所选工作区校验、合成并安装到当前项目的 `templates/`、+运行统一 apply 阶段,把所选工作区分别校验并安装到当前项目的 `templates/`、`images/`、`icons/`。最终 Stage 2 再把已确认沟通契约与安装状态适配;`template_application` 只描述**如何使用**,不负责决定**选哪个模板**。@@ -133,10 +133,10 @@ Layout 工作区:skills/ppt-master/templates/layouts/presentation_core/这四个索引是 Default Stage 1 模板控件与聊天发现共用的完整已注册模板来源;目录永远不会被扫描。直接问“有哪些模板可以用?”即可得到带精确工作区路径的-可读清单;四类 README 负责定义合同。完整数据模型与四类的合成 / 冲突解决+可读清单;四类 README 负责定义合同。完整数据模型、安装与片段所有权规则见 [`templates-architecture.md`](./templates-architecture.md)。-### 自由设计 vs 模板+### 自由设计与模板自由设计不是“没有结构”或“没有风格”——Strategist 仍会为这份 deck 规划叙事、层级与视觉系统,但生成页面使用 `pptx_structure.mode: flat`,所有可见对象都保留在 Slide 本地。仅使用 Brand 或 Style 工作区时同样保持 `flat`:Brand 提供身份约束,Style 提供可复用方法与视觉默认值候选。Layout 与 Deck 工作区提供可复用 Master / Layout / slot 合同;Strategist 会读取真实原型和当前内容,自动判断是复用结构,还是只参考视觉语言。@@ -326,7 +326,7 @@ Brand 与 Style 只写 `templates/design_spec.md`(Brand 可带真实身份资避免常见误解:- **可复用模板是一份显式工作区,不是打包后的源 PPTX。** Brand 与 Style 无 roster;Layout 与 Deck 才增加 structured SVG 合同。创作模式建立这份合同,mirror 则把经过验证的来源归属事实映射进去;导出只编译已声明的结构-- **模板不是一张不可拆分的“风格皮肤”。** Brand、Style、Layout 与 Deck 有意拆开身份、方向/方法、结构和应用,使每一段都能按明确所有权单独复用或参与合成+- **模板不是一张不可拆分的“风格皮肤”。** Brand、Style、Layout 与 Deck 有意拆开身份、方向/方法、结构和应用,使每个片段都能单独复用;同时安装多个工作区时,各片段按明确的所有权规则生效- **模板不会替你做内容决策**。策略师仍然会按内容判断每页用哪个版式、要不要扩展为变体,模板提供候选,不预设结果- **`fidelity` 模式不等于像素级搬运**。即便是 `literal` 保真,AI 仍会把杂质和不必要的重复结构清理掉——载体保留几何,但不照抄冗余- **`mirror` 的目标是受支持范围内的视觉与来源拓扑忠实,不是字节级 OOXML**。它继承源 PPT 的导入限制,只允许固定结构层 group 展开等机械归一化。不支持的原生对象保留可用 SVG fallback 或明确报告;mirror 不归纳替代 ownership。diff --git a/docs/zh/windows-installation.md b/docs/zh/windows-installation.mdindex 0abff78a..22804feb 100644--- a/docs/zh/windows-installation.md+++ b/docs/zh/windows-installation.md@@ -8,7 +8,7 @@----## Step 1 — 安装 Python(必须)+## 步骤 1 — 安装 Python(必须)Python 是唯一的硬性要求。@@ -28,27 +28,35 @@ Python 是唯一的硬性要求。----## Step 2 — 下载项目+## 步骤 2 — 下载项目**方式 A — 下载 ZIP**(最简单):-1. 打开 [GitHub](https://github.com/hugohe3/ppt-master)(或 [AtomGit 镜像](https://atomgit.com/hugohe3/ppt-master),国内更快)+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)):+**方式 B — Git Clone**(需要 [Git](https://git-scm.com/downloads))。下面两条 clone 命令任选其一:```powershell# GitHubgit clone https://github.com/hugohe3/ppt-master.git-# AtomGit(国内更快)+```++```powershell+# AtomGit 镜像git clone https://atomgit.com/hugohe3/ppt-master.git+```++然后进入克隆出的目录:++```powershellcd ppt-master```----## Step 3 — 安装依赖+## 步骤 3 — 安装依赖```powershellcd C:\Users\你的用户名\ppt-master # ← 替换为你的实际路径@@ -61,7 +69,7 @@ pip install -r requirements.txt----## Step 4 — 验证安装+## 步骤 4 — 验证安装```powershellpython -c "import pptx; import fitz; print('All core dependencies OK')"@@ -73,7 +81,7 @@ python -c "import pptx; import fitz; print('All core dependencies OK')"----## Step 5 — 跑一个最小示例+## 步骤 5 — 跑一个最小示例在支持 Agent 的 AI 工具(Claude Code、Codex、Cursor、VS Code agent 等)中打开 `ppt-master` 目录,在聊天面板输入:@@ -91,7 +99,7 @@ python -c "import pptx; import fitz; print('All core dependencies OK')"----## Step 6 — 可选增强(大多数用户可以跳过)+## 步骤 6 — 可选增强(大多数用户可以跳过)装好 Python 和 `requirements.txt` 后,生成 PPT 的全部功能已经就绪。PPTX 导出直接写入原生 DrawingML 形状,不需要 CairoSVG、GTK 或另一套 SVG 栅格化环境。下面只保留一种**边缘场景的备用工具**——遇到对应需求时再装。diff --git a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.mdindex 1c610eaf..e6ef1112 100644--- a/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md+++ b/skills/ppt-master/scripts/docs/advanced-image-motion-smoke.md@@ -299,7 +299,15 @@ slide_2 = """<svg xmlns="http://www.w3.org/2000/svg")run_tool("project_manager.py", "validate", project)-run_tool("svg_quality_checker.py", project, "--format", "ppt169")+run_tool(+ "svg_quality_checker.py",+ project,+ "--format",+ "ppt169",+ "--stage",+ "final",+ "--json",+)run_tool("animation_config.py", "validate", project)diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.mdindex 34c93001..bcd9c54d 100644--- a/skills/ppt-master/scripts/docs/confirm_ui.md+++ b/skills/ppt-master/scripts/docs/confirm_ui.md@@ -305,9 +305,9 @@ The command writes, and agents must not hand-author:```The handoff must match the current valid selection. Template mode also requires-`<project_path>/templates/design_spec.md`; free design requires no installed-spec. Write `recommendations.stage2.json` only after this command succeeds, so-its file time is newer than the handoff.+at least one `<project_path>/templates/design_spec.<kind>.<id>.md`; free design+requires no installed spec. Write `recommendations.stage2.json` only after this+command succeeds, so its file time is newer than the handoff.## Field shapesdiff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 5436231e..8997a2e4 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -12,20 +12,22 @@ diagnostic or forced route is needed.## Shared Output Contract-All `source_to_md` converters keep their existing Markdown output behavior and-now also write a lightweight sidecar profile when conversion succeeds:+All `source_to_md` backends preserve their Markdown output and attempt a+sidecar profile after conversion. Direct calls treat the sidecar as+best-effort: an I/O failure warns without changing the Markdown result. The+unified `source_to_md.py` dispatcher writes a missing profile before success.| Output | Convention ||---|---|| Markdown | `<stem>.md` beside the local source unless `-o` selects another path || Asset directory | `<stem>_files/` when the backend extracts images or media || Image manifest | `<stem>_files/image_manifest.json` when image metadata is available |-| Conversion profile | `<stem>.conversion_profile.json` beside the Markdown output |+| Conversion profile | `<stem>.conversion_profile.json` beside the Markdown output when written |-The conversion profile is metadata only. It records the converter, source path,+When present, the conversion profile is metadata only: converter, source path,Markdown structure counts, asset directory, image manifest path, and image-count. Downstream PPT workflows still use the Markdown and image manifest as the-content/asset contract; the profile is for inspection and debugging.+count. Downstream PPT workflows still use Markdown and the image manifest as+the content/asset contract; the profile is for inspection and debugging.## `source_to_md.py`@@ -64,9 +66,9 @@ Useful options:For multi-source project intake, use `project_manager.py import-sources` withall source paths / URLs. For local files, the default is to keep generated-Markdown/profile outputs beside the original source. `source_to_md.py` and the-backend converters support single files, explicit multi-file inputs, and-non-recursive directory inputs.+Markdown and profile outputs beside the original source.+`source_to_md.py` and the backend converters support single files, explicit+multi-file inputs, and non-recursive directory inputs.## `source_to_md/pdf_to_md.py`@@ -136,8 +138,10 @@ pip install mammoth markdownify ebooklib nbconvert beautifulsoup4# Windows: https://pandoc.org/installing.html```-All paths produce the same output convention: `<input>.md` plus a sibling `<input>_files/` directory containing extracted images with relative references.-On success, a sibling `<input>.conversion_profile.json` is also written.+All paths produce `<input>.md`. Extracted assets use a sibling `<input>_files/`+directory with relative references. Without assets, that directory need not remain.+The direct backend then attempts `<input>.conversion_profile.json` under the+shared best-effort sidecar contract.## `source_to_md/excel_to_md.py`@@ -165,7 +169,7 @@ Behavior:- trims empty outer rows and columns- propagates merged-cell labels for readable Markdown tables- exports formula cells as cached values; it does not recalculate formulas-- writes `<input>.conversion_profile.json` after successful conversion+- uses the shared best-effort conversion-profile contract after successDependency:@@ -202,7 +206,7 @@ Behavior:- exports embedded pictures to a sibling `_files/` directory- preserves supported run, table-cell, picture, and text-shape links as Markdown links, including `#slide-N` jumps- appends speaker notes when present-- writes `<input>.conversion_profile.json` after successful conversion+- uses the shared best-effort conversion-profile contract after successDependency:@@ -626,8 +630,8 @@ fetch WeChat Official Accounts (`mp.weixin.qq.com`) and other sites thatblock Python's default TLS fingerprint. No extra flags needed. If`curl_cffi` is not available, it falls back to plain `requests`.-On success, the converter writes `<output>.conversion_profile.json` beside the-Markdown output.+On success, the converter uses the shared best-effort sidecar contract for+`<output>.conversion_profile.json` beside the Markdown output.`--emit-result` is for wrapper scripts that need the actual saved Markdown pathwhen the converter derives a title-based filename.diff --git a/skills/ppt-master/scripts/docs/multilingual-text-smoke.md b/skills/ppt-master/scripts/docs/multilingual-text-smoke.mdindex 6896253a..00ff9fae 100644--- a/skills/ppt-master/scripts/docs/multilingual-text-smoke.md+++ b/skills/ppt-master/scripts/docs/multilingual-text-smoke.md@@ -97,6 +97,17 @@ with TemporaryDirectory(prefix="ppt-master-multilingual-smoke-") as tmp:json.dumps(recommendation),encoding="utf-8",)+ (confirm / "template_options.json").write_text(+ json.dumps(+ {+ "schema_version": 1,+ "phase": "template",+ "default_mode": "free_design",+ "explicit_workspace_roots": [],+ }+ ),+ encoding="utf-8",+ )app = create_app(str(project), idle_timeout=0)app.testing = Trueclient = app.test_client()@@ -107,6 +118,10 @@ with TemporaryDirectory(prefix="ppt-master-multilingual-smoke-") as tmp:"/api/confirm",json={"stage": "stage1",+ "template_selection": {+ "mode": "free_design",+ "selection_keys": [],+ },"primary_language": "ar-SA","canvas": "ppt169","audience": "Team",diff --git a/skills/ppt-master/templates/README.md b/skills/ppt-master/templates/README.mdindex dfbb3dcc..ada3fd66 100644--- a/skills/ppt-master/templates/README.md+++ b/skills/ppt-master/templates/README.md@@ -137,8 +137,9 @@ projections.Qualitative Structure is a Slide-local Executor method rather than a catalog:Default and Quick both derive its relationship model and compose shapes for the-current page. Only [`layouts/`](./layouts/) owns reusable Master/Layout, page-types, slots, and placeholders.+current page. Only Layout and Deck workspaces own reusable Master/Layout, page+types, slots, and placeholders. When both are present, Layout supplies the+active SVG roster and overrides only Deck's structure segment.## Icon Librarydiff --git a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.mdindex 000b8f6f..7658f58c 100644--- a/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md+++ b/skills/ppt-master/templates/VISUALIZATION_TEMPLATE_AUTHORING.md@@ -1,4 +1,4 @@-# Visualization Template Authoring Guide+# 可视化模板编写指南这是供维护者审阅的中文指南,因此放在两个 Visualization catalog 的共同父目录,而不是归某一个 family 所有。`templates/charts/` 和 `templates/tables/` 共同组成@@ -6,25 +6,26 @@ page-local Visualization 模板库;模板负责数据编码或单元格关系风格。模板必须保持源码可读、独立可渲染,并允许 Executor 根据项目 Design Spec与 `spec_lock.md` 重做字体、配色和装饰。-| Family | 定义 | 判定边界 |+| 分类 | 定义 | 判定边界 ||---|---|---|-| `chart` | Value-driven visualization | 数值、类别、时间、权重或持续时间决定 mark 的位置、长度、面积、角度、字号或连接宽度 |-| `table` | Row × column fact grid | 行头与列头共同寻址一个单元格事实;合并、对齐和边界保持该交点关系 |+| `chart` | 数值驱动的可视化 | 数值、类别、时间、权重或持续时间决定 mark 的位置、长度、面积、角度、字号或连接宽度 |+| `table` | 行 × 列事实网格 | 行头与列头共同寻址一个单元格事实;合并、对齐和边界保持该交点关系 |-**Hard rule — Structure is a method, not a catalog**: 定性顺序、层级、角色、+**硬规则——Structure 是一种方法,不是目录**:定性顺序、层级、角色、分区和关系由 [`executor-structure.md`](../references/executor-structure.md) 在当前页面现场构形,不登记固定 `structure/<key>`、SVG roster 或 index。Default 和 Quick 都先判断页面真实信息模型;需要定性拓扑时都必须采用这套 Structure 方法。删除 catalog只删除固定示例,不删除 Quick 或 Default 的 Structure 能力。-**Hard rule — Visualization is not Layout**: Chart/Table 模板和运行时 Structure+**硬规则——Visualization 不是 Layout**:Chart/Table 模板和运行时 Structure都不拥有 `data-pptx-master`、`data-pptx-layout`、`data-pptx-layer` 或`data-pptx-placeholder`。跨页 Master/Layout、page type、slot geometry 和-placeholder 合同仍只属于 [`layouts/`](./layouts/) workspace。+placeholder 合同属于 [`layouts/`](./layouts/) 或 [`decks/`](./decks/) workspace;+两者共存时,仅由 Layout 覆盖 Deck 的结构分段。## 0. 上游规范-**Hard rule**: 本指南只定义 Chart/Table 两个 catalog family 的结构与中性预览合同。通用 SVG 语法、效果、原生数据接口和 PowerPoint 结构分别由以下权威文件定义:+**硬规则**:本指南只定义 Chart/Table 两个 catalog family 的结构与中性预览合同。通用 SVG 语法、效果、原生数据接口和 PowerPoint 结构分别由以下权威文件定义:| 合同 | 权威文件 ||---|---|@@ -33,7 +34,7 @@ placeholder 合同仍只属于 [`layouts/`](./layouts/) workspace。| Native Chart/Table | [`native-data-interface.md`](../references/native-data-interface.md) || 画布格式 | [`canvas-formats.md`](../references/canvas-formats.md) |-**Forbidden — second SVG specification**: 不在本指南复述或放宽上游语法。发生冲突时以上游权威文件为准。+**禁止——重复定义第二套 SVG 规范**:不在本指南复述或放宽上游语法。发生冲突时以上游权威文件为准。---@@ -51,14 +52,14 @@ placeholder 合同仍只属于 [`layouts/`](./layouts/) workspace。| 必要的状态与语义区分 | 页面背景、页头、页脚和品牌 chrome || 独立预览所需的中性样式 | 最终强调策略与页面级视觉层级 |-**Hard rule — authoring integrity**: 维护某个库模板时必须保持该模板自身的-family 与信息模型:Chart 的 value mapping、Table 的 row × column fact grid。+**硬规则——编写完整性**:维护某个库模板时必须保持该模板自身的+family 与信息模型:Chart 的数值映射、Table 的行 × 列事实网格。若修改结果属于定性关系拓扑,不新增第三类模板,而由 runtime Structure 方法构建;若仍属于另一 catalog family,应登记到正确 family,不能保留错误标签。最终视觉样式仍来自使用它的项目,而不是模板的示例审美。-**Hard rule — flexible project reference**: Executor 选中的 `family/key` 仍只是-flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有最终结构;+**硬规则——灵活的项目引用**:Executor 选中的 `family/key` 仍只是+灵活的页内引用。Default 的 §IX 或 Quick 的页面决策拥有最终结构;选中引用不会锁死页面的可视化类型、几何、分组数、项目数或组合方式,Executor可按已确认的页面意图适配、重组或替换。项目若实际采用某一信息模型,必须保持其真实数据与关系准确;仅有引用本身不构成页面结构权威。@@ -74,20 +75,20 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有| 只让示例显得更精致、立体、品牌化或“高级” | 作为简化候选;通过文本与前后渲染核对后再删除 || 只对某个项目风格成立 | 交给 Executor 重建 |-**Default — information first (may override when semantics require it)**: 优先使用清楚的线、面、标签和留白。装饰不能成为理解信息的前提。+**默认——信息优先(语义需要时可以覆盖)**:优先使用清楚的线、面、标签和留白。装饰不能成为理解信息的前提。### 1.3 保真优先-**Hard rule — fidelity before slimming**: 模板瘦身不得改写或删除原有可见标题、标签、说明、数值、单位、状态、来源、顺序、容量和关系。占位内容保持原文;只有明确重复的信息可以删除,并记录理由。+**硬规则——先保真,再瘦身**:模板瘦身不得改写或删除原有可见标题、标签、说明、数值、单位、状态、来源、顺序、容量和关系。占位内容保持原文;只有明确重复的信息可以删除,并记录理由。-**Explicit migration exception**: 经明确批准的 family/key 合并、重组或退役可以用+**显式迁移例外**:经明确批准的 family/key 合并、重组或退役可以用中性占位内容重建 canonical SVG,或移除不再存活的工件;这不是普通模板瘦身。迁移必须在 §8 记录 catalog 边界和仍可读取的 legacy 语义。未列入批准迁移的模板仍受上一条逐字保真约束。-**Hard rule — structural frames survive**: 框线、底色、分隔、标签页或面板只要表达真实的信息单元、父子层级、阶段范围、绘图区或输出区,就属于结构。可以减少叠加效果,但不得为了 token 数字把有效层级压平。+**硬规则——保留结构框架**:框线、底色、分隔、标签页或面板只要表达真实的信息单元、父子层级、阶段范围、绘图区或输出区,就属于结构。可以减少叠加效果,但不得为了 token 数字把有效层级压平。-**Forbidden — compression by rewriting**: 不用缩写、概括、换词或删句降低 token。体积优化来自属性继承、重复样式合并和非语义效果简化,不来自内容编辑。+**禁止——通过改写压缩**:不用缩写、概括、换词或删句降低 token。体积优化来自属性继承、重复样式合并和非语义效果简化,不来自内容编辑。---@@ -95,7 +96,7 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有### 2.1 独立可渲染-**Hard rule**: 每个模板保持完整 `<svg>`、`viewBox="0 0 1280 720"` 和一个直接的白色全画布背景,使文件无需外部样式即可打开审阅。+**硬规则**:每个模板保持完整 `<svg>`、`viewBox="0 0 1280 720"` 和一个直接的白色全画布背景,使文件无需外部样式即可打开审阅。```xml<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" width="1280" height="720"@@ -122,9 +123,9 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有| 负向语义 | `#E11D48` | 仅表示下降、异常、未达标 || 警示语义 | `#D97706` | 仅表示风险或待处理 |-**Hard rule**: 多系列数据必须可区分;正负、完成/计划等语义状态必须可辨认。颜色承担这些信息时保留,颜色只承担装饰时移除。+**硬规则**:多系列数据必须可区分;正负、完成/计划等语义状态必须可辨认。颜色承担这些信息时保留,颜色只承担装饰时移除。-**Forbidden — fixed catalog palette**: 不要求每个卡片、步骤或能力点使用不同 Tailwind hue。项目配色不从模板示例反向推导。+**禁止——固定目录调色板**:不要求每个卡片、步骤或能力点使用不同 Tailwind hue。项目配色不从模板示例反向推导。### 2.3 页面 chrome@@ -141,7 +142,7 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有### 3.1 减少冗余效果-**Default — one clear treatment (may override when structure requires depth)**: 中性模板避免阴影、发光、纹理、渐变和多层框同时叠加;保留能帮助读者识别真实边界、重叠或空间关系的最少效果。+**默认——一种清楚的处理方式(结构需要深度时可以覆盖)**:中性模板避免阴影、发光、纹理、渐变和多层框同时叠加;保留能帮助读者识别真实边界、重叠或空间关系的最少效果。| 效果 | 默认 | 允许条件 ||---|---|---|@@ -151,13 +152,13 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有| 圆角卡片 | 保留真实信息单元的一层边界 | 圆角值与最终外观由项目适配 || 图标底板 | 非默认 | 需要明确图标槽位或状态边界 |-**Hard rule**: Heatmap 色阶、Sankey 流量宽度、系列区分、Isometric 面向关系和真实模块边界属于信息编码或结构。普通卡片阴影、气泡高光、无含义色带和不承担顺序的大号淡色编号通常不属于;删除前仍需确认没有弱化层级。+**硬规则**:Heatmap 色阶、Sankey 流量宽度、系列区分、Isometric 面向关系和真实模块边界属于信息编码或结构。普通卡片阴影、气泡高光、无含义色带和不承担顺序的大号淡色编号通常不属于;删除前仍需确认没有弱化层级。### 3.2 容器克制-**Hard rule**: 每个真实信息单元保留至少一种清楚的边界表达:留白、分隔线、描边或底色。通常只需一种;父级区域与子级内容确实表达两个层级时可以保留两层。不要同时叠加无语义的描边、阴影、渐变和多层圆角框。+**硬规则**:每个真实信息单元保留至少一种清楚的边界表达:留白、分隔线、描边或底色。通常只需一种;父级区域与子级内容确实表达两个层级时可以保留两层。不要同时叠加无语义的描边、阴影、渐变和多层圆角框。-**Reference — not a constraint**: 项目最终可能采用强装饰风格。那是 Executor 根据 Design Spec 重建的项目决策,不是共享模板的默认形态。+**参考说明——不是约束**:项目最终可能采用强装饰风格。那是 Executor 根据 Design Spec 重建的项目决策,不是共享模板的默认形态。---@@ -165,7 +166,7 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有### 4.1 语义压缩-**Hard rule**: 缩小模板时保留正常换行、缩进、语义 `id` 和必要分区注释。压缩目标是减少重复信息,不是把 XML 变成一行。+**硬规则**:缩小模板时保留正常换行、缩进、语义 `id` 和必要分区注释。压缩目标是减少重复信息,不是把 XML 变成一行。| 做法 | 要求 ||---|---|@@ -178,7 +179,7 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有### 4.2 禁止的压缩-**Forbidden — opaque source**:+**禁止——不可读源码**:- 单行 minify、随机缩写 ID 或删除结构注释。- 为省字符把核心构图拆成难以追踪的深层 `<symbol>/<use>` 图。@@ -194,9 +195,9 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有| 页面标题 | `30–36`,`700–800` || 区域标题 | `18–24`,`600–700` || 正文/标签 | `13–16` |-| Caption/轴刻度 | `12–14` |+| 图注/轴刻度 | `12–14` |-**Hard rule**: 所有文本 `font-size >= 12`,使用有限无单位数值。需要成为一个 PowerPoint 文本框的多格式逻辑行使用一个 `<text>` 加非定位 `<tspan>`;独立文本框使用独立 `<text>`。+**硬规则**:所有文本 `font-size >= 12`,使用有限无单位数值。需要成为一个 PowerPoint 文本框的多格式逻辑行使用一个 `<text>` 加非定位 `<tspan>`;独立文本框使用独立 `<text>`。---@@ -204,7 +205,7 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有### 5.1 语义分组-**Hard rule**: 使用描述性顶层 `<g id>` 表达页面级逻辑单元,例如 Header、Chart、Legend、Card Grid 或 Process。不要为每条文字、图标或数据点建立一个直属根组。+**硬规则**:使用描述性顶层 `<g id>` 表达页面级逻辑单元,例如 Header、Chart、Legend、Card Grid 或 Process。不要为每条文字、图标或数据点建立一个直属根组。| 顶层组 | 典型内容 ||---|---|@@ -214,13 +215,13 @@ flexible page-local reference。Default 的 §IX 或 Quick 的页面决策拥有| `table-area` / replacement carrier | Table 的行、列、单元格和必要 metadata || `table-notes` | 来源、口径或脚注 |-**Forbidden — workspace metadata**: 两个 catalog family 都不得写入+**禁止——工作区元数据**:两个 catalog family 都不得写入Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整个`1280×720` 画布也仍是 Slide-local 构形,不会因此成为 Layout workspace。### 5.2 `data-pptx-bounds`-**Hard rule**: 每个可见直属根 `<g>` 都声明正数、根坐标系的 `data-pptx-bounds="x y width height"`。即使该组已有 native chart/table frame,也保留 bounds。+**硬规则**:每个可见直属根 `<g>` 都声明正数、根坐标系的 `data-pptx-bounds="x y width height"`。即使该组已有 native chart/table frame,也保留 bounds。```xml<g id="header" data-pptx-bounds="60 40 1160 72">@@ -240,7 +241,7 @@ Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整| 嵌套组 | 不写;Checker 忽略嵌套 bounds || 背景/defs | 直接背景 primitive 与非可见定义不需要 bounds |-**Forbidden — bounds noise**: 不给每个嵌套 `<g>`、图标、数据点或实现碎片添加 bounds。+**禁止——冗余 bounds**:不给每个嵌套 `<g>`、图标、数据点或实现碎片添加 bounds。### 5.3 Shape-first@@ -253,7 +254,7 @@ Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整| 图元、预设、Boolean 都不能表达的数据/语义/锁定风格几何 | `<path>`、`<polygon>`、`<polyline>` || 数据图表 | 默认 Shape fallback;符合条件时附带 native replacement marker |-**Forbidden — inferred native semantics**: 概念图、流程图和框架图不添加 `data-pptx-replace-with="chart"`;普通关系线不添加 Connector attachment metadata。+**禁止——推断原生语义**:概念图、流程图和框架图不添加 `data-pptx-replace-with="chart"`;普通关系线不添加 Connector attachment metadata。---@@ -261,7 +262,7 @@ Master/Layout/placeholder 所有权标记。运行时 Structure 即使占满整### 6.1 绘图区标记-**Hard rule**: calculator-supported 数据图表在 `<g id="chartArea">` 内、轴之后、首个数据元素之前保留精确机器注释:+**硬规则**:calculator-supported 数据图表在 `<g id="chartArea">` 内、轴之后、首个数据元素之前保留精确机器注释:```xml<!-- chart-plot-area: 140,150,1160,550 -->@@ -276,7 +277,7 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与### 6.2 Native Chart/Table-**Hard rule**: 只有 [`native-data-interface.md`](../references/native-data-interface.md) 支持的真实 Chart 或纯文本 Table 使用 replacement marker。JSON metadata 与可见 fallback 必须表达同一份数据。运行时构建的 Structure 永远不使用 Chart/Table replacement marker。+**硬规则**:只有 [`native-data-interface.md`](../references/native-data-interface.md) 支持的真实 Chart 或纯文本 Table 使用 replacement marker。JSON metadata 与可见 fallback 必须表达同一份数据。运行时构建的 Structure 永远不使用 Chart/Table replacement marker。```xml<g id="line-chart"@@ -287,7 +288,7 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与</g>```-**Hard rule**: 项目颜色适配时同步修改可见系列颜色和 metadata `style.colors`。默认 Shape 输出与显式 native 输出都必须可验证。+**硬规则**:项目颜色适配时同步修改可见系列颜色和 metadata `style.colors`。默认 Shape 输出与显式 native 输出都必须可验证。### 6.3 数据装饰边界@@ -306,7 +307,7 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与### 7.1 占位内容-**Hard rule**: 模板占位文本使用英文,展示真实文本容量和数据格式,但不承载具体项目事实。+**硬规则**:模板占位文本使用英文,展示真实文本容量和数据格式,但不承载具体项目事实。| 应展示 | 示例 ||---|---|@@ -315,7 +316,7 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与| 正常换行 | 2–3 行短描述 || 结构容量 | 真实建议数量范围内的 series/items/nodes |-**Forbidden — placeholder storytelling**: 不写长篇营销文案、部门归属、真实品牌或无法复用的项目背景。+**禁止——用占位内容讲故事**:不写长篇营销文案、部门归属、真实品牌或无法复用的项目背景。### 7.2 分类索引与规划投影@@ -338,7 +339,7 @@ Catalog 模板本身只有一个主 Chart,可保留上述 unscoped marker 与规划主路径不读取这些记录。Chart 与 Table 的规划词汇表必须完整列出各自同一组canonical `family/<key>`,只说明信息关系,不写 SVG 实现、布局参数或选择结论。-**Hard rule**: `key` 与同 family 文件名一致,`meta.total` 与该 family catalog+**硬规则**:`key` 与同 family 文件名一致,`meta.total` 与该 family catalog数量一致;每份 planning vocabulary 与 owning index 的成员集合必须精确一致。除此以外不要建立跨 family 的第二份成员清单。@@ -350,7 +351,7 @@ canonical `family/<key>`,只说明信息关系,不写 SVG 实现、布局参39 个 SVG:Chart 33 个、Table 6 个。各 live index 是成员清单的唯一权威;Structure 不再有固定 SVG roster、index 或 canonical key。-**Hard rule — topology is generated, not recalled**: 从来源 deck 吸收的是 Shape+**硬规则——拓扑由现场生成,不从目录召回**:从来源 deck 吸收的是 Shapegrammar 和构形思维,而不是页面示例清单。先还原顺序、层级、分组、分区、连接、交叠等真实关系,再由 `executor-structure.md` 使用区域、节点、主轴、连接、标签与装饰等角色现场组合。Default 在 §IX 描述该关系,Quick 在当前上下文作同一判断;@@ -359,13 +360,13 @@ Structure 载体判断。**已批准的图表容量迁移**:-| Canonical key | 已批准边界 | 兼容处理 |+| 规范 key | 已批准边界 | 兼容处理 ||---|---|---|| `gauge_chart` | 2026-08-10:中性预览从三个并列 Gauge 重组为一个有界域、明确目标或阈值的 KPI;多个同级 KPI 改用 `bullet_chart` 或 `progress_bar_chart` | canonical key 保持不变;旧三指标示例不再作为可读取容量合同,无需 alias |-**Canonical Table set**:+**规范 Table 集合**:-| Canonical key | 核心信息关系 |+| 规范 key | 核心信息关系 ||---|---|| `record_table` | 每行一条记录、每列一个稳定字段 || `metric_table` | 实体与 KPI 的交点承载度量、变化、状态或 cell 内微图形 |@@ -374,14 +375,14 @@ Structure 载体判断。| `rating_matrix` | 评价维度与方案的交点使用同一套序数等级 || `hierarchical_table` | 分组或缩进行、明细与小计/总计形成层级网格 |-**Hard rule — semantic family before physical object**: PowerPoint 中的物理+**硬规则——先判定语义分类,再看物理对象**:PowerPoint 中的物理Table 对象不自动属于 `table` family。只有行头与列头的交点可寻址为一个事实时才是Table;日期或持续时间决定 `x`/`width` 的排期是 `chart/gantt_chart`;阶段与泳道只表达定性活动位置时由 runtime Structure 构建。-**Canonical catalog aliases**:+**规范目录别名**:-| Canonical reference | Legacy bare keys |+| 规范引用 | 旧版裸 key ||---|---|| `table/record_table` | `basic_table` || `table/metric_table` | `consulting_table` |@@ -398,7 +399,7 @@ Table;日期或持续时间决定 `x`/`width` 的排期是 `chart/gantt_chart`也不能写入新 §VII/lock。消费方把该意图投影为定性关系提示,再交给 runtime Structure构形;不得把它伪装成仍存活的模板。-**Hard rule**: 修改一个仍属 canonical 的模板时先冻结可见文本、数据和结构层级,+**硬规则**:修改一个仍属 canonical 的模板时先冻结可见文本、数据和结构层级,再简化确认无语义的效果、补齐直属根 bounds,并完成文本差异、独立渲染与双路线验证。经本节明确登记的 catalog 合并/重组/退役不要求保留旧示例文案;除此之外,未经说明的文本删除、改写或结构边界丢失都会阻断变更。@@ -424,9 +425,9 @@ Table;日期或持续时间决定 `x`/`width` 的排期是 `chart/gantt_chart`- [ ] 颜色差异确实表达 series、state、positive/negative 等语义。- [ ] 标题、副标题和来源只用于展示必要结构或容量。-### 9.3 Family 与 PowerPoint+### 9.3 分类与 PowerPoint-- [ ] Family 判定正确:Chart 为 value-driven、Table 为 row × column fact grid;定性拓扑退出 catalog 并由 runtime Structure 构建。+- [ ] 分类判定正确:Chart 为数值驱动、Table 为行 × 列事实网格;定性拓扑退出 catalog 并由 runtime Structure 构建。- [ ] Chart/Table 模板不含 Master/Layout/layer/placeholder ownership metadata。- [ ] Calculator-supported Chart 保留准确 `chart-plot-area` 标记。- [ ] Eligible Chart/Table 的 metadata 与可见 fallback 数据一致。@@ -434,7 +435,7 @@ Table;日期或持续时间决定 `x`/`width` 的排期是 `chart/gantt_chart`- [ ] 存在 replacement marker 时,显式 native Chart/Table 导出通过。- [ ] `svg_quality_checker.py` 无 error;warning 已人工判断。-### 9.4 Catalog+### 9.4 目录- [ ] 新模板只登记到 owning family index,index object、`meta.total` 与 SVG roster 一致。- [ ] 修改 key/summary 后通过 `visualization_recall.py validate` 和 recall 烟测。@@ -460,4 +461,4 @@ python3 skills/ppt-master/scripts/compact_svg_coordinates.py \skills/ppt-master/templates/<family-directory>/<key>.svg```-**Validation**: 修改后至少完成 XML 解析、独立 SVG 渲染、Checker、默认 Shape-first 导出,以及 marker 模板的 native Chart/Table 导出。+**验证**:修改后至少完成 XML 解析、独立 SVG 渲染、Checker、默认 Shape-first 导出,以及 marker 模板的 native Chart/Table 导出。diff --git a/skills/ppt-master/workflows/index.md b/skills/ppt-master/workflows/index.mdindex c122a966..60072e2c 100644--- a/skills/ppt-master/workflows/index.md+++ b/skills/ppt-master/workflows/index.md@@ -28,6 +28,7 @@ Maintainer-only inventory for adding, moving, or removing workflow documents. Ru| `create-layout` | Template child workflow | [`create-template/create-layout.md`](./create-template/create-layout.md) | Create Template || `create-deck` | Template child workflow | [`create-template/create-deck.md`](./create-template/create-deck.md) | Create Template || `topic-research` | Research/source-preparation stage | [`stages/topic-research.md`](./stages/topic-research.md) | Inside Generate Step 1 |+| `web-image-review` | Image-review stage | [`stages/web-image-review.md`](./stages/web-image-review.md) | Generate Step 5 bounded multimodal review between web candidate-page save and promotion || `resume-execute` | Control stage | [`stages/resume-execute.md`](./stages/resume-execute.md) | Generate Step 6 resume || `refine-spec` | Planning stage | [`stages/refine-spec.md`](./stages/refine-spec.md) | After Design Spec Gate 1, before lock Gate 2 || `verify-charts` | Quality gate | [`stages/verify-charts.md`](./stages/verify-charts.md) | Before Generate Step 7 |diff --git a/skills/ppt-master/workflows/profiles/beautify-pptx.md b/skills/ppt-master/workflows/profiles/beautify-pptx.mdindex 0f8a2f2e..6d272eec 100644--- a/skills/ppt-master/workflows/profiles/beautify-pptx.md+++ b/skills/ppt-master/workflows/profiles/beautify-pptx.md@@ -6,7 +6,11 @@ description: Generate profile for 1:1, content-faithful re-layout of an existing> Generate profile, not a top-level route. [`template-fill-pptx.md`](../template-fill-pptx.md) reuses a deck's design and swaps in new content; this profile keeps a deck's content and redoes its layout.-Re-lays-out an existing `.pptx`: the text is preserved **verbatim**, the source deck's visual identity (palette / fonts) is **inherited as truth**, and only layout, hierarchy, and whitespace are redesigned. Output is a brand-new native deck generated through the standard SVG pipeline — not a patch over the original.+Re-lays-out an existing `.pptx`: text is preserved **verbatim** and source+palette / fonts are the preselected recommendation. Only explicit user+requirements or final confirmation may override them; never deviate silently.+It rebuilds layout, hierarchy, whitespace, and effective visual treatment into+a new native deck through the SVG pipeline — not a patch over the original.**Trigger**: the user supplies a `.pptx` and asks to beautify / re-layout / 重新排版 / 美化 while keeping the content. Explicit intent + a provided file only; never auto-infer.@@ -30,7 +34,7 @@ Beautify constraints in this file apply in either runtime.**Hard rule — not a patch, not a fill**: this regenerates a native deck through the selected Default or Quick SVG → PPTX runtime. It does **not** edit the source file in place, and it is **not** [`template-fill-pptx`](../template-fill-pptx.md) (which clones source slides and replaces text). It also does not parse an arbitrary third-party template for text-only substitution (the rejected #53 direction) — it builds every page from scratch.-**Distinct from mirror templates**: `replication_mode: mirror` ([`executor-structured.md`](../../references/executor-structured.md) §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, identity inherited.+**Distinct from mirror templates**: `replication_mode: mirror` ([`executor-structured.md`](../../references/executor-structured.md) §1.1) keeps layout + visuals verbatim and edits text. Beautify is the inverse — content verbatim, layout redone, source identity recommended unless the user overrides it.**Distinct from page-image reconstruction**: when the authoritative input isan ordered raster page roster and the user wants its visible layout preserved,@@ -102,9 +106,9 @@ python3 ${SKILL_DIR}/scripts/pptx_intake.py <project_path>/sources/<source.pptx>| `layout_sizes_pt` (pt, frequency-ranked) | **reference fact only**, NOT an auto-seed — the level-1 sizes that the in-use slide layouts' body placeholders declare. Usually empty (decks rely on runs / master) and ambiguous when present; use it as a hint when judging the body size, never as the authoritative seed || `canvas.aspect` | drives the Step 3 format choice |-> Note: `theme` is what the deck declares; `observed` is a frequency sample of run-level overrides (not a complete style resolution — it misses `schemeClr` and master/layout inheritance, and counts chart/gradient fills). A hand-edited deck can diverge from `theme` — Step 5 recommends which to inherit and the user confirms.+> Note: `theme` is what the deck declares; `observed` is a frequency sample of run-level overrides (not a complete style resolution — it misses `schemeClr` and master/layout inheritance, and counts chart/gradient fills). A hand-edited deck can diverge from `theme` — Step 5 resolves which to use.-**Hard rule — regenerate visuals, do not carry them over**: charts / tables / images are rebuilt from their data in the inherited style, never spliced in byte-for-byte. This keeps the deck style-consistent and natively editable. **Data values are frozen** (categories / series / cell text / numbers unchanged); only their rendering is the deck's own. Pictures (`ppt_to_md`-extracted files) are reused but re-laid-out — position / crop / size follow the new layout, not the source slot. A user who wants an original element verbatim copies it across themselves.+**Hard rule — regenerate visuals, do not carry them over**: charts / tables / images are rebuilt from their data in the effective style, never spliced in byte-for-byte. This keeps the deck style-consistent and natively editable. **Data values are frozen** (categories / series / cell text / numbers unchanged); only their rendering is the deck's own. Pictures (`ppt_to_md`-extracted files) are reused but re-laid-out — position / crop / size follow the new layout, not the source slot. A user who wants an original element verbatim copies it across themselves.**Optional source-SVG visual reference**: when the source deck has complex vector decoration, distinctive page chrome, or a visual language that cannot be captured by `<stem>.identity.json` colors/fonts alone, create a read-only SVG reference package under `analysis/`. This is for understanding style only; it is not a carry-over asset path.@@ -128,7 +132,7 @@ path. Promote to `<project_path>/icons/imported/` and reference with`<use data-icon="imported/<name>"/>`; Quick never runs `finalize_svg.py`. Neverpromote text-bearing groups, charts/tables, page layouts, or dense composites.-**Assemble the inventory** — the deterministic join into one per-slide ledger, `analysis/beautify_inventory.json`, the contract Step 5 confirms and Step 7 verifies against:+**Assemble the inventory** — the deterministic join into one per-slide ledger, `analysis/beautify_inventory.json`, the contract Step 5 resolves and Step 7 verifies against:```bashpython3 ${SKILL_DIR}/scripts/beautify_inventory.py <project_path>/analysis/<stem>.slide_library.json \@@ -223,7 +227,7 @@ This step has two halves:| Item | What v1 delivers ||---|---|| Overcrowded source page | layout / hierarchy / whitespace improve **within the page as-is** — v1 does **not** relieve information overload (that needs re-pagination / rewrite, deferred). Flag such pages; the user may accept or note them for manual split |-| Paste-back into the original | regenerated elements share the inherited palette + fonts, so they **blend visually** when pasted. v1 does **not** guarantee a seamless coordinate-level drop-in (slide coordinates, master placeholders, font availability are the original deck's, not ours) |+| Paste-back into the original | regenerated elements retain confirmed palette + font declarations; v1 does **not** guarantee coordinate alignment or font availability in the original deck || Complex charts / merged-cell tables | best-effort from the captured data; combo / dual-axis / waterfall lose the un-captured plots — flagged for the user |**Visual re-confirm — full confirmation seeded from the source**:@@ -326,17 +330,17 @@ python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <project_path>/exports/<o| Text fidelity | every source text string appears in the output, unaltered || Data fidelity | chart categories / series / table cells match the source exactly || Page count | output slide count equals the source slide count |-| Regenerated visuals | charts / tables are native SVG re-themed to the inherited palette |-| Identity | generated text / shapes use only `<stem>.identity.json` colors + fonts |-| Paste-back | copying a beautified element into the original deck looks native |+| Regenerated visuals | charts / tables are native SVG re-themed to the effective palette |+| Identity | text / shapes use effective colors + fonts, seeded from `<stem>.identity.json` |+| Paste-back | copied elements retain effective palette + font declarations; alignment and font availability are not guaranteed |```markdown## ✅ Beautify Complete- [x] Content + data values verbatim (read-back Markdown matches the source)- [x] 1:1 page count preserved-- [x] Source-derived or explicitly overridden colors + fonts applied consistently-- [x] Charts / tables regenerated as native SVG in the inherited style+- [x] Effective colors + fonts applied consistently+- [x] Charts / tables regenerated as native SVG in the effective style- [x] Native PPTX exported to `exports/````@@ -347,11 +351,11 @@ python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <project_path>/exports/<o| Capability | Status ||---|---|| Re-layout with verbatim text | Supported |-| Inherit source palette / fonts as truth | Supported |+| Source palette / fonts as preselected recommendation, with user-approved overrides | Supported || Strict 1:1 page mapping | Supported || Regenerate charts / tables as native SVG from extracted data | Supported || Re-lay-out source pictures | Supported || Re-pagination (split dense / merge sparse) | Not in v1 || Carry source charts / tables / images over byte-for-byte | Out of scope — user copies originals manually if wanted |-| Free visual-style application / cleanup deviating from source identity | Not in v1 |+| Silent visual-style / identity deviation | Out of scope || Batch / multi-deck beautification | Not in v1 |diff --git a/skills/ppt-master/workflows/stages/live-preview.md b/skills/ppt-master/workflows/stages/live-preview.mdindex fb7f9ff1..97ce9188 100644--- a/skills/ppt-master/workflows/stages/live-preview.md+++ b/skills/ppt-master/workflows/stages/live-preview.md@@ -13,7 +13,7 @@ description: Main-pipeline editor stage for starting live preview and applying s- **Start (Step 1)** — preview service is not currently running and the user wants to look at the deck or click an element. Typical cases: post-export re-entry in a fresh chat, or the user clicked **Exit preview** earlier and now wants it back.- **Apply annotations (Step 2)** — Step 7 has produced at least one PPTX, and the user signals that submitted annotations should now be applied. Triggers include:- quoting the browser prompt (`Changes saved to svg_output...` / `修改已保存到 svg_output...`)- - saying `apply my annotations` / `apply my edits` / `应用注解` / `开始应用` / 等价表达+ - saying `apply my annotations` / `apply my edits` / `应用注解` / `开始应用` / or equivalent expressions## When NOT to Run