README
¶
内部包导航
internal 存放仓库内部共享的实现，对外入口位于 pkg，应用入口位于 cmd。
包按具体职责命名；跨模块共享的基础能力直接放在一级目录，某个模块的专用实现放在其子目录。
| 职责 | 包 |
|---|---|
| OFD 包访问、模型与解析 | container（ZIP 索引及逻辑包视图）、models、parser |
| XML 读写与校验 | fastxml、xmlcodec、schema |
| 渲染与图像、字体处理 | render（含绘制后端）、media、coloricc、fontrepair、cidmap |
| 文字提取、结构分析与输出 | textdoc、textdoc/markdown、textdoc/docx、search |
| 清单导入导出与排版 | manifest、manifest/export、layout |
| 外部转换工具 | convert/browser、convert/office、convert/xps |
| PDF 导入与文字识别 | pdf2ofd、ocr |
| 加解密、签名与印章 | crypt、ses、signeddata、physicalsig、securexml、sealimg |
| ZIP 配置与受限包写出 | container（压缩策略与规模预算）、container/entrywriter |
| 应用支持 | server、localization、version |
| 报告排版与输出 | report（格式推断、默认主题、字体及 OFD/PDF 输出） |
| 共享基础能力与测试辅助 | cache、fileutil、contextio、testutil |
共享基础包的边界：
cache：并发安全的有界 LRU，支持权重限制、淘汰回调和条目保护。fileutil：文件查找和路径身份判断。report：统一报告格式推断、flow 默认 Material 主题、中文字体和粗体选择、长文本处理及 OFD/PDF 输出。contextio：在读写边界检查上下文取消。testutil：跨包测试共用的辅助函数。
manifest/export 依赖 manifest 的清单模型，供 creator CLI 和模型级合并共同使用。
清单解析和资源加载保留在 manifest 包中。
container 统一维护 ZIP 压缩策略、规模限制和流式写入预算；container/entrywriter
在其上实现包内路径与重复条目检查、受限写入和确定性时间，供合并、替换及解密共用。
两者均不依赖 pkg。pkg/creator 的公开 ZIP 类型和辅助函数通过别名及转调复用这些实现。
textdoc 负责文字及图片提取和版面结构分析，textdoc/docx、textdoc/markdown
消费这些结果并编排输出。格式注册和转换流程位于 pkg/converter。
convert 下的子包负责调用外部工具生成 PDF；格式注册、输入适配以及衔接
pdf2ofd 的流程位于 pkg/converter/import，详见 外部转换工具。
各模块的开发和验证约定见对应目录的 AGENTS.md。
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cache 提供支持容量、权重和淘汰保护的并发安全缓存。
|
Package cache 提供支持容量、权重和淘汰保护的并发安全缓存。 |
|
Package cidmap 为 PDF 解码和字体修复提供共享的 Adobe 字符集映射数据。
|
Package cidmap 为 PDF 解码和字体修复提供共享的 Adobe 字符集映射数据。 |
|
Package coloricc 提供基于 ICC 色彩配置文件的设备颜色到 sRGB 的转换。
|
Package coloricc 提供基于 ICC 色彩配置文件的设备颜色到 sRGB 的转换。 |
|
Package container 提供 OFD 文档容器的索引、安全读取、逻辑包视图及 ZIP 压缩和规模预算。
|
Package container 提供 OFD 文档容器的索引、安全读取、逻辑包视图及 ZIP 压缩和规模预算。 |
|
entrywriter
Package entrywriter 提供带规模限制与确定性选项的 OFD ZIP 条目写入器， 供 ZIP 级处理工具（如 pkg/merge、pkg/replace）复用。
|
Package entrywriter 提供带规模限制与确定性选项的 OFD ZIP 条目写入器， 供 ZIP 级处理工具（如 pkg/merge、pkg/replace）复用。 |
|
Package contextio 在读写边界检查取消，不负责中断底层已经阻塞的 I/O。
|
Package contextio 在读写边界检查取消，不负责中断底层已经阻塞的 I/O。 |
|
convert
|
|
|
browser
Package browser 通过 chromedp 驱动 Chrome/Chromium 把 HTML/MHTML 渲染为 PDF。
|
Package browser 通过 chromedp 驱动 Chrome/Chromium 把 HTML/MHTML 渲染为 PDF。 |
|
htmlbridge
Package htmlbridge 将预处理为 HTML 的输入接入现有浏览器转换链，统一复用 纸张、临时目录、资源访问、取消处理以及 PDF 导入设置。
|
Package htmlbridge 将预处理为 HTML 的输入接入现有浏览器转换链，统一复用 纸张、临时目录、资源访问、取消处理以及 PDF 导入设置。 |
|
office
Package office 通过 LibreOffice 命令行把 Office 文档（docx/doc/odt/rtf/wps/ pptx/xlsx 等）转换为 PDF。
|
Package office 通过 LibreOffice 命令行把 Office 文档（docx/doc/odt/rtf/wps/ pptx/xlsx 等）转换为 PDF。 |
|
process
Package process 配置外部转换命令的进程树取消和输出管道等待上限。
|
Package process 配置外部转换命令的进程树取消和输出管道等待上限。 |
|
xps
Package xps 通过 xpstopdf 命令把 XPS 文档转换为 PDF。
|
Package xps 通过 xpstopdf 命令把 XPS 文档转换为 PDF。 |
|
Package crypt 实现 GM/T 0099-2020 规定的容器协议。
|
Package crypt 实现 GM/T 0099-2020 规定的容器协议。 |
|
Package fastxml 提供 OFD 快速解析路径共用的零分配 XML lexer。
|
Package fastxml 提供 OFD 快速解析路径共用的零分配 XML lexer。 |
|
Package fileutil 提供文件查找和文件路径身份判断。
|
Package fileutil 提供文件查找和文件路径身份判断。 |
|
Code generated by generate_cff.py; DO NOT EDIT.
|
Code generated by generate_cff.py; DO NOT EDIT. |
|
Package layout 把与版式无关的流式文档模型排版为 OFD 固定版式页面。
|
Package layout 把与版式无关的流式文档模型排版为 OFD 固定版式页面。 |
|
Package localization 提供各工具共用的语言规范化逻辑。
|
Package localization 提供各工具共用的语言规范化逻辑。 |
|
compare
Package comparelocalization 提供 OFD 对比报告使用的本地化消息。
|
Package comparelocalization 提供 OFD 对比报告使用的本地化消息。 |
|
viewer
Package viewerlocalization 提供 OFD Viewer 使用的本地化消息。
|
Package viewerlocalization 提供 OFD Viewer 使用的本地化消息。 |
|
Package manifest 负责读取声明式 manifest 并构建 OFD 文档模型。
|
Package manifest 负责读取声明式 manifest 并构建 OFD 文档模型。 |
|
export
Package export 将 OFD 文档导出为 ofd-creator 可读取的 manifest。
|
Package export 将 OFD 文档导出为 ofd-creator 可读取的 manifest。 |
|
fielddocs
Package fielddocs 从 manifest 的 schema 源码中提取字段说明，供 ofd-creator schema 生成字段参考文档，也供生成器产出 fielddocs.go。
|
Package fielddocs 从 manifest 的 schema 源码中提取字段说明，供 ofd-creator schema 生成字段参考文档，也供生成器产出 fielddocs.go。 |
|
fielddocs/cmd/gen-fielddocs
command
gen-fielddocs 读取 internal/manifest/manifest.go 的字段注释，生成 internal/manifest/fielddocs.go。
|
gen-fielddocs 读取 internal/manifest/manifest.go 的字段注释，生成 internal/manifest/fielddocs.go。 |
|
Package media 提供 OFD 包中图像资源的读取和解码能力。
|
Package media 提供 OFD 包中图像资源的读取和解码能力。 |
|
Package models 定义 OFD XML 文档的内部数据模型。
|
Package models 定义 OFD XML 文档的内部数据模型。 |
|
Package ocr 提供 OCR 引擎的统一接口与结果标准化。
|
Package ocr 提供 OCR 引擎的统一接口与结果标准化。 |
|
Package parser 提供 OFD 文件的打开、解析和文档对象访问能力。
|
Package parser 提供 OFD 文件的打开、解析和文档对象访问能力。 |
|
Package pdf2ofd 提供纯 Go 的 PDF 到 OFD 转换实现：解析 PDF 页面几何、文字、 路径和图像 XObject，并使用 pkg/creator 输出 OFD 包，不依赖原生 PDF 渲染器。
|
Package pdf2ofd 提供纯 Go 的 PDF 到 OFD 转换实现：解析 PDF 页面几何、文字、 路径和图像 XObject，并使用 pkg/creator 输出 OFD 包，不依赖原生 PDF 渲染器。 |
|
config
Package config 定义 PDF 导入配置，不依赖 PDF 解析器，供 converter 与导入器共享。
|
Package config 定义 PDF 导入配置，不依赖 PDF 解析器，供 converter 与导入器共享。 |
|
Package physicalsig 读取由明文 OFD 入口定位的密文包签名，并隔离物理与逻辑引用域。
|
Package physicalsig 读取由明文 OFD 入口定位的密文包签名，并隔离物理与逻辑引用域。 |
|
Package render 将解析后的 OFD 文档渲染为图形内容。
|
Package render 将解析后的 OFD 文档渲染为图形内容。 |
|
backends/canvas
Package canvas 提供 tdewolff/canvas 的 render 后端实现：DrawContext （canvasBackend）、矢量表面与 PDF 写入器（VectorSurface/PDFDocument）、 SVG 场景、离屏栅格表面、内置栅格后端（BackendCanvas），以及默认字体引擎 （Fonts）。
|
Package canvas 提供 tdewolff/canvas 的 render 后端实现：DrawContext （canvasBackend）、矢量表面与 PDF 写入器（VectorSurface/PDFDocument）、 SVG 场景、离屏栅格表面、内置栅格后端（BackendCanvas），以及默认字体引擎 （Fonts）。 |
|
backends/canvas/canvasconv
Package canvasconv 适配OFD画笔、渐变与canvas输出。
|
Package canvasconv 适配OFD画笔、渐变与canvas输出。 |
|
backends/ftgg
Package ftgg 提供基于 FloatTech/gg 的页面栅格化后端（fogleman API + freetype/raster），通过空白导入注册到 internal/render 的注册表（Go image 包风格）：
|
Package ftgg 提供基于 FloatTech/gg 的页面栅格化后端（fogleman API + freetype/raster），通过空白导入注册到 internal/render 的注册表（Go image 包风格）： |
|
backends/rastercore
Package rastercore 提供可切换栅格后端共用的渲染上下文状态机。
|
Package rastercore 提供可切换栅格后端共用的渲染上下文状态机。 |
|
backends/rasterstate
Package rasterstate 提供栅格后端 Push/Pop 时需要镜像保存/恢复的样式 状态容器。
|
Package rasterstate 提供栅格后端 Push/Pop 时需要镜像保存/恢复的样式 状态容器。 |
|
drawing
Package drawing 定义绘制后端契约、注册表，以及 render 核心与各实现包共享的公共契约类型（字体、矢量输出、SVG 场景等）。
|
Package drawing 定义绘制后端契约、注册表，以及 render 核心与各实现包共享的公共契约类型（字体、矢量输出、SVG 场景等）。 |
|
geom
Package geom 提供渲染核心与各后端共用的几何类型及OFD绘制规则。
|
Package geom 提供渲染核心与各后端共用的几何类型及OFD绘制规则。 |
|
testscene
Package testscene 提供后端一致性测试共用的“页面场景”与配套图元/度量： 同一段 DrawContext 绘制命令可依次作用到不同光栅后端，用于逐像素对照 与速度测试。
|
Package testscene 提供后端一致性测试共用的“页面场景”与配套图元/度量： 同一段 DrawContext 绘制命令可依次作用到不同光栅后端，用于逐像素对照 与速度测试。 |
|
Package report 提供报告格式推断、flow 排版、字体加载与标准文档输出。
|
Package report 提供报告格式推断、flow 排版、字体加载与标准文档输出。 |
|
Package schema 提供内置 OFD XSD 模式的加载和查询能力。
|
Package schema 提供内置 OFD XSD 模式的加载和查询能力。 |
|
Package sealimg 生成仅供演示与测试的印章图片。
|
Package sealimg 生成仅供演示与测试的印章图片。 |
|
Package search 提供基于 Unicode 字符的文本索引与匹配能力。
|
Package search 提供基于 Unicode 字符的文本索引与匹配能力。 |
|
Package securexml 约束密码元数据 XML 的大小、结构与包内路径。
|
Package securexml 约束密码元数据 XML 的大小、结构与包内路径。 |
|
server
|
|
|
allowlist
Package allowlist 为主机名与 IP 地址提供拉取白名单，供 ofd-server 使用。
|
Package allowlist 为主机名与 IP 地址提供拉取白名单，供 ofd-server 使用。 |
|
convertersvc
Package convertersvc 把 pkg/converter 的转换能力包成可被任务队列驱动的服务。
|
Package convertersvc 把 pkg/converter 的转换能力包成可被任务队列驱动的服务。 |
|
jobstore
Package jobstore 为 ofd-server 提供基于 bbolt 的任务持久化与队列。
|
Package jobstore 为 ofd-server 提供基于 bbolt 的任务持久化与队列。 |
|
notify
Package notify 负责把任务状态变化投递到预注册的 Webhook 目标。
|
Package notify 负责把任务状态变化投递到预注册的 Webhook 目标。 |
|
runner
Package runner 是 ofd-server 的常驻编排层：取任务、跑转换、记结果、发通知。
|
Package runner 是 ofd-server 的常驻编排层：取任务、跑转换、记结果、发通知。 |
|
transfer
Package transfer 为 ofd-server 定义输入与输出两侧的抽象：待转换文档从哪里来， 转换结果写到哪里去。
|
Package transfer 为 ofd-server 定义输入与输出两侧的抽象：待转换文档从哪里来， 转换结果写到哪里去。 |
|
Package ses 实现 GB/T 38540-2020 规定的 SES 电子印章数据格式。
|
Package ses 实现 GB/T 38540-2020 规定的 SES 电子印章数据格式。 |
|
Package signeddata 实现 GB/T 35275 的 SM2/SM3 SignedData 与原文字节绑定。
|
Package signeddata 实现 GB/T 35275 的 SM2/SM3 SignedData 与原文字节绑定。 |
|
Package testutil 提供跨包测试共享的辅助构造函数。
|
Package testutil 提供跨包测试共享的辅助构造函数。 |
|
Package textdoc 把 OFD 页面中的文字对象提取为带位置的条目，供文本、Markdown 等编码器复用。
|
Package textdoc 把 OFD 页面中的文字对象提取为带位置的条目，供文本、Markdown 等编码器复用。 |
|
docx
Package docx 提供生成 OOXML WordprocessingML（.docx）所需的最小子集。
|
Package docx 提供生成 OOXML WordprocessingML（.docx）所需的最小子集。 |
|
markdown
Package markdown 把 OFD 页面渲染成 Markdown（GFM）。
|
Package markdown 把 OFD 页面渲染成 Markdown（GFM）。 |
|
Package version 提供全仓库唯一的版本号来源。
|
Package version 提供全仓库唯一的版本号来源。 |
|
Package xmlcodec 提供 OFD XML 顺序写入及读取、修改、写回支持。
|
Package xmlcodec 提供 OFD XML 顺序写入及读取、修改、写回支持。 |
Click to show internal directories.
Click to hide internal directories.