dsh-ppt 0.7.0 → 0.8.1

package/docs/USAGE.en.md

@@ -0,0 +1,194 @@
+# dsh-ppt usage guide
+
+[Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
+
+## Capabilities
+
+| Capability | Description |
+| --- | --- |
+| `ppt_create` tool | Markdown / structured slides → `*.html` + `*.pptx` + `*.json` |
+| `ppt_themes` tool | Lists the 5 built-in themes and their best use cases; pass `preview: true` with `outputDir` to write a side-by-side gallery plus one SVG palette card per theme |
+| 11 layouts | cover / section / bullets / statement / quote / table / closing / image / image-left / image-right / chart |
+| Speaker notes | `<!-- note: ... -->` comments or the `notes` field: press `S` in the HTML player; native PPTX notes slides (presenter view) |
+| Motion | On by default: HTML slide-in transitions + staggered bullet entrances; native PPTX fade transitions + click-to-reveal bullets. `motion: 'off'` / `--motion off` for a fully static deck |
+| Markdown extras | Tables (`\| ... \|`), blockquotes (`>`), and note comments are auto-detected into matching layouts |
+| `dsh-ppt` skill | A complete six-step SOP registered into DSH |
+| Standalone SKILL.md | Copy `skills/dsh-ppt/` into Claude Code / Cursor / Gemini CLI / Codex for cross-harness use |
+| Visual engine | Reuses the hyperframes visual style library; HTML and PPTX share the same theme source |
+
+Example:
+
+> Turn this sentence into a deck: "AI support cuts first response time to 8 seconds", with a dark tech theme.
+>
+> Turn `docs/quarterly-review.md` into a bilingual presentation and export PPTX.
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-ppt
+```
+
+On desktop, install `dsh-ppt` through plugin management. Restart the host after updating to load seven tools and the skill. Ask naturally to include screenshots/charts, edit only slide three, or undo the last edit; users do not need to write JSON.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-ppt
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+## Quick start
+
+### Inside DSH (recommended)
+
+```
+1. ppt_themes { preview: true, outputDir: "dist" }   # themes + gallery
+2. ppt_create {
+     title: "Fewer Meetings",
+     content: "# Problem\n- Too many meetings\n\n# Solution\n- Async decisions",
+     theme: "data",
+     lang: "en"
+   }
+3. Open the returned HTML path in a browser; edit the PPTX in PowerPoint / WPS / Keynote
+```
+
+### Any harness (standalone SKILL.md)
+
+Copy `skills/dsh-ppt/` to any Agent Skills directory, then:
+
+```bash
+node <skill-dir>/scripts/build-deck.mjs \
+  --title "Product Launch" \
+  --content deck.md \
+  --theme data \
+  --lang en \
+  --out dist/deck
+```
+
+Artifacts:
+
+Existing artifacts are not overwritten by default: if any member of the trio already exists, the whole set receives a shared `-1`, `-2`, ... suffix. Replacement requires explicit `overwrite: true` (or `--overwrite` in the CLI).
+
+| File | Purpose |
+| --- | --- |
+| `*.html` | Standalone slideshow: arrow keys, V presenter view (separate window with real current/next previews, thumbnail strip, notes, timer, progress, pause, font size, blank screen), S notes, G thumbnail overview, F fullscreen, P print, ? shortcuts, Esc close |
+| `*.pptx` | Editable 16:9 presentation (hand-written OOXML, zip via `node:zlib`, no third-party deps) |
+| `*.json` | Structured manifest (version, theme, language, slides) |
+
+## Images, charts, editing and review
+
+### Lightweight Settings editor (0.8.0)
+
+Open Settings → Presentations and choose a project registered by `ppt_create`, `ppt_edit` or `ppt_check`. Select a page to edit text, bullets and speaker notes; clicking text in the HTML preview focuses its field. Upload PNG/JPEG images, reorder pages and undo changes. Saving regenerates HTML, PPTX and JSON together.
+
+Save or cancel pending changes before switching pages, reordering, downloading or rendering. A stale revision cannot overwrite another writer's changes. Use “Load latest, keep my input”, review overlapping fields, then explicitly save. The HTML preview and actual PPTX rendering are separate; edits invalidate previous renders. Review every rendered page and font diagnostics before downloading the latest files. The editor works with this plugin's own JSON projects; it does not import arbitrary external PPTX files, and ordinary generation/editing does not need the optional renderer.
+
+The additional tools are `ppt_templates`, `ppt_edit`, `ppt_undo`, `ppt_check`, and `ppt_render`. New layouts are `image`, `image-left`, `image-right` and `chart`, alongside the seven existing layouts.
+
+An image slide accepts `image: {src, alt, fit: "contain"|"cover", caption}`. Use local PNG/JPEG paths relative to session cwd or matching data URIs. Assets are embedded in all outputs and undo works after original files move. Limits: 5 MiB / 32 megapixels per image, 32 MiB total project assets. Remote links and SVG are not automatically downloaded or converted.
+
+A chart accepts `chart: {kind:"column"|"bar"|"line"|"pie", categories, series:[{name,values}], unit, caption}` or `rows` with a category/series header. Values must be finite with matching lengths. Pie requires one nonnegative series with a positive total. HTML uses accessible SVG and data tables; PPTX contains native charts and embedded editable workbooks.
+
+`brand` supports `name`, `primaryColor`, `backgroundColor`, `textColor`, `fontFamily`, `logo` and `footer`. Colors are `#RRGGBB`; select a font available on the recipient computer. `template` is `weekly|defense|project|pitch` and does not overwrite a supplied narrative.
+
+Edit example: `{deckPath:"report.json",expectedRevision:0,edits:[{slide:3,patch:{title:"A clearer conclusion",bullets:["Evidence","Next action"]}}]}`. Use `ppt_check` to obtain stable IDs and the revision; `ppt_undo` restores the latest edit including assets/brand. Keeps up to 20 edits and rejects stale revisions. The artifact trio is regenerated atomically with rollback on commit failure.
+
+`deliveryStatus: draft` means unfilled slots; `ready-for-review` means review can start. Static estimates, rendering and visual inspection are recorded separately. Generation/rendering never automatically certifies visual quality. Inspect HTML and every page image before delivery.
+
+## Optional PNG/PDF renderer
+
+Install in the plugin's project or standalone skill directory:
+
+```bash
+npm install --ignore-scripts @deepseek-ai/libreoffice-kit@0.1.5
+```
+
+The exact optional peer is not a mandatory engine download for ordinary consumers. Windows also needs the Microsoft Visual C++ v14 runtime matching Node's architecture. Missing dependency/engine returns `unavailable` with guidance.
+
+`ppt_render {pptxPath:"report.pptx",format:"both"}` reads the final PPTX without resaving it and returns page PNGs, PDF and `receiptPath`. Pass that path as `renderReceipt` to `ppt_check` to recheck the current PPTX and every output's digest. Editing the source or outputs invalidates the receipt. Static artifacts do not retain animation. LibreOffice/PowerPoint/WPS may lay out files differently; font diagnostics do not guarantee every glyph or install fonts. See [integration details](../docs/LIBREOFFICE-INTEGRATION-2026-10-01.md).
+
+This repository's pnpm overrides are not inherited by consumers. If an installed renderer's audit reports `fflate@0.8.2`, set `overrides: { "@deepseek-ai/libreoffice-kit": { "fflate": "0.8.3" } }` in the consumer's root package.json (npm), or `overrides: { "@deepseek-ai/libreoffice-kit>fflate": "0.8.3" }` in its root pnpm-workspace.yaml, then reinstall. The plugin also validates PPTX/ZIP64 bounds before rendering; that check does not replace updating the underlying dependency.
+
+CLI supports `--slides @slides.json`, `--brand @brand.json`, `--template weekly`, `--edit report.json --edits @edits.json --revision 0`, `--undo report.json --revision 1`, `--check report.json`, and `--render report.pptx --format both`. Explicit receipt validation uses `--check report.json --render-receipt path/to/render-receipt.json`; failure returns a nonzero exit code.
+
+For standalone usage copy the entire skill directory and run `npm install --ignore-scripts` there. Plain text remains usable without Office Kit; image/chart/logo/footer PPTX export needs Office Kit 0.21.0. `dsh-ppt/deck-advanced` exports `buildDeckAsync`, `editDeck`, `undoDeck`, `checkDeckAsync` and `renderDeck`. The legacy synchronous `deck-core` API supports plain text and explicitly rejects unsupported media inputs.
+
+## Theme palette
+
+| ID | Name | Mood | Best for |
+| --- | --- | --- | --- |
+| `data` | Data Drift (default) | Futuristic / immersive | AI, tech launches, research |
+| `swiss` | Swiss Pulse | Precise / rational | Data, SaaS, developer tools |
+| `velvet` | Velvet Standard | Premium / restrained | Executive decks, brand, investor pitches |
+| `soft` | Soft Signal | Warm / human | Brand stories, training, personal talks |
+| `bold` | Maximalist Type | Loud / kinetic | Product launches, events, big moments |
+
+Themes are derived from [dsh-hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) `visual-styles.md`. Full palettes: `skills/dsh-ppt/references/themes.md`. Run `ppt_themes { preview: true, outputDir: "dist" }` for a side-by-side gallery and SVG palette cards.
+
+## Markdown input rules
+
+- The first `# heading` becomes the cover title; its first paragraph becomes the cover subtitle.
+- Each `## section` becomes one slide: lists produce `bullets` slides; empty sections produce `section` dividers.
+- Plain text without headings: the first paragraph is the cover, then every 5 sentences become one slide.
+- A single sentence automatically produces a complete 3-slide structure: cover → core idea → closing.
+- Long tables paginate automatically with repeated headers and up to 8 data rows per page. Notes stay on the first page. Tables support 8 columns and 60 characters per cell; oversized input returns an actionable error. Short rows are padded consistently in all artifacts.
+- `maxSlides` counts pages after expansion. Exceeding it fails before writing files; raise the limit (up to 120) or split the deck. Middle slides are never silently discarded.
+- For precise control, use structured `slides` (`cover | section | bullets | statement | quote | table | closing`), with `rows` for tables and `notes` for speaker notes.
+
+## Configuration
+
+No required configuration. Optional:
+
+```yaml
+- id: dsh-ppt
+  config:
+    outputDir: E:\decks   # optional; defaults to the session working directory
+    maxSlides: 40         # optional; default 60 (3–120)
+    defaultTheme: data    # optional; used when ppt_create has no theme
+    defaultLang: en       # optional; used when ppt_create has no lang (zh/en/bilingual)
+```
+
+The `DSH_PPT_OUTPUT_DIR` env var can also set the default output directory; the `ppt_create` `outputDir`/`theme`/`lang` arguments have the highest priority.
+
+Relative paths and configured output directories resolve per session cwd without changing process cwd. Cancellation is checked during generation and before atomic commit of the trio. Optional rendering defaults to a unique `<deck>-render` directory beside the PPTX.
+
+## Bilingual support
+
+- `lang` argument: `zh` (default) / `en` / `bilingual` controls the player UI, page numbers, and closing defaults.
+- Content language is up to the author: for a bilingual deck, prefer "Chinese title + English subtitle" or generate two decks from the same outline.
+- Plugin docs come in Chinese (README.md) and English (this file); CLI and skill error messages are in Chinese.
+
+## Engineering quality
+
+- Tools and the skill share an asynchronous generator. The legacy synchronous plain-text API remains available.
+- Images and native charts use MIT-licensed `@office-kit/pptx@0.21.0`; optional rendering is loaded on demand.
+- Unit tests cover registration contracts, JSON Schema, theme resolution, Markdown parsing, artifact generation, PPTX part integrity, and the CLI.
+- No `eval` / `child_process` / secrets; artifacts are only written to the user-specified local directory.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build      # tsc → lib/
+pnpm test           # build + node --test (registration/config/engine/CLI)
+pnpm run smoke:cli  # bare CLI smoke test, generates .smoke-deck
+```
+
+## Known limitations
+
+- The PPTX uses a blank layout plus text boxes: text is editable in PowerPoint / WPS, but no smart master placeholders yet.
+- A one-sentence input produces a minimal 3-slide structure; for richer decks, expand the content into a Markdown outline first.
+- `bilingual` only localizes the player UI; it does not translate content.
+- Selected-page editing supports this plugin's JSON project, not arbitrary external PPTX editing.
+- Text fit checks are static estimates; inspect actual rendered output for clipping and font substitution.
+
+## License
+
+Plugin: MIT. Office Kit: MIT. Optional official LibreOffice Kit and its engine retain their own source/license/third-party notices. This community plugin is not officially maintained by DeepSeek.
+
+## Related projects
+
+- [dsh-hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) — HTML video skills (source of this plugin's visual styles)
+- [dsh-remotion](https://github.com/STARDUSTLC666/dsh-remotion) — React programmatic video skills
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — Email toolset

package/docs/USAGE.md

@@ -0,0 +1,209 @@
+# dsh-ppt 使用说明
+
+[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
+
+## 能力一览
+
+| 能力 | 说明 |
+| --- | --- |
+| `ppt_create` 工具 | Markdown / 结构化 slides → `*.html` + `*.pptx` + `*.json` 三件套 |
+| `ppt_themes` 工具 | 列出 5 套内置主题与适用场景；传 `preview: true, outputDir: "dist"` 生成主题对比页 + 每套一张 SVG 色板卡（可直接进 README/npm 首屏） |
+| 11 种页型 | 封面 / 章节 / 要点 / 核心观点 / 金句 / 表格 / 结束 / 整页图片 / 左图右文 / 左文右图 / 图表 |
+| `ppt_templates` | 周报、论文答辩、项目汇报、路演的大纲和草稿结构参考 |
+| `ppt_edit` / `ppt_undo` | 修改指定页、保留其他页，支持最多 20 次历史与修订号冲突保护 |
+| `ppt_check` | 只读质量检查，定位具体页的问题；可复核当前渲染收据 |
+| `ppt_render` | 可选官方引擎生成 PNG / PDF，保留源 PPTX，报告缺失字体 |
+| 品牌 | 共享颜色、字体、Logo、页脚，同步到 HTML 与 PPTX |
+| 演讲者备注 | `<!-- 备注: ... -->` 或 `notes` 字段：HTML 按 `S` 呼出，PPTX 原生备注页（演示者视图） |
+| 动效（motion） | 默认开：HTML 页间淡入 + 要点逐条入场；PPTX 原生转场 + 要点逐条点击显现；`motion: 'off'` / `--motion off` 产出纯静态 |
+| Markdown 进阶 | 表格（`\| ... \|`）、引用金句（`>`）、备注注释自动识别成对应页型 |
+| `dsh-ppt` 技能 | 完整 SOP 注册进 DSH：从一句话到成品 deck 的六步流水线 |
+| 裸 SKILL.md | 把 `skills/dsh-ppt/` 复制到 Claude Code / Cursor / Gemini CLI / Codex 即可跨 harness 使用 |
+| 视觉引擎 | 复用 hyperframes 视觉风格库，5 套主题 HTML 与 PPTX 同源同色 |
+
+示例对话：
+
+> 把这句话做成 PPT：「AI 客服把首次响应时间压缩到 8 秒」，主题用科技感深色。
+>
+> 把 `docs/季度汇报.md` 做成双语演示文稿，导出 PPTX。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-ppt
+```
+
+桌面版可在插件管理中安装 `dsh-ppt`。更新后重启对应宿主，加载七个工具与 `dsh-ppt` 技能。无需手写 JSON，可直接要求 Agent「加入这两张截图和销售图表」「只修改第三页」「撤销上次修改」。
+
+## 快速开始
+
+### DSH 内（推荐）
+
+```
+1. ppt_themes { preview: true, outputDir: "dist" }   # 看 5 套主题 + 生成对比页
+2. ppt_create {
+     title: "把会议减半",
+     content: "# 问题\n- 周会太多\n\n# 方案\n- 异步决策",
+     theme: "data",
+     lang: "zh"
+   }
+3. 打开返回的 HTML 路径（浏览器放映），PPTX 用 PowerPoint / WPS / Keynote 编辑
+```
+
+### 任意 harness（裸 SKILL.md）
+
+把整个 `skills/dsh-ppt/` 复制到任意 Agent Skills 目录，在技能目录运行 `npm install --ignore-scripts`，然后：
+
+```bash
+node <skill-dir>/scripts/build-deck.mjs \
+  --title "产品发布" \
+  --content deck.md \
+  --theme data \
+  --lang zh \
+  --out dist/deck
+```
+
+输出三件套：
+
+默认不会覆盖已有同名产物：三件套中任一文件存在时会整组追加 `-1`、`-2`… 后缀；只有显式传 `overwrite: true`（CLI 为 `--overwrite`）才会覆盖。
+
+| 文件 | 用途 |
+| --- | --- |
+| `*.html` | 独立网页放映：← → 翻页，V 演讲者视图（独立窗口：真实当前页/下一页预览、缩略图跳页、备注、计时、进度、暂停、字号、黑/白屏），S 备注，G 缩略图总览，F 全屏，P 打印，? 快捷键，Esc 关闭 |
+| `*.pptx` | 16:9 原生可编辑文字、表格、图片和图表，保留备注与转场 |
+| `*.json` | 工程、图片资产、页面 ID、修订号、最多 20 次修改历史和质量报告 |
+
+## 图片、图表、编辑与交付
+
+### 设置页轻量编辑（0.8.0）
+
+打开「设置 → 演示文稿」，选择由 `ppt_create`、`ppt_edit` 或 `ppt_check` 登记的本插件工程。点击页码，修改标题、正文、要点和演讲备注；也可点击 HTML 预览中的文字定位字段。上传 PNG/JPEG 会嵌入工程并同步生成 PPTX。页面上移/下移与文字修改均可撤销。
+
+保存会同时更新 HTML、PPTX 和 JSON。未保存时先保存或取消，再切换页面、排序、下载或渲染。若助手同时修改了工程，旧修订不会覆盖新文件；点击「载入最新版本，保留我的输入」后检查重叠字段，再明确保存。
+
+「HTML 预览」用于检查放映效果；安装可选引擎后，「渲染当前 PPTX」生成实际 PPTX 的逐页图片。编辑后旧渲染自动失效。最终交付前逐页检查图片和缺失字体提示，随后下载最新 PPTX / HTML，或备份 JSON 工程。面板仅编辑自产 JSON 工程，不导入任意外部 PPTX；普通生成和编辑不需要可选渲染引擎。
+
+结构化 slides 新增 `image | image-left | image-right | chart`。图文页示例：
+
+```json
+{ "layout": "image-left", "title": "新版流程减少操作步骤", "image": { "src": "assets/screenshot.png", "alt": "新版流程截图", "fit": "contain" }, "bullets": ["填写内容后即可生成", "修改指定页保留其他页"] }
+```
+
+图片只接受本地 PNG/JPEG 或对应 data URI；相对路径按会话工作目录解析。图片嵌入三件套，原文件移走后仍可使用并撤销修改。每张最多 5 MiB / 3200 万像素，工程图片总量最多 32 MiB。不自动下载外链或转换 SVG。`fit` 为 `contain`（完整显示）或 `cover`（居中裁切）。
+
+图表示例：
+
+```json
+{ "layout": "chart", "title": "完成量逐月增加", "chart": { "kind": "column", "categories": ["七月", "八月", "九月"], "series": [{ "name": "完成量", "values": [3, 5, 9] }], "unit": "项" } }
+```
+
+支持 `column | bar | line | pie`，也可传 `rows`（首行为类别列和系列名）。数值必须有限、数据长度一致；饼图要求一个非负系列且总和大于零。HTML 使用 SVG 与读屏数据表，PPTX 使用原生图表与可编辑工作簿。
+
+`brand` 支持 `name`、`primaryColor`、`backgroundColor`、`textColor`、`fontFamily`、`logo`、`footer`。颜色用 `#RRGGBB`，字体选择接收方电脑可用的字体。`template` 为 `weekly | defense | project | pitch`，提供正文时不会替换原大纲。
+
+编辑示例：`ppt_edit { deckPath: "report.json", expectedRevision: 0, edits: [{ slide: 3, patch: { title: "新的结论", bullets: ["依据一", "下一步"] } }] }`。先用 `ppt_check` 获取页码/ID/修订号，再修改；`ppt_undo` 撤销最近一次修改，恢复图片、图表和品牌。编辑和撤销更新整套文件，失败会回滚。
+
+`deliveryStatus: draft` 表示模板未填完；`ready-for-review` 表示可开始检查。静态估算、PPTX 渲染和视觉检查分开记录。生成或渲染成功不会自动代表视觉验收通过，应查看 HTML 和每页图片，修正问题后交付。
+
+## 可选 PNG / PDF 渲染
+
+在插件所在项目或独立技能目录安装：
+
+```bash
+npm install --ignore-scripts @deepseek-ai/libreoffice-kit@0.1.5
+```
+
+声明为精确版本可选 peer，普通消费者安装不要求引擎。Windows 还需与 Node 架构匹配的 Microsoft Visual C++ v14 运行库。缺失时 `ppt_render` 返回 `unavailable` 和安装提示。
+
+本仓库的 pnpm 依赖覆盖不会传递到消费项目。安装引擎后如审计提示其 `fflate@0.8.2`，在消费项目根配置 `overrides: { "@deepseek-ai/libreoffice-kit": { "fflate": "0.8.3" } }`（npm），或在根 `pnpm-workspace.yaml` 配置 `overrides: { "@deepseek-ai/libreoffice-kit>fflate": "0.8.3" }`，然后重新安装。插件渲染前另有 PPTX/ZIP64 边界校验，但不替代底层依赖更新。
+
+`ppt_render { pptxPath: "report.pptx", format: "both" }` 读取最终 PPTX，生成逐页 PNG、PDF 和 `render-receipt.json`，不重新保存可编辑源文稿。`ppt_check` 可携带返回的 `receiptPath` 作为 `renderReceipt`，核验源文件和每个输出的摘要；编辑源文稿或修改输出后旧收据失效。静态产物不保留动画；LibreOffice 与 PowerPoint/WPS 的排版可能不同。字体诊断不保证每个字符，也不自动安装字体。更多细节见 [渲染说明](../docs/LIBREOFFICE-INTEGRATION-2026-10-01.md)。
+
+CLI 支持 `--slides @slides.json`、`--brand @brand.json`、`--template weekly`、`--edit report.json --edits @edits.json --revision 0`、`--undo report.json --revision 1`、`--check report.json`、`--render report.pptx --format both`。收据核验用 `--check report.json --render-receipt path/to/render-receipt.json`；失败返回非零退出码。
+
+## 内置主题
+
+| ID | 名称 | 情绪 | 适用 |
+| --- | --- | --- | --- |
+| `data` | 数据漂移（默认） | 未来 / 沉浸 | AI、技术发布、研究 |
+| `swiss` | 瑞士脉冲 | 精准 / 理性 | 数据、SaaS、开发者工具 |
+| `velvet` | 天鹅绒标准 | 高级 / 克制 | 高管汇报、品牌、融资路演 |
+| `soft` | 柔和信号 | 温暖 / 人本 | 品牌故事、培训、个人分享 |
+| `bold` | 极繁大字 | 大声 / 动能 | 产品发布、活动、大事件 |
+
+主题灵感来自 [hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) 的 `visual-styles.md`，完整色板见 `skills/dsh-ppt/references/themes.md`。也可运行 `ppt_themes { preview: true, outputDir: "dist" }` 生成并排对比页与 SVG 色板卡。
+
+## Markdown 输入规则
+
+- 第一个 `# 标题` → 封面标题；其下第一段 → 封面副标题。
+- 每个 `## 小节` → 一页：有列表生成 `bullets` 页，无内容生成 `section` 过渡页。
+- 没有标题的纯文本 → 第一段作封面，后续每 5 句一页。
+- 只有一句话 → 自动生成「封面 → 核心观点 → 结束页」三页完整结构。
+- 长表格自动分页：每页重复表头，最多 8 行数据；备注只放第一页。最多 8 列、每格 60 字符，超限会提示拆分。短行补空白，三种产物保留相同数据。
+- `maxSlides` 计算分页后的总页数；超过限制时先报错，不落盘、不静默删掉中间页。可提高配置上限（最多 120）或拆分文稿。
+- 需要精确控制时用结构化 `slides`（`cover | section | bullets | statement | quote | table | closing`），表格使用 `rows`，备注使用 `notes`。
+
+## 配置
+
+插件无必填配置。可选：
+
+```yaml
+- id: dsh-ppt
+  config:
+    outputDir: E:\decks   # 可选；默认会话工作目录
+    maxSlides: 40         # 可选；默认 60（3–120）
+    defaultTheme: data    # 可选；ppt_create 未指定 theme 时使用
+    defaultLang: zh       # 可选；ppt_create 未指定 lang 时使用（zh/en/bilingual）
+```
+
+也可用环境变量 `DSH_PPT_OUTPUT_DIR` 指定默认输出目录；`ppt_create` 的 `outputDir`/`theme`/`lang` 参数优先级最高。
+
+输出目录按每次调用的会话 cwd 解析，相对路径与插件配置保持一致，不修改进程 cwd。生成阶段及提交前检查取消，三件套一起提交或回滚。可选渲染默认写入 PPTX 旁的 `<名称>-render`，已有目录会追加后缀。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-ppt
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
+## 中英双语
+
+- `lang` 参数：`zh`（默认）/ `en` / `bilingual`，控制播放器界面、页码与结束页默认文案。
+- 内容语言由你撰写：双语 deck 推荐「中文标题 + 英文副标题」，或同一大纲分别生成中英两份。
+- 插件文档提供中英两版（README.md / README.en.md）；CLI 与技能的报错提示为中文。
+
+## 工程质量
+
+- 技能和工具共用异步生成器；纯文本的旧同步 API 保留，媒体输入会明确要求 `buildDeckAsync`。
+- 图片与原生图表采用 MIT 的 `@office-kit/pptx@0.21.0`；可选渲染引擎按需加载。
+- 单元测试覆盖注册契约、JSON Schema、主题解析、Markdown 解析、三件套落盘、PPTX 部件完整性、CLI。
+- 无 `eval` / `child_process` / 密钥；产物只写用户指定的本地目录。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run build      # tsc → lib/
+pnpm test           # 构建 + node --test（注册/配置/引擎/CLI）
+pnpm run smoke:cli  # 裸 CLI 冒烟，生成 .smoke-deck
+```
+
+## 已知限制
+
+- PPTX 采用空白版式 + 文本框实现：PowerPoint / WPS 中可正常编辑文字，但暂不生成智能母版占位符。
+- 一句话输入自动生成三页最小结构；更丰富的内容需要先扩写成 Markdown 大纲再调用 `ppt_create`。
+- `bilingual` 只双语化播放器界面，不自动翻译内容。
+- 按页编辑仅支持本插件 JSON 工程，不导入任意外部 PPTX 编辑。
+- 文字大小与溢出检查是静态估算；实际裁切和字体替换必须查看渲染画面。
+
+## 协议
+
+插件 MIT；Office Kit MIT；可选官方 LibreOffice Kit 及其引擎保留各自许可、来源与第三方声明。使用官方库不表示本插件由 DeepSeek 官方维护。
+
+## 相关项目
+
+- [dsh-hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) — HTML 视频创作技能（本插件视觉风格来源）
+- [dsh-remotion](https://github.com/STARDUSTLC666/dsh-remotion) — React 编程式视频技能
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套

package/docs/VALIDATION.md

@@ -0,0 +1,17 @@
+# dsh-ppt 验证记录
+
+[0.8.1 中英文界面验收](validation-language-2026-10-03.md)。
+
+本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
+
+## 最新记录
+
+[0.8.0 Windows 与浏览器操作验收](validation/0.8.0.md)：113 项测试、编辑/冲突恢复、三种实际下载、五页官方引擎渲染及 390px 布局。桌面窗口内的新功能逐项操作待验收。
+
+## 原中文记录
+
+插件和独立技能均要求 Node `^22.19.0 || >=24.0.0`。插件无需密钥或必填配置，可选渲染引擎缺失不会阻止普通启动与生成。Windows 示例已通过浏览器操作、真实 Microsoft PowerPoint 打开/逐页导出，以及官方 Kit 原生渲染；具体产物仍需逐页检查。
+
+## Original English record
+
+Plugin and standalone skill require Node `^22.19.0 || >=24.0.0`. No API key or mandatory configuration. The optional renderer is loaded on demand and its absence does not prevent startup or ordinary creation. Windows samples have been exercised in the browser, opened/exported in Microsoft PowerPoint, and rendered using the official Kit; review the actual pages for each new deck.

package/docs/validation/0.8.0.md

@@ -0,0 +1,10 @@
+# 0.8.0 验收（2026-10-02，Windows）
+
+- 官方宿主：DeepSeek Harness 0.2.0-rc.2 / master 639ed01。隔离 DSH_HOME，使用合成工程和图片，没有复制个人密钥、账号或日程。
+- Windows Node 24.16.0：113 项测试通过，无失败/跳过；包含原子保存/撤销、稳定页面 ID 排序、过期修订拒绝、受限图片输入、同源请求和下载原始字节。
+- 真实浏览器：项目列表/空状态、字段定位、文字修改与取消、图片文件选择/替换、排序/撤销、重启后恢复、未保存保护、并发非重叠与重叠修改恢复均已操作。
+- 最终下载：从页面点击 PPTX、HTML、JSON 三个按钮，实际下载文件与修订 8 的源文件逐字节一致。修复 GET 路由缺失 requestBody 声明造成的下载失败。
+- 官方 LibreOffice Kit 0.1.5 的 Windows 原生引擎：修订 8 的五页 PPTX 渲染完成，逐页检查封面、要点、图片、原生图表和结束页；没有缺失字体报告。
+- 390px 窄屏：修正设置侧栏挤压编辑区、导航换行；编辑区宽 366px，页面无横向溢出，输入/取消和未保存保护通过。
+
+以上是浏览器实际操作与 Windows 原生渲染验证。该版本尚未在 DSH 桌面窗口内逐项操作，不能把网页版通过记成完整桌面验收。PowerPoint/WPS 的接收方字体和最终版式仍需按成品逐页复核。

package/docs/validation-language-2026-10-03.md

@@ -0,0 +1,16 @@
+# 0.8.1：中英文界面验收
+
+2026-10-03，Windows / Node 24.16.0。采用 E 盘独立 DSH_HOME、合成资料与无密钥 profile；用户资料、账号、密钥、桌面窗口与 VPN 保持原状。
+
+- 自动测试：114 项全部通过。
+- 可见 Web 操作：在中文和英文工作台分别编辑并保存标题；三份工程文件共用修订号，中文正文保留。英文质量提醒定位第 2 页；使用本机官方 Kit 从当前 PPTX 生成三页预览。
+- 宿主：官方 DSH 0.2.1-alpha.1 Web；官方 RC2 与 alpha SDK 同载 18 组件，110 工具、35 插件技能、19 输出样例注册与 schema 检查通过。无账号的健康结果不代表真实连接。
+- 边界：放映成品的语言跟随工程配置，工作台跟随宿主语言。最终排版仍需逐页检查。
+
+中英文共用同一份资料；界面翻译不会改写标题、正文、路径、引用或项目文件。系统文件选择控件和文件对话框跟随 Windows / 浏览器语言。未知技术诊断与原始引擎日志保留原文；英文界面提供操作恢复引导。
+
+此记录不代表原生桌面窗口内的新功能已逐项操作通过。发布包完整性、GitHub CI 与公开 npm 全新安装在发布时另行核对。
+
+## English scope
+
+The Chinese and English UI share the same data. UI translation preserves original content, paths and project files. Visible interactions were performed in an isolated official alpha Web profile; both RC2 and alpha SDK registration/schema checks passed. Native file controls use the OS/browser language, and original diagnostic logs are retained. Browser results do not certify native desktop interaction or real-service delivery.