@microi.net/cli 4.6.2

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

@@ -0,0 +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；不要记录密钥参数
+};
+```
+
+反序列化器、实体元数据和字段名缓存是进程内优化，允许节点重启后重建；
+不能作为跨节点业务事实。查询缓存使用滑动过期，写后按业务失效。

package/dist/microi.skills/job-engine/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: job-engine
+description: Microi 定时任务与可靠后台任务规范。用于配置 Microi.Job、Quartz 和接口引擎任务，设计多节点租约、幂等、重试、停机排空、恢复、进度与验收。
+---
+
+# Microi Job 定时与后台任务
+
+## 何时使用
+
+- 周期扫描、补偿、归档：`Microi.Job`
+- 用户触发的长耗时安装/导入/同步：菜单后台任务
+- 可靠跨服务异步：MQ + outbox/inbox
+- 请求内等待外部结果：`await`，不要创建后台线程
+
+禁止用后端 `setTimeout`、`Task.Run`、`static bool` 或本机定时器承载可靠业务。
+
+## 平台对象
+
+Quartz 管理能力包含查询、添加、更新、暂停、恢复、删除任务。任务配置、接口引擎代码和执行日志属于控制面，只允许 `Level >= 9999` 维护；业务用户只能触发明确授权的后台动作。
+
+任务通常调用稳定的 `ApiEngineKey`。接口引擎返回 `Code=1` 只表示本次执行成功，不代表调度系统可忽略重试与幂等。
+
+## 多节点设计
+
+每个任务必须同时具备：
+
+1. 分布式租约：Key 至少含 `OsClient + JobKey + 计划时间/业务分片`，有唯一持有者、TTL、续租和仅持有者释放。
+2. 业务幂等：稳定 `IdempotencyKey/EventId`、数据库唯一约束或条件状态迁移。
+3. 可恢复状态：待处理、处理中、成功、失败、下次重试时间写共享数据库/Redis/MQ。
+4. fencing：锁可能过期的资金、库存等任务使用版本号/条件更新拒绝旧持有者写入。
+
+锁只能减少并发，不能替代幂等。
+
+## 任务骨架
+
+```js
+// 接口引擎由 Job 调用；JobRunId/FireTime 由调度层传入
+var idempotencyKey = String(V8.Param.JobRunId || '');
+if (!idempotencyKey) return { Code: 0, Msg: '缺少 JobRunId' };
+
+// 推荐调用专用后端能力，以唯一约束抢占执行记录
+var claim = V8.FormEngine.AddFormData('job_execution', {
+  JobKey: 'daily_order_summary',
+  IdempotencyKey: idempotencyKey,
+  Status: 'Running'
+});
+if (claim.Code !== 1) return { Code: 1, Msg: '已执行或正在执行' };
+
+// 分页处理；每个业务副作用仍需自己的幂等键
+return { Code: 1, Data: { IdempotencyKey: idempotencyKey } };
+```
+
+实际项目优先由数据库唯一索引和接口引擎事务完成抢占，不能仅用“先查再新增”。该唯一索引必须声明在 Manifest `tables[].indexes`，并用 `microi_create_table_index` 创建、`microi_get_table_indexes` 回读；禁止在 Job/V8 内手写 `CREATE INDEX`。任务扫描还应按实际 SQL 建立 `(OsClient, Status, NextRetryTime)` 或 `(OsClient, JobKey, ScheduleTime)` 等组合索引。
+
+## 失败、重试与停机
+
+- 失败记录错误分类、重试次数和 `NextRetryTime`，采用有上限退避；永久错误进入人工处理。
+- 外部调用设置超时；无法确认对方是否成功时用业务幂等号查询，不盲目重发。
+- 服务停机先停止接单，再在有限宽限期排空或持久化；重启扫描未完成任务。
+- 若要求 `kill -9` 前也零丢失，业务成功响应前必须获得共享 outbox/MQ/WAL 持久化确认。
+
+## 后台按钮
+
+满足任一条件即按后台任务设计：预计超过 2 分钟、500 条以上、1000 个以上扇出子操作、100 次以上外部调用、总量未知且可能持续运行，或安装/初始化/批量导入/批量生成/全量同步/迁移/备份。预计超过 10 分钟时，仅设置 `RunBackground=true` 仍不够，必须按 checkpoint 分片，每片独立事务。
+
+菜单按钮设置 `RunBackground/BackgroundTask/IsBackgroundTask=true` 和 `ApiEngineKey`，并配置 `BackgroundTaskOptions`：
+
+- `IdempotencyKey` 或 `IdempotencyKeyFields`：跨节点、重试和重复点击保持稳定。
+- `ConcurrencyKey`：DDL、安装等不能并行的工作使用同一租约组。
+- `BusinessTable + BusinessId`：关联业务记录。
+- `BusinessStatusField + BusinessTaskIdField`：业务记录至少标记“后台处理中”和任务 Id；推荐再配置 `BusinessProgressField + BusinessEtaField`。
+
+按钮提交成功后，平台前端会通过当前用户的 `V8.FormEngine` 权限把业务记录标记为“后台处理中”并写入任务 Id；后台服务不能直接相信客户端字段名而绕过表单权限。接口引擎仍必须在最后一片或异常补偿中把该业务记录改成“已完成 / 失败 / 已取消”，并保留任务 Id 供详情追溯：
+
+```js
+var task = V8.Param._BackgroundTask || {};
+if (task.BusinessTable && task.BusinessId) {
+  var patch = { Id: task.BusinessId };
+  patch[task.BusinessStatusField] = '后台处理中';
+  patch[task.BusinessTaskIdField] = task.Id;
+  V8.FormEngine.UptFormData(task.BusinessTable, patch);
+}
+```
+
+不得让通用后台服务按客户端传入的任意表名/字段名直接写库；需要脱离前端自动标记的专用任务，应在受控接口引擎中使用固定表名和固定字段名。
+
+接口通过 `V8.Method.UpdateBackgroundTask({Current,Total,Msg,Log})` 上报已提交的真实工作量，`Log`/`AppendLog` 用于追加任务详情（不得包含密码、Token 或密钥）。平台按实际吞吐计算 `EstimatedEndTime`；总量未知时不传 `Total`，通知中心显示“不定进度/估算中”，禁止用固定 10%、阶段占位或计时器伪造进度。失败和取消停在最后真实进度，不得显示 100%。
+
+分片接口在仍有后续工作时返回：
+
+```js
+return {
+  Code: 1,
+  Data: {
+    BackgroundTask: {
+      HasMore: true,
+      Checkpoint: { LastId: lastId },
+      Current: committedCount,
+      Total: totalCount,
+      NextDelaySeconds: 1,
+      Msg: '本批已提交，等待下一批'
+    }
+  }
+};
+```
+
+最后一片返回普通 `Code:1`。每个业务副作用还要用 `_BackgroundTaskIdempotencyKey + 业务行Id` 建唯一约束；`_BackgroundTaskFencingToken` 用于拒绝租约过期旧执行者的写入。
+
+## 长任务的 Jint 预算
+
+后台 Worker 最终仍调用接口引擎，因此每个执行片段都受 `Timeout`、`MaxStatements`、单层累计分配预算、根调用树累计分配预算、JavaScript 递归和接口嵌套深度限制。`LimitMemory=2048` 表示当前片段累计分配了多少托管字节，不表示实时占用或预留 2GB 物理内存。
+
+- 总任务运行 10 分钟、30 分钟或数小时是允许的；单个连续 Jint 调用不应承担全部时长。
+- 每片在预算内提交事务并返回 `HasMore + Checkpoint`；Worker 重新入队后会创建新的 Jint Engine，新片重新获得超时、语句和累计分配预算。
+- `V8.ApiEngine.Run` 的多层编排可以保留。新版父子单层分配隔离后，子接口不会被所有祖先重复计费，但根调用树仍有整体预算；循环调用由独立的嵌套深度上限终止。
+- 捕获失败时读取 `DataAppend.V8Limit.Code`。内存/调用树/语句/超时分别缩小批次，递归错误修复函数递归，嵌套深度错误检查循环编排；不要统一归因于服务器资源不足。
+- 可记录 `V8.Limits` 到脱敏诊断日志，但不要在每条业务数据上重复输出。
+- 若分片提交会破坏“全部成功或全部回滚”的业务原子性，可为受控接口开启 `sys_apiengine.V8Unlimited`，并继续使用后台任务承载进度。该模式仍受进程常驻内存、取消、并发、接口嵌套深度和数据库限制；必须评估长事务锁/日志/回滚，保留幂等重试，并为每个下游接口和表后端事件分别配置，不能由根接口自动继承。
+
+## MCP 工作流
+
+1. 读取表、接口引擎和现有任务。
+2. 先设计幂等键、状态机、租约和补偿。
+3. `microi_save_job` 保存任务，写入需明确确认。
+4. 回读任务 cron、启用状态、Key、接口引擎。
+5. 两节点同时触发、重复投递、持有者中止、Redis 故障和滚动升级验收。
+
+## 验收清单
+
+- [ ] 任务配置仅管理员可改
+- [ ] 两节点同一时刻触发，业务副作用仅一次
+- [ ] 重复消息/请求不会重复扣减或生成流水
+- [ ] 锁持有者退出后可恢复，无永久死锁
+- [ ] 失败可重试、可追踪、可人工补偿
+- [ ] 新旧版本滚动共存，状态和消息合约兼容
+- [ ] 未知总量不显示假百分比；已知总量由 Current/Total 唯一推导
+- [ ] ETA 来自真实吞吐，样本不足时明确显示“估算中”
+- [ ] 业务记录可通过 BackgroundTaskId 跳转通知中心排查
+- [ ] 超过 10 分钟的任务有 checkpoint，重启后从最后已提交批次恢复
+- [ ] 单片低于超时/语句/累计分配预算，任务总时长不依赖放大单次接口上限
+- [ ] 嵌套接口没有循环调用，且错误日志包含结构化 `V8Limit` 分类和调用路径

package/dist/microi.skills/job-engine/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "任务引擎"
+  short_description: "设计可幂等、可恢复并适用于多节点滚动部署的定时与后台任务"
+  default_prompt: "使用 $job-engine 设计并验收当前 Microi 定时或后台任务。"

package/dist/microi.skills/message-notification/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: message-notification
+description: 设计、实现、迁移和验收 Microi 多通道消息通知。用于涉及 wx_tpl_msg、mic_msgset、mic_msg_event_log、微信公众号或服务号模板消息、小程序跳转、短信、邮件、平台内部通知、V8.Notification、通知中心 SignalR、msg_event、消息幂等或通知应用商城交付的任务。
+---
+
+# Microi 消息通知
+
+## 目标
+
+交付“配置可维护、事件先持久化、实时可降级、多节点不重复、租户不串线”的通知能力。支持微信公众号/服务号模板消息、短信、邮件和平台内部通知；小程序是公众号模板消息的跳转目标，不是独立的公众号发送主体。
+
+## 开始前
+
+1. 读取工作区 `AGENTS.md`，并按任务同时读取 `microi-db-schema`、`v8-api-config`、`v8-frontend-events`、`microi-client-frontend`；涉及商城时再读 `app-store`，涉及浏览器时再读 `playwright-e2e`。
+2. 用用户点名的 MCP 连接读取实时结构，不以本地字典替代远端事实。至少读取 `wx_tpl_msg`、`mic_msgset`、`mic_msg_event_log`，按需读取 `wx_mp`、`wx_mini_program`、`sys_menu` 和接口引擎。
+3. 多租户比较按字段语义合并：保留双方新增字段、控件、说明和数据源，再把并集同步到双方。每次写入后重新读取字段、物理索引和接口源码。
+4. 只有用户明确要求时才复制渠道配置。复制微信公众号/小程序密钥时不在输出中打印秘密；模板、发送主体和小程序跳转引用必须一起回读验证。
+
+## 核心模型
+
+- `mic_msgset`：通知策略。`Key` 是稳定业务键，`Type` 是多选渠道，`ChannelApiEngineMap` 配置短信、邮件或自定义渠道适配器。
+- `wx_tpl_msg`：微信公众号/服务号模板。`WxMpId` 决定发送主体；`MiniProgramId`、`MiniProgramAppId`、`MiniProgramPagePath` 仅表示点击模板消息后跳入的小程序。
+- `mic_msg_event_log`：每位接收人、每个渠道的权威事件记录。至少包含稳定 `EventId`、`ChannelType`、`ReceiverUserId`、标题、内容、链接、Payload、已读状态和结果。
+- 唯一约束：`EventId + ChannelType + ReceiverUserId`。租户使用独立业务库时表内无需虚构 `OsClient` 字段；共享库模型则必须把租户键加入唯一约束。
+
+完整字段、接口和可靠性契约见 [references/contracts.md](references/contracts.md)。
+
+## 实现流程
+
+### 1. 合并结构
+
+对两个租户分别读取字段列表，按 `Name` 生成差异表。新增缺失字段后刷新缓存，并回读：
+
+- `mic_msgset.Type` 包含 `微信公众号模板消息`、`短信`、`邮件`、`平台内部`；
+- `mic_msgset.ChannelApiEngineMap` 为 JSON 对象；
+- `wx_tpl_msg` 同时有 `WxMpId/WxMpName` 和小程序跳转字段；
+- `mic_msg_event_log` 有完整的事件、接收人、渠道、内容和已读字段；
+- 业务唯一索引与常用未读查询索引存在。
+
+不要用一次性 SQL 修某个租户而跳过通用表单/资源升级路径。应用包与平台升级资源必须携带同一结构。
+
+### 2. 配置发送策略
+
+`mic_msgset.Key` 对业务长期稳定。接收人可以来自固定用户、角色和调用参数，必须去重并限制扇出。渠道适配器统一接收：
+
+```js
+{
+  EventId: '业务稳定幂等键',
+  ChannelType: '短信',
+  User: { Id: '...', Phone: '...', Email: '...', WxOpenId: '...' },
+  Title: '审批提醒',
+  Content: '您有一条待审批记录',
+  LinkUrl: '/#/approval/123',
+  Payload: { BusinessId: '123' }
+}
+```
+
+适配器必须按 `EventId` 幂等。不要把密钥放进 `ChannelApiEngineMap` 或 Payload；密钥保存在对应渠道配置表或租户安全配置中。
+
+### 3. 后端发送
+
+业务代码优先调用 `msg_event`，由它读取策略、解析接收人、原子登记日志后分发。调用方在重试时保持同一个 `EventId`：
+
+```js
+return V8.ApiEngine.Run('msg_event', {
+  MsgKey: 'order_wait_approve',
+  EventId: 'order-wait-approve-' + V8.Param.OrderId,
+  ReceiverUserIds: [V8.Param.ApproverId],
+  Content: '订单 ' + V8.Param.OrderNo + ' 等待审批',
+  LinkUrl: '/#/orders/detail?id=' + V8.Param.OrderId,
+  Payload: { OrderId: V8.Param.OrderId }
+}, V8.DbTrans);
+```
+
+`V8.Notification.Send` 是宿主的“平台内部实时提示”原语。它不替代日志 claim，通常只由 `msg_event` 在日志成功登记后调用。事务存在时，推送在提交后进行有界等待；回滚不得推送。
+
+### 4. 前端通知中心
+
+前端 V8 使用 `V8.Notification.List` 获取当前登录用户的权威快照，使用 `MarkRead` 标记本人通知。SignalR 固定事件 `ReceivePlatformNotification` 只用于低延迟刷新：客户端按 `Id/EventId` 去重，收到后仍以列表接口回读为准。
+
+```js
+await V8.Notification.Send('order_wait_approve', {
+  EventId: 'order-wait-approve-' + V8.Form.Id,
+  ReceiverUserIds: [V8.Form.ApproverId],
+  Content: '订单等待审批'
+});
+
+var result = await V8.Notification.List({ PageIndex: 1, PageSize: 20 });
+await V8.Notification.MarkRead(result.Data[0].Id);
+await V8.Notification.MarkRead({ All: true });
+```
+
+列表和已读接口必须以 `V8.CurrentUser.Id` 作为服务端过滤条件，不能信任客户端传入的用户 Id。外链只允许站内路径、锚点或 `http/https`。
+
+### 5. 多节点可靠性
+
+- 数据库日志是事实源，SignalR 是可丢失提示；Redis backplane 使任一节点能通知连接在其它节点的用户。
+- “先查询再新增”不能防并发；依赖唯一索引抢占。同一事件重复投递只能产生一份 `EventId + 渠道 + 接收人` 记录。
+- 外部供应商在“已发送但响应丢失”时无法凭本地状态保证恰好一次。适配器必须把 `EventId` 传给支持幂等的供应商；不支持时进入可审计的人工确认/重试状态。
+- 发布中新旧版本短暂共存，先扩展字段与接口，再发布读写代码，最后才收缩旧字段。
+
+## 应用商城交付
+
+“消息通知”应用包至少包含三张业务表、相关菜单、`msg_event`、`msg_internal_list`、`msg_internal_mark_read` 和必要索引。包内不得包含真实公众号 Token/AppSecret、用户接收人、OpenId、历史发送记录或租户专属 URL。先 `ValidateOnly`，再在获准的目标租户安装并回读；结构校验不能替代真实安装验收。
+
+## 最低验收
+
+1. 两个 MCP 租户的字段、数据源、物理索引和三段接口代码回读一致。
+2. 重复 `EventId`、重复接收人和两个 API 节点并发发送，持久副作用仅一次。
+3. 事务回滚不推送；提交后在线用户即时收到，离线/SignalR/Redis 故障后登录仍能回读。
+4. 用户只能查询和标记自己的通知；危险链接、超长正文、跨租户接收人和匿名调用被拒绝。
+5. 公众号/服务号发送主体与小程序跳转目标分别验证，不把 `MiniProgramAppId` 当作模板发送主体。
+6. 源码定向测试、后端编译、远端 MCP 回读、真实浏览器点击和商城安装/校验分别报告；未执行的生产发布不得写成已上线。

package/dist/microi.skills/message-notification/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Microi 消息通知"
+  short_description: "设计、实现并验收租户安全的多通道与平台内部实时消息通知"
+  brand_color: "#409EFF"
+  default_prompt: "Use $message-notification to design and verify a tenant-safe Microi notification flow."
+

package/dist/microi.skills/message-notification/references/contracts.md

@@ -0,0 +1,99 @@
+# 消息通知契约
+
+## 表结构并集
+
+### `mic_msgset`
+
+| 字段 | 用途 |
+|---|---|
+| `Key` | 稳定业务键，租户内唯一 |
+| `Title` | 配置名称/默认标题 |
+| `IsEnable` | 总开关 |
+| `Type` | 多选渠道：微信公众号模板消息、短信、邮件、平台内部 |
+| `Receivers` | 固定接收用户 JSON |
+| `ReceiversRoles` | 固定接收角色 JSON |
+| `WxTplMsgId` | 公众号模板配置 Id |
+| `ChannelApiEngineMap` | 渠道到适配器接口引擎 Key 的 JSON 映射 |
+| `TenantId/TenantName` | 业务层租户信息；不能替代 MCP 的 OsClient 边界 |
+| `TableChild99` | 兼容已有子表配置 |
+
+### `wx_tpl_msg`
+
+| 字段 | 用途 |
+|---|---|
+| `Key/Title/TemplateId/Content/Remark/LinkUrl` | 模板业务键、标题、微信模板 Id、内容与普通跳转 |
+| `WxMpId/WxMpName` | 发送模板消息的公众号或服务号；关联 `wx_mp` |
+| `MiniProgramId/MiniProgramName` | 可选小程序配置；关联 `wx_mini_program` |
+| `MiniProgramAppId/MiniProgramPagePath` | 模板消息的可选小程序跳转目标 |
+
+公众号和服务号都属于微信公众帐号，由 `wx_mp` 保存发送凭据。小程序由 `wx_mini_program` 保存，不能使用小程序 AppId 调用公众号模板消息发送接口。
+
+### `mic_msg_event_log`
+
+| 字段 | 用途 |
+|---|---|
+| `EventId` | 调用方稳定幂等键 |
+| `MsgEventId` | 关联的消息设置 Id |
+| `ChannelType` | 本条日志对应的渠道 |
+| `ReceiverUserId` | 单一接收用户 Id |
+| `Receivers` | 接收人安全快照 JSON |
+| `Title/MsgContent/LinkUrl/Payload` | 通知展示快照 |
+| `IsRead/ReadTime` | 平台内部通知已读状态 |
+| `IsSuccess/MsgResult` | 分发状态和经过脱敏的结果 |
+
+索引基线：
+
+- 唯一：`EventId, ChannelType, ReceiverUserId`；共享表模型再前置 `OsClient`。
+- 普通：`ReceiverUserId, ChannelType, IsRead, CreateTime`。
+- `mic_msgset.Key`、`wx_tpl_msg.Key` 在租户业务库内唯一。
+
+## V8 接口
+
+### `msg_event`
+
+输入：
+
+```js
+{
+  MsgKey: '策略 Key',
+  EventId: '稳定幂等键',
+  ReceiverUserId: '可选单用户',
+  ReceiverUserIds: ['可选用户数组'],
+  Title: '可覆盖配置标题',
+  Content: '正文',
+  LinkUrl: '/#/route',
+  Payload: { BusinessId: '...' }
+}
+```
+
+处理顺序：校验当前租户与登录上下文 → 读取启用策略 → 合并固定用户、角色用户和参数用户 → 去重/限流 → 按接收人和渠道插入日志 claim → 仅对 claim 成功项分发 → 汇总成功、失败、重复。出现部分失败时仍要提交已经产生的日志与外部副作用，并把失败逐项返回，不能为了漂亮的 `Code` 回滚成功事实。
+
+### `msg_internal_list`
+
+- 仅返回 `V8.CurrentUser.Id` 的 `ChannelType=平台内部` 记录。
+- 支持 `PageIndex/PageSize`，`PageSize` 最大 100。
+- `DataAppend.UnreadCount` 返回同一用户权威未读数。
+
+### `msg_internal_mark_read`
+
+- `{ Id }` 只允许更新当前用户拥有的单条平台内部通知。
+- `{ All: true }` 更新当前用户全部未读平台内部通知。
+- 不接受客户端指定 `ReceiverUserId` 越权操作。
+
+### `V8.Notification.Send`
+
+`ReceiverUserId/ReceiverUserIds` 必填其一，最多 200 个；`Title` 最长 200 字符；`Content` 与序列化后的 `Payload` 各最多 32 KiB；`LinkUrl` 最长 500 字符且只允许站内路径、锚点、HTTP/HTTPS。事件名固定为 `ReceivePlatformNotification`。
+
+## 验收矩阵
+
+| 场景 | 断言 |
+|---|---|
+| 重复请求 | 同一接收人/渠道只存在一条日志，适配器不重复产生业务副作用 |
+| 两节点同时发送 | 唯一索引只有一个 claim 成功，两节点都不崩溃 |
+| 写入后节点退出 | 日志仍可查询；发送状态可审计、可补偿 |
+| SignalR/Redis 短故障 | 业务写入不回滚，客户端列表回读恢复 |
+| 事务回滚 | 不产生实时通知，业务日志随事务回滚 |
+| 离线用户 | 下次打开通知中心能看到并标记已读 |
+| 越权读取/已读 | 其它用户 Id 无效，记录不改变 |
+| 微信配置 | `WxMpId` 决定发送主体，小程序字段只决定跳转 |
+| 应用安装 | 无密钥、OpenId、历史日志或固定用户；安装后字段/索引/接口回读一致 |