核心用法
easylink-easydoc-parse 是一个面向文档解析的 API 调用技能，专为中国 EasyLink 平台（cn）与全球 EasyDoc 平台（global）设计。用户通过该技能提交异步解析任务，将 PDF、Word 等格式的非结构化文档转换为结构化的 JSON 输出，包含 Markdown 正文、节点树、元数据等字段，便于下游 LLM 流水线或 RAG 检索使用。
技能遵循固定的生命周期：平台选择 → 输入验证 → 提交任务 → 轮询结果 → 输出规范化。支持两种解析模式：中国平台的 easydoc-parse-flash（快速）与 easydoc-parse-premium（高精度），以及全球平台的 lite 模式。文件大小限制为 100MB，通过 multipart/form-data 上传。
显著优点
1. 双平台兼容：一套接口同时支持国内 EasyLink（api.easylink-ai.com）与国际 EasyDoc（api.easydoc.sh），API 路径与参数差异已内部封装。
2. 结构化输出稳定：返回标准化的 task_id、status、files 信封，内含 markdown 与 nodes 数组，方便下游消费。
3. RAG 安全策略：明确禁止默认全量加载大 JSON，强制优先使用宿主代理的文本搜索工具（如 Grep）进行切片检索，降低上下文膨胀风险。
4. 开箱即用脚本：附带 scripts/easydoc_parse.py，支持命令行一键提交、自动轮询、结果保存，且优先从环境变量读取 API Key。
潜在缺点与局限性
- 异步轮询依赖：需外部实现或依赖脚本完成状态轮询，无原生 Webhook 回调机制。
- 平台差异隐性：文件字段名（
filesvsfile）、结果端点路径、状态枚举值（SUCCESS/COMPLETED/DONE）存在平台特化，需仔细区分。 - RAG 策略强制：若宿主代理未提供搜索工具，技能本身不提供替代搜索实现，可能阻塞检索路径。
- 无内置重试：HTTP 或解析失败时需用户手动处理重试或模式切换建议。
适合人群
- 需要批量将合同、论文、报告等文档结构化的开发者
- 构建 RAG 知识库、需避免全文加载导致 Token 爆炸的 AI 应用团队
- 同时面向中国大陆与海外用户的 SaaS 产品，需统一文档解析层
常规风险
- API Key 泄露：
EASYLINK_API_KEY与EASYDOC_API_KEY需存储于环境变量，避免硬编码。 - 敏感文件传输：文档内容经 HTTPS 上传至第三方平台，需确认合规性。
- 大文件轮询超时：未明确超时阈值，长文档可能导致长时间等待。
- 解析质量波动：OCR 与版式还原依赖云端模型，复杂表格或手写体可能出现错位。