Codex 负责协作，翻译排版大师负责文档处理
本地桥接读取 Codex 发出的 JSON-RPC 消息，附加 Bearer API Key 后转发到线上 MCP 地址。文档翻译仍是异步任务：先创建任务并保存 task_id，再轮询到 SUCCESS 或 FAILED。
为 Codex 单独创建 Key，不要把它放进提示词、截图、项目文件或共享配置。
运行已验证的安装脚本，或使用 Node.js 18 及以上版本手动注册 stdio 桥接。
先确认 MCP 注册、共享 credits 账户和当前计费规则，再创建付费任务。
提交一份代表性本地文档，保存 task_id，并持续查询到 SUCCESS 或 FAILED。
准备 Codex、Node.js 和专用 API Key
建议给每个客户端创建独立 Key，后续撤销时不会影响其他接入。
- 安装 Codex，并确认终端中可以执行 codex 命令。
- 安装 Node.js 18 或更高版本。本地桥接使用 Node 内置 fetch，不会给业务项目增加依赖。
- 在开发者中心创建专用 API Key。完整 Key 只在创建时展示一次。
- 准备一份不超过 20 MB 的代表性 PDF、DOCX、PPTX 或 XLSX。更大的文件请改用 REST API 上传。
根据系统运行已验证的安装命令
脚本会从固定的翻译排版大师域名下载桥接、使用 MCP 地址验证 API Key、替换 Codex 中名为 fanyipaiban 的旧配置，并提示你重启 Codex。
$installerUrl = "https://www.fanyipaiban.com/poly/fanyipaiban-mcp-install.ps1"
$installer = Invoke-RestMethod $installerUrl
if ($installer -notmatch "(?m)^# FANYIPAIBAN_MCP_INSTALLER$") {
throw "Installer file is unavailable. Use the manual setup below."
}
& ([ScriptBlock]::Create($installer))installer=$(mktemp)
curl -fsSL https://www.fanyipaiban.com/poly/fanyipaiban-mcp-install.sh -o "$installer"
grep -q "^# FANYIPAIBAN_MCP_INSTALLER$" "$installer" || {
echo "Installer unavailable. Use manual setup below."
rm -f "$installer"
exit 1
}
bash "$installer"; rm -f "$installer"手动配置 Codex
安装脚本最终注册的是下面这条本地 stdio 命令。请先下载桥接、创建 mcp.json，再把示例中的路径替换为当前电脑上的绝对路径。
# Download the bridge to ~/.fanyipaiban/fanyipaiban-mcp-proxy.mjs
# Create ~/.fanyipaiban/mcp.json with: {"apiKey":"YOUR_API_KEY"}
[mcp_servers.fanyipaiban]
command = "node"
args = [
"FULL_PATH/.fanyipaiban/fanyipaiban-mcp-proxy.mjs",
"--config",
"FULL_PATH/.fanyipaiban/mcp.json"
]先查询账户和计费，不要一上来就创建付费任务
重启 Codex 并新建任务，先执行两个只读调用，确认服务、API Key 和当前计费规则均可正常读取。
codex mcp list本次只使用翻译排版大师 MCP 做只读检查：
1. 调用 translation_get_account，概括账户字段，不要暴露任何密钥。
2. 调用 translation_get_pricing，告诉我当前每计费页 credits，以及 PDF、DOCX、PPTX、XLSX 分别按什么计费。
3. 不要创建翻译任务，也不要修改任何本地文件。给 Codex 一条边界明确、可核对的任务提示词
明确文件、目标语言、轮询终止条件和结果保存位置，同时要求保留原文件。
请使用翻译排版大师 MCP，把当前工作区的 ./manual.pdf 翻译为中文。
要求：
1. 先确认文件存在且不超过 20 MB；如果更大，停止任务并建议改用 REST API。
2. 调用 translation_create_document_task，设置 source_lang=auto、target_lang=cn，并为本次操作使用稳定的 request_id。
3. 保存返回的 task_id；每 3 至 5 秒调用 translation_get_task，直到状态为 SUCCESS 或 FAILED。
4. SUCCESS 后，如果当前环境允许下载，把结果保存为 ./outputs/manual-zh.pdf；否则返回短时有效的 download_url。
5. 告诉我 estimated credits 和 charged credits，不要覆盖原文件。
6. 提醒我在交付前复核扫描识别、表格、示意图和业务关键数值。当前线上实际开放 4 个 MCP 工具
下面的列表已通过生产环境 tools/list 响应核验。本地新版代码中的 PDF 工具和图片翻译尚未出现在生产 MCP，因此本页暂不宣传。
translation_get_account读取共享账户的可用、冻结、已使用和累计充值 credits。translation_get_pricing读取当前每计费页价格，以及 PDF、DOCX、PPTX、XLSX 的计费单位。translation_create_document_task创建异步文档翻译任务。必填 file_name、file_base64、target_lang；source_lang、parse_engine、request_id 可选。translation_get_task按 task_id 查询状态、进度、credits 和短时有效的结果地址，直到 SUCCESS 或 FAILED。AI 工作区使用 MCP，系统集成使用 REST API
MCP 与 REST API 调用的是同一套文档翻译能力，但适合的工作场景不同。
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 在 Codex 中处理一份或几份本地文件 | MCP | Codex 可以读取工作区文件、创建任务，并在同一任务中持续查询结果。 |
| 后台系统、RPA、队列或批量流程 | REST API | 业务系统可控制 multipart 上传、Idempotency-Key、重试、日志和结果归档。 |
| 本地文件超过 20 MB | REST API | 生产环境 MCP 的单份文档载荷上限为 20 MB。 |
| 开发前先查看实际翻译效果 | 网页工作台 | 先用代表性样例检查翻译与排版，再决定是否自动化。 |
把本地 Key 文件和结果地址都当作敏感信息
桥接可以避免把 Key 写入提示词和项目代码，但凭据仍需按正常密钥规范管理。
- 安装器会把 API Key 以明文 JSON 保存在当前用户目录。请限制该系统账户的访问权限，不要把目录加入共享网盘或公共备份。
- 每个客户端使用独立 Key。设备、截图、终端日志或配置文件泄露时，应立即在开发者中心撤销并重建。
- 根据工作区和沙箱设置，Codex 读取本地文件、访问网络或写入下载结果时可能需要你确认权限。
- 任务结果地址短时有效。确认结果后及时保存，并保留原文用于对照与复核。
- 翻译和版式保留不保证绝对完美。扫描件、公式、表格、示意图和业务关键数值必须在交付前检查。
按注册、会话、凭据、文件和账户逐层检查
不要一出现问题就重复创建任务，先定位失败发生在哪一层。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| codex mcp list 中没有 fanyipaiban | 安装器未完成，或终端找不到 codex。 | 修复 Codex 命令后重新运行安装器，确认列表出现条目再重启。 |
| 已有 MCP 条目，但 Codex 看不到翻译工具 | 当前任务创建于配置更新之前。 | 重启 Codex，并新建一个任务。 |
| Invalid API key 或 HTTP 401 | Key 输入错误、已撤销或已失效。 | 新建专用 Key，并重新运行安装器。 |
| 文件在创建任务前被拒绝 | 格式不支持、载荷无效，或文件超过 20 MB。 | 使用 PDF、DOCX、PPTX、XLSX；大文件切换 REST API。 |
| 任务长时间处于 QUEUED 或 RUNNING | 文档处理是异步任务。 | 继续使用同一个 task_id 适度轮询，不要重复创建任务。 |
| INSUFFICIENT_CREDITS | 共享 credits 不足以覆盖预估任务。 | 给同一账户充值，然后创建新请求。 |
正式用于日常工作前需要确认的问题
当前生产环境 MCP 实际有哪些工具？
目前线上开放 translation_get_account、translation_get_pricing、translation_create_document_task 和 translation_get_task。本页不会提前宣传只存在于本地新版代码中的工具。
安装器把 API Key 保存在哪里？
安装器在输入时隐藏 Key，随后将它以明文 JSON 保存到当前用户的 ~/.fanyipaiban/mcp.json。请保护该目录、使用独立 Key，并在设备或文件泄露时立即撤销。
MCP 可以翻译超过 20 MB 的本地文件吗？
不可以。当前生产环境 MCP 的单份文档载荷上限为 20 MB，更大的文件应使用公开 REST API 的 multipart 上传流程。
MCP 会使用独立的 credits 余额吗？
不会。MCP、REST API 与网页工作台共用同一个账户余额；文档翻译当前按 1,500 credits / 计费页收费。
Codex 是否需要读取本地文档的权限？
需要。Codex 必须先读取工作区中选定的文件，才能把文件内容交给 MCP 工具。根据工作区和沙箱设置，它可能会请求读取文件、访问网络或保存结果的权限。
翻译完成后可以不复核直接交付吗？
不建议。扫描识别、公式、表格、示意图、数字、术语和版式都应在交付前检查，源文件质量和文档复杂度会影响最终结果。
先验证连接，再翻译付费文档
创建专用 Key、安装桥接、重启 Codex，并先查询账户和计费。确认连接正常后，再用一份代表性文档测试并复核结果。