ioBroker 智能管家 Theo555/SARAH-KI-ioBroker-Assistant

SARAH-KI-ioBroker-Assistant

S.A.R.A.H. – ioBroker 智能家居 AI 助手

这是一个 JavaScript 脚本，用于 ioBroker 的 JavaScript 适配器，把你的智能家居和 AI 连接起来。S.A.R.A.H.（灵感来自剧集 Eureka 里的 AI）会回复 Telegram 消息、读取传感器、通过 MQTT 控制 Tasmota 设备，还能借助内置的网页搜索（「Max」）从互联网获取最新信息。

注意：这个脚本是个人模板，不是成品。
所有数据点、设备与传感器 ID 以及名称（例如 DL_Angela、Wohnzimmer2、 fb-checkpresence.1.Theo）都是我自己的配置。脚本在你这里跑起来之前，你必须把这些值改成你自己智能家居里的对应值。

适合谁用？

这个项目面向具备 ioBroker、JavaScript 和 MQTT 基础知识的用户，他们想找一个能跑起来的 Telegram／AI 助手参考实现——而不是期待开箱即用产品的初学者。

如果你符合下面这些情况，收益最大：

- 已经在运行 ioBroker，并且装了 Telegram 和 MQTT 适配器，
- 能替换自己的数据点 ID，
- 想弄明白 DeepSeek 工具调用、缓存优化和 MQTT 控制在实际中怎么配合。

目录

1. 功能
2. 架构与流程
3. 前提条件
4. 安装
5. 配置
6. 可控设备
7. 可用传感器
8. 操作方式
9. Token 与成本优化
10. 安全
11. 故障排查
12. 文件存放

功能

- Telegram 接入：自动回复文本消息。
- 个性化 AI 提示词：每个 Telegram 用户有自己的语气（benutzer_eins / benutzer_zwei）。
- 通过工具调用查询传感器：天气、在家状态、阳台电站、灯状态和时间都实时读取——绝不猜测。
- 通过 MQTT 控制硬件：用 [CMD:...] 标签开关 Tasmota 设备和设备组。
- 网页搜索「Max」：通过 Serper.dev 获取最新实时信息——只在明确确认之后。
- 天气服务：天气数据用 Open-Meteo，地名用 Nominatim（OpenStreetMap）。
- 成本优化：稳定的系统提示词放在最前面 + Token 日志记录带缓存统计（DeepSeek 上下文缓存）。
- 对话记忆：带超时的短期记忆，Token 不会无限增长。

架构与流程

flowchart TD
A[Telegram Nachricht] --> B[Listener telegram.0.communicate.request]
B --> C{Sender bekannt?}
C -- nein --> X[Ignorieren]
C -- ja --> D{Direkte Max-Suche?}
D -- ja --> E[Serper.dev Websuche]
D -- nein --> F{Offene Suchbestätigung?}
F -- 是/否 --> E
F -- 否 --> G[DeepSeek API 调用，带工具]
G --> H{工具调用？}
H -- 是 --> I[读取 get_sensor_value]
I --> J[第 2 次 DeepSeek API 调用]
H -- 否 --> K[解析回答]
J --> K
K --> L{存在 CMD 标签？}
L -- 是 --> M[切换 MQTT 设备]
L -- 否 --> N[清理回答]
M --> N
N --> O[把回答发送到 Telegram]

脚本结构：

| 区域 | 内容 |
| 1. Datenpunkte | 自动创建所有 0_userdata.0. 状态 |
| updateWeather() | 天气 + 地名，每 30 分钟一次 |
| logTokenVerbrauch() | token 与缓存统计 |
| 2. Maps & Speicher | geräteMap、sensorMap、聊天记录 |
| 3. System Prompts & Tools | 角色提示词 + get_sensor_value 工具 |
| 4. Haupt-Listener | Telegram 处理、Max 搜索、DeepSeek、MQTT |

前提条件

- ioBroker，并运行 JavaScript 适配器（版本需支持 async/await 和 require('axios')）。
- 适配器：
- telegram – Telegram 接入
- mqtt – 控制 Tasmota 设备
- 可选 viessmannapi、node-red、fb-checkpresence – 用于对应的传感器
- API key：
- DeepSeek（https://api.deepseek.com）
- Serper.dev（https://serper.dev）– 用于网页搜索「Max」

安装

1. 把 sarah3.txt 的脚本内容复制到 ioBroker JavaScript 适配器（例如通过 Objekte → javascript.0 → Scripts* 下的编辑器）。
2. 保存脚本并启动。
3. 0_userdata.0 下的数据点会自动创建。

提示：首次启动时会通过 require 加载 axios。如果 require 调用失败，需要在 JavaScript 适配器中安装或放行 axios。

配置

所有值都通过对象树中的数据点配置：

| 数据点 | 含义 | 默认值 |
| 0_userdata.0.DeepseekAPI | DeepSeek API key | 空 |
| 0_userdata.0.SerperAPI | 用于「Max」的 Serper.dev API key | 空 |
| 0_userdata.0.SARAH.Haushalt.Mitglieder | 家庭成员姓名/角色，用于 AI 提示词 | Person A (Bewohner), Person B (Bewohner) |
| 0_userdata.0.Wetter.Koordinaten | 天气与地名用的坐标 Lat,Lon | 52.52,13.405（柏林） |
| 0_userdata.0.Wetter.Ortsname | 自动获取 | Berlin |
| 0_userdata.0.Telegramm_User_1 | 用户配置（JSON，见下文） | 模板 |
| 0_userdata.0.Telegramm_User_2 | 用户配置（JSON，见下文） | 模板 |

用户配置（Telegram）

数据点 Telegramm_User_1 / Telegramm_User_2 包含一个 JSON 模板：

{
"username": "telegram_name",
"chatId": "chat_id",
"rufname": "rufname",
"promptKey": "benutzer_eins"
}

| 字段 | 含义 |
| username | Telegram 用户名，必须与消息发送者一致 |
| chatId | Telegram 聊天 ID |
| rufname | 称呼，Sarah 会偶尔使用 |
| promptKey | benutzer_eins（机灵/讽刺）或 benutzer_zwei（友好/忠诚） |

重要：没有有效的 username 映射，消息会被忽略。

可控设备

映射通过 geräteMap 完成。设备通过 Tasmota 设备的 MQTT cmnd topic 开关。

| 名称 | MQTT topic |
| deckenlicht | mqtt.0.cmnd.DL_Angela.POWER1 |
| bettlicht | mqtt.0.cmnd.DL_Angela.POWER2 |
| esszimmer | mqtt.0.cmnd.Esszimmer.POWER |
| wohnzimmer | mqtt.0.cmnd.Wohnzimmer2.POWER |
| keller | mqtt.0.cmnd.Keller1.POWER |

分组：

| 分组 | 包含 |
| alle_lichter | deckenlicht, bettlicht, esszimmer, wohnzimmer, keller |
| schlafzimmer | deckenlicht, bettlicht |

可用传感器

映射通过 sensorMap 完成。单个传感器：

| 名称 | 来源 | 单位 |
| aussentemperatur | Viessmann 室外温度 | °C |
| wetter_temperatur | Open-Meteo | °C |
| wetter_feuchtigkeit | Open-Meteo | % |
| wetter_niederschlag | Open-Meteo | mm |
| wetter_wind | Open-Meteo | km/h |
| wetter_windrichtung | Open-Meteo | ° |
| balkonkraftwerk | Node-RED Strom_BKW | W |
| theo / angela / christopher | 在场状态（fb-checkpresence） | – |
| deckenlicht_status … | MQTT stat topic | – |
| aktuelle_zeit | 本地计算 | – |

分组：

| 分组 | 包含 |
| wetter | 所有 Open-Meteo 天气值 |
| lichter_status | 所有灯的状态 |
| heizung | 室外温度 |
| lichtverhaeltnisse | 阳台光伏 |
| anwesenheit | theo, angela, christopher |

操作

普通对话

直接通过 Telegram 发消息就行——Sarah 会用配置好的语气回复。

查询传感器

像「天气怎么样？」或「灯开着吗？」这样的问题，会自动触发一次 get_sensor_value 调用。Sarah 会实时读取数值，然后再回复。

开关设备

意图明确时，Sarah 会在回复末尾加一个控制标签，脚本会把它翻译成 MQTT 命令：

- [CMD:deckenlicht_on]
- [CMD:wohnzimmer_off]
- [CMD:alle_lichter_off]

网络搜索「Max」

- 直接：Max, wie ist der aktuelle Strompreis?
- 间接：Sarah 需要最新数据时，会先征求许可
（[FRAGE_AN_MAX: suchbegriff]）。确认（ja、ok、los …）会启动搜索，
拒绝（nein、lass …）会取消。

Token 与成本优化

- 稳定前缀：系统提示词始终放在最前面，且保持不变——这样 DeepSeek 上下文缓存就能命中重复消息。
- 历史限制：历史记录最多保留 6 条消息。
- 记忆超时：闲置 10 分钟后清空历史记录。
- Token 日志：每次请求都会记录总 token、提示词 token、缓存 token 和回复 token：

[DeepSeek Token（请求）] 总计：1234 | 提示词总计：1000（其中缓存：800 ⚡ / 新付费：200 💸）| 回答：234

缓存数值来自 DeepSeek 字段 prompt_cache_hit_tokens 和 prompt_cache_miss_tokens（带 OpenAI 回退）。

安全

- Sarah 绝不能未经询问就切换设备。遇到含义模糊、开玩笑或自相矛盾的请求，她要先追问，而不是发送 [CMD:...] 标签。
- 网络搜索只在用户明确确认后才执行。
- 内部工具调用、函数名和控制标签永远不会作为文本输出。

提示：控制标签基于 AI 回答。如果安装实例可公开访问，或会处理未经过滤的网页内容，建议额外加上服务端确认，用于关键操作。

故障排查

| 问题 | 原因 / 解决 |
| 脚本无法启动 | require('axios') 失败 → 让 axios 在 JS 适配器中可用 |
| 启动时 TypeError ... .val | 数据点缺失 → 脚本会在启动时创建它；必要时检查命名空间权限 |
| Telegram 没有回复 | Telegramm_User_* 里的 username 与发送者不一致 |
| 「API-Key 缺失」 | 0_userdata.0.DeepseekAPI 或 0_userdata.0.SerperAPI 为空 |
| 最大搜索失败 | 检查 Serper-Key；Serper 已达上限 |
| 设备不切换 | 检查 geräteMap 里的 MQTT-Topic；测试 Tasmota 连接 |
| 日志里缓存始终为 0 | DeepSeek 提供 prompt_cache_hit_tokens/prompt_cache_miss_tokens —— 日志已相应更新 |

文件存放

脚本以 sarah3.txt 形式存在，导入 ioBroker-JavaScript-Adapter 使用。
这份 README 与脚本放在同一个文件夹里。

许可证

本项目采用 MIT 许可证 —— 完整文本见 LICENSE。
任何人都可以自由使用、修改和分发这个脚本 —— 包括商业用途 ——只要保留许可证文本即可。

支持

不提供任何支持。 脚本按「原样」（AS IS）提供 ——不担保、不维护，也没有修复错误的义务。使用风险自负。