dsh-ppt 0.5.0 → 0.6.0

package/README.md

@@ -1,176 +1,228 @@
-[English](README.en.md)
-
-# dsh-ppt
+[English](README.en.md)
+
+# dsh-ppt
+
+## 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.1.7-rc.2（保留本地工具调度器修复）。构建与自动测试通过；实际操作和外部服务限制见本轮验收记录。
-
-> **一句话 / 一篇文档 → 完整演示文稿**：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) — 邮件六件套
+验证宿主：官方源码构建的 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) — 邮件六件套

package/docs/FEATURE-PLAN-2026-10-01.md

@@ -0,0 +1,50 @@
+# PPT 0.6 功能与验收方案
+
+目标：保留现有主题和放映体验，同时让图片、数据图表、单页修改、撤销、质量检查和场景模板成为完整工作流。
+
+## 技术选择
+
+- 复用 MIT 许可的 `@office-kit/pptx@0.21.0`，按精确版本锁定其尚未稳定的 0.x API。
+- 官方源码：https://github.com/office-kit/pptx 。官方示例：https://office-kit.github.io/pptx/docs/recipes 。npm 版本与许可证已核对。
+- 原型先生成现有 PPTX，再用库加入图表并回写。已确认原生图表、内嵌 XLSX、备注、转场和要点时序树仍在包内。正式验收还需真实渲染，不能用 ZIP 结构检查代替。
+- HTML 保留现有离线播放器。图表使用本地 SVG 展示，PPTX 使用原生图表对象；两者共享归一化数据。图片只接受本地 PNG/JPEG 或这些格式的 data URI，统一嵌入，避免外链失效。
+- 原同步 `buildDeck`/`buildPptx` 保留文字版兼容性。增加异步 `buildDeckAsync`，插件工具与 CLI 走此入口，图片/图表依赖只在需要时载入。跨 harness 技能目录携带依赖清单，按文档安装。
+
+## 用户功能
+
+| 能力 | 行为 | 验收 |
+| --- | --- | --- |
+| 图片 | `image`、`image-left`、`image-right` 布局，contain/cover 保比例缩放或居中裁切，替换图片，离线嵌入 | 中文路径、横竖图、移走原图后 HTML/PPTX 可显示；坏图或路径报页码且不覆盖旧文件 |
+| 单页修改 | `ppt_edit` 用 1-based 页码或稳定 ID 合并指定字段，清空可选字段用 null，其他页不重新生成正文 | 原页面内容和 ID 保持一致；多页修改一次提交；错误与版本冲突无部分写入 |
+| 撤销 | JSON 保存最多 20 次内容快照，`ppt_undo` 恢复上一内容版本并递增修订号 | 文字、图表、图片和品牌一起恢复；原图删掉后仍能撤销；无历史时明确提示 |
+| 质量检查 | `ppt_check` 返回页码、稳定 ID、严重度、原因与建议；生成和修改也附报告 | 长标题、密集要点、潜在溢出、低分辨率、缺资产、模板未填、低对比度均有可复现用例；标明估算不能保证所有字体渲染 |
+| 图表 | column/bar/line/pie，categories+series 或二维表，严格校验有限数值、类别一致性和饼图约束 | 4 类 HTML/SVG 数据匹配；PPTX 原生图表与内嵌 Excel 数据匹配；Windows 真实打开/渲染 |
+| 模板与品牌 | weekly/defense/project/pitch 可查询大纲与骨架，模板空白位置标注待填；品牌主色、背景色、文字色、字体、Logo、页脚 | 4 场景各生成；品牌出现在 HTML 和 PPTX；内容由用户或代理提供，示例数字不当作事实 |
+
+## 数据与文件规则
+
+- JSON 添加 manifest schema、deck ID、revision、稳定 slide ID、嵌入资产字典、品牌、模板、质量报告和非递归历史。
+- 图片有单文件和总量上限；历史限制条数与总大小。历史保留的资产不能在更新时错误清理。
+- 编辑仅支持本插件 JSON 工程；任意外部 PPTX 导入不属于这次范围。
+- 修改先验证和生成全部输出，再对 HTML/PPTX/JSON 统一提交。检查预期修订号和原文件摘要，防止覆盖并行修改。
+- 图片相对路径依据 DSH 当前会话工作目录解析。编辑工程路径同样遵循会话目录，不改进程 cwd，不读取或输出 API 密钥。
+- AbortSignal 在加载、导出和提交前检查。取消时不留下半套输出。
+
+## 交付顺序
+
+1. 原有测试基线；增加数据/失败/文件事务回归，再接入工具和 CLI。
+2. 四场景、所有图片布局和图表类型的 HTML 浏览器操作与视觉检查，指定页修改和撤销。
+3. Windows PPTX 渲染及数据编辑能力检查；检查旧主题、表格、备注、动效回归。
+4. 同步中英文文档、技能指南和变更记录，构建入库 lib。
+5. GitHub 提交推送、CI、npm 最终 tarball 全新安装和官方 DSH 0.2.0-rc.2 契约/启动验收。
+6. 发布独立插件并核验 registry，再更新 Suite 精确版本与锁文件、CI、安装与发布；核对本地和云端。
+
+## 官方渲染接入与协作
+
+与“了解 dsh-libreoffice-kit”会话协作，对面负责 deck-render.mjs、渲染回归与渲染方案文档，本会话整合工具/CLI/文档/提交/发布。明确授权为成熟方案完成后直接开工、提交和npm更新。
+
+官方 @deepseek-ai/libreoffice-kit@0.1.3 作为精确版本可选peer，读取已生成的PPTX，输出逐页PNG/PDF，不重写可编辑源文稿。ppt_render按实际页面尺寸换算DPI，统一期限、取消、输入/输出限制和独占目录，失败清理仅限本次产物。
+
+ppt_check分别展示静态估算、摘要匹配的渲染证据和未自动通过的视觉状态。收据核验源PPTX与所有输出；任何内容变更后重新渲染。CLI显式收据失效返回非零。缺失字体须替换为可用字体，再生成并检查；字体负例渲染成功但中文重叠，不能把成功状态当作成品验收。
+
+Windows实际Office打开与官方Kit原生渲染均用最终11页样例验证，不读取或输出API密钥。最终tarball需在没有可选引擎的消费者安装中证明普通启动/生成仍正常。

package/docs/LIBREOFFICE-INTEGRATION-2026-10-01.md

@@ -0,0 +1,69 @@
+# PPT 成品渲染与 PDF 导出方案
+
+目标是在现有 HTML 放映稿与可编辑 PPTX 交付流程中，补上真实 PPTX 静态渲染、PDF 导出和缺失字体报告。生成、编辑和撤销仍以本插件 JSON 工程为准。
+
+## 库的分工
+
+- 现有生成器与 `@office-kit/pptx@0.21.0` 负责主题、文字、图片、原生图表、备注、转场和可编辑 PPTX。
+- 可选的 `@deepseek-ai/libreoffice-kit@0.1.3` 读取保存后的 PPTX，直接生成每页 PNG，或导出 PDF。两种静态产物方便检查和分享。
+- 引擎渲染成功只证明生成了该输入版本的静态产物。内容准确、文字裁切、图表可读性和设计质量仍由视觉检查判断。
+
+## 安装和平台
+
+插件声明精确版本的 optional peer，不让普通安装默认下载重型引擎。需要渲染时，在插件所在项目或独立技能目录运行：
+
+```bash
+npm install --ignore-scripts @deepseek-ai/libreoffice-kit@0.1.3
+```
+
+官方要求 Node.js >=22.19.0，与插件现有约束一致。Windows x64/ARM64 和 macOS 使用匹配原生引擎；Linux 使用 WASM。Windows 另需匹配 Node 架构的 Microsoft Visual C++ v14 运行库。依赖或引擎缺失时，`ppt_render` 返回 `unavailable` 与安装提示，正常生成 HTML/PPTX 的流程仍可使用。
+
+2026-10-01 npm 元数据显示 Windows x64 引擎解包载荷为 190,877,547 字节，约191MB，不包含 API 的其他依赖。这是解包体积，不是下载体积。运行时无需额外下载引擎或字体。
+
+## API 与输出
+
+`deck-render.mjs` 导出：
+
+```js
+await renderDeck({
+  pptxPath: '/absolute/path/deck.pptx',
+  outputDir: '/absolute/path/deck-render', // 可选
+  format: 'both',                       // png（默认）/ pdf / both
+  width: 1440,                          // 320–3840，近似目标宽度
+  timeoutMs: 120000,                     // 1000–300000，整次渲染期限
+  signal,
+})
+readRenderReceipt(pptxPath, receiptPath)
+```
+
+宽度通过 PPTX 的实际页面尺寸换算 DPI，输出因像素取整可能相差少量像素。适配器使用 Kit 的全部页面模式，最多120页，不截断页面。输入上限64MiB，输出 PNG/PDF 与 manifest 总量128MiB，单图最多16,777,216像素。PDF-only 的 `slideCount` 来自输入 PPTX 的页数，PNG/both 的页数来自真实引擎。
+
+成功返回 `ok:true, status:'rendered'`、真实 `backend`（native/wasm）、`rendererVersion`、`slideCount`、`pngPaths` / `pdfPath`、`missingFonts`、`sourceSha256` 和 `receiptPath`。`visual` 固定为 `not-verified`，不会自动声称视觉验收通过。依赖/引擎缺失返回 `ok:false, status:'unavailable'`；参数、文件和运行失败抛错；取消原样保留 `signal.reason`。
+
+默认目录为 `<PPTX-basename>-render`，已存在时追加后缀。目录由独占 mkdir 预留，产物先写私有 staging，等待引擎退出、验证原文件摘要仍匹配后，再提交 `artifacts/` 子目录。PNG、PDF 和收据随同提交；取消、超时或任一步失败都清理本次 staging。不会递归删除预先存在的输出目录。
+
+## 收据与检查状态
+
+收据 `render-receipt.json` 包含 `schemaVersion:1`、`producer:'dsh-ppt-render'`、引擎包名/版本/backend、源 PPTX SHA256/长度、格式、页数、缺失字体和每个输出的相对路径/长度/SHA256。
+
+`readRenderReceipt()` 验证源文件和输出的实际内容、精确引擎版本、完整页码以及路径范围。源 PPTX 编辑后、图片/PDF被修改或删除后，旧收据返回 `not-verified`，需要重新渲染。收据是本地完整性记录，不是签名证明。
+
+`ppt_check` 分别展示静态估算、源文件匹配的渲染证据和视觉检查状态。PNG 或 PDF 成功生成后，视觉检查仍需查看每一页并修正发现的问题。LibreOffice 输出不保证与 PowerPoint/WPS 完全一致，真实 Office 打开、备注、动画与可编辑图表的验收另行保留。
+
+## 字体和许可
+
+Kit 使用环境中可用的字体，OOXML 的 `missingFonts` 只报告缺失的声明字体，不是完整缺字报告，也不自动安装字体。依赖使用 MPL-2.0；发布和打包时保留其及原生引擎携带的来源、许可和第三方声明。插件自身和 Office Kit 的许可保持各自声明。
+
+默认主题的 PPTX 分别指定西文和东亚字体，避免把 CSS 字体栈第一项同时当作中文字体。Windows 使用 Segoe UI / Georgia / Impact 等主题回退，中文使用 Microsoft YaHei 或 SimSun；macOS 和 Linux 使用对应平台的字体映射。显式品牌字体保留请求的西文字体，中文按可用的东亚字体家族映射。平台映射不等于检测字体已安装；实际缺失仍由引擎报告。HTML 使用原有 CSS 字体栈。
+
+缺失字体可能导致替代后的文字重叠，即使引擎成功返回且 PDF/PNG 收据有效，也需要换用可用字体、重新生成并逐页检查。自定义不存在字体的真实负例已确认这一限制。渲染器不会修改源 PPTX 字体或自动宣称画面合格。
+
+## 当前验证证据
+
+2026-10-01 在 Windows x64、Node 24.16.0、Kit 0.1.3 原生引擎上运行完整11页样例，包含3种图片布局、4种原生图表、中文、备注、表格与品牌字体/页脚。成功生成11张 PNG 和 PDF，约6.13秒，`missingFonts:[]`，源 PPTX 摘要未变化，收据复核通过。逐页查看11张PNG，样例中的标题、正文、图片和图表均可读，无明显裁切或对象遮挡；这是该样例的验证，不是所有文件的兼容保证。
+
+随后对默认无品牌设置的五个主题做字体回归，每主题生成封面、要点页和中文原生柱形图，合计15页。修复前五主题均声明本环境缺失的默认字体，已检查的正文页均出现中文重叠。修复 PPTX 西文/东亚字体映射后，同一探针重新生成15张PNG和5份PDF，全部原生渲染成功，`missingFonts:[]`，源文件匹配的收据复核通过；逐页查看15张PNG，中文与英文标题、正文、图表标签和图例均可读，无明显文字重叠或裁切。证据为 `theme-font-matrix-1790862328203/font-matrix-result.json`；修复前证据单独保留。这项实际渲染回归在Windows完成，macOS/Linux未在本次运行中实测。
+
+独立证据目录：`E:\deepseek\.harness-validation\libreoffice-kit-probe-20261001`。主流程工具/CLI、打包安装与发布验收由整合会话继续执行。
+
+官方资料：[API 与限制](https://github.com/deepseek-ai/dsh-libreoffice-kit/blob/master/packages/entry/README.md)、[字体与平台](https://github.com/deepseek-ai/dsh-libreoffice-kit/blob/master/README.zh.md)、[分发和许可](https://github.com/deepseek-ai/dsh-libreoffice-kit/blob/master/docs/packaging.md)。

package/lib/execution.d.ts

@@ -15,4 +15,12 @@ export interface PptExecution {
 export declare function createPptExecutors(config: ResolvedPptConfig, loadEngine?: () => Promise<DeckEngine>): {
     themes(rawArgs: unknown, exec?: PptExecution): Promise<PptThemesResult>;
     create(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptCreateResult>;
+    templates(rawArgs: unknown, exec?: PptExecution): Promise<{
+        ok: boolean;
+        templates: unknown[];
+    }>;
+    edit(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptCreateResult>;
+    undo(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptCreateResult>;
+    check(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptQualityResult | import("./types.js").PptCheckResult>;
+    render(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptRenderResult>;
 };