fix(issue-1543): [bug]-alphasift-可用性检测不应静默吞掉非预期异常 (#1544)

Author: ZhuLinsen

api/v1/endpoints/alphasift.py

@@ -5,13 +5,14 @@
 
 import importlib
 import inspect
+import logging
 import math
 import os
 import subprocess
 import sys
 from dataclasses import asdict, is_dataclass
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional, Tuple
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel, Field
@@ -21,8 +22,10 @@
 from src.auth import COOKIE_NAME, is_auth_enabled, verify_session
 
 router = APIRouter()
+logger = logging.getLogger(__name__)
 
 ALPHASIFT_DSA_ADAPTER_MODULE = "alphasift.dsa_adapter"
+ALPHASIFT_EXPECTED_MISSING_MODULES = frozenset({"alphasift", ALPHASIFT_DSA_ADAPTER_MODULE})
 ALLOWED_ALPHASIFT_INSTALL_SPECS = frozenset({DEFAULT_ALPHASIFT_INSTALL_SPEC})
 
 
@@ -46,23 +49,18 @@ class AlphaSiftStrategyResponse(BaseModel):
 
 @router.get("/status")
 def alphasift_status(config: Config = Depends(get_config_dep)) -> Dict[str, Any]:
-    adapter_status: Dict[str, Any] = {}
-    available = _is_alphasift_available()
-    if available:
-        try:
-            adapter_status = _call_alphasift_status()
-            available = bool(adapter_status.get("available", True))
-        except Exception:
-            available = False
-
-    return {
+    adapter_status, available, diagnostics = _get_alphasift_status_snapshot()
+    payload = {
         "enabled": bool(config.alphasift_enabled),
         "available": available,
         "install_spec_is_default": _is_default_alphasift_install_spec(config.alphasift_install_spec),
         "contract_version": adapter_status.get("contract_version"),
         "version": adapter_status.get("version"),
         "strategy_count": adapter_status.get("strategy_count"),
     }
+    if diagnostics:
+        payload["diagnostics"] = diagnostics
+    return payload
 
 
 @router.get("/strategies")
@@ -251,10 +249,20 @@ def _ensure_alphasift_enabled(config: Config) -> None:
 
 
 def _is_alphasift_available() -> bool:
+    _, available, _ = _get_alphasift_status_snapshot()
+    return available
+
+
+def _get_alphasift_status_snapshot() -> Tuple[Dict[str, Any], bool, Optional[Dict[str, str]]]:
     try:
-        return _is_adapter_available(_call_alphasift_status())
-    except Exception:
-        return False
+        adapter_status = _call_alphasift_status()
+    except HTTPException as exc:
+        return {}, False, _extract_alphasift_diagnostics(exc)
+    except Exception as exc:
+        diagnostics = _log_unexpected_alphasift_exception("status_probe", exc)
+        return {}, False, diagnostics
+
+    return adapter_status, _is_adapter_available(adapter_status), None
 
 
 def _is_adapter_available(adapter_status: Any) -> bool:
@@ -264,16 +272,24 @@ def _is_adapter_available(adapter_status: Any) -> bool:
 
 
 def _import_alphasift() -> Any:
-    _prepare_alphasift_runtime_env()
     try:
+        _prepare_alphasift_runtime_env()
         return importlib.import_module(ALPHASIFT_DSA_ADAPTER_MODULE)
+    except ModuleNotFoundError as exc:
+        if _is_expected_alphasift_missing(exc):
+            raise _alphasift_unavailable_exception(
+                f"AlphaSift 未安装或未挂载到当前 Python 环境，无法导入 {ALPHASIFT_DSA_ADAPTER_MODULE}：{exc}"
+            ) from exc
+        diagnostics = _log_unexpected_alphasift_exception("import_adapter", exc)
+        raise _alphasift_unavailable_exception(
+            f"AlphaSift 适配层导入失败，请检查依赖完整性和当前 Python 环境：{exc}",
+            diagnostics=diagnostics,
+        ) from exc
     except Exception as exc:
-        raise HTTPException(
-            status_code=424,
-            detail={
-                "error": "alphasift_unavailable",
-                "message": f"AlphaSift 未安装或未挂载到当前 Python 环境，无法导入 {ALPHASIFT_DSA_ADAPTER_MODULE}：{exc}",
-            },
+        diagnostics = _log_unexpected_alphasift_exception("import_adapter", exc)
+        raise _alphasift_unavailable_exception(
+            f"AlphaSift 适配层导入失败，请检查依赖完整性和当前 Python 环境：{exc}",
+            diagnostics=diagnostics,
         ) from exc
 
 
@@ -309,22 +325,64 @@ def _get_adapter_callable(adapter: Any, name: str, missing_error: str) -> Any:
 
 def _call_alphasift_status() -> Dict[str, Any]:
     adapter = _import_alphasift()
-    get_status = _get_adapter_callable(adapter, "get_status", "get_status() 不可调用。")
+    try:
+        get_status = _get_adapter_callable(adapter, "get_status", "get_status() 不可调用。")
+    except HTTPException as exc:
+        diagnostics = _log_unexpected_alphasift_exception("get_status_callable", exc)
+        raise _alphasift_unavailable_exception(
+            "AlphaSift 适配层 get_status 不可调用，请检查适配层版本。",
+            diagnostics=diagnostics,
+        ) from exc
     try:
         result = _to_plain(get_status())
     except Exception as exc:
-        raise HTTPException(
-            status_code=424,
-            detail={
-                "error": "alphasift_unavailable",
-                "message": f"AlphaSift 适配层 get_status 调用失败：{exc}",
-            },
+        diagnostics = _log_unexpected_alphasift_exception("get_status", exc)
+        raise _alphasift_unavailable_exception(
+            f"AlphaSift 适配层 get_status 调用失败：{exc}",
+            diagnostics=diagnostics,
         ) from exc
     if not isinstance(result, dict):
-        return {}
+        exc = TypeError(f"get_status returned {type(result).__name__}, expected dict")
+        diagnostics = _log_unexpected_alphasift_exception("get_status_result", exc)
+        raise _alphasift_unavailable_exception(
+            "AlphaSift 适配层 get_status 返回结构非法，请检查适配层版本。",
+            diagnostics=diagnostics,
+        ) from exc
     return result
 
 
+def _is_expected_alphasift_missing(exc: ModuleNotFoundError) -> bool:
+    return getattr(exc, "name", None) in ALPHASIFT_EXPECTED_MISSING_MODULES
+
+
+def _alphasift_unavailable_exception(
+    message: str,
+    *,
+    diagnostics: Optional[Dict[str, str]] = None,
+) -> HTTPException:
+    detail: Dict[str, Any] = {"error": "alphasift_unavailable", "message": message}
+    if diagnostics:
+        detail["diagnostics"] = diagnostics
+    return HTTPException(status_code=424, detail=detail)
+
+
+def _log_unexpected_alphasift_exception(stage: str, exc: BaseException) -> Dict[str, str]:
+    logger.warning("Unexpected AlphaSift %s failure: %s", stage, exc, exc_info=exc.__traceback__ is not None)
+    return {
+        "reason": "unexpected_exception",
+        "stage": stage,
+        "error_type": exc.__class__.__name__,
+    }
+
+
+def _extract_alphasift_diagnostics(exc: HTTPException) -> Optional[Dict[str, str]]:
+    detail = exc.detail if isinstance(exc.detail, dict) else {}
+    diagnostics = detail.get("diagnostics")
+    if not isinstance(diagnostics, dict):
+        return None
+    return {str(key): str(value) for key, value in diagnostics.items()}
+
+
 def _list_strategies() -> List[Dict[str, Any]]:
     adapter = _get_dsa_adapter()
     list_strategies = _get_adapter_callable(adapter, "list_strategies", "list_strategies() 不可调用。")

docs/CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [修复] AlphaSift 默认安装来源改为锁定 commit 的受信任 GitHub 地址，自动安装接口要求管理员会话并限制安装来源。
 - [修复] 修复 Web 开启 AlphaSift 时先安装后写配置导致默认关闭状态无法开启的问题。
 - [修复] AlphaSift 状态与安装接口不再返回 `install_spec` 明文，仅返回 `install_spec_is_default` 等非敏感状态字段。
+- [修复] AlphaSift 状态探测区分可选依赖缺失与非预期异常，异常场景记录 warning 并返回非敏感诊断信息。
 - [修复] 调整 AlphaSift 筛选调用兼容：`screen` 以 `max_results` 为主并支持历史 `max_output` 关键词，同时允许策略透传以对齐前端手动策略参数。
 - [修复] AlphaSift Web 选股请求使用独立长超时，避免开启 LLM 重排后被通用 30 秒 API 超时提前中断。
 - [修复] 桌面端打包阶段预置 AlphaSift 并收集适配层，避免发布包运行时再要求管理员自动安装。

docs/alphasift-integration.md

@@ -70,6 +70,7 @@ AlphaSift 侧已在 `ZhuLinsen/alphasift@b2ca66dd47001b9a09890cfe21c2b18c7219ccf
 - 任何配置清理、回退与告警仍沿用当前后端配置解析链路（包括运行时保存前验证、兼容别名解析和非法值 fallback）；AlphaSift 功能本身不引入额外清理/迁移副作用。
 - 如果用户已在 `.env`/设置页配置过历史值，AlphaSift 开启前后应保持可用行为一致；需要恢复旧行为时，按既有方式回退到原配置（例如恢复旧的模型名/BASE URL，或关闭相关模型通道）即可。
 - 失败可见性：`status`/`screen` 接口返回明确错误码与 `message`，前端在设置页或选股页会将 `403/424/400/422` 等错误直接提示给用户，便于定位并回退到“关闭 AlphaSift + 保持原有 LLM 运行链路”。
+- 状态诊断：`/api/v1/alphasift/status` 对 AlphaSift 包或 `alphasift.dsa_adapter` 未安装仍保持 `200` + `available=false` 的兼容语义；如果导入过程、`get_status()` 调用或返回结构出现非预期异常，后端会记录 warning，并在响应中追加不含安装来源明文的 `diagnostics` 字段，便于从接口状态和服务端日志定位问题。
 
 错误策略：
 

tests/test_alphasift_api.py

@@ -73,17 +73,19 @@ def test_default_install_spec_is_commit_pinned(self) -> None:
     def test_status_defaults_to_disabled(self) -> None:
         config = self._config(enabled=False)
 
-        with patch("api.v1.endpoints.alphasift._is_alphasift_available", return_value=False):
+        with patch("api.v1.endpoints.alphasift._call_alphasift_status", side_effect=_raise_alphasift_unavailable):
             payload = alphasift_endpoint.alphasift_status(config=config)
 
         self.assertEqual(payload["enabled"], False)
+        self.assertEqual(payload["available"], False)
         self.assertEqual(payload["install_spec_is_default"], True)
+        self.assertNotIn("diagnostics", payload)
         self.assertNotIn("install_spec", payload)
 
     def test_status_marks_custom_install_source(self) -> None:
         config = self._config(enabled=False, install_spec="git+https://example.com/private/alphasift.git")
 
-        with patch("api.v1.endpoints.alphasift._is_alphasift_available", return_value=False):
+        with patch("api.v1.endpoints.alphasift._call_alphasift_status", side_effect=_raise_alphasift_unavailable):
             payload = alphasift_endpoint.alphasift_status(config=config)
 
         self.assertEqual(payload["install_spec_is_default"], False)
@@ -92,29 +94,94 @@ def test_status_marks_custom_install_source(self) -> None:
     def test_status_includes_adapter_contract_metadata(self) -> None:
         config = self._config(enabled=True)
 
-        with (
-            patch("api.v1.endpoints.alphasift._is_alphasift_available", return_value=True),
-            patch(
-                "api.v1.endpoints.alphasift._call_alphasift_status",
-                return_value={"available": True, "contract_version": "1", "version": "0.2.0", "strategy_count": 8},
-            ),
+        with patch(
+            "api.v1.endpoints.alphasift._call_alphasift_status",
+            return_value={"available": True, "contract_version": "1", "version": "0.2.0", "strategy_count": 8},
         ):
             payload = alphasift_endpoint.alphasift_status(config=config)
 
+        self.assertTrue(payload["available"])
         self.assertEqual(payload["contract_version"], "1")
         self.assertEqual(payload["version"], "0.2.0")
         self.assertEqual(payload["strategy_count"], 8)
 
-    def test_status_maps_adapter_runtime_exception_to_unavailable(self) -> None:
+    def test_status_preserves_adapter_available_false_without_diagnostics(self) -> None:
+        config = self._config(enabled=False)
+
+        with patch(
+            "api.v1.endpoints.alphasift._call_alphasift_status",
+            return_value={"available": False, "contract_version": "1", "version": "0.2.0", "strategy_count": 0},
+        ):
+            payload = alphasift_endpoint.alphasift_status(config=config)
+
+        self.assertFalse(payload["available"])
+        self.assertEqual(payload["contract_version"], "1")
+        self.assertNotIn("diagnostics", payload)
+
+    def test_status_logs_and_reports_adapter_runtime_exception_diagnostics(self) -> None:
+        config = self._config(enabled=False)
+        fake_module = _make_adapter_module(get_status=MagicMock(side_effect=RuntimeError("get_status failed")))
+
+        with (
+            patch("api.v1.endpoints.alphasift._import_alphasift", return_value=fake_module),
+            self.assertLogs("api.v1.endpoints.alphasift", level="WARNING") as captured,
+        ):
+            payload = alphasift_endpoint.alphasift_status(config=config)
+
+        self.assertFalse(payload["available"])
+        self.assertEqual(payload["diagnostics"]["reason"], "unexpected_exception")
+        self.assertEqual(payload["diagnostics"]["stage"], "get_status")
+        self.assertEqual(payload["diagnostics"]["error_type"], "RuntimeError")
+        self.assertIn("Unexpected AlphaSift get_status failure", "\n".join(captured.output))
+
+    def test_status_logs_and_reports_unexpected_import_exception_diagnostics(self) -> None:
+        config = self._config(enabled=False)
+        missing_sub_dependency = ModuleNotFoundError("No module named 'optional_dep'", name="optional_dep")
+
+        with (
+            patch("api.v1.endpoints.alphasift._prepare_alphasift_runtime_env"),
+            patch("api.v1.endpoints.alphasift.importlib.import_module", side_effect=missing_sub_dependency),
+            self.assertLogs("api.v1.endpoints.alphasift", level="WARNING") as captured,
+        ):
+            payload = alphasift_endpoint.alphasift_status(config=config)
+
+        self.assertFalse(payload["available"])
+        self.assertEqual(payload["diagnostics"]["reason"], "unexpected_exception")
+        self.assertEqual(payload["diagnostics"]["stage"], "import_adapter")
+        self.assertEqual(payload["diagnostics"]["error_type"], "ModuleNotFoundError")
+        self.assertIn("Unexpected AlphaSift import_adapter failure", "\n".join(captured.output))
+
+    def test_status_logs_and_reports_invalid_get_status_result_diagnostics(self) -> None:
+        config = self._config(enabled=False)
+        fake_module = _make_adapter_module(get_status=lambda: ["not", "a", "dict"])
+
+        with (
+            patch("api.v1.endpoints.alphasift._import_alphasift", return_value=fake_module),
+            self.assertLogs("api.v1.endpoints.alphasift", level="WARNING") as captured,
+        ):
+            payload = alphasift_endpoint.alphasift_status(config=config)
+
+        self.assertFalse(payload["available"])
+        self.assertEqual(payload["diagnostics"]["reason"], "unexpected_exception")
+        self.assertEqual(payload["diagnostics"]["stage"], "get_status_result")
+        self.assertEqual(payload["diagnostics"]["error_type"], "TypeError")
+        self.assertIn("Unexpected AlphaSift get_status_result failure", "\n".join(captured.output))
+
+    def test_status_logs_and_reports_missing_get_status_callable_diagnostics(self) -> None:
         config = self._config(enabled=False)
+        fake_module = SimpleNamespace(list_strategies=lambda: [], screen=MagicMock(return_value=[]))
 
         with (
-            patch("api.v1.endpoints.alphasift._is_alphasift_available", return_value=True),
-            patch("api.v1.endpoints.alphasift._call_alphasift_status", side_effect=RuntimeError("get_status failed")),
+            patch("api.v1.endpoints.alphasift._import_alphasift", return_value=fake_module),
+            self.assertLogs("api.v1.endpoints.alphasift", level="WARNING") as captured,
         ):
             payload = alphasift_endpoint.alphasift_status(config=config)
 
         self.assertFalse(payload["available"])
+        self.assertEqual(payload["diagnostics"]["reason"], "unexpected_exception")
+        self.assertEqual(payload["diagnostics"]["stage"], "get_status_callable")
+        self.assertEqual(payload["diagnostics"]["error_type"], "HTTPException")
+        self.assertIn("Unexpected AlphaSift get_status_callable failure", "\n".join(captured.output))
 
     def test_strategies_returns_adapter_strategies(self) -> None:
         config = self._config(enabled=True)