企业官网建设流程全解析

ppt-master 图片执行分支（Executor Image Branch）实战指南：从图片状态机到逐页构图决策

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master

导读

本篇技术指南讲解 ppt-master 中负责所有含图页面的执行分支——executor-image.md。它定义了图片在整条生成流水线（资源获取 → 校验 → SVG 编排 → 导出 PPTX）中的状态语义、裁剪策略、模板内置图片重定位规则，以及每页在写任何坐标之前必须完成的一次性构图决策链。读完本文，你将掌握：图片状态如何驱动 Executor 行为、no-crop与adaptive两种裁剪策略的合法边界、#M1-11同源可寻址裁剪的触发条件，以及五个方向生成器的构图数学，并了解这些契约在仓库脚本（如analyze_images.py、svg_quality_checker.py）中的落地支撑。

一、分支定位与触发条件

在 ppt-master 的执行架构中，executor-base.md 是所有页面共用的“平坦 SVG 页面创作核心”，而executor-image.md是它的条件分支（Conditional Executor authority）：只要任意一张幻灯片含图，该分支就与 image-layout-spec.md（几何计算）、image-layout-patterns.md（构图词汇）、svg-image-embedding.md（嵌入与裁剪策略执行）一起被装载。

按照 executor-base 的条件分支路由规则，所有触发器必须在 P01（第一页）之前对整张花名册（roster）扫描一次，触发到的模块在进入页面循环之前一次性批量读取，从而保证“读取动作不出现在页面循环里”。具体到图片的装载触发条件为：

两种执行档案对“权威来源”的定义不同，但都遵守同一套图片契约：

• Default Generate：以design_spec.md §VIII（图片资源列表）及其锁定投影（lock projection）为权威。用户图片确认后需要运行analyze_images.py补齐资源列表，再交给 Executor。
• Quick：以主 Agent 的 active-context 决策为权威，显式用户路径优先、未指定的获取方式自动解决，且在 SVG 创作前完成全部准备，无需确认或持久化花名册。

分支读取遵循“从每个对象的信息模型出发”的原则——不能只看图表引用判断分支，图片分支的触发只看页面是否真的含图。

二、图片状态处理契约（Status Handling）

executor-image.md开篇即给出契约：Executor 只消费已经准备好的资源（prepared assets），所有派生图（derivatives）已存在，原生处理（native treatments）是 SVG 层面的工作。状态枚举与生命周期完整定义在 svg-image-embedding.md，其语义在 image-base.md §1 中被进一步细化为“Acquire Via 路径分发”。Executor 对五种状态的处理如下：

2.1 状态的完整生命周期（svg-image-embedding 视角）

在创作（authoring）之前，svg-image-embedding.md 的 Workflow 要求所有资源先完成本地化准备：

1. 解决图片需求——Default：Strategist 资源列表 + 锁定投影；Quick：主 Agent 在 active-context 中决定。
2. 准备项目本地资源——user→ 落到images/→Existing；待处理的派生图 → image-base.md §1；ai→ Image_Generator →Generated；带视觉的web→ Image_Searcher 最多保存 8 个排名的预览 →Needs-Selection→ 提升或翻页 →Sourced/Needs-Manual；无视觉的web→ 严格按元数据排名取唯一最佳候选并记录方法 →Sourced/Needs-Manual；slice→ 父图版Generated后运行slice_images.py→Generated。
3. 只消费准备好的资源——Existing/Generated→<image href="../images/xxx.png" …/>；Sourced→<image>加署名<text>（仅attribution-required）；Placeholder/Needs-Manual→ 虚线边框加描述文字，直到文件被校验并调和为有效状态。
4. 导出——Default：generate-pptx.mdStep 7；Quick：全部必需资源具备已校验文件/出处与可用状态后，最终检查器通过再--quick-generate导出。

关键边界（Hard rule）：svg_final/ 是自包含预览，可被插入 PowerPoint 作为 SVG 图片；唯一受支持的生成-PPTX 路径是 svg_output/ 经项目转换器。PowerPoint 的手动 Convert-to-Shape 不被支持。

2.2 状态机在脚本层的落地

状态机并不是纸面约定，仓库脚本为它提供了可执行的支撑：

• analyze_images.py：报告目录内所有图片的客观参数（宽、高、宽高比、格式、是否含透明像素、文件大小），并生成analysis/image_analysis.csv。其 docstring 明确声明它“不解析画布、不规定布局、不生成 Strategist 建议”，与“Executor 只消费已准备资源”的分工完全一致。脚本还会读取image_manifest.json（可选）为 EMF/WMF 等矢量媒介补充分辨率元数据，并按宽高比把图片归类为 Ultra-wide / Wide landscape / Standard landscape / Near square / Portrait。
• svg_quality_checker.py：最终检查器会校验 SVG 层面的合规（例如行内样式白名单、clipPath只能在<image>上使用且<defs>中必须恰好一个基本图元等，见 shared-standards-core.md §1.2），同时负责Sourced图片缺失“作者 + 许可证”行内署名时报错。

三、模板内置图片：一次传输重写，不是视觉编辑

executor-image.md明确要求：模板内置图片（template-bundled images）必须被重新定位（rebased）。apply-template-workspace.md 负责把模板工作区中的images/、icons/便携资源原子化安装进项目（命令为python3 skills/ppt-master/scripts/apply_template.py <project_path> --root <workspace_root>）。

安装之后，含图页面（包括mirror页）都必须把相同的字节重定位到精确的../images/<name>：

• 这是传输层重写（transport rewrite），不是视觉编辑——像素内容不变，只是 href 指向项目本地资源。
• 绝不保留裸 href 或来源模板的 href。也就是说，任何页面 SVG 里出现指向模板源目录的资源引用都是违规的。
• 模板 SVG 只是创作原型（Master + Layout 上下文已解析），页面的真正身份来自design_spec.md与spec_lock.md，模板只指导构建、从不提供导出内容（executor-base 的 Shape-first 硬规则）。

四、裁剪策略契约（Crop Policy）

这是executor-image.md最核心的约束之一。Executor 必须读取 §VIII 行及其锁定投影（source、crop），并按以下规则处理：

4.1crop=no-crop（或旧式| no-crop）

在每一张使用no-crop源的幻灯片上：

• 必须保留一个可见的完整实例（one visible complete instance）；
• 该实例必须使用九种合法meet锚点之一；
• 严禁：none（拉伸）、clip-path、mask、溢出裁剪（overflow clipping）、嵌套裁剪视口（nested crop viewport）。

仅在“完整实例保持可见”的前提下，才允许**同页的辅助细节视图或放大镜（lens）**对同一源进行裁剪。

4.2crop=adaptive

adaptive表示允许但不要求裁剪。此时 Executor 需要从用途（purpose）、宽高比（ratio）、焦点（focus）与容器（container）出发，选择meet或焦点安全的slice。

4.3 冲突与回退

• 投影缺失或冲突 →返回上游（return upstream），不得自行猜测；
• §VIII 的Image pattern是Reference（参考起点）——除非标注(binding)，否则可以自由调整。

4.4 与嵌入语法的对应

svg-image-embedding.md 给出了标准<image>形态：

<image href="../images/image.png" x="0" y="0" width="1280" height="720" preserveAspectRatio="xMidYMid slice"/>

• preserveAspectRatio="xMidYMid slice"：居中裁剪，等价 CSScover；
• xMidYMid meet：完整显示，等价 CSScontain；
• none：拉伸——绝不允许用于no-crop源；
• Base64data:href 只是svg_final/预览形式，不是创作形态；
• clipPath在<image>上属于条件允许（见 shared-standards-core.md §1.2：<defs>中恰好一个circle/ellipse/rect/path/polygon）；不适用时应先把圆角烘焙进带 alpha 的 PNG 再嵌入。

五、硬规则一：同源可寻址裁剪（#M1-11）

executor-image.md对“同源可寻址裁剪”设定了严格的门槛——任何布局建议（包括#M1-11本身）都不会自动激活这种传输机制：

• #M1-11（same-source addressable crops）从多个独立对象中导出一组共享精确源坐标系的原生图片；
• #M1-09是刻意错位（deliberate-offset）处理，没有已注册或 Morph 的连续性，不属于本规则管辖。

只有在以下需求真正存在时才使用：

1. 多个独立裁剪必须保持一个精确的场景映射；或
2. 有明确的可编辑 / Morph 需求需要多个独立图片对象。

启用时的四条强制条件：

1. 复用同一个精确href，不得使用切片资源（slice assets）；
2. 每个独立对象要有稳定的、页面唯一的id，并且拥有自己的嵌套裁剪包装（nested crop wrapper）；
3. 每个包装的viewBox都必须从一个共享的“源到页面”变换推导，该变换作用于所有可见容器的并集——这样移除像素不会引起重缩放（gaps remove pixels without rescaling）；
4. 包装语法与形状框裁剪形式（shaped-frame clip form）见 svg-effects.md §6.5。

失败判定：重复裁剪或 SVG/PPT 漂移（drift）即失败。另外注意：在单个<image>上做复合裁剪（compound clip）是#M1-10（一个源导出为一个带分离裁剪子路径的原生图片，片段不是独立图片对象），不能替代需要“对象保持独立可编辑或可 Morph”的#M1-11。

image-layout-patterns.md §4.1 用一张拓扑对照表精确区分了三种“看似相似”的模式：

六、硬规则二：可见层时序（Visible-Layer Timing）

该规则约束“动效规划与 SVG 创作”的先后关系：

最终 SVG 中必须已经存在动效方案需要的每一个裁剪、放大镜、暗化层（scrim）、对比层、证据层或标注层；动效阶段可以重新分组普通的 Slide-local 内容，但绝不允许发明或修改可见内容。

推论：

• 当某个非绑定建议没有合法单元可用时，应简化为现有单元、页面切换或none；
• 当某个显式需求无法表达时，走失败恢复流程（failure recovery），不得在动效阶段偷偷补内容。

这与 executor-base 的“创作动效端点”（author motion endpoints）默认规则互为表里：转场与 Morph 配对键是后处理，但两个可见端点状态必须在页面书写阶段就创作好——连续的入场 / 翻转 / 推入 / 渐进揭示 / 平移都应该作为连续页面、各自延续端点在兼容的直接根组中完成，animations.json在之后负责绑定。

七、硬规则三：窄范围视觉检查（Narrow Visual-Inspection Scope）

为了在“检查图片”与“不越权处理资源”之间划界，该分支规定视觉检查必须极窄：

• 起点：§VIII 的Reference加尺寸信息；
• 时机：仅当焦点安全的裁剪、覆盖层对比度、安静区域或计划的主题关系仍不明确时，才对资源（或它的审查副本）检查一次；
• 次数：照片主导的页面可能对多张资源各查一次，但每张一次、绝不查整个文件夹；
• Generated 资源：仅当意图与尺寸无法消解歧义时才检查，绝不例行检查。

检查永不重新打开资源选择、改变身份或必须使用项（must-use）、推断出处、替换资源或虚构焦点。不确定的adaptive焦点一律使用meet；冲突的绑定约束返回上游。

八、逐页图片构图决策链（Image Composition）

executor-image.md§1 的第一条是Mandatory（强制）：每张含图页面，在几何（geometry）之前、仅 active-context 中，执行一次完整的构图决策：

role → direction generator → parent contour → slots/rhythm → crop → image-shape action → labels/overlays → depth/continuity

该链由沟通任务（communication job）、信息层级（hierarchy）、文案（copy）、资源宽高比 / 焦点与整副牌节奏（deck rhythm）共同推导，使用的动词包括anchor、continue、bridge、overlap、reveal、echo、register——仅当确实有用时才采用。

决策后必须与朴素 / 仅P的放置做对比，实施更强的合法构图；不做额外产物、不多跑一遍、只要上下文有效就不得重读分支。

8.1 默认：积极图片整合（可覆盖）

• image-layout-patterns.md 是词汇表，image-layout-spec.md 是数学，两者都不是配额也不是锁；
• #P…建议只是骨架，可以通过 svg-effects.md 与 native-shape-authoring.md 加深、简化或组合；
• 必须保留：role / source、must-use、crop / content、显式约束；纯表达层面的改动无需返回上游重写。

8.2 默认：最终尺寸下保留图片任务（可覆盖）

在接受窄条（narrow band）、小尺寸放置或裁剪之前，必须保证图片用途所命名的主体或关系在其页内尺寸上仍然可识别；如果它塌缩成颜色纹理（color texture），就放大或重组，并且只有当上游任务允许时才把它当作纯纹理处理。

8.3 默认：每个图片组一个方向生成器（可覆盖）

槽位位置、裁剪边缘、重叠与旋转都必须从一个生成器推导；多角度需要显式声明节奏或碰撞规则。五个生成器的行为如下：

在 image-layout-spec.md §4.3 中，每个生成器都有精确的可执行数学规则（直线帧方程、基线B(t) = b + t×d、曲线p[i] = C(u[i]) + e[i]×n[i]、四边形面板F(u,v)双线性插值），并明确禁止剪切、斜切与真实透视（panel是 2D 四边形裁剪集合，绝不是扭曲的图像平面）。当采用curve-spine且某点导数为零时，退化为取最近不同采样点之间的割线或换用其他生成器。

8.4 参考：动效就绪分层（Motion-Ready Layering）

当自定义动效激活时（见 executor-base.md §1）：

• 每个独立揭示或延续的图片单元现在就应是自描述的、直接根下的<g id>；
• 稳定取景保持静态，结构化原子与槽位保持边界；
• 已有单元或页面切换可能已经足够；
• 效果、配对、顺序与时机归动效阶段所有。

九、与构图词汇、几何计算的分工

为避免职责重叠，图片相关文档的分工是清晰的：

9.1 网页图片署名（Sourced 状态必读）

executor-web-image.md 规定：manifest（image_sources.json）是署名的唯一来源，署名渲染在 Executor 创作的 SVG 里，绝不由后处理或导出补写。

从 manifest 的attribution_text出发，文件名与完整 URL 在来源清晰时可省略，但作者与许可必须保留，否则svg_quality_checker.py会报错（一个笼统的 CC 标记不能覆盖多个文件）。署名绝不重复进 speaker notes 或其他产物。

十、工具链与导出边界

• 分析：用户图片选定后、Executor 开始前运行python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images，生成控制台报告与analysis/image_analysis.csv，补齐 §VIII 资源列表。
• 预览：在项目根目录运行python3 -m http.server -d <project_path> 8000预览svg_output/（直接打开文件时浏览器会拦截跨目录图片）。
• 导出：Default 的finalize_svg.py把图片嵌入svg_final/预览；Quick 跳过该步；两者的原生导出都直接读取svg_output/。受支持的唯一生成-PPTX 路径是svg_output/经项目转换器，svg_final/只作为可选预览（EMF/WMF 保留外链例外做无损透传）。
• 资源消费：SVG 创作只消费project/images/*.{jpg,png,webp}与image_sources.json；Default Executor 从不调用image_gen.py/image_search.py/slice_images.py/image_treat.py，缺料一律返回 Strategist 所属的准备阶段；Quick 在创作前完成获取与派生，绘制期间不获取、不派生、不重选。

十一、落地检查清单

按executor-image.md的契约，一张合规的含图页面应满足：

• 状态合法：只消费Existing/Generated/Sourced，Placeholder用stroke-dasharray="8,4"虚线加描述，Needs-Manual在 Default 中等到 Step 7、在 Quick 中直接阻断；
• no-crop源：每页至少一个可见完整实例，只用九种合法meet锚点，无none/clip-path/mask/ 溢出 / 嵌套视口；
• 模板内置图片全部重定位到../images/<name>，无裸 href 或来源模板 href；
• #M1-11仅在可编辑 / Morph 或精确场景映射需求下启用，且满足“同一 href、页面唯一 id、独立嵌套包装、共享源到页面变换推导 viewBox”四条；
• 可见层时序成立：最终 SVG 已包含动效所需全部裁剪 / 放大镜 / 暗化层，动效阶段不发明内容；
• 每张含图页在几何之前完成一次构图决策链，并与朴素放置对比后实施更强构图；
• Sourced图片按license_tier渲染行内署名，作者与许可可被检查器绑定。

这套契约的最终目的是让 Executor 在“只消费已准备资源”的红线下，仍然能产出构图更强、裁剪合法、可编辑可动效的高质量含图页面——从状态机到构图决策，每一步都有文档、脚本与检查器共同背书。

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master