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 解释本身是为那些完全没有原生数据的罕见图形（如仪表盘截图）准备的——在任何分发格式上，都绝不需要仅为了从图表中获取真实数字而使用它。

以库、CLI、MCP 服务器和一键式 Claude Desktop 捆绑包的形式提供——每个接口都返回相同的原生保真输出，而不是为代理降级的摘要。

功能

• 原生图表数据提取 — 直接读取 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（[vlm-direct] 额外依赖）直接使用 OpenAI/Ollama/vLLM/LM Studio/Anthropic。--strict 将一种特定失败（系统缺少 soffice/LibreOffice 二进制文件）从优雅跳过升级为硬错误；其他所有 VLM 失败仍会降级。

• 丰富、类型化的结果 — ConversionResult（markdown + 警告 + 图表/组计数 + vlm_used），而不是裸字符串。

• 包含 CLI — refigure 控制台命令，以 stdin/stdout 为先，原生批处理模式，类型化退出码（见下文）。

• 包含 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，见下文）。

Related MCP server: x2md

演示

可选的 VLM 解释 — 对于完全没有原生图表数据（截图，而非 OOXML 图表部件）且也没有匹配的 mermaid 结构（密集的径向旭日图——原始 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 安装一个控制台命令——对编程使用的同一个 convert() 的薄封装，没有单独的逻辑：

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

批处理模式（2 个以上源，或单个目录）需要 -o DIR，默认在失败源之后继续（--fail-fast 则在第一个失败时中止），并始终向 stderr 打印摘要（N/M converted, K failed）。--json 输出完整结果——markdown 加上图表/组计数和警告——而不是纯 markdown。-v/-q 控制详细程度；--strict 转发到 Python API 使用的同一个 Config.strict。

退出码：

refigure-mcp — 作为 MCP 服务器的相同转换器，供直接使用该协议的代理/IDE 使用，而不是调用 CLI 或导入库。已在官方 MCP Registry 上以 io.github.HelgDemidov/refigure 列出：

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

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

或者将客户端指向 uvx，完全无需永久安装：

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

refigure[full] 是 refigure[mcp,docx,xlsx,vlm-direct] 的快捷方式——所有工具、两种格式、所有 VLM 提供商，一个额外依赖字符串。

三个工具——convert_docx、convert_xlsx 和 convert_batch（一次调用多个文件：一个坏文件报告自己的错误而不中止其余文件）——每个工具仅在其格式额外依赖实际安装时注册。use_vlm/--vlm-provider 等与 CLI 相同。对于太大而无法内联的结果，会存储并作为 refigure://conversion/{id} 资源返回，而不是膨胀工具响应。两个提示（ingest_for_rag、explain_conversion_warnings）帮助客户端为任务选择合适的工具/VLM 设置。

Streamable HTTP 是可选启用的，用于共享/远程部署——需要 bearer-token 认证，而非可选：

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

按调用方限流（保护操作者自身的支出免受泄露/失控令牌的影响）在 HTTP 上自动应用，并在配置 2 个以上调用方时应用公平性软上限；refigure-mcp --help 涵盖所有调优标志（并发、超时、资源存储限制、批大小、VLM 上限）。

一个镜像，两个接口——refigure 和 refigure-mcp 已在 PATH 上，无需在单独的 CLI/MCP 构建之间选择。这种格式相对于 pip/uvx 带来的唯一优势是：VLM 复合图形路径所需的系统 soffice/LibreOffice 二进制文件已内置，而非手动安装。多架构清单（linux/amd64 + linux/arm64）——docker pull 自动解析正确的层，包括在 Apple Silicon 上。

docker pull ghcr.io/helgdemidov/refigure:latest

为了可重现性，请固定精确版本而不是 :latest——例如 :0.3.4——参见 package page 获取可用标签。

包页面的 OS/Arch 选项卡在真实的 linux/amd64/linux/arm64 条目旁边列出了 unknown/unknown——这是构建来源/SBOM 证明（此镜像为每个平台发布的 in-toto + SPDX 元数据），而不是损坏或不受信任的镜像。GHCR 自己的 UI 不标记证明清单，这是注册表包视图的一个已知且被广泛报告的限制，与本项目无关。

CLI，通过绑定挂载（镜像的工作目录已经是 /data）：

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

MCP，stdio——客户端自行启动容器：

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

MCP，Streamable HTTP——此处需要 --mcp-http-host 0.0.0.0，而非可选：默认的 127.0.0.1 绑定通过 -p 端口发布无法访问（Docker 的 NAT 到达容器的外部网络接口，而非其回环），因此没有此标志的“明显”调用会静默地永不响应：

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

对非技术用户来说，最简单的安装方式：下载、双击、完成——无需终端，无需 pip/uvx/docker。仅涵盖 docx+xlsx 转换（没有 VLM——那需要 [vlm] 附加依赖，特意不随此捆绑包提供）；依赖会在首次启动时通过 uv 从 PyPI 全新解析，与 uvx 底层使用的机制相同，只不过是一键点击，而非一段配置片段。

下载 refigure.mcpb — 用 Claude Desktop 打开它即可安装。

真实示例

对真实、开放许可文档上的真实 convert() 输出进行的浓缩摘录（每个 ≤200 行）——这是管道实际会摄入的 markdown，而非截图或精心挑选的单行示例。每个文件自己的文件头都标明其来源、许可证和署名；被裁剪的部分会在行内标注，绝不会为填充篇幅而虚构。

在 GitHub 上打开其中任意一个，两种视图都直接可见：原始 ```mermaid 围栏（LLM/RAG 管道会读取的内容），以及它在 GitHub 上的原生 渲染——无需额外步骤，这正是 GitHub 自己的 Markdown 支持。

状态

• 已验证：在 27 份真实文档（15 份 DOCX + 12 份 XLSX）上验证——发现 407 个原生 图表（400 个已渲染），35 个复合图形被恢复为带定位的零损失标记。完整出处： tests/integration/fixtures/manifest.yaml。

• 已测试：CI 以单元+集成综合覆盖率下限 95% 为门槛。

• 已发布为 v0.3.4——PyPI （可信发布，不存储令牌）、 GHCR， 以及官方 MCP Registry 下的 io.github.HelgDemidov/refigure。refigure-md 是保留的备用名称， 而非活跃发布版本。

提取自一个实际运行中的文档分析管道（政府 AI 政策研究语料库），并非为本次发布从零构建。

对图表引擎无法重建的复合图形，VLM 解读已完整实现并通过测试，而非空壳——[vlm] 附加依赖、与提供商无关（通过 [vlm-direct] 直接使用 OpenAI/Anthropic），还需要系统中的 soffice/LibreOffice 二进制文件。

Mermaid 图表识别取决于图表类型以及源图形实际包含的内容：

• 常见类型（流程图、饼图/XY 图）能被可靠识别。

• 更专业化的类型需要在源图形上有明确的视觉线索。

• 并非每个图形都会生成图表——纯文本描述是诚实的回退，而非失败。

PDF 刻意不在范围内——这是一个边界，而非缺口。 对于任何主流图表生成器，PDF 都没有与 OOXML 的缓存图表数据（numCache/strCache）对等的机制，因此，本项目所基于的原生、免栅格化提取方式无法迁移到 PDF——这一点已通过对 PDF 自身结构以及当前主流 PDF 转换器如何处理图表的研究得到证实，而非凭空假设。对于混合格式的语料库，请根据扩展名进行路由，而不是指望一个工具覆盖一切：

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

对于 PDF，请使用 Docling 或 MarkItDown；对于图表数据实际仍保存在文件中的 DOCX/XLSX，请使用 refigure。

许可证

Apache-2.0 — 参见 LICENSE 和 NOTICE。