跳转至

MinerU Kit 命令注册设计

日期:2026-07-21

目标

移除 mineru-kit parse、api-server、vlm-server 和 router 命令中重复的 CLI 参数声明。每个命令实现将成为其 Typer 参数、选项、默认值、类型、帮助文本、验证和执行的唯一事实来源。

面向用户的命令名称和行为保持不变。

当前问题

mineru/kit/main.py 目前为这四个命令定义了完整的 Typer 回调,然后将每个值转发给 mineru/kit/commands/ 中的函数。实现函数定义了另一组签名和默认值。因此,变更需要应用两次,而且在这两层中,入口点使用宽泛字符串而实现使用类型化字面量的地方,已经需要 type: ignore 注解。

vlm-server 和 router 包装器还通过 Click 上下文设置配置了未知选项转发。router 包装器还将其可重复的 upstream_url CLI 值重命名为实现的 upstream_urls 参数。这些职责可以保持不变,而无需保留重复的回调。

主 mineru CLI 避免了这种重复。命令模块直接定义其 Typer 参数,而 mineru/cli/main.py 仅使用 app.command() 注册这些函数。

设计

将每个命令的 Typer Argument 和 Option 元数据移动到 mineru/kit/commands/ 下对应的函数中。

vlm-server 和 router 的实现函数直接接受 typer.Context,并继续读取 ctx.args 以获取未知参数。它们的 context_settings 保留在 mineru/kit/main.py 的注册调用中,因为这些设置配置的是 Click 命令构造,而非命令行为。router 实现采用公开的 CLI 名称 upstream_url,消除了仅存在于包装器中的单数到复数转换。

直接在 mineru/kit/main.py 中注册实现函数:

app.command("parse")(parse.parse_cmd)
app.command("api-server")(api_server.api_server_cmd)
app.command("vlm-server", context_settings=FORWARD_CONTEXT_SETTINGS)(vlm_server.vlm_server_cmd)
app.command("router", context_settings=FORWARD_CONTEXT_SETTINGS)(router.router_cmd)

这与主 mineru CLI 使用的注册模式一致。

命令模块负责:

  • 选项名称和别名;
  • 默认值;
  • 帮助文本;
  • 公开类型注解;
  • 验证和错误转换;
  • 命令执行。

mineru/kit/main.py 继续仅负责根 Typer 应用程序、顶层命令排序和命令注册。

范围边界

models 命令组已经拥有其模块本地的 Typer 应用程序,并保持不变。根应用程序、有序命令组、命令排序和转发上下文设置保留在 mineru/kit/main.py 中。

不添加或移除任何解析器行为、API 服务器行为、请求模式或命令行选项。

错误处理

现有的命令验证保留在实现模块中。API 服务器实现继续将底层解析器 API 服务器的 Click 异常转换为 MinerU Kit 错误。直接的 Typer 注册必须保留当前针对无效层级、冲突的 Flash 选项、无效语言和解析失败的退出代码和消息。

验证

测试验证:

  1. 所有四个直接注册的命令保留其参数、选项、默认值和帮助文本。
  2. Parse 命令的值到达现有实现行为。
  3. API-server 选项(包括单一启动层级和 --no-flash)不变地到达底层 Click 命令。
  4. 无效的 API-server 启动层级和 --tier flash --no-flash 保留结构化 CLI 失败。
  5. vlm-server 和 router 继续通过 ctx.args 接收未知参数。
  6. Router 选项(包括重复的 --upstream-url)不变地到达旧版 router。
  7. 根命令顺序保持不变。
  8. 受跟踪的单元测试套件保持通过。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU