kotonebot 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

kotonebot/devtools/web/server/rest_api.py

@@ -0,0 +1,217 @@
+import os
+import logging
+from pathlib import Path
+from typing import Any, TypeVar, Generic, Optional
+
+import cv2
+from fastapi import APIRouter, HTTPException, Query, Body
+from fastapi.responses import FileResponse, JSONResponse
+from pydantic import BaseModel
+from pydantic.generics import GenericModel
+
+from kotonebot.devtools.project.project import Project
+from kotonebot.devtools.project.scanner import scan_prefabs
+
+
+T = TypeVar("T")
+
+
+class ResponseModel(GenericModel, Generic[T]):
+    success: bool
+    message: Optional[str] = None
+    data: Optional[T] = None
+
+
+class WriteTextRequest(BaseModel):
+    content: str
+
+def create_rest_router(project: Project) -> APIRouter:
+    router = APIRouter(prefix="/api")
+    _prefabs_cache = None
+
+    project_root = Path(project.conf_path).parent.resolve()
+    thumbnail_cache_root = project_root / ".kotonebot" / "cache" / "thumbnails"
+    image_suffixes = {".png", ".jpg", ".jpeg", ".bmp", ".webp"}
+
+    def _is_image_file(path: Path) -> bool:
+        return path.suffix.lower() in image_suffixes
+
+    def _get_thumbnail_path(source: Path, size: int) -> Path:
+        if size <= 0:
+            raise ValueError("size must be positive")
+        try:
+            rel = source.resolve().relative_to(project_root)
+        except Exception as e:
+            raise ValueError(str(e))
+        size_dir = thumbnail_cache_root / str(size)
+        target_dir = size_dir / rel.parent
+        target_dir.mkdir(parents=True, exist_ok=True)
+        return target_dir / rel.name
+
+    def _ensure_thumbnail(source: Path, size: int) -> Path:
+        cache_path = _get_thumbnail_path(source, size)
+        regenerate = True
+        if cache_path.exists():
+            src_stat = source.stat()
+            cache_stat = cache_path.stat()
+            if cache_stat.st_mtime >= src_stat.st_mtime and cache_stat.st_size > 0:
+                regenerate = False
+        if regenerate:
+            img = cv2.imread(str(source))
+            if img is None:
+                raise ValueError(f"Could not read image: {source}")
+            height, width = img.shape[:2]
+            longest = max(width, height)
+            if longest <= 0:
+                raise ValueError("invalid image size")
+            scale = size / float(longest)
+            new_width = max(1, int(round(width * scale)))
+            new_height = max(1, int(round(height * scale)))
+            resized = cv2.resize(img, (new_width, new_height), interpolation=cv2.INTER_AREA)
+            cv2.imwrite(str(cache_path), resized)
+        return cache_path
+
+    def _get_safe_path(path_str: str) -> Path:
+        p = Path(path_str)
+        if not p.is_absolute():
+            p = project_root / p
+
+        try:
+            p = p.resolve()
+            if not str(p).startswith(str(project_root)):
+                raise ValueError(f"Access denied: Path {p} is outside project root {project_root}")
+        except Exception as e:
+            raise ValueError(f"Invalid path: {e}")
+
+        return p
+
+    def _ok(data: Any = None, message: Optional[str] = None) -> JSONResponse:
+        return JSONResponse(ResponseModel[Any](success=True, message=message, data=data).dict())
+
+
+    def _err(message: str) -> JSONResponse:
+        return JSONResponse(ResponseModel[Any](success=False, message=message, data=None).dict())
+
+
+    @router.get("/project/root")
+    async def get_project_root():
+        try:
+            data: dict = {"resource_root": str(project_root)}
+            # include editor configuration if available (prefabs_module, resource_path)
+            try:
+                if project.conf and project.conf.editor:
+                    data["editor"] = project.conf.editor.model_dump()
+            except Exception:
+                logging.exception("Failed to include editor config in /project/root response")
+
+            return _ok(data)
+        except Exception as e:
+            logging.exception("Error while handling /project/root")
+            return _err(str(e))
+
+    @router.get("/fs/list_dir")
+    async def list_dir(path: str = Query(..., description="Path relative to project root or absolute path")):
+        try:
+            safe_path = _get_safe_path(path)
+            if not safe_path.exists():
+                return _err("Path not found")
+            if not safe_path.is_dir():
+                return _err("Not a directory")
+
+            items = []
+            entries = sorted(list(safe_path.iterdir()), key=lambda x: (not x.is_dir(), x.name.lower()))
+            for item in entries:
+                is_image = _is_image_file(item) if item.is_file() else False
+                thumbnail_url: Optional[str]
+                if is_image:
+                    thumbnail_url = f"/api/image/thumbnail?path={item}&size=128"
+                else:
+                    thumbnail_url = None
+                items.append({
+                    "name": item.name,
+                    "isDirectory": item.is_dir(),
+                    "path": str(item),
+                    "isImage": is_image,
+                    "thumbnailUrl": thumbnail_url,
+                })
+
+            return _ok({"items": items})
+        except PermissionError:
+            return _err("Permission denied")
+        except Exception as e:
+            return _err(str(e))
+
+    @router.get("/fs/read_text")
+    async def read_text(path: str = Query(...)):
+        try:
+            safe_path = _get_safe_path(path)
+            if not safe_path.exists():
+                return _err("File not found")
+            if not safe_path.is_file():
+                return _err("Not a file")
+
+            content = safe_path.read_text(encoding="utf-8")
+            return _ok({"content": content})
+        except Exception as e:
+            return _err(str(e))
+
+    @router.put("/fs/write_text")
+    async def write_text(path: str = Query(...), body: WriteTextRequest = Body(...)):
+        try:
+            safe_path = _get_safe_path(path)
+            if not safe_path.parent.exists():
+                return _err("Parent directory does not exist")
+
+            temp_path = safe_path.with_suffix(safe_path.suffix + ".tmp")
+            temp_path.write_text(body.content, encoding="utf-8")
+            os.replace(temp_path, safe_path)
+            return _ok({"status": "ok"})
+        except Exception as e:
+            return _err(str(e))
+
+    @router.get("/image")
+    async def get_image(path: str = Query(...)):
+        safe_path = _get_safe_path(path)
+        if not safe_path.exists():
+             raise HTTPException(status_code=404, detail="Image not found")
+        
+        if not _is_image_file(safe_path):
+             raise HTTPException(status_code=400, detail="Not an image file")
+             
+        return FileResponse(safe_path)
+
+    @router.get("/image/thumbnail")
+    async def get_image_thumbnail(path: str = Query(...), size: int = Query(128, ge=1, le=2048)):
+        safe_path = _get_safe_path(path)
+        if not safe_path.exists():
+            raise HTTPException(status_code=404, detail="Image not found")
+        if not _is_image_file(safe_path):
+            raise HTTPException(status_code=400, detail="Not an image file")
+        try:
+            cache_path = _ensure_thumbnail(safe_path, size)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        return FileResponse(cache_path)
+
+    @router.get("/prefabs/schema")
+    async def get_prefabs_schema():
+        nonlocal _prefabs_cache
+        try:
+            if _prefabs_cache is not None:
+                return _ok(_prefabs_cache)
+
+            if not project.conf or not project.conf.editor or not project.conf.editor.prefabs_module:
+                return _ok({"version": 1, "prefabs": {}})
+
+            schema = scan_prefabs(project.conf.editor.prefabs_module)
+            _prefabs_cache = schema
+            return _ok(schema)
+        except Exception as e:
+            return _err(str(e))
+
+
+    @router.get("/health")
+    async def health_check():
+        return _ok({"status": "ok", "service": "kotonebot-devtools"})
+
+    return router

kotonebot/devtools/web/server/server.py

@@ -0,0 +1,85 @@
+import webbrowser
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import JSONResponse, HTMLResponse
+import uvicorn
+
+from kotonebot.devtools.project.project import Project
+from .rest_api import create_rest_router
+
+
+def create_app():
+    """Create and configure the FastAPI application."""
+    app = FastAPI(title="KotoneBot DevTools")
+
+    project = Project()
+
+    # REST API for DevTools2 (file IO, images, prefab schema)
+    app.include_router(create_rest_router(project))
+    
+    # Get the dist directory path
+    dist_dir = Path(__file__).parent.parent / "web" / "dist"
+
+    # Mount static files if dist directory exists
+    if dist_dir.exists():
+        # 优先将打包好的静态资源挂载到 /assets（如果构建将资源放在 dist/assets）
+        assets_dir = dist_dir / "assets"
+        app.mount("/assets", StaticFiles(directory=assets_dir), name="assets")
+
+        # SPA: 直接将除 /api/* 之外的所有路径映射到 index.html
+        @app.get("/{_path:path}")
+        async def spa_catchall(_path: str):
+            # 保留 API 路由的行为
+            if _path.startswith("api/"):
+                return JSONResponse({"detail": "Not Found"}, status_code=404)
+
+            index_file = dist_dir / "index.html"
+            if index_file.exists():
+                return HTMLResponse(index_file.read_text(encoding="utf-8"))
+
+            return JSONResponse({"detail": "Not Found"}, status_code=404)
+    else:
+        # If dist doesn't exist, provide a helpful message
+        @app.get("/")
+        async def missing_dist():
+            return JSONResponse({
+                "error": "DevTools frontend not found",
+                "message": f"Expected frontend dist at {dist_dir}",
+                "info": "Build the frontend using: npm run build in kotonebot-devtool directory"
+            }, status_code=503)
+    
+    return app
+
+
+def start_devtools(
+    host: str = "127.0.0.1",
+    port: int = 1178,
+    open_browser: bool = False
+) -> None:
+    """Start the DevTools web server.
+    
+    Args:
+        host: Host to listen on (default: 127.0.0.1)
+        port: Port to listen on (default: 1178)
+        open_browser: Automatically open browser (default: False)
+    """
+    app = create_app()
+    
+    # Open browser before starting server
+    if open_browser:
+        url = f"http://{host}:{port}"
+        webbrowser.open(url)
+    
+    # Start server
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_level="info"
+    )
+
+
+if __name__ == "__main__":
+    start_devtools()

kotonebot/errors.py

@@ -1,4 +1,4 @@
-from typing import Callable
+from typing import Callable, Sequence
 
 
 class KotonebotError(Exception):
@@ -7,6 +7,11 @@ class KotonebotError(Exception):
 class KotonebotWarning(Warning):
     pass
 
+class MissingDependencyError(KotonebotError, ImportError):
+    def __init__(self, e: ImportError, group_name: str) -> None:
+        self.original_error = e
+        super().__init__(f'Cannot import module "{e.name}". Did you forget to run "pip install kotonebot[{group_name}]"?')
+
 class UserFriendlyError(KotonebotError):
     def __init__(
         self,
@@ -58,7 +63,7 @@ class TaskNotFoundError(KotonebotError):
         super().__init__(f'Task "{task_id}" not found.')
 
 class UnscalableResolutionError(KotonebotError):
-    def __init__(self, target_resolution: tuple[int, int], screen_size: tuple[int, int]):
+    def __init__(self, target_resolution: Sequence[int], screen_size: Sequence[int]):
         self.target_resolution = target_resolution
         self.screen_size = screen_size
         super().__init__(f'Cannot scale to target resolution {target_resolution}. '

kotonebot/interop/win/__init__.py

@@ -1,3 +1,12 @@
 # ruff: noqa: E402
 from kotonebot.util import require_windows
-require_windows('kotonebot.interop.win module')
+require_windows('kotonebot.interop.win module')
+
+
+from . import _mouse as mouse
+from .shake_mouse import ShakeMouse
+
+__all__ = [
+    'mouse',
+    'ShakeMouse',
+]

kotonebot/interop/win/_mouse.py

@@ -0,0 +1,311 @@
+import math
+import time
+from typing import Callable, Literal, TypedDict, overload, Tuple
+
+import mouse
+from typing_extensions import Unpack
+
+from kotonebot.primitives import Point
+
+MouseButton = Literal['left', 'right', 'middle']
+TweenFunc = Callable[[float], float]
+Tween = Literal['linear', 'ease_in', 'ease_out', 'ease_in_out'] | TweenFunc
+
+# https://stackoverflow.com/a/76554895
+def high_precision_sleep(duration):
+    start_time = time.perf_counter()
+    while True:
+        elapsed_time = time.perf_counter() - start_time
+        remaining_time = duration - elapsed_time
+        if remaining_time <= 0:
+            break
+        if remaining_time > 0.02:  # Sleep for 5ms if remaining time is greater
+            time.sleep(max(remaining_time/2, 0.0001))  # Sleep for the remaining time or minimum sleep interval
+        else:
+            pass
+
+class AnimationParams(TypedDict, total=False):
+    duration: float
+    """动画持续时间，单位为秒。
+
+    动画实际持续时间可能会略大于此值，具体取决于系统以及 delay_func 的实现。
+    """
+    speed: float
+    """动画速度，单位为像素/秒。"""
+    steps: int
+    """动画步数。"""
+    tween: Tween
+    """插值函数。
+
+    可选 'linear', 'ease_in', 'ease_out', 'ease_in_out'，默认为 'ease_in_out'。
+    也可以是一个函数，其输入为动画进度，输出为动画值。
+    """
+    delay_func: Callable[[float], None] | None
+    """延时函数。默认为 time.sleep。
+
+    可选，如果提供了此参数，则会在每个动画点之间调用此函数。
+    """
+    user_interrupt: Callable[[], bool | None] | Literal[True] | None
+    """可选，用户中断函数，默认为 None。
+
+    若提供此参数，那么在动画执行时会检测用户输入，如果用户尝试移动鼠标，
+    会自动终止动画（传入 True）或调用此函数（传入 Callable，根据返回值决定是否继续）。
+    """
+    user_interrupt_threshold: float | None
+    """可选，用户中断阈值，单位为像素，默认为 None，表示使用全局参数。
+
+    如果提供此参数，则在检测用户中断时，仅当移动鼠标的距离大于此值时才会触发终止。
+    """
+
+default_speed = 3000
+animation_args: AnimationParams = {
+    'steps': 100,
+    'tween': 'ease_in_out',
+    'delay_func': high_precision_sleep,
+    'user_interrupt': None,
+    'user_interrupt_threshold': 30,
+}
+"""全局动画参数。"""
+
+# https://easings.net
+def _tween_linear(t: float) -> float:
+    return t
+
+def _tween_ease_in(t: float) -> float:
+    return t * t
+
+def _tween_ease_out(t: float) -> float:
+    return t * (2 - t)
+
+def _tween_ease_in_out(t: float) -> float:
+    return t * t * (3 - 2 * t)
+
+_TWEEN_FUNCTIONS = {
+    'linear': _tween_linear,
+    'ease_in': _tween_ease_in,
+    'ease_out': _tween_ease_out,
+    'ease_in_out': _tween_ease_in_out,
+}
+
+def _get_animated_points(start_point: Point, end_point: Point, steps: int, tween: Tween):
+    if isinstance(tween, str):
+        tween_func = _TWEEN_FUNCTIONS.get(tween, _tween_linear)
+    else:
+        tween_func = tween
+    for i in range(steps + 1):
+        progress = i / steps
+        eased_progress = tween_func(progress)
+        x = start_point.x + (end_point.x - start_point.x) * eased_progress
+        y = start_point.y + (end_point.y - start_point.y) * eased_progress
+        yield Point(int(x), int(y))
+
+def do_tween(start: Point, end: Point, args: AnimationParams, *, skip_first: bool = True):
+    """从起点到终点根据输入的动画参数进行插值，并自动进行延时。
+
+    :param start: 开始位置。
+    :param end: 结束位置。
+    :param args: 动画参数，详见 :class:`.AnimationParams`。
+    :param skip_first: 是否跳过第一个点。默认为 True。
+    :raises ValueError: 输入的 speed 为非正数时抛出。
+    :raises ValueError: 同时提供 speed 与 duration 参数时抛出。
+    :return: 一个迭代器，包含所有插值的中间点。
+    """
+    duration = args.get('duration')
+    speed = args.get('speed')
+    steps = args.get('steps', animation_args.get('steps'))
+    tween = args.get('tween', animation_args.get('tween'))
+    delay_func = args.get('delay_func', animation_args.get('delay_func'))
+    user_interrupt = args.get('user_interrupt', animation_args.get('user_interrupt'))
+    user_interrupt_threshold = args.get('user_interrupt_threshold', animation_args.get('user_interrupt_threshold'))
+    assert steps is not None and tween is not None and delay_func is not None
+
+    def _speed_to_duration(speed: float) -> float:
+        return math.sqrt((end.x - start.x)**2 + (end.y - start.y)**2) / speed
+
+    if duration is None and speed is not None:
+        # 设置了速度，但没有设置时长，则计算时长
+        if speed <= 0:
+            raise ValueError('speed must be positive')
+        duration = _speed_to_duration(speed)
+    elif duration is not None and speed is None:
+        # 设置了时长，但没有设置速度，则计算速度
+        pass
+    elif duration is not None and speed is not None:
+        # 两个都设置
+        raise ValueError('duration and speed cannot be set at the same time')
+    else:
+        # 两个都没有设置，使用默认速度
+        duration = _speed_to_duration(default_speed)
+
+    delay = duration / steps if steps > 0 else 0
+    print(duration, steps, delay)
+    
+    point_iterator = _get_animated_points(start, end, steps, tween)
+    if skip_first:
+        next(point_iterator, None)
+
+    # 调用函数 (drag/move) 负责设置鼠标位置。
+    # 在每次迭代中，我们检查当前鼠标位置是否与我们在“上一次”迭代中生成的位置匹配。
+    # 我们无法在此处知道初始鼠标位置，因此我们从第二个点开始检查。
+    
+    iterator = iter(point_iterator)
+    try:
+        prev_pos = next(iterator)
+        yield prev_pos
+        delay_func(delay)
+    except StopIteration:
+        return
+
+    for pt in iterator:
+        # 检测用户中断
+        if user_interrupt:
+            pos = get_pos()
+            should_interrupt = False
+            if user_interrupt_threshold is not None:
+                if pos.distance_to(prev_pos) > user_interrupt_threshold:
+                    should_interrupt = True
+            else:
+                if pos != prev_pos:
+                    should_interrupt = True
+            
+            if should_interrupt:
+                # 鼠标被用户移动，中断动画。
+                if user_interrupt is True:
+                    return
+                if callable(user_interrupt):
+                    if not user_interrupt():
+                        return
+        
+        yield pt
+        prev_pos = pt
+        delay_func(delay)
+
+@overload
+def set_pos(p: Point) -> None: 
+    """移动光标到指定位置。
+
+    :param p: 坐标，Point 实例。
+    """
+
+@overload
+def set_pos(p: Tuple[int, int]) -> None:
+    """移动光标到指定位置。
+
+    :param p: 坐标，二元 tuple[int, int]。
+    """
+
+@overload
+def set_pos(p: int, y: int) -> None:
+    """移动光标到指定位置。
+
+    :param p: 坐标，x 坐标。
+    :param y: 坐标，y 坐标。
+    """
+
+def set_pos(p, y: int | None = None):
+    if y is None:
+        # 可能是 Point 或二元 tuple
+        if isinstance(p, Point):
+            x = int(p.x)
+            y = int(p.y)
+        else:
+            # 假定为 (x, y)
+            _x, _y = p
+            x = int(_x)
+            y = int(_y)
+    else:
+        x = int(p)
+        y = int(y)
+
+    mouse.move(x, y)
+
+
+def get_pos() -> Point:
+    x, y = mouse.get_position()
+    return Point(x, y)
+
+
+def down(button: MouseButton):
+    mouse.press(button)
+
+
+def up(button: MouseButton):
+    mouse.release(button)
+
+
+def click(button: MouseButton, *, duration: float = 0.1):
+    """模拟鼠标点击。
+    
+    :param button: 必填，鼠标按钮。
+    :param duration: 可选，点击持续时间。默认为 0.1。
+    """
+    down(button)
+    time.sleep(duration)
+    up(button)
+
+
+def drag(
+    start: Point,
+    end: Point,
+    *,
+    button: MouseButton | None = 'left',
+    **kargs: Unpack[AnimationParams],
+):
+    """模拟鼠标拖拽。
+    参数中与动画相关的部分详见 :class:`.AnimationParams`。
+
+    :param start: 必填，起点。
+    :param end: 必填，终点。
+    :param button: 可选，拖拽使用的鼠标按钮。默认为 `left`。None 表示不按下任何鼠标按钮，相当于只移动光标。
+    :param duration: 可选，动画持续时间。
+    :param speed: 可选，动画速度。
+    :param steps: 可选，动画步数。
+    :param tween: 可选，动画曲线。
+    :param delay_func: 可选，延时函数。详见 :class:`.AnimationParams`。
+    :param user_interrupt: 可选，用户中断函数。详见 :class:`.AnimationParams`。
+    :param user_interrupt_threshold: 可选，用户中断阈值。详见 :class:`.AnimationParams`。
+    """
+    if button:
+        set_pos(start)
+        time.sleep(0.02)
+        down(button)
+        time.sleep(0.02)
+    
+    try:
+        for p in do_tween(start, end, kargs):
+            set_pos(p)
+            pass
+    finally:
+        if button:
+            up(button)
+
+def move(
+    start: Point,
+    end: Point,
+    /,
+    **kargs: Unpack[AnimationParams],
+):
+    """模拟鼠标移动。
+    参数中与动画相关的部分详见 :class:`kotonebot.interop.win.AnimationParams`。
+
+    :param start: 必填，起点。
+    :param end: 必填，终点。
+    :param duration: 可选，动画持续时间。
+    :param speed: 可选，动画速度。
+    :param steps: 可选，动画步数。
+    :param tween: 可选，动画曲线。
+    :param delay_func: 可选，延时函数。详见 :class:`.AnimationParams`。
+    :param user_interrupt: 可选，用户中断函数。详见 :class:`.AnimationParams`。
+    :param user_interrupt_threshold: 可选，用户中断阈值。详见 :class:`.AnimationParams`。
+    """
+    drag(start, end, button=None, **kargs)
+
+__all__ = [
+    'set_pos',
+    'get_pos',
+    'down',
+    'up',
+    'click',
+    'drag',
+    'move',
+]