🏠🔍 家庭助理诊断代理
专为拥抱脸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工具）-- .
签名高级工具（新）
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