CLI JSON 模式报错一致性整改计划¶
日期: 2026-06-17
状态: 待实施
范围: mineru/cli_next 中所有已支持 --json 的命令,在业务错误和“服务未运行/无法连接”等场景下统一输出结构化 JSON;同时收口 mineru server status --json 在 server 未运行时的输出。
非目标:
- 不为当前尚未支持 --json 的 mutation 命令补加 --json
- 不改变 parse --json、read --json 的成功响应顶层 shape
- 不处理 Typer / Click 参数解析阶段的框架默认错误输出
1. 背景¶
当前 cli_next 中大多数命令已经提供 --json,但错误路径并不统一:
mineru parse --json已会输出结构化 JSON error。read、search、find、watch、config、show、cleanup、forget、server status等命令,在业务错误下仍会输出纯文本错误。mineru server status --json在 server 未运行时当前会输出"Server is not running."文本,而不是稳定 JSON。
这使得 --json 不能被稳定地当作机器接口使用。
2. 目标¶
统一规则如下:
- 已支持
--json的命令,在进入命令实现之后发生的业务错误,stdout 必须输出:
{
"error": {
"type": "invalid_request_error",
"code": "some_code",
"message": "...",
"param": "..."
}
}
-
stderr不得混入额外的人类解释文本;stdout 不得混入Error:、Written to、Rich 样式文本或 traceback。 -
mineru server status --json在 server 未运行时,不走 error JSON,而是返回稳定的状态 JSON,例如:
理由:这不是异常,而是命令查询到的合法状态。
- Typer / Click 在参数解析阶段产生的错误维持框架默认行为,当前阶段不在本计划内统一。
3. 影响命令清单¶
本计划覆盖当前已支持 --json 的命令:
mineru parsemineru readmineru scanmineru watch add/list/remove/rescanmineru searchmineru findmineru list files/docs/parses/scansmineru show file/doc/parse/scanmineru server statusmineru config show/getmineru config exclude-rules add/listmineru config parsing-rules add/listmineru forgetmineru cleanup deleted-files/orphan-docs/temp
不覆盖当前未支持 --json 的命令:
mineru invalidatemineru config set/unsetmineru config exclude-rules removemineru config parsing-rules remove
4. 实施策略¶
4.1 抽取统一 helper¶
在 mineru/cli_next 中抽取统一的 JSON 错误输出 helper,职责:
- 接受
Exception - 尝试复用
parse已有的MineruError/error_response映射逻辑 - 在
json_mode=True时输出结构化 JSON error - 在
json_mode=False时维持现有print_error(...)
该 helper 应避免每个命令重复手写:
4.2 server status 特判¶
mineru server status 在 json_mode=True 且 server 未运行时:
- 直接输出稳定状态 JSON
- 不走
print_info("Server is not running.") - 不走 error JSON
json_mode=False 时维持当前人类可读提示。
4.3 保持成功响应 shape 不变¶
本计划不调整成功响应结构,只整改错误路径:
parse --json继续使用{parse, content}read --json继续使用DocContentResponselist/search/show/... --json继续直接输出其 response model
5. 分步任务¶
- 新增统一 JSON error helper,并将
parse当前逻辑并入公共实现。 - 将
read、search/find、watch、scan、show、config、cleanup、forget接入该 helper。 - 单独收口
server status --json在 server 未运行时的稳定 JSON 输出。 - 为各类命令补测试:
- 业务错误下 stdout 为可解析 JSON
- 不包含
Error:文本 server status --json在未运行时返回状态 JSON- 更新 CLI 文档和 E2E 用例中对
--json错误行为的预期。
6. 测试矩阵¶
至少覆盖以下场景:
read --json读取不存在 locatorsearch --json非法 tier 或后端错误watch add --json路径不存在show parse --json不存在的 parse idconfig get --json不存在的 keycleanup temp --json非法older_thanserver status --json在 server 未运行时
断言重点:
- stdout 可直接
json.loads(...) - 退出码符合预期
- stdout 不混入人类文本前缀
7. 风险与注意事项¶
- 当前部分异常只是一段普通字符串,需要先尽量映射到稳定错误码;若无法映射,也应统一落到
api_error或等价兜底 code,而不是把纯文本直接塞到 stdout。 - 不能为了统一错误输出而改变成功输出 shape。
- 不能把“server 未运行”误归类为错误 JSON;该场景属于状态查询结果。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU