easyppt

Readme

# easyppt — 自动化 PPT 生成（DSH dsh-plugin）

> **English**: [README.en.md](README.en.md) · 上传 GitHub 教程：[docs/UPLOAD_TO_GITHUB.md](docs/UPLOAD_TO_GITHUB.md)

`easyppt` 是一个面向 **DeepSeek Harness (DSH)** 的演示文稿生成 **dsh-plugin**（npm 包 + Cordis bundle + 内置技能）。用户输入大纲（Markdown / JSON / 自然语言）与插图，即可基于 **DSH 原生 Univer 工具链**生成：

- **`<name>.pptx`** —— 标准 16:9，可在 PowerPoint / Keynote / WPS 中打开并自由编辑；
- **`build/<name>.html`** —— 自包含的网页放映版，用于浏览器离线预览；
- **`build/<name>.manifest.json`** —— 结构化清单，记录主题、配色、字体与每页内容，便于版本管理。

> 设计说明：渲染不在此插件内重写。`easyppt` 负责**输入校验、大纲归一、主题解析与构建清单**，
> 实际幻灯片渲染由模型按 `SKILL.md` 驱动 DSH 原生 `univer_*` 工具完成（生成、lint、
> 截图、导出可编辑 .pptx）。这复用 DSH 的可编辑出库管线，避免重复实现排版引擎。

---

## 目录结构

```
easyppt/
├── package.json                # dsh-plugin 包元数据（dsh.bundle.patch / main / peerDeps）
├── cordis.patch.yml            # profile bundle 补丁：插入 easyppt 插件行
├── index.js                    # Cordis 插件入口：注册 ppt_create / ppt_themes / ppt_template_list / ppt_template_upload + easyppt 技能
├── lib/
│   ├── themes.json             # 10 套内置视觉主题（id / 场景 / 配色 / 字体 / 版式）
│   ├── themes.js               # 主题库：list / get / resolve
│   ├── outline.js              # 大纲解析：Markdown / JSON / 自然语言 -> 归一化 deck
│   └── template-parser.js      # 模板上传校验 + 注册表 + 从 Univer 快照推导样式
├── skills/easyppt/
│   ├── SKILL.md                # 生成工作流（主题规范、逐页 SVG、校验、导出）
│   └── themes.json             # 随技能分发的主题清单（资源目录）
├── preset/
│   ├── preset.yml              # 预设展示元数据
│   └── agent.cordis.yml        # PPT 模式预设（standard 基础 + 设计师 persona + 技能层）
├── docs/theme.schema.json      # themes.json 的 JSON Schema
└── README.md
```

---

## 安装（dsh-plugin 一键安装）

依赖：已安装 DeepSeek Harness（含 `dsh-univer-office` 提供的 `univer_*` 工具链）。
peer 依赖（`@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-skill` / `@deepseek-ai/cordis`）由 DSH
宿主自动解析，无需单独安装。

### 方式一：从 GitHub 安装（推荐）

```powershell
dsh plugin --profile web add https://github.com/<你的用户名>/easyppt
```

### 方式二：本地路径安装（开发调试）

```powershell
dsh plugin --profile web add ./easyppt        # 或 dsh plugin --profile web add C:\path\to\easyppt
```

> `dsh plugin` 是一个 pnpm 转发器：安装后自动把声明了 `dsh.bundle.patch` 的依赖并入
> `dsh.profile.bundles` 层，无需手改配置。**重启 DSH 生效**。

安装后插件会：

1. 注册 4 个模型可见工具：`ppt_create`、`ppt_themes`、`ppt_template_list`、`ppt_template_upload`；
2. 注册内置 **easyppt** 技能（主题库 + 生成工作流），任意会话可按需加载。

卸载：`dsh plugin --profile web remove easyppt`（或 `dsh plugin --profile web rm easyppt`）。

### 方式三（可选）：EasyPPT 模式（Agent 预设会话）

想让 DSH Web 控制台出现独立的 **EasyPPT** 会话模式，把 `preset/` 复制到用户预设目录：

```powershell
$dest = "$env:USERPROFILE\.dsh\.agent-presets\easyppt"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item -Recurse -Force "preset\*" $dest
Copy-Item -Recurse -Force "skills\easyppt" "$dest\skills\"
Copy-Item -Force "lib\themes.json" "$dest\skills\easyppt\themes.json"
```

重启后新建会话选择 **EasyPPT** 即进入“PPT 模式”，会话自动加载设计师 persona 与 easyppt 技能。

> 未装 bundle 前，`ppt_*` 工具也可在单个会话内通过 `cordis_define` + `cordis_run`
> 注册等价动态插件试用（见下文“快速试用工具”）。核心生成能力始终由技能 + 原生 `univer_*` 工具提供。

---

## 使用

### 命令行 / 一次性指令

让模型生成一份 PPT，一句话即可：

> `请用 easyppt 生成一份主题为‘data’的《AI 产品发布》PPT`，并传入你的大纲与插图路径。

等价地，调用工具：

```jsonc
ppt_create {
  title: "AI 产品发布",
  content: "# AI 产品发布\n## 市场机会\n- 市场空间大\n- 增速快\n## 产品方案\n- 核心亮点一\n- 核心亮点二",
  theme: "data",
  lang: "zh"
}
```

### Web 界面（PPT 模式）

1. 新建会话，选择 **EasyPPT** 预设。
2. 用自然语言给出：标题、大纲（可粘贴 Markdown / 上传 JSON）、插图（拖入工作区）。
3. 可指定主题（id）或要求“把这份 .pptx 作为模板”。
4. 模型按技能生成：建 `.univer` → 逐页 SVG → 校验 → 导出 `.pptx` + HTML + manifest。

### 常用命令

| 意图 | 命令 |
| --- | --- |
| 查看所有可用主题 | `ppt_themes`（或 `ppt_themes {format:"full"}`） |
| 查看所有模板（内置+自定义） | `ppt_template_list` |
| 上传自定义模板 | `ppt_template_upload {file:"templates/公司模板.pptx", name:"公司模板"}` |
| 生成并落盘构建清单 | `ppt_create {title:"…", content:"…", theme:"business", lang:"zh"}` |
| 打开/编辑生成的源文件 | 在 Web 工作区打开 `<name>.univer`，或直接编辑导出的 `.pptx` |

---

## 内置主题（10 套）

| id | 名称 | 适用场景 |
| --- | --- | --- |
| `data` | 科技感深色 | 科技、AI、大数据、产品发布、开发者大会 |
| `business` | 商务理性 | 经营分析、项目汇报、跨部门评审 |
| `executive` | 高管汇报 | 董事会、战略、投融资、高管述职 |
| `warm` | 温暖人本 | HR、培训、团队文化、公益、用户报告 |
| `minimal` | 极简留白 | 设计、品牌、作品集、极简产品 |
| `education` | 教育培训 | 课程、教学、讲座、知识科普 |
| `finance` | 金融报告 | 银行、证券、基金、财报、投研 |
| `health` | 医疗健康 | 医疗、医院、健康产品、临床试验 |
| `startup` | 创业路演 | 融资路演、创业大赛、Demo Day |
| `academic` | 学术论文 | 论文答辩、学术报告、研究工作汇报 |

每套主题在 `lib/themes.json` 中定义了完整的 `colors`（bg/panel/primary/secondary/accent/
text/muted/line…）、`fonts`（title/heading/body 的字族、字重、字号）与 `layout`
（标题栏、页脚、圆角、最大要点数、推荐结构）。

---

## 模板管理

内置主题无需额外文件。自定义模板三步：

1. `ppt_template_upload`（或直接把 `.pptx` 放进工作区）校验并入库；
2. 用 `univer_import` 将该 `.pptx` 导入草稿工作区，`univer_inspect` 读取其配色/字体；
3. 用 `lib/template-parser.js` 的 `deriveStyleFromSnapshot`（或自行归纳）得到样式，
   写入 `.easyppt/templates.json`。之后即可用 `ppt_create template:<id>` 像内置主题一样选用。

> 上传限制：`.pptx`，位于会话工作区内，单个 ≤ 20 MiB。

---

## 快速试用工具（动态插件）

在当前会话（无需改动 profile）注册 `index.js` 的等价动态插件，使 `ppt_*` 工具立即可见：

1. 用 `cordis_define` 定义插件（`host` 返回一个 `apply`，内部用
   `harness.defineTool` + `harness.registerTool` 注册 4 个工具）。
2. 用 `cordis_run` 激活。
3. `cordis_inspect_query`（Host `Tool.listTools`）确认 4 个工具已出现。

> 动态插件随进程回收，不写入磁盘；用于试用与验证。持久化请走上面的 bundle 安装。

---

## 校验与质量

- 每页 `univer_inspect`（结构）→ `univer_lint`（文字出界/溢出/重叠）→ `univer_screenshot`
  （渲染帧）三连校验后再导出。
- 遵循主题 token，避免夸色/字体；`maxBullets` 约束每页要点数量，宁可少而精。
- 仅使用工作区内的 PNG/JPG/GIF 插图，单张 ≤ 20 MiB，经 `<image>` 嵌入。

---

## 许可

MIT。Univer 集成由 `dsh-univer-office` 提供。
"# dsh-plugin-easyppt"