@microi.net/cli 6.2.4 → 6.3.2

package/skills/vision-engine/SKILL.md

@@ -1,280 +1,284 @@
----
-name: vision-engine
-description: 设计、实现、配置、扩展和验收视觉引擎能力。处理 Microi.Vision、V8.Vision、ONNX Runtime、图片或视频帧、商品或物体样本库优先匹配、平台 AI 异步回退、人脸特征与关注人员合规、platform-vision-runtime、microi-vision 前端微服务和应用商城交付时使用。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# 视觉引擎
-
-<!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=vision-engine-000 sha256=70053ac1db19e3d2ea23cc875a3de5fedb7c614d3c348572972309bf4a9ff4a8 -->
-## 先读取相关规范
-
-- 涉及完整表、字段、菜单和权限交付时，读取 `../microi-system-delivery/SKILL.md`。
-- 涉及接口引擎业务逻辑时，读取 `../v8-crud-api/SKILL.md` 与 `../v8-api-config/SKILL.md`。
-- 涉及图片上传、私有 HDFS 或保留清理时，读取 `../v8-file-upload/SKILL.md`。
-- 涉及 AI 回退时，读取 `../ai-engine/SKILL.md`；涉及持久异步任务时读取 `../job-engine/SKILL.md`。
-- 涉及人脸、关注人员、日志、租户或特征向量时，读取 `../v8-security/SKILL.md` 与 `../v8-saas-multi-tenant/SKILL.md`。
-- 涉及全新工作台时，读取 `../microi-microservice/SKILL.md`、`../microi-frontend-sdk/SKILL.md`、`../ui-design/SKILL.md` 与 `../playwright-e2e/SKILL.md`。
-- 涉及官方应用包时，读取 `../app-store/SKILL.md`。
-
-## 固定架构
-
-用户可见的应用、菜单、页面和文档标题统一使用中性名称“视觉引擎”；`Microi.Vision`、`V8.Vision` 和 `microi-vision` 仅作为程序集、API 与 AppKey 等技术标识，不得把“Microi 视觉识别”作为租户界面的固定品牌名称。
-
-Microi.Vision 是可信 .NET 宿主中的最小视觉原子层，只负责：
-
-1. 有界 JPEG/PNG/WebP 解码；
-2. 只从受控模型目录按 `ModelKey` 加载 `model.json + *.onnx`；
-3. 校验模型路径、大小、任务类型、输入参数和 SHA-256；
-4. 用 ONNX Runtime 执行检测、分割、Embedding/FaceEmbedding，并按已安装运行库选择 CPU、CUDA、TensorRT、OpenVINO 或 DirectML；
-5. 对检测框做人脸五点对齐或对象裁剪，归一化向量并执行 HNSW 近邻检索；
-6. 提供 IoU 目标跟踪、连续帧投票和有界帧流入口。
-
-商品/人员表、样本查询、阈值、状态机、AI 回退、业务日志和租户 Hook 必须留在接口引擎。不能把这些逻辑搬入 C# Controller/Service，也不能让 V8 指定模型路径、执行提供程序、Endpoint、API Key、摄像头凭据或其它 OsClient。
-
-固定组件：
-
-| 组件 | 策略 | 职责 |
-|---|---|---|
-| `platform-vision-runtime` | `Managed` | Recognize/Enroll/Result/Recent/Correct/Bootstrap/Capabilities；授权视频图库 CaptureFaces/SaveCaptureSettings |
-| `platform-vision-ai-worker` | `Managed` | 持久任务消费、Microi.AI 视觉调用、回写与敏感图片清理 |
-| `platform-vision-category-options` | `Managed` | 当前租户启用分类选项 |
-| `platform-vision-subject-options` | `Managed` | 当前租户启用对象选项 |
-| `platform-vision-custom-hook` | `CreateIfMissing` | 租户自己的低敏业务扩展，官方升级永不覆盖 |
-| `microi-vision/workbench` | MicroService | 图片、摄像头帧、连续模式、来源阶段、最近记录、纠错与样本录入 |
-
-详细数据、状态、协议和验收规范见 [architecture-and-acceptance.md](references/architecture-and-acceptance.md)。
-
-## 数据库优先，AI 异步回退
-
-识别顺序不可颠倒：
-
-1. 生成稳定 `RequestId`，先按 `RequestNo` 做幂等读取；
-2. 用当前策略的 `PipelineKey/ModelKey` 调用 `V8.Vision.Analyze`，先检测/分割，再对每个目标生成特征；
-3. 只查询当前租户 `Status=Ready`、`Mode` 和 `ModelKey` 一致的样本；
-4. 解保护候选向量，调用 `V8.Vision.Search` 执行 HNSW 近邻检索；
-5. 连续视频调用 `V8.Vision.Stabilize` 做会话级投票；达阈值返回 `Status=LocalMatched, MatchSource=Database`；
-6. 未达阈值且 AI 关闭，返回 `Status=Unmatched, MatchSource=None`；
-7. AI 开启时先保存私有输入并创建共享后台任务，立即返回 `Status=AiPending`；
-8. Worker 收敛到 `AiMatched` 或 `Failed`，前端用同一 `RequestNo` 轮询。
-
-不得同步阻塞前端等待大模型，不得把 AI 结果自动写入可信对象主数据，也不得把本地相似度与 AI 置信度混成一个分数。生鲜的冰冻状态、新鲜度、预估价格/单位/币种也必须按字段保存 `Database/AI/Manual` 来源：样本或对象主数据优先，只有数据库未命中后才允许 AI 推断；AI 价格只是非约束估计，不能直接覆盖门店售价。
-
-历史记录纠错使用 `Correct` 动作：只允许绑定当前租户中启用且模式兼容的对象，记录原标签、原来源、修正人、时间和原因；选择 `SaveAsSample` 时通过来源 `RequestNo` 做幂等录入。AI 结果不得自动加入 `Ready` 样本，必须由有权限的用户明确确认。`Recent/Result` 只返回 `HasImage` 与后端生成的短期授权 URL，禁止把 `InputFilePath`、图片 Base64 或永久公开地址交给浏览器。
-
-## V8 原子函数
-
-```js
-var analyzed = await V8.Vision.Analyze({
-  FileByteBase64: V8.FilesByteBase64['frame'],
-  FileName: 'frame.jpg',
-  PipelineKey: 'general-yolox-dinov2-v1',
-  Mode: 'General',
-  FrameId: 'camera-01-000123',
-  StreamSessionId: 'scale-01-session-42',
-  FrameSequence: 123
-});
-
-var ranked = await V8.Vision.Search({
-  QueryEmbeddingBase64: analyzed.Data.Detections[0].EmbeddingBase64,
-  Candidates: candidates,
-  Threshold: 0.82,
-  TopK: 5,
-  EfSearch: 80,
-  IndexKey: 'ready-general-samples'
-});
-
-var voted = await V8.Vision.Stabilize({
-  StreamSessionId: 'scale-01-session-42',
-  FrameId: 'camera-01-000123',
-  Key: ranked.Data.Matches.length ? ranked.Data.Matches[0].Key : '__unmatched__',
-  Confidence: ranked.Data.Matches.length ? ranked.Data.Matches[0].Similarity : 0,
-  WindowSize: 5,
-  MinimumVotes: 3
-});
-```
-
-主流流水线方法：`V8.Vision.Analyze`、`V8.Vision.Search`、`V8.Vision.Stabilize`；兼容原子方法：`V8.Vision.Extract`、`V8.Vision.ExtractBatch`、`V8.Vision.Compare`、`V8.Vision.CompareBatch`、`V8.Vision.GetCapabilities`。业务入口优先使用 `V8.ApiEngine.Run('platform-vision-runtime', ...)`，不要把向量返回给普通浏览器或日志。
-
-## 模型与准确率门禁
-
-- 默认 `builtin-visual-fingerprint-v1` 只是相同/近似样图指纹，不能称为语义分类器或人脸模型。
-- 内核已经实现 YOLOv8/YOLOX/RT-DETR/SCRFD 常见 ONNX 输出适配、DINOv2/DINOv3/SigLIP2 类嵌入、ArcFace 类人脸嵌入、HNSW、IoU 跟踪和连续帧投票；生产结果取决于实际安装的受控模型包与门店数据，不得把“已兼容”写成“模型准确率已通过”。
-- 模型代码许可证、权重许可证、训练数据限制和商用授权必须分别核对；`model.json` 的 `License` 字段不是法律结论。
-- 每个模型包固定版本、输入尺寸、RGB/BGR、Mean/Std、池化、来源、许可证和 SHA-256；不允许浮动 URL 在线下载后直接加载。
-- 模型必须在目标 CPU/GPU、真实镜头、光照、角度和包装变化下建立标注集，测 Top-1/Top-K、误接受率、误拒绝率、P50/P95/P99、内存和人工复核率。
-- 没有真实模型包与标注结果时，只能说“平台接入完成/指纹联调通过”，不能说“商品或人脸识别准确率通过”。
-- ONNX Runtime 是主流部署运行时，但运行时主流不等于所装模型第一梯队；未测真实标注集与目标硬件 P50/P95/P99 前，不得宣称准确率或速度第一梯队。
-
-## 人脸与关注人员强制边界
-
-- 录入、识别、留存和共享生物特征前必须有合法依据、告知/同意、用途限制、访问控制和删除流程。
-- 手工图片 Face 模式必须要求本次明确同意；视频自动图库使用管理员明确授权的租户配置，缺省关闭，不能把前端默认开关当授权。两条入口都须后端校验。
-- 人脸模板和请求按当前租户隔离；向量使用绑定租户和接口引擎的保护能力保存，列表/Hook/普通日志不返回正文。
-- 默认 `RetainFaceInput=0`；AI Worker 无论成功失败都清理临时图片。
-- 数据库未命中时，大模型只能描述中性可见事实，不得猜姓名、罪犯身份、族群、健康、政治等敏感属性。
-- “罪犯/关注人员”命中仅是人工复核线索，不能单独触发抓捕、处罚、解雇、拒绝服务或身份认证。
-- 身份认证仍使用 DiyToken、Passkey/严格人脸一次性票据和原有权限体系；视觉相似度不能替代登录或强身份验证。
-
-## 视频入口
-
-### 默认全画面与服务端识别
-
-视频巡检必须默认全画面，无需画区或填写录像发生日期即可开启；手机摄像头打开后自动识别。
-工位绘制采用矩形拖动或两个对角点，画面内明确提供“应用工位/重画/取消”；规则与人员核验
-收进可选设置。历史录像未填写发生时间时，邀请时段准入保持Unknown，不使用观看时间兜底。
-主屏必须展示工位状态、占用率/绑定员工在岗率、手机、安全帽、离岗次数/总时长/逐次区间，
-异步行为结果标注原媒体时间，未知不能冒充正常。
-
-v1.9.0 起禁止在巡检浏览器持续执行人员模型；手机仅采集、播放、显示节点签名结果，
-不能再用 MediaPipe/EfficientDet 的本地框独立宣布有人。运行产物不包含推理模型/WASM。
-手机默认后置摄像头并支持前后切换，限制720p/15fps；发送帧长边不超过1280像素，
-检测请求串行、完成后间隔至少500ms，失败退避至10秒，画布复用。后台/卸载释放镜头，
-暂停或切源中止检测与复核，忽略迟到结果。断流、过期帧、局部肢体和画面无效不能当无人。
-手机大幅移动时工位统计标记中断/未知。60秒模拟负载测试不能冒充物理手机温控验收。
-固定RF-DETR legacy Large 560、YuNet/SFace和Qwen3-VL本地复核须分别锁定权重来源与许可；
-预训练可直接推理不等于场景准确率达标，行为无正例或人脸无身份真值时不得声明90%。
-通用节点Compose完整定义vision/behavior/media，默认启动vision+media，behavior为可选profile；API/PC继续复用，必须报告实际容器与复用原生服务的区别。
-服务器准备入口为 `Microi.Server/tools/vision-deployment/deploy.py`，官网原位文档
-`/doc/getting-started/docker-run.html#vision-engine-compose`。它生成一个三服务Compose，
-要求Linux root、空目标目录、已发布镜像摘要和当前租户受限节点密钥；现有租户增设节点
-使用 `--signing-key-file` 复用签名，不能覆盖当前租户密钥使原节点失效。模型固定下载地址、
-大小和SHA，保留原配置及媒体，运行模型只读挂载。Ollama必须设置 `OLLAMA_NOPRUNE=true`，
-避免启动清理未注册的已下载权重；导入阶段暂时可写且无论成功失败恢复只读。
-官方Instruct GGUF导入明确指定 `renderer=qwen3-vl-instruct`、视觉projector和stop token，
-使用独立模型别名，记录实际manifest digest；备份整个模型目录（包含manifests-v2）。
-通用安装默认行为关闭；候选评估必须明确Candidate/Unvalidated，不能变正式告警。正式行为启用须有绑定摘要的独立留出集回执，不能把导入成功、JSON有效或少量样图
-当成90%验收。服务器部署包通过官方MCP公有CDN发布并独立校验，应用私有源码与部署包分开。
-官网必须保留完整、可复制的视觉 Compose 与服务器安装步骤；服务标题独立进入当前页大纲。
-用户要求折叠时，代码置于默认关闭的 details/summary，标题、能力边界与配置入口仍可见；不得以折叠为由删减旧资料。群晖无宿主Python时使用
-`microi.doc/docs/public/downloads/vision/prepare-nas.sh` 与 `import-nas.sh`，仅准备容器使用
-CHOWN/FOWNER，不挂Docker socket；复用固定部署包、镜像与模型摘要。既有目录拒绝覆盖，
-模型续传先校验安装标识；导入核对编排归属并恢复模型只读。DS1821+无GPU，48GB内存不能
-作为CPU吞吐或准确率证明；Linux隔离验证、真实NAS、手机温控与独立准确率验收分别记录。
-FP16/量化候选必须与原精度逐图比较人数、框坐标和输出有效性，出现明显漏检不得发布。
-异步行为模型需限制图片、上下文、输出与GPU占用；超时/格式错误保持未知，不能把复核链路可调用当作动作识别达标。
-
-录像自 v1.9.9 起的旧节点本地/中继路径默认连续播放，保留可选“跟随分析播放（逐帧等待）”，旧单帧结果仅在原采样时刻±120ms绘制。v1.9.11可信公开对象时间轴走已登记HTTPS直连：固定每1秒媒体游标连续分析，默认准确率优先等待已接受且已回读的区段，可显式切换流畅预览，未知不计统计。原PTS结果到对应画面才建立真实纹理锚点；播放等待不覆盖手动暂停，seek只切显示窗口、不跳过后台分析秒。历史查看/切源关闭旧会话、取消原作业，晚回执不作用新会话；详见[可信录像时间轴、身份与私有图库](references/video-timeline.md)。
-
-### v1.9.5 人脸定位与有界跟随
-
-- 节点默认 YuNet 定位只产生 `faceBox/faceScore`，不因定位自动提身份模板。`evidenceKind=body/body-face/face` 区分证据：保留原人体 `box`，仅脸时 `box` 也必须是真实脸框，不补全身体。绘制优先合格脸框、否则人体；全帧 `valid=false` 保持未知清框。
-- 摄像头显示层允许低负载灰度纹理跟随，不重新加载手机神经网络。迟到签名锚点必须按请求 FrameId/sequence 绑定原图，从原帧初始化并有界重放；禁止把旧框先套当前图再匹配。当前实现灰度长边256、8Hz、缓冲/锚点最多6秒，正反校验、纹理分数、几何与耗时预算全部通过才绘制；断流、遮挡、离开、低纹理、过期、暂停及换源及时清除。
-- 节点1.9.8的独立快脸定位使用当前DiyToken和专用签名，单并发不排RF队列，最大640像素；只显示真实脸框，不提取模板/归档，不反向写人数、无人、身份或考勤。无脸不等于无人。
-- 跟随只服务显示，不生成新人数/身份/考勤证据。仅脸可证明默认全画面有人，指定工位须人体脚点；脸下缘不能当脚点。历史有效片段占用率100%与当前待判断可以并存，但UI必须显示有效观测/覆盖范围，避免被理解为当前或全片100%。
-- 回归必须覆盖3秒以上迟到锚点重放、真实像素移动/遮挡/离开、相机媒体时钟、暂停换源晚结果、face优先/body回退、320宽和短横屏明暗布局。模拟设备与桌面纹理耗时不能冒充物理手机温控。
-
-### 授权视频图库、示例与候选行为
-
-- `SaveCaptureSettings` 仅当前租户管理员可用；未配置默认关闭。真正空表首次显式保存才CreateIfMissing默认策略，已有禁用/删除/非默认或歧义策略拒绝而不重置。MySQL下先锁固定sys_config行再当前读，配合ProfileKey唯一索引；不能只用进程锁或RepeatableRead旧快照宣称并发安全。
-- `CaptureFaces` 仅接受可信节点私有签名包，绑定tenant/owner/session/sequence/time/frameId/imageSha256，且主观测valid。签名、质量、数量、私有JPEG与128维模板均有界；relay必须剥离所有私有payload。图库采用独立 `opencv-sface-2021dec-gallery-v1`，不混员工准入person Id、identityQuality或subjectId。
-- 对象/样本通过runtime保护模板和私有存储入库；未知建未命名人员，模糊区不乱合并也不反复建对象，后续名称取权威subject.Name。每帧最多新增1张、公平轮转，每人最多3张且间隔至少30秒；256帧有界ledger记录零新增与成功回执，同帧改包拒绝。当前读与真实双并发验收须在实际提供商执行；当前自动归档仅MySQL验证，其它提供商在上传前失败关闭。
-- Capture使用独立事务；v1.9.6起仅可信runtime明确分类为Operational的图库存储故障返回captureError并保留已验签人员观测，Rejected、签名/身份拒绝、未知分类及网络超时仍失败。失败上传只能补偿本次自有私有路径；数据库事务不等于对象存储原子回滚。普通结果仅gallerySubjectId/gallerySubjectName/samplesAdded，不返回图片、模板或私有路径；runtime/monitor/relay关闭请求正文日志。
-- Bootstrap的CanCaptureFaces来自当前租户授权与管理员权限，前端开关仅在true时有效。v1.9.7的ExampleVideos仅向已登录的同租户查看者只读共享当前默认策略ExampleVideosJson中管理员明确配置且Ready的白名单，节点只接受relay权威签发的ReadOnlyExampleAssetIds，观测owner/session仍绑定查看者；非示例媒体、上传/删除及人脸样本和模板不随之开放，用户明确授权的原片可通过独立BackupPublic流程公有发布，不开放图库或匿名识别；桌面显著提供示例入口，手机初始仍camera。官方包DataSelections只保留非空分类种子，不导出profile/AutoCaptureFaces/ExampleVideosJson/CaptureReceiptsJson及任何客户样本或录像。
-- 行为使用POST `/behavior-jobs`、GET/DELETE `/behavior-jobs/{32位小写hex}`，单并发、2秒轮询、有界600秒生命周期；暂停/切源/卸载取消所属旧节点任务。Queued/Running/Completed/Failed/Cancelled/Expired分别呈现。Completed必须核对原session/sequence/time与签名，来源错配拒绝。
-- 安全帽/手机使用/拍摄当前进入candidateEvents，标Candidate/Unvalidated/需复核、原帧时间和模型摘要，formalBehaviorCount保持0；不能靠节点自报validated升级正式违规。完成无候选也不构成90%通过；模型未配不发无效任务。正式门禁、候选演示与专用模型研究分开报告。
-- UI以视频、紧凑工具栏与六指标为核心，历史/候选明细用抽屉或内部滚动，不堆叠长页。明暗/安全区/320宽/手机前后切换继续验收；不为科幻效果牺牲未知提示或添加高耗持续动画。
-
-工作台提供可见的服务设置入口，通过 capabilities 区分节点未连接、模型未配置、复核失败与画面未知；缺少行为模型时不发送无效 review，也不显示一直“复核中”。NAS 平台中继无需浏览器填写 NAS 内网地址；直连的公开地址由管理员在普通系统设置的 sys_config.VisionEdgePublicBase 维护，签名密钥 Vision.Edge.SigningKey 才属于安全与服务接入，不得暴露或被页面覆盖。公开地址仍须经过租户与可信来源校验。专用 CPU 模型诊断、目标 NAS 吞吐和独立场景准确率分别验收。
-
-用户指定DSM反向代理时按实际规则核查HTTPS域名/证书、目标节点环回端口和空闲监听端口；指定1000–1999范围也不能猜端口或覆盖既有规则。配置成功后将公开HTTPS地址经同源MCP保存普通VisionEdgePublicBase并回读，再验收直连与允许来源；秘密仍仅在安全配置。反代、应用发布、节点运行及物理手机分别留证，不以中继可用替代用户指定的直连交付。
-
-`OfficialApplications/Vision` 是应用工程，`src`为Vue微服务、`engines`为V8业务，
-`edge`为额外部署的Python视频节点；`Microi.Vision`仍是独立闭源.NET内核。
-应用源码发布不能冒充.NET内核更新或节点部署；不能因目录都包含Vision而声称后端完全统一。
-
-### 视频巡检模式（v1.5）
-
-`microi-vision/workbench` 保留图片模式，增加录像/手机摄像头/登记监控源巡检。
-责任源码为 `Microi.Server/OfficialApplications/Vision`，规范由
-`OfficialApplications/Resource/vision-release.json` 锁定；旧 AI-Project 镜像不作为新版本发布源。
-
-- 两张新增表 `mci_vision_monitor_session`、`mci_vision_person` 与 Managed
-  `platform-vision-monitor` 通过 MCP Manifest 升级；不新增 .NET 定制迁移或业务 Controller。
-- `Create/Read/Close/Bootstrap/Process/Review` 管理本人会话；
-  `People/SavePerson/ClearFace/EnrollFace/MatchFaces` 管理准入与受保护模板。
-- 受信边缘节点只解码/转码/推理，DiyToken 向当前租户核验身份；媒体票据短期有效。
-  RTSP 只来自节点登记的 MediaMTX 路径，摄像头凭据不进入浏览器、普通 V8 或日志。
-- 检测帧 HMAC 绑定 owner、tenant、session、sequence、媒体时刻和新鲜度；
-  `Process` 以数据库 Revision CAS 保存，重复/乱序不重复积分。
-  签名使用真实原子 `V8.Method.HmacSha256Sign(observation, key)`，返回 Base64。
-  节点密钥在 `V8.SysConfig.ServerPrivateSettings['Vision.Edge.SigningKey']`，通过
-  `microi_manage_server_private_secret` 配置，禁止进入源码。
-- `Review` 只追加原视频时刻的候选行为事件，不重放考勤积分、不替换当前检测框，也不计正式违规。
-  一个节点同时最多一项行为复核；人员检测保持独立，不等待大模型完成。
-- 工位不绑定人员时叫“工位占用率”；绑定后才叫“员工在岗率”。
-  身份不明不能替指定员工算在岗，跳播/断流/无效帧前后间隔为未知。
-  录像覆盖率用全片时长作分母，观测区间取并集；倒退识别必须新开会话，不能重复累计同一段离岗。
-- 历史录像的 `rules.recordedAt` 与媒体时间决定邀请核验时刻；签名新鲜度仍由 wallTimeMs 决定。
-- YuNet/SFace 等实际人脸检测和五点对齐后才生成模板；宽高不足80像素、模糊、
-  多人录入不合格。合格未匹配人脸只能产生未登记复核线索，不直接驱动门禁或处罚。
-- 人员/手机/安全帽/拍摄分别标注评估；无正例、未知和模拟视频不能证明90%识别率。
-  具体边缘协议与验收见责任源码 `edge/README.md` 和
-  [架构与验收](references/architecture-and-acceptance.md)。
-
-已有通用 MCP 的 `microi_get_db_schema`、`microi_plan_system`、
-`microi_generate_system`、`microi_validate_system`、`microi_save_engine_code`、
-`microi_run_engine`、私有源码同步和 V3 发布工具已覆盖这条链路；无需增加绕过权限的摄像头工具。
-`platform-vision-ai-worker` 延迟重试用 `await System.Threading.Tasks.Task.Delay(ms)`，
-不能调用不存在的 `V8.Action.Sleep`。
-
-前端使用 `getUserMedia` 并按 `FrameIntervalMs` 取帧，必须提供开启、暂停、继续、立即识别当前帧和关闭操作；每次打开摄像头生成新的 `StreamSessionId`，每帧递增 `FrameSequence`。自动连续模式允许跳过相同画面，人工主按钮必须显式绕过前端去重以提交当前帧。可信边缘宿主将 RTSP/WebRTC 解码为 `IAsyncEnumerable<MicroiVisionExtractParam>` 后调用 `RecognizeFramesAsync`。Microi.Vision 不直接连接调用方提交的 RTSP URL，不保存摄像头账号，不承担流媒体服务器职责。
-
-打开摄像头、`getUserMedia`、`video.play()`、关闭和组件卸载之间必须使用递增操作令牌或等价取消机制。关闭时先同步写入关闭态并使旧操作失效，再停止轨道和清空 `srcObject`；不能等待媒体清理完成后才改 UI，否则快速关闭会被较早的异步打开流程反向覆盖。移动控件或条件渲染按钮可在 `pointerdown` 立即执行停止语义，并对随后 `click` 做短时去重，防止 DOM 重排吞掉关闭操作。
-
-连续帧必须有：最大图片大小、最小间隔、单客户端串行、取消/停止、RequestId 幂等、网络退避和后台任务去重。不能每个视频帧都无界调用大模型。接口返回 `AiPending` 后，前端必须进入 single-flight 状态：暂停提交新帧，只轮询当前 `RequestId`，直到 `AiMatched/AiFailed/Unmatched`、超时或用户取消后才允许下一帧；禁止并行创建多个 AI 任务。
-
-跨版本接口字段必须在协议边界归一化。连续稳定结果至少兼容 `.NET` 原子常用的 `VoteCount/WindowCount/AverageConfidence` 与历史接口的 `Votes/WindowSize/Confidence`，前端只读取归一化 DTO，任何真实响应都不得展示 `undefined/undefined`。
-
-手机收银/巡检工作台属于高频全屏操作面：在宿主提供的可用高度内同时露出取景区、主要识别按钮、当前状态、核心结果和“最近识别”入口，不依赖页面纵向滚动才能完成一次识别；竖屏按采集/结果/最近记录三段紧凑分配，短横屏改为三列，且不得改变已验收的桌面布局。历史列表可以成为卡片内部的唯一滚动区。相机权限拒绝、数据库匹配中、数据库未命中、AI 等待、终态结果和恢复操作都要在当前视口可见，平台底部菜单和安全区不得遮挡按钮。
-
-桌面工作台使用宿主可用宽度，不再用固定窄版 `max-width`；采集、结果、最近记录同屏三栏。预览使用有界容器和 `object-fit: contain`，上传竖图或打开摄像头不能撑高整个页面。不要同时提供语义重复的底部“再次识别当前画面”和主操作按钮；保留一个清晰的“立即识别”，连续模式另提供暂停/继续。
-
-## 交付顺序
-
-### 视频巡检的手机连接与准确率门禁
-
-手机默认选择摄像头；连接优先采用Bootstrap已验证登记的HTTPS节点，未登记时使用平台HTTPS中继（`edge=platform`），用户显式中继选择跨刷新保留，不能把电脑环回节点当作手机自身访问。复用 `platform-vision-edge-relay` / `platform-vision-edge-media` 与16个固定共享技术槽位，节点仅出站连接；受限访问密钥兑换DiyToken，Windows凭据用CurrentUser DPAPI保护。原始图片/特征仅进入短期加密缓存或节点有界内存，不记录在槽位表、浏览器结果或普通日志；官方包不包含节点凭据、运行槽位数据和客户录像。仍支持已登记HTTPS节点直连。
-
-手机视频使用页面内控制和大画面保留跟随标注；不要调用iOS原生video全屏来承载SVG。画区时收起规则面板、定位取景区，控件至少44px，处理自动播放拒绝、横竖屏、相机关闭竞态。录像从节点原分辨率提帧，私有HLS只承担播放；分片上传每段SHA-256，不将整个长视频Base64放入V8。
-
-90%以上必须由真实独立留出集分能力证明。应用准确率门禁要求各项准确率/精确率/召回率/特异度/覆盖率>90%，未知保留在分母；缺少正例或身份真值时不能声明达标。离岗区间另做时间线对账。完整边界与MCP/浏览器验收见 [architecture-and-acceptance.md](references/architecture-and-acceptance.md)。
-
-1. 更新并测试 Microi.Vision、V8 注入与 API DI；
-2. 用 MCP `microi_plan_system` 做 dry run，再生成并 `microi_validate_system`；
-3. 同步私有微服务源码，构建后按 V3 stage/finalize 发布公开产物并回读；
-4. 只发布默认分类种子；策略由管理员显式保存时安全初始化，禁止导出或覆盖租户授权、示例与回执；
-5. 发布框架 NuGet/Docker，使目标运行时实际包含 `V8.Vision`；
-6. 通过官方应用发布引擎生成商城包，明确 `Managed/CreateIfMissing`，回读包 SHA 和不可变版本；
-7. 在目标租户安装/更新后做真实浏览器、接口、后台任务和模型测试；
-8. 分别报告源码、包、制品、部署、浏览器、模型准确率和物理摄像头边界。
-
-`Microi.Vision` 必须作为独立闭源仓维护：`Microi.Anderson.sln` 使用 `ProjectReference`，公开 `Microi.net.sln` 只能使用同版本 NuGet；一键发布必须像 `Microi.AI`、`Microi.WorkFlow` 一样对 DLL 执行 Obfuscar、回写 nupkg，并以加密前后哈希变化及 `.microi-encrypted` 清单为门禁。模型权重继续独立分发，不进入 NuGet。
-
-## 禁止事项
-
-- 禁止用 HTTP 200、构建成功、Mock UI、同一图片命中代替真实商品/人脸准确率。
-- 禁止把大模型标签伪装成数据库命中或权威身份。
-- 禁止把 AI 新鲜度、冰冻状态或估价伪装成传感器、检疫、食品安全结论或正式售价。
-- 禁止把历史识别的原始私有文件路径或永久公开 URL 返回前端，也禁止未经人工确认把 AI 结果自动沉淀为可信样本。
-- 禁止在接口参数中接受模型目录、任意本地路径、任意网络地址或执行提供程序。
-- 禁止把图片 Base64、原始人脸、向量、提示词、AI Key 写入 Hook 或普通日志。
-- 禁止用进程内队列、`static` 字典或本地文件作为 AI 任务完成事实源。
-- 禁止在应用升级时覆盖 `platform-vision-custom-hook`。
-- 禁止只发布商城包却宣称旧平台运行时已经具备 `V8.Vision`。
-
-## 验收输出
-
-视频工作台保持画面优先：紧凑模式栏和来源/识别操作，六项核心指标可见，说明与明细按需展开。
-覆盖暂停、切源、卸载与自动播放受限的异步播放竞态；正常 AbortError 不冒充故障，真实媒体错误不能静默吞掉。
-Python 节点迁入 .NET 时必须分别列明媒体网关、FFmpeg、模型/GPU、行为模型资源及差分验证；未实际迁移不得声称已无额外运行依赖。
-
-最终报告至少分开列出：源码测试、5 表/字段/索引、7 菜单、5 引擎/4 事件、微服务源码与构建哈希、商城包与版本、框架制品、目标节点版本、真实浏览器、PC/手机横竖屏布局、历史图片与纠错、真实图片素材来源、数据库命中、AI 回退、生鲜属性/价格来源、人脸同意、模型准确率和未执行的物理设备测试。
-<!-- /microi-progressive:chunk -->
-## 详细参考路由（渐进披露）
-
-- [references/architecture-and-acceptance.md](references/architecture-and-acceptance.md)：架构与验收
-- [references/video-timeline.md](references/video-timeline.md)：可信录像时间线与快速人脸定位
-<!-- microi-progressive:end -->
+---
+name: vision-engine
+description: 设计、实现、配置、扩展和验收视觉引擎能力。处理 Microi.Vision、V8.Vision、ONNX Runtime、图片或视频帧、商品或物体样本库优先匹配、平台 AI 异步回退、人脸特征与关注人员合规、platform-vision-runtime、microi-vision 前端微服务和应用商城交付时使用。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# 视觉引擎
+
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=vision-engine-000 sha256=feb5033ba2aee8445af8a12bbe47db5064bf263d97262936c9c8478325beb160 -->
+## 先读取相关规范
+
+- 涉及完整表、字段、菜单和权限交付时，读取 `../microi-system-delivery/SKILL.md`。
+- 涉及接口引擎业务逻辑时，读取 `../v8-crud-api/SKILL.md` 与 `../v8-api-config/SKILL.md`。
+- 涉及图片上传、私有 HDFS 或保留清理时，读取 `../v8-file-upload/SKILL.md`。
+- 涉及 AI 回退时，读取 `../ai-engine/SKILL.md`；涉及持久异步任务时读取 `../job-engine/SKILL.md`。
+- 涉及人脸、关注人员、日志、租户或特征向量时，读取 `../v8-security/SKILL.md` 与 `../v8-saas-multi-tenant/SKILL.md`。
+- 涉及全新工作台时，读取 `../microi-microservice/SKILL.md`、`../microi-frontend-sdk/SKILL.md`、`../ui-design/SKILL.md` 与 `../playwright-e2e/SKILL.md`。
+- 涉及官方应用包时，读取 `../app-store/SKILL.md`。
+
+## 固定架构
+
+用户可见的应用、菜单、页面和文档标题统一使用中性名称“视觉引擎”；`Microi.Vision`、`V8.Vision` 和 `microi-vision` 仅作为程序集、API 与 AppKey 等技术标识，不得把“Microi 视觉识别”作为租户界面的固定品牌名称。
+
+Microi.Vision 是可信 .NET 宿主中的最小视觉原子层，只负责：
+
+1. 有界 JPEG/PNG/WebP 解码；
+2. 只从受控模型目录按 `ModelKey` 加载 `model.json + *.onnx`；
+3. 校验模型路径、大小、任务类型、输入参数和 SHA-256；
+4. 用 ONNX Runtime 执行检测、分割、Embedding/FaceEmbedding，并按已安装运行库选择 CPU、CUDA、TensorRT、OpenVINO 或 DirectML；
+5. 对检测框做人脸五点对齐或对象裁剪，归一化向量并执行 HNSW 近邻检索；
+6. 提供 IoU 目标跟踪、连续帧投票和有界帧流入口。
+
+商品/人员表、样本查询、阈值、状态机、AI 回退、业务日志和租户 Hook 必须留在接口引擎。不能把这些逻辑搬入 C# Controller/Service，也不能让 V8 指定模型路径、执行提供程序、Endpoint、API Key、摄像头凭据或其它 OsClient。
+
+固定组件：
+
+| 组件 | 策略 | 职责 |
+|---|---|---|
+| `platform-vision-runtime` | `Managed` | Recognize/Enroll/Result/Recent/Correct/Bootstrap/Capabilities；授权视频图库 CaptureFaces/SaveCaptureSettings |
+| `platform-vision-ai-worker` | `Managed` | 持久任务消费、Microi.AI 视觉调用、回写与敏感图片清理 |
+| `platform-vision-category-options` | `Managed` | 当前租户启用分类选项 |
+| `platform-vision-subject-options` | `Managed` | 当前租户启用对象选项 |
+| `platform-vision-custom-hook` | `CreateIfMissing` | 租户自己的低敏业务扩展，官方升级永不覆盖 |
+| `microi-vision/workbench` | MicroService | 图片、摄像头帧、连续模式、来源阶段、最近记录、纠错与样本录入 |
+
+详细数据、状态、协议和验收规范见 [architecture-and-acceptance.md](references/architecture-and-acceptance.md)；巡检、中继、可信媒体与公开试用组件见 [视频参考](references/video-timeline.md#公开试用与登录时间轴隔离)。
+
+## 数据库优先，AI 异步回退
+
+识别顺序不可颠倒：
+
+1. 生成稳定 `RequestId`，先按 `RequestNo` 做幂等读取；
+2. 用当前策略的 `PipelineKey/ModelKey` 调用 `V8.Vision.Analyze`，先检测/分割，再对每个目标生成特征；
+3. 只查询当前租户 `Status=Ready`、`Mode` 和 `ModelKey` 一致的样本；
+4. 解保护候选向量，调用 `V8.Vision.Search` 执行 HNSW 近邻检索；
+5. 连续视频调用 `V8.Vision.Stabilize` 做会话级投票；达阈值返回 `Status=LocalMatched, MatchSource=Database`；
+6. 未达阈值且 AI 关闭，返回 `Status=Unmatched, MatchSource=None`；
+7. AI 开启时先保存私有输入并创建共享后台任务，立即返回 `Status=AiPending`；
+8. Worker 收敛到 `AiMatched` 或 `Failed`，前端用同一 `RequestNo` 轮询。
+
+不得同步阻塞前端等待大模型，不得把 AI 结果自动写入可信对象主数据，也不得把本地相似度与 AI 置信度混成一个分数。生鲜的冰冻状态、新鲜度、预估价格/单位/币种也必须按字段保存 `Database/AI/Manual` 来源：样本或对象主数据优先，只有数据库未命中后才允许 AI 推断；AI 价格只是非约束估计，不能直接覆盖门店售价。
+
+历史记录纠错使用 `Correct` 动作：只允许绑定当前租户中启用且模式兼容的对象，记录原标签、原来源、修正人、时间和原因；选择 `SaveAsSample` 时通过来源 `RequestNo` 做幂等录入。AI 结果不得自动加入 `Ready` 样本，必须由有权限的用户明确确认。`Recent/Result` 只返回 `HasImage` 与后端生成的短期授权 URL，禁止把 `InputFilePath`、图片 Base64 或永久公开地址交给浏览器。
+
+## V8 原子函数
+
+```js
+var analyzed = await V8.Vision.Analyze({
+  FileByteBase64: V8.FilesByteBase64['frame'],
+  FileName: 'frame.jpg',
+  PipelineKey: 'general-yolox-dinov2-v1',
+  Mode: 'General',
+  FrameId: 'camera-01-000123',
+  StreamSessionId: 'scale-01-session-42',
+  FrameSequence: 123
+});
+
+var ranked = await V8.Vision.Search({
+  QueryEmbeddingBase64: analyzed.Data.Detections[0].EmbeddingBase64,
+  Candidates: candidates,
+  Threshold: 0.82,
+  TopK: 5,
+  EfSearch: 80,
+  IndexKey: 'ready-general-samples'
+});
+
+var voted = await V8.Vision.Stabilize({
+  StreamSessionId: 'scale-01-session-42',
+  FrameId: 'camera-01-000123',
+  Key: ranked.Data.Matches.length ? ranked.Data.Matches[0].Key : '__unmatched__',
+  Confidence: ranked.Data.Matches.length ? ranked.Data.Matches[0].Similarity : 0,
+  WindowSize: 5,
+  MinimumVotes: 3
+});
+```
+
+主流流水线方法：`V8.Vision.Analyze`、`V8.Vision.Search`、`V8.Vision.Stabilize`；兼容原子方法：`V8.Vision.Extract`、`V8.Vision.ExtractBatch`、`V8.Vision.Compare`、`V8.Vision.CompareBatch`、`V8.Vision.GetCapabilities`。业务入口优先使用 `V8.ApiEngine.Run('platform-vision-runtime', ...)`，不要把向量返回给普通浏览器或日志。
+
+## 模型与准确率门禁
+
+- 默认 `builtin-visual-fingerprint-v1` 只是相同/近似样图指纹，不能称为语义分类器或人脸模型。
+- 内核已经实现 YOLOv8/YOLOX/RT-DETR/SCRFD 常见 ONNX 输出适配、DINOv2/DINOv3/SigLIP2 类嵌入、ArcFace 类人脸嵌入、HNSW、IoU 跟踪和连续帧投票；生产结果取决于实际安装的受控模型包与门店数据，不得把“已兼容”写成“模型准确率已通过”。
+- 模型代码许可证、权重许可证、训练数据限制和商用授权必须分别核对；`model.json` 的 `License` 字段不是法律结论。
+- 每个模型包固定版本、输入尺寸、RGB/BGR、Mean/Std、池化、来源、许可证和 SHA-256；不允许浮动 URL 在线下载后直接加载。
+- 模型必须在目标 CPU/GPU、真实镜头、光照、角度和包装变化下建立标注集，测 Top-1/Top-K、误接受率、误拒绝率、P50/P95/P99、内存和人工复核率。
+- 没有真实模型包与标注结果时，只能说“平台接入完成/指纹联调通过”，不能说“商品或人脸识别准确率通过”。
+- ONNX Runtime 是主流部署运行时，但运行时主流不等于所装模型第一梯队；未测真实标注集与目标硬件 P50/P95/P99 前，不得宣称准确率或速度第一梯队。
+
+## 人脸与关注人员强制边界
+
+- 录入、识别、留存和共享生物特征前必须有合法依据、告知/同意、用途限制、访问控制和删除流程。
+- 手工图片 Face 模式必须要求本次明确同意；视频自动图库使用管理员明确授权的租户配置，缺省关闭，不能把前端默认开关当授权。两条入口都须后端校验。
+- 人脸模板和请求按当前租户隔离；向量使用绑定租户和接口引擎的保护能力保存，列表/Hook/普通日志不返回正文。
+- 默认 `RetainFaceInput=0`；AI Worker 无论成功失败都清理临时图片。
+- 数据库未命中时，大模型只能描述中性可见事实，不得猜姓名、罪犯身份、族群、健康、政治等敏感属性。
+- “罪犯/关注人员”命中仅是人工复核线索，不能单独触发抓捕、处罚、解雇、拒绝服务或身份认证。
+- 身份认证仍使用 DiyToken、Passkey/严格人脸一次性票据和原有权限体系；视觉相似度不能替代登录或强身份验证。
+
+## 视频入口
+
+### 默认全画面与服务端识别
+
+视频巡检必须默认全画面，无需画区或填写录像发生日期即可开启；手机摄像头打开后自动识别。
+工位绘制采用矩形拖动或两个对角点，画面内明确提供“应用工位/重画/取消”；规则与人员核验
+收进可选设置。历史录像未填写发生时间时，邀请时段准入保持Unknown，不使用观看时间兜底。
+主屏必须展示工位状态、占用率/绑定员工在岗率、手机、安全帽、离岗次数/总时长/逐次区间，
+异步行为结果标注原媒体时间，未知不能冒充正常。
+
+v1.9.0 起禁止在巡检浏览器持续执行人员模型；手机仅采集、播放、显示节点签名结果，
+不能再用 MediaPipe/EfficientDet 的本地框独立宣布有人。运行产物不包含推理模型/WASM。
+手机默认后置摄像头并支持前后切换，限制720p/15fps；发送帧长边不超过1280像素，
+检测请求串行、完成后间隔至少500ms，失败退避至10秒，画布复用。后台/卸载释放镜头，
+暂停或切源中止检测与复核，忽略迟到结果。断流、过期帧、局部肢体和画面无效不能当无人。
+手机大幅移动时工位统计标记中断/未知。60秒模拟负载测试不能冒充物理手机温控验收。
+固定RF-DETR legacy Large 560、YuNet/SFace和Qwen3-VL本地复核须分别锁定权重来源与许可；
+预训练可直接推理不等于场景准确率达标，行为无正例或人脸无身份真值时不得声明90%。
+通用节点Compose完整定义vision/behavior/media，默认启动vision+media，behavior为可选profile；API/PC继续复用，必须报告实际容器与复用原生服务的区别。
+服务器准备入口为 `Microi.Server/tools/vision-deployment/deploy.py`，官网原位文档
+`/doc/getting-started/docker-run.html#vision-engine-compose`。它生成一个三服务Compose，
+要求Linux root、空目标目录、已发布镜像摘要和当前租户受限节点密钥；现有租户增设节点
+使用 `--signing-key-file` 复用签名，不能覆盖当前租户密钥使原节点失效。模型固定下载地址、
+大小和SHA，保留原配置及媒体，运行模型只读挂载。Ollama必须设置 `OLLAMA_NOPRUNE=true`，
+避免启动清理未注册的已下载权重；导入阶段暂时可写且无论成功失败恢复只读。
+官方Instruct GGUF导入明确指定 `renderer=qwen3-vl-instruct`、视觉projector和stop token，
+使用独立模型别名，记录实际manifest digest；备份整个模型目录（包含manifests-v2）。
+通用安装默认行为关闭；候选评估必须明确Candidate/Unvalidated，不能变正式告警。正式行为启用须有绑定摘要的独立留出集回执，不能把导入成功、JSON有效或少量样图
+当成90%验收。服务器部署包通过官方MCP公有CDN发布并独立校验，应用私有源码与部署包分开。
+官网必须保留完整、可复制的视觉 Compose 与服务器安装步骤；服务标题独立进入当前页大纲。
+用户要求折叠时，代码置于默认关闭的 details/summary，标题、能力边界与配置入口仍可见；不得以折叠为由删减旧资料。群晖无宿主Python时使用
+`microi.doc/docs/public/downloads/vision/prepare-nas.sh` 与 `import-nas.sh`，仅准备容器使用
+CHOWN/FOWNER，不挂Docker socket；复用固定部署包、镜像与模型摘要。既有目录拒绝覆盖，
+模型续传先校验安装标识；导入核对编排归属并恢复模型只读。DS1821+无GPU，48GB内存不能
+作为CPU吞吐或准确率证明；Linux隔离验证、真实NAS、手机温控与独立准确率验收分别记录。
+FP16/量化候选必须与原精度逐图比较人数、框坐标和输出有效性，出现明显漏检不得发布。
+异步行为模型需限制图片、上下文、输出与GPU占用；超时/格式错误保持未知，不能把复核链路可调用当作动作识别达标。
+
+录像自 v1.9.9 起的旧节点本地/中继路径默认连续播放，保留可选“跟随分析播放（逐帧等待）”，旧单帧结果仅在原采样时刻±120ms绘制。v1.9.11可信公开对象时间轴走已登记HTTPS直连：固定每1秒媒体游标连续分析，默认准确率优先等待已接受且已回读的区段，可显式切换流畅预览，未知不计统计。原PTS结果到对应画面才建立真实纹理锚点；播放等待不覆盖手动暂停，seek只切显示窗口、不跳过后台分析秒。历史查看/切源关闭旧会话、取消原作业，晚回执不作用新会话；详见[可信录像时间轴、身份与私有图库](references/video-timeline.md)。
+
+### v1.9.5 人脸定位与有界跟随
+
+- 节点默认 YuNet 定位只产生 `faceBox/faceScore`，不因定位自动提身份模板。`evidenceKind=body/body-face/face` 区分证据：保留原人体 `box`，仅脸时 `box` 也必须是真实脸框，不补全身体。绘制优先合格脸框、否则人体；全帧 `valid=false` 保持未知清框。
+- 摄像头显示层允许低负载灰度纹理跟随，不重新加载手机神经网络。迟到签名锚点必须按请求 FrameId/sequence 绑定原图，从原帧初始化并有界重放；禁止把旧框先套当前图再匹配。当前实现灰度长边256、8Hz、缓冲/锚点最多6秒，正反校验、纹理分数、几何与耗时预算全部通过才绘制；断流、遮挡、离开、低纹理、过期、暂停及换源及时清除。
+- 节点1.9.8的独立快脸定位使用当前DiyToken和专用签名，单并发不排RF队列，最大640像素；只显示真实脸框，不提取模板/归档，不反向写人数、无人、身份或考勤。无脸不等于无人。
+- 跟随只服务显示，不生成新人数/身份/考勤证据。仅脸可证明默认全画面有人，指定工位须人体脚点；脸下缘不能当脚点。历史有效片段占用率100%与当前待判断可以并存，但UI必须显示有效观测/覆盖范围，避免被理解为当前或全片100%。
+- 回归必须覆盖3秒以上迟到锚点重放、真实像素移动/遮挡/离开、相机媒体时钟、暂停换源晚结果、face优先/body回退、320宽和短横屏明暗布局。模拟设备与桌面纹理耗时不能冒充物理手机温控。
+
+### 授权视频图库、示例与候选行为
+
+- `SaveCaptureSettings` 仅当前租户管理员可用；未配置默认关闭。真正空表首次显式保存才CreateIfMissing默认策略，已有禁用/删除/非默认或歧义策略拒绝而不重置。MySQL下先锁固定sys_config行再当前读，配合ProfileKey唯一索引；不能只用进程锁或RepeatableRead旧快照宣称并发安全。
+- `CaptureFaces` 仅接受可信节点私有签名包，绑定tenant/owner/session/sequence/time/frameId/imageSha256，且主观测valid。签名、质量、数量、私有JPEG与128维模板均有界；relay必须剥离所有私有payload。图库采用独立 `opencv-sface-2021dec-gallery-v1`，不混员工准入person Id、identityQuality或subjectId。
+- 对象/样本通过runtime保护模板和私有存储入库；未知建未命名人员，模糊区不乱合并也不反复建对象，后续名称取权威subject.Name。每帧最多新增1张、公平轮转，每人最多3张且间隔至少30秒；256帧有界ledger记录零新增与成功回执，同帧改包拒绝。当前读与真实双并发验收须在实际提供商执行；当前自动归档仅MySQL验证，其它提供商在上传前失败关闭。
+- Capture使用独立事务；v1.9.6起仅可信runtime明确分类为Operational的图库存储故障返回captureError并保留已验签人员观测，Rejected、签名/身份拒绝、未知分类及网络超时仍失败。失败上传只能补偿本次自有私有路径；数据库事务不等于对象存储原子回滚。普通结果仅gallerySubjectId/gallerySubjectName/samplesAdded，不返回图片、模板或私有路径；runtime/monitor/relay关闭请求正文日志。
+- Bootstrap的CanCaptureFaces来自当前租户授权与管理员权限，前端开关仅在true时有效。v1.9.7的ExampleVideos仅向已登录的同租户查看者只读共享当前默认策略ExampleVideosJson中管理员明确配置且Ready的白名单，节点只接受relay权威签发的ReadOnlyExampleAssetIds，观测owner/session仍绑定查看者；非示例媒体、上传/删除及人脸样本和模板不随之开放，用户明确授权的原片可通过独立BackupPublic流程公有发布，不开放图库或匿名识别；桌面显著提供示例入口，手机初始仍camera。官方包DataSelections只保留非空分类种子，不导出profile/AutoCaptureFaces/ExampleVideosJson/CaptureReceiptsJson及任何客户样本或录像。
+- 匿名试用须唯一默认profile显式`EnablePublicTrial=1`（默认0），仅独立Managed `platform-vision-public-trial`的有界公开示例/临时帧；不回退为匿名、不开放私有媒体/身份/图库，票据不替代DiyToken。协议、限额、真实排空及Candidate/Unknown边界见[视频参考](references/video-timeline.md#公开试用与登录时间轴隔离)。
+- FileServerBak `BackupPublic`只复用授权并已校验的对象，分别冻结母片/播放件/原生像素/展示与送检帧的质量；下载、播放和准确率分别验收，不为修页面重复上传或降清晰度。详见[来源与有界计算](references/video-timeline.md#来源与有界计算)。
+- 正式浏览器Origin须精确进入节点CORS并核真实响应；长期组合以单一持久Compose管理，完整保护挂载/资源/其它服务并按实际镜像回滚。宝塔路径和诊断步骤见[正式来源与持久编排](references/video-timeline.md#正式来源与持久编排)。
+- 行为使用POST `/behavior-jobs`、GET/DELETE `/behavior-jobs/{32位小写hex}`，单并发、2秒轮询、有界600秒生命周期；暂停/切源/卸载取消所属旧节点任务。Queued/Running/Completed/Failed/Cancelled/Expired分别呈现。Completed必须核对原session/sequence/time与签名，来源错配拒绝。
+- 安全帽/手机使用/拍摄当前进入candidateEvents，标Candidate/Unvalidated/需复核、原帧时间和模型摘要，formalBehaviorCount保持0；不能靠节点自报validated升级正式违规。完成无候选也不构成90%通过；模型未配不发无效任务。正式门禁、候选演示与专用模型研究分开报告。
+- UI以视频、紧凑工具栏与六指标为核心，历史/候选明细用抽屉或内部滚动，不堆叠长页。明暗/安全区/320宽/手机前后切换继续验收；不为科幻效果牺牲未知提示或添加高耗持续动画。
+
+工作台提供可见的服务设置入口，通过 capabilities 区分节点未连接、模型未配置、复核失败与画面未知；缺少行为模型时不发送无效 review，也不显示一直“复核中”。NAS 平台中继无需浏览器填写 NAS 内网地址；直连的公开地址由管理员在普通系统设置的 sys_config.VisionEdgePublicBase 维护，签名密钥 Vision.Edge.SigningKey 才属于安全与服务接入，不得暴露或被页面覆盖。公开地址仍须经过租户与可信来源校验。专用 CPU 模型诊断、目标 NAS 吞吐和独立场景准确率分别验收。
+
+用户指定DSM反向代理时按实际规则核查HTTPS域名/证书、目标节点环回端口和空闲监听端口；指定1000–1999范围也不能猜端口或覆盖既有规则。配置成功后将公开HTTPS地址经同源MCP保存普通VisionEdgePublicBase并回读，再验收直连与允许来源；秘密仍仅在安全配置。反代、应用发布、节点运行及物理手机分别留证，不以中继可用替代用户指定的直连交付。
+
+`OfficialApplications/Vision` 是应用工程，`src`为Vue微服务、`engines`为V8业务，
+`edge`为额外部署的Python视频节点；`Microi.Vision`仍是独立闭源.NET内核。
+应用源码发布不能冒充.NET内核更新或节点部署；不能因目录都包含Vision而声称后端完全统一。
+
+### 视频巡检模式（v1.5）
+
+`microi-vision/workbench` 保留图片模式，增加录像/手机摄像头/登记监控源巡检。
+责任源码为 `Microi.Server/OfficialApplications/Vision`，规范由
+`OfficialApplications/Resource/vision-release.json` 锁定；旧 AI-Project 镜像不作为新版本发布源。
+
+- 两张新增表 `mci_vision_monitor_session`、`mci_vision_person` 与 Managed
+  `platform-vision-monitor` 通过 MCP Manifest 升级；不新增 .NET 定制迁移或业务 Controller。
+- `Create/Read/Close/Bootstrap/Process/Review` 管理本人会话；
+  `People/SavePerson/ClearFace/EnrollFace/MatchFaces` 管理准入与受保护模板。
+- 受信边缘节点只解码/转码/推理，DiyToken 向当前租户核验身份；媒体票据短期有效。
+  RTSP 只来自节点登记的 MediaMTX 路径，摄像头凭据不进入浏览器、普通 V8 或日志。
+- 检测帧 HMAC 绑定 owner、tenant、session、sequence、媒体时刻和新鲜度；
+  `Process` 以数据库 Revision CAS 保存，重复/乱序不重复积分。
+  签名使用真实原子 `V8.Method.HmacSha256Sign(observation, key)`，返回 Base64。
+  节点密钥在 `V8.SysConfig.ServerPrivateSettings['Vision.Edge.SigningKey']`，通过
+  `microi_manage_server_private_secret` 配置，禁止进入源码。
+- `Review` 只追加原视频时刻的候选行为事件，不重放考勤积分、不替换当前检测框，也不计正式违规。
+  一个节点同时最多一项行为复核；人员检测保持独立，不等待大模型完成。
+- 工位不绑定人员时叫“工位占用率”；绑定后才叫“员工在岗率”。
+  身份不明不能替指定员工算在岗，跳播/断流/无效帧前后间隔为未知。
+  录像覆盖率用全片时长作分母，观测区间取并集；倒退识别必须新开会话，不能重复累计同一段离岗。
+- 历史录像的 `rules.recordedAt` 与媒体时间决定邀请核验时刻；签名新鲜度仍由 wallTimeMs 决定。
+- YuNet/SFace 等实际人脸检测和五点对齐后才生成模板；宽高不足80像素、模糊、
+  多人录入不合格。合格未匹配人脸只能产生未登记复核线索，不直接驱动门禁或处罚。
+- 人员/手机/安全帽/拍摄分别标注评估；无正例、未知和模拟视频不能证明90%识别率。
+  具体边缘协议与验收见责任源码 `edge/README.md` 和
+  [架构与验收](references/architecture-and-acceptance.md)。
+
+已有通用 MCP 的 `microi_get_db_schema`、`microi_plan_system`、
+`microi_generate_system`、`microi_validate_system`、`microi_save_engine_code`、
+`microi_run_engine`、私有源码同步和 V3 发布工具已覆盖这条链路；无需增加绕过权限的摄像头工具。
+`platform-vision-ai-worker` 延迟重试用 `await System.Threading.Tasks.Task.Delay(ms)`，
+不能调用不存在的 `V8.Action.Sleep`。
+
+前端使用 `getUserMedia` 并按 `FrameIntervalMs` 取帧，必须提供开启、暂停、继续、立即识别当前帧和关闭操作；每次打开摄像头生成新的 `StreamSessionId`，每帧递增 `FrameSequence`。自动连续模式允许跳过相同画面，人工主按钮必须显式绕过前端去重以提交当前帧。可信边缘宿主将 RTSP/WebRTC 解码为 `IAsyncEnumerable<MicroiVisionExtractParam>` 后调用 `RecognizeFramesAsync`。Microi.Vision 不直接连接调用方提交的 RTSP URL，不保存摄像头账号，不承担流媒体服务器职责。
+
+打开摄像头、`getUserMedia`、`video.play()`、关闭和组件卸载之间必须使用递增操作令牌或等价取消机制。关闭时先同步写入关闭态并使旧操作失效，再停止轨道和清空 `srcObject`；不能等待媒体清理完成后才改 UI，否则快速关闭会被较早的异步打开流程反向覆盖。移动控件或条件渲染按钮可在 `pointerdown` 立即执行停止语义，并对随后 `click` 做短时去重，防止 DOM 重排吞掉关闭操作。
+
+连续帧必须有：最大图片大小、最小间隔、单客户端串行、取消/停止、RequestId 幂等、网络退避和后台任务去重。不能每个视频帧都无界调用大模型。接口返回 `AiPending` 后，前端必须进入 single-flight 状态：暂停提交新帧，只轮询当前 `RequestId`，直到 `AiMatched/AiFailed/Unmatched`、超时或用户取消后才允许下一帧；禁止并行创建多个 AI 任务。
+
+跨版本接口字段必须在协议边界归一化。连续稳定结果至少兼容 `.NET` 原子常用的 `VoteCount/WindowCount/AverageConfidence` 与历史接口的 `Votes/WindowSize/Confidence`，前端只读取归一化 DTO，任何真实响应都不得展示 `undefined/undefined`。
+
+手机收银/巡检工作台属于高频全屏操作面：在宿主提供的可用高度内同时露出取景区、主要识别按钮、当前状态、核心结果和“最近识别”入口，不依赖页面纵向滚动才能完成一次识别；竖屏按采集/结果/最近记录三段紧凑分配，短横屏改为三列，且不得改变已验收的桌面布局。历史列表可以成为卡片内部的唯一滚动区。相机权限拒绝、数据库匹配中、数据库未命中、AI 等待、终态结果和恢复操作都要在当前视口可见，平台底部菜单和安全区不得遮挡按钮。
+
+桌面工作台使用宿主可用宽度，不再用固定窄版 `max-width`；采集、结果、最近记录同屏三栏。预览使用有界容器和 `object-fit: contain`，上传竖图或打开摄像头不能撑高整个页面。不要同时提供语义重复的底部“再次识别当前画面”和主操作按钮；保留一个清晰的“立即识别”，连续模式另提供暂停/继续。
+
+## 交付顺序
+
+### 视频巡检的手机连接与准确率门禁
+
+手机默认选择摄像头；连接优先采用Bootstrap已验证登记的HTTPS节点，未登记时使用平台HTTPS中继（`edge=platform`），用户显式中继选择跨刷新保留，不能把电脑环回节点当作手机自身访问。复用 `platform-vision-edge-relay` / `platform-vision-edge-media` 与16个固定共享技术槽位，节点仅出站连接；受限访问密钥兑换DiyToken，Windows凭据用CurrentUser DPAPI保护。原始图片/特征仅进入短期加密缓存或节点有界内存，不记录在槽位表、浏览器结果或普通日志；官方包不包含节点凭据、运行槽位数据和客户录像。仍支持已登记HTTPS节点直连。
+
+手机视频使用页面内控制和大画面保留跟随标注；不要调用iOS原生video全屏来承载SVG。画区时收起规则面板、定位取景区，控件至少44px，处理自动播放拒绝、横竖屏、相机关闭竞态。录像从节点原分辨率提帧，私有HLS只承担播放；分片上传每段SHA-256，不将整个长视频Base64放入V8。
+
+90%以上必须由真实独立留出集分能力证明。应用准确率门禁要求各项准确率/精确率/召回率/特异度/覆盖率>90%，未知保留在分母；缺少正例或身份真值时不能声明达标。离岗区间另做时间线对账。完整边界与MCP/浏览器验收见 [architecture-and-acceptance.md](references/architecture-and-acceptance.md)。
+
+1. 更新并测试 Microi.Vision、V8 注入与 API DI；
+2. 用 MCP `microi_plan_system` 做 dry run，再生成并 `microi_validate_system`；
+3. 同步私有微服务源码，构建后按 V3 stage/finalize 发布公开产物并回读；
+4. 只发布默认分类种子；策略由管理员显式保存时安全初始化，禁止导出或覆盖租户授权、示例与回执；
+5. 发布框架 NuGet/Docker，使目标运行时实际包含 `V8.Vision`；
+6. 通过官方应用发布引擎生成商城包，明确 `Managed/CreateIfMissing`，回读包 SHA 和不可变版本；
+7. 在目标租户安装/更新后做真实浏览器、接口、后台任务和模型测试；
+8. 分别报告源码、包、制品、部署、浏览器、模型准确率和物理摄像头边界。
+
+`Microi.Vision` 必须作为独立闭源仓维护：`Microi.Anderson.sln` 使用 `ProjectReference`，公开 `Microi.net.sln` 只能使用同版本 NuGet；一键发布必须像 `Microi.AI`、`Microi.WorkFlow` 一样对 DLL 执行 Obfuscar、回写 nupkg，并以加密前后哈希变化及 `.microi-encrypted` 清单为门禁。模型权重继续独立分发，不进入 NuGet。
+
+## 禁止事项
+
+- 禁止用 HTTP 200、构建成功、Mock UI、同一图片命中代替真实商品/人脸准确率。
+- 禁止把大模型标签伪装成数据库命中或权威身份。
+- 禁止把 AI 新鲜度、冰冻状态或估价伪装成传感器、检疫、食品安全结论或正式售价。
+- 禁止把历史识别的原始私有文件路径或永久公开 URL 返回前端，也禁止未经人工确认把 AI 结果自动沉淀为可信样本。
+- 禁止在接口参数中接受模型目录、任意本地路径、任意网络地址或执行提供程序。
+- 禁止把图片 Base64、原始人脸、向量、提示词、AI Key 写入 Hook 或普通日志。
+- 禁止用进程内队列、`static` 字典或本地文件作为 AI 任务完成事实源。
+- 禁止在应用升级时覆盖 `platform-vision-custom-hook`。
+- 禁止只发布商城包却宣称旧平台运行时已经具备 `V8.Vision`。
+
+## 验收输出
+
+视频工作台保持画面优先：紧凑模式栏和来源/识别操作，六项核心指标可见，说明与明细按需展开。
+覆盖暂停、切源、卸载与自动播放受限的异步播放竞态；正常 AbortError 不冒充故障，真实媒体错误不能静默吞掉。
+Python 节点迁入 .NET 时必须分别列明媒体网关、FFmpeg、模型/GPU、行为模型资源及差分验证；未实际迁移不得声称已无额外运行依赖。
+
+最终报告至少分开列出：源码测试、5 表/字段/索引、7 菜单、5 引擎/4 事件、微服务源码与构建哈希、商城包与版本、框架制品、目标节点版本、真实浏览器、PC/手机横竖屏布局、历史图片与纠错、真实图片素材来源、数据库命中、AI 回退、生鲜属性/价格来源、人脸同意、模型准确率和未执行的物理设备测试。
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
+
+- [references/architecture-and-acceptance.md](references/architecture-and-acceptance.md)：架构与验收
+- [references/video-timeline.md](references/video-timeline.md)：可信录像时间线与快速人脸定位
+- [references/realtime-cpu-profiles.md](references/realtime-cpu-profiles.md)：实时CPU模型、跟随策略与候选训练边界
+<!-- microi-progressive:end -->