@microi.net/cli 4.6.2

package/dist/microi.skills/v8-mongodb/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: v8-mongodb
+description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、DelFormData、GetFormData、GetTableData、对象过滤和文档 Id。
+---
+
+# Microi V8 MongoDB 操作
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。
+
+## V8.MongoDb API
+
+| 方法 | 说明 |
+|------|------|
+| `V8.MongoDb.AddFormData({...})` | 新增文档 |
+| `V8.MongoDb.UptFormData({...})` | 修改文档（按 Id） |
+| `V8.MongoDb.DelFormData({...})` | 删除文档（按 Id） |
+| `V8.MongoDb.GetFormData({...})` | 查询单个文档（按 Id） |
+| `V8.MongoDb.GetTableData({...})` | 查询文档列表 |
+| `V8.MongoDb.NewId()` | 生成 MongoDB Id |
+
+## 新增文档
+
+```javascript
+var newId = V8.MongoDb.NewId();
+V8.MongoDb.AddFormData({
+  DbName: 'sys_log_2024',       // 数据库名
+  TableName: 'log_2024_12',     // 集合（表）名
+  Id: newId,                     // 可选，不指定自动生成
+  _FormData: {
+    UserId: V8.CurrentUser.Id,
+    Action: '登录',
+    IP: '192.168.1.1',
+    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+## 修改文档
+
+```javascript
+V8.MongoDb.UptFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id,              // 必传
+  _FormData: {
+    Action: '更新操作',
+    UpdateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+## 删除文档
+
+```javascript
+V8.MongoDb.DelFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id               // 必传
+});
+```
+
+## 查询单个文档
+
+```javascript
+var result = V8.MongoDb.GetFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id               // 必传
+});
+```
+
+## 查询文档列表
+
+```javascript
+var result = V8.MongoDb.GetTableData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  _Where: [
+    ['Type', '=', '访问菜单'],
+    ['OR', 'Type', '=', '点击V8按钮']
+  ]
+});
+```
+
+## 实战模式
+
+### IoT 设备日志存储
+
+```javascript
+// 接收 MQTT 消息后存入 MongoDB
+var eventName = V8.EventName;
+if (eventName === 'MessageReceived') {
+  V8.MongoDb.AddFormData({
+    DbName: 'iot_data',
+    TableName: 'device_log_' + DateNow('yyyy_MM'),
+    _FormData: {
+      DeviceId: V8.MQTT.ClientId,
+      Topic: V8.MQTT.Topic,
+      Payload: V8.MQTT.Payload,
+      Timestamp: DateNow('yyyy-MM-dd HH:mm:ss')
+    }
+  });
+}
+```
+
+### 操作审计日志
+
+```javascript
+// 在 SubmitAfterServerV8.js 中记录审计日志到 MongoDB
+V8.MongoDb.AddFormData({
+  DbName: 'audit_log',
+  TableName: 'form_audit_' + DateNow('yyyy'),
+  _FormData: {
+    TableName: V8.TableModel.Name,
+    Action: V8.FormSubmitAction,
+    DataId: V8.Form.Id,
+    UserId: V8.CurrentUser.Id,
+    UserName: V8.CurrentUser.Name,
+    OldData: V8.FormSubmitAction === 'Update' ? JSON.stringify(V8.OldForm) : null,
+    NewData: JSON.stringify(V8.Form),
+    CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  }
+});
+```
+
+### 按月分表查询
+
+```javascript
+// 查询指定月份的日志
+var month = V8.Param.month || DateNow('yyyy_MM');
+var result = V8.MongoDb.GetTableData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_' + month,
+  _Where: [
+    ['UserId', '=', V8.CurrentUser.Id]
+  ]
+});
+
+return { Code: 1, Data: result };
+```
+
+## 注意事项
+
+- MongoDB 参数统一使用**对象格式**：`{ DbName, TableName, Id, _FormData, _Where }`
+- `DbName` 是 MongoDB 数据库名，`TableName` 是集合名
+- `_Where` 条件语法与 `V8.FormEngine` 一致
+- 适合存储日志、IoT 数据、大文档等非结构化 / 海量数据
+- 建议按时间分库分表（如 `log_2024_01`），便于清理历史数据
+- MongoDB 操作不参与 `V8.DbTrans` 事务

package/dist/microi.skills/v8-mq-mqtt/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: v8-mq-mqtt
+description: Microi V8 消息队列与 MQTT 指南。用于使用 V8.MQ.SendMsg、RabbitMQ 队列、MQTT 事件处理、主题、载荷、客户端 Id 和异步集成。
+---
+
+# Microi V8 消息队列与 MQTT
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 RabbitMQ 消息队列或 MQTT 物联网协议。
+
+## V8.MQ — RabbitMQ 消息队列
+
+### 生产消息（后端）
+
+```javascript
+// 在 async 接口引擎或 V8 事件中发送消息。
+// 业务重试必须复用同一个 EventId，供消费者幂等去重。
+var result = await V8.MQ.SendMsg({
+  QueueName: 'order_process',
+  EventId: V8.Param.eventId || V8.Method.NewUlid(),
+  Message: {
+    ProductId: '123',
+    Count: 2,
+    OrderId: V8.Param.orderId
+  }
+});
+if (result.Code !== 1) return result;
+```
+
+逻辑队列名由服务端规范为 `microi.{lowerOsClient}.{queueName}`。V8 上下文、登录 Token 与后台显式 `OsClient` 是权威租户，body 不能切换到其它租户队列。
+
+### 生产消息（前端）
+
+```javascript
+V8.Post('/api/mq/sendmsg', {
+  QueueName: 'queue_name',
+  EventId: stableEventId,
+  Message: { ProductId: '123', Count: 2 }
+}, function(result) {
+  if (result.Code === 1) V8.Tips('消息已发送', true);
+}, null, {}, 'json');
+```
+
+### 消费消息
+
+消费者是一个接口引擎，在 `diy_queue_receive` 表中配置队列名和接口引擎 Key 后，消息到达时自动调用。
+
+```javascript
+// 消费者接口引擎
+var message = V8.Param.Message;   // object 类型
+// message.EventId     — 稳定业务幂等 Id
+// message.Id          — EventId 的兼容别名
+// message.OsClient    — 消息所属租户
+// message.Message     — 消息内容
+// message.CurrentUserId — 生产消息的用户 Id
+
+// 处理业务逻辑
+var data = message.Message;
+V8.FormEngine.UptFormData('Product', {
+  Id: data.ProductId,
+  Stock: data.Count
+});
+```
+
+### 实战模式：异步处理耗时操作
+
+```javascript
+// 接口引擎：接收请求后发送到队列，快速返回
+await V8.MQ.SendMsg({
+  QueueName: 'order_process',
+  EventId: V8.Param.eventId,
+  Message: {
+    orderId: V8.Param.orderId,
+    action: 'create',
+    userId: V8.CurrentUser.Id
+  }
+});
+
+return { Code: 1, Msg: '订单处理中，请稍候查看结果' };
+```
+
+```javascript
+// 消费者接口引擎：异步处理订单
+var msg = V8.Param.Message;
+var data = msg.Message;
+
+try {
+  // 耗时操作：调用第三方 ERP 接口
+  var erpResult = V8.Http.Post({
+    Url: 'https://erp.company.com/api/order',
+    PostParamString: JSON.stringify({ orderId: data.orderId }),
+    ParamType: 'json',
+    Timeout: 30
+  });
+
+  V8.FormEngine.UptFormData('Order', {
+    Id: data.orderId,
+    SyncStatus: 'success',
+    SyncTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  });
+} catch (ex) {
+  V8.FormEngine.UptFormData('Order', {
+    Id: data.orderId,
+    SyncStatus: 'failed',
+    SyncError: ex.message
+  });
+  console.error('订单同步失败: ' + ex.message);
+}
+```
+
+### MQ 配置
+
+主租户提供共享 Broker 地址 `MQHost/MQPort`。每个子租户必须在 RabbitMQ 中真实创建独立的 `MQUserName/MQPassword/MQVitrualHost`，并把权限限制在自己的 vhost 与 `microi.{osClient}.*` 队列；缺少凭据或与其它租户共用 user/password/vhost 时失败关闭，不回退主租户管理员账号。
+
+在 `diy_queue_receive` 表新增记录后，平台启动时自动订阅：
+
+| 字段 | 含义 |
+|------|------|
+| `Type` | `接口引擎`（固定） |
+| `QueueName` | 逻辑队列名（与生产端 `SendMsg({ QueueName, ... })` 一致） |
+| `ApiEngineKey` | 消费者接口引擎 Key |
+| `IsEnable` | 是否启用 |
+| `OsClient` | 所属租户（多租户隔离） |
+
+> ⚠️ 修改 `diy_queue_receive` 后需重启平台才会生效订阅。
+
+多节点会对同一租户队列使用 RabbitMQ competing consumer，但“只有一个节点收到”不等于业务只执行一次。消息 envelope 的 `EventId` 是稳定幂等键，消费者必须配合数据库唯一约束、inbox/条件更新保证副作用仅一次；连接凭据轮换后当前版本需要重启节点重建连接。
+
+---
+
+## V8.MQTT — IoT 物联网
+
+### MQTT 事件类型
+
+MQTT 通过一个接口引擎处理所有事件，通过 `V8.EventName` 判断当前事件类型：
+
+| V8.EventName | 说明 |
+|---|---|
+| `StartServer` | MQTT 服务启动 |
+| `Connected` | 客户端连接 |
+| `Disconnected` | 客户端断开连接 |
+| `MessageReceived` | 收到客户端消息 |
+| `StopServer` | MQTT 服务停止 |
+
+### V8.MQTT 上下文
+
+| 属性 | 说明 |
+|---|---|
+| `V8.MQTT.ClientId` | 客户端 Id |
+| `V8.MQTT.Topic` | 消息主题 |
+| `V8.MQTT.Payload` | 消息内容（在 MessageReceived 事件中） |
+
+子租户必须 `MqttEnable=1` 并配置独立 `MqttAccount/MqttPwd`。子租户不能通过 `MqttAllowAnonymous=1` 或 `MqttTopicIsolation=0` 关闭边界；缺少完整凭据时拒绝连接。Topic 统一为 `tenant/{lowerOsClient}/{businessTopic}`，服务端 publish、subscribe、retained、ResponseTopic 都会校验并拒绝其它租户、系统 Topic 和共享订阅绕过。
+
+### 完整示例
+
+```javascript
+var eventName = V8.EventName;
+
+if (eventName === 'StartServer') {
+  console.log('MQTT 服务已启动');
+
+} else if (eventName === 'Connected') {
+  console.log('设备已连接: ' + V8.MQTT.ClientId);
+  // 记录设备在线状态
+  V8.FormEngine.UptFormDataByWhere('Device', {
+    _Where: [['DeviceCode', '=', V8.MQTT.ClientId]],
+    OnlineStatus: 1,
+    LastOnlineTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  });
+
+} else if (eventName === 'Disconnected') {
+  console.log('设备已断开: ' + V8.MQTT.ClientId);
+  V8.FormEngine.UptFormDataByWhere('Device', {
+    _Where: [['DeviceCode', '=', V8.MQTT.ClientId]],
+    OnlineStatus: 0,
+    LastOfflineTime: DateNow('yyyy-MM-dd HH:mm:ss')
+  });
+
+} else if (eventName === 'MessageReceived') {
+  // 处理设备上报的数据
+  var clientId = V8.MQTT.ClientId;
+  var topic = V8.MQTT.Topic;
+  var payload = V8.MQTT.Payload;
+
+  console.log('收到消息: ' + clientId + ' - ' + topic);
+
+  // 存储到 MongoDB（适合海量数据）
+  V8.MongoDb.AddFormData({
+    DbName: 'iot_data',
+    TableName: 'device_msg_' + DateNow('yyyy_MM'),
+    _FormData: {
+      DeviceId: clientId,
+      Topic: topic,
+      Payload: payload,
+      CreateTime: DateNow('yyyy-MM-dd HH:mm:ss')
+    }
+  });
+
+  // 解析特定主题的数据
+  var temperatureTopic = 'tenant/' + V8.OsClient.toLowerCase() + '/sensor/temperature';
+  if (topic === temperatureTopic) {
+    var temp = parseFloat(payload);
+    if (temp > 80) {
+      // 温度报警
+      V8.ApiEngine.Run('send-alarm', {
+        deviceId: clientId,
+        type: 'temperature',
+        value: temp
+      });
+    }
+  }
+
+} else if (eventName === 'StopServer') {
+  console.log('MQTT 服务已停止');
+}
+```
+
+## 注意事项
+
+- MQ 消费者接口引擎通过 `V8.Param.Message` 获取消息，包含 `EventId`、兼容 `Id`、`OsClient`、`Message`、`CurrentUserId`
+- MQ 适合异步解耦、削峰填谷、耗时操作异步化
+- MQTT 所有事件在同一个接口引擎中处理，通过 `V8.EventName` 区分
+- MQTT 适合 IoT 设备管理、实时数据采集
+- 海量 MQTT 数据建议存入 MongoDB 而非 MySQL
+- MQ 和 MQTT 的租户凭据在 SaaS 引擎中管理，但必须先在真实 Broker 创建对应资源，不能只写数据库字段
+- `ConnectedClients` 只代表当前 MQTT 节点的诊断快照，不是集群全局在线事实
+- 内嵌 MQTT Broker 不具备跨节点共享会话/订阅/retained 的集群一致性；多 API 节点生产部署应使用支持集群的外部 Broker，或把内嵌 Broker 固定到独立节点并由负载入口路由，不能让每个 API 节点各自充当一套独立 Broker

package/dist/microi.skills/v8-saas-multi-tenant/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: v8-saas-multi-tenant
+description: Microi V8 SaaS 多租户指南。用于处理 OsClient、OsClientType、OsClientNetwork、租户配置、V8.OsClientModel、隔离和租户感知代码。
+---
+
+# Microi V8 SaaS 多租户引擎
+
+你正在为 Microi 吾码平台编写多租户（SaaS）相关代码。每个租户使用独立数据库账号；Redis、对象存储、RabbitMQ、MQTT 和搜索集群可以共享基础设施，但必须使用租户命名空间与独立服务凭据，**所有 V8 代码都在租户上下文中运行**。
+
+## 核心概念
+
+Microi 多租户 = **`OsClient` + `OsClientType` + `OsClientNetwork`** 三参数模型：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `OsClient` | 租户标识（系统Key） | `tenant_a`, `tenant_demo` |
+| `OsClientType` | 租户类型 | `Normal` / `App` / `Wechat` |
+| `OsClientNetwork` | 网络环境 | `Intranet`（内网）/`Outernet`（外网） |
+
+主租户不是固定字符串 `master`，而是由当前部署的环境变量 `OsClient` 或 `AppSettings:OsClient` 决定。租户记录存放在受保护的 `sys_osclients` 表中；普通业务角色和普通 V8 不得直接查询、复制或修改该表。
+
+## 上下文变量
+
+```javascript
+V8.OsClient            // 当前租户标识，如 'tenant_demo'
+V8.OsClientType        // 'Normal' / 'App' / 'Wechat'
+V8.OsClientNetwork     // 'Intranet' / 'Outernet'
+V8.OsClientModel       // 当前租户 SaaS 配置的脱敏副本
+V8.ClientModel         // OsClientModel 的兼容别名，同样是脱敏副本
+V8.SysConfig           // 当前租户 sys_config 的独立脱敏副本
+```
+
+`V8.SysConfig` 与 `V8.FormEngine.GetSysConfig(...)` 不暴露 `ClientSecrets`、`PwdV8`、`GlobalServerV8Code` 或疑似凭据字段；子租户显式传其它 `OsClient` 也会被强制改回当前租户。
+
+### V8.OsClientModel 常用字段
+
+```javascript
+V8.OsClientModel.SysTitle              // 租户系统标题
+V8.OsClientModel.DbType                // 非敏感数据库类型
+V8.OsClientModel.HDFS                  // 'Aliyun' / 'MinIO' / 'S3'
+V8.OsClientModel.AliOssPublicDomain    // 可公开的文件域名
+// 当前租户自行扩展的业务集成字段仍可读取
+
+// 以下基础设施字段不会注入 V8：
+// DbConn / DbReadConn / AuthSecret
+// RedisHost / RedisPwd / MinIOSecretKey / AliOss*AccessKey*
+// MQHost / MQUserName / MQPassword / MqttPwd / SearchEngineApiKey
+```
+
+## 平台级配置与主租户规则
+
+`sys_osclients` 既保存每个租户自己的数据库、Redis、第三方密钥等配置，也可以承载影响整个 API 进程的平台级配置。平台级配置必须遵守“主租户为准、子租户只能降额隔离”的规则：
+
+- 所有可变业务逻辑默认必须由接口引擎编排，包括但不限于租户开通、开库、初始化、归属修复、官网个人中心、付费额度等 SaaS 业务流程。C# 后端只暴露原子 V8 能力，例如建库、导入空库模板、复制 `sys_config`、刷新 SaaS 缓存、补偿回滚、字段兜底等；不要把可变业务分支写死到 Controller 或 `TenantProvisioningService` 这类后端定制代码里。接口引擎缺少能力时，优先扩展 `V8.Method`/V8 引擎原子函数，再由接口引擎调用。
+- 主租户由运行环境决定：优先读取环境变量 `OsClient`，其次读取 `appsettings.json` 的 `AppSettings:OsClient`。只有这条主租户 `sys_osclients` 数据中的平台级字段会作为全局配置生效。
+- 普通业务与运行参数统一从主租户 `sys_osclients` 或 `sys_config` 读取，未配置时使用代码安全默认值；不要再为同一参数增加 `MICROI_*` 或 `DOS_ORM_*` 环境变量。数据库、Redis 和必要密钥属于启动基础设施，继续使用现有专用安全配置；节点身份由平台自动生成。
+- 文件上传的租户业务开关与额度按“当前租户 `sys_osclients` → 代码默认值”解析；平台固定灾难保护、HTTP/Multipart/Form 和反向代理上限不可由租户覆盖，也不要求安装者维护额外上传环境变量。
+- 类似 MQTT 端口、PressureGuard、V8Limits、OrmLimits、StartupLimits、SecurityGuard 这类影响整进程资源的配置，不能让每个子租户各自抬高全局上限。子租户同名隔离字段只能降低自己的并发、等待时间或资源额度，用于隔离弱租户、试用租户或异常租户。
+- 修改 `sys_osclients` 的表、字段、数据源或配置值后，必须刷新 SaaS 引擎运行缓存，并回读验证字段 `Component`、`Data`、`Config`、实际数据值和前端真实消费结果。不要只看 MCP 写入成功。
+- SaaS 配置只在启动、管理员保存 `sys_osclients` 或显式租户刷新时发布到共享 Redis。初始化数据库会话、创建 `V8.Dbs` 运行态对象、普通 FormEngine 请求和表单设计器保存不得冒充配置变更反复发布。
+- 扩展库缓存必须区分“尚未加载”和“已加载但为 0 条”；后者是有效结果。没有配置 `microi_database` 的租户不能在每次 V8 执行时重复查询、调用 `AddOrUptClient` 或打印“缓存 OsClient 配置到 Redis”。
+- 多节点的缓存失效订阅只做本节点失效与数据库回源，禁止收到消息后再次发布形成回声。进程内初始化标记仅是可丢失优化，真正租户配置仍以共享数据库/Redis 为准。
+- 新增平台级字段时，字段名建议保持英文稳定，例如 `PressureGlobalMaxConcurrentRequests`、`PressureV8MaxConcurrentExecutions`、`PressureOrmMaxConcurrentConnectionOpens`；字段标签和说明必须中文，说明中写清楚“主租户有效/子租户仅可降低”。
+- 新租户记录不得复制主租户的数据库、鉴权、Redis/对象存储密钥或 MQ/MQTT/Search 凭据。共享基础设施地址与管理密钥只在服务端运行时解析，不持久化到子租户记录，也不进入 V8 投影。
+- RabbitMQ 子租户必须使用独立 user/vhost/ACL，MQTT 必须使用独立账号密码，Search 必须使用限制到 `{osClient}_*` 的 API Key/用户。外部资源尚未真实创建时保持空凭据并失败关闭，禁止把主租户管理员凭据复制过去冒充完成。
+- `V8.Cache`、`V8.HDFS`、RabbitMQ、MQTT、Search 分别强制 `Microi:{OsClient}:*`、`/{osClient}/...`、`microi.{osClient}.*`、`tenant/{osClient}/...`、`{osClient}_*` 命名空间。body/query 中的 `OsClient` 不能覆盖登录 Token 或 V8 上下文。
+
+## 接口调用区分租户的三种方式
+
+### 方式 1：Token 自动识别（最常用）
+
+请求头携带 `Token`，平台自动识别用户所属租户。
+
+```bash
+GET /apiengine/get-products
+Token: xxx-token-xxx
+```
+
+### 方式 2：URL 参数
+
+```bash
+GET /apiengine/get-products?OsClient=tenant_demo
+```
+
+### 方式 3：特殊 URL 格式（无 Token、无参数）
+
+```bash
+GET /apiengine/get-products--OsClient--tenant_demo--
+GET /apiengine/get-products--OsClient--tenant_demo--OsClientType--App--
+```
+
+> 适用于第三方回调（无法添加 Header）、支付/微信回调等场景。
+
+## 跨租户操作（仅可信控制面）
+
+普通 V8 的 `FormEngine`、`DataSourceEngine`、`TranslateEngine`、`WFEngine`、`Cache`、`HDFS`、MQ/MQTT、Search 和 `Dbs` 都必须绑定当前 Token/V8 上下文中的 `OsClient`。请求 body/query 里传入其它租户不能切换连接，也不能读取其它租户凭据。
+
+租户开通、迁移、备份或平台管理员代维只能走明确的控制面服务/接口引擎：
+
+- 调用者必须是 `Level >= 9999`，并再次校验目标租户白名单和操作类型；
+- 使用专用原子能力，不通过通用 FormEngine 读取完整 `sys_osclients` 记录；
+- 不把数据库、认证、Redis、存储、MQ/MQTT、搜索等连接与密钥投影进 V8；
+- 每次操作写安全审计、幂等键和补偿状态，并对目标租户回读验收；
+- 多节点部署使用共享租约和业务幂等，不能依赖进程静态锁。
+
+## 缓存按租户隔离
+
+```javascript
+// 推荐传逻辑 Key；服务端自动添加当前租户前缀
+var key = 'Product:' + V8.Param.id;
+V8.Cache.Set(key, value, 600);
+
+// 完整当前租户 Key 继续兼容
+var fullKey = 'Microi:' + V8.OsClient + ':Product:' + V8.Param.id;
+
+// 其它租户的 Microi: 前缀会被服务端拒绝
+```
+
+## 接口引擎中针对不同租户走不同逻辑
+
+```javascript
+// 租户差异应来自当前租户的非敏感业务配置，不要硬编码某个“主租户”字符串
+if (V8.OsClientModel.OrderApprovalMode === 'Direct') {
+  V8.FormEngine.UptFormData('Order', { Id: id, Status: 'Approved' });
+} else {
+  await V8.WFEngine.StartWork({ FlowDesignId: 'order-flow', TableRowId: id });
+}
+
+// App 端 vs PC 端不同返回
+if (V8.OsClientType === 'App') {
+  return { Code: 1, Data: simplifiedList };
+}
+return { Code: 1, Data: fullList };
+
+// 内网外网走不同 ERP 网关
+var erpUrl = (V8.OsClientNetwork === 'Intranet')
+  ? 'http://192.168.1.10/erp/api'
+  : 'https://erp.public.com/api';
+```
+
+## 第三方密钥放 OsClientModel（不要硬编码）
+
+```javascript
+// ❌ 危险：密钥写在代码里，所有租户共用，无法独立轮换
+var ak = 'AKIDxxxxxxxx';
+
+// ✅ 正确：每个租户在 sys_osclients 表中配置自己的业务集成密钥
+var ak = V8.OsClientModel.WxPayMchKey;
+var secret = V8.OsClientModel.WxPaySecret;
+```
+
+> 在表单引擎中给 `sys_osclients` 添加租户自有业务字段（如 `WxPayMchKey`），可通过 `V8.OsClientModel.字段名` 访问。共享基础设施字段由服务端强制移除，不能用自定义同义字段绕过安全代理。
+
+## 用户扩展字段访问（同理）
+
+平台 `sys_user` 也由表单引擎驱动。如给 `sys_user` 添加 `Wife` 字段：
+
+```javascript
+// V8 代码中可访问
+V8.CurrentUser.Wife;
+
+// SQL 数据源中可访问
+SELECT * FROM Contact WHERE OwnerId = $CurrentUser.Id$ AND Spouse = $CurrentUser.Wife$
+```
+
+## 常见错误
+
+❌ 绕开 `V8.Cache` 使用底层 Redis → 租户数据串号（V8 已不再暴露底层句柄）
+❌ MongoDB DbName 不带 OsClient → 数据混淆  
+❌ 把 OsClientModel 字段直接返回给前端 → 密钥泄漏  
+❌ 在前端硬编码 OsClient → 一改全改，应通过 token/URL 自动识别  
+❌ 跨租户操作不验证当前用户权限 → 越权风险  
+❌ 子租户缺少 MQ/MQTT/Search 独立凭据时回退主账号 → 全平台越权
+
+## 检查清单
+
+- [ ] 缓存只通过 `V8.Cache` 使用逻辑 Key 或当前租户完整 Key
+- [ ] 所有 MongoDB DbName 都包含 `V8.OsClient`
+- [ ] 当前租户自有的业务集成密钥可放 `V8.OsClientModel`，共享 Redis/存储/MQ/MQTT/Search 凭据只能由服务端托管
+- [ ] 跨租户操作前校验权限
+- [ ] 不向前端返回 `V8.OsClientModel`
+- [ ] 子租户数据库账号只授权本租户库，MQ/MQTT/Search 独立凭据已真实创建
+- [ ] 文件、队列、Topic、索引均由服务端规范为当前租户命名空间
+- [ ] 无扩展库租户重复执行 V8 时不会重复刷新 SaaS 配置；真实 `sys_osclients` 保存后各节点能按租户失效并回源
+
+## Microi.AI 中转站租户凭据
+
+- `mic_ai` 的 `Microi.AI中转站.ApiKey` 是租户调用吾码官方中转站的用户凭据。运行时不得因为该字段为空而静默创建、回退到当前用户字段或绕过校验，否则管理员无法判断真实配置来源。
+- 老租户由用户在吾码官网个人中心复制 ApiKey 后填写到本租户的 `mic_ai` 中转站记录；空值应返回明确配置错误。
+- 官网创建新 SaaS 租户时，必须先取得当前官网账号的 ApiKey，再由租户初始化服务写入新库 `mic_ai` 的 `Microi.AI中转站` 记录。该自动写入只发生在受控开库流程，不得散落到普通 AI 对话请求中。
+- 开库入口把 ApiKey 传给后台 worker 后，worker 还必须继续显式传入最终的原子初始化方法；不能只在父接口或中间参数中“带过”。每个异步/后台边界都应对空值立即失败，避免租户创建成功但 `mic_ai.ApiKey` 静默为空。
+- 自动化验收必须通过新租户 `admin` 登录回读 `mic_ai`，只输出“非空、长度、与官网账号 ApiKey 是否一致”等布尔结果，不得把真实 ApiKey 写入日志、截图或测试报告。
+- 中转模型公开目录只返回模型 Id、显示名、厂商等非敏感字段，可匿名读取；严禁把官方上游模型的 ApiKey、Endpoint 私密配置随模型列表返回前端。