Doc2X CLI 使用手册

doc2x-cli 是 Doc2X 提供的命令行工具，用于将 PDF 或图片文件解析、转换为 Markdown、Word、LaTeX、HTML 或 PDF 格式，并支持多语言的文档翻译与批量处理。

核心命令总览

命令	功能说明
`doc2x login`	通过浏览器登录 Doc2X（OAuth）
`doc2x logout`	清除已保存的 OAuth 凭证
`doc2x parse <input>`	解析 PDF 或图片，导出为指定结构化文档格式
`doc2x translate <input>`	解析并翻译 PDF 文件
`doc2x batch <action> [inputs...]`	对多个文件或目录执行批量 `parse` 或 `translate`
`doc2x models list`	查询当前账号支持的翻译模型列表
`doc2x term list`	查询当前账号下配置的术语表及 ID

环境与安装

环境要求： Node.js 22 或更高版本
网络要求： 需要能够访问 Doc2X 服务
文件限制： PDF 文件最大支持 300 MB，图片最大支持 3 MB
支持的图片格式： png、jpg、jpeg、gif、bmp（不支持 webp、tiff、tif）

前置条件

为 @noedgeai 作用域配置 GitHub Packages registry（一次性操作）：

bash

npm config set @noedgeai:registry=https://npm.pkg.github.com

本包托管在 GitHub Packages 上且公开访问，无需登录或配置 token。

安装

通过 npm 全局安装工具包：

bash

npm i -g @noedgeai/doc2x-cli@latest

# 验证安装
doc2x --version

提示： 如果安装后提示 command not found: doc2x，请检查 npm 的全局可执行目录是否已加入系统环境变量 PATH 中。

鉴权与登录

doc2x-cli 提供两种鉴权模式，可通过 --auth-mode 参数切换。

Client 模式（默认）

直接读取本地正在运行的 Doc2X 桌面客户端的登录状态。适用于个人开发机。确保桌面客户端已登录并保持运行状态即可直接执行命令：

bash

doc2x parse ./paper.pdf

OAuth 模式

通过浏览器进行 OAuth 登录鉴权。适用于服务器、CI/CD 环境或无桌面客户端的设备：

bash

# 登录（打开浏览器完成 OAuth 授权）
doc2x login

# 登录成功后即可执行命令
doc2x --auth-mode oauth parse ./paper.pdf

# 如果无法打开浏览器，可使用 --no-browser 选项手动复制链接
doc2x login --no-browser

# 退出登录（清除凭证）
doc2x logout

OAuth 凭证存储在系统应用数据目录下（macOS：~/Library/Application Support/doc2x/，Linux：~/.config/doc2x/，Windows：%APPDATA%\doc2x\），支持自动刷新 Token。

全局参数

以下参数适用于所有命令：

参数	说明	默认值
`--config <path>`	配置文件路径（YAML/JSON）	-
`--auth-mode <mode>`	鉴权模式：`client` 或 `oauth`	`client`
`--timeout <ms>`	API 请求超时时间（毫秒）	`60000`
`--retry <n>`	下载/导出的重试次数	`2`
`--json`	以 JSON 格式输出结果	`false`
`--quiet`	静默模式，仅输出错误和最终结果	`false`
`--verbose`	输出调试信息	`false`
`--no-color`	禁用彩色输出（非 TTY 环境自动禁用）	自动检测

快速开始

以下为最常见的四个操作场景：

bash

# 1. 解析 PDF 并导出为 Markdown（默认）
doc2x parse ./paper.pdf

# 2. 解析 PDF 并导出为 Word
doc2x parse ./paper.pdf --to docx

# 3. 将 PDF 翻译为中文，并导出为 Word
doc2x translate ./paper.pdf --target-language zh --to docx

# 4. 批量解析目录下的所有 PDF 为 Markdown
doc2x batch parse ./docs --glob "**/*.pdf"

默认情况下，输出文件将保存在当前目录的 output 文件夹中。

文档解析 (parse)

parse 命令支持处理 PDF 和图片。使用 --to 参数指定输出格式，支持：md（默认）、docx、tex、html、pdf、none（仅解析不导出）。

bash

doc2x parse ./paper.pdf --to tex
doc2x parse ./image.png

解析参数

参数	说明	默认值
`--to <fmt>`	输出格式：`none`、`md`、`tex`、`docx`、`html`、`pdf`	`md`
`--image-models <models...>`	图片 OCR 模型（`doc2x` 为必选）：`doc2x` `mathpix`	`doc2x`
`--vision-models <models...>`	LLM 视觉模型（使用 `doc2x models list` 查询模型 ID）	-
`--image-hosting <mode>`	图片来源：`local` 或 `online`	`local`
`--formula-mode <mode>`	公式分隔符：`normal` 或 `dollar`	`normal`
`--formula-level <level>`	公式降级级别：`normal`、`onlyLine`、`processAll`	`normal`
`--merge-cross-page-forms`	尝试合并跨页表格	`false`
`--remove-comments`	移除输出中的 HTML 注释	`false`
`--avoid-indented-code-blocks`	代码缩进兼容性处理	`false`
`--out <path>`	输出目录或文件路径	`./output`
`--name <pattern>`	文件名模板：`{basename}`、`{date}`、`{lang}`	`{basename}`
`--overwrite`	覆盖已有的输出文件	`false`

公式 dollar 模式注意： --formula-mode dollar 仅在导出为 Markdown 时生效，搭配其他导出格式无效。
导出 HTML 的注意事项： 导出 HTML 格式时，公式渲染依赖 MathJax CDN。如果需要在完全离线的环境下阅读文档，推荐导出为 docx 或 pdf。
在线图片托管注意： 使用 --image-hosting online 时，图片仅保存 30 天。

文档翻译 (translate)

translate 针对 PDF 文件进行翻译。必须通过 --target-language 指定目标语言代码。

支持的目标语言

zh（中文）、en（英语）、ja（日语）、fr（法语）、ru（俄语）、pt（葡萄牙语）、pt-BR（巴西葡萄牙语）、es（西班牙语）、de（德语）、ko（韩语）、ar（阿拉伯语）

翻译模式差异

根据需求不同，翻译支持两种模式（通过 --translate-type 控制）：

文档型翻译（默认：md）： 提取内容翻译后，可自由导出为 Markdown、Word、HTML 等格式。支持双语对照设置。
固定排版翻译（pdf）： 保持原文档版式，直接输出翻译后的 PDF 文件。此时输出格式固定为 .pdf。

bash

# 文档型翻译：翻译为中文，输出 Word
doc2x translate ./paper.pdf --target-language zh --to docx

# 固定排版翻译：翻译为中文，输出保持原排版的 PDF
doc2x translate ./paper.pdf --target-language zh --translate-type pdf

翻译参数

以下为翻译命令的专属参数（翻译命令同时继承所有解析参数）：

参数	说明	默认值
`--translate-type <t>`	翻译模式：`md` 或 `pdf`	`md`
`--target-language <lang>`	目标语言代码	`zh`
`--target-model <model>`	翻译使用的 LLM 模型	默认模型
`--term-id <id>`	术语表 ID（通过 `doc2x term list` 获取）	-
`--font-color-extraction`	提取字体颜色	`false`
`--ignore-translate-types <list...>`	忽略的元素类型：`table`、`code`、`figure`、`reference`	-
`--convert-trans <t>`	输出内容：`both`（双语）、`origin`（仅原文）、`translate`（仅译文）	`both`
`--contextual-translation`	启用上下文增强翻译	`false`

批量处理 (batch)

batch 命令用于一次性处理多个文件或整个目录，并自动生成处理报告。

bash

# 批量解析目录中的指定文件
doc2x batch parse ./docs --glob "**/*.pdf" --to docx

# 批量翻译，遇到错误继续执行
doc2x batch translate ./papers --glob "**/*.pdf" --target-language zh --continue-on-error

批量参数

参数	说明	默认值
`--glob <pattern>`	文件匹配模式	`*/.{pdf,png,jpg,jpeg}`
`--continue-on-error`	单个文件失败后继续处理	`false`
`--skip-existing`	跳过已有输出文件	`true`
`--report <path>`	处理报告输出路径	`./doc2x-report.json`
`--dry-run`	仅打印将要处理的文件列表，不执行实际操作	`false`

批量命令同时支持所有 parse 和 translate 参数。

模型查询 (models)

查询当前账号可用的翻译模型列表，返回模型 ID、名称及订阅要求等信息。翻译命令的 --target-model 参数需要使用此处的模型 ID。

bash

doc2x models list

# JSON 格式输出
doc2x models list --json

术语表管理 (term)

术语表用于在翻译时统一专业术语的翻译结果。

术语表子命令

子命令	说明	必需参数
`doc2x term list`	查询所有术语表	-
`doc2x term create`	创建新的术语表	`--name <name>`
`doc2x term items`	查看术语表中的条目	`--term-id <id>`
`doc2x term import`	从 CSV 文件导入术语	`--term-id <id> --file <path>`

bash

# 查询所有术语表
doc2x term list

# 创建术语表
doc2x term create --name "技术词典"

# 查看术语表中的条目
doc2x term items --term-id <id>

# 从 CSV 文件导入术语
doc2x term import --term-id <id> --file terms.csv

CSV 导入格式

CSV 文件支持以下列（符合 RFC 4180 标准）：

列名	说明	默认值
`origin`	原文术语	（必填）
`translate`	翻译术语	（必填）
`originLang`	原文语言代码	`en`
`translateLang`	翻译语言代码	`zh`

语言代码支持：zh、en、ja、fr、ru、pt、pt-BR、es、de、ko、ar。

示例 CSV 文件：

text

origin,translate,originLang,translateLang
machine learning,机器学习,en,zh
neural network,神经网络,en,zh

配置与输出设置

输出控制

通过 --out 指定输出目录，通过 --name 配置文件名模板。支持的占位符包括：{basename}、{date}、{lang}。

bash

# 指定输出目录与带语言后缀的文件名
doc2x translate ./paper.pdf --target-language zh --out ./results --name "{basename}_{lang}" --to docx

使用配置文件

对于常用的参数组合，可编写 YAML 或 JSON 配置文件，通过 --config 调用。

配置优先级（从高到低）：CLI 命令行参数 > 配置文件 > 内置默认值。

yaml

# doc2x.yaml
authMode: client
timeout: 60000
retry: 2
defaults:
  parse:
    to: docx
    imageModels: ["doc2x"]
    visionModels: []
    imageHosting: local
    formulaMode: normal
    formulaLevel: normal
    mergeCrossPageForms: false
    removeComments: false
    avoidIndentedCodeBlocks: false
    out: ./output
    name: "{basename}"
    overwrite: false
  translate:
    translateType: md
    targetLanguage: zh
    targetModel: "72"
    termId: ""
    fontColorExtraction: false
    ignoreTranslateTypes: []
    convertTrans: both
    contextualTranslation: false
  batch:
    glob: "**/*.{pdf,png,jpg,jpeg}"
    continueOnError: false
    skipExisting: true
    report: ./doc2x-report.json
    dryRun: false

bash

doc2x --config ./doc2x.yaml parse ./paper.pdf

JSON 输出

使用 --json 参数可将命令输出格式化为 JSON，便于脚本集成和自动化处理：

bash

doc2x parse ./paper.pdf --json
doc2x batch parse ./docs --json

退出码

退出码	含义
`0`	成功
`1`	参数错误
`2`	鉴权失败
`3`	输入文件错误
`4`	任务处理失败
`5`	导出失败
`6`	批量处理部分失败

常见问题排查

现象 / 报错	排查建议
`Cannot connect to desktop client`	确认桌面客户端已启动并登录。若在服务器或无图形界面环境，请使用 `doc2x login` 并切换为 `--auth-mode oauth`
OAuth 登录失败	确认网络可访问 Doc2X 服务，尝试使用 `doc2x login --no-browser` 手动复制链接
目标文件未生成或无变化	CLI 默认不覆盖已有文件。如果需强制更新输出结果，请在命令中添加 `--overwrite` 参数
图片上传被拒绝或失败	检查图片格式与大小。当前限制单张图片最大 3 MB，格式不支持 webp、tiff 或 tif，建议转换为 png 或 jpg
提示额度不足 / 模型需订阅	检查账户剩余调用额度及订阅状态。部分特性（如启用 `mathpix` 模型）可能需要高级账户权限

Doc2X 客户端

一键转存指南

Doc2X MCP 使用指南

Doc2X CLI 使用手册

核心命令总览

环境与安装

前置条件

安装

鉴权与登录

Client 模式（默认）

OAuth 模式

全局参数

快速开始

文档解析 (parse)

解析参数

文档翻译 (translate)

支持的目标语言

翻译模式差异

翻译参数

批量处理 (batch)

批量参数

模型查询 (models)

术语表管理 (term)

术语表子命令

CSV 导入格式

配置与输出设置

输出控制

使用配置文件

JSON 输出

退出码

常见问题排查

一键转存指南

Doc2X CLI 使用手册 ​

核心命令总览 ​

环境与安装 ​

前置条件 ​

安装 ​

鉴权与登录 ​

Client 模式（默认） ​

OAuth 模式 ​

全局参数 ​

快速开始 ​

文档解析 (parse) ​

解析参数 ​

文档翻译 (translate) ​

支持的目标语言 ​

翻译模式差异 ​

翻译参数 ​

批量处理 (batch) ​

批量参数 ​

模型查询 (models) ​

术语表管理 (term) ​

术语表子命令 ​

CSV 导入格式 ​

配置与输出设置 ​

输出控制 ​

使用配置文件 ​

JSON 输出 ​

退出码 ​

常见问题排查 ​

Doc2X CLI 使用手册

核心命令总览

环境与安装

前置条件

安装

鉴权与登录

Client 模式（默认）

OAuth 模式

全局参数

快速开始

文档解析 (parse)

解析参数

文档翻译 (translate)

支持的目标语言

翻译模式差异

翻译参数

批量处理 (batch)

批量参数

模型查询 (models)

术语表管理 (term)

术语表子命令

CSV 导入格式

配置与输出设置

输出控制

使用配置文件

JSON 输出

退出码

常见问题排查