knight6669/knight-imagetopptx-skill

Knight ImageToPPTX Skill

把图片、图片型 PPTX、PDF 页面复刻成对象级可编辑的 PowerPoint。

Semantic slide rebuilding protocol for Codex · native PPT objects · generated transparent assets · page-by-page visual QA

---

Skill 定位

knight-imagetopptx-skill 是一个面向 Codex 的 图片页转可编辑 PPTX 复刻技能。

它不是“从零生成一份 PPT”的创作模板，也不是“把图片塞进幻灯片”的打包工具。它给 Codex 提供一套可复用的复刻协议：先拆解现有视觉页，再把文本、表格、卡片、箭头、按钮、图标和复杂视觉资产重建为可继续编辑的 PowerPoint 对象。

适合用在这些任务中：

• 将 PNG / JPG / WebP 幻灯片截图复刻为可编辑 PPTX
• 将图片版 PPTX 按页重建为文字、表格、图标可编辑的 PPTX
• 将 PDF 汇报页、扫描页或图片型 PDF 复刻为 PowerPoint
• 复刻中文商务汇报页、政务信息图、流程图、仪表盘和高密度 UI 截图
• 对图标裁切、CJK 字体、局部渲染差异和复杂资产进行强约束 QA

不适合用在这些任务中：

• 从空白内容创作新 deck
• 只需要整页截图作为背景展示
• SVG-only 转换或纯矢量图标库建设
• 不需要对象级编辑能力的简单归档

效果展示

元素可编辑状态

复刻结果保留对象级编辑能力：文本、表格、卡片、按钮、图标和复杂视觉资产都可以在 PowerPoint 中独立选中、移动和二次调整。

核心能力

语义化重建

复刻目标不是像素级截图包裹，而是把页面拆成 PowerPoint 可以继续编辑的对象。

• 文本：原生文本框，保留可改字、可调字体、可移动
• 表格：原生单元格、边框、表头和内容区
• 卡片/面板：原生圆角矩形、边框、阴影和填充
• 流程箭头/连接线：PowerPoint 原生形状或可编辑 freeform
• UI 按钮：按钮背景、图标、文字分层独立可编辑

箭头几何保真

箭头不是只有方向。对非直线箭头，复刻时必须同时保留起点、终点、路径类型、回折侧、线宽或填充厚度，以及与标签的相对关系。

• 粗实心流程箭头使用原生填充箭头形状
• 细线连接使用连接线或连续 freeform 路径
• U 形、弯钩、回流、反馈和注释箭头先记录 tail -> head、straight / elbow / arc / U-turn / hook / loop 等路径类型
• 内置 U 形或弯钩箭头必须在目标尺寸下比较 0° / 90° / 180° / 270° 四种方向；默认方向不能作为最终依据
• 箭头与其附近标签作为一个视觉组件，必须用同一局部裁图对照原图

生图资产约束

图标、pictogram、装饰城市线稿、复杂徽章、tiny glyph、插画片段等最终资产必须来自 image generation model。

脚本只负责后处理：基于原生 alpha 的切片、alpha 重打包、边缘检查和插入 PPT。禁止把 PIL / SVG / canvas / 手写路径 / PowerPoint 形状伪装成最终图标资产。

通用 C×R / N×N 对齐

skill使用通用 C×R 规则网格对齐：

• C = columns，R = rows
• N×N 网格必须使用正方形画布和 N 行 N 列
• 矩形网格必须让画布比例匹配 C:R
• 每个图标居中在自己的 cell center
• 图标限制在 cell 中央 55-65% safe zone
• 每个 cell 内保留至少 20-25% 空白 padding
• 生成结果必须是原生 RGBA：透明角、非空 alpha bbox、主体覆盖均需验证
• 切割使用原生 alpha 前景蒙版，不对已透明资产进行二次透明化处理

切图时先检测真实内容网格，再根据 row/column centers 计算 cell edges，避免从 (0,0) 用 image_width / C 硬切导致图标截断。

CJK 与 PowerPoint 渲染

中文文本不仅设置 run.font.name，还要求在 OOXML 中设置 a:latin、a:ea、a:cs。这样可以减少 PowerPoint 导出时回退到宋体、字号漂移或换行变化的问题。

文本槽与字号保真

ppt_text_fit.py 是溢出预检工具，不是把文字一律缩小的指令。复刻时应先按边框、图标和真实内边距确定完整的可用文本槽，再测量字号。

• 为标题、长单行标签、双行栏头和中英混排短语记录参考字号、行数和可用文字框
• 对高风险文本使用 --target-pt ；工具会返回 required_box_px 与 box_deficit_px
• 出现字号偏小而不溢出时，先扩大文本框、减少重复 margin、调整图标/分隔线/列宽占位，再考虑减小字号
• fits: true 只说明不越界；最终必须以 1:1 渲染裁图检查字高、宽度、基线和参考层级
• 勾选清单、步骤列表等重复组件不能共用固定文字宽高；先锁定图标槽，再逐行分配剩余宽度，并对中英混排长标签记录 reference_scale。同组单行文本若低于参考字高的 90%，必须先修文本槽或卡片几何

多页输入独立复刻

当输入是多张图片、图片版 PPTX 或 PDF 时，每一页都必须按独立单页规格严格复刻。

默认交付方式是：逐页渲染、逐页对比、逐页修正，最后按原始顺序拼接成一个完整的多页可编辑 PPTX。

复刻工作流

Rebuild Protocol

QA Trace

每次高质量复刻建议保留以下证据链：

source page
  -> visual inventory
  -> asset manifest
  -> generated asset sheet
  -> transparent PNG assets
  -> rebuilt PPTX
  -> rendered preview
  -> local crop QA
  -> arrow-label crop QA
  -> corrected final PPTX

这条链路让问题能被定位到具体环节：是生图资产本身截断、切图坐标错误、透明 padding 丢失，还是 PPT 插入和缩放导致的渲染裁切。

图像资产规则

资产联系图

每个复杂图标都作为独立透明 PNG 资产插入 PPT，便于单独替换、缩放和排查边缘裁切问题。

Content-grid cutting

生成式图标网格常见问题：

• 外圈留白导致硬切错位
• edge cell 源图被模型画到边界外
• 相邻 cell 残片混入目标图标
• 原生 alpha 边缘或透明 padding 不符合要求

skill 要求生成网格时就保证每个图标完整落在各自 cell 的 safe zone 内，不截断、不溢出、不跨格；再检测真实内容网格后切割，并输出 grid alignment report。

Native Alpha Validation

生图模型现在直接输出透明 PNG。skill 将原生 alpha 视为资产的一部分，而不是待清理的背景：生成后立即验证 RGBA 模式、四角透明、非空 alpha bbox、主体覆盖和最小透明 padding；验证通过后保留原始 alpha，再按网格切片与视觉质心重打包。

处理规则：

• 验证 PNG 为 RGBA，四角 alpha 为 0，且 alpha bbox 非空
• 用 alpha 前景蒙版检测真实的 C×R / N×M 内容中心和 cell 边界
• 每个 cell 只输出一个语义资产，并保留至少 10 px 透明安全边距
• 按 alpha bbox 和 alpha 视觉质心重打包到透明方形画布

这样能保护抗锯齿边缘，也能减少浅色底块、透明 halo 和不同网格尺寸复用时的切图漂移。

安装

将本仓库放到 Codex skills 目录下：

$env:CODEX_HOME = "$HOME\.codex"
git clone https://github.com/knight6669/knight-imagetopptx-skill "$env:CODEX_HOME\skills\knight-imagetopptx-skill"

或直接把目录放到：

~/.codex/skills/knight-imagetopptx-skill

使用方式

在 Codex 中触发 skill：

[$knight-imagetopptx-skill](./SKILL.md) 复刻这张图片成可编辑 PPTX

可以输入的素材包括：

• 单张 PNG / JPG / WebP 幻灯片截图
• 图片版 PPTX，也就是每页都是截图或整页图片的 PowerPoint
• PDF 页面，例如导出的汇报 PDF、扫描版或图片型 PDF
• 已渲染的 slide page，需要重建为可编辑对象

多页输入规则：

• 每一页都按独立单页复刻，不偷懒套模板
• 每一页都要单独渲染对比和局部裁图检查
• 修正完成后按原始顺序合并成一个 .pptx
• 默认交付一个多页可编辑 PPTX，而不是多个零散 PPTX

示例：

[$knight-imagetopptx-skill](./SKILL.md) 复刻这张图片成可编辑 PPTX

[$knight-imagetopptx-skill](./SKILL.md) 这个 PPTX 是图片版的，请逐页复刻成文字、表格、图标都可编辑的 PPTX

[$knight-imagetopptx-skill](./SKILL.md) 把这个 PDF 里的汇报页复刻成可编辑 PPTX

也可以直接提出类似任务：

把这张中文商务汇报截图复刻成可编辑 PPTX，文字、表格、卡片、箭头都要可编辑，图标独立成透明 PNG。

Skill 设计理念

这个 skill 的目标不是生成一张“像 PPT 的图片”，而是把静态视觉页重建成可继续工作的 PowerPoint 系统。

• 先理解结构，再复刻画面：文本、表格、卡片、箭头、图标和复杂视觉各归其位。
• 复杂资产交给生图模型，版式关系交给原生 PPT 对象，保证观感与可编辑性同时成立。
• 每一页都按独立作品处理：逐页拆解、逐页渲染、逐页校准，再合并成完整 deck。
• 把字体、网格、裁切、图层和渲染 QA 沉淀为流程约束，让复刻结果可复用、可追溯、可迭代。

目录结构

knight-imagetopptx-skill/
├─ SKILL.md
├─ README.md
├─ LICENSE
├─ agents/
├─ scripts/
│  ├─ check_rebuild_assets.py
│  └─ ppt_text_fit.py
└─ assets/
   ├─ skill-banner.svg
   ├─ reference-slide-01.png
   ├─ rebuilt-slide-01.png
   ├─ rebuilt-slide-01.pptx
   ├─ reference-slide-02.png
   ├─ rebuilt-slide-02.png
   ├─ rebuilt-slide-02.pptx
   ├─ editable-elements-01.png
   ├─ editable-elements-02.png
   ├─ comparison.png
   ├─ asset-contact-regenerated-grid.png
   └─ new_sheet_projection_runs.png

质量约束

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

推荐每个复刻项目都保存：

• rendered preview
• comparison/contact sheet
• local crop QA
• asset manifest
• grid alignment report

完成交付前至少检查：

• 图标没有截断、残片、浅色底块和透明边缘污染
• 中文字体没有回退到宋体或发生异常换行
• 表格、卡片、按钮和流程箭头保持可编辑
• 非直线箭头的头向、回折侧、路径、线宽和关联标签均与参考裁图一致
• 多页输入中每一页都有独立渲染校准
• 最终文件是一个完整 .pptx，而不是零散单页文件

Roadmap

Capability Roadmap

Release Intent

关于作者

Knight | 贺 | 持续探索 vibe-coding

许可

MIT License 开源。详见 LICENSE。