node-red-contrib-knx-ultimate 6.1.1 → 6.2.0

package/nodes/locales/it/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Analisi Traffico)",
     "sections": {
+      "quickSetup": "Configurazione rapida",
       "capture": "Cattura",
       "storage": "Storico e Summary",
       "detection": "Rilevamento e Avvisi",
       "llmConnection": "Connessione Assistente AI",
       "llmContext": "Contesto Assistente AI",
-      "advanced": "Tuning Avanzato"
+      "chatAdapter": "Adattatori chat",
+      "advanced": "AI avanzata"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "Prompt di sistema",
       "llmIncludeRaw": "Includi payload raw in hex",
       "llmIncludeFlowContext": "Includi inventario del progetto Node-RED",
+      "llmAllowKnxCommands": "Consenti all'AI di leggere stati KNX e comandare attuatori",
+      "llmRequireCommandConfirmation": "Chiedi conferma prima di inviare comandi KNX",
+      "chatAdapterPreset": "Preset adattatore",
+      "chatInputCode": "Mappatura ingresso (chat → KNX AI)",
+      "chatOutputCode": "Mappatura uscita (KNX AI → chat)",
       "llmIncludeDocsSnippets": "Includi estratti documentazione (help/README/esempi)",
       "llmDocsLanguage": "Lingua documentazione"
     },
     "outputs": {
       "summary": "Summary/Statistiche",
       "anomalies": "Anomalie",
-      "assistant": "Assistente AI"
+      "assistant": "Assistente AI",
+      "knxCommands": "Operazioni KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "Compatibile OpenAI (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (locale, beta)"
+      },
+      "chatAdapter": {
+        "none": "Nessun adattatore"
       }
     },
     "buttons": {
@@ -69,7 +80,9 @@
       "installedOllamaModel": "Modello Ollama installato",
       "installOllamaModelFailed": "Installazione modello Ollama non riuscita",
       "ollamaInstallSteps": "1) Apri la libreria, scegli un modello e copiane il nome (es. llama3.1). 2) Inserisci il nome nel campo Modello e clicca Installalo.",
-      "ollamaStartedAuto": "Server Ollama avviato automaticamente."
+      "ollamaStartedAuto": "Server Ollama avviato automaticamente.",
+      "chatAdapterIntro": "Scegli un preset per inserire il codice di mappatura in ingresso e in uscita. La lista viene caricata dal file degli adattatori chat incluso nel pacchetto; il codice generato resta modificabile.",
+      "chatAdapterCodeHelp": "Le mappature sono sincrone. Restituisci msg per continuare oppure nessun valore per scartarlo. Gli errori vengono intercettati e segnalati senza arrestare Node-RED."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (o endpoint compatibile)",

package/nodes/locales/zh-CN/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 此节点会监听所选 KNX Ultimate 网关上的**所有 KNX 电报**，生成流量统计、检测异常，并可选调用 LLM。
 
+编辑器各部分使用与 Matter 节点相同的左侧垂直选项卡。**快速配置**仅包含常用 AI 选项（启用、提供商、凭据、模型、KNX 状态读取/执行器控制和确认）；技术参数按主题归入其他选项卡。
+
 ## 输出
 1. **摘要/统计**（`msg.payload` 为 JSON）
 2. **异常**（`msg.payload` 为 JSON）
 3. **AI 助手**（`msg.payload` 为文本，包含 `msg.summary`）
+4. **KNX 操作**（每个通过验证的读取或写入输出一条 Universal Mode 消息）
+
+输出 3 和输出 4 发出的每条消息还会在 `msg.inputMessage` 中包含原始输入消息的副本。因此，原始 payload、topic、聊天元数据及其他输入属性都可供后续节点使用。克隆或输出错误会被捕获并报告，不会传播到 Node-RED 运行时。
 
 ## 命令（输入）
 发送 `msg.topic`：
 - `summary`（或空）：立即输出摘要
 - `reset`：清空内部历史与计数器
 - `ask`：向已配置的 LLM 提问
+- `confirm` / `cancel`：无需再次调用 LLM，即可确认或取消待处理的 KNX 命令
+- `clear_chat`：清除当前会话的对话记忆
+
+`ask` 的问题建议放在 `msg.prompt`，也可放在 `msg.payload`（字符串）或常见 Telegram 字段 `msg.payload.content` / `msg.payload.text`。
+
+启用 KNX 控制后，最近的对话会按 `msg.knxAi.sessionId`、`msg.sessionId` 或检测到的 Telegram 聊天 ID 保存在 RAM 中。将输出 3 连接到聊天发送节点，将输出 4 连接到配置为**通用模式**的 KNX Ultimate 节点。启用确认后，第一条回复会显示 GA、DPT 和 payload，但不会发送写入；同一会话必须在 5 分钟内回复“确认”或“取消”。新请求会替换旧的待处理计划。每条已确认命令都包含 `msg.destination`、`msg.dpt`、`msg.payload` 和 `msg.event = "GroupValue_Write"`。
+对于 DPT 1.xxx 写入，AI 生成的安全等价值 `true`/`false`、`1`/`0` 和 `on`/`off` 会在本地校验和输出前统一转换为真正的布尔值。
+
+### 最新 KNX 读取
+当用户明确要求当前或最新状态时，AI 可以查询已导入 ETS 目录中的精确对象，包括状态对象和其他只读对象。输出 4 会发送 `msg.destination`、`msg.dpt`、`msg.event = "GroupValue_Read"` 和 `msg.readstatus = true`。节点会为每个 `GroupValue_Response` 或最新写入等待最多 6 秒，然后在输出 3 返回解码值，并在 `msg.knxAi.readResults` 中提供详细信息。读取从不需要确认，也绝不会转换为写入。
+
+### 用于聊天按钮的确认请求
+计划等待确认时，输出 3 包含 `msg.knxAi.confirmationRequest`。该对象包括 `required`、`status`、`sessionId`、`expiresAt`、`commandCount`，以及 `actions` 中的两个项目。使用 `action.label` 作为 Telegram 按钮文本，使用 `action.callbackData` 作为回调，并将 `action.message` 发送回 KNX AI，即可在无需输入文本的情况下确认或取消。
+
+### 聊天适配器预设
+**聊天适配器**选项卡从 `resources/KNXAIChatAdapterMappings.js` 加载可选映射。选择预设会在全宽文本框中插入两段可编辑的同步 JavaScript 映射：一段在 KNX AI 处理输入前运行，另一段在输出 3 发出消息前运行。返回 `msg` 以继续，或不返回值以丢弃消息。语法和执行错误会被捕获并报告，不会停止 Node-RED。
+
+随附的 **windkh/node-red-contrib-telegrambot** 预设遵循该包的 receiver/sender 消息约定。把 `telegram receiver` 直接连接到 KNX AI，并把输出 3 直接连接到 `telegram sender`。如需内联确认按钮，还要把配置为 `callback_query` 的 `telegram event` 连接到同一个 KNX AI 输入。输入映射会提取 `msg.payload.content`、`msg.payload.chatId` 和 Telegram 语言；输出映射会创建所需的 `msg.payload.chatId`、`type` 和 `content`，并在写入等待确认时从 `msg.knxAi.confirmationRequest` 添加 `options.reply_markup`。Telegram 包仍是独立的可选依赖项。
 
-`ask` 的问题建议放在 `msg.prompt`，也可放在 `msg.payload`（字符串）。
+## 快速工作流程：KNX 控制
+1. 将 ETS CSV 导入网关，并配置 LLM 提供商、模型和凭据。
+2. 启用 **LLM 助手**和 **读取 KNX 状态并控制执行器**；保持确认选项启用。
+3. 将聊天输入连接到 KNX AI，并保留稳定的会话/聊天 ID。
+4. 将输出 3 连接到聊天回复，将输出 4 连接到处于**通用模式**的 KNX Ultimate。
+5. 用户发送请求；当前状态会立即读取，而写入会先显示 GA、DPT 和值，不会立即写入总线。
+6. 同一聊天必须在 5 分钟内准确回复“确认”或“取消”。
+7. 只有“确认”会重新验证并在输出 4 发送命令；请通过 KNX 状态 GA 验证执行结果。
 
 ## 配置字段
 以下是编辑器里用户可见的全部字段名称。
@@ -53,7 +83,13 @@
 - **Endpoint URL**：chat/completions 接口 URL。
 - **API key**：API Key（本地 Ollama 可不填）。
 - **Model**：模型 ID/名称。
+- **聊天模型兼容性**：所选模型必须支持已配置的 Chat Completions 端点。刷新模型列表时，会排除仅支持旧版 completions 的模型，例如 `gpt-3.5-turbo-instruct`。如果提供商拒绝自定义 temperature 值或令牌限制参数，KNX AI 会仅移除或替换不兼容字段后重试。
 - **System prompt**：KNX 分析全局系统提示词（Advanced）。
+- **允许 AI 读取 KNX 状态并控制执行器**：启用输出 4，默认关闭。可以读取 ETS 目录中的精确对象；仅接受写入明确标记为 `command` 的对象。未知、DPT 不匹配、无效或数量过多的操作，以及向状态或中性对象的写入，都会在本地被拒绝。
+- **发送 KNX 命令前请求确认**：默认启用。先显示已验证的修改，在同一聊天会话确认前不会发送任何 KNX 命令。有命令等待确认时，回复始终会使用当前请求的语言附加准确的确认或取消说明。命令会在输出前再次验证。
+- **适配器预设**：从随附的聊天适配器文件加载一对输入/输出映射。选择预设会有意替换两个文本框，之后仍可编辑代码。
+- **输入映射（聊天 → KNX AI）**：在处理输入命令前运行的同步 JavaScript。
+- **输出映射（KNX AI → 聊天）**：仅应用于输出 3 消息的同步 JavaScript。
 - 如果启用了磁盘归档，**Ask** 默认会查询该归档：若问题里写了明确日期/时间范围就按其查询，否则默认查询最近 24 小时并补上当前 RAM 事件。
 - **Include raw payload hex**：在提示词中包含原始十六进制 payload。
 - **包含 Node-RED 项目清单**：在提示词中加入整个 Node-RED 项目的节点清单，不仅包含 KNX 节点，也包含 function/change/inject/template 等在内且带有 KNX 逻辑或组地址的有用节点。
@@ -84,5 +120,5 @@
 - 若 Node-RED 运行在 Docker 中，endpoint 请使用 `host.docker.internal` 替代 `localhost`。
 
 ## 安全说明
-启用 LLM 后，KNX 流量上下文可能发送到所配置的 endpoint。若需严格本地化，请使用本地 provider。
+启用 LLM 后，KNX 流量上下文可能发送到所配置的 endpoint。若需严格本地化，请使用本地 provider。输出 4 上的命令仅表示已通过本地验证并转发到 flow，并不能证明执行器已执行；需要确认时请使用 KNX 状态 GA。
 </script>

package/nodes/locales/zh-CN/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "快速配置",
       "capture": "Capture",
       "storage": "历史与摘要",
       "detection": "检测与告警",
       "llmConnection": "AI 助手连接",
       "llmContext": "AI 助手上下文",
-      "advanced": "高级调优"
+      "chatAdapter": "聊天适配器",
+      "advanced": "AI 高级设置"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "包含 Node-RED 项目清单",
+      "llmAllowKnxCommands": "允许 AI 读取 KNX 状态并控制执行器",
+      "llmRequireCommandConfirmation": "发送 KNX 命令前请求确认",
+      "chatAdapterPreset": "适配器预设",
+      "chatInputCode": "输入映射（聊天 → KNX AI）",
+      "chatOutputCode": "输出映射（KNX AI → 聊天）",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "摘要/统计",
       "anomalies": "异常",
-      "assistant": "AI 助手"
+      "assistant": "AI 助手",
+      "knxCommands": "KNX 操作"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "无适配器"
       }
     },
     "messages": {
@@ -61,7 +72,9 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "选择预设即可插入输入和输出映射代码。列表从随包提供的聊天适配器文件加载；生成的代码仍可编辑。",
+      "chatAdapterCodeHelp": "映射同步运行。返回 msg 以继续，或不返回值以丢弃消息。错误会被捕获并报告，不会停止 Node-RED。"
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/utils/sysLogger.js

@@ -1,86 +1,8 @@
 /**
 * (C) 2024 Supergiovane
 */
-const util = require('util')
 const logger = require('node-color-log')
 
-const DEBUG_BUFFER_LIMIT = 5000
-const debugBuffer = []
-let debugSequence = 0
-
-const cloneEntry = (entry) => ({
-  seq: entry.seq,
-  level: entry.level,
-  prefix: entry.prefix,
-  message: entry.message,
-  timestamp: entry.timestamp,
-  isoTimestamp: entry.isoTimestamp,
-  sessionStart: entry.sessionStart
-})
-
-const normaliseLevel = (level) => {
-  const allowed = ['success', 'debug', 'info', 'warn', 'error']
-  if (allowed.includes(level)) return level
-  return 'info'
-}
-
-const stringifyArg = (arg) => {
-  if (arg === null) return 'null'
-  if (arg === undefined) return 'undefined'
-  if (arg instanceof Error) return arg.stack || `${arg.name || 'Error'}: ${arg.message}`
-  const type = typeof arg
-  if (type === 'string') return arg
-  if (type === 'number' || type === 'boolean' || type === 'bigint') return String(arg)
-  if (type === 'symbol') return arg.toString()
-  try {
-    return util.inspect(arg, { depth: 6, breakLength: 120, compact: false })
-  } catch (error) {
-    return String(arg)
-  }
-}
-
-const formatArgs = (args) => {
-  if (!args || !args.length) return ''
-  return args.map(stringifyArg).join(' ')
-}
-
-const pushDebugEntry = (level, prefix, args, meta = {}) => {
-  try {
-    const effectiveLevel = normaliseLevel(level)
-    const timestamp = Date.now()
-    const isoTimestamp = new Date(timestamp).toISOString()
-    const message = formatArgs(args)
-    debugSequence += 1
-    debugBuffer.push({
-      seq: debugSequence,
-      level: effectiveLevel,
-      prefix: prefix || '',
-      message,
-      timestamp,
-      isoTimestamp,
-      sessionStart: !!meta.sessionStart
-    })
-    if (debugBuffer.length > DEBUG_BUFFER_LIMIT) {
-      debugBuffer.splice(0, debugBuffer.length - DEBUG_BUFFER_LIMIT)
-    }
-  } catch (error) {
-    // As a last resort, make sure the failure itself is recorded.
-    debugSequence += 1
-    debugBuffer.push({
-      seq: debugSequence,
-      level: 'error',
-      prefix: prefix || '',
-      message: `Logger buffer failure: ${error.message || error}`,
-      timestamp: Date.now(),
-      isoTimestamp: new Date().toISOString(),
-      sessionStart: false
-    })
-    if (debugBuffer.length > DEBUG_BUFFER_LIMIT) {
-      debugBuffer.splice(0, debugBuffer.length - DEBUG_BUFFER_LIMIT)
-    }
-  }
-}
-
 class loggerClass {
   logLevel = 'info'
   prefix = ''
@@ -99,62 +21,31 @@ class loggerClass {
     this.logger.setLevel(requestedLevel)
     this.logger.setDate(() => (new Date()).toLocaleString())
     this.logLevel = requestedLevel
-    pushDebugEntry('info', this.prefix, [`--- Logger session started (level: ${this.logLevel}) ---`], { sessionStart: true })
   }
 
   destroy = () => {
     // Placeholder for backward compatibility; kept for API symmetry.
   }
 
-  record = (level, args) => {
-    pushDebugEntry(level, this.prefix, args)
-  }
-
   success = (...args) => {
-    this.record('success', args)
     this.logger.success(...args)
   }
 
   debug = (...args) => {
-    this.record('debug', args)
     this.logger.debug(...args)
   }
 
   info = (...args) => {
-    this.record('info', args)
     this.logger.info(...args)
   }
 
   warn = (...args) => {
-    this.record('warn', args)
     this.logger.warn(...args)
   }
 
   error = (...args) => {
-    this.record('error', args)
     this.logger.error(...args)
   }
 }
 
-loggerClass.getDebugSnapshot = (options = {}) => {
-  const sinceSeqRaw = options.sinceSeq
-  const sinceSeq = Number.isInteger(sinceSeqRaw) ? sinceSeqRaw : null
-  const source = sinceSeq === null ? debugBuffer : debugBuffer.filter((entry) => entry.seq > sinceSeq)
-  const entries = source.map(cloneEntry)
-  const latestSeq = debugBuffer.length ? debugBuffer[debugBuffer.length - 1].seq : (sinceSeq || 0)
-  return {
-    entries,
-    latestSeq,
-    total: debugBuffer.length,
-    limit: DEBUG_BUFFER_LIMIT
-  }
-}
-
-loggerClass.clearDebugBuffer = () => {
-  debugBuffer.length = 0
-  debugSequence = 0
-}
-
-loggerClass.DEBUG_BUFFER_LIMIT = DEBUG_BUFFER_LIMIT
-
 module.exports = loggerClass

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.1.1",
+  "version": "6.2.0",
   "description": "KNX Ultimate is the most advanced KNX integration for Node-RED, providing secure KNX/IP communication, routing, ETS project import, Philips Hue, Matter Controller and Matter Bridge (control matter device via KNX and expose KNX GA via Matter), MQTT, diagnostics with AI, virtual devices, and powerful automation nodes. Build professional, reliable, and scalable smart home and building automation projects with minimal effort.",
   "files": [
     "nodes/",
@@ -32,7 +32,6 @@
     "version": ">=3.1.1",
     "plugins": {
       "commonFunctions": "/nodes/commonFunctions.js",
-      "knxUltimateMonitorSidebar": "/nodes/plugins/knxUltimateMonitor-sidebar-plugin.html",
       "knxUltimateFlowBubbles": "/nodes/plugins/knxUltimate-flow-bubbles-plugin.html"
     },
     "nodes": {

package/resources/KNXAIChatAdapterMappings.js

@@ -0,0 +1,87 @@
+; (function (root) {
+  const KNXAIChatAdapterMappings = [
+    {
+      id: 'windkh-telegrambot',
+      title: 'windkh/node-red-contrib-telegrambot',
+      inputCode: `// Receiver/Event -> KNX AI
+// Supports "telegram receiver" text messages and "telegram event"
+// callback_query messages produced by inline confirmation buttons.
+const telegram = msg.payload;
+if (!telegram || typeof telegram !== 'object') return;
+
+const chatId = telegram.chatId;
+const content = typeof telegram.content === 'string' ? telegram.content.trim() : '';
+if (chatId === undefined || chatId === null || content === '') return;
+
+msg.sessionId = String(chatId);
+msg.language =
+    (msg.originalMessage && msg.originalMessage.from && msg.originalMessage.from.language_code) ||
+    msg.language ||
+    '';
+
+if (telegram.type === 'callback_query' && (content === 'confirm' || content === 'cancel')) {
+    msg.topic = content;
+    msg.knxAi = Object.assign({}, msg.knxAi, {
+        sessionId: String(chatId),
+        confirm: content === 'confirm'
+    });
+    return msg;
+}
+
+if (telegram.type !== 'message') return;
+msg.topic = 'ask';
+msg.prompt = content;
+return msg;`,
+      outputCode: `// KNX AI chat output -> Telegram sender
+// Converts the text reply and, when required, adds inline
+// confirmation/cancellation buttons.
+const source = msg.inputMessage && typeof msg.inputMessage === 'object'
+    ? msg.inputMessage
+    : inputMessage;
+const sourcePayload = source && source.payload && typeof source.payload === 'object'
+    ? source.payload
+    : {};
+const chatId = sourcePayload.chatId !== undefined
+    ? sourcePayload.chatId
+    : source && source.chatId;
+if (chatId === undefined || chatId === null) return;
+
+let content = msg.payload;
+if (content && typeof content === 'object') {
+    content = content.error || content.message || JSON.stringify(content);
+}
+content = String(content === undefined || content === null ? '' : content);
+
+const telegramPayload = {
+    chatId: chatId,
+    type: 'message',
+    content: content
+};
+const confirmation = msg.knxAi && msg.knxAi.confirmationRequest;
+if (confirmation && confirmation.required === true && Array.isArray(confirmation.actions)) {
+    telegramPayload.options = {
+        reply_markup: JSON.stringify({
+            inline_keyboard: [
+                confirmation.actions.map(function (action) {
+                    return {
+                        text: action.label,
+                        callback_data: action.callbackData
+                    };
+                })
+            ]
+        })
+    };
+}
+
+msg.payload = telegramPayload;
+return msg;`
+    }
+  ]
+
+  if (root) {
+    root.KNXAIChatAdapterMappings = KNXAIChatAdapterMappings
+  }
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = KNXAIChatAdapterMappings
+  }
+})(typeof window !== 'undefined' ? window : (typeof globalThis !== 'undefined' ? globalThis : this))