Skip to content
zc310Public

About

Go toolkit for OFD: convert (OFD⇄PDF/PNG/Markdown, PDF/Office/HTML→OFD), create, validate, analyze, render, sign, encrypt and preview in browser, desktop and Android.

Topics

Resources

Security policy

Stars

19 stars

Watchers

4 watching

Forks

Repository files navigation

OFD Go Toolkit 图标

OFD Go Toolkit

GoDoc GitHub Release Go Build & Test Coverage Status GitHub Stars

用 Go 解析、创建、转换、渲染、校验和分析 OFD 文档。提供 Go API、命令行工具、 HTTP 服务,以及桌面、Android 和浏览器阅读器。

想做什么 入口
在线体验 OFD Toolbox(覆盖本库大部分功能);浏览器阅读器;Gio Web 阅读器
下载应用或命令行工具 GitHub Releases、发布包下载指南(文件名、系统与架构对应表)
转换、创建和检查文档 快速开始、功能特性
选择桌面、Android 或浏览器阅读器 阅读器
让 AI 调用命令行工具 CLI Skill(工具选择、命令示例与安全边界)
接入自己的 Go 项目 Go API、库使用指南
组合签名、加密与完整性保护 安全能力指南
从源码运行和打包 构建与打包、构建指南
查询兼容性与标准资料 支持清单、文档目录

快速开始

下载 Release 中对应平台的命令行程序后运行; 文件名中的 darwin 表示 macOS,amd64 适用于 Intel/AMD 64 位电脑,完整对应表见 发布包下载指南。

从源码运行时,在仓库根目录将程序名替换为 go run ./cmd/工具名,例如 go run ./cmd/ofd-converter input.ofd output.pdf。工具链与构建依赖见构建与打包。

转换文档

# OFD 转 PDF
ofd-converter input.ofd output.pdf

# 首页输出为 PNG;页码从 1 开始
ofd-converter --page 1 --dpi 150 input.ofd page1.png

# 多页图片输出为 ZIP
ofd-converter --format png input.ofd pages.zip

# PDF 转 OFD
ofd-converter input.pdf output.ofd

ofd-converter 默认使用 150 DPI 和白色背景,--page 使用多文档体合并后的全局页码。 OFD 转 PDF 默认不新增有损图片压缩;--pdf-lossy-images 可允许图片颜色转 JPEG, 透明蒙版仍无损保存。PNG 编码速度可通过 --png-compression-level 调整,像素保持无损。 批量转换、完整选项和退出码见 转换工具说明。

常规 OFD 转 PDF、图片及 PDF、CSV/TSV 导入使用 Go 实现。Office、HTML、EML、SVG、XPS 和 OCR 的 外部工具要求见 运行依赖,PDF 的可选 OpenJPEG 后端见 PDF 支持清单。

创建与检查

# 从 YAML 或 JSON 清单创建 OFD
ofd-creator -i document.yaml -o result.ofd --validate

# 校验与分析
ofd-validator --format text input.ofd
ofd-analyzer --format json input.ofd

# 多份文档与第一份比较,生成可离线查看的图文差异报告
ofd-compare -o comparison.html original.ofd revised.ofd final.ofd

创建清单见 creator 示例;大对比报告可使用 --external-images 将图片保存到报告旁。

加密与解密

# 口令文件按原始 UTF-8 字节读取,保留空格和换行
ofd-crypt encrypt --password-file password.txt -o encrypted.ofd input.ofd
ofd-crypt decrypt --password-file password.txt -o plain.ofd encrypted.ofd

GM/T 0099-2020 加解密使用不提供认证的 CBC;解密成功不证明内容未被篡改、证书可信或签名有效。 重要场景请独立验证签名和完整性证据,组合方式见安全能力指南, 格式约定与限制见密码功能说明。

功能特性

场景 能力与工具
文档转换 ofd-converter:OFD 导出 PDF、DOCX、HTML、文本、Markdown、PNG/JPG、TIFF、SVG;PDF、Markdown、Office、HTML/MHTML、图片、XPS、EML、SVG、CSV/TSV 导入 OFD。
创建与编辑 ofd-creator:JSON/YAML 清单、数据模板与配置导出;流式自动排版、主题、提示框、表格与公文基础版式;合并、拆分、选页重排、页面叠加、水印与条目替换。
规范校验 ofd-validator:检查 ZIP、XML、XSD、引用、语义与摘要,提供分阶段状态和问题定位。
结构分析 ofd-analyzer:分析文档、页面、资源、附件、注解与签名,提供结构化诊断、静态 URI 审计和资源依赖闭包;不代替规范校验。
文档对比 ofd-compare:比较目录、摘要、XML、文字和画面,支持页配对、局部放大与外置图片;输出 HTML、JSON、文本和 Markdown。
档案预检与处理 ofd-archive:技术清单、归档准备目录、符合性矩阵与 SHA-256 固定性验证;preserve 提供长期保存转换与改动计划。
发票处理 ofd-invoice:增值税电子发票、铁路电子客票抽取,支持结构化附件与自定义标引,JSON/CSV/XLSX 汇总、去重、自校验与 PDF 合并打印。
电子印章与签名 ofd-seal 生成 SES V4 SM2/SM3 印章;pkg/sign 支持签章、SM2/RSA/ECDSA 普通数字签名、外部签署与完整验证;ofd-creator 支持签名追加和移除。
OFD 加解密 ofd-crypt:口令/证书、多接收者、整包/条目/页面范围加密、多层解密和只读解密视图。
完整性保护 pkg/integrity 与 ofd-crypt integrity:带时间戳清单、物理集合、内容覆盖及引用闭包检查。
阅读器 桌面、Android 与浏览器阅读器,提供独立应用、在线入口和 WASM API。
HTTP 服务 ofd-server:同步流输出、异步转换任务、ZIP 图片包按文件名自然排序合成 OFD、图片导入 OCR(本机或 HTTP)、远程产物传输及 OpenAPI 在线文档。
Linux 桌面集成 ofd-thumbnailer:OFD 首页及 ZIP 包内图片缩略图,加密 OFD 显示固定挂锁图案;提供 ZIP、DEB 和 RPM 安装包。

校验器与分析器均支持文本、Markdown、JSON、OFD、PDF 和 XLSX 报告。OFD/PDF 报告使用统一的 Material 主题,以提示框突出状态与检查范围,问题明细支持跨页表格;未执行的检查不代表通过。

电子证照的 TypeID="cert" 标引入口支持创建、读取及 JSON/YAML 清单往返。 独立校验使用 ofd-validator --custom-tag-type-id;该开关仅覆盖标引入口, 尚不代表 GB/T 36905 全面合规。用法和范围见 创建示例。 基础元数据与标识本地检查另用 ofd-validator --certificate-metadata (Go API:validator.WithCertificateMetadata(true)),支持必选项、标准短名、 MOD 37,36、日期及多值对应;不验证登记、授权、签名或全面合规。 规则范围及标准示例差异见 证照库说明。 原件锁定、移除明确指定的旧锁定签名后制作加注件及重新验收,使用独立 Go API pkg/certificate/workflow。它要求完整信任、 吊销证据与外部机构角色授权,不把数学验签或元数据格式通过当作证照业务可信。

签名验收应检查完整结论 Result.FullyValid(),而非仅检查数学验签结果。 外部签署协议示例见 ofd-signer-demo。

Go API

在已有 Go 项目中添加依赖,Go 工具链要求以 go.mod 为准:

go get github.com/zc310/ofd@latest

下面是一个完整的 OFD 转 PDF 示例。转换入口的首参是 context.Context,长任务可传入 带取消或超时的上下文:

package main

import (
	"context"
	"log"
	"os"

	"github.com/zc310/ofd/pkg/converter"
)

func main() {
	output, err := os.Create("output.pdf")
	if err != nil {
		log.Fatal(err)
	}

	err = converter.PDF(context.Background(), "input.ofd", output)
	closeErr := output.Close()
	if err != nil {
		log.Fatal(err)
	}
	if closeErr != nil {
		log.Fatal(closeErr)
	}
}
需求 Go 入口
标准常量与 XML 声明模型 pkg/spec、公开范围与使用边界
转换与渲染 pkg/converter、可运行示例
导入 PDF、Markdown 等格式 按需注册导入器、Markdown 排版与字体
按页渲染、文字、搜索与导航 pkg/reader、接入示例
创建 OFD 与流式写出 pkg/creator 库指南
自动排版、主题与提示框 pkg/creator/flow 流式创作、Callout 提示框
多文档合并、拼页和重排 pkg/creator/merge、合并与选页说明
按范围、每 N 页或文档体拆分 pkg/creator/split 库指南、拆分命令
条目编辑与水印 pkg/creator/replace、pkg/creator/watermark
签署、生成印章和验证 pkg/sign 库指南
检查加密元数据与加解密 OFD pkg/crypt 库指南、密码功能与实现约定
整包完整性检查及安全能力组合 pkg/integrity 库指南、安全能力指南
文档对比 pkg/compare 库指南
长期保存转换与改动计划 pkg/archive/preserve、输入限制与处理边界

接入约定

  • 输入与输出:输入类型、页码、DPI、缓存和字体等细节见 Go API 使用指南。 转换取消或失败后应丢弃部分输出,并处理调用方输出文件的关闭错误。
  • 文档权限:阅读、导出、编辑和签署等入口执行对应权限及有效期检查,策略与显式诊断授权见 阅读器权限策略。归档检查、原件保存与长期保存处理属于独立用途, 不因声明或过期拒绝;业务归档授权与访问控制由调用方负责,普通阅读/导出权限不因此豁免。
  • JSON 契约:请求、配置和创建清单的字段名区分大小写,同一对象中的字段不能重复。 报告与服务响应应按字段解析,map 键不保证输出顺序。

独立应用接入示例:ofd-viewer、 ofd-toolbox。

阅读器

阅读器入口

阅读器 平台 定位与入口
ofd-viewer(Gio) Windows、macOS、Linux、Android、浏览器 Gio 阅读器;连续阅读、缩略图及桌面端 PDF/图片/文本导出,移动端和浏览器功能有差异。
ofd-wasm 浏览器 在线阅读;文字选择、搜索、导航、图层、附件和签名检查,提供 WASM API 与 Worker 协议。
ofd-viewer-wails Windows、macOS、Linux、Android 实验性;原生 Go 渲染,与浏览器共用界面,支持搜索、导航、附件预览、导出及桌面打印。

浏览器版本在本地处理文档,本地启动方式见 WASM 构建与运行。 加密文档解锁、附件与媒体预览、导出范围及资源预算见对应阅读器文档;印章预览不代表签名有效或证书可信。 Wails 使用独立构建入口;Wails Android 暂不支持原生打印。

桌面版系统要求对照

系统支持范围同时受 Go 工具链、界面框架和实际产物的动态库依赖限制。 依赖版本以 go.mod 为准;下表是运行条件,不代表所有系统组合均已实机验证。

平台 Gio 版 ofd-viewer Wails 版 ofd-viewer-wails
Windows Windows 10/11,需要 OpenGL 图形驱动,不依赖 WebView2 Windows 10/11,需要 WebView2 Runtime;安装包不捆绑该运行时
macOS 最低系统版本取决于实际构建使用的 Go 工具链 同样受 Go 工具链限制,另需系统 WKWebView 支持界面所用的网页功能
Linux X11/Wayland、OpenGL 及相应运行库,不依赖 GTK/WebKit 默认 GTK4、WebKitGTK 6.0 及桌面图形环境,以 Ubuntu 24.04+ 为发行适配目标
Android 实际要求以 Gio 构建的 APK 为准 Android 7.0 / API 24 及以上,ARM64 / x86_64,需现代系统 WebView

两版正式 Windows 构建均不支持 Windows 7/8/8.1。Linux CGO 产物受构建机 glibc 和图形库版本约束, 在新发行版编译不代表能在旧发行版运行;应在计划支持的最老目标系统上构建并验证。 详细版本与依赖见 阅读器说明、 Wails 系统要求,移动端差异见 Wails Android 说明。

构建与打包

需要 Go 1.27 或更高版本,具体要求以 go.mod 为准。在仓库根目录执行,发行版本由 Makefile 的 VERSION 统一注入:

# 当前平台的命令行工具
make build-tools

# 当前平台的命令行工具 ZIP 包
make package-tools

# 当前平台的桌面阅读器与命令行工具包
make package-desktop

构建输出默认位于 /tmp/ofd/.build,发布包位于 /tmp/ofd/dist,可通过 BUILD_DIR、DIST_DIR 覆盖。默认 make 还会生成 Linux 缩略图 DEB 和 RPM,需先安装 nFPM(make install-nfpm 并将 Go bin 目录加入 PATH,或设置 NFPM)。 Android、WASM、交叉编译、系统依赖与 Windows 7 兼容工具链的试编译说明见 构建指南。

实验性渲染后端

  • Gio GPU 栅格后端:提供自动 CPU 回退、严格 GPU 入口和累计回退诊断,尚未作为默认转换后端。
  • pdfcpu PDF 写入后端:可用 go build -tags pdfcpu ./cmd/ofd-converter 注册;不加标签仍使用 canvas。

内置绘图与字体库维护

绘图与字体解析代码分别维护在 internal/thirdparty/canvas 和 internal/thirdparty/font,不再依赖外部 github.com/tdewolff/canvas、github.com/tdewolff/font 模块或本地 workspace。 来源、MIT 许可、裁剪范围与测试入口见各自说明。两者均不附带字体文件; 文档内嵌字体和系统字体回退策略不变。

支持清单与工具文档

支持清单区分已支持、部分支持和暂不支持,记录能力边界与兼容处理:

格式 支持范围与限制
OFD 解析、创建、渲染、校验与阅读
PDF PDF 转 OFD、资源预算与诊断
Office Office 转 OFD/PDF
HTML/MHTML 浏览器打印与格式转换
CSV/TSV 表格导入、编码与字体
EML 邮件 邮件正文、CID 图片与原附件保留
SVG 矢量图导入与纸张设置

工具的参数与退出码见功能表中的文档。标准资料、截图与维护入口汇总在 文档目录;已发布接口的破坏性变更见 CHANGELOG。 指定版本的性能测试见 ofd-performance,结果见性能趋势。 交叉库性能对比见 ofd-benchmark,实际表现取决于 文档样本、字体、操作系统和运行环境。

OFD 简介

OFD(Open Fixed-layout Document)是中国电子文件领域常用的版式文档格式,适用于 电子证照、电子发票、数字档案和公文。文件通常以 ZIP 容器组织 XML、页面、文字、 路径、图片、字体、附件和签名等资源,并保留相应的布局和绘制信息。

GB/T 33190-2016 等标准的官方查询链接见标准资料索引。 项目不随仓库分发标准全文;不同生产方的扩展与兼容处理见 OFD 支持清单。

许可证

本项目基于 Apache License 2.0 发布,声明见 LICENSE 和 NOTICE。 第三方依赖的来源与许可见 THIRD-PARTY-LICENSES,测试样例来源见 testdata/README.md,项目图标的来源与许可见图标说明。

使用本项目及其输出结果前,请阅读 免责声明。本项目不保证所有 OFD 文件的解析、转换、校验或渲染结果适用于特定业务、法律或合规场景。如发现仓库、文档 或示例中可能存在侵权内容,请通过 GitHub Issues 联系维护者。

About

Go toolkit for OFD: convert (OFD⇄PDF/PNG/Markdown, PDF/Office/HTML→OFD), create, validate, analyze, render, sign, encrypt and preview in browser, desktop and Android.

Topics

Resources

Security policy

Stars

19 stars

Watchers

4 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages