@microi.net/cli 5.5.8 → 5.6.0

package/skills/dos-orm/references/api-reference.md

@@ -1,229 +1,229 @@
-# Dos.ORM API 参考
-
-## 数据库 Provider
-
-| DatabaseType | Provider |
-|---|---|
-| `SqlServer` | SQL Server 2000 |
-| `SqlServer9` | SQL Server 2005+ |
-| `MySql` | MySQL |
-| `Oracle` | Oracle |
-| `PostgreSql` | PostgreSQL |
-| `DaMeng` | 达梦 |
-| `KingBase` | 人大金仓 |
-| `Sqlite3` | SQLite |
-| `MsAccess` | Access |
-
-兼容协议数据库仍需目标库实测，不能只凭协议名称判定所有 DDL、分页和 BulkCopy 一致。
-
-默认会话入口是 `DbSession.Default`；多数据库、读写分离和分片场景使用明确的
-`DbSession` 实例，避免把默认连接误用于其它租户或数据库。
-
-## 实体
-
-```csharp
-[TableName("sys_user")]
-public class SysUser : Entity
-{
-    public string Id { get; set; }
-    public string Account { get; set; }
-    public DateTime CreateTime { get; set; }
-
-    public override Field[] GetFields() => new[] { _.Id, _.Account, _.CreateTime };
-    public override object[] GetValues() => new object[] { Id, Account, CreateTime };
-    public override Field GetIdentityField() => _.Id;
-
-    public sealed class _
-    {
-        public static readonly Field Id = new Field("Id", "sys_user");
-        public static readonly Field Account = new Field("Account", "sys_user");
-        public static readonly Field CreateTime = new Field("CreateTime", "sys_user");
-    }
-}
-```
-
-`Entity.GetFields()` 的字段顺序也是批量写入和 CodeFirst 映射依据；实体声明、
-字段数组与数据库列变更必须同步。
-
-## 查询链
-
-| API | 作用 |
-|---|---|
-| `From<T>()` / `From("table")` | 查询入口 |
-| `Where(predicate)` / `Where(WhereClip)` | 条件 |
-| `OrderBy` / `OrderByDescending` | 排序 |
-| `GroupBy` / `Having` | 分组 |
-| `Select` / `AddSelect` | 选择字段 |
-| `Distinct` / `Top` / `Page` | 去重、Top、分页 |
-| `InnerJoin/LeftJoin/RightJoin/CrossJoin/FullJoin` | Join |
-| `Union/UnionAll` | 集合联合 |
-| `SetCacheTimeOut` / `Refresh` | 查询缓存/绕过缓存 |
-| `ToList/ToListAsync` | 列表 |
-| `ToFirst/ToFirstAsync` | 第一条或 null |
-| `ToFirstDefault` | 第一条或 new 实体 |
-| `ToScalar/ToScalarAsync` | 标量 |
-| `ToDataReader` / `ToDataTable/ToDataTableAsync` | Reader/DataTable |
-| `ToEnumerable` | 流式枚举 |
-| `Count/CountAsync` | 计数 |
-| `ExecuteNonQuery/ExecuteNonQueryAsync` | 非查询 |
-
-查询缓存入口的完整成员名是 `FromSection.SetCacheTimeOut`。缓存 Key 包含 SQL
-与参数值，但写后失效、租户隔离和多节点一致性仍由业务负责。
-
-```csharp
-var users = await dbSession.From<SysUser>()
-    .Where(u => u.Account == account)
-    .OrderByDescending(u => u.CreateTime)
-    .Page(20, 1)
-    .ToListAsync();
-```
-
-## WhereClip
-
-```csharp
-var where = new Where<SysUser>();
-where.And(u => u.Status == 1);
-if (!string.IsNullOrWhiteSpace(keyword))
-    where.And(u => u.Name.Like(keyword));
-if (deptIds?.Any() == true)
-    where.And(u => u.DeptId.In(deptIds));
-
-var list = dbSession.From<SysUser>()
-    .Where(where.ToWhereClip())
-    .ToList();
-```
-
-支持比较、`Like/NotLike/StartsWith/EndsWith`、`In/NotIn` 和 NULL。
-
-## 原生 SQL
-
-```csharp
-var users = dbSession
-    .FromSql("SELECT Id,Account FROM sys_user WHERE Status=@p0")
-    .AddInParameter("@p0", 1)
-    .ToList<SysUser>();
-```
-
-动态值只走参数；动态标识符先从固定白名单映射。
-Provider 的标识符替换最终由 `DataUtils.FormatSQL` 完成；不要绕过该步骤手工
-拼接用户输入的表名或字段名。
-
-## 写入
-
-```csharp
-dbSession.Insert(entity);
-dbSession.Insert(list);
-dbSession.Update<SysUser>(u => u.Status, 0, u => u.Id == id);
-dbSession.Delete<SysUser>(u => u.Id == id);
-```
-
-批量：
-
-```csharp
-var affected = dbSession.BulkInsert(list, batchSize: 5000, bulkCopyTimeoutSeconds: 600);
-var affectedAsync = await dbSession.BulkInsertAsync(list, batchSize: 5000, ct: token);
-```
-
-原生优选：
-
-- SQL Server：SqlBulkCopy
-- MySQL：MySqlBulkCopy
-- PostgreSQL/KingBase：Binary COPY
-- Oracle/达梦/SQLite/Access：多行参数化 INSERT 回退
-
-批大小 5000 只是起点；按行宽、索引、日志、网络和数据库负载测量。
-
-## Upsert
-
-```csharp
-dbSession.Upsert(user, SysUser._.Account);
-await dbSession.UpsertAsync(
-    user,
-    ct: token,
-    conflictFields: new[] { SysUser._.Account });
-```
-
-各 Provider 使用 `ON DUPLICATE KEY`、`ON CONFLICT`、`MERGE` 或更新后插入回退。
-冲突字段必须有数据库唯一约束。
-
-## SqlFunc 与子查询
-
-`SqlFunc` 提供 `SqlFunc.IfNull`、`SqlFunc.IIF`、`SqlFunc.Length`、
-`SqlFunc.Substring`、`SqlFunc.Now`、`SqlFunc.DateDiff`、
-`SqlFunc.JsonValue`、`SqlFunc.Concat`、`SqlFunc.Upper`、`SqlFunc.Lower`、
-`SqlFunc.Trim`、`SqlFunc.Abs`、`SqlFunc.Round`、`SqlFunc.Count`、
-`SqlFunc.Sum`、`SqlFunc.Avg`、`SqlFunc.Min`、`SqlFunc.Max` 的 Provider 方言。
-
-`SqlSubQuery` 提供 `SqlSubQuery.Exists`、`SqlSubQuery.NotExists`、
-`SqlSubQuery.In`、`SqlSubQuery.NotIn`、`SqlSubQuery.Scalar` 和
-`SqlSubQuery.Count`。
-返回的是 SQL 片段，数据值仍要参数化。
-
-## 导航属性
-
-`[Navigate]` 支持 `NavigateType.OneToOne`、`NavigateType.OneToMany`、
-`NavigateType.ManyToMany`；加载入口：
-
-- `IncludeOne`
-- `IncludeMany`
-- `IncludeManyToMany`
-
-实现使用批量 IN，避免逐行 N+1。仍要限制主结果规模。
-
-## CodeFirst
-
-```csharp
-dbSession.CreateTable<SysUser>();
-dbSession.SyncSchema(typeof(SysUser), typeof(Order));
-var exists = dbSession.TableExists("sys_user");
-```
-
-`CreateTable<T>(dropIfExists: true)` 是破坏性操作，只可在明确授权的隔离环境使用。
-实体索引可用 `[Index]` 声明；Microi 低代码业务表的运行时索引仍必须走 Manifest/MCP。
-
-## 读写分离
-
-```csharp
-var router = new ReadWriteRouter(master);
-router.AddSlave(slave1, weight: 1);
-router.AddSlave(slave2, weight: 2);
-
-var read = router.GetReadSession();
-var write = router.GetWriteSession();
-
-using (router.ForceMaster())
-{
-    var latest = router.GetReadSession().From<SysUser>().ToList();
-}
-```
-
-支持加权轮询、摘除和回退。事务与读自己刚写的数据必须读主。
-
-## 分库分表
-
-表名路由：
-
-- `ShardingRouter.MonthlyTable`
-- `ShardingRouter.HashModTable`
-- `ShardingRouter.ModTable`
-
-数据库路由：
-
-- `DbShardingRouter.AddNode`
-- `RouteByHash`
-- `AllNodes`
-
-稳定 Hash 使用 FNV-1a。跨分片事务、全局唯一键、分页排序和聚合需要业务层明确设计。
-
-## 监控与缓存
-
-```csharp
-Dos.ORM.Section.SlowSqlThresholdMs = 1000;
-Dos.ORM.Section.OnSlowSql = (cmd, elapsed, operation) =>
-{
-    // 记录脱敏 SQL 模板、耗时和关联 Id；不要记录密钥参数
-};
-```
-
-反序列化器、实体元数据和字段名缓存是进程内优化，允许节点重启后重建；
-不能作为跨节点业务事实。查询缓存使用滑动过期，写后按业务失效。
+# Dos.ORM API 参考
+
+## 数据库 Provider
+
+| DatabaseType | Provider |
+|---|---|
+| `SqlServer` | SQL Server 2000 |
+| `SqlServer9` | SQL Server 2005+ |
+| `MySql` | MySQL |
+| `Oracle` | Oracle |
+| `PostgreSql` | PostgreSQL |
+| `DaMeng` | 达梦 |
+| `KingBase` | 人大金仓 |
+| `Sqlite3` | SQLite |
+| `MsAccess` | Access |
+
+兼容协议数据库仍需目标库实测，不能只凭协议名称判定所有 DDL、分页和 BulkCopy 一致。
+
+默认会话入口是 `DbSession.Default`；多数据库、读写分离和分片场景使用明确的
+`DbSession` 实例，避免把默认连接误用于其它租户或数据库。
+
+## 实体
+
+```csharp
+[TableName("sys_user")]
+public class SysUser : Entity
+{
+    public string Id { get; set; }
+    public string Account { get; set; }
+    public DateTime CreateTime { get; set; }
+
+    public override Field[] GetFields() => new[] { _.Id, _.Account, _.CreateTime };
+    public override object[] GetValues() => new object[] { Id, Account, CreateTime };
+    public override Field GetIdentityField() => _.Id;
+
+    public sealed class _
+    {
+        public static readonly Field Id = new Field("Id", "sys_user");
+        public static readonly Field Account = new Field("Account", "sys_user");
+        public static readonly Field CreateTime = new Field("CreateTime", "sys_user");
+    }
+}
+```
+
+`Entity.GetFields()` 的字段顺序也是批量写入和 CodeFirst 映射依据；实体声明、
+字段数组与数据库列变更必须同步。
+
+## 查询链
+
+| API | 作用 |
+|---|---|
+| `From<T>()` / `From("table")` | 查询入口 |
+| `Where(predicate)` / `Where(WhereClip)` | 条件 |
+| `OrderBy` / `OrderByDescending` | 排序 |
+| `GroupBy` / `Having` | 分组 |
+| `Select` / `AddSelect` | 选择字段 |
+| `Distinct` / `Top` / `Page` | 去重、Top、分页 |
+| `InnerJoin/LeftJoin/RightJoin/CrossJoin/FullJoin` | Join |
+| `Union/UnionAll` | 集合联合 |
+| `SetCacheTimeOut` / `Refresh` | 查询缓存/绕过缓存 |
+| `ToList/ToListAsync` | 列表 |
+| `ToFirst/ToFirstAsync` | 第一条或 null |
+| `ToFirstDefault` | 第一条或 new 实体 |
+| `ToScalar/ToScalarAsync` | 标量 |
+| `ToDataReader` / `ToDataTable/ToDataTableAsync` | Reader/DataTable |
+| `ToEnumerable` | 流式枚举 |
+| `Count/CountAsync` | 计数 |
+| `ExecuteNonQuery/ExecuteNonQueryAsync` | 非查询 |
+
+查询缓存入口的完整成员名是 `FromSection.SetCacheTimeOut`。缓存 Key 包含 SQL
+与参数值，但写后失效、租户隔离和多节点一致性仍由业务负责。
+
+```csharp
+var users = await dbSession.From<SysUser>()
+    .Where(u => u.Account == account)
+    .OrderByDescending(u => u.CreateTime)
+    .Page(20, 1)
+    .ToListAsync();
+```
+
+## WhereClip
+
+```csharp
+var where = new Where<SysUser>();
+where.And(u => u.Status == 1);
+if (!string.IsNullOrWhiteSpace(keyword))
+    where.And(u => u.Name.Like(keyword));
+if (deptIds?.Any() == true)
+    where.And(u => u.DeptId.In(deptIds));
+
+var list = dbSession.From<SysUser>()
+    .Where(where.ToWhereClip())
+    .ToList();
+```
+
+支持比较、`Like/NotLike/StartsWith/EndsWith`、`In/NotIn` 和 NULL。
+
+## 原生 SQL
+
+```csharp
+var users = dbSession
+    .FromSql("SELECT Id,Account FROM sys_user WHERE Status=@p0")
+    .AddInParameter("@p0", 1)
+    .ToList<SysUser>();
+```
+
+动态值只走参数；动态标识符先从固定白名单映射。
+Provider 的标识符替换最终由 `DataUtils.FormatSQL` 完成；不要绕过该步骤手工
+拼接用户输入的表名或字段名。
+
+## 写入
+
+```csharp
+dbSession.Insert(entity);
+dbSession.Insert(list);
+dbSession.Update<SysUser>(u => u.Status, 0, u => u.Id == id);
+dbSession.Delete<SysUser>(u => u.Id == id);
+```
+
+批量：
+
+```csharp
+var affected = dbSession.BulkInsert(list, batchSize: 5000, bulkCopyTimeoutSeconds: 600);
+var affectedAsync = await dbSession.BulkInsertAsync(list, batchSize: 5000, ct: token);
+```
+
+原生优选：
+
+- SQL Server：SqlBulkCopy
+- MySQL：MySqlBulkCopy
+- PostgreSQL/KingBase：Binary COPY
+- Oracle/达梦/SQLite/Access：多行参数化 INSERT 回退
+
+批大小 5000 只是起点；按行宽、索引、日志、网络和数据库负载测量。
+
+## Upsert
+
+```csharp
+dbSession.Upsert(user, SysUser._.Account);
+await dbSession.UpsertAsync(
+    user,
+    ct: token,
+    conflictFields: new[] { SysUser._.Account });
+```
+
+各 Provider 使用 `ON DUPLICATE KEY`、`ON CONFLICT`、`MERGE` 或更新后插入回退。
+冲突字段必须有数据库唯一约束。
+
+## SqlFunc 与子查询
+
+`SqlFunc` 提供 `SqlFunc.IfNull`、`SqlFunc.IIF`、`SqlFunc.Length`、
+`SqlFunc.Substring`、`SqlFunc.Now`、`SqlFunc.DateDiff`、
+`SqlFunc.JsonValue`、`SqlFunc.Concat`、`SqlFunc.Upper`、`SqlFunc.Lower`、
+`SqlFunc.Trim`、`SqlFunc.Abs`、`SqlFunc.Round`、`SqlFunc.Count`、
+`SqlFunc.Sum`、`SqlFunc.Avg`、`SqlFunc.Min`、`SqlFunc.Max` 的 Provider 方言。
+
+`SqlSubQuery` 提供 `SqlSubQuery.Exists`、`SqlSubQuery.NotExists`、
+`SqlSubQuery.In`、`SqlSubQuery.NotIn`、`SqlSubQuery.Scalar` 和
+`SqlSubQuery.Count`。
+返回的是 SQL 片段，数据值仍要参数化。
+
+## 导航属性
+
+`[Navigate]` 支持 `NavigateType.OneToOne`、`NavigateType.OneToMany`、
+`NavigateType.ManyToMany`；加载入口：
+
+- `IncludeOne`
+- `IncludeMany`
+- `IncludeManyToMany`
+
+实现使用批量 IN，避免逐行 N+1。仍要限制主结果规模。
+
+## CodeFirst
+
+```csharp
+dbSession.CreateTable<SysUser>();
+dbSession.SyncSchema(typeof(SysUser), typeof(Order));
+var exists = dbSession.TableExists("sys_user");
+```
+
+`CreateTable<T>(dropIfExists: true)` 是破坏性操作，只可在明确授权的隔离环境使用。
+实体索引可用 `[Index]` 声明；Microi 低代码业务表的运行时索引仍必须走 Manifest/MCP。
+
+## 读写分离
+
+```csharp
+var router = new ReadWriteRouter(master);
+router.AddSlave(slave1, weight: 1);
+router.AddSlave(slave2, weight: 2);
+
+var read = router.GetReadSession();
+var write = router.GetWriteSession();
+
+using (router.ForceMaster())
+{
+    var latest = router.GetReadSession().From<SysUser>().ToList();
+}
+```
+
+支持加权轮询、摘除和回退。事务与读自己刚写的数据必须读主。
+
+## 分库分表
+
+表名路由：
+
+- `ShardingRouter.MonthlyTable`
+- `ShardingRouter.HashModTable`
+- `ShardingRouter.ModTable`
+
+数据库路由：
+
+- `DbShardingRouter.AddNode`
+- `RouteByHash`
+- `AllNodes`
+
+稳定 Hash 使用 FNV-1a。跨分片事务、全局唯一键、分页排序和聚合需要业务层明确设计。
+
+## 监控与缓存
+
+```csharp
+Dos.ORM.Section.SlowSqlThresholdMs = 1000;
+Dos.ORM.Section.OnSlowSql = (cmd, elapsed, operation) =>
+{
+    // 记录脱敏 SQL 模板、耗时和关联 Id；不要记录密钥参数
+};
+```
+
+反序列化器、实体元数据和字段名缓存是进程内优化，允许节点重启后重建；
+不能作为跨节点业务事实。查询缓存使用滑动过期，写后按业务失效。

package/skills/email-engine/SKILL.md

@@ -1,80 +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 权限、连接、实际收件、附件字节、重复发送、
-自动同步、宿主表单、商城包与官网真实截图。
+---
+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 权限、连接、实际收件、附件字节、重复发送、
+自动同步、宿主表单、商城包与官网真实截图。