# PPT成片工作室

**Repository Path**: godbirds/dsh-pptvm-studio

## Basic Information

- **Project Name**: PPT成片工作室
- **Description**: 一条流水线完成 ：内容确认 → 生成 PPT（含动画增强）→ 生成视频 → 总结报告，全流程任务化、可回看、可复跑。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📊 dsh-pptvm-studio

> **PPT 成片智能体（DeepSeek Harness 插件）**
>
> 一条流水线完成 **内容确认 → 生成 PPT（含动画增强）→ 生成视频 → 总结报告**，全流程任务化、可回看、可复跑。
>
> 命名说明：**`pptvm` = PPT + Video Maker**（与模型工具前缀 `pptvm_*` 一致），**`studio`** 表示“成片工作室”（起草 → PPT → 视频 → 报告）。
> 支持导入 PPTX / MD 大纲 / AI 对话起草；内容审查为 **规则 + LLM 二次审查** 双通道（LLM 走后台任务，不卡界面）。
> 主题库内置 6 套，并支持**用一段文字描述让 AI 生成自定义主题**（全局 `.ppttheme.json`，所有任务可复用）。
> 「静帧渲染」用 PowerPoint 逐页截图 + ffmpeg 合成 mp4；未装 ffmpeg 时自动降级导出 PNG 帧序列与计时。

## 🚀 功能特性

| 模块 | 能力 |
| --- | --- |
| 内容确认 | 任务下拉**可直接输入新名称**，点「＋ 新建任务」即创建（无需先点下拉项；同名任务已存在则直接打开）；导入 PPTX（含备注口播）/ MD 大纲（两种形态）/ AI 对话起草（**20 行文本域**录入需求，Ctrl/⌘+Enter 起草）；**AI 起草输出结构化六段**（版式 / 核心文案 / 节点 / 结论 / 视觉元素 / 口播），节点与结论落为页 md 的 `points` / `conclusion`、版式落为 `layout`；**结构角色词（封面 / 开场钩子 / 原因分析 / 行动召唤…）只用于内部规划，导入与出图会自动剥离，不进成片**；页大纲表格 + 等高 Markdown 编辑区；逐页锁定 + 一键「全部锁定/解锁」（查看锁定页时禁止一键解锁）；规则审查（含节点 2–5 条、单条 ≤35 字、缺结论提示）+ **AI 二次审查（后台任务 + 轮询）**；「应用修复」一键补口播 / 加封面 / 加结尾 |
| 生成 PPT | **4 列紧凑主题卡片**（背景/卡片/标题/正文色板与字体全部可视化）；内置 6 套主题 + 独立「自定义主题」区：输入描述 → **AI 后台生成**（可反复重新生成）→ 可视化预览 → 保存并应用；自定义主题可修改/删除、全局复用，内置主题只读；内容页按 `layout` 出**流程 / 步骤 / 卡片 / 数据 / 金句**版式（编号卡片 + 卡间箭头 + 底部「结论」条，含 `data` 大数字），无节点的页沿用原文字排版（向后兼容）；生成时注入入场动画与转场（卡片逐条淡入） |
| 产物管理 | 进入第 2/3 步**自动展示已有产物**（PPT / 计时版 / 视频的大小、时间、下载；视频内嵌播放）；重新生成即覆盖同名文件 |
| 生成视频 | ① **静帧渲染**：PowerPoint COM 截图 + ffmpeg 合成 mp4（分辨率 1080p/720p、帧率可选）；② **计时动画版 pptx**：无需外部软件，交 Office 导出/录屏；计时模式自动禁用无关项；渲染失败显示**脚本退出码 + stderr 摘要**，缺 ffmpeg 时降级为帧序列 |
| 总结报告 | 进入第 4 步**自动生成 / 加载**报告（也可点「生成 / 更新报告」覆盖更新）；Markdown 自动渲染（零第三方依赖、无 `v-html`）；独立「📦 产物清单」表格，每项可下载 |
| 任务化 | 顶部步骤条**点击跳转已完成节点**；任务详情展示 4 节点状态并可「前往」；running/preparing 任务支持**强制删除**；插件启动时残留任务自动标记 `interrupted`；`.tasklist.json` 持久化，DSH 重启可回看 |
| 设置 / 须知 | 顶部「⚙️ 设置」（入口位置、AI 接口与 Key，读取脱敏）与「📖 须知」（两种渲染模式差异、PowerPoint/ffmpeg 安装指引与验证命令） |
| 模型工具 | `pptvm_config / prompts / workspace / deck / task / import / review / outline / content / chat / ppt / video / report`，agent 可端到端驱动 |

## 📦 安装

> **本插件无原生依赖**，安装时**不需要**放行任何构建脚本（与 datatransfer 的 oracledb/odbc 情况不同）。
> 运行依赖 `pptxgenjs` / `jszip` 会随插件安装自动就绪。
> 环境要求：DSH（web profile）、Node.js ≥ 18、pnpm ≥ 10（11 兼容）；「静帧渲染」另需本机 PowerPoint/Office 桌面版与 ffmpeg（见下）。

### 方式一：市场 UI 安装（推荐给最终用户）

> 前提：插件已收录进 DSH 市场目录；未收录时市场搜不到，请改用方式二/三。

1. 打开 DSH → **设置 → 市场**；
2. 搜索 `dsh-pptvm-studio`（或浏览「插件市场」分类）找到卡片 → 点「**安装**」→「**确认安装**」；
3. 看到「已安装 · 刷新页面后生效」后：**完全退出并重启 DSH**，浏览器 **Ctrl+F5 硬刷新**；
4. 侧边栏出现「📊 PPT 成片」即成功；
5. 「静帧渲染」模式还需本机 PowerPoint/ffmpeg，见下方「外部软件」。

### 方式二：一键脚本（推荐给能拿到源码的人）

先获取插件源码（`install-to-dsh.mjs` 就在仓库里），再在**插件根目录**执行（幂等，可反复运行）：

```bash
git clone <本插件仓库>            # 或直接使用工作区内的插件目录
cd dsh-pptvm-studio

node install-to-dsh.mjs                          # 安装到默认 web profile
DSH_PROFILE=<profile> node install-to-dsh.mjs    # 安装到其它 profile
```

脚本自动完成：① 在 profile 的 `dependencies` 写入 `file:<插件目录>`；② 执行 `pnpm install --no-frozen-lockfile`
（`pptxgenjs` / `jszip` 随之自动安装）；③ 兜底把包名加入 `dsh.profile.bundles`；④ 打印重启指引。
完成后：**完全退出并重启 DSH**，浏览器 **Ctrl+F5 硬刷新**。



### 方式三：DSH 官方 CLI

```bash
# ⚠️ 需在 DSH CLI 源码仓库目录运行（dsh 是该工作区注册的 pnpm 插件）
cd <DSH-CLI-源码目录>
pnpm dsh plugin --profile web add https://gitee.com/godbirds/dsh-autobook-gener.git
```

1. 确认 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 含 `dsh-autobook-gener`（不在则手动追加）；



### 方式四：手动安装（备用）

```bash
pnpm --dir ~/.dsh/profiles/web add "file:<本插件目录>"     # 或 git 地址
```

再编辑 `~/.dsh/profiles/web/package.json`，在 `dsh.profile.bundles` 末尾追加 `"dsh-pptvm-studio"`，
然后**完全退出并重启 DSH** + Ctrl+F5。

> CLI 变体：若使用 DSH 官方 CLI，可在其源码目录执行
> `pnpm dsh plugin --profile web add <本插件 git 地址或本地路径>`，确认 `dsh.profile.bundles` 含包名后重启。

**更新插件**：重新执行方式二/三拉取最新版本；若为已安装副本，也可在插件根执行 `node sync-to-dsh.mjs` 增量同步，然后**重启 DSH + Ctrl+F5**。

**卸载**：从 profile 的 `dependencies` 与 `dsh.profile.bundles` 中移除 `dsh-pptvm-studio` 并执行一次 `pnpm install`，重启 DSH 即可。
（配置 / 自定义主题 / 报告位于 `~/.dsh/dsh-pptvm-studio/`，可自行保留或删除。）

### 外部软件（仅「静帧渲染」模式需要）

| 软件 | 是否必需 | 安装方式 |
| --- | --- | --- |
| PowerPoint / Microsoft 365（**桌面版**） | 必需（静帧渲染截图） | 打开 microsoft.com/microsoft-365 或 portal.office.com → 安装含 PowerPoint 的桌面版 → 重启 DSH。网页版不支持 COM |
| ffmpeg | 建议（合成 mp4） | `winget install Gyan.FFmpeg` / `scoop install ffmpeg` / 官网 gyan.dev 解压后加入 PATH；验证 `ffmpeg -version` |

> 未装 ffmpeg 不会失败：插件会导出 `frames/*.png` 与计时文件，安装后可再合成 mp4。
> 仅用「计时动画版 pptx」模式时，**无需任何外部软件**。GUI 顶部「📖 须知」内有同样指引。

## 🖥 快速使用（四步向导）

1. **内容确认**：选已有任务，或直接在任务下拉里输入新名称后点「＋ 新建任务」（无需先点下拉项）→ 导入 `MD`/`PPTX` 或「💬 AI 起草大纲」（录入框为 **20 行文本域**，可写主题+受众+关键信息，Ctrl/⌘+Enter 起草）→ 运行审查（规则）与「AI 二次审查」（后台任务）→ 在大纲表格与右侧编辑区修改；可用行内开关或右下角一键锁控。
2. **生成 PPT**：选主题（4 列卡片，可直接看出配色/字体效果）；需要新风格时在「自定义主题」区用一段文字描述让 AI 生成（可反复重新生成，满意后「保存并应用」，其他任务也能选到）→「🎬 生成 PPT」（重复生成覆盖同名文件）。含 `节点/结论` 的页会自动出**卡片/流程/步骤**版式与底部**结论条**，并逐卡入场。
3. **生成视频**：选模式 —— ①静帧渲染（需 PowerPoint + ffmpeg，可选分辨率/帧率）②计时动画版 pptx（无外部依赖）；生成后页面直接内嵌播放/下载。
4. **总结报告**：进入即自动生成/加载报告；点「生成 / 更新报告」按最新产物覆盖更新；「汇总当前产物」查看独立产物清单并可逐项下载。

## 🗂 目录结构

```
dsh-pptvm-studio/
├── src/                      # Host 端（Node ESM，业务零 DSH 依赖）
│   ├── index.js              # 入口：createApp + 注册 pptvm_* 工具 + /ppt-video-maker RPC；启动时标记残留任务
│   ├── app.js                # 组合根（构造注入装配全部服务）
│   ├── tools.js              # ToolRegistry：pptvm_*（schema 序列化守卫）
│   ├── rpc.js                # RpcServer：仅 POST + JSON 校验 + { ok, data }；artifact 流式下载
│   ├── core/
│   │   ├── config.js         # 配置持久化（~/.dsh/dsh-pptvm-studio/config.json，原子写 + Key 掩码保护）
│   │   ├── deps.js           # 第三方依赖加载（CJS 产物优先，规避宿主 require(esm) 循环）
│   │   └── prompts/          # ppt-outline.md（默认大纲生成提示词）
│   ├── services/             # workspace / deck / outline / content / deck-import / importer /
│   │                         # review / ai / ai-jobs / theme / theme-jobs / pptgen / video /
│   │                         # report / artifact / task / task-list / animator
│   ├── engine/               # ooanim.js（动画 OOXML）+ ppt/…（示例资产，运行时以 services 为准）
│   └── script/               # video-render.ps1（PowerPoint 截图 + ffmpeg 合成；UTF-8 BOM）
├── frontend/                 # Vue3 + Element Plus 工程（build.mjs → 根目录 client.js）
├── client.js                 # 构建产物（勿手改，需提交入库）
├── docs/                     # 01 需求设计 / 02 开发实现 / 03 阶段规划 / 04 大纲生成提示词
├── test/                     # core / task / tools-schema / engine / p1–p4 / theme（+ 可选 e2e）
├── builder.mjs               # 一键发布：release.mjs + sync-to-dsh.mjs
├── release.mjs               # 构建 + 全量验证 + 结构自检 + pnpm audit 提示
├── sync-to-dsh.mjs           # 同步到 DSH profile 副本（file: 形态支持 Junction，含依赖自检）
└── install-to-dsh.mjs        # 一键安装到 DSH profile（写 file: 依赖 + pnpm install + bundles）
```

## 💻 本地开发 / 发布

```bash
node test/run.mjs                             # 全量测试（文档零依赖或本地依赖均可跑）
cd frontend && npm run build                  # 重建 client.js（改前端后必须执行）
node builder.mjs                              # release（构建 + 验证 + 依赖审计）→ sync 到 DSH
```

发布后：**完全退出并重启 DSH**，浏览器 Ctrl+F5 硬刷新。

## 🛠 测试

| 文件 | 覆盖 |
| --- | --- |
| `test/core.test.mjs` | 配置默认/脱敏、**掩码与空串不覆盖 Key**、提示词、工作空间、deck CRUD |
| `test/task.test.mjs` | 任务状态机、`.tasklist.json`、非 force 禁删 / **force 强删**、**非法 taskId 拒绝**、残留任务 `interrupted`、RPC 冒烟 |
| `test/tools-schema.test.mjs` | 全部 `pptvm_*` 工具 schema 无 `undefined` |
| `test/engine.test.mjs` | 引擎（动画 OOXML 注入、计时/转场构造） |
| `test/p1.test.mjs` | md 双形态解析、**结构化字段（版式/节点/结论）解析与落盘、未知字段不污染**、页写入、大纲/内容/锁定、审查与修复（含 `points_count` / `conclusion_missing` 规则）、AI 二次审查（降级与解析） |
| `test/p2.test.mjs` | 真实 pptxgenjs/jszip 生成 + 动画；**卡片/流程版式与结论条落地（形状数 > 纯文字页、动画目标存在性断言）**；主题自定义保存/合并/RPC |
| `test/video.test.mjs` | 计时换算、advTm 注入、jszip 自动加载、`render-result.json`（含 BOM）解析、渲染管线 fake runner |
| `test/report.test.mjs` | 报告固定文件名覆盖、磁盘回退、产物统计、**artifact.list**、非法 taskId 拒绝、删除联动 |
| `test/theme.test.mjs` | 全局 `.ppttheme.json`、旧文件兼容、prompt/时间戳、内置不可删、AI 主题长任务（成功/失败） |

> 依赖 `pptxgenjs`/`jszip` 从本插件 `node_modules` 解析（可移植）；`test/e2e.mjs` 为安装后手动冒烟（无参时用内联样例）。

## ❓ 常见问题

| 问题 | 处理 |
| --- | --- |
| 装了插件没生效 / GUI 入口不出现 | 确认包名在 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles`；运行 `node install-to-dsh.mjs` 后**完全重启** DSH 并 Ctrl+F5 |
| 生成 PPT 提示“缺少依赖 pptxgenjs” | 运行 `node install-to-dsh.mjs` 或 `node sync-to-dsh.mjs`（会自动在 profile 安装运行依赖）后重启 |
| 生成视频提示“渲染脚本未返回结果” | 现在会显示**脚本退出码 + stderr 摘要**：多为缺 PowerPoint/ffmpeg；按「📖 须知」安装后重启 |
| 缺 ffmpeg | 仍会导出 `frames/*.png` 与计时 JSON；安装 ffmpeg（`winget install Gyan.FFmpeg`）后可重新生成 mp4 |
| 缺 PowerPoint | 静帧渲染不可用；可改用「计时动画版 pptx」，用 Office 导出视频/录屏 |
| AI 二次审查 / 主题生成失败 | 检查「⚙️ 设置」中的 AI 接口与 Key，或确认 DSH 默认模型可用；主题生成是后台任务，可在日志区看到进度 |
| 报告不显示 | 进入第 4 步会自动生成/加载；如为空点「生成 / 更新报告」 |
| 任务删不掉 | running/preparing 任务会显示「**强制删除**」，二次确认后清理日志/报告（任务目录产物保留） |
| 切换任务后还能选到自定义主题 | 预期行为：自定义主题存全局 `.ppttheme.json`，所有任务共享 |
| 请求超时 | 长任务（AI/渲染）默认 10 分钟；若频繁超时请检查模型或本机 Office/ffmpeg 环境 |
| 市场里搜不到本插件 | 插件尚未收录进市场目录 → 用「方式二：一键脚本」或「方式三：手动安装」 |
| 如何更新到最新版本 | 重跑方式二/三（或对已安装副本执行 `node sync-to-dsh.mjs`）后**重启 DSH + Ctrl+F5** |

## 🔐 安全与健壮性

- RPC **仅允许 POST**，请求体 JSON 校验（非法 → 400）；统一 `{ ok, data }` 返回；
- 产物下载：限定工作空间内（`path.relative` + realpath 判定），且仅允许 `pptx/mp4/json/md/png`；
- 任务 ID 全链路校验（防路径穿越）；报告文件名由校验后的 ID 生成；
- API Key 读取脱敏、**掩码/空串不覆盖**已保存值；LLM `baseUrl` 限 http(s)；指定 ffmpeg 路径必须存在；
- pptx 导入防 zip 炸弹（条目数 / 解压总体积上限）；`config.json`、`.tasklist.json`、`.ppttheme.json` **原子写**；
- 长耗时 AI 调用采用**后台任务 + 轮询**（`ai.job.start/poll`、`theme.draft.start/poll`），避免界面长时间无响应；
- 依赖安全：`node builder.mjs` 末尾执行 `pnpm audit --prod`（无 `pnpm-lock.yaml` 时回退 `npm audit --omit=dev`）提示（不阻断发布）；当前 `pptxgenjs → image-size` 有 2 个 high 级 DoS 告警（上游未修复，插件自身不调用图片解析路径）。

## 📚 相关文档

| 文档 | 说明 |
| --- | --- |
| [docs/01-需求设计文档.md](docs/01-需求设计文档.md) | 需求基线、功能清单（含「运行环境要求」附录） |
| [docs/02-开发实现说明.md](docs/02-开发实现说明.md) | 架构、服务分工、RPC/工具清单、安全与测试 |
| [docs/03-阶段实施规划.md](docs/03-阶段实施规划.md) | P0–P5 阶段交付与状态 |
| [docs/04-大纲生成提示词.md](docs/04-大纲生成提示词.md) | 默认大纲生成提示词（对话起草 / 审查基准） |

## ⚠️ 已知边界

- **静帧渲染仅 Windows**：依赖 PowerPoint COM 自动化；无 Office 时请用「计时动画版 pptx」；
- **无 ffmpeg**：仅产出 PNG 帧序列与计时文件（不阻断流程），装好后可再合成 mp4；
- **时长估算**：按口播字数（约 4.2 字/秒）估算，非逐帧对齐，实际请以试听为准；
- **视频在线预览**：当前下载端点未实现 HTTP Range，拖动进度可能受限（可视为已知项，后续增强）；
- **主题令牌**：AI 生成的主题为“配色 + 字体”级别的设计令牌，不改变版面结构（卡片/流程版式会取用 `panel/line/accent/gold` 令牌）；
- **结构化内容为可选**：页 md 无 `points/conclusion/layout` 的老任务仍按原「核心文案 + 视觉元素」文字排版出图，行为不变；
- **结构角色词会被剥离**：`封面：X` / `行动召唤：Y` / `原因分析：Z` 这类提示词前缀在**导入落盘**与**出图**时自动剥离（历史 deck 重新生成 PPT 也生效）；标题若只剩角色词（如 `封面`），出图回退到核心文案；如需保留原样请在编辑器中手动改回；
- **卡片动画**：卡片底（无文字形状）不参与逐拍动画，卡片内「序号 / 主张 / 佐证」按卡依次淡入（卡片容器先显示，后续可增强为整卡同拍）；
- **pptx 再导入**：解析正文与备注（口播），不保证像素级还原用户手工排版（采用“回灌内容、重新出图”模型）；
- **引擎示例文件**（`src/engine/*.example.js`）为参考资产，不参与运行时逻辑。