# easyppt — Automated PPT generation for DeepSeek Harness (dsh-plugin)

`easyppt` is a presentation-generation **dsh-plugin** for **DeepSeek Harness (DSH)**: an npm
package + Cordis bundle + bundled skill. Give it an outline (Markdown / JSON / plain text) and
optional illustrations, and it produces, via **DSH's native Univer toolchain**:

- **`<name>.pptx`** — standard 16:9, fully editable in PowerPoint / Keynote / WPS;
- **`build/<name>.html`** — a self-contained web slideshow for offline preview;
- **`build/<name>.manifest.json`** — a structured manifest (theme, palette, fonts, per-slide copy) for versioning.

> Design note: rendering is **not** re-implemented inside this plugin. `easyppt` owns **input
> validation, outline normalization, theme resolution, and the build manifest**. The actual
> slide rendering is model-driven: the agent, following the bundled `SKILL.md`, drives DSH's
> native `univer_*` tools (build → lint → screenshot → export editable .pptx). This reuses the
> harness's editable-export pipeline instead of writing a layout engine.

---

## Repository layout

```
easyppt/
├── package.json                # dsh-plugin metadata (dsh.bundle.patch / main / peerDeps)
├── cordis.patch.yml            # profile-bundle patch: inserts the easyppt plugin row
├── index.js                    # Cordis plugin: ppt_create / ppt_themes / ppt_template_list / ppt_template_upload + easyppt skill
├── lib/
│   ├── themes.json             # 10 built-in visual themes (id / scenario / colors / fonts / layout)
│   ├── themes.js               # theme library: list / get / resolve
│   ├── outline.js              # outline parser: Markdown / JSON / plain text → normalized deck
│   └── template-parser.js      # template upload validation + registry + style derivation from a Univer snapshot
├── skills/easyppt/
│   ├── SKILL.md                # generation workflow (theme tokens, per-page SVG, checks, export)
│   └── themes.json             # theme manifest bundled with the skill (resource directory)
├── preset/
│   ├── preset.yml              # preset display metadata
│   └── agent.cordis.yml        # "EasyPPT mode" agent preset (standard base + designer persona + skill layer)
├── docs/theme.schema.json      # JSON Schema for themes.json
└── README.md / README.en.md
```

---

## Install (one command)

Requires DeepSeek Harness (with `dsh-univer-office` providing the `univer_*` toolchain).
Peer dependencies (`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-skill`, `@deepseek-ai/cordis`)
are resolved from the DSH host automatically — nothing else to install.

### From GitHub (recommended)

```powershell
dsh plugin --profile web add https://github.com/<your-user>/easyppt
```

### From a local checkout (development)

```powershell
dsh plugin --profile web add ./easyppt        # or an absolute path
```

> `dsh plugin` is a thin pnpm forwarder: after installing, it automatically folds any dependency
> that declares `dsh.bundle.patch` into the profile's `dsh.profile.bundles` layer. **Restart DSH
> to activate.** No manual configuration is needed.

After installation the plugin:

1. registers 4 model-visible tools — `ppt_create`, `ppt_themes`, `ppt_template_list`,
   `ppt_template_upload`;
2. registers the bundled **easyppt** skill (theme library + generation workflow), loadable from
   any session.

Uninstall: `dsh plugin --profile web remove easyppt`.

### Optional: "EasyPPT mode" agent preset

To get a dedicated **EasyPPT** session mode in the DSH web console, copy `preset/` into the user
preset root:

```powershell
$dest = "$env:USERPROFILE\.dsh\.agent-presets\easyppt"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item -Recurse -Force "preset\*" $dest
Copy-Item -Recurse -Force "skills\easyppt" "$dest\skills\"
Copy-Item -Force "lib\themes.json" "$dest\skills\easyppt\themes.json"
```

Restart, then create a session with the **EasyPPT** preset to enter "PPT mode" (designer persona +
skill preloaded).

> Without the bundle, the `ppt_*` tools can still be tried in a single session by registering an
> equivalent dynamic plugin with `cordis_define` + `cordis_run` (see README). The core generation
> capability always comes from the skill + native `univer_*` tools.

---

## Usage

### One-liner (CLI / model instruction)

> `Please generate a deck on "AI Product Launch" with theme 'data' using easyppt` — and paste your
> outline and image paths.

Equivalent tool call:

```jsonc
ppt_create {
  title: "AI Product Launch",
  content: "# AI Product Launch\n## Market opportunity\n- Large market\n- Fast growth\n## Solution\n- Highlight 1\n- Highlight 2",
  theme: "data",
  lang: "en"
}
```

### Web (PPT mode)

1. New session → pick the **EasyPPT** preset (or just ask with "use easyppt").
2. Give a title, outline (paste Markdown / upload JSON), and drop illustrations into the workspace.
3. Optionally name a theme id or say "use this .pptx as the template".
4. The agent generates: scaffold `.univer` → per-page SVG → verify → export `.pptx` + HTML + manifest.

### Common commands

| Intent | Command |
| --- | --- |
| List all themes | `ppt_themes` (or `ppt_themes {format:"full"}`) |
| List all templates (built-in + custom) | `ppt_template_list` |
| Upload a custom template | `ppt_template_upload {file:"templates/company.pptx", name:"Company template"}` |
| Normalize + write build manifest | `ppt_create {title:"…", content:"…", theme:"business", lang:"en"}` |
| Open/edit the source | open `<name>.univer` in the workspace, or edit the exported `.pptx` |

---

## Built-in themes (10)

| id | Name | Scenario |
| --- | --- | --- |
| `data` | Tech dark | Tech, AI, big data, product launch, developer conferences |
| `business` | Business rational | Business analysis, project reports, cross-team reviews |
| `executive` | Executive report | Board, strategy, fundraising, exec briefings |
| `warm` | Warm & human | HR, training, team culture, NGO, user-experience reports |
| `minimal` | Minimal whitespace | Design, brand, portfolio, minimal products |
| `education` | Education & training | Courses, lectures, knowledge sharing |
| `finance` | Finance report | Banking, securities, funds, earnings, research |
| `health` | Healthcare | Hospitals, health products, clinical trials, medical talks |
| `startup` | Startup pitch | Fundraising, demo day, product launch |
| `academic` | Academic paper | Thesis defense, seminars, research reports |

Each theme in `lib/themes.json` defines complete `colors` (bg/panel/primary/secondary/accent/
text/muted/line…), `fonts` (title/heading/body family, weight, size), and `layout` (title bar,
footer, card radius, max bullets, recommended structure).

---

## Template management

Built-in themes need nothing extra. Custom templates, in three steps:

1. `ppt_template_upload` (or just drop a `.pptx` into the workspace) validates + registers it;
2. `univer_import` the `.pptx` into a draft worktree, then `univer_inspect` to read its palette/fonts;
3. derive the style with `deriveStyleFromSnapshot` from `lib/template-parser.js` (or summarize it
   yourself) and write it to `.easyppt/templates.json` in the workspace. The template is then
   selectable via `ppt_create template:<id>` like any built-in theme.

> Upload limits: `.pptx`, inside the session workspace, ≤ 20 MiB each.

---

## Quality gates

- Every page passes `univer_inspect` (structure) → `univer_lint` (text off-page / overflow /
  overlap) → `univer_screenshot` (rendered frame) before export.
- Theme tokens are respected (no invented colors/font sizes); `maxBullets` keeps pages readable.
- Illustrations must be workspace PNG/JPG/GIF ≤ 20 MiB, embedded via `<image>`.

---

## License

MIT. Univer integration provided by `dsh-univer-office`.