fix(arch): 迁移 LLM 异常到 llm/exceptions.py 消除分层异味

将 LLMError/LLMProviderError/ModelNotFoundError 定义从 core/exceptions.py
迁移到 llm/exceptions.py，使 LLM 异常定义归位 LLM 层。

- core/exceptions.py 用 PEP 562 __getattr__ 延迟 re-export，打破循环依赖：
  core.exceptions → llm.exceptions → llm.__init__ → llm.retry → core.exceptions
- llm/exceptions.py 中 LLMError 仍继承 AgentFrameworkError，保持 isinstance 兼容
- llm/__init__.py 导出 exceptions，支持 from agentkit.llm import LLMError
- 现有 from agentkit.core.exceptions import LLMProviderError 调用无需修改

零破坏性变更，ruff + import 兼容性验证通过。

src/agentkit/core/exceptions.py

@@ -132,24 +132,32 @@ class EvolutionError(AgentFrameworkError):
         super().__init__(f"Evolution failed for agent '{agent_name}': {reason}")
 
 
-class LLMError(AgentFrameworkError):
+# Re-export LLM exceptions from llm/exceptions.py for backward compatibility.
-    """LLM 基础异常"""
+# New code should import from agentkit.llm.exceptions directly.
-
+# ponytail: 架构分层修复 — LLM 异常定义归位 LLM 层；re-export 保留以避免破坏
-    def __init__(self, message: str = "LLM error"):
+# 现有 `from agentkit.core.exceptions import LLMProviderError` 调用方。
-        super().__init__(message)
+# 升级路径：调用方逐步迁移到 llm.exceptions 后可移除 __getattr__。
+#
+# 用 PEP 562 模块级 __getattr__ 延迟导入，打破循环依赖：
+# core.exceptions → llm.exceptions → llm.__init__ → llm.retry → core.exceptions.LLMProviderError
+# （若顶层 import，LLMProviderError 尚未绑定 → ImportError）
+_LLM_EXCEPTION_NAMES = ("LLMError", "LLMProviderError", "ModelNotFoundError")
 
 
-class LLMProviderError(LLMError):
+def __getattr__(name: str):  # PEP 562
-    """LLM Provider 特定异常"""
+    if name in _LLM_EXCEPTION_NAMES:
+        from agentkit.llm.exceptions import (  # noqa: PLC0415
+            LLMError,
+            LLMProviderError,
+            ModelNotFoundError,
+        )
 
-    def __init__(self, provider: str, reason: str = ""):
+        globals()["LLMError"] = LLMError
-        self.provider = provider
+        globals()["LLMProviderError"] = LLMProviderError
-        super().__init__(f"LLM provider '{provider}' error: {reason}")
+        globals()["ModelNotFoundError"] = ModelNotFoundError
+        return globals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-class ModelNotFoundError(LLMError):
+def __dir__():  # 让 from agentkit.core.exceptions import * 仍能发现 re-export
-    """模型别名未找到异常"""
+    return [*(globals().keys()), *_LLM_EXCEPTION_NAMES]
-
-    def __init__(self, model: str):
-        self.model = model
-        super().__init__(f"Model not found: {model}")

src/agentkit/llm/__init__.py

@@ -7,6 +7,7 @@ from agentkit.llm.providers.anthropic import AnthropicProvider
 from agentkit.llm.providers.openai import OpenAICompatibleProvider
 from agentkit.llm.providers.tracker import UsageSummary, UsageTracker
 from agentkit.llm.providers.usage_store import UsageRecord
+from agentkit.llm.exceptions import LLMError, LLMProviderError, ModelNotFoundError
 from agentkit.llm.remote_provider import RemoteLLMProvider
 from agentkit.llm.retry import (
     CircuitBreaker,
@@ -38,4 +39,7 @@ __all__ = [
     "UsageTracker",
     "UsageRecord",
     "UsageSummary",
+    "LLMError",
+    "LLMProviderError",
+    "ModelNotFoundError",
 ]

src/agentkit/llm/exceptions.py

@@ -0,0 +1,37 @@
+"""LLM 层异常定义。
+
+架构分层原则：LLM 异常定义在 LLM 层，而非 core/exceptions.py。
+core/exceptions.py 保留 re-export 以保持向后兼容。
+"""
+
+from agentkit.core.exceptions import AgentFrameworkError
+
+
+class LLMError(AgentFrameworkError):
+    """LLM 基础异常"""
+
+    def __init__(self, message: str = "LLM error"):
+        super().__init__(message)
+
+
+class LLMProviderError(LLMError):
+    """LLM Provider 特定异常"""
+
+    def __init__(self, provider: str, reason: str = ""):
+        self.provider = provider
+        super().__init__(f"LLM provider '{provider}' error: {reason}")
+
+
+class ModelNotFoundError(LLMError):
+    """模型别名未找到异常"""
+
+    def __init__(self, model: str):
+        self.model = model
+        super().__init__(f"Model not found: {model}")
+
+
+__all__ = [
+    "LLMError",
+    "LLMProviderError",
+    "ModelNotFoundError",
+]