@microi.net/cli 5.9.2 → 5.9.4

package/skills/v8-template-engine/SKILL.md

@@ -1,167 +1,167 @@
----
-name: v8-template-engine
-description: Microi V8 模板引擎指南。用于编写表格/表单模板渲染、V8.Result HTML/text 输出、行格式化、徽章、图片和自定义显示逻辑。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi V8 模板引擎（表格/表单 V8 模板）
-
-你正在为 Microi 吾码平台编写 **表格 V8 模板引擎**、**表单 V8 模板引擎** 代码。模板引擎用于在数据渲染后自定义最终展示效果（颜色、徽章、图片、HTML），是表单引擎的高级特性。
-
-## 核心规则
-
-- 模板引擎绑定在【表单属性】的【表格 V8 模板引擎】或【表单 V8 模板引擎】
-- 通过给 `V8.Result` 赋值字符串（HTML 或纯文本）来控制最终渲染结果
-- 在 **表格模板** 中：每行数据都会执行一次，`V8.Form` 是当前行数据
-- 注意：`V8.Form` 此时只能访问到【模块引擎】配置的【查询列】字段；若查询列为空则可访问全部字段
-- 支持 `bootstrap`、`element-ui` 样式类名
-- `V8.EventName` 可能为 `TableTemplateEngine` 或 `FormTemplateEngine`
-- 表格模板同步执行，输出优先级是 `V8.Result` → JavaScript `return` → 原字段值；表单模板异步执行并以 `V8.Result` 为输出
-- 模板结果通过 `v-safe-html`/DOMPurify 净化。`script`、`iframe`、`on*` 事件属性、`javascript:` 等危险内容会被剥离，禁止依赖内联点击事件
-- 业务文本必须 HTML 转义后再拼接；权限、校验、状态写入等业务逻辑必须放后端
-
-模板中需要拼 HTML 时，先定义安全转义函数：
-
-```javascript
-var escapeHtml = function (value) {
-  return String(value == null ? '' : value)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-};
-```
-
-## 状态徽章（Bootstrap 样式）
-
-```javascript
-var value = V8.Form.Zhuangtai;
-if (V8.IsNull(value)) {
-  V8.Result = '';
-} else {
-  var classStr = 'badge-primary';
-  if (value === '禁用')      classStr = 'badge-danger';
-  else if (value === '未通过') classStr = 'badge-warning';
-  else if (value === '待审核') classStr = 'badge-info';
-  else if (value === '通过')   classStr = 'badge-success';
-  V8.Result = '<span class="badge badge-pill ' + classStr + '">' + escapeHtml(value) + '</span>';
-}
-```
-
-可用 Bootstrap 徽章类：`badge-primary`, `badge-secondary`, `badge-success`, `badge-danger`, `badge-warning`, `badge-info`, `badge-light`, `badge-dark`
-
-## 内联样式（颜色高亮）
-
-```javascript
-// 不同业务状态显示不同字体颜色
-if (V8.Form.XuqiuLX === '合并') {
-  V8.Result = '<span style="color:blue;">' + escapeHtml(V8.Form.XuqiuDDH) + '</span>';
-} else if (V8.Form.HebingID) {
-  V8.Result = '<span style="color:#999;">' + escapeHtml(V8.Form.XuqiuDDH) + '</span>';
-} else {
-  V8.Result = escapeHtml(V8.Form.XuqiuDDH);
-}
-```
-
-## 单图列渲染
-
-```javascript
-var html = '';
-var fileServer = V8.SysConfig.FileServer;
-if (!V8.IsNull(V8.Form.GongsiLOGO)) {
-  html = '<img src="' + escapeHtml(fileServer + V8.Form.GongsiLOGO) + '" '
-       + 'alt="公司Logo" '
-       + 'style="height:40px;width:40px;object-fit:cover;margin:5px 0;" />';
-}
-V8.Result = html;
-```
-
-## 多图列渲染（带点击放大）
-
-```javascript
-var html = '';
-var fileServer = V8.SysConfig.FileServer;
-if (!V8.IsNull(V8.Form.TupianMS) && V8.Form.TupianMS.indexOf('[') !== -1) {
-  var imgs = JSON.parse(V8.Form.TupianMS);
-  imgs.forEach(function(item) {
-    var url = escapeHtml(fileServer + item.Path);
-    html += '<a href="' + url + '" target="_blank" rel="noopener noreferrer">'
-         +  '<img src="' + url + '" alt="图片" '
-         +  'style="width:40px;height:40px;object-fit:cover;margin:5px 5px 5px 0;" />'
-         +  '</a>';
-  });
-}
-V8.Result = html;
-```
-
-## 进度条渲染
-
-```javascript
-var percent = V8.Form.Progress || 0;
-var color = '#67C23A';
-if (percent < 30) color = '#F56C6C';
-else if (percent < 70) color = '#E6A23C';
-
-V8.Result =
-  '<div style="width:100%;background:#eee;border-radius:4px;height:16px;position:relative;">'
-  + '<div style="width:' + percent + '%;background:' + color + ';height:100%;border-radius:4px;"></div>'
-  + '<span style="position:absolute;left:50%;top:0;transform:translateX(-50%);color:#333;font-size:12px;line-height:16px;">' + percent + '%</span>'
-  + '</div>';
-```
-
-## 多字段合并显示
-
-```javascript
-// 联系人姓名 + 电话脱敏
-var name = V8.Form.LianxiR || '';
-var phone = V8.Form.LianxiPhone || '';
-if (phone.length === 11) phone = phone.substring(0, 3) + '****' + phone.substring(7);
-V8.Result = '<div><b>' + escapeHtml(name) + '</b><br/><small style="color:#999;">'
-  + escapeHtml(phone) + '</small></div>';
-```
-
-模块引擎已有更轻量的声明式方案：`ViewSchema.Layout.List.Columns` 可用 `Field + Lines +
-TrailingFields` 组成多行列，`Layout.Card` 可配置移动端顶部、右侧、正文、元信息和底部字段。
-仅需要多字段排版、图标、`Tone/Color/Prefix/Suffix` 时优先使用声明式配置；需要复杂条件
-HTML 时再给被引用的 `diy_field` 配置 `V8TmpEngineTable`。两种方式都会复用净化后的模板
-结果，且所有引用字段仍必须在模块查询列或 `_SelectFields` 中。
-
-## 条件性图标
-
-```javascript
-var html = escapeHtml(V8.Form.Title || '');
-if (V8.Form.IsHot === 1) html += ' <i class="fas fa-fire" style="color:#F56C6C;"></i>';
-if (V8.Form.IsNew === 1) html += ' <span class="badge badge-danger">NEW</span>';
-V8.Result = html;
-```
-
-## 与字段值变更事件配合（动态计算）
-
-```javascript
-// 表格模板中根据多个字段计算
-var price = parseFloat(V8.Form.Price) || 0;
-var discount = parseFloat(V8.Form.Discount) || 1;
-var total = (price * discount).toFixed(2);
-var color = total > 1000 ? '#F56C6C' : '#67C23A';
-V8.Result = '<span style="color:' + color + ';font-weight:bold;">¥' + total + '</span>';
-```
-
-## 常见错误
-
-❌ 不要在模板中调用 `V8.FormEngine`（每行都查 → N+1 性能问题）；需要关联数据时在查询列、接口引擎或后端 `DataFilterV8` 预取，只有 `DataFilterV8` 才提供 `V8.CacheData`
-❌ 不要依赖对象/数组的隐式字符串化；`V8.Result` 建议显式输出字符串
-❌ 模板中 `V8.Form` 默认只有【查询列】字段；缺字段就要去模块引擎补查询列  
-❌ 不要在模板里写复杂业务逻辑（应放到接口引擎或 DataFilterV8）  
-❌ 不要输出 `onclick/onerror`、`script/iframe` 或 `javascript:` URL；DOMPurify 会剥离这些内容
-
-## 与 DataFilterV8 的区别
-
-| | DataFilterV8（后端） | 模板引擎（前端） |
-|---|---|---|
-| 运行端 | 服务器 | 浏览器 |
-| 用途 | 加工数据、脱敏、补字段 | 渲染 HTML 样式 |
-| 输出 | `V8.Form.字段 = ...` | `V8.Result = '<html>...</html>'` |
-| 字段范围 | 全部数据 | 仅查询列 |
-| 性能 | 每行执行（可用 `V8.CacheData`） | 浏览器渲染时执行 |
+---
+name: v8-template-engine
+description: Microi V8 模板引擎指南。用于编写表格/表单模板渲染、V8.Result HTML/text 输出、行格式化、徽章、图片和自定义显示逻辑。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 模板引擎（表格/表单 V8 模板）
+
+你正在为 Microi 吾码平台编写 **表格 V8 模板引擎**、**表单 V8 模板引擎** 代码。模板引擎用于在数据渲染后自定义最终展示效果（颜色、徽章、图片、HTML），是表单引擎的高级特性。
+
+## 核心规则
+
+- 模板引擎绑定在【表单属性】的【表格 V8 模板引擎】或【表单 V8 模板引擎】
+- 通过给 `V8.Result` 赋值字符串（HTML 或纯文本）来控制最终渲染结果
+- 在 **表格模板** 中：每行数据都会执行一次，`V8.Form` 是当前行数据
+- 注意：`V8.Form` 此时只能访问到【模块引擎】配置的【查询列】字段；若查询列为空则可访问全部字段
+- 支持 `bootstrap`、`element-ui` 样式类名
+- `V8.EventName` 可能为 `TableTemplateEngine` 或 `FormTemplateEngine`
+- 表格模板同步执行，输出优先级是 `V8.Result` → JavaScript `return` → 原字段值；表单模板异步执行并以 `V8.Result` 为输出
+- 模板结果通过 `v-safe-html`/DOMPurify 净化。`script`、`iframe`、`on*` 事件属性、`javascript:` 等危险内容会被剥离，禁止依赖内联点击事件
+- 业务文本必须 HTML 转义后再拼接；权限、校验、状态写入等业务逻辑必须放后端
+
+模板中需要拼 HTML 时，先定义安全转义函数：
+
+```javascript
+var escapeHtml = function (value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+};
+```
+
+## 状态徽章（Bootstrap 样式）
+
+```javascript
+var value = V8.Form.Zhuangtai;
+if (V8.IsNull(value)) {
+  V8.Result = '';
+} else {
+  var classStr = 'badge-primary';
+  if (value === '禁用')      classStr = 'badge-danger';
+  else if (value === '未通过') classStr = 'badge-warning';
+  else if (value === '待审核') classStr = 'badge-info';
+  else if (value === '通过')   classStr = 'badge-success';
+  V8.Result = '<span class="badge badge-pill ' + classStr + '">' + escapeHtml(value) + '</span>';
+}
+```
+
+可用 Bootstrap 徽章类：`badge-primary`, `badge-secondary`, `badge-success`, `badge-danger`, `badge-warning`, `badge-info`, `badge-light`, `badge-dark`
+
+## 内联样式（颜色高亮）
+
+```javascript
+// 不同业务状态显示不同字体颜色
+if (V8.Form.XuqiuLX === '合并') {
+  V8.Result = '<span style="color:blue;">' + escapeHtml(V8.Form.XuqiuDDH) + '</span>';
+} else if (V8.Form.HebingID) {
+  V8.Result = '<span style="color:#999;">' + escapeHtml(V8.Form.XuqiuDDH) + '</span>';
+} else {
+  V8.Result = escapeHtml(V8.Form.XuqiuDDH);
+}
+```
+
+## 单图列渲染
+
+```javascript
+var html = '';
+var fileServer = V8.SysConfig.FileServer;
+if (!V8.IsNull(V8.Form.GongsiLOGO)) {
+  html = '<img src="' + escapeHtml(fileServer + V8.Form.GongsiLOGO) + '" '
+       + 'alt="公司Logo" '
+       + 'style="height:40px;width:40px;object-fit:cover;margin:5px 0;" />';
+}
+V8.Result = html;
+```
+
+## 多图列渲染（带点击放大）
+
+```javascript
+var html = '';
+var fileServer = V8.SysConfig.FileServer;
+if (!V8.IsNull(V8.Form.TupianMS) && V8.Form.TupianMS.indexOf('[') !== -1) {
+  var imgs = JSON.parse(V8.Form.TupianMS);
+  imgs.forEach(function(item) {
+    var url = escapeHtml(fileServer + item.Path);
+    html += '<a href="' + url + '" target="_blank" rel="noopener noreferrer">'
+         +  '<img src="' + url + '" alt="图片" '
+         +  'style="width:40px;height:40px;object-fit:cover;margin:5px 5px 5px 0;" />'
+         +  '</a>';
+  });
+}
+V8.Result = html;
+```
+
+## 进度条渲染
+
+```javascript
+var percent = V8.Form.Progress || 0;
+var color = '#67C23A';
+if (percent < 30) color = '#F56C6C';
+else if (percent < 70) color = '#E6A23C';
+
+V8.Result =
+  '<div style="width:100%;background:#eee;border-radius:4px;height:16px;position:relative;">'
+  + '<div style="width:' + percent + '%;background:' + color + ';height:100%;border-radius:4px;"></div>'
+  + '<span style="position:absolute;left:50%;top:0;transform:translateX(-50%);color:#333;font-size:12px;line-height:16px;">' + percent + '%</span>'
+  + '</div>';
+```
+
+## 多字段合并显示
+
+```javascript
+// 联系人姓名 + 电话脱敏
+var name = V8.Form.LianxiR || '';
+var phone = V8.Form.LianxiPhone || '';
+if (phone.length === 11) phone = phone.substring(0, 3) + '****' + phone.substring(7);
+V8.Result = '<div><b>' + escapeHtml(name) + '</b><br/><small style="color:#999;">'
+  + escapeHtml(phone) + '</small></div>';
+```
+
+模块引擎已有更轻量的声明式方案：`ViewSchema.Layout.List.Columns` 可用 `Field + Lines +
+TrailingFields` 组成多行列，`Layout.Card` 可配置移动端顶部、右侧、正文、元信息和底部字段。
+仅需要多字段排版、图标、`Tone/Color/Prefix/Suffix` 时优先使用声明式配置；需要复杂条件
+HTML 时再给被引用的 `diy_field` 配置 `V8TmpEngineTable`。两种方式都会复用净化后的模板
+结果，且所有引用字段仍必须在模块查询列或 `_SelectFields` 中。
+
+## 条件性图标
+
+```javascript
+var html = escapeHtml(V8.Form.Title || '');
+if (V8.Form.IsHot === 1) html += ' <i class="fas fa-fire" style="color:#F56C6C;"></i>';
+if (V8.Form.IsNew === 1) html += ' <span class="badge badge-danger">NEW</span>';
+V8.Result = html;
+```
+
+## 与字段值变更事件配合（动态计算）
+
+```javascript
+// 表格模板中根据多个字段计算
+var price = parseFloat(V8.Form.Price) || 0;
+var discount = parseFloat(V8.Form.Discount) || 1;
+var total = (price * discount).toFixed(2);
+var color = total > 1000 ? '#F56C6C' : '#67C23A';
+V8.Result = '<span style="color:' + color + ';font-weight:bold;">¥' + total + '</span>';
+```
+
+## 常见错误
+
+❌ 不要在模板中调用 `V8.FormEngine`（每行都查 → N+1 性能问题）；需要关联数据时在查询列、接口引擎或后端 `DataFilterV8` 预取，只有 `DataFilterV8` 才提供 `V8.CacheData`
+❌ 不要依赖对象/数组的隐式字符串化；`V8.Result` 建议显式输出字符串
+❌ 模板中 `V8.Form` 默认只有【查询列】字段；缺字段就要去模块引擎补查询列  
+❌ 不要在模板里写复杂业务逻辑（应放到接口引擎或 DataFilterV8）  
+❌ 不要输出 `onclick/onerror`、`script/iframe` 或 `javascript:` URL；DOMPurify 会剥离这些内容
+
+## 与 DataFilterV8 的区别
+
+| | DataFilterV8（后端） | 模板引擎（前端） |
+|---|---|---|
+| 运行端 | 服务器 | 浏览器 |
+| 用途 | 加工数据、脱敏、补字段 | 渲染 HTML 样式 |
+| 输出 | `V8.Form.字段 = ...` | `V8.Result = '<html>...</html>'` |
+| 字段范围 | 全部数据 | 仅查询列 |
+| 性能 | 每行执行（可用 `V8.CacheData`） | 浏览器渲染时执行 |

package/skills/v8-utilities/SKILL.md

@@ -1,104 +1,104 @@
----
-name: v8-utilities
-description: Microi V8 全局对象、上下文变量和通用函数索引。用于查询某个 V8 函数是否存在、区分前端与后端 API，或使用 V8.Method、Base64、EncryptHelper、V8.WeChat、Action、CurrentUser、SysConfig、OsClient、扫码和客户端导航工具。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi V8 通用能力与函数索引
-
-本 Skill 是 V8 能力的路由入口，不替代 CRUD、HTTP、缓存、文件、图片、Office、
-工作流等专项 Skill。遇到“吾码有没有某个函数”“这个 API 在前端还是后端”
-或官网函数列表同步任务时，先在这里确定运行端和正式名称，再读取专项 Skill。
-
-## 先判断运行端
-
-| 运行端 | 典型位置 | API 特征 |
-|---|---|---|
-| 前端 | 字段事件、按钮、列表、InFormV8、SubmitFormV8、OutFormV8 | 浏览器 Promise/回调、弹窗、路由、`V8.Print`、扫码 |
-| 后端 | 接口引擎、SubmitBeforeServerV8、SubmitAfterServerV8、DataFilterV8 | `V8.Db`、事务、缓存、Office、加密、服务端 HTTP |
-
-同名对象不保证两端方法一致。例如前端 `V8.Base64.encode/decode` 与后端
-`V8.Base64.StringToBase64/Base64ToString` 不同；前端标准运行时没有公开
-`V8.ModuleEngine`，后端才有模块引擎对象。
-
-## 必读索引
-
-- 前端全部上下文、表单/列表、导航、网络、引擎和工具：
-  `references/client-api-index.md`
-- 后端上下文、`V8.Method`、Base64、加密、异步与扩展对象：
-  `references/server-api-index.md`
-- 平台 HTTP 路由、动态路由与管理接口边界：
-  `references/platform-http-routes.md`
-- 蓝牙标签/小票打印：
-  `../v8-frontend-events/references/bluetooth-print.md`
-
-若函数未出现在上述索引或当前源码定义中，不得按名字猜测。先搜索
-`Microi.Client/src/views/form-engine/diy-components/v8-api-definitions.js`、
-`v8-api-server-definitions.js`、V8 宿主接口和官网中文函数列表。
-
-邮箱相关能力读取 [email-engine](../email-engine/SKILL.md)：`V8.Email` 包含
-`ProtectCredential / TestConnection / ListFolders / Fetch / Inspect / GetMessage /
-GetAttachment / SetFlags / Move / Send / StoreSent`。
-业务使用 `mci-email` 接口引擎，MCP 使用 `microi_email_query / microi_email_manage / microi_email_send`。
-
-## 常用通用写法
-
-```javascript
-// 两端通用的租户/用户上下文，具体字段按当前上下文判空
-var osClient = V8.OsClient;
-var userId = V8.CurrentUser && V8.CurrentUser.Id;
-
-// 后端稳定标识与时间
-var id = V8.Method.NewUlid();
-var now = DateNow('yyyy-MM-dd HH:mm:ss');
-var timestamp = V8.Method.GetTimestamp();
-
-// 后端 Base64
-var encoded = V8.Base64.StringToBase64('吾码');
-var decoded = V8.Base64.Base64ToString(encoded);
-
-// 前端 Base64
-var clientEncoded = V8.Base64.encode('吾码');
-var clientDecoded = V8.Base64.decode(clientEncoded);
-```
-
-## 能力选择
-
-- 日期基础函数由新版后端运行时自举，不能要求租户先配置 DateNow 才能安装应用。全局函数管理使用系统设置子表 `mci_global_function`，按 `SysConfigId + Runtime(Client/Server) + FunctionName` 隔离，一行一个同名 function 声明；用 `V8.Method.ValidateGlobalFunction` 只解析验证，不执行源码。
-- 原有前后端全局 V8 必须保留，合并顺序为内置日期、函数库、租户原有代码；同名原有函数优先。不得用官方全局脚本整段覆盖客户脚本。函数库种子 `InsertIfMissing`，不得升级覆盖客户已改源码。
-- 列表和合并代码走 L1/Redis，表单引擎真实提交后更新租户版本并通知其它节点；回滚不变更版本。禁止通过直接 SQL 修改函数库规避失效。前端已打开页面需要刷新。
-
-## 受信固定步长运行时发现
-
-`V8.Method.RunPlatformApiRuntime({RuntimeKey:'fixed-step-simulation',Action,Param})` 属于需后端正式安装的通用原子。动作是 DescribeInvocation/CreateInitialState/AdvanceBatch/Project/ObserveOwnedRoom/StopOwnedRoom/DrainOwnedRoom；精确引擎Key由后台已审批目录限制，不能用通用private转发接口原样接受玩家信封。Param只能承载经接口引擎授权后的数据，不能指定Tenant/EngineKey/NodeId/客户端时钟作为真实上下文。Observe是提交前有界调度提示，后续须重新核DB，不是提交回执；终局用Drain保留当前请求提交机会，Stop则立即取消。规则程序集入口与hash须由私有后端发行组合固定，V8/MCP不提供上传即执行的注册能力。详细边界见unity-integration及后端V8主文档；线上缺原子时明确未安装，不能用Job/SignalR冒充。
-
-固定步运行时的临时拒绝仅使用 `DataAppend.ErrorCode` 六码白名单：KernelBusy/HostMemoryPressure/RoomStillDraining/CoordinatorStopping/StaleLease/ComputeBudgetExceeded，并要求 `Retryable===true`。Managed须显式catch-return稳定Code0并回滚，客户端有界同键重试；禁止按中文Msg或带行号异常猜测重试，更不能把授权/来源/未知失败当临时成功。此兼容扩展不增加审批表/配置或MCP任意注册入口。
-
-普通租户的编译证明默认 `TenantInstallation`，保留真实 Installed 回执及旧摘要。官方同租户发布源禁止安装自己，只能由后端发行组合明确固定 `OfficialPublishedSnapshot`：`InstallRecordId` 绑定 `mic_data_version.Id`，原始 `Data` 的UTF-8 SHA-256另固定于编译回执并参与独立审批摘要。该类别与快照摘要不从Param或自由表字段选择、不新增表字段、不伪造Installed。受信官方身份、当前Published/审批有效指针、Verified包hash/size/HDFS、不可变快照、V3 Completed源码hash及实际DLL依赖须全部匹配；当前状态变化、软删或主库不可用下次调用立即拒绝，旧历史存在不足以授权。跨租户仍拒绝，结构发布不等于后端安装或代码审批。审批表纳入通用强制管理员清单，普通用户即使误授表/菜单权限仍不得改授权状态；V8Limit和ReadPrimary不是写权限。
-
-## 平台兼容入口索引
-
-下列旧 HTTP 地址仍由受控兼容链路识别，不能据此绕过 DiyToken、租户或权限校验：`/api/FormEngine/GetSysConfig`、`/api/Os/GetDateTimeNow`、`/api/SysLog/AddSysLog`、`/api/SysUser/`。畅捷通 V2 回调在接口引擎中编排，可信后端只提供当前租户绑定的 `V8.Method.DecodeChanjetCallbackV2` 原子。
-
-| 需求 | 专项 Skill |
-|---|---|
-| 表单 CRUD、`_Where` | `v8-crud-api`、`v8-sql-query` |
-| HTTP/第三方接口 | `v8-http-integration` |
-| TCP 原始字节/网络小票机/设备 | `v8-tcp-integration` |
-| Redis/Hash | `v8-cache-pattern` |
-| 文件/HDFS | `v8-file-upload` |
-| 图片 | `v8-image-processing` |
-| Excel/Word/PPT/邮件 | `v8-export-import` |
-| 微信支付签名、授权头、API v3 AES-GCM 解密 | `references/server-api-index.md`；安全边界见 `v8-security` |
-| 前端事件/打印/扫码 | `v8-frontend-events` |
-| 后端表单事件 | `v8-table-event` |
-| 接口配置/流式响应/异步/后台任务 | `v8-api-config` |
-
-## 不可越过的边界
-
-- 平台能力优先使用 `V8.*`，不要假设全局 `System` 可访问任意 CLR 类型。
-- `V8.SysConfig`、`V8.OsClientModel`、`V8.ClientModel` 可能含连接串、密钥和供应商配置，不直接返回前端或写日志。
-- 摘要算法不是密码存储。新密码不使用 MD5/SHA1/SHA256 直接保存。
-- `setTimeout`、`Task.Run` 不能承担请求返回后的可靠后台执行。
-- 前端值只可用于交互；权限、事务和最终业务校验必须在可信后端执行。
+---
+name: v8-utilities
+description: Microi V8 全局对象、上下文变量和通用函数索引。用于查询某个 V8 函数是否存在、区分前端与后端 API，或使用 V8.Method、Base64、EncryptHelper、V8.WeChat、Action、CurrentUser、SysConfig、OsClient、扫码和客户端导航工具。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 通用能力与函数索引
+
+本 Skill 是 V8 能力的路由入口，不替代 CRUD、HTTP、缓存、文件、图片、Office、
+工作流等专项 Skill。遇到“吾码有没有某个函数”“这个 API 在前端还是后端”
+或官网函数列表同步任务时，先在这里确定运行端和正式名称，再读取专项 Skill。
+
+## 先判断运行端
+
+| 运行端 | 典型位置 | API 特征 |
+|---|---|---|
+| 前端 | 字段事件、按钮、列表、InFormV8、SubmitFormV8、OutFormV8 | 浏览器 Promise/回调、弹窗、路由、`V8.Print`、扫码 |
+| 后端 | 接口引擎、SubmitBeforeServerV8、SubmitAfterServerV8、DataFilterV8 | `V8.Db`、事务、缓存、Office、加密、服务端 HTTP |
+
+同名对象不保证两端方法一致。例如前端 `V8.Base64.encode/decode` 与后端
+`V8.Base64.StringToBase64/Base64ToString` 不同；前端标准运行时没有公开
+`V8.ModuleEngine`，后端才有模块引擎对象。
+
+## 必读索引
+
+- 前端全部上下文、表单/列表、导航、网络、引擎和工具：
+  `references/client-api-index.md`
+- 后端上下文、`V8.Method`、Base64、加密、异步与扩展对象：
+  `references/server-api-index.md`
+- 平台 HTTP 路由、动态路由与管理接口边界：
+  `references/platform-http-routes.md`
+- 蓝牙标签/小票打印：
+  `../v8-frontend-events/references/bluetooth-print.md`
+
+若函数未出现在上述索引或当前源码定义中，不得按名字猜测。先搜索
+`Microi.Client/src/views/form-engine/diy-components/v8-api-definitions.js`、
+`v8-api-server-definitions.js`、V8 宿主接口和官网中文函数列表。
+
+邮箱相关能力读取 [email-engine](../email-engine/SKILL.md)：`V8.Email` 包含
+`ProtectCredential / TestConnection / ListFolders / Fetch / Inspect / GetMessage /
+GetAttachment / SetFlags / Move / Send / StoreSent`。
+业务使用 `mci-email` 接口引擎，MCP 使用 `microi_email_query / microi_email_manage / microi_email_send`。
+
+## 常用通用写法
+
+```javascript
+// 两端通用的租户/用户上下文，具体字段按当前上下文判空
+var osClient = V8.OsClient;
+var userId = V8.CurrentUser && V8.CurrentUser.Id;
+
+// 后端稳定标识与时间
+var id = V8.Method.NewUlid();
+var now = DateNow('yyyy-MM-dd HH:mm:ss');
+var timestamp = V8.Method.GetTimestamp();
+
+// 后端 Base64
+var encoded = V8.Base64.StringToBase64('吾码');
+var decoded = V8.Base64.Base64ToString(encoded);
+
+// 前端 Base64
+var clientEncoded = V8.Base64.encode('吾码');
+var clientDecoded = V8.Base64.decode(clientEncoded);
+```
+
+## 能力选择
+
+- 日期基础函数由新版后端运行时自举，不能要求租户先配置 DateNow 才能安装应用。全局函数管理使用系统设置子表 `mci_global_function`，按 `SysConfigId + Runtime(Client/Server) + FunctionName` 隔离，一行一个同名 function 声明；用 `V8.Method.ValidateGlobalFunction` 只解析验证，不执行源码。
+- 原有前后端全局 V8 必须保留，合并顺序为内置日期、函数库、租户原有代码；同名原有函数优先。不得用官方全局脚本整段覆盖客户脚本。函数库种子 `InsertIfMissing`，不得升级覆盖客户已改源码。
+- 列表和合并代码走 L1/Redis，表单引擎真实提交后更新租户版本并通知其它节点；回滚不变更版本。禁止通过直接 SQL 修改函数库规避失效。前端已打开页面需要刷新。
+
+## 受信固定步长运行时发现
+
+`V8.Method.RunPlatformApiRuntime({RuntimeKey:'fixed-step-simulation',Action,Param})` 属于需后端正式安装的通用原子。动作是 DescribeInvocation/CreateInitialState/AdvanceBatch/Project/ObserveOwnedRoom/StopOwnedRoom/DrainOwnedRoom；精确引擎Key由后台已审批目录限制，不能用通用private转发接口原样接受玩家信封。Param只能承载经接口引擎授权后的数据，不能指定Tenant/EngineKey/NodeId/客户端时钟作为真实上下文。Observe是提交前有界调度提示，后续须重新核DB，不是提交回执；终局用Drain保留当前请求提交机会，Stop则立即取消。规则程序集入口与hash须由私有后端发行组合固定，V8/MCP不提供上传即执行的注册能力。详细边界见unity-integration及后端V8主文档；线上缺原子时明确未安装，不能用Job/SignalR冒充。
+
+固定步运行时的临时拒绝仅使用 `DataAppend.ErrorCode` 六码白名单：KernelBusy/HostMemoryPressure/RoomStillDraining/CoordinatorStopping/StaleLease/ComputeBudgetExceeded，并要求 `Retryable===true`。Managed须显式catch-return稳定Code0并回滚，客户端有界同键重试；禁止按中文Msg或带行号异常猜测重试，更不能把授权/来源/未知失败当临时成功。此兼容扩展不增加审批表/配置或MCP任意注册入口。
+
+普通租户的编译证明默认 `TenantInstallation`，保留真实 Installed 回执及旧摘要。官方同租户发布源禁止安装自己，只能由后端发行组合明确固定 `OfficialPublishedSnapshot`：`InstallRecordId` 绑定 `mic_data_version.Id`，原始 `Data` 的UTF-8 SHA-256另固定于编译回执并参与独立审批摘要。该类别与快照摘要不从Param或自由表字段选择、不新增表字段、不伪造Installed。受信官方身份、当前Published/审批有效指针、Verified包hash/size/HDFS、不可变快照、V3 Completed源码hash及实际DLL依赖须全部匹配；当前状态变化、软删或主库不可用下次调用立即拒绝，旧历史存在不足以授权。跨租户仍拒绝，结构发布不等于后端安装或代码审批。审批表纳入通用强制管理员清单，普通用户即使误授表/菜单权限仍不得改授权状态；V8Limit和ReadPrimary不是写权限。
+
+## 平台兼容入口索引
+
+下列旧 HTTP 地址仍由受控兼容链路识别，不能据此绕过 DiyToken、租户或权限校验：`/api/FormEngine/GetSysConfig`、`/api/Os/GetDateTimeNow`、`/api/SysLog/AddSysLog`、`/api/SysUser/`。畅捷通 V2 回调在接口引擎中编排，可信后端只提供当前租户绑定的 `V8.Method.DecodeChanjetCallbackV2` 原子。
+
+| 需求 | 专项 Skill |
+|---|---|
+| 表单 CRUD、`_Where` | `v8-crud-api`、`v8-sql-query` |
+| HTTP/第三方接口 | `v8-http-integration` |
+| TCP 原始字节/网络小票机/设备 | `v8-tcp-integration` |
+| Redis/Hash | `v8-cache-pattern` |
+| 文件/HDFS | `v8-file-upload` |
+| 图片 | `v8-image-processing` |
+| Excel/Word/PPT/邮件 | `v8-export-import` |
+| 微信支付签名、授权头、API v3 AES-GCM 解密 | `references/server-api-index.md`；安全边界见 `v8-security` |
+| 前端事件/打印/扫码 | `v8-frontend-events` |
+| 后端表单事件 | `v8-table-event` |
+| 接口配置/流式响应/异步/后台任务 | `v8-api-config` |
+
+## 不可越过的边界
+
+- 平台能力优先使用 `V8.*`，不要假设全局 `System` 可访问任意 CLR 类型。
+- `V8.SysConfig`、`V8.OsClientModel`、`V8.ClientModel` 可能含连接串、密钥和供应商配置，不直接返回前端或写日志。
+- 摘要算法不是密码存储。新密码不使用 MD5/SHA1/SHA256 直接保存。
+- `setTimeout`、`Task.Run` 不能承担请求返回后的可靠后台执行。
+- 前端值只可用于交互；权限、事务和最终业务校验必须在可信后端执行。