officecli-pptx

# OfficeCLI PPTX Skill ## 运行环境与交付链（本系统专用，先读这一段） **`officecli` 已经预装在运行环境的 PATH 中，不要联网安装、不要 curl。** `Bash` 工具直接调用即可，自检用 `officecli --version`。 所有命令在当前会话工作目录执行，输入输出使用相对路径或用户指定的真实路径。一次完整作业 = 3 步 + 1 步交付： ``` # Step 1（仅当用户上传过原始文件）把 artifact 送进沙盒 sandbox_put_artifact(artifact_id="<用户文件的 file_id>", dest_path="./in.docx") # Step 2 用 Bash 跑 officecli —— 本文件下面讲的全部命令都在这一步里 Bash("officecli create ./out.docx") # Step 3 把成稿从沙盒取出、登记成 artifact，拿到新的 file_id sandbox_get_artifact(src_path="./out.docx", name="终稿.docx") # Step 4（必做）交付给用户 pin_to_workspace(file_ids=["<新 file_id>"]) ``` **铁律**： - `sandbox_put_artifact` = 放**进**沙盒，`sandbox_get_artifact` = 从沙盒**取出**，别搞反；两个路径参数使用当前工作目录内的相对路径或真实绝对路径。 - 拿到 `file_id` 却不 `pin_to_workspace` 就等于没交付，用户看不到文件。多个产物一次性放进同一个列表，别分多次调用。 - 下文示例里的 `$FILE` 指实际文件；相对路径按当前会话工作目录解析。 - 下文的可视化质检（`view <file> screenshot` / `view <file> html`）依赖沙盒内的 Chromium，镜像已预装；截图失败就按下文 fallback 走 `view html`，并如实标注「未做视觉验证」，不要谎报 PASS。 - **导出 PDF 不要用 `officecli view <file> pdf`** —— 那个模式依赖本系统没有安装的 exporter 插件，必然失败。改用沙盒里的 LibreOffice： `soffice --headless --convert-to pdf --outdir . ./out.docx`。.xlsx / .pptx 换掉扩展名同理，但要沙盒里装了 LibreOffice Calc / Impress 才转得动；转换报错就如实告诉用户 PDF 没导出成功、主产物仍是原文件，不要谎报已导出。 ## ⚠️ Help-First Rule **This skill teaches what good slides look like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.** ```bash officecli help pptx # List all pptx elements officecli help pptx <element> # Full element schema (e.g. shape, chart, animation, connector, zoom, group) officecli help pptx <verb> <element> # Verb-scoped (e.g. add shape, set slide) officecli help pptx <element> --json # Machine-readable schema ``` Help reflects the installed CLI version. When skill and help disagree, **help is authoritative**. Triggers to run help immediately: `UNSUPPORTED props:` warning, unknown animation preset, `connector.shape=` enum drifts, prop-vs-alias (`lineWidth` vs `line.width`, `color` vs `font.color`). ## Shell & Execution Discipline **Shell quoting (zsh / bash).** ALWAYS quote element paths (`"/slide[1]/..."`) — zsh globs unquoted `[1]` to `no matches found`. Escaping happens at three layers — keep them separate (the CLI handles the second for you): 1. **Shell.** `$` in a value still belongs to the shell — single-quote the whole value: `--prop text='$15M'`. Double-quoted `"$15M"` gets expanded to `M`. The CLI does NOT unescape `\$` for you. 2. **CLI (`text=`).** The two-char escapes `\n` and `\t` ARE interpreted, consistently across pptx / docx / xlsx — `\n` is a line / paragraph break, `\t` is a tab. To produce a literal backslash-n in text, double it (`\\n`); this is rarely what you want. 3. **JSON (batch heredoc).** The recipes below pipe `cat <<EOF | officecli batch` **unquoted** so `$SLIDE` / `$FILE` expand inside the body. That same unquoted heredoc also expands a literal `$` in a value: `"$1.42"` silently becomes `.42` and `"$2.4B"` becomes `.4B` (`$1` / `$2` are empty shell params). **Escape currency as `\$`** — `"text":"\$1.42"` — which still lets `$SLIDE` expand. `\n` / `\t` inside the JSON work either way. A fully-quoted `<<'EOF'` protects every `$` but then `$SLIDE` won't expand, so only use it when the body has no shell variables. After writing money values, `view text` and confirm the `$` survived. If in doubt, `view text` after writing and compare character-for-character. **Incremental execution.** One command → check exit code → continue. A 50-command script that fails at command 3 cascades silently. After any structural op (new slide, chart, animation, connector) run `get` before stacking more. ## Requirements for Outputs These are the deliverable standards every deck MUST meet. Violating any one = not done, regardless of content quality. ### All decks **One idea per slide.** If a slide needs a second title to explain what it covers, split it. Dense "everything about X" slides lose the audience inside 3 seconds. Use a section divider to group related one-idea slides, not a mega-slide. **Explicit type hierarchy — do NOT rely on theme defaults.** Theme defaults drift between masters. Set sizes explicitly on every text shape. | Element | Minimum | Typical | Min shape height | |---|---|---|---| | Slide title | **≥ 36pt** bold | 36–44pt | ≥ 2cm | | Section / subtitle | ≥ 20pt | 20–24pt | ≥ 1.2cm | | Body text | **≥ 18pt** | 18–22pt | ≥ 1cm | | Caption / axis label | ≥ 10pt muted | 10–12pt | ≥ 0.6cm | Rule of thumb: **min shape height ≈ font_pt × 0.05cm**. An 18pt sublabel in a 0.8cm-tall box will overflow — `view annotated` catches this. Title must be **≥ 2× body size** (36pt over 20pt works; 28pt over 20pt looks timid). Four legit exceptions to body ≥ 18pt: chart axis labels, legends, footer / page number, and ≤ 5-word KPI sublabels (e.g. "Active users"). Descriptive sentences must be ≥ 18pt. Left-align body; center only titles and hero numbers. If "the cards won't fit", drop cards instead of shrinking font. **Two fonts max, one palette.** One heading font + one body font (e.g. Georgia + Calibri) — a third *display* face is fine only for big numerals or the cover title, as long as that heading+body pair stays intact. One dominant brand color (60–70% weight) + one supporting + one accent. Never mix 4+ colors in body content. **The palettes and font pairings in Design Principles are a floor, not a menu:** if the user gave brand colors/fonts or an existing template, match those first; otherwise the named sets are calibrated seeds — blend or diverge freely, as long as the result isn't *worse* than them and still clears the contrast floor. **Every slide carries a non-text visual — one that informs.** Shape, chart, icon, gradient band that carries meaning, not decoration. A bullet-only deck is interchangeable with a Word doc. Exceptions: literal quote slides, code blocks, a single summary-table slide. **Less is more — every element earns its place.** The visual rule above guards against bullet-walls; it is not licence to clutter. Don't pad with decorative stats, icons, or filler sections that don't inform ("data slop"). If a slide feels empty, fix it with layout and whitespace, not invented content — cut scope rather than bulk it up, and flag a larger addition instead of making it unprompted. **Speaker notes on every content slide.** `--type notes --prop text="..."`. The speaker needs a script; the audience shouldn't read the slide verbatim. **Copy reads human, not AI.** Titles orient on content, not punchline. No "It's not X. It's Y.", no manufactured tension, no faux-insight ("The magic moment"), no one-word drama ("Momentum."). Cut hype adjectives (seamless, robust, game-changing) — let the number carry it. **Preserve existing templates.** When a file already has a theme and masters, match them. Existing conventions override these guidelines. ### Visual delivery floor (applies to EVERY deck) Before declaring done, the per-slide render (see QA) MUST satisfy: - **No placeholder tokens rendered as content.** `{{name}}`, `$fy$24`, `<TODO>`, `lorem`, `xxxx`, empty `()`/`[]` in chart titles never appear. - **No overflow off-edge, no clipped text in shapes.** `view issues` flags both (`shape_off_slide` + a text-fit hint). To fix a clip: grow the box or shorten the value — never trim content to fit. - **Cover carries its orienting elements.** Title + subtitle + presenter/client + date + a brand band or key-takeaway strap — a title-only cover reads as a stub. Generous whitespace around them is still right; rich ≠ crowded. - **Contrast.** `view issues` auto-flags the common case — opaque dark text on a shape's own dark fill (`low_contrast`). It can't see the rest: icon / chart-series fills, scheme/inherited colors, or text over a *separate* background shape. So on any fill with brightness < 30% (`1E2761`, `36454F`, deep forest / berry / cherry), still confirm every body run, card body, chart series, and icon is `FFFFFF` or brightness > 80% — mid-gray (`6B7B8D` ≈ 44%) reads on a laptop and vanishes on projection. Spot-check via `view html` after the dark-fill pass. If any fails, STOP and fix before declaring done. ## Design Principles A deck is not a document. The audience has 3 seconds to get each slide. Before adding anything, ask: "If the audience reads only the biggest element and glances once, do they get the point?" If they have to read the bullets, the biggest element is wrong. ### Grid, margins, negative space Standard widescreen is **33.87 × 19.05cm**. Treat it as a 12-column grid internally: - **Edge margin ≥ 1.27cm** (0.5") on all sides. - **Inter-block gap ≥ 0.76cm** (0.3") between cards / columns / rows — pick one value (0.76 or 1.27cm) and use it everywhere; mixed gaps look unfinished. - **≥ 20% negative space per slide.** Filling every pixel reads as amateur. - **Compose, don't web-center.** Whitespace is structural: a slide top-weighted with open space in the lower third is correct composition, not an empty defect. Intentional asymmetry (content left, breathing room right) reads more designed than centering everything — don't fill a gap just because it's there. - For card grids: `usable = 33.87 − 2·margin − (N−1)·gap`, then `col_width = usable / N`. Don't hand-pick x coordinates. ### Font pairings Pair by document register, not by novelty. "Best For" is a prompt, not a decree; a pairing outside this table is fine if it fits — these 8 are seeds, not the set. | Header | Body | Best For | |---|---|---| | Georgia | Calibri | Formal business, finance, executive reports | | Arial Black | Arial | Bold marketing, product launches | | Calibri | Calibri Light | Clean corporate, minimal design | | Cambria | Calibri | Traditional professional, legal, academic | | Trebuchet MS | Calibri | Friendly tech, startups, SaaS | | Impact | Arial | Bold headlines, event decks, keynotes | | Palatino | Garamond | Elegant editorial, luxury, nonprofit | | Consolas | Calibri | Developer tools, technical / engineering | Set both fonts explicitly on every shape (`--prop font=Georgia` on titles, `--prop font=Calibri` on body), not via theme inheritance. ### Color and contrast The columns: **Primary** (dominant — 60–70% of weight, the color you see first), **Secondary** (supporting tone), **Accent** (sparing, one-hit emphasis), **Text** (body on light fills), **Muted** (captions / axis labels / footer). | Theme | Primary | Secondary | Accent | Text | Muted | |---|---|---|---|---|---| | Coral Energy | `F96167` | `F9E795` | `2F3C7E` | `333333` | `8B7E6A` | | Midnight Executive | `1E2761` | `CADCFC` | `FFFFFF` | `333333` | `8899BB` | | Forest & Moss | `2C5F2D` | `97BC62` | `F5F5F5` | `2D2D2D` | `6B8E6B` | | Charcoal Minimal | `36454F` | `F2F2F2` | `212121` | `333333` | `7A8A94` | | Warm Terracotta | `B85042` | `E7E8D1` | `A7BEAE` | `3D2B2B` | `8C7B75` | | Berry & Cream | `6D2E46` | `A26769` | `ECE2D0` | `3D2233` | `8C6B7A` | | Ocean Gradient | `065A82` | `1C7293` | `21295C` | `2B3A4E` | `6B8FAA` | | Teal Trust | `028090` | `00A896` | `02C39A` | `2D3B3B` | `5E8C8C` | | Sage Calm | `84B59F` | `69A297` | `50808E` | `2D3D35` | `7A9488` | | Cherry Bold | `990011` | `FCF6F5` | `2F3C7E` | `333333` | `8B6B6B` | Pick by topic, not by default — finance reads Midnight Executive, a product launch reads Coral Energy, safety / LOTO reads Cherry Bold. If the closest named theme is not quite right, blend (e.g. Forest primary + gold `D4A843` accent). Use **Text** on light fills, **Muted** for captions / axis / footer, `FFFFFF` or Secondary for body on dark fills. On dark backgrounds, text and chart series follow the Hard rules contrast floor above. ### Chart-choice decision table Wrong chart type kills the 3-second test: | Data shape | Use | Avoid | |---|---|---| | Category comparison (A vs B vs C) | `column` (vertical) / `bar` (≥ 6 categories, horizontal) | pie (slices merge), line (no time axis) | | Time series, 1–3 series | `line` | area (occlusion), bar (implies discrete) | | Part-of-whole, 2–5 slices | `pie` / `doughnut` | pie with 8+ slices (unreadable) | | Correlation / distribution | `scatter` | line (implies ordering) | | Multiple categories × metrics, dense | stacked `column` or heatmap | one chart per metric — consolidate | | KPI snapshot (single big number) | **Large-text shape** (60–72pt + ≤ 5-word sublabel), NOT a chart | gauge chart, tiny bar | Rule of thumb: if > 3 series and > 8 categories, split into two charts or switch to a table. ### Animation Use as much or as little as the brand and content call for — a formal finance deck trends to near-zero, a product launch can be more expressive. Animation is a tool, not décor. Three floors keep it from hurting the deck (none caps how much you use): - **Purposeful** — each one reveals or emphasizes (progressive bullet reveal, a build-up chart), never decorates. If it doesn't aid comprehension, cut it. - **Degrades gracefully** — pptx animation renders inconsistently across viewers (Keynote / Slides / web / mobile) and may not play at all, so every slide must read correctly as a *static* frame. Never hide essential content behind a reveal. - **Verify live** — animation is runtime-only; `view html` and screenshots can't see it, so confirm in a real presentation viewer before shipping. Taste steer (not a ban): `fade` / `appear` / a single `zoom-entrance` with snappy durations (~hundreds of ms) fit most decks; `bounce` / `swivel` / `spin` / `fly-from-edge` / dense multi-object choreography usually read amateur — reach for them only when the brand is deliberately playful. ### Layout patterns & data display Vary layout across slides — repeating the same pattern makes every slide feel identical. These are common building blocks, not the full set — pick one per slide, or build a layout outside the table when the content calls for it: | Pattern | When to use | Key measurement | |---|---|---| | **Two-column** (text left, visual right) | Concept + evidence; feature + screenshot | Each col ≈ 14-15cm; gap 1cm | | **Icon rows** (icon in filled circle + bold header + description) | Feature lists, benefits, team roles | Icon circle 1.5-2cm; 3-4 rows max | | **2×2 or 2×3 grid** (card tiles) | Quadrant analysis, SWOT, option comparison | Gap ≥ 0.76cm; consistent card height | | **Half-bleed image** (full left or right half, content overlay on other side) | Hero moments, case study openers | Image 16-17cm wide; content column ≥ 14cm | | **Large stat callout** (60-72pt number + ≤5-word sublabel below) | Single KPI, milestone, market size | Use shape, NOT a chart; sublabel 14-16pt muted | **Data display quick rules:** - Comparison columns (before/after, A vs B) beat a table for 2-3 options. - Timelines and process flows: numbered step shapes + connectors, not a bullet list. ### Image treatment (only when a slide uses a photo / screenshot / logo) **Read the image first** (open the file) and choose treatment from what you see — don't place blind from a filename. - **Full-bleed photo** → size to COVER the region (crop edges), no border. - **Screenshot / diagram / logo** → size to FIT (never crop content). A transparent or fit image sits on a contrasting fill — drop a colored rectangle behind it, don't let it float on white. - **Text over a photo** → never raw on the image. Put it on a card, or lay a protection scrim between image and text (a dark rectangle at ~50–60% opacity, or a gradient fading from the text edge). - Never stretch (distort the aspect ratio); don't overlay text on a busy screenshot. - Prefer user-provided images / brand assets; no emoji or self-drawn art unless asked. ### Visual motif commitment Pick ONE distinctive element (rounded image frames, section numbers in filled circles, single-side border band, diagonal accent strips) and carry it to every slide — commit across the whole deck; styling one slide and leaving the rest plain reads as abandoned. A secondary motif is fine only if it doesn't compete with the primary. Declare it in your build plan first: `## Motif: numbered circles in brand color`. ### Visual AI-tells to avoid - **No decorative underline under slide titles.** A stripe / rule below a heading is the single most common AI-slide tell — use whitespace or a background-color change instead.