Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

feat(webui): add bidirectional PDF and image source tracing

myhloli3a82fdf783b4
diff --git a/docs/next/cli/mineru-kit-webui.md b/docs/next/cli/mineru-kit-webui.md
index 86c50c26..90c8c88e 100644
--- a/docs/next/cli/mineru-kit-webui.md
+++ b/docs/next/cli/mineru-kit-webui.md
@@ -10,7 +10,8 @@ Gradio 界面要求 `gradio>=6.21,<7`,使用 6.21 修复后的纯前端事件
PDF 预览使用独立 iframe 和随 MinerU 分发的 PDF.js 6.3.289,支持连续阅读、翻页、页码跳转、缩放和适应宽度。
核心模块、worker、CMap、标准字体及解码资源均从当前 Gradio 站点加载,预览无需外部 CDN 或 npm。
-上传时显示原始 PDF;解析完成后显示布局 PDF,布局文件不可用时显示裁页后的原始 PDF。
+上传时显示原始 PDF,解析完成后显示所选范围的原文 PDF,并叠加可点击的布局区域。
+图片解析完成后通过单页 PDF 提供相同的双向溯源交互。
每次切换文档回到第一页并适应宽度;浏览页码不改变解析页范围,翻页和缩放不调用 Python 解析接口。
需要密码或损坏的 PDF 会显示预览错误。文字搜索、编辑、打印和缩略图不在当前预览功能范围内。
静态资源和文件沿用 Gradio 的认证与文件路由,支持反向代理子路径;自定义挂载仍需传入自己的结果目录 `allowed_paths`。
@@ -25,6 +26,16 @@ UI 也可安装在独立环境,通过 `--api-url` 连接推理服务。
`mineru-kit webui` 提供一个基于 MinerU V1 API 的文档解析界面。它不直接调用旧 `/file_parse` 或 `/tasks` 接口,也不使用 `doclib` 缓存。
+## 双向溯源
+
+解析完成后,点击左侧区域可以定位并高亮右侧正文,点击右侧段落、标题、公式、图表主体或有独立坐标的子块可以返回原文区域。
+“显示区域框”默认开启。关闭后,区域在悬停或选中时显示。选中文字、点击正文链接及操作折叠控件分别执行对应的正文操作。
+
+跨页合并的段落、列表和表格会记录多个原文区域。点击右侧内容先定位首个来源,选中内容旁的“来源页”按钮可以切换关联原文页。
+来源页使用原文页号,左侧查看器的页码输入使用当前预览 PDF 的页序。键盘 Tab、Enter 和空格可用于激活区域。
+
+溯源映射由 DocVortex HTML renderer 提供,WebUI 通过浏览器消息完成定位。文件切换、清除及重新转换会重置来源与选中状态。
+
## 启动
安装 Gradio 基础依赖:
diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.py
index d018c525..35ca6df7 100644
--- a/mineru/kit/gradio/app.py
+++ b/mineru/kit/gradio/app.py
@@ -380,6 +380,7 @@ def build_gradio_app(
_resource_text("gradio_status_timer.js"),
)
)
+ app_js = app_js.replace("__MINERU_TRACE__", _resource_text("gradio_trace.js"))
# 等待限制放在生成器内部,使其他会话也能立即显示本地排队状态。
conversions = SessionConversions()
conversion_service = ConversionService(
diff --git a/mineru/kit/gradio/artifacts.py b/mineru/kit/gradio/artifacts.py
index 103bcab0..25932c7f 100644
--- a/mineru/kit/gradio/artifacts.py
+++ b/mineru/kit/gradio/artifacts.py
@@ -289,7 +289,12 @@ def persist_parse_result(
def render_html_preview(artifacts: RunArtifacts, *, public_base_url: str) -> str:
"""用独立 iframe 展示公共 HTML renderer 的完整输出,保留样式及公式脚本。"""
with _output_stage("html_preview", artifacts):
- value = _render_html(artifacts, public_base_url=public_base_url)
+ trace = artifacts.origin_pdf_path is not None
+ if trace:
+ value = _render_html(artifacts, public_base_url=public_base_url, include_source_map=True)
+ value = _add_trace_preview(value, artifacts, public_base_url=public_base_url)
+ else:
+ value = _render_html(artifacts, public_base_url=public_base_url)
# srcdoc 默认继承外层页面的基准地址,显式指定自身才能让章节锚点在预览内跳转。
value = value.replace("<head>", '<head>\n<base href="about:srcdoc">', 1)
value = _prepare_preview_links(value)
@@ -300,6 +305,43 @@ def render_html_preview(artifacts: RunArtifacts, *, public_base_url: str) -> str
)
+def _add_trace_preview(document: str, artifacts: RunArtifacts, *, public_base_url: str) -> str:
+ """向隔离结果页注入自有溯源脚本,配置只包含产物身份和页映射。"""
+ from .i18n import MESSAGES
+
+ base = urlsplit(public_base_url)
+ config = (
+ json.dumps(
+ {
+ "documentId": artifacts.root.name,
+ "pageIndices": list(artifacts.page_indices),
+ "parentOrigin": f"{base.scheme}://{base.netloc}",
+ "pageLabels": MESSAGES["trace_source"],
+ },
+ ensure_ascii=True,
+ )
+ .replace("<", "\\u003c")
+ .replace(">", "\\u003e")
+ .replace("&", "\\u0026")
+ )
+ script = (Path(__file__).resolve().parents[2] / "resources" / "gradio_trace_html.js").read_text(encoding="utf-8")
+ styles = """<style>
+[data-docvortex-trace-id] { cursor: pointer; scroll-margin: 24px; }
+[data-docvortex-trace-id]:hover { outline: 1px solid #fb923c66; outline-offset: 3px; }
+[data-mineru-selected] { outline: 2px solid #ea580c !important; outline-offset: 3px; background: #fb923c12; }
+.mineru-trace-pages { position: fixed; right: 8px; z-index: 100;
+ display: flex; flex-wrap: wrap; gap: 4px;
+ max-width: 75%; padding: 5px; background: Canvas;
+ border: 1px solid #fb923c; border-radius: 6px; }
+.mineru-trace-pages[hidden] { display: none; }
+.mineru-trace-pages button { cursor: pointer; color: CanvasText; background: Canvas;
+ border: 1px solid #aaa; border-radius: 4px; padding: 3px 6px; }
+.mineru-trace-pages button[aria-pressed=true] { border-color: #ea580c; background: #fb923c30; }
+</style>"""
+ document = document.replace("</head>", styles + "</head>", 1)
+ return document.replace("</body>", f"<script>({script})({config});</script></body>", 1)
+
+
def _prepare_preview_links(document: str) -> str:
"""仅为预览中的网页外链指定新标签页,保留内部锚点及邮件、电话等链接行为。"""
soup = BeautifulSoup(document, "html.parser")
@@ -315,7 +357,7 @@ def _prepare_preview_links(document: str) -> str:
return str(soup)
-def _render_html(artifacts: RunArtifacts, *, public_base_url: str) -> str:
+def _render_html(artifacts: RunArtifacts, *, public_base_url: str, include_source_map: bool = False) -> str:
"""把已物化语义树渲染为使用当前 Gradio 静态图片地址的独立 HTML。"""
if urlsplit(public_base_url).scheme not in {"http", "https"} or not urlsplit(public_base_url).netloc:
raise ValueError("HTML rendering requires the current Gradio HTTP base URL")
@@ -330,6 +372,7 @@ def _render_html(artifacts: RunArtifacts, *, public_base_url: str) -> str:
standalone=True,
document_title=artifacts.stem,
asset_base_url=asset_base_url,
+ include_source_map=include_source_map,
),
),
)
diff --git a/mineru/kit/gradio/conversion_service.py b/mineru/kit/gradio/conversion_service.py
index 57c5af13..079da576 100644
--- a/mineru/kit/gradio/conversion_service.py
+++ b/mineru/kit/gradio/conversion_service.py
@@ -219,7 +219,7 @@ def _prepare_preview(suffix: str, artifacts: RunArtifacts) -> PreviewPlan:
"""仅描述结果预览数据,保留已有 Office、OFD、EPUB 和网页源预览。"""
if suffix in OFFICE_EXTENSIONS | HTML_EXTENSIONS | MHTML_EXTENSIONS | {"ofd", "epub"}:
return PreviewPlan(preserve_source=True)
- preview_path = artifacts.layout_pdf_path or artifacts.origin_pdf_path
+ preview_path = artifacts.origin_pdf_path or artifacts.layout_pdf_path
return PreviewPlan(
preserve_source=False,
pdf_path=preview_path,
diff --git a/mineru/kit/gradio/i18n.py b/mineru/kit/gradio/i18n.py
index cc2a5b22..cc518406 100644
--- a/mineru/kit/gradio/i18n.py
+++ b/mineru/kit/gradio/i18n.py
@@ -62,6 +62,8 @@ MESSAGES: dict[str, tuple[str, str]] = {
"pdf_page": ("Page", "页码"),
"pdf_zoom_out": ("Zoom out", "缩小"),
"pdf_zoom_in": ("Zoom in", "放大"),
+ "trace_regions": ("Show regions", "显示区域框"),
+ "trace_source": ("Source page", "来源页"),
"pdf_fit_width": ("Fit width", "适应宽度"),
"pdf_invalid": ("This PDF is damaged or invalid.", "PDF 已损坏或格式无效。"),
"pdf_password": ("This PDF requires a password and cannot be previewed.", "此 PDF 需要密码,暂时无法预览。"),
diff --git a/mineru/render/api.py b/mineru/render/api.py
index 70f80abb..ecc69890 100644
--- a/mineru/render/api.py
+++ b/mineru/render/api.py
@@ -166,6 +166,7 @@ def render(
asset_base_url=resolved_options.asset_base_url,
standalone=resolved_options.standalone,
document_title=resolved_options.document_title,
+ include_source_map=resolved_options.include_source_map,
)
if output_format is RenderFormat.LATEX:
diff --git a/mineru/render/html.py b/mineru/render/html.py
index 36f77791..c3565374 100644
--- a/mineru/render/html.py
+++ b/mineru/render/html.py
@@ -14,6 +14,7 @@ def render_html(
asset_base_url: str = "",
standalone: bool = True,
document_title: str | None = None,
+ include_source_map: bool = False,
) -> str:
"""惰性加载 HTML 实现并渲染严格 MiddleJson。"""
from docvortex.render.html import render_html as _render_html
@@ -24,6 +25,7 @@ def render_html(
asset_base_url=asset_base_url,
standalone=standalone,
document_title=document_title,
+ include_source_map=include_source_map,
)
diff --git a/mineru/resources/gradio_app.js b/mineru/resources/gradio_app.js
index 2f64b3d7..d1508afd 100644
--- a/mineru/resources/gradio_app.js
+++ b/mineru/resources/gradio_app.js
@@ -1,5 +1,5 @@
() => {
- const APP_SCRIPT_VERSION = "v6-local-status-clock";
+ const APP_SCRIPT_VERSION = "v7-bidirectional-trace";
if (window.__mineruGradioAppInstalled === APP_SCRIPT_VERSION) {
return;
}
@@ -19,6 +19,7 @@
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
};
const i18n = window.__mineruI18n = __MINERU_I18N__;
+ (__MINERU_TRACE__)();
const statusTimer = (__MINERU_STATUS_TIMER__)(i18n);
window.__mineruStatusPanel = statusTimer;
// HTML 回调和前端事件使用同一份词典与首选语言规则。
diff --git a/mineru/resources/gradio_pdf_preview.js b/mineru/resources/gradio_pdf_preview.js
index e1c7b8e1..8774d865 100644
--- a/mineru/resources/gradio_pdf_preview.js
+++ b/mineru/resources/gradio_pdf_preview.js
@@ -36,6 +36,7 @@
})[character]);
if (action === "reset" || action === "clear") {
+ window.__mineruTrace?.reset();
disposeCurrentViewer();
state.source = action === "clear" ? "" : key(args[0]);
state.conversion = "";
@@ -44,6 +45,7 @@
return empty();
}
if (action === "begin") {
+ window.__mineruTrace?.reset();
state.conversion = state.source;
return [];
}
@@ -55,6 +57,7 @@
} else if (action === "result") {
if (!runId || state.conversion !== state.source) return skip();
state.result = runId;
+ window.__mineruTrace?.activate(runId);
} else {
return skip();
}
@@ -67,10 +70,11 @@
try {
const messages = Object.fromEntries([
"preview", "pdf_loading", "pdf_previous", "pdf_next", "pdf_page", "pdf_zoom_out", "pdf_zoom_in",
- "pdf_fit_width", "pdf_invalid", "pdf_password", "pdf_load_failed",
+ "trace_regions", "trace_source", "pdf_fit_width", "pdf_invalid", "pdf_password", "pdf_load_failed",
].map((name) => [name, text(name)]));
const viewerUrl = fileUrl(viewer);
const params = new URLSearchParams({ file: fileUrl(file, viewerUrl), messages: JSON.stringify(messages) });
+ if (action === "result") params.set("documentId", runId);
const url = new URL(viewerUrl);
// Gradio 6 会复用 iframe 节点;只改 hash 不会重新加载文档,必须改变查询参数。
url.searchParams.set("document", String(++state.revision));
diff --git a/mineru/resources/gradio_trace.js b/mineru/resources/gradio_trace.js
new file mode 100644
index 00000000..8a8bea7b
--- /dev/null
+++ b/mineru/resources/gradio_trace.js
@@ -0,0 +1,63 @@
+// 父页面协调两个预览,产物身份与转换 ticket 分别管理。
+() => {
+ if (window.__mineruTrace) return;
+ let documentId = "";
+ let entries = [];
+ let pageIndices = [];
+ // 只向当前自有 iframe 发消息,隔离的 HTML 使用明确窗口引用。
+ const send = (selector, message) => {
+ const frame = document.querySelector(selector);
+ frame?.contentWindow?.postMessage(
+ { ...message, channel: "mineru-trace", documentId },
+ selector.includes("rendered") ? "*" : location.origin
+ );
+ };
+ // 初始化可重复执行,覆盖两侧加载次序和 iframe 重挂载。
+ const initialize = () => {
+ send("iframe.mineru-pdf-frame", { type: "init", entries, pageIndices });
+ };
+ window.__mineruTrace = {
+ // 切换或重提立即使旧来源和待定位请求失效。
+ reset() {
+ send("iframe.mineru-pdf-frame", { type: "clear" });
+ documentId = "";
+ entries = [];
+ pageIndices = [];
+ },
+ // 只在已接受的结果回执进入预览时绑定产物标识。
+ activate(id) {
+ if (documentId === id) return;
+ this.reset();
+ documentId = id;
+ }
+ };
+ window.addEventListener("message", (event) => {
+ const data = event.data;
+ if (!documentId || data?.channel !== "mineru-trace" || data.documentId !== documentId) return;
+ const htmlFrame = document.querySelector("iframe.mineru-rendered-html-frame");
+ const pdfFrame = document.querySelector("iframe.mineru-pdf-frame");
+ const fromHtml = event.source === htmlFrame?.contentWindow;
+ const fromPdf = event.source === pdfFrame?.contentWindow && event.origin === location.origin;
+ if (!fromHtml && !fromPdf) return;
+ if (data.type === "ready") {
+ if (fromHtml) {
+ if (!Array.isArray(data.entries) || !Array.isArray(data.pageIndices)) return;
+ entries = data.entries;
+ pageIndices = data.pageIndices;
+ send("iframe.mineru-rendered-html-frame", {
+ type: "labels",
+ pageLabel: window.__mineruI18n.text("trace_source")
+ });
+ }
+ initialize();
+ return;
+ }
+ if (data.type !== "select") return;
+ const entry = entries.find((item) => item.id === data.id);
+ if (!entry) return;
+ const source = entry.sources.find((item) => item.page_idx === data.pageIdx) || entry.sources[0];
+ if (!source) return;
+ send("iframe.mineru-rendered-html-frame", { type: "select", id: entry.id, pageIdx: source.page_idx, scroll: fromPdf });
+ send("iframe.mineru-pdf-frame", { type: "select", id: entry.id, pageIdx: source.page_idx, scroll: fromHtml });
+ });
+}
diff --git a/mineru/resources/gradio_trace_html.js b/mineru/resources/gradio_trace_html.js
new file mode 100644
index 00000000..e3c51c2f
--- /dev/null
+++ b/mineru/resources/gradio_trace_html.js
@@ -0,0 +1,120 @@
+// 此脚本运行于隔离的结果 iframe,全部内容定位在本窗口完成。
+(config) => {
+ let pageLabel = config.pageLabels[navigator.language.startsWith("zh") ? 1 : 0];
+ const nodes = new Map();
+ const entries = [];
+ let selected = null;
+ let selectedPage = null;
+ let alignOnResize = false;
+ let resizeFrame = 0;
+ // 来源只从 renderer 创建的属性读取,不从正文字符串推断。
+ for (const node of document.querySelectorAll("[data-docvortex-trace-id]")) {
+ const id = node.dataset.docvortexTraceId;
+ const sources = JSON.parse(node.dataset.docvortexSources);
+ if (!sources.length) continue;
+ nodes.set(id, node);
+ entries.push({ id, sources, depth: sources[0].child_path.length });
+ node.tabIndex = 0;
+ }
+ const navigation = document.createElement("nav");
+ navigation.className = "mineru-trace-pages";
+ navigation.setAttribute("aria-label", pageLabel);
+ navigation.hidden = true;
+ document.body.append(navigation);
+ // 所有事件带产物身份,父窗口仍需核对实际发送窗口。
+ const send = (message) =>
+ parent.postMessage({ ...message, channel: "mineru-trace", documentId: config.documentId }, config.parentOrigin);
+ // 页码条贴近选中内容并限制在当前 iframe 的可见范围内。
+ const positionNavigation = () => {
+ if (!selected) return;
+ const rect = selected.getBoundingClientRect();
+ navigation.style.top = `${Math.max(8, Math.min(innerHeight - navigation.offsetHeight - 8, rect.top))}px`;
+ };
+ // 仅调整结果 iframe 自身滚动,避免带动整个 Gradio 页面。
+ const align = () => {
+ if (!selected || !alignOnResize) return;
+ const rect = selected.getBoundingClientRect();
+ window.scrollTo({
+ top: scrollY + rect.top - Math.max(24, (innerHeight - Math.min(rect.height, innerHeight - 48)) / 2)
+ });
+ positionNavigation();
+ };
+ // 一个目标对应多个原文页时,用去重后的原文页号切换来源。
+ const select = (id, pageIdx, scroll) => {
+ selected?.removeAttribute("data-mineru-selected");
+ selected = nodes.get(id);
+ if (!selected) return;
+ selectedPage = pageIdx;
+ selected.setAttribute("data-mineru-selected", "true");
+ navigation.replaceChildren();
+ const entry = entries.find((item) => item.id === id);
+ const pages = [...new Set(entry.sources.map((source) => source.page_idx))].sort((a, b) => a - b);
+ for (const page of pages) {
+ const button = document.createElement("button");
+ button.textContent = `${pageLabel} ${page + 1}`;
+ button.setAttribute("aria-pressed", String(page === selectedPage));
+ button.addEventListener("click", () => send({ type: "select", id, pageIdx: page }));
+ navigation.append(button);
+ }
+ navigation.hidden = pages.length < 2;
+ alignOnResize = scroll;
+ // 展开源内容所属的 details 后再读取其真实位置。
+ for (let ancestor = selected.parentElement; ancestor; ancestor = ancestor.parentElement) {
+ if (ancestor.tagName === "DETAILS") ancestor.open = true;
+ }
+ align();
+ positionNavigation();
+ };
+ // 文字选择、链接及原生控件优先处理,普通块点击和键盘激活发送定位请求。
+ const activate = (event) => {
+ if (event.type === "keydown" && !["Enter", " "].includes(event.key)) return;
+ if (event.target.closest("a,button,input,textarea,select,summary,[contenteditable=true]")) return;
+ if (event.type === "click" && !window.getSelection()?.isCollapsed) return;
+ const node = event.target.closest("[data-docvortex-trace-id]");
+ if (!node || !nodes.has(node.dataset.docvortexTraceId)) return;
+ if (event.type === "keydown") event.preventDefault();
+ send({ type: "select", id: node.dataset.docvortexTraceId });
+ };
+ document.addEventListener("click", activate);
+ document.addEventListener("keydown", activate);
+ window.addEventListener("message", (event) => {
+ const data = event.data;
+ if (
+ event.source !== parent ||
+ event.origin !== config.parentOrigin ||
+ data?.channel !== "mineru-trace" ||
+ data.documentId !== config.documentId
+ )
+ return;
+ if (data.type === "labels") {
+ pageLabel = data.pageLabel;
+ navigation.setAttribute("aria-label", pageLabel);
+ }
+ if (data.type === "select") select(data.id, data.pageIdx, data.scroll);
+ });
+ // 用户主动滚动后停止异步布局校正;新的定位请求重新启用。
+ for (const name of ["wheel", "touchstart", "pointerdown", "keydown"]) {
+ window.addEventListener(
+ name,
+ () => {
+ alignOnResize = false;
+ },
+ { passive: true }
+ );
+ }
+ window.addEventListener("scroll", positionNavigation, { passive: true });
+ const observer = new ResizeObserver(() => {
+ cancelAnimationFrame(resizeFrame);
+ resizeFrame = requestAnimationFrame(align);
+ });
+ observer.observe(document.body);
+ window.addEventListener(
+ "pagehide",
+ () => {
+ observer.disconnect();
+ cancelAnimationFrame(resizeFrame);
+ },
+ { once: true }
+ );
+ send({ type: "ready", entries, pageIndices: config.pageIndices });
+}
diff --git a/mineru/resources/pdf_preview/trace.mjs b/mineru/resources/pdf_preview/trace.mjs
new file mode 100644
index 00000000..dd05b526
--- /dev/null
+++ b/mineru/resources/pdf_preview/trace.mjs
@@ -0,0 +1,169 @@
+// PDF.js 的溯源层只依赖宿主查看器及公开页视图,状态按文档隔离。
+export function installTrace({ viewer, eventBus, container, documentId, messages }) {
+ const layers = new Set();
+ let entries = [];
+ let pageIndices = [];
+ let selectedId = "";
+ let pending = null;
+ let showAll = true;
+ const abort = new AbortController();
+ const options = { signal: abort.signal };
+ const toggle = document.createElement("button");
+ toggle.type = "button";
+ toggle.id = "trace-toggle";
+ toggle.textContent = messages.trace_regions;
+ toggle.setAttribute("aria-pressed", "true");
+ toggle.hidden = true;
+ document.getElementById("toolbar").append(toggle);
+ // 以当前父窗口的同源地址发送状态,来源页号始终采用原文索引。
+ const send = (message) => parent.postMessage({ ...message, channel: "mineru-trace", documentId }, location.origin);
+ // 清除已挂载区域,同时保留 PDF.js 自己管理的画布及批注。
+ const clearLayers = () => {
+ for (const layer of layers) layer.remove();
+ layers.clear();
+ };
+ // 重绘时从文档状态恢复选中样式,避免依赖已销毁的 DOM 引用。
+ const updateSelection = () => {
+ for (const layer of layers) {
+ layer.classList.toggle("show-all", showAll);
+ for (const box of layer.children) box.classList.toggle("selected", box.traceIds.includes(selectedId));
+ }
+ };
+ // 跳页后的页面可能尚未获得真实尺寸,等待对应页完成渲染再定位。
+ const finishNavigation = () => {
+ if (!pending) return;
+ const pageNumber = pageIndices.indexOf(pending.pageIdx) + 1;
+ const page = viewer.getPageView(pageNumber - 1);
+ const layer = page?.div.querySelector(".mineru-trace-layer");
+ const box = [...(layer?.children || [])].find((item) => item.traceIds.includes(pending.id));
+ if (!box) return;
+ const rect = box.getBoundingClientRect();
+ const host = container.getBoundingClientRect();
+ container.scrollTo({
+ top:
+ container.scrollTop +
+ rect.top -
+ host.top -
+ Math.max(16, (container.clientHeight - Math.min(rect.height, container.clientHeight - 32)) / 2)
+ });
+ pending = null;
+ };
+ // 同框父子优先具体节点,剩余重叠按面积从小到大排列命中层级。
+ const mount = (pageNumber) => {
+ const page = viewer.getPageView(pageNumber - 1);
+ if (!page?.div.querySelector("canvas")) return;
+ for (const layer of layers) if (!layer.isConnected) layers.delete(layer);
+ const old = page.div.querySelector(".mineru-trace-layer");
+ if (old) {
+ layers.delete(old);
+ old.remove();
+ }
+ const candidates = entries.flatMap((entry) =>
+ entry.sources
+ .filter((source) => source.page_idx === pageIndices[pageNumber - 1])
+ .map((source) => ({ entry, bbox: source.bbox }))
+ );
+ candidates.sort((a, b) => b.entry.depth - a.entry.depth);
+ const unique = new Map();
+ for (const item of candidates) {
+ const key = item.bbox.join(",");
+ if (!unique.has(key)) unique.set(key, { ...item, ids: [] });
+ unique.get(key).ids.push(item.entry.id);
+ }
+ const regions = [...unique.values()];
+ regions.sort(
+ (a, b) => (b.bbox[2] - b.bbox[0]) * (b.bbox[3] - b.bbox[1]) - (a.bbox[2] - a.bbox[0]) * (a.bbox[3] - a.bbox[1])
+ );
+ const layer = document.createElement("div");
+ layer.className = "mineru-trace-layer";
+ for (const { entry, bbox, ids } of regions) {
+ const box = document.createElement("button");
+ box.type = "button";
+ box.dataset.traceId = entry.id;
+ box.traceIds = ids;
+ box.setAttribute("aria-label", `${messages.trace_source} ${pageIndices[pageNumber - 1] + 1}`);
+ box.style.left = `${bbox[0] * 100}%`;
+ box.style.top = `${bbox[1] * 100}%`;
+ box.style.width = `${(bbox[2] - bbox[0]) * 100}%`;
+ box.style.height = `${(bbox[3] - bbox[1]) * 100}%`;
+ box.addEventListener("click", () => send({ type: "select", id: entry.id, pageIdx: pageIndices[pageNumber - 1] }));
+ layer.append(box);
+ }
+ page.div.append(layer);
+ layers.add(layer);
+ updateSelection();
+ finishNavigation();
+ };
+ // 仅接受当前宿主、当前产物的结构化消息。
+ window.addEventListener(
+ "message",
+ (event) => {
+ const data = event.data;
+ if (
+ event.source !== parent ||
+ event.origin !== location.origin ||
+ data?.channel !== "mineru-trace" ||
+ data.documentId !== documentId
+ )
+ return;
+ if (data.type === "clear") {
+ entries = [];
+ selectedId = "";
+ pending = null;
+ clearLayers();
+ toggle.hidden = true;
+ } else if (data.type === "init") {
+ if (!Array.isArray(data.entries) || !Array.isArray(data.pageIndices)) return;
+ entries = data.entries.filter(
+ (entry) =>
+ typeof entry.id === "string" &&
+ Array.isArray(entry.sources) &&
+ entry.sources.every(
+ (source) =>
+ Number.isInteger(source.page_idx) &&
+ Array.isArray(source.bbox) &&
+ source.bbox.length === 4 &&
+ source.bbox.every((value) => Number.isFinite(value) && value >= 0 && value <= 1)
+ )
+ );
+ pageIndices = data.pageIndices;
+ toggle.hidden = !entries.length;
+ for (const page of viewer.getCachedPageViews()) mount(page.id);
+ } else if (data.type === "select" && entries.some((entry) => entry.id === data.id)) {
+ pending = null;
+ selectedId = data.id;
+ updateSelection();
+ if (data.scroll) {
+ const pageNumber = pageIndices.indexOf(data.pageIdx) + 1;
+ if (pageNumber < 1) return;
+ pending = data;
+ viewer.scrollPageIntoView({ pageNumber });
+ finishNavigation();
+ }
+ }
+ },
+ options
+ );
+ toggle.addEventListener(
+ "click",
+ () => {
+ showAll = !showAll;
+ toggle.setAttribute("aria-pressed", String(showAll));
+ updateSelection();
+ },
+ options
+ );
+ // 查看器事件在缩放和缓存重建后重新挂载区域。
+ const onRendered = (event) => {
+ if (!event.error) mount(event.pageNumber);
+ };
+ eventBus.on("pagerendered", onRendered);
+ send({ type: "ready" });
+ return () => {
+ // 查看器卸载时释放本次文档拥有的监听器和浮层。
+ abort.abort();
+ eventBus.off("pagerendered", onRendered);
+ clearLayers();
+ toggle.remove();
+ };
+}
diff --git a/mineru/resources/pdf_preview/viewer.css b/mineru/resources/pdf_preview/viewer.css
index 014c8cdd..21f30207 100644
--- a/mineru/resources/pdf_preview/viewer.css
+++ b/mineru/resources/pdf_preview/viewer.css
@@ -44,3 +44,21 @@ button:focus-visible, input:focus-visible, #viewer-container:focus-visible { out
button:hover:enabled { background: #374151; }
#toolbar { border-color: #4b5563; }
}
+/* 溯源区域跟随页面 CSS 尺寸,边框显隐和选中状态独立。 */
+.mineru-trace-layer { position: absolute; inset: 0; z-index: 4; pointer-events: none; }
+.mineru-trace-layer > button { position: absolute; pointer-events: auto; min-width: 0; height: auto; padding: 0; border: 1px solid transparent; border-radius: 2px; background: transparent; cursor: pointer; }
+.mineru-trace-layer.show-all > button { border-color: #e88b5666; }
+.mineru-trace-layer > button:hover, .mineru-trace-layer > button:focus-visible { border-color: #ea580c; background: #fb923c18; }
+.mineru-trace-layer > button.selected { border: 2px solid #ea580c; background: #fb923c30; }
+#trace-toggle { font-size: 11px; padding: 0 5px; }
+@media (max-width: 480px) {
+ body:has(#trace-toggle:not([hidden])) { --toolbar-height: 80px; }
+ #toolbar { flex-wrap: wrap; align-content: center; }
+ #trace-toggle { grid-column: 1 / -1; }
+ #toolbar:has(#trace-toggle:not([hidden])) { height: var(--toolbar-height); }
+}
+
+@media (max-width: 360px) {
+ body:has(#trace-toggle:not([hidden])) { --toolbar-height: 112px; }
+ #trace-toggle { grid-area: 3 / 1 / 4 / 6; }
+}
diff --git a/mineru/resources/pdf_preview/viewer.mjs b/mineru/resources/pdf_preview/viewer.mjs
index cbd28371..7daad87d 100644
--- a/mineru/resources/pdf_preview/viewer.mjs
+++ b/mineru/resources/pdf_preview/viewer.mjs
@@ -1,3 +1,4 @@
+import { installTrace } from "./trace.mjs";
// 查看器独立于宿主框架运行;PDF、字体和解码器只从同源的固定资源目录读取。
const params = new URLSearchParams(window.location.hash.slice(1));
const messages = JSON.parse(params.get("messages") || "{}");
@@ -25,6 +26,7 @@ let resizeObserver;
let resizeFrame;
let fitWidth = true;
let ready = false;
+let disposeTrace;
// 清除或换文件时释放渲染队列、worker 和观察器,旧页面不会向新预览写入结果。
const dispose = () => {
@@ -32,6 +34,7 @@ const dispose = () => {
disposed = true;
cancelAnimationFrame(resizeFrame);
resizeObserver?.disconnect();
+ disposeTrace?.();
try {
viewer?.setDocument(null);
links?.setDocument(null);
@@ -102,6 +105,9 @@ try {
ready = true;
document.getElementById("toolbar").setAttribute("aria-busy", "false");
resize();
+ if (params.get("documentId")) {
+ disposeTrace = installTrace({ viewer, eventBus, container, documentId: params.get("documentId"), messages });
+ }
});
eventBus.on("pagechanging", updateControls);
eventBus.on("scalechanging", updateControls);
diff --git a/pyproject.toml b/pyproject.toml
index 51bf08b0..eff79567 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,7 +38,7 @@ classifiers = [
"Programming Language :: Python :: 3.14",
]
dependencies = [
- "docvortex>=0.6.17,<0.7",
+ "docvortex>=0.6.18,<0.7",
"gradio>=6.21,<7",
"mineru[torch] ; sys_platform == 'darwin' and platform_machine == 'arm64'",
"mineru-vl-utils>=2.0.8,<3",
diff --git a/tests/unittest/test_kit_gradio_status_timer.cjs b/tests/unittest/test_kit_gradio_status_timer.cjs
index 42a2a1f3..27070095 100644
--- a/tests/unittest/test_kit_gradio_status_timer.cjs
+++ b/tests/unittest/test_kit_gradio_status_timer.cjs
@@ -263,7 +263,8 @@ const appContext = vm.createContext({
});
vm.runInContext(resource("gradio_app.js")
.replace("__MINERU_I18N__", "stubI18n")
- .replace("__MINERU_STATUS_TIMER__", "stubTimer"), appContext)();
+ .replace("__MINERU_STATUS_TIMER__", "stubTimer")
+ .replace("__MINERU_TRACE__", "() => {}"), appContext)();
while (frames.length) frames.shift()();
const beforeRefresh = localizations;
observer([externalMutation]);
diff --git a/tests/unittest/test_kit_gradio_trace.cjs b/tests/unittest/test_kit_gradio_trace.cjs
new file mode 100644
index 00000000..7663b161
--- /dev/null
+++ b/tests/unittest/test_kit_gradio_trace.cjs
@@ -0,0 +1,58 @@
+// 执行真实父页面协调脚本,覆盖加载乱序、文档替换和消息身份。
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const vm = require("node:vm");
+const path = require("node:path");
+const handlers = {};
+const delivered = [];
+// 为两个实际 iframe 接口提供最小可观测替身。
+const frame = (name) => ({ contentWindow: { postMessage: (message, origin) => delivered.push({ name, message, origin }) } });
+const html = frame("html");
+const pdf = frame("pdf");
+const window = {
+ addEventListener: (name, callback) => {
+ handlers[name] = callback;
+ },
+ __mineruI18n: { text: () => "来源页" }
+};
+const document = { querySelector: (selector) => (selector.includes("rendered") ? html : pdf) };
+const location = { origin: "https://mineru.test" };
+const script = fs.readFileSync(path.join(__dirname, "../../mineru/resources/gradio_trace.js"), "utf8");
+vm.runInNewContext(`(${script})()`, { window, document, location });
+// 统一构造来源消息,允许测试替换发送者与文档身份。
+const emit = (source, data, origin = "null") =>
+ handlers.message({ source: source.contentWindow, origin, data: { channel: "mineru-trace", documentId: "one", ...data } });
+const entry = {
+ id: "p2-b1",
+ sources: [
+ { page_idx: 2, bbox: [0.1, 0.1, 0.8, 0.2] },
+ { page_idx: 5, bbox: [0.1, 0.1, 0.8, 0.2] }
+ ],
+ depth: 0
+};
+window.__mineruTrace.activate("one");
+emit(pdf, { type: "ready" }, location.origin);
+emit(html, { type: "ready", entries: [entry], pageIndices: [2, 5] });
+emit(html, { type: "select", id: entry.id });
+assert.equal(delivered.at(-1).message.pageIdx, 2);
+assert.equal(delivered.at(-1).message.scroll, true);
+emit(pdf, { type: "select", id: entry.id, pageIdx: 5 }, location.origin);
+assert.equal(delivered.at(-2).message.pageIdx, 5);
+assert.equal(delivered.at(-2).message.scroll, true);
+assert.equal(delivered.at(-1).message.scroll, false);
+// 同一结果重复激活仍保留映射,可供重挂载的 PDF 查看器恢复。
+window.__mineruTrace.activate("one");
+emit(pdf, { type: "ready" }, location.origin);
+assert.equal(delivered.at(-1).message.entries.length, 1);
+const count = delivered.length;
+emit(frame("foreign"), { type: "select", id: entry.id });
+emit(pdf, { type: "select", id: entry.id }, "https://foreign.test");
+emit(html, { type: "select", id: "missing" });
+assert.equal(delivered.length, count);
+window.__mineruTrace.activate("two");
+const switched = delivered.length;
+emit(html, { type: "ready", entries: [entry], pageIndices: [2, 5] });
+emit(pdf, { type: "select", id: entry.id }, location.origin);
+assert.equal(delivered.length, switched);
+window.__mineruTrace.reset();
+console.log("Trace identity, handshake and bidirectional routing passed");
diff --git a/tests/unittest/test_kit_gradio_trace.py b/tests/unittest/test_kit_gradio_trace.py
new file mode 100644
index 00000000..86512624
--- /dev/null
+++ b/tests/unittest/test_kit_gradio_trace.py
@@ -0,0 +1,37 @@
+"""溯源预览的真实产物、公共门面和前端协议回归。"""
+
+from pathlib import Path
+import shutil
+import subprocess
+
+from bs4 import BeautifulSoup
+
+from mineru.kit.gradio.artifacts import persist_parse_result, render_html_preview, render_download
+from mineru.kit.gradio.conversion_service import _prepare_preview
+from mineru.parser.base import ParseResult
+from test_kit_gradio import _middle_json, _pdf_bytes
+
+
+def test_pdf_trace_preview_and_public_render(tmp_path: Path) -> None:
+ """抽页预览携带原始页映射与来源属性,下载走普通渲染入口。"""
+ source = tmp_path / "source.pdf"
+ source.write_bytes(_pdf_bytes())
+ middle = _middle_json(with_image=False)
+ artifacts = persist_parse_result(ParseResult(middle_json=middle), source, output_root=tmp_path, page_range="")
+ assert _prepare_preview("pdf", artifacts).pdf_path == artifacts.origin_pdf_path
+ preview = render_html_preview(artifacts, public_base_url="http://testserver")
+ frame = BeautifulSoup(preview, "html.parser").iframe
+ assert "allow-same-origin" not in frame["sandbox"]
+ document = BeautifulSoup(frame["srcdoc"], "html.parser")
+ assert document.select_one("[data-docvortex-trace-id]")
+ assert artifacts.root.name in document.get_text() or artifacts.root.name in str(document)
+ assert "pageIndices" in str(document)
+ download = render_download(artifacts.as_state(), "html", public_base_url="http://testserver")
+ assert "data-docvortex-sources" not in Path(download).read_text()
+
+
+def test_trace_frontend_coordination() -> None:
+ """用 Node 执行真实父窗口脚本的双向消息与失效回归。"""
+ node = shutil.which("node")
+ assert node is not None
+ subprocess.run([node, str(Path(__file__).with_suffix(".cjs"))], check=True)