@microi.net/cli 5.4.8 → 5.5.0

package/skills/README.md

@@ -8,7 +8,7 @@
 
 ## 包含的 Skills
 
-当前仓库包含 65 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
+当前仓库包含 66 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
 
 ### V8 引擎核心（后端）
 
@@ -32,6 +32,7 @@
 | **v8-security** | 安全最佳实践（权限/输入验证/防注入） | `v8-security/SKILL.md` |
 | **v8-utilities** | 前后端 V8 上下文、通用函数、扫码、消息、Base64、加密和专项 API 索引 | `v8-utilities/SKILL.md` |
 | **ocr-engine** | 通用 OCR 网关、SaaS 配置、PaddleX 服务与多节点验收 | `ocr-engine/SKILL.md` |
+| **vision-engine** | 通用物体/商品/人员视觉识别、租户样本匹配、异步 AI 回退与生物特征治理 | `vision-engine/SKILL.md` |
 | **spider-engine** | 爬虫/浏览器采集 Worker、会话、目标地址、配额与交付边界 | `spider-engine/SKILL.md` |
 
 ### V8 引擎核心（前端）

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 重试。查询不再次扣生成额度。
@@ -87,9 +88,18 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - 角色策略存在但 `AllowedModels` 为空时，客户端最终仍会得到无可用模型；不得把它误判为前端角色拦截。应补齐当前租户启用模型白名单并回读，而不是删除 `mci_ai_role_policy` 校验或在客户端强制把 `Enabled` 改成 `true`。
 - 商城包不能携带发布租户的角色 Id、模型 Id 或密钥；应携带业务域定义和接口引擎，由安装后的目标租户动态发现自己的启用模型。发布后回读 `sys_microistore.AppVersion/AppPakcet`，并真实执行 `Bootstrap` 验证超级管理员可用、模型非空、快捷问题存在。
 
-## Schema 检索双模式
-
-### 默认关键词模式
+## Schema 检索双模式
+
+### 启动、租户与存储边界
+
+- SaaS 引擎启动时挂载 `sys_osclients` 中符合节点条件的租户运行配置到 `OsClientExtend.ClientList`；这是配置、数据库访问对象和基础设施运行态，不是 AI Schema 预热。不得根据 `ClientList` 数量声称主租户和全部子租户的表字段均已加载。
+- `AiSchemaInitializationHostedService` 只对 `GetConfigOsClient()` 返回的配置主租户执行启动预热，空值时回退默认租户；`InitializeSchemaCache` 还受在线 AI License 门禁。子租户必须在其首次 NL2SQL/NL2V8 Schema 请求中按可信 `OsClient` 惰性加载，禁止启动时无界遍历所有租户、所有表和字段。
+- 在线 AI Schema 的事实源是当前租户未删除的 `diy_table`、`diy_field` 及绑定表的 `sys_menu`，不是 `INFORMATION_SCHEMA`，也不是开发者本地 `.microi-db-schema.md`。只存在于物理数据库、未登记低代码元数据的表字段不能宣称已被在线 AI 发现。
+- 关键词索引的 Redis L2 Key 为 `Microi:{OsClient}:AiSchemaKeywordIndex:{FormEngineAuthzVersion}`，保存原始 `List<TableSchemaInfo>`，TTL 为 10 分钟；进程内 L1 保存预构建倒排索引，TTL 为 2 分钟。版本来自 `Microi:{OsClient}:FormEngineAuthz:Version`；无法读取 Redis 版本时必须回源租户数据库，不得沿用版本未知的旧索引。
+- 标准 FormEngine 元数据/权限变更必须推进版本或显式刷新。绕过 FormEngine 直接执行 SQL 可能不会立即失效，应明确提示缓存到期、重启或手动刷新边界。
+- Qdrant 只在 `EnableVectorDatabase=1` 时保存租户隔离的 Schema 向量和元数据 Payload，不能保存业务行数据、充当事实源或绕过表权限。NL2SQL 的业务结果始终在完成授权和只读 SQL 校验后实时查询当前租户数据库。
+
+### 默认关键词模式
 
 `mic_ai.EnableVectorDatabase` 缺失、`null`、空值或 `0` 均表示关闭；只有显式启用才进入向量模式。旧数据库没有该字段时必须保持可用，不能因为读取不到开关而尝试连接历史向量配置。
 
@@ -173,7 +183,9 @@ MCP 提供实时事实和受控执行；关键词索引提供低依赖、确定
 - [ ] 官方中转模型清单可在无 Token 下返回非空公开白名单，且不含 ApiKey、Endpoint；Bootstrap 失败不会被静默降级为空列表
 - [ ] 直接动态路由与 `/api/ApiEngine/Run` 兼容入口的 JSON Body 均能到达 `V8.Param`，HTTP 伪造可信字段仍被清除
 - [ ] Schema/向量/对话/配额按 `OsClient` 隔离
-- [ ] `EnableVectorDatabase` 缺失、空值或 `0` 时不创建、连接、初始化、同步或搜索 Embedding/Ollama/Qdrant
+- [ ] 启动期只预热配置主租户 Schema；子租户首次 AI Schema 请求可正确惰性加载，且未把 `ClientList` 挂载误报为全租户结构预热
+- [ ] Redis/Qdrant 中只有 Schema 索引和元数据，没有复制业务行数据；分析 SQL 始终查询当前租户数据库
+- [ ] `EnableVectorDatabase` 缺失、空值或 `0` 时不创建、连接、初始化、同步或搜索 Embedding/Ollama/Qdrant
 - [ ] 默认链路使用结构化大模型扩词；扩词失败时中文 2/3 字确定性回退仍能召回常见业务实体
 - [ ] 文档明确区分普通 Chat、NL2SQL Schema 双模式检索和 NL2V8 Skill + Schema 双模式检索
 - [ ] NL2SQL 服务端可信标记不可由两套 JSON 序列化输入伪造，空白名单失败关闭

package/skills/app-store/SKILL.md

@@ -147,9 +147,11 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 - [ ] 同一包重复安装无重复表/字段/菜单/任务
 - [ ] 客户自定义 V8 与非包拥有配置保持不变
 - [ ] 源码包、构建包、Manifest 和数据库版本一致且哈希可核
-- [ ] 无版本号根入口与当前商城版本一致，历史版本 URL 仍可独立访问
-- [ ] 安装到不同 ApiBase/OsClient 后，入口 HTML 使用目标租户上下文且分享 URL 无运行参数
-- [ ] 中断/重启后可恢复，两个节点不会重复副作用
+- [ ] 无版本号根入口与当前商城版本一致，历史版本 URL 仍可独立访问
+- [ ] 安装到不同 ApiBase/OsClient 后，入口 HTML 使用目标租户上下文且分享 URL 无运行参数
+- [ ] Web/UniApp 安装后的 `PreviewUrl` 使用目标租户 `FileServer + 真实对象 Key`，不含 OSS/S3 内网域名或临时签名；即使发布包漏选菜单，也会幂等生成可直接在线使用的 Iframe 入口，已有入口则重绑到目标租户地址
+- [ ] 只更新菜单/说明/声明式资源且复用旧运行时的版本，`sys_microistore.AppVersion` 跟随安装包版本，运行版本表保留真实构建版本；商城安装状态不能因两种版本合同合法分离而显示异常
+- [ ] 中断/重启后可恢复，两个节点不会重复副作用
 - [ ] 普通角色不能安装、升级、卸载或读取私有源码
 - [ ] 缓存刷新后远端 API 与真实 UI 通过
 - [ ] 卸载范围明确、可审计、可恢复或已提示不可恢复

package/skills/microi-db-schema/references/schema-overview.md

@@ -1,7 +1,7 @@
 # Microi DB Schema Overview
 
 - Source: generic reference snapshot; current tenant truth must come from `microi_get_db_schema`.
-- Tables: 75
+- Tables: 74
 - Configurable fields: 975
 
 ## Fixed Fields
@@ -166,7 +166,6 @@ DIY tables created by the platform include fixed fields even when they are not p
 | `diy_course` | 3 | 课程表 |
 | `eban` | 5 | EBAN |
 | `mic_memo` | 3 | 备忘录 |
-| `mic_3d_engine` | 0 | 3D引擎 |
 
 ## Component Counts
 

package/skills/microi-db-schema/references/schema.md

@@ -205,7 +205,6 @@
 | `diy_course` | 3 | 课程表（示例） |
 | `eban` | 5 | EBAN（示例） |
 | `mic_memo` | 3 | 备忘录 |
-| `mic_3d_engine` | 0 | 3D 引擎 |
 
 ---
 

package/skills/microi-db-schema/references/table-catalog.md

@@ -34,7 +34,6 @@ Generic reference catalog. Load it only to understand common platform tables; ne
 | `eban` | 5 | EBAN |
 | `mci_mqtt_client` | 5 | MQTT客户端 |
 | `mci_mqtt_log` | 4 | MQTT记录 |
-| `mic_3d_engine` | 0 | 3D引擎 |
 | `mic_ai` | 19 | AI模型管理 |
 | `mic_ai_record` | 5 | mic_ai_record |
 | `mic_data_dashboard` | 5 | 数据大屏 |
@@ -574,14 +573,7 @@ Generic reference catalog. Load it only to understand common platform tables; ne
 | `Type` | 类型 | `varchar(50)` | `Radio` | 类型 |
 | `MqttClientId` | MqttClientId | `varchar(36)` | `Guid` | MqttClientId |
 
-### `mic_3d_engine` - 3D引擎
-
-字段数：0
-
-| 字段 | 标签 | 类型 | 控件 | 说明 |
-|---|---|---|---|---|
-
-### `mic_ai` - AI模型管理
+### `mic_ai` - AI模型管理
 
 字段数：20
 

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 与商城交付 |
@@ -52,11 +54,13 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/mqtt-engine.md` | v8-mq-mqtt | MQTT Broker、SaaS 认证、Topic ACL、V8 事件、设备路由、下行与生产部署 |
 | `system-engine/page-engine.md` | page-engine | 界面引擎 JSON |
 | `system-engine/print-engine.md` | print-engine, v8-frontend-events | 服务端模板打印与蓝牙直连边界 |
-| `system-engine/bluetooth-printer.md` | v8-frontend-events, print-engine, microi-client-frontend | GP-M322 与 CC4 双型号、TSPL/CPCL/ESC-POS、BLE/SPP、旧 V8 兼容及实机验收 |
+| `system-engine/bluetooth-printer.md` | v8-frontend-events, print-engine, microi-client-frontend, microi-microservice | GP-M322 与 CC4 双型号、TSPL/CPCL/ESC-POS、BLE/SPP、微服务平台普通打印桥、旧 V8 兼容及实机验收 |
 | `system-engine/report-engine.md` | report-engine | 虚拟报表和导出 |
 | `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

@@ -181,6 +181,13 @@ AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data
 宿主桥接不授予菜单或数据权限。业务保存成功后才能关闭/跳转，不能把尽力返回的
 `micro-app:host-action-result` 当作业务持久化确认。
 
+微服务需要平台普通打印时使用 `openPlatformPrint`，并先确认它存在于
+`hostCapabilities.actions`。参数只传 `mic_print.Id`、标题和当前 `apiBase` 同源且以
+`/apiengine/` 开头的数据地址；地址必须明确携带与页面一致的 `OsClient`，不得携带 Token、
+帐号密码或其它 URL 凭据。该动作只表示 Print Engine 预览已打开，不代表浏览器已打印或
+打印机已出纸，也不是 BLE/SPP 蓝牙代理。独立运行没有宿主时应隐藏/禁用入口。可复制示例见
+[`references/runtime-delivery.md`](references/runtime-delivery.md#微服务调用平台普通打印)。
+
 微服务自己的左侧菜单、页签和详情层级属于**子应用内部路由**，必须由子应用 Vue Router、
 状态机或 iframe 内 Hash 管理；禁止为 `/overview`、`/portal` 等同一 AppKey 页面调用宿主
 `navigate/replaceTab`。吾码 TagsView 以主框架 `$route.fullPath` 作为组件 key，修改宿主路由会
@@ -188,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` 打开，也禁止子应用通过随机实例名规避运行时缓存；双层缓存会产生旧宿主与当前路由竞争、无数据、永久骨架屏和白屏。
@@ -214,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/microi-microservice/references/runtime-delivery.md

@@ -221,6 +221,52 @@ window.addEventListener('appstate-change', function (event) {
 子应用通过模板 SDK 调用接口，不自行发明认证协议。关闭/结果使用宿主约定的
 success、cancel、error/close 事件；业务写入成功后再报告 success。
 
+## 微服务调用平台普通打印
+
+菜单微服务需要增加“普通打印”时，使用 `microi.host.v1` 的 `openPlatformPrint` 动作打开
+吾码 Print Engine 预览。不要跨 iframe 调 `window.parent.V8`、Vue 实例或打印组件，也不要
+把平台打印弹窗复制进每个子应用。
+
+```javascript
+function openPlatformPrint(printId, businessId) {
+  const host = window.microApp?.getData?.() || {};
+  const capabilities = host.hostCapabilities;
+  if (capabilities?.protocol !== 'microi.host.v1'
+      || !capabilities?.actions?.includes('openPlatformPrint')) {
+    throw new Error('当前吾码宿主不支持平台普通打印');
+  }
+
+  const dataApi = new URL('/apiengine/get-print-data', host.apiBase);
+  dataApi.searchParams.set('OsClient', host.osClient);
+  dataApi.searchParams.set('Id', businessId);
+  const requestId = `print-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  window.microApp.dispatch({
+    type: capabilities.requestType || 'micro-app:host-action',
+    action: 'openPlatformPrint',
+    requestId,
+    data: {
+      printId, // mic_print.Id
+      dataApi: dataApi.toString(),
+      title: '普通打印'
+    }
+  });
+  return requestId;
+}
+```
+
+参数与失败语义：
+
+- `printId` 只接受 1～128 位字母、数字、下划线或连字符，对应当前租户可读的
+  `mic_print.Id`。
+- `dataApi` 必须是绝对 HTTP(S) 地址，与宿主当前 `apiBase` 同源，路径以
+  `/apiengine/` 开头，并明确携带大小写不敏感匹配的 `OsClient`；禁止 URL 凭据和片段。
+- 宿主通过 `micro-app:host-action-result` 回传同一个 `requestId`。成功数据
+  `{ accepted:true, printId }` 只说明预览弹层已打开，不证明浏览器打印或物理出纸。
+- 独立运行没有 `hostCapabilities`；应隐藏/禁用按钮或使用应用自己的独立预览方案。
+- 该动作不是蓝牙代理。平台前端 V8 的 TSPL/CPCL/ESC-POS 与 BLE/SPP 继续使用
+  `V8.Print`，不能把原生命令字节传给 `openPlatformPrint`。
+
 ## 版本与回滚
 
 - 每个发布版本保存入口、文件清单、哈希和页面清单。

package/skills/print-engine/SKILL.md

@@ -26,6 +26,9 @@ ZICOX CC4、BLE/SPP 或
 
 - Print Engine 决定“页面/模板如何排版”，适合 A4、PDF、浏览器打印和统一模板。
 - `V8.Print` 生成/适配打印机原生命令并通过 BLE 或 Android SPP 写入，适合标签和热敏小票；GP-M322 保持 TSPL 原字节，CC4 可自动生成 CPCL。
+- MicroService 不能跨 iframe 访问父页面打印组件；普通打印使用 `microi.host.v1` 的
+  `openPlatformPrint`，只传当前租户 `mic_print.Id` 和同源 `/apiengine/` 数据地址。该动作
+  不是蓝牙代理，不发送 BLE/SPP 字节。详见 `../microi-microservice/references/runtime-delivery.md`。
 - 两者可以由同一个按钮按设备能力选择，但不能把 `PageObj` 直接交给
   `V8.Print.prepareSend`，也不能把 TSPL/CPCL/ESC-POS 字节当作 Print Engine JSON。
 

package/skills/v8-frontend-events/references/bluetooth-print.md

@@ -8,6 +8,7 @@
 ## 目录
 
 - [前端挂载范围](#前端挂载范围)
+- [微服务中的平台普通打印桥](#微服务中的平台普通打印桥)
 - [运行环境与能力判断](#运行环境与能力判断)
 - [双型号兼容契约](#双型号兼容契约)
 - [连接与发送语义](#连接与发送语义)
@@ -38,6 +39,19 @@ Microi 浏览器/5+App 前端 V8 中可用，不属于后端接口引擎、后
 PC/平板顶部导航和移动端【我的】页的蓝牙入口也使用该单例：它们展示实时连接状态和设备名，
 点击后复用 `OpenBluetoothPage()`，因此用户可以先在全局入口连接，再进入任意模块执行 V8 打印。
 
+## 微服务中的平台普通打印桥
+
+隔离运行的 MicroService 不能直接访问父页面 `V8.Print`、Vue 组件或打印弹窗。微服务页面需要
+提供“普通打印”时，调用 `microi.host.v1` 的 `openPlatformPrint` 宿主动作；参数为当前租户
+`mic_print.Id`、标题，以及当前 `apiBase` 同源、路径以 `/apiengine/` 开头并明确携带同一
+`OsClient` 的绝对数据地址。禁止把 Token、帐号密码或其它凭据放进 URL。
+
+`openPlatformPrint` 只打开 Print Engine 预览，不发送 TSPL/CPCL/ESC-POS；它不是蓝牙代理，
+也不发送 BLE/SPP 字节。
+宿主返回 `accepted:true` 只表示预览已打开，不代表浏览器已打印或打印机已出纸。独立运行没有
+宿主能力时应隐藏/禁用该入口。完整调用示例与结果协议见
+`../../microi-microservice/references/runtime-delivery.md` 的“微服务调用平台普通打印”。
+
 ## 运行环境与能力判断
 
 | 运行环境 | 当前引擎 | 结论 |

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."