Doc2X 文档

简体中文

English

简体中文

English

主题

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 MiB，图片最大支持 3 MiB
  • 支持的图片格式： png、jpg、jpeg、gif、bmp（不支持 webp、tiff、tif）

前置条件

本页按公开 npm 包 @noedgeai-org/doc2x-cli@0.2.0 核对（2026-10-05）。旧的 @noedgeai GitHub Packages 安装方式已不是本教程入口；无需为新 @noedgeai-org 包配置该 registry。升级后先检查 doc2x --version 与具体命令的 --help，不要执行网上来源不明的安装脚本。

安装

通过 npm 全局安装工具包：

bash
npm i -g @noedgeai-org/doc2x-cli@0.2.0

# 验证安装
doc2x --version

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

鉴权与登录

默认 --auth-mode auto：优先使用 doc2x login 保存的 CLI 登录，没有时才使用桌面客户端。显式参数优先于配置文件；OAuth 刷新失败不会偷偷切换为另一个桌面账号。CLI 使用个人账户，不接受开放平台 API Key 替代登录。

Client 模式（显式选择）

直接读取本地正在运行的 Doc2X 桌面客户端的登录状态。适用于个人开发机。确保桌面客户端已登录并保持运行状态后，可显式选择该模式：

bash
doc2x parse ./paper.pdf --auth-mode client

OAuth 模式

通过浏览器进行 OAuth 登录，无需安装桌面客户端。浏览器必须能访问运行 CLI 电脑的 localhost 随机回调端口；--no-browser 只打印登录链接，不是远程服务器的 device-code 登录。不要把本机 Token 复制到不受信任环境。

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>鉴权模式：auto、client 或 oauthauto
--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、pdfmd
--image-models <models...>图片 OCR 模型（doc2x 为必选）：doc2x mathpixdoc2x
--vision-models <models...>LLM 视觉模型（使用 doc2x models list 查询模型 ID）-
--image-hosting <mode>图片来源：local 或 onlinelocal
--formula-mode <mode>公式分隔符：normal 或 dollarnormal
--formula-level <level>公式降级级别：normal、onlyLine、processAllnormal
--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 文件进行翻译。目标语言默认 zh；建议每次显式传 --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 或 pdfmd
--target-language <lang>目标语言代码zh
--target-model <model>服务列表中的模型 ID 或名称可用时为 Free（10001）
--term-id "YOUR_TERM_ID"术语表 ID（通过 doc2x term list 获取）-
--font-color-extraction提取字体颜色false
--ignore-translate-types <list...>忽略的元素类型：table、code、figure、reference-
--convert-trans <t>仅流式输出；固定版 PDF 必须 both。输出内容：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 "YOUR_TERM_ID"
doc2x term import从 CSV 文件导入术语--term-id "YOUR_TERM_ID" --file <path>
bash
# 查询所有术语表
doc2x term list

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

# 查看术语表中的条目
doc2x term items --term-id "YOUR_TERM_ID"

# 从 CSV 文件导入术语
doc2x term import --term-id "YOUR_TERM_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: auto
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: "10001"
    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 登录失败确认浏览器能访问 CLI 所在电脑的 localhost 回调；--no-browser 只是打印链接，不提供异机免回调登录
目标文件未生成或无变化CLI 默认不覆盖已有文件。如果需强制更新输出结果，请在命令中添加 --overwrite 参数
图片上传被拒绝或失败检查图片格式与大小。当前限制单张图片最大 3 MiB，格式不支持 webp、tiff 或 tif，建议转换为 png 或 jpg
提示额度不足 / 模型需订阅检查账户剩余调用额度及订阅状态。部分特性（如启用 mathpix 模型）可能需要高级账户权限

先检查账户，再处理一个样本

bash
doc2x --version
doc2x login
doc2x account status --json
doc2x models list --json

确认鉴权账号、会员条件、共享解析页数和点数。null 表示未知，不是余额零；原始点数单位与显示点数不同（100 个记账单位对应 1 显示点），不是人民币。查询不会预留下一批任务额度。不要把网页登录、开放平台 Key 和 CLI OAuth 混用。

bash
doc2x parse ./paper.pdf --to md --out ./output --receipt ./paper-run.json --json

这一步会创建真实任务。命令完成后核对输出的 outputFiles、meta 和 receipt，打开实际文件；不要只看终端“完成”。MD/TEX/HTML 可能有配套图片，移动时一起保存。HTML 数学显示可依赖 MathJax 网络资源。

Word 模板与翻译输出选择

bash
# V3 流式 Word 模板
doc2x parse ./paper.pdf --to docx --docx-template academic --out ./word-output

# 可编辑的仅译文 Word，重新排版
doc2x translate ./paper.pdf --translate-type md --convert-trans translate --target-language en --to docx --docx-template technical --out ./translated-word

# 固定版双语 PDF，原文左、译文右
doc2x translate ./paper.pdf --translate-type pdf --target-language en --pdf-font-strategy page-optimal --out ./bilingual-pdf

--docx-template 可选 default/general/academic/business/elegant/minimal/technical，只用于 V3 Word 导出。--pdf-font-strategy 可选 global-consistent（默认）或 page-optimal，用于固定版翻译。固定版 PDF 的 --to docx/md/tex/html 与 --convert-trans origin/translate 组合会在上传前被拒绝；--to none 则处理但不导出。

CLI 的 --to pdf 普通解析输出是重新排版 PDF；不等于原页扫描文本层。网页的保版 Word/WPS、MathType、Typst、Excel、Eduediter 与图片翻译编辑不是当前 CLI 参数。Office 文件先另行转为 PDF，不把 .docx 改后缀当转换。

批量预览、回执与失败续查

bash
# 只列出将处理的文件，不提交解析
doc2x batch parse ./docs --glob "**/*.pdf" --dry-run --json

# 确认清单后才运行；按文件顺序处理
doc2x batch parse ./docs --glob "**/*.pdf" --to md --out ./batch-output --report ./batch-report.json --json

批量默认顺序处理，首个错误停止调度，除非显式 --continue-on-error。报告包含尚未处理数量；不要把未处理当失败或成功。已有输出可能被跳过；要覆盖前先核对路径与备份。

每次单文件尝试默认在输出目录 .doc2x-receipts/ 保存回执；--receipt 可为单次任务指定新文件，不能覆盖旧回执。回执中 taskIds、stages、status、outputFiles、artifacts 记录各阶段。--to none 是处理成功、导出跳过，不是未处理。Ctrl+C 或断电不保证远端取消。

以下 ID 为占位符，应使用自己回执中的真实 ID：

bash
doc2x records show --parse-id op_example --json
doc2x records show --translate-id ot_example --json
doc2x records list --kind translate --limit 20 --json
doc2x usage show --translate-id ot_example --json

records list 的 limit 按源文档计数；有 nextCursor 时用 --cursor 继续。它不是完整失败账本；状态 unknown 不等于任务失败。usage show 只读单任务已报告用量，reported_by_task 不证明最终结算或退款；空零值可能为 unconfirmed，解析消费为 not_provided。当前没有 usage list 消费历史命令，也没有通用恢复/重新导出命令；不要编造参数或为取结果直接重跑付费任务。

回执不包含访问 Token 或签名 URL，但含本地路径和任务元数据，分享前仍需检查。成功 JSON 写 stdout，失败 JSON 可在 stderr，并返回非零退出码。

模型详情与外部 Zotero 导入

bash
doc2x models show 10001 --json
doc2x models guide
doc2x zotero manifest --receipt ./paper-run.json --library-id 1 --item-key ABCD1234 --out ./zotero-import.json --json

模型来自当前服务列表；订阅要求不是完整价格表，未知上下文长度或价格保持 null。--vision-models 使用列表返回且当前账户可用的 ID/名称，不能假设每个翻译模型都保证图片增强质量；先核对适用标记和权限。

Zotero 示例中的 library/item key 必须来自自己的 Zotero 工具。该命令要求成功且含文件的回执，核对文件尺寸/hash并生成导入清单；不会写入 Zotero 文献库，输出 writtenToZotero: false。由适配的外部插件/MCP导入到正确父条目并去重，保留用户笔记与配套图片；导入失败先重试导入，不重复 Doc2X 处理。

版本来源