Clean JSON 工具包

要解决什么问题

API 响应、配置文件和 JSONL 事件流都是嵌套 JSON：路径深、类型杂、文件大时，用 python -m json.tool 或临时脚本往往只能「漂亮打印」，很难系统回答「这条记录里到底有哪些字段、各出现多少次、某路径下取值长什么样」。若再叠加 jq 依赖、jsonschema 安装或要在 CI 里做合并/补丁，运维和 Agent 流水线里的摩擦会明显变大。

clean-json-toolkit 是 clean-* 系列里专门处理 JSON/JSONL 的一员：与 csv、text、log 工具包一样，纯 Python 3 标准库，不 eval、不 subprocess、不远程调用，路径查询走自研 tokenizer，并遵循与同系列一致的 safe-path 策略。

核心能力怎么组织

脚本按「看清结构 → 取数 → 变形 → 约束 → 组合变更」排列：

• scripts/inspect.py：对 .json / .jsonl 做剖析，输出每条 distinct path 的类型、计数，以及每路径最多 N 个样本值，适合陌生 payload 摸底。
• scripts/query.py：jq 风格路径（如 .key.nested、.key[0]、.[]、.key.[].field）；输出 --json / --jsonl / --lines / --raw；JSONL 输入默认在顶层逐条迭代。
• scripts/flatten.py / --unflatten：嵌套对象压成点号键，支持可逆往返。
• scripts/validate.py：轻量 schema（required、type、min/max、min_length/max_length、enum、regex、item_type、allow_extra）。
• scripts/merge.py（v0.2.0）：多文件合并，策略含 deep（默认，数组替换）、shallow、array-concat、array-uniq、array-extend（要求输入均为数组后拼接）——典型场景是 defaults + 用户 + 环境配置级联。
• scripts/patch.py（v0.2.0）：RFC 6902 JSON Patch（add/remove/replace/move/copy/test）；可 --op --path --value 内联或 --patch FILE；--strict 首错即停，--dry-run 只输出不写盘；支持 "/items/-" 追加数组。

退出码约定：0 成功或有结果；1 无结果/校验失败/空输入；2 参数错误、不安全路径、缺文件、非法 JSON 或 schema 问题。

适用边界

• 不是 jq/jsonschema 的全量替代：查询语法与 schema 能力刻意做小，换的是零 pip、可脚本化、与同系列一致的安全模型。
• validate 的 schema 是内置子集，复杂 $ref、多版本 JSON Schema 草案需另选工具。
• merge 策略要选对：例如 deep 下数组合并是替换而非拼接，级联配置常用 array-concat 或 array-extend。
• 可与 clean-csv-toolkit、clean-text-toolkit、clean-log-toolkit 串联：表格、纯文本、带时间戳日志与 JSON 各管一段流水线。