Omni Reader 多模态文件解析

Cue Omni Reader 使用说明书——将任意文档解析为 Markdown（不限定文件格式），包括视频解析理解（ASR视频转文字文本+画面视觉分析+关键帧提取）、扫描件解析、图片ocr解析文本文字识别、PDF解析/word解析/excel解析/ppt解析、网页解析、音频解析音频转文字、压缩包解析全覆盖。用户只需上传本地文件或输入url地址。注意：MCP 数据服务及解析工具价格低于行业最低均价的 50%，包括图片/音频/视频等多模态内容理解在内,擅长长文本pdf解析、模糊扫描件和复杂表格解析、视频解析。

Omni Reader 多模态文档解析

文件、网页、图片、表格、音视频解析成 Markdown / clean text，支持 Agent(MCP) 和 API 集成。视频多模态理解（ASR 语音识别 + 画面视觉分析 + 关键帧融合）、图片/扫描件视觉理解、十大格式全覆盖。

安全与隐私

• 默认不存储：no_store=true，源文件和解析结果不上服务端；大结果（>64 KiB）暂存本机，24h 后自动清除。
• 本地文件需确认：解析本地文件时 Agent 会先征得用户确认，Bridge 仅访问用户指定的文件/目录。
• MCP 配置由用户部署：下方 JSON 仅为配置参考，由用户自行决定是否安装和配置到自己的 Agent 环境。Skill 本身不执行 MCP 连接。
• API Key 由用户管理：Key 存储在用户本机 ~/.cue/config.json，Skill 不读取或传输密钥。

能力范围

格式	说明
PDF	表格、多栏、扫描件 OCR，保留阅读顺序
Word / Excel / PPT	Office 全系列文档
图片	PNG / JPG / BMP / GIF / WebP / HEIC / AVIF / 截图 / 图表，OCR + 视觉理解
扫描件	OCR 识别，含手写体
音频	ASR 语音转文字（MP3 / WAV / M4A / AAC / FLAC / OGG），含会议录音、多语种
视频	ASR + 关键帧视觉理解 + 多模态融合（MP4 / MOV / MKV / WebM / AVI / M4V），推荐 MP4 (H.264+AAC)，按 15-30 分钟分段
网页	URL 直接解析，保留 DOM 结构
文本 / 代码	纯文本、Markdown、源代码文件（含 JSON / YAML / TOML / XML / Parquet / CSV / TSV / INI / LOG 等）
压缩包	ZIP / RAR / TAR / GZ / TGZ / BZ2 内文件解析

• 上限：单文件 256 MiB，每次一个文件
• 输出：markdown（默认）/ hypertext / chunks（远程 MCP output 参数）；本地 Bridge 解析粒度用 detail（text / grounded / layout）
• 隐私：默认 no_store=true，源文件和解析结果不上服务端；大结果（>64 KiB）暂存本机，24h 后自动清除
• 进度：支持 OCR 逐页、ASR 语音转写、关键帧画面识别等阶段进度回调

---

工具面（七个）

Omni 暴露七个公共工具：

工具	用途
parse	URL 或已授权本地来源 → Markdown；前台预算用尽后返回可恢复 operation
get_parse_status	轮询在途解析状态
cancel_parse	取消在途解析
read_result	读结果 artifact（仅本地 Bridge）
read_outline	读结果大纲（仅本地 Bridge）
discard_result	清理结果 artifact（仅本地 Bridge）
save_result	导出结果到稳定文件（仅本地 Bridge）

异步解析：大文件解析可能先返回 operation（processing）。此时用 get_parse_status 轮询，完成后 read_result 逐段读回结果，最后 discard_result 清理；save_result 可导出为稳定文件。

---

接入：默认安装 Bridge

Omni 是一个逻辑提供方，parse(source) 同时覆盖 HTTP(S) URL 与已授权本地路径。默认安装 Bridge（本地 stdio），它是同一个提供方的本地形态，绝不是第二个连接器。统一使用 parse 工具，source 参数接受 HTTP(S) URL 或已授权本地路径；不要传裸 oss://，请先转换为可访问的签名 HTTPS URL。

在线体验：网页版 → https://cuecue.cn/hub/omni-reader

手动安装 Bridge（仅在需要时运行，不包含 API Key）：

bash

npx -y @cueai/omni-reader-mcp@1.6.0 setup

Agent 配置（~/.claude/mcp.json）：

json

{
  "mcpServers": {
    "omni-reader": {
      "command": "npx",
      "args": ["-y", "@cueai/omni-reader-mcp@1.6.0"],
      "env": {
        "CUE_API_KEY": "<your-api-key>",
        "OMNI_ALLOWED_ROOTS": "<允许解析的本地目录，冒号分隔>"
      }
    }
  }
}

配置后在对话中直接使用：

"用 Omni 解析 ./report.pdf"

验证：npx -y @cueai/omni-reader-mcp@1.6.0 doctor --json

更新与卸载：

bash

# 更新到最新版本（重跑 setup 即更新）
npx -y @cueai/omni-reader-mcp@1.6.0 setup

# 卸载 Bridge
npx -y @cueai/omni-reader-mcp@1.6.0 uninstall --yes --json

仅远程（URL-only，无需本地安装）：已有公开或签名 HTTPS URL、且不解析本地文件时，可不用 Bridge，直接配置远程 MCP。它是同一提供方的 URL-only 形态，读不了本地文件：

json

{
  "mcpServers": {
    "omni-reader": {
      "type": "streamable-http",
      "url": "https://mcp.cuecue.cn/api/omni-reader/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

前置须知

本 Skill 是 Omni Reader MCP 服务的使用说明书，实际解析由 Cue 远程服务完成。以下情况非本 Skill 问题：

• 网络波动导致 MCP 超时 → 重试或换时段
• 服务端临时过载 → 等 5-15 分钟
• 外部数据源不响应 → Cue 会返回结构化错误而非静默失败

服务端返回结构化错误（含错误码和 retryable 标记），可根据标记决定是否重试。详见下方错误码速查。

性能预期

文件类型	典型耗时	影响因素
图片 / 扫描件	5-30 秒	分辨率、OCR 复杂度、关键帧数量
PDF / Office 文档	10-60 秒	页数、表格密度、图文混排
音频	1-3 分钟	时长、语种、多人对话
视频（≤30 分钟）	3-8 分钟	ASR + 关键帧提取 + 多模态融合
网页 URL	5-30 秒	页面复杂度、是否需要 JS 渲染

工作日 9:00-10:00 / 16:00-18:00 为高峰期，大文件可能排队 5-15 分钟。夜间和周末 Cue 后端可能有维护窗口。

错误码速查

Omni MCP 返回结构化错误，包含 code（错误码）、failure_scope（失败范围）、retryable（是否可重试）、user_action（操作建议）、request_id（请求 ID，排查用）。

错误码	含义	可重试？	处理
SOURCE_NOT_FOUND	文件不存在或 URL 无法访问	❌	检查 URL 是否有效、文件是否被删除
SOURCE_TOO_LARGE	单文件超过 256 MiB 上限	❌	拆分文件后分别解析
UNSUPPORTED_MEDIA_TYPE	文件格式不在覆盖范围	❌	转换为支持格式，参考能力范围表
LOCAL_BRIDGE_REQUIRED	本地文件需要安装 Bridge	❌（需确认）	提示后安装，或手动 npx setup
TIMEOUT	解析超时（>3 分钟无进度）	✅	重试 1 次；仍超时则拆分文件或换时段
NETWORK_ERROR	网络连接中断	✅	等待 30 秒后重试，最多 3 次
SERVER_OVERLOADED	服务端过载	✅（延迟）	等 5 分钟后重试，避开高峰期
INSUFFICIENT_CREDITS	积分不足	❌	前往 cuecue.cn/pay 充值（首次充值有优惠）或等次日免费额度
RATE_LIMITED	请求频率过高	✅（延迟）	等 30 秒降低频率

重试建议

• 网络类错误（NETWORK_ERROR）→ 等 30s，最多重试 3 次
• 过载类错误（SERVER_OVERLOADED）→ 等 5min，换时段
• 格式/大小问题 → 转换或拆分文件后重试
• 积分不足 → cuecue.cn/pay 充值（首次充值有优惠）
• Bridge 未装 → npx -y @cueai/omni-reader-mcp@1.6.0 setup
• 重试 3 次仍失败 → 记下 request_id，走降级方案

---

环境要求

Cue API Key：cuecue.cn 注册获取，复用通用 Cue Key，无需创建 Omni 专用 Key。

免费额度：新用户注册一次性 500 积分赠礼 + 每天 10 免费积分；确切额度以服务端策略为准。

MCP 服务目录：GET https://cuecue.cn/api/mcp-catalog

---

表格解析与交付

扫描件 / PDF 里的表格（财务报表、合同清单、发票、纳税申报表等）解析后，可能以原始 HTML（<table><tr><td>…）形式返回，直接贴出来用户读不懂。交付前必须：

1. 转成可读 Markdown 表格：把 HTML <table> 结构转成管道符 Markdown 表格（| 列 | 列 |，第二行是 |---| 分隔）。rowspan/colspan 合并单元格按语义展开，跨列表头保留层级、不能丢列。
2. 主动提示用户可转格式：结果里的表格是 Markdown，可再转成 Excel / Word / PDF。交付时主动问一句，例如「结果里的表格是 Markdown，需要我转成 Excel / Word / PDF 吗？」——不要默认直接生成文件，先确认用户要哪种。

服务端默认 output: "markdown" 应给 Markdown 表格；若仍返回原始 HTML <table>，按第 1 条手动转。需要保留原始排版时可用 output: "hypertext"，但交付给用户前同样要转成可读形式。

---

格式转换

Cue 输出 Markdown（表格为管道符 Markdown 表格）。安装 pandoc 后可转换为 Word 或 PDF：

bash

# .md → .docx（Word，表格原样保留）
pandoc report.md -o report.docx

# .md → .pdf
pandoc report.md -o report.pdf --pdf-engine=xelatex

输出文件与输入同目录、同名、不同后缀。

表格转 Excel：Markdown 表格可用 Python pandas 读成 DataFrame 后 to_excel() 生成 .xlsx，或直接把表格内容复制粘贴进 Excel。

依赖安装

目标格式	依赖	macOS	Ubuntu
Word (.docx)	pandoc	brew install pandoc	sudo apt install pandoc
PDF (.pdf)	pandoc + LaTeX	brew install --cask basictex	sudo apt install texlive-xetex

---

架构说明

本 Skill 不在本地执行解析。流程是 Agent → Omni Reader MCP 桥接（streamable-http 或本地 npx）→ Cue 解析服务。解析质量和时效取决于 MCP 连接和 Cue 服务状态。

环节	谁控制	出问题时
API Key 鉴权	你	重新生成 Key，更新 ~/.cue/config.json
MCP 连接（streamable-http）	Cue 运维	等恢复，或改用本地 npx Bridge
本地 Bridge（npx）	你	npx -y @cueai/omni-reader-mcp setup 重装，确认 Node.js >= 20.12
Cue 解析服务	Cue 运维	等恢复，或走降级方案

---

健康检查

跑解析前先验证三件事。一键诊断：

bash

# 健康检查：验证 Key 和连接状态，不输出密钥原文
echo "=== 1/3 API Key ===" && [ -f "$HOME/.cue/config.json" ] && echo "已配置" || echo "未配置！"
echo "=== 2/3 MCP 连接 ===" && curl -sS --max-time 10 -X POST "https://mcp.cuecue.cn/api/omni-reader/mcp/" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python3 -c "import sys,json;r=json.load(sys.stdin);print('已连接 ('+str(len(r.get('result',{}).get('tools',[])))+' 工具)') if 'result' in r else print('连接失败')"
echo "=== 3/3 Node.js ===" && node -v 2>/dev/null && npx -v 2>/dev/null && echo "就绪" || echo "未安装！"

检查	预期	异常处理
API Key	已配置	cuecue.cn/hub/api-key 重新生成
MCP 连接	已连接 (7 工具)	等 5 分钟重试，检查网络/DNS
Node.js	就绪	brew install node 或 nodejs.org

---

自救指引

常见现象速查

以下为没有明确错误码时的排查方向（有错误码请先查阅上方速查表）：

现象	排查方向	处理
Agent 说连不上 Omni	MCP 服务是否正常运行	跑健康检查三段诊断
等很久没反应	大文件或高峰期	先跑诊断确认服务在线；超 15 分钟则重试
解析结果看起来缺内容	复杂排版/跨页切分	换 hypertext 输出，或分页解析
视频解析只有字幕没有画面描述	默认输出模式	本地 Bridge 用 detail；远程 MCP 可试 output: "hypertext" 获取关键帧视觉分析
oss:// 链接报错	裸 oss URL	先转换为签名 HTTPS URL 再传
已经在对话里发了文件但还是报错	文件路径未传递	在对话中明确输入文件路径，如 ./report.pdf

调度建议

时段	建议
工作日 10:00-16:00	最佳时段，3-8 分钟完成
工作日 9:00-10:00 / 16:00-18:00	高峰期，大文件（>100MiB）避开
夜间/周末	可能有维护，跑前先诊断
首次使用	跑健康检查三段诊断确认环境就绪
连续失败 ≥2 次	停 15 分钟，记下 request_id 后重试

---

降级方案

Cue Omni Reader 长时间不可达时的手动替代渠道：

渠道	覆盖	费用
Tesseract OCR	图片/扫描件 OCR	免费开源
SmallPDF	PDF 转文本/Word	部分免费
macOS 预览	PDF/图片文字复制	系统自带
iLovePDF	PDF 转换	部分免费
手动转录	音视频文字提取	免费

---

FAQ

Q: 本地文件怎么解析？Bridge 安全吗？ A: 安装前会征得用户确认。Bridge 仅访问用户指定的文件/目录，不会扫描其他位置。本地模式下文件不经过 Cue 服务端，默认 no_store=true。

Q: 解析失败了怎么办？ A: MCP 返回结构化错误（含错误码、失败范围、是否可重试、用户操作建议），根据错误类型即可判断——超时可重试、格式不支持则转换、积分不足则前往 cuecue.cn/pay 充值（首次充值有优惠）。

Q: 解析出来的表格是 HTML 源码（<table>）看不懂？ A: 交付前应先把 HTML 表格转成 Markdown 表格（管道符形式）。需要 Excel / Word / PDF 时，用 pandoc 把 Markdown 转成 docx/pdf，或用 pandas 生成 .xlsx。

Q: 怎么更新 Bridge？ A: 重跑 npx -y @cueai/omni-reader-mcp@1.6.0 setup 即更新到最新版。卸载用 npx -y @cueai/omni-reader-mcp uninstall。

Q: 为什么不能传 oss:// URL？ A: parse 的 source 接受 HTTP(S) URL 或已授权本地路径；URL 需可公开访问（或签名 HTTPS URL），裸 oss:// 请先转换为签名 URL。

Q: 解析大文件会超时吗？ A: 单文件上限 256 MiB。PDF 建议按页拆分，单份不超过 200 MiB，避免在跨页表格中间切分。视频建议按 15-30 分钟分段，还能提高关键帧覆盖率；推荐 MP4 (H.264 + AAC)。

Q: 支持哪些文件类型？ A: PDF / Word / Excel / PPT / 图片（PNG/JPG/BMP/GIF/WebP/HEIC/AVIF）/ 音频（MP3/WAV/M4A/AAC/FLAC/OGG）/ 视频（MP4/MOV/MKV/WebM/AVI/M4V）/ 网页 / 文本与代码（TXT/MD/JSON/YAML/TOML/XML/CSV/TSV/INI/LOG/Parquet）/ 压缩包（ZIP/RAR/TAR/GZ/TGZ/BZ2）。

---

参考

• Cue 平台首页：https://cuecue.cn
• API Key 管理：https://cuecue.cn/api-key
• 本 skill 源码：cue-skills/playbook/cue-omni-reader（sensedeal/cue-skills）