@microi.net/cli 4.9.3 → 4.9.5

package/skills/v8-mq-mqtt/references/mqtt-production.md

@@ -0,0 +1,341 @@
+# Microi MQTT 生产参考
+
+本参考用于设计或审查 Microi MQTT 配置、事件接口引擎、设备路由、服务端下行、
+安全边界和生产部署。优先以目标版本源码与实际租户元数据为准；旧部署可能尚未
+具备本文列出的全部字段或行为。
+
+## 目录
+
+- [事实源与适用边界](#事实源与适用边界)
+- [接入架构与协议边界](#接入架构与协议边界)
+- [SaaS 配置矩阵](#saas-配置矩阵)
+- [租户识别与连接认证](#租户识别与连接认证)
+- [Topic ACL 与规范化](#topic-acl-与规范化)
+- [事件与字段可用性](#事件与字段可用性)
+- [V8 返回值和失败关闭](#v8-返回值和失败关闭)
+- [设备级接口引擎](#设备级接口引擎)
+- [安全的遥测处理模式](#安全的遥测处理模式)
+- [服务端安全下行](#服务端安全下行)
+- [数据分层与可观测性](#数据分层与可观测性)
+- [单节点与多节点部署](#单节点与多节点部署)
+- [上线验收清单](#上线验收清单)
+- [自动覆盖检查的证据边界](#自动覆盖检查的证据边界)
+
+## 事实源与适用边界
+
+按以下顺序确认当前能力，不要仅凭示例或历史文档推断：
+
+1. `Microi.Server/Microi.Core/Model/MqttParam.cs`：`V8.MQTT` 可用字段。
+2. `Microi.Server/Microi.MQTT/MicroiMQTT.cs`：Broker、认证、Topic ACL、事件、
+   返回值、设备缓存和日志的真实行为。
+3. `Microi.Server/Microi.Core/SaaSEngine/TenantConfigurationSecurity.cs`：共享监听
+   配置、租户凭据、Topic 规范化和敏感字段边界。
+4. `Microi.Server/Microi.Core/Interface/IMicroiMQTT.cs`：
+   `IMicroiMQTT.PublishAsync(osClient, ...)` 可信后端发布和节点状态接口。
+5. `Microi.Server/Microi.net.Api/Controllers/MqttController.cs`：平台管理员、当前节点
+   状态与示例下行入口的权限边界。
+6. `microi.doc/docs/doc/system-engine/mqtt-engine.md`：面向用户的完整能力说明。
+
+目标服务器可能落后于当前源码。编写事件代码前回读其 `sys_osclients` 字段和运行
+版本；缺少字段时走官方应用包/版本升级，不要在 V8 中伪造配置。
+
+## 接入架构与协议边界
+
+Microi 当前直接处理 MQTT，不直接解析 RS-485、ZigBee、BLE 或 Modbus 帧：
+
+```text
+现场设备 -> 边缘网关/协议转换 -> MQTT TCP/TLS -> Microi Broker
+         -> 租户认证与 Topic ACL -> mci_mqtt_client / mci_mqtt_log
+         -> V8.EventName + V8.MQTT -> 业务表、MongoDB、HTTP、告警、工单
+```
+
+边缘网关负责现场总线、采样与协议解析；Microi 负责租户边界、实时业务规则、数据
+治理和应用联动。浏览器 MQTT 需要独立的 WebSocket MQTT 网关；当前隐藏元数据
+`MqttWsPort` 不代表内嵌 Broker 已启用 WebSocket。
+
+## SaaS 配置矩阵
+
+| 字段 | 作用域 | 当前行为与默认值 | 变更生效 |
+| --- | --- | --- | --- |
+| `MqttEnable` | 每租户 | 主租户为 `1` 才启动 Broker；子租户为 `1` 才允许其连接 | 启停监听需重启 MQTT 节点 |
+| `MqttPort` | 主租户共享 | TCP 监听端口，默认 `1883` | 重启 MQTT 节点 |
+| `MqttUseTls` | 主租户共享 | `1` 时尝试启用 TLS 端点 | 重启 MQTT 节点 |
+| `MqttTlsPort` | 主租户共享 | TLS 端口，默认 `8883` | 重启 MQTT 节点 |
+| `MqttCertPath` | 主租户共享 | 进程/容器内可读的 PFX 路径 | 挂载证书后重启 |
+| `MqttCertPassword` | 主租户共享秘密 | PFX 密码，只允许可信后端读取 | 轮换后重启 |
+| `MqttFallbackPort` | 主租户运行时 | Windows 主端口被拒绝时使用；无有效配置则 `21883` | 重启 MQTT 节点 |
+| `MqttWsPort` | 保留元数据 | 当前未创建 WebSocket 监听 | 不得宣称已生效 |
+| `MqttAccount` | 每租户凭据 | 子租户必须独立、完整，不能与其它租户账号重复 | 新连接使用新值 |
+| `MqttPwd` | 每租户秘密 | 子租户必须独立、完整，不能与其它租户密码重复 | 新连接使用新值 |
+| `MqttApiEngine` | 每租户 | 默认 MQTT 事件接口引擎；兼容历史 GUID/ULID Id 和当前 `ApiEngineKey` | 按接口引擎缓存规则 |
+| `MqttAllowAnonymous` | 仅主租户兼容 | 只有主租户显式为 `1` 才可能匿名；生产不建议 | 新连接使用新值 |
+| `MqttTopicIsolation` | 兼容元数据 | 不能关闭强制租户 Topic ACL，子租户设为 `0` 也不放宽 | 无放宽语义 |
+
+把 PFX 以只读 Secret/持久卷挂载，不把证书密码、MQTT 密码写入代码、URL、日志、
+前端或普通 V8。运行时读取了某字段不等于所有历史数据库都已经拥有该字段；部署前
+必须回读目标表结构。
+
+当前 `MqttUseTls=1` 是在默认明文 TCP 端点之外增加 TLS 1.2 端点，不是 TLS-only
+模式；证书路径无效时会写诊断，但默认 TCP Broker 仍可能启动。要求强制加密时，
+除验证 TLS 握手外，还要在防火墙/入口层关闭公网明文端口，不能只看 `IsRunning`。
+
+## 租户识别与连接认证
+
+连接验证按以下优先级解析租户：
+
+1. MQTT v5 User Property `OsClient`；
+2. Username 的 `<OsClient>:<MqttAccount>` 前缀；
+3. ClientId 的 `<OsClient>:<设备Id>` 前缀；
+4. 旧主租户客户端仅在 Username 精确等于主租户 `MqttAccount` 时兼容。
+
+同时提供多个来源时必须全部指向同一租户。显式未知租户、未启用租户、空/非法
+ClientId、错误密码和跨租户 ClientId 冲突均失败关闭，不回退主租户。
+
+子租户还必须满足：
+
+- 账号与密码都非空；
+- 账号不能与任一其它租户账号相同；
+- 密码不能与任一其它租户密码相同；
+- 不能通过 `MqttAllowAnonymous=1` 或 `MqttTopicIsolation=0` 绕过边界。
+
+凭据使用常量时间字符串比较。不要在 Payload 中传一个 `OsClient` 后自行切换租户；
+业务代码只信任 `V8.MQTT.OsClient`。
+
+同一 ClientId 快速重连时，每次有效连接持有独立会话令牌。旧连接的延迟
+`Disconnected` 会被记录为 `StaleDisconnectIgnored`，不会删除替代连接的租户映射
+或错误标记新会话下线。
+
+## Topic ACL 与规范化
+
+业务 Topic 会被收敛为：
+
+```text
+tenant/{lowerOsClient}/{businessTopic}
+```
+
+| 输入 | 结果 |
+| --- | --- |
+| `sensor/temperature` | 自动加当前租户前缀 |
+| `tenant/<当前租户>/sensor/temperature` | 保留并规范化租户大小写 |
+| `<当前租户>/sensor/temperature` | 兼容旧前缀并转为标准格式 |
+| `tenant/<其它租户>/...` | 拒绝 |
+| `$SYS/...`、`$share/...` | 拒绝 |
+| 发布 Topic 包含 `+` 或 `#` | 拒绝 |
+| 订阅 `sensor/+/state` 或 `sensor/#` | 允许合法完整段通配符并加租户前缀 |
+| 包含控制字符、反斜杠、`//`、`.` 或 `..` 路径段 | 拒绝 |
+
+发布、订阅、Retained Message、可信后端下行和 MQTT v5 `ResponseTopic` 都执行同一
+租户边界。`#` 只能是订阅的最后一个完整段，`+` 只能作为完整段。
+
+## 事件与字段可用性
+
+| `V8.EventName` | 触发时机 | 主要字段 | 返回值影响 |
+| --- | --- | --- | --- |
+| `StartServer` | Broker 成功启动后，逐个启用且配置引擎的租户 | `OsClient` | 不改变启动结果 |
+| `Connected` | 认证成功、设备表/日志更新后 | `ClientId`、`OsClient`、`UserName`、`UserProperties` | 不能否决连接 |
+| `Disconnected` | 当前有效会话断开、设备表/日志更新后 | `ClientId`、`OsClient`、`UserProperties` | 不能否决断开 |
+| `Subscribing` | Topic ACL 已通过、订阅日志写入后 | `ClientId`、`OsClient`、`Topic`、`UserProperties` | 不能否决订阅 |
+| `MessageReceived` | 发布 Topic 通过 ACL、接收日志写入后 | `ClientId`、`OsClient`、`Topic`、`Payload`、`PayloadRaw`、`Qos`、`Retain`、`UserProperties` | `Code != 1` 阻止广播 |
+| `MessageChanged` | Retained Message 变化并通过 ACL 后 | `ClientId`、`OsClient`、`Topic`、`Payload`、`PayloadRaw`、`Qos`、`Retain` | 返回值不改变结果 |
+| `StopServer` | Broker 正常停止后，逐个启用且配置引擎的租户 | `OsClient` | 不改变停止结果 |
+
+`V8.MQTT` 完整模型：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `ClientId` | `string` | 设备/客户端 Id |
+| `Payload` | `object / string` | JSON 自动反序列化；失败时为原始字符串 |
+| `PayloadRaw` | `string` | 原始 UTF-8 文本，适合验签与审计 |
+| `Topic` | `string` | 已规范化的完整 Topic |
+| `OsClient` | `string` | 已校验租户 |
+| `UserName` | `string` | 连接用户名，仅部分事件有值 |
+| `Qos` | `number` | `0`、`1`、`2` |
+| `Retain` | `boolean` | Retain 标记 |
+| `UserProperties` | `object` | MQTT v5 用户属性；没有时为空 |
+
+按事件读取字段，不要假设生命周期事件也有 ClientId/Payload，或连接事件已有 Topic。
+
+## V8 返回值和失败关闭
+
+只有 `MessageReceived` 把接口引擎返回值作为发布策略：
+
+- `null`/无返回值：放行；
+- 字符串、数字等普通历史返回值：放行；
+- 没有 `Code` 的对象：放行；
+- `Code: 1`：放行；
+- 显式 `Code != 1`：阻止向订阅者广播并写系统诊断；
+- 已配置的事件引擎执行异常：归一为 `Code: 0`，失败关闭。
+
+没有配置 `MqttApiEngine` 时不存在 V8 策略闸门，Broker 仍只执行内置认证与 Topic
+ACL。接收日志在 V8 执行前进入 `mci_mqtt_log`，因此规则拒绝的消息仍可审计。
+
+`Connected`、`Disconnected`、`Subscribing`、`MessageChanged` 和生命周期事件是业务
+观察/联动入口，当前返回值不会反向改变底层协议动作。不要误写“在 `Connected`
+返回 `Code: 0` 即可拒绝连接”或“在 `Subscribing` 返回失败即可拒绝订阅”。
+
+## 设备级接口引擎
+
+`mci_mqtt_client.ApiEngineId` 可覆盖租户 `sys_osclients.MqttApiEngine`。连接时平台：
+
+1. 新增或更新 `ClientId`、`LastConnectTime`、`IsOnline`；
+2. 把已有设备 `ApiEngineId` 放进当前节点缓存；
+3. 优先使用设备引擎处理当前连接期间的 MQTT 事件；
+4. 缺少设备引擎时回退租户默认引擎。
+
+历史 JoinForm 配置可能保存 `sys_apiengine.Id`（GUID/ULID）；运行时会解析为真实
+`ApiEngineKey`。新配置优先保存 Key。
+
+设备级缓存是当前节点、当前连接的优化，不是共享事实。修改 `ApiEngineId` 后让设备
+重新连接。当前源码在有效断开时先移除连接与设备引擎缓存，因此
+`Disconnected` 事件会走租户默认引擎；需要设备专属离线业务时，在租户默认引擎
+按 `ClientId` 查询设备配置，不要假设断开事件仍持有设备缓存。
+
+## 安全的遥测处理模式
+
+```javascript
+var mqtt = V8.MQTT || {};
+
+if (V8.EventName !== 'MessageReceived') {
+  return { Code: 1 };
+}
+
+var data = mqtt.Payload;
+if (typeof data === 'string') {
+  try {
+    data = JSON.parse(data);
+  } catch (ex) {
+    return { Code: 0, Msg: 'Payload 必须是合法 JSON。' };
+  }
+}
+
+if (!data || !data.eventId) {
+  return { Code: 0, Msg: '缺少稳定的 eventId。' };
+}
+
+var temperature = Number(data.temperature);
+if (isNaN(temperature) || temperature < -80 || temperature > 200) {
+  return { Code: 0, Msg: 'temperature 超出允许范围。' };
+}
+
+// iot_telemetry_ingest 必须按 mqtt.OsClient + data.eventId 做唯一约束/inbox 去重。
+var result = V8.ApiEngine.Run('iot_telemetry_ingest', {
+  eventId: data.eventId,
+  osClient: mqtt.OsClient,
+  clientId: mqtt.ClientId,
+  topic: mqtt.Topic,
+  temperature: temperature,
+  qos: mqtt.Qos,
+  retain: mqtt.Retain,
+  payloadRaw: mqtt.PayloadRaw
+});
+
+return result && result.Code === 1
+  ? { Code: 1 }
+  : { Code: 0, Msg: (result && result.Msg) || '遥测处理失败。' };
+```
+
+不要在重试时用 `NewUlid()` 重新生成业务幂等键。稳定 `EventId` 应由设备/网关生成，
+或由网关基于设备序列号、消息序号和采样时间确定性构造。消费端仍需数据库唯一约束、
+inbox/outbox、状态机或条件更新，QoS 2 也不能代替业务幂等。
+
+## 服务端安全下行
+
+可信后端只调用带租户上下文的接口：
+
+```csharp
+await mqttService.PublishAsync(
+    osClient,
+    $"device/{deviceId}/command",
+    JsonConvert.SerializeObject(new { Action = "restart", EventId = eventId }),
+    qos: 1,
+    retain: false);
+```
+
+运行时会规范化 Topic、`ResponseTopic`，覆盖 User Property 中的 `OsClient`，并用内部
+租户 SenderClientId 注入消息。缺少 `osClient` 的旧原生重载会直接抛错拒绝。
+
+`V8.MQTT` 是只读事件上下文，不是 `Publish` API。若需要 V8 下行，先在 C# 提供
+最小、租户隔离、不可覆盖基础设施秘密的原子能力，再由接口引擎做菜单/表/行权限、
+状态机、稳定 EventId、审计和业务编排；不要开放匿名通用发布 Controller。
+
+## 数据分层与可观测性
+
+| 数据 | 推荐位置 | 原因 |
+| --- | --- | --- |
+| 设备档案、阈值、归属、工单、告警状态 | FormEngine/关系库 | 需要事务、权限和后台维护 |
+| 高频遥测、采样序列 | MongoDB/专用时序存储 | 便于分区、保留和批量查询 |
+| 图片、音频、固件、大文件 | 对象存储/文件服务 | MQTT 只传文件 Id、哈希和元数据 |
+| Broker 运行审计 | `mci_mqtt_log` | 排障，不代替长期遥测仓 |
+| 当前设备接入台账 | `mci_mqtt_client` | 最后连接、基础在线状态、设备引擎 |
+
+系统日志 `Type=MQTT` 记录端口占用、TLS、认证拒绝、Topic ACL、V8 异常和旧连接
+断开忽略等诊断。当前 `mci_mqtt_log` 的 `Receive` 审计会保存解析后的 Payload 与
+`PayloadRaw`；不要在 MQTT Payload 携带密码、Token 等秘密，并为该表配置严格权限、
+脱敏、保留、归档和容量策略。日志/设备表写入失败只记录告警，不会停止消息主流程，
+因此它们不能单独作为“消息一定持久化”的证明。
+
+`mci_mqtt_client.IsOnline` 只能反映运行时最后写入的基础状态。节点崩溃不会保证
+产生 `Disconnected`；业务在线判断应结合共享数据库中的心跳、最后活动时间、超时
+窗口和设备状态机。
+
+## 单节点与多节点部署
+
+### 单节点或独立 MQTT 节点
+
+- 显式映射 `MqttPort` 和 `MqttTlsPort`，开放防火墙/负载入口。
+- 把证书挂载为只读文件；轮换后重启 MQTT 节点。
+- 把 MQTT TCP/TLS 流量稳定路由到该节点，不要求 HTTP 会话粘滞来保证业务正确。
+- `GetConnectedClients(osClient)` 和管理状态接口只用于当前节点诊断。
+
+### 多 API 节点
+
+内嵌 Broker 的连接、会话、订阅、Retained Message 和内存缓存不会跨 API 节点共享。
+不要让负载均衡后的每个 API 节点各启动一套 Broker，再宣称它们组成一个集群。
+
+选择以下一种生产架构：
+
+1. 仅在独立 MQTT 节点启用内嵌 Broker，TCP/TLS 入口固定路由到该节点；
+2. 使用支持持久化与集群的外部 Broker，并通过租户感知网关/适配器进入 Microi
+   事件链；外部 Broker 本身不会自动触发当前进程内 `V8.MQTT`；
+3. 所有业务副作用使用稳定 EventId、数据库唯一约束、inbox/outbox 和条件更新。
+
+若要求掉电或强杀窗口内零丢失，必须在返回成功前获得外部 Broker 持久化、共享
+outbox 或同步 WAL 的确认；内存状态与异步稍后写库不能覆盖该窗口。
+
+## 上线验收清单
+
+- [ ] 主租户启用后 TCP 端口真实监听；TLS 证书链、端口和客户端握手真实可用。
+- [ ] 正确凭据连接成功；错误密码、未知/未启用租户、凭据碰撞均被拒绝。
+- [ ] 多租户来源冲突、跨租户 ClientId、空或非法 ClientId 被拒绝。
+- [ ] 普通 Topic 自动加租户前缀；其它租户、`$SYS`、`$share`、非法路径被拒绝。
+- [ ] 合法订阅通配符、QoS 0/1/2、Retain、`ResponseTopic` 按预期工作。
+- [ ] 七类事件按实际触发时机进入正确租户，字段可用性与本参考一致。
+- [ ] `MessageReceived` 返回 `Code: 0` 或执行异常时订阅端收不到广播，审计仍存在。
+- [ ] JSON 与 UTF-8 文本载荷都按策略处理，非法载荷不会写业务表。
+- [ ] 设备级 `ApiEngineId` 重连后生效，历史 Id 能解析为 `ApiEngineKey`。
+- [ ] 同一 ClientId 快速重连时，旧断开不会把新连接标记为离线。
+- [ ] 可信后端下行被强制限制在当前租户 Topic，旧无租户重载被拒绝。
+- [ ] 重复消息、接口超时、数据库短故障、节点重启后，业务副作用仍然至多一次。
+- [ ] 多节点场景验证入口路由、故障转移与共享业务状态，不把节点快照当全局事实。
+- [ ] 峰值压测记录 Broker、V8、关系库/MongoDB、日志的 CPU、内存、延迟与磁盘增长。
+
+静态源码、自动测试、本地 Broker、生产网络和真实硬件属于不同证据层。未执行某一层
+时必须明确说明，不能用另一层的成功替代。
+
+## 自动覆盖检查的证据边界
+
+运行：
+
+```powershell
+node microi.skills/v8-mq-mqtt/scripts/check-mqtt-skill-coverage.mjs
+```
+
+脚本验证当前源码提取到的 MQTT 事件与 `MqttParam` 属性都出现在主 Skill、生产参考、
+官网 MQTT 文档和 V8 后端索引中，并检查配置、安全、设备路由、下行、节点状态与
+部署关键字。它不能证明：
+
+- 字段已升级到某台目标服务器；
+- Broker 已监听或证书有效；
+- 外部 Broker/网关适配器已实现；
+- V8 示例在目标表结构上运行成功；
+- 真实设备、网络抖动、吞吐、掉电和多节点故障转移已经实测。

package/skills/v8-mq-mqtt/scripts/check-mqtt-skill-coverage.mjs

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const workspaceRoot = path.resolve(scriptDir, '..', '..', '..');
+
+const files = {
+  skill: 'microi.skills/v8-mq-mqtt/SKILL.md',
+  reference: 'microi.skills/v8-mq-mqtt/references/mqtt-production.md',
+  mqttDoc: 'microi.doc/docs/doc/system-engine/mqtt-engine.md',
+  v8Doc: 'microi.doc/docs/doc/v8-engine/v8-server.md',
+  runtime: 'Microi.Server/Microi.MQTT/MicroiMQTT.cs',
+  model: 'Microi.Server/Microi.Core/Model/MqttParam.cs',
+  mqttInterface: 'Microi.Server/Microi.Core/Interface/IMicroiMQTT.cs',
+  tenantSecurity: 'Microi.Server/Microi.Core/SaaSEngine/TenantConfigurationSecurity.cs',
+  controller: 'Microi.Server/Microi.net.Api/Controllers/MqttController.cs'
+};
+
+const content = {};
+const failures = [];
+
+for (const [name, relativePath] of Object.entries(files)) {
+  const absolutePath = path.join(workspaceRoot, relativePath);
+  if (!fs.existsSync(absolutePath)) {
+    failures.push(`${name}: 文件不存在 ${relativePath}`);
+    content[name] = '';
+    continue;
+  }
+  content[name] = fs.readFileSync(absolutePath, 'utf8');
+}
+
+function collectMatches(text, regex) {
+  const values = [];
+  for (const match of text.matchAll(regex)) values.push(match[1]);
+  return values;
+}
+
+function requireTokens(targetName, tokens) {
+  const text = content[targetName] || '';
+  for (const token of tokens) {
+    if (!text.includes(token)) failures.push(`${targetName}: 缺少 ${token}`);
+  }
+}
+
+function requireAny(targetName, alternatives, label) {
+  const text = content[targetName] || '';
+  if (!alternatives.some((token) => text.includes(token))) {
+    failures.push(`${targetName}: 缺少 ${label}`);
+  }
+}
+
+const runtimeEvents = new Set([
+  ...collectMatches(
+    content.runtime,
+    /RunMqttV8EngineAsync\([^,\r\n]+,\s*"([A-Za-z]+)"/g
+  ),
+  ...collectMatches(
+    content.runtime,
+    /FireV8EventForAllTenantsAsync\(\s*"([A-Za-z]+)"/g
+  )
+]);
+
+const expectedEvents = [
+  'StartServer',
+  'Connected',
+  'Disconnected',
+  'Subscribing',
+  'MessageReceived',
+  'MessageChanged',
+  'StopServer'
+];
+
+for (const eventName of expectedEvents) {
+  if (!runtimeEvents.has(eventName)) failures.push(`runtime: 未提取到事件 ${eventName}`);
+}
+
+const mqttProperties = new Set(collectMatches(
+  content.model,
+  /public\s+[A-Za-z0-9_<>,.\s]+\s+([A-Za-z0-9_]+)\s*\{\s*get;\s*set;\s*\}/g
+));
+
+const expectedProperties = [
+  'ClientId',
+  'Payload',
+  'PayloadRaw',
+  'Topic',
+  'OsClient',
+  'UserName',
+  'Qos',
+  'Retain',
+  'UserProperties'
+];
+
+for (const propertyName of expectedProperties) {
+  if (!mqttProperties.has(propertyName)) failures.push(`model: 未提取到属性 ${propertyName}`);
+}
+
+const sourceEvents = [...runtimeEvents].sort();
+const sourceProperties = [...mqttProperties].sort();
+for (const targetName of ['skill', 'reference', 'mqttDoc', 'v8Doc']) {
+  requireTokens(targetName, sourceEvents);
+  requireTokens(targetName, sourceProperties);
+}
+
+const configurationTokens = [
+  'MqttEnable',
+  'MqttPort',
+  'MqttUseTls',
+  'MqttTlsPort',
+  'MqttCertPath',
+  'MqttCertPassword',
+  'MqttFallbackPort',
+  'MqttWsPort',
+  'MqttAccount',
+  'MqttPwd',
+  'MqttApiEngine',
+  'MqttAllowAnonymous',
+  'MqttTopicIsolation'
+];
+
+const securityTokens = [
+  'tenant/{lowerOsClient}',
+  '$SYS',
+  '$share',
+  'ResponseTopic',
+  'Code != 1',
+  'StaleDisconnectIgnored'
+];
+
+const operationsTokens = [
+  'mci_mqtt_client',
+  'mci_mqtt_log',
+  'ApiEngineId',
+  'IMicroiMQTT.PublishAsync',
+  'ConnectedClients',
+  'GetConnectedClients',
+  '外部 Broker',
+  '独立 MQTT 节点'
+];
+
+requireTokens('skill', [
+  'MqttEnable',
+  'MqttPort',
+  'MqttWsPort',
+  'MqttAccount',
+  'MqttPwd',
+  'MqttApiEngine',
+  'MqttAllowAnonymous',
+  'MqttTopicIsolation'
+]);
+requireTokens('reference', configurationTokens);
+
+for (const targetName of ['skill', 'reference']) {
+  requireTokens(targetName, securityTokens);
+  requireTokens(targetName, operationsTokens);
+}
+
+requireTokens(
+  'mqttDoc',
+  configurationTokens.filter((token) => token !== 'MqttAllowAnonymous')
+);
+requireAny(
+  'mqttDoc',
+  ['MqttAllowAnonymous', '匿名连接只可能由主租户显式开启'],
+  '主租户匿名连接边界'
+);
+requireTokens(
+  'mqttDoc',
+  securityTokens.filter(
+    (token) => token !== 'StaleDisconnectIgnored' && token !== 'tenant/{lowerOsClient}'
+  )
+);
+requireAny(
+  'mqttDoc',
+  ['tenant/{lowerOsClient}', 'tenant/<lowerOsClient>'],
+  '标准租户 Topic 模板'
+);
+requireTokens('v8Doc', ['## V8.MQTT', 'IMicroiMQTT.PublishAsync', 'Code != 1']);
+
+requireTokens('runtime', [
+  'NormalizeTopic',
+  'ResponseTopic',
+  'StaleDisconnectIgnored',
+  '$share/',
+  '$SYS/',
+  'mci_mqtt_client',
+  'mci_mqtt_log',
+  'PublishRejectedByV8'
+]);
+requireTokens('mqttInterface', ['PublishAsync(string osClient', 'GetConnectedClients(string osClient)']);
+requireTokens('tenantSecurity', ['NormalizeMqttTopic', 'HasTenantServiceCredentialCollision']);
+requireTokens('controller', ['[PlatformAdminOnly]', 'StatusScope = "CurrentNode"']);
+
+if (failures.length > 0) {
+  console.error('MQTT Skill 覆盖检查失败：');
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exitCode = 1;
+} else {
+  console.log(
+    `MQTT Skill 覆盖检查通过：${sourceEvents.length} 个事件、` +
+    `${sourceProperties.length} 个 V8.MQTT 字段、` +
+    `${configurationTokens.length} 个配置项及生产安全/部署契约均已覆盖。`
+  );
+}

package/skills/v8-utilities/references/client-api-index.md

@@ -114,7 +114,7 @@
 | `V8.AddSysLog(...)` | 前端发起系统日志记录；不得含秘密 |
 | `V8.SendSystemMessage(...)` | 发送站内系统消息 |
 | `await V8.Method.ScanCode()` | 扫码；成功值同时写入 `V8.ScanCodeRes` |
-| `V8.Print.*` | BLE 标签/小票打印，见蓝牙打印参考 |
+| `V8.Print.*` | TSPL/CPCL/ESC-POS 蓝牙标签与小票打印，兼容 GP-M322、CC4，见蓝牙打印参考 |
 | `V8.Identity.GetCapabilities()` | 读取当前租户强身份能力和本人登记状态 |
 | `V8.Identity.CreateActionHash(value)` | 为稳定业务命令生成 SHA-256 摘要 |
 | `V8.Identity.RegisterPasskey(options?)` | 登记当前用户 Passkey |
@@ -124,11 +124,13 @@
 `V8.Identity` 是强身份验证模块。`V8.Identity.Verify` 的成功结果不能直接授权业务；后端必须重读权威数据、重算摘要并调用 `V8.Method.ConsumeIdentityVerificationTicket`。
 蓝牙打印完整 API 包含 `V8.Print.createNew`、`V8.Print.createNewESC`、
 `V8.Print.OpenBluetoothPage`、`V8.Print.isConnected`、
+`V8.Print.reconnect`、`V8.Print.getConnectionState`、`V8.Print.subscribeConnection`、
+`V8.Print.getPrinterProfile`、`V8.Print.setPrinterProfile`、
 `V8.Print.prepareSend`、`V8.Print.Send`、`V8.Print.setOneTimeData`、
 `V8.Print.setPrinterNum`、`V8.Print.disconnect` 和
 `V8.Print.BLEInformation`。其中 `Send` 依赖 `prepareSend` 设置的共享分包游标，
 只作内部状态机入口；业务代码必须调用并 `await prepareSend`。当前挂载范围、连接
-真实性和串行约束见
+真实性、佳博原 TSPL 回归、CC4 CPCL 适配、Android SPP 与串行约束见
 [`bluetooth-print.md`](../../v8-frontend-events/references/bluetooth-print.md)，TSC/ESC
 完整方法见
 [`bluetooth-print-api.md`](../../v8-frontend-events/references/bluetooth-print-api.md)。

package/skills/workspace-conventions/SKILL.md

@@ -106,10 +106,11 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 | 吾码 App 源码 | `microi.app/` |
 | 吾码 UniApp 源码 | `microi.uniapp/` |
 | 吾码官方网站 / 文档源码 | `microi.doc/` |
-| 吾码 AI 应用源码 | `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/` |
-| 吾码官方应用商城发行包源码 | `microi.apps/{packageKey}/` |
+| 吾码 AI 应用及应用商城发行源码 | `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/` |
 
 以上路径只作为通用工作区相对路径规范，不写入具体本机盘符。跨仓库、空工作区或普通用户项目中，如果路径不存在，以插件生成的 `AGENTS.md`、MCP 配置和实际文件树为准。
+
+每个 `AI应用/{appKey}` 必须是界面、微服务、Manifest、接口引擎、资源策略、测试、构建脚本与商城上传素材的唯一事实源。纯平台应用没有前端时仍使用该目录；禁止另建 `microi.apps/` 平行发行根。
 
 ## Skills 通用化原则