# dsh-knowledge v0.5.0 — Structured Evidence and Experimental Managed MinerU

This release expands the document-processing pipeline with structured evidence and adds an optional, isolated MinerU deployment path. The existing cloud API and external self-hosted MinerU integration remain available.

## Highlights

- **Structured evidence from parse to answer.** Page and block references, table/formula structure, and inert image assets can travel through parsing, chunking, storage, retrieval context, and anchored reads. Evidence tools can continue from a specific chunk instead of repeatedly reopening unrelated sections.
- **Rechunk without reparsing.** Saved parse artifacts can be reused to produce a new chunk/index generation. Failed replacement keeps the previous usable generation available.
- **Optional managed MinerU — experimental.** The setup flow checks a selected CPython environment, previews verified model reuse and download size, honors separately configured Hugging Face and Python package sources, and installs into a dedicated environment. The active deployment pointer changes only after the candidate passes a real PDF parse probe.
- **Safer processing lifecycle.** Imports and rebuilds share processing paths, with bounded queue/state reporting and generation-aware recovery behavior.
- **UI and evidence workflow improvements.** Processing configuration and evidence views have clearer grouping, status messages, and navigation affordances while retaining existing controls.
- **Fixes for issues #34–#37.** Automatic evidence uses a producer-owned source accepted by DSH v4. Desktop controls avoid the native titlebar. The usage prompt lists only base names and can be switched off. Native OCR inference runs in a child process; raster allocations are bounded and explicitly released, incomplete imports fail visibly, and startup recovery is capped.

## Verification and limits

The local release-candidate checks passed: typecheck, 488 Vitest tests, retrieval benchmark v2, structured regression tests, worker protocol smoke, build, package verification, release metadata verification, and the production dependency audit policy. The tests include a real 26-page MuPDF render of 2800×4600 pages and child-process crash/timeout recovery. `undici` is upgraded to 7.30.0 to remove the newly reported production audit findings.

The audit currently permits two high-severity `sharp` advisories only through **2026-10-14** for the narrowly scoped `@huggingface/transformers > sharp` dependency path. This is a temporary exception, not a clean/no-vulnerability result, and must be reviewed before its deadline.

The built auto-retrieval message also passed the upstream DSH v4 source validator at commit `639ed015397290b3745d163aafe02ffee4aa3f84`. Focused browser checks rendered the actual React panel with simulated 40px/56px overlay geometry and ordinary-browser mode, verified panel close/toggle/toast placement, and saved only `injectUsagePrompt: false` through the settings UI's mocked API.

Cross-platform CI additionally identified and fixed a managed-preparation cleanup race: restoring a previous verified installation now remains busy until the saved state and installation lock are settled. A deterministic regression blocks the actual state-file rename to verify this ordering. Managed-path test fixtures resolve the platform's temporary-directory symlinks before creating owned paths, preserving the production rejection of symlinks and junctions.

The packed smoke covers public DSH 0.1.1-rc.2 and 0.2.0-rc.2 on Windows and Ubuntu. The legacy CLI has an upstream HMR initialization race and permits newer HMR dependencies that removed `registerConfig`. Its isolated test installation pins HMR to 1.0.16 and enables the watch-only service before boot; the newer host keeps its own configuration. Startup requires a continuous healthy response interval while the host stays alive. It rejects a host that serves the route and then exits. The normal plugin bundle does not change host HMR settings. Similar upstream reports are documented in [DSH discussion #7593](https://github.com/deepseek-ai/deepseek-harness/discussions/7593).

Real managed MinerU cold-install/parse runs on Windows and Ubuntu, full managed-settings acceptance in a live DSH host, and the final clean-commit GitHub Actions run are still pending. Managed MinerU therefore remains **experimental**. This release does not claim certified OCR accuracy, all-platform support, or a successful real-model installation on every supported Python version.

## Upgrade notes

- Managed MinerU is opt-in. Opening settings or detecting Python does not install Python packages or download model files; installation requires an explicit preflight and confirmation.
- Python packages and model files use separate configurable sources. The selected endpoints are shown before installation; downloaded model files are verified against the pinned manifest.
- Existing cloud/self-hosted MinerU configuration remains supported. No automatic fallback from local processing to a cloud service is introduced.
- Existing data upgrade compatibility must be confirmed by the release-candidate upgrade checks before calling the release fully ready. No forced re-embedding or model download is intended by the new managed deployment flow.
- Reparse scanned PDFs that older versions already indexed with missing pages. OCR now rejects incomplete extraction instead of silently returning a prefix. Failed sources remain available for a manual rebuild.
- `injectUsagePrompt` defaults to `true` but only lists base names; global/deployment and per-base overrides may disable that list while keeping tools and automatic retrieval enabled.

## 中文摘要

0.5.0 增加从解析、分块、检索到锚点续读的结构化证据链，并允许重分块复用解析产物。托管 MinerU 使用独立 Python 环境，支持安装前检查模型复用和下载容量、分别配置模型源与 Python 包源；只有真实 PDF 解析探针通过后，候选环境才会成为当前可用部署。原有云 API 和外部自部署方式保持可用。

同时修复 #34–#37：自动检索使用 v4 可接受的插件来源；桌面面板动态避让原生窗口按钮；系统提示只保留库名并提供开关；OCR 改为独立子进程推理，页面分配前限制内存、逐页释放 pixmap，漏页明确失败，启动恢复加入次数上限。旧版本已漏页的扫描件需要手动重新解析。

自动检索消息已通过 DSH 上游实际 v4 校验。浏览器定向验收使用实际 React 组件、模拟的 40px/56px 标题栏和 API，覆盖动态避让、普通浏览器零偏移、关闭面板及新提示开关保存；这不等于实际桌面壳和托管设置的完整验收。

跨平台 CI 还发现并修复了托管安装清理的竞态：重新准备失败时，必须保存状态并释放安装锁后才对外报告空闲，保证旧的已验证安装可以立即安全启动。macOS 测试使用解析后的真实临时目录；生产环境的符号链接和 junction 拒绝规则保持有效。

安装包启动检查覆盖 Windows/Ubuntu 和 DSH 0.1.1-rc.2、0.2.0-rc.2。旧版 CLI 有 HMR 初始化竞态，而且允许安装已删除 `registerConfig` 的新版依赖；隔离的测试安装将 HMR 固定为 1.0.16，在临时配置中提前启用只监听配置的服务。新版宿主保持自己的配置。检查要求接口连续可用且宿主进程保持运行，防止短暂响应后崩溃被误判为成功；插件的正常安装不更改宿主 HMR 配置。

托管 MinerU 仍为实验性功能：Windows/Linux 实机安装解析、DSH 托管设置完整验收和最终 GitHub Actions 尚待完成。本机自动化测试通过不能代替这些实测，也不代表 OCR 准确率认证。undici 升级到 7.30.0 后新增高危告警已消除；依赖审计仍有两条限期接受的 `sharp` 高危告警，须在 2026-10-14 前复核。