agentpreso（agentpreso 演示文稿）

AgentPreso

AI-native presentation platform. Create, edit, and render professional slide decks through natural conversation.

Getting Started

1. Install the CLI

curl -fsSL https://agentpreso.com/install.sh | sh

Installs the agentpreso binary. Run agentpreso update later to get new versions.

2. Create an account

Sign up at https://app.agentpreso.com/register. An invite code is required during early access — run agentpreso login for details on how to request one.

3. Authenticate

agentpreso login

Prompts for email and password, then saves an API key locally. Verify with agentpreso whoami.

Reading Strategy (for AI agents)

Read this file first. Only read additional docs when needed:

• Building a custom theme? → docs/DESIGN-GUIDE.md, then the Custom Themes section below
• Adding charts/diagrams? → the Charts and Diagrams section below
• Logo handling? → the Logos section below

Don't front-load all references — read them just-in-time.

CLI Quick Reference

# Auth
agentpreso login                          # Authenticate
agentpreso whoami                         # Check current user

# Themes
agentpreso themes                         # List available themes
agentpreso themes show <name>             # Show theme details
agentpreso themes add <path>              # Upload custom theme directory
agentpreso themes update <name> theme.yaml  # Update theme from manifest
agentpreso themes update <name> --css f.css # Update raw CSS only
agentpreso themes delete <name>           # Delete custom theme

# Decks — local-first workflow
agentpreso new <file> -t <theme>          # Scaffold local markdown file
agentpreso push [file]                    # Push local file to cloud (creates or updates)
agentpreso pull <slug>                    # Download cloud deck to local file
agentpreso list                           # List cloud decks

# Rendering
agentpreso render <file> --format pdf     # Export to html, pdf, or pptx
agentpreso render <file> --var company="Acme" --vars data.yaml
agentpreso preview <file> -s 1            # Preview slide as PNG (for verification)
agentpreso serve <file>                   # Live preview server with hot reload

# Content generation
agentpreso add-graphic <slug> "prompt"    # AI-generate image into deck
agentpreso add-illustration <slug> --file drawing.yaml
agentpreso render-chart chart.yaml        # Render chart YAML to SVG
agentpreso render-diagram flow.mmd        # Render Mermaid to SVG

# Assets
agentpreso assets upload <file>           # Upload image for use in slides
agentpreso assets                         # List uploaded assets

# Sharing
agentpreso share <slug>                   # Generate public share link
agentpreso share <slug> --private         # Revoke public access

Workflow

AgentPreso uses a local-first workflow: edit markdown files locally, push to cloud for rendering.

1. Start: agentpreso themes — pick a theme that matches the tone
2. Create: Write a .md file (see format below), or agentpreso new deck.md -t corporate
3. Push: agentpreso push deck.md — uploads to cloud, prints a dashboard link (requires login)
4. Preview: agentpreso preview deck.md -s 1 — check each slide as PNG
5. Iterate: Edit the local file, re-push, re-preview until satisfied
6. Deliver: Always give the user the dashboard URL from push so they can view their slides
7. Export: agentpreso render deck.md --format pdf — check response for warnings
8. Share (optional, requires consent): Only if the user explicitly asks for a public link, run agentpreso share deck-slug. You MUST ask the user for confirmation before sharing — this creates a public URL accessible to anyone without authentication.

For cloud-only editing (no local file), use agentpreso pull <slug> to fetch, edit, then agentpreso push.

Previewing Slides

Use agentpreso preview <file> -s <n> to render a single slide as PNG. To review multiple slides, run preview for each slide index sequentially. Always preview after push to verify charts, diagrams, and images rendered correctly. If the preview shows a red error block, the chart/diagram has a syntax error — fix before continuing.

Sharing

WARNING: agentpreso share creates a PUBLIC link accessible to anyone without authentication. Never run this command without explicit user consent. The presentation may contain confidential information.

To generate a share link (only after the user confirms they want a public link):

agentpreso share <deck-slug>

To revoke public access:

agentpreso share <deck-slug> --private

Render Warnings

After rendering, check the response for warnings. If any chart, diagram, or image errors occurred, they appear in the warnings array. Fix all warnings before sharing — they indicate broken content in the rendered output.

Markdown Format

Standard markdown. Slides separated by ---. Deck-level frontmatter sets theme and options. Per-slide frontmatter sets layout and directives:

---
theme: corporate
paginate: true
---

# Title Slide

---
layout: bullets
---

## Content Slide

- Bullet points work naturally

---
layout: quote
---

> "Styled blockquote"
>
> — Attribution

Per-Slide Frontmatter

Each slide can have its own YAML frontmatter block (Slidev-style). The layout key maps to the slide's CSS class:

---
layout: bullets
---

## My Bullets
- Point A
- Point B

Supported per-slide keys: layout, class, transition, backgroundColor, backgroundImage, fragments, fragmentType, paginate, header, footer, color, style.

The layout key is the primary way to set a slide's layout. Alternative: <!-- _class: layout-name --> (HTML comment syntax, still supported).

Named Slots

For multi-column and container layouts, use ::name:: syntax to route content into named slots:

---
layout: two-col
---

## Comparison

::left::
### Option A
- First benefit

::right::
### Option B
- Different benefit

Available slot names: left, right, center, col, column, stat. The :::name...::: container syntax is also supported as an alternative.

Pagination directives

These can also be set via per-slide frontmatter: paginate: false, paginate: skip, paginate: hold.

Slide Layouts

Apply with per-slide frontmatter layout: layout-name (preferred) or <!-- _class: layout-name -->:

Opening & Closing

Content

Media

Data

Comparison

Dark Mode Per-Slide

Add invert to flip any slide to dark palette. Combine with layouts:

---
layout: invert title-hero
---

# Dark Opening Slide

Alternative syntax: <!-- _class: invert title-hero -->

Charts, diagrams, and images auto-adapt to dark background.

Images

Upload first, then reference by asset URI:

![Description](asset://asset_abc123)

Logos

Use an existing logo file (SVG or PNG). Download it first if needed:

curl -o logo.png "https://example.com/logo.png"
agentpreso assets upload logo.png

Then reference via asset URI in slides, or attach to a theme:

agentpreso themes add ./my-theme/ --logo logo.svg

Do NOT attempt to reconstruct logos from HTML/CSS/JS extraction — use intact image files.

Charts and Diagrams

type: bar data: labels: [Q1, Q2, Q3, Q4] datasets: - label: Revenue data: [10, 15, 12, 18]

graph LR A[Start] --> B[Process] --> C[End]

Template Variables

Define defaults in frontmatter, override at render time:

---
agentpreso:
  theme: corporate
  vars:
    company: "Acme Corp"
    deal_size: "$500K"
---

# Proposal for {{company}}
Deal size: {{deal_size}}

Override: agentpreso render deck.md --var company="Contoso" --var deal_size="$1.2M"

Or from a file: agentpreso render deck.md --vars overrides.yaml

Slide Design Principles

• Every slide needs visual structure — use layouts, bold hierarchy, tables, callouts, and stats. Charts and images are powerful but not required on every slide.
• One topic per slide — but density is OK. A table + callouts + stats serving one topic is better than 3 sparse slides.
• Match density to purpose — board decks and data analysis should be information-dense. Keynotes and narratives should breathe. There's no single right density.
• Create visual rhythm — vary layouts, alternate dense and simple slides, mix data with narrative. Don't repeat the same layout three times in a row.
• Bold text is your main tool — **bold** renders in heading color in bullets, tables, and stats. Use it to create visual anchors that guide the eye.
• Preview before done — always check with agentpreso preview before declaring finished.

Writing Beautiful Markdown

The CSS does heavy lifting — but only if you write markdown that gives it something to work with. These patterns produce noticeably better slides:

Bullet lists with bold titles: Lead each item with a bold phrase. The CSS renders the bold text in heading color, creating visual anchors:

- **Revenue grew 42%** — driven by enterprise expansion and seat upgrades
- **Net retention hit 130%** — expansion outpacing churn 6:1
- **Gross margin at 94%** — infrastructure migration cut per-query cost 44%

Nested bullets as descriptions: Sub-items render smaller in secondary color — like a title + description pattern:

- **Revenue grew 42%**
  - Driven by enterprise expansion and seat upgrades across all segments
- **Net retention hit 130%**
  - Expansion outpacing churn 6:1, with enterprise NRR at 145%

Tables with bold emphasis: Bold cells get heading color automatically. Use bold for the numbers you want to stand out:

| Metric     | Q3      | Q4        | Change       |
|------------|---------|-----------|--------------|
| ARR        | $6.8M   | **$10.2M**| **+50%**     |
| Customers  | 380     | **528**   | **+39%**     |

Blockquote callouts: Use blockquotes for contextual annotations. Lead with a bold title line:

> **Revenue on track**
> Q4 exceeded forecast by 12%, driven by enterprise expansion.

Stats with bold values: In stats-grid and stats-row layouts, bold text becomes the hero number:

Revenue
**$10.2M**

Data-Dense Slides

For board decks, financial reports, and analytical presentations, single-topic slides with multiple components create the most professional output. Use two-col or three-col layouts to combine:

• A table in one column showing the data
• Callouts in the other column providing context and interpretation
• Stat boxes summarizing key numbers

Example structure:

---
layout: two-col
---
## Revenue by Segment

::left::
| Segment | ARR | Growth |
|---------|-----|--------|
| Enterprise | **$5.8M** | **+68%** |
| Mid-Market | $2.9M | +41% |
| SMB | $1.5M | +12% |

::right::
> **Enterprise is the growth engine**
> Average ACV doubled from $119K to $200K.

> **SMB churn needs attention**
> 4.2% quarterly — 16% annualized.

This produces a slide with a clean data table on the left and interpretive callouts on the right — far more useful than splitting this across 3 slides.

Custom HTML Slides

For layouts not covered by built-in options, use layout: custom with raw HTML. The slide inherits theme variables but imposes no structural CSS.

Prefer component classes over inline styles. The base CSS includes pre-styled components that work across all themes:

Authoring priority:

1. Standard markdown with a named layout (best — simplest, most portable)
2. layout: custom with component classes (good — structured, theme-aware)
3. layout: custom with inline styles and theme variables (acceptable — one-off designs)
4. <style> or <script> blocks (forbidden — stripped at render time)

Semantic colors available in all components and via inline styles: var(--color-success), var(--color-warning), var(--color-danger), var(--color-info) — plus -light variants for backgrounds.

Example custom slide with components:

---
layout: custom
---

<div style="display: grid; grid-template-columns: 3fr 2fr; gap: 2rem; height: 100%;">
  <div class="card">
    <div class="card-title">Revenue by Segment</div>
    <!-- markdown table or HTML table here -->
  </div>
  <div>
    <div class="callout callout-success">
      <h5>Enterprise is the engine</h5>
      <p>ACV doubled to $200K. Net retention at 145%.</p>
    </div>
    <div class="callout callout-warning" style="margin-top: 1rem;">
      <h5>SMB churn rising</h5>
      <p>4.2% quarterly churn — needs the Growth tier.</p>
    </div>
  </div>
</div>

Diagrams and Charts — Layout Rules

Be cautious mixing long lists with large visuals. If a chart or diagram shares a slide with bullets, keep the list short (3-4 items max) and use two-col or figure layout to give each element room. The renderer will warn if content overflows.

For detailed theme design guidance (color palettes, typography, CSS variables, logo placement), see docs/DESIGN-GUIDE.md.

Built-in Themes

Custom Themes

Create a directory with theme.yaml (required), optional overrides.css and scaffold.md, then:

Font limitation: Only web-safe and Google Fonts render correctly. Proprietary fonts (e.g., CiscoSans, BrandFont) will fall back to system fonts. Use close alternatives: Inter, DM Sans, Source Sans Pro, etc.

Theme Customization Strategy

Use theme.yaml manifest options (colors, fonts, imagery) for all standard customization. Do NOT create overrides.css unless the user explicitly requests styling that cannot be achieved through theme.yaml parameters. The manifest covers colors, fonts, spacing, imagery guidance, and layout preferences — overrides.css is a last-resort escape hatch, not a default tool.

Usage:

agentpreso themes add ./my-theme/
agentpreso themes add ./my-theme/ --logo logo.svg --logo-position bottom-right --logo-size small

To update an existing theme, point to the theme.yaml file directly:

agentpreso themes update my-brand ./my-theme/theme.yaml

This re-assembles CSS from the manifest, auto-discovers overrides.css and logo files from the same directory, and updates the theme in-place (preserving logo asset IDs when logos haven't changed).