Skip to content
Back to search

knight-imagetopptx-skill

Use when Codex must rebuild an existing slide image, screenshot, or image-only PPTX page into an editable .pptx replica, especially Chinese business report slides with editable text, cards, arrows, complex visuals, and independently movable generated image assets.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/knight6669--knight-imagetopptx-skill/badge.svg)](/listings/knight6669--knight-imagetopptx-skill)

HTML

<a href="/listings/knight6669--knight-imagetopptx-skill"><img src="/api/listings/knight6669--knight-imagetopptx-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

将本仓库放到 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 248 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: knight-imagetopptx-skill
  3. description: Use when Codex must rebuild an existing slide image, screenshot, or image-only PPTX page into an editable .pptx replica, especially Chinese business report slides with editable text, cards, arrows, complex visuals, and independently movable generated image assets.
  4. ---
  5. # Knight Image To PPTX
  6. ## Scope
  7. Use this only for **existing visual slides**:
  8. - A PNG/JPG/WebP slide image that must become editable PowerPoint.
  9. - A PPTX whose slides are image-only screenshots or generated full-page images.
  10. - A PDF or multi-page image set where each page must become an editable PowerPoint slide.
  11. - A rendered slide page that needs editable text, containers, arrows, icons, and layout objects.
  12. Do not use this for creating a new deck from scratch, SVG-only conversion, or simple image packaging where the user does not need object-level editing.
  13. ## Core Rule
  14. Rebuild the slide semantically so the parts the user needs to edit are practical PowerPoint objects.
  15. - Text, cards, panels, dividers, lines, simple arrows, bullets, badges, and tables: create as native PowerPoint objects.
  16. - Icons, pictograms, complex badges, decorative marks, tiny UI glyphs, illustration-like elements, complex pictures, and complex visual objects: **must be generated with the image generation model as independent transparent PNG assets**, then inserted into the PPTX.
  17. - Flowing ribbon arrows, migration streams, gradient arrow bands, multi-lane flow arrows, or any arrow system that needs soft fades, bundled curves, overlapping streams, or fused arrowheads is a complex visual object. Generate it separately with the image generation model and stitch it into the PPTX as one or a small number of transparent PNG visual assets; do not rebuild it from many native rectangles, triangles, or curve fragments.
  18. - Source-image crops are reference material only. Do not use cropped screenshot fragments as final icon assets unless the user explicitly provides a real logo/brand mark that must remain exact.
  19. ## Mandatory Execution Contract
  20. When this skill is triggered, the workflow below is binding, not optional guidance. Do not jump directly from screenshot to PPTX, and do not deliver a file unless the required evidence exists.
  21. Before building, track the execution state in memory or local notes. Write `rebuild_execution_report.json` only once near the end as a compact final summary; do not repeatedly rewrite a verbose phase log. The final summary must cover these required phases:
  22. - `input_prepared`: source path, slide/page count, slide size, aspect ratio, and output target recorded.
  23. - `visual_inventory_done`: major text blocks, native objects, connectors, tables, cards, icons, and complex visuals listed with stable IDs.
  24. - `asset_classification_done`: every non-text visual marked as `native_editable` or `imagegen_asset`.
  25. - `imagegen_assets_done`: every `imagegen_asset` has an image-generation source, final transparent PNG, manifest entry, and contact sheet or crop QA.
  26. - `text_fit_done`: every visible PPT text object was checked with `ppt_text_fit.py` or has a recorded exception; the report may be compact.
  27. - `pptx_built`: editable PPTX generated with native text/shapes and independent image assets.
  28. - `render_qa_done`: PPTX rendered to PNG and compared against the reference at full-page level.
  29. - `local_crop_qa_done`: tight regions such as icon buttons, dense cards, tables, labels, bottom bars, and user-flagged areas cropped and inspected.
  30. - `validation_done`: asset checker and relevant script/compile checks run, or blockers recorded.
  31. If any phase cannot be completed, stop and report the blocker instead of silently skipping it. If the user asks for speed or a rough pass, still perform the minimum compact execution summary, asset manifest, rendered preview, and validation; mark the result as draft if QA is intentionally incomplete.
  32. Final answers must include the PPTX path and the most important evidence paths, normally rendered preview, asset contact sheet, compact text-fit report, and notable crop QA. Do not claim completion from code generation alone.
  33. ## Non-Negotiable Image-Generation Gate
  34. **Final icon and complex-visual assets must come from the image generation model.** Do not hand-draw, script-generate, trace, or approximate final icons with PIL, SVG, canvas, icon fonts, manually authored vector paths, or PowerPoint shape drawings. Those methods are allowed only for native editable primitives such as cards, lines, arrows, tables, separators, simple badges, and text containers.
  35. Before rebuilding, classify every non-text visual region:
  36. - `native_editable`: simple geometry that should remain editable in PowerPoint, such as panels, rounded rectangles, ordinary single arrows, table cells, divider lines, small numeric badges, and plain UI containers.
  37. - `imagegen_asset`: icons, pictograms, logos that are not supplied as exact brand files, decorative skylines, illustration fragments, complex badges/seals, screenshots that should become stylized editable-adjacent assets, dense tiny glyph clusters, mascots/people/devices/scenes, complex pictures, flowing ribbon arrows, migration streams, multi-lane gradient arrows, or any visual whose faithful reconstruction would require custom drawing logic.
  38. For every `imagegen_asset`, call the image generation model or reuse an asset that was already produced by that model for this rebuild. Keep the original generated file if the tool saves one, copy it into the working `assets/` folder, then cut/repack/clean it as needed into independent transparent PNGs. Record the generated source path or prompt in the asset manifest.
  39. If the image generation tool is unavailable, blocked, or fails repeatedly, stop and report the blocker. Do not silently replace the required asset with a script-drawn or hand-authored substitute, and do not describe such a substitute as generated.
  40. ## Workflow
  41. 1. **Prepare input**
  42. - Create a working folder beside the source, e.g. `editable-replica-XX/`.
  43. - If the input is image-only PPTX or PDF, render/export each page/slide to PNG first and treat each rendered page as a reference image.
  44. - If the input is multiple images, preserve their order and treat each image as one target slide.
  45. - Record slide size, aspect ratio, source filenames/page numbers, and output path.
  46. - Start tracking the execution phases required by the Mandatory Execution Contract, but write the final `rebuild_execution_report.json` once after validation as a compact summary.
  47. - For multi-page inputs, each page is an independent single-slide rebuild task. Do not build page 2 by copying page 1 and making rough edits unless the visual page is genuinely repeated and the render check confirms it.
  48. 2. **Inventory the page**
  49. - Build a visual inventory: title/subtitle/body text, cards, panels, containers, arrows, connectors, icons, labels, footers, backgrounds.
  50. - Assign stable IDs to every non-text visual asset, e.g. `process_log_parse`, `output_excel_sheet`, `bottom_human_reviewer`.
  51. - Record approximate bounding boxes and target visual size for each asset.
  52. - Mark each non-text visual as either `native_editable` or `imagegen_asset` using the Non-Negotiable Image-Generation Gate above.
  53. - For every arrow or connector that is not a plain straight line, record its stable ID, tail-to-head direction, path class (`straight`, `elbow`, `arc`, `U-turn`, `hook`, `loop`, or `ribbon`), stroke/fill role, approximate bbox, and any attached label. Treat the arrow and its attached label as one visual component for later QA.
  54. 3. **Generate icons and visual assets**
  55. - Use the image generation model for every `imagegen_asset`. Prompt for isolated flat/vector-style assets with no text, no labels, no numbers, no card frame, no shadow unless visible in the reference.
  56. - **Color fidelity is a first-pass requirement.** Before prompting, sample/record every icon's reference colors: foreground stroke/fill, internal detail color, container/host color, and whether the icon is meant to be transparent, monochrome, white-on-color, color-on-white, or multi-color. The first image-generation prompt must state these color roles and approximate hex values per asset or per grid cell. Do not let the model choose a generic palette.
  57. - Treat color role as part of the asset identity. If the reference uses the same pictogram in different colors or states, generate separate color-specific assets or separate grid cells. If the generated asset's color role does not match the reference, mark it invalid and regenerate from the prompt/source sheet before PPT insertion; do not rely on PPT tinting, recoloring, opacity tricks, or later cleanup to repair a wrong first-pass color.
  58. - For complex visual regions, first analyze the semantic target and prompt the model for a clean rebuilt asset, not a pixel crop copy. Keep text outside the image whenever it can be native editable text in PowerPoint.
  59. - For flowing arrows, migration streams, ribbon bands, and other compound arrow visuals, generate the visual object as a transparent PNG asset. Prompt for the exact lane count, direction, color roles, fade behavior, curvature, arrowhead style, and empty center/edge zones needed for later PPT placement. If independent alignment is needed, split the generated source into a small number of semantic transparent assets, such as left-flow and right-flow; avoid fragmenting each lane or arrowhead into separate PPT objects.
  60. - Request genuine transparent background PNGs from the image generation model. Preserve the native alpha channel; generated assets must be RGBA with transparent corners, a non-empty alpha bbox, and plausible subject coverage before cutting or insertion.
  61. - Asset grids are allowed only with explicit `C×R` / `N×M` alignment rules, where `C` or `N` is column count and `R` or `M` is row count. This covers square `N×N` grids and rectangular grids such as `5×4` or `4×2`.
  62. - In the image-generation prompt, state the grid dimensions exactly: `C columns × R rows`, overall canvas ratio `C:R`, equal-size cells, visible or intentionally empty gutters between cells, each icon centered on its own cell center, each icon constrained to the central 55-65% safe zone, and at least 20-25% empty transparent padding inside every cell. Require no clipped edges, no overflow into gutters, and no cross-cell overlap.
  63. - For square `N×N` grids, request a square canvas and `N` equal rows/columns. For rectangular `C×R` / `N×M` grids, request a canvas whose aspect ratio matches the column:row ratio. Edge cells must use the same safe-zone and padding rules as interior cells. Do not hard-code `5×4`, `4×2`, or any specific grid size; pass columns and rows as parameters.
  64. - Validate native-alpha grid outputs before cutting: confirm RGBA mode, transparent corners, a non-empty alpha bbox, and no unexpected opaque background.
  65. - Each cell must be cut into exactly one semantic asset. Avoid mixing multiple icons into one asset.
  66. - Do not trust grid math alone. After cutting an asset grid, remove cross-cell fragments and inspect a contact sheet of the final independent PNGs. If any icon contains stray arcs, dots, wedges, clipped strokes, partial marks from adjacent cells, or edge-cell clipping from the generated sheet itself, treat the grid as invalid and regenerate the grid with stricter safe-zone, gutter, and padding constraints before inserting assets into PPT.
  67. - After cutting, normalize each PNG to a square transparent canvas with generous safety padding. Target: at least 10 px transparent edge padding. Center by alpha visual centroid, not only by the alpha bounding box center; asymmetric icons such as targets, stars, rays, arrows, and magnifiers can look off-center when bbox-centered.
  68. - Store generated source sheets under an `assets/source/` or equivalent source folder and keep the final asset directory limited to independent transparent PNGs that will be inserted into PPT. This prevents source sheets from being mistaken for final assets during QA.
  69. - When inserting into PPT, scale by the asset's non-transparent alpha extent and align by alpha centroid, not by the full transparent canvas. Preserve aspect ratio; do not stretch icons to fill arbitrary target boxes.
  70. 4. **Rebuild the PPTX**
  71. - Use `python-pptx`, PowerPoint automation, or the repo's established PPT tooling.
  72. - Prefer native slide background fill for plain white/off-white pages (`slide.background.fill`) instead of adding a full-slide white rectangle shape. Only use a bottom background rectangle when it carries visible editable decoration that PowerPoint background fill cannot represent.
  73. - Use native PowerPoint text boxes for all readable text. Do not rasterize editable text into images.
  74. - Use native shapes for rounded cards, panels, borders, separator lines, dashed lines, and ordinary arrows.
  75. - Match arrow geometry before choosing the PPT object type: direction, tail/head endpoints, path class, stroke/fill weight, bends or curvature, and label relationship all matter. If the reference shows a thick filled arrow shaft/head between cards or steps, build it as a native filled arrow shape such as `DOWN_ARROW`, `UP_ARROW`, `LEFT_ARROW`, or `RIGHT_ARROW`, not as a connector line with an arrowhead. Use connectors only when the source visually looks like a thin line/connector.
  76. - Compact return, U-turn, hook, feedback, and callout arrows must not be simplified into a straight arrow or a differently directed default shape. Use a single editable open freeform/arc path with native arrowhead when it matches the reference; use a built-in U-turn/hook shape only after rendering candidate rotations (`0`, `90`, `180`, `270`) at the target size and selecting the matching head direction and loop side. Do not approximate a visibly curved return with separate straight fragments unless the reference itself has square segmented geometry.
  77. - For rectangle-like objects such as section headers, title bars, pills, metric cards, tabs, and label strips, use native `RECTANGLE` or `ROUNDED_RECTANGLE` shapes. Do not use ribbon, chevron, triangle, or freeform tail helpers unless the source visibly has a real slanted notch or flag tail.
  78. - Insert generated complex visual assets such as flowing ribbon arrows, dense screenshots, and illustration-like regions as transparent PNGs positioned behind or between native objects according to the reference. Scale by visible alpha bounds and align to measured target edges; keep editable labels, cards, center circles, legends, and callouts as native PPT objects above or around the asset.
  79. - For direction-sensitive native shapes such as funnels, trapezoids, chevrons, arrow wedges, triangular tabs, and slanted badges, do not rely on the default PowerPoint orientation. Compare the rendered direction against the reference and rotate or rebuild with a native freeform path when needed.
  80. - Control PowerPoint rounded rectangles explicitly. `MSO_SHAPE.ROUNDED_RECTANGLE` defaults to huge capsule corners on some aspect ratios; set `shape.adjustments[0]` around `0.025-0.08` and verify in render.
  81. - Use one generated PNG per icon/complex visual, with transparent background and no clipped edges.
  82. - Do not stretch icons. Preserve aspect ratio and center by alpha content box.
  83. - Before writing dense table cells, cards, button labels, mixed Chinese/English labels, and any long title/subtitle, measure the full usable text slot (after reserving borders, icons, and true padding), then run a text-fit preflight. Actually call `scripts/ppt_text_fit.py` with that exported pixel bbox, intended font, bold state, and reference max line count; use its `recommended_pt` as the first build size and save a compact `text_fit_report.json` or equivalent evidence file.
  84. - Text-fit coverage is based on the final visible text, not on whether a helper named `add_fitted_text()` was used. Every code path that creates PowerPoint text must have fit evidence before writing the text: `add_text()`, manual `text_frame` edits, `paragraph.add_run()`, mixed-style number/unit lines, table cells, badges, labels, legends, chart/axis labels, and small UI captions. Hard-coded run sizes are allowed only after fitting the complete visible phrase or each declared sub-box, and the report must name the text object that was fitted.
  85. - Avoid both extremes: do not let text overflow, cross table borders, or force unintended line breaks; also do not shrink text below the visual hierarchy of the reference just to make it fit. If text only fits after becoming visibly too small for its role, treat it as a text-slot geometry defect first: widen the text box into available whitespace, reduce duplicated internal margins, adjust icon/divider/column allocation, or allow the same wrap pattern as the reference. Reducing the font is the final option, not the default repair.
  86. - For Chinese text in `python-pptx`, set the East Asian typeface in OOXML (`a:ea`) as well as `run.font.name`; otherwise PowerPoint may fall back to Songti/serif fonts and shift the layout.
  87. - Treat repeated label/button components as responsive, not fixed. Mixed English+Chinese labels such as `Agents 工作流` often need a smaller font, wider text box, or adjusted text offset compared with pure Chinese labels.
  88. - Build tool/example buttons as native button shapes plus one independent icon PNG plus editable text. Do not bake labels such as `Doc`, `PPT`, `frontend`, `imagegen`, or `GitHub` into the icon image.
  89. - For circular process loops, avoid relying only on curved connectors when the reference uses smooth arc arrows. Use true PowerPoint native arc/arrow objects or high-precision open freeform curve paths. Do not simulate smooth arcs with many separate straight connector segments; visible joints and selection-pane clutter are real defects.
  90. - When an arc loop needs several curved arrows, make each arc segment one continuous editable object and group the segments into one top-level visual object. Name the group descriptively, e.g. `center_cycle_curved_arrows_group`, so the user can move the loop as one object while still being able to ungroup for edits.
  91. - Run a final layer-order pass before rendering. Hard rule: **preserve native internal order; only lift icons and text**. Keep native objects' internal visual order, bring image-generation icon assets above native objects, then bring all text to the top. Shapes must not cover editable text, and icons should not cover labels.
  92. - Prefer building each component in natural visible order: native container/card first, then its icon/image asset, then its editable text. Do not do a blind whole-slide XML reorder when component-local order already gives the correct visual stack.
  93. - After any z-order change, verify the rendered PPT crop, not only the PPTX shape list. A picture can exist in the PPTX and still be hidden behind later native shapes if the physical PowerPoint shape-tree order is wrong.
  94. - Keep faint construction rings and guide circles subtle. Translucent PPT oval strokes stack and can become unwanted gray rings after export; delete ambiguous rings or use very high transparency and clear inherited shadows.
  95. 5. **Render and compare**
  96. - Render the rebuilt PPTX to PNG using PowerPoint export when available.
  97. - Produce a visual preview/contact sheet and compare against the reference.
  98. - Iterate on obvious mismatches: icon clipping, icon size, arrow direction, text wrapping, card borders, alignment, and spacing.
  99. - Crop crowded regions for QA, not only the full slide. Save 1:1 PNG crops for bottom tags, dense cards, circular diagrams, right-side tool panels, feedback bars, compact return/callout arrows, and any selected-object complaints.
  100. - For every compact non-straight arrow or annotated callout, compare the rendered crop against the same reference crop. Verify the head direction, path/loop side, line or fill thickness, endpoints, and label position as one unit. Fix a mismatch before delivery even when the broader flow direction is semantically correct.
  101. - For every tight icon slot, especially button/tool/UI icons, render a 1:1 local crop of the inserted PPT region. Asset thumbnails are not enough: verify the final rendered PPT does not show clipped edges, stray fragments, or adjacent-cell debris.
  102. - For multi-page inputs, render and compare every rebuilt slide against its own source page. Fix mismatches page-by-page before final delivery.
  103. 6. **Assemble multi-page output**
  104. - For multiple source images/pages, append all independently rebuilt slides into one `.pptx` in the original order.
  105. - Keep per-page assets, manifests, rendered previews, and QA crops traceable by slide/page number.
  106. - Do not deliver separate PPTX files unless the user explicitly asks; the default deliverable is one combined editable PPTX.
  107. ## Implementation Patterns
  108. - **CJK font XML:** after setting `run.font.name`, also set `a:latin`, `a:ea`, and `a:cs` `typeface` on the run XML. Use this for every Chinese text run.
  109. - **Text-fit preflight:** for every dense table cell, card title/body, subtitle, button label, and icon-adjacent label, estimate text width/height before generating the PPTX. Prefer the bundled helper:
  110. ```bash
  111. python scripts/ppt_text_fit.py --text="升级方向不是少做事,而是更会定义、拆解、验收和复盘。" \
  112. --box 980x42 --font "Microsoft YaHei" --max-pt 22 --min-pt 12 --max-lines 1
  113. ```
  114. Use the returned `recommended_pt` and `lines` to set the first PPT build. For any high-risk title or mixed-language label, also pass `--target-pt <reference-size>`: the report then returns `required_box_px` and `box_deficit_px`, making it explicit whether the correct repair is a wider/taller text box rather than a smaller font. Keep the final `text_fit_report.json` compact: record `called`, `notfits`, `exceptions`, and representative high-risk long texts with their reference size and box deficit. Do not write every successful short-label fit by default; keep full per-shape details only in temporary debug data when actively diagnosing a failure. The helper uses Windows font files, slide export scale, visible glyph bounding boxes, CJK-aware wrapping, binary search, safety margins, robust argparse handling for leading-minus text, and forced UTF-8 stdout for Chinese/symbol JSON output. If the helper is unavailable, use PIL `ImageFont.truetype()` with Microsoft YaHei/SimHei/Arial and the same logic; only fall back to rough CJK estimates as a last resort. Do not use raw font ascent+descent as the only line-height estimate; it over-counts invisible YaHei padding and makes labels too small.
  115. - **Text argument safety:** when calling `ppt_text_fit.py` from Python or shell, pass text as `--text=<value>` instead of `--text <value>`. This prevents values that begin with minus signs, plus signs, dash variants, arrows, parentheses, or symbol-heavy metric prefixes from being misread as command options. If a wrapper constructs subprocess arguments, build `f"--text={text}"` as one argv item.
  116. - **Strict text-fit coverage:** do not restrict fitting to a single wrapper such as `add_fitted_text()`. Treat every text-producing operation as in scope, including `add_run()` branches, direct `shape.text_frame` edits, table cell text, manually composed numeric metrics, badge labels, split title/body runs, chart labels, and footer notes. For mixed-size metric lines such as number+unit, English acronym+number+unit, signed value+unit, or value+trend-symbol combinations, fit the full visible phrase against the whole bbox first, then derive number/unit run sizes from that fitted base size or fit the number and unit in explicit sub-boxes. Track coverage internally while building. The final compact `text_fit_report.json` should include `called`, `notfits`, `exceptions`, and representative `key_long_texts`; only failed, exceptional, or high-risk long text needs per-object detail.
  117. - **Manual run exception discipline:** if a tiny decorative label, page number, or intentionally fixed-size badge truly cannot use `ppt_text_fit.py`, record it under `exceptions` in the compact report with its bbox and reason, then verify it with a local render crop. Unreported hard-coded text sizes are a defect.
  118. - **Reference line-count lock:** derive the target max line count from the source image before fitting. One-line source labels must be fitted as one line; two-line source titles must remain two lines. Do not insert manual line breaks that create more lines than the reference unless the source visibly does so.
  119. - **PPT point-to-pixel scale:** calculate from the actual export setup, not from memory. For 1672 px wide output on a 13.333333 in slide, `px_per_pt = (1672 / 13.333333) / 72 ~= 1.742`; the helper applies this scale plus a render fudge. If using a different slide size or export width, pass `--slide-px` and `--slide-in`.
  120. - **Role text hierarchy:** keep font sizes flexible and derived from the reference page, not fixed numeric ranges. Preserve the relative hierarchy between title, subtitle, card titles, table headers, table body, tool names, labels, and notes. If text only fits by becoming visibly weaker than peer text in the same role, adjust geometry, margins, columns, or wrapping instead of silently accepting tiny text.
  121. - **Text-slot geometry lock:** treat a text box as the full editable slot available to that phrase, not the dark-pixel bbox of the source glyphs. Record the reference point size and inspect `target_required_box_px` / `target_box_deficit_px` for every title, long single-line label, and mixed CJK/Latin phrase. A low `reference_scale` means the box, icon reservation, or margins must be repaired before accepting a smaller point size. Preserve the source's visual text height through a render crop; `fits: true` alone is insufficient.
  122. - **Peer checklist parity:** never run every checklist row through one fixed `text_w × text_h` helper. Reserve the icon first, then allocate the remaining card width per row; long CJK/Latin identifiers often need a wider box, smaller duplicated margin, and an explicit reference point size. For each one-line checklist row, report `reference_scale`; if it falls below `0.90`, repair the row slot or card geometry and compare a crop against neighboring rows before accepting the result. A long identifier may be modestly smaller only when the source visibly does the same.
  123. - **Overflow guards:** table body text should stay inside its own cell with at least 10-16 px visual padding from vertical grid lines. Card text should reserve icon space first, then fit only in the remaining text area. For one-line reference labels, do not allow accidental wrapping; for multi-line reference labels, match the observed line count and line spacing. Treat mixed CJK/Latin labels such as `看 diff、看运行结果` as wider than CJK-only text and give them extra width or a smaller role-consistent size before rendering.
  124. - **Card text centering:** for pills, buttons, workflow cards, and icon+label cards, align the text box to the full intended visual slot and set vertical anchoring to middle (`MSO_ANCHOR.MIDDLE` or equivalent). Do not place a smaller text box by eyeballing baseline position. Card body text should be vertically centered within its reserved area when the reference is centered, with line count and line spacing matching the reference.
  125. - **Reserved trend/arrow slots:** for compact metric rows that combine a label, signed value, unit, and trend arrow/icon, divide the row into explicit label, value, and arrow/icon slots before fitting text. The fitted text bbox must exclude the arrow slot; the arrow should be anchored inside its own reserved slot with enough padding from the card edge. Do not place trend arrows by absolute x-offsets that can overlap longer percentages or mixed number/unit runs. Render a local crop for these dense rows before delivery.
  126. - **Trend arrow shape fidelity:** if the reference shows a thick trend arrow with a filled shaft and triangular head, build it as a native PowerPoint arrow shape such as `UP_ARROW` or `DOWN_ARROW`, not as a text glyph, thin connector, or line with arrowhead. Reserve a separate arrow slot and keep the metric text editable beside it.
  127. - **Responsive card layout:** repeated cards may need per-card geometry overrides. Do not force one divider position, text offset, or body width formula across all cards when titles or mixed Chinese/English body text differ. Adjust divider x-position, body box width, icon slot, and title/body font scale per card, then verify with local crops.
  128. - **Undersize guards:** if fitted text uses little of the available width and looks visibly smaller than neighboring peer labels, raise it toward the peer/reference scale. Avoid overcorrecting from overflow into a weak, under-scaled table.
  129. - **Native-alpha icon sheets:** request native transparent RGBA output and validate alpha mode, transparent corners, alpha bbox, and subject coverage before cutting. Preserve this alpha without recoloring or background-removal processing.
  130. - **Generic `N×M` cutting:** implement grid cutting with explicit `columns` and `rows` parameters. Validate that the asset spec count equals `columns * rows`, compute cell bounds from these parameters, and never hard-code a specific grid such as `5×4` or `4×2`. Save grid dimensions, source path, per-cell bbox, and centering metrics to the asset manifest.
  131. - **Centroid-centered repacking:** after alpha-based cutting, crop to the alpha bbox, then repack each asset into a square transparent canvas using the alpha visual centroid as the center. Record post-pack centroid delta and keep it near zero. Bounding-box centering alone is insufficient for asymmetric icons such as target arrows, people/star groups, heads with rays, magnifiers, and wide trend marks.
  132. - **Alpha image placement:** inspect each transparent PNG's alpha bbox and alpha centroid. Scale by visible alpha extent and align the centroid to the target slot center, then place the full transparent canvas accordingly. This keeps transparent safety padding without shrinking or visually offsetting icons.
  133. - **Complex visual object placement:** when a flow ribbon, migration stream, complex illustration, dense UI screenshot, or other complex picture is classified as `imagegen_asset`, treat it as a designed visual layer. Generate it without editable text where possible, clean it into true RGBA, then place it by measured visible-alpha edges. Keep native editable objects such as center circles, cards, tags, legends, callouts, and labels above it. Split the generated source only by semantic region needed for alignment, e.g. left stream and right stream, not by every small lane or arrowhead.
  134. - **Icon color contract:** first-pass image-generation prompts must include exact visual color roles from the reference. For each asset, record sampled/estimated hex colors and specify foreground stroke/fill, internal details, background or host shape color, and whether the color belongs to the icon itself or its container. If a grid mixes colors, specify each cell's colors explicitly. The asset manifest should include the intended color role or sampled hex notes for every icon. A color-mismatched icon is an invalid asset and should be regenerated or replaced by a correctly colored image-generation-derived variant before PPT insertion.
  135. - **Content-grid cutting:** for generated asset sheets, first detect the real `C×R` / `N×M` content grid before cutting. Build the foreground mask from native alpha, project foreground pixels on X and Y, detect exactly `C` column centers and `R` row centers, then compute cell edges from adjacent center midpoints. Cut cells from these detected edges, not from `(0,0)` equal image division, unless the prompt deliberately produced a full-sheet uniform grid with no outer margin ambiguity and detection confirms it. If the detected center count does not match the declared columns/rows, reject the sheet and regenerate. Save detected centers, edges, per-cell bbox, and padding failures to the asset manifest or grid alignment report.
  136. - **Rounded rectangles:** after creating `ROUNDED_RECTANGLE`, set `shape.adjustments[0]`; use smaller values for large panels (`0.025-0.04`) and slightly larger values for pills/buttons (`0.06-0.10`).
  137. - **Rectangle-like header discipline:** section headers and title bars that read as rectangular should be native rectangles or rounded rectangles only. Avoid adding triangle tails, ribbon slants, chevrons, or freeform wedges as decorative construction unless the reference clearly shows them. If a helper named `ribbon` or similar creates extra points, replace it with a plain native rectangle and verify the local crop.
  138. - **Effect hygiene:** PowerPoint shapes, pictures, charts, and connectors can inherit theme effects even when the reference is flat. After creating every shape class, explicitly clear shadow, glow, soft-edge, reflection, and effect-list XML unless the source visibly requires that effect. Run a final slide-level effect cleanup before saving, then verify the PPTX XML has no unexpected `outerShdw`, `glow`, `softEdge`, or `reflection` nodes.
  139. - **Line restraint:** do not add divider lines, connector strokes, or panel borders just because they help construction. Every line must correspond to a visible reference line or a needed native boundary. Match line weight and opacity conservatively; if a line reads as darker than the screenshot, reduce width/color instead of accepting a visual grid that was not in the source.
  140. - **Tool buttons:** compose each button from a native rounded rectangle, `add_picture(icon_id, ...)`, and `add_text(label, ...)`. Tune icon slot, text offset, and font size per label.
  141. - **Wide icon slots:** magnifier, loop, sync, person-loop, and arrow-heavy icons often have a much wider transparent canvas or handle than square symbols. In tight cards, give these icons smaller/lower-left slots or a dedicated variant so both the visible icon and the PPT selection box stay clear of text.
  142. - **Smooth arc arrows:** when using open freeform curves, build each visible arc as one path with native line styling and native arrowhead, not many separate line shapes. Use a high internal coordinate scale before converting to PPT coordinates so PowerPoint's integer path coordinates do not create jagged or stepped arcs. Prefer rounded line caps/joins when available, and group related arc paths after creation.
  143. - **Pie/doughnut and center-circle discipline:** for pie/doughnut charts, radial dashboards, and large circular KPI nodes, first list the visible roles: outer ring, main fill circle, hollow center, center label, icon, and any real highlight. Derive every overlay from the same measured center. If the source only shows an outer stroke, create it as no-fill stroke; do not fill it with white. Do not add decorative highlight ovals, glow circles, white backing circles, or extra center disks unless they are visibly present in the reference. Include a tight center crop proving there is no stray or off-center circle.
  144. - **Layer-order pass:** after building and grouping, classify shapes into text, image assets, and native objects. Generate with the principle **"preserve native internal order, only lift icons and text"**. Preserve the existing internal order of native objects unless a specific mismatch requires a local fix; do not blindly send every native object to the back, because this can hide colored pills, center fills, or foreground lines behind white panels/rings. Bring image assets/icons forward, then bring all text boxes/text shapes to the very front. Preserve intentionally grouped native visuals as one object, but keep them in the native-object layer unless they are icons.
  145. - **Icon render-layer safety:** do not trust `slide.shapes` enumeration or object existence as proof that inserted PNG icons will render above cards. PowerPoint renders by the physical shape-tree order in `ppt/slides/slideN.xml`; a mistaken `_spTree.append()`, `insert_element_before()`, or mutation-while-iterating helper can place `pic` nodes before later `sp` nodes, making icons disappear behind white cards while the PPTX still contains the pictures. Prefer component-local creation order over global XML surgery. If a global lift is necessary, collect stable shape references first, move them with one vetted helper, then inspect the saved slide XML order and render a crop proving each icon is visible in its final slot.
  146. - **Missing-icon diagnosis:** when icons do not appear in the rendered PPT, check alpha integrity and z-order before regenerating assets. Confirm: the PNG is RGBA with non-empty alpha, the picture dimensions are non-zero, the `pic` node is after its card/container shape and before/top of text as intended, and a local rendered crop shows the icon. If the asset contact sheet is correct but the render is blank, it is usually a layer-order problem.
  147. - **Local crop QA:** after rendering, crop suspicious regions with PIL and inspect them separately. Do this before final delivery when a slide has tight labels, right-side tool grids, or bottom feedback bars.
  148. - **Asset manifest proof:** include for every `imagegen_asset` its prompt summary, generated source path when available, final PNG path, and any cleanup/cutting operation. If an asset has no image-generation source, it is not a valid final icon/complex asset.
  149. 7. **Validate before delivery**
  150. - Run the bundled helper:
  151. ```bash
  152. python scripts/check_rebuild_assets.py --asset-dir path/to/assets
  153. ```
  154. - Open or inspect the rendered PNG before claiming completion.
  155. - Write the compact final `rebuild_execution_report.json` once, and confirm it has no incomplete required phase unless the final answer explicitly labels the output as a draft and explains the missing evidence.
  156. ## Lessons From Real Repairs
  157. - Prevent icon clipping by requiring the generated grid itself to keep every icon fully inside its own cell, then cut by verified grid cells and repack content into a larger transparent canvas.
  158. - Native transparent generation is the required asset path. Validate RGBA mode, alpha bbox, transparent corners, and non-transparent subject coverage immediately after generation; preserve valid alpha throughout cutting, repacking, and insertion.
  159. - After cutting icons, center by alpha visual centroid, not just by the alpha bbox. Explorer thumbnails often expose this issue before PPT: asymmetric icons can pass padding checks while still looking visually off-center.
  160. - After centroid-centered repacking, clamp the paste offset so the final alpha bbox still keeps the required transparent edge padding. Tall arrows and trend marks can be visually centered yet still touch the top edge; asset checker failures such as `unsafe transparent padding (..., 0, ...)` require repacking, not PPT scaling.
  161. - Trust the actual input file dimensions, not the chat preview or apparent screenshot aspect. Open the source with PIL, record `size` and `aspect`, and choose the PowerPoint page size from that ratio before placing anything. For a `1536×1024` source, a `12×8 in` slide gives a clean `128 px/in` mapping and avoids accidental horizontal stretching.
  162. - Grid cutting must stay generic. Use parameterized `columns × rows` / `N×M` logic and fail if the provided asset spec count does not match the grid; do not copy a previous slide's `4×2` or `5×4` constants into a new task.
  163. - Generated sheets often contain outer margins even when the prompt asks for a strict grid. Detect the real content centers first, then cut from center-midpoint edges; naive equal slicing from the image origin can erase whole icons or clip edge cells while still producing a plausible contact sheet.
  164. - Color fidelity must be specified during the first image-generation attempt. Assets with different foreground colors, container colors, internal detail colors, or state colors should be treated as distinct targets; do not rely on a generic icon palette when the reference assigns specific colors to specific assets or states. A contact sheet that looks structurally correct but uses the wrong color role is still a failed asset sheet.
  165. - The word "generated" is not enough. A script-drawn PNG is still a hand-authored substitute and violates this skill for icons and complex visuals. Use the image generation model first, then post-process the generated image.
  166. - Asset sheets can leak adjacent-cell fragments into button icons. Treat stray bottom arcs, dots, wedges, or partial marks as a real grid/cutting failure even if the cut asset passes padding checks. Fix the grid prompt, alpha-component cleanup, or recutting logic, then re-render the actual PPT crop.
  167. - Edge cells in a generated icon sheet must have the same safe-zone and padding as interior cells. Do not accept a grid sheet with edge-cell clipping, overflow, or cross-cell overlap.
  168. - Windows Explorer thumbnails may expose edge problems sooner than PPT. Treat any thumbnail clipping as a real asset bug.
  169. - Ordinary single arrows, straight connectors, and simple chevrons can stay native. Flowing ribbon arrows, migration streams, gradient arrow bands, multi-lane arrow systems, and fused arrowhead streams should be generated with the image generation model as transparent complex visual assets, then layered into the PPTX with native text and surrounding objects preserved above them.
  170. - Step-flow arrows between stacked or adjacent cards are not automatically connector lines. If the original arrow is a compact filled block arrow, use a native filled arrow shape and place it in the visible gap between cards. Do not let the arrow endpoint touch or hide under the next card border; later-created card shapes can cover connector arrowheads and make the arrow look missing in the render.
  171. - Direction-sensitive shapes can be visually reversed by PowerPoint defaults. Funnel stages should be checked against the reference for top/bottom width and slant direction; if the built-in shape points the wrong way, rotate it or rebuild it as an editable native freeform instead of accepting the default.
  172. - Text fitting must be handled before first render, not only by approximate coordinates. Use a preflight fit guided by the reference hierarchy, then check the rendered PPT and local crops. Widen boxes, adjust columns, or reduce font size only when it still preserves the same visual role as neighboring text.
  173. - PowerPoint text is usually wider/taller than a naive pixel guess. First-build failures often come from guessing font sizes from screenshot pixels. Use `scripts/ppt_text_fit.py` with the real exported pixel bbox, font, bold state, and reference line count before writing the PPTX.
  174. - Calling `ppt_text_fit.py` means actually executing it and preserving compact evidence, not merely applying its rule by memory. A slim `text_fit_report.json` with `called`, `notfits`, `exceptions`, and key long-text samples is enough for routine runs; expand to per-object debug only when fixing a concrete overflow.
  175. - Leading-minus, leading-plus, dash-leading, arrow-leading, parenthesis-leading, and other symbol-leading metric text is a known argparse trap. Always include representative signed values, trend-arrow phrases, parenthesized labels, and mixed number/unit strings during verification; the report must not contain JSON parse exceptions from helper stderr or empty stdout.
  176. - `ppt_text_fit.py` must emit UTF-8 JSON on Windows. Chinese text, symbols, and ranking glyphs should not require every caller to set `PYTHONIOENCODING`; the helper owns its stdout encoding.
  177. - Text-fit evidence must cover manual runs too. Mixed numeric metrics and split-run labels are common overflow sources because they bypass `add_fitted_text()`; fit the whole visible phrase or declared sub-boxes before adding runs, and fail the QA pass if the final PPT contains untracked text-producing code paths.
  178. - CJK font assignment must survive PowerPoint export. If the render shows serif/Songti-like glyphs, set `a:latin`, `a:ea`, and `a:cs` typefaces in the run XML.
  179. - Reused tag/button components need per-label overrides. If a label mixes English and Chinese, test a local crop and tune `font_size`, `text_offset`, or width before final delivery.
  180. - PowerPoint rounded rectangles can turn into oversized capsules. Always adjust corner radius and render-check large panels, cards, and small tool buttons.
  181. - Rectangular section headers are not ribbons by default. If a title strip only looks like a blue rectangle, build it as a native rectangle/rounded rectangle; extra triangular tails are visible defects.
  182. - Right-side tool panels should stay editable: native rounded buttons, generated icon PNGs, and separate text labels.
  183. - Avoid leaving a full-slide white rectangle at the bottom of the selection pane. It usually comes from using a shape as the page background; use native slide background fill for plain backgrounds so the editable object list stays clean.
  184. - Faint decorative rings are easy to overbuild. If the user sees extra gray circles, reduce the number of ellipses, increase transparency, and clear shadows; keep only rings visible in the reference.
  185. - For circular workflows, freeform arc arrows can match the reference better than connector curves while staying editable. Each visible arc should be a continuous native arc/freeform path with its own arrowhead; a grouped set of paths is acceptable, but a stack of short straight segments is not.
  186. - For rounded dashed feedback loops, first try a single editable open freeform path with PPT native dashed line styling and a native tail arrow. This gives the cleanest selection pane and preserves editability. PowerPoint's built-in connector types are only straight/elbow/curve, so use a freeform path when the loop needs multiple bends. If that renders poorly, fall back to whole native dashed connectors for straight runs and segmented elbows only.
  187. - Card and pill labels should be centered by geometry, not by visual luck. Use the full pill/card text slot with middle vertical anchoring, then render a crop; if the text appears high/low or clipped, fix the text box and anchoring before changing font size.
  188. - Text overflow must be treated as a layout bug, even if it is only a few pixels beyond a card border. For repeated cards, tune each card's divider, body width, and mixed-language text size independently rather than shrinking every peer card.
  189. - Dense metric cards with trend arrows are overlap-prone. Reserve an arrow slot first, fit the label/value only in the remaining text box, and check a crop whenever the reference has long percentages, signs, units, or up/down arrows in the same row.
  190. - For cramped number+unit KPI cards, if fitting the whole phrase would force a wrap or a tiny font, split the visual phrase into explicit editable sub-boxes such as number and unit. Fit each sub-box with `ppt_text_fit.py`, align them as one visual line, and record both sub-boxes in `text_fit_report.json`; do not allow helper output like `line_count: 2` for a one-line reference metric.
  191. - Filled trend arrows are shapes, not text. Text arrows often render too thin and font-dependent; use native filled arrow shapes when the source arrow is visibly thick.
  192. - Filled process arrows are shapes, not connector styling. A connector with `end_arrowhead` may render as a thin line, lose the triangular head at card boundaries, or be hidden by z-order. For card-to-card vertical/horizontal process steps, reserve a separate arrow slot in the inter-card gap, create a filled native arrow shape, and verify the rendered crop.
  193. - Arrow geometry fidelity is more than “points left/right/up/down.” For every compact hook, U-turn, feedback, loop, or annotated callout arrow, inventory its tail/head, path class, loop side, stroke/fill thickness, bbox, and attached label. A native U-turn shape may have a surprising default orientation; render all four rotations at the intended size before selecting it. If no candidate matches the reference, use one continuous editable freeform/arc path with an arrowhead, not a straight-arrow substitute or a stack of construction segments.
  194. - Arrow-label crop QA: an arrow that has a nearby label is a single visual component. Save a tight rendered crop containing the full path, arrowhead, label, and adjacent boundary; compare it against the equivalent reference crop before delivery. Do not accept a callout whose flow meaning is correct but whose path geometry or label anchoring differs from the source.
  195. - Doughnut, radial, and KPI center overlays should be computed from the chart/plot center or circle bbox, not nudged by eye. After changing chart size, hole size, callout labels, or center-node size, re-center the overlay circle and text from the same coordinate source and verify with a tight crop. A common defect is an unintended extra white/highlight disk from a reused helper such as `outer_ring`, `center_white`, or `highlight`; remove any center circle whose role is not explicitly visible in the reference.
  196. - Theme effects are a hidden source of false fidelity. If the source is mostly flat, clear default shadows and effects globally; a subtle PowerPoint shadow can make cards, arrows, and headers look like extra objects.
  197. - Effect checks must scan every PPTX XML part, including `ppt/theme/theme1.xml`, not only slide XML. Theme-level `outerShdw` nodes can survive even when no slide shape explicitly has a shadow; remove them with a correct XML rewrite or a verified regex such as `<a:outerShdw\b...>`, then re-scan for `outerShdw`, `glow`, `softEdge`, and `reflection` counts of zero.
  198. - On Windows, close any file descriptor returned by `tempfile.mkstemp()` before replacing a PPTX with `shutil.move`; otherwise the cleanup step can fail with `WinError 32` even when PowerPoint is not the blocker. Also close the COM presentation and quit PowerPoint before rebuilding or overwriting the same PPTX.
  199. - Extra construction lines are defects, not harmless decoration. Keep separators and helper borders only when the reference visibly contains them, and tune weight/color from a rendered crop.
  200. - Z-order is part of fidelity. If text or icons seem clipped, dim, hidden, or missing from the PowerPoint render, inspect the physical slide layer order before changing content. The default final stack should be text, then icons/images, then native containers/arrows/lines, while preserving the native layer's own internal foreground/background order. A clean asset contact sheet is not enough; icon visibility must be proven by the rendered PPT crop.
  201. - When an output PPTX is open and locked, write a new versioned filename instead of killing the user's app or overwriting their open file.
  202. - In PowerShell, use `Copy-Item -Path` for wildcard copies such as `*.png`; `-LiteralPath` does not expand wildcards and can leave QA crops or final icon assets out of the deliverables.
  203. ## Deliverables
  204. Return the final `.pptx` path plus, when produced:
  205. - Rendered PNG preview.
  206. - `assets/` folder of generated transparent icon PNGs.
  207. - Asset manifest or visual inventory.
  208. Mention any remaining limitation plainly, especially if a complex icon is a generated approximation rather than a perfect vector recreation.
README.md · README · 337 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/skill-banner.svg" alt="Knight ImageToPPTX Skill banner" width="100%" />
  3. </p>
  4. <h1 align="center">Knight ImageToPPTX Skill</h1>
  5. <p align="center">
  6. <strong>把图片、图片型 PPTX、PDF 页面复刻成对象级可编辑的 PowerPoint。</strong>
  7. </p>
  8. <p align="center">
  9. <a href="#skill-定位"><img alt="Codex Skill" src="https://img.shields.io/badge/Codex-Skill-0052C4?style=for-the-badge" /></a>
  10. <a href="#图像资产规则"><img alt="ImageGen Assets" src="https://img.shields.io/badge/Assets-ImageGen%20PNG-111827?style=for-the-badge" /></a>
  11. <a href="#质量约束"><img alt="Render QA" src="https://img.shields.io/badge/QA-Render%20First-0F766E?style=for-the-badge" /></a>
  12. <a href="#许可"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge" /></a>
  13. </p>
  14. <p align="center">
  15. <sub>Semantic slide rebuilding protocol for Codex · native PPT objects · generated transparent assets · page-by-page visual QA</sub>
  16. </p>
  17. ---
  18. ## Skill 定位
  19. `knight-imagetopptx-skill` 是一个面向 Codex 的 **图片页转可编辑 PPTX 复刻技能**。
  20. 它不是“从零生成一份 PPT”的创作模板,也不是“把图片塞进幻灯片”的打包工具。它给 Codex 提供一套可复用的复刻协议:先拆解现有视觉页,再把文本、表格、卡片、箭头、按钮、图标和复杂视觉资产重建为可继续编辑的 PowerPoint 对象。
  21. 适合用在这些任务中:
  22. - 将 PNG / JPG / WebP 幻灯片截图复刻为可编辑 PPTX
  23. - 将图片版 PPTX 按页重建为文字、表格、图标可编辑的 PPTX
  24. - 将 PDF 汇报页、扫描页或图片型 PDF 复刻为 PowerPoint
  25. - 复刻中文商务汇报页、政务信息图、流程图、仪表盘和高密度 UI 截图
  26. - 对图标裁切、CJK 字体、局部渲染差异和复杂资产进行强约束 QA
  27. 不适合用在这些任务中:
  28. - 从空白内容创作新 deck
  29. - 只需要整页截图作为背景展示
  30. - SVG-only 转换或纯矢量图标库建设
  31. - 不需要对象级编辑能力的简单归档
  32. ## 效果展示
  33. | 原图 | 可编辑复刻效果 |
  34. | --- | --- |
  35. | <img src="assets/reference-slide-01.png" alt="Source slide 1" /> | <img src="assets/rebuilt-slide-01.png" alt="Rebuilt editable PPT effect 1" /> |
  36. | <img src="assets/reference-slide-02.png" alt="Source slide 2" /> | <img src="assets/rebuilt-slide-02.png" alt="Rebuilt editable PPT effect 2" /> |
  37. ### 元素可编辑状态
  38. 复刻结果保留对象级编辑能力:文本、表格、卡片、按钮、图标和复杂视觉资产都可以在 PowerPoint 中独立选中、移动和二次调整。
  39. | 可编辑状态 1 | 可编辑状态 2 |
  40. | --- | --- |
  41. | <img src="assets/editable-elements-01.png" alt="Editable element state screenshot 1" /> | <img src="assets/editable-elements-02.png" alt="Editable element state screenshot 2" /> |
  42. ## 核心能力
  43. ### 语义化重建
  44. 复刻目标不是像素级截图包裹,而是把页面拆成 PowerPoint 可以继续编辑的对象。
  45. - 文本:原生文本框,保留可改字、可调字体、可移动
  46. - 表格:原生单元格、边框、表头和内容区
  47. - 卡片/面板:原生圆角矩形、边框、阴影和填充
  48. - 流程箭头/连接线:PowerPoint 原生形状或可编辑 freeform
  49. - UI 按钮:按钮背景、图标、文字分层独立可编辑
  50. ### 箭头几何保真
  51. 箭头不是只有方向。对非直线箭头,复刻时必须同时保留起点、终点、路径类型、回折侧、线宽或填充厚度,以及与标签的相对关系。
  52. - 粗实心流程箭头使用原生填充箭头形状
  53. - 细线连接使用连接线或连续 freeform 路径
  54. - U 形、弯钩、回流、反馈和注释箭头先记录 `tail -> head`、`straight / elbow / arc / U-turn / hook / loop` 等路径类型
  55. - 内置 U 形或弯钩箭头必须在目标尺寸下比较 `0° / 90° / 180° / 270°` 四种方向;默认方向不能作为最终依据
  56. - 箭头与其附近标签作为一个视觉组件,必须用同一局部裁图对照原图
  57. ### 生图资产约束
  58. 图标、pictogram、装饰城市线稿、复杂徽章、tiny glyph、插画片段等最终资产必须来自 image generation model。
  59. 脚本只负责后处理:基于原生 alpha 的切片、alpha 重打包、边缘检查和插入 PPT。禁止把 PIL / SVG / canvas / 手写路径 / PowerPoint 形状伪装成最终图标资产。
  60. ### 通用 C×R / N×N 对齐
  61. skill使用通用 `C×R` 规则网格对齐:
  62. - `C` = columns,`R` = rows
  63. - `N×N` 网格必须使用正方形画布和 N 行 N 列
  64. - 矩形网格必须让画布比例匹配 `C:R`
  65. - 每个图标居中在自己的 cell center
  66. - 图标限制在 cell 中央 55-65% safe zone
  67. - 每个 cell 内保留至少 20-25% 空白 padding
  68. - 生成结果必须是原生 RGBA:透明角、非空 alpha bbox、主体覆盖均需验证
  69. - 切割使用原生 alpha 前景蒙版,不对已透明资产进行二次透明化处理
  70. 切图时先检测真实内容网格,再根据 row/column centers 计算 cell edges,避免从 `(0,0)` 用 `image_width / C` 硬切导致图标截断。
  71. ### CJK 与 PowerPoint 渲染
  72. 中文文本不仅设置 `run.font.name`,还要求在 OOXML 中设置 `a:latin`、`a:ea`、`a:cs`。这样可以减少 PowerPoint 导出时回退到宋体、字号漂移或换行变化的问题。
  73. ### 文本槽与字号保真
  74. `ppt_text_fit.py` 是溢出预检工具,不是把文字一律缩小的指令。复刻时应先按边框、图标和真实内边距确定完整的可用文本槽,再测量字号。
  75. - 为标题、长单行标签、双行栏头和中英混排短语记录参考字号、行数和可用文字框
  76. - 对高风险文本使用 `--target-pt <参考字号>`;工具会返回 `required_box_px` 与 `box_deficit_px`
  77. - 出现字号偏小而不溢出时,先扩大文本框、减少重复 margin、调整图标/分隔线/列宽占位,再考虑减小字号
  78. - `fits: true` 只说明不越界;最终必须以 1:1 渲染裁图检查字高、宽度、基线和参考层级
  79. - 勾选清单、步骤列表等重复组件不能共用固定文字宽高;先锁定图标槽,再逐行分配剩余宽度,并对中英混排长标签记录 `reference_scale`。同组单行文本若低于参考字高的 `90%`,必须先修文本槽或卡片几何
  80. ### 多页输入独立复刻
  81. 当输入是多张图片、图片版 PPTX 或 PDF 时,每一页都必须按独立单页规格严格复刻。
  82. 默认交付方式是:逐页渲染、逐页对比、逐页修正,最后按原始顺序拼接成一个完整的多页可编辑 PPTX。
  83. ## 复刻工作流
  84. ### Rebuild Protocol
  85. | 阶段 | Codex 执行内容 | 质量约束 |
  86. | --- | --- | --- |
  87. | 01 · 输入规整 | 接收图片、图片版 PPTX 或 PDF;渲染/排序为逐页参考图 | 记录页码、尺寸、比例、源文件 |
  88. | 02 · 视觉盘点 | 拆出标题、正文、表格、卡片、按钮、箭头、图标、背景区域 | 为每个非文本对象分配稳定 asset id;非直线箭头记录尾端、头端、路径类型、回折侧和关联标签 |
  89. | 03 · 资产分类 | 标记 `native_editable` 与 `imagegen_asset` | 图标和复杂视觉必须进入生图门禁 |
  90. | 04 · 资产生成 | 用生图模型生成独立透明 PNG;验证 alpha 后做网格切割与重打包 | 保留原生 alpha,输出 contact sheet 与 grid alignment report |
  91. | 05 · PPT 重建 | 用原生 PPT 对象重建文本、表格、卡片、线条和可编辑结构 | 保持图层、命名、位置和比例可维护 |
  92. | 06 · 渲染校准 | 导出 PPTX 为 PNG,和原图做全页及局部裁图对比 | 修正截断、换行、边距、阴影、字体、对齐,以及回流/注释箭头的路径几何 |
  93. | 07 · 多页装配 | 多页输入按原始顺序合并为一个 PPTX | 每页都有独立 QA 证据,不用粗略套模板 |
  94. ### QA Trace
  95. 每次高质量复刻建议保留以下证据链:
  96. ```text
  97. source page
  98. -> visual inventory
  99. -> asset manifest
  100. -> generated asset sheet
  101. -> transparent PNG assets
  102. -> rebuilt PPTX
  103. -> rendered preview
  104. -> local crop QA
  105. -> arrow-label crop QA
  106. -> corrected final PPTX
  107. ```
  108. 这条链路让问题能被定位到具体环节:是生图资产本身截断、切图坐标错误、透明 padding 丢失,还是 PPT 插入和缩放导致的渲染裁切。
  109. ## 图像资产规则
  110. ### 资产联系图
  111. 每个复杂图标都作为独立透明 PNG 资产插入 PPT,便于单独替换、缩放和排查边缘裁切问题。
  112. <p align="center">
  113. <img src="assets/asset-contact-regenerated-grid.png" alt="Generated asset contact sheet" width="72%" />
  114. </p>
  115. ### Content-grid cutting
  116. <p align="center">
  117. <img src="assets/new_sheet_projection_runs.png" alt="Content grid projection diagnostic" width="72%" />
  118. </p>
  119. 生成式图标网格常见问题:
  120. - 外圈留白导致硬切错位
  121. - edge cell 源图被模型画到边界外
  122. - 相邻 cell 残片混入目标图标
  123. - 原生 alpha 边缘或透明 padding 不符合要求
  124. skill 要求生成网格时就保证每个图标完整落在各自 cell 的 safe zone 内,不截断、不溢出、不跨格;再检测真实内容网格后切割,并输出 grid alignment report。
  125. ### Native Alpha Validation
  126. 生图模型现在直接输出透明 PNG。skill 将原生 alpha 视为资产的一部分,而不是待清理的背景:生成后立即验证 RGBA 模式、四角透明、非空 alpha bbox、主体覆盖和最小透明 padding;验证通过后保留原始 alpha,再按网格切片与视觉质心重打包。
  127. 处理规则:
  128. - 验证 PNG 为 RGBA,四角 alpha 为 0,且 alpha bbox 非空
  129. - 用 alpha 前景蒙版检测真实的 `C×R` / `N×M` 内容中心和 cell 边界
  130. - 每个 cell 只输出一个语义资产,并保留至少 10 px 透明安全边距
  131. - 按 alpha bbox 和 alpha 视觉质心重打包到透明方形画布
  132. 这样能保护抗锯齿边缘,也能减少浅色底块、透明 halo 和不同网格尺寸复用时的切图漂移。
  133. ## 安装
  134. 将本仓库放到 Codex skills 目录下:
  135. ```powershell
  136. $env:CODEX_HOME = "$HOME\.codex"
  137. git clone https://github.com/knight6669/knight-imagetopptx-skill "$env:CODEX_HOME\skills\knight-imagetopptx-skill"
  138. ```
  139. 或直接把目录放到:
  140. ```text
  141. ~/.codex/skills/knight-imagetopptx-skill
  142. ```
  143. ## 使用方式
  144. 在 Codex 中触发 skill:
  145. ```text
  146. [$knight-imagetopptx-skill](./SKILL.md) 复刻这张图片成可编辑 PPTX
  147. ```
  148. 可以输入的素材包括:
  149. - 单张 PNG / JPG / WebP 幻灯片截图
  150. - 图片版 PPTX,也就是每页都是截图或整页图片的 PowerPoint
  151. - PDF 页面,例如导出的汇报 PDF、扫描版或图片型 PDF
  152. - 已渲染的 slide page,需要重建为可编辑对象
  153. 多页输入规则:
  154. - 每一页都按独立单页复刻,不偷懒套模板
  155. - 每一页都要单独渲染对比和局部裁图检查
  156. - 修正完成后按原始顺序合并成一个 `.pptx`
  157. - 默认交付一个多页可编辑 PPTX,而不是多个零散 PPTX
  158. 示例:
  159. ```text
  160. [$knight-imagetopptx-skill](./SKILL.md) 复刻这张图片成可编辑 PPTX
  161. ```
  162. ```text
  163. [$knight-imagetopptx-skill](./SKILL.md) 这个 PPTX 是图片版的,请逐页复刻成文字、表格、图标都可编辑的 PPTX
  164. ```
  165. ```text
  166. [$knight-imagetopptx-skill](./SKILL.md) 把这个 PDF 里的汇报页复刻成可编辑 PPTX
  167. ```
  168. 也可以直接提出类似任务:
  169. ```text
  170. 把这张中文商务汇报截图复刻成可编辑 PPTX,文字、表格、卡片、箭头都要可编辑,图标独立成透明 PNG。
  171. ```
  172. ## Skill 设计理念
  173. 这个 skill 的目标不是生成一张“像 PPT 的图片”,而是把静态视觉页重建成可继续工作的 PowerPoint 系统。
  174. - 先理解结构,再复刻画面:文本、表格、卡片、箭头、图标和复杂视觉各归其位。
  175. - 复杂资产交给生图模型,版式关系交给原生 PPT 对象,保证观感与可编辑性同时成立。
  176. - 每一页都按独立作品处理:逐页拆解、逐页渲染、逐页校准,再合并成完整 deck。
  177. - 把字体、网格、裁切、图层和渲染 QA 沉淀为流程约束,让复刻结果可复用、可追溯、可迭代。
  178. ## 目录结构
  179. ```text
  180. knight-imagetopptx-skill/
  181. ├─ SKILL.md
  182. ├─ README.md
  183. ├─ LICENSE
  184. ├─ agents/
  185. ├─ scripts/
  186. │ ├─ check_rebuild_assets.py
  187. │ └─ ppt_text_fit.py
  188. └─ assets/
  189. ├─ skill-banner.svg
  190. ├─ reference-slide-01.png
  191. ├─ rebuilt-slide-01.png
  192. ├─ rebuilt-slide-01.pptx
  193. ├─ reference-slide-02.png
  194. ├─ rebuilt-slide-02.png
  195. ├─ rebuilt-slide-02.pptx
  196. ├─ editable-elements-01.png
  197. ├─ editable-elements-02.png
  198. ├─ comparison.png
  199. ├─ asset-contact-regenerated-grid.png
  200. └─ new_sheet_projection_runs.png
  201. ```
  202. ## 质量约束
  203. ```bash
  204. python scripts/check_rebuild_assets.py --asset-dir path/to/assets
  205. ```
  206. 推荐每个复刻项目都保存:
  207. - rendered preview
  208. - comparison/contact sheet
  209. - local crop QA
  210. - asset manifest
  211. - grid alignment report
  212. 完成交付前至少检查:
  213. - 图标没有截断、残片、浅色底块和透明边缘污染
  214. - 中文字体没有回退到宋体或发生异常换行
  215. - 表格、卡片、按钮和流程箭头保持可编辑
  216. - 非直线箭头的头向、回折侧、路径、线宽和关联标签均与参考裁图一致
  217. - 多页输入中每一页都有独立渲染校准
  218. - 最终文件是一个完整 `.pptx`,而不是零散单页文件
  219. ## Roadmap
  220. ### Capability Roadmap
  221. | Layer | Direction | Target |
  222. | --- | --- | --- |
  223. | Asset Reliability | 通用 C×R / N×N 资产网格切割器 | 自动检测真实内容边界、cell center、透明 padding 和异常残片 |
  224. | Visual QA | 多区域 QA contact sheet | 自动生成全页、局部、按钮区、底栏、表格区和图标区对比图 |
  225. | Editable Semantics | Selection pane 命名规范 | 为文本、表格、卡片、图标和流程对象建立可读命名体系 |
  226. | Multi-page Engine | PPTX / PDF 批量页复刻协议 | 逐页生成 inventory、manifest、render preview,并合并为单一 deck |
  227. | Style Library | 中文商务与政务版式样例库 | 沉淀高频卡片、蓝色政务风、信息图、流程图和仪表盘复刻模式 |
  228. | Agentic Review | 自动复核与回修循环 | 让 Codex 基于渲染差异生成修正清单并执行二次校准 |
  229. ### Release Intent
  230. | Milestone | Focus |
  231. | --- | --- |
  232. | v0.1 | 固化生图资产约束、CJK 字体规则、基础可编辑复刻流程 |
  233. | v0.2 | 增强图标网格检测、asset manifest、局部 crop QA |
  234. | v0.3 | 强化多页 PPTX / PDF 输入,形成稳定的 page-by-page assembly |
  235. | v1.0 | 建立可复用复刻协议:输入解析、资产生成、PPT 重建、渲染校准、最终交付 |
  236. ## 关于作者
  237. Knight | 贺 | 持续探索 vibe-coding
  238. ## 许可
  239. MIT License 开源。详见 [LICENSE](LICENSE)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.