Liquid Converter

本地单机、单用户、localhost 优先的异步文档提取工具。

V1 只保留一条可信主线：

• PDF / DOCX / PPTX -> Markdown / JSON
• XLSX -> JSON

/convert 已废弃，不再作为主执行入口。

Quick Start

首次运行：

./setup_deps.sh

启动服务：

./启动\ Liquid\ Converter.command

也可以显式选择 PDF 引擎设备策略：

./启动\ Liquid\ Converter.command auto
./启动\ Liquid\ Converter.command cpu
./启动\ Liquid\ Converter.command mps
./启动\ Liquid\ Converter.command cuda

启动后访问：

http://127.0.0.1:8000

Runtime Model

• 后端：Python + FastAPI
• 前端：原生 HTML + CSS + JavaScript
• PDF 主引擎：marker-pdf
• DOCX / PPTX 主引擎：markitdown
• XLSX 主引擎：openpyxl

前端会从 /api/v1/capabilities 拉取当前真实能力面，并展示当前 PDF 运行模式：

• Auto
• CPU
• MPS
• CUDA
• Fallback to CPU

API Contract

V1 对外只保留异步任务流：

POST /api/v1/extract/markdown

提交一个 Markdown 提取任务。

POST /api/v1/extract/json

提交一个 JSON 提取任务。

GET /api/v1/status/{job_id}

查询任务状态。已知任务返回 200，未知或过期任务返回 404。

GET /api/v1/download/{job_id}

下载已完成产物。任务未完成时返回 409，任务不存在或产物过期时返回 404。

GET /api/v1/capabilities

返回当前真实可用的转换规则、引擎预加载状态和运行时策略。

GET /health/ready

供启动器与未来 Mac App sidecar 轮询。至少一个引擎（Marker 或 MarkItDown）可用时返回 200 与 {"ready": true}，否则 503。

兼容性说明：

• 废弃的 /convert 会固定返回 410 Gone

Frontend Behavior

• 上传提交和状态轮询都使用 AbortController
• 默认请求超时是 120s
• 状态轮询也有固定 wall-clock 超时，不会无限轮询
• 下载按钮会先检查 /api/v1/download/{job_id} 的真实响应
• 409 / 404 下载错误会直接显示在页面里，不会把页面跳走
• 本地 localhost 模式不会注册 Service Worker，也会主动清理旧缓存

Testing

运行全量回归：

.venv/bin/pytest -q

只看前端相关测试：

.venv/bin/pytest -q tests/test_frontend.py tests/test_frontend_rules.py

Repository layout

.
├── app/                 # FastAPI 应用、中间件、V1 路由、任务队列
├── engines/             # MarkItDown / Marker / Excel 等底层引擎
├── tests/               # pytest 与 fixtures
├── docs/
│   ├── CODEMAPS/        # 架构地图
│   ├── plans/           # 设计 / 稳定性规划
│   ├── archive/         # 历史复盘与审计（非运行时权威）
│   └── assets/          # 示意图等静态资源
├── scripts/             # 基准、版本检查、fixtures 生成
│   └── dev/             # 手动 HTTP 调试（非 CI）
├── tests/               # pytest；`_legacy/` 默认不运行
├── index.html / script.js / style.css   # 玻璃拟态 Web UI（PWA）
├── main.py              # 入口：lifespan + create_app()
├── setup_deps.sh        # 首次依赖（Homebrew / Pandoc / LibreOffice）
└── 启动 Liquid Converter.command

本地目录 artifacts/、.venv/、.env 不纳入 Git。发布到 GitHub 前请确认未提交密钥或大文件。

Acknowledgments

本项目的 PDF / Office 提取能力分别建立在 Marker（marker-pdf）与 MarkItDown（Microsoft）等开源项目之上；另有 Pandoc、LibreOffice、PyTorch 等依赖。完整署名、许可证说明与商用注意事项见 ACKNOWLEDGMENTS.md。

本仓库 MIT 许可证仅覆盖 Liquid Converter 自有代码；使用 Marker 时须同时遵守其 GPL-3.0 及模型权重条款。

Notes

• 严格 MIME 校验依赖系统 libmagic
• marker-pdf 若遇到 GPU 兼容问题，会在运行时诚实降级到 CPU
• 这个仓库当前的可信产品边界是本地单机异步提取，不是公网 SaaS，也不是全能转换平台