1. Dify 多语言 PDF 原格式翻译到底难在哪版式保留与链路拆解Dify 多语言 PDF 原格式翻译说白了就是让一份法语、德语或者日语的 PDF翻译成中文之后字体、图片位置、表格线、页眉页脚这些视觉元素基本不动只把文字换掉。这件事听起来简单做起来坑特别多。我一开始也以为丢给大模型直接翻译就行结果发现模型只能处理纯文本PDF 里的坐标、字体嵌入、图层信息它根本碰不到。真正要落地得把「解析版式 → 提取文本 → 翻译 → 回填版式 → 重新渲染」拆成一条可编排的链路而 Dify 的 Agent MCP 正好能把这条链路串起来。先说版式保留的难点。PDF 不是 Word它没有「段落」这种语义结构只有一堆带坐标的绘制指令。一个句子可能被拆成七八个文本块分别落在不同坐标上。如果你直接把提取出来的文本拼起来翻译再按原坐标塞回去中文长度和英文、法文差异很大很容易出现文字溢出、重叠、被裁切。所以翻译节点必须知道每个文本块的边界框翻译后还要做字号自适应或者换行重排。这就是为什么单纯靠大模型对话式翻译搞不定必须有一个专门处理 PDF 的 MCP Server 来承担版式计算。再说链路拆解。整条链路我实测下来分成五步第一步Agent 接收用户给的 PDF URL调用 MCP 工具下载文件第二步MCP Server 解析 PDF按页、按文本块提取内容和坐标同时识别哪些是扫描件需要走 OCR第三步把提取出的文本分批送给翻译模型这里要注意上下文长度和术语一致性第四步把译文按原坐标回填处理字体缺失和换行第五步生成双语对照版和单语版两个 PDF返回下载链接。Dify 的 Agent 负责调度这些工具MCP 负责具体执行TaoToken 统一 Key 负责让翻译模型调用稳定、可计费、可切换。适合谁看这篇如果你正在用 Dify 1.6 做文档处理类应用或者手头有大量多语言 PDF 需要批量翻译又不想每个模型单独配 Key、单独对账那这套方案就是给你准备的。下面我会把 Dify DSL 配置、TaoToken 统一 Key 接入、MCP 工具挂载、验证请求和常见报错排查全部写清楚你可以直接照着复现。2. TaoToken 统一 Key 前置准备一个 Key 打通 MCP 与 Agent 的模型调用在动手配 Dify 之前先把模型调用的入口统一掉。为什么要用 TaoToken因为这条翻译链路里Agent 的对话模型、翻译节点用的模型、可能还有 OCR 后的润色模型如果每个都去单独申请 Key、单独配 Base URL后期换模型或者做成本核算会非常痛苦。TaoToken 提供的是 OpenAI 兼容接口一个 Key 可以调用多个主流模型Base URL 统一计费也统一特别适合 Dify 这种需要多节点调模型的场景。先拿 Key。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台在 API Keys 页面创建一个新 Key。建议给这个 Key 起个名字叫 dify-pdf-translate方便后面在 Dify 里识别。创建完复制出来只显示一次丢了就得重建。控制台地址是 https://taotoken.net/console API Keys 页面是 https://taotoken.net/api-keys 这两个 deep link 你收藏一下后面配 Dify 和排障都要用。拿到 Key 之后记下两个核心参数Base URL 填 https://taotoken.net/api 注意这里不加任何 UTM 参数就是纯 API 地址Model ID 根据你翻译任务选一般对话和调度用 claude-sonnet 或者 gpt-4o 这类翻译节点可以用更便宜的模型具体模型列表在文档里查。文档地址 https://taotoken.net/doc 里面有每个模型的上下文长度和计费说明。如果你后面要做长期编码或者 Agent 自动化可以看看 Coding Plan https://taotoken.net/coding-plan 那个套餐对高频调用更划算。在 Dify 里配置模型供应商。进入 Dify 设置 → 模型供应商 → 添加 OpenAI-API-compatible名称填 TaoTokenAPI Key 填刚才复制的Base URL 填 https://taotoken.net/api 模型名称手动填你要用的 Model ID。保存后测试连接如果返回成功说明 Key 和地址都没问题。这一步做完你后面在 Agent 节点、翻译节点、甚至 MCP 内部调用模型时都可以复用这个供应商不用再重复配 Key。这里有个细节要注意Dify 的 MCP 工具如果内部也要调模型它走的是 MCP Server 自己的配置不一定复用 Dify 的模型供应商。所以你要么在 MCP Server 的环境变量里也配上 TaoToken 的 Base URL 和 Key要么让 MCP 只做版式处理翻译动作回到 Dify 的 Agent 节点里做。我实测下来后者更好控制成本因为 Dify 的日志能看到每次调用的 token 消耗方便对账。如果你想让 MCP 内部也统一走 TaoToken就在 MCP Server 启动参数里加 OPENAI_BASE_URLhttps://taotoken.net/api 和 OPENAI_API_KEY你的Key这样 MCP 里所有模型调用也走同一个入口。还有一点TaoToken 的模型对话功能可以单独用来验证 Key 是否正常。打开 https://taotoken.net/chat 选一个模型随便发一句话如果能正常回复说明 Key 有效、余额充足。这个页面在排障时特别有用因为 Dify 报错有时候是 Dify 配置问题有时候是 Key 问题先用模型对话验证一下能快速定位是哪一层出了毛病。3. 可复制配置Dify DSL、MCP 挂载与 TaoToken 参数片段这一节直接给可复制的配置。先配 MCP。打开 Dify 工作流工作台点击工具按钮选择 MCP然后添加基于 HTTP 服务的 MCP。如果你用的是 SSE 方式URL 填你的 MCP Server 地址比如 https://pdftranslate2.duckcloud.fun/sse 认证方式选无或者按你的服务要求填。配置完成后点右上角授权如果成功你能看到这个 MCP 暴露出来的工具列表一般有 9 个左右包括下载 PDF、解析版式、翻译、生成双语、查询状态、获取下载链接等。接下来是 Dify DSL 的关键片段。Dify 的 DSL 是 YAML 格式你可以直接导入或者对照修改。下面这段是 Agent 节点的核心配置注意 model 部分引用的是 TaoToken 供应商tools 部分挂载 MCPapp: name: pdf-translate-agent mode: agent-chat model: provider: openai-api-compatible name: claude-sonnet base_url: https://taotoken.net/api api_key: sk-你的TaoTokenKey tools: - type: mcp provider: pdftranslate-mcp-server tools: - download_pdf - parse_layout - translate_blocks - render_bilingual - render_mono - get_status - get_download_url prompt: | 你是一个 PDF 翻译助手。用户会给你一个 PDF 链接和目标语言。 请按以下步骤操作 1. 调用 download_pdf 下载文件 2. 调用 parse_layout 解析版式和文本块 3. 调用 translate_blocks 翻译文本目标语言从用户输入提取 4. 调用 render_bilingual 和 render_mono 生成两个 PDF 5. 轮询 get_status 直到完成然后调用 get_download_url 返回链接 如果用户只要单语版只调用 render_mono。如果你用的是 Cline MCP 或者 Claude Code 这类客户端配置方式类似核心三件套是 Base URL、Key、Model ID。以 Cline 的 MCP 配置为例在 settings.json 里加{ mcpServers: { pdftranslate: { url: https://pdftranslate2.duckcloud.fun/sse, transport: sse } }, openai: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet } }Codex 的 auth.json 配置也类似把 base_url 和 api_key 换成 TaoToken 的即可。注意 Codex 的 auth.json 路径一般在 ~/.codex/auth.json内容格式{ openai_api_key: sk-你的TaoTokenKey, openai_base_url: https://taotoken.net/api }Dify 的 MCP 配置界面里如果你要填 JSON 格式的工具描述可以参考下面这段这是 MCP Server 暴露的工具 schema 简化版{ tools: [ { name: download_pdf, description: 下载 PDF 文件到 MCP Server 本地, parameters: { type: object, properties: { url: {type: string, description: PDF 文件 URL} }, required: [url] } }, { name: translate_blocks, description: 翻译解析出的文本块, parameters: { type: object, properties: { blocks: {type: array}, target_lang: {type: string} }, required: [blocks, target_lang] } } ] }配完这些你的 Dify Agent 就具备了调用 MCP 的能力同时模型调用走 TaoToken 统一 Key。这里再强调一下三件套Base URL 是 https://taotoken.net/api Key 是你控制台创建的Model ID 按需选。这三个参数在 Dify、Cline、Codex 里都要保持一致否则会出现 401 或者模型找不到的报错。4. 验证请求与成功结果从 PDF URL 到双语对照文档配置完成后点 Dify 工作流左上角发布然后进入 Agent 对话页面测试。输入下面这句话请把这个文件翻译一下文件 URL 地址 https://music-1258720957.cos.ap-nanjing.myqcloud.com/11.pdfAgent 会开始调用 MCP 工具。第一步 download_pdf你会在 Dify 的日志里看到工具调用记录。第二步 parse_layout这一步耗时取决于 PDF 页数和复杂度一般几页的文档十几秒几十页的可能要一两分钟。第三步 translate_blocks这里会调用翻译模型如果你在 MCP 内部配了 TaoToken日志里能看到模型调用如果翻译在 Dify 节点做就在 Dify 的模型日志里看。第四步 render_bilingual 和 render_mono生成两个 PDF。第五步 get_status 轮询直到状态变成 completed然后 get_download_url 返回链接。成功的结果是这样的Agent 返回两个下载链接一个是双语对照版左边原文右边译文一个是单语版只有译文。你点开链接下载用 PDF 阅读器打开对比原文和译文。重点检查几个地方页眉页脚是否保留、表格线是否错位、图片位置是否偏移、中文是否溢出文本框、字体是否变成默认字体导致排版变化。我实测下来只要 MCP Server 的版式回填逻辑没问题视觉上基本和原文一致只有文字内容变了。如果你发现 Agent 返回不了下载链接或者一直卡在轮询状态可以补一句请把刚才翻译后的 PDF 下载链接地址发给我让模型继续调用 get_download_url直到返回成功。有时候 MCP Server 处理大文件需要几分钟Agent 的轮询次数有限手动催一下就能拿到结果。另外你也可以在后端 MCP 服务的日志里看到请求记录确认每一步是否执行成功。如果 MCP 日志显示 translate_blocks 报错多半是模型调用失败检查 TaoToken 的 Key 和余额如果 render 报错多半是字体缺失或者坐标计算问题需要检查 MCP Server 的依赖。验证模型是否正常可以打开 TaoToken 的模型对话页面 https://taotoken.net/chat 选同一个 Model ID发一段 PDF 里提取的文本看翻译质量是否符合预期。这一步能帮你区分是 MCP 版式问题还是模型翻译问题。如果模型对话正常但 Dify 里报错那就是 Dify 配置或者 MCP 连接的问题如果模型对话也报错那就是 Key 或者余额的问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障这一节我按真实报错来写你遇到对应错误直接对照。401 Unauthorized。这个最常见说明 Key 无效或者没带上。检查三处Dify 模型供应商里的 API Key 是否填了 TaoToken 的 KeyMCP Server 环境变量里的 OPENAI_API_KEY 是否一致Cline 或 Codex 的配置文件里 api_key 是否正确。如果 Key 是对的检查 Base URL 是否写成了 https://taotoken.net/api 不要多加斜杠或者路径。还有一种情况是 Key 被删了或者余额不足去控制台 https://taotoken.net/api-keys 确认 Key 状态去 https://taotoken.net/console 看余额。local proxy failed。这个报错通常出现在 Dify 调用 MCP 或者调用模型时网络层没通。先确认 MCP Server 的 URL 是否可访问用 curl 测一下curl -v https://pdftranslate2.duckcloud.fun/sse 。如果返回 200 或者 event stream 相关头说明 MCP 服务正常。如果超时检查 Dify 所在服务器是否能出网以及 MCP Server 是否限制了来源 IP。模型调用侧的 local proxy failed多半是 Base URL 写错或者 DNS 解析问题把 https://taotoken.net/api 在浏览器里打开看是否返回正常 JSON 错误信息能打开说明网络通。reading choices 报错。这个一般出现在模型返回格式不符合预期时Dify 解析响应失败。原因可能是 Model ID 填错了比如填了一个不存在的模型名TaoToken 返回了错误结构Dify 按正常结构解析就报 reading choices。解决办法去文档 https://taotoken.net/doc 确认 Model ID 拼写然后在模型对话页面 https://taotoken.net/chat 用同一个 Model ID 发一句话确认能正常返回 choices 结构。如果模型对话正常但 Dify 报错检查 Dify 的模型供应商配置里模型名称是否有多余空格。OAuth 相关报错。如果你在 Dify 的 MCP 配置里选了 OAuth 认证但 MCP Server 实际不需要 OAuth就会报授权失败。解决办法把认证方式改成无或者 API Key重新授权。如果 MCP Server 确实需要 OAuth检查 client_id 和 client_secret 是否正确回调地址是否在 MCP Server 的白名单里。我实测下来自建的 PDF 翻译 MCP 一般用无认证或者简单 Bearer Token 就够了OAuth 反而增加复杂度。还有一个容易忽略的错MCP 工具列表为空。授权成功后看不到工具说明 MCP Server 的 SSE 连接建立了但工具注册失败。检查 MCP Server 日志看是否有工具注册报错。如果是 Dify 1.6 版本确认 MCP 功能已开启有些版本需要手动在环境变量里打开 FEATURE_MCPtrue。另外MCP Server 的 SSE 地址末尾不要多加斜杠有些实现对路径敏感。6. 长期编码与 Agent 链路把 TaoToken 统一 Key 用到位这条 PDF 翻译链路跑通之后你会发现它不只是一个翻译工具而是一个可复用的 Agent 编排模板。Dify 负责调度和对话MCP 负责具体能力TaoToken 负责模型调用统一入口。后面你要加新的文档格式比如 Word、PPT只需要在 MCP Server 里加对应的解析和渲染工具Dify 的 Agent 配置基本不用大改。你要换翻译模型也只需要在 TaoToken 控制台换 Model ID不用每个节点重新配 Key。如果你打算把这条链路做成长期运行的服务比如批量翻译、定时任务、或者对外提供 API建议看看 TaoToken 的 Coding Plan https://taotoken.net/coding-plan 那个套餐对高频调用更友好而且支持多模型切换适合 Agent 这种需要反复调模型的场景。接入文档在 https://taotoken.net/doc 里面有详细的 Base URL、认证方式、模型列表和计费说明配 Dify、Cline、Codex 都够用。最后给一个实用技巧在 Dify 的 Agent 提示词里把「如果翻译失败重试一次并检查 MCP 状态」写进去能减少手动催下载链接的次数。另外MCP Server 的日志一定要开每次翻译请求的输入输出都记下来方便对比版式回填效果。我踩过的坑是一开始没开日志翻译出来文字重叠根本不知道是解析坐标错了还是回填字号错了后来加了日志才定位到是字体缺失导致换行计算偏差。你把日志开起来后面调版式会快很多。
Dify 多语言 PDF 原格式翻译实战：用 TaoToken 统一 Key 打通 MCP 与 Agent 链路
1. Dify 多语言 PDF 原格式翻译到底难在哪版式保留与链路拆解Dify 多语言 PDF 原格式翻译说白了就是让一份法语、德语或者日语的 PDF翻译成中文之后字体、图片位置、表格线、页眉页脚这些视觉元素基本不动只把文字换掉。这件事听起来简单做起来坑特别多。我一开始也以为丢给大模型直接翻译就行结果发现模型只能处理纯文本PDF 里的坐标、字体嵌入、图层信息它根本碰不到。真正要落地得把「解析版式 → 提取文本 → 翻译 → 回填版式 → 重新渲染」拆成一条可编排的链路而 Dify 的 Agent MCP 正好能把这条链路串起来。先说版式保留的难点。PDF 不是 Word它没有「段落」这种语义结构只有一堆带坐标的绘制指令。一个句子可能被拆成七八个文本块分别落在不同坐标上。如果你直接把提取出来的文本拼起来翻译再按原坐标塞回去中文长度和英文、法文差异很大很容易出现文字溢出、重叠、被裁切。所以翻译节点必须知道每个文本块的边界框翻译后还要做字号自适应或者换行重排。这就是为什么单纯靠大模型对话式翻译搞不定必须有一个专门处理 PDF 的 MCP Server 来承担版式计算。再说链路拆解。整条链路我实测下来分成五步第一步Agent 接收用户给的 PDF URL调用 MCP 工具下载文件第二步MCP Server 解析 PDF按页、按文本块提取内容和坐标同时识别哪些是扫描件需要走 OCR第三步把提取出的文本分批送给翻译模型这里要注意上下文长度和术语一致性第四步把译文按原坐标回填处理字体缺失和换行第五步生成双语对照版和单语版两个 PDF返回下载链接。Dify 的 Agent 负责调度这些工具MCP 负责具体执行TaoToken 统一 Key 负责让翻译模型调用稳定、可计费、可切换。适合谁看这篇如果你正在用 Dify 1.6 做文档处理类应用或者手头有大量多语言 PDF 需要批量翻译又不想每个模型单独配 Key、单独对账那这套方案就是给你准备的。下面我会把 Dify DSL 配置、TaoToken 统一 Key 接入、MCP 工具挂载、验证请求和常见报错排查全部写清楚你可以直接照着复现。2. TaoToken 统一 Key 前置准备一个 Key 打通 MCP 与 Agent 的模型调用在动手配 Dify 之前先把模型调用的入口统一掉。为什么要用 TaoToken因为这条翻译链路里Agent 的对话模型、翻译节点用的模型、可能还有 OCR 后的润色模型如果每个都去单独申请 Key、单独配 Base URL后期换模型或者做成本核算会非常痛苦。TaoToken 提供的是 OpenAI 兼容接口一个 Key 可以调用多个主流模型Base URL 统一计费也统一特别适合 Dify 这种需要多节点调模型的场景。先拿 Key。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台在 API Keys 页面创建一个新 Key。建议给这个 Key 起个名字叫 dify-pdf-translate方便后面在 Dify 里识别。创建完复制出来只显示一次丢了就得重建。控制台地址是 https://taotoken.net/console API Keys 页面是 https://taotoken.net/api-keys 这两个 deep link 你收藏一下后面配 Dify 和排障都要用。拿到 Key 之后记下两个核心参数Base URL 填 https://taotoken.net/api 注意这里不加任何 UTM 参数就是纯 API 地址Model ID 根据你翻译任务选一般对话和调度用 claude-sonnet 或者 gpt-4o 这类翻译节点可以用更便宜的模型具体模型列表在文档里查。文档地址 https://taotoken.net/doc 里面有每个模型的上下文长度和计费说明。如果你后面要做长期编码或者 Agent 自动化可以看看 Coding Plan https://taotoken.net/coding-plan 那个套餐对高频调用更划算。在 Dify 里配置模型供应商。进入 Dify 设置 → 模型供应商 → 添加 OpenAI-API-compatible名称填 TaoTokenAPI Key 填刚才复制的Base URL 填 https://taotoken.net/api 模型名称手动填你要用的 Model ID。保存后测试连接如果返回成功说明 Key 和地址都没问题。这一步做完你后面在 Agent 节点、翻译节点、甚至 MCP 内部调用模型时都可以复用这个供应商不用再重复配 Key。这里有个细节要注意Dify 的 MCP 工具如果内部也要调模型它走的是 MCP Server 自己的配置不一定复用 Dify 的模型供应商。所以你要么在 MCP Server 的环境变量里也配上 TaoToken 的 Base URL 和 Key要么让 MCP 只做版式处理翻译动作回到 Dify 的 Agent 节点里做。我实测下来后者更好控制成本因为 Dify 的日志能看到每次调用的 token 消耗方便对账。如果你想让 MCP 内部也统一走 TaoToken就在 MCP Server 启动参数里加 OPENAI_BASE_URLhttps://taotoken.net/api 和 OPENAI_API_KEY你的Key这样 MCP 里所有模型调用也走同一个入口。还有一点TaoToken 的模型对话功能可以单独用来验证 Key 是否正常。打开 https://taotoken.net/chat 选一个模型随便发一句话如果能正常回复说明 Key 有效、余额充足。这个页面在排障时特别有用因为 Dify 报错有时候是 Dify 配置问题有时候是 Key 问题先用模型对话验证一下能快速定位是哪一层出了毛病。3. 可复制配置Dify DSL、MCP 挂载与 TaoToken 参数片段这一节直接给可复制的配置。先配 MCP。打开 Dify 工作流工作台点击工具按钮选择 MCP然后添加基于 HTTP 服务的 MCP。如果你用的是 SSE 方式URL 填你的 MCP Server 地址比如 https://pdftranslate2.duckcloud.fun/sse 认证方式选无或者按你的服务要求填。配置完成后点右上角授权如果成功你能看到这个 MCP 暴露出来的工具列表一般有 9 个左右包括下载 PDF、解析版式、翻译、生成双语、查询状态、获取下载链接等。接下来是 Dify DSL 的关键片段。Dify 的 DSL 是 YAML 格式你可以直接导入或者对照修改。下面这段是 Agent 节点的核心配置注意 model 部分引用的是 TaoToken 供应商tools 部分挂载 MCPapp: name: pdf-translate-agent mode: agent-chat model: provider: openai-api-compatible name: claude-sonnet base_url: https://taotoken.net/api api_key: sk-你的TaoTokenKey tools: - type: mcp provider: pdftranslate-mcp-server tools: - download_pdf - parse_layout - translate_blocks - render_bilingual - render_mono - get_status - get_download_url prompt: | 你是一个 PDF 翻译助手。用户会给你一个 PDF 链接和目标语言。 请按以下步骤操作 1. 调用 download_pdf 下载文件 2. 调用 parse_layout 解析版式和文本块 3. 调用 translate_blocks 翻译文本目标语言从用户输入提取 4. 调用 render_bilingual 和 render_mono 生成两个 PDF 5. 轮询 get_status 直到完成然后调用 get_download_url 返回链接 如果用户只要单语版只调用 render_mono。如果你用的是 Cline MCP 或者 Claude Code 这类客户端配置方式类似核心三件套是 Base URL、Key、Model ID。以 Cline 的 MCP 配置为例在 settings.json 里加{ mcpServers: { pdftranslate: { url: https://pdftranslate2.duckcloud.fun/sse, transport: sse } }, openai: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet } }Codex 的 auth.json 配置也类似把 base_url 和 api_key 换成 TaoToken 的即可。注意 Codex 的 auth.json 路径一般在 ~/.codex/auth.json内容格式{ openai_api_key: sk-你的TaoTokenKey, openai_base_url: https://taotoken.net/api }Dify 的 MCP 配置界面里如果你要填 JSON 格式的工具描述可以参考下面这段这是 MCP Server 暴露的工具 schema 简化版{ tools: [ { name: download_pdf, description: 下载 PDF 文件到 MCP Server 本地, parameters: { type: object, properties: { url: {type: string, description: PDF 文件 URL} }, required: [url] } }, { name: translate_blocks, description: 翻译解析出的文本块, parameters: { type: object, properties: { blocks: {type: array}, target_lang: {type: string} }, required: [blocks, target_lang] } } ] }配完这些你的 Dify Agent 就具备了调用 MCP 的能力同时模型调用走 TaoToken 统一 Key。这里再强调一下三件套Base URL 是 https://taotoken.net/api Key 是你控制台创建的Model ID 按需选。这三个参数在 Dify、Cline、Codex 里都要保持一致否则会出现 401 或者模型找不到的报错。4. 验证请求与成功结果从 PDF URL 到双语对照文档配置完成后点 Dify 工作流左上角发布然后进入 Agent 对话页面测试。输入下面这句话请把这个文件翻译一下文件 URL 地址 https://music-1258720957.cos.ap-nanjing.myqcloud.com/11.pdfAgent 会开始调用 MCP 工具。第一步 download_pdf你会在 Dify 的日志里看到工具调用记录。第二步 parse_layout这一步耗时取决于 PDF 页数和复杂度一般几页的文档十几秒几十页的可能要一两分钟。第三步 translate_blocks这里会调用翻译模型如果你在 MCP 内部配了 TaoToken日志里能看到模型调用如果翻译在 Dify 节点做就在 Dify 的模型日志里看。第四步 render_bilingual 和 render_mono生成两个 PDF。第五步 get_status 轮询直到状态变成 completed然后 get_download_url 返回链接。成功的结果是这样的Agent 返回两个下载链接一个是双语对照版左边原文右边译文一个是单语版只有译文。你点开链接下载用 PDF 阅读器打开对比原文和译文。重点检查几个地方页眉页脚是否保留、表格线是否错位、图片位置是否偏移、中文是否溢出文本框、字体是否变成默认字体导致排版变化。我实测下来只要 MCP Server 的版式回填逻辑没问题视觉上基本和原文一致只有文字内容变了。如果你发现 Agent 返回不了下载链接或者一直卡在轮询状态可以补一句请把刚才翻译后的 PDF 下载链接地址发给我让模型继续调用 get_download_url直到返回成功。有时候 MCP Server 处理大文件需要几分钟Agent 的轮询次数有限手动催一下就能拿到结果。另外你也可以在后端 MCP 服务的日志里看到请求记录确认每一步是否执行成功。如果 MCP 日志显示 translate_blocks 报错多半是模型调用失败检查 TaoToken 的 Key 和余额如果 render 报错多半是字体缺失或者坐标计算问题需要检查 MCP Server 的依赖。验证模型是否正常可以打开 TaoToken 的模型对话页面 https://taotoken.net/chat 选同一个 Model ID发一段 PDF 里提取的文本看翻译质量是否符合预期。这一步能帮你区分是 MCP 版式问题还是模型翻译问题。如果模型对话正常但 Dify 里报错那就是 Dify 配置或者 MCP 连接的问题如果模型对话也报错那就是 Key 或者余额的问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障这一节我按真实报错来写你遇到对应错误直接对照。401 Unauthorized。这个最常见说明 Key 无效或者没带上。检查三处Dify 模型供应商里的 API Key 是否填了 TaoToken 的 KeyMCP Server 环境变量里的 OPENAI_API_KEY 是否一致Cline 或 Codex 的配置文件里 api_key 是否正确。如果 Key 是对的检查 Base URL 是否写成了 https://taotoken.net/api 不要多加斜杠或者路径。还有一种情况是 Key 被删了或者余额不足去控制台 https://taotoken.net/api-keys 确认 Key 状态去 https://taotoken.net/console 看余额。local proxy failed。这个报错通常出现在 Dify 调用 MCP 或者调用模型时网络层没通。先确认 MCP Server 的 URL 是否可访问用 curl 测一下curl -v https://pdftranslate2.duckcloud.fun/sse 。如果返回 200 或者 event stream 相关头说明 MCP 服务正常。如果超时检查 Dify 所在服务器是否能出网以及 MCP Server 是否限制了来源 IP。模型调用侧的 local proxy failed多半是 Base URL 写错或者 DNS 解析问题把 https://taotoken.net/api 在浏览器里打开看是否返回正常 JSON 错误信息能打开说明网络通。reading choices 报错。这个一般出现在模型返回格式不符合预期时Dify 解析响应失败。原因可能是 Model ID 填错了比如填了一个不存在的模型名TaoToken 返回了错误结构Dify 按正常结构解析就报 reading choices。解决办法去文档 https://taotoken.net/doc 确认 Model ID 拼写然后在模型对话页面 https://taotoken.net/chat 用同一个 Model ID 发一句话确认能正常返回 choices 结构。如果模型对话正常但 Dify 报错检查 Dify 的模型供应商配置里模型名称是否有多余空格。OAuth 相关报错。如果你在 Dify 的 MCP 配置里选了 OAuth 认证但 MCP Server 实际不需要 OAuth就会报授权失败。解决办法把认证方式改成无或者 API Key重新授权。如果 MCP Server 确实需要 OAuth检查 client_id 和 client_secret 是否正确回调地址是否在 MCP Server 的白名单里。我实测下来自建的 PDF 翻译 MCP 一般用无认证或者简单 Bearer Token 就够了OAuth 反而增加复杂度。还有一个容易忽略的错MCP 工具列表为空。授权成功后看不到工具说明 MCP Server 的 SSE 连接建立了但工具注册失败。检查 MCP Server 日志看是否有工具注册报错。如果是 Dify 1.6 版本确认 MCP 功能已开启有些版本需要手动在环境变量里打开 FEATURE_MCPtrue。另外MCP Server 的 SSE 地址末尾不要多加斜杠有些实现对路径敏感。6. 长期编码与 Agent 链路把 TaoToken 统一 Key 用到位这条 PDF 翻译链路跑通之后你会发现它不只是一个翻译工具而是一个可复用的 Agent 编排模板。Dify 负责调度和对话MCP 负责具体能力TaoToken 负责模型调用统一入口。后面你要加新的文档格式比如 Word、PPT只需要在 MCP Server 里加对应的解析和渲染工具Dify 的 Agent 配置基本不用大改。你要换翻译模型也只需要在 TaoToken 控制台换 Model ID不用每个节点重新配 Key。如果你打算把这条链路做成长期运行的服务比如批量翻译、定时任务、或者对外提供 API建议看看 TaoToken 的 Coding Plan https://taotoken.net/coding-plan 那个套餐对高频调用更友好而且支持多模型切换适合 Agent 这种需要反复调模型的场景。接入文档在 https://taotoken.net/doc 里面有详细的 Base URL、认证方式、模型列表和计费说明配 Dify、Cline、Codex 都够用。最后给一个实用技巧在 Dify 的 Agent 提示词里把「如果翻译失败重试一次并检查 MCP 状态」写进去能减少手动催下载链接的次数。另外MCP Server 的日志一定要开每次翻译请求的输入输出都记下来方便对比版式回填效果。我踩过的坑是一开始没开日志翻译出来文字重叠根本不知道是解析坐标错了还是回填字号错了后来加了日志才定位到是字体缺失导致换行计算偏差。你把日志开起来后面调版式会快很多。