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

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

@@ -1,18 +1,82 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 此节点会监听所选 KNX Ultimate 网关上的**所有 KNX 电报**，生成流量统计、检测异常，并可选调用 LLM。
 
+编辑器使用三个主要折叠面板：**AI 助手**包含配置、知识/上下文以及提供商限制；**对话与家庭**包含聊天渠道、主动家庭和受限记忆；**KNX 总线流量分析**包含总线报文、历史/摘要以及异常/模式。打开一个主要面板即可同时看到其中全部相关选项。已保存字段的 ID 和值保持不变。
+
 ## 输出
 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`：清空内部历史与计数器
+- `reset`：清空内部历史、计数器和已学习的家庭记忆；AI 教育保持不变
 - `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 包仍是独立的可选依赖项。
+
+## 主动家庭智能与有限记忆
+**对话与家庭**中的**主动家庭与记忆**子部分以可选方式启用主动通知。节点会根据 ETS 层级、名称、角色和 DPT，使用意大利语、英语、德语、法语、西班牙语和中文术语，为卷帘、窗户、门、照明、温度、气候、占用和报警建立确定性的语义模型。首个主动检测器只监视可靠识别且非命令的卷帘/窗户/门状态。超过配置的打开时间且当前不在静默时段时，输出 3 会发送本地化消息，并设置 `msg.knxAi.type = "proactive_notification"`。节点绝不会主动使用输出 4，也不会自行修改 KNX；用户之后提出的任何操作仍须经过正常的校验与确认。
+
+最近一次聊天会话会被记为主人，也可以通过**主要接收者 / 聊天 ID**明确指定。合成的 `msg.inputMessage` 会保留接收者，使 Telegram 适配器能够发送主动通知。冷却时间和每小时最多三条主动通知可防止消息泛滥。
+
+学习到的参考文件会在启动时从 `<userDir>/knxai/memory/knxai-home-memory-<node-id>.md` 加载，每 15 分钟以原子方式重写，并严格限制在可配置的 64–1,024 KB（默认 256 KB）。最多保留 120 条重要观察、80 条聚合习惯、80 条通知和 300 个 ETS 语义对象，绝不会保存无限的原始报文流。较旧且优先级较低的项目会先被删除。**AI 教育**最多 16,000 个字符，并且始终来自节点配置：AI 可以将其作为权威指导读取，但不能修改或覆盖。如果已填写 AI 教育但 LLM 无法进行评估，候选通知会被抑制，以免违反用户指导。
+
+## 实用配置示例
+此示例创建一个简洁的助手：它会报告重要的长时间开启状态，但允许书房卷帘保持开启。
+
+| 编辑器字段 | 示例值 | 结果 |
+|---|---|---|
+| **启用主动家庭通知** (`proactiveEnabled`) | 启用 | 节点评估可靠识别的卷帘、窗户和门开启状态。 |
+| **主要接收者 / 聊天 ID** (`proactiveRecipient`) | `123456789` | 主动消息发送到该聊天；留空则记住最近一次 Ask 会话。 |
+| **开启多久后通知** (`proactiveOpenMinutes`) | `120` | 开启两小时后评估是否需要通知。 |
+| **静默时间开始 / 结束** | `23:00` / `07:00` | 夜间不会发送主动消息。 |
+| **重复冷却时间** (`proactiveCooldownMinutes`) | `360` | 同一对象六小时内不会再次通知。 |
+| **家庭记忆文件上限** (`homeMemoryMaxKb`) | `256` | 此节点的 Markdown 参考文件始终小于 256 KB。 |
+
+**AI 教育** (`aiEducation`) 示例：
+
+```text
+称呼我为 Alex，并使用与我相同的语言回答。
+除非我要求技术细节，否则回答要简短。
+书房卷帘白天可以保持开启：不要因此通知我。
+其他卷帘、窗户或门异常长时间开启时请通知我。
+如果“客厅灯”指向多个灯，请先询问我具体是哪一个。
+在 KNX 状态对象确认之前，绝不要声称执行器已经改变。
+```
+
+使用这些设置后，客厅卷帘开启 120 分钟时，输出 3 可以发送本地化的 `proactive_notification`；而书房卷帘的候选通知会根据 AI 教育被抑制。如果 Alex 随后要求关闭客厅卷帘，KNX AI 会准备准确的 ETS 命令，但在输出 4 前仍执行正常的验证与确认。
+
+请使用清晰的 ETS 层级和对象名称，并正确设置状态/命令角色。AI 教育可以个性化决策和措辞，但不能虚构组地址、更改 DPT 或绕过 KNX 验证。
 
-`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 +117,20 @@
 - **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。
+- **启用主动家庭通知**：可选检测器，仅处理可靠识别的卷帘、窗户和门开启状态；绝不会自主写入 KNX。
+- **主要接收者 / 聊天 ID**：主动消息的可选目标；未填写时记住最近一次 Ask 会话。
+- **开启多久后通知（分钟）**：考虑发送主动通知前的开启时长阈值。
+- **静默时间开始 / 结束**：每天禁止主动消息的时间段。
+- **AI 教育**：仅由用户管理的权威指导，AI 可以读取但永远不能修改。
+- **重复冷却时间（分钟）**：同一对象再次通知前的最短间隔。
+- **家庭记忆文件上限（KB）**：64 到 1,024 KB 的硬限制；默认 256 KB。
 - 如果启用了磁盘归档，**Ask** 默认会查询该归档：若问题里写了明确日期/时间范围就按其查询，否则默认查询最近 24 小时并补上当前 RAM 事件。
 - **Include raw payload hex**：在提示词中包含原始十六进制 payload。
 - **包含 Node-RED 项目清单**：在提示词中加入整个 Node-RED 项目的节点清单，不仅包含 KNX 节点，也包含 function/change/inject/template 等在内且带有 KNX 逻辑或组地址的有用节点。
@@ -84,5 +161,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,19 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
-      "capture": "Capture",
-      "storage": "历史与摘要",
-      "detection": "检测与告警",
+      "groupAssistant": "AI 助手",
+      "groupChatHome": "对话与家庭",
+      "groupKnxAnalysis": "KNX 总线流量分析",
+      "quickSetup": "助手配置",
+      "capture": "总线报文输入",
+      "storage": "KNX 历史与摘要",
+      "detection": "异常与模式",
       "llmConnection": "AI 助手连接",
-      "llmContext": "AI 助手上下文",
-      "advanced": "高级调优"
+      "llmContext": "AI 知识与上下文",
+      "chatAdapter": "聊天渠道",
+      "homeIntelligence": "主动家庭与记忆",
+      "homeIntelligenceAdvanced": "高级主动通知设置",
+      "advanced": "提供商与限制"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +46,36 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "包含 Node-RED 项目清单",
+      "llmAllowKnxCommands": "允许 AI 读取 KNX 状态并控制执行器",
+      "llmRequireCommandConfirmation": "发送 KNX 命令前请求确认",
+      "chatAdapterPreset": "适配器预设",
+      "chatInputCode": "输入映射（聊天 → KNX AI）",
+      "chatOutputCode": "输出映射（KNX AI → 聊天）",
+      "proactiveEnabled": "启用主动家庭通知",
+      "proactiveRecipient": "主要接收者 / 聊天 ID",
+      "proactiveOpenMinutes": "保持打开多少分钟后通知",
+      "proactiveCooldownMinutes": "重复通知冷却时间（分钟）",
+      "proactiveQuietStart": "静默时段开始",
+      "proactiveQuietEnd": "静默时段结束",
+      "homeMemoryMaxKb": "家庭记忆文件最大值（KB）",
+      "aiEducation": "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,13 +85,20 @@
       "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。",
+      "homeIntelligenceIntro": "节点会创建多语言 ETS 语义模型，并在可靠识别的卷帘、窗户或门长时间保持打开时主动通知聊天。它绝不会自行发送 KNX 命令。",
+      "aiEducationHelp": "只有用户可以编辑此部分。AI 会把它作为权威指导读取，但学习到的记忆绝不能覆盖它。最多 16,000 个字符。",
+      "homeMemoryLimitHelp": "Markdown 记忆每 15 分钟以原子方式重写，并始终限制在 64 到 1,024 KB。达到限制时会先删除较旧的观察，再删除习惯和语义对象。"
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",
       "llmApiKey": "Paste API key (starts with sk-)",
       "llmModel": "e.g. gpt-4o-mini",
-      "llmSystemPrompt": "Optional. Leave empty for default."
+      "llmSystemPrompt": "Optional. Leave empty for default.",
+      "proactiveRecipient": "可选：Telegram 聊天 ID；留空则记住最近一次聊天会话",
+      "aiEducation": "示例：23:00 到 07:00 之间不要通知我。书房卷帘夜间可以保持打开。"
     },
     "sidebar": {
       "ui": {