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 选项、无效语言和解析失败的退出代码和消息。
验证¶
测试验证:
- 所有四个直接注册的命令保留其参数、选项、默认值和帮助文本。
- Parse 命令的值到达现有实现行为。
- API-server 选项(包括单一启动层级和
--no-flash)不变地到达底层 Click 命令。 - 无效的 API-server 启动层级和
--tier flash --no-flash保留结构化 CLI 失败。 vlm-server和router继续通过ctx.args接收未知参数。- Router 选项(包括重复的
--upstream-url)不变地到达旧版 router。 - 根命令顺序保持不变。
- 受跟踪的单元测试套件保持通过。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU