Ekko Studio OCR 与文档提取技能实战：从扫描 PDF 到结构化 Markdown 的本地优先工作流

AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载导读Ekko Studio本地优先的多 Agent 协作工作区内置了一组 Agent Skills其中ocr-and-documents专门解决普通文本提取失效的场景——扫描件、纯图片型 PDF 和复杂版式文档。本文基于 ocr-and-documents 技能目录 及其 SKILL.md系统讲解该技能的适用判断、轻重两条提取路径、命令行用法、隐私边界与结果校验方法并结合仓库内两个 Python 助手脚本的源码与测试用例带你掌握一套可复制、可落地的本地文档 OCR 工作流。一、这个 Skill 解决什么问题ocr-and-documents在 DESCRIPTION.md 中的定位非常明确Skills for extracting text from PDFs, scanned documents, images, and other file formats using OCR and document parsing tools.而在 SKILL.md 中则进一步收敛了使用边界Use this Skill when ordinary document extraction fails because the source is scanned, image-based, or layout-heavy.即只有当普通文本提取失效时才启用。对于生来就是数字文本的文档born-digital应该走各自的常规技能——PDF 用pdfSkillWord 用docxSkill而不是盲目地对一切文件做 OCR。在 ekko-agent/README.md 的内置技能清单中ocr-and-documents与pdf、docx、xlsx、powerpoint等一同被列为包内置package-owned技能随 Agent 自动同步安装属于skill_list/skill_view/skill_manage工具可发现的默认能力之一。这意味着你不需要手动部署Agent 会通过skill_list检索、skill_view加载技能目录并返回可执行脚本所在的baseDirectory。典型触发场景场景特征推荐路径扫描版 PDF合同、票据纯图片页无文本层先用pdfSkill 渲染页面 视觉检查再按需转录文本型扫描 PDF有文本层但质量差extract_pymupdf.py轻量复杂版式表格、公式、多页扫描版式密集、结构复杂extract_marker.py重量级需谨慎URL 指向的文档HTML 或文件不确定先用浏览器/HTTP 工具判别再下载本地处理二、核心原则先走最轻的路SKILL.md 给出了明确的四步决策阶梯这是整个技能的灵魂——不要一上来就上重型 OCR常规提取优先PDF 用pdfSkill.docx用docxSkill不对数字文本做 OCR。这与 pdf/SKILL.md 中的约定相互印证——pdf Skill 明确写着Use OCR only when normal text extraction is empty or clearly incomplete. Route scanned documents through the ocr-and-documents Skill两个技能形成了清晰的分工与转介关系。少量扫描页先用pdfSkill 渲染页面再用view_image查看渲染图只转录用户要求的页面。文本型扫描 PDF尝试extract_pymupdf.py——这是更轻的本地路径依赖只有 PyMuPDF。复杂版式/表格/公式/大量扫描页确认需求并检查资源后才使用extract_marker.py。这个阶梯设计的背后是对资源成本的清醒认识marker-pdf 可能需要数 GB 的包和模型下载而 PyMuPDF 路径只需一个 pip 包。仓库中extract_marker.py的--check参数见下文第四节正是为这一决策提供磁盘空间依据。三、轻量路径extract_pymupdf.py 全解3.1 基本用法python3 baseDirectory/scripts/extract_pymupdf.py input.pdf -o extracted.md其中baseDirectory是调用skill_view后返回的技能目录绝对路径。运行依赖python3 -m pip install pymupdf而--markdown模式额外需要pymupdf4llm。从源码看extract_pymupdf.py 采用延迟导入策略pymupdf、pymupdf4llm、pandas都在各自函数内部导入因此只跑普通文本提取时无需安装全套依赖这也与轻量优先的定位一致。3.2 五种提取模式互斥脚本通过argparse的add_mutually_exclusive_group定义了四种互斥模式外加默认的纯文本模式参数作用底层实现要点无参数纯文本提取逐页document[index].get_text()输出带--- Page N/M ---分页标记--markdown结构化 Markdown 提取pymupdf4llm.to_markdown(path, pagespages)需额外安装pymupdf4llm--tables表格识别为 Markdown 表格page.find_tables()检测表格table.to_pandas().to_markdown(indexFalse)输出--images DIRECTORY提取 PDF 内嵌图片遍历page.get_images(fullTrue)输出page{N}_img{M}.png当pixmap.n 5如 CMYK时先转换到 RGB 再保存--metadata输出文档元数据 JSON返回页数、标题、作者、主题、创建者、生产者、格式等字段json.dumps(..., ensure_asciiFalse)保留中文3.3 页面范围选择--pages参数接受从 0 开始的页索引支持逗号分隔的单个页和-连接的区间例如# 提取第 15 页内部为索引 0-4 python3 baseDirectory/scripts/extract_pymupdf.py input.pdf --pages 0-4 -o first5.md # 提取第 1、3、6 页 python3 baseDirectory/scripts/extract_pymupdf.py input.pdf --pages 0,2,5 -o selected.md源码中的parse_pages函数会做两类合法性校验区间起点不能大于终点否则抛ArgumentTypeError页索引不能为负超出文档实际页数的索引会被静默跳过if index len(document): continue因此可以放心给大范围。这个能力让只转录用户要求的页面这一轻量原则有了落地的抓手。3.4 输出行为不传-o/--output时结果直接打印到 stdout传-o时结果以 UTF-8 写入文件同时 stdout 输出一行 JSON{output: /abs/path/to/extracted.md}方便 Agent 拿到绝对路径返回给用户。任何ImportError、OSError、ValueError、RuntimeError都会以Error: ...形式写到 stderr 并返回退出码 2便于上层捕获失败。四、重量级路径extract_marker.py 与资源检查4.1 定位与风险提示extract_marker.py基于marker-pdf脚本源码对复杂版式的处理能力远超 PyMuPDF 路径——它在内部调用PdfConverter与create_model_dict()会加载真实的视觉/版面模型。代价是依赖包与模型下载可能占用数 GB 空间SKILL.md 明确要求绝不可自动安装必须先检查磁盘空间并征求用户同意。4.2 --check先查资源再干活python3 baseDirectory/scripts/extract_marker.py --checkcheck_requirements()函数用shutil.disk_usage计算当前磁盘可用空间单位 GiB可用空间 5GB打印Only X.XGB free. marker-pdf needs about 5GB.并提示改用extract_pymupdf.py或释放空间返回退出码 1空间充足打印X.XGB free; sufficient for marker-pdf.返回 0。关键设计--check分支在import marker之前返回因此即使 marker 尚未安装也能执行用于快速、零成本地评估可行性。4.3 转换用法与输出格式# 默认 Markdown 输出 python3 baseDirectory/scripts/extract_marker.py input.pdf -o extracted.md # 结构化 JSON 输出markdown metadata 双字段 python3 baseDirectory/scripts/extract_marker.py input.pdf --json -o extracted.json # 同时把提取出的图片保存到目录 python3 baseDirectory/scripts/extract_marker.py input.pdf -o extracted.md --output-dir assets/ # 启用 marker 配置的 LLM 增强 python3 baseDirectory/scripts/extract_marker.py input.pdf --use-llm -o extracted.md参数说明参数含义document输入文档路径--check模式下可省略-o/--output结果写入 UTF-8 文件stdout 返回{output: ...}JSON--output-dir提取出的图片保存目录脚本从rendered.images中逐张落盘--json输出{markdown: ..., metadata: ...}结构化 JSON--use-llm将{use_llm: True}注入 marker 的ConfigParser启用其配置的 LLM 增强环节--check只做磁盘空间检查不加载 marker五、URL 来源的处理规范当来源是 URL 时SKILL.md 给出的流程是先用可用的浏览器或 HTTP 工具判别目标到底是 HTML 页面还是文档文件只下载被请求的那一份文档并尊重认证与访问边界不要越权抓取下载为本地副本后再走上述提取流程不要假设存在某个特定的 Web 工具——工具可用性以当前环境为准。这保证了 URL 场景下依然保持本地处理 最小权限的隐私姿态。六、隐私与依赖安全边界整个技能有一条贯穿始终的红线SKILL.md 与 pdf Skill 的约定一致优先本地处理未经用户明确授权不得把私人文档上传到外部 OCR 服务重型依赖不自动安装marker-pdf 及其模型下载必须先检查磁盘空间、先征得用户同意敏感内容不外泄不要向外部服务发送敏感文档内容。这与 ekko-agent/README.md 中对技能工具的描述相辅相成——skill_view只加载SKILL.md或允许的支持文件并返回baseDirectory脚本由 Agent 在本地执行天然适合处理含隐私信息的合同、票据、证件类文档。七、结果校验清单VerificationOCR 结果的可靠性与校验投入成正比SKILL.md 给出了明确的验收标准这也是提取 ≠ 完成的关键一步保留结构与引用阅读顺序、页码引用、标题、表格、脚注、置信度提示都要保留在输出中视觉比对用view_image将提取文本与代表性渲染页面逐页对照渲染页面可用pdfSkill 的pdf_page_image.py参见 pdf/SKILL.md不猜不补对不确定的字符和字段要显式标记而不是凭猜测补全表格单独核验列对齐与数值需要单独逐一核对OCR 对表格数字的误识别率远高于正文返回映射关系尽可能同时给出提取产物路径与原始来源/页码的映射方便用户回溯验证。八、自动化测试如何守护这两个脚本仓库在 tests/test_ocr_documents.py 中为两个助手脚本提供了三个关键测试可作为理解脚本契约的权威参考test_helpers_expose_non_loading_help对两个脚本执行--help断言退出码为 0 且输出中包含--output。注意测试名中的 non-loading——--help路径不触发重型依赖导入保证在任何环境下都能查看用法test_marker_disk_check_does_not_import_marker执行extract_marker.py --check断言退出码为 0 或 1且输出中包含GB。这正是对检查不加载 marker这一设计的直接验证test_pymupdf_writes_requested_output用 PyMuPDF 现场生成一页含 OCR helper smoke test 文本的 PDF运行extract_pymupdf.py --output断言返回码为 0 且输出文件中包含该文本端到端验证了写文件 UTF-8 编码 文本提取全链路。这三个测试覆盖了无依赖可自检、轻量路径端到端可用两条关键承诺也是你在自己的环境中复现脚本行为的最小验证集。九、端到端实战示例综合以上内容一个完整的扫描 PDF 提取典型会话流程如下# 1. Agent 加载技能拿到 baseDirectory示意路径 # skill_view - base/skills/ocr-and-documents # 2. 先确认是否真的需要 OCR渲染第 1 页看内容 python3 base/skills/pdf/scripts/pdf_page_image.py scan.pdf -o rendered --pages 1-3 # 3. 用 view_image 查看渲染图确认是扫描件、需要提取的页码范围 # 4. 走轻量路径提取文本假设第 1~10 页 python3 base/skills/ocr-and-documents/scripts/extract_pymupdf.py scan.pdf --pages 0-9 -o extracted.md # 5. 若版式复杂表格/公式且资源允许先检查再走重量级路径 python3 base/skills/ocr-and-documents/scripts/extract_marker.py --check python3 base/skills/ocr-and-documents/scripts/extract_marker.py scan.pdf -o extracted_marker.md # 6. 渲染关键页用 view_image 与提取结果逐一比对标记不确定字符 # 7. 返回提取产物绝对路径 页码映射说明置信度限制整个过程无需任何外部 OCR 服务文档全程留在本机符合该技能本地优先、用户授权优先的核心理念。参考资源技能说明packages/ekko-agent/skills/ocr-and-documents/DESCRIPTION.md技能指南packages/ekko-agent/skills/ocr-and-documents/SKILL.md轻量提取脚本scripts/extract_pymupdf.py重型提取脚本scripts/extract_marker.py自动化测试tests/test_ocr_documents.py协作技能pdf/SKILL.md、docx/SKILL.md技能机制总览ekko-agent/README.md赞分享AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐IsaacLab 自碰撞过滤完整指南3 步配好机器人碰撞组让仿真不再自己撞自己IsaacLab 自碰撞过滤完整指南3 步配好机器人碰撞组让仿真不再自己撞自己 在 IsaacLab 机器人学习仿真框架里做机械臂、灵巧手这类多连杆任务人工智能强化学习机器人具身智能深度学习OCRmyPDF文本提取从扫描文档中提取结构化数据OCRmyPDF文本提取从扫描文档中提取结构化数据 你是否还在为无法编辑的扫描PDF烦恼是否曾因找不到文档中的关键信息而反复翻阅OCRmyPDFOptiOCRCLIEkko Studio原 Hermes Studio本地优先多智能体工作区架构、功能全景与部署实践Ekko Studio原 Hermes Studio本地优先多智能体工作区架构、功能全景与部署实践 Ekko Studio 是一个 local firstAI 应用人工智能AI Agent本地部署前端后端工作流自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考