v0.4.0

可靠性修复：describe 打码更严、MCP --root 不会被链接绕过、读不出的金额不再按 0 汇总、rename 先写恢复记录再改名。
Reliability fixes: stricter masking in describe, MCP --root that links cannot get around, amounts that are not numbers no longer summed as 0, and rename that writes its undo log before renaming.

pip install --upgrade ofdkit

Fixed

• ofdkit rename --apply used to rename files first and write the --undo log last. Now the log is created before anything is renamed (if it cannot be, nothing is renamed), each rename is written to it and flushed to disk before it happens, and renaming stops if a line cannot be written. An OFD file and its PDF or XML copies are renamed together: if one fails, the others go back to their old names. --undo can be run more than once.
• Amounts that are not numbers were summed as 0 without a word. Such a value is now kept as found and noted in the invoice's warnings; sums add only plain decimal numbers (a real 0.00 still counts); the summary's new not_summed counts, for each amount, the invoices where it is missing or not a number. The command line, the Excel workbook and the MCP tool all use this rule.
• MCP --root: list_ofd_invoices could read OFD files behind links inside the allowed folder (a symbolic link to a file elsewhere, or a Windows directory junction in a recursive listing). Every file is now checked by its real location right before it is opened, links to folders outside are not entered, and listings report skipped_outside_root.
• ofdkit describe copied entry names, locations (FileLoc, DocRoot, BaseLoc ...) and ASCII attribute values as they were. Now only the OFD layout's own names are kept, other path parts are masked the same way wherever they appear so references can still be followed, other attribute values and runs of seven or more digits are masked. Masking is a best effort: check the output before sharing it.

Changed output: summaries gain not_summed, MCP listings gain skipped_outside_root, and describe output masks more.

v0.3.1

在官方 MCP Registry 上架：支持这个目录的 AI 工具可以直接搜到并安装 ofdkit。
Listed in the official MCP Registry, so AI tools that read it can find and install ofdkit.

Added

• Listed in the official MCP Registry as io.github.Edgar-311/ofdkit, so MCP clients and directories that read the registry can find and install the server. server.json describes it, and the release workflow publishes every new version there.

v0.3.0

报销帮手：按发票内容给文件改名（可以预览、可以改回去），检查发票抬头。
For reimbursement: rename invoice files after their contents (with a preview and an undo), and check who invoices are made out to.

pip install --upgrade ofdkit
ofdkit rename 发票文件夹                    # 预览新名字 / preview the new names
ofdkit rename 发票文件夹 --apply            # 改名 / rename
ofdkit 发票文件夹 --buyer 某某有限公司       # 检查抬头 / check the buyer

Added

• ofdkit rename: renames invoice files after their contents, by default as {开票日期}_{销售方}_{价税合计}_{发票号码}.ofd. It only previews until --apply is given, renames PDF and XML copies with the same name along with the OFD file, never overwrites a file (a clashing name gets (2)), leaves files that already have their new name alone, and writes a log that ofdkit rename --undo LOG uses to restore the old names. --pattern sets the format from 13 fields, in Chinese or English.
• --buyer NAME_OR_TAX_ID for show and batch: flags invoices made out to another buyer (发票抬头), in the summary, the CSV warnings and in orange in Excel. The MCP tool list_ofd_invoices and ofdkit.read_invoices() take buyer too.
• py.typed, so type checkers use ofdkit's annotations.

v0.2.0

导出 Excel、直接读 .zip 压缩包、一条命令看发票，命令行改成中文；阅读顺序更准，新增发票种类。
Excel export, ZIP archives, a one-command invoice view and a Chinese command line; better reading order and the invoice type.

pip install --upgrade ofdkit
ofdkit 发票.ofd                           # 看一张发票 / show an invoice
ofdkit batch 发票文件夹 -o 发票汇总.xlsx   # 汇总到 Excel / summarise into Excel

Added

• Excel output: ofdkit batch FOLDER -o 发票汇总.xlsx writes a workbook, still with only the standard library. Invoice numbers, codes and tax IDs stay text (in a CSV, Excel turns a 20-digit 数电票 number into 2.4E+19), amounts are numbers and dates are dates. A totals row follows filters; duplicates and unreadable files are coloured and explained; a second sheet lists every line item.
• ZIP archives: batch, show and the MCP tool list_ofd_invoices read the .ofd files inside .zip archives, such as a batch download from the tax service.
• ofdkit show, and the shortcut ofdkit PATH: an invoice as aligned Chinese text, another document's text, or a table of the invoices in folders and archives with totals.
• ofdkit.read_invoices() reads files, folders and archives into InvoiceFile results.
• Totals without duplicates, and sums of amounts and tax, in the batch summary and list_ofd_invoices; an item_names column in the CSV.
• ofdkit describe: the file's structure as JSON with all text masked, so problems can be reported without sharing an invoice. GitHub issue forms ask for it instead of the file.
• invoice_type: the invoice type as printed in its title, such as 电子发票（增值税专用发票） or 上海增值税电子普通发票.

Changed

• Better reading order. Vertical labels such as 购买方信息 and 备注 are read as words; columns of prose are read column by column, tables still row by row.
• Command-line help and messages are in Chinese. text and show say when a file has no text at all, which usually means a scan.
• The CSV from batch has new invoice_type and item_names columns.

Fixed

• Older invoices that share a number but have different invoice codes are no longer flagged as duplicates.
• Output piped into a program that stops reading early, such as head, no longer ends with an error.
• The MCP tool read_ofd_text with a page range no longer fails when one page in the range is damaged.

Four new reading-order samples in ofd-samples check these changes on every commit.

v0.1.0

ofdkit 的第一个版本：用 Python 读取 OFD 文件（GB/T 33190），提取文字和电子发票字段，并接入 AI 工具。
The first release: read OFD documents (GB/T 33190) in Python, extract text and e-invoice fields, and use them from AI tools.

pip install ofdkit                 # 核心，无依赖 / core, no dependencies
pip install "ofdkit[mcp]"          # MCP 服务器 / MCP server
pip install "ofdkit[markitdown]"   # MarkItDown 插件 / MarkItDown plugin

Added

• Read OFD documents with only the Python standard library: pages, templates, page blocks and composite graphic units, tolerant of common producer bugs (absolute or wrongly cased paths, GBK names and encodings, broken XML prefixes).
• Text extraction in reading order, as plain text or Markdown.
• Invoice fields from e-invoices (数电票 and 增值税电子发票), from XML attachments, custom tags and OFD.xml metadata, with amounts and dates normalised and a warning when totals do not add up.
• Command line: ofdkit info, text, invoice, batch (CSV for Excel, duplicate invoice numbers flagged) and mcp.
• MCP server for AI tools, read-only, with an optional folder restriction.
• MarkItDown plugin.
• The ofd-reader Agent Skill.

Tested on every commit against the shared ofd-samples files. Most of the code was written with AI assistance (Claude); see the README.