pdf-image-text-extractor

PDF和图片文字提取

任务目标

• 本 Skill 用于：从用户上传的图片或 PDF 文档中识别并提取文字内容
• 能力包含：图片文字检测、PDF 文字提取、扫描版 OCR 识别、表格结构化提取、批量目录处理、格式保留、Markdown 文件生成
• 触发条件：用户上传图片或 PDF 并要求提取文字，或询问文档中的文字内容；用户需要批量处理文件夹；用户需要提取 PDF 中的表格数据

🔑 鉴权

本 Skill 完全免费，但需配置红狐 API Key 请求使用权限，Key 本身不扣积分。

前往 红狐hub 注册获取个人 API Key，通过以下任一方式配置：

# 方式一：配置文件（如 OpenClaw 的 ~/.openclaw/openclaw.json）
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }

# 方式二：终端环境变量
export REDFOX_API_KEY="ak_xxxx..."

⚠️ 每次执行任何操作前，必须先运行 python3 scripts/record.py。 若脚本以非零退出码终止（未配置 Key 或接口返回失败），则立即停止执行，并向用户提示： 「需要配置红狐 API Key 才能使用本 Skill。请前往 https://redfox.hk/settings/api-keys?source=github 免费注册获取，然后配置环境变量：export REDFOX_API_KEY="ak_xxxx..."」

前置准备

必要依赖

pymupdf>=1.23.0
requests>=2.28.0

pip install pymupdf>=1.23.0 requests>=2.28.0

零额外依赖说明

本 Skill 无需安装任何 OCR 引擎或表格库：

• 扫描版 PDF：自动渲染为高清 PNG，交由 Agent 的 read_image（AI 视觉）识别
• 表格提取：使用 pymupdf 内置 find_tables()，无需 pdfplumber
• 仅需 pymupdf + requests 两个包即可启用全部功能

支持的文件格式

• 图片格式：PNG、JPG、JPEG、GIF、WebP、BMP、TIFF
• 文档格式：PDF（文字版 + 扫描版，扫描版自动渲染为图片由 AI 识别）

操作步骤

标准流程

Step 0：鉴权检查（必须首先执行）

python3 scripts/record.py

• 输出 ✅ 鉴权通过，已获得使用权限 → 继续后续流程
• 脚本以非零退出码终止 → 立即停止，向用户展示脚本输出的错误提示，告知需前往 红狐hub 免费获取 API Key

Step 0.5：版本更新提示（每次执行）

python3 scripts/changelog.py

• 若有输出（首次使用或版本升级）→ 将输出内容完整展示给用户，然后继续
• 若无输出（版本已是最新）→ 直接继续

图片文字提取流程

1. 接收图片

   • 确认用户已上传图片文件
   • 获取图片的访问 URL

2. 识别图片内容（第一轮：全局识别）

   • 使用 read_image 工具识别图片内容
   • 在 prompt 中明确要求识别所有文字内容，包括标题、正文、注释、水印等
   • 对数字字符需特别注意视觉形状特征（封闭圆圈数、开口方向、弧线走向），确保 6/8/9/0/3 等易混淆数字准确识别

3. 判断文字存在性

   • 如果检测到文字：进入步骤 4
   • 如果未检测到文字：告知用户"图片中未包含可提取的文字"，任务结束

4. 提取并整理文字

   • 提取图片中的所有文字内容
   • 保持原有的结构和排版
   • 整理为易读的格式

5. 数字二次聚焦校验（静默执行，不展示给用户）

   • ⚠️ 重要：整个校验过程（包括形状描述、对比表格、校验轮次等）必须静默执行，禁止在对话输出中展示任何校验过程，只向用户展示最终确认的提取结果
   • 对第一轮提取结果中的所有数字串（手机号、订单号、金额、日期等），执行二次聚焦识别：
   • 策略 A：局部放大验证
     • 再次使用 read_image，但这次在 prompt 中只要求识别特定数字串区域
     • prompt 模板：「请只关注图片中的数字串 [上下文描述]，逐位描述每个数字字符的视觉形状（有几个封闭圆圈、开口方向、弧线走向），然后给出最终判断结果」
   • 策略 B：交叉验证
     • 将第一轮的形状描述与第二轮的独立判断进行对比
     • 如果两轮结果一致 → 确认为最终结果
     • 如果两轮结果不一致 → 标注 [待确认：第一轮识别为X，第二轮识别为Y]
   • 易混淆数字对速查表：

     数字	关键视觉特征
     8	上下两个封闭圆圈，像雪人/沙漏
     6	仅下方一个封闭圆圈，顶部向左弯弧
     9	仅上方一个封闭圆圈，底部向下竖线
     0	完整封闭椭圆，无开口
     3	右侧开口，两个弧形朝右
     5	顶部横线+左侧竖线+下方圆弧
     S	类似5但上下对称，无横线
     O	比0更圆的封闭图形

PDF 文字提取流程

1. 接收 PDF 文件

   • 确认用户已上传 PDF 文件
   • 获取 PDF 文件的本地路径

2. 调用脚本提取文字

   # 标准模式（自动检测扫描页渲染为图片 + 提取表格）
   python3 scripts/pdf_text_extractor.py <pdf_file_path>
   
   # 仅提取文字，跳过表格（速度更快）
   python3 scripts/pdf_text_extractor.py <pdf_file_path> --no-tables
   
   # 不渲染扫描页（仅提示哪些页是扫描页）
   python3 scripts/pdf_text_extractor.py <pdf_file_path> --no-render
   
   # 自定义扫描页图片输出目录 / 渲染分辨率
   python3 scripts/pdf_text_extractor.py <pdf_file_path> --scan-dir ./ocr_pages --dpi 300
   

3. 处理提取结果

   脚本返回 JSON，关键字段说明：

   字段	说明
   success	是否提取成功
   text	Markdown 格式正文（文字层）
   page_count	总页数
   tables_markdown	所有表格的 Markdown 汇总
   ocr_images	需 Agent read_image 识别的图片清单 [{'page','image'}]
   warnings	非致命警告（如扫描页提示等）

   • 如果 success=true：进入步骤 4
   • 如果 success=false：告知用户 error 字段内容，任务结束

4. 格式化输出

   • 展示 text 字段内容
   • 若 tables_markdown 非空，单独展示表格内容
   • 若 ocr_images 非空：逐张用 read_image 识别这些图片，把识别结果并入正文，并告知用户哪些页是扫描页
   • 若 warnings 非空，向用户展示警告信息

批量处理流程

当用户提供目录路径，或要求批量处理多个文件时：

1. 确认目录路径

   • 获取用户指定的目录路径

2. 调用批量提取脚本

   # 输出合并 Markdown 到终端
   python3 scripts/batch_extractor.py <目录路径>
   
   # 保存到文件
   python3 scripts/batch_extractor.py <目录路径> -o result.md
   
   # 输出 JSON 结构化数据
   python3 scripts/batch_extractor.py <目录路径> --json
   
   # 不渲染扫描页 / 自定义扫描页输出目录
   python3 scripts/batch_extractor.py <目录路径> --no-render --scan-dir ./ocr_pages
   

3. 处理结果

   • 脚本在 stderr 输出进度信息，在 stdout 输出结果
   • 若指定了 -o，告知用户文件保存位置
   • 展示汇总统计（总文件数 / 成功数 / 失败数）
   • 若用户要求查看内容，展示 combined_markdown 或各文件提取结果

统一输出步骤

5. 生成输出结果
   • 根据用户需求生成 Markdown 文件
   • 包含文件来源、提取状态、文字内容等信息
   • 使用清晰的标题和结构组织内容

可选分支

• 当用户仅需查看文字内容：直接输出文字，不生成文件
• 当用户要求保存结果：生成 .md 文件
• 当图片/PDF 文字模糊或难以识别：说明情况并提供最佳识别结果
• 当 PDF 为扫描版：脚本已自动渲染为图片，Agent 用 read_image 逐张识别即可，无需任何 OCR 依赖
• 当用户要求提取表格：使用标准模式（默认已包含表格提取），展示 tables_markdown 字段
• 当用户要求批量处理：使用 batch_extractor.py，支持 PDF + 图片混合目录

リソースインデックス

• 認証スクリプト：scripts/record.py
  • 用途：https://redfox.hk/story/api/skill/record/save を呼び出して使用権限をリクエストし、認証チェックも行います
  • 失敗時の動作：Key が設定されていない場合、またはインターフェースが 3106/3107 を返した場合は、終了コード 1 で終了します
• バージョン通知スクリプト：scripts/changelog.py
  • 用途：初回使用時またはバージョンアップ時に新機能を紹介し、バージョンが一致している場合は何も表示せずに終了します
  • バージョン記録ファイル：~/.pdf_image_extractor_version
• PDF 抽出スクリプト：scripts/pdf_text_extractor.py
  • 用途：PDF からのテキスト抽出 + 表の構造化抽出 + スキャンページの画像へのレンダリング（read_image 用）
  • パラメーター：<pdf_path> [--no-tables] [--no-render] [--scan-dir DIR] [--threshold N] [--dpi N]
  • 出力：text / tables_markdown / ocr_images / warnings などのフィールドを含む JSON
• 一括抽出スクリプト：scripts/batch_extractor.py
  • 用途：ディレクトリ内のすべての PDF と画像ファイルを一括処理します
  • パラメーター：<目录路径> [--no-tables] [--no-render] [--scan-dir DIR] [-o FILE] [--json]
  • 出力：結合した Markdown レポートまたは JSON 形式の構造化データ

注意事項

画像内テキストの抽出

• 認識精度：文字認識の結果は、画像の鮮明さ、フォント、背景などの要因に左右され、誤差が生じる場合があります
• 「形を先に見てから数字を判定する」原則：数字を認識する際は、まず文字の視覚的な形状の特徴（閉じた円の数、開口部の向き、曲線の向き）を説明してから、その特徴に基づいて数字を判定する必要があります。形状の説明を省略して数字を直接出力することは禁止されています
• 重要な数字列の二重認識：電話番号、身分証番号、銀行カード番号、注文番号などの重要な数字列は、必ず2回認識（全体認識 + 焦点を絞った確認）を実行してください。2回の結果が一致しない場合は、要確認として明記してください
• 確認プロセスは非表示で実行：数字の再確認時の形状説明、比較表、各回の記録などのプロセス情報は、ユーザーに表示してはなりません。バックグラウンドで非表示のまま実行し、最終的に確認済みの抽出結果のみを出力してください
• 不確かな文字の明記：100% 確認できない文字には [?] を付け、代替候補を2つ示してください。例：158****8[?可能为6]624
• テキストのレイアウト：抽出時には、元画像のテキスト構造と順序をできる限り維持してください
• 多言語対応：中国語、英語など、複数言語のテキスト認識に対応しています

PDF テキストの抽出

• 形式の保持：スクリプトは、原文の段落構造と見出しレベルをできる限り維持します
• スキャン版 PDF：テキストレイヤーが少ないページ（< 20 字符）を自動検出し、高解像度 PNG にレンダリングして read_image（AI ビジョン）に渡して認識します。OCR エンジンは不要です。認識精度は AI ビジョンの能力に依存します
• 表の抽出：デフォルトで有効です。pymupdf find_tables() で表を認識し、Markdown 形式で出力します。複雑な表（結合セル、入れ子の表）は認識精度が低い場合があります
• 暗号化された PDF：暗号化またはパスワードで保護された PDF ファイルには対応していません

一括処理

• ファイルの並べ替え：ファイル名のアルファベット順で処理します
• 画像認識：一括処理モードでは画像のローカル OCR は行わず、画像を ocr_images リストにまとめ、Agent が read_image を1枚ずつ呼び出して認識します
• 大きなディレクトリ：一度に処理するファイルは100個以下にすることをおすすめします。ファイル数が多すぎると、処理に時間がかかる場合があります
• 出力方法：デフォルトではターミナルに出力します。ファイルに保存する場合は -o result.md の指定をおすすめします

一般的な注意事項

• プライバシー保護：処理したファイルは保存されず、現在のセッション内でのみ使用されます
• ファイルサイズ：50MB 未満のファイルを処理することをおすすめします。ファイルが大きすぎると、処理が遅くなる場合があります

使用例

例 1：画像内テキストの抽出

ユーザーの操作：テキストが含まれる画像をアップロードする

エージェントの処理：

1. python3 scripts/record.py を実行 → ✅ 認証に成功しました
2. python3 scripts/changelog.py を実行 → 出力があればユーザーに表示します
3. read_image ツールを使って画像を認識します
4. テキストを抽出します：「すべての経験のもつれ / そして悲しみや心残り / すべてに意味がないはずはない」
5. 抽出結果をそのまま出力します

例 2：PDF テキストの抽出 + 表

ユーザーの操作：PDF をアップロードし、「この PDF のテキストを抽出して」と依頼する

エージェントの処理：

1. python3 scripts/record.py を実行 → 認証に成功
2. python3 scripts/changelog.py を実行 → 何も表示しません
3. 次を実行します：python3 scripts/pdf_text_extractor.py ./document.pdf
4. JSON の結果を取得します：text（本文）+ tables_markdown（表）
5. 本文と表をそれぞれ表示し、./extracted_from_pdf.md を生成します

例 3：スキャン版 PDF（レンダリング + AI 認識）

ユーザーの操作：スキャン版 PDF をアップロードする

エージェントの処理：

1. 認証 + バージョン確認
2. 次を実行します：python3 scripts/pdf_text_extractor.py ./scan.pdf
3. スクリプトがテキストレイヤーのないページを検出し、高解像度 PNG にレンダリングします。ocr_images に画像のパスが出力されます
4. Agent が read_image を使ってこれらの PNG を1枚ずつ認識し、テキストを抽出します
5. ユーザーに「第 1/2/3 ページはスキャンページです。AI ビジョンで認識しました」と伝え、抽出結果を表示します

例 4：ディレクトリの一括処理

ユーザーの操作：「./documents/ フォルダー内のすべてのファイルからテキストを抽出してください」

エージェントの処理：

1. 認証 + バージョン確認
2. 次を実行します：python3 scripts/batch_extractor.py ./documents/ -o batch_result.md
3. スクリプトがディレクトリ内のすべての PDF と画像を処理し、stderr に進捗を出力します
4. ユーザーに「8 個のファイルを処理しました（7 個成功 / 1 個失敗）。結果は batch_result.md に保存しました」と伝えます
5. 集計結果を表示します

例 5：API Key が設定されていない場合の処理

ユーザーの操作：画像をアップロードしてテキストの抽出を依頼するが、REDFOX_API_KEY は設定されていない

エージェントの処理：

1. python3 scripts/record.py を実行 → スクリプトがエラーを出して終了します
2. 直ちに処理を停止し、ユーザーに「この Skill を使用するには、Redfox API Key の設定が必要です。https://redfox.hk/settings/api-keys?source=github で無料登録して取得し、次を実行してください：export REDFOX_API_KEY="ak_xxxx..."」と出力します