智能家居聊天机器人

┌─────────────────────────────────────────────────────────────┐
│                    Home Assistant                            │
│                                                             │
│  ┌──────────┐    ┌──────────┐    ┌───────────────────┐     │
│  │  Chat    │───▶│ views.py │───▶│  n8n_proxy.py     │     │
│  │  Panel   │    │ REST API │    │  (HTTP + BasicAuth)│     │
│  │ (iframe) │◀───│          │◀───│                   │     │
│  └──────────┘    └──────────┘    └─────────┬─────────┘     │
│       │               │                     │               │
│       │          ┌──────────┐               │               │
│       │          │ recorder │               │               │
│       │          │ (SQLite) │               │               │
│       │          └──────────┘               │               │
└───────│─────────────────────────────────────│───────────────┘
        │                                     │
        │                                     ▼
        │                        ┌────────────────────┐
        │                        │   n8n Workflow      │
        │                        │                    │
        │                        │  Webhook (POST)    │
        │                        │       │            │
        │                        │       ▼            │
        │                        │  AI Agent          │
        │                        │  (MiniMax M3)      │
        │                        │       │            │
        │                        │       ▼            │
        │                        │  15 HA Tool Nodes  │
        │                        │  + Simple Memory   │
        │                        └────────────────────┘
        │
        ▼
   ┌──────────┐
   │ Browser  │  (Desktop / Mobile / Tablet)
   └──────────┘

sequenceDiagram
    participant User as User (Browser)
    participant HA as Home Assistant
    participant DB as SQLite (Recorder)
    participant n8n as n8n Webhook
    participant AI as MiniMax M3
    participant Tools as HA Tools (15)

    User->>HA: POST /api/ha_mcp_client/.../messages
    HA->>DB: Save user message (immediate)
    HA->>n8n: POST /webhook/ha-chat (Basic Auth)
    n8n->>AI: Process with system prompt
    AI->>Tools: Call HA tools (state, service, template...)
    Tools-->>AI: Tool results
    AI-->>n8n: AI response JSON
    n8n-->>HA: {"output": "response text"}
    HA->>DB: Save AI response (shielded)
    HA-->>User: {"ai_response": "...", "user_message": "..."}

graph TB
    subgraph "Frontend (app.js)"
        A[Chat Panel iframe] -->|fetch POST| B[HA REST API]
    end

    subgraph "Backend (Python)"
        B -->|Step 1| C[record_single: save user msg]
        C -->|Step 2| D[asyncio.shield]
        D -->|send_chat| E[n8n_proxy.py]
        D -->|record_single| F[save AI response]
    end

    subgraph "n8n Workflow"
        E -->|HTTP POST| G[Webhook Node]
        G --> H[AI Agent - MiniMax M3]
        H --> I[15 HA Tool Nodes]
        I -->|HA REST API| J[Home Assistant API]
    end

    subgraph "Storage"
        C --> K[(SQLite via Recorder)]
        F --> K
    end

// POST /api/ha_mcp_client/conversations/{id}/messages
// Request:
{"message": "把客廳的燈打開亮度50%"}

// Response:
{
  "user_message": "把客廳的燈打開亮度50%",
  "ai_response": "已完成 ✅ 客廳燈已打開，亮度設定為 50%。",
  "conversation_id": "uuid-..."
}

Woow_ha_mcp_chatbot/
├── README.md                    # English documentation
├── README_zh-TW.md              # 繁體中文文件
├── LICENSE                      # MIT License
├── hacs.json                    # HACS integration metadata
├── .gitignore                   # Git ignore rules
│
├── custom_components/ha_mcp_client/
│   ├── __init__.py              # Integration setup, panel registration, services
│   ├── config_flow.py           # 3-step configuration wizard
│   ├── const.py                 # Constants and configuration keys
│   ├── n8n_proxy.py             # n8n webhook HTTP client (Basic Auth)
│   ├── views.py                 # REST API endpoints (6 routes)
│   ├── conversation_recorder.py # SQLite-based conversation history
│   ├── manifest.json            # Integration metadata (v1.0.0)
│   ├── services.yaml            # Service definitions
│   ├── strings.json             # Default UI strings
│   │
│   ├── brand/                   # Brand assets
│   │   ├── icon.png / icon@2x.png
│   │   └── logo.png / logo@2x.png
│   │
│   ├── frontend/                # Chat panel UI
│   │   ├── index.html           # Panel HTML template
│   │   ├── app.js               # Frontend logic (vanilla JS)
│   │   └── styles.css           # CSS with HA theme sync
│   │
│   └── translations/            # Localization
│       ├── en.json              # English
│       └── zh-Hant.json         # Traditional Chinese
│
└── docs/
    ├── screenshots/             # README images
    └── plans/                   # Design & planning documents