@microi.net/cli 5.8.4 → 5.8.6

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

@@ -1,147 +1,147 @@
----
-name: v8-tcp-integration
-description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi V8 TCP 原始字节集成
-
-使用后端 `V8.Tcp` 完成一次性 TCP 连接、原始字节写入和可选的有界响应读取。典型场景是 RAW/JetDirect 9100 网络小票机、串口服务器和 PLC；具体协议帧、校验码与打印业务仍由接口引擎编排。
-
-文档维护时，只在 `microi.doc/docs/doc/v8-engine/v8-server.md` 原位更新后端 API；不要新建重复页面，也不要手工维护英文文档。改变公共契约时同步后端源码/测试、Microi.Client Monaco 定义、Microi.Agent 类型与生成知识、AI Skill 镜像。
-
-## 先判断是否适用
-
-| 需求 | 选择 |
-|---|---|
-| 后端向设备 TCP 端口发送原始字节 | `V8.Tcp` |
-| HTTP/HTTPS API | `V8.Http`，不要用 TCP 重写 HTTP |
-| RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
-| 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
-| 长连接、TCP 服务端监听、TLS、自定义连接池 | 当前 `V8.Tcp` 不提供；设计独立网关/Worker |
-
-平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
-
-## API 契约
-
-| 方法 | 行为 |
-|---|---|
-| `V8.Tcp.Send({...})` | 连接、发送、关闭，返回 `DosResult` |
-| `await V8.Tcp.SendAsync({...})` | 当前请求内异步发送 |
-| `V8.Tcp.SendAndReceive({...})` | 发送后读取响应，再关闭 |
-| `await V8.Tcp.SendAndReceiveAsync({...})` | 当前请求内异步发送并读取响应 |
-
-必填目标参数：
-
-- `Host`：主机名或 IP；只允许主机，不传 `tcp://` URL。
-- `Port`：1-65535。
-
-发送内容必须且只能选择一组：
-
-- `Bytes`（别名 `RawBytes`、`ByteArray`）：每项为 0-255 的整数。
-- `ByteBase64`（别名 `BytesBase64`、`Base64`）。
-- `Hex`：允许空格、`0x`、`-`、`:`、逗号和下划线分隔。
-- `Text`：按 `Encoding` 编码。默认 `utf-8`，还支持 `ascii`、`gb18030`、`gbk/gb2312`、UTF-16/UTF-32 大小端。
-
-边界参数：
-
-| 参数 | 默认 | 范围 |
-|---|---:|---:|
-| `ConnectTimeout` | 10 秒 | 1-120 秒 |
-| `SendTimeout` | 10 秒 | 1-120 秒 |
-| `ReceiveTimeout` | 3 秒 | 1-120 秒 |
-| `MaxReceiveBytes` | 65536 | 1-1048576 |
-| `NoDelay` | `true` | 布尔值 |
-
-单次发送最多 4 MiB。`Send` 成功数据为 `{BytesSent, RemoteEndPoint}`。收发方法另有 `BytesReceived`、`RawBytes`、`ByteBase64`、`Hex`、`ReceiveEndReason`、`Truncated`；`ReceiveEndReason` 为 `RemoteClosed`、`Timeout` 或 `MaxReceiveBytes`。
-
-## 实现流程
-
-### 1. 固定并授权设备目标
-
-从 SaaS 可信配置或受行权限保护的设备表读取 `Host`、`Port`，按当前用户/门店/租户决定可用设备，再与精确白名单比较。禁止这样写：
-
-```javascript
-// 错误：匿名或普通调用者可扫描后端可达内网。
-return V8.Tcp.Send({
-  Host: V8.Param.Host,
-  Port: V8.Param.Port,
-  Hex: V8.Param.Hex
-});
-```
-
-### 2. 形成一个完整帧
-
-ESC/POS、Modbus TCP 或设备私有协议的命令、正文和校验码应先合成一个完整字节载荷。不要为了拼帧而打开多次连接；包含中文和控制命令时，优先在可信后端/上游把完整帧编码为 `Bytes`、`ByteBase64` 或 `Hex`。
-
-```javascript
-var result = V8.Tcp.Send({
-  Host: '192.168.1.88', // 示例；生产从可信配置读取
-  Port: 9100,
-  Bytes: [
-    27, 64,                         // ESC @ 初始化
-    77, 105, 99, 114, 111, 105, 10,
-    10, 10,
-    29, 86, 0                       // GS V 0 切纸
-  ],
-  ConnectTimeout: 5,
-  SendTimeout: 5
-});
-if (result.Code !== 1) return result;
-```
-
-只有纯文本时可使用打印机常见编码：
-
-```javascript
-var result = await V8.Tcp.SendAsync({
-  Host: '192.168.1.88',
-  Port: 9100,
-  Text: '吾码小票\n合计：12.00\n\n',
-  Encoding: 'gb18030'
-});
-if (result.Code !== 1) return result;
-```
-
-### 3. 需要协议响应时显式收取
-
-```javascript
-var result = V8.Tcp.SendAndReceive({
-  Host: '192.168.1.20',
-  Port: 4001,
-  Hex: '01 03 00 00 00 02 C4 0B',
-  ReceiveTimeout: 3,
-  MaxReceiveBytes: 4096
-});
-if (result.Code !== 1) return result;
-
-var bytes = result.Data.RawBytes;
-var hex = result.Data.Hex;
-```
-
-接收超时是整段接收的总时间。已收到部分数据后超时会返回成功和已有数据，并标记 `ReceiveEndReason='Timeout'`；未收到任何字节则失败。协议必须知道响应长度或结束条件，不能把超时默认当作完整帧。
-
-### 4. 分开判断写入、设备执行和实物结果
-
-- `Code=1` 只表示字节已写入 TCP 连接。
-- 设备协议回执可证明设备接受/处理到哪一步，但仍不一定证明机械动作完成。
-- “小票已打印”需要打印机状态、设备回执或实物/硬件验收证据。
-
-打印不是天然幂等。不确定失败时自动重试可能重复出纸；需要可靠打印时使用业务打印单号、设备回执、状态机以及 Job/MQ/outbox，且重试策略必须识别“尚未发送”和“结果未知”。
-
-## 安全与运行约束
-
-1. TCP 不经过 `V8.Http` 的 SSRF 防护。容器网络策略/防火墙只放行目标设备网段和端口；匿名接口不得暴露任意目标。
-2. 不把票据正文、设备口令、原始帧和响应秘密写入日志；日志只记录脱敏设备标识、业务单号、字节数、耗时和错误分类。
-3. `SendAsync` 只是在当前请求内等待 I/O，不能替代后台任务。不要遗留未等待 Promise、`setTimeout` 或 `Task.Run`。
-4. 每次调用都会创建并关闭连接；不能假设设备会保持会话状态。
-5. Docker 内的 `localhost` 指容器自身。验收前从实际后端容器验证到设备 IP/端口的路由和出站策略。
-6. 载荷、超时和响应均有硬上限；不要通过拆成无限循环规避限制。
-
-## 修改公共能力时的同步门禁
-
-- 源码：`Microi.Server/Microi.V8Engine/Extend/Tcp/V8Tcp.cs` 与 `V8Extend.cs`。
-- 测试：真实 Jint 注入、Byte/Base64/Hex/Text、回环收发、超时/上限/非法参数。
-- 编辑器：`Microi.Client/.../v8-api-server-definitions.js` 与 `Microi.Agent/src/editor/typingsManager.ts`。
-- 文档与知识：官网中文后端 V8 页面、`microi.skills/README.md`、`v8-utilities` 索引、`Microi.AI/Resource` 镜像和向量资源列表。
-- 验收：目标测试、后端构建、精确重启与健康检查、独立 TCP 回环；真实打印机出纸必须单独报告，不能用回环测试替代。
+---
+name: v8-tcp-integration
+description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 TCP 原始字节集成
+
+使用后端 `V8.Tcp` 完成一次性 TCP 连接、原始字节写入和可选的有界响应读取。典型场景是 RAW/JetDirect 9100 网络小票机、串口服务器和 PLC；具体协议帧、校验码与打印业务仍由接口引擎编排。
+
+文档维护时，只在 `microi.doc/docs/doc/v8-engine/v8-server.md` 原位更新后端 API；不要新建重复页面，也不要手工维护英文文档。改变公共契约时同步后端源码/测试、Microi.Client Monaco 定义、Microi.Agent 类型与生成知识、AI Skill 镜像。
+
+## 先判断是否适用
+
+| 需求 | 选择 |
+|---|---|
+| 后端向设备 TCP 端口发送原始字节 | `V8.Tcp` |
+| HTTP/HTTPS API | `V8.Http`，不要用 TCP 重写 HTTP |
+| RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
+| 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
+| 长连接、TCP 服务端监听、TLS、自定义连接池 | 当前 `V8.Tcp` 不提供；设计独立网关/Worker |
+
+平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
+
+## API 契约
+
+| 方法 | 行为 |
+|---|---|
+| `V8.Tcp.Send({...})` | 连接、发送、关闭，返回 `DosResult` |
+| `await V8.Tcp.SendAsync({...})` | 当前请求内异步发送 |
+| `V8.Tcp.SendAndReceive({...})` | 发送后读取响应，再关闭 |
+| `await V8.Tcp.SendAndReceiveAsync({...})` | 当前请求内异步发送并读取响应 |
+
+必填目标参数：
+
+- `Host`：主机名或 IP；只允许主机，不传 `tcp://` URL。
+- `Port`：1-65535。
+
+发送内容必须且只能选择一组：
+
+- `Bytes`（别名 `RawBytes`、`ByteArray`）：每项为 0-255 的整数。
+- `ByteBase64`（别名 `BytesBase64`、`Base64`）。
+- `Hex`：允许空格、`0x`、`-`、`:`、逗号和下划线分隔。
+- `Text`：按 `Encoding` 编码。默认 `utf-8`，还支持 `ascii`、`gb18030`、`gbk/gb2312`、UTF-16/UTF-32 大小端。
+
+边界参数：
+
+| 参数 | 默认 | 范围 |
+|---|---:|---:|
+| `ConnectTimeout` | 10 秒 | 1-120 秒 |
+| `SendTimeout` | 10 秒 | 1-120 秒 |
+| `ReceiveTimeout` | 3 秒 | 1-120 秒 |
+| `MaxReceiveBytes` | 65536 | 1-1048576 |
+| `NoDelay` | `true` | 布尔值 |
+
+单次发送最多 4 MiB。`Send` 成功数据为 `{BytesSent, RemoteEndPoint}`。收发方法另有 `BytesReceived`、`RawBytes`、`ByteBase64`、`Hex`、`ReceiveEndReason`、`Truncated`；`ReceiveEndReason` 为 `RemoteClosed`、`Timeout` 或 `MaxReceiveBytes`。
+
+## 实现流程
+
+### 1. 固定并授权设备目标
+
+从 SaaS 可信配置或受行权限保护的设备表读取 `Host`、`Port`，按当前用户/门店/租户决定可用设备，再与精确白名单比较。禁止这样写：
+
+```javascript
+// 错误：匿名或普通调用者可扫描后端可达内网。
+return V8.Tcp.Send({
+  Host: V8.Param.Host,
+  Port: V8.Param.Port,
+  Hex: V8.Param.Hex
+});
+```
+
+### 2. 形成一个完整帧
+
+ESC/POS、Modbus TCP 或设备私有协议的命令、正文和校验码应先合成一个完整字节载荷。不要为了拼帧而打开多次连接；包含中文和控制命令时，优先在可信后端/上游把完整帧编码为 `Bytes`、`ByteBase64` 或 `Hex`。
+
+```javascript
+var result = V8.Tcp.Send({
+  Host: '192.168.1.88', // 示例；生产从可信配置读取
+  Port: 9100,
+  Bytes: [
+    27, 64,                         // ESC @ 初始化
+    77, 105, 99, 114, 111, 105, 10,
+    10, 10,
+    29, 86, 0                       // GS V 0 切纸
+  ],
+  ConnectTimeout: 5,
+  SendTimeout: 5
+});
+if (result.Code !== 1) return result;
+```
+
+只有纯文本时可使用打印机常见编码：
+
+```javascript
+var result = await V8.Tcp.SendAsync({
+  Host: '192.168.1.88',
+  Port: 9100,
+  Text: '吾码小票\n合计：12.00\n\n',
+  Encoding: 'gb18030'
+});
+if (result.Code !== 1) return result;
+```
+
+### 3. 需要协议响应时显式收取
+
+```javascript
+var result = V8.Tcp.SendAndReceive({
+  Host: '192.168.1.20',
+  Port: 4001,
+  Hex: '01 03 00 00 00 02 C4 0B',
+  ReceiveTimeout: 3,
+  MaxReceiveBytes: 4096
+});
+if (result.Code !== 1) return result;
+
+var bytes = result.Data.RawBytes;
+var hex = result.Data.Hex;
+```
+
+接收超时是整段接收的总时间。已收到部分数据后超时会返回成功和已有数据，并标记 `ReceiveEndReason='Timeout'`；未收到任何字节则失败。协议必须知道响应长度或结束条件，不能把超时默认当作完整帧。
+
+### 4. 分开判断写入、设备执行和实物结果
+
+- `Code=1` 只表示字节已写入 TCP 连接。
+- 设备协议回执可证明设备接受/处理到哪一步，但仍不一定证明机械动作完成。
+- “小票已打印”需要打印机状态、设备回执或实物/硬件验收证据。
+
+打印不是天然幂等。不确定失败时自动重试可能重复出纸；需要可靠打印时使用业务打印单号、设备回执、状态机以及 Job/MQ/outbox，且重试策略必须识别“尚未发送”和“结果未知”。
+
+## 安全与运行约束
+
+1. TCP 不经过 `V8.Http` 的 SSRF 防护。容器网络策略/防火墙只放行目标设备网段和端口；匿名接口不得暴露任意目标。
+2. 不把票据正文、设备口令、原始帧和响应秘密写入日志；日志只记录脱敏设备标识、业务单号、字节数、耗时和错误分类。
+3. `SendAsync` 只是在当前请求内等待 I/O，不能替代后台任务。不要遗留未等待 Promise、`setTimeout` 或 `Task.Run`。
+4. 每次调用都会创建并关闭连接；不能假设设备会保持会话状态。
+5. Docker 内的 `localhost` 指容器自身。验收前从实际后端容器验证到设备 IP/端口的路由和出站策略。
+6. 载荷、超时和响应均有硬上限；不要通过拆成无限循环规避限制。
+
+## 修改公共能力时的同步门禁
+
+- 源码：`Microi.Server/Microi.V8Engine/Extend/Tcp/V8Tcp.cs` 与 `V8Extend.cs`。
+- 测试：真实 Jint 注入、Byte/Base64/Hex/Text、回环收发、超时/上限/非法参数。
+- 编辑器：`Microi.Client/.../v8-api-server-definitions.js` 与 `Microi.Agent/src/editor/typingsManager.ts`。
+- 文档与知识：官网中文后端 V8 页面、`microi.skills/README.md`、`v8-utilities` 索引、`Microi.AI/Resource` 镜像和向量资源列表。
+- 验收：目标测试、后端构建、精确重启与健康检查、独立 TCP 回环；真实打印机出纸必须单独报告，不能用回环测试替代。

package/skills/v8-tcp-integration/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "V8 TCP 原始字节"
-  short_description: "通过后端 V8 安全发送和接收 TCP 原始字节数据"
-  default_prompt: "使用 $v8-tcp-integration 编写一个安全、可验证的 Microi 后端 V8 TCP 设备集成。"
+interface:
+  display_name: "V8 TCP 原始字节"
+  short_description: "通过后端 V8 安全发送和接收 TCP 原始字节数据"
+  default_prompt: "使用 $v8-tcp-integration 编写一个安全、可验证的 Microi 后端 V8 TCP 设备集成。"

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

@@ -1,167 +1,167 @@
----
-name: v8-template-engine
-description: Microi V8 模板引擎指南。用于编写表格/表单模板渲染、V8.Result HTML/text 输出、行格式化、徽章、图片和自定义显示逻辑。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# 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`） | 浏览器渲染时执行 |