@microi.net/cli 6.1.1 → 6.1.3

package/skills/v8-mongodb/SKILL.md

@@ -1,201 +1,201 @@
----
-name: v8-mongodb
-description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、UptFormDataByWhere、DelFormData、DelFormDataByWhere、GetFormData、GetTableData、对象过滤和文档 Id。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi V8 MongoDB 操作
-
-你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。
-
-## V8.MongoDb API
-
-### 存量 MongoDB 兼容诊断
-
-- `reports wire version 6 ... requires at least 9` 是驱动与服务端不兼容，不是日志为空，也不是 Token 失效。先记录原始错误和服务端真实协议，不能把 wire version 6 推断成 MongoDB 4.2。
-- 平台兼容镜像以含安全修复的驱动 3.11.2 构建，恢复平台 CRUD/日志所需的 MongoDB 3.6 协议路径；不是降级至 2.30，也不声明上游继续维护 3.6。来源、单文件补丁和摘要维护在 `Microi.Server/Microi.MongoDB.Driver/`。
-- 普通开发与全部默认测试先从当前 MCP 同源只读诊断发现真实 MongoDB 版本，沿已授权隔离范围执行认证、BSON、读写、索引、幂等重放、游标和租户隔离断言；不为旧版或其它版本重复询问、建库或新增服务。配置标签和 wire version 不能冒充实际版本回读。
-- 只有任务明确修改或验证存量兼容层、旧版本缺陷或跨版本升级时，才按该兼容目标扩展真实矩阵（例如需支持的 3.6 协议端与当前 MCP 实际版本），不固定假设当前端是 7.x。每个版本必须独立回读和实际执行，未执行记未覆盖；不得只验证编译或 ping，也不得把驱动兼容当作修复旧数据库服务端自身漏洞。
-- C# 驱动改动需要更新后端镜像才生效。镜像更新后通过 `microi_query_system_observability` 回读日志、队列持久化和错误状态；查询失败应原样报错，禁止返回成功空表。
-
-| 方法 | 说明 |
-|------|------|
-| `V8.MongoDb.AddFormData({...})` | 新增文档 |
-| `V8.MongoDb.UptFormData({...})` | 修改文档（按 Id） |
-| `V8.MongoDb.UptFormDataByWhere({...})` | 按非空 `_Where` 批量修改，禁止修改 `_id` |
-| `V8.MongoDb.DelFormData({...})` | 删除文档（按 Id） |
-| `V8.MongoDb.DelFormDataByWhere({...})` | 按非空 `_Where` 批量删除 |
-| `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
-var result = V8.MongoDb.UptFormDataByWhere({
-  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
-  TableName: 'chat_' + DateNow('yyyy'),
-  _Where: [
-    ['FromUserId', '=', V8.Param.PeerUserId],
-    ['ToUserId', '=', V8.CurrentUser.Id],
-    ['IsRead', '=', false]
-  ],
-  _FormData: { IsRead: true }
-});
-```
-
-`_Where` 缺失、为空或包含无效条件时必须返回失败，不得执行全集合更新。`_FormData` 禁止设置 `_id` 或 `_id.*`。返回值的 `Data` 包含 `MatchedCount` 和 `ModifiedCount`。
-
-## 删除文档
-
-```javascript
-V8.MongoDb.DelFormData({
-  DbName: 'sys_log_2024',
-  TableName: 'log_2024_12',
-  Id: V8.Param.id               // 必传
-});
-```
-
-### 按条件批量删除
-
-```javascript
-var result = V8.MongoDb.DelFormDataByWhere({
-  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
-  TableName: 'chat_last_contact',
-  _Where: [
-    ['UserId', '=', V8.CurrentUser.Id],
-    ['ContactUserId', '=', V8.Param.PeerUserId]
-  ]
-});
-```
-
-删除条件必须包含当前权威用户/资源边界，不能只用可伪造的前端参数。返回值的 `Data` 包含 `DeletedCount`。
-
-## 查询单个文档
-
-```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按钮']
-  ],
-  _OrderBy: 'CreateTime',
-  _OrderByType: 'DESC',
-  _PageIndex: 1,
-  _PageSize: 20
-});
-```
-
-`GetFormData` 和 `GetTableData` 属于 dynamic 无模式读取。服务端会在 MongoDB 投影阶段过滤 BSON 内部 `_t` CLR 类型判别字段，避免存量强类型 C# 写入留下的旧类型名称触发反序列化失败。`_t` 不是 V8 业务契约；业务需要类型标记时应使用自有字段（例如 `DocumentType`），不得读取、筛选或依赖 `_t`。强类型 C# MongoDB 模型仍按自身的多态映射处理。
-
-## 实战模式
-
-### 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, _OrderBy, _OrderByType }`
-- `DbName` 是 MongoDB 数据库名，`TableName` 是集合名
-- `_Where` 条件语法与 `V8.FormEngine` 一致
-- 批量写入仅接受安全字段名、已知操作符和非空条件；条件中的租户、用户和资源 Id 应来自 `V8.OsClient` / `V8.CurrentUser` / 权威回查，不得信任 `V8.Param` 中的同名身份字段
-- 非主库 V8 运行时会把 MongoDB 操作绑定到当前租户；显式传入其它 `OsClient` 不能跨租户
-- 适合存储日志、IoT 数据、大文档等非结构化 / 海量数据
-- 建议按时间分库分表（如 `log_2024_01`），便于清理历史数据
-- MongoDB 操作不参与 `V8.DbTrans` 事务。批量写入 `Code=1` 后即是已提交事实；后续 Hook/投递失败应返回警告或进入补偿，不得返回“未发生”导致盲目重试，重试必须有稳定业务 Id 幂等
+---
+name: v8-mongodb
+description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、UptFormDataByWhere、DelFormData、DelFormDataByWhere、GetFormData、GetTableData、对象过滤和文档 Id。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 MongoDB 操作
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。
+
+## V8.MongoDb API
+
+### 存量 MongoDB 兼容诊断
+
+- `reports wire version 6 ... requires at least 9` 是驱动与服务端不兼容，不是日志为空，也不是 Token 失效。先记录原始错误和服务端真实协议，不能把 wire version 6 推断成 MongoDB 4.2。
+- 平台兼容镜像以含安全修复的驱动 3.11.2 构建，恢复平台 CRUD/日志所需的 MongoDB 3.6 协议路径；不是降级至 2.30，也不声明上游继续维护 3.6。来源、单文件补丁和摘要维护在 `Microi.Server/Microi.MongoDB.Driver/`。
+- 普通开发与全部默认测试先从当前 MCP 同源只读诊断发现真实 MongoDB 版本，沿已授权隔离范围执行认证、BSON、读写、索引、幂等重放、游标和租户隔离断言；不为旧版或其它版本重复询问、建库或新增服务。配置标签和 wire version 不能冒充实际版本回读。
+- 只有任务明确修改或验证存量兼容层、旧版本缺陷或跨版本升级时，才按该兼容目标扩展真实矩阵（例如需支持的 3.6 协议端与当前 MCP 实际版本），不固定假设当前端是 7.x。每个版本必须独立回读和实际执行，未执行记未覆盖；不得只验证编译或 ping，也不得把驱动兼容当作修复旧数据库服务端自身漏洞。
+- C# 驱动改动需要更新后端镜像才生效。镜像更新后通过 `microi_query_system_observability` 回读日志、队列持久化和错误状态；查询失败应原样报错，禁止返回成功空表。
+
+| 方法 | 说明 |
+|------|------|
+| `V8.MongoDb.AddFormData({...})` | 新增文档 |
+| `V8.MongoDb.UptFormData({...})` | 修改文档（按 Id） |
+| `V8.MongoDb.UptFormDataByWhere({...})` | 按非空 `_Where` 批量修改，禁止修改 `_id` |
+| `V8.MongoDb.DelFormData({...})` | 删除文档（按 Id） |
+| `V8.MongoDb.DelFormDataByWhere({...})` | 按非空 `_Where` 批量删除 |
+| `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
+var result = V8.MongoDb.UptFormDataByWhere({
+  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
+  TableName: 'chat_' + DateNow('yyyy'),
+  _Where: [
+    ['FromUserId', '=', V8.Param.PeerUserId],
+    ['ToUserId', '=', V8.CurrentUser.Id],
+    ['IsRead', '=', false]
+  ],
+  _FormData: { IsRead: true }
+});
+```
+
+`_Where` 缺失、为空或包含无效条件时必须返回失败，不得执行全集合更新。`_FormData` 禁止设置 `_id` 或 `_id.*`。返回值的 `Data` 包含 `MatchedCount` 和 `ModifiedCount`。
+
+## 删除文档
+
+```javascript
+V8.MongoDb.DelFormData({
+  DbName: 'sys_log_2024',
+  TableName: 'log_2024_12',
+  Id: V8.Param.id               // 必传
+});
+```
+
+### 按条件批量删除
+
+```javascript
+var result = V8.MongoDb.DelFormDataByWhere({
+  DbName: 'diy_chat_' + V8.OsClient.toLowerCase(),
+  TableName: 'chat_last_contact',
+  _Where: [
+    ['UserId', '=', V8.CurrentUser.Id],
+    ['ContactUserId', '=', V8.Param.PeerUserId]
+  ]
+});
+```
+
+删除条件必须包含当前权威用户/资源边界，不能只用可伪造的前端参数。返回值的 `Data` 包含 `DeletedCount`。
+
+## 查询单个文档
+
+```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按钮']
+  ],
+  _OrderBy: 'CreateTime',
+  _OrderByType: 'DESC',
+  _PageIndex: 1,
+  _PageSize: 20
+});
+```
+
+`GetFormData` 和 `GetTableData` 属于 dynamic 无模式读取。服务端会在 MongoDB 投影阶段过滤 BSON 内部 `_t` CLR 类型判别字段，避免存量强类型 C# 写入留下的旧类型名称触发反序列化失败。`_t` 不是 V8 业务契约；业务需要类型标记时应使用自有字段（例如 `DocumentType`），不得读取、筛选或依赖 `_t`。强类型 C# MongoDB 模型仍按自身的多态映射处理。
+
+## 实战模式
+
+### 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, _OrderBy, _OrderByType }`
+- `DbName` 是 MongoDB 数据库名，`TableName` 是集合名
+- `_Where` 条件语法与 `V8.FormEngine` 一致
+- 批量写入仅接受安全字段名、已知操作符和非空条件；条件中的租户、用户和资源 Id 应来自 `V8.OsClient` / `V8.CurrentUser` / 权威回查，不得信任 `V8.Param` 中的同名身份字段
+- 非主库 V8 运行时会把 MongoDB 操作绑定到当前租户；显式传入其它 `OsClient` 不能跨租户
+- 适合存储日志、IoT 数据、大文档等非结构化 / 海量数据
+- 建议按时间分库分表（如 `log_2024_01`），便于清理历史数据
+- MongoDB 操作不参与 `V8.DbTrans` 事务。批量写入 `Code=1` 后即是已提交事实；后续 Hook/投递失败应返回警告或进入补偿，不得返回“未发生”导致盲目重试，重试必须有稳定业务 Id 幂等