agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

ksadk/deployment/registry.py

@@ -4,115 +4,121 @@
 使用装饰器模式自动注册 Provider，支持动态扩展。
 """
 
-from typing import Dict, Type, List, Optional
+from typing import Dict, List, Optional, Type
+
 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:
+    def get(cls, name: str, config: Optional[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),
-            })
+            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):
         """清空注册表 (主要用于测试)"""

ksadk/deployment/state.py

@@ -4,11 +4,11 @@
 用于管理本地 .agentengine.state 文件，记录已部署的 Agent/MCP 信息。
 """
 
-import yaml
-from pathlib import Path
-from typing import Optional, Dict, Any
 from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
 
+import yaml
 
 STATE_FILE_NAME = ".agentengine.state"
 
@@ -23,9 +23,9 @@ 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:
+        with open(state_file, "r", encoding="utf-8") as f:
             return yaml.safe_load(f) or {}
     except Exception:
         return {}
@@ -34,12 +34,12 @@ def load_state(project_dir: Path) -> Dict[str, Any]:
 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:
+
+    with open(state_file, "w", encoding="utf-8") as f:
         yaml.dump(data, f, default_flow_style=False, allow_unicode=True)
 
 
@@ -51,9 +51,9 @@ def update_state(project_dir: Path, updates: Dict[str, Any]) -> Dict[str, Any]:
     return current_state
 
 
-def clear_state(project_dir: Path, key: str = None) -> bool:
+def clear_state(project_dir: Path, key: Optional[str] = None) -> bool:
     """清理状态文件
-    
+
     Args:
         project_dir: 项目目录
         key: 如果指定，仅当状态中的 ID 与 key 匹配时才删除
@@ -64,7 +64,7 @@ def clear_state(project_dir: Path, key: str = None) -> bool:
     state_file = get_state_file_path(project_dir)
     if not state_file.exists():
         return False
-        
+
     if key:
         # 检查是否匹配
         state = load_state(project_dir)

ksadk/deployment/ui_config.py

@@ -2,13 +2,13 @@
 
 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,
+    UIConfig,
     default_ui_path,
     extract_ui_state,
     infer_ui_profile_from_framework,

ksadk/detection/__init__.py

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

ksadk/detection/detector.py

@@ -4,7 +4,7 @@
 
 import ast
 import json
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import Optional
@@ -20,6 +20,8 @@ class FrameworkType(Enum):
     LANGGRAPH = "langgraph"
     DEEPAGENTS = "deepagents"
     HERMES = "hermes"
+    FASTMCP = "fastmcp"
+    CODEX = "codex"
     UNKNOWN = "unknown"
 
 
@@ -34,6 +36,9 @@ class DetectionResult:
     agent_variable: str = "root_agent"
     runner_class: str = ""
     confidence: float = 0.0
+    # 配置文件的原始内容(ksadk.yaml/agentengine.yaml),供 runner 读 model/prompt 等
+    # 真实生效字段(codex 无 root_agent,配置全靠它)。默认空 dict,不影响既有构造。
+    raw_config: dict = field(default_factory=dict)
 
     @property
     def is_valid(self) -> bool:
@@ -44,6 +49,14 @@ class FrameworkDetector:
     """框架检测器"""
 
     _ENTRY_FILES = ("agent.py", "main.py", "app.py")
+    _LANGCHAIN_MODULES = frozenset(
+        {
+            "langchain",
+            "langchain_openai",
+            "langchain_core",
+            "langchain_community",
+        }
+    )
 
     def __init__(self, project_dir: str):
         self.project_dir = Path(project_dir).resolve()
@@ -56,6 +69,11 @@ class FrameworkDetector:
         if config_result:
             return config_result
 
+        # 1.5 codex.yaml 标志文件(fallback 自动探测,优先级低于 ksadk.yaml framework)
+        codex_result = self._check_codex_yaml()
+        if codex_result:
+            return codex_result
+
         graph_config_result = self._check_langgraph_json()
         if graph_config_result:
             return graph_config_result
@@ -104,12 +122,15 @@ class FrameworkDetector:
                 "langgraph": FrameworkType.LANGGRAPH,
                 "deepagents": FrameworkType.DEEPAGENTS,
                 "hermes": FrameworkType.HERMES,
+                "codex": FrameworkType.CODEX,
             }.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"
             )
+            # codex 无 root_agent 变量(agent 逻辑在 prompt),跳过 entry_exposes_variable 校验
+            is_codex = framework_type == FrameworkType.CODEX
             default_entry_point = (
                 "runtime/app.py"
                 if is_hermes_container and (self.project_dir / "runtime" / "app.py").is_file()
@@ -119,10 +140,13 @@ class FrameworkDetector:
             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():
+            # codex 无 agent.py(逻辑在 prompt),容忍 entry_point 不存在
+            if not is_codex and (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
+            if (
+                not is_codex
+                and not is_hermes_container
+                and not self._entry_exposes_variable(entry_path, agent_variable)
             ):
                 return None
             package = str(config.get("package") or "").strip()
@@ -141,10 +165,30 @@ class FrameworkDetector:
                 agent_variable=agent_variable,
                 runner_class=runner_class,
                 confidence=1.0,
+                raw_config=config,
             )
         except Exception:
             return None
 
+    def _check_codex_yaml(self) -> Optional[DetectionResult]:
+        """fallback:项目根有 codex.yaml 即判 CODEX(最小标志文件,可含 model/sandbox)。
+
+        保守规则,不做源码 import 扫描(避免误判普通 Python 项目)。优先级低于
+        ksadk.yaml framework: codex 显式声明。
+        """
+        codex_path = self.project_dir / "codex.yaml"
+        if not codex_path.exists():
+            return None
+        return DetectionResult(
+            type=FrameworkType.CODEX,
+            name=self.project_dir.name,
+            entry_point="",
+            package_path=str(self.project_dir),
+            agent_variable="",
+            runner_class="",
+            confidence=0.9,
+        )
+
     def _find_package_dir(self) -> Optional[Path]:
         """查找 Python 包目录"""
         # 优先查找与项目同名的包 (下划线版本)
@@ -270,19 +314,16 @@ class FrameworkDetector:
     ) -> FrameworkType:
         try:
             content = entry_path.read_text(encoding="utf-8-sig")
+        except Exception:
+            return fallback
+        try:
             tree = ast.parse(content, filename=str(entry_path))
             imports = self._extract_imports(tree)
+            calls = self._extract_call_names(tree)
+            framework = self._classify(imports, calls, content)
         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
+            framework = self._classify_from_strings(content)
+        return framework if framework != FrameworkType.UNKNOWN else fallback
 
     def _check_langgraph_json(self) -> Optional[DetectionResult]:
         config_path = self.project_dir / "langgraph.json"
@@ -318,71 +359,79 @@ class FrameworkDetector:
 
     def _analyze_code(self, agent_file: Path, package_path: Path) -> DetectionResult:
         """分析代码确定框架类型"""
+        entry_point = str(agent_file.relative_to(self.project_dir))
         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)),
+                entry_point=entry_point,
                 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,
-            )
+        calls: set = set()
+        try:
+            tree = ast.parse(content, filename=str(agent_file))
+            imports = self._extract_imports(tree)
+            calls = self._extract_call_names(tree)
+            framework = self._classify(imports, calls, content)
+        except Exception:
+            # AST 解析失败(语法错误等)时退化为字符串判定，避免直接判 UNKNOWN
+            framework = self._classify_from_strings(content)
 
+        name = package_path.name if framework != FrameworkType.UNKNOWN else self.project_dir.name
         return DetectionResult(
-            type=FrameworkType.UNKNOWN,
-            name=self.project_dir.name,
-            entry_point=str(agent_file.relative_to(self.project_dir)),
+            type=framework,
+            name=name,
+            entry_point=entry_point,
             package_path=str(package_path),
+            agent_variable="root_agent",
+            confidence=self._confidence_for(framework, calls),
         )
 
+    def _classify(self, imports: set, calls: set, content: str) -> FrameworkType:
+        """AST 级统一分类,顺序:
+        ADK → DeepAgents → LangChain(高层) → LangGraph → LangChain(legacy) → UNKNOWN"""
+        if self._is_adk(imports, content):
+            return FrameworkType.ADK
+        if self._is_deepagents(imports, calls, content):
+            return FrameworkType.DEEPAGENTS
+        if self._is_langchain_high_level(imports, calls):
+            return FrameworkType.LANGCHAIN
+        if self._is_langgraph(calls):
+            return FrameworkType.LANGGRAPH
+        if self._is_langchain_legacy(imports, calls):
+            return FrameworkType.LANGCHAIN
+        return FrameworkType.UNKNOWN
+
+    def _classify_from_strings(self, content: str) -> FrameworkType:
+        """AST 解析失败时的字符串兜底，顺序与 _classify 保持一致"""
+        if "google.adk" in content or "from google.adk" in content:
+            return FrameworkType.ADK
+        if "deepagents" in content or "create_deep_agent(" in content:
+            return FrameworkType.DEEPAGENTS
+        if "create_agent(" in content:
+            return FrameworkType.LANGCHAIN
+        if (
+            "StateGraph" in content
+            or "langgraph.graph" in content
+            or "create_react_agent(" in content
+        ):
+            return FrameworkType.LANGGRAPH
+        if any(m in content for m in self._LANGCHAIN_MODULES):
+            return FrameworkType.LANGCHAIN
+        return FrameworkType.UNKNOWN
+
+    def _confidence_for(self, framework: FrameworkType, calls: set) -> float:
+        if framework == FrameworkType.UNKNOWN:
+            return 0.0
+        if framework == FrameworkType.LANGCHAIN:
+            # 高层(create_agent 调用) 0.9，legacy 兜底 0.8
+            return 0.9 if "create_agent" in calls else 0.8
+        return 0.9
+
     def _extract_imports(self, tree: ast.AST) -> set:
         """提取导入的模块"""
         imports = set()
@@ -395,6 +444,19 @@ class FrameworkDetector:
                     imports.add(node.module.split(".")[0])
         return imports
 
+    def _extract_call_names(self, tree: ast.AST) -> set:
+        """提取代码中实际调用的函数/方法名（AST 级，避免注释/字符串误判）"""
+        calls = set()
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            func = node.func
+            if isinstance(func, ast.Name):
+                calls.add(func.id)
+            elif isinstance(func, ast.Attribute):
+                calls.add(func.attr)
+        return calls
+
     def _is_adk(self, imports: set, content: str) -> bool:
         """检测是否为 ADK 项目"""
         # 检查 google.adk 导入
@@ -402,30 +464,31 @@ class FrameworkDetector:
             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_langgraph(self, calls: set) -> bool:
+        """检测是否为 LangGraph 项目:直接编排 StateGraph 或调用 create_react_agent。
+        不再用 `"StateGraph" in content` 字符串包含,避免注释/类型注解误命中
+        导致 deepagents/langchain 塌缩。"""
+        return "StateGraph" in calls or "create_react_agent" in calls
 
-    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_langchain_high_level(self, imports: set, calls: set) -> bool:
+        """新版 LangChain 高层 API：langchain 系 import 且调用 create_agent。"""
+        if not (self._LANGCHAIN_MODULES & imports):
+            return False
+        return "create_agent" in calls
+
+    def _is_langchain_legacy(self, imports: set, calls: set) -> bool:
+        """LangChain legacy 兜底:langchain 系 import 且无 LangGraph 直接编排
+        信号(覆盖 LCEL 链等旧用法)。"""
+        if not (self._LANGCHAIN_MODULES & imports):
+            return False
+        return "StateGraph" not in calls and "create_react_agent" not in calls
 
-    def _is_deepagents(self, imports: set, content: str) -> bool:
+    def _is_deepagents(self, imports: set, calls: set, content: str) -> bool:
         """检测是否为 DeepAgents 项目"""
         if "deepagents" in imports:
             return True
+        if "create_deep_agent" in calls:
+            return True
         if "from deepagents import" in content or "create_deep_agent(" in content:
             return True
         return False

ksadk/detection/mcp_detector.py

@@ -3,12 +3,14 @@ MCP 检测器 - 自动检测 FastMCP 项目
 """
 
 import ast
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import List, Optional
 
 import yaml
 
+from ksadk.detection.detector import FrameworkType
+
 
 @dataclass
 class MCPDetectionResult:
@@ -19,17 +21,18 @@ class MCPDetectionResult:
     entry_point: str
     package_path: str
     mcp_variable: str = "mcp"
-    tools: List[str] = None  # 检测到的工具名称
+    tools: List[str] = field(default_factory=list)  # 检测到的工具名称
     confidence: float = 0.0
 
-    def __post_init__(self):
-        if self.tools is None:
-            self.tools = []
-
     @property
     def is_valid(self) -> bool:
         return self.is_mcp
 
+    @property
+    def type(self) -> FrameworkType:
+        """Expose the framework contract expected by shared builders."""
+        return FrameworkType.FASTMCP
+
 
 class MCPDetector:
     """MCP 检测器 - 检测 FastMCP 项目"""