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
fix(images): make visual inspection context-first
hugohe3d675e50ea06f
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 5542f6fb..347149b9 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -282,7 +282,7 @@ These invariants are stronger than ordinary implementation preferences. If a cha| `svg_final/` is mandatory but derived | it is regenerated from `svg_output/` for self-contained visual preview or manual insertion as an SVG picture; it does not become the native export source of truth, and PowerPoint Convert to Shape is outside the supported contract || Native PPTX export reads `svg_output/` by default | converter preserves icons, `preserveAspectRatio`, rounded rects, and native image crop metadata before finalization rewrites them || Direct OOXML routes do not enter the SVG pipeline | preservation workflows patch native PPTX parts directly |-| Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; agents do not inspect image pixels directly |+| Image facts come from regenerated metadata | `analysis/image_analysis.csv` is re-derived from the live `images/` folder; Strategist uses source context first and inspects only a specifically ambiguous asset when semantics or safe placement cannot otherwise be resolved; Executor does not re-read source pixels || Raw PPTX templates are not Step 3 templates | Step 3 consumes reusable template directories only |---@@ -352,7 +352,7 @@ PPT Master uses **role switching within one main agent** rather than parallel su**Strategist confirmation stage as the only blocking gate.** Strategist ends with one gate delivered in three dependency-ordered stages. Stage 1 confirms an open communication contract and canvas. Its prose boxes contain editable recommendations, but 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. Stage 2 is authored once from that contract and confirms the complete deck solution: reading mode, narrative mode, page count, coordinated visual system, image sources, and generated-image rendering. When a template is installed, Strategist also derives its page/prototype application plan from the actual workspace and current content and exposes that plan as editable natural-language prose; only 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. Stage 3 is authored once and contains production mechanics only: conditional AI acquisition, formula policy, generation mode, and spec refinement. The compatibility key `delivery_purpose` means reading mode. Generated images inherit the selected deck color anchors directly; there is no independent image-palette choice. After the final wait, the final visible state in `confirm_ui/result.json` is read exactly once and consumed into `design_spec.md`, including production mechanics. Normal lock authoring and downstream execution do not reopen it. 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.-**Image analysis goes through regenerated metadata, not pixels.** When images exist, Strategist and Executor use `analyze_images.py` output (`analysis/image_analysis.csv`) rather than directly opening image files. The CSV is a regenerated view over the live `images/` folder, not a durable cache. Re-running it before image-sensitive decisions is the staleness strategy: user images, extracted images, web images, AI outputs, formulas, and sliced elements all converge into the same measured fact table.+**Image analysis is metadata-first, with a narrow Strategist visual fallback.** When images exist, `analyze_images.py` supplies the regenerated measured facts in `analysis/image_analysis.csv`; the CSV is a view over the live `images/` folder, not a durable cache. Strategist first resolves supplied images from source placement and nearby prose, captions / alt text / titles, filenames, user notes, existing resource records, and that metadata. It may inspect one specific image only when a material ambiguity remains about selection, factual identity, page role, crop safety, or focal placement—never as a bulk inventory scan. The answer is written into Design Spec §VIII, after which Executor uses the plan and measured geometry without reopening source pixels for semantic discovery. User images, extracted images, web images, AI outputs, formulas, and sliced elements still converge into the same measured fact table.**Per-page context projection** carries stable continuity anchors plus the current page delta — full rationale in § Spec Propagation below.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex ae322f42..e8e1bca1 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -284,7 +284,7 @@ CLI 支持 `--move`、`--copy` 和自动默认,但共享同一条固定的所| native PPTX 标准导出读取 `svg_output/` | 唯一受支持的可编辑形状路线由项目转换器执行;它要在 finalize 重写前保留图标、`preserveAspectRatio`、圆角矩形和原生图片裁剪语义 || PowerPoint 手工“转换为形状”不属于兼容性契约 | `svg_final/` 可以作为 SVG 图片插入,但转换后的结构与视觉结果不做保证,也不反向约束 SVG 允许能力 || 直接 OOXML 路由不进入 SVG 流水线 | 保留型工作流直接 patch 原生 PPTX parts |-| 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;agent 不直接看图片像素 |+| 图片事实来自重算元数据 | `analysis/image_analysis.csv` 从实时 `images/` 目录重算;Strategist 先用源文上下文,只在图片语义或安全放置仍无法确定时查看那一张具体图片;Executor 不重新读取源图像素 || 原生 PPTX 模板不是 Step 3 模板 | Step 3 只消费可复用模板目录 |---@@ -348,7 +348,7 @@ PPT Master 用的是**单主代理内的角色切换**,不是并行子代理**策略师确认阶段是唯一的阻塞 gate。** Strategist 阶段以一个按依赖排序的三阶段 gate 作为核心决策点。第一阶段确认开放式沟通契约与画布。其中的文本框承载可编辑推荐,但没有任何一项要求非空:确认时按当前文本原样保存,清空后的值保持为空,不会回退到推荐内容。第二阶段只从该契约计算一次并确认完整 PPT 方案:阅读模式、叙事 mode、页数、成套视觉系统、图片来源和生成图渲染。存在模板时,Strategist 还会根据真实工作区和当前内容推导页面/原型应用计划,并以可编辑的自然语言文本展示;只有内部复用/遵循模式保持隐藏。阅读模式决定信息由页面、视觉、讲者和备注如何共同承担,其选项卡不展示 px 数值。浏览器可以在本地执行确定性的「阅读模式 → 正文基准 → 未锁定角色字号」联动;手动编辑字号即锁定可见值,不会重新计算第二阶段。第三阶段也只计算一次,并且只处理生产机制:条件式 AI 图片获取路径、公式策略、生成模式与规范精修。JSON 为兼容保留 `delivery_purpose` 键,但用户侧统一称为阅读模式。生成图直接继承已选 PPT 色彩锚点,不再单设图片调色选择。最终等待结束后,流程只读取一次 `confirm_ui/result.json` 的完整最终状态,并把全部确认值(含生产机制)写入 `design_spec.md`;正常的 lock 编写与下游执行不再回读它。项目校验要求 `spec_lock.md ## communication` 下存在紧凑的 `audience` / `objective` / `core_message` 锚点,并要求 §IX 每个 Slide block 都有 `Audience move`。-**图片分析走重算元数据,不读像素。** 当项目里存在图片时,Strategist 和 Executor 使用 `analyze_images.py` 的输出(`analysis/image_analysis.csv`),而不是直接打开图片文件。这个 CSV 是基于当前 `images/` 目录重算出来的视图,不是持久缓存。每次做图片敏感决策前重跑分析,就是它的防陈旧策略:用户图、抽取图、网络图、AI 图、公式图和切片图最终都会汇入同一张可度量事实表。+**图片分析以重算元数据为先,Strategist 只保留小范围视觉兜底。** 当项目里存在图片时,`analyze_images.py` 把可度量事实重算到 `analysis/image_analysis.csv`;该 CSV 是实时 `images/` 目录的派生视图,不是持久缓存。Strategist 先根据图片在源文中的位置与前后文、图注 / alt / 标题、文件名、用户说明、已有资源记录和这些元数据判断。只有当某一张具体图片在选用、事实身份、页面角色、裁剪安全或焦点放置上仍有实质歧义时,才可单独查看它,绝不得扫描整个图片目录。结论写入 Design Spec §VIII 后,Executor 只消费该计划与几何数据,不会重新打开源图进行语义探索。用户图、抽取图、网络图、AI 图、公式图和切片图仍统一汇入同一张可度量事实表。**逐页上下文投影** 是长 deck 的抗漂移机制——完整理由见下面的 § 设计规范的传播。diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.mdindex fba7b468..29f9fd0a 100644--- a/skills/ppt-master/references/executor-image.md+++ b/skills/ppt-master/references/executor-image.md@@ -25,6 +25,8 @@ Handle images by their status in the Design Spec's Image Resource List. Status e**Mandatory — selected pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once when this branch loads, then resolve every primary/modifier id in each active §VIII/lock row to its exact catalog entry. Preserve the selected semantic composition. Adapt geometry, ratio, placement, spacing, and hierarchy for the actual page; never replace the pattern, role, file/source, must-use, or crop policy downstream. If another pattern is needed, return upstream to update the Design Spec. Only explicit user/template preservation locks exact geometry. Avoid generic left/right repetition.+**No semantic re-reading**: §VIII owns image identity, purpose, and focus / crop constraints. Executor uses its `Reference` plus regenerated dimensions; it never opens source images to rediscover subjects, substitute assets, or invent focus. For `adaptive` without reliable focus, use `meet`; missing or contradictory required constraints return upstream.+**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text**Crop policy**: read the §VIII row and matching lock projection. `crop=no-crop` (or a legacy trailing `| no-crop`) requires a native-ratio container and `preserveAspectRatio="xMidYMid meet"`. `crop=adaptive` permits but never requires cropping; choose `meet` or focal-safe `slice` from purpose, ratio, focus, and container. A missing or conflicting projection returns upstream instead of being inferred during execution.diff --git a/skills/ppt-master/references/strategist-image.md b/skills/ppt-master/references/strategist-image.mdindex 8f15a174..8e50d88e 100644--- a/skills/ppt-master/references/strategist-image.md+++ b/skills/ppt-master/references/strategist-image.md@@ -14,6 +14,8 @@ Before Stage 2, use proposed sources only for candidate construction. After confFor illustration, apply this precedence: confirmed `none` → explicit user intent → the locked visual style's `Illus.` propensity (`core` / `supportive` / `sparse`) → none. Propensity controls the lean, not the source or a page quota. When illustration is active, prefer one coherent motif family across hero/section anchors and local spots, but only when the confirmed assets can form that family.+**Context-first understanding for provided assets**: Do not visually scan `images/`. First infer identity, role, and crop / focus needs from source position and surrounding prose, captions / alt / titles, filename, user notes / confirmed `image_notes`, existing resource records, and CSV geometry. Inspect only one specific image when a remaining ambiguity would change selection, factual identity, page role, crop safety, or focal placement. Never inspect for inspiration, bulk-open the folder, or infer external facts / provenance from pixels. Record the result in §VIII. Leave an optional unresolved asset unused; route an unresolved must-use asset through failure recovery.+For ≥3 AI-generated same-family spots, plan one unplaced `ai` Illustration Sheet row plus one placed `slice` row per used element; only slice rows enter `spec_lock.md images`. State the intended placement shape family in the sheet reference and use separate sheets for incompatible shapes. [`image-generator.md`](./image-generator.md) §4.3 owns grid, ratio, slicing, and execution details. Stage 3 chooses the AI execution path under `image-generator.md` §7; do not pre-empt or re-pick it here.## 2. AI Image Strategy — propose before Stage 2; lock only for confirmed `ai`@@ -22,7 +24,7 @@ When proposed sources include `ai`, read [`image-renderings/_index.md`](./image-Also write one `custom_candidates.image_strategy` under the Confirm UI contract: localized `name` / `visual` / `mood`, `rendering: custom`, and non-empty localized `behavior` satisfying the catalog grammar. If it combines or borrows existing renderings, name every exact id in the visible proposal and read every corresponding `image-renderings/<id>.md` before writing the synthesis. If it is genuinely novel, read no preset file and name no catalog basis. Keep it unselected unless the user supplied it (`recommend.image_strategy: custom`); under a template it obeys inherited identity and application. Only a selected custom locks its edited behavior as `image_rendering_behavior`; when catalog material is actually used, also project the exact ids as `image_rendering_references`, otherwise omit that field. Discard an unselected candidate downstream. Ignore legacy `image_palette`.-For specialized or regulated paper-figure subjects, preserve the prompt depth required by [`image-generator.md`](./image-generator.md) §4.2 rather than shortening to a generic brief. Scan the outline for genuine image-led pages, list the proposed hero pages in Stage-2 `image_notes` so the user can retain, edit, or remove them in the same confirmation, then mark only the confirmed pages' AI rows `page_role: hero_page`; local is the default. `text_policy: embedded` is reserved for lettering that must be fused into the artwork; ordinary titles, data, labels, and prose remain editable SVG. Analyze confirmed provided assets before writing §VIII.+For specialized or regulated paper-figure subjects, preserve the prompt depth required by [`image-generator.md`](./image-generator.md) §4.2 rather than shortening to a generic brief. Scan the outline for genuine image-led pages, list the proposed hero pages in Stage-2 `image_notes` so the user can retain, edit, or remove them in the same confirmation, then mark only the confirmed pages' AI rows `page_role: hero_page`; local is the default. `text_policy: embedded` is reserved for lettering that must be fused into the artwork; ordinary titles, data, labels, and prose remain editable SVG. Resolve confirmed provided assets through the context-first boundary above before writing §VIII.## 3. Formula Asset Policydiff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.mdindex 127b6d9d..4b60815b 100644--- a/skills/ppt-master/scripts/docs/image.md+++ b/skills/ppt-master/scripts/docs/image.md@@ -164,7 +164,7 @@ Analyze images in a project directory before writing the design spec or composinpython3 scripts/analyze_images.py <project_path>/images```-Use this instead of opening image files directly when following the project workflow.+Use this as the default inventory and geometry source; it does not perform semantic image understanding. Generate planning follows the Strategist's context-first boundary: source context, captions / alt text / titles, filenames, user notes, and existing resource records come first. Only a specific asset whose meaning or safe placement remains materially ambiguous may be inspected, and the workflow never bulk-opens the image folder.## `image_search.py`diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.jsonindex 08412b31..12db5295 100644--- a/skills/ppt-master/scripts/prompt_audit_manifest.json+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json@@ -29,7 +29,7 @@"skills/ppt-master/references/native-data-interface.md": 6200,"skills/ppt-master/references/pptx-structure-interface.md": 4300,"skills/ppt-master/references/strategist.md": 13450,- "skills/ppt-master/references/strategist-image.md": 2100,+ "skills/ppt-master/references/strategist-image.md": 2250,"skills/ppt-master/references/strategist-template.md": 2100,"skills/ppt-master/templates/design_spec_reference.md": 2850,"skills/ppt-master/templates/spec_lock_reference.md": 2350,@@ -335,7 +335,7 @@"stage.generate.image.ai-two-types"],"files": [],- "max_tokens": 122550+ "max_tokens": 122800},"route.generate.flat-in-hand-image": {"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",@@ -347,7 +347,7 @@"stage.generate.executor.notes"],"files": [],- "max_tokens": 95850+ "max_tokens": 96100},"route.generate.flat-web-image": {"description": "Generate-PPTX context with web image acquisition.",@@ -360,7 +360,7 @@"stage.generate.image.web"],"files": [],- "max_tokens": 103100+ "max_tokens": 103350},"route.enhance-native-pptx.audio": {"description": "Enhance Native PPTX with the shared narration-audio stage.",@@ -549,7 +549,7 @@"stage.generate.executor.image"],"files": [],- "max_tokens": 58775+ "max_tokens": 58800},"stage.generate.topic-research": {"description": "Gap-targeted factual intake stage.",@@ -687,7 +687,7 @@"route.generate.planning-ai"],"files": [],- "max_tokens": 72275+ "max_tokens": 72450},"stage.generate.executor.chart": {"description": "Conditional chart/table page execution rules.",@@ -703,7 +703,7 @@"files": ["skills/ppt-master/references/strategist-image.md"],- "max_tokens": 2100+ "max_tokens": 2250},"stage.generate.strategist.image-layout": {"description": "Non-formula image planning plus the image-layout pattern catalog required for Section VIII rows.",@@ -714,7 +714,7 @@"files": ["skills/ppt-master/references/image-layout-patterns.md"],- "max_tokens": 8100+ "max_tokens": 8250},"stage.generate.strategist.template": {"description": "Conditional Strategist module for an explicitly installed template workspace.",@@ -741,7 +741,7 @@"skills/ppt-master/references/image-layout-spec.md","skills/ppt-master/references/svg-image-embedding.md"],- "max_tokens": 11600+ "max_tokens": 11625},"stage.generate.executor.web-image": {"description": "Conditional sourced-image attribution layered on image execution.",@@ -752,7 +752,7 @@"files": ["skills/ppt-master/references/executor-web-image.md"],- "max_tokens": 12000+ "max_tokens": 12050},"stage.generate.executor.notes": {"description": "Post-SVG speaker-notes generation rules.",diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.mdindex ff47c5a8..d8586aa8 100644--- a/skills/ppt-master/workflows/generate-pptx.md+++ b/skills/ppt-master/workflows/generate-pptx.md@@ -232,7 +232,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images> 🔁 **Image facts are regenerated on change, never maintained as a second store.** `images/` is the live working folder and single source of truth; `analysis/image_analysis.csv` is its regenerated view. Run `analyze_images.py` before the first inventory read, then reuse that CSV while `images/` is unchanged. Re-run after import/acquisition or any user addition, removal, or replacement; if the folder becomes empty, treat the inventory as empty and ignore a stale CSV.-> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output (`analysis/image_analysis.csv`) or the Design Spec's Image Resource List.+> ⚠️ **Image understanding**: Do not bulk-open images. Strategist uses source context, captions / alt / titles, filenames, user notes, existing resource records, and `image_analysis.csv` first; only a specifically ambiguous asset may be inspected under [`strategist-image.md`](../references/strategist-image.md). Record the result in §VIII. Executor never reopens source images for semantic discovery or reselection.**Output**:- `<project_path>/design_spec.md` — complete human-readable design narrative and durable confirmed production state