sycommon-python-lib 0.2.0b32__tar.gz → 0.2.1a0__tar.gz

{sycommon_python_lib-0.2.0b32 → sycommon_python_lib-0.2.1a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.0b32
+Version: 0.2.1a0
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.0b32 → sycommon_python_lib-0.2.1a0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.0b32"
+version = "0.2.1a0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.0b32 → sycommon_python_lib-0.2.1a0}/src/sycommon/agent/__init__.py

@@ -6,6 +6,15 @@ sycommon.agent - DeepAgents 便捷封装
 
 from sycommon.agent.exports import *
 
+# 沙箱模块
+from sycommon.agent.sandbox import (
+    HTTPSandboxBackend,
+    SandboxPool,
+    SandboxInstance,
+    areset_all_sandboxes,
+    aget_sandbox_status,
+)
+
 __all__ = [
     # 主要接口
     "get_agent",
@@ -35,4 +44,10 @@ __all__ = [
     # 技能系统中间件
     "SkillsMiddleware",
     "SkillMetadata",
+    # 沙箱模块
+    "HTTPSandboxBackend",
+    "SandboxPool",
+    "SandboxInstance",
+    "areset_all_sandboxes",
+    "aget_sandbox_status",
 ]

sycommon_python_lib-0.2.1a0/src/sycommon/agent/sandbox/__init__.py

@@ -0,0 +1,91 @@
+"""
+沙箱模块
+
+提供远程沙箱容器的连接和管理能力，支持通过 Nacos 服务发现。
+
+架构说明:
+┌─────────────────────────────────────────────────────────────┐
+│                      调用服务                                │
+│                                                             │
+│  HTTPSandboxBackend.from_nacos("sandbox-service")          │
+│                           │                                 │
+│                           ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Nacos                             │   │
+│  │  负责服务发现 + 负载均衡                              │   │
+│  │                                                     │   │
+│  │  sandbox-service:                                   │   │
+│  │    - 192.168.1.100:8080 (实例1)                     │   │
+│  │    - 192.168.1.101:8080 (实例2)                     │   │
+│  │    - 192.168.1.102:8080 (实例3)                     │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                           │                                 │
+│              Nacos 轮询返回一个实例                          │
+│                           ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              沙箱容器 (多副本)                        │   │
+│  │                                                     │   │
+│  │  每个容器运行 sandbox_server.py                     │   │
+│  │  提供命令执行、文件操作 API                          │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+
+使用示例:
+
+    # 方式 1: 获取单个沙箱（推荐，Nacos 负责负载均衡）
+    from sycommon.agent.sandbox import HTTPSandboxBackend
+
+    sandbox = HTTPSandboxBackend.from_nacos("sandbox-service", user_id="user123")
+    result = await sandbox.aexecute("python --version")
+
+    # 方式 2: 普通用户重置自己的工作目录
+    await sandbox.areset()  # 仅重置 /workspace/user123/
+
+    # 方式 3: 管理员批量管理所有沙箱
+    from sycommon.agent.sandbox import SandboxPool
+
+    pool = await SandboxPool.from_nacos("sandbox-service", is_admin=True)
+    print(await pool.astatus())  # 查看所有实例状态
+    await pool.areset_all()  # 重置所有沙箱（需要管理员权限）
+
+    # 方式 4: 配合 Agent 使用
+    from deepagents import create_deep_agent
+    from sycommon.agent.sandbox import HTTPSandboxBackend
+
+    sandbox = HTTPSandboxBackend.from_nacos("sandbox-service", user_id="user123")
+    agent = create_deep_agent(
+        model="openai:gpt-4o",
+        backend=sandbox,
+    )
+
+    # 方式 5: 启用沙箱服务（在其他项目中）
+    from fastapi import FastAPI
+    from sycommon.services import Services
+
+    app = Services.plugins(
+        app=FastAPI(),
+        sandbox_service=True,  # 启用沙箱服务
+        ...
+    )
+"""
+
+from sycommon.agent.sandbox.http_sandbox_backend import HTTPSandboxBackend
+from sycommon.agent.sandbox.sandbox_pool import (
+    SandboxPool,
+    SandboxInstance,
+    areset_all_sandboxes,
+    aget_sandbox_status,
+)
+
+__all__ = [
+    # 后端
+    "HTTPSandboxBackend",
+
+    # 池管理
+    "SandboxPool",
+    "SandboxInstance",
+
+    # 便捷函数
+    "areset_all_sandboxes",
+    "aget_sandbox_status",
+]

sycommon_python_lib-0.2.1a0/src/sycommon/agent/sandbox/file_ops.py

@@ -0,0 +1,132 @@
+"""
+沙箱文件操作 Mixin
+
+提供文件相关的异步操作方法
+"""
+
+import base64
+from typing import List, TYPE_CHECKING
+
+from sycommon.logging.kafka_log import SYLogger
+from deepagents.backends.protocol import (
+    FileInfo,
+    GrepMatch,
+    WriteResult,
+    EditResult,
+)
+
+if TYPE_CHECKING:
+    from sycommon.agent.sandbox.http_sandbox_backend import HTTPSandboxBackend
+
+# 沙箱 API 路径前缀
+SANDBOX_API_PREFIX = "/v1/sandbox"
+
+
+class FileOperationsMixin:
+    """文件操作 Mixin（仅异步）"""
+
+    _timeout: int  # 类型提示，子类需要提供此属性
+    user_id: str  # 类型提示，子类需要提供此属性
+
+    async def _post_async(self: "HTTPSandboxBackend", endpoint: str, data: dict, timeout: int = None) -> dict:
+        """发送异步 POST 请求"""
+        ...
+
+    # ============== 目录操作 ==============
+
+    async def als_info(self: "HTTPSandboxBackend", path: str) -> List[FileInfo]:
+        """异步列出目录内容"""
+        SYLogger.info(f"[Sandbox] 列出目录: {path}")
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/ls", {
+            "path": path,
+            "user_id": self.user_id
+        })
+        items = [FileInfo(**item) for item in result]
+        SYLogger.info(f"[Sandbox] 目录内容: {len(items)} 项")
+        return items
+
+    # ============== 文件读写 ==============
+
+    async def aread(self: "HTTPSandboxBackend", file_path: str, offset: int = 0, limit: int = 2000) -> str:
+        """异步读取文件内容"""
+        SYLogger.info(f"[Sandbox] 读取文件: {file_path} (offset={offset}, limit={limit})")
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/read", {
+            "file_path": file_path,
+            "user_id": self.user_id,
+            "offset": offset,
+            "limit": limit
+        })
+        if result.get("error"):
+            SYLogger.error(f"[Sandbox] 读取文件失败: {result['error']}")
+            return f"Error: {result['error']}"
+        content = result.get("content", "")
+        SYLogger.info(f"[Sandbox] 读取完成: {len(content)} 字符")
+        return content
+
+    async def awrite(self: "HTTPSandboxBackend", file_path: str, content: str) -> WriteResult:
+        """异步写入文件"""
+        SYLogger.info(f"[Sandbox] 写入文件: {file_path} ({len(content)} 字符)")
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/write", {
+            "file_path": file_path,
+            "content": base64.b64encode(content.encode()).decode(),
+            "user_id": self.user_id
+        })
+        write_result = WriteResult(
+            error=result.get("error"),
+            path=result.get("path")
+        )
+        if write_result.error:
+            SYLogger.error(f"[Sandbox] 写入失败: {write_result.error}")
+        else:
+            SYLogger.info(f"[Sandbox] 写入成功: {write_result.path}")
+        return write_result
+
+    async def aedit(
+        self: "HTTPSandboxBackend",
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False
+    ) -> EditResult:
+        """异步编辑文件"""
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/edit", {
+            "file_path": file_path,
+            "old_string": base64.b64encode(old_string.encode()).decode(),
+            "new_string": base64.b64encode(new_string.encode()).decode(),
+            "user_id": self.user_id,
+            "replace_all": replace_all
+        })
+        return EditResult(
+            error=result.get("error"),
+            path=result.get("path"),
+            occurrences=result.get("occurrences")
+        )
+
+    # ============== 搜索 ==============
+
+    async def aglob_info(self: "HTTPSandboxBackend", pattern: str, path: str = "/") -> List[FileInfo]:
+        """异步 glob 搜索文件"""
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/glob", {
+            "pattern": pattern,
+            "path": path,
+            "user_id": self.user_id
+        })
+        return [FileInfo(**item) for item in result]
+
+    async def agrep_raw(
+        self: "HTTPSandboxBackend",
+        pattern: str,
+        path: str = None,
+        glob: str = None
+    ) -> List[GrepMatch] | str:
+        """异步搜索文件内容"""
+        try:
+            result = await self._post_async(f"{SANDBOX_API_PREFIX}/grep", {
+                "pattern": pattern,
+                "user_id": self.user_id,
+                "path": path,
+                "glob": glob
+            })
+            return [GrepMatch(**item) for item in result]
+        except Exception as e:
+            return f"Error: {e}"

sycommon_python_lib-0.2.1a0/src/sycommon/agent/sandbox/http_sandbox_backend.py

@@ -0,0 +1,215 @@
+"""
+HTTP 客户端沙箱后端
+
+通过 HTTP API 连接远程沙箱容器，支持 Nacos 服务发现
+仅提供异步方法，使用 aiohttp 实现
+"""
+
+import base64
+from typing import Optional, List
+
+from sycommon.logging.kafka_log import SYLogger
+from sycommon.agent.sandbox.session import get_async_session
+from sycommon.agent.sandbox.file_ops import FileOperationsMixin, SANDBOX_API_PREFIX
+
+from deepagents.backends.protocol import (
+    BackendProtocol,
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileUploadResponse,
+)
+
+
+class HTTPSandboxBackend(FileOperationsMixin, BackendProtocol):
+    """
+    通过 HTTP API 连接远程沙箱容器（仅异步）
+
+    支持两种模式:
+    1. 直接 URL: 直接指定沙箱服务地址
+    2. Nacos 服务发现: 通过服务名从 Nacos 获取实例
+
+    使用示例:
+        # 直接 URL 模式
+        backend = HTTPSandboxBackend(
+            base_url="http://192.168.1.100:8080",
+            user_id="user123"
+        )
+
+        # Nacos 服务发现模式
+        backend = HTTPSandboxBackend.from_nacos(
+            service_name="sandbox-service",
+            user_id="user123"
+        )
+
+        # 异步调用
+        result = await backend.aexecute("python --version")
+    """
+
+    def __init__(self, base_url: str, user_id: str, timeout: int = 120):
+        """
+        初始化 HTTP 沙箱后端
+
+        Args:
+            base_url: 沙箱服务地址，如 http://192.168.1.100:8080
+            user_id: 用户ID，用于隔离工作目录
+            timeout: 默认超时时间（秒）
+        """
+        self._base_url = base_url.rstrip("/")
+        self._user_id = user_id
+        self._timeout = timeout
+
+        # 生成 ID
+        self._id = self._base_url.replace(
+            "http://", ""
+        ).replace(
+            "https://", ""
+        ).replace(
+            ":", "-"
+        ).replace(
+            "/", "-"
+        )
+
+    @classmethod
+    def from_nacos(
+        cls,
+        service_name: str,
+        user_id: str,
+        group: str = "DEFAULT_GROUP",
+        version: str = None,
+        timeout: int = 120,
+    ) -> "HTTPSandboxBackend":
+        """
+        从 Nacos 服务发现创建后端实例
+
+        Args:
+            service_name: Nacos 服务名
+            user_id: 用户ID，用于隔离工作目录
+            group: 服务分组
+            version: 服务版本
+            timeout: 超时时间
+
+        Returns:
+            HTTPSandboxBackend 实例
+
+        Raises:
+            RuntimeError: 无法发现服务实例
+        """
+        from sycommon.synacos.nacos_service import NacosService
+
+        nacos_manager = NacosService(None)
+        instances = nacos_manager.get_service_instances(
+            service_name, group=group, target_version=version
+        )
+
+        if not instances:
+            raise RuntimeError(f"服务 [{service_name}] 无可用实例")
+
+        instance = instances[0]
+        base_url = f"http://{instance['ip']}:{instance['port']}"
+
+        SYLogger.info(f"Nacos 发现沙箱服务: {service_name} -> {base_url}")
+
+        return cls(base_url=base_url, user_id=user_id, timeout=timeout)
+
+    # ============== 内部方法 ==============
+
+    async def _post_async(self, endpoint: str, data: dict, timeout: int = None) -> dict:
+        """发送异步 POST 请求"""
+        import aiohttp
+        session = get_async_session()
+        async with session.post(
+            f"{self._base_url}{endpoint}",
+            json=data,
+            timeout=aiohttp.ClientTimeout(total=(timeout or self._timeout) + 10)
+        ) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+    # ============== 属性 ==============
+
+    @property
+    def id(self) -> str:
+        """沙箱 ID"""
+        return self._id
+
+    @property
+    def base_url(self) -> str:
+        """服务基础 URL"""
+        return self._base_url
+
+    @property
+    def user_id(self) -> str:
+        """用户ID"""
+        return self._user_id
+
+    # ============== 执行命令 ==============
+
+    async def aexecute(self, command: str, *, timeout: int = None) -> ExecuteResponse:
+        """异步执行 shell 命令"""
+        SYLogger.info(f"[Sandbox] 执行命令: {command}")
+        result = await self._post_async(f"{SANDBOX_API_PREFIX}/execute", {
+            "command": command,
+            "user_id": self._user_id,
+            "timeout": timeout or self._timeout
+        })
+        response = ExecuteResponse(
+            output=result["output"],
+            exit_code=result["exit_code"],
+            truncated=result.get("truncated", False)
+        )
+        SYLogger.info(f"[Sandbox] 执行完成: exit_code={response.exit_code}, output={response.output[:500] if response.output else 'None'}...")
+        return response
+
+    # ============== 批量操作 ==============
+
+    async def aupload_files(self, files: List[tuple[str, bytes]]) -> List[FileUploadResponse]:
+        """异步上传多个文件"""
+        results = []
+        for path, content in files:
+            try:
+                result = await self._post_async(f"{SANDBOX_API_PREFIX}/upload", {
+                    "path": path,
+                    "content": base64.b64encode(content).decode(),
+                    "user_id": self._user_id
+                })
+                results.append(FileUploadResponse(
+                    path=result["path"],
+                    error=result.get("error")
+                ))
+            except Exception as e:
+                results.append(FileUploadResponse(path=path, error=str(e)))
+        return results
+
+    async def adownload_files(self, paths: List[str]) -> List[FileDownloadResponse]:
+        """异步下载多个文件"""
+        results = []
+        for path in paths:
+            try:
+                result = await self._post_async(
+                    f"{SANDBOX_API_PREFIX}/download",
+                    {"path": path, "user_id": self._user_id}
+                )
+                if result.get("error"):
+                    results.append(FileDownloadResponse(
+                        path=path,
+                        error=result["error"]
+                    ))
+                else:
+                    content = base64.b64decode(result["content"])
+                    results.append(FileDownloadResponse(path=path, content=content))
+            except Exception as e:
+                results.append(FileDownloadResponse(path=path, error=str(e)))
+        return results
+
+    # ============== 管理操作 ==============
+
+    async def areset(self) -> dict:
+        """异步重置沙箱环境"""
+        return await self._post_async(f"{SANDBOX_API_PREFIX}/reset", {"user_id": self._user_id})
+
+    async def ahealth_check(self) -> dict:
+        """异步健康检查"""
+        # 健康检查不需要 user_id
+        async with get_async_session().get(f"{self._base_url}{SANDBOX_API_PREFIX}/health") as resp:
+            resp.raise_for_status()
+            return await resp.json()