project-4cdad308_rk3588 相对 AAPGS_model_20260714 变更记录
================================================================

对比基准
--------
旧包：AAPGS_model_20260714.tar.gz
新包：project-4cdad308_rk3588.tar.gz
对比日期：2026-08-04

一、总体结论
------------
新包不是对旧包的简单重命名，而是包含新模型、新运行时 ABI、新版公共 C API、
新版示例程序和更新验证记录的一次完整升级。新旧包的二进制接口不兼容，使用旧包
头文件或链接 libyolo_runtime.so.2 的应用程序不能直接替换为新包，必须依据新版
头文件重新适配并重新编译。

二、包信息变更
--------------
1. 包名称由 AAPGS_model_20260714 变更为 project-4cdad308_rk3588。
2. 压缩包大小由 14,199,356 字节减小为 6,859,304 字节，减少 7,340,052 字节，
   约减少 51.7%。
3. 解压后文件总大小由约 41.37 MiB 减小为约 14.50 MiB。
4. 普通文件数量由 37 个变为 38 个。
5. 两包存在 31 个相同相对路径，其中 11 个文件内容完全一致，20 个文件内容已修改。

三、模型及配置变更
------------------
1. 模型名称：
   旧：model_20260712T020258_0000_6339d04b
   新：project-4cdad308

2. 模型版本：
   旧：1.0.0
   新：20260804_000209_109_cb390eaf

3. 模型文件：
   旧：models/model_20260712T020258_0000_6339d04b/
       model_20260712T020258+0000_6339d04b.rknn，3,547,568 字节
   新：models/primary/model.rknn，3,550,128 字节

4. 分类标签：
   旧：a320、b737，共 2 类
   新：a320、b737、other，共 3 类

5. RKNN 输出张量：
   旧：[1, 2]，输出结果 2 项
   新：[1, 3]，输出结果 3 项

6. 模型配置新增或调整：
   - 新包明确增加 model_family: "yolo8"。
   - 新包明确增加 output_contract: "task_specific"。
   - 后处理适配器由 ultralytics_yolov8_cls 调整为 ultralytics_yolo8_cls。
   - 新包增加 bbox_edge_tolerance_px 和 pose_keypoint_tolerance_px 验证参数。
   - 模型配置路径统一为 models/primary/model.yaml。

四、运行时及 ABI 变更
--------------------
1. 公共 Runtime ABI 由 3 升级为 5。
2. 主要运行库 SONAME 由 libyolo_runtime.so.2 升级为 libyolo_runtime.so.5。
3. libyolo_runtime.so 大小由 263,440 字节变为 297,920 字节。
4. libyolo_backend_cls.so 大小由 957,664 字节变为 961,832 字节。
5. 新包额外保留 libyolo_runtime.so.3 和 libyolo_runtime.so.3.0.2 文件；
   但未包含旧包所需的 libyolo_runtime.so.2，因此不具备旧 ABI 2/3 应用的直接
   二进制替换条件。
6. librga.so 和 librknnrt.so 的内容未发生变化。

五、公共 C API 变更
------------------
1. 增加 YOLO_RUNTIME_API 导出符号宏。
2. yolo_runtime_create() 增加结构化错误信息参数。
3. 原 yolo_runtime_get_capabilities() 被新版 yolo_runtime_get_info() 取代。
4. 推理输入结构由 yolo_image_view_t 升级为带版本号的 yolo_image_view_v1_t。
5. 增加 yolo_infer_options_v1_t，可指定分割几何计算方式。
6. 推理结果由调用方持有的固定 yolo_result_list_t 数组，改为运行时返回的不透明
   yolo_result_set_t 对象。
7. 增加结果数量、性能数据、公共结果、检测框、旋转框、分割掩码、分割几何和
   姿态关键点等独立读取接口。
8. 增加 yolo_result_set_release()，调用方必须显式释放结果集。
9. 增加 ABI 不匹配、缓冲区过小、结果不可用、配置无效、索引越界等状态码。
10. 数据结构统一增加 struct_size、version 和 reserved 字段，以支持后续扩展。

六、示例程序变更
----------------
1. C/C++ 示例已适配 Runtime ABI 5 和新的结果集接口。
2. 预编译示例程序已重新构建：
   - yolo_c_example：18,808 字节变为 23,432 字节。
   - yolo_cpp_example：23,912 字节变为 24,544 字节。
3. 新示例增加 --seg-geometry rect|circle 参数支持。
4. 新示例使用 yolo_error_info_v1_t 返回创建及推理错误信息。
5. result_json 模块已改为通过新版结果查询接口生成 JSON，并扩展对不同任务结果
   类型的支持。
6. 交叉编译检查目标由 libyolo_runtime.so.2 调整为 libyolo_runtime.so.5。

七、示例资源变更
----------------
1. 旧包包含：
   - examples/assets/a320.bmp，15,040,566 字节
   - examples/assets/b737.bmp，15,040,566 字节
2. 新包改为：
   - examples/assets/sample.bmp，1,228,854 字节
3. 旧包的 package.env、manifest.json 和运行脚本声明使用
   examples/assets/sample.bmp，但旧压缩包实际未包含该文件。因此按旧包自带脚本
   直接运行会找不到示例图片。
4. 新包中的 PACKAGE_SAMPLE_IMAGE 与实际 sample.bmp 文件一致，消除了该资源路径
   不一致问题。
5. 示例图片精简是新包体积明显下降的主要原因。

八、文档及交付元数据变更
------------------------
以下文件均已更新：
- README.md
- docs/C_API.md
- docs/DEB_INTEGRATION.md
- docs/INSTALL.md
- docs/MODEL_CONFIG.md
- manifest.json
- package.env
- verification.json
- build/cross-build.log

新 manifest.json 额外记录：
- projectId
- projectKey
- modelVersionId
- deliveryContractVersion
- modelSlot
- compatibilityFingerprint
- layoutFingerprint

九、验证记录变更
----------------
1. 两个包的 manifest.json 和 verification.json 均记录：
   - 已完成 AArch64 交叉编译。
   - 已在 RK3588 上验证。
   - 设备内核为 5.10.209。

2. 旧包记录的验证时间为 2026-07-15，推理输出为 2 类。
3. 新包记录的验证时间为 2026-08-04，C/C++ 示例均输出 3 类结果；记录的单次
   RKNN 推理时间约为 3.78～3.92 ms。

十、保持不变的主要内容
----------------------
以下 11 个共有文件的 SHA256 完全一致：
- examples/c/build.sh
- examples/c/CMakeLists.txt
- examples/c/run.sh
- examples/common/bmp_loader.c
- examples/common/bmp_loader.h
- examples/cpp/build.sh
- examples/cpp/CMakeLists.txt
- examples/cpp/run.sh
- lib/librga.so
- lib/librknnrt.so
- scripts/install.sh

十一、迁移注意事项
------------------
1. 旧应用不能只替换 .so 文件；需要同时更新头文件、调用代码并重新编译。
2. 业务代码需要处理新增的 other 分类，不能继续假定结果恒为 2 类。
3. 推理结果使用完毕后必须调用 yolo_result_set_release()。
4. 应按新 package.env 使用 models/primary/model.yaml 和
   examples/assets/sample.bmp。
5. 上述“设备已验证”结论来自两个交付包内的历史验证记录。本次工作完成了压缩包
   清单、文件哈希、配置和源码的静态比对，但未重新连接 RK3588 进行现场复测。