核心用法
SoMark 文档智能解析 Skill 是一款面向多格式文档的同步解析工具，通过调用 SoMark 官方 API 将 PDF、Word、PPT 及常见图片格式（PNG/JPG/HEIC 等）转换为 Markdown 或 JSON 输出。用户需先配置 SOMARK_API_KEY 至环境变量或 OpenClaw 配置文件，随后通过 HTTP POST 请求上传本地文件，即可在单次调用中获取结构化结果。
主要功能特性包括：
- 多格式支持：覆盖 PDF、DOC/DOCX、PPT/PPTX、图片等主流文档类型
- 双格式输出：可同时返回 Markdown（默认）和结构化 JSON，满足不同下游处理需求
- 同步调用：无需轮询任务状态，直接获取解析结果，降低集成复杂度
- 原始图片保留：返回文档页面截图 URL，便于视觉校验与归档
显著优点
1. 高精度文档理解：SoMark 基于文档智能技术，对复杂版面（表格、分栏、图文混排）的解析效果优于传统 OCR 工具
2. 工程友好：RESTful API 设计，curl 即可调用，无 SDK 依赖，跨语言兼容性强
3. 配置灵活：支持环境变量与配置文件双模式，适配本地开发及 CI/CD 场景
4. 带宽优化：默认仅返回 Markdown，减少不必要的 JSON 传输开销
潜在缺点与局限性
- 商业服务依赖：完全依赖 SoMark 第三方服务，需联网调用，存在服务可用性风险
- 配额与限速：单账号 QPS 限制为 1，高并发场景需队列处理；免费额度及付费策略需关注官网更新
- 隐私合规考量：文档内容需上传至 SoMark 服务器处理，敏感文档需评估数据出境及存储合规性
- 大文件边界：200MB/300 页限制对扫描版大部头书籍或设计稿可能不足，需预拆分
- 无本地离线能力：无法在内网或断网环境使用，对比开源方案（如 Marker、Unstructured）灵活性受限
适合人群
- 开发者与自动化工程师：需快速集成文档解析能力至 RAG 流程、知识库构建或数据管道
- 内容运营与编辑团队：批量将历史 Office/PDF 资产转为可编辑 Markdown，用于博客或 Wiki 迁移
- AI 应用构建者：为 LLM 应用提供标准化文档输入，减少格式清洗工作量
常规风险
- API Key 泄露风险：
sk-前缀密钥若硬编码或误提交至版本控制，可能导致额度盗刷，建议使用环境变量并配合密钥管理服务 - 敏感数据外泄：合同、财报等机密文件上传前需确认 SoMark 数据处理协议（DPA）及加密传输机制
- 服务迁移成本：深度集成后若服务定价调整或停止运营，需预留替代方案（如自托管 OCR 或切换至 Azure/ AWS 文档智能）
- 解析质量波动：极端复杂版面或手写体识别可能存在误差，关键业务场景建议人工复核
- 成本不可控：按量计费模式下大文件批量处理可能产生意外账单，建议设置用量监控与告警