@microi.net/cli 5.5.9 → 5.6.1

package/skills/business-blueprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: business-blueprint
-description: Microi 业务架构蓝图（System Blueprint）— 设计期系统知识图谱，AI 生成低代码系统时防幻觉的唯一事实源
+description: Microi 业务架构蓝图（System Blueprint）— 设计期系统知识图谱，AI 生成低代码系统时防幻觉的唯一事实源
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
@@ -9,7 +9,7 @@ description: Microi 业务架构蓝图（System Blueprint）— 设计期系统
 
 ## 这是什么
 
-业务架构蓝图是 Microi 吾码的 **设计期系统总图**，不是 n8n / Dify / ComfyUI 那种运行时工作流。它一次同时承担三个职责：
+业务架构蓝图是 Microi 吾码的 **设计期系统总图**，不是 n8n / Dify / ComfyUI 那种运行时工作流。它一次同时承担三个职责：
 
 1. **可视化总图** — 用户在前端 X6 画布拖拽节点，完整描述一个业务系统的组成
 2. **AI 事实源** — AI 生成代码、表、接口引擎、菜单前必读的"宪法"，防止幻觉
@@ -39,17 +39,17 @@ description: Microi 业务架构蓝图（System Blueprint）— 设计期系统
 |---|---|---|
 | `microi_get_blueprint_schema` | 读取蓝图协议指南 | 否 |
 | `microi_list_blueprints` | 列出当前 OsClient 所有蓝图 | 否 |
-| `microi_get_blueprint` | 读取单个蓝图（含 BlueprintData） | 否 |
-| `microi_list_blueprint_history` | 分页读取不可变历史元数据与当前哈希 | 否 |
-| `microi_get_blueprint_history` | 读取指定历史快照 | 否 |
-| `microi_compare_blueprint_versions` | 结构化比较两个快照或历史与当前草稿 | 否 |
-| `microi_export_blueprint` | 导出 `microi.blueprint.v1` 设计包与稳定哈希 | 否 |
-| `microi_save_blueprint` | 创建或更新蓝图 + 自动写历史 + 重建反向索引 | 是（需 confirmExecution） |
-| `microi_rollback_blueprint` | 带 `ExpectedCurrentHash` 回滚并重建反向索引 | 是（需 confirmExecution） |
-| `microi_delete_blueprint` | 软删除蓝图 | 是 |
-| `microi_validate_blueprint` | 漂移检测：所有 refs 是否仍存在 | 否 |
-
-保存前必须从详情或历史列表取得当前哈希，并把它作为蓝图对象的 `ExpectedCurrentHash`。哈希冲突时先比较版本再合并，不得移除并发保护强行覆盖。回滚会先保存回滚前快照，再在同一事务中恢复目标内容并重建反向索引；历史不会被删除。
+| `microi_get_blueprint` | 读取单个蓝图（含 BlueprintData） | 否 |
+| `microi_list_blueprint_history` | 分页读取不可变历史元数据与当前哈希 | 否 |
+| `microi_get_blueprint_history` | 读取指定历史快照 | 否 |
+| `microi_compare_blueprint_versions` | 结构化比较两个快照或历史与当前草稿 | 否 |
+| `microi_export_blueprint` | 导出 `microi.blueprint.v1` 设计包与稳定哈希 | 否 |
+| `microi_save_blueprint` | 创建或更新蓝图 + 自动写历史 + 重建反向索引 | 是（需 confirmExecution） |
+| `microi_rollback_blueprint` | 带 `ExpectedCurrentHash` 回滚并重建反向索引 | 是（需 confirmExecution） |
+| `microi_delete_blueprint` | 软删除蓝图 | 是 |
+| `microi_validate_blueprint` | 漂移检测：所有 refs 是否仍存在 | 否 |
+
+保存前必须从详情或历史列表取得当前哈希，并把它作为蓝图对象的 `ExpectedCurrentHash`。哈希冲突时先比较版本再合并，不得移除并发保护强行覆盖。回滚会先保存回滚前快照，再在同一事务中恢复目标内容并重建反向索引；历史不会被删除。
 
 ## AI 工作流（强制约定）
 
@@ -59,11 +59,11 @@ description: Microi 业务架构蓝图（System Blueprint）— 设计期系统
 1. microi_list_blueprints              # 看是否已有相关蓝图
 2. microi_get_blueprint(id)            # 有则读取作为上下文
 3. microi_get_manifest_schema          # 读 manifest 协议
-4. microi_plan_system / generate_system
-5. microi_get_table_indexes / microi_create_table_index
-                                         # 按蓝图查询与业务不变量创建并回读索引
-6. microi_save_blueprint               # 同步写入/更新蓝图（含本次新增的表/引擎/菜单引用）
-7. microi_validate_blueprint           # 验收
+4. microi_plan_system / generate_system
+5. microi_get_table_indexes / microi_create_table_index
+                                         # 按蓝图查询与业务不变量创建并回读索引
+6. microi_save_blueprint               # 同步写入/更新蓝图（含本次新增的表/引擎/菜单引用）
+7. microi_validate_blueprint           # 验收
 ```
 
 ### 场景 B：用户让 AI 修改某张表 / 加字段 / 改接口引擎
@@ -115,73 +115,73 @@ description: Microi 业务架构蓝图（System Blueprint）— 设计期系统
       ]
     }
   ],
-  "domainModel": {
-    "entities": [
-      { "table": "crm_customer", "x": 50, "y": 50,
-        "relations": [{ "to": "crm_contact", "type": "1:N", "via": "CustomerId" }],
-        "indexes": [
-          { "name": "uk_crm_customer_osclient_code", "columns": ["OsClient", "Code"], "unique": true, "purpose": "租户内客户编码唯一" },
-          { "name": "idx_crm_customer_osclient_status_createtime", "columns": ["OsClient", "Status", "CreateTime"], "unique": false, "purpose": "客户状态列表" }
-        ] }
-    ]
-  },
-  "menuTree": {
-    "requiredDepth": 2,
-    "groups": [
-      { "name": "客户中心", "children": ["客户管理", "联系人管理"] },
-      { "name": "业务运营", "children": ["工单管理", "服务记录"] },
-      { "name": "报表中心", "children": ["检测报告", "阅读日志"] }
-    ]
-  }
-}
-```
-
-`refs` 内可填的资源类型：`tables` `fields`（"table.field"）`engines` `menus` `v8Events`（"table:eventType"）`dataSources` `printTemplates` `workflows` `pages` `jobs`。
-
-领域层每张实体表还必须描述真实查询需要的 `indexes`（名称、有序字段、唯一性、用途）。关系的 `via` 外键、租户内业务唯一键、幂等键、待办/重试扫描字段都必须评估索引。蓝图或需求一旦明确索引，生成 Manifest 时不得遗漏 `tables[].indexes`，落地必须调用 `microi_create_table_index` 并以 `microi_get_table_indexes` 回读；禁止在 V8 中手写 DDL。
-
-### 关系基数先于表单控件（强制）
-
-- 每条领域关系必须先写清 `1:1`、`N:1` 或 `1:N`，再决定控件。自然语言中的“子表、
-  明细、清单、条目、行项目、多个记录”默认按 `1:N` 建模，除非用户明确说明只关联一条。
-- `1:N` 的 `via` 必须是**子表上的真实外键**，例如
-  `order -> order_detail, type: 1:N, via: OrderId`；Manifest 同时生成子表外键、
-  `(OsClient, OrderId)` 回查索引、隐藏子菜单和主表 `TableChild` 控件。
-- `JoinForm` 只映射“主表保存一个目标 Id，并内嵌一条独立目标记录”的 `N:1`/`1:1`
-  关系。禁止把 `1:N` 蓝图映射为 `JoinForm`，禁止让 `JoinForm` 指向当前表。
-- 如果蓝图写了 `1:N`，而 Manifest 只有主表 `XxxId`/`JoinForm`，或缺少子表 `via`
-  外键、子菜单、回查索引，蓝图检查必须失败，不能进入 `dryRun:false`。
-- 基数仍有歧义时，在任何 MCP 写入前询问用户；不得为了避免询问而选择 `JoinForm`。
-
-后台菜单必须在蓝图阶段规划为至少两级结构。客户、设备、工单、报告、日志、配置等业务域应先形成父级菜单，再把具体 CRUD/报表/日志页面作为子菜单写入 Manifest/MCP；不要把所有模块平铺为一级菜单。
-
-如果是改造已生成系统，蓝图不能停留在建议层。必须列出现有一级菜单、目标父级菜单、每个子菜单的 `ParentId` 迁移关系，并通过 MCP 回读 `sys_menu` 验证迁移完成。
-
-## 角色与权限蓝图
-
-从自然语言需求生成 Microi 业务系统时，必须把角色、菜单权限、移动端能力和数据范围写进蓝图，而不是只建表和菜单。
-
-要求：
-
-- 内部账号默认使用 `sys_user`，角色来源为 `sys_user.RoleIds` 关联 `sys_role`。移动端和接口引擎都应按 `RoleIds` / `V8.CurrentUser` 判断能力。
-- 蓝图中至少列出角色矩阵：角色名、使用端、后台菜单范围、移动端可见页面、关键动作、数据范围。常见角色如超级管理员、客服、售后师傅、客户账号。
-- 多角色账号按能力并集处理；只有服务端已确认的超级管理员（`Level>=9999`）默认拥有全部内部能力。前端角色名、“超级管理员”文案和 `_IsAdmin` 只能控制展示，不能代替后端授权。
-- 客户账号不能简单获得后台客户、工单、报告全量菜单。客户侧数据应通过客户手机号登录 token、客户绑定表和接口行级过滤提供。
-- 菜单权限使用 `sys_rolelimit` 控制入口；接口引擎仍要做业务级权限和行级数据过滤，不能只依赖菜单是否可见。
-- Manifest/MCP 交付后必须回读 `sys_role`、`sys_menu`、`sys_rolelimit`，验证角色存在、菜单授权正确。
-- 如果 MCP 的通用角色写入工具因 `UpdateTime cannot be null` 等系统字段问题失败，要记录工具缺口并使用平台修复后的专用角色工具。临时迁移可用一次性接口引擎和参数化 `V8.Db` 补建角色，但必须回读验证，且不要把临时接口作为长期业务接口。
-
-角色矩阵示例：
-
-| 角色 | 后台菜单 | 移动端能力 | 数据范围 |
-|---|---|---|---|
-| 售后师傅 | 维保运营、工单、维保记录、检测报告 | 查看工单、接单、到场、提交记录、生成报告 | 分配给自己或待接单工单 |
-| 客服 | 客户中心、维保运营、客户报修、报告中心、资讯 | 查看客户与报修、调度工单、查看报告 | 公司内部客户服务数据 |
-| 客户账号 | 默认无后台菜单 | 查看绑定客户的计划、记录、报告，提交报修 | 仅绑定客户 |
-
-## 不要做的事
-
-- ❌ 不要把蓝图当成运行时执行器（它不会自动跑接口、不会调度任务）
+  "domainModel": {
+    "entities": [
+      { "table": "crm_customer", "x": 50, "y": 50,
+        "relations": [{ "to": "crm_contact", "type": "1:N", "via": "CustomerId" }],
+        "indexes": [
+          { "name": "uk_crm_customer_osclient_code", "columns": ["OsClient", "Code"], "unique": true, "purpose": "租户内客户编码唯一" },
+          { "name": "idx_crm_customer_osclient_status_createtime", "columns": ["OsClient", "Status", "CreateTime"], "unique": false, "purpose": "客户状态列表" }
+        ] }
+    ]
+  },
+  "menuTree": {
+    "requiredDepth": 2,
+    "groups": [
+      { "name": "客户中心", "children": ["客户管理", "联系人管理"] },
+      { "name": "业务运营", "children": ["工单管理", "服务记录"] },
+      { "name": "报表中心", "children": ["检测报告", "阅读日志"] }
+    ]
+  }
+}
+```
+
+`refs` 内可填的资源类型：`tables` `fields`（"table.field"）`engines` `menus` `v8Events`（"table:eventType"）`dataSources` `printTemplates` `workflows` `pages` `jobs`。
+
+领域层每张实体表还必须描述真实查询需要的 `indexes`（名称、有序字段、唯一性、用途）。关系的 `via` 外键、租户内业务唯一键、幂等键、待办/重试扫描字段都必须评估索引。蓝图或需求一旦明确索引，生成 Manifest 时不得遗漏 `tables[].indexes`，落地必须调用 `microi_create_table_index` 并以 `microi_get_table_indexes` 回读；禁止在 V8 中手写 DDL。
+
+### 关系基数先于表单控件（强制）
+
+- 每条领域关系必须先写清 `1:1`、`N:1` 或 `1:N`，再决定控件。自然语言中的“子表、
+  明细、清单、条目、行项目、多个记录”默认按 `1:N` 建模，除非用户明确说明只关联一条。
+- `1:N` 的 `via` 必须是**子表上的真实外键**，例如
+  `order -> order_detail, type: 1:N, via: OrderId`；Manifest 同时生成子表外键、
+  `(OsClient, OrderId)` 回查索引、隐藏子菜单和主表 `TableChild` 控件。
+- `JoinForm` 只映射“主表保存一个目标 Id，并内嵌一条独立目标记录”的 `N:1`/`1:1`
+  关系。禁止把 `1:N` 蓝图映射为 `JoinForm`，禁止让 `JoinForm` 指向当前表。
+- 如果蓝图写了 `1:N`，而 Manifest 只有主表 `XxxId`/`JoinForm`，或缺少子表 `via`
+  外键、子菜单、回查索引，蓝图检查必须失败，不能进入 `dryRun:false`。
+- 基数仍有歧义时，在任何 MCP 写入前询问用户；不得为了避免询问而选择 `JoinForm`。
+
+后台菜单必须在蓝图阶段规划为至少两级结构。客户、设备、工单、报告、日志、配置等业务域应先形成父级菜单，再把具体 CRUD/报表/日志页面作为子菜单写入 Manifest/MCP；不要把所有模块平铺为一级菜单。
+
+如果是改造已生成系统，蓝图不能停留在建议层。必须列出现有一级菜单、目标父级菜单、每个子菜单的 `ParentId` 迁移关系，并通过 MCP 回读 `sys_menu` 验证迁移完成。
+
+## 角色与权限蓝图
+
+从自然语言需求生成 Microi 业务系统时，必须把角色、菜单权限、移动端能力和数据范围写进蓝图，而不是只建表和菜单。
+
+要求：
+
+- 内部账号默认使用 `sys_user`，角色来源为 `sys_user.RoleIds` 关联 `sys_role`。移动端和接口引擎都应按 `RoleIds` / `V8.CurrentUser` 判断能力。
+- 蓝图中至少列出角色矩阵：角色名、使用端、后台菜单范围、移动端可见页面、关键动作、数据范围。常见角色如超级管理员、客服、售后师傅、客户账号。
+- 多角色账号按能力并集处理；只有服务端已确认的超级管理员（`Level>=9999`）默认拥有全部内部能力。前端角色名、“超级管理员”文案和 `_IsAdmin` 只能控制展示，不能代替后端授权。
+- 客户账号不能简单获得后台客户、工单、报告全量菜单。客户侧数据应通过客户手机号登录 token、客户绑定表和接口行级过滤提供。
+- 菜单权限使用 `sys_rolelimit` 控制入口；接口引擎仍要做业务级权限和行级数据过滤，不能只依赖菜单是否可见。
+- Manifest/MCP 交付后必须回读 `sys_role`、`sys_menu`、`sys_rolelimit`，验证角色存在、菜单授权正确。
+- 如果 MCP 的通用角色写入工具因 `UpdateTime cannot be null` 等系统字段问题失败，要记录工具缺口并使用平台修复后的专用角色工具。临时迁移可用一次性接口引擎和参数化 `V8.Db` 补建角色，但必须回读验证，且不要把临时接口作为长期业务接口。
+
+角色矩阵示例：
+
+| 角色 | 后台菜单 | 移动端能力 | 数据范围 |
+|---|---|---|---|
+| 售后师傅 | 维保运营、工单、维保记录、检测报告 | 查看工单、接单、到场、提交记录、生成报告 | 分配给自己或待接单工单 |
+| 客服 | 客户中心、维保运营、客户报修、报告中心、资讯 | 查看客户与报修、调度工单、查看报告 | 公司内部客户服务数据 |
+| 客户账号 | 默认无后台菜单 | 查看绑定客户的计划、记录、报告，提交报修 | 仅绑定客户 |
+
+## 不要做的事
+
+- ❌ 不要把蓝图当成运行时执行器（它不会自动跑接口、不会调度任务）
 - ❌ 不要在审批工作流（jsPlumb / wf_flowdesign）里用蓝图替代 — 两者并存，蓝图是设计图，工作流是执行图
 - ❌ 不要跳过 `microi_get_blueprint` 直接生成代码 — 会产生幻觉（编造字段名、引用不存在的引擎）
 - ❌ 写入 BlueprintData 必须是合法 JSON 字符串（后端会用 JObject.Parse 校验）

package/skills/datasource-engine/SKILL.md

@@ -1,91 +1,91 @@
----
-name: datasource-engine
-description: Microi 数据源引擎设计、调用与安全规范。用于配置 sys_datasource 的 SQL、V8、JSON 数据源，为表单选项、报表、接口或远程搜索供数，以及通过前后端 V8.DataSourceEngine.Run 调用和验收。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 数据源引擎
-
-## 适用边界
-
-数据源引擎适合复用“只读或计算型数据获取”，支持 `SQL`、`V8`、`JSON`。需要跨表事务、状态推进、扣减库存或外部副作用时应创建接口引擎，不要把数据源当业务命令。
-
-数据源定义保存在 `sys_datasource`，属于平台控制面：创建、修改、删除、匿名开关和角色配置只允许 `Level >= 9999` 的可信管理链路。普通角色只能调用已经授权的数据源。
-
-## 标准调用
-
-前端 V8：
-
-```js
-var result = await V8.DataSourceEngine.Run('product_options', {
-  Keyword: V8.Form.Keyword || ''
-});
-if (result.Code !== 1) V8.Tips(result.Msg || '加载数据失败', false);
-```
-
-后端 V8：
-
-```js
-var result = await V8.DataSourceEngine.RunAsync({
-  DataSourceKey: 'product_options',
-  Keyword: V8.Param.Keyword || ''
-});
-return result;
-```
-
-兼容代码可以使用 callback；新代码优先 `await`。`DataSourceKey` 也兼容数据源 Id，但发布配置应使用稳定、可读且租户内唯一的 Key。
-
-## SQL 数据源
-
-- 动态值必须参数化；禁止拼接用户输入、Token、排序字段或原始 `_Where`。
-- 默认仅查询当前租户数据库，查询中必须保留 `OsClient` 隔离；扩展库由可信配置引用，不能让客户端传连接串。
-- 只选择需要的列并设置结果上限。下拉远程搜索必须分页，不能一次返回整张大表。
-- `$CurrentUser.*$` 等平台替换变量只能用于服务端已验证的当前用户，不能把客户端对象当身份。
-- 菜单数据范围不是任意数据源 SQL 的自动授权。涉及客户、订单、合同等受限数据时，应在 SQL/V8 中显式应用当前用户范围，或改为受菜单授权的 FormEngine/接口引擎。
-- 第三方数据库结构先通过 `microi_inspect_external_database` 发现；数据源只引用已保存的可信 DbKey，不能把浏览器或普通调用者传入的连接字符串交给 `V8.Dbs.Open`。
-
-## V8 与 JSON 数据源
-
-- V8 数据源按接口引擎安全标准处理：校验参数、限制返回字段、避免泄露堆栈和密钥。
-- JSON 数据源只存非敏感静态枚举。密钥、连接串和 Token 不得放入 JSON 或返回给浏览器。
-- 数据源 V8 在 `V8TenantContext` 中只能使用当前租户。普通租户伪造 `OsClient` 不会获得跨租户权限。
-- 匿名数据源必须是无身份、无敏感数据、有限结果且可限流的公开能力；不能因为“只读”就默认匿名。
-
-## 表单字段配置
-
-选择类字段使用数据源引擎时，至少配置：
-
-```json
-{
-  "DataSource": "DataSource",
-  "DataSourceId": "product_options",
-  "SelectLabel": "Name",
-  "SelectSaveField": "Id",
-  "DataSourceSqlRemote": true
-}
-```
-
-保存后回读 `diy_field.Component/Data/Config`，刷新字段/菜单缓存，再从真实表单验证显示值、保存值、搜索、清空和权限。
-
-## MCP 工作流
-
-1. `microi_get_db_schema` 读取 `sys_datasource`、目标表和菜单关系。
-2. 使用 `microi_save_data_source` 保存；写入必须有用户确认。
-3. 回读数据源定义，确认 Key、类型、匿名、角色和代码/SQL。
-4. 用普通角色、无权限角色和管理员分别调用。
-5. 对 SQL 注入、超大分页、跨租户 `OsClient` 和匿名访问做负向测试。
-
-## 缓存与分布式
-
-结果缓存 Key 至少包含 `OsClient + DataSourceKey + 权限主体/角色版本 + 参数哈希`。权限相关结果不能只按数据源 Key 缓存。缓存是优化，不是授权事实源；配置更新后使用共享版本或发布订阅让所有节点失效，不能依赖单机静态字典。
-
-## 验收清单
-
-- [ ] 普通用户不能维护 `sys_datasource`
-- [ ] 调用只在当前租户执行，伪造 `OsClient` 失败
-- [ ] SQL 参数化、有列清单、分页和上限
-- [ ] 敏感数据应用真实业务权限/数据范围
-- [ ] 匿名、角色和错误响应不泄露内部配置
-- [ ] 字段显示值与保存值真实回读通过
-- [ ] 多节点配置更新后无需逐节点重启
+---
+name: datasource-engine
+description: Microi 数据源引擎设计、调用与安全规范。用于配置 sys_datasource 的 SQL、V8、JSON 数据源，为表单选项、报表、接口或远程搜索供数，以及通过前后端 V8.DataSourceEngine.Run 调用和验收。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 数据源引擎
+
+## 适用边界
+
+数据源引擎适合复用“只读或计算型数据获取”，支持 `SQL`、`V8`、`JSON`。需要跨表事务、状态推进、扣减库存或外部副作用时应创建接口引擎，不要把数据源当业务命令。
+
+数据源定义保存在 `sys_datasource`，属于平台控制面：创建、修改、删除、匿名开关和角色配置只允许 `Level >= 9999` 的可信管理链路。普通角色只能调用已经授权的数据源。
+
+## 标准调用
+
+前端 V8：
+
+```js
+var result = await V8.DataSourceEngine.Run('product_options', {
+  Keyword: V8.Form.Keyword || ''
+});
+if (result.Code !== 1) V8.Tips(result.Msg || '加载数据失败', false);
+```
+
+后端 V8：
+
+```js
+var result = await V8.DataSourceEngine.RunAsync({
+  DataSourceKey: 'product_options',
+  Keyword: V8.Param.Keyword || ''
+});
+return result;
+```
+
+兼容代码可以使用 callback；新代码优先 `await`。`DataSourceKey` 也兼容数据源 Id，但发布配置应使用稳定、可读且租户内唯一的 Key。
+
+## SQL 数据源
+
+- 动态值必须参数化；禁止拼接用户输入、Token、排序字段或原始 `_Where`。
+- 默认仅查询当前租户数据库，查询中必须保留 `OsClient` 隔离；扩展库由可信配置引用，不能让客户端传连接串。
+- 只选择需要的列并设置结果上限。下拉远程搜索必须分页，不能一次返回整张大表。
+- `$CurrentUser.*$` 等平台替换变量只能用于服务端已验证的当前用户，不能把客户端对象当身份。
+- 菜单数据范围不是任意数据源 SQL 的自动授权。涉及客户、订单、合同等受限数据时，应在 SQL/V8 中显式应用当前用户范围，或改为受菜单授权的 FormEngine/接口引擎。
+- 第三方数据库结构先通过 `microi_inspect_external_database` 发现；数据源只引用已保存的可信 DbKey，不能把浏览器或普通调用者传入的连接字符串交给 `V8.Dbs.Open`。
+
+## V8 与 JSON 数据源
+
+- V8 数据源按接口引擎安全标准处理：校验参数、限制返回字段、避免泄露堆栈和密钥。
+- JSON 数据源只存非敏感静态枚举。密钥、连接串和 Token 不得放入 JSON 或返回给浏览器。
+- 数据源 V8 在 `V8TenantContext` 中只能使用当前租户。普通租户伪造 `OsClient` 不会获得跨租户权限。
+- 匿名数据源必须是无身份、无敏感数据、有限结果且可限流的公开能力；不能因为“只读”就默认匿名。
+
+## 表单字段配置
+
+选择类字段使用数据源引擎时，至少配置：
+
+```json
+{
+  "DataSource": "DataSource",
+  "DataSourceId": "product_options",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "DataSourceSqlRemote": true
+}
+```
+
+保存后回读 `diy_field.Component/Data/Config`，刷新字段/菜单缓存，再从真实表单验证显示值、保存值、搜索、清空和权限。
+
+## MCP 工作流
+
+1. `microi_get_db_schema` 读取 `sys_datasource`、目标表和菜单关系。
+2. 使用 `microi_save_data_source` 保存；写入必须有用户确认。
+3. 回读数据源定义，确认 Key、类型、匿名、角色和代码/SQL。
+4. 用普通角色、无权限角色和管理员分别调用。
+5. 对 SQL 注入、超大分页、跨租户 `OsClient` 和匿名访问做负向测试。
+
+## 缓存与分布式
+
+结果缓存 Key 至少包含 `OsClient + DataSourceKey + 权限主体/角色版本 + 参数哈希`。权限相关结果不能只按数据源 Key 缓存。缓存是优化，不是授权事实源；配置更新后使用共享版本或发布订阅让所有节点失效，不能依赖单机静态字典。
+
+## 验收清单
+
+- [ ] 普通用户不能维护 `sys_datasource`
+- [ ] 调用只在当前租户执行，伪造 `OsClient` 失败
+- [ ] SQL 参数化、有列清单、分页和上限
+- [ ] 敏感数据应用真实业务权限/数据范围
+- [ ] 匿名、角色和错误响应不泄露内部配置
+- [ ] 字段显示值与保存值真实回读通过
+- [ ] 多节点配置更新后无需逐节点重启

package/skills/dos-orm/SKILL.md

@@ -29,6 +29,15 @@ Dos.ORM 是 Microi.Server 底层 C# ORM。它不是接口引擎里的 `V8.Db`：
 
 ## 安全规则
 
+### 连接生命周期与在线恢复
+
+- 创建事务、准备读取器、打开连接、提交/回滚及批处理任一路径抛异常，都必须释放本层拥有的连接；借用外部事务或批处理连接时不能擅自关闭。保留原始异常，不因 Dispose 失败遮盖原始错误。
+- `DbTrans` 提交成功后先归还连接，再执行提交后通知。通知失败不能把已提交事务报告为回滚，也不能自动重放业务 SQL。调用者仍必须使用 `using`，防止业务异常绕过 Commit/Rollback。
+- `DatabasePoolExhausted`、`DatabaseCapacityExceeded`、`DatabaseEndpointUnreachable` 是不同故障；不要把应用池等待、数据库全局连接限制和慢 SQL 混为一谈。
+- 可信 C# 宿主通过 `Database.GetConnectionPoolSnapshot()` 读取脱敏状态，`ResetConnectionPool()` 只轮换准确匹配的 MySQL/SQL Server 池，`ProbeConnectionPoolAsync` 用原池执行固定 `SELECT 1`。不使用 `ClearAllPools`，不杀借出的事务，不重放 SQL。
+- `BeginIsolatedConnections()` 仅用于有并发限制的可信应急鉴权作用域，设置无池连接与 5 秒连接/命令超时；未知驱动拒绝。不能给普通业务或 V8 增加绕过限流的开关，不能在此作用域内执行清池或把无池探测冒充原池恢复。
+- AI 在线恢复使用 `microi_manage_system_observability(action=ResetDatabasePools)` 的预览、确认和回读协议，详细决策见 [系统日志/监控](../system-observability/SKILL.md)。需要升级含 `database-pools/v1` 的后端和 MCP；事故恢复本身不要求重启数据库/API。
+
 - 数据值全程参数化；`FromSql` 的动态值用 `AddInParameter`。
 - 表名、字段名、排序名不能来自未经白名单验证的用户输入。
 - 保留 `{0}Name{1}` 标识符延迟绑定机制，不能改成字符串替换。
@@ -73,6 +82,12 @@ Dispose 幂等，未 Commit 时自动回滚。事务内异步操作串行执行
 
 ## 验收
 
+- Oracle 原生 `TO_CHAR(value, format[, nlsparam])` 必须保留参数顺序；Provider 不得用
+  字符串扫描交换参数。单参数、嵌套函数、格式串中的逗号、注释与字面量也要原样保留。
+- `ToArray/ToList` 是查询执行与读取边界，堆栈停在这里不能证明对象转换出错。
+  遇到 `ORA-01722`，先用同一账号条件拆分计数/列表，核对最终命令文本与参数类型，
+  再执行最小原生 SQL 对照；确定性的转换/语法错误不得用盲目重试或更改业务过滤掩盖。
+
 - 至少在目标数据库 Provider 运行定向测试，不用 MySQL 结果宣称 Oracle/达梦通过。
 - 覆盖 NULL、DateTime、decimal、Guid、enum、byte[] 和分页边界。
 - 覆盖事务提交/回滚、唯一冲突、超时、取消和连接故障。