node-red-contrib-knx-ultimate 6.3.22 → 6.3.25

package/nodes/locales/it/knxUltimateAI.html

@@ -25,9 +25,13 @@ Se l'elaborazione dura più di 1,2 secondi, l'uscita 3 emette subito il messaggi
 
 Le richieste Ollama e Bionic LM Studio usano automaticamente un timeout minimo di 10 minuti; i provider cloud mantengono un minimo di 2 minuti. Non esiste un campo timeout da gestire nell'editor. Se viene raggiunto anche il limite locale, KNX AI segnala che il modello non ha completato la risposta e suggerisce di riprovare o ridurre il contesto del prompt.
 
+Per i provider locali, **Quantità contesto chat** permette di scegliere esplicitamente 4K, 8K o 16K; 16K resta il valore predefinito. La scelta limita proporzionalmente i dati KNX, memoria, progetto Node-RED e adapter forniti al modello, mantenendo completo il contratto degli strumenti dell’agente. Nessuna funzione viene abilitata o disabilitata in base a formulazioni, parole chiave o intent linguistici.
+
 Lo stato del nodo sul canvas è riservato intenzionalmente all'ultima richiesta in ingresso e al messaggio localizzato «Sto pensando…» mentre l'LLM è in esecuzione. Telegrammi KNX, aggiornamenti del gateway, frequenze del traffico, messaggi ready e risultati tecnici non lo sovrascrivono mai; restano disponibili tramite uscite, log e dati dell'Assistente.
 
-Ogni sessione Ask/chat conserva gli ultimi 8 turni e fino a 20 istruzioni esplicite a lungo termine, separate per `msg.knxAi.sessionId`, `msg.sessionId` o chat ID Telegram rilevato. Richieste come «Ricordati di non usare il termine unknown» diventano istruzioni persistenti. Tutti i nodi KNX AI che usano lo stesso storage condividono questo context in tempo reale e lo ricaricano dopo un riavvio di Node-RED da `knxultimatestorage/knxai/memory/knxai-chat-context.md`. Il file, scritto atomicamente, è limitato a 50 sessioni e 512 KB. Quando il controllo KNX è abilitato, collega l'uscita 3 al nodo di risposta della chat e l'uscita 4 a un nodo KNX Ultimate configurato in **Modalità Universale**. Con la conferma attiva, la prima risposta mostra GA, DPT e payload delle scritture senza emetterle; la stessa sessione deve poi rispondere `CONFERMA`/`ANNULLA` entro 5 minuti. Una nuova richiesta sostituisce l'eventuale piano precedente. Ogni comando confermato contiene `msg.destination`, `msg.dpt`, `msg.payload` e `msg.event = "GroupValue_Write"`.
+Ogni sessione Ask/chat conserva gli ultimi 8 turni e fino a 20 istruzioni a lungo termine scelte dal modello, separate per `msg.knxAi.sessionId`, `msg.sessionId` o chat ID Telegram rilevato. È il modello a decidere semanticamente quando il significato di una conversazione vada ricordato o dimenticato tramite lo strumento di memoria strutturato: non esistono liste di parole chiave o intent linguistici. Tutti i nodi KNX AI che usano lo stesso storage condividono questo context in tempo reale e lo ricaricano dopo un riavvio di Node-RED da `knxultimatestorage/knxai/memory/knxai-chat-context.knxctx`. Il file, scritto atomicamente, è limitato a 50 sessioni e 512 KB. Quando il controllo KNX è abilitato, collega l'uscita 3 al nodo di risposta della chat e l'uscita 4 a un nodo KNX Ultimate configurato in **Modalità Universale**. Con la conferma attiva, la prima risposta mostra GA, DPT e payload delle scritture senza emetterle; la stessa sessione deve poi rispondere `CONFERMA`/`ANNULLA` entro 5 minuti. Una nuova richiesta sostituisce l'eventuale piano precedente. Ogni comando confermato contiene `msg.destination`, `msg.dpt`, `msg.payload` e `msg.event = "GroupValue_Write"`.
+La memoria recente della sessione viene collocata immediatamente accanto alla richiesta corrente, così i modelli locali mantengono fatti forniti dall'utente, come nome preferito o lingua, anche dentro un prompt KNX molto grande. Il modello può rendere persistenti fatti, preferenze e istruzioni durevoli tramite `memoryActions`; resta una scelta semantica dello strumento, senza classificatori di frasi o routing per intent. Credenziali, codici di sicurezza e API key non devono mai essere appresi.
+
 Per le scritture DPT 1.xxx, gli equivalenti sicuri prodotti dall'AI `true`/`false`, `1`/`0` e `on`/`off` vengono normalizzati in un vero booleano prima della validazione locale e dell'uscita.
 
 ### Letture KNX aggiornate
@@ -42,24 +46,38 @@ Quando un piano è in attesa, l'uscita 3 contiene `msg.knxAi.confirmationRequest
 ### Preset adattatori chat
 La tab **Adattatori chat** carica le mappature selezionabili da `resources/KNXAIChatAdapterMappings.js`. Scegliendo un preset vengono installate internamente due mappature JavaScript sincrone predefinite: una eseguita prima che KNX AI elabori l'ingresso e una prima dell'emissione sull'uscita 3. Le mappature restano nascoste nell'editor. Errori di sintassi o esecuzione vengono intercettati e segnalati senza arrestare Node-RED.
 
-Il preset incluso **windkh/node-red-contrib-telegrambot** segue il contratto receiver/sender del pacchetto. Collega direttamente un `telegram receiver` a KNX AI e l'uscita 3 direttamente a un `telegram sender`; per usare i pulsanti inline di conferma, collega allo stesso ingresso KNX AI anche un `telegram event` configurato come `callback_query`. La mappatura d'ingresso estrae `msg.payload.content`, `msg.payload.chatId` e la lingua Telegram. Quella d'uscita crea i campi richiesti `msg.payload.chatId`, `type` e `content`, aggiungendo `options.reply_markup` da `msg.knxAi.confirmationRequest` quando una scrittura attende conferma. Il pacchetto Telegram resta una dipendenza opzionale separata.
+Il preset incluso **windkh/node-red-contrib-telegrambot** segue il contratto receiver/sender del pacchetto. Collega direttamente un `telegram receiver` a KNX AI e l'uscita 3 direttamente a un `telegram sender`. La conferma usa una tastiera Telegram temporanea: premendo **Conferma** o **Annulla** viene inviato un normale messaggio localizzato attraverso lo stesso receiver, quindi non servono `telegram event` né collegamenti callback. I vecchi messaggi `callback_query` restano accettati. La mappatura d'ingresso estrae `msg.payload.content`, `msg.payload.chatId` e la lingua Telegram. Quella d'uscita crea i campi richiesti `msg.payload.chatId`, `type` e `content`, aggiungendo `options.reply_markup` da `msg.knxAi.confirmationRequest` quando una scrittura attende conferma. Il pacchetto Telegram resta una dipendenza opzionale separata.
 
 Il preset incluso **RedBot / node-red-contrib-chatbot (Telegram)** segue il formato comune dei messaggi RedBot. Collega direttamente `chatbot-telegram-receive` a KNX AI e l'uscita 3 direttamente a `chatbot-telegram-send`; non serve un nodo callback separato perché RedBot converte i postback dei pulsanti inline in normali messaggi in ingresso. La mappatura d'ingresso legge `transport`, `chatId`, `type`, `content` e la lingua Telegram. Quella d'uscita conserva i dati di tracciamento RedBot `originalMessage`, `chat`, `api` e `client`, quindi emette un payload `message` oppure un payload `inline-buttons` con azioni `postback` per la conferma. RedBot resta una dipendenza opzionale separata.
 
 ### Adapter telecamera rilevati automaticamente
 I pacchetti di telecamere installati possono pubblicare a runtime un adapter per KNX AI. Non esistono selettori né nodi telecamera da collegare a KNX AI: adapter, controller e telecamere disponibili vengono rilevati automaticamente e inseriti nel contesto della chat. `node-red-contrib-unifi-ultimate` è il primo provider supportato; altri pacchetti, come `hikvision-ultimate`, possono registrarsi tramite lo stesso contratto indipendente dal produttore.
 
-L'utente può chiedere uno snapshot aggiornato oppure domandare al modello vision che cosa è visibile. I preset Telegram e RedBot inviano l'immagine come foto nativa con didascalia. L'utente può anche creare notifiche persistenti per movimento, attraversamento di una linea intelligente o ingresso in una zona di intrusione/stazionamento, limitandole facoltativamente alle persone rilevate e a una linea o zona nominata esatta. Le regole vengono salvate nello stesso file `knxai-chat-context.md` e ripristinate dopo i riavvii di Node-RED. Le sottoscrizioni agli eventi UniFi e le richieste snapshot avvengono direttamente tramite il provider rilevato: l'uscita 4 di KNX AI non è coinvolta e non servono collegamenti intermedi nel flow.
+L'utente può chiedere uno snapshot aggiornato oppure domandare al modello vision che cosa è visibile. I preset Telegram e RedBot inviano l'immagine come foto nativa con didascalia. L'utente può anche creare notifiche persistenti per movimento, attraversamento di una linea intelligente o ingresso in una zona di intrusione/stazionamento, limitandole facoltativamente alle persone rilevate e a una linea o zona nominata esatta. Le regole vengono salvate nello stesso file `knxai-chat-context.knxctx` e ripristinate dopo i riavvii di Node-RED. Le sottoscrizioni agli eventi UniFi e le richieste snapshot avvengono direttamente tramite il provider rilevato: l'uscita 4 di KNX AI non è coinvolta e non servono collegamenti intermedi nel flow.
 
-Ogni evento pubblicato da un adapter rilevato automaticamente viene normalizzato e aggiunto a un file giornaliero `YYYY-MM-DD.jsonl` sotto `knxultimatestorage/knxai/adapter-history/<id-nodo>/`. L'archivio conserva 10 giorni, garantisce più di 24 ore di storico e salva i metadati degli eventi, non le immagini. Assistente web e canali CHAT lo interrogano insieme all'archivio giornaliero KNX. I totali comprendono tutte le righe memorizzate nell'intervallo richiesto; i dettagli selezionati sono soltanto un campione pertinente.
+Ogni evento pubblicato da un adapter rilevato automaticamente viene normalizzato e aggiunto direttamente nel formato nativo compatto a righe di KNX AI a un file giornaliero `YYYY-MM-DD.knxctx` sotto `knxultimatestorage/knxai/adapter-history/<id-nodo>/`. L'archivio dei telegrammi KNX usa lo stesso formato compatto, senza serializzazione JSON intermedia. L'archivio conserva 10 giorni, garantisce più di 24 ore di storico e salva i metadati degli eventi, non le immagini. Gli archivi JSONL esistenti non vengono letti né migrati. I totali comprendono tutte le righe memorizzate nell'intervallo richiesto; i dettagli selezionati sono soltanto un campione pertinente.
 
 ### Annunci con TTS Ultimate
 Quando è installato il pacchetto opzionale `node-red-contrib-tts-ultimate`, questo compare tra gli adapter rilevati automaticamente. Il selettore elenca tutti i nodi `ttsultimate` presenti in tutti i flow del progetto, indicando flow, nome del nodo e player configurato. Scegli il nodo che deve gestire gli annunci della chat e fai il deploy del flow.
 
-Solo una richiesta esplicita nel messaggio corrente della chat può creare un annuncio. KNX AI invia il testo esatto direttamente al nodo scelto come `msg.payload`, con `msg.topic = "knx_ai_announcement"`; non servono collegamenti intermedi nel flow. TTS Ultimate gestisce poi il player Sonos configurato, voce, volume, hailing e coda. Contesto persistente, Educazione AI, contenuto delle telecamere ed eventi dedotti non attivano mai autonomamente la voce.
+Il modello decide se usare questo adapter ragionando sulla richiesta corrente, sulle istruzioni persistenti della chat e sull'Educazione AI gestita dall'utente: non esistono intent per gli annunci né liste di frasi di attivazione. Valori KNX, eventi degli adapter, immagini e archivi restano dati e non diventano istruzioni, ma le indicazioni autorevoli dell'utente possono insegnare al modello come agire su quei dati. KNX AI invia il testo scelto direttamente al nodo come `msg.payload`, con `msg.topic = "knx_ai_announcement"`; non servono collegamenti intermedi nel flow. TTS Ultimate gestisce poi player Sonos, voce, volume, hailing e coda.
 
 ### Riepilogo del contesto della chat
-L'editor del nodo mostra una scheda compatta con le fonti disponibili alla chat: traffico KNX corrente e archiviato, eventi persistenti degli adapter, semantica ETS e progetto Node-RED, memoria di sessione e domestica, Educazione AI e telecamere rilevate. Mostra anche il contesto operativo massimo e il peso UTF-8 effettivo dell'ultimo prompt della chat; quando il provider comunica i token di input viene usato il valore esatto, altrimenti il conteggio è indicato come stima. La scheda elenca le directory assolute degli archivi KNX e degli eventi adapter e il formato giornaliero `YYYY-MM-DD.jsonl`.
+L'editor del nodo mostra una scheda compatta con le fonti disponibili alla chat: traffico KNX corrente e archiviato, eventi persistenti degli adapter, semantica ETS e progetto Node-RED, memoria di sessione e domestica, Educazione AI e telecamere rilevate. Mostra anche il contesto operativo massimo scelto dall'utente e il peso UTF-8 effettivo dell'ultimo prompt della chat; quando il provider comunica i token di input viene usato il valore esatto, altrimenti il conteggio è indicato come stima. La scheda elenca le directory assolute degli archivi KNX e degli eventi adapter e il formato giornaliero `YYYY-MM-DD.knxctx`.
+
+Il modello riceve letture e scritture KNX, adapter telecamera, annunci TTS e memoria persistente come strumenti strutturati. Può sceglierli e combinarli semanticamente partendo dalla richiesta corrente e dalle indicazioni autorevoli apprese, senza routing per intent linguistici. Il runtime valida soltanto argomenti, disponibilità degli adapter e confini di sicurezza; le scritture KNX conservano validazione ETS/DPT locale e conferma configurata.
+
+### Modifica e backup dell'apprendimento CHAT
+La scheda **Conversazioni e casa** nella configurazione Node-RED di KNX AI include il pulsante **Apri Apprendimento AI Chat**, che apre la Web UI Vue direttamente su questo editor per il nodo corrente.
+
+Nella UI web Vue, apri **Impostazioni → Apprendimento AI Chat** per visualizzare e modificare il file condiviso esatto `knxai-chat-context.knxctx` e il suo percorso assoluto. Il file può essere copiato, scaricato come backup o ripristinato da un altro file `.knxctx`. **Re-inizializza memoria**, protetto da una conferma esplicita, lo sostituisce con un nuovo contesto vuoto e cancella sessioni, istruzioni, sorveglianze telecamera e conferme chat pendenti in ogni nodo KNX AI che usa lo stesso archivio. I record nativi separati da tabulazioni `KNXAI_CHAT_CONTEXT 3` sono autorevoli e direttamente modificabili: `SESSION` contiene record `INSTRUCTION`, `TURN` e `CAMERA_WATCH` fino a `END_SESSION`. Il salvataggio valida e limita questi record, riscrive atomicamente il file e aggiorna il contesto attivo di ogni nodo KNX AI che usa lo stesso archivio. Un controllo di revisione impedisce di sovrascrivere o azzerare l'apprendimento cambiato dopo il caricamento nell'editor.
+
+È supportato soltanto il formato nativo V3. I precedenti file Markdown/JSON V2 e Base64 V1 non vengono volutamente letti, importati né migrati; il vecchio file `.md` resta intatto e KNX AI avvia un nuovo contesto `.knxctx`. Restano validi i limiti di 50 sessioni e 512 KB.
+
+### Ruoli appresi dei group address KNX
+Il ruolo `neutral` indica un'incertezza iniziale, non un divieto permanente di controllo. Il modello può usare lo strumento strutturato `gaRoleActions` per imparare che un group address ETS esatto è un oggetto di comando, stato o neutro partendo dall'insegnamento autorevole dell'utente, dalle indicazioni persistenti della chat, dall'Educazione AI o da una semantica inequivocabile del progetto ETS. Non servono parole chiave né intent di ruolo; se le prove sono ambigue, il modello chiede un chiarimento invece di imparare.
+
+Ruolo, motivazione e prova appresi vengono salvati per nodo in `<userDir>/knxai/config/knxai-config-<id-nodo>.json` e sincronizzati nella memoria semantica domestica limitata. Un ruolo appreso come `command` può rendere valida una scrittura già nella stessa risposta e resta disponibile dopo il riavvio; il modello può anche dimenticarlo e ripristinare la classificazione automatica. L'apprendimento non può inventare un GA, cambiarne il DPT ETS, aggirare la validazione del payload o saltare la conferma di scrittura configurata.
 
 ## Intelligenza domestica proattiva guidata dall'Educazione e memoria limitata
 Da gerarchia ETS, nomi, ruoli e DPT, il nodo crea un modello semantico deterministico per persiane, finestre, porte, luci, temperatura, clima, presenza e allarmi usando termini italiani, inglesi, tedeschi, francesi, spagnoli e cinesi. Il rilevatore proattivo osserva soltanto stati non di comando di persiane, finestre e porte riconosciuti con sufficiente affidabilità.
@@ -131,7 +149,7 @@ Di seguito sono elencati tutti i campi presenti nell'editor del nodo KNX AI.
   - **2) Installalo**: scarica e installa localmente il modello (esempio `llama3.1`).
 - Durante refresh/installazione, KNX AI prova anche ad avviare automaticamente il server Ollama quando possibile.
 - Se l'installazione fallisce per errore di connessione, verifica che Ollama sia avviato (app desktop o `ollama serve`).
-- Il contesto massimo dichiarato da `/api/show` resta informativo. KNX AI invia sempre `num_ctx = 16384` (oppure il massimo del modello se inferiore) e usa la stessa vista semantica di 16K selezionata per pertinenza, evitando una KV cache sovradimensionata senza rimuovere capacità dell'agente.
+- Il contesto massimo dichiarato da `/api/show` resta informativo. KNX AI invia come `num_ctx` il budget scelto di 4K, 8K o 16K (oppure il massimo del modello se inferiore) e limita proporzionalmente ogni fonte di contesto senza rimuovere capacità dell'agente.
 - Se Node-RED gira in Docker, usa `host.docker.internal` al posto di `localhost` nell'endpoint.
 
 ### Setup rapido Bionic LM Studio (locale)
@@ -139,7 +157,7 @@ Di seguito sono elencati tutti i campi presenti nell'editor del nodo KNX AI.
 - Avvia il server API di LM Studio dalla pagina **Developer** oppure con `lms server start`.
 - Endpoint predefinito: `http://localhost:1234/v1/chat/completions`.
 - Premi **Aggiorna** per caricare tutti i modelli esposti da `/v1/models`; se non è configurato un modello viene selezionato il primo.
-- Se un modello è già caricato, KNX AI conserva la lunghezza del contesto attiva. KNX AI non carica mai un modello Bionic inattivo tramite l'API di gestione: la prima richiesta chat lascia che Bionic lo carichi JIT con i valori predefiniti salvati per il modello. Indipendentemente dal contesto dichiarato da Bionic, KNX AI limita sempre il proprio prompt a una vista semantica di 16K selezionata per pertinenza; evita così di inviare l'intero insieme di dati da 131K senza rimuovere capacità di ragionamento, KNX, routine, telecamere o TTS.
+- Se un modello è già caricato, KNX AI conserva la lunghezza del contesto attiva. KNX AI non carica mai un modello Bionic inattivo tramite l'API di gestione: la prima richiesta chat lascia che Bionic lo carichi JIT con i valori predefiniti salvati per il modello. Indipendentemente dal contesto dichiarato da Bionic, KNX AI usa il budget prompt scelto di 4K, 8K o 16K e mantiene disponibili ragionamento, KNX, routine, telecamere e TTS.
 - La API key è opzionale, salvo autenticazione attiva nelle impostazioni del server LM Studio. In Docker sostituisci `localhost` con `host.docker.internal`.
 
 ## Nota sicurezza

package/nodes/locales/it/knxUltimateAI.json

@@ -6,6 +6,7 @@
       "groupChatHome": "Conversazioni e casa",
       "detectedAdapters": "Adapter rilevati automaticamente",
       "chatContextOverview": "Contesto disponibile alla chat",
+      "chatLearning": "Apprendimento AI Chat",
       "quickSetup": "Configurazione assistente",
       "llmConnection": "Connessione Assistente AI",
       "chatAdapter": "Canali chat",
@@ -21,6 +22,7 @@
       "llmBaseUrl": "URL endpoint",
       "llmApiKey": "API key",
       "llmModel": "Modello",
+      "llmPromptContextTokens": "Quantità contesto chat",
       "llmSystemPrompt": "Prompt di sistema",
       "llmIncludeRaw": "Includi payload raw in hex",
       "llmAllowKnxCommands": "Consenti all'AI di leggere stati KNX e comandare attuatori",
@@ -45,6 +47,11 @@
         "ollama": "Ollama (locale)",
         "lmstudio": "Bionic LM Studio"
       },
+      "promptContext": {
+        "small": "Ridotto (4K, più veloce)",
+        "medium": "Medio (8K)",
+        "full": "Completo (16K)"
+      },
       "chatAdapter": {
         "none": "Nessun adattatore"
       },
@@ -57,7 +64,8 @@
       "refreshModels": "Aggiorna",
       "installOllamaModel": "2) Installalo",
       "ollamaLibrary": "Libreria modelli",
-      "downloadOllamaModel": "1) Scarica il modello"
+      "downloadOllamaModel": "1) Scarica il modello",
+      "openChatLearning": "Apri Apprendimento AI Chat"
     },
     "messages": {
       "loadingModels": "Carico i modelli…",
@@ -69,6 +77,7 @@
       "lmStudioContextFailed": "Impossibile configurare il contesto del modello",
       "lmStudioContextCurrentlyLoaded": "attualmente caricato",
       "localContextBudget": "Budget contesto KNX AI",
+      "promptContextHint": "Controlla la quantità di contesto KNX, memoria, progetto e adapter inviata ai modelli locali. Non abilita o disabilita strumenti e non usa intent linguistici.",
       "ollamaNotSupported": "Modalita locale Ollama: API key non richiesta. Endpoint predefinito: http://localhost:11434/api/chat.",
       "ollamaNoModels": "Nessun modello Ollama locale trovato. Installa un modello o scegli dalla libreria.",
       "installingOllamaModel": "Avvio Ollama e installo il modello…",
@@ -88,6 +97,7 @@
       "ttsUltimateHint": "Le richieste esplicite di annuncio della chat vengono inviate direttamente al nodo scelto; non servono collegamenti nel flow.",
       "chatContextLoading": "Caricamento del riepilogo del contesto…",
       "chatContextUnavailable": "Il riepilogo del contesto della chat non è momentaneamente disponibile.",
+      "chatLearningOpenHint": "Apri la Web UI direttamente nell’editor dell’apprendimento CHAT condiviso per visualizzare, modificare, copiare o salvare il suo file persistente.",
       "chatContextIntro": "La chat riceve automaticamente queste fonti. I percorsi sottostanti sono quelli effettivi usati da questa installazione Node-RED.",
       "chatContextLimitLabel": "Contesto operativo massimo",
       "chatContextProviderManaged": "gestito dal provider/modello selezionato",

package/nodes/locales/it/knxUltimateIoTBridge.html

@@ -45,7 +45,8 @@ Il resto di questo aiuto descrive la modalità classica **Bridge IoT**.
 ## Campi della mappatura
 
 - **Direzione** — scegli KNX→IoT, IoT→KNX oppure bidirezionale.
-- **Tipo canale** — per MQTT il target è il topic; per REST è l'URL base; per Modbus è il registro/indirizzo.
+- **Tipo canale** — per MQTT il target è il topic; per REST è l'URL base; per Modbus **Target** è l'indirizzo di protocollo zero-based (0–65535).
+- **Formato Modbus / Unit ID / Area / Tipo di dato** — per le nuove mappature scegli **Compatibile con Flex Write**, quindi imposta unità, area di memoria e `bool`, `uint16` o `int16`. Se il formato è assente resta attivo il contratto scalare legacy, così i flow esistenti continuano a funzionare.
 - **Scala & Offset** — applicati su KNX→IoT; IoT→KNX usa la trasformazione inversa.
 - **Template** — stringa opzionale con segnaposto `{{value}}`, `{{ga}}`, `{{label}}`, `{{target}}`, `{{type}}`, `{{isoTimestamp}}`.
 - **Timeout / Tentativi** — campi informativi esposti nel messaggio in uscita per i nodi successivi.
@@ -88,7 +89,32 @@ Il resto di questo aiuto descrive la modalità classica **Bridge IoT**.
 
 ### Sincronizzazione Modbus
 
-- Abbina il bridge ai nodi `node-red-contrib-modbus` (`modbus-flex-write`). L'uscita 1 fornisce `msg.address` e `msg.payload` già pronti.
+Il bridge è un adattatore di messaggi per `node-red-contrib-modbus`: non apre connessioni TCP/seriali e non interroga autonomamente il dispositivo. Installa una versione del pacchetto compatibile con il tuo runtime Node-RED, poi usa i suoi nodi client e di trasporto.
+
+|Area|Lettura|Scrittura|Direzione ammessa|
+|--|--|--|--|
+| Coil | FC1 | FC5 | Entrambe le direzioni |
+| Discrete input | FC2 | — | Solo Modbus → KNX |
+| Holding register | FC3 | FC6 | Entrambe le direzioni |
+| Input register | FC4 | — | Solo Modbus → KNX |
+
+Per una nuova mappatura seleziona `Formato = Compatibile con Flex Write`. Da KNX a Modbus, l'output 1 si collega direttamente a un nodo `modbus-flex-write` ed emette:
+
+```
+msg.payload = {
+  value: 215,
+  fc: 6,
+  unitid: 1,
+  address: 9,
+  quantity: 1
+}
+```
+
+`address` è sempre zero-based: se il manuale del dispositivo indica un holding register come `40010`, il relativo indirizzo di protocollo è comunemente `9`; verifica la convenzione nel manuale. Il bridge gestisce un bit o un singolo registro a 16 bit per mappatura. Al momento non combina più word, non decodifica valori a 32 bit/float e non gestisce l'ordine di byte/word.
+
+Da Modbus a KNX, collega l'uscita dati di un nodo `modbus-flex-getter` o `modbus-read` all'ingresso del bridge. Flex Getter fornisce la richiesta (`fc`, `unitid`, `address`, `quantity`) in `msg.modbusRequest`; Modbus Read la conserva in `msg.input.payload`. L'array dei valori restituiti può trovarsi in `msg.payload` oppure in `msg.values`. Il bridge supporta entrambe le forme, abbina tutte le mappature Flex comprese nella risposta e usa l'elemento corretto dell'array. Abilita **Keep Msg Properties** su Flex Getter. Scala e offset seguono `raw = KNX × scala + offset`; in ingresso viene applicata la trasformazione inversa.
+
+`Leggi valori KNX al deploy` legge soltanto KNX; pianifica le letture Modbus nel flow Modbus esterno. Le mappature legacy (comprese quelle senza `modbusMessageFormat`) continuano a emettere il precedente payload scalare con i metadati `msg.address`/`msg.modbusFunction` al livello principale.
 
 ## Flow di esempio
 

package/nodes/locales/it/knxUltimateIoTBridge.json

@@ -79,6 +79,10 @@
       "target": "Target",
       "method": "Metodo HTTP",
       "modbusFunction": "Funzione Modbus",
+      "modbusMessageFormat": "Formato messaggio Modbus",
+      "modbusUnitId": "Unit ID",
+      "modbusArea": "Area Modbus",
+      "modbusDataType": "Tipo di dato",
       "scale": "Scala",
       "offset": "Offset",
       "timeout": "Timeout (ms)",
@@ -103,7 +107,7 @@
       "target": "Topic, URL o registro",
       "target_mqtt": "Topic, es. knx/light/soggiorno",
       "target_rest": "https://example/api/endpoint",
-      "target_modbus": "Registro (es. 40001)",
+      "target_modbus": "Indirizzo zero-based (es. 0)",
       "template": "{\"value\":{{value}}}",
       "property": "Proprietà/percorso opzionale",
       "method": "POST",
@@ -114,7 +118,7 @@
         "default": "Target",
         "mqtt": "Topic MQTT",
         "rest": "URL REST",
-        "modbus": "Registro Modbus"
+        "modbus": "Indirizzo Modbus (zero-based)"
       },
       "method": {
         "default": "Metodo HTTP",
@@ -125,6 +129,20 @@
         "modbus": "Funzione Modbus"
       }
     },
+    "modbus": {
+      "formatLegacy": "Messaggio scalare legacy",
+      "formatFlex": "Compatibile con Flex Write",
+      "areaCoil": "Coil (lettura FC1 / scrittura FC5)",
+      "areaDiscreteInput": "Discrete input (lettura FC2, sola lettura)",
+      "areaHoldingRegister": "Holding register (lettura FC3 / scrittura FC6)",
+      "areaInputRegister": "Input register (lettura FC4, sola lettura)",
+      "dataTypeBool": "Booleano",
+      "dataTypeUint16": "16 bit senza segno",
+      "dataTypeInt16": "16 bit con segno",
+      "zeroBasedHint": "Usa l’indirizzo di protocollo zero-based (0–65535), non il riferimento 4xxxx riportato da alcuni manuali.",
+      "flexHint": "Flex emette msg.payload = {value,fc,unitid,address,quantity}, collegabile direttamente a modbus-flex-write.",
+      "readOnlyHint": "Discrete input e input register sono di sola lettura e possono usare solo Modbus → KNX."
+    },
     "labels": {
       "outputKnxToIoT": "Flusso KNX → IoT",
       "outputIoTToKnx": "Ack IoT → KNX",

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

@@ -25,9 +25,13 @@
 
 Ollama 和 Bionic LM Studio 请求会自动使用至少 10 分钟的超时时间；云端提供商仍使用至少 2 分钟。编辑器中无需维护超时字段。即使达到本地模型限制，KNX AI 也会说明模型未完成响应，并建议重试或缩减提示上下文。
 
+对于本地提供商，**聊天上下文量**可明确选择 4K、8K 或 16K；默认仍为 16K。该选择会按比例限制发送给模型的 KNX、记忆、Node-RED 项目和适配器数据，同时保留完整的代理工具协议。任何能力都不会因措辞、关键词或语言 intent 而被启用或禁用。
+
 Canvas 上的节点状态专门用于显示最近收到的请求，以及 LLM 运行期间本地化的“我正在思考…”状态。KNX 报文、网关更新、流量速率、ready 消息和技术结果绝不会覆盖该状态；这些信息仍可通过节点输出、日志和助手数据查看。
 
-每个 Ask/聊天会话都会保留最近 8 轮对话和最多 20 条明确的长期指令，并按 `msg.knxAi.sessionId`、`msg.sessionId` 或检测到的 Telegram 聊天 ID 隔离。像“请记住不要在回答中使用 unknown 这个词”这样的请求会成为持久指令。使用相同存储的所有 KNX AI 节点实时共享此上下文，并在 Node-RED 重启后从 `knxultimatestorage/knxai/memory/knxai-chat-context.md` 重新加载。该文件采用原子写入，最多保存 50 个会话且不超过 512 KB。启用 KNX 控制后，将输出 3 连接到聊天发送节点，将输出 4 连接到配置为**通用模式**的 KNX Ultimate 节点。启用确认后，第一条回复会显示 GA、DPT 和 payload，但不会发送写入；同一会话必须在 5 分钟内回复“确认”或“取消”。新请求会替换旧的待处理计划。每条已确认命令都包含 `msg.destination`、`msg.dpt`、`msg.payload` 和 `msg.event = "GroupValue_Write"`。
+每个 Ask/聊天会话都会保留最近 8 轮对话和最多 20 条由模型选择的长期指令，并按 `msg.knxAi.sessionId`、`msg.sessionId` 或检测到的 Telegram 聊天 ID 隔离。模型通过结构化记忆工具，按语义判断一段对话的含义应被记住还是遗忘；系统不使用语言关键词或 intent 列表。使用相同存储的所有 KNX AI 节点实时共享此上下文，并在 Node-RED 重启后从 `knxultimatestorage/knxai/memory/knxai-chat-context.knxctx` 重新加载。该文件采用原子写入，最多保存 50 个会话且不超过 512 KB。启用 KNX 控制后，将输出 3 连接到聊天发送节点，将输出 4 连接到配置为**通用模式**的 KNX Ultimate 节点。启用确认后，第一条回复会显示 GA、DPT 和 payload，但不会发送写入；同一会话必须在 5 分钟内回复“确认”或“取消”。新请求会替换旧的待处理计划。每条已确认命令都包含 `msg.destination`、`msg.dpt`、`msg.payload` 和 `msg.event = "GroupValue_Write"`。
+最近的会话记忆会紧邻当前请求放置，使本地模型即使面对很大的 KNX 提示，也能保留用户提供的事实，例如首选姓名或语言。模型可以通过 `memoryActions` 持久保存耐久的事实、偏好和指令；这仍是没有短语分类器或 intent 路由的语义工具选择。凭据、安全代码和 API 密钥绝不能被学习。
+
 对于 DPT 1.xxx 写入，AI 生成的安全等价值 `true`/`false`、`1`/`0` 和 `on`/`off` 会在本地校验和输出前统一转换为真正的布尔值。
 
 ### 最新 KNX 读取
@@ -42,24 +46,38 @@ Canvas 上的节点状态专门用于显示最近收到的请求，以及 LLM
 ### 聊天适配器预设
 **聊天适配器**选项卡从 `resources/KNXAIChatAdapterMappings.js` 加载可选映射。选择预设会在内部安装两段预定义的同步 JavaScript 映射：一段在 KNX AI 处理输入前运行，另一段在输出 3 发出消息前运行。这些映射在编辑器中始终保持隐藏。语法和执行错误会被捕获并报告，不会停止 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 包仍是独立的可选依赖项。
+随附的 **windkh/node-red-contrib-telegrambot** 预设遵循该包的 receiver/sender 消息约定。把 `telegram receiver` 直接连接到 KNX AI，并把输出 3 直接连接到 `telegram sender`。确认操作使用一次性 Telegram 回复键盘：点击**确认**或**取消**后，会通过同一个 receiver 返回普通的本地化消息，因此不需要 `telegram event` 或 callback 连线。旧的 `callback_query` 消息仍可接受。输入映射会提取 `msg.payload.content`、`msg.payload.chatId` 和 Telegram 语言；输出映射会创建所需的 `msg.payload.chatId`、`type` 和 `content`，并在写入等待确认时从 `msg.knxAi.confirmationRequest` 添加 `options.reply_markup`。Telegram 包仍是独立的可选依赖项。
 
 随附的 **RedBot / node-red-contrib-chatbot (Telegram)** 预设遵循 RedBot 的通用消息格式。将 `chatbot-telegram-receive` 直接连接到 KNX AI，并将输出 3 直接连接到 `chatbot-telegram-send`；无需单独的 callback 节点，因为 RedBot 会把内联按钮的 postback 转换成普通入站消息。输入映射读取 `transport`、`chatId`、`type`、`content` 和 Telegram 语言。输出映射保留 RedBot 的 `originalMessage`、`chat`、`api` 和 `client` 跟踪数据，然后发送 `message` payload，或发送带有确认 `postback` 操作的 `inline-buttons` payload。RedBot 仍是独立的可选依赖项。
 
 ### 自动检测的摄像机适配器
 已安装的摄像机软件包可以在运行时向 KNX AI 发布适配器。无需选择器，也无需将摄像机节点连接到 KNX AI：可用的适配器、控制器和摄像机会被自动检测并加入聊天上下文。`node-red-contrib-unifi-ultimate` 是首个受支持的提供方；`hikvision-ultimate` 等其他软件包可通过同一套厂商无关协议注册。
 
-用户可以请求当前快照，或询问视觉模型画面中可见的内容。Telegram 和 RedBot 预设会把图像作为带说明文字的原生照片发送。用户还可以为移动、智能越线或进入入侵/徘徊区域创建持久通知，并可按检测到的人员以及指定名称的线或区域进行限制。这些规则保存在同一个 `knxai-chat-context.md` 文件中，并在 Node-RED 重启后恢复。UniFi 事件订阅和快照请求直接通过检测到的提供方完成；不会使用 KNX AI 输出 4，也不需要中间 Flow 连线。
+用户可以请求当前快照，或询问视觉模型画面中可见的内容。Telegram 和 RedBot 预设会把图像作为带说明文字的原生照片发送。用户还可以为移动、智能越线或进入入侵/徘徊区域创建持久通知，并可按检测到的人员以及指定名称的线或区域进行限制。这些规则保存在同一个 `knxai-chat-context.knxctx` 文件中，并在 Node-RED 重启后恢复。UniFi 事件订阅和快照请求直接通过检测到的提供方完成；不会使用 KNX AI 输出 4，也不需要中间 Flow 连线。
 
-自动检测到的适配器发布的每个事件都会被标准化，并追加到 `knxultimatestorage/knxai/adapter-history/<节点ID>/` 下的每日 `YYYY-MM-DD.jsonl` 文件。存档保留 10 天，保证超过 24 小时的历史，只保存事件元数据，不保存图像。Web 助手和所有 CHAT 渠道会同时查询它与每日 KNX 报文存档。总数涵盖所请求区间内的全部存档行；选出的详情仅是相关样本。
+自动检测到的适配器发布的每个事件都会被标准化，并以 KNX AI 原生紧凑行格式直接追加到 `knxultimatestorage/knxai/adapter-history/<节点ID>/` 下的每日 `YYYY-MM-DD.knxctx` 文件。KNX 报文存档使用相同的紧凑格式，不经过中间 JSON 序列化。存档保留 10 天，保证超过 24 小时的历史，只保存事件元数据，不保存图像。现有 JSONL 存档不会被读取或迁移。总数涵盖所请求区间内的全部存档行；选出的详情仅是相关样本。
 
 ### 使用 TTS Ultimate 播报
 安装可选软件包 `node-red-contrib-tts-ultimate` 后，它会显示在自动检测的适配器中。选择器会列出项目所有 Flow 中的全部 `ttsultimate` 节点，并显示 Flow、节点名称和已配置的播放器。请选择负责聊天播报的节点，然后部署 Flow。
 
-只有当前聊天消息中的明确请求才能创建播报。KNX AI 会将准确文本作为 `msg.payload` 直接发送到所选节点，并设置 `msg.topic = "knx_ai_announcement"`；无需在 Flow 中增加中间连线。之后由 TTS Ultimate 处理已配置的 Sonos 播放器、语音、音量、提示音和队列。持久上下文、AI 教育、摄像机内容和推断事件绝不会自行触发语音。
+模型会根据当前请求、持久聊天指令和用户管理的 AI 教育自行判断是否使用此适配器；系统没有播报 intent，也没有触发短语列表。KNX 数值、适配器事件、图像和存档始终是数据而不是指令，但可信的用户指导可以教会模型如何处理这些数据。KNX AI 会将选定文本作为 `msg.payload` 直接发送到所选节点，并设置 `msg.topic = "knx_ai_announcement"`；之后由 TTS Ultimate 处理 Sonos 播放器、语音、音量、提示音和队列。
 
 ### 聊天上下文概览
-节点编辑器会显示一张紧凑卡片，汇总聊天可用的来源：当前 KNX 流量、ETS 语义与 Node-RED 项目、会话和家庭记忆、AI 教育及检测到的摄像机。卡片还会显示最大运行上下文和上次聊天提示词的实际 UTF-8 大小；提供商返回输入令牌数时使用精确值，否则明确标为估算值。卡片还会列出 `knxai-chat-context.md`、`knxai-home-memory.md` 和 `knxai-config-<节点-id>.json`，以及 KNX 报文归档的绝对根目录、该节点专用目录和每日文件模式 `YYYY-MM-DD.jsonl`。这些路径会在运行时根据已配置网关实际使用的数据目录解析。
+节点编辑器会显示一张紧凑卡片，汇总聊天可用的来源：当前 KNX 流量、ETS 语义与 Node-RED 项目、会话和家庭记忆、AI 教育及检测到的摄像机。卡片还会显示用户选择的最大运行上下文和上次聊天提示词的实际 UTF-8 大小；提供商返回输入令牌数时使用精确值，否则明确标为估算值。卡片还会列出 `knxai-chat-context.knxctx`、`knxai-home-memory.md` 和 `knxai-config-<节点-id>.json`，以及 KNX 报文归档的绝对根目录、该节点专用目录和每日文件模式 `YYYY-MM-DD.knxctx`。这些路径会在运行时根据已配置网关实际使用的数据目录解析。
+
+模型会把 KNX 读写、摄像机适配器、TTS 播报和持久记忆作为结构化工具。它可以依据当前请求和可信的已学习指导进行语义选择与组合，而不经过语言 intent 路由。运行时只验证工具参数、适配器可用性和安全边界；KNX 写入仍保留本地 ETS/DPT 校验和已配置的确认步骤。
+
+### 编辑和备份聊天学习
+Node-RED 的 KNX AI 配置中，**对话与家庭**选项卡包含**打开 AI 聊天学习**按钮；它会为当前节点直接打开 Vue Web UI 中的此编辑器。
+
+在 Vue Web UI 中打开**设置 → AI 聊天学习**，即可查看和编辑准确的共享文件 `knxai-chat-context.knxctx` 及其绝对路径。可复制该文件、下载备份，或从另一个 `.knxctx` 文件恢复。**重新初始化记忆**操作受明确确认保护；它会用新的空白上下文替换该文件，并清除使用同一存储的所有 KNX AI 节点中的已保存会话、指令、摄像机监视和待处理聊天确认。以制表符分隔的原生 `KNXAI_CHAT_CONTEXT 3` 记录是权威数据，并可直接编辑：`SESSION` 包含 `INSTRUCTION`、`TURN` 和 `CAMERA_WATCH` 记录，直至 `END_SESSION`。保存时会验证并限制这些记录、以原子方式重写文件，并立即更新所有相关节点的活动上下文。修订检查会拒绝覆盖或重置编辑器加载后又发生变化的学习内容。
+
+仅支持原生 V3 格式。旧版 Markdown/JSON V2 和 Base64 V1 文件不会被读取、导入或迁移；旧的 `.md` 文件保持不变，KNX AI 会启动新的 `.knxctx` 上下文。仍保留 50 个会话和 512 KB 的限制。
+
+### 学习到的 KNX 组地址角色
+`neutral` 角色表示初始不确定性，而不是永久禁止控制。模型可以使用结构化工具 `gaRoleActions`，根据可信的用户教学、持久聊天指导、AI 教育或明确无歧义的 ETS 项目语义，学习某个准确的 ETS 组地址属于命令、状态或中性对象。无需固定关键词或角色 intent；如果证据不明确，模型会先询问澄清，而不会擅自学习。
+
+学习到的角色、原因和证据会按节点保存到 `<userDir>/knxai/config/knxai-config-<节点-id>.json`，并同步到受限的家庭语义记忆。学习为 `command` 的角色可以在同一条回复中使写入通过验证，并在重启后继续可用；模型也可以忘记它并恢复自动分类。学习过程不能虚构 GA、修改其 ETS DPT、绕过 payload 校验或跳过已配置的写入确认。
 
 ## 由 AI 教育驱动的主动家庭智能与有限记忆
 节点会根据 ETS 层级、名称、角色和 DPT 建立确定性的语义模型。不再提供单独的开关或高级主动通知设置。只有启用 LLM 且 **AI 教育**明确要求时，系统才会评估通知。条件、持续时间、静默时段和重复频率完全由 AI 教育定义。没有明确规则或 LLM 无法评估时，不会发送任何消息。
@@ -125,7 +143,7 @@ Canvas 上的节点状态专门用于显示最近收到的请求，以及 LLM
   - **2) Install it**：在本机下载并安装模型（例如 `llama3.1`）。
 - 在刷新/安装模型时，KNX AI 也会在可能情况下尝试自动启动 Ollama 服务。
 - 若安装因连接错误失败，请确认 Ollama 已运行（桌面应用或 `ollama serve`）。
-- `/api/show` 报告的最大上下文仅用于显示。KNX AI 始终发送 `num_ctx = 16384`（若模型最大值更小则使用该值），并使用同一个按相关性选择的 16K 语义视图，从而避免分配过大的 KV 缓存，同时保留代理能力。
+- `/api/show` 报告的最大上下文仅用于显示。KNX AI 会将所选的 4K、8K 或 16K 预算作为 `num_ctx` 发送（若模型最大值更小则使用该值），并按比例限制每个上下文来源，同时保留代理能力。
 - 若 Node-RED 运行在 Docker 中，endpoint 请使用 `host.docker.internal` 替代 `localhost`。
 
 ### Bionic LM Studio 快速配置（本地）
@@ -133,7 +151,7 @@ Canvas 上的节点状态专门用于显示最近收到的请求，以及 LLM
 - 在 LM Studio 的 **Developer** 页面启动 API 服务，或运行 `lms server start`。
 - 默认 endpoint：`http://localhost:1234/v1/chat/completions`。
 - 点击 **Refresh** 加载 `/v1/models` 提供的全部模型；未配置模型时会自动选择第一个。
-- 如果模型已加载，KNX AI 会保留其当前上下文长度。KNX AI 不会通过管理 API 加载未运行的 Bionic 模型：首次聊天请求会让 Bionic 根据该模型已保存的默认值进行 JIT 加载。无论 Bionic 报告的上下文是多少，KNX AI 都会将自己的提示词限制为按相关性选择的 16K 语义视图；这样可避免发送完整的 131K 数据集，同时保留推理、KNX、例程、摄像头和 TTS 能力。
+- 如果模型已加载，KNX AI 会保留其当前上下文长度。KNX AI 不会通过管理 API 加载未运行的 Bionic 模型：首次聊天请求会让 Bionic 根据该模型已保存的默认值进行 JIT 加载。无论 Bionic 报告的上下文是多少，KNX AI 都会使用所选的 4K、8K 或 16K 提示预算，并保留推理、KNX、例程、摄像头和 TTS 能力。
 - 除非在 LM Studio 服务设置中启用了身份验证，否则 API Key 可留空。在 Docker 中请将 `localhost` 替换为 `host.docker.internal`。
 
 ## 安全说明

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

@@ -6,6 +6,7 @@
       "groupChatHome": "对话与家庭",
       "detectedAdapters": "自动检测到的适配器",
       "chatContextOverview": "聊天上下文概览",
+      "chatLearning": "AI 聊天学习",
       "quickSetup": "助手配置",
       "llmConnection": "AI 助手连接",
       "chatAdapter": "聊天渠道",
@@ -21,6 +22,7 @@
       "llmBaseUrl": "Endpoint URL",
       "llmApiKey": "API key",
       "llmModel": "Model",
+      "llmPromptContextTokens": "聊天上下文量",
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmAllowKnxCommands": "允许 AI 读取 KNX 状态并控制执行器",
@@ -45,6 +47,11 @@
         "ollama": "Ollama（本地）",
         "lmstudio": "Bionic LM Studio"
       },
+      "promptContext": {
+        "small": "精简（4K，更快）",
+        "medium": "中等（8K）",
+        "full": "完整（16K）"
+      },
       "chatAdapter": {
         "none": "无适配器"
       },
@@ -61,6 +68,7 @@
       "lmStudioContextFailed": "无法配置模型上下文",
       "lmStudioContextCurrentlyLoaded": "当前已加载",
       "localContextBudget": "KNX AI 上下文预算",
+      "promptContextHint": "控制发送给本地模型的 KNX、记忆、项目和适配器上下文量。它不会启用或禁用工具，也不使用 intent 路由。",
       "ollamaNotSupported": "Ollama local mode: API key not required. Default endpoint is http://localhost:11434/api/chat.",
       "ollamaNoModels": "No local Ollama model found. Install one or pick one from the library.",
       "installingOllamaModel": "Starting Ollama and installing model…",
@@ -80,6 +88,7 @@
       "ttsUltimateHint": "聊天中的明确播报请求会直接发送到所选节点，无需在 Flow 中额外连线。",
       "chatContextLoading": "正在加载聊天上下文摘要…",
       "chatContextUnavailable": "聊天上下文摘要暂时不可用。",
+      "chatLearningOpenHint": "直接在 Web UI 中打开共享 CHAT 学习编辑器，以查看、编辑、复制或备份其持久文件。",
       "chatContextIntro": "聊天会自动接收这些来源。以下路径是此 Node-RED 安装实际使用的路径。",
       "chatContextLimitLabel": "最大运行上下文",
       "chatContextProviderManaged": "由所选提供商/模型管理",
@@ -172,7 +181,8 @@
     "buttons": {
       "installOllamaModel": "2) Install it",
       "ollamaLibrary": "Model library",
-      "downloadOllamaModel": "1) Download model"
+      "downloadOllamaModel": "1) Download model",
+      "openChatLearning": "打开 AI 聊天学习"
     }
   }
 }

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

@@ -45,7 +45,8 @@ KNX 总线的值会发布到 MQTT，可写的数据点接受来自 Home Assistan
 ## 映射字段
 
 - **方向** — 选择 KNX→IoT、IoT→KNX 或双向。
-- **通道类型** — MQTT 将目标视为主题；REST 将其视为基础 URL；Modbus 视为寄存器标识。
+- **通道类型** — MQTT 将目标视为主题；REST 将其视为基础 URL；对于 Modbus，**目标**是从零开始的协议地址（0–65535）。
+- **Modbus 格式 / Unit ID / 区域 / 数据类型** — 新映射请选择**兼容 Flex Write**，然后选择单元、内存区域以及 `bool`、`uint16` 或 `int16`。如果没有格式字段，则继续使用旧版标量协议，现有 Flow 不受影响。
 - **缩放 & 偏移** — 应用于 KNX→IoT；在 IoT→KNX 时使用逆向变换。
 - **模板** — 可选字符串，可替换 `{{value}}`、`{{ga}}`、`{{label}}`、`{{target}}`、`{{type}}`、`{{isoTimestamp}}`。
 - **超时 / 重试** — 信息字段，用于告知下游节点应如何处理重试和时间窗口。
@@ -88,7 +89,32 @@ KNX 总线的值会发布到 MQTT，可写的数据点接受来自 Home Assistan
 
 ### Modbus 寄存器同步
 
-- 将桥接节点与 `node-red-contrib-modbus` 的 `modbus-flex-write` 节点配合使用。输出 1 会在 `msg.address` 中携带 Modbus 地址，在 `msg.payload` 中携带数值。
+本桥接节点是 `node-red-contrib-modbus` 的消息适配器；它本身不会打开 TCP/串行连接，也不会轮询设备。请安装与你的 Node-RED 运行环境兼容的该软件包版本，然后使用其中的客户端和传输节点。
+
+|区域|读取|写入|允许的方向|
+|--|--|--|--|
+| 线圈 | FC1 | FC5 | 双向 |
+| 离散输入 | FC2 | — | 仅 Modbus → KNX |
+| 保持寄存器 | FC3 | FC6 | 双向 |
+| 输入寄存器 | FC4 | — | 仅 Modbus → KNX |
+
+对于新映射，请选择`格式 = 兼容 Flex Write`。从 KNX 到 Modbus 时，输出 1 可直接连接到 `modbus-flex-write` 节点，并输出：
+
+```
+msg.payload = {
+  value: 215,
+  fc: 6,
+  unitid: 1,
+  address: 9,
+  quantity: 1
+}
+```
+
+`address` 始终从零开始：如果设备手册将某个保持寄存器标为 `40010`，其协议地址通常为 `9`；请确认该手册采用的规则。每条映射支持一个位或一个 16 位寄存器。目前不会组合多个字、解码 32 位/浮点值，也不处理字节/字顺序。
+
+从 Modbus 到 KNX 时，将 `modbus-flex-getter` 或 `modbus-read` 节点的数据输出连接到桥接输入。Flex Getter 在 `msg.modbusRequest` 中提供请求（`fc`、`unitid`、`address`、`quantity`）；Modbus Read 则将请求保留在 `msg.input.payload` 中。返回的值数组可以位于 `msg.payload` 或 `msg.values`。桥接节点支持这两种消息形式，会匹配该响应覆盖的所有 Flex 映射，并使用正确的数组元素。请在 Flex Getter 上启用 **Keep Msg Properties**。缩放和偏移遵循 `raw = KNX × 缩放 + 偏移`；输入路径应用逆变换。
+
+`部署时读取 KNX 数值`只读取 KNX；Modbus 读取应在外部 Modbus Flow 中安排。旧版映射（包括没有 `modbusMessageFormat` 的映射）仍会输出之前的标量 payload，并在顶层保留 `msg.address`/`msg.modbusFunction` 元数据。
 
 ## 示例 Flow
 

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

@@ -79,6 +79,10 @@
       "target": "目标",
       "method": "HTTP 方法",
       "modbusFunction": "Modbus 功能",
+      "modbusMessageFormat": "Modbus 消息格式",
+      "modbusUnitId": "Unit ID",
+      "modbusArea": "Modbus 区域",
+      "modbusDataType": "数据类型",
       "scale": "缩放",
       "offset": "偏移",
       "timeout": "超时 (ms)",
@@ -103,7 +107,7 @@
       "target": "主题、URL 或寄存器",
       "target_mqtt": "主题，例如 knx/light/living",
       "target_rest": "https://example/api/endpoint",
-      "target_modbus": "寄存器（如 40001）",
+      "target_modbus": "从零开始的地址（如 0）",
       "template": "{\"value\":{{value}}}",
       "property": "可选属性/路径",
       "method": "POST",
@@ -114,7 +118,7 @@
         "default": "目标",
         "mqtt": "MQTT 主题",
         "rest": "REST URL",
-        "modbus": "Modbus 寄存器"
+        "modbus": "Modbus 地址（从零开始）"
       },
       "method": {
         "default": "HTTP 方法",
@@ -125,6 +129,20 @@
         "modbus": "Modbus 功能"
       }
     },
+    "modbus": {
+      "formatLegacy": "旧版标量消息",
+      "formatFlex": "兼容 Flex Write",
+      "areaCoil": "线圈（FC1 读取 / FC5 写入）",
+      "areaDiscreteInput": "离散输入（FC2 读取，只读）",
+      "areaHoldingRegister": "保持寄存器（FC3 读取 / FC6 写入）",
+      "areaInputRegister": "输入寄存器（FC4 读取，只读）",
+      "dataTypeBool": "布尔值",
+      "dataTypeUint16": "16 位无符号整数",
+      "dataTypeInt16": "16 位有符号整数",
+      "zeroBasedHint": "请使用从零开始的协议地址（0–65535），不要使用某些手册中标注的 4xxxx 引用编号。",
+      "flexHint": "Flex 输出 msg.payload = {value,fc,unitid,address,quantity}，可直接连接到 modbus-flex-write。",
+      "readOnlyHint": "离散输入和输入寄存器为只读，只能使用 Modbus → KNX。"
+    },
     "labels": {
       "outputKnxToIoT": "KNX → IoT 流",
       "outputIoTToKnx": "IoT → KNX 确认",