# Pandoc 运行时与分发规范 状态：`v0.6.0` 阶段 2 冻结。 ## 1. 固定版本 `v0.6.0` 固定使用 Pandoc `3.9.0.2`。 选择依据： - 这是阶段冻结时的官方稳定版本； - 本地 DOCX 探查和 Word/WPS 往返实验使用同一版本； - 官方 Windows 和 Linux 静态发行包均包含 Lua 支持； - 默认 `reference.docx` 已嵌入可执行文件； - Windows 便携程序和 Linux 静态程序均不需要 Python。 不得在构建时自动下载“latest”。升级 Pandoc 必须作为显式变更，重新执行 DOCX OOXML、Word/WPS 互操作和包体回归。 ## 2. 官方发行文件 ### 2.1 Windows Desktop ```text 文件：pandoc-3.9.0.2-windows-x86_64.zip SHA-256：C97542F2800F446E788D9F74237856D995421AD1BB3CC8324286840C5F272D3A 压缩大小：41,250,425 字节 pandoc.exe：231,056,136 字节 ``` 发行包来源： Desktop 只将解压后的以下内容放入应用资源目录，不嵌入 MSI 安装器： ```text resources/pandoc/3.9.0.2/windows-x86_64/ ├── pandoc.exe ├── COPYING.rtf └── COPYRIGHT.txt ``` `MANUAL.html` 可以放入发行文档或第三方说明，不是运行必需文件。 ### 2.2 Docker amd64 ```text 文件：pandoc-3.9.0.2-linux-amd64.tar.gz SHA-256：A69ABFABABDA8A56969A254B09F9553A7BE89DDEC00D4E0FE9FD585D71A67508 压缩大小：34,520,947 字节 pandoc：161,618,224 字节 ``` 发行包来源： 该程序已在 `node:22-bookworm-slim` 中验证： ```text pandoc 3.9.0.2 Features: +server +lua not a dynamic executable ``` Docker 安装目标： ```text /opt/pandoc/3.9.0.2/bin/pandoc /usr/local/bin/pandoc -> /opt/pandoc/3.9.0.2/bin/pandoc ``` 官方 Linux 二进制 tarball 实际只包含 `bin/pandoc`，不包含许可证和版权 文件。Docker 构建会从同一个不可变版本标签 `3.9.0.2` 取得以下文件，并 分别执行 SHA-256 校验后放入相同运行目录： ```text COPYING.md SHA-256：9D56CAC92294E206AF026A5502BEE0FED77200B08B51EC28AA63C9EFDA4DCFDD COPYRIGHT SHA-256：842E33EF01625E93F85BEBB8BAC83AA570186B7AA77A09971257CC29F8F60740 ``` 二进制归档、许可证和版权文件均在独立下载阶段获取与校验，最终镜像只 复制 `/opt/pandoc/3.9.0.2/`，不保留下载缓存、Curl 或下载阶段依赖。 `v0.6.0` 正式验证范围为 Linux amd64。官方同时提供 arm64 包，但在完成 Playwright、Pandoc 和 DOCX 全链路验证前，不宣称 arm64 发布支持。 ## 3. 路径发现与版本校验 应用服务采用以下优先级： 1. 服务端或开发环境显式配置的 `DOCX_PANDOC_PATH`； 2. Desktop 的 `process.resourcesPath` 固定资源路径； 3. Docker 的 `/opt/pandoc/3.9.0.2/bin/pandoc`； 4. 开发环境 `PATH` 中的 `pandoc`。 约束： - Web 页面、Markdown 和导出请求不能指定可执行路径； - Desktop 渲染进程不能直接启动或选择 Pandoc； - 显式路径只允许由受信任的服务端环境或开发者配置； - 调用必须使用 Node `spawn`/`execFile` 的参数数组，不经过 Shell； - 路径解析后执行 `pandoc --version`，首行必须精确匹配 `pandoc 3.9.0.2`； - 不接受不同补丁版本静默降级； - 能力检测失败时 DOCX capability 返回不可用原因，PDF 能力继续可用。 正式实现中的能力状态至少区分： ```text available not-found version-mismatch not-executable probe-timeout ``` ## 4. 许可证与源码义务 Pandoc 采用 GNU GPL version 2 or later。项目将其作为未修改的独立程序， 通过命令行参数和临时文件通信，不链接或导入 Pandoc 代码。 每个包含 Pandoc 的二进制发行必须： - 保留 Pandoc `COPYING`、`COPYRIGHT` 和版本信息； - 在第三方声明中标明 Pandoc 名称、版权、许可证和项目地址； - 提供与所分发二进制精确对应的源码获取方式； - 将对应源码归档与应用二进制放在同一版本的发布位置； - 保证离线或内部转交发布产物时，许可证说明和源码获取信息同时转交； - 不对 Pandoc 施加禁止再分发、禁止逆向或额外保密限制。 项目发布资产计划至少包含： ```text md-to-pdf-0.6.0-x86_64-Setup.exe md-to-pdf-0.6.0-x86_64.zip pandoc-3.9.0.2-source.tar.gz THIRD_PARTY_NOTICES.md ``` Docker 镜像必须包含许可证、版权声明和源码归档位置说明，并通过 OCI `org.opencontainers.image.source`、版本和文档标签指向项目发布位置。 若未来修改 Pandoc 源码或构建方式，必须重新审查 GPL 对完整对应源码和 构建脚本的要求。公开或商业发布前应由项目权利人完成最终法律审查；本 规范是工程合规约束，不构成法律意见。 ## 5. 包体实测 基线为本机已有 `v0.5.1` 正式产物。以下数值使用官方压缩包和解压程序 实测，NSIS 与 ZIP 最终值仍以 `v0.6.0` 构建结果为准。 | 产物 | v0.5.1 基线 | v0.6.0 估算 | 增量 | | --- | ---: | ---: | ---: | | Desktop 运行目录 | 333.98 MiB | 554.33 MiB | 220.35 MiB | | NSIS 安装包 | 109.38 MiB | 约 148.71 MiB | 约 39.34 MiB | | Desktop ZIP | 145.13 MiB | 约 184.47 MiB | 约 39.34 MiB | | Docker 内容大小 | 615.91 MiB | 约 770.05 MiB | 154.13 MiB | | Docker 压缩拉取层 | — | — | 约 32.92 MiB | 结论： - Desktop 解压目录增长明显，但安装包和 ZIP 受压缩后增量约 39 MiB； - Docker 运行时内容增长约 154 MiB，镜像传输增量约 33 MiB； - 不采用首次使用时联网下载，以保持内网和离线 Desktop 能力； - 不使用 UPX 或二次修改官方二进制，避免兼容性、杀毒误报和合规风险； - 不为了减小包体引入 Python 或另一个文档转换运行时。 ## 6. 构建与更新规则 后续实现应增加受版本控制的运行时清单，至少记录： - Pandoc 版本； - 平台和架构； - 官方下载地址； - SHA-256； - 解压后的相对可执行路径； - 许可证和版权文件； - 对应源码归档地址。 构建流程必须： 1. 根据清单下载或读取缓存； 2. 校验 SHA-256； 3. 拒绝未知平台和架构； 4. 将运行所需文件复制到固定目录； 5. 生成或复制第三方声明； 6. 构建后执行 `pandoc --version`； 7. 用最小 Markdown 生成 DOCX 冒烟文件； 8. 检查发行包中不存在用户级 Pandoc 配置或缓存。 运行时不得读取用户 Pandoc 数据目录。DOCX 转换应通过隔离环境变量或显式 参数使用项目控制的模板、Lua Filter 和临时资源目录，确保不同设备输出 可复现。