翔云通用文档/表格识别

功能概述

调用翔云 OCR 平台的通用文档识别 API（typeId: 3050），对图片、PDF、扫描件中的文字、表格、版面结构进行一体化识别，并支持导出为 Excel、Word、Markdown、PDF、TXT、OFD 等多种格式。

适用场景：

💡 表格识别建议：layout: 1（开启版面分析）对表格结构识别更友好。

⚠️ 安全说明

数据发送范围：

• 识别阶段：用户图片和 API 凭据会被发送至 netocr.com 进行云端 OCR 处理，图片不会在服务端持久化存储
• 下载阶段：OSS 导出会话凭证来自 API 返回的预签名 URL，文件直接下载到本地

SSL 处理策略：

• 主 API（netocr.com）：保持完整的 SSL 证书验证
• OSS 下载（product.netocr.com）：仅对 OSS 域名禁用证书验证，因该 CDN 证书存在主机名不匹配问题（product.netocr.com 证书未包含此域名），其他所有请求均使用标准 SSL 验证

⚠️ 凭据配置

配置文件

将凭据保存到 Skill 目录下的 config.json：

// config.json（Skill 同目录下）
{
  "key": "你的OCRKey",
  "secret": "你的OCRSecret"
}

💡 首次使用：创建 config.json，填入凭据即可。配置一次，永久使用。

凭据加载优先级

首次配置流程

1. 检查 ./config.json 是否存在且含 key 和 secret
2. 若不存在或不完整，向用户提示：

首次使用翔云文档识别，请配置 API 凭据：

1. 前往 https://netocr.com 注册并登录
2. 进入【个人中心】获取 API Key 和 Secret
3. 请提供：
   - key：______
   - secret：______

3. 收到后写入 ./config.json，并提示用户"凭据已保存，后续无需重复输入"

触发词参考

执行流程

阶段一：识别文档

Step 1：加载凭据

按【凭据配置】章节顺序加载 key / secret：

• config.json → 环境变量 → 用户输入

Step 2：获取图片输入

支持以下方式：

• 本地文件路径：用户提供绝对路径，脚本读取后转 Base64
• 用户拖入文件：直接获取文件路径
• 批量目录：用户提供文件夹路径，遍历所有图片

Step 3：配置识别参数

固定参数：

{ "typeId": 3050, "format": "json" }

语言参数 nLanguage（默认 0=简体中文）：

💡 语言推断：提到"英文"→ 2；"日文"→ 11；"繁体"→ 1；未指定→ 0

版面参数 layout：

图像校正参数：

预处理参数：

Step 4：调用识别 API

执行脚本 scripts/recognize_table.py：

python scripts/recognize_table.py --image <路径> --export xls

API 接口：

• Base64：POST https://netocr.com/api/recog_table_base64
• File 上传：POST https://netocr.com/api/recog_table_file

响应格式：{"message": {"status": 0, "value": {...}}}

• status == 0 表示成功
• consumeId 在 message.value.consumeId

Step 5：展示结果

• 以 Markdown 表格预览识别内容
• 告知 consumeId，提示可随时导出

阶段二：导出文件（按需触发）

仅当用户明确提出"导出/下载/转换/保存为"时才执行。

导出格式：

下载接口：POST https://netocr.com/api/download_file

• 不需要 key/secret
• 返回 OSS 预签名 URL → 再发 GET 请求下载实际文件

批量识别

1. 遍历目录下所有 jpg/png/jpeg/webp/tif/pdf 文件
2. 逐一调用识别 API（间隔 0.5 秒）
3. 汇总展示成功/失败统计
4. 按需批量导出

图片/文件要求

错误处理

参考文档

详细 API 字段、参数枚举及返回结构，参考：references/api_docs.md