dsh-ppt 0.7.0 → 0.8.0

package/README.md

@@ -1,236 +1,44 @@
-[English](README.en.md)
-
 # dsh-ppt
 
-## 0.7.0 更新（2026-10-02）
-
-- 生成的 HTML 演示文稿增加上一页、下一页和页码跳转，支持键盘与触屏，390px 窄屏也可操作。
-- 新增“检查与导出”面板：查看质量提示与大纲，点击提示定位到对应页面，直接下载可编辑 PPTX 或保存项目 JSON。
-- 待补全草稿明确标记；静态检查仅供参考，交付前仍需目视检查。页面排版继续通过 Agent 项目编辑或 PowerPoint/WPS 完成。
-- 下载链接始终指向同组实际文件，兼容中文文件名与自动重命名；HTML、PPTX、JSON 三个文件保留原来的离线交付方式。
-- Windows 103 项测试及中英文浏览器实际操作通过。本次未验证原生 Office 或 DSH 桌面窗口。
-
-## 0.6.0 更新（2026-10-01）
-
-加入图文排版、四类原生可编辑图表、按页编辑和撤销、具体到页面的质量报告、四种场景结构参考与共享品牌。可选官方 LibreOffice Kit 可读取最终 PPTX，生成逐页 PNG / PDF 并报告缺失字体。修正网页总览缩略图重叠、PPTX 表格标题太小、图文说明间距和图表标签显示。
-
-原来的目标保持一致：Agent 整理内容和事实，插件生成可用成品。仅选择模板会生成明确标注的**待填写草稿**；生成器不会调查事实或编造缺失内容。应补齐正文、检查输出后再交付。
-
-默认 PPTX 字体与 HTML 的 CSS 字体栈分开处理，使用平台字体并明确东亚字体，避免把未安装的西文字体写成中文字体。缺失字体必须先替换、重新生成并检查；未解决时标注字体问题，不声称已验收。
-
-本次验证：Windows / Node 24.16.0，100项测试通过；官方源码构建 Harness 0.2.0-rc.2（639ed01539）中18组件共同加载，104工具/35技能契约通过。默认无品牌五主题15页已通过官方原生PNG/PDF渲染和逐页视觉检查；另有11页图片/图表/品牌示例经浏览器、Microsoft PowerPoint与官方Kit检查。此为这些样例的证据，不代表任意文稿自动通过。
-
-## 0.5.0 更新（2026-09-27）
-
-包含新的演讲者预览、缩略图和计时控件。浏览器不支持或拒绝全屏时显示操作提示，不再无声失败。
-
-验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-28）。70 项插件测试在隔离环境全部通过；同一个宿主里 18 个插件共同加载，注册 1 个技能、2 个工具，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务。
-
-> **一句话 / 一篇文档 → 完整演示文稿**：HTML 网页放映 + PPTX 导出，5 套视觉主题，页间转场 + 要点入场动画，中英双语。
-
-![npm version](https://img.shields.io/npm/v/dsh-ppt?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-ppt) ![license](https://img.shields.io/npm/l/dsh-ppt) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-ppt?style=social)
-
-[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
-
-DSH（DeepSeek Harness）演示文稿技能 + 工具插件：Agent 根据需求准备内容，再生成离线 **HTML 网页**、可编辑 **PPTX** 和 **JSON 工程**。图片与图表采用精确版本 `@office-kit/pptx@0.21.0`，共享 Node 生成流程支持 Windows / macOS / Linux。
-
-## 能力一览
-
-| 能力 | 说明 |
-| --- | --- |
-| `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。
-
-## 兼容性
-
-插件和独立技能均要求 Node `^22.19.0 || >=24.0.0`。插件无需密钥或必填配置，可选渲染引擎缺失不会阻止普通启动与生成。Windows 示例已通过浏览器操作、真实 Microsoft PowerPoint 打开/逐页导出，以及官方 Kit 原生渲染；具体产物仍需逐页检查。
-
-## 安装
-
-```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 次修改历史和质量报告 |
-
-## 图片、图表、编辑与交付
-
-结构化 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.3
-```
-
-声明为精确版本可选 peer，普通消费者安装不要求引擎。Windows 还需与 Node 架构匹配的 Microsoft Visual C++ v14 运行库。缺失时 `ppt_render` 返回 `unavailable` 和安装提示。
-
-`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) — 邮件六件套
+[English](README.en.md)
+
+把材料制作成 HTML 放映、可编辑 PPTX 和可继续修改的工程文件。
+
+[![npm](https://img.shields.io/npm/v/dsh-ppt)](https://www.npmjs.com/package/dsh-ppt) [![downloads](https://img.shields.io/npm/dm/dsh-ppt)](https://www.npmjs.com/package/dsh-ppt)
+
+## 功能
+
+- 生成图文、表格、原生图表和品牌化演示文稿。
+- 在设置页编辑文字和图片、调整页面顺序，并支持撤销。
+- 提供质量检查与可选的最终 PPTX 图片 / PDF 渲染。
+
+## 安装
+
+桌面版可在「插件」面板按包名 `dsh-ppt` 安装。已配置 dsh 命令时也可使用：
+
+```bash
+dsh plugin --profile desktop add dsh-ppt
+```
+
+网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
+
+## 开始使用
+
+可说：“把这份材料做成可直接交付的演示文稿，生成 HTML、PPTX 和工程文件。”0.8.0 起可在「设置 → 演示文稿」轻量修改自产工程，也可在 PowerPoint / WPS 中继续编辑 PPTX。
+
+## 依赖与配置
+
+普通生成不需要 Office。最终 PPTX 渲染使用可选的官方 LibreOffice Kit；依赖版本、字体环境和安装方法见使用说明。
+
+详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
+
+## 文档
+
+- [使用与排错](docs/USAGE.md)
+- [更新记录](CHANGELOG.md)
+- [验证范围与历史记录](docs/VALIDATION.md)
+- [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-ppt/issues)
+
+## License
+
+[MIT](LICENSE)

package/docs/CHANGELOG.en.md

@@ -0,0 +1,29 @@
+# Historical release notes
+
+[Current changelog](../CHANGELOG.md) · [Overview](../README.en.md)
+
+These English notes preserve the earlier translations. The main changelog contains the consolidated version history.
+
+## 0.7.0 (2026-10-02)
+
+- Generated HTML decks now have previous/next buttons and page-number navigation, with keyboard, touch and a usable 390px layout.
+- A Review and export panel shows quality findings and the outline, links findings to their slides, and offers editable PPTX and project JSON downloads.
+- Incomplete drafts are clearly labeled. Static checks are guidance and require visual review before delivery; layout editing remains available through Agent project tools or PowerPoint/WPS.
+- Download links target the actual sibling files, including Unicode filenames and collision renaming. The existing three-file offline delivery format is preserved.
+- All 103 tests pass on Windows, with Chinese and English browser interaction checks. Native Office and the DSH desktop window were not verified in this round.
+
+## 0.6.0 (2026-10-01)
+
+Adds image/text layouts, four native editable chart types, selected-page edits and undo, page-specific quality reports, four scenario outlines and shared branding. Optional official LibreOffice Kit rendering reads the final PPTX to produce PNG/PDF with font diagnostics. Fixes overlapping overview thumbnails, undersized table titles, image-caption spacing and chart labels.
+
+The goal remains a usable finished deck. The agent prepares actual facts and content; the deterministic generator does not research or invent missing facts. Template-only output is explicitly an unfilled **draft** and must not be delivered as a finished presentation.
+
+Default PPTX fonts use platform fallbacks and explicit East Asian families separately from HTML's CSS font stacks. Replace missing fonts, regenerate and review the pages; unresolved font problems must be disclosed instead of claiming acceptance.
+
+Validation: Windows / Node 24.16.0, 100 passing tests; 18 components mount together on official-source Harness 0.2.0-rc.2 (639ed01539) with 104 tools and 35 skills. Fifteen default-theme pages without brand overrides passed native PNG/PDF rendering and individual visual review; an eleven-page image/chart/brand sample was checked in the browser, Microsoft PowerPoint and the official Kit. This covers those samples, not automatic acceptance of arbitrary decks.
+
+## 0.5.0 (2026-09-24)
+
+Includes presenter previews, thumbnails and timer controls. Unsupported or rejected fullscreen requests now show an actionable message instead of silently failing.
+
+Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-28. All 70 plugin tests pass in an isolated environment; all 18 plugins mount together in one host registering 1 skills and 2 tools, with tool schemas and health-check contracts passing. No live ports or external services were exercised in this round.

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