secagentx 3.0.0__py3-none-any.whl

backend/config/provider_profiles.py

@@ -0,0 +1,416 @@
+"""模型 Provider 档案与系统凭据存储。
+
+配置文件只保存路由元数据和凭据引用；API Key 由系统 Keyring 或 Windows
+DPAPI 保存。也可通过环境变量提供凭据，适合 Docker、CI 和无桌面的服务器。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import base64
+import ctypes
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger("secagentx.provider_profiles")
+
+KEYRING_SERVICE = "SecAgentX"
+CONFIG_VERSION = 1
+
+
+PROVIDER_PRESETS: dict[str, dict[str, Any]] = {
+    "deepseek": {
+        "label": "DeepSeek",
+        "protocol": "openai_compatible",
+        "api_base": "https://api.deepseek.com/v1",
+        "model": "deepseek-chat",
+        "env_key": "DEEPSEEK_API_KEY",
+    },
+    "qwen": {
+        "label": "通义千问 (DashScope)",
+        "protocol": "openai_compatible",
+        "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "model": "qwen-max",
+        "env_key": "QWEN_API_KEY",
+    },
+    "openai": {
+        "label": "OpenAI",
+        "protocol": "openai_compatible",
+        "api_base": "https://api.openai.com/v1",
+        "model": "gpt-4o-mini",
+        "env_key": "OPENAI_API_KEY",
+    },
+    "anthropic": {
+        "label": "Anthropic",
+        "protocol": "anthropic_compatible",
+        "api_base": "https://api.anthropic.com/v1",
+        "model": "claude-sonnet-4-5",
+        "env_key": "ANTHROPIC_API_KEY",
+    },
+    "azure_openai": {
+        "label": "Azure OpenAI",
+        "protocol": "openai_compatible",
+        "api_base": "",
+        "model": "",
+        "env_key": "AZURE_OPENAI_API_KEY",
+        "auth_style": "api-key",
+        "api_version": "2024-10-21",
+    },
+    "gemini": {
+        "label": "Google Gemini (OpenAI 兼容接口)",
+        "protocol": "openai_compatible",
+        "api_base": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "model": "gemini-2.5-flash",
+        "env_key": "GEMINI_API_KEY",
+    },
+    "openrouter": {
+        "label": "OpenRouter",
+        "protocol": "openai_compatible",
+        "api_base": "https://openrouter.ai/api/v1",
+        "model": "openai/gpt-4o-mini",
+        "env_key": "OPENROUTER_API_KEY",
+    },
+    "xai": {
+        "label": "xAI (Grok)",
+        "protocol": "openai_compatible",
+        "api_base": "https://api.x.ai/v1",
+        "model": "grok-3-mini",
+        "env_key": "XAI_API_KEY",
+    },
+    "kimi": {
+        "label": "Moonshot / Kimi",
+        "protocol": "openai_compatible",
+        "api_base": "https://api.moonshot.cn/v1",
+        "model": "moonshot-v1-8k",
+        "env_key": "MOONSHOT_API_KEY",
+    },
+    "ollama": {
+        "label": "Ollama（本地）",
+        "protocol": "openai_compatible",
+        "api_base": "http://127.0.0.1:11434/v1",
+        "model": "llama3.2",
+        "env_key": "",
+        "requires_api_key": False,
+    },
+    "lmstudio": {
+        "label": "LM Studio（本地）",
+        "protocol": "openai_compatible",
+        "api_base": "http://127.0.0.1:1234/v1",
+        "model": "local-model",
+        "env_key": "",
+        "requires_api_key": False,
+    },
+    "custom_openai": {
+        "label": "自定义 OpenAI 兼容接口",
+        "protocol": "openai_compatible",
+        "api_base": "",
+        "model": "",
+        "env_key": "SECAGENTX_LLM_API_KEY",
+    },
+    "custom_anthropic": {
+        "label": "自定义 Anthropic 兼容接口",
+        "protocol": "anthropic_compatible",
+        "api_base": "",
+        "model": "",
+        "env_key": "SECAGENTX_LLM_API_KEY",
+    },
+    "mock": {
+        "label": "离线 Mock（仅验证流程）",
+        "protocol": "mock",
+        "api_base": "mock://local",
+        "model": "mock-llm",
+        "env_key": "",
+        "requires_api_key": False,
+    },
+}
+
+
+def get_secagentx_home() -> Path:
+    override = os.getenv("SECAGENTX_HOME", "").strip()
+    if override:
+        return Path(override).expanduser().resolve()
+    if os.name == "nt" and os.getenv("APPDATA"):
+        return Path(os.environ["APPDATA"]) / "SecAgentX"
+    config_home = os.getenv("XDG_CONFIG_HOME", "").strip()
+    return (Path(config_home) if config_home else Path.home() / ".config") / "secagentx"
+
+
+@dataclass
+class ProviderProfile:
+    profile_id: str
+    provider_id: str
+    label: str
+    protocol: str
+    api_base: str
+    model: str
+    credential_type: str = "keyring"
+    credential_ref: str = ""
+    env_key: str = ""
+    auth_style: str = "bearer"
+    api_version: str = ""
+    requires_api_key: bool = True
+    timeout_seconds: float = 60.0
+    max_tokens: int = 4096
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "ProviderProfile":
+        allowed = cls.__dataclass_fields__.keys()
+        return cls(**{k: value[k] for k in allowed if k in value})
+
+    def runtime_config(self, api_key: str = "") -> dict[str, Any]:
+        return {
+            "api_base": self.api_base,
+            "api_key": api_key,
+            "model": self.model,
+            "timeout_seconds": self.timeout_seconds,
+            "max_tokens": self.max_tokens,
+            "auth_style": self.auth_style,
+            "api_version": self.api_version,
+            "allow_no_key": not self.requires_api_key,
+        }
+
+
+class CredentialStoreError(RuntimeError):
+    pass
+
+
+class CredentialStore:
+    """系统凭据包装；Windows 可在无第三方包时使用用户级 DPAPI。"""
+
+    def __init__(self, service: str = KEYRING_SERVICE, dpapi_path: Optional[Path] = None):
+        self.service = service
+        self.dpapi_path = dpapi_path or (get_secagentx_home() / "credentials.dpapi")
+
+    @staticmethod
+    def _keyring_available() -> bool:
+        try:
+            import keyring
+            backend = keyring.get_keyring()
+            return backend is not None and backend.priority > 0
+        except Exception:
+            return False
+
+    @staticmethod
+    def available() -> bool:
+        return CredentialStore._keyring_available() or os.name == "nt"
+
+    @staticmethod
+    def _dpapi_transform(payload: bytes, protect: bool) -> bytes:
+        if os.name != "nt":
+            raise CredentialStoreError("当前系统无可用的本地安全凭据存储")
+
+        class DataBlob(ctypes.Structure):
+            _fields_ = [("cbData", ctypes.c_uint32), ("pbData", ctypes.POINTER(ctypes.c_ubyte))]
+
+        buffer = ctypes.create_string_buffer(payload)
+        input_blob = DataBlob(len(payload), ctypes.cast(buffer, ctypes.POINTER(ctypes.c_ubyte)))
+        output_blob = DataBlob()
+        crypt32 = ctypes.windll.crypt32
+        function = crypt32.CryptProtectData if protect else crypt32.CryptUnprotectData
+        if protect:
+            success = function(
+                ctypes.byref(input_blob), None, None, None, None, 0,
+                ctypes.byref(output_blob),
+            )
+        else:
+            success = function(
+                ctypes.byref(input_blob), None, None, None, None, 0,
+                ctypes.byref(output_blob),
+            )
+        if not success:
+            raise CredentialStoreError("Windows DPAPI 操作失败")
+        try:
+            return ctypes.string_at(output_blob.pbData, output_blob.cbData)
+        finally:
+            ctypes.windll.kernel32.LocalFree(output_blob.pbData)
+
+    def _load_dpapi(self) -> dict[str, str]:
+        if not self.dpapi_path.exists():
+            return {}
+        try:
+            encrypted = base64.b64decode(self.dpapi_path.read_bytes(), validate=True)
+            raw = self._dpapi_transform(encrypted, protect=False)
+            value = json.loads(raw.decode("utf-8"))
+            return value if isinstance(value, dict) else {}
+        except Exception as exc:
+            raise CredentialStoreError("无法读取 Windows DPAPI 凭据库") from exc
+
+    def _save_dpapi(self, values: dict[str, str]) -> None:
+        self.dpapi_path.parent.mkdir(parents=True, exist_ok=True)
+        raw = json.dumps(values, ensure_ascii=False).encode("utf-8")
+        encoded = base64.b64encode(self._dpapi_transform(raw, protect=True))
+        fd, tmp_name = tempfile.mkstemp(prefix="credentials-", suffix=".tmp", dir=self.dpapi_path.parent)
+        try:
+            with os.fdopen(fd, "wb") as handle:
+                handle.write(encoded)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.chmod(tmp_name, 0o600)
+            os.replace(tmp_name, self.dpapi_path)
+        finally:
+            if os.path.exists(tmp_name):
+                os.unlink(tmp_name)
+
+    def set(self, reference: str, secret: str) -> None:
+        if not secret:
+            raise CredentialStoreError("拒绝保存空 API Key")
+        if self._keyring_available():
+            import keyring
+            try:
+                keyring.set_password(self.service, reference, secret)
+                # 安装 Keyring 后迁移并清除可能遗留的 DPAPI 副本。
+                if os.name == "nt" and self.dpapi_path.exists():
+                    values = self._load_dpapi()
+                    if values.pop(f"{self.service}:{reference}", None) is not None:
+                        self._save_dpapi(values)
+                return
+            except Exception:
+                if os.name != "nt":
+                    raise CredentialStoreError("系统 Keyring 写入失败，请改用环境变量")
+        values = self._load_dpapi()
+        values[f"{self.service}:{reference}"] = secret
+        self._save_dpapi(values)
+
+    def get(self, reference: str) -> str:
+        if not reference:
+            return ""
+        if self._keyring_available():
+            import keyring
+            try:
+                secret = keyring.get_password(self.service, reference) or ""
+                if secret:
+                    return secret
+            except Exception:
+                pass
+        if os.name == "nt":
+            try:
+                return self._load_dpapi().get(f"{self.service}:{reference}", "")
+            except CredentialStoreError:
+                return ""
+        return ""
+
+    def delete(self, reference: str) -> None:
+        if not reference:
+            return
+        if self._keyring_available():
+            import keyring
+            try:
+                keyring.delete_password(self.service, reference)
+            except Exception:
+                pass
+        if os.name == "nt":
+            values = self._load_dpapi()
+            values.pop(f"{self.service}:{reference}", None)
+            self._save_dpapi(values)
+
+
+class ProviderProfileStore:
+    def __init__(self, path: Optional[Path] = None, credentials: Optional[CredentialStore] = None):
+        self.path = path or (get_secagentx_home() / "providers.json")
+        self.credentials = credentials or CredentialStore()
+
+    def load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {"version": CONFIG_VERSION, "active_profile": "", "profiles": {}}
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            if not isinstance(data.get("profiles"), dict):
+                raise ValueError("profiles 必须为对象")
+            return data
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            raise ValueError(f"Provider 配置损坏: {self.path}: {exc}") from exc
+
+    def save(self, data: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+        fd, tmp_name = tempfile.mkstemp(prefix="providers-", suffix=".tmp", dir=self.path.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(payload)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.chmod(tmp_name, 0o600)
+            os.replace(tmp_name, self.path)
+        finally:
+            if os.path.exists(tmp_name):
+                os.unlink(tmp_name)
+
+    def active(self) -> Optional[ProviderProfile]:
+        data = self.load()
+        profile_id = data.get("active_profile", "")
+        raw = data.get("profiles", {}).get(profile_id)
+        return ProviderProfile.from_dict(raw) if raw else None
+
+    def list_profiles(self) -> list[ProviderProfile]:
+        return [ProviderProfile.from_dict(v) for v in self.load().get("profiles", {}).values()]
+
+    def get_secret(self, profile: ProviderProfile) -> str:
+        if not profile.requires_api_key:
+            return "local-no-key"
+        if profile.env_key and os.getenv(profile.env_key):
+            return os.environ[profile.env_key]
+        if profile.credential_type == "env":
+            return os.getenv(profile.credential_ref or profile.env_key, "")
+        return self.credentials.get(profile.credential_ref)
+
+    def put(self, profile: ProviderProfile, api_key: str = "", make_active: bool = True) -> None:
+        if profile.requires_api_key and api_key:
+            profile.credential_type = "keyring"
+            profile.credential_ref = profile.credential_ref or f"provider:{profile.profile_id}"
+            self.credentials.set(profile.credential_ref, api_key)
+        elif profile.requires_api_key and not (
+            (profile.env_key and os.getenv(profile.env_key)) or self.get_secret(profile)
+        ):
+            raise CredentialStoreError("未提供可用 API Key")
+
+        data = self.load()
+        data["version"] = CONFIG_VERSION
+        data.setdefault("profiles", {})[profile.profile_id] = asdict(profile)
+        if make_active:
+            data["active_profile"] = profile.profile_id
+        self.save(data)
+
+    def set_active(self, profile_id: str) -> ProviderProfile:
+        data = self.load()
+        raw = data.get("profiles", {}).get(profile_id)
+        if not raw:
+            raise KeyError(f"Provider 档案不存在: {profile_id}")
+        data["active_profile"] = profile_id
+        self.save(data)
+        return ProviderProfile.from_dict(raw)
+
+
+def activate_profile(profile: ProviderProfile, api_key: str) -> None:
+    os.environ["SECAGENTX_ACTIVE_PROVIDER"] = profile.protocol
+    os.environ["LLM_PROVIDER"] = profile.protocol
+    os.environ["SECAGENTX_LLM_PROFILE"] = profile.profile_id
+    os.environ["SECAGENTX_LLM_PROVIDER_ID"] = profile.provider_id
+    os.environ["SECAGENTX_LLM_API_BASE"] = profile.api_base
+    os.environ["SECAGENTX_LLM_MODEL"] = profile.model
+    os.environ["SECAGENTX_LLM_AUTH_STYLE"] = profile.auth_style
+    os.environ["SECAGENTX_LLM_API_VERSION"] = profile.api_version
+    os.environ["SECAGENTX_LLM_ALLOW_NO_KEY"] = "true" if not profile.requires_api_key else "false"
+    if api_key:
+        os.environ["SECAGENTX_LLM_API_KEY"] = api_key
+
+
+def activate_stored_profile(store: Optional[ProviderProfileStore] = None) -> Optional[ProviderProfile]:
+    """加载活动档案到当前进程；无配置时保持现有环境变量兼容行为。"""
+    store = store or ProviderProfileStore()
+    try:
+        profile = store.active()
+        if not profile:
+            return None
+        secret = store.get_secret(profile)
+        if profile.requires_api_key and not secret:
+            logger.warning("活动 Provider %s 的凭据不可用", profile.profile_id)
+            return profile
+        activate_profile(profile, secret)
+        return profile
+    except ValueError as exc:
+        logger.error("%s", exc)
+        return None

backend/config/runtime_settings.py

@@ -0,0 +1,84 @@
+"""Web 运行设置。
+
+管理员密码仅保存 bcrypt 哈希；JWT secret 保存于系统 Keyring。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import tempfile
+from pathlib import Path
+from typing import Any, Optional
+
+from .provider_profiles import CredentialStore, CredentialStoreError, get_secagentx_home
+
+
+class RuntimeSettingsStore:
+    def __init__(self, path: Optional[Path] = None, credentials: Optional[CredentialStore] = None):
+        self.path = path or (get_secagentx_home() / "settings.json")
+        self.credentials = credentials or CredentialStore()
+
+    def load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {"version": 1, "web": {"host": "127.0.0.1", "port": 8000}}
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            raise ValueError(f"运行配置损坏: {self.path}: {exc}") from exc
+
+    def save(self, data: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(prefix="settings-", suffix=".tmp", dir=self.path.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(data, handle, ensure_ascii=False, indent=2)
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.chmod(tmp_name, 0o600)
+            os.replace(tmp_name, self.path)
+        finally:
+            if os.path.exists(tmp_name):
+                os.unlink(tmp_name)
+
+    def configure_web_credentials(self, password: str) -> None:
+        if len(password) < 12:
+            raise ValueError("管理员密码至少需要 12 个字符")
+        import bcrypt
+
+        data = self.load()
+        data["admin_password_hash"] = bcrypt.hashpw(
+            password.encode("utf-8"), bcrypt.gensalt(rounds=12)
+        ).decode("utf-8")
+        jwt_ref = data.get("jwt_secret_ref") or "runtime:jwt-secret"
+        self.credentials.set(jwt_ref, secrets.token_urlsafe(48))
+        data["jwt_secret_ref"] = jwt_ref
+        self.save(data)
+
+    def activate(self) -> dict[str, Any]:
+        data = self.load()
+        password_hash = data.get("admin_password_hash", "")
+        if password_hash and not os.getenv("SECAGENTX_PASSWORD_HASH") and not os.getenv("SECAGENTX_PASSWORD"):
+            os.environ["SECAGENTX_PASSWORD_HASH"] = password_hash
+        jwt_ref = data.get("jwt_secret_ref", "")
+        if jwt_ref and not os.getenv("SECAGENTX_JWT_SECRET"):
+            jwt_secret = self.credentials.get(jwt_ref)
+            if jwt_secret:
+                os.environ["SECAGENTX_JWT_SECRET"] = jwt_secret
+        return data
+
+    def web_ready(self) -> bool:
+        self.activate()
+        return bool(
+            (os.getenv("SECAGENTX_PASSWORD_HASH") or os.getenv("SECAGENTX_PASSWORD"))
+            and os.getenv("SECAGENTX_JWT_SECRET")
+        )
+
+
+def activate_runtime_settings() -> None:
+    try:
+        RuntimeSettingsStore().activate()
+    except (ValueError, CredentialStoreError):
+        return

backend/decision_fusion/__init__.py

@@ -0,0 +1,32 @@
+"""
+Decision Fusion 决策融合模块 — 统一决策框架（Sense-Decide 分离）
+
+职责:
+  - 各专业 Agent（感知层）只输出证据包 EvidencePackage
+  - Decision Fusion（决策层）统一裁决 → 唯一 final verdict
+  - 融合引擎为可替换模块（接口见 base.py）
+
+用法:
+    from backend.decision_fusion import FusionEngineFactory
+    engine = FusionEngineFactory.get_engine("dempster_shafer", config={...})
+    result = engine.fuse(evidence_packages)   # -> FusionResult
+
+引擎注册表:
+  - dempster_shafer   （默认，DS 证据理论，支持未知/冲突）
+  - weighted_average  （参考实现 / 兜底）
+"""
+from .base import DecisionFusionEngine, FusionEngineFactory, DEFAULT_AGENT_WEIGHTS
+from .dempster_shafer import DempsterShaferEngine
+from .weighted_average import WeightedAverageEngine
+from ..models.output import (
+    EvidencePackage, EvidenceMass, FusionConflict, FusionResult,
+    FusionVerdict, Finding, build_evidence_package, build_fusion_result,
+)
+
+__all__ = [
+    "DecisionFusionEngine", "FusionEngineFactory", "DEFAULT_AGENT_WEIGHTS",
+    "DempsterShaferEngine", "WeightedAverageEngine",
+    "EvidencePackage", "EvidenceMass", "FusionConflict", "FusionResult",
+    "FusionVerdict", "Finding", "build_evidence_package", "build_fusion_result",
+]
+

backend/decision_fusion/base.py

@@ -0,0 +1,127 @@
+"""
+DecisionFusionEngine — 决策融合引擎抽象接口（可替换模块）
+
+设计目标（Sense-Decide 分离）:
+  1. 各专业 Agent 只输出证据包（EvidencePackage），不直接裁决风险
+  2. Decision Fusion 统一裁决 → 唯一 final verdict
+  3. 引擎是可替换模块：通过工厂按名称注册/切换，默认 Dempster-Shafer
+
+接入新引擎步骤:
+  1. 继承 DecisionFusionEngine，实现 fuse()
+  2. 在 FusionEngineFactory._ENGINES 注册（或在运行时 register）
+  3. 配置 config.yaml: decision_fusion.engine = "你的引擎名"
+
+所有引擎输出统一 FusionResult（见 backend/models/output.py），
+上层（react_loop / RiskScorer / 前端）不感知具体算法。
+"""
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from ..models.output import (
+    EvidencePackage, FusionResult, build_fusion_result,
+)
+
+# ── 各 Agent 的固定基础权重（与 react_loop.CONFIDENCE_WEIGHTS 对齐） ──
+DEFAULT_AGENT_WEIGHTS = {
+    "analyst-001": 0.35,
+    "intel-001": 0.25,
+    "responder-001": 0.20,
+    "alert-filter-001": 0.10,
+    "knowledge-001": 0.10,
+}
+
+
+class DecisionFusionEngine(ABC):
+    """决策融合引擎抽象基类 — 可替换模块接口。
+
+    子类只需实现 fuse()；其余辅助方法（权重归一化等）可直接复用。
+    """
+
+    #: 引擎唯一标识（config 中 decision_fusion.engine 引用此名称）
+    name: str = "base"
+
+    def __init__(self, config: Optional[dict] = None):
+        self.config = config or {}
+        self.agent_weights = dict(DEFAULT_AGENT_WEIGHTS)
+        self.agent_weights.update(self.config.get("agent_weights", {}) or {})
+
+    @abstractmethod
+    def fuse(self, evidence_packages: list[EvidencePackage]) -> FusionResult:
+        """融合所有证据包，产出唯一权威裁决。
+
+        Args:
+            evidence_packages: 各 Agent 证据包（已标准化）
+
+        Returns:
+            FusionResult（verdict/confidence/conflicts/decision_path ...）
+        """
+        ...
+
+    # ── 共享辅助 ──
+
+    def _weight_for(self, agent_id: str, degraded: bool = False) -> float:
+        """获取 Agent 基础权重（降级折半，与既有纪律一致）。"""
+        w = self.agent_weights.get(agent_id, 0.0)
+        if degraded:
+            w *= 0.5
+        return w
+
+    def _normalize_weights(self, packages: list[EvidencePackage]) -> list[tuple[EvidencePackage, float]]:
+        """为每个证据包计算归一化权重（基础权重 × 证据可靠度）。
+
+        规则:
+          - failed 包权重 = 0（不参与融合，但记录）
+          - 无结构化裁决（evidence_confidence 接近默认且无 findings）→ 权重打折
+        """
+        scored = []
+        for p in packages:
+            if p.failed:
+                scored.append((p, 0.0))
+                continue
+            base = self._weight_for(p.agent_id, p.degraded)
+            # 证据可靠度：findings 均值 / evidence_confidence
+            ev_conf = p.evidence_confidence
+            if ev_conf <= 0.0:
+                ev_conf = 0.5
+            scored.append((p, base * ev_conf))
+        total = sum(w for _, w in scored)
+        if total <= 0:
+            return [(p, 0.0) for p in packages]
+        return [(p, w / total) for p, w in scored]
+
+
+# ═══════════════════════ 引擎工厂（可替换模块注册表） ═══════════════════════
+
+class FusionEngineFactory:
+    """决策融合引擎工厂 — 按名称获取引擎实例。
+
+    默认注册 dempster_shafer；可调用 register() 注册自定义引擎。
+    """
+
+    _ENGINES: dict[str, type] = {}
+
+    @classmethod
+    def register(cls, name: str, engine_cls: type) -> None:
+        cls._ENGINES[name] = engine_cls
+
+    @classmethod
+    def get_engine(cls, name: str = "dempster_shafer",
+                   config: Optional[dict] = None) -> "DecisionFusionEngine":
+        """获取引擎实例；未知名称抛 ValueError（配置错误要尽早暴露）。"""
+        engine_cls = cls._ENGINES.get(name)
+        if engine_cls is None:
+            raise ValueError(
+                f"未知决策融合引擎: {name!r}，可用: {sorted(cls._ENGINES.keys())}"
+            )
+        return engine_cls(config=config)
+
+    @classmethod
+    def available(cls) -> list[str]:
+        return sorted(cls._ENGINES.keys())
+
+
+__all__ = [
+    "DecisionFusionEngine", "FusionEngineFactory",
+    "DEFAULT_AGENT_WEIGHTS",
+]
+