glmocr-handwriting

GLM-OCR 手書き文字認識スキル / GLM-OCR 手写体识别技能

ZhiPu GLM-OCR のレイアウト解析 API を使用して、画像や PDF から手書き文字を認識します。

使用する場面 / 使用场景

• 手書きのメモ、手紙、文書から文字を抽出する / 从手写笔记、信件或文档中提取文字
• 手書き文字を編集可能なテキストに変換する / 将手写内容转为可编辑文本
• 手書き文字と印刷文字が混在する内容を認識する / 识别手写和印刷混排内容
• 手書きの数式、ラベル、注釈を読み取る / 读取手写公式、标签或批注
• ユーザーが「handwriting OCR」「recognize handwriting」「手写识别」「手写体OCR」「识别手写字」と言及した場合

主な機能 / 核心特性

• 複数のスタイルに対応：筆記体やブロック体など、さまざまな手書きスタイルを処理できます
• 多言語対応：中国語、英語、および複数言語が混在する手書き文字に対応しています
• 混在したコンテンツ：手書き文字と印刷文字の両方を含む文書を認識できます
• ローカルファイルと URL：ローカルファイルとリモート URL の両方に対応しています

リソースリンク / 资源链接

リソース	リンク
API キーの取得	智谱开放平台 API Keys
API ドキュメント	版面解析 / 版面解析

前提条件 / 前置条件

API キーの設定 / API Key 配置（必須 / 必需）

スクリプトは ZHIPU_API_KEY 環境変数からキーを取得します。他の Zhipu スキルと同じキーを共有できます。 This script reads the key from the ZHIPU_API_KEY environment variable. Reusing the same key across Zhipu skills is optional.

キーの取得 / 获取 Key： 智谱开放平台 API Keys にアクセスして、キーを作成またはコピーします。

設定方法 / 配置方式（いずれか1つ）：

1. グローバル設定（推奨） / 全局配置（推荐）： openclaw.json の env.vars で一度設定すると、すべての Zhipu スキルで共有されます：

   {
     "env": {
       "vars": {
         "ZHIPU_API_KEY": "你的密钥"
       }
     }
   }
   

2. スキル単位の設定 / Skill 级别配置： openclaw.json でこのスキルのみを対象に設定します：

   {
     "skills": {
       "entries": {
         "glmocr-handwriting": {
           "env": {
             "ZHIPU_API_KEY": "你的密钥"
           }
         }
       }
     }
   }
   

3. Shell 環境変数 / Shell 环境变量： ~/.zshrc に追加します：

   export ZHIPU_API_KEY="你的密钥"
   

💡 他の Zhipu スキル（glmocr、glmv-caption、glm-image-generation など）ですでにキーを設定している場合、それらは同じ ZHIPU_API_KEY を共有するため、設定し直す必要はありません。

セキュリティと透明性 / 安全与透明度

• 使用する環境変数：
  • ZHIPU_API_KEY（必須 / 必需）
  • GLM_OCR_TIMEOUT（タイムアウト秒数、任意 / 可选超时秒数）
• 固定された公式エンドポイント： https://open.bigmodel.cn/api/paas/v4/layout_parsing
• カスタム API URL の上書きには非対応： リダイレクトされたエンドポイントを介したキーの意図しない流出を防ぎます。
• 上流からの生レスポンスは任意： デバッグで必要な場合にのみ --include-raw を使用します。

⛔ 必須の制限事項 / 强制限制 ⛔

1. GLM-OCR API のみを使用してください — スクリプト python scripts/glm_ocr_cli.py を実行します
2. 自分で手書き文字を解析しないでください — 内蔵のビジョン機能やその他の方法で手書き文字を読もうとしないでください
3. 代替案を提示しないでください — 「読んでみます」などと提案しないでください
4. API が失敗した場合 — エラーメッセージを表示し、直ちに停止してください
5. フォールバック方法を使用しないでください — 他の方法で手書き文字を認識しようとしないでください

📋 出力の表示ルール / 输出展示规则

スクリプトの実行後、OCR 結果を明確かつ安全に提示してください。

• 抽出された手書き文字（text）をすべて表示します
• 要約してもかまいませんが、重要な抽出エラーを隠さないでください
• 結果ファイルが保存された場合は、ユーザーにファイルパスを伝えます
• 上流からの生レスポンスは、明示的に求められた場合またはデバッグの場合にのみ表示します（--include-raw）

使用方法 / 使用方法

URL から認識する / 从 URL 识别

python scripts/glm_ocr_cli.py --file-url "https://example.com/handwriting.jpg"

ローカルファイルから認識する / 从本地文件识别

python scripts/glm_ocr_cli.py --file /path/to/notes.png

結果をファイルに保存する / 保存结果到文件

python scripts/glm_ocr_cli.py --file notes.png --output result.json --pretty

上流からの生レスポンスを含める（デバッグ専用） / 包含原始上游响应（仅调试）

python scripts/glm_ocr_cli.py --file notes.png --output result.json --include-raw

CLI リファレンス / CLI パラメーター

python {baseDir}/scripts/glm_ocr_cli.py (--file-url URL | --file PATH) [--output FILE] [--pretty] [--include-raw]

パラメーター	必須	説明
--file-url	いずれか	画像／PDF の URL
--file	いずれか	画像／PDF のローカルファイルパス
--output, -o	いいえ	結果の JSON をファイルに保存
--pretty	いいえ	JSON 出力を整形して表示
--include-raw	いいえ	result フィールドに上流 API の生レスポンスを含めます（デバッグ専用）

レスポンス形式

{
  "ok": true,
  "text": "Recognized handwritten text in Markdown...",
  "layout_details": [...],
  "result": null,
  "error": null,
  "source": "/path/to/file",
  "source_type": "file",
  "raw_result_included": false
}

主なフィールド：

• ok — 認識に成功したかどうか
• text — Markdown 形式で抽出されたテキスト（表示にはこれを使用します）
• layout_details — レイアウト分析の詳細
• error — 失敗時のエラー詳細

エラー処理

API キーが設定されていない場合：

ZHIPU_API_KEY not configured. Get your API key at: https://bigmodel.cn/usercenter/proj-mgmt/apikeys

→ エラーをそのままユーザーに表示し、設定方法を案内します

認証に失敗した場合（401/403）： API キーが無効または期限切れです → 再設定してください

レート制限（429）： クォータを使い切りました → 待つようユーザーに案内します

ファイルが見つからない場合： ローカルファイルが見つかりません → パスを確認してください