docs: 固化 Pandoc 分发与内部许可策略
This commit is contained in:
SkyJourney
@@ -0,0 +1,186 @@
|
||||
# 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 字节
|
||||
```
|
||||
|
||||
发行包来源：
|
||||
|
||||
<https://github.com/jgm/pandoc/releases/download/3.9.0.2/pandoc-3.9.0.2-windows-x86_64.zip>
|
||||
|
||||
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 字节
|
||||
```
|
||||
|
||||
发行包来源：
|
||||
|
||||
<https://github.com/jgm/pandoc/releases/download/3.9.0.2/pandoc-3.9.0.2-linux-amd64.tar.gz>
|
||||
|
||||
该程序已在 `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
|
||||
```
|
||||
|
||||
构建必须校验 SHA-256 后再解压。下载、校验和解压应位于同一构建层，不在
|
||||
最终镜像保留下载缓存。
|
||||
|
||||
`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 和临时资源目录，确保不同设备输出
|
||||
可复现。
|
||||
+12
-2
@@ -68,6 +68,15 @@ Python；左侧编辑器计划升级为 CodeMirror 6，并通过项目自有命
|
||||
支持基础工具栏及后续 Front Matter、ECharts YAML 工具扩展。完整设计与
|
||||
验收门禁见 [v0.6.0 设计文档](V0.6.0_DESIGN.md)。
|
||||
|
||||
`v0.6.0` 阶段 2 已完成 Pandoc 运行时探查：固定 `3.9.0.2`，官方
|
||||
Windows ZIP 和 Linux amd64 tarball 的 SHA-256 均已核验；Linux 静态程序
|
||||
可直接运行于 `node:22-bookworm-slim`。Desktop 安装包预计增加约
|
||||
39.34 MiB，解压目录增加约 220.35 MiB；Docker 压缩层预计增加约
|
||||
32.92 MiB，运行内容增加约 154.13 MiB。项目当前采用公司内部专属许可，
|
||||
未来公开 GitHub 时计划重新评估并切换到 Apache License 2.0。三套 Typora
|
||||
复制主题允许继续用于公司内部源码共享、部署和安装包分发，但不受项目
|
||||
许可证重新授权；公开 GitHub 前必须移除、替换或取得公开分发授权。
|
||||
|
||||
## 2. 已完成
|
||||
|
||||
### 2.1 项目骨架
|
||||
@@ -943,8 +952,9 @@ ECharts 第二阶段浏览器与 PDF 验证结果：
|
||||
|
||||
### 阶段一：v0.6.0 分阶段开发
|
||||
|
||||
- 阶段 1：冻结架构、能力边界和 Word/WPS 验收门禁；
|
||||
- 阶段 2：冻结 Pandoc 版本、许可证、Docker 与 Desktop 分发方式；
|
||||
- 阶段 1：已冻结架构、能力边界和 Word/WPS 验收门禁；
|
||||
- 阶段 2：已冻结 Pandoc `3.9.0.2`、许可证、Docker 与 Desktop
|
||||
分发方式；
|
||||
- 阶段 3：实现 DOCX 共享模型和跨端导出协议；
|
||||
- 阶段 4：实现 CodeMirror 6 与可扩展基础 Markdown 工具栏；
|
||||
- 阶段 5～8：依次实现资源预处理、动态 reference.docx、Pandoc 转换服务
|
||||
|
||||
+27
-8
@@ -1,6 +1,6 @@
|
||||
# v0.6.0 DOCX 导出与 Markdown 工具栏设计
|
||||
|
||||
状态：阶段 1 设计冻结，尚未开始功能实现。
|
||||
状态：阶段 1 架构已冻结；阶段 2 Pandoc 运行时与许可证方案已冻结。
|
||||
|
||||
## 1. 版本目标
|
||||
|
||||
@@ -153,15 +153,19 @@ Desktop 只提供平台运行时、传输与保存能力。
|
||||
|
||||
### 4.3 Pandoc 分发
|
||||
|
||||
- 开发环境允许通过显式配置或 `PATH` 使用本地 Pandoc；
|
||||
- Docker 镜像安装项目固定版本；
|
||||
- Windows Desktop 通过发行包资源目录携带固定版本；
|
||||
- 固定使用 Pandoc `3.9.0.2`，不在构建时跟随 latest；
|
||||
- 开发环境允许通过 `DOCX_PANDOC_PATH` 或 `PATH` 使用相同版本；
|
||||
- Docker amd64 使用官方 Linux 静态发行包，安装到
|
||||
`/opt/pandoc/3.9.0.2/`；
|
||||
- Windows Desktop 将官方 ZIP 中的 `pandoc.exe`、许可证和版权文件放入
|
||||
`process.resourcesPath` 下的固定资源目录；
|
||||
- 用户输入不得成为可执行路径或任意命令行参数；
|
||||
- 启动时或导出前校验版本，并通过 capability 状态报告不可用原因；
|
||||
- 发布前记录 Pandoc 许可证、源码获取方式和第三方声明；
|
||||
- 下一阶段实测 Docker 镜像与 Desktop 安装包的体积增量。
|
||||
- 启动时或导出前校验精确版本，并通过 capability 状态报告不可用原因；
|
||||
- 发行时保留 GPL、版权声明和精确版本源码获取方式；
|
||||
- Pandoc 继续作为独立子进程，不链接或导入其程序代码。
|
||||
|
||||
最终版本号和分发方式在阶段 2 根据许可证与实际包体测试冻结。
|
||||
官方文件、SHA-256、路径优先级、包体实测和许可证义务见
|
||||
[Pandoc 运行时与分发规范](PANDOC_DISTRIBUTION.md)。
|
||||
|
||||
### 4.4 动态 reference.docx
|
||||
|
||||
@@ -286,6 +290,21 @@ Front Matter 表单工具和 ECharts YAML 工具不在 `v0.6.0` 实现，但必
|
||||
DOCX 沿用当前无历史数据库原则。Markdown、图片、中间 PNG、动态模板和
|
||||
最终 DOCX 只存在于当前请求或桌面保存流程中。
|
||||
|
||||
### 6.4 当前项目许可与内部发行
|
||||
|
||||
- 当前仓库采用公司内部专属许可证，包元数据标记为 `UNLICENSED`；
|
||||
- 公司内部可以共享源码，并分发 Web/Docker、Desktop、ZIP 和测试产物；
|
||||
- 未经书面许可，不向公司外部或公开网络分发项目源码与二进制；
|
||||
- 用户文档和导出结果不因使用本软件而自动受项目许可证约束；
|
||||
- 三套 Typora 复制主题只允许随公司内部发行物分发；
|
||||
- Apache License 2.0 是未来公开 GitHub 时的候选许可证，不在当前阶段
|
||||
自动授予；
|
||||
- 公开前必须重新审查第三方依赖、主题、字体、Pandoc 源码义务及 Git
|
||||
历史。
|
||||
|
||||
根许可证和第三方边界分别见仓库根目录 `LICENSE` 与
|
||||
`THIRD_PARTY_NOTICES.md`。
|
||||
|
||||
## 7. 验收矩阵
|
||||
|
||||
### 7.1 文档内容
|
||||
|
||||
Reference in New Issue
Block a user