ofdkit

ofdkit

軽量な Python ツールです。OFD ファイルを読み取り、テキストや請求書の項目を抽出し、AI ツールから利用できます。OFD は中国の国家標準の固定レイアウト文書形式（GB/T 33190）で、電子請求書や公文書によく使われています。

OFD 文書（GB/T 33190、中国の固定レイアウト形式で、電子請求書や公文書に使われています）を読み取るための軽量な Python ツールキットです。テキストや請求書の項目を抽出し、AI ツールから利用できます。

状態：0.4 版です。インターフェースは今後変更される可能性があります。更新記録は CHANGELOG をご覧ください。 状態：0.4 版です。API は今後変更される可能性があります。CHANGELOG をご覧ください。

できること / できること

• 請求書を確認：1 つのコマンドで請求書番号、日付、購入者、販売者、金額、明細を表示します。 1 つのコマンドで、請求書番号、日付、購入者、販売者、金額、明細を表示できます。
• フォルダー内の請求書を Excel にまとめたり、税務プラットフォームから一括ダウンロードした .zip アーカイブを直接読み込んだりできます。請求書番号はそのまま保持され（2.4E+19 のように変換されません）、金額はそのまま合計でき、重複した請求書には印が付きます。 フォルダー内の請求書、または税務サービスからダウンロードした .zip アーカイブを Excel ブックにまとめます。請求書番号はそのまま保持され、金額は数値として扱われ、重複には印が付きます。
• 経費精算をサポート：請求書の宛先（購入者名、税番号）が正しいか確認します。請求書の内容に基づいてファイル名を変更でき、プレビューや元に戻すこともできます。 経費精算用に、請求書の宛先が正しいか確認し、内容に基づいて請求書ファイルの名前を変更できます。プレビューと元に戻す機能もあります。
• テンプレートや複合オブジェクト内のテキストも含め、読み取り順にテキストを抽出します。 テンプレートや複合オブジェクト内のテキストも含め、読み取り順にテキストを抽出します。
• プログラムや AI で利用：請求書の項目を JSON で出力し、MCP サーバー、Agent Skill、MarkItDown プラグインを提供します。 プログラムや AI で利用するために、請求書の項目を JSON で出力し、MCP サーバー、Agent Skill、MarkItDown プラグインを提供します。
• Python 標準ライブラリのみを使用し、サードパーティーの依存関係はありません。パスの記述やエンコーディング、XML のプレフィックスなどに誤りがある、多くの不適合ファイルも読み取れます。 標準ライブラリのみを使用し、依存関係はありません。パスやエンコーディング、XML のプレフィックスに誤りがあるなど、多くの不適合ファイルを読み取れます。

クイックスタート / クイックスタート

1. Python 3.10 以降をインストールします。Windows では、インストール時に「Add python.exe to PATH」にチェックを入れてください。 Python 3.10 以降をインストールします。

2. コマンドラインを開き（Windows ではスタートメニューで「ターミナル」または「cmd」を検索し、Mac では「ターミナル」を開きます）、ofdkit をインストールします： ターミナルを開いて ofdkit をインストールします：

   pip install ofdkit
   

3. 請求書を確認します（ファイルをコマンドラインウィンドウにドラッグすると、パスが入力されます）： 請求書を表示します（ファイルをターミナルウィンドウにドラッグすると、パスを入力できます）：

   ofdkit 发票.ofd
   

   电子发票（普通发票）
   
   发票号码  00000000000000000001
   开票日期  2026-01-02
   购买方    测试单位甲
             税号 TESTBUYER0001
   销售方    测试单位乙
             税号 TESTSELLER0002
   金额      100.00
   税额      6.00
   价税合计  106.00
   明细      *测试*服务项目  100.00  6%
   开票人    测试人员
   

   （データは架空のものです / 架空のデータです）

4. フォルダーまたは .zip アーカイブ内のすべての請求書と合計を確認し、Excel にエクスポートします： フォルダーまたは .zip アーカイブ内のすべての請求書と合計を一覧表示し、Excel にエクスポートします：

   ofdkit 发票文件夹
   ofdkit batch 发票文件夹 -o 发票汇总.xlsx
   

   Excel ファイルには 2 つのシートがあります：「发票」には請求書ごとに 1 行が表示され、最後に合計が記載されます。「明细」には商品またはサービスごとに 1 行が表示されます。重複した請求書は黄色、読み取れないファイルは赤、その他の注意事項がある請求書（宛先が違う、金額が欠落している、または数値でない）はオレンジで示され、原因はすべて「提醒」欄に記載されます。合計には SUBTOTAL が使われるため、フィルター後は表示されている行だけが計算されます。数値でない金額は元のまま保持され、合計には含まれません。合計の下には該当する請求書の枚数が記載されます。 Excel ブックには 2 つのシートがあります：「发票」（請求書ごとに 1 行。合計が記載され、重複は黄色、読み取れないファイルは赤、その他の注意事項（宛先違い、金額の欠落や数値以外など）はオレンジで示され、それぞれの理由が記載されます）と「明细」（明細項目ごとに 1 行）です。合計には SUBTOTAL が使われるため、フィルターに応じて計算されます。

5. 請求書の宛先を確認します：--buyer を付けると、購入者名または税番号が自社のものと異なる請求書に印が付きます（Excel ではオレンジ色で表示されます）。両方を確認するには、2 回指定します： 請求書の宛先を確認します：--buyer を指定すると、購入者名または税番号が異なる請求書に印が付きます（Excel ではオレンジ色で表示されます）。両方を確認するには、2 回指定します：

   ofdkit 发票文件夹 --buyer 某某有限公司 --buyer 91310000XXXXXXXXXX
   

6. 請求書の内容に基づいてファイル名を変更します。たとえば、dzfp_2411…_20240528.ofd を 2024-05-28_某某公司_4449.00_2411….ofd に変更します。--apply を付けない場合はプレビューのみです。同じ名前の PDF、XML も一緒に変更されます（いずれか 1 つでも変更できない場合、その請求書のファイルはすべて元の名前のままです）。変更前に名前変更の記録が書き込まれ、記録を書き込めない場合はファイルを 1 つも変更しません。--undo を使うと、記録に基づいて元の名前に戻せます。何度実行しても問題ありません： 請求書の内容に基づいてファイル名を変更します。--apply を付けない場合はプレビューのみです。同じ名前の PDF、XML も一緒に変更されます（いずれか 1 つでも変更できない場合、その請求書のファイルはすべて元の名前のままです）。名前を変更する前にログが書き込まれ、書き込めない場合はファイルを一切変更しません。--undo を使うと、ログから元の名前に戻せます。繰り返し実行しても問題ありません：

   ofdkit rename 发票文件夹            # 预览 / preview
   ofdkit rename 发票文件夹 --apply    # 改名 / rename
   ofdkit rename --undo 发票文件夹/改名记录_20261028_093000.csv
   

   名前の形式は、たとえば --pattern "{开票日期}_{购买方}_{商品}" のように変更できます。使用できるフィールド：請求日、請求書番号、請求書コード、請求書の種類、販売者、販売者の税番号、購入者、購入者の税番号、金額、税額、税込合計、商品、元のファイル名。 名前の形式は --pattern で変更できます。フィールドの一覧は ofdkit rename --help にあります（{date}、{seller}、{total} などの英語名も使用できます）。

コマンドライン

ofdkit 文件.ofd                              # 看发票，不是发票就显示文字 / show an invoice, or the text
ofdkit 文件夹或压缩包.zip                     # 发票列表和合计 / list invoices with totals
ofdkit batch 文件夹 -o 发票汇总.xlsx          # 导出 Excel / export to Excel
ofdkit batch 文件夹 -o 发票汇总.csv           # 导出 CSV（给程序用）/ export CSV for programs
ofdkit 文件夹 --buyer 公司名或税号             # 检查发票抬头 / check the buyer
ofdkit rename 文件夹                         # 按内容改名（先预览）/ rename after contents (preview first)
ofdkit text 文件.ofd                         # 提取文字 / print text
ofdkit invoice 发票.ofd                      # 发票字段（JSON）/ invoice fields as JSON
ofdkit info 文件.ofd                         # 页数、作者等信息 / pages and metadata
ofdkit describe 文件.ofd -o 结构.json         # 打码的结构，用于报告问题 / masked structure for bug reports

show、batch、rename に -r を追加すると、サブフォルダーも対象になります。ofdkit PATH は ofdkit show PATH の省略形です。

ofdkit invoice の出力例（架空のデータ）：

{
  "invoice_number": "00000000000000000001",
  "invoice_code": null,
  "issue_date": "2026-01-02",
  "check_code": null,
  "machine_number": null,
  "buyer": {"name": "测试单位甲", "tax_id": "TESTBUYER0001", "address_phone": null, "bank_account": null},
  "seller": {"name": "测试单位乙", "tax_id": "TESTSELLER0002", "address_phone": null, "bank_account": null},
  "amount_without_tax": "100.00",
  "tax_amount": "6.00",
  "total_amount": "106.00",
  "issuer": "测试人员",
  "payee": null,
  "reviewer": null,
  "note": null,
  "items": [
    {"name": "*测试*服务项目", "specification": null, "unit": null, "quantity": null,
     "unit_price": null, "amount": "100.00", "tax_rate": "6%", "tax_amount": "6.00"}
  ],
  "sources": ["custom_tags"],
  "warnings": []
}

金額は小数の文字列なので、精度が失われません。合計が一致しない場合や、数値ではない金額（見つかった状態のまま保持されます）がある場合は、warnings に記録されます。集計では実際の数値だけを加算します。0 は 0 として扱い、欠落している金額と数値ではない金額は合計に含めず、not_summed に件数を記録します。

AI ツールから使用する

MCP サーバー

Claude、Codex、Cursor などの AI ツールで OFD ファイルを直接読み取れます。uv が必要です。すべてのツールは読み取り専用です。

公式 MCP Registry に io.github.Edgar-311/ofdkit として登録されています。このディレクトリに対応したツールでは、検索してインストールできます。

ツール	機能
read_ofd_text	読み取り順にテキストを抽出します。Markdown 形式とページ範囲を指定できます
read_ofd_invoice	請求書のフィールド
ofd_info	ページ数、サイズ、メタデータ
list_ofd_invoices	フォルダー内の請求書を集計します。必要に応じて購入者も確認できます

Claude Code:

claude mcp add ofdkit -- uvx --from "ofdkit[mcp]" ofdkit mcp

Claude Desktop、Cursor など、JSON 設定を使用するツール：

{
  "mcpServers": {
    "ofdkit": {
      "command": "uvx",
      "args": ["--from", "ofdkit[mcp]", "ofdkit", "mcp"]
    }
  }
}

Codex（~/.codex/config.toml）:

[mcp_servers.ofdkit]
command = "uvx"
args = ["--from", "ofdkit[mcp]", "ofdkit", "mcp"]

--root FOLDER を追加すると、そのフォルダー内のファイルのみを読み取るように制限できます。判定には各ファイルの実際の場所を使用します。そのため、フォルダー外を指すシンボリックリンクや Windows のディレクトリジャンクションは読み取られません。フォルダーの一覧表示では、それらをスキップして件数を記録します（skipped_outside_root）。

エージェントスキル

skills/ofd-reader は、AI エージェントに ofdkit コマンドラインを使う場面と方法を伝えます。Agent Skills に対応したツールで使用できます。このフォルダーを次の場所にコピーしてください。

• Claude Code: ~/.claude/skills/ofd-reader/
• Codex: ~/.codex/skills/ofd-reader/

MarkItDown プラグイン

MarkItDown は、さまざまなファイルを AI が読み取れる Markdown に変換するツールです。このプラグインをインストールすると、OFD も読み取れるようになります。

pip install "ofdkit[markitdown]"
markitdown --use-plugins 发票.ofd

Python

import ofdkit

with ofdkit.open("发票.ofd") as doc:
    print(doc.text())
    invoice = doc.invoice()        # 不是发票时返回 None / None if not an invoice
    if invoice:
        print(invoice.invoice_number, invoice.total_amount)

# 文件夹、.zip 压缩包或多个文件 / folders, ZIP archives or several files
for result in ofdkit.read_invoices("发票文件夹", recursive=True, buyer=["某某有限公司"]):
    if result.invoice:
        print(result.file, result.invoice.total_amount, "重复" if result.duplicate else "", result.buyer_mismatch)
    else:
        print(result.file, result.error)

読み取れないファイルの報告

実際の請求書をオンラインに投稿しないでください。次のコマンドでファイル構造をエクスポートし、GitHub issue に添付してください。テキスト、ファイル名、長い番号はマスキングされます。構造、座標、OFD 形式固有の名前（Doc_0、Content.xml）は保持されます。マスキングは可能な範囲で行うため、投稿する前にファイルを確認してください。

ofdkit describe 文件.ofd -o 结构.json

注意 / メモ

• ofdkit はファイルに記載された内容を読み取るだけで、請求書が本物かどうかは検証しません。真偽の確認には、国家税務総局の請求書検証プラットフォームを利用してください。 ofdkit はファイルの内容を報告します。請求書が本物かどうかは検証しません。
• 図形や画像として描かれた文字は読み取れません（OCR が必要ですが、本プロジェクトの対象外です）。 図形や画像として描かれた文字は抽出できません（OCR が必要ですが、本プロジェクトの対象外です）。
• 読み取り順序は位置から推測しています。本文は段ごとに、表は行ごとに読み取ります。複雑なレイアウトのページ（画像のある複数段組みの雑誌ページなど）では、正確に読み取れない場合があります。 読み取り順序は位置から推測しています。本文は段ごとに、表は行ごとに読み取ります。非常に複雑なページ（画像のある雑誌のレイアウトなど）では、完全に正確でない場合があります。

原則 / 原則

• OFD の読み取りのみを行います。請求書の作成や変更は行いません。 OFD のみを読み取ります。請求書の作成や変更は行いません。
• コードの大部分は AI（Claude）の支援を受けて作成されています。メンテナーが方針を決定し、リリースを承認します。 コードの大部分は AI の支援（Claude）を受けて作成されています。メンテナーが方針を決定し、リリースを承認します。

ライセンス / ライセンス

Apache-2.0