Summary

MinerU already documents support for macOS 14+ and Apple Silicon, but the repository still lacks two pieces that would make the macOS path much easier to trust and maintain:

1. a lightweight macOS smoke automation job in CI
2. a more explicit macOS-first quick start for first install / first run / first model download

I think these two changes are a better fit for the open-source repository than adding a new end-user shell script entrypoint.

Current gap

The current docs already promise:

• macOS 14+ support
• Apple Silicon / MPS support
• uv as a recommended install path
• CLI / API / Gradio as supported entrypoints

But in practice:

• CI is currently Ubuntu-centric, so macOS installation regressions are harder to catch early
• the quick start does not clearly spell out the recommended first verification sequence on macOS
• first-time model download behavior can still be confusing for new macOS users, especially on Apple Silicon and in regions where huggingface is unstable

This is not a duplicate of existing macOS runtime bug reports. The proposal here is specifically about CI coverage and onboarding/documentation gaps.

Related but not duplicate issues

There is already enough evidence that macOS is an active user path, not an edge case. Examples:

• Installer not readable on Mac #4370
• 在 Python 3.10 上运行 magic-pdf 1.3.10 时出现 HFValidationError 及 transformers 版本冲突 #2452
• batch_ratio calculation on 'mps' devices doing pipeline mode #3882
• 希望支持GPU适配加速后端mps #1204
• MacOS M1 Chip Failed to use #1197
• "Illegal hardware instruction" error when running magic-pdf on macOS Sonoma with M1 chip #273

Related docs/workflow context:

• Documentation: Clarify CLI output file formats for per-page text extraction #4540
• .github/workflows/update_base.yml uses a deprecated Node.js version #686
• 【QA】1.0版本文档quick start环节，图片/ppt/doc 不支持txt mode #1442

These issues span installer UX, Apple Silicon dependency/runtime behavior, MPS-related execution expectations, and documentation/workflow maintenance.

Proposal

1. Add a macOS smoke automation job

Suggested scope:

• runs-on: macos-latest
• Python 3.12
• install via uv venv --python 3.12 + uv pip install .[core]
• smoke checks only:
  • mineru --version
  • mineru-models-download --help
  • mineru-api --help
  • mineru-gradio --help

Out of scope for the first iteration:

• real model downloads
• long parsing jobs
• network-sensitive end-to-end validation

2. Improve the macOS quick start

Suggested additions in both Chinese and English docs:

• recommend uv first on Apple Silicon
• suggest a first verification sequence:
  • mineru --version
  • mineru-models-download --help
  • mineru-api --help
  • mineru-gradio --help
• clarify that the first real parse may download models, which is expected
• recommend export MINERU_MODEL_SOURCE=modelscope for users in regions where huggingface is unstable
• recommend starting with -b pipeline for the most predictable first run on macOS

Non-goals

For the first upstream contribution, I do not recommend:

• adding a new repository-level scripts/ entrypoint
• adding .command launchers
• auto-installing system dependencies like uv or brew
• introducing shell wrappers that manage ~/mineru.json or local model state on behalf of users

Those workflows may be useful locally, but they seem more like personal/operator tooling than the minimum maintainable surface for the core repository.

Why this direction

From the repository + website + docs perspective, this seems like the lowest-risk, highest-acceptance contribution path:

• aligns with support already promised in README/docs
• adds validation without expanding the runtime surface area
• improves macOS onboarding without competing with the official client / hosted product surfaces
• matches the kind of small documentation-oriented improvements that have already been accepted upstream