AILANG Parse

AILANG Parse

在 AILANG 中通用地解析并生成文档。从 DOCX、PPTX、XLSX、PDF 和图像文件中提取结构化内容，生成 JSON 和 Markdown；也可将文档写入 9 种格式。要编写文档，请先写 Markdown，再进行转换；请参阅使用 Markdown 编写文档。

Office 格式（DOCX、PPTX、XLSX）使用确定性的 XML 解析，无需 AI、无需云端，结果即时返回。PDF 默认使用确定性的 pdftotext 后端（poppler），同样无需 AI、无需云端；也可选择 docling 和 liteparse 作为本地替代方案，对于扫描版或仅含图像的 PDF，则会自动升级为本地 docling OCR。通过 --pdf-backend ai 可使用可插拔的 AI（Gemini、Claude、本地 Ollama），但不会自动选择 AI。图像交由你接入的任意 AI 模型处理。AILANG Parse 不依赖特定 AI：切换 --pdf-backend/--ai 即可更换后端，无需修改代码。

安装

有两种方式；两种都会在你的 PATH 中添加 docparse 命令，并将输出写入你解析的文件所在目录（使用 --output-dir DIR 或 DOCPARSE_OUTPUT_DIR 可更改）。

已经安装 AILANG？（本软件包版本需为 0.42.0 或更高，AILANG 需为 v0.40.0 dev 或更高）

ailang install sunholo/ailang_parse
docparse report.docx

软件包的 [bin] 表会在 ~/.ailang/bin 中为你提供一个垫片，直接从注册表缓存运行：解析单个文件，或使用 --convert 转换文件。这是一条有意保持精简的路径——不支持 describe/summarize、批处理模式、PDF 后端和 --install-backends（见下文）。可使用 ailang bin list / ailang bin uninstall docparse 管理它。

否则，或需要完整 CLI：

curl -fsSL https://www.sunholo.com/ailang-parse/install.sh | sh

此命令会获取已发布的软件包（约 400 KB），在你尚未安装 AILANG 运行时的情况下安装它，并将完整的 docparse 包装器（以及 docparse-audit 和 docparse-render）链接到 ~/.local/bin。支持 --version、--prefix 和 --uninstall；重复运行不会产生任何影响。如果你同时安装了两种方式，ailang install 会告知 docparse 会解析到哪一个。

以上涵盖所有确定性格式。PDF 还需要另外两项，而且很容易忽略：

brew install poppler        # pdftotext, the default PDF backend
                            # (apt install poppler-utils on Debian/Ubuntu)
docparse --install-backends # docling + liteparse, for scans and layout

即使你从不传入 --pdf-backend，--install-backends 也很重要：当 pdftotext 找不到文本层时，解析器会自动升级到 docling，因此没有安装它，扫描版 PDF 就无法使用默认后端解析。AI 后端使用 Google ADC（gcloud auth application-default login）进行身份验证，而不是使用 API 密钥。

git clone https://github.com/sunholo-data/ailang-parse.git
ln -s "$(pwd)/ailang-parse/bin/docparse" /usr/local/bin/docparse

SDK

使用你选择的语言调用 AILANG Parse：

pip install ailang-parse          # Python
npm install @ailang/parse         # JavaScript/TypeScript
go get github.com/sunholo-data/ailang-parse-go  # Go

快速入门

# Office documents (deterministic, no AI needed)
docparse report.docx
docparse slides.pptx
docparse spreadsheet.xlsx

# PDF (deterministic pdftotext by default — no AI); images (AI auto-enabled)
docparse document.pdf
docparse photo.png

# Options
docparse report.docx describe        # AI image descriptions
docparse report.docx summarize       # AI document summary
docparse contract.pdf                # PDF: deterministic pdftotext (default)
docparse scan.pdf                    # Scanned PDF: escalates to local docling OCR
docparse scan.pdf --pdf-backend ai --ai gemini-2.5-flash  # External AI (paid), opt-in only

# Format conversion
docparse report.docx --convert output.html
docparse data.csv --convert report.docx
docparse notes.md --convert slides.pptx
docparse notes.md --convert offer.docx --reference-doc letterhead.docx

# AI document generation
ailang run --entry main --caps IO,FS,Env,AI --ai gemini-2.5-flash \
  docparse/main.ail --generate report.docx --prompt "Q1 sales report with tables"

输出

每次运行都会在当前目录中生成以下文件（使用 --output-dir DIR 或 DOCPARSE_OUTPUT_DIR 可更改）：

• <filename>.json — 包含类型化块的结构化 JSON
• <filename>.md — 适用于大模型的 Markdown

AILANG Parse 的提取内容

OfficeDocBench v2（87 个文件、11 种格式、8 项指标）：AILANG Parse PR #115 候选版本的综合得分为 97.7%，覆盖率为 100.0%。比较了九种适配器，其中包括标准模式下的 LlamaParse。现在，经过源文件验证的结构断言会测量单元格位置、批注目标、列表层级、格式、公式、颜色以及幻灯片/备注关系。方法和结果。

支持的格式

解析（16 种格式）： DOCX、PPTX、XLSX、ODT、ODP、ODS、HTML、Markdown、CSV、EPUB、EML、MBOX、TEX、RTF、PDF、图像（JPG/PNG）

生成（9 种格式）： DOCX、PPTX、XLSX、ODT、ODP、ODS、HTML、Markdown、QMD（Quarto）

使用 Markdown 编写文档

Markdown 是大模型可以编写的输入格式，因此它是生成文档的实用方式：编写 Markdown，然后转换为九种输出格式中的任意一种。

docparse report.md --convert report.docx

转换后保留的内容：YAML front matter（标题／作者／日期 → 文档属性）、粗体/斜体/代码/删除线等真正的字符格式、真正的超链接、图片（读取并嵌入本地路径）、围栏代码块、引用块、嵌套列表、分隔线，以及带对齐方式和列跨度的表格。

Markdown 没有页眉、页脚、注释和修订记录的语法；从已经包含这些内容的文档转换时，这些内容会保留。

本地文档验证（v0.41.2+）

docparse-audit 和 docparse-render 是 CLI 的 AILANG 配套工具。AILANG Parse v0.41.2 要求 AILANG 0.35.0 或更高版本。它们在本地运行，无需托管账户。安装程序会在已安装的版本中提供这些工具时将其链接起来；在代码检出目录中使用 ./bin/docparse-audit 和 ./bin/docparse-render。

docparse-audit report.docx --strict
docparse-render report.docx --output-dir qa/report
docparse-render before.docx --compare after.docx --output-dir qa/comparison

只读 DOCX 审计会输出 JSON 清单，并报告表格网格和页眉、标题间断、图片描述、链接、注释和字段方面的问题。审计完成时退出码为 0，使用 --strict 且发现问题时为 1，输入无法读取时为 2。这是一项有范围限制的结构检查；它不会认证无障碍性，也不会解析任意样式继承。

渲染支持 .docx、.odt、.pptx、.xlsx 和 .pdf。处理 Office 输入时，请安装 LibreOffice 和 Poppler；处理 PDF 只需 Poppler。无需新增 Python 依赖。使用 --soffice / --pdftoppm（或 DOCPARSE_SOFFICE / DOCPARSE_PDFTOPPM）选择工具。--dpi 默认值为 144，--timeout 默认值为每个进程 120 秒。输出目录必须是新目录。每份文档都会生成一个 PDF 和编号的 PNG 页面；清单会记录源文件哈希、工具路径和页面目录。比较功能使用未压缩的栅格哈希来识别更改、新增和删除的页面。请并排检查两组 PNG；不会生成差异叠加图。visual_review: pending 表示仍需检查页面图像。

实现位于 docparse/services/document_render.ail 和 docparse/services/docx_audit.ail；回归验证也使用 AILANG：

ailang run --entry main --caps IO,FS,Env,Process \
  --process-allowlist "true,false,mktemp,mkdir,$(command -v soffice),$(command -v pdftoppm)" \
  --process-timeout 120s scripts/verify_document_quality.ail -- \
  /tmp/docparse-quality-new "$(command -v soffice)" "$(command -v pdftoppm)"

使用模板设置生成的 DOCX 样式

--reference-doc 是 Quarto/Pandoc 的 reference-doc 功能：现有的 .docx 提供外观，Markdown 提供内容。

docparse annex.md --convert annex.docx --reference-doc letterhead.docx

生成的表格使用所选节的可用宽度，并为列设置有界的内容权重，同时重复语义表头。合并单元格的宽度为其覆盖列的宽度之和。

模板的 styles.xml、numbering.xml、主题、嵌入字体、页眉、页脚和页面设置都会应用到新内容中。合并过程不会重新生成的所有内容都会逐字节保留，因此信笺抬头、徽标和授权字体的呈现效果与原文件完全一致。

各部分内容的来源：

以下两点值得注意：

• 模板的页眉和页脚优先。 源文档自带的页眉会被丢弃，不会与信笺抬头混合。所有页面装饰都位于模板正文的 <w:sectPr> 中，并会整体提取。
• 模板的批注会随正文一起被丢弃，commentsExtended.xml 和 people.xml 也会被丢弃。源文档中的批注仍会保留。

以下两个标志可调整包含多个节的模板：

• --reference-section N 用于选择提供页面设置、页眉和页脚的模板节；1 表示第一个节，按照 Word 的编号方式。默认值是最后一个节（正文级别的节，也是未指定标志时始终会提取的节）。多节模板中所需的页面装饰通常位于更早的节中，例如主协议中的 CONFIDENTIAL 页脚，而不是附件中缺失的页脚。
• --table-style NAME 将生成的表格绑定到模板定义的表格样式（先按 styleId 匹配，再按样式名称匹配）。如果不指定，模板中有名为 Table 的样式时就使用该样式，否则使用第一个非隐式 Normal Table 表格样式。绑定样式后，生成器不再输出自己的硬编码边框，而由该样式提供边框。

无法读取或不是 DOCX 格式的引用文件会导致错误，且不会写入任何内容——静默回退到内置样式可能会生成看似正常、却恰好缺少所需信笺抬头的文件。仅支持 DOCX 输出。

架构

docparse/
├── types/document.ail           # Block ADT (11 variants)
├── services/
│   ├── format_router.ail        # Format detection (36 inline tests)
│   ├── zip_extract.ail          # ZIP layer (9 inline tests)
│   ├── docx_parser.ail          # DOCX XML → Blocks (6 inline tests)
│   ├── pptx_parser.ail          # PPTX slides → Blocks
│   ├── xlsx_parser.ail          # XLSX worksheets → Blocks
│   ├── direct_ai_parser.ail     # PDF/image → Blocks (AI)
│   ├── layout_ai.ail            # AI self-healing (optional)
│   ├── output_formatter.ail     # JSON + markdown output
│   └── docparse_browser.ail     # WASM browser adapter
└── main.ail                     # CLI entry point

共 91 条契约和 50 多项内联测试。其中 14 条由 Z3 直接证明；其余契约在 CI 中通过 --prove／--verify-contracts 在运行时检查，并因解析器代码具有递归和高阶特性（不属于 Z3 的可判定片段）而跳过静态检查。

AI 配置

AILANG Parse 使用 AILANG 的 AI effect——AILANG 支持的任何模型都可以使用：

docparse scan.pdf --ai gemini-2.5-flash          # Google (default; fast)
docparse scan.pdf --ai gemini-3-flash-preview    # Google (slower; thinking model)
docparse scan.pdf --ai granite-docling           # Local Ollama (free)
docparse scan.pdf --ai claude-haiku-4-5          # Anthropic

AI 用量受能力预算限制（main 上的 AI @limit=200），因此成本可预测。

开发命令

docparse --check       # Type-check all modules
docparse --test        # Run inline tests
docparse --prove       # Static Z3 contract verification

基准测试

uv run benchmarks/run_benchmarks.py --suite office     # Structural (no API, instant)
uv run benchmarks/run_benchmarks.py --suite pdf         # PDF extraction (needs AI)
uv run benchmarks/run_benchmarks.py --competitors       # Compare to Docling etc.

详情请参阅 benchmarks/。

许可证

Apache 2.0