noracu 0.1.0 → 0.1.1

package/imctl/src/imctl/vision.py

@@ -0,0 +1,138 @@
+"""Local OCR via the macOS Vision framework.
+
+Runs VNRecognizeTextRequest on a screenshot of the mirroring window
+and returns text with normalized (0-1) coordinates, ready to feed into
+input.tap(). Everything runs locally — no network, no API keys.
+
+Coordinate convention: Vision returns bottom-left-origin bounding
+boxes; we convert to top-left-origin (screen convention) and normalize
+to the window size so results map directly onto tap(nx, ny).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+
+from .window import get_bounds, get_window_info
+
+
+class OCRError(RuntimeError):
+    """Raised when OCR fails."""
+
+
+@dataclass(frozen=True)
+class OCRHit:
+    text: str
+    nx: float  # normalized x of the text center (0-1)
+    ny: float  # normalized y of the text center (0-1)
+    confidence: float
+
+    def __str__(self) -> str:
+        return f"({self.nx:.2f},{self.ny:.2f}) {self.text!r} [{self.confidence:.2f}]"
+
+
+def capture_window(path: str | None = None) -> str:
+    """Screenshot the mirroring window to a PNG file; returns the path.
+
+    Captures by CGWindow id (``screencapture -l``) so the image is the window's own content even when
+    other windows cover it or it is not frontmost. Falls back to a screen-region capture of the AX bounds
+    when the window id cannot be resolved.
+    """
+    if path is None:
+        path = tempfile.mktemp(prefix="imctl_", suffix=".png")
+    info = get_window_info()
+    if info is not None:
+        r = subprocess.run(
+            ["screencapture", "-x", "-o", "-l", str(info["id"]), path],
+            capture_output=True,
+            timeout=10,
+        )
+        if r.returncode == 0 and os.path.exists(path) and os.path.getsize(path) > 0:
+            return path
+    b = get_bounds()
+    subprocess.run(
+        ["screencapture", "-x", f"-R{b.x},{b.y},{b.width},{b.height}", path],
+        check=True,
+        timeout=10,
+    )
+    return path
+
+
+def ocr(image_path: str, languages: tuple[str, ...] = ("en-US", "zh-Hans")) -> list[OCRHit]:
+    """Run Vision OCR on an image; return hits sorted reading-order.
+
+    Uses the pyobjc Vision bindings (no subprocess Swift compile).
+    """
+    try:
+        import Vision
+        from Foundation import NSURL
+        from Quartz import (
+            CGImageSourceCreateWithURL,
+            CGImageSourceCreateImageAtIndex,
+            CGImageGetWidth,
+            CGImageGetHeight,
+        )
+    except ImportError as exc:  # pragma: no cover
+        raise OCRError(f"pyobjc frameworks missing: {exc}") from exc
+
+    url = NSURL.fileURLWithPath_(image_path)
+    src = CGImageSourceCreateWithURL(url, None)
+    if src is None:
+        raise OCRError(f"cannot open image: {image_path}")
+    cg_image = CGImageSourceCreateImageAtIndex(src, 0, None)
+    if cg_image is None:
+        raise OCRError(f"cannot decode image: {image_path}")
+
+    request = Vision.VNRecognizeTextRequest.alloc().init()
+    request.setRecognitionLevel_(Vision.VNRequestTextRecognitionLevelAccurate)
+    if hasattr(request, "setRecognitionLanguages_"):
+        request.setRecognitionLanguages_(list(languages))
+    request.setUsesLanguageCorrection_(True)
+
+    handler = Vision.VNImageRequestHandler.alloc().initWithCGImage_options_(
+        cg_image, None
+    )
+    ok = handler.performRequests_error_([request], None)
+    if not ok:
+        raise OCRError("VNImageRequestHandler.performRequests failed")
+
+    results = request.results() or []
+    hits: list[OCRHit] = []
+    for obs in results:
+        cand = obs.topCandidates_(1)
+        if not cand:
+            continue
+        cand = cand[0]
+        box = obs.boundingBox()  # bottom-left origin, normalized
+        cx = box.origin.x + box.size.width / 2
+        cy_top = 1.0 - (box.origin.y + box.size.height / 2)  # flip to top-left
+        hits.append(
+            OCRHit(
+                text=str(cand.string()),
+                nx=cx,
+                ny=cy_top,
+                confidence=float(cand.confidence()),
+            )
+        )
+
+    # Reading order: group by row (within 3% height), then left-to-right.
+    hits.sort(key=lambda h: (round(h.ny / 0.03), h.nx))
+    return hits
+
+
+def find(text: str, image_path: str | None = None,
+         exact: bool = False) -> OCRHit | None:
+    """Find the first OCR hit matching text; returns None if absent."""
+    path = image_path or capture_window()
+    for hit in ocr(path):
+        if (hit.text == text) if exact else (text in hit.text):
+            return hit
+    return None
+
+
+def read_screen() -> list[OCRHit]:
+    """Convenience: capture + OCR the current mirroring window."""
+    return ocr(capture_window())

package/imctl/src/imctl/window.py

@@ -0,0 +1,248 @@
+"""Window management for the iPhone Mirroring app.
+
+Resolves the iPhone Mirroring window bounds dynamically before every
+gesture. The window can be moved, minimized, or closed between actions,
+so callers must never cache bounds across gestures.
+
+Uses System Events (AppleScript) rather than the raw AX C API: it is
+the most reliable way to enumerate windows of another process and
+survives permission quirks better than direct AXUIElement calls.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+APP_NAME = "iPhone Mirroring"
+PROCESS_NAME = "iPhone Mirroring"
+
+
+class WindowError(RuntimeError):
+    """Raised when the iPhone Mirroring window cannot be found or used."""
+
+
+@dataclass(frozen=True)
+class WindowBounds:
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return (self.x + self.width // 2, self.y + self.height // 2)
+
+    def denormalize(self, nx: float, ny: float) -> tuple[int, int]:
+        """Convert normalized (0-1) coordinates to screen coordinates."""
+        if not (0.0 <= nx <= 1.0 and 0.0 <= ny <= 1.0):
+            raise ValueError(f"normalized coords out of range: ({nx}, {ny})")
+        return (
+            round(self.x + nx * self.width),
+            round(self.y + ny * self.height),
+        )
+
+
+_GET_BOUNDS_SCRIPT = '''
+tell application "System Events"
+    tell process "iPhone Mirroring"
+        set winCount to count of windows
+        if winCount is 0 then return "NO_WINDOW"
+        set {x, y} to position of window 1
+        set {w, h} to size of window 1
+        return (x as text) & "," & (y as text) & "," & (w as text) & "," & (h as text)
+    end tell
+end tell
+'''
+
+_FRONTMOST_SCRIPT = '''
+tell application "System Events"
+    tell process "iPhone Mirroring"
+        return frontmost as text
+    end tell
+end tell
+'''
+
+
+def _run_osascript(script: str) -> str:
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    if result.returncode != 0:
+        raise WindowError(f"osascript failed: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def is_running() -> bool:
+    """Return True if the iPhone Mirroring process is alive."""
+    result = subprocess.run(
+        ["pgrep", "-x", PROCESS_NAME], capture_output=True
+    )
+    return result.returncode == 0
+
+
+def ensure_running() -> None:
+    """Launch iPhone Mirroring if it is not running."""
+    if is_running():
+        return
+    subprocess.run(
+        ["open", "-a", APP_NAME], check=True, timeout=15
+    )
+    import time
+
+    for _ in range(20):  # wait up to ~10s for the process
+        if is_running():
+            break
+        time.sleep(0.5)
+    else:
+        raise WindowError("iPhone Mirroring did not start within 10s")
+
+
+def ensure_frontmost() -> None:
+    """Bring the iPhone Mirroring window to the front.
+
+    CGEvents are delivered to the frontmost app; if another window
+    covers the mirroring window, taps would land on the wrong target.
+    """
+    if _run_osascript(_FRONTMOST_SCRIPT) == "true":
+        return
+    subprocess.run(
+        ["osascript", "-e", f'tell application "{APP_NAME}" to activate'],
+        capture_output=True,
+        timeout=10,
+    )
+    import time
+
+    time.sleep(0.4)  # let the window server settle
+    if _run_osascript(_FRONTMOST_SCRIPT) != "true":
+        raise WindowError("could not bring iPhone Mirroring to front")
+
+
+def get_bounds() -> WindowBounds:
+    """Return current bounds of the mirroring window.
+
+    Raises WindowError if the app is not running or has no window
+    (e.g. the window was closed but the process lives on).
+    """
+    out = _run_osascript(_GET_BOUNDS_SCRIPT)
+    if out == "NO_WINDOW":
+        # Window closed but process alive: re-activate to restore it.
+        subprocess.run(
+            ["osascript", "-e", f'tell application "{APP_NAME}" to activate'],
+            capture_output=True,
+            timeout=10,
+        )
+        import time
+
+        time.sleep(1.0)
+        out = _run_osascript(_GET_BOUNDS_SCRIPT)
+        if out == "NO_WINDOW":
+            raise WindowError(
+                "iPhone Mirroring window not found (app running, no window)"
+            )
+    try:
+        x, y, w, h = (int(v) for v in out.split(","))
+    except ValueError as exc:
+        raise WindowError(f"unexpected bounds format: {out!r}") from exc
+    if w <= 0 or h <= 0:
+        raise WindowError(f"degenerate window size: {w}x{h}")
+    return WindowBounds(x=x, y=y, width=w, height=h)
+
+
+_PAUSED_SCRIPT = '''
+tell application "System Events"
+    tell process "iPhone Mirroring"
+        tell window 1
+            return (exists (static text "Connection Paused" of group 1)) as text
+        end tell
+    end tell
+end tell
+'''
+
+_RESUME_SCRIPT = '''
+tell application "System Events"
+    tell process "iPhone Mirroring"
+        tell window 1
+            if exists (static text "Connection Paused" of group 1) then
+                click button 1 of group 1
+                return "clicked"
+            end if
+            return "not-paused"
+        end tell
+    end tell
+end tell
+'''
+
+
+def get_window_info() -> dict | None:
+    """Return the mirroring window's CGWindow record: {"id", "x", "y", "w", "h", "onscreen"}.
+
+    Uses Quartz (pyobjc). Prefers the window literally named "iPhone Mirroring"; otherwise the largest
+    normal-layer window of the process. Returns None when nothing qualifies. The id is what
+    ``screencapture -l`` needs to capture the window's own pixels even when other windows cover it.
+    """
+    try:
+        import Quartz  # type: ignore
+    except ImportError:
+        return None
+    opts = Quartz.kCGWindowListOptionAll | Quartz.kCGWindowListExcludeDesktopElements
+    best = None
+    for w in Quartz.CGWindowListCopyWindowInfo(opts, Quartz.kCGNullWindowID) or []:
+        if w.get("kCGWindowOwnerName") != PROCESS_NAME or w.get("kCGWindowLayer", 0) != 0:
+            continue
+        b = w.get("kCGWindowBounds") or {}
+        rec = {
+            "id": int(w["kCGWindowNumber"]),
+            "x": int(b.get("X", 0)),
+            "y": int(b.get("Y", 0)),
+            "w": int(b.get("Width", 0)),
+            "h": int(b.get("Height", 0)),
+            "onscreen": bool(w.get("kCGWindowIsOnscreen", False)),
+        }
+        if rec["w"] < 50 or rec["h"] < 50:
+            continue
+        if w.get("kCGWindowName") == APP_NAME:
+            return rec
+        if best is None or rec["w"] * rec["h"] > best["w"] * best["h"]:
+            best = rec
+    return best
+
+
+def is_frontmost() -> bool:
+    """True when iPhone Mirroring is the frontmost application."""
+    try:
+        return _run_osascript(_FRONTMOST_SCRIPT) == "true"
+    except WindowError:
+        return False
+
+
+def is_paused() -> bool | None:
+    """True when the window shows "Connection Paused"; None when that cannot be read (e.g. localized UI)."""
+    try:
+        return _run_osascript(_PAUSED_SCRIPT) == "true"
+    except WindowError:
+        return None
+
+
+def resume() -> bool:
+    """Click the Resume control when the session is paused.
+
+    Returns True when the session is not paused afterwards (or was never paused). The phone may still
+    ask for Face ID / passcode on its own screen; that part cannot be automated from the Mac.
+    """
+    import time
+
+    try:
+        out = _run_osascript(_RESUME_SCRIPT)
+    except WindowError:
+        return False
+    if out == "not-paused":
+        return True
+    for _ in range(10):  # up to ~5 s for the stream to come back
+        time.sleep(0.5)
+        if is_paused() is False:
+            return True
+    return False

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noracu",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local, no-cloud MCP server for macOS and Playwright computer-use, plus experimental iPhone. Acts by element index.",
   "type": "module",
   "main": "src/server.mjs",
@@ -28,7 +28,9 @@
     "claude",
     "claude-desktop",
     "claude-code",
-    "cursor"
+    "cursor",
+    "iphone",
+    "iphone-mirroring"
   ],
   "license": "MIT",
   "dependencies": {
@@ -52,6 +54,10 @@
     "README.zh-CN.md",
     "LICENSE",
     "CHANGELOG.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "imctl/README.md",
+    "imctl/LICENSE",
+    "imctl/pyproject.toml",
+    "imctl/src/imctl/*.py"
   ]
 }

package/src/server.mjs

@@ -27,8 +27,8 @@ import { createRequire } from "node:module";
 
 // ── 配置（开源友好：环境变量覆盖 + 同级目录解析）──
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
-// imctl 默认按同级 checkout 解析（…/code/noracu → …/code/imctl），可用 NORACU_IMCTL_DIR 覆盖
-const IMCTL_DIR = process.env.NORACU_IMCTL_DIR || join(__dirname, "..", "..", "imctl");
+// imctl (the iPhone Mirroring driver, Python) ships inside the package at imctl/; NORACU_IMCTL_DIR overrides it (e.g. a dev checkout)
+const IMCTL_DIR = process.env.NORACU_IMCTL_DIR || join(__dirname, "..", "imctl");
 const CLICLICK = process.env.NORACU_CLICLICK || "/opt/homebrew/bin/cliclick";
 if (!existsSync(IMCTL_DIR)) {
   process.stderr.write(`[noracu] warning: imctl not found at ${IMCTL_DIR} — phone_* tools will fail. Set NORACU_IMCTL_DIR.\n`);
@@ -47,23 +47,50 @@ function sh(cmd, args, timeoutMs = 15000) {
   }
 }
 
+// The iPhone layer runs the bundled imctl (Python) and needs an interpreter that has pyobjc (Quartz, Vision, AppKit).
+// Resolution: NORACU_PYTHON if set, else the first candidate that imports Quartz. Probed once, lazily, on the first
+// phone_* call, so the Mac and browser layers pay nothing. Apple's /usr/bin/python3 usually lacks pyobjc; Homebrew's
+// python3 plus the three pyobjc-framework-* packages is the common working setup.
+const PYTHON_CANDIDATES = ["/opt/homebrew/bin/python3", "/usr/local/bin/python3", "python3", "/usr/bin/python3"];
+const PYOBJC_INSTALL = "python3 -m pip install pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-AppKit";
+let pythonProbe = null; // { path, tried } once resolved; path === null when nothing qualified
+function pythonArgv(path) { return path === "python3" ? ["/usr/bin/env", ["python3"]] : [path, []]; }
+function resolvePython() {
+  if (pythonProbe) return pythonProbe;
+  const tried = [];
+  for (const cand of (process.env.NORACU_PYTHON ? [process.env.NORACU_PYTHON] : PYTHON_CANDIDATES)) {
+    const [cmd, pre] = pythonArgv(cand);
+    try {
+      execFileSync(cmd, [...pre, "-c", "import Quartz, Vision, AppKit"], { timeout: 20000, stdio: ["ignore", "ignore", "ignore"] });
+      pythonProbe = { path: cand, tried };
+      return pythonProbe;
+    } catch { tried.push(cand); }
+  }
+  pythonProbe = { path: null, tried };
+  return pythonProbe;
+}
+
 function imctl(...args) {
+  const py = resolvePython();
+  if (!py.path) {
+    return { ok: false, out: `imctl unavailable: no python3 with pyobjc found (tried ${py.tried.join(", ")}) — run \`${PYOBJC_INSTALL}\` for the python3 you want, or set NORACU_PYTHON=/path/to/python3 (see README)` };
+  }
+  const [cmd, pre] = pythonArgv(py.path);
   try {
-    const out = execFileSync("/usr/bin/env", ["python3", "-m", "imctl.cli", ...args], {
+    const out = execFileSync(cmd, [...pre, "-m", "imctl.cli", ...args], {
       timeout: 30000, encoding: "utf8", maxBuffer: 10 * 1024 * 1024,
-      cwd: IMCTL_DIR, env: { ...process.env, PYTHONPATH: join(IMCTL_DIR, "src") },
+      cwd: IMCTL_DIR, env: { ...process.env, PYTHONPATH: join(IMCTL_DIR, "src"), PYTHONDONTWRITEBYTECODE: "1" },
     });
     return { ok: true, out: out.trim() };
   } catch (e) {
     const raw = String(e.stderr || e.stdout || e.message);
-    // imctl 不可用 —— checkout 缺失，或 python3 没有 pyobjc（Quartz）。
-    // 把 Python traceback / spawn 错误收敛成一行可操作信息，phone_* 因此干净失败、测试可据此跳过（优雅降级）。
+    // Collapse Python tracebacks / spawn errors into one actionable line so phone_* fail cleanly and tests can skip (graceful degradation).
     if (/No module named|ModuleNotFoundError|ImportError|Traceback \(most recent/.test(raw)) {
       const mod = (raw.match(/No module named '([^']+)'/) || [])[1];
-      return { ok: false, out: `imctl unavailable: its python3 is missing ${mod ? `the ${mod} module (pyobjc)` : "pyobjc"} — install pyobjc for that python, or point NORACU_IMCTL_DIR at a checkout whose python has it (see README)` };
+      return { ok: false, out: `imctl unavailable: ${py.path} is missing ${mod ? `the ${mod} module` : "a module"} — run \`${PYOBJC_INSTALL}\` for that python, or set NORACU_PYTHON (see README)` };
     }
     if (/ENOENT|No such file or directory/.test(raw)) {
-      return { ok: false, out: `imctl unavailable: cannot run python3 for imctl at ${IMCTL_DIR} — install imctl or set NORACU_IMCTL_DIR (see README)` };
+      return { ok: false, out: `imctl unavailable: cannot run imctl at ${IMCTL_DIR} — the bundled imctl/ directory is missing or NORACU_IMCTL_DIR points to the wrong place (see README)` };
     }
     return { ok: false, out: raw.slice(0, 500) };
   }
@@ -700,21 +727,16 @@ function phoneOpen(args) {
   return imctl("open", args.app);
 }
 function phoneScreenshot() {
-  // Mirroring 窗口截图（imctl status 拿窗口 frame → screencapture -R）
-  const st = imctl("status");
-  if (!st.ok) return { error: "imctl status failed: " + st.out.slice(0, 150) };
+  // Captured by imctl by CGWindow id, so it is the Mirroring window's own pixels even when another window covers it.
+  const file = join(tmpdir(), `noracu-phone-${randomUUID().slice(0, 8)}.png`);
+  const r = imctl("screenshot", file);
+  if (!r.ok) return { error: r.out.slice(0, 300) };
   try {
-    const j = JSON.parse(st.out);
-    const w = j.window;
-    if (!w) return { error: "no mirroring window" };
-    const file = join(tmpdir(), `noracu-phone-${randomUUID().slice(0, 8)}.png`);
-    const r = sh("/usr/sbin/screencapture", ["-x", "-R", `${w.x},${w.y},${w.w},${w.h}`, file]);
-    if (!r.ok) return { error: r.out };
     const data = readFileSync(file).toString("base64");
     unlinkSync(file);
     return { image: data, mime: "image/png" };
   } catch (e) {
-    return { error: "parse status failed: " + String(e.message).slice(0, 150) };
+    return { error: "screenshot file missing: " + String(e.message).slice(0, 150) };
   }
 }
 
@@ -764,20 +786,20 @@ const TOOLS = [
   { name: "browser_evaluate", desc: "Evaluate JavaScript in the page and return the result.", args: { js: "string" }, fn: browserEvaluate },
   { name: "browser_close", desc: "Close the browser.", args: {}, fn: browserClose },
   // iPhone device-use（imctl）
-  { name: "phone_status", desc: "EXPERIMENTAL. Requires imctl (not yet public). Return the iPhone Mirroring session status as JSON.", args: {}, fn: phoneStatus },
-  { name: "phone_launch", desc: "EXPERIMENTAL. Requires imctl (not yet public). Ensure iPhone Mirroring is running and brought to the front.", args: {}, fn: phoneLaunch },
-  { name: "phone_screenshot", desc: "EXPERIMENTAL. Requires imctl (not yet public). Screenshot the iPhone screen (the Mirroring window region).", args: {}, fn: phoneScreenshot },
-  { name: "phone_ocr", desc: "EXPERIMENTAL. Requires imctl (not yet public). OCR the iPhone screen into text with coordinates.", args: {}, fn: phoneOcr },
-  { name: "phone_find", desc: "EXPERIMENTAL. Requires imctl (not yet public). Locate text on the iPhone screen.", args: { text: "string" }, fn: phoneFind },
-  { name: "phone_tap", desc: "EXPERIMENTAL. Requires imctl (not yet public). Tap at {x, y} in normalized 0-1 coordinates.", args: { x: "number", y: "number" }, fn: phoneTap },
-  { name: "phone_longpress", desc: "EXPERIMENTAL. Requires imctl (not yet public). Long-press at {x, y} for an optional duration in seconds.", args: { x: "number", y: "number", duration: "number?" }, fn: phoneLongpress },
-  { name: "phone_swipe", desc: "EXPERIMENTAL. Requires imctl (not yet public). Swipe from [x,y] to [x,y] over an optional duration in ms.", args: { from: "array", to: "array", ms: "number?" }, fn: phoneSwipe },
-  { name: "phone_home", desc: "EXPERIMENTAL. Go to the iPhone Home Screen via the iPhone Mirroring menu (works without imctl when the mirror is connected); falls back to an imctl swipe.", args: {}, fn: phoneHome },
-  { name: "phone_app_switcher", desc: "EXPERIMENTAL. Open the iPhone App Switcher via the iPhone Mirroring menu (works without imctl when the mirror is connected); falls back to an imctl gesture.", args: {}, fn: phoneAppSwitcher },
-  { name: "phone_scroll", desc: "EXPERIMENTAL. Requires imctl (not yet public). Scroll up or down by a distance.", args: { direction: "string?", distance: "number?" }, fn: phoneScroll },
-  { name: "phone_type", desc: "EXPERIMENTAL. Requires imctl (not yet public). Type text via the clipboard (IME-safe).", args: { text: "string" }, fn: phoneType },
-  { name: "phone_key", desc: "EXPERIMENTAL. Requires imctl (not yet public). Press a key: return, delete, up, down, left, or right.", args: { key: "string" }, fn: phoneKey },
-  { name: "phone_open", desc: "EXPERIMENTAL. Requires imctl (not yet public). Open an app via Spotlight search plus OCR-guided tap.", args: { app: "string" }, fn: phoneOpen },
+  { name: "phone_status", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Return the iPhone Mirroring session status as JSON (running, window, onscreen, frontmost, paused).", args: {}, fn: phoneStatus },
+  { name: "phone_launch", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Ensure iPhone Mirroring is running, brought to the front, and resumed if the connection is paused.", args: {}, fn: phoneLaunch },
+  { name: "phone_screenshot", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Screenshot the iPhone screen (the Mirroring window, captured by window id so it works even when covered).", args: {}, fn: phoneScreenshot },
+  { name: "phone_ocr", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. OCR the iPhone screen into text with coordinates.", args: {}, fn: phoneOcr },
+  { name: "phone_find", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Locate text on the iPhone screen.", args: { text: "string" }, fn: phoneFind },
+  { name: "phone_tap", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Tap at {x, y} in normalized 0-1 coordinates.", args: { x: "number", y: "number" }, fn: phoneTap },
+  { name: "phone_longpress", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Long-press at {x, y} for an optional duration in seconds.", args: { x: "number", y: "number", duration: "number?" }, fn: phoneLongpress },
+  { name: "phone_swipe", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Swipe from [x,y] to [x,y] over an optional duration in ms.", args: { from: "array", to: "array", ms: "number?" }, fn: phoneSwipe },
+  { name: "phone_home", desc: "EXPERIMENTAL. Go to the iPhone Home Screen via the iPhone Mirroring menu (works without python/pyobjc when the mirror is connected); falls back to an imctl swipe.", args: {}, fn: phoneHome },
+  { name: "phone_app_switcher", desc: "EXPERIMENTAL. Open the iPhone App Switcher via the iPhone Mirroring menu (works without python/pyobjc when the mirror is connected); falls back to an imctl gesture.", args: {}, fn: phoneAppSwitcher },
+  { name: "phone_scroll", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Scroll up or down by a distance.", args: { direction: "string?", distance: "number?" }, fn: phoneScroll },
+  { name: "phone_type", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Type text via the clipboard (IME-safe).", args: { text: "string" }, fn: phoneType },
+  { name: "phone_key", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Press a key: return, delete, up, down, left, or right.", args: { key: "string" }, fn: phoneKey },
+  { name: "phone_open", desc: "EXPERIMENTAL. Needs iPhone Mirroring and a python3 with pyobjc. Open an app via Spotlight search plus OCR-guided tap.", args: { app: "string" }, fn: phoneOpen },
 ];
 
 // ── 统一参数校验（全工具入口门禁，返回 null=通过 / string=错误）──