名称：u2-doc-parser
描述：使用 UniDoc API 解析文档，支持转换为 Markdown 或 JSON 格式。同时支持同步与异步解析，并内置自动状态轮询机制。

UniDoc 文档解析器

概述

使用 UniDoc API 解析文档，可将其转换为 Markdown 或 JSON 格式。支持同步和异步两种解析模式，并在异步模式下自动轮询任务状态。适用于通过云端 API 服务将多种文档格式（PDF、DOC、DOCX、图像等）进行格式转换。

⚠️ 重要隐私提示

• 本技能会将您的文档上传至外部 API 服务：https://unidoc.uat.hivoice.cn
• 文档经互联网传输，并在第三方服务器上处理
• 当前 UAT 环境无需身份认证或 API 密钥
• 请勿对敏感、机密或私有文档使用本技能
• 使用本技能即表示您已知悉并接受文件将被上传至外部服务器

前置条件 / 何时查阅参考资料

如遇 API 错误、网络问题，或需深入了解 API 接口定义，请参阅：

• references/unidoc-notes.md

快速开始（单个文档）

# 输出到终端（默认行为）
python scripts/unidoc_parse.py /path/to/file.pdf

# 保存为文件
python scripts/unidoc_parse.py /path/to/file.pdf --output result.md

# 转换为 JSON 格式（异步模式）
python scripts/unidoc_parse.py /path/to/file.docx --format json --mode async

选项

• --format md|json（默认值：md）
  • 输出格式：Markdown 或 JSON
• --mode sync|async（默认值：sync）
  • 同步模式：等待转换完成后再返回结果
  • 异步模式：持续轮询任务状态直至完成
• --func METHOD（默认值：unisound）
  • 指定使用的转换方法/算法
• --output FILE（可选）
  • 将输出保存至指定文件，而非打印到终端
  • 未指定时，默认直接输出至 stdout
• --uid UUID（可选）
  • 自定义用户 ID；若未提供，则自动生成

输出

• 默认行为：将转换后的内容直接打印至终端（stdout）
• 配合 --output 使用：保存至指定路径的文件中
• 进度信息与错误消息均输出至 stderr
• 支持管道操作，例如：python scripts/unidoc_parse.py doc.pdf | grep "keyword"

注意事项

• 隐私性：您的文档将上传至 UniDoc 的 UAT 服务器进行处理
• 无需认证：当前实现不依赖 API 密钥或任何凭据
• 网络要求：需能访问 https://unidoc.uat.hivoice.cn
• 支持格式：PDF、DOC、DOCX、PNG、JPG 等
• 异步模式：每秒轮询一次状态，最长等待时间为 5 分钟
• 限制条件：最大文件大小及调用频率限制取决于 API 服务端配置
• 使用建议：对于大文件或批量处理任务，推荐使用异步模式
• 安全性：仅限用于非敏感的测试文档