@microi.net/cli 5.5.3 → 5.5.5

package/skills/README.md

@@ -8,7 +8,7 @@
 
 ## 包含的 Skills
 
-当前仓库包含 66 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
+当前仓库包含 67 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
 
 ### V8 引擎核心（后端）
 
@@ -59,7 +59,8 @@
 | **dos-orm** | Dos.ORM 实体、查询、事务、Provider、批量写入与 CodeFirst | `dos-orm/SKILL.md` |
 | **microi-left-right-layout** | 模块引擎“树形+表格/表单”左右布局与主外键过滤 | `microi-left-right-layout/SKILL.md` |
 | **datasource-engine** | SQL/V8/JSON 数据源设计、租户与权限、字段供数和验收 | `datasource-engine/SKILL.md` |
-| **job-engine** | 定时/后台任务、多节点租约、幂等、恢复和进度 | `job-engine/SKILL.md` |
+| **job-engine** | 定时/后台任务、多节点租约、幂等、恢复和进度 | `job-engine/SKILL.md` |
+| **email-engine** | 多账号邮箱、IMAP/SMTP、自动同步、草稿、附件、发送防重和邮箱 MCP | `email-engine/SKILL.md` |
 | **message-notification** | 公众号/服务号、短信、邮件、平台内部通知、SignalR、幂等与商城交付 | `message-notification/SKILL.md` |
 | **search-engine** | Elasticsearch 索引、同步、查询、租户/数据范围和重建 | `search-engine/SKILL.md` |
 | **report-engine** | Rpt_Report 虚拟报表、数据源、聚合、写接口和导出 | `report-engine/SKILL.md` |

package/skills/ai-engine/SKILL.md

@@ -9,7 +9,21 @@ description: Microi AI 引擎、MiniMax 图片/音乐/视频生成与预览、
 
 平台媒体生成的受控 HTTP 入口包括 `/api/Ai/GenerateMiniMaxImage`、`/api/Ai/GenerateMiniMaxMusic`、`/api/Ai/CreateMiniMaxVideo`、`/api/Ai/GetMiniMaxVideoTask`、`/api/Ai/GetMiniMaxVideoFile`、`/api/Ai/PersistMiniMaxVideoFile`；AI 工作流统一调用 Managed 接口引擎 `/apiengine/platform-ai-workflow`，通过 `Action` 选择概览、节点详情、生成、列表、读取、保存或删除。调用方只提交业务参数和模型选择，供应商密钥、租户配额、任务归属和文件读取权限由服务端判定。生成结果必须先进入当前租户 HDFS 或受控临时句柄，浏览器不接触供应商密钥、图片 Base64、音频十六进制或原始视频任务 Id。`PersistMiniMaxVideoFile` 只能转存当前登录用户所属且已完成的任务，禁止作为任意 URL 搬运器。
 
-## 能力
+## 能力
+
+### 媒体模型目录与中转（2026-09）
+
+- 媒体选择以当前租户 `mic_ai.Id` 和实际媒体 `Model` 为准，图片、音乐、视频及配音请求携带 `AiModelId`。显式记录不可用时不得静默切换其它账号、主租户密钥或聊天模型。
+- `MediaProtocol` 与 `MediaModels` 由 AI助手应用包交付。目录项为 `{ Id, Name, Capability, Protocol }`，能力支持 `image/music/video/speech`；协议与模型名称分离，未知协议明确不可选。新增供应商协议仍须真实后端适配器和契约测试，不能只改模型名称。
+- `/api/Ai/GetMediaModels` 返回当前登录租户的可选目录，官方中转 `/v1/microi/media_models` 只返回安全投影，不含 Key、Endpoint 或供应商记录 Id。中转接收端按本机 `IsRelayModel=1` 的供应商目录选实际模型，不接受外部租户记录 Id。
+- 图片生成继续使用持久任务；等待中转结果与执行供应商请求的 Worker 必须分开调度并预留执行容量，避免同节点循环等待。中断后查询原 TaskId，不能把 HTTP 524、Uncertain 或 Token Plan 使用状态猜测为关键词违规或扣费。
+- 必须区分 MiniMax 开放平台 `image-01` 的 `subject_reference` 人物参考协议、MiniMax Code 的 `connector__matrix__generate_image` / `input_urls` 图像编辑工具，以及 OpenAI Images edits 协议。某个接口编辑失败，不能推断整个 MiniMax Code 不支持编辑；聊天界面选择 M3 也不证明实际图像工具的底层模型就是 M3。验收须看输出原图。
+- MiniMax Code 图像编辑使用独立 `mic_ai` 行：`MediaProtocol=minimax-connector-image`，逻辑模型 `minimax-code-image`，Endpoint 为官方 `https://agent.minimaxi.com` 或 `https://agent.minimax.io`。工具未开放底层 model 字段，不能伪造。只接受服务器发现的固定图像/上传/文件 URL 工具，不增加任意工具执行入口。
+- Connector 使用独立 OAuth 授权，不能复用 Token Plan API Key，也不能复制桌面 `electron` 登录态的 refresh_token。管理员通过连接账户或导入独立授权绑定引擎；凭据按租户和记录加密，续期使用共享锁与 CAS，目录、日志和响应不含 Token。应用包只扩展协议选项和凭据字段容量，不复制账号。
+- 原图先通过当前租户私有 HDFS 校验，再取得供应商临时上传凭证。Multipart 文件分段须先写 Content-Disposition 再写 Content-Type，避免供应商 OSS 返回 MalformedPOSTRequest。生成结果先保存 node_id 回执，再调用 get_asset_url 并转存 HDFS；已有节点时只恢复下载，不重新生成。临时 URL 不作为永久结果，也不携带 OAuth 头访问文件域名。失败状态提供 CanRecoverResult 时，可通过 RecoverMiniMaxImageTask 或中转任务 recover 入口显式恢复原 TaskId；恢复 Worker 必须再次检查节点，节点失效时禁止重新生图。4K 图片下载允许最大 64 MiB，并继续执行租户存储限额。每次工具调用前重新取得当前连接授权；明确 401 才可刷新后重试一次，超时不重发生成。
+- 升级要求包括 AI助手 v7.6.9、平台后端 v8.1.11 或更高版本、平台前端和中转节点程序；应用包只升级字段/受管资源，不复制租户密钥或替换运行二进制。媒体存储必须保留真实用户的上传开关、载荷和配额检查，仅可信后端能授权固定的私有参考图与公有生成结果目录，不能放宽普通用户上传策略。
+- MiniMax 参考图以已校验原始字节的 data URI 发送，仍须先执行租户私有 HDFS 上传与配额检查；参考图请求关闭 prompt_optimizer。人物主体参考重绘不能等同局部精确编辑，验收必须同时检查任务结果和图片实际内容。
+- 图片工具须按操作匹配模型能力：MiniMax 人物参考最多一张，不得用于消除、扩图、线稿还原、多图合成等结构编辑；前端过滤与后端校验必须一致。兼容媒体协议的型号由当前租户 mic_ai 目录验证，参数规范层不得再次把音乐、视频、配音固定为单一历史型号；未实现的供应商协议仍明确标为不可用。
 
 平台 AI 包含聊天/流式聊天、模型代理、模型路由、订阅配额、NL2SQL、NL2V8、数据库 Schema 关键词检索、可选向量融合和 V8 Skill 文档检索。AI 输出是建议，不是授权；执行 SQL、V8 或 MCP 写入前仍走平台权限与确认。
 
@@ -54,12 +68,18 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - 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助手。
 
-## 模型与密钥
-
+## 模型与密钥
+
+存量模型配置的兼容验收组合包括 `GenerateMiniMaxImage + image-01`、`GenerateMiniMaxMusic + music-2.6`。这些组合只适用于服务端已配置且供应商账号仍有权限的旧路由；新路由仍遵循下列实时能力选择规则。验收必须同时检查实际返回的模型标识、媒体类型与 HDFS 读取，不能仅凭兼容接口名称判断底层模型。
+
 - 模型 Provider、Endpoint、ApiKey、AuthPrefix 和上游模型 Id 只保存在服务端受保护配置。
 - 普通用户使用平台签发的受限 API Key/订阅身份，不能枚举或读取上游密钥。
-- 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` 精确处理。
+- MiniMax 对话媒体必须区分意图模型与生成工具：`MiniMax-M3` 是对话与工具编排模型；图片入口兼容名仍为 `GenerateMiniMaxImage`，实际模型由 `mic_ai.MediaProtocol / MediaModels` 与当前媒体选择决定，不能固定为 `image-01`。MiniMax Code 的 `generate_image + input_urls` 使用 `minimax-connector-image` 协议和逻辑路由 `minimax-code-image`；供应商未公开底层图像模型名，不得把界面选择的 M3 当成图片生成底模。纯音乐优先使用所配置且可用的 `music-3.0`，兼容 `music-2.6`；托管音乐只有明确返回 410 退役终态时才允许切到官方开源 `MiniMax-Music3`，不得把超时、5xx、额度不足当作回退条件。目标账号能力必须实时校准，不得用文本说明冒充生成产物。
+- `GenerateMiniMaxImage` 使用稳定 `RequestId` 持久入队，返回 `Code=2 + Data.TaskId` 后只通过 `GET /api/Ai/GetMiniMaxImageTask?taskId=...` 查询。只有 `Code=1 + Images` 才表示原图已写入 HDFS；浏览器超时、刷新或停止等待不能取消后台生成，也不能换请求号自动重发。图片任务复用 `mci_background_task` 的租户/用户隔离、数据库唯一键、分布式租约和 fencing，原生 Worker Key 为 `__microi_native_ai_image__`，不可由租户 V8 覆盖。请求参数只保存在服务端私有任务列，状态接口不返回提示词或参考图。
+- `GenerateMiniMaxImage` 可接收最多 4 张 JPEG/PNG/WebP 参考图；先写当前租户私有 HDFS，由可信适配器上传原图或提供短时签名 URL，浏览器与响应均不得得到供应商上传票据和签名地址。`image-01` 的 `subject_reference` 是人物参考重绘，不能据此声称所有 MiniMax 工具都不支持消除。消除、换背景等操作须选择目录中声明对应编辑能力的协议：MiniMax Code 使用 `input_urls`，OpenAI Images 兼容模型使用 edits；实际效果必须逐张检查，生成式身份保持、发丝边缘与像素不变不能仅凭接口成功判为通过。黑白、纯色背景抠除、缩放、裁剪、旋转、翻转、格式转换和拼图使用 `platform-ai-runtime/ProcessImage + V8.Image` 精确处理。
+- MiniMax Code 媒体连接使用管理员独立 OAuth 授权，不读取或复用桌面客户端凭据。令牌在可信后端按租户及引擎记录绑定加密保存，刷新使用共享锁与旧值比较；明确 401 可刷新后重试一次，不确定生成请求不得重发。生成结果节点须先保存到共享存储；下载或 HDFS 失败且存在节点时，通过同一 TaskId 的 `RecoverMiniMaxImageTask` 或 `/v1/microi/image_tasks/{taskId}/recover` 恢复已有图片，不再次生成。目录只公开能力元数据。`MediaModels` 可扩展同协议模型；新的供应商协议仍需适配器、商城字段及真实中转验收，不能只填名称就宣称已接通。
+- 吾码节点之间的图片中转使用 `POST /v1/microi/image_tasks` 与 `GET /v1/microi/image_tasks/{taskId}`，服务端平台 API Key 鉴权，提交必须有稳定 `Idempotency-Key`。查询不占用生成额度；接收节点只能使用已启用且公布的供应商媒体模型，禁止自调用中转环路。MiniMax 官方适配器调用同步 `/v1/image_generation`，其它供应商由对应协议适配器处理。消费者、官方中转节点和前端必须更新到同一持久任务协议；应用包更新不能代替平台二进制与前端更新。
+- HTTP 524、连接取消或空响应仅说明传输状态不确定，不能断言提示词违规、Token Plan 不可用或已扣费。明确供应商拒绝保留 `UpstreamHttpStatus`、`UpstreamCode` 和错误消息；`Failed/Uncertain` 不能在回读时合并成“仍在生成”。MiniMax 同步接口没有本任务可用的结果查询号时，不得伪造回查成功或盲目重发；相同 RequestId 参数冲突必须拒绝。
 - 图片与音乐都使用稳定 `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/类型校验。
 - 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 不能替代生成成功。
@@ -68,7 +88,7 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - 视频创建必须要求调用方稳定 `RequestId`，先在当前租户共享 Redis 以 `OsClient + 用户 + RequestId` 原子 `NX` 占位；Redis 不可用时失败关闭。相同 RequestId/参数回放返回原任务，不同参数冲突拒绝；上游 POST 超时或结果不确定时禁止自动换 RequestId 重试。查询不再次扣生成额度。
 - 原始 MiniMax `task_id`/`file_id` 不下发。服务端返回由供应商 Key 签名、绑定当前用户和用途的短句柄；查询/下载验签后才还原。Key 轮换会使旧句柄失效，应先完成或重新登记在途任务。
 - 当前官方模型边界必须实时校准：`MiniMax-Hailuo-2.3` 支持文生/图生，`MiniMax-Hailuo-2.3-Fast` 仅图生且必须有首帧，首尾帧使用 `MiniMax-Hailuo-02`。Hailuo 2.3 的画质优先上限与平台默认值是 6 秒 / 1080P，时长优先上限是 10 秒 / 768P，两者不能同时最大；API 不提供 fps 参数，必须用媒体探针记录真实帧率，禁止把插帧/画布规格冒充模型原生能力。当前 Token Plan 使用统一用量条、5 小时固定窗口和周窗口，控制台是剩余额度事实源，不再把固定“每天 N 条”写成官方配额。需要自动生成时，在 `Microi.AI` 增加只读、脱敏、管理员限定的 `https://www.minimaxi.com/v1/token_plan/remains` 安全原子能力；不得由浏览器或可编辑 V8 读取 Provider Key，也不得把客户端今日计数当成供应商权威额度。
-- MiniMax 视频任务返回静音画面。需要人物对白时，男/女语音必须通过 `Microi.AI` 的 `GenerateMiniMaxSpeech` 受保护原子能力生成：固定 `speech-2.8-hd`、固定男女系统音色、稳定 RequestId、共享 Redis 幂等，并直接转存租户 HDFS；再由可靠 Worker 按时间轴混音、加准确字幕。无法证明口型同步时使用画外音或反打镜头。背景音乐使用 `GenerateMiniMaxMusic` 并在人声下压低。运行节点尚未部署 Speech 能力、额度未核实或母版混音/探针证据缺失时失败关闭，禁止静音、仅配乐、浏览器直连供应商或伪称模型原生带声。
+- 当前 Hailuo 2.3 视频适配器返回静音画面；其它视频协议是否含声以实际模型能力和音轨探针为准。需要人物对白时，男/女语音通过 `Microi.AI` 的 `GenerateMiniMaxSpeech` 受保护原子能力生成：由当前租户 mic_ai 选择 speech 模型与受支持音色，`speech-2.8-hd` 是现有默认值；保持稳定 RequestId、共享 Redis 幂等，并直接转存租户 HDFS；再由可靠 Worker 按时间轴混音、加准确字幕。无法证明口型同步时使用画外音或反打镜头。背景音乐使用 `GenerateMiniMaxMusic` 并在人声下压低。运行节点尚未部署 Speech 能力、额度未核实或母版混音/探针证据缺失时失败关闭，禁止静音、仅配乐、浏览器直连供应商或伪称模型原生带声。
 - 管理端【AI视频】应按 `TaskHandle` 轮询任务，成功后优先转存 HDFS，并用 `<video controls preload="metadata">` 原页预览和明确下载按钮消费同一个已校验地址。临时 URL、生成完成、HDFS 转存、媒体可播放和外部平台发布是五个不同事实，必须分别验收。
 - 使用 Microi.AI 中转站时，租户侧 AI Bootstrap 通过官方 `official_ai_relay_models` 发现可用运行模型。该接口是跨租户只读公共契约，必须保持启用、允许匿名 HTTP 调用，并且只返回模型标识、展示名等公开白名单字段，绝不能返回中转密钥或上游 Endpoint。消费者不得把 `NoAuth` 静默伪装为“没有配置模型”；应返回可诊断错误，同时前端显示明确空态。
 - PC、UniApp 和其它客户端通过 `POST /apiengine/{key}` 发送的 JSON Body 必须完整进入 `V8.Param`；兼容入口 `/api/ApiEngine/Run` 的 JSON Body 还必须包含 `ApiEngineKey`。API 层只负责请求绑定和清除客户端伪造的可信字段，模型选择、权限策略与对话逻辑仍全部位于 `Microi.AI` 或受控 AI 接口引擎中。
@@ -82,12 +102,24 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - 官方 AI助手应用归 `app.microi.ai-engine`。v6.3.6 的接口引擎必须严格只有 Managed `mci_ai_data_assistant`、Managed `platform-ai-account`、Managed `platform-ai-runtime` 和 CreateIfMissing `platform-ai-custom-hook` 四项，并声明 `V8.Method.ManageAiPlatform`、`V8.Method.RequireManagedProtocolContext` 与所需 `V8.AI` 能力；后端缺少任一能力时安装预检失败关闭。
 - `ai_app_list`、`ai_app_detail`、`ai_app_get_file`、`ai_app_save_file`、`ai_app_create`、`ai_app_build`、`ai_app_preview`、`ai_app_download_source_zip`、`ai_app_download_build_zip`、`ai_app_moveobject_probe`、`ai_app_moveobject_exec_probe`、`ai_app_publish_store` 这 12 个 `ai_app_*` 归 `app.microi.store` 维护。AI助手包移除它们的资源选择和所有权声明，但不会删除目标租户既有运行时接口记录；既有记录继续由应用商城包升级。
 - v6.3.6 还必须保持 AI助手包的 DDL、PhysicalColumns、DiyTables、DiyFields、DataSets 全层不再包含重复的 `mci_ai_app_version`、`mci_ai_app_file`、`sys_microistore`，这些表交回 Store/SaaS 既有平台包维护；当前仅 AI助手包拥有的 `app_mic_aiapp`、`mci_ai_app` 继续保留。
-- 普通角色必须匹配启用的 `mci_ai_role_policy`。只有后端可信的 `V8.CurrentUser.Level >= 9999` 可以在新安装租户缺少角色策略时获得安全兜底：从目标租户动态读取已启用业务域和模型，范围为 `All`，仍保持 `AllowRawSql=false`、敏感字段默认关闭。不得相信客户端提交的 Level、角色名或账号名。
-- 当租户要求“所有角色均可使用 AI 助手”时，必须为 `sys_role` 中每个目标角色建立显式启用策略；受限角色使用 `Self`/`Department` 与最小业务域，管理角色才可使用经确认的 `All`。禁止把“人人可打开助手”实现成普通角色默认全库可读。
-- `Sys_Config.DisableAiAssistant` 是负向开关：缺失、空值或 `0/false` 都显示 AI 助手，只有显式 `1/true` 才关闭图标。历史包曾复用旧 `IsShowAiAssistant` 的字段元数据 Id 就地改名；因此清理旧开关必须按当前表名和字段名回读定位，不能只按历史 Id 删除，避免误删已复用该 Id 的新开关。官方母版必须通过标准 MCP 删除旧字段元数据，不能仅隐藏；新版包的 DiyFields、PhysicalColumns、DDL 及生成器均不得重新创建旧开关。平台删除字段可保留存量物理列兼容，但新前端只读取 DisableAiAssistant，不得重建正向开关或改写租户现有配置值。关闭该开关前后都要做策略覆盖验收：回读 `sys_role` 与 `mci_ai_role_policy`，断言每个目标角色都有唯一启用策略，`AllowedDomains`、`AllowedModels` 均非空且模型仍处于启用状态；再至少用超级管理员、普通员工和客户身份分别调用 `Bootstrap`，确认 `Enabled=true` 且返回范围符合角色。仅看到入口图标不算可用。
-- 提审要求关闭 AI 入口时，必须把“关闭AI助手图标”设为 `DisableAiAssistant=1`，从数据库、客户端实际配置接口和入口逐层验收，不能用旧正向字段为 `0` 代替。官方包发布与其他租户安装是两个独立动作；未执行目标租户安装或字段清理时，不得宣称全体存量租户已移除旧元数据。
-- 角色策略存在但 `AllowedModels` 为空时，客户端最终仍会得到无可用模型；不得把它误判为前端角色拦截。应补齐当前租户启用模型白名单并回读，而不是删除 `mci_ai_role_policy` 校验或在客户端强制把 `Enabled` 改成 `true`。
-- 商城包不能携带发布租户的角色 Id、模型 Id 或密钥；应携带业务域定义和接口引擎，由安装后的目标租户动态发现自己的启用模型。发布后回读 `sys_microistore.AppVersion/AppPakcet`，并真实执行 `Bootstrap` 验证超级管理员可用、模型非空、快捷问题存在。
+- 普通角色读取业务数据必须匹配启用的 `mci_ai_role_policy`，这不是常规对话的前置条件。只有后端可信的 `V8.CurrentUser.Level >= 9999` 可以在新安装租户缺少角色策略时获得数据分析安全兜底：从目标租户动态读取已启用业务域和模型，范围为 `All`，仍保持 `AllowRawSql=false`、敏感字段默认关闭。不得相信客户端提交的 Level、角色名或账号名。
+- 所有已登录账号默认可使用 AI 常规对话，包括未分配任何角色、未申请业务身份、没有数据域、策略禁用或原模型已失效的账号。官方 AI助手 v7.7.1 在 `mic_ai` 的“基础配置”提供 `AllowAllRolesChat`（所有角色可常规对话），默认 `1`；存量缺失/null/空值兼容开启，显式 `0/false/'0'/'false'` 关闭该模型的公共对话使用权，启用值兼容 `1/true/'1'/'true'`。此开关不授予业务数据、SQL、菜单或管理权限，也不绕过登录、供应商额度和模型启用状态。
+- 历史“所有角色使用助手都必须逐个建策略”的经验只适用于授予这些角色业务分析权限，不再适用于打开助手或常规对话。需要分析数据的目标角色仍应有显式策略；受限角色使用 `Self`/`Department` 与最小业务域，管理角色才可使用经确认的 `All`。禁止把“人人可打开助手”实现成普通角色默认全库可读。
+- `Sys_Config.DisableAiAssistant` 是负向开关：缺失、空值或 `0/false` 都显示 AI 助手，只有显式 `1/true` 才关闭图标。历史包曾复用旧 `IsShowAiAssistant` 的字段元数据 Id 就地改名；因此清理旧开关必须按当前表名和字段名回读定位，不能只按历史 Id 删除，避免误删已复用该 Id 的新开关。官方母版必须通过标准 MCP 删除旧字段元数据，不能仅隐藏；新版包的 DiyFields、PhysicalColumns、DDL 及生成器均不得重新创建旧开关。平台删除字段可保留存量物理列兼容，但新前端只读取 DisableAiAssistant，不得重建正向开关或改写租户现有配置值。关闭该开关前后都要做权限分层验收：回读 `sys_role` 与 `mci_ai_role_policy`，需要业务分析的角色应有明确启用策略，`AllowedDomains`、`AllowedModels` 有效且模型仍处于启用状态；无策略账号仍可常规对话。至少用无角色、超级管理员、普通员工和客户身份分别调用 `Bootstrap`，确认 `Enabled=true`，并独立验证 `CanQueryData` 与数据范围符合角色。仅看到入口图标不算可用。
+- 提审要求关闭 AI 入口时，必须把“关闭AI助手图标”设为 `DisableAiAssistant=1`，从数据库、客户端实际配置接口和入口逐层验收，不能用旧正向字段为 `0` 代替。官方包发布与其他租户安装是两个独立动作；未执行目标租户安装或字段清理时，不得宣称全体存量租户已移除旧元数据。
+- 角色策略存在但 `AllowedModels` 为空或只引用已删除模型时，业务分析不可用，常规对话仍动态使用当前租户启用且开放的对话模型。要恢复原业务分析能力，应经管理员授权补齐当前租户模型白名单并回读，保留原 `DataScope/AllowedDomains`，不能静默把任何新模型当作已获准接收业务数据。禁止删除角色策略校验或在客户端强制 `Enabled=true`。
+- 商城包不能携带发布租户的角色 Id、模型 Id 或密钥；应携带业务域定义和接口引擎，由安装后的目标租户动态发现自己的启用模型。发布后回读 `sys_microistore.AppVersion/AppPakcet`，并真实执行 `Bootstrap` 验证超级管理员可用、模型非空、快捷问题存在。
+
+### 常规对话与业务数据权限分离（强制）
+
+- `Bootstrap.Enabled` 表示登录账号可进入助手，`ChatEnabled` 表示存在可用对话模型，`CanQueryData` 独立表示可分析已授权业务数据。无数据权限时返回空 `AllowedDomains` 和“常规对话”；模型列表为空时返回 `MODEL_UNAVAILABLE`，客户端提示检查模型，不得再显示“当前角色未开通 AI助手”。入口的 `DisableAiAssistant`、模型的 `AllowAllRolesChat` 和业务数据策略是三种不同含义，不能互相替代。
+- 多角色权限必须按“数据域 + 当前模型”分别合并。A 域的 `All` 不能提升 B 域的 `Self`，其它模型的白名单不能授权本轮模型读取数据。没有适用授权、范围无法落到固定业务字段、敏感字段未开放时，业务读取失败关闭。
+- 普通问候、写作与知识问答不自动查询全部业务域。常规对话路径不查询业务表、不提供 Schema/SQL/工具，也不把历史数据模式消息重新送入无数据权限的模型上下文。客户端伪造 Mode、RoleIds、Level、AllowedDomains 或模型 Id 不能扩大范围。
+- 对话模型发现必须按当前模型和媒体目录判断能力，纯图片/音乐/视频/配音型号不能成为默认文本模型；中转目录只暴露安全投影，不返回供应商 ApiKey 或 Endpoint。远端 HTTP 可能返回 Promise，必须等待真实模型结果，不能把 Promise 当字符串或用统计兜底冒充常规对话成功。
+- 打开助手和身份变更时重新获取 Bootstrap；请求结果按用户与请求代次隔离，旧角色/旧账号请求不能覆盖新状态。模型缺失、网络失败、会话失效分别处理，并保留重试。
+- 欢迎语、输入提示与等待状态也必须区分常规对话和业务分析；无数据权限时不得声称已连接业务数据、正在汇总业务记录。前端定时动画不能冒充服务端实际执行进度。
+- 官方 AI助手 v7.7.2 的 `mci_ai_data_assistant.ApiRole` 显式使用平台支持的 `["$authenticated"]`，`AllowAnonymous=0`，让 `OnlyGet` 只读角色也能调用助手和保存自己的对话。不能通过清空角色 `BaseLimit`、给账号添加管理员角色或放开其它业务接口解决聊天入口受阻；必须用真实只读客户账号验证 Bootstrap、Chat、会话记录与原业务限制仍成立。
+- 最低验收：无角色、客户、员工、管理、多角色账号分别执行 Bootstrap 和真实 Chat；确认无数据账号 `UsedAi=true/Mode=chat/Domains=[]`，有数据账号按本人/部门范围查询。测试禁用策略、旧模型、显式关闭公共对话模型、纯媒体模型、跨账号历史、伪造权限和模型故障。管理员单账号成功、仅图标截图或本地 mock 成功都不能代替普通账号真实验收。
 
 ## Schema 检索双模式
 

package/skills/app-store/SKILL.md

@@ -305,6 +305,8 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 - 触发场景：同一轮主租户批量任务在不同子租户分别报“数据集目标表尚未创建”“接口引擎写入后 HTTP 状态不一致”“既有菜单 Url 唯一冲突”或“未找到 OsClient”；父任务若在目录阶段对全部目标做有副作用自举，还会让一个坏租户阻断其余已可执行租户。
 - 包结构闭包：任何 `DataSets.TableName` 都必须由同一包的 `DiyTables + DiyFields + DDLStatements + PhysicalColumns` 完整创建或由显式依赖声明保证先安装，不能只因为官方母库已有该表就省略。契约测试要逐个数据集反向验证目标表、主键、字段和物理 DDL，并在真实缺表旧租户执行首次安装与重复安装。
+- 配置子表种子不能硬编码官方父记录 Id。`InsertIfMissing` 数据集可声明 `ParentBinding:{Field:'SysConfigId',TableName:'sys_config',MatchField:'IsEnable',MatchValue:1}`，仅在目标端查询恰好一条父记录 Id，先绑定外键再检查冲突。0 条、多条、查询失败或不安全标识立即失败；不能覆盖父配置值。导出器须保留该声明，旧导入器必须先升级，不能忽略绑定后按官方 Id 写入。
+- 大表物理兼容必须覆盖全部 DDL 路径：`BIT` 不能落入 `varchar` 默认映射，整数显示宽度与纯标签/注释差异不能触发改列；同一个包的字段元数据变化交给物理列阶段统一比较，不能先改再改回。只有默认值变化时使用 `ALTER COLUMN ... SET/DROP DEFAULT`、强回读并禁止 COPY 回退，不能用完整 `MODIFY COLUMN` 重写类型/字符集/历史行；空字符串默认值不等同于无默认值。安装器时间辅助必须自包含，应用文件落库等新增分支也不得直接依赖租户的 DateNow。
 - 受管接口状态：旧库 `diy_field` 元数据可能落后于 `sys_apiengine` 物理列，导致 FormEngine 返回成功却忽略 `IsEnable/StopHttp`。仅对受信官方 `Managed` 接口的固定布尔控制列，允许在 FormEngine 写后不一致时按稳定 Id 参数化校准物理列、清理租户缓存并严格二次回读；源码、匿名权限、ApiAddress 和租户扩展不得借此绕过三方冲突或所有权保护，二次回读仍不一致必须整包失败。
 - 菜单与目录隔离：更新既有菜单发生 Url 唯一冲突时，优先保留目标租户当前唯一路由；确需新路由时使用有界、可回读的稳定后缀，不得字符串拼 SQL。子租户目录发现必须是无副作用读取；运行时缺失在单目标投递前按 `sys_osclients` 受控热加载并只记录该租户失败，已经排队的子任务继续监控到终态，禁止一个 `未找到OsClient` 提前终止整批。
 - 百租户并发边界：父协调任务继续使用集群级防重键；子安装任务必须使用固定商城工作器 `ConcurrencyKey` 在当前运行环境内串行。不能根据 `OsClient` 推断物理库隔离，因为多个子租户可能共享同一数据库；只有未来能由服务端权威连接指纹证明互不共享物理库并建立分组锁时，才允许在不同物理库组间并行。

package/skills/email-engine/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: email-engine
+description: 开发、安装和使用吾码邮箱系统 mci-email。用于 QQ、163、126、企业或自定义 IMAP/SMTP 邮箱账号维护、自动与手动同步、邮件阅读、草稿、附件、回复转发、发送结果核对，以及邮箱 MCP 工具和 V8.Email 协议原子。
+---
+
+# 吾码邮箱系统
+
+> **Codex 非阻塞自动更新：** 先遵循 [工作区约定](../workspace-conventions/SKILL.md)，通过 `microi update --background --workspace "<工作区绝对路径>" --json` 投递更新检查；当前任务继续执行，不等待更新或重启现有会话。
+
+邮箱系统是使用吾码 UI 的独立 Vue 3 微服务，商城 AppKey 为 `mci-email`，
+后台入口为「系统引擎 → 邮箱系统」，菜单路由 `/mci-email`。
+
+先读取 `../workspace-conventions/SKILL.md`；开发或发布时还需读取
+`../microi-microservice/SKILL.md`、`../app-store/SKILL.md`。
+先调用 `microi_list_applications`，再读取目标应用完整上下文，禁止覆盖未读取的源码。
+
+## 选择正确入口
+
+| 需求 | 入口 |
+| --- | --- |
+| 邮箱工作台 | 源码微服务 `mci-email` |
+| 账号配置 | 原表 `mic_email_server`，通过宿主 `openForm` 打开吾码表单 |
+| 全部业务 HTTP | 接口引擎 `mci-email`，请求参数 `Action` |
+| 手动同步 | `Action: Sync` 返回持久后台任务，使用 `SyncStatus` 回读终态 |
+| 自动同步 | 定时任务调用 `mci-email-auto-sync`，内部调度 `mci-email-sync-step` |
+| 协议、MIME、加密 | 最小后端原子 `V8.Email`，不新增业务 Controller |
+| 租户扩展 | `mci-email-hook`，商城策略 `CreateIfMissing` |
+| AI 操作 | `microi_email_query`、`microi_email_manage`、`microi_email_send` |
+
+当前版本沿用原邮箱配置表的平台管理员权限（`Level >= 9999`），
+并按当前用户检查账号和邮件所有权。不得因 AI 使用而绕过这些约束。
+各运行节点需要包含 `V8.Email` 的平台版本；仅安装前端源码不能补齐 .NET 协议能力。
+
+## 配置和同步
+
+1. 确认用户拥有或获准使用邮箱；在服务商处开启 IMAP/SMTP，取得客户端授权码。
+2. 打开账号表单，选择 QQ / 163 / 126 / 腾讯企业邮箱 / 自定义，填写地址与授权码。
+3. QQ、163 常用 IMAP 993 / SMTP 465，选择 `SslOnConnect`；
+   使用 SMTP 587 时选择 `StartTls`。具体端口以服务商配置为准。
+4. 授权码提交后由可信后端加密。编辑留空保留旧值；列表、导出、源码、日志和截图不含原文。
+5. 先检测连接，再手动同步。首次先显示最新一批邮件，再增量补齐历史并核对状态。
+6. 自动同步由平台定时任务运行，不依赖浏览器开着；每个账号设置同步间隔。
+
+目录路径作为服务商的不透明值保存，不能自行翻译或改写。
+去重键必须包含账号、目录、UIDVALIDITY 和 UID；UIDVALIDITY 改变时只重建该目录缓存。
+同步锁使用接口引擎分布式锁，检查点进入数据库；进程重启后继续执行。
+邮件正文按需读取，默认阻止脚本、表单提交与外部图片；不能直接在宿主使用 `v-html`。
+
+## MCP 使用
+
+先通过 `microi_codex action=profiles` 选择用户指定租户，再按工具 Schema 调用。
+
+```json
+{"action":"Overview"}
+```
+
+以上参数用于 `microi_email_query`，不会回传授权码。
+查询邮件用 `action: Messages`，可传 `accountId`、`folderKind`、`keyword`、
+`pageIndex` 和 `pageSize`；只在任务需要时读取正文或附件。
+
+维护工具先返回操作预览。用户已有明确授权后，`confirmExecution` 精确填写
+`Action:目标Id`；新账号为 `SaveAccount:new`，新草稿为 `SaveDraft:账号Id`。
+同步需要稳定的 `requestId`，恢复同一请求不得生成新值。
+
+发信先通过 `microi_email_manage(action: SaveDraft)` 保存确定的收件人、正文与附件，
+然后调用 `microi_email_send(draftId, confirmExecution: draftId)`。
+只有用户已授权发送给这些收件人时才执行；不要把读取邮件的请求当作发送授权。
+
+## 发送和结果边界
+
+- 一次发送意图绑定稳定草稿 Id 和 Message-Id；同一草稿重复请求不能再次 SMTP 投递。
+- `Sent` 表示 SMTP 服务器已接受；收件端可见需要实际收件验证。
+- `Unknown` 表示连接中断等情况导致结果不确定，保留在发件箱，禁止自动重发。
+  先按 Message-Id 检查服务商已发送目录；确需新发时由用户确认新的发送意图。
+- 远端已发送副本单独保存；副本或租户 Hook 失败不得回滚已发生的 SMTP 副作用。
+- 原子只解密当前租户的凭据，不能向 V8 暴露解密方法；必须校验 TLS 证书。
+
+协议方法和参数见 [V8.Email 原子参考](references/v8-email.md)。
+最终分别验证源码/构建、API 权限、连接、实际收件、附件字节、重复发送、
+自动同步、宿主表单、商城包与官网真实截图。

package/skills/email-engine/references/v8-email.md

@@ -0,0 +1,34 @@
+# V8.Email 协议原子
+
+业务编排使用接口引擎，下面的方法只供可信后端调用。
+连接对象字段为 `Host`、`Port`、`Security`、`UserName`、`Credential`、`Timeout`。
+`Credential` 必须是 `V8.Email.ProtectCredential` 产生的当前租户密文。
+`Security` 仅允许 `SslOnConnect`、`StartTls`。超时默认 40 秒，最高 60 秒。
+
+| 方法 | 输入补充 | 返回 Data |
+| --- | --- | --- |
+| `V8.Email.ProtectCredential(value)` | 原文授权码 | 直接返回带版本前缀的租户密文字符串 |
+| `V8.Email.TestConnection(p)` | `Protocol: IMAP / SMTP` | `Connected, Protocol, Secure` |
+| `V8.Email.ListFolders(p)` | 无 | 最多 200 个 `Path, Name, Kind, Total, Unread` |
+| `V8.Email.Fetch(p)` | `Folder, AfterUid, UidValidity, Limit, Recent` | `NextUid, HasMore, Reset, UidValidity, Messages` |
+| `V8.Email.Inspect(p)` | `Folder, UidValidity, Uids`（最多 100） | `UidValidity, Messages`，含存在的 UID 和已读/星标/删除标志 |
+| `V8.Email.GetMessage(p)` | `Folder, UidValidity, Uid` | 信封、`TextBody, HtmlBody, Attachments` |
+| `V8.Email.GetAttachment(p)` | 上述字段及 `AttachmentIndex`（从 0 开始） | `FileName, ContentType, FileByteBase64` |
+| `V8.Email.SetFlags(p)` | `Folder, UidValidity, Uid, IsRead, IsStarred` | 结果状态 |
+| `V8.Email.Move(p)` | `Folder, UidValidity, Uid, DestinationFolder` | 移动结果；不得对整个目录执行无差别清空 |
+| `V8.Email.Send(p)` | SMTP 连接及下述 MIME 字段 | `DeliveryState, MessageId`，外层 `Code` 表示协议结果 |
+| `V8.Email.StoreSent(p)` | IMAP 连接及相同 MIME 字段 | 按 Message-Id 查重并保存已发送副本 |
+
+`Fetch.Recent=true` 读取末尾最多 `Limit` 封邮件，但保留历史 `AfterUid` 游标。
+常规 Fetch 按 UID 窗口分页，`Limit` 最高 100；即使窗口为空也推进游标。
+返回的 `Reset` 必须与 `UidValidity` 一起持久化，不能把旧代邮件指向新代同号 UID。
+
+MIME 字段：`To, Cc, Bcc, Subject, TextBody, HtmlBody, InReplyTo, MessageId, Attachments`。
+附件对象：`FileName, ContentType, FileByteBase64`，最多 10 个，总大小不超过 10MB；
+读取单封原始邮件上限 25MB，正文上限 2MB。超限应明确报错，不能静默丢内容。
+
+`Send` 的结果：`Accepted`、`Rejected` 或 `Unknown`。
+在业务层保存草稿及去重标记后才能调用；不要对 `Unknown` 自动重试 SMTP。
+`StoreSent` 与真正发信分开，不可将保存副本当作已经投递。
+
+相关源码：`Microi.Server/Microi.V8Engine/Extend/Email/V8Email.cs`。

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

@@ -58,6 +58,7 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/report-engine.md` | report-engine | 虚拟报表和导出 |
 | `system-engine/saas-engine.md` | v8-saas-multi-tenant | 租户识别、SaaS 配置、ZIP 开库进度与长任务租约 |
 | `system-engine/search-engine.md` | search-engine | Elasticsearch 索引和查询 |
+| `system-engine/email-engine.md` | email-engine | 邮箱系统、源码商城安装、账号维护、收发同步和邮箱 MCP |
 | `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 回退、摄像头帧、人脸治理、微服务与商城交付 |