dsh-ppt 0.6.0 → 0.8.0

package/README.md

@@ -1,228 +1,44 @@
-[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.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 同源同色 |
+[English](README.en.md)
 
-示例对话：
+把材料制作成 HTML 放映、可编辑 PPTX 和可继续修改的工程文件。
 
-> 把这句话做成 PPT：「AI 客服把首次响应时间压缩到 8 秒」，主题用科技感深色。
->
-> 把 `docs/季度汇报.md` 做成双语演示文稿，导出 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)
 
-## 兼容性
+## 功能
 
-插件和独立技能均要求 Node `^22.19.0 || >=24.0.0`。插件无需密钥或必填配置，可选渲染引擎缺失不会阻止普通启动与生成。Windows 示例已通过浏览器操作、真实 Microsoft PowerPoint 打开/逐页导出，以及官方 Kit 原生渲染；具体产物仍需逐页检查。
+- 生成图文、表格、原生图表和品牌化演示文稿。
+- 在设置页编辑文字和图片、调整页面顺序，并支持撤销。
+- 提供质量检查与可选的最终 PPTX 图片 / PDF 渲染。
 
 ## 安装
 
-```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`，然后：
+桌面版可在「插件」面板按包名 `dsh-ppt` 安装。已配置 dsh 命令时也可使用：
 
 ```bash
-node <skill-dir>/scripts/build-deck.mjs \
-  --title "产品发布" \
-  --content deck.md \
-  --theme data \
-  --lang zh \
-  --out dist/deck
+dsh plugin --profile desktop add dsh-ppt
 ```
 
-输出三件套：
-
-默认不会覆盖已有同名产物：三件套中任一文件存在时会整组追加 `-1`、`-2`… 后缀；只有显式传 `overwrite: true`（CLI 为 `--overwrite`）才会覆盖。
+网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
 
-| 文件 | 用途 |
-| --- | --- |
-| `*.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 使用原生图表与可编辑工作簿。
+可说：“把这份材料做成可直接交付的演示文稿，生成 HTML、PPTX 和工程文件。”0.8.0 起可在「设置 → 演示文稿」轻量修改自产工程，也可在 PowerPoint / WPS 中继续编辑 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
-```
+## 依赖与配置
 
-## 已知限制
+普通生成不需要 Office。最终 PPTX 渲染使用可选的官方 LibreOffice Kit；依赖版本、字体环境和安装方法见使用说明。
 
-- PPTX 采用空白版式 + 文本框实现：PowerPoint / WPS 中可正常编辑文字，但暂不生成智能母版占位符。
-- 一句话输入自动生成三页最小结构；更丰富的内容需要先扩写成 Markdown 大纲再调用 `ppt_create`。
-- `bilingual` 只双语化播放器界面，不自动翻译内容。
-- 按页编辑仅支持本插件 JSON 工程，不导入任意外部 PPTX 编辑。
-- 文字大小与溢出检查是静态估算；实际裁切和字体替换必须查看渲染画面。
+详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
 
-## 协议
+## 文档
 
-插件 MIT；Office Kit MIT；可选官方 LibreOffice Kit 及其引擎保留各自许可、来源与第三方声明。使用官方库不表示本插件由 DeepSeek 官方维护。
+- [使用与排错](docs/USAGE.md)
+- [更新记录](CHANGELOG.md)
+- [验证范围与历史记录](docs/VALIDATION.md)
+- [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-ppt/issues)
 
-## 相关项目
+## License
 
-- [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) — 邮件六件套
+[MIT](LICENSE)

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/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/FEATURE-PLAN-2026-10-01.md

@@ -1,50 +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需在没有可选引擎的消费者安装中证明普通启动/生成仍正常。
+# 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

@@ -1,69 +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)。
+# 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)。