ExStruct

ExStruct 是一个面向 LLM/RAG 预处理与 AI Agent 自动化场景的 Excel 结构化提取引擎。它将 Excel 工作簿中的单元格、公式、形状、图表、SmartArt、表格候选区、合并单元格范围、打印区域、超链接等富元素转换为结构化 JSON/YAML/TOON 输出。

提取能力#

引擎提供四种提取模式（light / libreoffice / standard / verbose），采用 Windows COM → LibreOffice UNO → 纯 Python OOXML 三级降级架构，在任意环境下均能安全运行不崩溃。

• light：纯 Python OOXML，单元格 + 表格候选 + 打印区域 + 最佳努力形状/图表（无 COM）
• libreoffice：LibreOffice UNO 桥接，.xlsx/.xlsm 最佳努力富提取；LO 可用时增加合并单元格、形状、连接器、图表
• standard：Excel COM，文本形状 + 箭头、图表、SmartArt、合并单元格范围
• verbose：Excel COM，所有形状（含宽高）+ 超链接 + colors_map

表格检测算法基于 numpy/scipy 启发式，支持通过 table_score_threshold、density_min、coverage_min、min_nonempty_cells 等参数动态调整。支持公式提取（formulas_map）、后端溯源元数据（provenance / approximation_level / confidence）。

编辑能力#

编辑侧采用 JSON patch 操作模型，支持 dry-run 试运行 → 检查 warnings/diff → 确认执行的可审查工作流，避免不可逆修改。提供 CLI（exstruct patch / exstruct make）和 Python API（exstruct.edit）两种调用方式，支持 --backend openpyxl/auto 后端选择。

集成方式#

• CLI：exstruct 命令行，支持管道，可输出 JSON/YAML/TOON，支持按 sheet 分文件输出
• Python API：exstruct.extract、exstruct.export、exstruct.edit、set_table_detection_params()
• MCP Server：内置 stdio 传输的 MCP Server，提供 10 个工具（含 exstruct_extract、exstruct_patch、exstruct_make、exstruct_capture_sheet_images 等），推荐通过 uvx --from 'exstruct[mcp]' exstruct-mcp 启动
• Agent Skill：仓库内 .agents/skills/exstruct-cli/SKILL.md，可通过 npx skills add 安装

渲染与输出#

可选渲染功能支持 PDF/PNG 导出（需 Excel COM + pypdfium2 + Pillow）。输出格式支持 JSON（紧凑/美化）、YAML（exstruct[yaml]）、TOON（exstruct[toon]）。

构建与质量#

构建系统为 uv_build（requires uv_build>=0.8.4）。代码质量体系包括 Ruff linting、mypy strict 类型检查、pytest + 覆盖率 ≥80%（集成 Codecov 与 Codacy）、pre-commit hooks。文档使用 MkDocs Material + mkdocstrings-python 自动生成 API 文档 + JSON Schema 自动生成。仓库内含 benchmark/ 子目录用于提取与评估管线基准测试。

安装与要求#

要求 Python ≥ 3.11，通过 PyPI 分发，BSD-3-Clause 许可证。

pip install exstruct                    # 基础安装
pip install exstruct[yaml,toon,render]  # 全部可选功能
pip install exstruct[mcp]               # MCP Server

最快上手：exstruct input.xlsx > output.json，无需任何配置即可在 light 模式下获得结构化 JSON。