agentengine-sdk-python 0.6.2__py3-none-any.whl → 0.6.9__py3-none-any.whl

ksadk/deployment/registry.py

@@ -0,0 +1,120 @@
+"""
+部署 Provider 注册表
+
+使用装饰器模式自动注册 Provider，支持动态扩展。
+"""
+
+from typing import Dict, Type, List, Optional
+from ksadk.deployment.base import BaseDeployProvider
+
+
+class DeployProviderRegistry:
+    """Provider 注册表
+    
+    使用方式:
+        @DeployProviderRegistry.register("my-provider")
+        class MyProvider(BaseDeployProvider):
+            ...
+    """
+    
+    _providers: Dict[str, Type[BaseDeployProvider]] = {}
+    _instances: Dict[str, BaseDeployProvider] = {}
+    
+    @classmethod
+    def register(cls, name: str):
+        """装饰器: 注册 Provider
+        
+        Args:
+            name: Provider 名称 (如 "serverless", "k8s", "docker")
+        """
+        def decorator(provider_class: Type[BaseDeployProvider]):
+            if not issubclass(provider_class, BaseDeployProvider):
+                raise TypeError(f"{provider_class} must inherit from BaseDeployProvider")
+            
+            provider_class.name = name
+            cls._providers[name] = provider_class
+            return provider_class
+        
+        return decorator
+    
+    @classmethod
+    def get(cls, name: str, config: Dict = None) -> BaseDeployProvider:
+        """获取 Provider 实例
+        
+        Args:
+            name: Provider 名称
+            config: Provider 配置
+            
+        Returns:
+            Provider 实例
+        """
+        if name not in cls._providers:
+            available = ", ".join(cls._providers.keys())
+            raise ValueError(f"Unknown provider: {name}. Available: {available}")
+        
+        # 缓存实例 (相同 name 返回相同实例)
+        cache_key = f"{name}:{hash(str(config))}"
+        if cache_key not in cls._instances:
+            cls._instances[cache_key] = cls._providers[name](config)
+        
+        return cls._instances[cache_key]
+    
+    @classmethod
+    def get_class(cls, name: str) -> Type[BaseDeployProvider]:
+        """获取 Provider 类 (不实例化)
+        
+        Args:
+            name: Provider 名称
+            
+        Returns:
+            Provider 类
+        """
+        if name not in cls._providers:
+            raise ValueError(f"Unknown provider: {name}")
+        return cls._providers[name]
+    
+    @classmethod
+    def list_providers(cls) -> List[str]:
+        """列出所有已注册的 Provider 名称
+        
+        Returns:
+            Provider 名称列表
+        """
+        return list(cls._providers.keys())
+    
+    @classmethod
+    def get_provider_info(cls) -> List[Dict]:
+        """获取所有 Provider 的详细信息
+        
+        Returns:
+            Provider 信息列表
+        """
+        result = []
+        for name, provider_class in cls._providers.items():
+            result.append({
+                "name": name,
+                "display_name": getattr(provider_class, "display_name", name),
+                "description": getattr(provider_class, "description", ""),
+                "supports_streaming": getattr(provider_class, "supports_streaming", False),
+                "supports_scaling": getattr(provider_class, "supports_scaling", False),
+                "requires_image_registry": getattr(provider_class, "requires_image_registry", False),
+            })
+        return result
+    
+    @classmethod
+    def has_provider(cls, name: str) -> bool:
+        """检查 Provider 是否存在
+        
+        Args:
+            name: Provider 名称
+            
+        Returns:
+            是否存在
+        """
+        return name in cls._providers
+    
+    @classmethod
+    def clear(cls):
+        """清空注册表 (主要用于测试)"""
+        cls._providers.clear()
+        cls._instances.clear()

ksadk/deployment/state.py

@@ -0,0 +1,78 @@
+"""
+部署状态管理
+
+用于管理本地 .agentengine.state 文件，记录已部署的 Agent/MCP 信息。
+"""
+
+import yaml
+from pathlib import Path
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+
+STATE_FILE_NAME = ".agentengine.state"
+
+
+def get_state_file_path(project_dir: Path) -> Path:
+    """获取状态文件路径"""
+    return project_dir / STATE_FILE_NAME
+
+
+def load_state(project_dir: Path) -> Dict[str, Any]:
+    """加载状态文件"""
+    state_file = get_state_file_path(project_dir)
+    if not state_file.exists():
+        return {}
+        
+    try:
+        with open(state_file, 'r', encoding='utf-8') as f:
+            return yaml.safe_load(f) or {}
+    except Exception:
+        return {}
+
+
+def save_state(project_dir: Path, data: Dict[str, Any]) -> None:
+    """保存状态文件"""
+    state_file = get_state_file_path(project_dir)
+    
+    # 自动添加 updated_at
+    if "updated_at" not in data:
+        data["updated_at"] = datetime.now().isoformat()
+        
+    with open(state_file, 'w', encoding='utf-8') as f:
+        yaml.dump(data, f, default_flow_style=False, allow_unicode=True)
+
+
+def update_state(project_dir: Path, updates: Dict[str, Any]) -> Dict[str, Any]:
+    """更新状态文件 (增量更新)"""
+    current_state = load_state(project_dir)
+    current_state.update(updates)
+    save_state(project_dir, current_state)
+    return current_state
+
+
+def clear_state(project_dir: Path, key: str = None) -> bool:
+    """清理状态文件
+    
+    Args:
+        project_dir: 项目目录
+        key: 如果指定，仅当状态中的 ID 与 key 匹配时才删除
+
+    Returns:
+        bool: 是否实际删除了状态文件
+    """
+    state_file = get_state_file_path(project_dir)
+    if not state_file.exists():
+        return False
+        
+    if key:
+        # 检查是否匹配
+        state = load_state(project_dir)
+        # 检查 agent_id 或 mcp_id
+        if state.get("agent_id") == key or state.get("mcp_id") == key:
+            state_file.unlink()
+            return True
+        return False
+    else:
+        state_file.unlink()
+        return True

ksadk/deployment/ui_config.py

@@ -0,0 +1,21 @@
+"""Backward-compatible import path for UI configuration helpers."""
+
+from ksadk.ui_config import (  # noqa: F401
+    SUPPORTED_UI_PROFILES,
+    UIConfig,
+    UI_PROFILE_ADK,
+    UI_PROFILE_AUTO,
+    UI_PROFILE_CUSTOM,
+    UI_PROFILE_HERMES,
+    UI_PROFILE_LANGCHAIN,
+    UI_PROFILE_OPENCLAW,
+    default_ui_path,
+    extract_ui_state,
+    infer_ui_profile_from_framework,
+    is_same_origin,
+    normalize_ui_path,
+    normalize_ui_profile,
+    normalize_ui_url,
+    resolve_ui_config,
+    ui_config_to_state_fields,
+)

ksadk/detection/__init__.py

@@ -0,0 +1,7 @@
+"""
+KsADK Detection - 框架自动检测模块
+"""
+
+from ksadk.detection.detector import FrameworkDetector, DetectionResult, FrameworkType
+
+__all__ = ["FrameworkDetector", "DetectionResult", "FrameworkType"]

ksadk/detection/detector.py

@@ -0,0 +1,431 @@
+"""
+框架检测器 - 自动检测 LangChain / LangGraph / DeepAgents / ADK 项目
+"""
+
+import ast
+import json
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+class FrameworkType(Enum):
+    """支持的框架类型"""
+
+    ADK = "adk"
+    LANGCHAIN = "langchain"
+    LANGGRAPH = "langgraph"
+    DEEPAGENTS = "deepagents"
+    HERMES = "hermes"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class DetectionResult:
+    """检测结果"""
+
+    type: FrameworkType
+    name: str
+    entry_point: str
+    package_path: str
+    agent_variable: str = "root_agent"
+    runner_class: str = ""
+    confidence: float = 0.0
+
+    @property
+    def is_valid(self) -> bool:
+        return self.type != FrameworkType.UNKNOWN
+
+
+class FrameworkDetector:
+    """框架检测器"""
+
+    _ENTRY_FILES = ("agent.py", "main.py", "app.py")
+
+    def __init__(self, project_dir: str):
+        self.project_dir = Path(project_dir).resolve()
+
+    def detect(self) -> DetectionResult:
+        """检测项目使用的框架类型"""
+
+        # 1. 检查 ksadk.yaml 配置文件 (显式声明)
+        config_result = self._check_config()
+        if config_result:
+            return config_result
+
+        graph_config_result = self._check_langgraph_json()
+        if graph_config_result:
+            return graph_config_result
+
+        # 2. 查找 Python 包目录
+        package_path = self._find_package_dir()
+        if not package_path:
+            return DetectionResult(
+                type=FrameworkType.UNKNOWN, name="Unknown", entry_point="", package_path=""
+            )
+
+        # 3. 查找 agent.py 或 __init__.py
+        agent_file = self._find_agent_file(package_path)
+        if not agent_file:
+            return DetectionResult(
+                type=FrameworkType.UNKNOWN,
+                name="Unknown",
+                entry_point="",
+                package_path=str(package_path),
+            )
+
+        # 4. 分析代码确定框架类型
+        return self._analyze_code(agent_file, package_path)
+
+    def _check_config(self) -> Optional[DetectionResult]:
+        """检查配置文件 (agentengine.yaml 或 ksadk.yaml)"""
+        # 优先检查 agentengine.yaml
+        config_path = self.project_dir / "agentengine.yaml"
+        if not config_path.exists():
+            config_path = self.project_dir / "ksadk.yaml"
+        if not config_path.exists():
+            config_path = self.project_dir / "ksadk.yml"
+
+        if not config_path.exists():
+            return None
+
+        try:
+            # 使用 utf-8-sig 自动处理 BOM，确保 Windows 兼容性
+            with open(config_path, "r", encoding="utf-8-sig") as f:
+                config = yaml.safe_load(f)
+
+            framework = config.get("framework", "adk").lower()
+            framework_type = {
+                "adk": FrameworkType.ADK,
+                "langchain": FrameworkType.LANGCHAIN,
+                "langgraph": FrameworkType.LANGGRAPH,
+                "deepagents": FrameworkType.DEEPAGENTS,
+                "hermes": FrameworkType.HERMES,
+            }.get(framework, FrameworkType.UNKNOWN)
+
+            artifact_type = str(config.get("artifact_type") or "").strip().lower()
+            is_hermes_container = (
+                framework_type == FrameworkType.HERMES and artifact_type == "container"
+            )
+            default_entry_point = (
+                "runtime/app.py"
+                if is_hermes_container and (self.project_dir / "runtime" / "app.py").is_file()
+                else "agent.py"
+            )
+            entry_point = config.get("entry_point", default_entry_point)
+            agent_variable = config.get("agent_variable", "root_agent")
+            runner_class = str(config.get("runner_class") or "").strip()
+            entry_path = self.project_dir / str(entry_point).replace("\\", "/")
+            if not entry_path.exists() or not entry_path.is_file():
+                return None
+            if not is_hermes_container and not self._entry_exposes_variable(
+                entry_path, agent_variable
+            ):
+                return None
+            package = str(config.get("package") or "").strip()
+            if package:
+                package_path = self.project_dir / package
+            elif is_hermes_container:
+                package_path = entry_path.parent
+            else:
+                package_path = self.project_dir / self.project_dir.name.replace("-", "_")
+
+            return DetectionResult(
+                type=framework_type,
+                name=config.get("name", self.project_dir.name),
+                entry_point=entry_point,
+                package_path=str(package_path),
+                agent_variable=agent_variable,
+                runner_class=runner_class,
+                confidence=1.0,
+            )
+        except Exception:
+            return None
+
+    def _find_package_dir(self) -> Optional[Path]:
+        """查找 Python 包目录"""
+        # 优先查找与项目同名的包 (下划线版本)
+        expected_name = self.project_dir.name.replace("-", "_")
+        expected_path = self.project_dir / expected_name
+        if expected_path.exists() and expected_path.is_dir():
+            if (expected_path / "__init__.py").exists() or any(
+                (expected_path / entry_file).exists() for entry_file in self._ENTRY_FILES
+            ):
+                return expected_path
+
+        # 查找任何包含 __init__.py 的子目录
+        for item in self.project_dir.iterdir():
+            if (
+                item.is_dir()
+                and not item.name.startswith(".")
+                and item.name not in ("tests", "test", "__pycache__")
+                and (
+                    (item / "__init__.py").exists()
+                    or any((item / entry_file).exists() for entry_file in self._ENTRY_FILES)
+                )
+            ):
+                return item
+
+        # 当前目录本身也可能是一个包
+        if (self.project_dir / "__init__.py").exists():
+            return self.project_dir
+
+        # 兼容脚本式项目: 当前目录直接包含 agent.py/main.py/app.py
+        if any((self.project_dir / entry_file).exists() for entry_file in self._ENTRY_FILES):
+            return self.project_dir
+
+        src_dir = self.project_dir / "src"
+        if src_dir.is_dir():
+            expected_src_path = src_dir / expected_name
+            if expected_src_path.exists() and expected_src_path.is_dir():
+                if (expected_src_path / "__init__.py").exists() or any(
+                    (expected_src_path / entry_file).exists() for entry_file in self._ENTRY_FILES
+                ):
+                    return expected_src_path
+
+            for item in src_dir.iterdir():
+                if (
+                    item.is_dir()
+                    and not item.name.startswith(".")
+                    and item.name not in ("tests", "test", "__pycache__")
+                    and (
+                        (item / "__init__.py").exists()
+                        or any((item / entry_file).exists() for entry_file in self._ENTRY_FILES)
+                    )
+                ):
+                    return item
+
+        return None
+
+    def _find_agent_file(self, package_path: Path) -> Optional[Path]:
+        """查找 agent.py 文件"""
+        # 优先查找常见入口文件
+        for entry_file in self._ENTRY_FILES:
+            entry_path = package_path / entry_file
+            if entry_path.exists():
+                return entry_path
+
+        # 检查 __init__.py 是否导出 root_agent
+        init_py = package_path / "__init__.py"
+        if init_py.exists():
+            try:
+                content = init_py.read_text(encoding="utf-8-sig")
+                if "root_agent" in content or "graph" in content or "app" in content:
+                    return init_py
+            except Exception:
+                pass
+
+        return None
+
+    @staticmethod
+    def _detect_agent_variable(content: str) -> str | None:
+        import re
+
+        patterns = [
+            (r"^\s*(root_agent)\s*=", "root_agent"),
+            (r"^\s*(root_agent)\s*:\s*[^=]+\s*=", "root_agent"),
+            (r"^\s*(\w+)\s*=\s*\w*graph\w*\.compile\(", None),
+            (r"^\s*(\w+)\s*=\s*StateGraph", None),
+            (r"^\s*(\w+)\s*=\s*Agent\(", None),
+            (r"^\s*(\w+)\s*=\s*create_react_agent\(", None),
+            (r"^\s*(\w+)\s*=\s*create_deep_agent\(", None),
+            (r"^\s*(\w+)\s*=\s*create_agent\(", None),
+        ]
+        for pattern, fixed_name in patterns:
+            match = re.search(pattern, content, re.MULTILINE | re.IGNORECASE)
+            if match:
+                return fixed_name if fixed_name else match.group(1)
+        return None
+
+    @classmethod
+    def _has_agent_variable(cls, content: str, agent_var: str) -> bool:
+        import re
+
+        if not agent_var:
+            return False
+        escaped = re.escape(agent_var)
+        patterns = [
+            rf"^\s*{escaped}\s*=",
+            rf"^\s*{escaped}\s*:\s*[^=]+=",
+            rf"^\s*from\s+[\.\w]+\s+import\s+.*\b{escaped}\b",
+            rf"^\s*import\s+[\.\w]+\s+as\s+{escaped}\b",
+        ]
+        return (
+            any(re.search(pattern, content, re.MULTILINE) for pattern in patterns)
+            or cls._detect_agent_variable(content) == agent_var
+        )
+
+    def _entry_exposes_variable(self, entry_path: Path, agent_var: str) -> bool:
+        try:
+            content = entry_path.read_text(encoding="utf-8-sig")
+        except Exception:
+            return False
+        return self._has_agent_variable(content, agent_var)
+
+    def _framework_from_entry(
+        self, entry_path: Path, fallback: FrameworkType = FrameworkType.UNKNOWN
+    ) -> FrameworkType:
+        try:
+            content = entry_path.read_text(encoding="utf-8-sig")
+            tree = ast.parse(content, filename=str(entry_path))
+            imports = self._extract_imports(tree)
+        except Exception:
+            return fallback
+        if self._is_deepagents(imports, content):
+            return FrameworkType.DEEPAGENTS
+        if self._is_langgraph(imports, content):
+            return FrameworkType.LANGGRAPH
+        if self._is_adk(imports, content):
+            return FrameworkType.ADK
+        if self._is_langchain(imports, content):
+            return FrameworkType.LANGCHAIN
+        return fallback
+
+    def _check_langgraph_json(self) -> Optional[DetectionResult]:
+        config_path = self.project_dir / "langgraph.json"
+        if not config_path.exists():
+            return None
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8-sig"))
+        except Exception:
+            return None
+        graphs = config.get("graphs")
+        if not isinstance(graphs, dict):
+            return None
+        for target in graphs.values():
+            if not isinstance(target, str) or ":" not in target:
+                continue
+            path_part, agent_var = target.rsplit(":", 1)
+            path_part = path_part.strip().removeprefix("./")
+            agent_var = agent_var.strip() or "root_agent"
+            entry_path = self.project_dir / Path(path_part.replace("\\", "/"))
+            if not entry_path.exists() or not entry_path.is_file():
+                continue
+            if not self._entry_exposes_variable(entry_path, agent_var):
+                continue
+            return DetectionResult(
+                type=self._framework_from_entry(entry_path, FrameworkType.LANGGRAPH),
+                name=self.project_dir.name,
+                entry_point=str(entry_path.relative_to(self.project_dir)),
+                package_path=str(entry_path.parent),
+                agent_variable=agent_var,
+                confidence=0.95,
+            )
+        return None
+
+    def _analyze_code(self, agent_file: Path, package_path: Path) -> DetectionResult:
+        """分析代码确定框架类型"""
+        try:
+            # 使用 utf-8-sig 自动处理 BOM，兼容 Windows/编辑器带 BOM 的脚本
+            content = agent_file.read_text(encoding="utf-8-sig")
+            tree = ast.parse(content, filename=str(agent_file))
+        except Exception:
+            return DetectionResult(
+                type=FrameworkType.UNKNOWN,
+                name=self.project_dir.name,
+                entry_point=str(agent_file.relative_to(self.project_dir)),
+                package_path=str(package_path),
+            )
+
+        imports = self._extract_imports(tree)
+
+        # 检测 ADK
+        if self._is_adk(imports, content):
+            return DetectionResult(
+                type=FrameworkType.ADK,
+                name=package_path.name,
+                entry_point=str(agent_file.relative_to(self.project_dir)),
+                package_path=str(package_path),
+                agent_variable="root_agent",
+                confidence=0.9,
+            )
+
+        # 检测 DeepAgents (LangChain 生态, 底层基于 LangGraph)
+        if self._is_deepagents(imports, content):
+            return DetectionResult(
+                type=FrameworkType.DEEPAGENTS,
+                name=package_path.name,
+                entry_point=str(agent_file.relative_to(self.project_dir)),
+                package_path=str(package_path),
+                agent_variable="root_agent",
+                confidence=0.9,
+            )
+
+        # 检测 LangGraph
+        if self._is_langgraph(imports, content):
+            return DetectionResult(
+                type=FrameworkType.LANGGRAPH,
+                name=package_path.name,
+                entry_point=str(agent_file.relative_to(self.project_dir)),
+                package_path=str(package_path),
+                agent_variable="root_agent",
+                confidence=0.9,
+            )
+
+        # 检测 LangChain
+        if self._is_langchain(imports, content):
+            return DetectionResult(
+                type=FrameworkType.LANGCHAIN,
+                name=package_path.name,
+                entry_point=str(agent_file.relative_to(self.project_dir)),
+                package_path=str(package_path),
+                agent_variable="root_agent",
+                confidence=0.8,
+            )
+
+        return DetectionResult(
+            type=FrameworkType.UNKNOWN,
+            name=self.project_dir.name,
+            entry_point=str(agent_file.relative_to(self.project_dir)),
+            package_path=str(package_path),
+        )
+
+    def _extract_imports(self, tree: ast.AST) -> set:
+        """提取导入的模块"""
+        imports = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.add(alias.name.split(".")[0])
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    imports.add(node.module.split(".")[0])
+        return imports
+
+    def _is_adk(self, imports: set, content: str) -> bool:
+        """检测是否为 ADK 项目"""
+        # 检查 google.adk 导入
+        if "google" in imports and ("google.adk" in content or "from google.adk" in content):
+            return True
+        return False
+
+    def _is_langgraph(self, imports: set, content: str) -> bool:
+        """检测是否为 LangGraph 项目"""
+        if "langgraph" in imports:
+            return True
+        if "StateGraph" in content or "langgraph.graph" in content:
+            return True
+        return False
+
+    def _is_langchain(self, imports: set, content: str) -> bool:
+        """检测是否为 LangChain 项目"""
+        langchain_modules = {
+            "langchain",
+            "langchain_openai",
+            "langchain_core",
+            "langchain_community",
+        }
+        if langchain_modules & imports:
+            return True
+        return False
+
+    def _is_deepagents(self, imports: set, content: str) -> bool:
+        """检测是否为 DeepAgents 项目"""
+        if "deepagents" in imports:
+            return True
+        if "from deepagents import" in content or "create_deep_agent(" in content:
+            return True
+        return False