@microi.net/cli 5.4.9 → 5.5.0

package/skills/ai-engine/SKILL.md

@@ -49,7 +49,7 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - AI 的 Qdrant/Ollama/Embedding 配置、Schema 初始化和其它生命周期任务由 `AddMicroiAI()` 在模块内自注册；API 的 `Program.cs` 只负责调用模块注册。
 - `Microi.Core` 只承载跨模块契约和模型。新增入口时先扩展 AI 领域服务，再添加薄 Controller/Hub 适配，禁止复制业务流程。
 - AI 账户统一入口是 Managed 接口引擎 `/apiengine/platform-ai-account`；套餐、订阅和订单由 V8 编排。支付宝回调 C# 只做可信租户选择/归一化、该租户配置验签和一次性 Managed 调用；`CompletePayment` 在同一接口引擎事务内完成订单条件认领、金额校验、订阅续期/新建与平台/供应商 API Key 分配。供应商协议、密钥隔离、分布式额度原子、任务句柄和受控媒体落盘仍由绑定原子完成。
-- 非流式 `UpdateConversationTitle / RecognizeIntent / Chat / NL2SQL / NL2V8EngineSync` 统一进入 Managed `/apiengine/platform-ai-runtime`，旧 Controller 同名路由只做兼容转发；SSE/流式、Provider Proxy、媒体、文件和策略元数据保持原生。`platform-ai-runtime` 只调用绑定当前租户和当前用户的 `V8.AI` 原子，不接收客户端伪造的租户、用户、Endpoint、ApiKey、表白名单或管理员标记。
+- 非流式 `UpdateConversationTitle / RecognizeIntent / Chat / NL2SQL / NL2V8EngineSync` 与精确图片 `ProcessImage` 统一进入 Managed `/apiengine/platform-ai-runtime`，旧 Controller 同名路由只做兼容转发；SSE/流式、Provider Proxy、生成式媒体、文件和策略元数据保持原生。`platform-ai-runtime` 只调用绑定当前租户和当前用户的 `V8.AI` / `V8.Image` 原子，不接收客户端伪造的租户、用户、Endpoint、ApiKey、表白名单或管理员标记。
 - AI 官方应用只有一个应用级租户扩展点 `platform-ai-custom-hook`，策略为 `CreateIfMissing`。`mci_ai_data_assistant` 与 `platform-ai-runtime` 只传 `Stage`、`SourceApiEngineKey`、`Action`；支付动作最多增加 `EventId`、`Provider`，账户其它动作只增加白名单资源元数据。Hook 禁止接收订单号、交易号、金额、标题、SQL、模型、附件、提示词或问题原文及其摘要、回答、供应商/平台密钥、供应商任务号、文件句柄或媒体内容。匿名发现接口不调用 Hook，`/v1/usage` 继续由 C# 凭据网关直接校验，使 `Authorization` 永不进入 V8。
 - 9 张 `mic_sub_*` 订阅表与 `mci_ai_token_account`、`mci_ai_token_log` 由官方 `app.microi.ai-engine` 应用升级提供，必须同时声明 DDL、PhysicalColumns、DiyTables、DiyFields；`PromptPreview` 属于日志表正式字段。`mci_ai_token_recharge` 当前不在该运行时实体闭包内，禁止根据线上残留自行扩包。运行时发现缺失时失败关闭，禁止在请求路径自动建表、加列或修改业务 Schema。
 - `Sys_User.AiApiKey` 归官方 `app.microi.sys_user`，由系统账号包同时维护建表 DDL、PhysicalColumns 和隐藏只读 DiyField；AI助手包不得重复声明 `Sys_User`。缺列错误必须提示升级系统账号应用，不能误导用户升级 AI助手。
@@ -58,10 +58,11 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 
 - 模型 Provider、Endpoint、ApiKey、AuthPrefix 和上游模型 Id 只保存在服务端受保护配置。
 - 普通用户使用平台签发的受限 API Key/订阅身份，不能枚举或读取上游密钥。
-- MiniMax 对话媒体必须区分意图模型与生成模型：`MiniMax-M3` 只负责识别普通对话、绘图或音乐意图；图片固定走 `GenerateMiniMaxImage + image-01`，纯音乐固定走 `GenerateMiniMaxMusic + music-2.6`。不得让文本模型用说明文字冒充媒体生成，也不得声称图片/音乐是 `MiniMax-M3` 原生输出。
-- 图片请求限制为 1～4 张和受控比例，音乐当前仅向平台管理员开放且固定无人声、44.1kHz、256kbps、MP3。两者都使用稳定 `RequestId` 和共享幂等；相同参数回放、参数冲突拒绝，上游结果不确定时禁止换 Id 盲重试。成功内容由服务端校验后直接写入当前租户公有 HDFS。
+- MiniMax 对话媒体必须区分意图模型与生成模型：`MiniMax-M3` 只负责识别普通对话、绘图或音乐意图；生成式图片固定走 `GenerateMiniMaxImage + image-01`，纯音乐新路由优先走 `GenerateMiniMaxMusic + music-3.0`，并继续兼容已有供应商配置的 `GenerateMiniMaxMusic + music-2.6`。托管音乐只有明确返回 410 退役终态时才允许切到官方开源 `MiniMax-Music3`，不得把超时、5xx、额度不足等不确定状态当作回退条件；目标账号支持的实际模型必须在线校准。不得让文本模型用说明文字冒充媒体生成，也不得声称图片/音乐是 `MiniMax-M3` 原生输出。
+- `GenerateMiniMaxImage` 可接收最多 4 张 JPEG/PNG/WebP 主体参考图；参考图先写当前租户私有 HDFS，只将短时签名 URL 交给供应商，浏览器与响应均不得得到签名地址。图生图、重绘、扩图、消除、去水印、证件照、多图合成、上色、修复等当前属于参考图提示词重绘，不得冒充像素级蒙版工具。黑白、纯色背景抠除、缩放、裁剪、旋转、翻转、格式转换和拼图使用 `platform-ai-runtime/ProcessImage + V8.Image` 精确处理。
+- 图片与音乐都使用稳定 `RequestId` 和共享幂等；相同参数回放、参数冲突拒绝，上游结果不确定时禁止换 Id 盲重试。音乐当前仅向平台管理员开放且固定无人声；托管结果为 MP3，开源回退为 32kHz 立体声 WAV、10～60 秒。成功内容由服务端校验后直接写入当前租户公有 HDFS。
 - 聊天附件的公有媒体 URL 优先按当前运行租户 `FileServer + FilePath` 解析，禁止写死域名或沿用其它租户的前缀。图片使用 Element Plus `el-image` 的 `preview-src-list` 原页放大，不能套 `target="_blank"`；音乐使用 `<audio controls preload="metadata">` 在线播放。媒体是结构化附件，文本才走安全 Markdown 渲染，禁止拼接任意 HTML 绕过 URL/类型校验。
-- Provider/中转账号未开通音乐产品、额度不足或上游停用时必须返回可诊断失败，不生成占位音频、不伪报成功。图片、音乐和视频的真实可用性都需用目标租户登录态调用及媒体 GET/播放回读证明，源码存在或接口 HTTP 200 不能替代生成成功。
+- MiniMax 自 2026-08-20 起不再向新用户开放付费 Music/Lyrics API，并停止旧免费 Music 模型。既有 `music-3.0` 账号仍可优先直连；官方开源 `MiniMax-Music3` Space 可作为明确 410 后的回退，但公开 ZeroGPU 配额不是生产 SLA。需要专属额度时只在既有服务端 `mic_ai` 模型路由中保存官方 Space Endpoint 与受保护 Hugging Face Token，不新增 API `AppSettings`、环境变量或前端密钥。Provider/中转账号未开通、额度不足或上游停用时必须返回可诊断失败，不生成占位音频、不伪报成功。图片、音乐和视频的真实可用性都需用目标租户登录态调用及媒体 GET/播放回读证明，源码存在或接口 HTTP 200 不能替代生成成功。
 - MiniMax 视频生成属于可复用供应商原子能力，应实现在 `Microi.AI`，Controller 只读取可信用户/`OsClient`、绑定参数并传递取消信号。理由是上游密钥隔离、异步 `task_id → file_id → download_url` 协议、订阅额度和跨节点幂等都不是某个可编辑接口引擎应复制的业务逻辑；具体文章、提示词和分发编排仍可留在 Job/接口引擎/发布 Skill。
 - MiniMax Token Plan Key 与按量 API Key 是相互独立的凭据，必须复用现有服务器端 Provider/ApiKey 受保护配置，不新增 API `AppSettings`、`MICROI_*` 环境变量或浏览器可见 Key。视频创建、查询和下载仅允许官方 HTTPS Host `api.minimaxi.com`。
 - 视频创建必须要求调用方稳定 `RequestId`，先在当前租户共享 Redis 以 `OsClient + 用户 + RequestId` 原子 `NX` 占位；Redis 不可用时失败关闭。相同 RequestId/参数回放返回原任务，不同参数冲突拒绝；上游 POST 超时或结果不确定时禁止自动换 RequestId 重试。查询不再次扣生成额度。

package/skills/microi-docs-coverage/references/capability-map.md

@@ -34,6 +34,8 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `more/sso.md` | microi-sso, v8-security, app-store | 双向 OIDC/SAML2/CAS、账号映射、协议端点、安全基线、商城发布与验收 |
 | `more/sys-config.md` | v8-utilities, microi-deployment | 系统/租户配置和敏感边界 |
 | `system-engine/ai-engine.md` | ai-engine, v8-http-integration, microi-ai-application | 模型代理、License、V8.AI、MCP 对话、跨端调用和安全 |
+| `system-engine/ai-data-analysis.md` | ai-engine, v8-security, v8-saas-multi-tenant | 权限感知 Schema、NL2SQL、实时经营分析、追问与数据边界 |
+| `system-engine/ai-creative-studio.md` | ai-engine, v8-image-processing, v8-file-upload | 图片、视频、音乐、29 项图像工具、HDFS 结果与创作安全边界 |
 | `system-engine/ai-platform-governance.md` | ai-platform-governance, app-store, business-blueprint, page-engine | 门户、身份、配置、发布、服务韧性、Trace/日志、资产协作与可恢复导入 |
 | `system-engine/ai-workflow-suite.md` | business-blueprint, v8-workflow, microi-system-delivery | AI 工作流、蓝图、状态机、自动化流和流程挖掘 |
 | `system-engine/system-observability.md` | system-observability, performance-testing, v8-debugging, microi-microservice | 系统日志、Trace、热点接口、资源监控、网络流量归因、安全治理、AI/MCP 与商城交付 |
@@ -57,6 +59,8 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/saas-engine.md` | v8-saas-multi-tenant | 租户识别和 SaaS 配置 |
 | `system-engine/search-engine.md` | search-engine | Elasticsearch 索引和查询 |
 | `system-engine/spider-engine.md` | spider-engine | 浏览器采集和 Worker |
+| `system-engine/ocr-engine.md` | ocr-engine, v8-file-upload, v8-saas-multi-tenant, v8-security | 图片/PDF 文字识别、独立模型服务、租户配置、V8/HTTP/MCP 调用、安全边界与生产验收 |
+| `system-engine/vision-engine.md` | vision-engine, ai-engine, microi-microservice, app-store, v8-security | ONNX 视觉特征、租户样本匹配、异步 AI 回退、摄像头帧、人脸治理、微服务与商城交付 |
 | `system-engine/translate-engine.md` | translate-engine | 多语言与翻译供应商 |
 | `system-engine/unity-integration.md` | unity-integration, v8-api-config, microi-client-frontend | Unity UPM、WebGL/Windows、多人租约、公屏、DiyToken 与 V8 通讯边界 |
 | `system-engine/visualization-engine.md` | page-engine, microi-ui | 3D、CAD、goView 与数据大屏能力边界 |

package/skills/microi-microservice/SKILL.md

@@ -195,6 +195,22 @@ AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data
 放在右侧内容容器内，使微服务导航栏和顶部栏保持挂载；浏览器 `popstate/hashchange` 要能恢复
 内部路由。只有确实要离开当前微服务、打开另一个吾码后台菜单或替换顶部 Tab 时才调用宿主路由动作。
 
+### 页面打开与路由切换骨架屏（强制）
+
+所有新建或修改的 MicroService，在首次打开、内部路由切换、菜单页签冷启动以及影响主要内容几何的
+异步数据读取期间，都必须先同步呈现骨架屏；禁止只显示转圈图标、纯文字“加载中”、整页
+`v-loading` 遮罩、空白画布或等待接口结束后才补 Loading。顶部栏、子应用导航和不依赖新数据的
+操作保持挂载，骨架只接管正在变化的内容容器。
+
+- 路由组件使用 `defineAsyncComponent + Suspense fallback`；已缓存组件再次切换也要有短暂且可观测的路由骨架，组件挂载后的接口加载继续使用页面内骨架，避免两者之间闪白。
+- 骨架必须复刻最终页面的主要几何：列表保留工具栏、行和分页轮廓，表单保留分组与字段轮廓，设计器保留节点库/画布/属性栏，3D、图表和大屏保留画布边界、图例及主体轮廓。不能用一组与最终布局无关的灰条冒充。
+- 加载容器必须设置 `aria-busy="true"` 并提供可读状态文本；`prefers-reduced-motion: reduce` 时停用 shimmer。成功、空数据、失败和无权限是四种独立终态，失败不得永久停留在骨架。
+- 骨架必须在 import/fetch 之前进入 DOM，切换期间不销毁宿主导航；真实浏览器验收要用网络节流或可控延迟分别截取首次打开和至少一次内部路由切换的骨架，再确认最终页面、前进/后退与错误重试均正常。
+
+复盘：AI 工作流业务蓝图曾在路由切换后先显示空白/转圈，根因是只给异步组件配置了加载逻辑，
+没有把路由加载、页面数据加载和最终几何统一成状态协议。通用规则是“路由 fallback + 页面内骨架 +
+明确终态”三层同时存在，并以真实浏览器慢网截图作为交付门禁。
+
 ### 菜单页签缓存与子应用生命周期（强制）
 
 - 菜单微服务只有一个缓存所有者：Vue 路由宿主固定 `meta.keepAlive=false`，`<micro-app keep-alive>` 独占子应用状态。禁止把外层 Vue `KeepAlive` 打开，也禁止子应用通过随机实例名规避运行时缓存；双层缓存会产生旧宿主与当前路由竞争、无数据、永久骨架屏和白屏。
@@ -221,6 +237,20 @@ window.addEventListener('appstate-change', (event) => {
 `isolation:isolate` 作为第二道边界，但不能代替子应用命名空间。验收需检查宿主 Logo/菜单样式、
 内部导航不重挂微服务、内容区局部骨架屏，以及前进/后退恢复。
 
+### 平台主题、明暗模式与租户主色（强制）
+
+所有新建或修改的 MicroService 都必须跟随宿主平台主题，不能交付只适配固定白底、固定深色或
+单一品牌色的页面。宿主下发的 `themeMode`、`themeColor`、`themePalette`、`themeOnPrimary`、
+`themePrimaryText`、`themeColorStrong` 与 `themeTokens` 是嵌入运行时的主题事实源；首次挂载、
+`addDataListener` 收到 `host:theme`，以及 `appstate-change=aftershow` 时都要重新应用。嵌入态以
+宿主值优先，独立预览才允许使用已保存偏好或 `prefers-color-scheme` 作为回退。
+
+- 唯一根容器必须同时写入 `data-mci-ui-root="{AppKey}"`、`data-theme`、`data-mci-palette`，并把宿主字段映射为本应用的语义 Token；禁止把宿主页面的 `html/body` 当作子应用样式开关。
+- 主操作色优先使用 `--mci-color-primary` / `--el-color-primary` 或宿主 `themeColor`；表面、文字、边框分别使用 `themeTokens.surface/surfaceSoft/textPrimary/textSecondary/border`。成功、警告、错误色可以保持语义独立，但必须分别提供浅色与深色可读状态。
+- 表格、表单、弹窗、上传、骨架屏、空状态、错误态、禁用态、悬停和焦点环都必须覆盖浅色与深色；大面积背景不能直接写死 `#fff` 或某个深色，主题色不能只改按钮而其它视觉仍留在旧配色。
+- 主题切换必须即时生效且不重挂应用、不丢失表单/筛选/内部路由；卸载时清理本应用创建的媒体查询、数据与生命周期监听器。
+- 自动化验收至少覆盖“浅色 + 深色 + 一个非默认租户主题色”，同时断言根属性、计算后的主色/表面/文字、基本对比度和宿主 Logo/菜单未被污染，并各保留一张真实宿主截图。只测独立 Vite 预览、只检查 CSS 文本或只显示切换按钮均不算完成。
+
 `closeTab` 与 TagsView 当前页签关闭语义一致，固定页签和最后一个页签拒绝关闭；顶部 Tab
 右键刷新与 `reloadTab` 都应重载当前微服务。`OpenAppDialog` 页面不使用 Tab 动作，继续发送
 `app-dialog:success/cancel/error` 关闭弹窗并回传结果。

package/skills/vision-engine/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: vision-engine
+description: 设计、实现、配置、扩展和验收视觉引擎能力。处理 Microi.Vision、V8.Vision、ONNX Runtime、图片或视频帧、商品或物体样本库优先匹配、平台 AI 异步回退、人脸特征与关注人员合规、platform-vision-runtime、microi-vision 前端微服务和应用商城交付时使用。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# 视觉引擎
+
+## 先读取相关规范
+
+- 涉及完整表、字段、菜单和权限交付时，读取 `../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/Bootstrap/Capabilities |
+| `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 置信度混成一个分数。
+
+## 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`；兼容原子方法：`Extract`、`ExtractBatch`、`Compare`、`CompareBatch`、`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/严格人脸一次性票据和原有权限体系；视觉相似度不能替代登录或强身份验证。
+
+## 视频入口
+
+前端使用 `getUserMedia` 并按 `FrameIntervalMs` 取帧，必须提供开启、暂停、继续、再次识别和关闭操作；每次打开摄像头生成新的 `StreamSessionId`，每帧递增 `FrameSequence`。可信边缘宿主将 RTSP/WebRTC 解码为 `IAsyncEnumerable<MicroiVisionExtractParam>` 后调用 `RecognizeFramesAsync`。Microi.Vision 不直接连接调用方提交的 RTSP URL，不保存摄像头账号，不承担流媒体服务器职责。
+
+连续帧必须有：最大图片大小、最小间隔、单客户端串行、取消/停止、RequestId 幂等、网络退避和后台任务去重。不能每个视频帧都无界调用大模型。
+
+## 交付顺序
+
+1. 更新并测试 Microi.Vision、V8 注入与 API DI；
+2. 用 MCP `microi_plan_system` 做 dry run，再生成并 `microi_validate_system`；
+3. 同步私有微服务源码，构建后按 V3 stage/finalize 发布公开产物并回读；
+4. 写入默认分类/策略，按业务 Key 先查后写；
+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、同一图片命中代替真实商品/人脸准确率。
+- 禁止把大模型标签伪装成数据库命中或权威身份。
+- 禁止在接口参数中接受模型目录、任意本地路径、任意网络地址或执行提供程序。
+- 禁止把图片 Base64、原始人脸、向量、提示词、AI Key 写入 Hook 或普通日志。
+- 禁止用进程内队列、`static` 字典或本地文件作为 AI 任务完成事实源。
+- 禁止在应用升级时覆盖 `platform-vision-custom-hook`。
+- 禁止只发布商城包却宣称旧平台运行时已经具备 `V8.Vision`。
+
+## 验收输出
+
+最终报告至少分开列出：源码测试、5 表/字段/索引、7 菜单、5 引擎/4 事件、微服务源码与构建哈希、商城包与版本、框架制品、目标节点版本、真实浏览器、真实图片素材来源、数据库命中、AI 回退、人脸同意、模型准确率和未执行的物理设备测试。

package/skills/vision-engine/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "视觉引擎"
+  short_description: "构建与验收数据库优先、AI回退的通用视觉识别"
+  default_prompt: "Use $vision-engine to build and validate tenant-isolated Microi.Vision workflows."

package/skills/vision-engine/references/architecture-and-acceptance.md

@@ -0,0 +1,172 @@
+# Microi.Vision 架构与验收参考
+
+## 表模型
+
+| 表 | 主业务键 | 关键字段 |
+|---|---|---|
+| `mci_vision_category` | `CategoryNo` | Name、Scope、ParentId、Sort、Enabled |
+| `mci_vision_subject` | `ObjectNo` | Name、CategoryId、ObjectType、RecognitionMode、ThresholdOverride、ReviewRequired |
+| `mci_vision_sample` | `SampleNo` | SubjectId、Mode、ImagePath、EmbeddingBase64、ModelKey、QualityScore、Status |
+| `mci_vision_request` | `RequestNo` | Mode、Status、MatchSource、StreamSessionId、FrameSequence、DetectionsJson、StabilityJson、AI 字段、耗时 |
+| `mci_vision_profile` | `ProfileKey` | 两类 ModelKey/Threshold、TopK、CandidateLimit、HnswEfSearch、连续投票、AI 开关、取帧间隔、保留策略 |
+
+数据库隔离租户的业务表物理层可能没有 `OsClient` 列；建索引前必须以 `microi_get_db_schema` 和物理索引回读为准。若当前部署是共享表租户模型，才把真实租户字段放到唯一索引前缀，不能机械套用。
+
+## 推荐索引
+
+独立租户库基线：
+
+- category: unique `(CategoryNo)`；普通 `(ParentId, Sort)`；
+- subject: unique `(ObjectNo)`；普通 `(CategoryId, RecognitionMode, Enabled)`；
+- sample: unique `(SampleNo)`；普通 `(ModelKey, Mode, Status)`、`(SubjectId)`；
+- request: unique `(RequestNo)`；普通 `(Status, CreateTime)`、`(SubjectId, CreateTime)`；
+- profile: unique `(ProfileKey)`；普通 `(IsDefault, Enabled)`。
+
+## 状态与来源
+
+| Status | MatchSource | Terminal | 说明 |
+|---|---|---:|---|
+| `Received` | `None` | 否 | 连续帧已处理，投票尚未稳定 |
+| `LocalMatched` | `Database` | 是 | 当前模型版本样本达到阈值 |
+| `AiPending` | `None` | 否 | 后台任务已接受 |
+| `Unmatched` | `None` | 是 | 未命中且 AI 关闭 |
+| `AiMatched` | `AI` | 是 | AI 标签已回写 |
+| `Failed` | `None` | 是 | 本地流水线或 Worker 最终失败 |
+| `ManualReview` | `None` | 是 | 高风险场景需要人工复核 |
+| `LowQuality` | `None` | 是 | 低于质量阈值 |
+
+`Status` 与 `MatchSource` 必须一起返回。AI 成功不应填充 `SubjectId`，除非后续人工确认并通过正常业务接口绑定。
+
+## Runtime 请求
+
+### Recognize
+
+```json
+{
+  "Action": "Recognize",
+  "RequestId": "稳定幂等键",
+  "Mode": "General",
+  "ProfileKey": "default",
+  "FrameId": "camera-01-000123",
+  "StreamSessionId": "scale-01-session-42",
+  "FrameSequence": 123,
+  "Continuous": true,
+  "ResetStream": false,
+  "FileName": "frame.jpg",
+  "FileByteBase64": "...",
+  "ConsentConfirmed": false
+}
+```
+
+Face 模式必须 `ConsentConfirmed=true`；服务端不能只信任前端 checkbox。
+
+### Result
+
+```json
+{ "Action": "Result", "RequestNo": "稳定幂等键" }
+```
+
+轮询应在终态停止，并使用指数或有界间隔；页面卸载、取消或新帧覆盖旧帧时应中止旧轮询。
+
+### Enroll
+
+```json
+{
+  "Action": "Enroll",
+  "SubjectId": "当前租户对象Id",
+  "FileName": "sample.jpg",
+  "FileByteBase64": "...",
+  "ConsentConfirmed": true
+}
+```
+
+服务端读取对象的 Category/Mode，不能信任调用方自行提交 SubjectName、CategoryName 或 ModelKey。
+
+## 公开结果最小字段
+
+允许返回：RequestNo、FrameId、StreamSessionId、FrameSequence、Mode、Status、MatchSource、SubjectId/Name、CategoryId/Name、LocalSimilarity、Confidence、对象框/TrackId、Stability、AiLabel/Category/Description/Candidates、ModelKey/Version、ImageWidth/Height、QualityScore、RequestedAt、CompletedAt、ElapsedMs、ErrorMessage。
+
+禁止返回：EmbeddingBase64、InputFilePath、图片 Base64、模型磁盘路径、AI Provider Key、系统提示词、后台任务内部载荷。
+
+## 模型包 model.json
+
+```json
+{
+  "SchemaVersion": 1,
+  "ModelKey": "general-dinov2-v1",
+  "ModelVersion": "1.0.0",
+  "TaskType": "Embedding",
+  "FileName": "model.onnx",
+  "Sha256": "64位十六进制",
+  "InputName": "input",
+  "OutputName": "embedding",
+  "InputWidth": 224,
+  "InputHeight": 224,
+  "ResizeMode": "CenterCrop",
+  "ChannelOrder": "RGB",
+  "Mean": [0.485, 0.456, 0.406],
+  "Std": [0.229, 0.224, 0.225],
+  "OutputPooling": "ClsToken",
+  "Provider": "ONNX Runtime",
+  "License": "按实际模型/权重填写",
+  "SourceUrl": "权威来源"
+}
+```
+
+流水线模型包可声明 `TaskType=Detection/Segmentation/FaceDetection/Pipeline` 并引用受控 detector/embedding；目前支持 YOLOv8、YOLOX、RT-DETR、SCRFD 常见张量布局，Face 模型使用 `TaskType=FaceEmbedding`。人脸必须经过检测和五点对齐，不能用简单 resize 伪装完成对齐。
+
+## 测试矩阵
+
+### .NET 单元/契约
+
+- 合法 JPEG/PNG/WebP 提取与维数归一化；
+- 非法 Base64、伪造格式、超大图片、像素炸弹拒绝；
+- 路径穿越、错误 SHA、超大模型、不支持任务类型拒绝；
+- 相同向量、相反向量、维数不一致、TopK、候选上限；
+- YOLO/YOLOX/RT-DETR/SCRFD 解码、NMS、对象裁剪、人脸五点对齐；
+- HNSW 精确回退、缓存指纹、IoU TrackId、连续帧窗口与最少票数；
+- CPU 及目标部署环境实际可用的 CUDA/TensorRT/OpenVINO 提供程序；
+- Face/General 与 TaskType 不匹配拒绝；
+- V8 租户上下文覆盖调用参数；
+- 能力返回不泄漏模型磁盘路径。
+
+### 接口引擎
+
+- 同 RequestId 幂等；
+- 数据库优先且 AI 不入队；
+- 未命中 + AI 开启立即返回 AiPending；
+- Worker 成功/失败/重复消费收敛；
+- AI 关闭直接 Unmatched；
+- 低质量不进入匹配；
+- 受保护向量只能在同租户同核心引擎解开；
+- Hook 不接收敏感载荷且 CreateIfMissing 不被升级覆盖。
+
+### 浏览器
+
+- 已登录真实菜单打开 MicroService，不是独立 Mock 页面；
+- 桌面、窄屏、暗色、键盘焦点和文字对比度；
+- 上传预览、清除、重复选择、错误格式/超限；
+- 摄像头授权拒绝、成功、暂停、继续、再次识别、关闭与卸载清理；
+- Database/AiPending/AI/Unmatched/LowQuality/AiFailed 状态；
+- FaceConsent 默认未勾选，未同意按钮禁用且后端拒绝；
+- Console/PageError/失败请求为 0 或逐项解释。
+
+### 准确率
+
+至少分离 train/reference 与 test，测试集不能复用完全相同文件充当准确率。商品需覆盖角度、包装、遮挡、数量、背景、秤盘和光照；鱼类需覆盖鲤鱼/鲫鱼等相近类；人脸需覆盖姿态、光照、遮挡并按同意范围采样。
+
+报告：样本数、类别数、Top-1、Top-K、混淆矩阵、阈值、FAR、FRR、P50/P95/P99、硬件、模型/权重版本与失败样本。完全相同图片命中只能算协议/回归测试，不计为泛化准确率。
+
+## 发布证据
+
+分别保存：
+
+- 源码路径与测试命令；
+- NuGet 包清单和公共源回读；
+- Docker tag/digest 与匿名回读；
+- MCP 表/字段/索引/菜单/引擎/事件回读；
+- MicroService SourceManifestHash、RuntimeManifestHash、RouteSnapshotHash 与 committed version；
+- 应用商城 PackageSha256、PackageSize、StoreVersionId、ResourceSnapshotHash；
+- 目标平台版本、实例重启、真实登录浏览器截图；
+- 素材 URL、许可证、作者/署名要求、本地 SHA-256；
+- 未完成的模型包、物理摄像头、GPU 或生产部署边界。