dsh-ppt 0.4.4 → 0.4.5

package/README.md

@@ -1,170 +1,170 @@
-[English](README.en.md)
-
-# dsh-ppt
-
-> **一句话 / 一篇文档 → 完整演示文稿**：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）演示文稿技能 + 工具插件：把一句话、一段文字或一篇 Markdown 文档变成可直接放映的 **HTML 网页** 与可编辑的 **PPTX**。纯 Node 实现，**零运行时依赖**，Windows / macOS / Linux 同一份代码。
-
-## 能力一览
-
-| 能力 | 说明 |
-| --- | --- |
-| `ppt_create` 工具 | Markdown / 结构化 slides → `*.html` + `*.pptx` + `*.json` 三件套 |
-| `ppt_themes` 工具 | 列出 5 套内置主题与适用场景 |
-| 7 种页型 | 封面 / 章节 / 要点 / 核心观点 / **金句** / **表格** / 结束页 |
-| 演讲者备注 | `<!-- 备注: ... -->` 或 `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。
-
-## 兼容性
-
-2026-09-21：当前发布包经官方 CLI 安装到隔离 profile，在源码构建的 Harness `0.1.6-alpha.2` 上与另外两个下载量前三插件共同加载，18 个插件工具注册正常；日历/邮件配置自检、PPT 主题查询和 17 行表格生成通过。测试本体基于官方 alpha.2 发布提交，另含工具调度器 `Symbol.for` 修复（`93badd88`）。本轮未连接真实邮箱或日历服务。
-
-已在官方 `@deepseek-ai/dsh@0.1.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
-
-## 安装
-
-```bash
-dsh plugin --profile web add dsh-ppt
-```
-
-重启后即可使用 `ppt_create` / `ppt_themes` 工具，并自动加载 `dsh-ppt` 技能。插件自带空配置，**不会弄崩启动**。
-
-## 快速开始
-
-### DSH 内（推荐）
-
-```
-1. ppt_themes                        # 看 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 目录，然后：
-
-```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` | 独立网页放映：方向键/滚轮/触屏翻页，F 全屏，G 总览，P 打印或另存 PDF |
-| `*.pptx` | 16:9 可编辑演示文稿（OOXML 由插件手写，zip 用 node:zlib，无第三方依赖） |
-| `*.json` | 结构化 manifest（版本、主题、语言、每页内容） |
-
-## 内置主题
-
-| ID | 名称 | 情绪 | 适用 |
-| --- | --- | --- | --- |
-| `data` | 数据漂移（默认） | 未来 / 沉浸 | AI、技术发布、研究 |
-| `swiss` | 瑞士脉冲 | 精准 / 理性 | 数据、SaaS、开发者工具 |
-| `velvet` | 天鹅绒标准 | 高级 / 克制 | 高管汇报、品牌、融资路演 |
-| `soft` | 柔和信号 | 温暖 / 人本 | 品牌故事、培训、个人分享 |
-| `bold` | 极繁大字 | 大声 / 动能 | 产品发布、活动、大事件 |
-
-主题灵感来自 [hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) 的 `visual-styles.md`，完整色板见 `skills/dsh-ppt/references/themes.md`。
-
-## 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` 参数优先级最高。
-
-输出目录按每次工具调用的 `exec.agent.session.header.cwd` 解析：不指定目录时写入当前会话工作目录，相对目录（包括插件配置）相对此目录解析，绝对目录保持原意。直接调用工具而未提供会话时，回退到进程工作目录；并行会话不会修改进程 cwd。工具在加载引擎前和加载完成后检查 `exec.signal`，取消的调用不会继续生成文件；生成和写入阶段为同步操作，开始后会完成本次三件套。
-
-
-## 卸载
-
-```bash
-dsh plugin --profile web remove dsh-ppt
-```
-
-卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
-
-## 中英双语
-
-- `lang` 参数：`zh`（默认）/ `en` / `bilingual`，控制播放器界面、页码与结束页默认文案。
-- 内容语言由你撰写：双语 deck 推荐「中文标题 + 英文副标题」，或同一大纲分别生成中英两份。
-- 插件文档提供中英两版（README.md / README.en.md）；CLI 与技能的报错提示为中文。
-
-## 工程质量
-
-- 纯 Node，零运行时依赖：HTML 模板、OOXML、zip 全部手写，只用 `node:fs` / `node:path` / `node:zlib`。
-- 技能与工具共用一个引擎（`skills/dsh-ppt/scripts/deck-core.mjs`），不会出现「DSH 一个效果、裸技能另一个效果」。
-- 单元测试覆盖注册契约、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` 只双语化播放器界面，不自动翻译内容。
-- 暂不支持图表与图片；演讲者备注及 HTML/PPTX 动效已经支持。
-
-## 协议
-
-MIT。社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保留命名空间。
-
-## 相关项目
-
-- [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)
+
+# dsh-ppt
+
+> **一句话 / 一篇文档 → 完整演示文稿**：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）演示文稿技能 + 工具插件：把一句话、一段文字或一篇 Markdown 文档变成可直接放映的 **HTML 网页** 与可编辑的 **PPTX**。纯 Node 实现，**零运行时依赖**，Windows / macOS / Linux 同一份代码。
+
+## 能力一览
+
+| 能力 | 说明 |
+| --- | --- |
+| `ppt_create` 工具 | Markdown / 结构化 slides → `*.html` + `*.pptx` + `*.json` 三件套 |
+| `ppt_themes` 工具 | 列出 5 套内置主题与适用场景；传 `preview: true, outputDir: "dist"` 生成主题对比页 + 每套一张 SVG 色板卡（可直接进 README/npm 首屏） |
+| 7 种页型 | 封面 / 章节 / 要点 / 核心观点 / **金句** / **表格** / 结束页 |
+| 演讲者备注 | `<!-- 备注: ... -->` 或 `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。
+
+## 兼容性
+
+2026-09-21：当前发布包经官方 CLI 安装到隔离 profile，在源码构建的 Harness `0.1.6-alpha.2` 上与另外两个下载量前三插件共同加载，18 个插件工具注册正常；日历/邮件配置自检、PPT 主题查询和 17 行表格生成通过。测试本体基于官方 alpha.2 发布提交，另含工具调度器 `Symbol.for` 修复（`93badd88`）。本轮未连接真实邮箱或日历服务。
+
+已在官方 `@deepseek-ai/dsh@0.1.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-ppt
+```
+
+重启后即可使用 `ppt_create` / `ppt_themes` 工具，并自动加载 `dsh-ppt` 技能。插件自带空配置，**不会弄崩启动**。
+
+## 快速开始
+
+### 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 目录，然后：
+
+```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 可编辑演示文稿（OOXML 由插件手写，zip 用 node:zlib，无第三方依赖） |
+| `*.json` | 结构化 manifest（版本、主题、语言、每页内容） |
+
+## 内置主题
+
+| 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` 参数优先级最高。
+
+输出目录按每次工具调用的 `exec.agent.session.header.cwd` 解析：不指定目录时写入当前会话工作目录，相对目录（包括插件配置）相对此目录解析，绝对目录保持原意。直接调用工具而未提供会话时，回退到进程工作目录；并行会话不会修改进程 cwd。工具在加载引擎前和加载完成后检查 `exec.signal`，取消的调用不会继续生成文件；生成和写入阶段为同步操作，开始后会完成本次三件套。
+
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-ppt
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
+## 中英双语
+
+- `lang` 参数：`zh`（默认）/ `en` / `bilingual`，控制播放器界面、页码与结束页默认文案。
+- 内容语言由你撰写：双语 deck 推荐「中文标题 + 英文副标题」，或同一大纲分别生成中英两份。
+- 插件文档提供中英两版（README.md / README.en.md）；CLI 与技能的报错提示为中文。
+
+## 工程质量
+
+- 纯 Node，零运行时依赖：HTML 模板、OOXML、zip 全部手写，只用 `node:fs` / `node:path` / `node:zlib`。
+- 技能与工具共用一个引擎（`skills/dsh-ppt/scripts/deck-core.mjs`），不会出现「DSH 一个效果、裸技能另一个效果」。
+- 单元测试覆盖注册契约、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` 只双语化播放器界面，不自动翻译内容。
+- 暂不支持图表与图片；演讲者备注及 HTML/PPTX 动效已经支持。
+
+## 协议
+
+MIT。社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保留命名空间。
+
+## 相关项目
+
+- [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/cordis.patch.yml

@@ -1,19 +1,19 @@
-# dsh-ppt：演示文稿技能 + 工具插件（DeepSeek Harness 插件）。
-#
-# 安装即同时注册：
-#   1. 技能 dsh-ppt（把一句话/一篇文档变成完整演示文稿的完整 SOP）
-#   2. 工具 ppt_create / ppt_themes（确定性生成 HTML 网页放映 + PPTX 导出）
-#
-# 插件自带空配置，绝不弄崩启动；无需任何账号或密钥。可选配置：
-#
-#   - id: dsh-ppt
-#     config:
-#       outputDir: E:\decks        # 可选：默认写入会话工作目录
-#       maxSlides: 40              # 可选：单次生成幻灯片上限，默认 60
-#       defaultTheme: data         # 可选：默认视觉主题
-#       defaultLang: zh            # 可选：默认界面语言 zh/en/bilingual
-#
-- insert:
-    - id: dsh-ppt
-      name: dsh-ppt
-      config: {}
+# dsh-ppt：演示文稿技能 + 工具插件（DeepSeek Harness 插件）。
+#
+# 安装即同时注册：
+#   1. 技能 dsh-ppt（把一句话/一篇文档变成完整演示文稿的完整 SOP）
+#   2. 工具 ppt_create / ppt_themes（确定性生成 HTML 网页放映 + PPTX 导出）
+#
+# 插件自带空配置，绝不弄崩启动；无需任何账号或密钥。可选配置：
+#
+#   - id: dsh-ppt
+#     config:
+#       outputDir: E:\decks        # 可选：默认写入会话工作目录
+#       maxSlides: 40              # 可选：单次生成幻灯片上限，默认 60
+#       defaultTheme: data         # 可选：默认视觉主题
+#       defaultLang: zh            # 可选：默认界面语言 zh/en/bilingual
+#
+- insert:
+    - id: dsh-ppt
+      name: dsh-ppt
+      config: {}

package/lib/execution.js

@@ -23,7 +23,18 @@ export function createPptExecutors(config, loadEngine = getEngine) {
             const lang = typeof args.lang === 'string' && args.lang.trim() !== '' ? args.lang.trim() : 'zh';
             const engine = await loadEngine();
             exec?.signal?.throwIfAborted();
-            return { ok: true, themes: engine.listThemes(lang) };
+            const themes = engine.listThemes(lang);
+            if (args.preview === true) {
+                const cwd = exec?.agent?.session.header.cwd ?? process.cwd();
+                const requested = typeof args.outputDir === 'string' && args.outputDir.trim() !== '' ? args.outputDir.trim() : '.';
+                const preview = engine.buildThemePreview({
+                    outputDir: resolve(cwd, requested),
+                    lang,
+                    overwrite: args.overwrite === true,
+                });
+                return { ok: true, themes, preview };
+            }
+            return { ok: true, themes };
         },
         async create(rawArgs, exec) {
             exec?.signal?.throwIfAborted();

package/lib/tools.js

@@ -40,6 +40,7 @@ const themesResultSchema = {
     properties: {
         ok: { type: 'boolean' },
         themes: { type: 'array', items: themeInfoSchema },
+        preview: { type: 'object', additionalProperties: true },
     },
     additionalProperties: true,
 };
@@ -74,14 +75,18 @@ function renderThemes(value) {
     if (value.themes.length === 0)
         return oneText('dsh-ppt 没有可用主题。');
     const lines = value.themes.map((theme) => '- ' + theme.id + '：' + theme.name + '（' + theme.mood + '）｜适合：' + theme.bestFor + '｜' + (theme.dark ? '深色' : '浅色'));
-    return oneText('dsh-ppt 内置主题：\n\n' + lines.join('\n') + '\n\nppt_create 的 theme 参数填其中的 id（默认 data）。');
+    const summary = 'dsh-ppt 内置主题：\n\n' + lines.join('\n') + '\n\nppt_create 的 theme 参数填其中的 id（默认 data）。';
+    if (value.preview) {
+        return oneText(summary + '\n\n主题预览已写入：' + value.preview.htmlPath + '\nSVG 色板卡：' + value.preview.svgs.map((svg) => svg.path).join(' / '));
+    }
+    return oneText(summary + '\n\n想要并排对比：ppt_themes { preview: true, outputDir: "..." } 会生成 themes-preview.html 和每套主题的 SVG 色板卡。');
 }
 function renderCreate(value) {
     return oneText('dsh-ppt 已生成 ' + value.slideCount + ' 页演示文稿（主题 ' + value.theme + '，语言 ' + value.language + '）：\n' +
         'HTML 网页放映：' + value.htmlPath + '\n' +
         'PPTX 导出：' + value.pptxPath + '\n' +
         'Manifest：' + value.jsonPath + '\n' +
-        'HTML 双击即可放映（方向键翻页 / F 全屏 / G 总览 / P 打印）；PPTX 可用 PowerPoint / WPS / Keynote 打开。');
+        'HTML 双击即可放映（← → 翻页 / V 演讲者视图 / S 备注 / G 缩略图总览 / F 全屏 / P 打印 / ? 快捷键）；PPTX 可用 PowerPoint / WPS / Keynote 打开。');
 }
 /** Assemble presentation schemas, rendering and the session-aware executors. */
 export function buildPptTools(config) {
@@ -89,9 +94,12 @@ export function buildPptTools(config) {
     return [
         {
             name: 'ppt_themes',
-            description: 'List the built-in visual themes of dsh-ppt (id, name, mood, best-for, light/dark palette) before building a deck. Use a theme id as the theme argument of ppt_create. 中文：列出 dsh-ppt 内置视觉主题（id、名称、情绪、适用场景、明暗色板），用于选择 ppt_create 的 theme 参数。',
+            description: 'List the built-in visual themes of dsh-ppt (id, name, mood, best-for, light/dark palette) before building a deck. Pass preview: true with outputDir to also write a self-contained theme gallery HTML plus one SVG palette card per theme (ready for README/npm screenshots). Use a theme id as the theme argument of ppt_create. 中文：列出 dsh-ppt 内置视觉主题（id、名称、情绪、适用场景、明暗色板）；传 preview: true + outputDir 会额外生成主题对比页和每套主题的 SVG 色板卡（可直接放 README/npm 首屏），用于选择 ppt_create 的 theme 参数。',
             parameters: compileParameters({
                 lang: { type: 'string', description: 'Theme description language: zh (default), en, or bilingual.' },
+                preview: { type: 'boolean', description: 'Write a theme gallery HTML and one SVG palette card per theme into outputDir. Default false (list only).' },
+                outputDir: { type: 'string', description: 'Directory for preview files when preview is true. Default: session working directory (or the plugin outputDir config).' },
+                overwrite: { type: 'boolean', description: 'Overwrite existing preview files instead of adding a numeric suffix. Default false.' },
             }),
             output: {
                 schema: themesResultSchema,

package/lib/types.d.ts

@@ -48,9 +48,22 @@ export interface PptThemeInfo {
     palette: Record<string, string>;
     fonts: Record<string, string>;
 }
+export interface PptThemePreviewResult {
+    ok: boolean;
+    outputDir: string;
+    htmlPath: string;
+    svgs: Array<{
+        id: string;
+        path: string;
+    }>;
+    themeCount: number;
+    language: string;
+}
 export interface PptThemesResult {
     ok: boolean;
     themes: PptThemeInfo[];
+    /** 传 preview: true 时返回：主题对比页 + 每套主题的 SVG 色板卡。 */
+    preview?: PptThemePreviewResult;
 }
 export interface PptCreateResult {
     ok: boolean;
@@ -71,6 +84,7 @@ export interface PptCreateResult {
 /** deck-core.mjs 暴露给插件的最小面。 */
 export interface DeckEngine {
     buildDeck(options: Record<string, unknown>): PptCreateResult;
+    buildThemePreview(options: Record<string, unknown>): PptThemePreviewResult;
     listThemes(lang?: string): PptThemeInfo[];
     resolveTheme(input: unknown): Record<string, unknown>;
     resolveLanguage(input: unknown): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ppt",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "DSH 演示文稿插件：Markdown 生成网页放映与可编辑 PPTX，长表格自动分页，内置 5 套主题、备注与转场动画。",
   "type": "module",
   "main": "lib/index.js",

package/skills/dsh-ppt/SKILL.md

@@ -1,69 +1,69 @@
----
-name: dsh-ppt
-description: "Turn one sentence or a Markdown document into a complete, presentation-ready deck: a standalone HTML web slideshow plus an editable PPTX export, with 5 built-in visual themes (Swiss Pulse / Velvet Standard / Data Drift / Soft Signal / Maximalist Type), slide transitions + bullet entrance animations (motion, on by default), and bilingual Chinese/English support. Use when the user asks for a PPT, slides, deck, keynote, 演示文稿, 幻灯片, 汇报, 提案, 路演, 培训材料, or wants to turn a document into a presentation. 中文：把一句话或一篇文档变成完整演示文稿（HTML 网页放映 + PPTX 导出），内置 5 套视觉主题、页间转场与要点入场动画，中英双语。"
-compatibility: "DSH plugin runs in-process with zero runtime dependencies. The standalone CLI needs Node.js >= 20. Cross-harness: copy this skill directory into any Agent Skills directory."
-allowed-tools: "Bash, Read, Write, Edit"
----
-
-# dsh-ppt
-
-一句话或一篇文档 → 完整演示文稿：**独立 HTML 网页放映 + 可编辑 PPTX**。本文件只做路由与纪律；具体规则按需读取 `references/`。
-
-## 触发条件
-
-用户要做 PPT / 幻灯片 / 演示文稿 / deck / 汇报 / 提案 / 路演 / 培训材料，或给一句话、一段文字、一篇 Markdown 想变成可放映的演示。
-
-## 执行纪律（每次都要遵守）
-
-- 一页一个观点；标题是判断句，不是名词短语。
-- 内容语言由你撰写；`lang` 只决定界面文字。
-- 先选主题再构建；不确定就用默认 `data`。
-- 交付前逐项过一遍文末「质量门禁」。
-
-## 核心流水线
-
-1. **Probe 需求**：读入用户的句子/文档，确定听众、目标、语气。一句话输入不要反问，直接按发布场景推断。
-2. **Outline 大纲**：产出 5–12 页大纲（封面 → 问题/背景 → 方案/论点 3–6 页 → 证据 → 行动号召 → 结束页）。
-   → 写大纲与正文前先读 `references/copywriting.md`。
-3. **Theme 主题**：调 `ppt_themes`（DSH）或 `node scripts/build-deck.mjs --list-themes`（跨 harness）。
-   → 拿不准选哪套时读 `references/themes.md` 的情绪决策树。
-4. **Build 生成**：
-   - DSH 内：调 `ppt_create`，大纲写成 Markdown 传 `content`（推荐），或传结构化 `slides`。
-   - 跨 harness：`node <skill-dir>/scripts/build-deck.mjs --title "标题" --content deck.md --theme data --lang zh --out dist`。
-   - 动效默认开（页间转场 + 要点逐条入场）；严肃/打印场景传 `motion: 'off'`。
-   → 用表格 / 金句 / 备注 / 结构化 slides 前读 `references/syntax.md`。
-5. **Verify 校验**：确认 HTML 页数与大纲一致、标题无截断、PPTX 文件头为 `PK`。
-6. **Deliver 交付**：给用户三个绝对路径，说明 HTML 直接放映（← → 翻页 · F 全屏 · G 总览 · S 备注 · P 打印），PPTX 用 PowerPoint / WPS / Keynote 打开（备注在演示者视图可见，bullets 页放映时逐条点击出现）。
-
-## 按需装载索引
-
-| 何时读 | 文件 | 内容 |
-| --- | --- | --- |
-| 写大纲 / 正文前 | `references/copywriting.md` | 叙事骨架、单页规则、双语规则 |
-| 选主题拿不准 | `references/themes.md` | 5 套主题色板 + 情绪决策树 |
-| 用表格/金句/备注/结构化 slides | `references/syntax.md` | Markdown 解析、进阶语法、slides JSON、motion 开关 |
-| 交付异常 | `references/troubleshooting.md` | 症状 → 处理对照表 |
-
-## 质量门禁（交付前逐项确认）
-
-- [ ] 页数 3–60，首屏是封面，末屏是结束页。
-- [ ] 每页有明确标题；bullets 页 1–8 条，中文每条 ≤ 20 字、英文 ≤ 12 词。
-- [ ] HTML 与 PPTX 使用同一主题，配色一致。
-- [ ] 主题色对比度足够（深底浅字或浅底深字）。
-- [ ] 中文内容无错别字；英文标题用 Title Case。
-- [ ] 最后一页有可执行的行动号召，不只是「谢谢」。
-- [ ] 文件已写到用户工作区，路径为绝对路径。
-
-## 跨 harness 安装
-
-把整个 `dsh-ppt` 技能目录复制到目标 agent 的技能目录即可（只依赖 Node 20+）：
-
-| Agent | 技能目录 |
-| --- | --- |
-| DeepSeek Harness | `dsh plugin --profile web add dsh-ppt` |
-| Claude Code | `~/.claude/skills/` |
-| Cursor | `.cursor/skills/` |
-| Gemini CLI | `~/.gemini/skills/` |
-| OpenAI Codex | `~/.codex/skills/` |
-
-一次编写，处处可用。
+---
+name: dsh-ppt
+description: "Turn one sentence or a Markdown document into a complete, presentation-ready deck: a standalone HTML web slideshow plus an editable PPTX export, with 5 built-in visual themes (Swiss Pulse / Velvet Standard / Data Drift / Soft Signal / Maximalist Type), slide transitions + bullet entrance animations (motion, on by default), and bilingual Chinese/English support. Use when the user asks for a PPT, slides, deck, keynote, 演示文稿, 幻灯片, 汇报, 提案, 路演, 培训材料, or wants to turn a document into a presentation. 中文：把一句话或一篇文档变成完整演示文稿（HTML 网页放映 + PPTX 导出），内置 5 套视觉主题、页间转场与要点入场动画，中英双语。"
+compatibility: "DSH plugin runs in-process with zero runtime dependencies. The standalone CLI needs Node.js >= 20. Cross-harness: copy this skill directory into any Agent Skills directory."
+allowed-tools: "Bash, Read, Write, Edit"
+---
+
+# dsh-ppt
+
+一句话或一篇文档 → 完整演示文稿：**独立 HTML 网页放映 + 可编辑 PPTX**。本文件只做路由与纪律；具体规则按需读取 `references/`。
+
+## 触发条件
+
+用户要做 PPT / 幻灯片 / 演示文稿 / deck / 汇报 / 提案 / 路演 / 培训材料，或给一句话、一段文字、一篇 Markdown 想变成可放映的演示。
+
+## 执行纪律（每次都要遵守）
+
+- 一页一个观点；标题是判断句，不是名词短语。
+- 内容语言由你撰写；`lang` 只决定界面文字。
+- 先选主题再构建；不确定就用默认 `data`。
+- 交付前逐项过一遍文末「质量门禁」。
+
+## 核心流水线
+
+1. **Probe 需求**：读入用户的句子/文档，确定听众、目标、语气。一句话输入不要反问，直接按发布场景推断。
+2. **Outline 大纲**：产出 5–12 页大纲（封面 → 问题/背景 → 方案/论点 3–6 页 → 证据 → 行动号召 → 结束页）。
+   → 写大纲与正文前先读 `references/copywriting.md`。
+3. **Theme 主题**：调 `ppt_themes`（DSH）或 `node scripts/build-deck.mjs --list-themes`（跨 harness）。
+   → 拿不准选哪套时读 `references/themes.md` 的情绪决策树。
+4. **Build 生成**：
+   - DSH 内：调 `ppt_create`，大纲写成 Markdown 传 `content`（推荐），或传结构化 `slides`。
+   - 跨 harness：`node <skill-dir>/scripts/build-deck.mjs --title "标题" --content deck.md --theme data --lang zh --out dist`。
+   - 动效默认开（页间转场 + 要点逐条入场）；严肃/打印场景传 `motion: 'off'`。
+   → 用表格 / 金句 / 备注 / 结构化 slides 前读 `references/syntax.md`。
+5. **Verify 校验**：确认 HTML 页数与大纲一致、标题无截断、PPTX 文件头为 `PK`。
+6. **Deliver 交付**：给用户三个绝对路径，说明 HTML 直接放映（← → 翻页 · F 全屏 · G 总览 · S 备注 · P 打印），PPTX 用 PowerPoint / WPS / Keynote 打开（备注在演示者视图可见，bullets 页放映时逐条点击出现）。
+
+## 按需装载索引
+
+| 何时读 | 文件 | 内容 |
+| --- | --- | --- |
+| 写大纲 / 正文前 | `references/copywriting.md` | 叙事骨架、单页规则、双语规则 |
+| 选主题拿不准 | `references/themes.md` | 5 套主题色板 + 情绪决策树 |
+| 用表格/金句/备注/结构化 slides | `references/syntax.md` | Markdown 解析、进阶语法、slides JSON、motion 开关 |
+| 交付异常 | `references/troubleshooting.md` | 症状 → 处理对照表 |
+
+## 质量门禁（交付前逐项确认）
+
+- [ ] 页数 3–60，首屏是封面，末屏是结束页。
+- [ ] 每页有明确标题；bullets 页 1–8 条，中文每条 ≤ 20 字、英文 ≤ 12 词。
+- [ ] HTML 与 PPTX 使用同一主题，配色一致。
+- [ ] 主题色对比度足够（深底浅字或浅底深字）。
+- [ ] 中文内容无错别字；英文标题用 Title Case。
+- [ ] 最后一页有可执行的行动号召，不只是「谢谢」。
+- [ ] 文件已写到用户工作区，路径为绝对路径。
+
+## 跨 harness 安装
+
+把整个 `dsh-ppt` 技能目录复制到目标 agent 的技能目录即可（只依赖 Node 20+）：
+
+| Agent | 技能目录 |
+| --- | --- |
+| DeepSeek Harness | `dsh plugin --profile web add dsh-ppt` |
+| Claude Code | `~/.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| Gemini CLI | `~/.gemini/skills/` |
+| OpenAI Codex | `~/.codex/skills/` |
+
+一次编写，处处可用。