PPT Template Reuse

ppt-template-reuse is a local-first, host-neutral engine that learns what a native PowerPoint template is for and turns user material into a content-complete, editable deck with speaker notes and rendered QA.

The package is one system with four layers:

1. core: deterministic source extraction, template inspection, adaptive planning, native OOXML editing, rendering, and validation;
2. ppt-reuse: a resumable command-line interface;
3. MCP: nine stable tools for any compatible AI host;
4. Skill adapters for Codex, Claude Code, Kimi Code, Kimi Work, and WorkBuddy.

The host AI supplies semantic judgment. The local engine keeps every source anchor, freezes the plan, edits PPTX objects, and enforces quality gates. It does not need a separate model API key.

Status

The current package version is 0.4.0-rc.2. It is a release candidate for macOS and Windows. Linux is covered by core/protocol CI but is not yet a declared desktop compatibility target.

Requirements

• Node.js 20 or 22;
• LibreOffice for final rendering and acceptance;
• a native .pptx or .potx template;
• one of .docx, .pdf, .pptx, .md, or .txt as source material.

Macro-enabled .pptm files are rejected and macros are never executed. Scanned PDF pages are returned to the host AI as visual-analysis tasks.

Install

For a local checkout:

npm install
npm install -g .
ppt-reuse doctor --host all
ppt-reuse install --auto

After the release candidate is published to npm:

npm install -g ppt-template-reuse@next
ppt-reuse install --auto

install --auto detects supported hosts, shows and records the files it changes, creates timestamped backups, merges MCP configuration idempotently, and installs the same Skill workflow. Kimi Work and WorkBuddy still require one explicit import/trust confirmation in their UI.

Codex plugin

The repository also remains a Codex Marketplace:

codex plugin marketplace add NEU-ZHA/ppt-template-reuse --ref v0.4.0-rc.2
codex plugin add ppt-template-reuse@ppt-template-reuse

The plugin calls the public local MCP engine; it no longer depends on Codex's built-in Presentations Skill or @oai/artifact-tool.

Claude Code

adapters/claude/ contains .claude-plugin/plugin.json, a Skill, and .mcp.json. It can be distributed through a Claude Code plugin marketplace or installed by ppt-reuse install --auto.

Kimi Code and Kimi Work

adapters/kimi/ contains kimi.plugin.json with the Skill and MCP declaration. adapters/kimi-work/ is an import-ready local Skill plus a separate MCP file.

WorkBuddy

adapters/workbuddy/ contains the uploadable Skill and local MCP declaration. The release builder emits a Skill-only WorkBuddy ZIP plus a separate MCP JSON, so the Skill importer receives the expected SKILL.md package.

Natural use

After the one-time installation and trust confirmation, the user can simply say:

参考这个模板和这些材料，做一份内容完整、可编辑、带讲稿的PPT。
根据材料多少自动决定页数；缺图片就先集中告诉我；逐页显示真实预览。

The Skill drives this sequence automatically:

create session → inspect → submit semantics → freeze plan
→ supply required assets → generate → poll previews → validate

Users do not need to know the MCP tool names or write JSON.

CLI

ppt-reuse create \
  --template "/absolute/path/template.pptx" \
  --source "/absolute/path/source.docx" \
  --output "/absolute/path/result.pptx" \
  --root "/absolute/path" \
  --duration 12-15 \
  --density rich

ppt-reuse status <session-id>
ppt-reuse resume <session-id>
ppt-reuse mcp --stdio
ppt-reuse serve --host 127.0.0.1 --port 8765

# Import a previously reviewed, SHA-bound template capsule:
ppt-reuse import-capsule \
  --capsule "/absolute/path/reviewed-capsule" \
  --template "/absolute/path/template.pptx" \
  --opening 3 \
  --closing 10 \
  --approve 26

Sessions live under ~/.ppt-template-reuse/sessions/. Template profiles live under ~/.ppt-template-reuse/library/. Existing ~/.codex/ppt-template-reuse/library/ capsules are indexed as read-only legacy references and are never moved or deleted.

The CLI exposes the mechanical engine. In normal use, an AI host completes the semantic packages returned by ppt_inspect before planning.

MCP contract

• ppt_create_session
• ppt_inspect
• ppt_submit_semantics
• ppt_plan
• ppt_supply_assets
• ppt_generate
• ppt_status
• ppt_validate
• ppt_cancel

Long generation uses persistent sessionId/jobId values and polling, not experimental MCP task APIs. Frozen plans, QA reports, outputs, and page previews are also available as ppt://session/... resources. Both stdio and loopback Streamable HTTP are supported.

Content completeness

• deterministic extraction records every paragraph, heading, table, slide, or PDF page with an immutable id and anchor, then splits oversized blocks into 300–400-character child units with preserved parent anchors;
• host semantics cannot omit, replace, or invent those ids;
• slide count grows with original character volume, independent claims, evidence, argument chains, template capacity, and speaking time;
• critical coverage must be 100%; weighted relevant coverage must be at least 95%;
• every included unit must trace to matching visible text or notes; original source-text trace coverage and critical visible coverage must both be 100%, while weighted visible coverage must be at least 90%;
• structured displayFragments carry dates, labels, steps, metric labels, and concise descriptions into timeline, process, comparison, and multi-item slots instead of forcing every page into generic claim/evidence boxes;
• original source text is stored in a clearly marked non-spoken trace block; speaking time is calculated from the talk track, and short material is not padded just to reach a requested minimum;
• every analysis page needs claim, evidence, why-it-matters, and native notes;
• counterarguments require mapped rebuttals;
• overloaded content is split instead of compressed with smaller fonts;
• missing visual assets block generation instead of becoming gray placeholders.

A previous 19-page deck is a private regression fixture for one source volume, not a global page target.

Public pressure tests cover 500–50,000 source characters, 1–100 pre-segmented semantic units, clustered and argument-chain structures, and one-, two-, and three-body-slot templates. They require monotonically increasing extraction and page counts, 100% traceable source coverage, and deterministic output in the same rendering environment.

The baseline scale test uses 5, 30, and 100 semantic units and currently yields 8, 33, and 103 pages on the synthetic three-body template. The character-volume test currently yields 4, 10, 19, 35, 66, and 160 pages for 500, 2,000, 5,000, 10,000, 20,000, and 50,000 source characters. These are regression observations, not hard-coded targets.

Fidelity and safety

The native OOXML layer rebuilds the presentation slide sequence while preserving untouched package parts, masters, layouts, themes, animations, SmartArt, media, and protected objects. It can rewrite declared text slots, replace inherited images, update matching table cells, and append native speaker notes.

Chart editing is fail-closed until both the visible cache and embedded workbook can be synchronized and rendered. Flattened decks are hybrid-locked and are never described as fully editable. Exact native generation never executes macros.

The engine only accepts declared roots, the current workspace, and temporary directories. It does not connect to the internet or upload templates and materials. A host may separately search or generate images when the user authorizes it.

Validation

npm run check:all
npm run privacy
npm run release:build

The test suite covers adaptive page growth, complete source coverage, three-run determinism, native notes, OOXML structure, optional real rendering, MCP schemas/resources, stdio and loopback HTTP, path rejection, macro rejection, installer idempotency, uninstall, and an environment-gated private golden fixture.

Final acceptance requires real LibreOffice rendering plus rendered-text fidelity checks between native PPTX text and exported PDF text. Missing or substituted glyphs keep the deck in validation-failed even when protected pixels pass. In that case WPS/PowerPoint compatibility remains manual-review-required until a person opens and smoke-tests the result.

Public release packages contain no user templates, course materials, local capsules, generated decks, personal paths, or platform tokens.