@microi.net/cli 6.0.9 → 6.1.1

package/skills/v8-tcp-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: v8-tcp-integration
-description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
+description: Microi 后端 TCP 与通用 IoT 集成规范。用于 V8.Tcp 一次性客户端、V8.IoT.Send 设备原连接下行、可配置拆帧/校验、跨节点路由，以及 MQTT/HTTP 能力选择、设备权限、幂等和真实验收。
 ---
 
 > **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
@@ -20,6 +20,7 @@ description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp
 | RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
 | 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
 | 设备原始 TCP 上报并保持连接等待应答 | API 宿主可选的 `TcpIngressRulesJson` 入站监听；固定租户与接口引擎，协议帧交给接口引擎处理 |
+| 设备已主动连接平台，需要发送控制命令 | `V8.IoT.Send`，沿已授权原连接下行；不依赖某个厂家 |
 | TLS、任意协议、可由 V8 动态开端口、自定义连接池 | 当前不提供；单独评估安全边界和传输实现 |
 
 平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
@@ -34,7 +35,73 @@ description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp
 
 启用前优先限制来源网段与云安全组，设置帧长、连接数和空闲时间上限；CRC、设备号都不是身份认证。经 CLB 时核对后端实际看到的源 IP，且当前不解析 Proxy Protocol v2 报头。全网例外必须有业务接口内的设备身份/授权校验、幂等与异常连接监控；如果协议本身没有不可伪造的设备凭据，应明确记录剩余风险，并在能识别来源时收窄规则及云侧放行。Docker 在同一个 API service 显式增加如 `19011:1885/tcp`（宿主机对外端口:容器内端口）的映射；不要把 `/apiengine/...` URL、HTTP 的 `80/1052` 或 `V8.Tcp.Send` 当作设备端 TCP 监听。新执行的在线一键安装器会在 `61600+` 连续宿主端口段末尾追加 MQTT/TCP 映射；离线默认宿主 `7010/7011`，都映射至 API 容器 `1883/1885` 并尝试放行宿主机防火墙。窄来源方案仍需云安全组/CLB 人工限源；已有 Compose 不会自动补映射，SaaS 内部端口改变后须同步 Compose。TCP 配置、引擎安全位或端口失败时仅 TCP 状态为 `Faulted`，HTTP 仍可健康；验收必须确认 TCP `Listening` 状态/监听日志、端口探测和合法心跳应答，再核对设备数据。只连上端口不能证明已回 ACK；当前没有对外的 TCP 状态 HTTP 端点，不能把 HTTP 健康当成 TCP 就绪。配置、回环测试、设备联调的详细步骤见官网中文后端 V8 页面；本地回环不等于客户真机已联网。
 
-## API 契约
+## 已建立 IoT 连接的主动下行
+
+`V8.IoT` 是受限的设备原连接下行扩展。
+设备主动连接平台且需要云端控制时，使用 `V8.IoT.Send({DeviceId, CommandId, FrameHex, ExpireSeconds})`，
+不能用 `V8.Tcp.Send` 新建连接代替原设备连接。须配套 Core、V8Engine 和 API 宿主更新；
+缺失 `TcpIngressRulesJson.downlink` 或 `enabled:false` 时不启用，修改配置后重启现有 API。
+
+`V8.IoT` 负责连接路由与传输状态；操作码、流水号、厂家 HTTP/MQTT 选择、设备权限和回执
+放在接口引擎。禁止在 Core/V8Engine 中新增按厂家名、业务表名或设备编号分支。
+MQTT 设备继续使用 MQTT 引擎，平台主动连接设备使用 `V8.Tcp`，厂家云接口使用 `V8.Http`。
+
+接入另一协议先读取厂家真实说明，再检查既有 `framing` 描述是否覆盖：
+
+- 省略 `framing` 保持历史 U16BE/XMODEM，不改变既有配置含义。
+- 显式 `framing.mode` 支持 `LengthPrefix`、`FixedLength`、`Delimiter`；帧头 0–32 字节、帧尾 0–16 字节。
+- `lengthBytes` 为 1/2/4，`lengthByteOrder` 为 BigEndian/LittleEndian；长度加 `lengthAdjustment` 得总帧长。
+- `fixedLength` 为固定帧总长；结束符模式必须有帧尾且载荷不含未转义结束符。
+- `checksum` 为 Crc16Xmodem/Crc16Modbus/None；`checksumByteOrder` 与 `checksumStartOffset` 可配置。
+- 上报地址由 `deviceOffset/deviceLength` 定义；下行偏移可用 `downlinkDeviceOffset`，地址不能与结构字段重叠。
+- 普通 ACK 关联规则继续严格执行；主动下行用同一结构描述单独核对设备，不通过缩短关联区间绕过校验。
+- 当前每个 API 进程只有一套监听规则；没有单端口多协议自动探测、TLS 或任意转义解码。
+  超出能力时补通用适配器，不声称全部协议均已支持；完整配置示例与限制见官网后端 V8 主文档。
+
+```javascript
+// 已完成设备行权限/操作权限校验，且业务指令已提交；由受权派发接口调用。
+return V8.IoT.Send({
+  DeviceId: deviceAddressHex,
+  CommandId: committedCommandId,
+  FrameHex: completeProtocolFrameHex,
+  ExpireSeconds: 30
+});
+```
+
+- `downlink` 必须声明 `deviceOffset`、`deviceLength` 和 `sendApiEngineKeys`；其余队列、有效期、
+  去重、租约和轮询限额见官网中文后端 V8 原页面。新设置继续使用既有 SaaS 规则，不加环境变量。
+- 内部上报引擎确认设备身份和绑定后，每个成功响应显式返回 `Data.IoTDeviceId` 及正常
+  `Data.ResponseFrameHex`；地址必须与物理帧匹配。ACK 写入后才登记下行连接；明确免应答消息按下文处理。
+- 控制接口必须校验当前用户的设备与操作权限；原子从可信执行上下文获取租户、接口 Key、
+  登录用户或可信任务身份，并按管理员的 Key 白名单约束调用。禁止透传前端任意报文。
+- `DeviceId` 为定长设备地址十六进制，由业务记录映射；`CommandId` 稳定且长期持久去重。
+  `FrameHex` 为无分隔符的完整协议帧。仅四个参数允许传入，租户/Host/Port 不接受。
+- `Code=1` 只表示接受指令或发现同编号既有指令。`Queued`、`Sending`、`Written`、
+  `Unknown`、`Expired` 是传输状态；设备执行结果由协议回执确认。`Sending/Unknown` 禁止换号重发。
+- 业务记录/outbox 先提交，再由派发任务调用原子；Redis 和设备动作不能随数据库回滚。
+  Redis 队列绑定连接代次，旧连接不能清除新连接租约，已经开始发送的指令不自动重投。
+- 保持正常 ACK 的关联规则；主动下行独立校验目标、结构和 CRC，无需缩短原关联长度。
+  原 ACK 与控制指令串行写入同一 Socket，重连与 Redis 故障必须覆盖。
+- 单元/Socket 回环、真实 Redis 多节点、真实设备回执和物理动作是不同验收层；不得相互替代。
+
+### 多控制功能与免应答回执
+
+- `V8.IoT.Send` 不筛选具体命令/操作码。设备开关、温度/阈值、定时数组、模式、报警提示等，
+  共用原子；命令目录、字段宽度/顺序/单位、机型范围和权限由接口引擎编排，不再加厂家专属 C# 方法。
+- 区分“报警上报/恢复”“远程报警提示开关”“消音/故障复位”。协议只有上报时，不能虚构清警指令，
+  也不能以修改平台报警记录代替设备故障消除。
+- 业务记录保存稳定 `CommandId` 与设备流水号映射；回执按设备、回执命令、子码、流水号及长度匹配。
+  不同命令的成功码、流水号位置甚至应答命令可能不同，未知值保持未知，不统一写死。
+- 温度范围、型号/固件语义或报文长度不明确的动作默认拒绝，等待厂家确认后修改可信配置。
+  前端不能上传命令目录、范围、成功码、完整报文或可执行表达式覆盖后端规则。
+- 控制回执无需平台再 ACK 时，受保护规则根节点显式配置 `allowNoResponse:true`，内部接口逐帧返回
+  `{Code:1,Data:{IoTDeviceId:authorizedAddressHex,ResponseMode:'None'}}`；不提供 `ResponseFrameHex` 属性。
+  默认关闭且必须布尔值，更新后重启 API；只有数值 Code=1 和有效帧才接受，仍复核设备授权。
+- `None` 表示消息已处理且零字节写回，不能代表设备已执行；缺失响应、空返回、失败或错误模式不能冒充 None。
+  正常应答继续使用 `ResponseFrameHex`（可选 `ResponseMode:'Reply'`）；心跳仍按厂家协议正常回 ACK。
+- 回归覆盖可变载荷、不同回执格式、回执后继续心跳/控制、授权撤销、无效模式和存量失败 ACK。
+
+## API 契约：一次性 TCP 客户端
 
 | 方法 | 行为 |
 |---|---|

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

@@ -86,6 +86,7 @@ var clientDecoded = V8.Base64.decode(clientEncoded);
 | 表单 CRUD、`_Where` | `v8-crud-api`、`v8-sql-query` |
 | HTTP/第三方接口 | `v8-http-integration` |
 | TCP 原始字节/网络小票机/设备 | `v8-tcp-integration` |
+| 通用 IoT 设备原连接控制、`V8.IoT.Send`、协议拆帧与跨节点去重 | `v8-tcp-integration`；MQTT 设备使用 `v8-mq-mqtt` |
 | Redis/Hash | `v8-cache-pattern` |
 | 文件/HDFS | `v8-file-upload` |
 | 图片 | `v8-image-processing` |