@deepseek-ai/libreoffice-kit

English | 中文

使用预编译 LibreOffice 引擎，在 Node.js 中转换、重算并直接渲染本地 Office 文档。通过同一套 API，为服务端、桌面应用和文档处理任务提供可配置字体、取消和资源限制。

转换与原生预览入口可在同一进程中同时使用，不受初始化顺序影响。

二进制 .doc、.xls、.ppt 输入必须是 OLE 复合文档，例如 Office 97–2003 文件。不支持改后缀的 RTF/HTML 和 .wps。二进制输入的 missingFonts 为空，因为其字体表由 LibreOffice 读取，而不是由 OOXML 检查器读取。

Node API 与各平台引擎独立指定版本。0.2.3 candidate 指定 0.2.3 的 macOS 与 Windows ARM64/x64 引擎，并使用重新编译的通用 0.2.3 WASM 引擎。ENGINE_VERSION 和 discoverRuntime().version 表示 Node API 版本；ENGINE_VERSIONS 列出各平台兼容的精确引擎版本。discoverRuntime().nativePreview 区分原生预览与 PDF 转换能力。缺少原生包时选择 WASM；已安装的包损坏时拒绝。

安装与使用

使用 Node.js 22.19.0 或更新版本。0.2.3 发布后可使用以下命令安装；未发布的候选包需先从源码构建并验证：

npm install @deepseek-ai/[email protected]

npm 安装共享 WASM 引擎和匹配平台的原生引擎。转换器优先使用已安装且兼容的原生引擎；平台没有原生包或可选原生包未安装时选择 WASM。已安装的包损坏时以 unavailable 拒绝。转换失败不会切换引擎。

import { createConverter } from '@deepseek-ai/libreoffice-kit';

const converter = await createConverter({ timeoutMs: 120_000 });
try {
  const result = await converter.render({
    inputPath: '/private/work/document.docx',
    outputPath: '/private/work/document.pdf',
  });
  console.log(result.backend, result.missingFonts, result.pageCount);
} finally {
  await converter.dispose();
}

原生与 WASM 引擎是按平台筛选的可选依赖。应用构建方必须验证所需引擎已安装：macOS/Windows 使用原生引擎，Linux 使用 WASM。必需引擎缺失时，createConverter() 以 unavailable 拒绝。

每个转换器串行执行渲染。一次渲染会创建独立的原生进程或 Node worker 以及私有配置目录，因此字体、文档状态和失败不会泄漏到后续渲染。截止时间在获得转换槽位之后开始计算。AbortSignal 可以取消排队中或进行中的工作；取消和 dispose() 都会等待进程或 worker 退出并完成临时文件清理。已释放的转换器会拒绝后续工作。

通过兼容 API createConverter(options) 创建的转换器，会自动与进程内使用相同引擎及字体配置的其他转换器共享有界字体元数据和匹配结果。释放 converter 仍只等待它自己的工作；元数据会留给后续兼容 converter，最多保留 16 种配置。maxFontMetadataCacheBytes 限制保留的逐文件元数据，maxFontResolutionEntries 限制匹配条目，默认值为 4096。

长驻服务如果需要为多个并发转换槽提供一个显式生命周期所有者，可创建 createConverterFactory(options)，再通过 factory.create() 建立转换器。这些转换器使用 factory 私有缓存，同时仍分别拥有 Worker、原生 helper、配置目录和输出。释放 factory 会停止并等待它创建的全部转换器。

convert() 按输出后缀导出格式。render() 和 convert() 的 PDF 结果包含从输出 PDF 页面树读取的 pageCount；尾部、目录或页面树无法读取的输出返回 invalid-output 并被删除。recalculate() 在保存前刷新电子表格公式结果，renderImages() 在全新目录中写入 PNG tile 和 manifest.json。Office 图像直接从一次加载的模型绘制，PDF 使用 PDFium。CLI 通过 dsoffice capabilities|convert|recalculate|render 提供相同行为。工作表名称按精确名称匹配：图像渲染指定不存在的工作表时返回 invalid-document，CSV 导出返回 failed，两者均不保留输出。重算作用于整个工作簿并拒绝 --sheet。选择失败后仍可复用转换器。

npm exec -- dsoffice render --input report.docx --output-dir report-pages --pages 1
npm exec -- dsoffice render --input budget.xlsx --output-dir budget-preview --sheet Summary --range A1:D20
npm exec -- dsoffice convert --input report.docx --output report.pdf
npm exec -- dsoffice recalculate --input budget.xlsx --output recalculated.xlsx

从右向左排列的工作表会生成文字可正常阅读、A 列位于右侧的 PNG。A1 范围和 manifest 中的矩形仍使用逻辑列坐标；拆分后的每张 tile 均独立调整像素方向。

转换 worker 以空的 execArgv 运行包内发布的 JavaScript；--input-type=module 之类的调用方启动参数不会被继承。

Windows 的转换、图像渲染和持久编辑 helper 使用匿名标准输入输出管道，继承调用方的令牌和 Job 限制。管道保持二进制像素帧完整，helper 等待命令时的管道轮询不会占用 libuv 工作线程。取消及工作表选择失败后，关闭会等待进程退出并读完输出，包括协议读取器已暂停 stdout 的情况；此传输方式不授予额外的文件系统或网络权限。

原生转换和图片渲染 helper 设置 SAL_DISABLE_PRINTERLIST=1 与 SAL_DISABLE_DEFAULTPRINTER=1，禁用打印机枚举和默认打印机查询。文档预览和导出不需要实体打印机；这些子进程设置可避免打印机驱动弹窗及网络打印机连接等待，不会修改系统打印机设置。

Windows 上，引擎可执行文件或程序目录路径达到 260 个字符时，在私有操作目录中使用 helper 临时副本和指向已安装资源的 junction。转换、图像渲染和编辑均保留这些路径直到子进程退出，包括启动失败时；随后清理 junction。渲染器若在返回协议响应前退出，会携带退出状态和捕获的诊断信息拒绝操作。

在 Linux 上，原生子进程会先在所选引擎的 program 目录中查找共享库，然后才查找系统路径。调用方提供的 LD_LIBRARY_PATH 和 LD_PRELOAD 不会被继承。

调用方负责授权输入访问并拥有私有输入/输出目录；路径必须是绝对路径，并在转换期间保持不变。输入文件必须是常规 Office 文件，且在配置的字节限制之内。ZIP 条目数和解压大小限制适用于 OOXML；二进制 DOC/XLS/PPT 使用 OLE 复合容器，内部结构由 LibreOffice 导入器验证。二进制格式仍遵守相同的转换超时和输入/输出限制。输出创建使用独占模式和 0600 权限；已存在的输出绝不会被覆盖。失败或取消的渲染会删除新建的输出。maxOutputBytes 限制返回的 PDF 及其读取缓冲区；原生临时磁盘文件在导出完成前可能继续增长，随后过大的 PDF 会在 Node 读取之前被拒绝并删除。成功的 PDF 归调用方所有，调用方可以将其字节发送给浏览器 PDF 阅读器。

ConversionError.code 区分 invalid-document、unsupported-format、input-too-large、output-too-large、invalid-output、timeout、unavailable 和 failed。这些 code 会原样穿过 worker 和原生传输层。无效的安装资源会让创建以 unavailable 拒绝；它们绝不会启用回退。EEXIST 等文件系统错误、无效配置错误和调用方取消原因保持原样。

原生编辑器

原生视图隐藏所有批注及其交互区域。导出原格式快照会保留批注正文、作者和回复关系；进入编辑模式也不会启用批注查看。

@deepseek-ai/libreoffice-kit/editor 通过 openDocument() 打开常驻的 DOCX、XLSX 或 PPTX 文档。调用方负责访问授权、输入字节、绘制和保存快照；close() 会等待原生进程退出。编辑需要设置 writable: true。编辑器不提供浏览器文档模型或 LibreOffice 桌面窗口。

openDocument({ onProgress }) 在各加载阶段开始时报告 fonts、engine 和 document。观察函数抛错会转为警告。只有返回的 Promise 完成后才能开始绘制；该回调不会让 LibreOffice 导入变为渐进式。

原生文档加载将自有 bytes 通过 helper 的 stdin 传入可寻址的 UNO InputStream，以 private:stream 打开，不创建输入文档文件。转换和图像渲染读取一次调用方输入路径，将 bytes 传给检查 worker 和原生加载器。标准 LibreOfficeKit 加载接口只接受 URL，无法传入流；内置 Core 增加私有内存加载入口，缺少该入口会明确失败，不回退到写文件。配置与字体文件、保存与导出输出，以及 LibreOffice 内部修复或存储临时文件另行管理；这不代表完全没有文件系统活动。WASM 使用内存文件系统。

renderBackend 选择原生绘制后端。默认 "auto" 启用 LibreOffice 的 Skia Ganesh GPU 路径（Windows 用 Vulkan，macOS 用 Metal）；当驱动进入黑名单或 GPU 上下文无法启动时保持 CPU 绘制，getInfo().renderBackend 返回实际使用的后端，便于调用方显式告警。"ganesh" 强制要求 GPU 后端，不可用时直接拒绝打开；"graphite" 在加载文档前初始化原生 Dawn device，并把最终输出设备直接绑定到 SDK 借用的纹理；"raster" 强制 CPU 绘制。graphiteCacheBytes 默认 128 MiB，分别分配给 Graphite context 和 recorder 缓存；正在使用或执行中的 GPU 分配以及 SDK 显示纹理不计入该缓存预算。强制指定的后端创建失败会拒绝打开文档；共享绘制失败不会切换后端或关闭文档。调用方可以导出当前内存文档，再显式打开 raster 替代进程。

从 0.1.3 迁移到 0.2.0 预览版时，需要同时更新 Node adapter 和其精确匹配的平台引擎；0.1.3 引擎不能处理新增的编辑器启动选项。现有转换调用保持原有行为；需要此前 CPU 路径的编辑器调用必须设置 renderBackend: "raster"，因为省略它现在会选择 "auto"。打开桌面文档时可显式选择 graphite，共享 receiver 连接、输入顺序和释放责任保持一致。切换后端需要新进程：先导出当前内存快照，在旧编辑器关闭前用 renderBackend: "raster" 打开替代进程，并由调用方恢复视图。快照保留文档内容，但不保留旧的撤销/重做历史或正在运行的放映。导出或替代进程初始化失败时，应保留旧编辑器及其未保存文档。

Graphite 后端不可用的设备会拒绝初始化；Linux 原生开发引擎仅支持 raster。共享绘制借用的 WebGPU 对象留在原生文档进程内，不通过 Node 或浏览器传递 device。GPU 提交和完成由 Dawn 管理，跨进程共享访问、帧配额和消费者释放仍由原生 SDK 管理。单独提交 WebGPU queue 不表示显示消费者已使用完该图像。

打开文档要求已安装的引擎提供编辑器协议 4 和 frame-forwarding 协议 1。缺失或不兼容的协议会使初始化失败，不会选择其他引擎。

getSelection() 返回当前选区的纯文本或 HTML。原生 JSON 回复以 maxOutputBytes 为预算，最低为 1 MiB；超出预算时只拒绝当前操作，文档保持打开。Escape 即使带有修饰键也只取消选择，不打开原生命令弹窗。

setViewport() 接收以 twip 为单位的实际可见区域和客户端像素／twip 比例。Writer 以打印布局打开；缩放和调整视口大小会保持纸张尺寸与换行。Impress 在文字选择的绘制和点击命中计算中使用当前单元格的行高设置，支持合并单元格与垂直对齐。

render() 和 renderSurface() 的绘制矩形可携带从零开始的 part，用于后台渲染幻灯片。此请求按需创建同一文档的只读视图，保留活动页和选区，并在接收后续输入前恢复活动视图。Word 页面使用其文档矩形坐标。两种绘制都要求先停止演示播放；打开文档仍需完成原生导入和分页后才能开始渲染。

render() 和 presentationFrame() 返回紧密排列、非预乘的 RGBA，使用后续渲染不会复用的独立缓冲区。原生 worker 原地转换文档图块；不透明的幻灯片播放帧本身已使用此格式。适配器校验尺寸和显式像素格式，不复制或转换返回的像素。

input() 和 dispatch() 按顺序提交输入与允许的编辑命令；exportSnapshot() 返回包含格式和修订号的原格式字节，调用方负责保存。打开时会复制输入字节，编辑和导出不会覆盖调用方源文件。只读文档拒绝修改和快照导出。取消信号结束文档生命周期；即使操作失败，也应调用 close() 等待清理。

需要共享图像的桌面应用将帧转发通道的 TX 凭据传给 attachSurfaceTransport(tx, { timeoutMs })，再调用 renderSurface() 或 presentationSurface()。timeoutMs 限制连接时长（包括等待该通道前一个生产者排空），且必须短于文档操作超时；通道忙时以 channel-busy 开头的消息拒绝。detachSurfaceTransport() 或进程退出后，另一个文档进程可使用同一凭据连接同一通道。回复只包含关联信息，图像由独立 SDK 传输；接收端在显示消费者完成使用后释放帧。waitForInput() 可让命令或导出等待对应输入序号；detachSurfaceTransport() 保留文档；设备健康时可继续请求 RGBA 输出，但它不会更换后端，Graphite 的像素请求仍需要回读。Raster 将 tile 回读到 CPU 缓冲区，再上传到 SDK 纹理。Ganesh 复用 LibreOffice 的 GPU 上下文，通过 Metal blit 或 Vulkan 外部内存复制将最终图像送入 SDK 纹理；Windows 在与 Vulkan 设备匹配的 D3D11 适配器上分配纹理。Ganesh 和 Graphite 的共享输出均跳过最终目标的 CPU 回读。文档功能仍可能要求内部位图回读或素材上传。

连续放映流仅在幻灯片请求 canvas 更新时申请并提交帧。静止或暂停时保留最后一张图像，不消耗额外帧额度。等待可用额度期间会保留变化，下一次成功提交包含最新状态及动画末帧。启动流或更改视口会强制输出一帧。显式调用 presentationFrame() 和 presentationSurface() 仍每次返回一帧；文档视图仅在显式请求时绘制。

引擎、字体与运行行为

Node API 通过 ENGINE_VERSION 报告其发布版本；ENGINE_VERSIONS 独立固定各平台的引擎版本。npm 安装预编译引擎；安装和转换阶段均不会编译 LibreOffice 或额外下载引擎资源。每个引擎包的 sources/ 和 licenses/ 保留匹配的源码配方、补丁、构建信息和第三方许可声明。

默认值和所有选项记录在随包发布的 lib/types/index.d.ts 类型声明中。字体目录使用所选操作系统的常规系统/用户路径。索引会跳过缺失或受保护的来源，并传播其他文件系统错误。fontkit 索引原始字体文件并选择已安装的字面和字形覆盖；它不重写字体。每次操作都会重新发现字体候选并验证缓存中的文件身份。一次操作使用一份有序元数据快照；快照变化后字体匹配条目失效。检测到转换期间字体变化时，操作会失败并删除其输出。字形匹配仅查询请求中的 Unicode 码点，同一物理字体集合中的各字面共享一次解码。码点查询结果只在本次操作内保留，开始检查下一文件前释放当前解析对象；不会遍历所有字形，也不会跨文档缓存字体字节。精确的 family 匹配优先于 fontFallbacks。missingFonts 包含可读文档 XML 中声明但缺失的 family，不包含无关的引擎默认值。未命名缺失 family 的缺字并不构成完整的文档可访问性报告。

引擎包解析器

默认情况下，适配器从自身安装位置按 Node 模块解析查找引擎包。引擎文件位于其他磁盘位置的应用，可在 createConverter()、createConverterFactory()、openDocument({ options }) 和 discoverRuntime() 的选项中传入 resolveEnginePackage。discoverRuntime() 接受并按相同规则校验与 createConverter() 相同的选项对象，因此各入口可共用同一个对象并选择同一引擎。选项类型为 EnginePackageResolver = (name: string) => string：

• 宿主有原生目标时，name 先是平台包（@deepseek-ai/libreoffice-kit-<target>）；选择 WASM 时为 @deepseek-ai/libreoffice-kit-wasm。
• 同步返回该包 package.json 的绝对路径。返回相对路径、不存在的路径、非文件路径或非字符串结果均视为错误，不会回退到 WASM。
• 要表示原生包不存在，抛出 code 为 MODULE_NOT_FOUND 的错误（与 require.resolve 一致）；随后通过同一解析器选择 WASM。抛出其他值均视为错误。
• 包是否存在只由解析器决定：解析器报告缺失的包，适配器不会再检查自身安装位置。要报告包存在但不完整，请抛出其他错误。
• 转换器、factory 和 discoverRuntime() 以 code 为 unavailable 的 ConversionError 拒绝上述错误，原始错误保留在 cause 中。openDocument() 与其处理其他引擎错误的方式一致，直接以原始错误拒绝。

适配器仍负责选择平台目标、应用 glibc 下限，并校验所解析包的版本固定与引擎资源。解析器在调用方线程运行，不会传入转换 Worker。Electron 示例见打包指南。

字体元数据缓存

createConverter() 和 createConverterFactory() 均接受：

macOS 默认使用 ~/Library/Caches/libreoffice-kit，Windows 使用 %LOCALAPPDATA%/libreoffice-kit/Cache（缺省时回退到用户的 AppData/Local），Linux 使用 $XDG_CACHE_HOME/libreoffice-kit（缺省时回退到 ~/.cache）。单个 font-metadata.json 文件保存规范文件路径、以十进制字符串精确保留的设备/inode 标识、大小、修改/变更时间及全部 face 元数据，包括解析结果为空的记录。它不保存字体字节、字形覆盖、解析对象、文档文本或文档匹配条目。请将此用户级文件保持私有。

没有可复用元数据的首次运行仍执行原来的完整字体 inspect。后续进程只跳过已发现且文件身份完全匹配的字体。每次操作重新枚举来源，包括 Office 补充字体，因此新增、删除、替换和目录变化无需重启。候选顺序、文件预算、Office 过滤、fallback 匹配、字形查询和原字体导入保持原有行为。缓存损坏、版本不兼容、超限或不可访问时回退到字体源计算；不可读的源字体不会复用旧记录。缓存格式、提取逻辑和固定的 fontkit 版本均须匹配。

新建缓存目录和文件使用私有权限（平台支持时为 0700/0600）。写入先在同目录独占创建临时文件，关闭后原子替换。未变化的快照不重写；超过字节上限的快照不保留、不写入。独立进程可以竞争发布完整快照，只影响命中率。元数据 Worker 退出后，所属操作清理自己创建的临时文件。

同一共享配置内同时开始的操作共享短生命周期元数据 Worker。每个等待者保留自己的取消和截止时间；取消一个不会取消其他等待者。最后一个等待者退出时终止并等待 Worker。扫描完成后只保留有界元数据，不保留扫描 Worker 或原始字体 Buffer。fontMetadataCacheDirectory: false 仍保留进程内共享与源字体版本检查。factory 缓存有独立生命周期，由 factory.dispose() 清理。

macOS 或 Windows 上省略 fontDirectories 时，默认发现还会检查 Microsoft Office 的捆绑/私有字体目录和用户 Office 字体缓存。只补充常规系统目录中不存在的精选 Office 兼容字体族，包括宋体和微软雅黑。显式 fontDirectories 会关闭这项补充发现。

精确匹配的已安装 family 优先，包括调用方显式要求的书法或装饰字体。默认 fontFallbacks 优先选择常见的衬线、无衬线、等宽文本字体族以及对应的简体中文字面，为 Calibri 和 Calibri Light 使用 Carlito，为 Cambria 使用 Caladea。当匹配的字面已安装时，目录匹配保留 WASM 字体请求给出的字重和斜体。完整索引目录对首选字体族缺失的字形仍然可用。调用方提供的分组会替换默认值；[] 会移除这些偏好但不关闭目录发现。WASM 对导入的字体使用相同的顺序别名。随包发布的选项类型包含 fontFallbacks 的定义。

原生转换会把缺失 family 的选择写入其私有 LibreOffice 配置。LibreOffice 会先解析已安装的原始字体及其度量兼容字体，然后才参考这些选择，因此自定义分组在不同引擎上可能产生不同的替换结果。原生的字重和斜体选择取决于引擎及其能发现的字体；原生字体预加载只请求常规字面。

maxFontFiles 和 maxFontFileBytes 限制字体索引；maxLoadedFontBytes 限制本次转换中由本 kit 显式导入的原始文件。WASM 只使用导入的原始文件，找不到可用字体时以 unavailable 拒绝；在最小化容器中转换前请安装字体或配置 fontDirectories。原生 macOS 和 Windows 引擎还可以使用操作系统管理的字体，因此该导入限制不是原生字体总内存的上限。字体匹配和 XML 处理在可取消的 worker 内运行；不涉及浏览器字体 RPC 或 DOM。

Node WASM 的图像降采样使用 LibreOffice 的 CPU 图像过滤器。文本排版、字体匹配和 PDF 序列化同样由 CPU 完成。

为获得可复现的比较结果，请使用相同的文档、字体、DPI 和限制；WASM 安装在 Linux 上运行。报告时应把引擎启动时间和转换时间一起给出；每次渲染都会启动一个全新的引擎。WASM 资源和平台载荷都带有各自的源码、许可证和完整性清单。

源码与许可

本包使用 MPL-2.0 许可。引擎包包含 prebuilds.json 完整性清单、sources/ 对应源码配方和补丁，以及 licenses/ 第三方再分发声明。

使用限制

• 保真度取决于源格式、已安装字体和所选引擎。缺失字体名称不能报告所有缺字。
• 支持 DOC/DOCX/ODT、XLS/XLSX/ODS 和 PPT/PPTX/ODP 转换；直接图像渲染还接受 PDF。转换不发现系统 LibreOffice，也不下载引擎和字体。
• 字体导入和输出限制不能约束全部原生内存或临时磁盘使用。原生平台引擎的字体解析可能与 WASM 不同。
• npm 安装使用按平台选择的可选包。自行打包引擎的应用需要保留所选包的完整内容，包括资源和许可声明。
• Windows 需要系统安装与 Node.js 架构一致的 Microsoft Visual C++ v14 Redistributable（x64 或 ARM64）；包中不捆绑该运行库。Windows ARM64 引擎需要使用 ARM64 Node.js。
• 预览版声明 macOS 和 Windows 的 ARM64、x64 原生引擎，以及供 Linux 使用的共享 Node WASM 引擎；其他原生平台仅保留开发构建配方。

帧转发 SDK

@deepseek-ai/libreoffice-kit/frame-forwarding 提供独立的 Node 生产者、接收者和 C/C++ SDK，支持 macOS、Windows 的 x64/ARM64。不需要 LibreOffice 引擎时可使用 --omit=optional 安装。四套插件及静态库均随 Kit 主包分发。./frame-forwarding/sdk 描述源码与库路径，./frame-forwarding/verify 校验完整 SDK。正常安装和运行不编译或下载原生二进制。资源所有权与显式诊断构建见 SDK 文档。