baidu-file-translate — Agent 参考文档

文件翻译是异步的。请始终使用下方的“提交 → 轮询”循环流程。
切勿在未指定超时（--wait-timeout）的情况下依赖 --wait 参数——在 Agent 框架中，它可能导致无限期阻塞。

步骤 1：提交翻译任务 → trans file submit  --from auto --to  --json  
        → 若退出码 ≠ 0 → ⚠ 若退出码为 2（认证/配置错误），立即终止；其余错误请按“错误处理”章节处理  
        → 若退出码为 0 → 从标准输出中记录 request_id  

步骤 2：每 5 秒轮询一次 → trans file query  --json  
        → 若退出码 ≠ 0 → 处理错误；若错误码为 DOC_FAILED，则不再重试  
        → 若退出码为 0 且 status=processing → 继续轮询（建议 Agent 级超时 ≤ 10 分钟）  
        → 若退出码为 0 且 status=done → ⚠ 下载前须先向用户确认  
                                       然后执行：trans file query  --download --output ./  
        → 若发生 WAIT_TIMEOUT → ⚠ 终止当前流程 —— 保存 request_id 并通知用户  

请设置 Agent 级超时（例如 10 分钟）。当发生 WAIT_TIMEOUT 时，应保存 request_id 并告知用户——该任务仍在后台运行，后续可恢复查询。

trans file submit

trans file submit report.pdf --from zh --to en --json
trans file submit report.pdf --to en --reference "Use academic tone"

trans file query

trans file query REQ123 --json
trans file query REQ123 --download --output ./output/

JSON 接口规范

提交成功（标准输出）：

{"request_id": "REQ123", "status": "submitted"}

查询中（标准输出）：

{"request_id": "REQ123", "status": "processing", "name": "report.pdf", "from": "zh", "to": "en"}

已完成（标准输出）：

{"request_id": "REQ123", "status": "done", "file_url": "https://...", "char_count": 1000, "amount": 70}

若启用 --download，则已完成响应中将额外包含：

{"local_path": "/absolute/path/to/report_en.pdf"}

错误（标准错误输出，退出码 ≠ 0）：

{"code": "AUTH_FAILED", "message": "...", "help_url": "https://fanyi-api.baidu.com/manage/apiKey"}

当不适用时，help_url 字段将被省略。

错误处理

退出码 ≠ 0
├── CONFIG_MISSING (退出码 2) → 引导用户配置 TRANS_API_KEY  
├── AUTH_FAILED    (退出码 2) → API 密钥无效或已过期；请访问 fanyi-api.baidu.com/manage/apiKey 核查  
├── QUOTA_EXCEEDED (退出码 3) → 配额耗尽；需充值后重试  
├── RATE_LIMITED   (退出码 3) → 触发限流；建议退避 30 秒后重试  
├── NETWORK_ERROR  (退出码 4) → 网络连接异常；请检查网络后重试  
├── DOC_FAILED     (退出码 3) → 服务端处理失败；请勿重试  
├── INVALID_INPUT  (退出码 1) → 修正文件路径 / 格式 / 或 --to 参数值  
└── WAIT_TIMEOUT   (退出码 1) → 任务仍在运行；保存 request_id，后续可恢复查询  

所有错误信息均仅通过标准错误输出（stderr）返回；stderr 中不会输出任何进度事件。

支持的文件格式

docx / doc / pdf / xlsx / xls / pptx / ppt / html / htm / txt / xml / md

file_url 链接有效期为 30 天。