_{Provider 与解析默认值的可视化配置；同一页面还提供缓存、重试、安全限制和存储运维。}

一个插件，两个 Provider，三项模型工具。模型不需要理解上游的 task ID、batch ID、预签名上传地址、状态 URL 或 ZIP 结构，只需要选择同步直返或 DSH 原生后台任务。

[!NOTE] 本项目是独立维护的 DSH 社区插件。Provider 只负责适配 MinerU 上游协议，DSH Job、缓存、安全边界和工具输出由插件统一管理。

快速开始

1. 安装

DeepSeek Harness 的 Web profile 可以直接安装 npm 包：

dsh plugin --profile web add dsh-pdf-mineru

本地开发或测试 checkout：

dsh plugin --profile web add link:/absolute/path/to/dsh-pdf-mineru

[!TIP] 使用 pnpm 10+ 从源码安装时，需要在 profile 的 pnpm-workspace.yaml 中显式允许所需构建脚本。

2. 连接 MinerU

打开 Settings → MinerU，选择活动 Provider：

• Self-hosted v2：默认连接 http://localhost:18000，本地 HTTP 需要显式启用 Allow Insecure HTTP。
• Official v4：默认连接 https://mineru.net/api/v4，并通过 DSH Credential 或环境变量提供 Token。

官方云最小凭据配置：

export MINERU_API_KEY="your-token"

在 Settings 中将 API Key Env Var 保持为 MINERU_API_KEY，点击 Test Active Provider 验证连通性与鉴权。

3. 交给 Agent

直接描述需要解析的本地文档和期望产物，例如：

请用 MinerU 解析 /absolute/path/to/paper.pdf，保留 Markdown、图片和 content list。

长文档或不希望阻塞当前回合时：

把 /absolute/path/to/report.pdf 作为 MinerU 后台任务解析，完成后读取结果。

Agent 会根据任务选择 mineru_parse_document 或 mineru_submit_parse_job。异步任务由 DSH 通用的 job_output、job_list 和 job_kill 管理。

核心能力

模型工具

插件只暴露三项 MinerU 工具：

解析参数

Markdown 始终包含在规范化产物集合中。大段 preview 会按配置截断，完整产物仍保存在 result manifest 指向的路径中。

工作方式

flowchart LR
    Agent[DSH Agent] --> Health[mineru_health]
    Agent --> Sync[mineru_parse_document]
    Agent --> Async[mineru_submit_parse_job]

    Async --> Jobs[DSH JobRegistry]
    Jobs --> Service[MinerUService]
    Sync --> Service
    Health --> Providers[ProviderRegistry]

    Service --> Cache{Result cache}
    Cache -->|hit| Result[Immutable result]
    Cache -->|miss| Shared[SharedOperationRegistry]
    Shared --> Providers
    Providers --> V2[Self-hosted v2]
    Providers --> V4[Official v4]
    V2 --> Staging[Validated staging]
    V4 --> Staging
    Staging --> Publish[Atomic publish]
    Publish --> Result

• RequestNormalizer 规范参数、页码范围和产物集合，并流式计算源文件 SHA-256。
• ResultRepository 校验并读取不可变结果；源文件绝对路径不会写入规范请求或 manifest。
• SharedOperationRegistry 只在当前进程内合并相同请求，不提供跨进程协调。
• ProviderRegistry 在一次操作生命周期内固定 Provider 配置，避免任务中途切换后端。

Provider 对照

Provider 不注册工具、不访问 DSH Session、不决定存储路径，也不生成模型文案。它只负责上游协议转换、轮询与产物收集。

配置

推荐通过 Settings → MinerU 编辑配置。Provider、解析默认值、轮询、重试和输出限制对新任务实时生效；storageRoot 变更需要重启插件进程。

schemaVersion: 1
activeProvider: mp_self_hosted
providers:
  - id: mp_self_hosted
    type: self-hosted-v2
    baseURL: http://localhost:18000
    apiKeyEnv: MINERU_API_KEY
    allowInsecureHttp: true
    modelMap:
      pipeline: pipeline
      vlm: vlm-engine
defaults:
  model: pipeline
  ocr: false
  parseMethod: auto
  language: ch
  formula: true
  table: true
  artifacts: [markdown]
retry:
  maxAttempts: 3
  baseDelayMs: 500
  maxDelayMs: 10000

schemaVersion: 1
activeProvider: mp_official
providers:
  - id: mp_official
    type: official-v4
    baseURL: https://mineru.net/api/v4
    apiKeyEnv: MINERU_API_KEY
    models: [pipeline, vlm]
    configuredVersion: v4
defaults:
  model: vlm
  ocr: false
  parseMethod: auto
  language: ch
  formula: true
  table: true
  artifacts: [markdown]

storage:
  storageRoot: /absolute/path/to/dsh/cache/pdf-mineru
  cacheEnabled: true
  retainSources: false
  stagingTtlMs: 86400000

polling:
  pollIntervalMs: 2000
  pollTimeoutMs: 600000
  requestTimeoutMs: 60000
  operationTimeoutMs: 3600000

retry:
  maxAttempts: 3
  baseDelayMs: 500
  maxDelayMs: 10000

output:
  maxInlineChars: 200000

limits:
  maxFilesPerRequest: 1
  maxFileBytes: 209715200
  maxApiResponseBytes: 8388608
  maxZipDownloadBytes: 536870912
  maxZipEntries: 10000
  maxZipEntryBytes: 268435456
  maxZipTotalBytes: 2147483648
  maxZipCompressionRatio: 200

配置只保存 Credential reference，例如 MINERU_API_KEY。每次 Provider 调用时，插件先从 DSH Credential Service 解析，再回退到同名环境变量；Token 值不会写入配置或缓存。

安全与存储

内容寻址结果

$DSH_HOME/cache/pdf-mineru/
├── results/sha256/<prefix>/<cache-key>/manifest.json
├── staging/<operation-id>/
├── quarantine/<timestamp_reason_id>/
└── .process.lock

• 已发布结果按单文件保存且不可修改，批量请求按文件 fan-out。
• staging 通过校验后只允许同文件系统原子 rename；EXDEV 不会退化为复制。
• 一个 storageRoot 同时只能由一个 DSH 进程持有。
• DSH JobRegistry 与 SharedOperation 是进程内状态；不可变结果在进程或 Session 结束后仍可复用。

[!IMPORTANT] 同步等待超时或 job_kill 只停止该调用的等待。若同一 SharedOperation 仍被其他调用依赖，上游 producer 会继续执行并发布缓存结果。

兼容性说明

• 当前只接受 Provider-based canonical config，不兼容旧 flat config。
• mineru_get_parse_status 和 mineru_get_parse_result 已移除；异步任务使用 DSH 通用 Job 工具。
• 默认缓存根目录为 $DSH_HOME/cache/pdf-mineru，旧目录不会自动迁移。
• 缓存不会在不同 DSH 实例之间自动共享；跨进程请求也不会合并。

开发与验证

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
git diff --check

# 在已运行的 DSH Web shell 中隔离加载当前 client bundle
pnpm run verify:gui

# 显式执行 Official v4 真实链路 smoke
MINERU_API_KEY=<token> pnpm run smoke:official-v4 -- /absolute/path/sample.pdf

默认测试使用 mock HTTP 和本地 ZIP fixture，不需要真实 Token。smoke:official-v4 必须显式提供真实 Token 和 PDF，不进入默认测试。

更深入的领域模型、缓存键、并发语义和安全约束见 ARCHITECTURE.md。

许可证与致谢

本项目使用 MIT License 开源。

感谢 DeepSeek Harness 提供插件运行时，感谢 MinerU 提供文档解析能力，也感谢 Huanlin/dsh-plugin-mineru 带来的早期实现灵感。