document-format-conversion

name	document-format-conversion
description	将图片或 PDF 文档转换为 Word/Excel，保留原版式，支持表格/印章/水印/手写内容。需要 OCR 文档格式转换、PDF 转 Word/Excel 时使用。
license	MIT

能力概述

文档格式转换（百度 OCR）是一个异步接口，分两步完成：

1. 提交请求（Submit）：上传图片或 PDF，获取 task_id
2. 轮询结果（Poll）：用 task_id 查询进度，直到 ret_code = 3 时获取下载链接

维度	说明
提交接口	POST https://app-bo4w33bsdqm9-api-rY7JZ6jqrneL-gateway.appmiaoda.com/rest/2.0/ocr/v1/doc_convert/request
查询接口	POST https://app-bo4w33bsdqm9-api-oYA6ZGjReooa-gateway.appmiaoda.com/rest/2.0/ocr/v1/doc_convert/get_request_result
Content-Type	application/x-www-form-urlencoded
认证模式	platform_managed（traefik: true）
输入格式	图片 base64（jpg/jpeg/png/bmp，≤4M）、图片 URL，或 PDF base64（≤10M）
输出格式	Word 和 Excel 文件下载链接（有效期 30 天）
计费	原价 ¥2.20 / 次，折扣价 ¥1.80 / 次（按提交请求计次，获取结果不计费）

关键约束：

• ret_code = 1（未开始）、ret_code = 2（进行中）时必须继续轮询，不可停止
• 仅 ret_code = 3 时停止轮询，读取 result_data.word / result_data.excel 下载链接
• 提交接口 QPS 上限 2，查询接口 QPS 上限 10
• 建议提交后等待 5～10 秒再首次查询

---

生成期用法（Agent 直接调用）

完整异步工作流（提交 → 轮询 → 获取结果），详见 references/doc-convert-submit-api.md 和 references/doc-convert-query-api.md。

以下为端到端完整示例：

const apiKey = process.env["INTEGRATIONS_API_KEY"]!; // platform_managed，密钥由平台注入

/**
 * 提交文档格式转换任务。
 * @param input - 输入来源，三选一：image（图片 base64）、url（图片 URL）、pdfFile（PDF base64）
 * @param pdfFileNum - 可选，指定 PDF 页码（从 1 开始），不传则识别所有页
 * @returns task_id 字符串
 */
async function submitDocConvert(
  input: { image?: string; url?: string; pdfFile?: string },
  pdfFileNum?: string
): Promise<string> {
  const params: Record<string, string> = {};
  if (input.image) params.image = input.image;
  else if (input.url) params.url = input.url;
  else if (input.pdfFile) params.pdf_file = input.pdfFile;
  else throw new Error("必须提供 image、url 或 pdfFile 其中之一");
  if (pdfFileNum) params.pdf_file_num = pdfFileNum;

  const response = await fetch(
    ,
    {
      : ,
      : {
        : ,
        : ,
      },
      :  (params).(),
    }
  );
   (!response.)   ();
   json =  response.();
   (!json.)   ();
   json..;
}


  (): <{
  : ;
  : ;
  ?: { : ; :  };
}> {
   response =  (
    ,
    {
      : ,
      : {
        : ,
        : ,
      },
      :  ({ : taskId }).(),
    }
  );
   (!response.)   ();
   json =  response.();
   (!json.)   ();
   json.;
}


  (): <{ : ; :  }> {
   taskId =  (input, pdfFileNum);

    = ;           
    =  *  * ;      
   deadline = .() + ;

   (.() < deadline) {
      ( (r, ));
     result =  (taskId);

     (result. === ) {
      
       result. ?? { : , :  };
    }
    
  }
    ();
}

详细参数说明与响应结构见：

• references/doc-convert-submit-api.md（提交请求接口）
• references/doc-convert-query-api.md（获取结果接口）

---

生成后用法（应用内通过 Edge Function 调用）

本插件为异步流程，需要两个 Edge Function（分别对应提交和查询），前端负责轮询。

平台	Edge Function	前端轮询方式
Web / MiniProgram	doc-convert-submit + doc-convert-query	调用两次 Edge Function，ret_code ≠ 3 时继续轮询

完整 Edge Function 代码、前端调用代码及注意事项详见：

• references/doc-convert-submit-api.md（提交 Edge Function + 前端调用）
• references/doc-convert-query-api.md（查询 Edge Function + 前端轮询循环）