# 图像系统性能、配额与诊断

目标设计与 API 草案，尚未实施。总体边界和推进状态见设计概述。

本文负责跨图像、节点、队列、采集、调试和显示的成本口径与诊断；格式扩展及显示账本各在对应专题维护。

关联：模型 · ToolFlow · 显示预算 · 验证

# 配额作用域与成本归属

相同 BufferId 的多个视图可以共享像素成本，但仍有 handle 和队列对象成本。同一分配在多个组件的局部读数中可能重复出现，只有明确作用域的去重账本才可汇总为物理保留量。SDK 槽位、托管分配字节、GPU 纹理和每秒复制带宽分别报告，不合并成一个含糊的“内存占用”。

# 热路径与内存成本

同步可授予时使用 ValueTask 快速路径，不为每次读取启动 Task.Run。清理回调、权限唤醒和用户 continuation 都在协调锁外执行；任务完成采用异步 continuation 方式，避免锁内重入。取消注册在请求结束时解除，取消只让一个授予/释放结果获胜。

handle 保持引用类型，避免可复制 struct IDisposable 造成多份伪所有权。不默认复用暴露给用户的 handle 对象，防止旧引用访问到被重新分配的新资源。物理像素存储可以池化；访问状态池化若实施必须证明没有 ABA、取消回调或尚未消费的 ValueTask 指向已复用状态。公开 ValueTask 按一次消费规则使用，需重复等待的归还事实用 Task。

任务/归还信号尽可能延迟创建，未订阅诊断的普通路径不捕获调用栈。可以按节点执行多个行任务，但它们共享同一独占写入阶段，调用方负责写区域不重叠，并在 Complete 前全部结束；不扩展为多个 ROI 并发写锁。长时间 native pin 计入持有时长及 pinned bytes，不能只统计托管对象数量。

大图操作按行进行取消检查和范围检查，避免要求整个 native 长容量存储构成一个 int 长度 Span。克隆整理成受控私有排列，精确保留原始格式。清理、临时色彩转换、复制和上传的峰值一起计量；吞吐优化不能以延迟归还 SDK 到无限队列为代价。

# 会话账本与诊断

核心可提供可选的资源诊断快照：BufferId、Generation/有效状态、保留字节、handle 数、活动读/写、等待申请、pin、归还状态与持有时长。会话、队列和预览适配另记接收/拒绝/替换计数、队列高水位、在途工作、归还延迟与归还失败。多个层级读数有不同含义，不用“节点 Task 已结束”推导内存已归还。

诊断注册在实际归还终态解除，不能用全局强引用表永久保存完整图像或节点。详尽节点/调用栈追踪按需开启，普通路径以计数和标识为主。Debug 检测未完成写入、重复交接、跨期访问和会话外保留；检测结果不能触发不安全的强制回收。

实施验证至少覆盖持续运行后内存和外借槽位达到稳定平台、停流后回到基线、归还延迟尾部、吞吐与丢弃率、复制带宽、UI 卡顿及故障恢复。报告实际格式、尺寸、采集速率、图像池/队列容量、SDK 协议、机器与后端；在没有测量前不承诺固定帧率、零分配或零泄漏。

# 场景与证据口径

这些是验收要求，不是本轮文档拆分已经取得的性能结论。实际平台、负载矩阵与退出条件统一见验证与完善路线。