EZ118/dsh-ppt-composer

dsh-ppt-composer

DeepSeek Harness 的 AI PPT 生成助手 Cordis 插件。在对话中完成 PPT 的创作全流程：内容确认 → 多页结构生成 → 媒体（图片/视频/图表）→ 主题 v2（每页独立配色/字体/SVG 装饰/入场动画）→ 实时浮动预览 → 独立 HTML 导出。

- Host 端：按会话存储 PPT、12 个模型工具（ppt_）、ppt/state / ppt/export RPC、独立 HTML 导出器、工作流系统提示词。
- Client 端：shell.overlay 中的可拖拽浮动预览面板（可调大小、翻页、缩略图、导出、toast 提示）、全屏演示层、会话头部开关按钮。

功能特性

| 能力 | 说明 |
| --- | --- |
| 对话式生成 | AI 主动询问主题/受众/结构 → 确认后拆解为多页 → 确认内容 → 询问配色 → 套用 → 导出 |
| 长宽比与过渡 | 16:9 / 4:3；页间过渡 fade / slide / zoom / none |
| 媒体支持 | image（URL / data URI）、video（控制条播放）、chart（CSS 柱状图，导出自包含） |
| 主题 v2 | 文档主题（配色/双字体/圆角）+ 每页局部主题覆盖（slide.theme），各页可不同配色/字体 |
| SVG 装饰 | slide.decor 内联 SVG（折线时间线箭头、流程图步骤、几何装饰），viewBox 0 0 1920 1080/1440 铺满整页、位于内容下层 |
| 入场动画 | slide.entrance：fade / rise / zoom / none，标题与正文分段错峰 |
| 页面对齐 | slide.align：center / top（带 decor 的复杂模板页默认 top，标题固定在顶部不与装饰重叠） |
| 实时预览 | 固定逻辑画布（1920×1080 / 1920×1440）transform: scale 缩放居中；可拖拽、右下角调整大小、翻页、缩略图跳转、导出 |
| HTML 导出 | 与预览同画布的自包含 HTML：键盘翻页、翻页按钮组、窗口自适应缩放、主题/装饰/动画一致 |

目录结构

dsh-ppt-composer/
├── package.json            # dsh 插件包元数据（exports、dsh 字段、Cordis peer 依赖）
├── README.md
├── LICENSE                 # MIT
├── .gitignore
├── src/
│   ├── host.js             # Host 插件体（权威源码，即 code.host 原文）
│   ├── client.js           # Client 插件体（权威源码，即 code.client 原文）
│   └── index.js            # 入口：读取两份源码并以字符串导出，供 cordis_define 使用
└── examples/
├── sample-slides.json  # 示例幻灯片结构（含时间线 decor 与每页主题）
└── demo/               # 测试导出的 HTML（gitignore，可再生成）

安装与加载

本仓库以 动态 Cordis 插件 形式分发：src/host.js 与 src/client.js 就是
cordis_define 所需的 code.host / code.client 原文（已验证可运行），单一事实来源。

方式一：动态加载（推荐，开箱即用）

在 DSH 会话中让模型执行 cordis_define：

import { definePayload } from './src/index.js'   // 或直接读取 src/host.js / src/client.js

definePayload()
// => { code: { host: , client:  } }

把 definePayload() 的返回传给 cordis_define({ plugin: { kind: 'new', idPrefix: 'pptco' }, …, code })，
随后 cordis_run 激活并批准运行。激活后当前会话即可使用全部 ppt_ 工具与预览面板。

重装（DSH 重启后）： 动态插件注册表是进程内内存，重启即失。仓库已预生成
install-payload.json（cordis_define 的完整载荷，含 code.host / code.client 原文，
与 src/ 字节级一致）。重装时读取该文件、把 plugin / name / purpose / code 原样传入
cordis_define 即可，无需转写源码。修改过 src/ 之后，重新生成载荷：

npm run make-payload   # 或 node scripts/make-payload.mjs

方式二：静态挂载（需少量适配）

DSH 部署通过 profile 的 cordis.patch.yml 挂载插件。src/host.js / src/client.js
目前使用动态运行器的全局 harness（defineTool / registerTool / handle）与
host.call 桥。静态挂载时需将：

- harness.defineTool / harness.registerTool → ctx.tools.register(toolDefinition)；
- harness.handle('ppt/state'|'ppt/export') → 通过会话/客户端 RPC 服务暴露；
- Client 的 host.call('ppt/…') → 替换为对应静态 RPC 通道。

（后续版本可提供静态适配层；欢迎 PR。）

使用流程（模型工作流，已内置系统提示词）

1. 用户表示要制作 PPT 或粘贴文案 → AI 确认主题/受众/结构，并确认 长宽比 与是否需要 页间过渡动画。
2. 确认后 ppt_create 一次性创建（空白默认主题、基础排版，不上色）。
3. ppt_slide_add / ppt_slide_update / ppt_slide_remove 微调，ppt_get 复核。
4. 内容确认后询问配色 → ppt_theme_create → ppt_theme_apply；不满意 ppt_theme_update 微调。
5. 满意后 ppt_export 导出独立 HTML 到会话工作区。

工具参考

| 工具 | 作用 |
| --- | --- |
| ppt_create | 创建/重建 PPT（title、slides[]、ratio、transition） |
| ppt_get | 读取完整状态（含每页 id、当前主题、可用主题） |
| ppt_update | 整体修改（标题/整组幻灯片/长宽比/过渡/主题） |
| ppt_delete | 删除当前会话 PPT |
| ppt_slide_add | 插入一页（slide、index?） |
| ppt_slide_update | 按 slideId 局部修改（patch 覆盖） |
| ppt_slide_remove | 按 slideId 删除 |
| ppt_theme_create | 创建主题（colors/fontFamily/fonts/radius） |
| ppt_theme_update | 修改主题（部分覆盖；默认主题不可改） |
| ppt_theme_get | 读取主题/列表/当前主题 |
| ppt_theme_apply | 套用主题到当前 PPT |
| ppt_export | 导出独立 HTML 到会话工作区 |

数据结构

幻灯片 slide

{
id: 's1',                       // 可选，唯一标识
layout: 'cover',                // cover | title | content | two-column | section | closing | blank
title: '…', subtitle: '…',
bullets: ['…'],                 // 要点（content）
paragraphs: ['…'],              // 段落（content）
columns: [{ heading: '…', bullets: ['…'] }],  // 双栏
quote: '…', quoteAuthor: '…',   // 引言
code: '…',                      // 代码块
image: 'https://… | data:…',    // 图片（content）
imageAlt: '…',
video: 'https://…',             // 视频（content）
chart: { labels: ['Q1'], values: [42] },      // 柱状图（content）
decor: '…',   // SVG 内联装饰，整页下层
theme: { colors?: {…}, fontFamily?: '…', fonts?: { heading?, body? }, radius?: 8 },  // 本页主题覆盖
entrance: 'fade',               // fade | rise | zoom | none
align: 'center',                // center | top（带 decor 默认 top）
note: '演讲备注'                 // 不渲染
}

主题 theme

{
id: 'slate', name: '石板夜',
colors: {
background: '#0f172a',   // 背景
foreground: '#f1f5f9',   // 主文字
accent: '#60a5fa',       // 强调色
muted: '#94a3b8',        // 次要文字
surface: '#1e293b',      // 卡片底色
},
fontFamily: '',                      // 可选，正文默认
fonts: { heading: '…', body: '…' },  // 可选，标题/正文分开
radius: 8,
}

所有颜色必须为十六进制。文档主题 + 每页 slide.theme 合并后渲染；预览与导出
（1920×1080 / 1920×1440 固定画布）共用同一套排版规则，所见即所得。

导出文件说明

ppt_export 生成的 HTML：

- 与预览完全相同的 1920×1080（16:9）/ 1920×1440（4:3）画布与排版；
- 自包含（无外部依赖），/ 引用外部 URL 时需联网，data URI 则完全离线；
- 键盘翻页：← → 空格 PgUp/PgDn Home End；
- 右下角「上一页 / 下一页」翻页按钮组；窗口缩放自适应居中；
- 主题/装饰/入场动画与预览一致。

开发与测试

- 纯 JavaScript + React（React.createElement），无需构建步骤。
- 修改 src/host.js / src/client.js 后，重新通过动态加载即可生效（更新时用 cordis_run mode:"update"）。
- 快速自测：按上文「使用流程」走一遍 创建 → 读取 → 主题 → 导出，并在预览面板核对翻页/缩放/主题。
- 示例结构见 examples/sample-slides.json（含折线时间线 decor 与每页独立主题）。

许可

MIT © 2026 dsh-ppt-composer contributors