fix: align service metadata and stabilize testability

Align declared services and translation keys with registered handlers so users only see supported actions. Improve local and CI test reliability by adding lightweight import fallbacks and a dedicated pytest workflow.

Author: Desmond-Dong

.github/workflows/tests.yaml

@@ -0,0 +1,21 @@
+name: Unit Tests
+
+on:
+  push:
+    paths-ignore:
+      - '.github/workflows/**'
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip && pip install pytest aiohttp
+      - name: Run tests
+        run: pytest -q

.gitignore

@@ -30,6 +30,8 @@ env/
 
 # 测试和覆盖率
 .pytest_cache/
+.mypy_cache/
+.ruff_cache/
 .coverage
 htmlcov/
 .tox/

custom_components/ai_hub/__init__.py

@@ -7,23 +7,41 @@
 from typing import Any, TypeAlias
 
 import aiohttp
-from homeassistant.config_entries import ConfigEntry, ConfigSubentry
-from homeassistant.const import CONF_API_KEY, Platform
-from homeassistant.core import HomeAssistant
-from homeassistant.exceptions import ConfigEntryAuthFailed, ConfigEntryNotReady
+
+try:
+    from homeassistant.config_entries import ConfigEntry, ConfigSubentry
+    from homeassistant.const import CONF_API_KEY, Platform
+    from homeassistant.core import HomeAssistant
+    from homeassistant.exceptions import ConfigEntryAuthFailed, ConfigEntryNotReady
+except ModuleNotFoundError:  # pragma: no cover - used only in lightweight test environments
+    ConfigEntry = Any  # type: ignore[assignment]
+    ConfigSubentry = Any  # type: ignore[assignment]
+    HomeAssistant = Any  # type: ignore[assignment]
+    CONF_API_KEY = "api_key"
+
+    class ConfigEntryAuthFailed(Exception):
+        """Fallback exception when Home Assistant is not installed."""
+
+    class ConfigEntryNotReady(Exception):
+        """Fallback exception when Home Assistant is not installed."""
+
+    Platform = None  # type: ignore[assignment]
 
 from .const import AI_HUB_CHAT_URL, DOMAIN
 
 _LOGGER = logging.getLogger(__name__)
 
-PLATFORMS = [
-    Platform.CONVERSATION,
-    Platform.AI_TASK,
-    Platform.TTS,
-    Platform.STT,
-    Platform.BUTTON,
-    Platform.SENSOR,
-]
+if Platform is None:
+    PLATFORMS: list[Any] = []
+else:
+    PLATFORMS = [
+        Platform.CONVERSATION,
+        Platform.AI_TASK,
+        Platform.TTS,
+        Platform.STT,
+        Platform.BUTTON,
+        Platform.SENSOR,
+    ]
 
 AIHubConfigEntry: TypeAlias = ConfigEntry  # Store API key
 

custom_components/ai_hub/api/__init__.py

@@ -0,0 +1,19 @@
+"""API client helpers for AI Hub integration."""
+
+from .base import (
+    APIClient,
+    APIError,
+    APIResponse,
+    AuthenticationError,
+    RateLimitError,
+    TimeoutError,
+)
+
+__all__ = [
+    "APIClient",
+    "APIError",
+    "APIResponse",
+    "AuthenticationError",
+    "RateLimitError",
+    "TimeoutError",
+]

custom_components/ai_hub/api/base.py

@@ -0,0 +1,123 @@
+"""Lightweight API client base classes used by tests and services."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+import aiohttp
+
+
+@dataclass
+class APIResponse:
+    """Normalized API response container."""
+
+    success: bool
+    data: Any = None
+    status_code: int | None = None
+
+    @property
+    def is_error(self) -> bool:
+        return not self.success
+
+    def get_error_message(self) -> str | None:
+        if self.success:
+            return None
+        if isinstance(self.data, str):
+            return self.data
+        if isinstance(self.data, dict):
+            if isinstance(self.data.get("error"), str):
+                return self.data["error"]
+            if isinstance(self.data.get("message"), str):
+                return self.data["message"]
+            nested_error = self.data.get("error")
+            if isinstance(nested_error, dict) and isinstance(nested_error.get("message"), str):
+                return nested_error["message"]
+        return None
+
+
+class APIError(Exception):
+    """Base API exception."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class AuthenticationError(APIError):
+    """Raised for authentication failures."""
+
+
+class RateLimitError(APIError):
+    """Raised when API rate limit is exceeded."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, retry_after: float | None = None) -> None:
+        super().__init__(message, status_code=status_code)
+        self.retry_after = retry_after
+
+
+class TimeoutError(APIError):
+    """Raised for API timeout failures."""
+
+
+class APIClient(ABC):
+    """Abstract API client with shared session handling."""
+
+    def __init__(self, api_key: str, session: aiohttp.ClientSession | None = None) -> None:
+        self._api_key = api_key
+        self._session = session
+        self._own_session = session is None
+
+    @property
+    def api_name(self) -> str:
+        return self.__class__.__name__
+
+    @abstractmethod
+    def _get_base_url(self) -> str:
+        """Return API base URL."""
+
+    def _get_default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+            self._own_session = True
+        return self._session
+
+    async def close(self) -> None:
+        if self._session is not None and self._own_session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> "APIClient":
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    def _extract_error_message(self, payload: Any) -> str | None:
+        if isinstance(payload, str):
+            return payload
+        if isinstance(payload, dict):
+            if isinstance(payload.get("error"), str):
+                return payload["error"]
+            if isinstance(payload.get("message"), str):
+                return payload["message"]
+            nested_error = payload.get("error")
+            if isinstance(nested_error, dict):
+                nested_message = nested_error.get("message")
+                if isinstance(nested_message, str):
+                    return nested_message
+        return None

custom_components/ai_hub/config_flow.py

@@ -145,9 +145,13 @@ async def async_step_user(
 
         try:
             await validate_input(self.hass, user_input)
-        except ValueError:
-            _LOGGER.exception("Invalid API key")
-            errors["base"] = "invalid_auth"
+        except ValueError as err:
+            reason = str(err)
+            if reason in {"invalid_auth", "cannot_connect"}:
+                errors["base"] = reason
+            else:
+                _LOGGER.exception("Unexpected validation error: %s", err)
+                errors["base"] = "unknown"
         except aiohttp.ClientError:
             _LOGGER.exception("Cannot connect")
             errors["base"] = "cannot_connect"

custom_components/ai_hub/const.py

@@ -24,7 +24,10 @@
 import logging
 from typing import Any, Final
 
-from homeassistant.core import HomeAssistant
+try:
+    from homeassistant.core import HomeAssistant
+except ModuleNotFoundError:  # pragma: no cover - used only in lightweight test environments
+    HomeAssistant = Any  # type: ignore[assignment]
 
 # Import llm for API constants
 try:

custom_components/ai_hub/diagnostics.py

@@ -18,9 +18,23 @@
 from datetime import datetime
 from typing import Any
 
-from homeassistant.components.diagnostics import async_redact_data
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
+try:
+    from homeassistant.components.diagnostics import async_redact_data
+    from homeassistant.config_entries import ConfigEntry
+    from homeassistant.core import HomeAssistant
+except ModuleNotFoundError:  # pragma: no cover - used only in lightweight test environments
+    ConfigEntry = Any  # type: ignore[assignment]
+    HomeAssistant = Any  # type: ignore[assignment]
+
+    def async_redact_data(data: dict[str, Any], to_redact: set[str]) -> dict[str, Any]:
+        """Fallback redaction helper when Home Assistant is unavailable."""
+        redacted = {}
+        for key, value in data.items():
+            if key in to_redact:
+                redacted[key] = "REDACTED"
+            else:
+                redacted[key] = value
+        return redacted
 
 from .const import (
     CONF_API_KEY,

custom_components/ai_hub/providers/__init__.py

@@ -215,24 +215,13 @@ def get_registry() -> UnifiedProviderRegistry:
 def _register_builtin_providers(registry: UnifiedProviderRegistry) -> None:
     """Register all built-in providers."""
     # Import and register LLM providers
-    try:
-        from .siliconflow import SiliconFlowProvider
-
-        registry.register(
-            SiliconFlowProvider,
-            is_default=True,
-            requires_api_key=True,
-            description="SiliconFlow (硅基流动) - Free tier available",
-        )
-    except ImportError as e:
-        _LOGGER.debug("SiliconFlow provider not available: %s", e)
 
     try:
         from .openai_compatible import OpenAICompatibleProvider
 
         registry.register(
             OpenAICompatibleProvider,
-            is_default=False,
+            is_default=True,
             requires_api_key=True,
             description="OpenAI-compatible API (OpenAI, Azure, local LLMs)",
         )

custom_components/ai_hub/services.yaml

@@ -126,40 +126,6 @@ create_automation:
       selector:
         text:
 
-get_automation_templates:
-  name: 获取自动化模板
-  description: 获取所有已创建的自动化模板
-
-delete_automation_template:
-  name: 删除自动化模板
-  description: 删除指定的自动化模板
-  fields:
-    template_id:
-      name: 模板ID
-      description: 要删除的模板ID
-      required: true
-      selector:
-        text:
-
-create_dashboard:
-  name: 创建仪表板
-  description: 通过自然语言描述创建Home Assistant仪表板
-  fields:
-    description:
-      name: 仪表板描述
-      description: 描述你想要的仪表板内容和布局
-      required: true
-      example: "创建一个包含温度传感器和灯光控制的主页面仪表板"
-      selector:
-        text:
-          multiline: true
-    dashboard_config:
-      name: 仪表板配置
-      description: 可选的自定义仪表板配置（JSON格式）
-      required: false
-      selector:
-        text:
-          multiline: true
 send_wechat_message:
   name: 发送微信消息
   description: 通过巴法云发送微信消息通知，设备标题显示实体名称和状态（需要Bemfa UID）