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