使用说明

🏠🔍 家庭助理诊断代理

专为拥抱脸MCP的第一个生日黑客马拉松而设计

🎯 什么是家庭助理诊断代理？

Home assistant智能家居的AI驱动诊断助手，结合了：

39 MCP工具 用于深度系统分析
13 MCP资源 有漂亮的降价报告
双子座2.0闪光灯 具有函数调用功能的AI代理
等级 6 具有3个专用界面的现代UI

这就像有一个 智能家居医生 这可以：

🔍 自动诊断问题
📡 分析Zigbee网状网络
⚡ 跟踪能耗和成本
🧹 查找孤立实体进行清理
🔧 检测自动化冲突和循环
🤖 自然地谈论你的智能家居

🚀 拥抱脸部空间

在拥抱脸部空间上试试： MCP-1st-Birthday/家庭助理诊断代理

✨ 主要特点

🏠 健康仪表板

带有实时系统指标的Apple Health风格仪表板：

整体系统健康评分（0-100）
Zigbee网状网络分析
电池健康监测
能耗跟踪
自动化安全状态
一键式完整诊断
📘 知识索引——基于LlamaIndex（演示数据和markdown上的关键字表索引）
🗂️ 诊断历史记录——可选Blaxel存根存储工具快照（功能标记）

💬 AI诊断聊天

由...驱动 双子座2.0闪光灯 使用MCP工具调用：

自然语言诊断
自动工具编排
可视化工具时间线
后续问题
可采取行动的建议
设备动作前的确认
OpenAI gpt-4o-mini回退（仅在Gemini不可用时解释）
可选LlamaIdex知识库（关键字索引）
可选Blaxel诊断历史记录（内存快照）

🔬 调查实验室

深入故障排除工具：

实体调查 -诊断任何实体
设备标识 -物理闪光/蜂鸣声
清理中心 -查找孤儿实体
自动化分析 -检测冲突

可选AI扩展

🔷 LlamaIdex集成（知识库工具）

默认启用： FEATURE_LLAMAINDEX=true （不需要API密钥）。
用途 llama-index-core, llama-index-readers-file, llama-index-llms-openai.
建立一个本地 KeywordTableIndex 发件人：
- demo_data/*.json （序列化为文本）
- resources/*.md （如果存在）
暴露工具： query_diagnostics_knowledge(question: str)
工具位于Gemini函数声明中，当模型检测到KB风格的问题时会自动调用；使用时显示在工具时间线中。
不会改变DEMO/LIVE或OpenAI回退。
有资格获得LlamaIndex类别奖。

🔷 Blaxel整合（诊断史存根）

可选标志： FEATURE_BLAXEL=false 默认情况下。
无外部SDK；离线工作。如果 BLAXEL_API_KEY 缺失，返回友好错误而不中断执行。
内存中最多可存储100个快照(blaxel_backend.py)，捕获：工具名、参数、结果、时间戳。
暴露工具： query_diagnostic_history() 检索存储的快照；使用时显示在工具时间线中。
足以获得Blaxel选择奖。

🏗️ 建筑

┌─────────────────────────────────────────────────────────────┐
│                    GRADIO UI (app.py)                       │
│  ┌──────────────┬──────────────┬─────────────────────────┐  │
│  │  Dashboard   │  AI Chat     │  Investigation Lab      │  │
│  └──────────────┴──────────────┴─────────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
            ┌────────────────┐
            │  agent.py      │  ◄── Gemini 2.0 Flash
            │  (Function     │      (Tool Calling)
            │   Calling)     │
            └────────┬───────┘
                     │
                     ▼
            ┌────────────────┐
            │ mcp_bridge.py  │  ◄── DEMO_MODE / LIVE_MODE
            └────────┬───────┘
                     │
         ┌───────────┴────────────┐
         │                        │
         ▼                        ▼
    ┌─────────┐            ┌──────────────┐
    │ MCP     │            │  demo_data/  │
    │ Server  │            │  (JSON/MD)   │
    │ (LIVE)  │            │  (DEMO)      │
    └─────────┘            └──────────────┘
         │
         ▼
┌────────────────────┐
│  Home Assistant    │
└────────────────────┘

🚀 快速开始

选项1：演示模式（拥抱面部空间）

# Clone repository
git clone https://github.com/burgueishon/Home-Assistant-Diagnostics-Agent.git
cd Home-Assistant-Diagnostics-Agent

# Install dependencies
pip install -r requirements.txt

# Set Gemini API key
export GEMINI_API_KEY="your_key_here"

# Run in demo mode (uses pre-generated data)
export DEMO_MODE=true
python app.py

打开浏览器 http://localhost:7861

选项2：实时模式（连接到您的HA）

# Copy environment template
cp .env.example .env

# Edit .env and set:
DEMO_MODE=false
GEMINI_API_KEY=your_gemini_key
HA_URL=                # set your HA URL when switching to LIVE
HA_TOKEN=              # set your HA token when switching to LIVE

# Install MCP server dependencies
cd Home-Assistant-Diagnostics-MCP-Server
pip install -e .

# Return to gradio app
cd ..

# Run in live mode
python app.py

🔧 环境变量

要求（典型）：

GEMINI_API_KEY --双子座2.0闪光灯
DEMO_MODE — true （演示数据）或 false （与HA_URL/HA_TOKEN直播）
HA_URL, HA_TOKEN --演示时留空；仅设置为实时模式

可选功能：

FEATURE_LLAMAINDEX=true （默认开启）
FEATURE_BLAXEL=false （默认关闭）
BLAXEL_API_KEY= （存根仅用于抑制警告；本地历史记录不需要）

🛠️ MCP工具（共39个）

由 家庭助理诊断MCP服务器 （39工具）-- GitHub.

签名高级工具（新）

audit_zigbee_mesh -基于LQI/RSSI的网格健康分析
find_orphan_entities -未使用实体检测
detect_automation_conflicts -比赛条件和循环
energy_consumption_report -能源跟踪和成本分析
query_diagnostics_knowledge （LlamaIdex）-KB查找（特征标记）
query_diagnostic_history （Blaxel）-快照历史记录（已标记功能）

系统诊断

diagnose_system -完成系统健康检查
diagnose_issue -实体级诊断
diagnose_automation -自动化故障排除
battery_report -电池健康监测
find_unavailable_entities -离线实体检测
find_stale_entities -冻结传感器检测

设备管理

identify_device -物理设备标识（闪烁/蜂鸣声）
list_entities -带有过滤器的实体列表
get_entity_statistics -历史分析

监控

get_repair_items -房委会维修小组问题
get_update_status -可用更新
get_error_log -误差分析

查看完整的工具列表

🤖 Gemini集成

用途 双子座2.0闪光灯 通过函数调用：

# Agent automatically decides which tools to use
response = agent.chat("Why isn't my kitchen light working?")

# Behind the scenes:
# 1. Gemini analyzes the question
# 2. Decides to call diagnose_issue(entity_id="light.kitchen")
# 3. Executes tool via MCP bridge
# 4. Analyzes results
# 5. Provides natural language response with recommendations

主要特点:

自动刀具选择
多回合对话
语境意识
设备动作前的确认
带降价的结构化响应

📊 演示模式vs直播模式

功能	演示模式	直播模式
数据源	预生成JSON	真实家庭助手
Gemini聊天	✅ 完整功能	✅ 功能齐全
MCP工具	✅ 模拟响应	✅ 真正的API调用
用例	HuggingFace Spaces演示	个人部署
需求	仅限Gemini API密钥	+HA URL和令牌

🔧 环境变量

# Core
DEMO_MODE=true                 # default demo
GEMINI_API_KEY=...             # required for Gemini
OPENAI_API_KEY=...             # optional fallback
HA_URL=                        # set when switching to LIVE mode
HA_TOKEN=                      # set when switching to LIVE mode

# Optional features
FEATURE_LLAMAINDEX=true        # knowledge base (default on)
FEATURE_BLAXEL=false           # diagnostic history snapshots (default off)
BLAXEL_API_KEY=                # optional; friendly error if missing

默认情况下，FEATURE_LLAMAINDEX始终处于打开状态（本地KeywordTableIndex，不需要密钥）。如果要使用历史记录工具，必须手动启用FEATURE_BLAXEL；关闭它对HF Spaces来说是安全的。

🎯 黑客马拉松标签

track: mcp-in-action-track-consumer
technologies:
  - mcp
  - home-assistant
  - diagnostics
  - gemini
  - openai
  - llamaindex
  - gradio
  - agents
features:
  - 39 MCP tools
  - 13 MCP resources
  - Gemini 2.0 Flash function calling
  - Dual-mode architecture (DEMO/LIVE)
  - Real-time diagnostics
  - Natural language interface

📖 查询示例

在AI聊天中尝试这些：

🔍 Diagnostics:
- "Run a complete system health check"
- "Why isn't my kitchen light working?"
- "Diagnose automation.morning_routine"
- "Show diagnostic history"

📡 Network Analysis:
- "Analyze my Zigbee mesh network"
- "Which Zigbee devices have weak signal?"
- "Show me mesh health with recommendations"

🧹 Cleanup & Optimization:
- "Find all orphan entities"
- "Which entities can I safely delete?"
- "Detect automation conflicts"

⚡ Energy & Monitoring:
- "Show energy consumption for last 24 hours"
- "Which devices consume the most power?"
- "Estimate my monthly electricity cost"

🔋 Maintenance:
- "Which batteries are low?"
- "Find sensors that haven't updated"
- "Are there any available updates?"

🔧 发展

项目结构

Home-Assistant-Diagnostics-Agent/
├── app.py                       # Main Gradio UI (3 tabs)
├── agent.py                     # Gemini AI agent with function calling
├── mcp_bridge.py                # MCP abstraction layer (DEMO/LIVE)
├── custom.css                   # Dark theme overrides
├── demo_data/                   # Pre-generated demo data
│   ├── *.json                   # Tool responses
│   └── *.md                     # Resource markdown
├── requirements.txt             # Python dependencies
├── requirements-dev.txt         # Dev/test dependencies
├── .env.example                 # Configuration template
├── tests/                       # Unit tests for the UI/bridge
├── Home-Assistant-Diagnostics-MCP-Server/   # MCP server (live mode)
│   ├── app/                     # MCP tool implementations
│   ├── tests/                   # MCP server tests
│   └── pyproject.toml           # MCP server deps
└── README.md                    # This file

🤝 贡献

专为 拥抱面孔MCP黑客马拉松2025

欢迎投稿！

📄 许可证

MIT许可证-请参阅许可证

内置于❤️ 智能家居社区

🏷️ mcp-in-action-track-consumer mcp home-assistant gemini openai llamaindex blaxel gradio

使用说明

🏠🔍 家庭助理诊断代理

🎯 什么是家庭助理诊断代理？

🚀 拥抱脸部空间

✨ 主要特点

🏠 健康仪表板

💬 AI诊断聊天

🔬 调查实验室

可选AI扩展

🔷 LlamaIdex集成（知识库工具）

🔷 Blaxel整合（诊断史存根）

🏗️ 建筑

🚀 快速开始

选项1：演示模式（拥抱面部空间）

选项2：实时模式（连接到您的HA）

🔧 环境变量

🛠️ MCP工具（共39个）

签名高级工具（新）

系统诊断

设备管理

监控

🤖 Gemini集成

📊 演示模式vs直播模式

🔧 环境变量

🎯 黑客马拉松标签

📖 查询示例

🔧 发展

项目结构

🤝 贡献

📄 许可证

相关 MCP

串口AI控制工具

系统化问题解决工具

智能家居设备控制服务器

Sonos控制服务器

热泵聊天服务

智能家居控制MCP服务器