Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
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.mdindex 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.pyindex 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.pyindex 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.pyindex 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_pathreturn PreviewPlan(preserve_source=False,pdf_path=preview_path,diff --git a/mineru/kit/gradio/i18n.py b/mineru/kit/gradio/i18n.pyindex 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.pyindex 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.pyindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.mjsnew file mode 100644index 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.cssindex 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 { outbutton: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.mjsindex 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.tomlindex 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.cjsindex 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.cjsnew file mode 100644index 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.pynew file mode 100644index 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)