pptx-windows-render

Windows 环境下用 tencent-pptx 技能做 PPT 时的两个硬补丁 + 一条风格复刻路径。
tencent-pptx 是内置技能（不可修改），本技能作为其 Windows 侧的补充说明。

补丁 1：把 .pptx 渲染成图片做视觉校验（三条路，按顺序试）

tencent-pptx/scripts/pptx2image.py 依赖 LibreOffice 的 soffice。Windows 机器通常只装了 Office，直接运行会报：

ERROR: LibreOffice soffice executable not found.

不要去找 LibreOffice，也不要因此放弃视觉校验。按下面顺序找可用的渲染路径（2026-09 实测：本机路径 1 报错、路径 2 报错、路径 3 成功）：

路径 1（最快）：slidep screenshot —— 自带渲染，不需要 Office

slidep screenshot "<deck>.pptx" --page-index 0 --out "shots/slide01.png"
slidep screenshot "<deck>.pptx" --page-index 1 --out "shots/slide02.png"

--page-index 是 0-based。它依赖本机 editor_sdk 服务（默认 http://localhost:39099，可用 --base-url 指定）。
已知失败：可能报 render failed: The argument 'filename' must be a file URL object ... Received 'file:///workspace/node_modules/...'（SDK 内部模块路径解析问题，与你的文件无关）。遇到就走路径 2。

路径 2：PowerShell + PowerPoint COM

$ErrorActionPreference='Stop'
$src="D:\path\to\deck.pptx"
$out="D:\path\to\render_out"
if(!(Test-Path $out)){New-Item -ItemType Directory -Path $out | Out-Null}
$ppt=New-Object -ComObject PowerPoint.Application
$pres=$ppt.Presentations.Open($src,$true,$false,$false)   # ReadOnly, Untitled=False, WithWindow=False
$pres.Export($out,"PNG",1280,720)                          # 与 1280×720 画布 1:1
$pres.Close()
$ppt.Quit()
[System.Runtime.InteropServices.Marshal]::ReleaseComObject($ppt) | Out-Null
Get-ChildItem $out | Select-Object -ExpandProperty Name

已知失败（2026-09-16 复测：已可用，不要再默认跳过）：曾报 TYPE_E_CANTLOADLIBRARY——

设置"Visible"时发生异常:"无法将类型为"Microsoft.Office.Interop.PowerPoint.ApplicationClass"的
COM 对象强制转换为接口类型"Microsoft.Office.Interop.PowerPoint._Application"…… 加载类型库/DLL 时出错。

即 PowerShell 绑定到了 PowerPoint 的 interop 程序集，而该类型库在本机注册损坏。此时 Presentations.Open 会静默返回 Null。别去跑 POWERPNT.EXE /regserver 修注册表（侵入性大），直接走路径 3。

2026-09-16 复测该路径正常（说明当年的类型库问题已不复现），且只要单页时它最省事：

$ppt=New-Object -ComObject PowerPoint.Application
$ppt.Visible=[Microsoft.Office.Core.MsoTriState]::msoTrue    # 用枚举赋值，别写 $true
$pres=$ppt.Presentations.Open($src,$true,$false,$false)
$pres.Slides.Item(50).Export($out,"PNG",1280,720)            # 单页导出，比整包 Export 快几十倍
$pres.Close(); $ppt.Quit()

注意：PowerShell 工具在命令行式的会话里不回显 stdout，把进度 Add-Content 写进日志文件再读。

路径 3（实测可用）：Python + pywin32 晚绑定

pywin32 走纯 IDispatch 晚绑定，绕开损坏的 interop 类型库，是这台机器上唯一成功的路径。

# 1) 准备隔离 venv 并装 pywin32（只装一次）
$py="C:\Users\<你>\.workbuddy\binaries\python\versions\<ver>\python.exe"
$venv="C:\Users\<你>\.workbuddy\binaries\python\envs\default"
if(!(Test-Path $venv)){ & $py -m venv $venv }
& "$venv\Scripts\python.exe" -m pip install --quiet pywin32

# 2) render.py —— win32com.client.Dispatch 即晚绑定
import os, pythoncom, win32com.client
base = r"D:\ascii_only\tmp"                 # 见下方「路径必须纯 ASCII」
src  = os.path.join(base, "deck.pptx")
out  = os.path.join(base, "out")
os.makedirs(out, exist_ok=True)
pythoncom.CoInitialize()
app = win32com.client.Dispatch("PowerPoint.Application")
try:
    app.Visible = True
except Exception as e:
    print("visible warn:", e)               # 部分版本该属性会抛错，忽略即可
pres = app.Presentations.Open(src, True, False, True)   # 第 4 个参数 WithWindow=True 更稳
print("slides =", pres.Slides.Count)
pres.Export(out, "PNG", 1280, 720)
pres.Close()
app.Quit()
pythoncom.CoUninitialize()
print(sorted(os.listdir(out)))

• 路径必须纯 ASCII：把 pptx 先 Copy-Item 到一个纯英文临时目录（如 D:\ProgramData\workbuddylog\<日期>\_render_tmp\）再渲染，避免中文目录名带来的编码问题。
• 导出文件名是 幻灯片1.PNG、幻灯片2.PNG…（与页序一一对应）；用 Glob 定位、Read 看图。
• 被安全策略挡住的路径（不要浪费轮次去试）：cscript / wscript 报 Known LOLBin executable；New-Object -ComObject KWPP.Application（WPS）报 COM object instantiation can run arbitrary code。

通用收尾

• 逐张用 Read 看图做视觉自检（文字溢出 / 折行断字 / 元素堆叠 / 留白失衡 / 配色跑偏）。

• 自检目录（check_render/、_render_tmp/）属临时产物，复核完必须删除，不要留在交付目录里。

• 导出文件名是 幻灯片1.PNG、幻灯片2.PNG…（与页序一一对应）。

• 导完用 Read 工具逐张看图，做逐页视觉自检（文字溢出 / 元素堆叠 / 留白失衡 / 配色跑偏）。
• 自检目录（如 check_render/）属临时产物，复核完即可删除，不要留在交付目录里。

补丁 2：slidep 的调用姿势（PATH / 子命令名 / 相对路径）

① 先确认 slidep 在不在 PATH 里。 本机 Git Bash 的默认 PATH 常常是坏的（连 ls/dirname 都找不到），slidep: command not found 不代表没装。单次调用前显式导出：

export PATH="/c/Users/<你>/.workbuddy/binaries/node/versions/22.22.2-3:/c/Users/<你>/.workbuddy/binaries/PortableGit/versions/1.2.0/usr/bin:/c/Windows/System32:/c/Windows:$PATH"

（slidep 就在托管 node 版本目录下；同一目录还有 slidep.cmd / slidep.ps1。）

② 没有 slidep-validate 这个独立可执行文件。 早期文档写的 slidep-validate 在 slidep 6.x 上不存在，正确写法是子命令 slidep validate：

slidep validate "<deck>.pptx" --dsl-file "slides/01.slide"     # 结构校验
slidep lint     "<deck>.pptx" --dsl-file "slides/01.slide"     # 布局/溢出校验（必须 ok:true）
slidep create   "<deck>.pptx"
slidep upsert-dsl "<deck>.pptx" --dsl-file "slides/01.slide"                     # 追加
slidep upsert-dsl "<deck>.pptx" --dsl-file "slides/01.slide" --page-index 0       # 替换第 1 页（0-based）

--dsl-file 用相对路径即可（在项目目录里 cd 后调用），不受 /d/... 被误解析成 D:\d\... 的影响——那个坑只出现在把 $(pwd) 传给 --project 的时候，而 6.x 的子命令已经不吃 --project 了。upsert-dsl 不会递增页码，改已有页务必带 --page-index，否则会追加出重复页。

标准单页循环（tencent-pptx 要求）：

slidep lint     "<file>.pptx" --dsl-file "slides/{NN}.slide"   # 必须 ok:true，否则按 error 修
slidep upsert-dsl "<file>.pptx" --dsl-file "slides/{NN}.slide"            # 追加
slidep upsert-dsl "<file>.pptx" --dsl-file "slides/{NN}.slide" --page-index <0-based>  # 改已有页

> 注意：upsert-dsl 不会递增页码，新增页仍是追加；改页务必带 --page-index，否则会生成重复页。

风格复刻：怎么最快最准

用户说「参考这个 PPT 的风格 / 样式」时：

1. 先找参考项目的 DESIGN.md —— 同系列 PPT 项目目录里通常已有 DESIGN.md（画布、母版分区 px、色板 hex、字号层级表、页面映射表）。直接读它，比从图片反推精确得多。
2. 也读参考项目的 STORY.md 了解叙事节奏，但不要读参考项目的 slides/*.slide 源码 —— 技能明确禁止跨项目"借鉴"页面写法，新页的写法依据必须来自本项目的 DESIGN.md + 组件规范。
3. 渲染图片核对 —— 用补丁 1 导出参考 PPT 的 PNG，看封面版式、卡片样式、深色块用法、页脚条，确认 DESIGN.md 描述与实际渲染一致。⚠️ 参考 DESIGN.md 常常是过期的：2026-09 实测某个「单页」参考项目的 pptx 里其实有 8 页，且页脚、页码、时间轴等元素 DESIGN.md 完全没写。所以逐页看图这步不能省，它才是真正的风格来源；DESIGN.md 只当起点。
4. 在新项目里复制一份 DESIGN.md 并声明「视觉基线继承自 XXX」，再按新内容改写页面映射表。

逐页高度预算（1280×720 画布，最常溢出）

母版三区固定：A 标题块 100 + B 内容区 540 + C 页脚 40 = 680 = 720 − 上下 padding 40。

所以每页只有 540px 放内容，动笔前必须算：
上padding + 标题区 + 内容区 + 各 gap + 下padding ≤ 720

⚠️ 最关键的一条：Text 的实测高度 ≈ fontSize × 1.27～1.5，lineHeight 基本不生效

lint 的 child-containment 是按实际渲染高度判超限的，而这个高度不是你在 style 里写的 fontSize × lineHeight。2026-09 实测标定：写 fontSize: 29, lineHeight: 1.2，lint 仍按 ≈43.5px（=29×1.5）算，导致「明明算得下」的容器报 bottom+8px。

两次独立标定（2026-09-15 复核）：
- 单行文本：fontSize: 56, lineHeight: 1.05 放进 height: 64 的容器 → 报 top+7px，即实际 71px → 系数 ≈ 1.27
- 同容器内堆叠两行文本时，会出现额外的行间距（近似 1em），叠加后更接近 ×1.5

实用结论：按 ×1.3 预算 + 每页留 ≥ 8px 总余量 布局，然后交给 lint 收敛。不要一律按 ×1.5 排 —— 540px 的 B 区按 ×1.5 排会严重装不下内容，逼你把本该有的信息砍掉。只有"容器里堆叠多行文本"的场景才按 ×1.5 保守估。

动笔前先把这一页所有 Text 按 fontSize × 1.5 累加作为上界，不要按 1.2/1.4 算：

配套习惯：
- 给容器留 ≥ 8px 总余量，别把 上padding + 各块高度 + 各 spacer 卡到 0。
- Text 上写了 height 也不能阻止它把父容器撑破 —— 要控制高度就控制外层容器，别指望 height 截断文字流。
- 一段中文小字如果换行成 3 行而不是 2 行，是右栏卡片超限的头号原因：按「可用宽度 ÷ fontSize」估字数，超了就删字，不要赌它只排 2 行。
- 修溢出时不要在已通过校验的容器里加高度 —— 改高度会挤动整页，要同时从别处减掉等量高度，保持总高不变。

常见溢出原因（都是实测踩过的）：
- 卡片内 padding 12/16 与文字行高按 16px×1.5=24 累加后超盒 —— 引用块里文字换行成 2 行是最常见的超限来源，宁可压缩文案也别指望它只有一行。
- 标题区 34px×1.3=44.2 + 8 + 16×1.4=22.4 ≈ 75，加 20 上边距 = 95，剩余 25px 才是间隙，不要在这里再塞元素。
- 一页内多卡片平均分高度时，先算 (总高 − 卡片数总和 gap) / 卡片数，再核对每卡内部实际内容高。
- 分栏里的长文本（尤其「中文＋英文/数字」混排）不会可靠换行，会直接压到相邻列上。宽度固定列里的文案要按宽度先估算，超了就改短 —— 渲染图里表现为两列文字粘在一起。
- 同行「左文本 + 右徽章」的溢出定式（2026-09-15 实测）：徽章（chip）用 padding + 内文 自然撑宽，实际渲染宽度常比手算宽 10–20%；左文本若写 flex: 1，它不会自动收缩，结果整行被顶出卡片边界。正确做法：给左文本写死 width（按 行宽 − 徽章上界 − 各 gap − padding 反推），不要用 flex: 1。本例 560px 行 → 左文本 width: 296，徽章上界 186px，一次通过。
- 徽章内文含产品名（Remotion / HyperFrames / Flova.ai）时，宽度按 ≈0.55em/字符 估，别按中文字宽估；两个英文词之间加 或 / · 很容易超。

风格复刻补充：迁到浅色商务风（白底）时的 5 条（2026-09-15 实测）

参考样本：资料库对比-v2.pptx —— 白底 + 橙色竖条标题 + 深蓝实色重点块 + 浅灰/浅蓝圆角卡，无渐变、无投影、无玻璃、无光晕。

1. 参考项目的 DESIGN.md 会过期，逐页渲染图才是风格真相：该 DESIGN.md 自称「单页」，实际 pptx 有 8 页，且页脚、页码等元素 DESIGN.md 完全没写。做法：先读 DESIGN.md 当起点 → 渲染全部页 → 拼联络图总览 + 挑 1–2 页看原图细节 → 抽取色板与版式写进新 DESIGN.md（注明「视觉基线继承自 XXX」）。
2. 迁移只换视觉层，不动高度账：把 v1 的 B 区切分（38/10/411/10/71 等）原样保留，只改颜色/圆角/边框/底色 → lint 一次全过。改版式与改风格同时做，等于把两个变量混在一起调。
3. 浅灰底 chip 必须配描边：#F3F4F6 底 + 深灰字放在 #F7F8FA 行底上轮廓完全消失（渲染图上像个空占位）。需补 1px solid #D1D5DB。
4. 12px 符号别用主色深蓝：★☆☆☆☆ 用 #1E3A5F 在白底上看起来像一串黑色实心块，会被误读成乱码；改中性灰 #6B7280 才柔和。
5. 要求兄弟卡内部段落 y 轴对齐时，必须手动断行：靠自动换行会产出「…叠加字 / 幕」这种孤字行，把分隔线挤错位。改成一行一个 Text（各写半句）最稳，行距也完全可控。

补充通用一条：把 flex: 1 文本改成写死 width 时，必须重算整行横向账 ——
paddingLeft + 徽章宽 + gap×n + 文本宽 + 星级宽 + chip 宽 + paddingRight ≤ 容器宽。
本例算出 786 > 784（超 2px），在渲染图上只表现为右端文字贴边，极易漏检。

补丁 3：本机文件删除与环境怪癖（2026-09-15 实测）

Remove-Item 报错但实际已删除：本机 Remove-Item 被安全策略接管，会返回

[safe-delete][SAFE_DELETE_FAIL_CLOSED] {"reason":"trash-failed", ... "Some operations were aborted"}

但文件确实已被删掉。不要据此重试、也不要以为清理失败 —— 用 Glob 复核目录内容即可确认。误判会导致把 -ErrorAction 调来调去浪费轮次。

slidep screenshot 在本机持续失败（文件/路径/环境 无关）：报

render failed: The argument 'filename' must be a file URL object, file URL string, or absolute path string.
Received 'file:///workspace/node_modules/.pnpm/@tencent+docs-slide-view-sdk-node@...'

这是 SDK 内部模块路径解析问题，与你的 pptx 无关，重试无用，直接走补丁 1 路径 3。

PowerShell 工具 stdout 可能不回显：命令结果用 Out-File / Set-Content 落盘，再用 Read 读文件确认，不要靠回显判断成败。

Bash 工具在本机基本不可用：shim 报 dirname: command not found，ls / mkdir / head / which 全部缺失。所有 shell 操作走 PowerShell；查文件用 Glob。

不要做的事

• 不要为了出图去安装 LibreOffice（PowerPoint COM 已经够用）。
• 不要用 read_image 之外的方式"凭感觉"校验 —— 每页都要真的看图。
• 不要在交付目录里留 style_preview/ check_render/ 等临时图片目录。