企业官网建设流程全解析

doc7 是一款把 PDF、Office、扫描件、截图、图表和公式转成 AI-ready Markdown 的文档转换工具。它的公开包github.com/magicrew/doc7与 CLI 共用同一套转换引擎，你可以在自己的 Go 程序里通过Read、Convert、ConvertBatch三大 API 直接调用，并用ProgressFunc回调实时跟踪每一页的转换进度。本文带你快速上手这三个入口的用法、选项默认值、进度事件与类型化错误处理。

三大入口 API 总览：先选对函数

doc7 的三个公开入口对应三种输入场景，选错函数是最常见的初学者错误：

简单记忆：

• 用户可能传给你的是文件、链接还是压缩包？用Read，它会在结果里告诉你最终是单文档（document）还是批量（batch）；
• 确定是单个本地文件，用Convert，返回最精简的Summary；
• 确定是一个文档目录，用ConvertBatch，返回逐文件明细BatchItem。

一键上手：用 Read 转换单个文档

首先在项目里引入公开包（不需要导入任何internal包）：

go get github.com/magicrew/doc7

一个最小可用的示例，把本地 PDF 交给配置好的 OpenAI 兼容视觉模型：

package main import ( "context" "log" "github.com/magicrew/doc7" ) func main() { options := doc7.DefaultReadOptions() options.OutputDir = "report-doc7" options.BaseURL = "http://127.0.0.1:1234/v1" options.Model = "qwen3.5-4b" result, err := doc7.Read(context.Background(), "report.pdf", options) if err != nil { log.Fatal(err) } if result.Document != nil { log.Println(result.Document.MergedMarkdown) } }

三个要点：

1. 用doc7.DefaultReadOptions()起步，只覆盖需要修改的字段，其余保持与 CLIread命令一致的默认值（见 api_read.go）；
2. ReadResult的Document和Batch两个指针字段互斥，输入是单个文件时填Document，输入是目录或 ZIP 时填Batch，用result.Mode（document或batch）判断；
3. result.Document.MergedMarkdown就是合并后的 Markdown 文件路径，可直接喂给 RAG 入库。

ReadOptions在基础选项之上多了一组批量与安全相关字段（见 api_read.go）：

Convert：单文档转换与关键选项

Convert接收一个本地路径和Options，返回Summary（定义见 api_types.go）。Summary字段可以直接用于日志和可观测性：

Options中与日常开发最相关的字段：

• 模型接入：Provider、BaseURL、Model、APIKey、Timeout；
• 页面控制：Pages（1 起始的闭区间页码，如"3-5"）、DPI（渲染分辨率）、Merge（是否合并为单文件）；
• 并发与重试：Workers（页面并发）、RetryCount；
• 恢复与缓存：Resume（跳过已成功页，只补失败页）。

DefaultOptions()的默认值与 CLI 完全一致（见 api_defaults.go）：

func main() { options := doc7.DefaultOptions() options.OutputDir = "report-doc7" options.BaseURL = "http://127.0.0.1:1234/v1" options.Model = "qwen3.5-4b" _, err := doc7.Convert(context.Background(), "report.pdf", options) if err != nil { panic(err) } }

默认值一览：PromptName: auto、Merge: true、Workers: 5、RetryCount: 3、DPI: 220、KeepImages: true、MaxTokens: 8192、ContextFallbacks: 2、MinImageDimension: 720、Timeout: 120s。其中 context fallback 是指模型因上下文不足拒绝请求时，doc7 自动降低图片分辨率重试的机制，最多重试ContextFallbacks次，图片最长边最低降到MinImageDimension像素。

ConvertBatch：递归批量转换整个目录

ConvertBatch递归转换inputDir下所有受支持的文档，返回BatchSummary（见 api_types.go）：

func main() { options := doc7.DefaultBatchOptions() options.OutputRoot = "out" options.BaseURL = "http://127.0.0.1:1234/v1" options.Model = "qwen3.5-4b" options.FileWorkers = 2 summary, err := doc7.ConvertBatch(context.Background(), "inbox", options) if err != nil { panic(err) } for _, item := range summary.Items { if item.Error != nil { log.Printf("file %d failed: %s", item.Index, item.Error.Message) } } }

批量场景的两个实用技巧：

• 先跑一次DryRun: true得到FilesTotal，再按文件数决定FileWorkers；
• 批处理中断后用Resume: true重跑，已成功的文档与页面会自动跳过。

进度回调详解：ProgressFunc 与 ProgressEvent

三个入口都支持同一个进度回调类型ProgressFunc（见 api_types.go），把它赋值给Options.Progress或BatchOptions.Progress即可：

options.Progress = func(event doc7.ProgressEvent) { switch event.Stage { case doc7.ProgressPageCompleted: fmt.Printf("page %d/%d %s\n", event.PagesCompleted, event.PagesTotal, event.Status) case doc7.ProgressFileCompleted: fmt.Printf("file %d/%d done\n", event.Index, event.Total) } }

六种进度阶段

阶段常量定义在 api_types.go：

ProgressEvent的关键字段（结构定义见 api_types.go）：

• Page/PagesTotal/PagesCompleted：单页进度三件套，做进度条用它们就够了；
• SourcePagesTotal：启用Pages页面选择时，与选中页数区分的源文档总页数；
• Cached：该页是否命中缓存，配合Resume续转时有用；
• Duration：该页或该文件的处理耗时；
• Error *PageError：非空表示失败，Kind是稳定的机器可读错误分类；
• Index/Total：仅批处理文件事件有值。

⚠️ 注意：启用并发（Workers > 1）时，页面和文件事件可能并行到达，回调内不要假设事件严格有序，聚合计数请使用原子操作或加锁。

回调的底层实现会把内部引擎的extract.ProgressEvent和batch.ProgressEvent适配为统一类型，代码见 api_progress.go。

类型化错误处理：用 errors.As 精准重试

转换失败时，doc7 返回统一的*doc7.Error，带稳定的错误分类和Retryable标志（见 api_error.go）：

result, err := doc7.Read(ctx, "report.pdf", options) if err != nil { var appErr *doc7.Error if errors.As(err, &appErr) { switch appErr.Kind { case doc7.RateLimitError: // 退避后重试 case doc7.AuthError: // 提示用户检查 API Key } } }

实践建议清单

1. 默认值起步：始终从DefaultReadOptions()/DefaultOptions()/DefaultBatchOptions()派生，只改必要字段，避免漏配；
2. 统一走 Read：对外暴露的转换接口优先用Read，让用户可以传文件、目录、URL 或 ZIP，无需你写输入分发逻辑；
3. 上下文取消：把context.Context贯穿到底，长任务可被上层优雅取消；
4. 断点续转：失败后开启Resume: true重跑同一OutputDir，成功页走缓存，只补失败页；
5. 进度做 UI：ProgressEvent.PagesCompleted / PagesTotal驱动进度条，Cached字段区分新转与命中缓存；
6. 错误分类驱动重试：只根据ErrorKind和Retryable做重试，不要解析错误文案。

相关资料

• 公开 API 定义：api.go、api_read.go、api_types.go、api_error.go
• 默认值与 CLI 对齐：api_defaults.go
• 进度事件适配：api_progress.go
• 内部编排实现：internal/read/read.go、internal/extract/extractor.go、internal/batch/batch.go
• 中文 README 中的 Go 嵌入章节：README.zh-CN.md
• 转换质量基准测试：benchmarks/visual-report/README.md