SuperstructureJH/dsh-workbuddy-ppt

WorkBuddy PPT 插件

English | 中文

dsh-workbuddy-ppt 是可直接安装的 DSH 演示文稿插件。默认 PPT 模式把自研 Kimi-compatible 创作 Skill、PPTD v2 确定性检查和可编辑 PowerPoint 渲染器完整打进 npm 包；全新 DSH profile 无需 WorkBuddy、Kimi 服务或运行时、SlideP 或 Tencent Docs SDK 就能生成 PPTX。可选 Slides 模式使用操作者有权使用的 Tencent PPT Skill、SlideP 和 Tencent Docs 本地运行时，承担独立的 JSX 与模板工作流。两条链路共同使用受控工作区图片、会话存储、审批、审计和最终文件预览。

dsh plugin --profile web add dsh-workbuddy-ppt

文档

• 安装与首次运行
• 配置参考
• 兼容性矩阵
• 架构
• 验证与发行门禁
• 变更记录
• 安全策略
• 贡献指南

执行链路

Slides 与 PPT 作为两个互斥操作显示在共享 New Session 输入框下方，文件继续使用统一附件、粘贴和拖拽链路。每个模式只展示自己的模板，并保留服务端权威 selectedTemplateId。PPT 内置来自 open-kimi-ppt-skill 的 44 套不重复 MIT 许可视觉参考包；每张卡片内置 3 页预览，ppt_get_template_reference 会返回所选模板的设计说明和全部 6 至 8 页可读参考。Slides 内置完整解析的 58 页“数据分析”和 58 页“活力蓝色”，116 个源页均带本地预览、语义索引和静态 SlideP JSX 结构参考。再次点击已选卡片或点击输入框缩略图的取消按钮会清除选择，同时保持模板区展开；取消请求被拒绝时，已加载目录和当前选择继续显示，并在目录内展示错误。

PPT 场景生成执行自包含流程：

1. 模型加载包内 kimi-ppt Skill，列出 PPT 模板目录，完整读取所选模板的视觉参考包，再编写完整场景；页面同时包含语义回退信息和按 PowerPoint 英寸计量的顺序原生文本、图形、图表与工作区图片元素。
2. ppt_scene_check 检查唯一 ID、页面边界、文字容量估算、字号、非预期重叠、图表序列结构和工作区图片。返回的 scene_hash 同时覆盖标准化场景和已准入图片的 SHA-256。
3. 模型修正后重复检查，直到状态为 pass 或 warning，再在同一轮使用原场景和准确 hash 调用 ppt_scene_create。Host 会在编译前重新计算 hash；场景内容或图片字节变化都会让回执失效。
4. Host 把已检查场景序列化为 deck.pptd 和逐页 .page 文件，再通过共享 PPTD 引擎解析该项目；结构或资源错误会在渲染前被拒绝。PPTD 因此成为渲染器真正消费的源，而不是旁路诊断文件。
5. 共享渲染器不启动 SlideP 或 Tencent Docs，直接写入可编辑文本、图形、线条、表格、图表和项目内图片。工作区交付目录包含 PPTX、PPTD 项目、PRESENTATION.scene.json 和复制后的图片资源。场景型产出在交付 PPTX 中编辑，不进入登记版式的局部更新兼容工具。

本地 PPTD CLI

包内提供可独立使用的 dsh-pptd 命令行入口，与网页 PPT 模式共用同一套转换、解析、检查、预览和渲染核心：

dsh-pptd convert <input>.pptx --output <project-directory> --json
dsh-pptd check <project> --page 1,3-5 --severity error,warning --level keep --json
dsh-pptd check <project> --level auto --json
dsh-pptd inspect <project> --json
dsh-pptd screenshot <project> --page 1-3 --output <screenshots> --scale 2 --json
dsh-pptd render <project> --output <output>.pptx --json

convert 从 PPTX 创建可编辑的 PPTD v2 项目。PPTX 到 PPTD 的转换以明确诊断为目标，不承诺无损：JSON 回执会返回发生归一化和暂不支持的源特性数量；任一数量不为零时，--strict 不发布项目。check --level auto 只执行确定性修复，包括安全类型转换、删除无效可选值和删除结构上无法恢复的可选节点；发生改动的页面 YAML 会整体重写。页码筛选使用从 1 开始的逗号列表或区间，诊断筛选支持严重级别和准确问题代码。

screenshot 通过 SVG 与 Sharp 生成受项目路径约束的本地预览，与 PowerPoint 或 WPS 打开最终 PPTX 属于不同证据层。render、package 和 export 把选中的 PPTD 页面编译为可编辑 PPTX。文件采用原子发布，覆盖既有结果必须显式提供 --force，--json 返回机器可读回执。加载器把页面、图片和生成产物限制在项目或指定输出根目录内，执行单文件与总字节上限，并保持网络资源关闭。

当前可编辑子集覆盖常用富文本标签、纯色填充、常用图形、直线、项目内图片、带主题的原生表格，以及原生柱图、条形图、折线图、面积图、散点图、气泡图、饼图、环形图、雷达图、带次坐标轴的组合图，并为自定义 SVG 路径提供明确的矢量回退。转换器保留原生对象顺序、常见文本 run、几何信息、表格、图表数据、图表方向和次坐标轴归属；复杂 OOXML 样式会归一化为已支持的 PPTD 模型。暂不支持的图表类型和资源违规会返回明确诊断。CLI 不执行也不依赖外部演示文稿运行时。

Slides 生成执行以下流程：

1. 系统提示词要求模型在当前轮调用 skill({"name":"tencent-pptx"})。ppt_create 校验同轮成功回执；用户直接输入 /tencent-pptx 也会形成同轮回执。
2. 插件从自身 runtime 目录加载完整 Tencent PPT Skill，并自动附加包内的 ppt-template-fidelity Skill；后者也可以单独发现。模型把 ppt_list_templates 标记的模板作为输入框当前选择，并按需读取模板页。只有当前请求明确附带了其他模板文件时，模型才在工作区中查找它。存在参考材料时，模型先执行 create-from-material，再执行 create-from-scratch；没有材料时直接执行后者。
3. 内置或上传的源 PPTX 作为模板时，Host 为每个源页保留标题、版式族、内容角色、图表/表格/图片特征、标准化区域坐标、形状、填色、局部文字色、前景/背景关系、字体、连接线、主视觉、画布占比和逐页简化说明。简化说明允许压缩文案和辅助解释，同时保留过半语义版式锚点。原始 shape 数、空 Box 和重复装饰均不计入保真度。生成的静态 SlideP JSX 参考携带这些关系。这个索引来自实际源页，与 PowerPoint Master 无关。
4. 模型先用 ppt_get_template_pages 读取完整语义目录和逐页简化说明，再读取选中源页的详细 JSX 参考。每个输出页在 STORY.md 和 DESIGN.md 中记录源页编号、选择理由和简化方式，并在继承的页面结构内替换内容。
5. 模型一次性提交 STORY.md、DESIGN.md、逐页语义摘要、源页映射、受限 SlideP JSX 和经过检查的图片文件引用。
6. Host 校验每个源页索引模板的输出页面均引用有效源页，并在对应页面区域保留至少 55% 的加权语义版式锚点。锚点来自源页 zone，按语义类型、配色关系和粗粒度空间单元去重；主图表/表格/图片的权重高于文字分组、主要色块和连接线。画布占比低于 1% 的填色形状、整页背景、空 Box 补齐和重复 primitive 均不计分。Host 另行校验选中模板的主要标志色区域、深色填充区的浅色反白文字，以及主图表、主表格或主图片的源页画布占比。字面量数值区域让检查可计量；只有 Flex 尺寸而无法对应源页位置的组件会被拒绝。随后 Host 把项目写入会话派生目录，再逐页检查 JSX。允许登记的 SlideP 组件、Text 内的 span 富文本片段、JSX Fragment、内联 SVG、字面量属性和对字面量数组的局部 map；拒绝出现在 Text 外的 span、import、任意调用、事件、spread、外部 URL 和越界图片路径。
7. 插件通过 ctx.subprocess 启动受管的 editor_sdk 和 SlideP，先运行每页 slidep-validate，再等待首轮同步完成并校验 PPTX ZIP 头。
8. 成功结果先保留一份供打开、下载和审计使用的内部不可变 PPTX 修订版，再把非隐藏交付文件夹原子发布到活动工作区直属目录。WorkBuddy 交付文件夹包含最终 PPTX、STORY.md、DESIGN.md、pages/ 和实际使用的 resources/images/；原生修订版交付最终 PPTX。工作区已有同名内容时，Host 使用新的产出目录并保留原内容。
9. 完成 ppt_create 或 ppt_update_slide 的对话轮次会优先使用 PPT 专用的尾部交付入口，并排在通用“生成文件”入口之前。该入口通过回环 RPC 读取持久化的最终 PPTX，并在浏览器本地渲染文件生成的缩略图和图表。浏览器 ZIP 限制约束解析规模；Host 路径和引擎 URL 不会暴露；文件超出内联限制或本地渲染失败时，界面使用明确标注的内容结构视图。交付卡同时展示工作区中的最终 PPTX，以及打开 PPT、在 Finder 中显示和下载 PPTX操作。WorkBuddy 结果通过打开工作区 PPTX 继续修改；ppt_update_slide 只服务原生兼容渲染器，避免把 WorkBuddy 页面降级成另一套版式。

ppt_create 是 Slides 链路的完整生成入口，接收标题、模板、受众/目的/目标、设计偏好、STORY、DESIGN、顺序页面、逐页模板引用和图片资产。ppt_scene_check 与 ppt_scene_create 归属 PPT 链路。ppt_list_templates 返回当前会话的内置或抽取模板，并标记输入框中的权威 Slides 选择；ppt_get_template_pages 先提供每页语义索引、简化说明和语义版式锚点保留目标，再按最多 12 个源页返回 JSX 结构参考。浏览器显式调用仍可使用原生 PptxGenJS 生成、模板抽取、内容抽取、下载和定位能力。

图片与模型分工

DeepSeek Vision 负责理解图片，不负责生成图片。文本规划、代码和 JSX 可以使用 Pro 或纯文本模型；视觉理解可以使用多模态模型；生图由当前 DSH 会话中独立注册的图片生成工具完成。

Tencent Skill 会先判断哪些页面需要图片，再调用真实可用的生图或图片检索工具，把结果保存到活动工作区。ppt_create.assets 只接受工作区内经过检查的 PNG、JPEG、WebP、GIF 或 SVG，Host 复制后统一通过 resources/images/<file_name> 引用。会话没有生图工具时，Skill 使用图形、图表、排版或内联 SVG 完成页面，不留下图片占位符。

操作者装配的设计系统

操作者可以提供三份有权使用的 Markdown 规范，分别包含 6 套 Academic、6 套 Promotion 和 6 套 Work 风格。插件校验完整的 18 套风格，注册一个精简的 ppt-design-systems 目录 Skill，并为每套风格注册一个虚拟 ppt-style-* Skill。配置存在时，PPT 与 Slides 都先读取目录，再按当前内容只加载一套风格。完整规范不会进入固定提示词，也不会进入非演示文稿轮次。

pnpm --filter dsh-workbuddy-ppt stage:design-systems -- \
  --destination <absolute-design-system-root> \
  --academic <absolute-academic-markdown> \
  --promotion <absolute-promotion-markdown> \
  --work <absolute-work-markdown>

把 pptDesignSystemRoot 设为装配目标，也可以提供 DSH_PPT_DESIGN_SYSTEM_ROOT。根目录必须是绝对路径，并包含装配后的 academic.md、promotion.md 和 work.md。装配器核对类别标记、每类 6 个 PART A 与 6 个 PART B、小节 slug 唯一性，再通过原子重命名写入带 SHA-256 的 manifest。目标目录已经存在时，装配器会停止。

风格 Skill 负责内容层级、构图、排版、配色、图片、图表和页面节奏。用户明确要求、事实和证据保持最高优先级；渲染器的安全、可编辑性、边界、溢出、对比度、审计和确定性检查始终执行。页面使用源模板时，继续保持源页实测分组、层级、前景/背景关系和主视觉；风格只补充兼容决策，不替换源页结构。三份源规范始终是操作者提供的本地文件，本包不重新分发。

可选 Slides 运行时

开源包不重新分发 WorkBuddy 提供的 SlideP 依赖树或 Tencent Docs 原生二进制。操作者把有权使用的本地文件写入插件自有 runtime 目录：

pnpm --filter dsh-workbuddy-ppt bundle
pnpm --filter dsh-workbuddy-ppt stage:workbuddy-runtime -- \
  --destination <absolute-office-ppt-root>/runtime \
  --slidep <absolute-@tencent/slidep-package> \
  --editor-engine <absolute-@tencent/tencent-docs-ai-engine-package> \
  --skill-zip <absolute-tencent-pptx-skill.zip>

构建结果包含 lib/runtime-staging.js，同时发布可由普通 Node 执行的 scripts/stage-workbuddy-runtime.mjs，因此安装后的插件无需 tsx 也能继续使用同一装配器。脚本核对包名、版本、入口、平台二进制和 Skill 必需文件，在同级临时目录中完成复制，再以原子重命名发布。已有目标必须带插件生成的 manifest.json；脚本拒绝覆盖普通目录。manifest 记录平台、版本、Skill 哈希和本地供应说明。

公开 npm 包与默认 PPT 模式不需要这些文件。直接把插件加入 DSH profile：

dsh plugin --profile web add dsh-workbuddy-ppt

bundle patch 把 root 设为 dshHomePath('office-ppt')，可选 Slides runtime 位于 <root>/runtime。Base profile 已提供 Skill Registry、skill 工具和本地 subprocess provider。requireWorkbuddyRuntime: true 会在插件加载时检查 Tencent 运行时；未提供这些文件时，默认 PPT 路径仍可使用，选择 Slides 后会在首次渲染前得到明确的 staging 错误。

主要部署配置包括可选运行时根目录、包内 WorkBuddy PPT Skill 覆盖路径、可选的本地设计系统根目录、Node 可执行文件、回环端口范围、引擎就绪/逐页验证/完整渲染超时、子进程终止宽限、诊断输出上限、验证并发、显式编辑器来源，以及 STORY、DESIGN、单页 JSX、单图和图片总量上限。独立仓库的配置参考列出全部可接受字段和默认值。

存储与安全

浏览器 RPC 只允许 loopback。调用方不能选择 Office 存储或交付路径；Host 读取活动 Session 的工作区，并依据 Session、Deck、标题和修订版生成内部项目、不可变修订版和可见交付位置。完整交付文件夹重命名进入工作区后，服务才提交会话状态。工作区图片先经 realpath 检查，随后检查大小、扩展名和文件签名。模型写操作进入共享 tools/pre-execute 审批流水线。

SlideP 和 editor_sdk 只通过 ctx.subprocess 启动。插件拥有进程句柄、超时、输出上限、终止和等待逻辑；插件卸载时会终止全部页面验证器、渲染器和共享 Tencent Docs 引擎。引擎只绑定回环端口，端口由有界范围探测得出。交付预览读取持久化 Deck 投影与最终文件，并且不向浏览器暴露引擎地址。Skill 内容和运行时二进制均不进入模型工具结果，PPTX 字节和宿主存储键也保持在模型上下文之外。

验证

聚焦测试覆盖真实 Loader 组合、两个互斥输入模式、场景回执隔离、场景/图片哈希、几何与内容诊断、PPTD 解析、项目路径限制、结构诊断、可编辑渲染、场景与 PPTD 源文件发布、完整 Tencent 与模板保真 Skill provider、可选的 18 风格设计系统 provider 与类别校验、四维相似性 review、同轮 Skill 回执、逐页模板语义/代码索引和简化说明、抽取文字配色、主视觉推断、116 个源页参考全部通过精确保真、100 个空 Box 得到 0 个有效语义锚点并被拒绝、有意义的锚点构图被接受、选中模板标志色替换被拒绝、目录和详细页读取、源页映射、主视觉尺寸、工具审批、Text 内富文本、Fragment/map/SVG JSX、可执行 JSX 与错误位置 span 的拒绝、工作区资产约束、项目原子写入、完整可见交付文件夹、同名目录避让、发布失败回滚、WorkBuddy 证据持久化、SlideP 图表规范化打包、演示文稿交付入口相对通用“生成文件”入口的优先级、最终公开文件名、基于最终 PPTX 的浏览器渲染、明确标注的内容结构回退、文件/文件夹打开、下载、原生兼容生成和模板 UI。Host 与 Client TypeScript 项目均单独检查。

运行时验收脚本从现有 WorkBuddy 项目读取 STORY、DESIGN、全部页面和图片，经 OfficePptService、受管 subprocess、逐页 SlideP 校验和 Tencent Docs 引擎生成 PPTX，并核对 OOXML 实际页数：

pnpm --filter dsh-workbuddy-ppt accept:workbuddy-runtime -- \
  --runtime <absolute-runtime-root> \
  --project <absolute-workbuddy-project> \
  --destination <absolute-acceptance-output-root>

运行时命令验证插件服务层和真实本地引擎。新资料经过真实模型完成材料拆解、外部生图工具实际生成图片、打包后 DSH Desktop 安装、Microsoft PowerPoint 打开编辑保存，以及不同平台的原生引擎兼容性属于独立验收层。

源模板验收命令按用户提供 PPTX 的 SHA-256 识别两套目录模板中的对应项，并核对 58 个逐页索引、静态 JSX 门禁和原生兼容输出：

pnpm --filter dsh-workbuddy-ppt accept:curated-template -- \
  <absolute-acceptance-output-root> \
  <absolute-58-page-catalog-pptx>

模型体验

Tencent PPT 项目生成

模型可见内容

模型看到六个演示文稿工具 schema 和两段稳定路由提示。PPT 路由要求声明式场景先检查再生成；Slides 路由携带选中模板，ppt_list_templates 确认服务端权威选择，完整 tencent-pptx Skill 只在当轮调用 skill 后进入上下文。两个生成工具都返回 Deck ID、页数、修订版、可见文件名与工作区目录、SHA-256、工作流、叙事、版式数量、QA 和渲染器。

Token 影响

固定工具 schema 与短路由提示进入可复用前缀。较长的 Tencent Skill、选中的设计风格、所选模板页代码、STORY、DESIGN 和最终 JSX 只在 PPT 生成轮次出现；其余 17 套风格不进入上下文。模板列表、完整逐页目录和生成结果保持精简。

KV Cache 影响

插件版本、工具 schema 和短路由提示不变时，请求前缀稳定。Skill 内容与工具轨迹追加在该前缀之后，生成和修订不会改写更早的提示词 token。

已知限制与暂缓事项

• PPT 模式包含 44 套不重复的 Kimi-compatible 视觉参考包，每套含 6 至 8 页。Slides 包含“数据分析”和“活力蓝色”两套 58 页完整逐页模板；用户上传的自定义模板继续保留在各自会话，同一源文件按 SHA-256 与两套 Slides 源模板去重。索引保留可复用区域结构和组件骨架；任意 PowerPoint Master、动画及复杂绘图的像素级复刻仍需独立能力。原生渲染器适合兼容输出和单页修订；WorkBuddy 渲染器负责 Tencent Skill 的自由页面、图片、图表和内联 SVG。两类渲染器都通过同一份最终 PPTX 提供只读交付预览。
• Host 内容抽取接受 PPTX、DOCX、Markdown 和 UTF-8 文本，一次最多返回配置的页数并报告截断。PDF 抽取、任意 PowerPoint 母版/动画复刻和 WorkBuddy 原生二进制的开源再分发仍属暂缓事项。
• 自研 PPTD 渲染器以文档化 v2 模型和当前真实项目使用到的元素族为目标。自定义 SVG 路径使用明确的矢量回退；任意图标保真、高级图片裁剪、渐变、K 线图、瀑布图、热力图、矩形树图、旭日图、桑基图和 PPTX 无损双向转换仍未进入已验证子集。私有 Kimi 渲染器当前不可用，Kimi 原生一致性继续作为独立对比层。
• 设计系统 Markdown 提供制作规则，不包含字体文件、源图片、图标或源模板页的实测资产。加载风格不代表已经证明视觉相似度、真实模型遵循效果或 PowerPoint/WPS 打开编辑保存；这些属于独立验收层。