ppt-dsl-renderer 1.1.7 → 1.1.8

package/AGENT_PPTX_EXPORT.md

@@ -68,12 +68,18 @@ node /app/node_modules/ppt-dsl-renderer/dist/cli.js \
 
 目录仅读取直接子级 `.html` 文件并自然排序。`--assets-root` 可省略；它只在 HTML 原路径失效时查找本地图片，缺失、同名冲突或图片加载失败时使用透明空白图。可用 `--selector` 指定页面根节点，`--browser-executable` 指定 Chromium。该命令不接受 DSL 的 `--pages`、`--timeout`。成功 JSON 含 `file`、`pages[].sourceFile`、`bytes`、对象统计 `objects` 和缺图清单 `imagePlaceholders`；返回前原子替换输出，其他失败保留已有文件。
 
+### 实时进度（两种导出共用）
+
+`export-pptx` 和 `export-html-pptx` 默认通过 stderr 实时逐行输出进度，无需额外参数，格式为 `{"type":"pptx-export-progress","status":"exporting","completedPages":1,"totalPages":3,"fileName":"editable.pptx","errors":[]}`。状态字段与浏览器端 DSL 导出一致：`exporting` 逐页更新，`writing` 表示打包与文件写入，`generated` 表示最终文件替换和清理完成，失败为 `error` 并在 `errors` 中给出原因。确定页数前总页数为 0；DSL 指定 `--pages` 时按选中页数计数；`fileName` 为 `--out` 的文件名。页数进度不代表耗时百分比。
+
+后端对两种命令使用相同的流式子进程接口，按行解析 stderr 中 `type` 为 `pptx-export-progress` 的 JSON；其他行作为诊断日志。上面的 `subprocess.run` 示例会收集全部输出，无法实时消费进度；Python 可改用 `subprocess.Popen`，通过独立线程消费 stderr，同时主线程读取 stdout，避免管道阻塞；Node 可用 `spawn` 分别消费两个流。stdout 保持最终清单，成功仍以退出码 0 为准。命令参数或输入 JSON 解析失败可能不产生进度事件，失败统一以非零退出码判定。
+
 ### 任务管理
 
 - 限制并发量，导出会启动浏览器；各任务使用独立输出路径。
 - `--timeout` 分别约束浏览器启动和页面生成，不是总时限，也不覆盖最后写文件。后端总时限需留出两个阶段及写入时间。
 - 若外部强制终止 CLI，任务执行器还需回收该任务的子进程，不能依赖 finally 一定执行。
-- CLI 不提供实时进度、HTTP 服务、上传或断点续传。业务方负责任务状态、存储和下载；不要在每个任务中安装包、下载浏览器或执行 build。
+- 两个 PPTX 导出 CLI 共用上述进度协议；CLI 不提供 HTTP 服务、上传或断点续传。业务方负责任务状态、存储和下载；不要在每个任务中安装包、下载浏览器或执行 build。
 
 ## CLI 实现范围
 
@@ -83,6 +89,8 @@ CLI 复用原 `dist/pptx/exporter.js`，没有修改 DSL、Vue/HTML 渲染或 PP
 
 普通 HTML 导出移入独立模块，使用隔离的 `pptxgenjs 4.0.1`；原 DSL 导出继续使用 `pptxgenjs 3.12.0`。它读取浏览器布局并转成可编辑文字/形状，照片、SVG 和复杂 CSS 背景为局部图片；不要求特定 HTML 标签结构，也不保证任意 CSS 与 PowerPoint 逐像素一致。
 
+两种导出的直线统一使用原生线段对象，支持两个端点编辑。DSL 直线保留箭头、虚线、透明度和阴影；HTML 识别出的纯色／渐变细线、伪元素细线和无填充无圆角的单边框分割线使用相同处理。曲线、折线和完整边框保留原有几何。
+
 ## 导出兼容边界
 
 - 结构化资源使用 HTTP(S) URL 或 data URL。空白页面通常使用不透明来源，远程素材仍受 CORS、网络和权限约束；来源不被允许时，可由后端读取素材并明确转成 data URL 后传入 DSL。本包不会自动绕过跨域限制或以占位内容替换读取失败的资源。
@@ -99,7 +107,7 @@ CLI 复用原 `dist/pptx/exporter.js`，没有修改 DSL、Vue/HTML 渲染或 PP
 - 普通文本、标题及 `fixedHeight` 文本均保持 DSL 的位置和宽高，不再额外扩宽或设置 Office 自动改框。字体不一致导致的换行差异应通过字体环境核对，不能靠修改原框掩盖。
 - 普通文本在网页中实际只有一行时关闭 Office 自动换行，避免大号章节数字被重新拆行；网页已折行、显式多行、列表和竖排保留自动换行。测量使用原字号、字体、字距和扣除左右内边距后的宽度，不改变输入 DSL 或导出文本框尺寸。
 - 文字颜色保留 RGBA 的 alpha，包括默认颜色和富文本继承；显式子颜色使用自身的 alpha，并与元素 `opacity` 相乘。底图上的形状蒙层继续按原图层顺序和填充透明度导出。
-- 普通文本无显式换行、列表或段距，且行高等于扣除上下内边距后的框高时，按 HTML 的单行居中用法导出为原生垂直居中，不再保留整框高度的段落行距。多行、竖排及未撑满框高的正文保留原来的行距和对齐。
+- 普通文本无显式换行、列表或段距，且行高等于扣除上下内边距后的框高时，按 HTML 的单行居中用法导出为原生垂直居中，不再保留整框高度的段落行距。显式设置 `vAlign: "middle"` 且浏览器实际为单行时，也使用 Office 原生行距，避免固定行距导致字形偏上。多行、竖排、有段距及未设置垂直居中的普通正文保留原来的行距和对齐。
 - 选页导出的元素页内链接按输出页序重新定位；目标页不在范围时不生成该链接。导出支持 DSL 的主要几何、颜色和文字样式，不承诺与浏览器逐像素一致，也不保留浏览器的所有图片滤镜。
 - 字体依赖浏览器和打开 PPTX 的系统，不自动嵌入字体；生成成功不能代替 Office/WPS 中的实际视觉和媒体播放验收。
 

package/AGENT_USAGE.md

@@ -102,9 +102,21 @@ HTML 中相对图片路径先按 HTML 文件位置解析。只有显式传入 `-
 
 CSS 首选字体不存在且字体栈明确包含 `serif` 时，导出器按字符使用后续可用字体：数字和英文使用 Georgia 等西文衬线字体，中文使用当前系统的中文衬线字体，避免 Office 将浏览器中的字体回退统一替换；其他字体栈不受影响。
 
-带文字的行内单边框按边框线导出；只有没有文字内容的零尺寸单边框元素才按 CSS 三角形处理。
+HTML 识别出的纯色／渐变细线、伪元素细线和无填充无圆角的单边框分割线统一导出为原生线段，支持两个端点编辑，保留颜色、渐变透明度、线宽和虚线样式。只有没有文字内容的零尺寸单边框元素才按 CSS 三角形处理。
 
-CLI 只返回最终清单，不提供结构化实时进度。生成成功不等于已通过 Office/WPS 视觉验收。
+### PPTX 导出进度（两种命令共用）
+
+`export-pptx` 和 `export-html-pptx` 默认在 stderr 中逐行输出进度 JSON，无需额外参数。字段与浏览器端 DSL 导出一致，并以 `type: "pptx-export-progress"` 区分普通诊断日志：
+
+```json
+{"type":"pptx-export-progress","status":"exporting","completedPages":1,"totalPages":3,"fileName":"editable.pptx","errors":[]}
+```
+
+`status` 按 `exporting` → `writing` → `generated` 更新，失败为 `error`，原因在 `errors` 中。确定页数前 `totalPages` 为 0，之后每完成一页更新 `completedPages`；DSL 指定 `--pages` 时按选中页数计数。`fileName` 为 `--out` 的文件名。`writing` 覆盖打包与文件写入，`generated` 在最终文件替换和清理完成后发出。进度按页统计，不表示耗时百分比；单页转换和打包期间没有更细进度。
+
+Agent 对两种命令使用同一套处理方式：实时按行读取 stderr，将 `type` 为 `pptx-export-progress` 的 JSON 作为进度，其他行作为诊断日志；等待退出码 0 后解析 stdout 中的最终清单。使用一次性收集输出的子进程 API 时，仍会在结束后才拿到进度。命令参数或输入 JSON 解析失败可能发生在导出开始前，不保证产生进度事件，失败统一以非零退出码判定。
+
+生成成功不等于已通过 Office/WPS 视觉验收。
 
 ## 失败处理