可编辑ppt生成（支持自定义模板）_秋叶职场

概述

Reference HTML PPTX

Version

Current design-workflow version: 2.8.3.

This is a self-contained HTML-to-editable-PPTX workflow. The shape/SVG annotation contract, HTML screenshot auditor, editable-PPTX exporter, and PowerPoint preview renderer live in this skill's own references/ and scripts/ directories. Do not require a separate export-editable-pptx skill to complete the workflow.

Create slides with Codex's own content reasoning and HTML/CSS design ability. Optimize in this order:

conclusion → semantic relationships → grouping → hierarchy → layout → wireframe → visual tokens → emphasis and component strategy → visual craft → PPTX annotation → dual-render QA

Do not begin styling before the content model and layout rationale are clear.

Input contract

Collect or identify:

• text-free 16:9 background image;
• at least one content-slide design reference image;
• title and body copy for each page;
• desired output: HTML only or HTML plus PPTX. Default to both for a complete PPT workflow.

Reuse the last confirmed background and reference language during the same task unless the user replaces them. Ask only when a missing input materially changes the result.

Authority order

1. Preserve user facts and required relationships. Do not invent claims, numbers, actors, or process steps.
2. Clarify the page's intended conclusion and reorganize copy to make that conclusion understandable.
3. Preserve the supplied background exactly as the bottom layer and stage it inside the output folder. When the user provides a background image, you MUST use it verbatim — copy it into assets/ and place it as the slide's bottom layer (a real <img class="slide-bg"> or background-image: url(assets/...)), never a hand-drawn CSS gradient. Derive accents, spacing, and ornament from it, but do not replace it. Only when no background image was supplied may you fall back to a generated gradient background.
4. Derive the visual system from the reference: palette, typography, components, spacing, shadows, icons, and rhythm. Match its design language, not its original subject matter or geometry.

Read [references/design-reasoning.md](references/design-reasoning.md) before planning. Read [references/design-extraction.md](references/design-extraction.md) before styling. Read [references/visual-craft.md](references/visual-craft.md) after extracting the reference and before writing final CSS. Read [references/preview-and-density.md](references/preview-and-density.md) before writing HTML. Read [references/html-contract.md](references/html-contract.md) only after the visual plan is frozen or when PPTX annotation begins. When the user requests editable decorative elements, also read the integrated references/editable-object-contract.md before writing those components.

Workflow

1. Inspect and stage inputs

Inspect every image at original detail. Identify background versus design reference. Create a new output directory and copy all required local assets into assets/; never leave temporary clipboard paths in final HTML. When a background image is provided, stage it as assets/background.<ext> and reference it from the slide's bottom layer.

2. Build the content model

For every logical page, create design-plan.json in the output directory with:

• coreQuestion: the one question the page answers;
• takeaway: the one-sentence conclusion the audience should retain;
• requiredFacts: facts and labels that must remain;
• relationType: sequence, hierarchy, collaboration, flow, cycle, comparison, classification, matrix, or cause-response;
• mainPath: the primary reading or process path;
• groups: usually 3–5 macro regions, treated as a heuristic rather than a quota;
• supportingMechanisms: governance, validation, context, or explanation;
• exceptions: conditions paired with responses;
• layoutFamily and primaryVisual;
• densityIntent: page type, intended content-region occupancy, minimum body size, and any justified density exemptions;
• referenceTraits: the visual traits to preserve.
• visualTokens: extracted color roles, type scale, radii, boundaries, shadows, icon language, and spacing rhythm;
• emphasisPlan: one primary focus, secondary accents, and accent intensity;
• componentStrategy: primary component types, card count, boundary methods, and deliberate exceptions.

If the page answers multiple unrelated questions or needs more than three information levels, split it when allowed; otherwise prioritize one main argument and demote the rest to supporting regions. Normalize parallel labels into consistent noun or verb structures.

3. Choose structure before style

Map the semantic relationship to a suitable layout using design-reasoning.md. For complex pages, evaluate at least two wireframe candidates internally. Choose based on:

1. relationship fidelity;
2. obvious reading order;
3. hierarchy and grouping;
4. density balance;
5. fit with the reference's design language.

Do not choose orbit, radial, timeline, matrix, or card-grid layouts unless the content relationship justifies them. Establish a 12-column grid or another explicit alignment system, title zone, content bounds, macro regions, and whitespace before styling.

Run node scripts/audit-design-plan.mjs <output>/design-plan.json before styling. Fix missing or contradictory decisions instead of silently inventing them in CSS.

4. Freeze the visual system

Translate the reference traits into reusable CSS variables and component rules. Define semantic color roles rather than isolated hex values. Give each component family one silhouette, one boundary method, one spacing rhythm, and one icon language. Plan where the accent appears before applying it.

Use cards only for information that needs a meaningful boundary: conclusions, key metrics, comparison subjects, states, or reusable modules. Use proximity, alignment, whitespace, background zones, and restrained dividers for ordinary explanation. Limit the page to a small visual vocabulary; more component types do not create more hierarchy.

5. Design the HTML page

Create a self-contained index.html with one fixed 1600×900 .slide[data-slide-index] per logical page, wrapped by a preview-only .slide-shell[data-slide-shell]. Scale the complete slide for smaller screens; do not make internal typography or geometry viewport-responsive. Use large structures for major relationships, medium structures for modules, and small components for labels and details. Maintain one primary reading path; comparison pages may use two intentionally equal panels.

Use hierarchy, alignment, distance, whitespace, and background regions before adding borders or cards. Avoid card-per-sentence layouts, nested cards, duplicate borders, and decoration without information value. Keep accent color scarce and purposeful. Mark informational cards with data-density-card="true", major component families with data-component-type, the primary focus with data-emphasis-level="primary", the principal content region with data-slide-content, and its major occupied blocks with data-content-block. Apply exemptions only with a documented semantic reason.

When a shape, line, or icon is intended to survive as an independently selectable PPTX object, create it as a real DOM element during this step. Do not rely on the exporter to infer ordinary CSS decoration. A shape behind text is still a separate atomic primitive and must have its own annotation; its child text remains a separate editable text object.

Use this mapping while authoring the HTML:

• filled or outlined container → data-pptx-render="native" plus data-pptx-shape="rect|roundRect|ellipse|...";
• underline, divider, axis, arrow, or connector → a real DOM element with data-pptx-line-shape, color, width, and endpoint metadata;
• icon or complex vector ornament → data-pptx-svg="true" data-pptx-render="svg" on the actual <svg> element;
• photo, texture, blur, mask, canvas, or unsupported artwork → data-pptx-render="raster" or data-pptx-ignore="true" with the flattening decision documented.

For native roundRect shapes, preserve a uniform HTML border-radius; the integrated exporter converts the computed CSS radius to PowerPoint's rectRadius. Use data-pptx-radius as a CSS-pixel override when the radius cannot be read reliably from CSS. PowerPoint supports one native radius adjustment per roundRect, so independent four-corner radii remain an SVG/raster case.

CSS border-bottom, ::before, and ::after are not independent editable objects. If the line matters structurally or must be selectable in PowerPoint, replace it with an annotated DOM line. If an SVG is decorative and should remain flattened, explicitly keep it out of the editable-object contract instead of leaving its status ambiguous.

By default, every generated HTML preview exposes in-browser text editing; omit it only when the user explicitly requests a clean presentation-only HTML. Mark the source text roles explicitly:

<h1 data-text-editor-role="page-title">页面标题</h1>
<h2 data-text-editor-role="heading">一级标题</h2>
<p data-text-editor-role="body">正文内容</p>

Use one page-title per slide, then mark headings and body paragraphs/list items in reading order. After the HTML is authored, inline the editor with the integrated script so the final index.html contains a visible 编辑文本 button and a right-side editor panel:

& "<skill-root>/scripts/inject-text-editor.ps1" `
  -InputPath "<output>/index.html" `
  -OutputPath "<output>/index.html"

The editor labels fields as 页面标题, 一级标题1, 一级标题2, 正文1, and so on, groups them by page, updates the slide live, supports locating the source text and restoring original copy. In Chrome/Edge with the File System Access API, the first 保存修改 click asks the user to select the current HTML file and grant write permission; later saves in that page session overwrite the selected HTML file. Browsers without file write-back support fall back to browser-local storage for automatic restoration on the next open. The editor UI is outside .slide and carries data-text-editor-ui, so it is excluded from HTML slide screenshots and PPTX export. If a text run contains mixed inline styling, mark the editable leaf text element rather than its rich parent; editing a parent replaces its child markup with plain text.

5.5 Verify visual-QA capability (multimodal gate)

Visual QA step 6's "human-eye" review depends on the model's multimodal (image-understanding) ability. Before running any QA screenshot, state plainly whether the current model can read images:

1. Declare capability. Right after finishing the HTML, tell the user explicitly whether the running model supports multimodal image inspection. Never pretend to see a screenshot you cannot view.
2. Generate the preview before asking. Run scripts/inspect-slide-html.ps1 and produce the individual-page and continuous-scroll PNGs so the user has concrete evidence to inspect. The screenshot bundle is the required QA artifact; the structured audit is a bounded, best-effort assistant check. It uses playwright-core with an installed system Edge/Chrome and does not download a Playwright browser. The default total audit limit is 120 seconds; use -AuditTimeoutSeconds to override it, and use -InstallDependencies only for an explicit one-time dependency setup.
3. Branch on capability:
   • Model supports multimodal → inspect the PNGs, report the visual judgment, show the previews, and ask the user whether to continue with PPTX export.
   • Model does NOT support multimodal → state that no subjective visual judgment was performed, report the structured audit results, show the previews, and recommend review with a model that supports image understanding.
4. Always wait for explicit confirmation before PPTX export. Do not continue to steps 7–8 until the user approves the HTML preview. The only exception is when the user explicitly requested a no-confirmation or direct-export mode in the current request.

6. Run HTML visual QA

Run scripts/inspect-slide-html.ps1 immediately after the capability declaration. It must produce one PNG per slide plus a continuous-scroll preview and audit page dimensions, separation, preview outline, scroll snapping, font floors, text overflow, and marked-card density. Inspect both the individual PNGs and the continuous preview at original detail only when the current model actually supports multimodal; otherwise rely on the structured audit output and let the user perform the subjective visual review. If the screenshot bundle is complete but the structured audit reaches its time limit or browser shutdown is slow, the wrapper returns auditStatus: "degraded", prints a warning, and the workflow continues. Do not retry a degraded audit indefinitely. A missing screenshot, browser launch failure, page-load failure, or screenshot failure remains a hard error. Apply the design acceptance gate in design-reasoning.md; fix logic, hierarchy, density, alignment, typography, page separation, or decoration failures before asking for export confirmation.

Use the integrated command shape:

& "<skill-root>/scripts/inspect-slide-html.ps1" `
  -InputPath "<output>/index.html" `
  -ScreenshotPath "<output>/qa/html.png"

Do not accept a page merely because it has no overflow. A page fails if the conclusion, reading path, relationship meaning, primary hierarchy, reference-derived visual grammar, emphasis control, or component consistency is unclear. Apply the visual-craft acceptance gate after the three-second test.

7. Annotate for PPTX after design freeze

Only after the HTML composition passes visual QA, audit and complete the annotations for every requested visual primitive. Classify each atomic element as native, chart, SVG, or raster, then add data-pptx-render, semantic role, z layer, and the matching shape/line/chart/SVG metadata. The minimum annotation patterns are:

<!-- editable container behind independently editable text -->
<article data-pptx-render="native"
         data-pptx-shape="roundRect"
         data-pptx-fill="#FFFFFF"
         data-pptx-fill-opacity="94"
         data-pptx-line="#D0D5DD"
         data-pptx-line-width="1"
         data-pptx-role="card"
         data-pptx-z="20">
  <h3>Editable text</h3>
</article>

<!-- editable underline/divider; do not use ::before or border-bottom alone -->
<div data-pptx-render="native"
     data-pptx-line-shape="horizontal"
     data-pptx-line-start="0,50"
     data-pptx-line-end="100,50"
     data-pptx-line-color="#C90000"
     data-pptx-line-width="2"
     data-pptx-role="underline"
     data-pptx-z="40"></div>

<!-- movable/scalable SVG image object; its internal paths are not PPTX shapes -->
<svg data-pptx-svg="true" data-pptx-render="svg" data-pptx-role="icon" viewBox="0 0 24 24">
  <path d="M4 12h16" stroke="#C90000" stroke-width="2" fill="none"/>
</svg>

A progress bar needs separate track and fill annotations; overlapping logo circles need separate ellipse annotations; flows need separate card and connector annotations; percentage rings should use native doughnut charts when chart editability is required. Marking only a parent component does not make its child primitives independently editable.

Do not assume that pixels in the supplied PNG become editable. If its ornaments must be editable, split the source into a clean base image plus DOM-rebuilt ornaments. Preserve the original image as a fidelity reference and verify the reconstructed result against it. Keep unsupported gradients, masks, glows, photographs, and illustrations explicitly marked raster or exported as SVG, and report that editability level truthfully.

Re-render once after annotation to confirm that metadata did not change the HTML appearance. Follow html-contract.md; do not redesign the page around exporter limitations.

7.5 Common decoration omissions (annotate proactively)

The hybrid exporter keeps an HTML screenshot as the bottom layer and only turns explicitly tagged real DOM elements into independently editable PowerPoint objects. Users are highly sensitive to decoration that cannot be selected, moved, or recolored in PowerPoint — treat "looks fine in the HTML render" as insufficient. After the base annotation patterns in §7, walk this checklist and tag every item that appears on your slides:

Pseudo-element trap (critical). ::before and ::after decorations are not real DOM nodes, so data-pptx-* cannot be attached and the exporter never sees them — they silently vanish from the PPTX. Any ring, underline, ribbon, dot, or dash drawn via a pseudo-element must be rebuilt as a sibling/child <div> carrying the same border in CSS, then tagged. This is the single most common cause of "the dashed circle is gone in PowerPoint." Also delete the now-redundant pseudo-element CSS rule so the ring is not drawn twice.

Gradient → solid trade-off. Native shapes support only a solid data-pptx-fill; CSS linear-gradient is not preserved (see §7 raster note). For a gradient container you must choose one:

• editable solid fill (lose the gradient); or
• data-pptx-render="raster" to keep the gradient but lose selectability.

When editability wins, read the gradient's color stops and pick the dominant/brand tone as the solid fill (e.g. blue block #2A4C7E, red block #B23A4A). Document the trade-off in your handoff note.

Batch annotation helper. When many same-class containers (e.g. 17 card variants, 8 character rings) need tagging, do not hand-edit every node. Use a small Node script that regex-injects the data-pptx-* attributes onto each matching class, run it, then re-audit. Pattern:

const fs = require('fs');
let html = fs.readFileSync('index.html', 'utf8');
// example: tag every .metric-tag as a native ellipse
html = html.replace(
  /<div class="metric-tag">(d{2})</div>/g,
  (m, n) => `<div class="metric-tag" data-pptx-render="native" data-pptx-shape="ellipse" data-pptx-fill="#C90000" data-pptx-line="#C90000" data-pptx-line-width="0" data-pptx-role="metric-tag">${n}</div>`
);
// example: convert a ::after dashed ring into a real DOM child
html = html.replace(
  /(<div class="char-orb"[^>]*>)([sS]*?)(</div>)/g,
  (m, open, inner, close) => `${open}${inner}<div class="char-ring" data-pptx-render="native" data-pptx-shape="ellipse" data-pptx-fill="#FFFFFF" data-pptx-fill-opacity="0" data-pptx-line="#C90000" data-pptx-line-width="2" data-pptx-line-dash="dash" data-pptx-role="char-ring"></div>${close}`
);
fs.writeFileSync('index.html', html);

Coverage gate. After export, read the semantic editability coverage figure in the export log. Below ~90% means decoration is still being flattened — re-scan for un-tagged CSS-only containers and pseudo-elements, tag them, and re-export. A transparent overlay over a raster duplicate does not count as coverage (see §8).

8. Export PPTX and finish

Before export, use the latest HTML QA result and resolve every unclassified shape/SVG candidate reported by a completed audit. A degraded audit is non-blocking when all required screenshots exist: preserve its warnings, do not launch an infinite retry loop, and continue to export. Block export only when the screenshot bundle is incomplete or the audit reports a real browser/page/screenshot error. Use the integrated scripts/export-editable-pptx.ps1 with .slide as the selector. Verify the expected slide, text, shape, line, chart, SVG, raster-only, and unsupported-semantic counts. For logic-heavy pages, zero editable shapes or zero editable lines is an automatic failure; target at least 90% native-editable coverage of semantic structures and require zero unclassified semantic objects. A transparent overlay over a raster duplicate does not count as editable coverage.

After the user approves the HTML preview, run:

& "<skill-root>/scripts/export-editable-pptx.ps1" `
  -InputPath "<output>/index.html" `
  -OutputPath "<output>/deck-editable.pptx" `
  -SlideSelector ".slide"

When the exporter completes successfully and the .pptx exists, finish the default workflow and return the PPTX path together with the exporter-reported object counts. Do not automatically render the PPTX, reopen it, compare it with the HTML, or start another visual-review loop after export. Perform post-export PowerPoint rendering/comparison only when the user explicitly requests PPTX QA, rendered PPTX previews, or troubleshooting.

# Optional only when the user explicitly requests post-export PPTX QA.
& "<skill-root>/scripts/render-pptx-preview.ps1" `
  -InputPath "<output>/deck-editable.pptx" `
  -OutputDirectory "<output>/qa/pptx"

Multi-page rules

• Give every page one narrative role and one takeaway.
• Treat every page as an independent 16:9 canvas. Put it inside a preview shell, separate shells by 6%–10% of a page height, and place the deck on a contrasting neutral canvas.
• Use vertical scroll snapping in preview mode. Prefer proximity; use mandatory only for a deliberate full-screen browsing experience.
• Do not rely on page numbers alone to distinguish adjacent pages. Page outline, space, shadow, border, or background contrast must remain visible.
• Keep the design system consistent while varying layout families according to content relationships.
• Do not repeat the same card grid or composition on consecutive pages without semantic reason.
• Maintain deck-level progression: setup → development → evidence/structure → implication/action.
• Check both individual-page quality and transitions between pages.

Deliverables

Return absolute links to:

• index.html;
• HTML preview PNGs;
• a continuous-scroll preview PNG for multi-page decks;
• .pptx; PowerPoint-rendered preview PNGs only when explicitly requested.

Report slide count, editable text-object count, editable shape-object count, editable line-object count, editable chart-object count, SVG image-object count, intentional raster-only count, unsupported semantic count, and structural editability coverage from the exporter output. Also report any remaining unclassified visual candidates or explicitly flattened shapes/SVGs. Identify intentionally flattened semantic objects. Mention font substitution only when non-system fonts are used. Do not block delivery on optional PowerPoint-rendered QA.

Prohibitions

• Do not invoke or depend on Dashi PPT.
• Do not overwrite an earlier page unless explicitly requested.
• Do not use temporary clipboard paths in final HTML.
• Do not force content into the reference's exact geometry.
• Do not use viewport units or viewport-dependent clamp() for slide typography; scale the complete 1600×900 canvas instead.
• Do not shrink normal body copy below 16px to make it fit. Recompose, condense, split, or resize the container.
• Do not place consecutive .slide canvases directly against each other in browser preview.
• Do not use decorative arrows, rings, tracks, or connectors without semantic meaning.
• Do not use shadow, border, glow, color fill, and accent stripe simultaneously on one ordinary component.
• Do not mix outline, filled, 3D, emoji, and photographic icons at the same semantic level.
• Do not turn every sentence into a card or every keyword into a badge.
• Do not claim arbitrary graphics, animations, canvas, filters, or videos are editable in PowerPoint.

Agent / sandbox environment gotchas (CodeBuddy / WorkBuddy sandbox, CI)

The visual-QA step (scripts/inspect-slide-html.ps1 → audit-slide-layout.mjs) drives a headless Chromium. In sandboxed shells:

1. chromium.launch must pass --no-sandbox (plus --disable-gpu --disable-dev-shm-usage). Without them Chromium's sandbox init crashes and the screenshot step fails with empty output / exit 1 (no per-slide PNG, no continuous preview). Already patched in audit-slide-layout.mjs — keep it patched if you re-edit. If screenshots silently fail, this is the first thing to check.
2. Invoke through the skill scripts, not by hand-rolling a browser call. The .ps1 wrapper is fine on a normal desktop; inside an agent sandbox run the underlying .mjs with node and a disabled sandbox so the browser process can spawn.

Recurring design-time pitfalls (caught while building real decks)

1. The HTML audit uses the installed browser, not a Playwright browser download. audit-slide-layout.mjs loads playwright-core, honors PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH, and searches the local Edge/Chrome paths. Do not run npx playwright install as part of a deck task. The skill ships without scripts/node_modules (SkillHub's publishing limits forbid the ~21 MB / ~300 files a full install produces, and its uploader rejects binary and extensionless files such as .wasm and LICENSE). On first use the .ps1 wrappers auto-run npm --prefix <scripts> install --no-audit --no-fund from the committed package.json / package-lock.json. That one-time install needs network access and a local node; it downloads npm packages only, never a Playwright browser. Steady-state requirements are node plus an installed Edge or Chrome.
2. A degraded audit is not a reason to block a completed screenshot run. The audit has bounded page-load, font, structural-analysis, screenshot, and browser-close timers. When screenshots exist, keep the warning and continue; never retry the same hung audit without a changed condition.
3. A user-supplied background image takes precedence over a generated gradient. If the user provides a background image, stage it into assets/ and use it as the exact bottom layer — do not silently substitute a CSS gradient. The "prefer a pure CSS gradient" advice applies only when no background image was supplied. AI-generated background images often bake a "AI生成" mark and random Chinese characters into the picture; when you generate a background yourself (no user image), inspect it at full detail first and reject any with text artifacts.
4. CSS specificity can collapse a position:absolute footer into normal flow. A rule like .slide > *:not(.slide-bg){position:relative} (specificity 0,2,1) overrides a class rule such as .src{position:absolute} (0,1,0), so the footer drops out of its layer and stacks against the chip row, causing apparent "overlapping text". Exclude the footer class: .slide > *:not(.slide-bg):not(.src). Always verify layered elements with a DOM-coordinate probe in addition to visual inspection; if the running model cannot inspect images, show the preview to the user and wait for confirmation.
5. Metric units wrap and look broken. Short values like 4–15s or 24 FPS can break across lines. Add white-space:nowrap to the value element and keep the unit as an inline <span> with vertical-align:bottom rather than a superscript-like baseline shift.