JSON 变更简报

离线比较两份 JSON，输出新增、删除、变化及 JSON Pointer 路径。适合配置审核和结果快照核对，Python 3.10+，无需安装依赖。

功能与适用场景

查看检查规则与边界，了解具体统计口径及限制。所有工具离线运行，运行时仅使用 Python 标准库；审计不会修改输入文件。报告输出选项可能覆盖指定报告文件。

环境要求

Python 3.10 或更新版本，支持 Windows、Linux 和 macOS。当前验收环境为 Windows；其他平台兼容性尚未实际验证。

获取与安装

git clone https://www.gitlink.org.cn/ZHENAN/json-change-reporter.git
cd json-change-reporter
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS 激活命令为 source .venv/bin/activate。安装会用到 setuptools 构建依赖；不安装也可以直接运行下面的 Python 命令。

快速开始

python report.py examples/before.json examples/after.json

安装后可使用 json-change-report --help；直接运行 python report.py --help 也可查看全部参数。示例文件保存在 examples。

输出和退出码

主要报告字段：change_count、changes（path、kind、before、after）。

退出码：0：相同；1：存在差异；2：输入错误。发现问题或差异的示例返回非零状态属于正常业务结果，不等同于程序崩溃。详细语义及限制见行为说明。

项目结构

json-change-reporter/
├── report.py        # 核心实现与 CLI 入口
├── tests/            # unittest 自动化测试
├── examples/         # 可直接运行的最小示例
├── docs/behavior.md  # 规则、报告及已知限制
├── pyproject.toml    # 安装元数据和命令入口
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── .gitignore
└── LICENSE

项目保持单模块结构，便于阅读和维护；测试、样例和说明分别存储。

开发与验证

python -B -m unittest discover -s tests -v

测试使用临时文件验证真实行为。重复文件项目的符号链接测试在 Windows 权限不足时跳过。贡献时请提供可复现输入和预期结果，详见贡献指南。

常见问题

如果 Windows 应用控制策略拦截安装生成的命令启动器，可使用 python -m report --help，或在仓库目录使用 python report.py --help。无需修改系统安全策略。安装时下载构建依赖失败，可先直接运行脚本，运行本身不需要第三方依赖。

数据与限制

报告可能包含输入原值或本地路径，公开分享前请检查敏感信息。工具采用内存报告，适合日常中小规模数据；大文件或大目录请评估资源开销。当前版本为 0.1.0，未承诺完整格式解析或业务规则判断。

许可证

采用 MIT 许可证。版本记录见 CHANGELOG.md。