# 机器视觉基建验证与完善路线
目标设计与 API 草案，尚未实施。总体边界和推进状态见设计概述。
本文区分确认契约、待细化机制和尚未取得的证据，组织收敛与验收，不改写当前控件事实。
# 当前确认与待细化边界
| 范围 | 已确认 | 仍需具体化或验证 |
|---|---|---|
| 图像模型 | 四格式、Info 合并、稳定 ReadOnly 与可写输出分离 | 泛型返回桥接的最小编译证据；工厂与外部适配边界 |
| 内存 | 独立引用、共享读/独占写、显式完成、pin 延寿 | 初始根范围登记；权限/取消竞争；归还并发与容量预约 |
| ToolFlow | 顺序 Run、终端链接、输入不可改写、稳定输出 | 输出集合与队列接管的最小集成接口、配额与诊断关联 |
| 最近输出 | KeepLatest 与连接分离，动态打开稳定引用 | 空集合、快照不可用的完整事件语义；订阅/重放/淘汰竞争 |
| 相机 | 可持帧则导入，否则回调内复制 | SDK 在 Stop/Close/断线时的地址保证、线程协议和池余量 |
| 显示 | 直接接收图像，复制/保留/脱离分别确认 | 四格式后端能力、线性化/mip、上传成本及像素对照 |
| 性能 | 全链路有界，真实归还与任务完成分离 | 稳态内存、归还尾延迟、停流基线、故障和平台证据 |
开放项不能弱化确认契约。例如可评估编译期只读接口，但不能允许工具流改写已发布输入；某 SDK 不支持持帧时复制接入，不假设地址一直有效。
# 分阶段推进与退出条件
| 阶段 | 涉及专题 | 退出条件 |
|---|---|---|
| A. API 契约 | 图像模型、内存 | 最小声明可编译；格式、所有权、能力上限及错误类别一致 |
| B. 存储协调 | 内存、诊断 | 初始化/恢复、最后引用、pin、取消/授予竞争及回调失败可验证 |
| C. 工具与队列 | ToolFlow、会话 | 0→0/0→N/N→0/N→M、暂存失败、部分路由、容量和清理规则可执行 |
| D. 相机适配 | 采集、会话 | 持帧/复制、SDK 满池、归还变慢、断线、排空与超时有证据 |
| E. 输出观察 | 动态调试 | 最近集合替换、空/不可用结果、动态连接、重放和查看者寿命一致 |
| F. 显示集成 | ImageDisplay、示例 | 四格式、ROI/负步长、取样、脱离、卸载/context 重建及失败保留 |
| G. 系统验收 | 全部专题 | 长时间负载/故障验证、平台说明、NativeAOT 和当前文档迁移 |
阶段可在文档和原型层交叉推进，集成不能绕过前置资源安全验证。本轮只完成文档组织与契约整理，没有接口原型、源码工程或运行验证。
# 设计收敛时优先处理的问题
- 类型能力：当前格式接口仍暴露写申请，输入由 Access.ReadOnly 在运行时拒绝。评估编译期只读时同时考虑工厂、Clone、ShareImage 和泛型桥接，避免两套图像模型。
- 发布完整性：首次根范围、正常 ROI 改写与 Invalid 恢复有不同边界，需收敛到能验证的协调状态，不把 Complete 当成自动覆盖检测。
- 清理调度：接受 SDK 引用前预约归还容量；一个卡住的供应商回调不能阻塞其他存储。抽象、并发与关闭归属在实际 SDK 协议下验证。
- 集合观察：最近输出按调用集合更新。空集合、保留失败和淘汰也需通知，不能只发送存在图像的 ImageOutputKey；完整事件模型与最小 API 同阶段完善。
- 配额口径：区分唯一分配、逻辑视图、SDK 槽、打开的调试引用和退休任务，明确预约、释放及故障成本。
正文在对应专题维护，本表只记录推进入口，不建立第二份 API。
# 当前实现与目标边界
| 项目 | 当前源码事实 | 目标设计 |
|---|---|---|
| 输入 | 静态 ImageSource 与专门的 FrameImageSource | 控件直接接收 IPixelImage，文件解码在图像创建阶段完成 |
| 内容模型 | ImageFrame 同时拥有 owner 和一次提交身份 | 存储、读写对象、静态图像与显示更新分别负责 |
| 编号 | SubmitAsync 要求 FrameId 严格递增 | 业务 ImageId 可空、可重复、可倒退，不参与排序 |
| 推进 | 单生产者等待绘制确认后继续提交 | 宿主按需设置下一张静态图像，无逐张绘制承诺 |
| 异步协调 | 来源会话、输入等待、绘制背压 | 新请求使旧准备失效，旧任务不能覆盖新意图 |
| 当前缓存 | 快照、mip 与 Skia tile 持有原图引用 | 内部不可变 DisplaySnapshot，区分原始存储与显示映射缓存 |
| 像素查询 | UI 当前原始帧的灰度值 | UI 当前快照的灰度、RGB/BGR 或深度原始样本 |
| 冻结 | IsFrozen 暂停流消费 | 宿主暂停提交即可保持当前图像，不设流冻结状态 |
| 主题与宿主 | Skia composition，主题设置焦点和裁剪 | 本专项不改变主题、坐标、交互或覆盖层职责 |
根因是将显示表面建模成连续帧消费者，使内存寿命、业务帧号和生产调度互相绑定。目标直接表达“设置当前图像”，不再叠加第二套流发布 API。
本次仅调整 specs。目标涉及 FrameImageSource、帧相关成员与事件的迁移或删除，是明确的 API/行为重设计，不再以“旧流协议完全保持”为目标。实际实施时同步库、Gallery、测试和当前控件文档，不能仅删一条帧号比较而保留整套流架构。
# 实施边界、迁移与验证
本次只调整设计稿，不修改源码、Gallery 或现有控件说明。实施按图像模型、显示捕获与释放、多格式渲染、调用方迁移四部分完成，每部分分别验证；完整交付时统一更新当前控件文档。
基础包抽取、任务流所有权集成和 SDK 会话适配必须有独立验证，不把 ImageDisplay 能显示一张图视为基建已稳定。API 草案中精确格式接口、泛型返回桥接及访问对象创建能力在实施前先做最小编译验证；外部扩展优先通过工厂导入存储和显式格式支持接入，不要求第三方绕过协调实体自行构造访问对象。
| 旧成员或旧草案 | 目标 |
|---|---|
| ImageFrame / FrameImageSource / SubmitAsync | IPixelImage / 格式接口，持续 SetImage 刷新 |
| FrameId 递增、单生产者和绘制背压 | 由宿主调度，不再成为显示契约 |
| ImageDisplay.Source: ImageSource? | Source: IPixelImage?，编码加载在外部完成 |
| PixelImageSource 显示适配层 | 删除该拟议类型，控件直接申请图像读取 |
| 灰度专用 ImagePixel.Gray | 多格式原始样本与显式 TryGet 方法 |
| FramePresentation / FrameRendered | ImageDisplayUpdate / ImageRendered，安装与绘制分开 |
| IsFrozen | 宿主暂停提交，当前快照保持静态 |
这是明确的 API/行为重设计；特别是 Source 类型与文件加载职责变化，不承诺旧二进制或 XAML 写法兼容。不得通过 Source: object、隐式格式猜测或保留另一条私有流管线掩盖迁移。现有模板、视口、覆盖层、工具接口和渲染后端继续复用；工具的像素展示与 Gallery API 示例必须同步调整。
验证重点：
- 四种图像接口与 Info/像素类型一致；工厂、Clone、Share、ROI、负步长、行尾空隙不破坏语义或布局。
- 基础包无 Avalonia/Skia/控件/流程引擎依赖，文件解码适配不能反向污染图像核心。
- 覆盖 0→0、0→N、N→0、N→M、图像列表、输入别名、多 ROI 输出、空/可选输入及非图像容器内图像的所有权。
- ToolFlow 链接校验无环（禁止反馈环）、顺序 Run；0～N 输入/输出全部稳定 ReadOnly；排队/分支保持内容，输入写申请立即拒绝，Clone 的新存储才可写。
- 已暂存多个输出后失败、AddOwned 中途拒绝、重复 handle、借入输入误提交、下游部分接受时都恰好关闭对应所有权。
- 无下游输出仍可被调试观察；缓存淘汰与打开竞争、连续运行/重试定位、共享/独立快照及配额失败均不破坏业务输出或已打开查看者。
- 调试器运行中连接、断开和重新连接不影响流程；KeepLatest 可重放当前集合，查询/订阅不漏更新，ReleaseAfterRouting 不冒充可恢复已回收历史。
- 节点成功的空输出清除旧当前集合，失败不冒充新的成功结果；最近输出替换、已打开查看者和 SDK 脱离分别管理引用。
- ToolFlow 自有输出的调试观察可稳定 Share，不阻塞后续创建新输出；SDK 快照仍验证及时归还，共享查看者未退出不误报原槽已回收。
- 初次只写 ROI 不可发布整图，ROI 写入中止使全存储 Invalid，普通类型化写不能错误恢复；padding 不进入默认导出。
- SDK 持帧与回调临时指针分别验证；地址复用不复用 BufferId，停止/断线协议不使在途地址提前失效。
- SDK 满池、归还线程变慢、归还失败、Latest 连续替换和 UI 长时间暂停均保持约束，回收责任可追溯。
- 排空和中止分别验证，节点/native 不响应取消时不强制释放；正常停流回到资源基线，外部保留和归还失败明确报告。
- 输出暂存、输入队列、缓存、合流配对表、并发节点及临时分配都受限制，不能仅证明控件缓存有界。
- 相同实例重复提交、相同或倒退业务编号均合法；原地写入完成后只有显式新请求才刷新。
- SetImage 对稳定输入保留固定内容，对可写输入异步申请读取；不把通用请求登记误报成已完成捕获，期望版本按实际授权验证。
- 当前 RetainInput、写者排队、同图或同缓冲 ROI 重复提交时，复用已授予读取，不排队形成读写自锁；脱离副本的来源身份不误当实际原图读取。
- 同一原图分别供多个算法和窗口读取，所有权独立，调用方关闭 handle 不破坏已经登记的显示。
- 一个准备工作和最新候选有界；快速提交、权限等待、替换和卸载不会积累旧读取或发生授权/取消泄漏。
- 候选失败保留旧图，Source/Current/渲染消息职责清晰，过时输入或显示参数任务不能覆盖最新意图。
- RGB/BGR 通道正确；Depth16 范围、无效码、尺度缺失、边界夹取和色表结果明确，ushort 运算不下溢。
- UI 取样是原始像素；缩小、伪彩、曝光变化与副本脱离均不改变取样值或来源版本。
- Snapshot 和 Detach 保存完整原格式；候选未授予读取、复制中和已安装阶段均能正确脱离。
- Completion、InputReleased、ImageRendered、ReturnCompleted 互不冒充；卸载及清空只排空对应旧输入。
- SDK 的调用方 handle、原图读取和 pin 未关闭时不得误报真实归还；native 工作真正退出前不复用其缓冲。
- CPU/GPU 计量覆盖格式差异、暂存、重叠 ROI 去重、峰值与退休工作；预算失败不提前丢弃旧画面。
- 文件加载的宿主顺序校验、错误归属和取消清理明确，控件没有残留第二条编码来源或流输入通道。
- 模板重建、隐藏、重挂载、图形 context 重建与真实后台绘制遵守同一快照寿命；不以仅模型单测替代显示验证。
- 生成器、绑定和接口分发不依赖运行时反射扫描；发布前完成对应 NativeAOT 验证。
测试生命周期遵循测试价值与生命周期。实施需分别报告构建、模块测试、真实显示、多格式持续更新负载和 NativeAOT。本次文档仅检查链接、API 一致性与 diff，不提供实现或性能验证结论。