automas-maafw-runner 0.1.1__tar.gz

automas_maafw_runner-0.1.1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: automas-maafw-runner
+Version: 0.1.1
+Summary: Isolated MaaFW runner service plugin for AUTO-MAS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: automas-maafw-agent-env>=0.1.0
+Requires-Dist: automas-maafw-interface>=0.1.1
+Requires-Dist: json5>=0.9
+Requires-Dist: pydantic>=2
+
+# automas-maafw-runner
+
+Isolated MaaFW runner service for AUTO-MAS.
+
+It provides `maafw.runner.v1`. The service builds run plans in the host process
+and runs MaaFW through a worker subprocess so importing the service does not load
+`maa` into the AUTO-MAS main process.
+
+The wheel includes the MaaFW runtime worker code. `maa` is imported only by the
+worker subprocess entrypoint, not by `MaaFWRunnerService`.

automas_maafw_runner-0.1.1/README.md

@@ -0,0 +1,10 @@
+# automas-maafw-runner
+
+Isolated MaaFW runner service for AUTO-MAS.
+
+It provides `maafw.runner.v1`. The service builds run plans in the host process
+and runs MaaFW through a worker subprocess so importing the service does not load
+`maa` into the AUTO-MAS main process.
+
+The wheel includes the MaaFW runtime worker code. `maa` is imported only by the
+worker subprocess entrypoint, not by `MaaFWRunnerService`.

automas_maafw_runner-0.1.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "automas-maafw-runner"
+version = "0.1.1"
+description = "Isolated MaaFW runner service plugin for AUTO-MAS"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+dependencies = [
+    "automas-maafw-agent-env>=0.1.0",
+    "automas-maafw-interface>=0.1.1",
+    "json5>=0.9",
+    "pydantic>=2",
+]
+
+[project.entry-points."auto_mas.plugins"]
+automas_maafw_runner = "automas_maafw_runner.plugin:Plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+automas_maafw_runner = ["py.typed"]

automas_maafw_runner-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

automas_maafw_runner-0.1.1/src/automas_maafw_runner/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .environment import MaaFWRunnerEnvironment
+from .models import (
+    MaaFWDeviceConfig,
+    MaaFWResolvedPath,
+    MaaFWResourceBundlePlan,
+    MaaFWRunnerJobPayload,
+    MaaFWRunPlan,
+    MaaFWRunResult,
+    MaaFWSkippedTaskPlan,
+    MaaFWTaskRunPlan,
+)
+from .run_plan import MaaFWRunPlanError, build_maafw_run_plan
+from .service import MaaFWRunnerService
+
+__all__ = [
+    "MaaFWDeviceConfig",
+    "MaaFWResolvedPath",
+    "MaaFWResourceBundlePlan",
+    "MaaFWRunPlan",
+    "MaaFWRunPlanError",
+    "MaaFWRunResult",
+    "MaaFWRunnerEnvironment",
+    "MaaFWRunnerJobPayload",
+    "MaaFWRunnerService",
+    "MaaFWSkippedTaskPlan",
+    "MaaFWTaskRunPlan",
+    "build_maafw_run_plan",
+]

automas_maafw_runner-0.1.1/src/automas_maafw_runner/environment.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import sysconfig
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterable
+
+
+RUNNER_ENV_MANIFEST_NAME = ".auto_mas_maafw_runner_env.json"
+RUNNER_DEFAULT_PACKAGES = (
+    "maafw",
+    "pydantic==2.11.7",
+    "json5==0.14.0",
+)
+RUNNER_ENV_TIMEOUT = 300
+REQUIREMENT_NAME_RE = re.compile(
+    r"^\s*([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)"
+    r"\s*(?:\[[^\]]+\])?\s*(?:===|[<>=!~]=?|@|;|\s|$)"
+)
+
+
+@dataclass(frozen=True)
+class MaaFWRunnerEnvironment:
+    python_executable: Path
+    venv_path: Path
+    env: dict[str, str]
+    packages: tuple[str, ...]
+    maafw_version: str | None
+
+
+def prepare_runner_environment(
+    project_path: str | Path,
+    *,
+    managed_env_root: str | Path | None = None,
+    import_paths: Iterable[str | Path] = (),
+    send_log: Callable[[str], None] | None = None,
+) -> MaaFWRunnerEnvironment:
+    """Prepare a project-scoped runner whose dependencies follow the project."""
+
+    project = Path(project_path).resolve()
+    root = (
+        Path(managed_env_root).resolve()
+        if managed_env_root is not None
+        else (Path.cwd() / "config" / "maafw_runner_venvs").resolve()
+    )
+    venv_path = root / _runner_env_name(project)
+    if venv_path.exists() and not _is_valid_venv(venv_path):
+        _reset_managed_venv(venv_path, root)
+
+    if not _is_valid_venv(venv_path):
+        venv_path.parent.mkdir(parents=True, exist_ok=True)
+        bootstrap_python = _venv_bootstrap_python()
+        _send_log(
+            send_log,
+            f"[MaaFW Runner] 创建项目隔离 venv: {venv_path} "
+            f"(引导 Python: {bootstrap_python})",
+        )
+        _run_setup_command(
+            [bootstrap_python, "-m", "venv", str(venv_path)],
+            cwd=Path.cwd(),
+        )
+
+    python_executable = _venv_python(venv_path)
+    packages = tuple(build_runner_packages(project))
+    manifest = _build_manifest(project, packages)
+    manifest_path = venv_path / RUNNER_ENV_MANIFEST_NAME
+    env = build_runner_environment(venv_path, import_paths=import_paths)
+    if not _manifest_matches(manifest_path, manifest):
+        _send_log(
+            send_log,
+            f"[MaaFW Runner] 安装项目运行依赖: {', '.join(packages)}",
+        )
+        _run_setup_command(
+            [
+                str(python_executable),
+                "-m",
+                "pip",
+                "install",
+                "--upgrade",
+                "--disable-pip-version-check",
+                "--quiet",
+                *packages,
+            ],
+            cwd=project,
+            env=env,
+        )
+        _write_manifest(manifest_path, manifest)
+        _send_log(send_log, f"[MaaFW Runner] 项目运行依赖已准备: {venv_path}")
+    else:
+        _send_log(send_log, f"[MaaFW Runner] 项目隔离 venv 已就绪: {venv_path}")
+
+    maafw_version = _installed_maafw_version(python_executable, env)
+    if maafw_version:
+        _send_log(send_log, f"[MaaFW Runner] 使用项目 MaaFW: v{maafw_version}")
+
+    return MaaFWRunnerEnvironment(
+        python_executable=python_executable,
+        venv_path=venv_path,
+        env=env,
+        packages=packages,
+        maafw_version=maafw_version,
+    )
+
+
+def build_runner_packages(project_path: str | Path) -> list[str]:
+    project_packages = _load_requirements(Path(project_path).resolve())
+    project_distribution_names = {
+        name
+        for requirement in project_packages
+        if (name := requirement_distribution_name(requirement)) is not None
+    }
+    packages = [
+        package
+        for package in RUNNER_DEFAULT_PACKAGES
+        if requirement_distribution_name(package) not in project_distribution_names
+    ]
+    packages.extend(project_packages)
+    return packages
+
+
+def requirement_distribution_name(requirement: str) -> str | None:
+    match = REQUIREMENT_NAME_RE.match(requirement)
+    if match is None:
+        return None
+    return re.sub(r"[-_.]+", "-", match.group(1)).lower()
+
+
+def build_runner_environment(
+    venv_path: str | Path,
+    *,
+    import_paths: Iterable[str | Path] = (),
+) -> dict[str, str]:
+    env = os.environ.copy()
+    for name in (
+        "PYTHONHOME",
+        "PYTHONUSERBASE",
+        "PIP_TARGET",
+        "PIP_PREFIX",
+        "PIP_USER",
+    ):
+        env.pop(name, None)
+
+    venv = Path(venv_path).resolve()
+    scripts_dir = venv / ("Scripts" if os.name == "nt" else "bin")
+    resolved_import_paths = [
+        str(Path(path).resolve())
+        for path in import_paths
+        if Path(path).exists()
+    ]
+    existing_python_path = env.get("PYTHONPATH", "")
+    if existing_python_path:
+        resolved_import_paths.append(existing_python_path)
+
+    env["VIRTUAL_ENV"] = str(venv)
+    env["PYTHONNOUSERSITE"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["PATH"] = f"{scripts_dir}{os.pathsep}{env.get('PATH', '')}"
+    if resolved_import_paths:
+        env["PYTHONPATH"] = os.pathsep.join(resolved_import_paths)
+    else:
+        env.pop("PYTHONPATH", None)
+    return env
+
+
+def prefer_active_venv_site_packages(
+    site_packages: str | Path | None = None,
+) -> Path | None:
+    """Keep the project Runner packages ahead of shared plugin dependencies."""
+
+    raw_path = site_packages or sysconfig.get_path("purelib")
+    if not raw_path:
+        return None
+
+    active_site_packages = Path(raw_path).resolve()
+    normalized_path = str(active_site_packages)
+    sys.path[:] = [
+        item
+        for item in sys.path
+        if _normalized_sys_path(item) != normalized_path
+    ]
+    sys.path.insert(0, normalized_path)
+    return active_site_packages
+
+
+def _load_requirements(project_path: Path) -> list[str]:
+    requirements_path = project_path / "requirements.txt"
+    packages: list[str] = []
+    try:
+        for raw_line in requirements_path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            packages.append(line)
+    except FileNotFoundError:
+        pass
+    return packages
+
+
+def _runner_env_name(project_path: Path) -> str:
+    key = str(project_path)
+    if os.name == "nt":
+        key = key.casefold()
+    digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
+    return f"maafw_runner_{digest}"
+
+
+def _build_manifest(project_path: Path, packages: tuple[str, ...]) -> dict[str, object]:
+    requirements_path = project_path / "requirements.txt"
+    interface_path = next(
+        (
+            project_path / file_name
+            for file_name in ("interface.json", "interface.jsonc")
+            if (project_path / file_name).is_file()
+        ),
+        None,
+    )
+    requirements_hash = (
+        hashlib.sha256(requirements_path.read_bytes()).hexdigest()
+        if requirements_path.is_file()
+        else ""
+    )
+    interface_hash = (
+        hashlib.sha256(interface_path.read_bytes()).hexdigest()
+        if interface_path is not None
+        else ""
+    )
+    return {
+        "schemaVersion": 4,
+        "projectPath": str(project_path),
+        "requirementsHash": requirements_hash,
+        "interfaceHash": interface_hash,
+        "packages": list(packages),
+        "pythonVersion": f"{sys.version_info.major}.{sys.version_info.minor}",
+    }
+
+
+def _manifest_matches(manifest_path: Path, expected: dict[str, object]) -> bool:
+    try:
+        current = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return False
+    return current == expected
+
+
+def _write_manifest(manifest_path: Path, manifest: dict[str, object]) -> None:
+    temporary_path = manifest_path.with_suffix(f"{manifest_path.suffix}.tmp")
+    temporary_path.write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    temporary_path.replace(manifest_path)
+
+
+def _run_setup_command(
+    command: list[str],
+    *,
+    cwd: Path,
+    env: dict[str, str] | None = None,
+) -> None:
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            timeout=RUNNER_ENV_TIMEOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=cwd,
+            env=env,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(f"MaaFW Runner 环境准备超时: {command[:3]}") from exc
+
+    if result.returncode == 0:
+        return
+    detail = (result.stderr or result.stdout or "").strip()
+    raise RuntimeError(
+        f"MaaFW Runner 环境准备失败 (exit={result.returncode}): {detail[:800]}"
+    )
+
+
+def _installed_maafw_version(
+    python_executable: Path,
+    env: dict[str, str],
+) -> str | None:
+    probe_env = env.copy()
+    probe_env.pop("PYTHONPATH", None)
+    try:
+        result = subprocess.run(
+            [
+                str(python_executable),
+                "-c",
+                "import importlib.metadata as m; print(m.version('maafw'))",
+            ],
+            capture_output=True,
+            timeout=15,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=probe_env,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    version = result.stdout.strip()
+    return version or None
+
+
+def _normalized_sys_path(path: str) -> str:
+    try:
+        return str(Path(path).resolve())
+    except (OSError, RuntimeError):
+        return path
+
+
+def _reset_managed_venv(venv_path: Path, managed_root: Path) -> None:
+    resolved_venv = venv_path.resolve()
+    if (
+        resolved_venv.parent != managed_root.resolve()
+        or not resolved_venv.name.startswith("maafw_runner_")
+    ):
+        raise RuntimeError(f"拒绝重建非托管 MaaFW Runner venv: {venv_path}")
+    shutil.rmtree(resolved_venv, ignore_errors=True)
+
+
+def _venv_python(venv_path: Path) -> Path:
+    if os.name == "nt":
+        return venv_path / "Scripts" / "python.exe"
+    return venv_path / "bin" / "python"
+
+
+def _is_valid_venv(venv_path: Path) -> bool:
+    return _venv_python(venv_path).is_file() and (venv_path / "pyvenv.cfg").is_file()
+
+
+def _venv_bootstrap_python() -> str:
+    portable_python = Path.cwd() / "environment" / "python" / "python.exe"
+    if portable_python.is_file():
+        return str(portable_python)
+    return sys.executable
+
+
+def _send_log(send_log: Callable[[str], None] | None, message: str) -> None:
+    if send_log is not None:
+        send_log(message)

automas_maafw_runner-0.1.1/src/automas_maafw_runner/models.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from automas_maafw_agent_env.models import MaaFWAgentCommandPlan
+from pydantic import BaseModel, ConfigDict, Field
+
+
+MaaFWControllerType = Literal["Adb", "Win32"]
+
+
+class MaaFWResolvedPath(BaseModel):
+    raw: str
+    resolved: str
+    exists: bool
+    isFile: bool = False
+    isDir: bool = False
+
+
+class MaaFWResourceBundlePlan(BaseModel):
+    name: str
+    label: str | None = None
+    paths: list[MaaFWResolvedPath] = Field(default_factory=list)
+    attachedPaths: list[MaaFWResolvedPath] = Field(default_factory=list)
+
+
+class MaaFWTaskRunPlan(BaseModel):
+    name: str
+    label: str | None = None
+    entry: str
+    options: dict[str, Any] = Field(default_factory=dict)
+    pipelineOverride: dict[str, Any] = Field(default_factory=dict)
+    logOptions: dict[str, Any] = Field(default_factory=dict)
+    overrideNodes: list[str] = Field(default_factory=list)
+
+
+class MaaFWSkippedTaskPlan(BaseModel):
+    name: str
+    label: str | None = None
+    entry: str | None = None
+    reason: str
+
+
+class MaaFWPretaskRunPlan(BaseModel):
+    name: str
+    label: str | None = None
+    executable: str
+    args: list[str] = Field(default_factory=list)
+    options: dict[str, Any] = Field(default_factory=dict)
+
+
+class MaaFWRunPlan(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    path: str
+    projectName: str
+    projectLabel: str | None = None
+    controllerName: str
+    controllerType: str
+    resourceName: str
+    resource: MaaFWResourceBundlePlan
+    agents: list[MaaFWAgentCommandPlan] = Field(default_factory=list)
+    pretasks: list[MaaFWPretaskRunPlan] = Field(default_factory=list)
+    piEnv: dict[str, str] = Field(default_factory=dict)
+    tasks: list[MaaFWTaskRunPlan] = Field(default_factory=list)
+    skippedTasks: list[MaaFWSkippedTaskPlan] = Field(default_factory=list)
+
+
+class MaaFWDeviceConfig(BaseModel):
+    type: MaaFWControllerType
+    adbPath: str | None = None
+    address: str | None = None
+    hWnd: int | None = None
+    screencapMethods: int = 0
+    inputMethods: int = 0
+    screencapMethod: int = 0
+    mouseMethod: int = 0
+    keyboardMethod: int = 0
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class MaaFWRunResult(BaseModel):
+    success: bool
+    projectName: str
+    controllerName: str
+    resourceName: str
+    completedTasks: list[str] = Field(default_factory=list)
+    failedTask: str | None = None
+    errorMessage: str | None = None
+
+
+class MaaFWRunnerJobPayload(BaseModel):
+    plan: MaaFWRunPlan
+    deviceConfig: MaaFWDeviceConfig