refactor: 符合 Home Assistant 集成规范

P0 修复:
- 实体类命名规范化 (AIHubTTSEntity, AIHubSTTEntity, AIHubConversationAgent, AIHubHealthCheckSensor)
- 服务合并 (tts_speech + tts_stream → tts_say)
- 补充核心测试 (test_conversation, test_config_flow, test_services)

P1 修复:
- 错误消息国际化 (使用字符串键)
- 优化实体唯一标识符 (使用 DOMAIN 前缀)
- 添加 HA 新特性支持 (TTS quality 参数, STT language 检测)

P2 修复:
- 优化实体类别使用 (Button 非诊断类别, Sensor device_class)
- 代码注释国际化
- PEP8 和 ruff 检查通过
- 删除不必要的 pyproject.toml

Author: Desmond-Dong

custom_components/ai_hub/button/__init__.py

@@ -8,7 +8,6 @@
 
 from homeassistant.components.button import ButtonEntity
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import config_entry_flow
 from homeassistant.helpers import device_registry as dr
@@ -70,7 +69,7 @@ class _AIHubServiceButton(ButtonEntity):
 
     _attr_has_entity_name = False
     _attr_should_poll = False
-    _attr_entity_category = EntityCategory.DIAGNOSTIC
+    _attr_entity_category = None
 
     def __init__(
         self,
@@ -88,7 +87,7 @@ def __init__(
         config = _BUTTON_CONFIGS[button_type]
 
         # Set attributes from configuration
-        self._attr_unique_id = f"{subentry.subentry_id}_{config['unique_id_suffix']}"
+        self._attr_unique_id = f"{DOMAIN}_{subentry.subentry_id}_{config['unique_id_suffix']}"
         self._attr_name = config["name"]
         self._attr_icon = config["icon"]
         self._service = config["service"]

custom_components/ai_hub/config_flow.py

@@ -117,10 +117,10 @@ async def validate_input(hass: HomeAssistant, data: dict[str, Any]) -> None:
                 timeout=aiohttp.ClientTimeout(total=10),
             ) as response:
                 if response.status == 401:
-                    raise ValueError("Invalid API key")
+                    raise ValueError("invalid_auth")
                 if response.status != 200:
-                    error_text = await response.text()
-                    raise Exception(f"API test failed: {error_text}")
+                    await response.text()  # Read response but don't use it
+                    raise ValueError("cannot_connect")
 
 
 class AIHubConfigFlow(ConfigFlow, domain=DOMAIN):

custom_components/ai_hub/const.py

@@ -1,13 +1,22 @@
 """Constants for the AI Hub integration.
 
 This module contains all constants organized by category:
-- Domain and API URLs
-- Timeouts and Retry Configuration
-- Cache and Audio Limits
-- Configuration Keys
-- Model Lists
-- Default Values and Recommended Options
-- Services
+
+SECTION 1: Domain and API URLs
+SECTION 2: Timeouts and Retry Configuration
+SECTION 3: Cache and Audio Limits
+SECTION 4: Configuration Keys
+SECTION 5: Default Values and Recommended Options
+SECTION 6: Model Lists
+SECTION 7: Error Messages
+SECTION 8: Services
+
+For better organization, consider extracting these to separate modules:
+- const/urls.py - API endpoints
+- const/timeouts.py - Timeout configurations
+- const/models.py - Model lists
+- const/defaults.py - Default values
+- const/errors.py - Error messages
 """
 
 from __future__ import annotations
@@ -362,8 +371,7 @@ def get_localized_name(hass: HomeAssistant, zh_name: str, en_name: str) -> str:
 SERVICES: Final = {
     "generate_image": "generate_image",
     "analyze_image": "analyze_image",
-    "tts_speech": "tts_speech",
-    "tts_stream": "tts_stream",
+    "tts_say": "tts_say",
     "stt_transcribe": "stt_transcribe",
     "send_wechat_message": "send_wechat_message",
     "translate_components": "translate_components",
@@ -373,8 +381,10 @@ def get_localized_name(hass: HomeAssistant, zh_name: str, en_name: str) -> str:
 # Legacy service constants
 SERVICE_GENERATE_IMAGE: Final = SERVICES["generate_image"]
 SERVICE_ANALYZE_IMAGE: Final = SERVICES["analyze_image"]
-SERVICE_TTS_SPEECH: Final = SERVICES["tts_speech"]
-SERVICE_TTS_STREAM: Final = SERVICES["tts_stream"]
+SERVICE_TTS_SAY: Final = SERVICES["tts_say"]
+# Deprecated: use SERVICE_TTS_SAY instead
+SERVICE_TTS_SPEECH: Final = "tts_speech"
+SERVICE_TTS_STREAM: Final = "tts_stream"
 SERVICE_STT_TRANSCRIBE: Final = SERVICES["stt_transcribe"]
 SERVICE_SEND_WECHAT_MESSAGE: Final = SERVICES["send_wechat_message"]
 SERVICE_TRANSLATE_COMPONENTS: Final = SERVICES["translate_components"]

custom_components/ai_hub/conversation.py

@@ -1,9 +1,16 @@
-"""Conversation support for AI Hub."""
+"""Conversation agent support for AI Hub integration.
+
+This module implements the ConversationEntity for AI-powered
+dialogue interactions, supporting:
+- Streaming responses
+- Tool calling (Home Assistant control)
+- Image understanding (vision models)
+- Context-aware conversations
+- Three-tier intent processing (local → HA built-in → LLM)"""
 
 from __future__ import annotations
 
 import logging
-import time
 from typing import Any, Literal
 
 from homeassistant.components import conversation
@@ -39,13 +46,13 @@ async def async_setup_entry(
             continue
 
         async_add_entities(
-            [AIHubConversationEntity(config_entry, subentry)],
+            [AIHubConversationAgent(config_entry, subentry)],
             config_subentry_id=subentry.subentry_id,
         )
-        _LOGGER.debug("Created conversation entity for subentry: %s", subentry.subentry_id)
+        _LOGGER.debug("Created conversation agent for subentry: %s", subentry.subentry_id)
 
 
-class AIHubConversationEntity(
+class AIHubConversationAgent(
     conversation.ConversationEntity,
     conversation.AbstractConversationAgent,
     AIHubBaseLLMEntity,
@@ -162,8 +169,10 @@ async def _async_handle_message(
                         _LOGGER.info("HA 内置意图处理成功: %s, type: %s", user_input.text, response_type)
                         return result
                     else:
-                        _LOGGER.debug("HA 内置意图未匹配(has_error=%s, is_no_match=%s)，交给 LLM 处理",
-                                    has_error, is_no_match)
+                        _LOGGER.debug(
+                            "HA 内置意图未匹配(has_error=%s, is_no_match=%s)，交给 LLM 处理",
+                            has_error, is_no_match
+                        )
             else:
                 _LOGGER.warning("HA 默认 agent 不可用")
 
@@ -238,9 +247,11 @@ async def _async_handle_message(
                 original_content = str(last_content.content)
                 filtered_content = filter_markdown_content(original_content)
                 if filtered_content != original_content:
-                    _LOGGER.debug("Filtered markdown from chat_log before returning: '%s' -> '%s'", 
-                                original_content[:50] if len(original_content) > 50 else original_content,
-                                filtered_content[:50] if len(filtered_content) > 50 else filtered_content)
+                    _LOGGER.debug(
+                        "Filtered markdown from chat_log before returning: '%s' -> '%s'",
+                        original_content[:50] if len(original_content) > 50 else original_content,
+                        filtered_content[:50] if len(filtered_content) > 50 else filtered_content
+                    )
                     last_content.content = filtered_content
 
         # Return result from chat log

custom_components/ai_hub/entity.py

@@ -607,7 +607,11 @@ def _convert_assistant_message(
                     "type": "function",
                     "function": {
                         "name": str(tool_call.tool_name) if tool_call.tool_name else "",
-                        "arguments": json.dumps(tool_call.tool_args, ensure_ascii=False) if tool_call.tool_args else "{}",
+                        "arguments": (
+                            json.dumps(tool_call.tool_args, ensure_ascii=False)
+                            if tool_call.tool_args
+                            else "{}"
+                        ),
                     },
                 })
             message["tool_calls"] = tool_calls_list
@@ -632,7 +636,11 @@ def _convert_tool_message(
         return {
             "role": "tool",
             "tool_call_id": tool_call_id,
-            "content": json.dumps(content.tool_result, ensure_ascii=False, default=str) if content.tool_result is not None else "{}",
+            "content": (
+                json.dumps(content.tool_result, ensure_ascii=False, default=str)
+                if content.tool_result is not None
+                else "{}"
+            ),
         }
 
     def _format_tool(
@@ -748,7 +756,12 @@ async def _transform_stream(
                                 }
 
                             # Update tool call data - only update id if it's a valid non-empty string
-                            if "id" in tc_delta and tc_delta["id"] and isinstance(tc_delta["id"], str) and tc_delta["id"].strip():
+                            if (
+                                "id" in tc_delta
+                                and tc_delta["id"]
+                                and isinstance(tc_delta["id"], str)
+                                and tc_delta["id"].strip()
+                            ):
                                 tool_call_buffer[index]["id"] = tc_delta["id"]
                             if "function" in tc_delta:
                                 func = tc_delta["function"]

custom_components/ai_hub/intents/loader.py

@@ -5,7 +5,7 @@
 import asyncio
 import logging
 from pathlib import Path
-from typing import Any
+from typing import Any, Dict
 
 from homeassistant.core import HomeAssistant
 

custom_components/ai_hub/sensor.py

@@ -66,7 +66,7 @@ async def async_setup_entry(
     entities = []
 
     # Main integration health sensor (always added)
-    entities.append(AIHubHealthSensor(hass, entry))
+    entities.append(AIHubHealthCheckSensor(hass, entry))
 
     # Edge TTS health sensor (always available, no API key needed)
     entities.append(EdgeTTSHealthSensor(hass, entry))
@@ -81,11 +81,12 @@ async def async_setup_entry(
     async_add_entities(entities)
 
 
-class AIHubHealthSensor(SensorEntity):
+class AIHubHealthCheckSensor(SensorEntity):
     """Sensor for overall AI Hub health status."""
 
     _attr_has_entity_name = True
     _attr_entity_category = EntityCategory.DIAGNOSTIC
+    _attr_device_class = SensorDeviceClass.ENUM
     _attr_icon = "mdi:heart-pulse"
     _attr_should_poll = True
 
@@ -97,7 +98,7 @@ def __init__(
         """Initialize the health sensor."""
         self.hass = hass
         self._entry = entry
-        self._attr_unique_id = f"{entry.entry_id}_health"
+        self._attr_unique_id = f"{DOMAIN}_{entry.entry_id}_health_sensor"
         self._attr_name = "Health Status"
         self._attr_device_info = _get_diagnostic_device_info(entry)
 
@@ -260,7 +261,7 @@ def __init__(
         """Initialize the sensor."""
         self.hass = hass
         self._entry = entry
-        self._attr_unique_id = f"{entry.entry_id}_{self._name_suffix}_latency"
+        self._attr_unique_id = f"{DOMAIN}_{entry.entry_id}_{self._name_suffix}_latency"
         self._attr_name = f"{self._name_suffix.replace('_', ' ').title()} Latency"
         self._attr_device_info = _get_diagnostic_device_info(entry)
 
@@ -328,6 +329,6 @@ class EdgeTTSHealthSensor(_BaseHealthSensor):
 class BemfaHealthSensor(_BaseHealthSensor):
     """Sensor for Bemfa API health and latency."""
 
-    _check_url = "https://apis.bemfa.com"
+    _check_url = "https://apis.bemfa.com/vb/wechat/v1/wechatAlertJson"
     _name_suffix = "bemfa"
     _attr_icon = "mdi:message-text"

custom_components/ai_hub/services.py

@@ -8,6 +8,7 @@
 from homeassistant.core import HomeAssistant, ServiceCall
 
 from .const import (
+    CONF_API_KEY,
     CONF_BEMFA_UID,
     CONF_CHAT_MODEL,
     CONF_CHAT_URL,
@@ -21,8 +22,7 @@
     SERVICE_STT_TRANSCRIBE,
     SERVICE_TRANSLATE_BLUEPRINTS,
     SERVICE_TRANSLATE_COMPONENTS,
-    SERVICE_TTS_SPEECH,
-    SERVICE_TTS_STREAM,
+    SERVICE_TTS_SAY,
 )
 from .services_lib import (
     BLUEPRINTS_TRANSLATION_SCHEMA,
@@ -32,7 +32,6 @@
     STT_SCHEMA,
     TRANSLATION_SCHEMA,
     TTS_SCHEMA,
-    TTS_STREAM_SCHEMA,
     WECHAT_SCHEMA,
     async_translate_all_blueprints,
     async_translate_all_components,
@@ -111,15 +110,16 @@ async def _handle_generate_image(call: ServiceCall) -> dict:
             return {"success": False, "error": "API密钥未配置"}
         return await handle_generate_image(hass, call, effective_key, image_url)
 
-    # ========== TTS 语音合成服务 ==========
-    async def _handle_tts_speech(call: ServiceCall) -> dict:
-        if not has_api_key():
-            return {"success": False, "error": "API密钥未配置"}
-        return await handle_tts_speech(hass, call, api_key)
-
-    # ========== TTS 流式语音服务 ==========
-    async def _handle_tts_stream(call: ServiceCall) -> dict:
-        return await handle_tts_stream(hass, call)
+    # ========== TTS 语音合成服务（统一） ==========
+    async def _handle_tts_say(call: ServiceCall) -> dict:
+        """Handle TTS service with optional streaming support."""
+        stream = call.data.get("stream", False)
+        if stream:
+            return await handle_tts_stream(hass, call)
+        else:
+            if not has_api_key():
+                return {"success": False, "error": "API密钥未配置"}
+            return await handle_tts_speech(hass, call, api_key)
 
     # ========== STT 语音转文字服务 ==========
     async def _handle_stt_transcribe(call: ServiceCall) -> dict:
@@ -200,15 +200,10 @@ async def _handle_translate_blueprints(call: ServiceCall) -> dict:
     )
 
     hass.services.async_register(
-        DOMAIN, SERVICE_TTS_SPEECH, _handle_tts_speech,
+        DOMAIN, SERVICE_TTS_SAY, _handle_tts_say,
         schema=vol.Schema(TTS_SCHEMA), supports_response=True
     )
 
-    hass.services.async_register(
-        DOMAIN, SERVICE_TTS_STREAM, _handle_tts_stream,
-        schema=vol.Schema(TTS_STREAM_SCHEMA), supports_response=True
-    )
-
     hass.services.async_register(
         DOMAIN, SERVICE_STT_TRANSCRIBE, _handle_stt_transcribe,
         schema=vol.Schema(STT_SCHEMA), supports_response=True
@@ -240,8 +235,7 @@ async def async_unload_services(hass: HomeAssistant) -> None:
     """
     hass.services.async_remove(DOMAIN, SERVICE_ANALYZE_IMAGE)
     hass.services.async_remove(DOMAIN, SERVICE_GENERATE_IMAGE)
-    hass.services.async_remove(DOMAIN, SERVICE_TTS_SPEECH)
-    hass.services.async_remove(DOMAIN, SERVICE_TTS_STREAM)
+    hass.services.async_remove(DOMAIN, SERVICE_TTS_SAY)
     hass.services.async_remove(DOMAIN, SERVICE_STT_TRANSCRIBE)
     hass.services.async_remove(DOMAIN, SERVICE_SEND_WECHAT_MESSAGE)
     hass.services.async_remove(DOMAIN, SERVICE_TRANSLATE_COMPONENTS)