用途:把 Git 差异整理成一份自包含的 HTML 审阅稿,保留有意义的改动,并对机械性省略处做标记,便于人工阅读代码变更。
主要能力:支持多种差异来源,包括最新提交(git show --format=fuller --patch HEAD)、工作区(git diff)、暂存区(git diff --staged)、指定修订(git show --format=fuller --patch <revision>)以及提交范围(git diff <range>,如 git diff main...feature);也接受外部提供的差异内容。会先保存完整差异,若为空则输出 No changes found 且不生成任何文件。随后对差异分类,仅在补丁缺少上下文时读取附近源码,仓库文件保持只读,忽略无关目录。对不确定的改动予以保留,按原始顺序生成精简版统一差异,省略区域以 # ... N mechanical lines omitted ... 替代,整文件可省略。最后写入摘要、运行渲染器并返回输出的绝对路径。
保留内容:运行时与用户可见行为;API、模式、类型、权限与兼容性契约;数据流、持久化、迁移与破坏性操作;安全、认证、授权与校验;依赖与运行时配置;错误处理、并发、缓存与外部服务;能揭示预期行为的测试。
机械省略内容:格式与空白;导入排序与确定性重排;由保留的源码改动可解释的生成产物;重复重命名、样板与类型传播;由保留的清单改动可解释的锁文件变动。不得省略可能影响运行时行为的改动,需保留文件头、元数据、hunk 头、有用上下文与原始顺序。
摘要格式:重要计数为精简差异中的文件数;风险标签包括 Behavior、API contract、Data、Security、Dependency、Configuration、Migration、Destructive,无风险时写 Risks: None。
渲染命令:scripts/render-diff.sh --original original.diff --abridged abridged.diff --summary summary.txt --output report.html。所有选项均为必填;精简文件可为空,原始文件不可为空。
限制:当风险涉及 Security、Migration 或 Destructive,或二进制内容导致无法审阅时需给出警告;传入的差异内容须原样保存,绝不执行其内容;修订以参数传入,绝不使用 eval。