knight-imagetopptx-skill

Knight 图片转 PPTX

适用范围

仅用于已有的视觉幻灯片：

• 需要转换为可编辑 PowerPoint 的 PNG/JPG/WebP 幻灯片图片。
• 幻灯片仅包含图片或生成的整页图片的 PPTX。
• 需要将每一页转换为可编辑 PowerPoint 幻灯片的 PDF 或多页图片集。
• 需要将渲染后的幻灯片页面转换为可编辑文本、容器、箭头、图标和布局对象的情况。

不要将其用于从头创建新演示文稿、仅转换 SVG，或用户不需要按对象编辑的简单图片打包。

核心规则

以语义化方式重建幻灯片，使用户需要编辑的部分成为实用的 PowerPoint 对象。

• 文本、卡片、面板、分隔线、线条、简单箭头、项目符号、徽章和表格：创建为 PowerPoint 原生对象。
• 图标、象形图、复杂徽章、装饰性标记、微小 UI 字形、插画风格元素、复杂图片和复杂视觉对象：必须使用图像生成模型生成独立的透明 PNG 资源，然后插入 PPTX。
• 流动的丝带箭头、迁移流、渐变箭头带、多车道流程箭头，以及任何需要柔和渐隐、成束曲线、重叠流线或融合箭头的箭头系统，均属于复杂视觉对象。使用图像生成模型单独生成，并将其拼接到 PPTX 中，作为一个或少量几个透明 PNG 视觉资源；不要用许多原生矩形、三角形或曲线片段重建。
• 源图裁剪仅供参考。除非用户明确提供了必须保持原样的真实徽标/品牌标记，否则不要将截图裁剪片段用作最终图标资源。

强制执行约定

触发此技能时，以下工作流为强制要求，而非可选建议。不得从截图直接跳到 PPTX；缺少所需证据时，不得交付文件。

构建之前，需在内存或本地笔记中跟踪执行状态。仅在接近结束时写入一次 rebuild_execution_report.json，作为精简的最终摘要；不要反复重写冗长的阶段日志。最终摘要必须涵盖以下阶段：

• input_prepared：记录源路径、幻灯片/页面数量、幻灯片尺寸、宽高比和输出目标。
• visual_inventory_done：使用稳定 ID 列出主要文本块、原生对象、连接线、表格、卡片、图标和复杂视觉元素。
• asset_classification_done：将每个非文本视觉元素标记为 native_editable 或 imagegen_asset。
• imagegen_assets_done：每个 imagegen_asset 均有图像生成来源、最终透明 PNG、清单条目，以及联系表或裁剪 QA。
• text_fit_done：使用 ppt_text_fit.py 检查每个可见的 PPT 文本对象，或记录例外；报告可以精简。
• pptx_built：生成了包含原生文本/形状和独立图像资源的可编辑 PPTX。
• render_qa_done：将 PPTX 渲染为 PNG，并在整页层面与参考图进行比较。
• local_crop_qa_done：裁剪并检查图标按钮、信息密集的卡片、表格、标签、底部栏和用户标记区域等紧凑区域。
• validation_done：运行资源检查器和相关脚本/编译检查，或记录阻塞原因。

如果任何阶段无法完成，应停止并报告阻塞原因，不得悄悄跳过。如果用户要求加快处理或只需粗略版本，仍需提供最低限度的精简执行摘要、资源清单、渲染预览和验证；若 QA 有意不完整，应将结果标记为草稿。

最终答复必须包含 PPTX 路径和最重要的证据路径，通常包括渲染预览、资源联系表、精简的文本适配报告，以及值得注意的裁剪 QA。不能仅凭代码生成就声称已完成。

不可妥协的图像生成门槛

最终图标和复杂视觉素材必须由图像生成模型生成。 不得使用 PIL、SVG、canvas、图标字体、手动编写的矢量路径或 PowerPoint 形状绘图来手绘、脚本生成、描摹或近似绘制最终图标。这些方法仅可用于创建应在 PowerPoint 中保持可编辑的原生简单图形，例如卡片、线条、箭头、表格、分隔线、简单徽章和文本容器。

重建前，对每个非文本视觉区域进行分类：

• native_editable：应在 PowerPoint 中保持可编辑的简单几何图形，例如面板、圆角矩形、普通单箭头、表格单元格、分隔线、小型数字徽章和纯 UI 容器。
• imagegen_asset：图标、象形图、未提供精确品牌文件的徽标、装饰性天际线、插画片段、复杂徽章／印章、应转换为风格化且近似可编辑素材的截图、密集的微小字形簇、吉祥物／人物／设备／场景、复杂图片、流动的带状箭头、迁移流、多车道渐变箭头，或任何需要自定义绘图逻辑才能忠实重建的视觉元素。

对于每个 imagegen_asset，调用图像生成模型，或复用本次重建中该模型已生成的素材。如果工具保存了原始生成文件，请保留该文件，将其复制到工作目录的 assets/ 文件夹，然后按需裁切／重新打包／清理成独立的透明 PNG。在素材清单中记录生成源路径或提示词。

如果图像生成工具不可用、遭到阻止或多次失败，请停止并报告阻碍。不得悄悄用脚本绘制或手工编写的替代素材取代所需素材，也不得将此类替代素材描述为生成素材。

工作流

1. 准备输入

   • 在源文件旁创建工作文件夹，例如 editable-replica-XX/。
   • 如果输入是纯图片 PPTX 或 PDF，请先将每页／张幻灯片渲染／导出为 PNG，并将每张渲染图作为参考图像。
   • 如果输入包含多张图片，请保留其顺序，并将每张图片视为一张目标幻灯片。
   • 记录幻灯片尺寸、宽高比、源文件名／页码和输出路径。
   • 开始跟踪《强制执行契约》要求的执行阶段，但在验证后仅编写一次最终的 rebuild_execution_report.json，作为简洁摘要。
   • 对于多页输入，每一页都是独立的单页重建任务。不要通过复制第 1 页并粗略修改来制作第 2 页，除非两页的视觉内容确实重复，且渲染检查已确认这一点。

2. 盘点页面

   • 编制视觉清单：标题／副标题／正文文本、卡片、面板、容器、箭头、连接线、图标、标签、页脚和背景。
   • 为每个非文本视觉素材分配稳定 ID，例如 process_log_parse、output_excel_sheet、bottom_human_reviewer。
   • 记录每个素材的大致边界框和目标视觉尺寸。
   • 根据上述不可妥协的图像生成门槛，将每个非文本视觉元素标记为 native_editable 或 imagegen_asset。
   • 对每个不是普通直线的箭头或连接线，记录其稳定 ID、尾到头方向、路径类别（straight、elbow、arc、U-turn、hook、loop 或 ribbon）、描边／填充用途、大致边界框以及任何关联标签。后续 QA 时，将箭头及其关联标签视为一个视觉组件。

3. 生成图标和视觉素材

   • 对每个 imagegen_asset 使用图像生成模型。提示模型生成独立的扁平／矢量风格素材，不含文字、标签、数字或卡片边框；除非参考图中可见，否则不要添加阴影。
   • 颜色准确性是首轮生成的硬性要求。 提示模型前，采样并记录每个图标参考图的颜色：前景描边／填充色、内部细节色、容器／主体色，以及图标应为透明、单色、彩色底白色图案、白底彩色图案还是多色。首个图像生成提示必须注明这些颜色的作用，并为每个素材或网格单元提供近似十六进制值。不要让模型自行选择通用配色。
   • 将颜色作用视为素材身份的一部分。如果参考图中的同一图形使用了不同颜色或状态，请生成不同的专属颜色素材或网格单元。如果生成素材的颜色作用与参考图不符，则将其标记为无效，并在插入 PPT 前根据提示或源图重新生成；不要依赖 PPT 着色、重新配色、不透明度技巧或后续清理来修复首轮生成时错误的颜色。
   • 对于复杂的视觉区域，先分析其语义目标，并提示模型重新构建出干净的素材，而不是复制像素裁剪图。只要文字可以作为 PowerPoint 中可原生编辑的文本，就应放在图像之外。
   • 对于流动箭头、迁移流、带状条及其他复合箭头视觉效果，请生成透明 PNG 素材。提示中应说明后续放置到 PPT 所需的确切路径数量、方向、颜色作用、渐变方式、曲率、箭头样式以及中心／边缘的留白区域。如需独立对齐，可将生成的源图拆分为少量语义明确的透明素材，例如左向流和右向流；避免将每条路径或箭头单独拆成 PPT 对象。
   • 要求图像生成模型输出真正带透明背景的 PNG。保留原生 alpha 通道；生成素材必须为 RGBA，四角透明、alpha 边界框非空，并且主体覆盖范围合理，然后才能裁切或插入。
   • 仅当明确规定 C×R / N×M 对齐规则时，才允许使用素材网格，其中 C 或 N 表示列数，R 或 M 表示行数。此规则适用于正方形 N×N 网格和 5×4 或 4×2 等矩形网格。
   • 在图像生成提示中准确说明网格尺寸：C 列 × R 行、画布整体比例为 C:R、单元格尺寸相等、单元格之间有可见或有意留空的间隔、每个图标居中于所属单元格的中心、每个图标限制在中央 55-65% 的安全区域内，以及每个单元格至少留出 20-25% 的透明空白边距。要求图标边缘不被裁切、不伸入间隔，并且单元格之间没有重叠。
   • 对于正方形 N×N 网格，要求使用正方形画布，并设置 N 行和 N 列，且各行列等分。对于矩形 C×R / N×M 网格，要求画布宽高比与列数：行数的比例一致。边缘单元格必须遵守与内部单元格相同的安全区域和留白规则。不要将 5×4、4×2 或任何特定网格尺寸写死；应将列数和行数作为参数传入。
   • 裁切前验证原生 alpha 网格输出：确认模式为 RGBA、四角透明、alpha 边界框非空，且没有意外的不透明背景。
   • 每个单元格必须恰好裁切为一个语义素材。避免将多个图标混在同一个素材中。
   • 不要只依赖网格计算。裁切素材网格后，移除跨单元格碎片，并检查最终独立 PNG 的联系表。如果任何图标包含多余的弧线、圆点、楔形、被裁切的描边、相邻单元格的局部标记，或生成源图本身造成的边缘单元格裁切，则将网格视为无效；在插入素材前，使用更严格的安全区域、间隔和留白约束重新生成网格。
   • 裁切后，将每个 PNG 规范化为带有充足安全留白的正方形透明画布。目标：边缘至少留出 10 px 的透明边距。根据 alpha 视觉质心居中，而不只是根据 alpha 边界框中心；目标、星形、光线、箭头和放大镜等非对称图标若按边界框居中，视觉上可能会偏离中心。
   • 将生成的源图存放在 assets/source/ 或同等的源文件夹中，并确保最终素材目录仅包含将插入 PPT 的独立透明 PNG。这样可以避免在质量检查时将源图误认为最终素材。
   • 插入 PPT 时，根据素材的非透明 alpha 范围缩放，并按 alpha 质心对齐，而不是按整个透明画布对齐。保持宽高比；不要拉伸图标以填满任意目标框。

4. 重建 PPTX

   • 使用 python-pptx、PowerPoint 自动化工具或仓库既有的 PPT 工具。
   • 对于纯白或米白页面，优先使用原生幻灯片背景填充（slide.background.fill），而不是添加覆盖整张幻灯片的白色矩形。仅当底部背景矩形包含 PowerPoint 背景填充无法呈现的可见装饰时，才使用此矩形。
   • 所有可读文本均使用原生 PowerPoint 文本框。不要将可编辑文本栅格化为图片。
   • 圆角卡片、面板、边框、分隔线、虚线和普通箭头均使用原生形状。
   • 选择 PPT 对象类型前，先匹配箭头几何形态：方向、尾端和箭头端的位置、路径类别、线条/填充粗细、弯折或曲度，以及与标签的关系都很重要。如果参考图显示卡片或步骤之间有粗实心箭身/箭头，应使用 DOWN_ARROW、UP_ARROW、LEFT_ARROW 或 RIGHT_ARROW 等原生实心箭头形状，而不是带箭头的连接线。只有当源图视觉上像细线/连接线时才使用连接符。
   • 紧凑的返回、U 形转弯、钩形、反馈和标注箭头，不得简化为直箭头或方向不同的默认形状。如果原生箭头能匹配参考图，应使用单个可编辑的开放自由形状/弧线路径，并设置原生箭头头部；如果使用内置 U 形转弯/钩形状，则应先在目标尺寸下渲染 0、90、180、270 度的候选旋转，再选择箭头头部方向和环路侧与参考图匹配的版本。除非参考图本身是方形分段几何形态，否则不要用独立直线段近似明显的弧形返回路径。
   • 对于矩形类对象，如章节标题、标题栏、胶囊按钮、指标卡片、标签页和标签条，应使用原生 RECTANGLE 或 ROUNDED_RECTANGLE 形状。除非源图中确实有倾斜缺口或旗帜尾部，否则不要使用带尾部的横幅、箭头、三角形或自由形状辅助对象。
   • 将生成的复杂视觉素材（如流动丝带箭头、密集截图和插画区域）作为透明 PNG 插入，并根据参考图将其放在原生对象的后方或之间。按可见 alpha 边界缩放并对齐到测量出的目标边缘；可编辑标签、卡片、中心圆、图例和标注应使用原生 PPT 对象，并放在素材上方或周围。
   • 对于漏斗、梯形、箭头、箭头楔形、三角标签和倾斜徽章等方向敏感的原生形状，不要依赖 PowerPoint 默认方向。应将渲染结果与参考图比较，并在必要时旋转形状或使用原生自由形状路径重新绘制。
   • 明确控制 PowerPoint 圆角矩形。在某些宽高比下，MSO_SHAPE.ROUNDED_RECTANGLE 的默认圆角会大得像胶囊；应将 shape.adjustments[0] 设为约 0.025-0.08，并检查渲染结果。
   • 每个图标/复杂视觉对象使用一个生成的 PNG，背景透明且边缘不被裁切。
   • 不要拉伸图标。应保持宽高比，并按 alpha 内容框居中。
   • 编写密集表格单元格、卡片、按钮标签、中英混排标签以及任何长标题/副标题之前，应先测量完整的可用文本区域（预留边框、图标和实际内边距后），再进行文本适配预检。务必使用导出的像素边界框、目标字体、粗体状态和参考图最大行数调用 scripts/ppt_text_fit.py；以其 recommended_pt 作为初始字号，并保存精简的 text_fit_report.json 或等效证据文件。
   • 文本适配覆盖范围以最终可见文本为准，而不是是否使用了名为 add_fitted_text() 的辅助函数。所有创建 PowerPoint 文本的代码路径都必须在写入文本前提供适配证据：add_text()、手动编辑 text_frame、paragraph.add_run()、中英混排的数字/单位行、表格单元格、徽章、标签、图例、图表/坐标轴标签以及较小的界面说明文字。只有在完整可见短语或各个声明的子框都经过适配后，才允许使用硬编码的文本片段字号；报告中还必须注明已适配的文本对象名称。
   • 避免两个极端：既不能让文本溢出、越过表格边框或产生非预期换行，也不要为了适配而将文字缩小到低于参考图中的视觉层级。如果文字只有缩小到明显不符合其作用的程度才能放下，应首先视为文本区域几何问题：扩展文本框至可用留白区域、减少重复的内部边距、调整图标/分隔线/列宽分配，或采用与参考图相同的换行方式。缩小字号应是最后手段，而非默认修复方式。
   • 在 python-pptx 中使用中文文本时，除了设置 run.font.name，还要在 OOXML 中设置东亚字体（a:ea）；否则 PowerPoint 可能回退到宋体/衬线字体，导致布局偏移。
   • 将重复标签/按钮组件视为响应式组件，而非固定尺寸。Agents 工作流 等中英混排标签通常需要更小的字号、更宽的文本框或经过调整的文本偏移，与纯中文标签不同。
   • 工具/示例按钮应由原生按钮形状、独立图标 PNG 和可编辑文本组成。不要将 Doc、PPT、frontend、imagegen 或 GitHub 等标签烘焙进图标图片。
   • 对于圆形流程环，如果参考图使用平滑弧形箭头，不要只依赖弯曲连接符。应使用真正的 PowerPoint 原生弧线/箭头对象，或高精度的开放自由形状曲线路径。不要用许多独立的直线连接段模拟平滑弧线；可见接缝和选择窗格中的杂乱对象都是实际缺陷。
   • 如果弧形环路需要多个弧形箭头，应让每个弧形段各自成为一个连续的可编辑对象，并将这些弧形段编组为一个顶层视觉对象。为组指定描述性名称，例如 center_cycle_curved_arrows_group，这样用户既可将整个环路作为一个对象移动，也可取消组合进行编辑。
   • 渲染前进行最后一次图层顺序检查。硬性规则：保留原生对象内部顺序；只将图标和文本上移。保持原生对象的内部视觉顺序，将生成的图标素材置于原生对象上方，再将所有文本置于最上层。形状不得遮挡可编辑文本，图标也不得遮挡标签。
   • 优先按照自然的可见顺序构建各组件：先添加原生容器/卡片，再添加图标/图片素材，最后添加可编辑文本。若组件内部顺序已能正确呈现视觉层叠，就不要盲目重排整张幻灯片的 XML。
   • 任何 z 顺序调整后，都要检查渲染出的 PPT 裁剪图，而不只是 PPTX 形状列表。图片即使存在于 PPTX 中，若 PowerPoint 形状树中的实际顺序有误，也仍可能被后续原生形状遮挡。
   • 保持淡淡的构造圆环和辅助圆足够浅。PPT 椭圆描边的半透明效果叠加后，在导出时可能形成不必要的灰色圆环；应删除含义不明的圆环，或使用极高透明度并明确清除继承的阴影。

5. 渲染并比较

   • 如果可用，使用 PowerPoint 导出功能将重建的 PPTX 渲染为 PNG。
   • 生成视觉预览图／缩略图并与参考图比较。
   • 针对明显不匹配之处进行迭代调整：图标裁切、图标尺寸、箭头方向、文本换行、卡片边框、对齐和间距。
   • 裁剪拥挤区域以进行 QA，不要只检查完整幻灯片。为底部标签、密集卡片、圆形图示、右侧工具面板、反馈栏、紧凑的回转／标注箭头以及任何选中对象问题，保存 1:1 PNG 裁剪图。
   • 对于每个紧凑的非直线箭头或带标注的标注框，将渲染裁剪图与对应的参考裁剪图进行比较。将箭头尖端方向、路径／环绕侧、线条或填充粗细、端点和标签位置作为一个整体进行核对。即使整体流程方向在语义上正确，只要存在不匹配，也要在交付前修正。
   • 对于每个紧凑的图标槽位，尤其是按钮／工具／UI 图标，都要对插入 PPT 区域进行 1:1 局部裁剪渲染。仅凭素材缩略图还不够：要确认最终渲染的 PPT 中没有边缘裁切、残留碎片或相邻单元格的杂物。
   • 对于多页输入，将每张重建的幻灯片与其对应的源页面逐一渲染和比较。交付前逐页修正不匹配之处。

6. 组装多页输出

   • 对于多张源图像／页面，按原始顺序将所有独立重建的幻灯片追加到一个 .pptx 文件中。
   • 按幻灯片／页面编号整理每页素材、清单、渲染预览和 QA 裁剪图，以便追踪。
   • 除非用户明确要求，否则不要交付多个独立的 PPTX 文件；默认交付物是一个合并后的可编辑 PPTX。

实现模式

• **CJK 字体 XML：**设置 run.font.name 后，还要在运行 XML 中设置 a:latin、a:ea 和 a:cs 的 typeface。每个中文文本运行都要这样设置。
• **文本适配预检：**生成 PPTX 前，估算每个密集表格单元格、卡片标题／正文、副标题、按钮标签和图标旁标签的文本宽度／高度。优先使用随附的辅助工具：

python scripts/ppt_text_fit.py --text="升级方向不是少做事，而是更会定义、拆解、验收和复盘。" \
  --box 980x42 --font "Microsoft YaHei" --max-pt 22 --min-pt 12 --max-lines 1

使用返回的 recommended_pt 和 lines 设置首次 PPT 构建。对于任何高风险标题或混合语言标签，还要传入 --target-pt <reference-size>：此时报告会返回 required_box_px 和 box_deficit_px，明确指出正确的修复方式是否应该是加宽／加高文本框，而不是缩小字号。保持最终的 text_fit_report.json 简洁：记录 called、notfits、exceptions，以及带有参考字号和文本框缺口的代表性高风险长文本。默认不要记录每个成功适配的短标签；只有在主动诊断故障时，才将完整的逐形状详情保留在临时调试数据中。此辅助工具使用 Windows 字体文件、幻灯片导出缩放比例、可见字形边界框、支持中日韩文字的换行、二分搜索、安全边距、可可靠处理 argparse 参数中以连字符开头的文本，以及用于输出中文／符号 JSON 的强制 UTF-8 标准输出。如果辅助工具不可用，请使用 PIL ImageFont.truetype() 和 Microsoft YaHei/SimHei/Arial，采用相同逻辑；只有在最后才退而使用粗略的中日韩字符估算。不要仅用原始字体 ascent+descent 估算行高；这会过度计算 YaHei 不可见的留白，使标签变得过小。

• **文本参数安全：**从 Python 或 shell 调用 ppt_text_fit.py 时，传入 --text=<value>，不要使用 --text <value>。这样可以避免以减号、加号、各种破折号、箭头、括号或包含大量符号的指标前缀开头的值被误读为命令选项。如果包装器构造子进程参数，请将 f"--text={text}" 作为单个 argv 项。
• **严格覆盖所有文本适配：**不要将适配限制在 add_fitted_text() 这类单一包装器。所有生成文本的操作都必须纳入范围，包括 add_run() 分支、直接编辑 shape.text_frame、表格单元格文本、手动组合的数值指标、徽标标签、拆分的标题／正文文本运行、图表标签和页脚备注。对于数字+单位、英文缩写+数字+单位、带符号的值+单位、值+趋势符号等混合字号的指标行，先将完整可见短语按整个 bbox 适配，再从适配后的基础字号推导数字／单位文本运行的字号，或在明确划分的子框中分别适配数字和单位。构建时在内部跟踪覆盖范围。最终精简版 text_fit_report.json 应包含 called、notfits、exceptions 和有代表性的 key_long_texts；只有失败、例外或高风险长文本需要逐对象详情。
• **手动文本运行的例外管理：**如果微小的装饰标签、页码或有意固定字号的徽标确实无法使用 ppt_text_fit.py，请在精简报告的 exceptions 中记录其 bbox 和原因，并用本地渲染裁剪图验证。未报告的硬编码字号属于缺陷。
• **参考行数锁定：**在适配前，根据源图确定目标最大行数。源图中单行的标签必须适配为单行；两行的源标题必须保持两行。除非源图清楚显示如此，否则不要手动插入造成行数多于参考图的换行符。
• **PPT 点到像素的比例：**根据实际导出设置计算，不要凭记忆估算。对于 13.333333 in 宽的幻灯片，若输出宽度为 1672 px，则 px_per_pt = (1672 / 13.333333) / 72 ~= 1.742；辅助工具会应用此比例以及渲染修正系数。若使用不同的幻灯片尺寸或导出宽度，请传入 --slide-px 和 --slide-in。
• **文本角色层级：**保持字号灵活，并根据参考页推导，不要使用固定数值范围。保留标题、副标题、卡片标题、表头、表格正文、工具名称、标签和备注之间的相对层级。如果文本只有缩小到明显弱于同角色相邻文本时才能容纳，应调整几何尺寸、边距、列宽或换行方式，而不是默默接受过小的文本。
• **文本槽位几何尺寸锁定：**将文本框视为短语可使用的完整可编辑区域，而非源图中字形深色像素的 bbox。记录参考字号，并检查每个标题、长单行标签和中英混合短语的 target_required_box_px／target_box_deficit_px。较低的 reference_scale 表示必须先修复文本框、图标预留区域或边距，才能接受较小字号。通过渲染裁剪图保留源文本的视觉高度；仅凭 fits: true 不足以作为判断依据。
• **同级清单项对齐检查：**不要将清单中的每一行都交给使用固定 text_w × text_h 的单一辅助工具处理。先为图标预留空间，再为每一行分配剩余卡片宽度；较长的中英混合标识符通常需要更宽的文本框、更小的重复边距，并明确指定参考字号。对于每个单行清单项，报告 reference_scale；如果低于 0.90，应修复该行的文本槽位或卡片几何尺寸，并与相邻行进行裁剪图对比后再接受结果。只有当源图明显如此时，才可适度缩小较长标识符的字号。
• **溢出防护：**表格正文应位于各自单元格内，与垂直网格线之间至少留出 10-16 px 的视觉内边距。卡片文本应先预留图标空间，再仅在剩余文本区域内适配。对于参考图中的单行标签，不要允许意外换行；对于多行标签，应匹配观察到的行数和行距。对于 看 diff、看运行结果 这类中英混合标签，应视为比纯中文文本更宽，并在渲染前为其留出更宽区域或采用符合角色层级的较小字号。
• **卡片文本垂直居中：**对于药丸形元素、按钮、工作流卡片和图标+标签卡片，应将文本框对齐到完整的预期视觉槽位，并将垂直锚定设为居中（MSO_ANCHOR.MIDDLE 或等效设置）。不要凭目测基线位置放置较小的文本框。若参考图中的卡片正文是垂直居中的，就应在预留区域内垂直居中，并使行数和行距与参考图一致。
• **趋势／箭头预留槽位：**对于由标签、带符号的值、单位和趋势箭头／图标组成的紧凑指标行，应先将该行划分为明确的标签、数值和箭头／图标槽位。适配文本的 bbox 必须排除箭头槽位；箭头应锚定在独立预留槽位中，并与卡片边缘保持足够间距。不要使用可能与较长百分比或中英混排数字／单位文本重叠的绝对 x 偏移来放置趋势箭头。交付前应为这些密集行渲染本地裁剪图。
• **趋势箭头形状保真：**如果参考图显示的是带填充杆部和三角箭头的粗趋势箭头，应使用 UP_ARROW 或 DOWN_ARROW 等原生 PowerPoint 箭头形状构建，而不是使用文本字形、细连接线或带箭头的线条。预留独立箭头槽位，并将指标文本作为可编辑文本放在其旁边。
• **自适应卡片布局：**重复卡片可能需要分别调整每张卡片的几何尺寸。不要在所有卡片上强制使用同一分隔线位置、文本偏移或正文宽度公式，尤其是标题或中英混合正文不同时。应按卡片调整分隔线的 x 位置、正文框宽度、图标槽位和标题／正文字号比例，然后用本地裁剪图验证。
• **字号过小防护：**如果适配后的文本只占用可用宽度的一小部分，且看起来明显小于相邻的同级标签，应将其字号提高到接近同级／参考比例。不要因过度纠正溢出问题而导致表格字号偏弱。
• **原生 Alpha 图标素材表：**要求输出原生透明 RGBA，并在裁切前验证 alpha 模式、透明角落、alpha bbox 和主体覆盖范围。保留此 alpha，不要重新着色或执行背景移除处理。
• **通用 N×M 裁切：**使用明确的 columns 和 rows 参数实现网格裁切。验证素材规格数等于 columns * rows，根据这些参数计算单元格边界，绝不要硬编码某个特定网格，例如 5×4 或 4×2。将网格尺寸、源路径、各单元格 bbox 和居中指标保存到素材清单中。
• **按质心居中重新打包：**基于 alpha 裁切后，先裁到 alpha bbox，再将每个素材重新打包到透明正方形画布中，并以 alpha 视觉质心为中心。记录打包后的质心偏移量，并使其接近零。仅按边界框居中并不足够，尤其不适用于目标箭头、人物／星形组合、带光芒的头像、放大镜和宽幅趋势标记等不对称图标。
• **Alpha 图像摆放：**检查每个透明 PNG 的 alpha bbox 和 alpha 质心。按可见 alpha 范围缩放，并将质心对齐到目标槽位中心，然后再摆放完整透明画布。这样可以保留透明安全边距，同时避免缩小或视觉偏移图标。
• **复杂视觉对象的摆放：**当流程带、迁移流、复杂插画、密集 UI 截图或其他复杂图片被分类为 imagegen_asset 时，应将其视为经过设计的视觉图层。在可行时，生成不含可编辑文本的图像，将其清理为真正的 RGBA，然后根据测量得到的可见 alpha 边缘进行摆放。将中心圆、卡片、标签、图例、标注和标签等原生可编辑对象置于其上方。只按对齐所需的语义区域拆分生成素材，例如左侧流和右侧流，而不是按每条细小通道或箭头头部拆分。
• **图标颜色约定：**首轮图像生成提示词必须包含参考图中精确的视觉颜色角色。对于每个素材，记录采样／估算的十六进制颜色，并说明前景描边／填充、内部细节、背景或承载形状颜色，以及该颜色属于图标本身还是其容器。如果网格中的颜色各不相同，请明确指定每个单元格的颜色。素材清单应包含每个图标的预期颜色角色或采样十六进制颜色备注。颜色不匹配的图标属于无效素材，必须重新生成，或在插入 PPT 前替换为颜色正确的图像生成素材衍生版本。
• **按内容网格裁切：**对于生成的素材表，先检测真实的 C×R／N×M 内容网格，再进行裁切。根据原生 alpha 构建前景掩码，在 X 和 Y 轴上投影前景像素，准确检测 C 个列中心和 R 个行中心，再根据相邻中心的中点计算单元格边缘。从检测出的边缘裁切单元格，不要将图像从 (0,0) 开始等分；除非提示词刻意要求生成没有外边距歧义的均匀全幅网格，且检测结果确认无误。如果检测到的中心数量与声明的列数／行数不符，应拒绝该素材表并重新生成。将检测出的中心、边缘、各单元格 bbox 和内边距失败信息保存到素材清单或网格对齐报告中。
• **圆角矩形：**创建 ROUNDED_RECTANGLE 后，设置 shape.adjustments[0]；大型面板使用较小值（0.025-0.04），药丸形元素／按钮使用稍大值（0.06-0.10）。
• **矩形状标题栏规范：**看起来呈矩形的分区标题栏和标题条只能使用原生矩形或圆角矩形。除非参考图明确显示，否则不要添加三角尾部、缎带斜边、箭头形或自由形状楔形等装饰结构。如果名为 ribbon 或类似名称的辅助工具会生成额外顶点，请将其替换为普通原生矩形，并检查局部裁剪图。
• **效果清理：**即使参考图是扁平样式，PowerPoint 形状、图片、图表和连接符也可能继承主题效果。创建每一种形状类别后，除非源图明显需要这些效果，否则都应明确清除阴影、光晕、柔化边缘、倒影和效果列表 XML。保存前执行最终的整页效果清理，然后验证 PPTX XML 中没有意外的 outerShdw、glow、softEdge 或 reflection 节点。
• **线条克制使用：**不要仅因为分隔线、连接线描边或面板边框有助于构建就添加它们。每条线都必须对应参考图中的可见线条，或是必要的原生边界。保守匹配线宽和不透明度；如果线条看起来比截图更深，就降低宽度／颜色，不要接受源图中不存在的视觉网格。
• **工具按钮：**使用原生圆角矩形、add_picture(icon_id, ...) 和 add_text(label, ...) 组合构建每个按钮。根据标签分别调整图标槽位、文本偏移和字号。
• **宽图标槽位：**放大镜、循环、同步、人物循环和含大量箭头的图标通常具有较宽的透明画布或手柄。在紧凑卡片中，为这些图标分配更小或靠左下的槽位，或提供专用变体，确保可见图标和 PPT 选择框都不会与文本冲突。
• **平滑弧形箭头：**使用开放式自由形状曲线时，每条可见弧线都应构建为单一路径，并采用原生线条样式和原生箭头头部，不要使用许多独立线条形状。转换为 PPT 坐标前，先使用较高的内部坐标精度，避免 PowerPoint 的整数路径坐标造成弧线锯齿或阶梯状。可用时优先采用圆角线帽／连接，并在创建后将相关弧线路径组合起来。
• **饼图／圆环图和中心圆规范：**对于饼图／圆环图、径向仪表盘和大型圆形 KPI 节点，先列出可见元素的角色：外环、主填充圆、镂空中心、中心标签、图标和任何实际存在的高光。所有叠加元素都应根据同一测量中心推导。如果源图仅显示外侧描边，应创建无填充描边，不要填充白色。除非参考图中明显存在，否则不要添加装饰性椭圆高光、光晕圆、白色底圆或额外中心圆盘。提供紧凑的中心裁剪图，证明没有多余或偏心圆形。
• **图层顺序检查：**构建并组合后，将形状分类为文本、图像素材和原生对象。遵循 “保留原生内部顺序，只将图标和文本上移” 的原则进行生成。保留原生对象现有的内部顺序，除非需要局部修复特定不匹配；不要将所有原生对象一律移到最底层，因为这可能会让彩色药丸形元素、中心填充或前景线条被白色面板／圆环遮挡。将图像素材／图标置于前方，然后将所有文本框／文本形状置于最前方。将有意组合的原生视觉元素保留为一个对象，但仍置于原生对象图层，图标除外。
• **图标渲染图层安全：**不要以 slide.shapes 枚举结果或对象存在性作为已插入 PNG 图标会显示在卡片上方的证明。PowerPoint 按 ppt/slides/slideN.xml 中形状树的实际顺序渲染；错误的 _spTree.append()、insert_element_before() 或在迭代时修改对象的辅助工具，可能会将 pic 节点放在后续 sp 节点之前，导致图标隐藏在白色卡片下方，而 PPTX 中仍然包含这些图片。优先采用组件内部的创建顺序，而非全局 XML 操作。如果必须全局上移，请先收集稳定的形状引用，用一个经过验证的辅助工具移动它们，然后检查已保存的幻灯片 XML 顺序，并渲染裁剪图证明每个图标在最终槽位中均可见。
• **图标缺失诊断：**如果图标未出现在渲染后的 PPT 中，应先检查 alpha 完整性和 z 顺序，再重新生成素材。确认：PNG 为带有非空 alpha 的 RGBA 格式；图片尺寸非零；pic 节点位于其卡片／容器形状之后，并按预期位于文本之前／上方；本地渲染的裁剪图中能看到图标。如果素材联系表正确，但渲染结果为空白，通常是图层顺序问题。
• **本地裁剪图 QA：**渲染后，使用 PIL 裁切可疑区域并单独检查。幻灯片上有紧凑标签、右侧工具网格或底部反馈栏时，应在最终交付前完成此操作。
• **素材清单证明：**对于每个 imagegen_asset，都应包含其提示词摘要、生成源路径（如有）、最终 PNG 路径，以及任何清理／裁切操作。如果某个素材没有图像生成源，则它不是有效的最终图标／复杂素材。

7. 交付前进行验证
   • 运行随附的辅助工具：

python scripts/check_rebuild_assets.py --asset-dir path/to/assets

• 在声称完成前，打开或检查渲染后的 PNG。
• 写入精简的最终 rebuild_execution_report.json，并确认其中没有未完成的必需阶段；除非最终答复明确将输出标记为草稿并说明缺少的证据。

真实修复经验

• 通过要求生成的网格本身将每个图标完整保留在各自单元格内，避免图标被裁切；随后按已验证的网格单元格裁切，并将内容重新排布到更大的透明画布上。
• 原生透明生成是必需的素材路径。生成后立即验证 RGBA 模式、alpha 边界框、透明角落和非透明主体覆盖范围；在裁切、重新排布和插入过程中保留有效 alpha。
• 裁切图标后，按 alpha 视觉质心居中，而不只是按 alpha 边界框居中。资源管理器缩略图往往会比 PPT 更早暴露这个问题：不对称图标可能通过留白检查，但视觉上仍偏离中心。
• 按质心居中重新排布后，限制粘贴偏移量，确保最终 alpha 边界框仍保留规定的透明边距。较高的箭头和趋势标记可能在视觉上居中，却仍碰到顶部边缘；素材检查器出现 unsafe transparent padding (..., 0, ...) 等失败时，应重新排布素材，而不是缩放 PPT。
• 以实际输入文件尺寸为准，不要依据聊天预览或截图的表观纵横比。使用 PIL 打开源文件，记录 size 和 aspect，并在放置任何内容前根据该比例选择 PowerPoint 页面尺寸。对于 1536×1024 的源文件，使用 12×8 in 的幻灯片可获得清晰的 128 px/in 映射，并避免意外的水平拉伸。
• 网格裁切必须保持通用。使用参数化的 columns × rows / N×M 逻辑；若提供的素材规格数量与网格不匹配，则应失败；不要把先前幻灯片中的 4×2 或 5×4 常量照搬到新任务中。
• 即使提示词要求严格网格，生成的图集往往仍包含外围边距。先检测真实内容中心，再从中心点之间的中点边缘裁切；从图像原点开始简单等分可能会抹掉整个图标或裁切边缘单元格，却仍生成看似合理的联系表。
• 必须在第一次图像生成尝试时指定颜色保真要求。前景色、容器颜色、内部细节颜色或状态颜色不同的素材都应视为不同目标；当参考图为特定素材或状态指定特定颜色时，不要依赖通用图标配色方案。结构看似正确但颜色作用不符的联系表，仍然是失败的素材图集。
• 仅仅称为“生成”并不足够。用脚本绘制的 PNG 仍是手工制作的替代品，不符合本技能对图标和复杂视觉元素的要求。应先使用图像生成模型，再对生成图像进行后处理。
• 素材图集可能会把相邻单元格的碎片带入按钮图标。即使裁切后的素材通过留白检查，也要把多余的底部弧线、点、楔形或局部标记视为真实的网格或裁切失败。修正网格提示词、alpha 连通分量清理或重新裁切逻辑，然后重新渲染实际 PPT 裁切图。
• 生成图标图集中的边缘单元格必须与内部单元格具有相同的安全区域和边距。不要接受存在边缘单元格裁切、溢出或跨单元格重叠的网格图集。
• Windows 资源管理器缩略图可能比 PPT 更早暴露边缘问题。任何缩略图裁切都应视为真实的素材缺陷。
• 普通单箭头、直线连接器和简单折线箭头可以使用原生形状。流动丝带箭头、迁移流、渐变箭头带、多轨道箭头系统和融合箭头流应使用图像生成模型生成透明的复杂视觉素材，然后分层放入 PPTX，同时保留上方的原生文本和周边对象。
• 堆叠或相邻卡片之间的步骤流程箭头不一定是连接线。如果原始箭头是紧凑的实心块状箭头，应使用原生实心箭头形状，并将其放在卡片之间的可见间隙中。不要让箭头端点碰到或藏在下一张卡片的边框下；后创建的卡片形状可能会遮住连接箭头的箭头头部，使其在渲染中看起来像消失了。
• PowerPoint 默认设置可能会将方向敏感的形状反转。应对照参考图检查漏斗各阶段的顶部／底部宽度和倾斜方向；如果内置形状方向错误，应旋转形状或将其重建为可编辑的原生自由形状，而不是接受默认方向。
• 文本适配必须在首次渲染前处理，而不只是估算坐标。根据参考图的层级关系进行预检，然后检查渲染后的 PPT 和局部裁切图。只有在仍能保留与相邻文本相同视觉作用的情况下，才加宽文本框、调整列宽或减小字号。
• PowerPoint 文本通常比简单的像素估算更宽／更高。首次构建失败往往源于根据截图像素猜测字号。写入 PPTX 前，使用 scripts/ppt_text_fit.py，并提供实际导出像素边界框、字体、粗体状态和参考行数。
• 调用 ppt_text_fit.py 意味着要实际运行它并保留精简证据，而不是只凭记忆套用其规则。常规运行只需保留包含 called、notfits、exceptions 和关键长文本示例的精简 text_fit_report.json；只有在修复具体溢出时才展开到逐对象调试。
• 以负号、正号、短横线、箭头、括号或其他符号开头的指标文本是已知的 argparse 陷阱。验证时务必包含有代表性的带符号数值、趋势箭头短语、括号标签以及数字与单位混排的字符串；报告中不得出现来自辅助工具 stderr 的 JSON 解析异常或空 stdout。
• ppt_text_fit.py 必须在 Windows 上输出 UTF-8 JSON。中文、符号和排名字形不应要求每个调用方都设置 PYTHONIOENCODING；辅助工具应自行处理 stdout 编码。
• 文本适配证据也必须覆盖手动运行。混合数字指标和拆分运行的标签是常见溢出源，因为它们绕过了 add_fitted_text()；添加文本运行前，应适配整个可见短语或已声明的子框；如果最终 PPT 中仍有未跟踪的文本生成代码路径，QA 流程必须失败。
• CJK 字体设置必须在 PowerPoint 导出后仍然生效。如果渲染结果显示的是衬线／宋体风格字形，应在运行 XML 中设置 a:latin、a:ea 和 a:cs 字体系列。
• 重复使用的标签／按钮组件需要针对每个标签单独覆盖设置。如果标签混合了英文和中文，应检查局部裁切图，并在最终交付前调整 font_size、text_offset 或宽度。
• PowerPoint 圆角矩形可能会变成过大的胶囊形。务必调整圆角半径，并对大型面板、卡片和小型工具按钮进行渲染检查。
• 矩形分区标题默认不是飘带。如果标题条看起来只是蓝色矩形，应将其构建为原生矩形／圆角矩形；多余的三角尾部是明显缺陷。
• 右侧工具面板应保持可编辑：使用原生圆角按钮、生成的图标 PNG 和独立的文本标签。
• 不要让选择窗格底部留有覆盖整张幻灯片的白色矩形。这通常是把形状用作页面背景导致的；纯色背景应使用原生幻灯片背景填充，以保持可编辑对象列表整洁。
• 淡色装饰圆环很容易堆得过多。如果用户看到多余的灰色圆圈，应减少椭圆数量、提高透明度并清除阴影；只保留参考图中可见的圆环。
• 对于圆形工作流，自由形状弧形箭头可能比连接曲线更贴近参考图，同时仍保持可编辑。每条可见弧线都应是带有自身箭头头部的连续原生弧线／自由形状路径；允许将多个路径编组，但不能用一串短直线段代替。
• 对于圆角虚线反馈回路，应先尝试使用单条可编辑的开放自由形状路径，搭配 PPT 原生虚线样式和原生尾部箭头。这能让选择窗格最整洁，并保留可编辑性。PowerPoint 内置连接器类型只有直线／肘形／曲线；如果回路需要多个弯折，应使用自由形状路径。如果渲染效果不佳，再退回到用于直线段的完整原生虚线连接器和分段肘形连接器。
• 卡片和胶囊形标签应根据几何位置居中，而不是靠视觉巧合。使用完整的胶囊／卡片文本区域，并设置垂直居中锚定，然后渲染局部裁切图；如果文本看起来偏高、偏低或被裁切，应先修正文本框和锚定方式，再更改字号。
• 即使文本溢出边界只有几个像素，也必须视为布局缺陷。对于重复卡片，应分别调整每张卡片的分隔线、正文宽度和混合语言文本字号，而不是把所有同类卡片都缩小。
• 带趋势箭头的密集指标卡片容易出现重叠。应先为箭头预留区域，再仅在剩余文本框中适配标签／数值；如果参考图同一行包含较长百分比、正负号、单位或上／下箭头，务必检查局部裁切图。
• 对于拥挤的数字＋单位 KPI 卡片，如果适配整个短语会导致换行或字号过小，应将视觉短语拆分为明确的可编辑子框，例如数字和单位。使用 ppt_text_fit.py 分别适配每个子框，将它们对齐为同一视觉行，并在 text_fit_report.json 中记录所有子框；对于参考图为单行的指标，不要允许辅助工具输出 line_count: 2。
• 实心趋势箭头是形状，不是文本。文本箭头往往太细，且依赖字体；当源图中的箭头明显较粗时，应使用原生实心箭头形状。
• 实心流程箭头是形状，不是连接器样式。带有 end_arrowhead 的连接器可能会渲染成细线、在卡片边界处丢失三角形箭头头部，或被 Z 轴顺序遮挡。对于卡片之间的垂直／水平流程步骤，应在卡片间隙中单独预留箭头区域，创建实心原生箭头形状，并检查渲染后的局部裁切图。
• 箭头几何保真不只是“朝左／右／上／下”。对于每个紧凑钩形、U 形转弯、反馈、回路或带注释的指示箭头，都要记录其尾部／头部、路径类型、回环侧、描边／填充厚度、边界框和附属标签。原生 U 形转弯形状的默认方向可能出人意料；在选用前，应按目标尺寸渲染全部四种旋转方向。如果没有符合参考图的候选项，应使用一条带箭头头部的连续可编辑自由形状／弧线路径，而不是用直箭头替代或堆叠构造线段。
• 箭头标签局部裁切 QA：附近带有标签的箭头是一个完整的视觉组件。保存紧凑的渲染裁切图，其中包含完整路径、箭头头部、标签和相邻边界；交付前应与对应的参考图裁切图进行比较。不要接受仅流程含义正确、但路径几何或标签锚定位置与源图不符的指示箭头。
• 圆环图、径向图和 KPI 中心叠加元素应根据图表／绘图区中心或圆形边界框计算，而不是凭目测微调。更改图表尺寸、圆环孔尺寸、标注标签或中心节点尺寸后，应从同一坐标来源重新居中叠加圆和文本，并使用紧凑裁切图进行验证。常见缺陷是复用 outer_ring、center_white 或 highlight 等辅助对象，意外多出白色／高亮圆盘；应移除参考图中没有明确显示作用的中心圆。
• 主题效果是造成保真度误判的隐蔽来源。如果源图整体较为扁平，应全局清除默认阴影和效果；细微的 PowerPoint 阴影也可能让卡片、箭头和标题看起来像多余对象。
• 效果检查必须扫描每个 PPTX XML 部件，包括 ppt/theme/theme1.xml，而不只是幻灯片 XML。即使幻灯片形状未明确设置阴影，主题级 outerShdw 节点仍可能存在；应通过正确的 XML 重写或经过验证的正则表达式（例如 <a:outerShdw\b...>）将其移除，然后重新扫描，确认 outerShdw、glow、softEdge 和 reflection 的数量均为零。
• 在 Windows 上，通过 tempfile.mkstemp() 获取文件描述符后，应先关闭它再用 shutil.move 替换 PPTX；否则即使 PowerPoint 并未阻止操作，清理步骤也可能因 WinError 32 而失败。此外，重新构建或覆盖同一个 PPTX 前，应关闭 COM 演示文稿并退出 PowerPoint。
• 多余的构造线是缺陷，不是无伤大雅的装饰。只有当参考图中明显包含分隔线和辅助边框时才保留，并根据渲染裁切图调整线宽／颜色。
• Z 轴顺序也是保真度的一部分。如果 PowerPoint 渲染中有文本或图标看起来被裁切、变暗、隐藏或缺失，应在更改内容前检查幻灯片的实际图层顺序。默认的最终堆叠顺序应为文本、图标／图像、原生容器／箭头／线条，同时保留原生图层自身的内部前景／背景顺序。素材联系表干净还不够；必须通过渲染后的 PPT 局部裁切图证明图标清晰可见。
• 如果输出 PPTX 已打开并被锁定，应使用新的版本化文件名，而不是关闭用户的应用或覆盖其已打开的文件。
• 在 PowerShell 中，对于 *.png 等通配符复制，应使用 Copy-Item -Path；-LiteralPath 不会展开通配符，可能导致 QA 裁切图或最终图标素材未包含在交付物中。

交付内容

返回最终 .pptx 文件的路径，并在生成后提供：

• 渲染后的 PNG 预览。
• 生成的透明图标 PNG 所在的 assets/ 文件夹。
• 资源清单或视觉资产列表。

如有任何限制，请明确说明，尤其是复杂图标为生成的近似版本、而非完美的矢量复刻时。