refigure

refigure

图表转换后，图表数据依然完整。

DOCX/XLSX → Markdown，保留图表和信息图中的机器可读数据，而不是让它们在 OCR 或视觉模型处理中丢失：从原生 OOXML 图表数据（numCache/strCache）中还原精确数值，无需调用 GPU 或 VLM，也不会损失精度——这就是默认方式，而非备用方案。

这条默认路径也是基础安装（pip install "refigure[docx,xlsx]"）比基于 PyTorch 的替代方案轻约 500 倍（5.6MB，而替代方案有数 GB）的原因——核心转换完全不需要 ML 模型。这个数据反映的是核心架构，而非所有分发格式：Docker 镜像有意增大体积，打包了 VLM 提供方和 LibreOffice，以便开箱即用地处理复合图表（见下文 Docker）。

只有极少数图表完全没有原生数据（例如仪表盘截图）时，才需要 VLM 进行解读——无论采用哪种分发格式，从图表中获取真实数值都不需要 VLM。

提供库、CLI、MCP 服务和一键安装的 Claude Desktop 套件——所有入口都返回保留原生精度的相同结果，不会向 Agent 提供降级后的摘要。

功能

• 原生图表数据提取——直接读取 OOXML numCache/strCache，图表无需经过栅格化、OCR 或 VLM 步骤，每次都能获取真实数值。
• 组合图形的定位零损失标记（DOCX）——mammoth 原本会将组合形状/信息图静默拆散为互不相连的片段，现在会为其生成清晰的标记，并保留位置和所有标题文字。即使资金充足的现有方案也不具备此功能——参见 Docling issue #1287。
• 可选的 VLM 解读（DOCX 组合图形，[vlm] 扩展包、--vlm/Config(use_vlm=True)）——在零损失基础上，为完全没有原生图表数据的图形（例如仪表板截图）提供云端描述和真正渲染的 mermaid 图表（支持 26 种图表类型——流程图、饼图/XY 图、时序图/状态图/ER 图、甘特图/时间线/桑基图/树图等，参见下文的状态）。不依赖特定提供商——默认使用 OpenRouter，也可通过 --vlm-provider 直接连接 OpenAI/Ollama/vLLM/LM Studio/Anthropic（[vlm-direct] 扩展包）。--strict 会将一种特定故障（系统缺少 soffice/LibreOffice 二进制文件）从优雅跳过升级为硬错误；其他所有 VLM 故障仍会降级处理。
• 丰富的类型化结果——ConversionResult（Markdown + 警告 + 图表/组合图形计数 + vlm_used），而非单纯的字符串。
• 内置 CLI——refigure 控制台命令，以标准输入/输出为先，支持原生批处理模式和类型化退出码（见下文）。
• 内置 MCP 服务——refigure-mcp 控制台命令（[mcp] 扩展包），支持 stdio 或 Streamable HTTP，提供工具/资源/提示词，支持按文件隔离的批量转换（见下文）。
• Docker 镜像——ghcr.io/helgdemidov/refigure，两个控制台命令均已加入 PATH，并内置 soffice/LibreOffice——VLM 组合图形处理路径开箱即用，无需手动安装 LibreOffice。支持多架构——linux/amd64 + linux/arm64，兼容原生 Apple Silicon（见下文）。
• 适用于 Claude Desktop 的 .mcpb 捆绑包——一键安装，无需终端（仅支持 docx+xlsx，见下文）。

演示

可选的 VLM 解读 — 针对完全没有原生图表数据（是截图，而不是 OOXML 图表部件）且没有匹配的 mermaid 结构的图形，例如（a）密集的放射状旭日图——原有的 4 种 mermaid 类型都无法表示它。--vlm 不仅能还原真实内容，还能生成真正可渲染的图表，而不只是还原文本：

原生图表数据提取 — 提取真实的 OOXML numCache，不是截图，也不是 OCR：

相同的提取方式，也适用于 DOCX — Word 也会嵌入原生图表，不只有 Excel；无论哪种格式，refigure 读取的都是相同的 OOXML 缓存数据：

组合图形 — 即使图形本身无法渲染，也能保留位置且不丢失任何内容（目前没有其他工具能做到这一点——参见 Docling issue #1287， 该问题已开放超过 1 年）：

快速开始

pip install "refigure[docx,xlsx]"

refigure report.docx                      # markdown to stdout

from refigure.docx import convert

result = convert("report.docx")
print(result.markdown)
print(f"{result.charts_found} charts, {result.groups_found} composite figures")

也可以通过 uv/uvx 使用，无需永久安装：

uvx --from "refigure[docx,xlsx]" refigure report.docx

对于图表引擎无法独立重建的组合图形，可选用 VLM 解读（参见上方的功能介绍）：

pip install "refigure[docx,vlm]"
export OPENROUTER_API_KEY=...                 # or --vlm-api-key-file/--vlm-provider
refigure report.docx --vlm                    # needs the system soffice/LibreOffice binary too

安装与使用

一个转换器，四种运行方式——选择最适合你工作流的方式。点击标题可展开。

refigure report.docx                      # markdown to stdout
refigure report.docx -o report.md         # markdown to a file
cat report.docx | refigure --format docx  # stdin, format hint required
refigure reports/ -o out/                 # batch: directory, walked recursively
refigure a.docx b.xlsx -o out/            # batch: 2+ explicit sources

pip install "refigure[mcp,docx,xlsx]"
refigure-mcp                              # stdio — the MCP client launches it

{
  "mcpServers": {
    "refigure": { "command": "refigure-mcp" }
  }
}

{
  "mcpServers": {
    "refigure": {
      "command": "uvx",
      "args": ["--from", "refigure[mcp,docx,xlsx,vlm-direct]", "refigure-mcp"]
    }
  }
}

echo "sk-... = alice" > tokens.txt
refigure-mcp --transport http --mcp-auth-token-file tokens.txt

docker pull ghcr.io/helgdemidov/refigure:latest

docker run --rm -v "$PWD:/data:ro" ghcr.io/helgdemidov/refigure:latest \
  refigure /data/report.docx

{
  "mcpServers": {
    "refigure": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/helgdemidov/refigure:latest", "refigure-mcp"]
    }
  }
}

echo "sk-... = alice" > tokens.txt
docker run --rm -p 8000:8000 -v "$PWD/tokens.txt:/data/tokens.txt:ro" \
  ghcr.io/helgdemidov/refigure:latest \
  refigure-mcp --transport http --mcp-http-host 0.0.0.0 \
  --mcp-auth-token-file /data/tokens.txt

真实 convert() 输出的精选摘录（每份不超过 200 行），取自真实且采用开放许可的文档——即流水线会摄取的实际 Markdown，而非截图或精挑细选的一行内容。每个文件的标题都注明其来源、许可和署名；删节部分会在文中标明，绝不会为了凑篇幅而编造内容。

在 GitHub 上打开其中任意一个文件，就能直接看到两种视图：原始 ```mermaid fence an LLM/RAG pipeline would read, and its native GitHub rendering — no extra step, that's GitHub's own Markdown support.

Status

• Validated against 27 real documents (15 DOCX + 12 XLSX) — 407 native charts found (400 rendered), 35 composite figures recovered as positioned zero-loss markers. Full provenance: tests/integration/fixtures/manifest.yaml.
• Tested: CI gates on a combined unit+integration coverage floor of 95%.
• Published as v0.3.4 — PyPI (trusted publishing, no stored tokens), GHCR, and the official MCP Registry as io.github.HelgDemidov/refigure. refigure-md is a reserved alternate name, not an active release.

Extracted from a working document-analysis pipeline (a government AI-policy research corpus), not built from scratch for this release.

VLM interpretation of composite figures the chart engine can't reconstruct is fully implemented and tested, not a stub — [vlm] extra, provider-agnostic (direct OpenAI/Anthropic via [vlm-direct]), also needs the system soffice/LibreOffice binary.

Mermaid-diagram recognition depends on diagram type and on what the source figure actually contains:

• Common types (flowcharts, pie/xy charts) are picked reliably.
• More specialized ones need an unambiguous visual cue on the source figure.
• Not every figure produces a diagram — a plain-text description is an honest fallback, not a failure.

PDF is out of scope, on purpose — a boundary, not a gap. PDF has no equivalent of OOXML's cached chart data (numCache/strCache) for any mainstream chart generator, so the native, rasterize-free extraction this project is built on doesn't transfer to it — confirmed by research into PDF's own structure and how leading PDF converters handle charts today, not assumed. For mixed-format corpora, route by extension instead of expecting one tool to cover everything:

import refigure.docx
import refigure.xlsx

if path.suffix == ".pdf":
    markdown = docling_convert(path)      # or any PDF-capable converter
elif path.suffix == ".docx":
    markdown = refigure.docx.convert(path).markdown
else:
    markdown = refigure.xlsx.convert(path).markdown

Use Docling or MarkItDown for PDF, refigure for DOCX/XLSX where the chart data actually survives in the file.

License

Apache-2.0 — see LICENSE and NOTICE.