dsh-deck-builder

Readme

# dsh-deck-builder 📽️

> A DeepSeek Harness tool plugin: convert Markdown into a self-contained HTML presentation (slides) — themes, keyboard navigation, zero dependencies, zero core changes.

[English](./README.md) | [简体中文](./README.zh.md)

A **DeepSeek Harness (DSH)** pure tool plugin that registers the `deck_build` tool, letting the agent turn any Markdown (research reports, meeting notes, course outlines…) into a single-file HTML deck the user opens directly in a browser — `←`/`→` to navigate, `f` for fullscreen, one slide per page when printing. All generation logic is **zero-dependency pure functions**, and the output is fully self-contained (inline CSS/JS, no external assets, no network).

## ✨ Features

- **`deck_build` tool**: `markdown` → HTML slides, returns output path / slide count / bytes.
- **Three themes**: `deepseek` / `light` / `dark`, CSS variables inlined.
- **Smart splitting**: splits on `---` / `***` / `___` rules, falling back to H1/H2 headings when no rules exist.
- **Full Markdown rendering**: headings, paragraphs, ordered/unordered lists, code blocks, blockquotes, bold/italic, inline code, links, images.
- **Zero dependencies, zero core changes**: pure `ctx.tools.register`, no client bundle, no network, no external assets.
- **Pure-function tested**: splitting / rendering / escaping / self-containment all covered by unit tests.

## 📦 Install

Prereqs: DSH (`dsh web` works), Node ≥ 22.19, pnpm.

```bash
# From GitHub (prebuilt lib/ committed)
dsh plugin --profile web add "github:Blaczz/dsh-deck-builder#main"

# Local directory
cd dsh-deck-builder && npm install --legacy-peer-deps && npm run build
dsh plugin --profile web add ./dsh-deck-builder
```

**Restart `dsh web` after install**, then ask the agent to "turn this into slides" or have it call `deck_build` directly.

## 🎬 Usage

In a conversation, ask the agent to build a deck:

```
Turn this research report into slides using the deepseek theme:
<markdown content>
```

The agent calls `deck_build`, producing `deck-<title>.html`. Open it and use `←`/`→` or space to navigate, `f` for fullscreen, and print/export to PDF for one-slide-per-page.

Or call the tool manually:

```json
{
  "markdown": "# Title\nbody\n\n---\n\n# Slide 2\nmore",
  "title": "My Deck",
  "theme": "deepseek",
  "outputPath": "slides/my-deck.html"
}
```

## 🛠️ Development

```bash
npm install --legacy-peer-deps
$env:DSH_NODE_MODULES = "$env:USERPROFILE\.dsh\profiles\node_modules"
npm run setup:dsh-workspace
npm run verify                          # ★ one-shot gate: clean + typecheck + test + build
npm test                                # vitest (19 tests: splitting / rendering / self-containment / themes / escaping)
```

## Layout

```
dsh-deck-builder/
├── package.json            # dsh.bundle.patch (pure tool plugin, no client half)
├── cordis.patch.yml        # bundle patch layer
├── scripts/                # build (tsc only) / clean / setup-dsh-workspace / verify
├── src/
│   ├── deck.ts             # ★ pure generation: splitSlides / renderBlocks / renderDeck
│   ├── theme.ts            # theme tokens (light/dark/deepseek)
│   └── index.ts            # host half: registers the deck_build tool
└── tests/                  # deck generation + manifest contract
```

## 🧩 Ecosystem positioning

- **Fills a gap**: the DSH Slides/PPT category previously had only `dsh-openmaic` (teaching) and `dsh-k12-lesson-builder`; a general "Markdown → presentation" tool was missing, even though `mdPresenter` proved the demand.
- **Technical route**: pure tool plugin (`ctx.tools.register` + `defineTool`), reusing the self-contained-HTML artifact shape of `hccccc01333/dsh-report-html`.
- **Zero core changes**: single-file output + zero-dependency pure functions + `ctx.effect` registration.

## ⚖️ License

MIT © 2026 Blaczz. An independent community plugin, not affiliated with [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).