@zhihand/mcp 0.26.4 → 0.28.0

package/bin/zhihand

@@ -53,7 +53,10 @@ Usage:
   zhihand pair               Pair with a phone device
   zhihand detect             Detect available CLI tools
 
-  zhihand test               Test device connectivity (sends click + type commands)
+  zhihand list               List all available tests with IDs
+  zhihand test               Run all safe device tests
+  zhihand test <ids>         Run specific test(s), e.g. 'zhihand test 4' or '4,9,20'
+  zhihand test all           Run ALL tests (including unsafe, e.g. power button)
   zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
@@ -286,13 +289,97 @@ switch (command) {
     break;
   }
 
+  case "list":
   case "test": {
     const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.js");
-    const { createControlCommand, enqueueCommand } = await import("../dist/core/command.js");
+    const { createControlCommand, createSystemCommand, enqueueCommand } = await import("../dist/core/command.js");
     const { waitForCommandAck } = await import("../dist/core/sse.js");
     const { fetchScreenshotBinary } = await import("../dist/core/screenshot.js");
     const { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded, formatDeviceStatus } = await import("../dist/core/device.js");
 
+    // ── Test Registry ────────────────────────────────────────
+    // Kind: "profile" | "status" | "screenshot" | "hid" | "system"
+    // Platform: undefined | "android" | "ios" (skipped on non-matching)
+    // Unsafe: won't run in full-suite unless explicitly requested
+    const REGISTRY = [
+      // Phase A — Device Info API
+      { id: 1, phase: "Device Info", label: "Fetch device profile", kind: "profile" },
+      { id: 2, phase: "Device Info", label: "Device status fields", kind: "status" },
+      // Phase B — Screenshot
+      { id: 3, phase: "Screenshot", label: "Screenshot", kind: "screenshot" },
+      // Phase C — Tap / Touch
+      { id: 4, phase: "Tap/Touch", label: "Click center", kind: "hid", params: { action: "click", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 5, phase: "Tap/Touch", label: "Double click", kind: "hid", params: { action: "doubleclick", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 6, phase: "Tap/Touch", label: "Long click (800ms)", kind: "hid", params: { action: "longclick", xRatio: 0.5, yRatio: 0.5, durationMs: 800 } },
+      { id: 7, phase: "Tap/Touch", label: "Right click", kind: "hid", params: { action: "rightclick", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 8, phase: "Tap/Touch", label: "Middle click", kind: "hid", params: { action: "middleclick", xRatio: 0.5, yRatio: 0.5 } },
+      // Phase D — Swipe / Scroll
+      { id: 9, phase: "Swipe/Scroll", label: "Swipe up", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 } },
+      { id: 10, phase: "Swipe/Scroll", label: "Swipe down", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 } },
+      { id: 11, phase: "Swipe/Scroll", label: "Swipe left", kind: "hid", params: { action: "swipe", startXRatio: 0.7, startYRatio: 0.5, endXRatio: 0.3, endYRatio: 0.5, durationMs: 300 } },
+      { id: 12, phase: "Swipe/Scroll", label: "Swipe right", kind: "hid", params: { action: "swipe", startXRatio: 0.3, startYRatio: 0.5, endXRatio: 0.7, endYRatio: 0.5, durationMs: 300 } },
+      { id: 13, phase: "Swipe/Scroll", label: "Scroll down", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 } },
+      { id: 14, phase: "Swipe/Scroll", label: "Scroll up", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 } },
+      // Phase E — Text + Keys
+      { id: 15, phase: "Text+Keys", label: "Type text", kind: "hid", params: { action: "type", text: "zhihand" } },
+      { id: 16, phase: "Text+Keys", label: "Enter key", kind: "hid", params: { action: "enter" } },
+      { id: 17, phase: "Text+Keys", label: "Key combo (select all)", kind: "hid", platformAware: "select_all" },
+      // Phase F — App Navigation
+      { id: 18, phase: "Navigation", label: "Press Home", kind: "hid", params: { action: "home" } },
+      { id: 19, phase: "Navigation", label: "Press Back", kind: "hid", params: { action: "back" } },
+      { id: 20, phase: "Navigation", label: "Open WeChat", kind: "hid", platformAware: "open_wechat" },
+      // Phase G — Clipboard
+      { id: 21, phase: "Clipboard", label: "Clipboard set", kind: "hid", platformAware: "clipboard_set" },
+      // Phase H — System Navigation
+      { id: 22, phase: "System Nav", label: "Notification shade", kind: "system", params: { action: "notification" } },
+      { id: 23, phase: "System Nav", label: "Recent apps", kind: "system", params: { action: "recent" } },
+      { id: 24, phase: "System Nav", label: "Search (query='zhihand')", kind: "system", params: { action: "search", text: "zhihand" } },
+      { id: 25, phase: "System Nav", label: "Switch input", kind: "system", params: { action: "switch_input" } },
+      { id: 26, phase: "System Nav", label: "Siri", kind: "system", params: { action: "siri" }, platform: "ios" },
+      { id: 27, phase: "System Nav", label: "Control Center", kind: "system", params: { action: "control_center" }, platform: "ios" },
+      { id: 28, phase: "System Nav", label: "Open browser", kind: "system", params: { action: "open_browser" }, platform: "android" },
+      { id: 29, phase: "System Nav", label: "Shortcut help", kind: "system", params: { action: "shortcut_help" }, platform: "android" },
+      // Phase I — Media
+      { id: 30, phase: "Media", label: "Volume up", kind: "system", params: { action: "volume_up" } },
+      { id: 31, phase: "Media", label: "Volume down", kind: "system", params: { action: "volume_down" } },
+      { id: 32, phase: "Media", label: "Mute toggle", kind: "system", params: { action: "mute" } },
+      { id: 33, phase: "Media", label: "Play/Pause", kind: "system", params: { action: "play_pause" } },
+      { id: 34, phase: "Media", label: "Next track", kind: "system", params: { action: "next_track" } },
+      { id: 35, phase: "Media", label: "Prev track", kind: "system", params: { action: "prev_track" } },
+      { id: 36, phase: "Media", label: "Fast forward", kind: "system", params: { action: "fast_forward" } },
+      { id: 37, phase: "Media", label: "Rewind", kind: "system", params: { action: "rewind" } },
+      { id: 38, phase: "Media", label: "Stop", kind: "system", params: { action: "stop" } },
+      // Phase J — Hardware
+      { id: 39, phase: "Hardware", label: "Brightness up", kind: "system", params: { action: "brightness_up" } },
+      { id: 40, phase: "Hardware", label: "Brightness down", kind: "system", params: { action: "brightness_down" } },
+      { id: 41, phase: "Hardware", label: "Power button (⚠️ may lock screen)", kind: "system", params: { action: "power" }, unsafe: true },
+    ];
+
+    // ── "list" sub-command ───────────────────────────────────
+    if (command === "list") {
+      console.log("📋 ZhiHand Test Registry\n");
+      let currentPhase = "";
+      for (const t of REGISTRY) {
+        if (t.phase !== currentPhase) {
+          console.log(`\n   ── ${t.phase} ──`);
+          currentPhase = t.phase;
+        }
+        const tags = [];
+        if (t.platform) tags.push(`${t.platform}-only`);
+        if (t.unsafe) tags.push("unsafe");
+        const tagStr = tags.length ? ` [${tags.join(", ")}]` : "";
+        console.log(`   ${String(t.id).padStart(2)}. ${t.label}${tagStr}`);
+      }
+      console.log(`\n   Total: ${REGISTRY.length} tests`);
+      console.log("\nUsage:");
+      console.log("   zhihand test            # run all safe tests");
+      console.log("   zhihand test 4          # run test #4 only");
+      console.log("   zhihand test 4,9,20     # run tests #4, #9, #20");
+      console.log("   zhihand test all        # run ALL tests (including unsafe)");
+      process.exit(0);
+    }
+
+    // ── "test" sub-command ───────────────────────────────────
     let testConfig;
     try {
       testConfig = resolveTestConfig(values.device ?? process.env.ZHIHAND_DEVICE);
@@ -302,152 +389,219 @@ switch (command) {
       process.exit(1);
     }
 
+    // Parse which tests to run from positional args
+    const filterArg = positionals[1];  // e.g. "4" or "4,9,20" or "all"
+    let selectedIds = null;   // null = default (all safe)
+    let includeUnsafe = false;
+    if (filterArg) {
+      if (filterArg === "all") {
+        includeUnsafe = true;
+      } else {
+        selectedIds = new Set(
+          filterArg.split(",").map((s) => {
+            const trimmed = s.trim();
+            const n = Number(trimmed);
+            // Strict: reject ranges like "4-10" (Number returns NaN), floats, empty
+            return Number.isInteger(n) && n > 0 ? n : NaN;
+          }).filter((n) => !isNaN(n))
+        );
+        if (selectedIds.size === 0) {
+          console.error(`Invalid test IDs: ${filterArg}`);
+          console.error("Run 'zhihand list' to see available tests.");
+          process.exit(1);
+        }
+        // Explicit selection implies user knows what they're doing
+        includeUnsafe = true;
+      }
+    }
+
     console.log("🧪 ZhiHand Device Test");
     console.log(`   Device: ${testConfig.credentialId}`);
     console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
 
+    // Pre-fetch device profile so platform-aware tests work.
+    // Note: platform is read dynamically via getDevicePlatform() so Test 1
+    // (Fetch device profile) can populate it before later tests consume it.
+    try {
+      await fetchDeviceProfile(testConfig);
+    } catch { /* non-fatal — Test 1 will retry and platform will update */ }
+    const getDevicePlatform = () => isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
+
     let passed = 0;
     let failed = 0;
+    let skipped = 0;
     let totalSteps = 0;
 
-    // ── Helper: run a single HID step ──
-    async function runHidStep(label, params) {
+    // ── Resolve platform-aware params (evaluated at test time) ──
+    function resolvePlatformAwareParams(variant) {
+      const platform = getDevicePlatform();
+      if (variant === "open_wechat") {
+        return platform === "ios"
+          ? { action: "open_app", bundleId: "com.tencent.xin" }
+          : { action: "open_app", appPackage: "com.tencent.mm" };
+      }
+      if (variant === "clipboard_set") {
+        return { action: "clipboard", text: `zhihand_test_${Date.now()}` };
+      }
+      if (variant === "select_all") {
+        const keys = platform === "ios" ? "cmd+a" : "ctrl+a";
+        return { action: "keycombo", keys };
+      }
+      return null;
+    }
+
+    // ── Test runners (shared ACK logic) ──
+    async function runCommandTest(t, command) {
       totalSteps++;
-      process.stdout.write(`   ${label}... `);
+      process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
       const t0 = Date.now();
       try {
-        const cmd = createControlCommand(params);
-        const queued = await enqueueCommand(testConfig, cmd);
+        const queued = await enqueueCommand(testConfig, command);
         const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
         const ms = Date.now() - t0;
         if (ack.acked) {
           const ackStatus = ack.command?.ack_status ?? "ok";
-          const detail = ackStatus !== "ok" ? ` [${ackStatus}]` : "";
           const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
-          console.log(`✅ (${ms}ms)${detail}${resultInfo}`);
-          passed++;
-          return ack;
+          if (ackStatus === "ok") {
+            console.log(`✅ (${ms}ms)${resultInfo}`);
+            passed++;
+          } else {
+            console.log(`❌ [${ackStatus}] (${ms}ms)${resultInfo}`);
+            failed++;
+          }
         } else {
           console.log(`⏱️  Timeout (${ms}ms)`);
           failed++;
-          return null;
         }
       } catch (err) {
         console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
         failed++;
-        return null;
       }
     }
 
-    // ── Helper: run a screenshot step ──
-    async function runScreenshotStep(label) {
-      totalSteps++;
-      process.stdout.write(`   ${label}... `);
-      const t0 = Date.now();
-      try {
-        const cmd = createControlCommand({ action: "screenshot" });
-        const queued = await enqueueCommand(testConfig, cmd);
-        const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
-        if (ack.acked) {
-          const buf = await fetchScreenshotBinary(testConfig);
-          const ms = Date.now() - t0;
-          console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${ms}ms)`);
-          passed++;
-        } else {
-          console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
-          failed++;
+    async function runSingleTest(t) {
+      // Platform skip (evaluated at test time — Test 1 may have just populated the profile)
+      const currentPlatform = getDevicePlatform();
+      if (t.platform && t.platform !== currentPlatform) {
+        totalSteps++;
+        skipped++;
+        console.log(`   ${String(t.id).padStart(2)}. ${t.label}... ⏭️  Skipped (${t.platform}-only, device is ${currentPlatform})`);
+        return;
+      }
+
+      switch (t.kind) {
+        case "profile": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          const t0 = Date.now();
+          try {
+            await fetchDeviceProfile(testConfig);
+            const ms = Date.now() - t0;
+            if (isDeviceProfileLoaded()) {
+              const s = getStaticContext();
+              console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
+              passed++;
+            } else {
+              console.log(`⚠️  Loaded but empty (${ms}ms)`);
+              failed++;
+            }
+          } catch (err) {
+            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            failed++;
+          }
+          break;
+        }
+        case "status": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          try {
+            const status = formatDeviceStatus();
+            const ignoredDefaults = new Set(["unknown", "0x0", "-1% (unknown)", "0"]);
+            const fields = Object.keys(status).filter((k) => {
+              const v = status[k];
+              if (v === null || v === undefined) return false;
+              if (ignoredDefaults.has(String(v))) return false;
+              return true;
+            });
+            console.log(`✅ ${fields.length} fields (${fields.join(", ")})`);
+            passed++;
+          } catch (err) {
+            console.log(`❌ ${err.message}`);
+            failed++;
+          }
+          break;
+        }
+        case "screenshot": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          const t0 = Date.now();
+          try {
+            const cmd = createControlCommand({ action: "screenshot" });
+            const queued = await enqueueCommand(testConfig, cmd);
+            const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+            if (ack.acked) {
+              const buf = await fetchScreenshotBinary(testConfig);
+              console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${Date.now() - t0}ms)`);
+              passed++;
+            } else {
+              console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+              failed++;
+            }
+          } catch (err) {
+            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            failed++;
+          }
+          break;
+        }
+        case "hid": {
+          const params = t.platformAware ? resolvePlatformAwareParams(t.platformAware) : t.params;
+          await runCommandTest(t, createControlCommand(params));
+          break;
+        }
+        case "system": {
+          await runCommandTest(t, createSystemCommand(t.params));
+          break;
         }
-      } catch (err) {
-        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
-        failed++;
       }
     }
 
     const pause = () => new Promise((r) => setTimeout(r, 1500));
 
-    // ── Phase 1: Device Profile ──────────────────────────────
-    console.log("   ── Phase 1: Device Info ──");
-    totalSteps++;
-    process.stdout.write("   1. Fetch device profile... ");
-    {
-      const t0 = Date.now();
-      try {
-        await fetchDeviceProfile(testConfig);
-        const ms = Date.now() - t0;
-        if (isDeviceProfileLoaded()) {
-          const s = getStaticContext();
-          console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
-          passed++;
-        } else {
-          console.log(`⚠️  Loaded but empty (${ms}ms)`);
-          failed++;
-        }
-      } catch (err) {
-        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
-        failed++;
-      }
+    // Select tests to run
+    const toRun = REGISTRY.filter((t) => {
+      if (selectedIds) return selectedIds.has(t.id);
+      if (t.unsafe && !includeUnsafe) return false;
+      return true;
+    });
+
+    if (toRun.length === 0) {
+      console.error("No matching tests.");
+      console.error("Run 'zhihand list' to see available tests.");
+      process.exit(1);
     }
 
-    totalSteps++;
-    process.stdout.write("   2. Device status fields... ");
-    {
-      try {
-        const status = formatDeviceStatus();
-        const ignoredDefaults = new Set(["unknown", "0x0", "-1% (unknown)", "0"]);
-        const fields = Object.keys(status).filter((k) => {
-          const v = status[k];
-          if (v === null || v === undefined) return false;
-          if (ignoredDefaults.has(String(v))) return false;
-          return true;
-        });
-        console.log(`✅ ${fields.length} fields (${fields.join(", ")})`);
-        passed++;
-      } catch (err) {
-        console.log(`❌ ${err.message}`);
-        failed++;
+    // Warn about missing IDs
+    if (selectedIds) {
+      const foundIds = new Set(toRun.map((t) => t.id));
+      const missing = [...selectedIds].filter((id) => !foundIds.has(id));
+      if (missing.length) {
+        console.warn(`⚠️  Unknown test IDs: ${missing.join(", ")}`);
       }
     }
 
-    await pause();
-
-    // ── Phase 2: Screenshot + Basic HID ──────────────────────
-    console.log("   ── Phase 2: Screenshot + HID ──");
-    await runScreenshotStep("3. Screenshot");
-    await pause();
-    await runHidStep("4. Click center", { action: "click", xRatio: 0.5, yRatio: 0.5 });
-    await pause();
-    await runHidStep("5. Swipe up", { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 });
-    await pause();
-    await runHidStep("6. Swipe down", { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 });
-    await pause();
-    await runHidStep("7. Scroll down", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 });
-    await pause();
-    await runHidStep("8. Scroll up", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 });
-    await pause();
-
-    // ── Phase 3: App + Navigation ────────────────────────────
-    console.log("   ── Phase 3: App + Navigation ──");
-    await runHidStep("9. Press Home", { action: "home" });
-    await pause();
-    {
-      const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "android";
-      const openParams = platform === "ios"
-        ? { action: "open_app", bundleId: "com.tencent.xin" }
-        : { action: "open_app", appPackage: "com.tencent.mm" };
-      await runHidStep(`10. Open WeChat (${platform})`, openParams);
+    let currentPhase = "";
+    for (let i = 0; i < toRun.length; i++) {
+      const t = toRun[i];
+      if (t.phase !== currentPhase) {
+        console.log(`   ── ${t.phase} ──`);
+        currentPhase = t.phase;
+      }
+      await runSingleTest(t);
+      if (i < toRun.length - 1) await pause();
     }
-    await pause();
-    await runHidStep("11. Press Back", { action: "back" });
-    await pause();
-
-    // ── Phase 4: Clipboard Set ─────────────────────────────
-    // Note: App only supports clipboard set, not get
-    console.log("   ── Phase 4: Clipboard ──");
-    const clipboardTestText = `zhihand_test_${Date.now()}`;
-    await runHidStep("12. Clipboard set", { action: "clipboard", text: clipboardTestText });
 
     // ── Summary ──────────────────────────────────────────────
-    console.log(`\n   Result: ${passed}/${totalSteps} passed`);
+    console.log(`\n   Result: ${passed}/${totalSteps} passed, ${failed} failed, ${skipped} skipped`);
     if (failed === 0) {
       console.log("   ✅ All tests passed! Device is fully responsive.");
     } else {

package/dist/core/command.d.ts

@@ -37,6 +37,11 @@ export interface WaitForCommandAckResult {
     command?: QueuedCommandRecord;
 }
 export declare function createControlCommand(params: ControlParams): QueuedControlCommand;
+export interface SystemParams {
+    action: string;
+    text?: string;
+}
+export declare function createSystemCommand(params: SystemParams): QueuedControlCommand;
 export declare function enqueueCommand(config: ZhiHandConfig, command: QueuedControlCommand): Promise<QueuedCommandRecord>;
 export declare function getCommand(config: ZhiHandConfig, commandId: string): Promise<QueuedCommandRecord>;
 export declare function formatAckSummary(action: string, result: WaitForCommandAckResult): string;

package/dist/core/command.js

@@ -93,6 +93,65 @@ export function createControlCommand(params) {
             throw new Error(`Unsupported action: ${params.action}`);
     }
 }
+const IOS_ONLY_ACTIONS = new Set(["siri", "control_center"]);
+const ANDROID_ONLY_ACTIONS = new Set(["open_browser", "shortcut_help"]);
+export function createSystemCommand(params) {
+    const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
+    // Platform validation — block mismatched platform-specific actions
+    if (platform === "android" && IOS_ONLY_ACTIONS.has(params.action)) {
+        throw new Error(`Action '${params.action}' is not supported on Android.`);
+    }
+    if (platform === "ios" && ANDROID_ONLY_ACTIONS.has(params.action)) {
+        throw new Error(`Action '${params.action}' is not supported on iOS.`);
+    }
+    switch (params.action) {
+        // System navigation
+        case "notification":
+            return { type: "receive_notification", payload: {} };
+        case "recent":
+            return { type: "receive_recent", payload: {} };
+        case "search":
+            return { type: "receive_search", payload: { query: params.text ?? "" } };
+        case "switch_input":
+            return { type: "receive_switch_input", payload: {} };
+        case "siri":
+            return { type: "receive_siri", payload: {} };
+        case "control_center":
+            return { type: "receive_control_center", payload: {} };
+        case "open_browser":
+            return { type: "receive_open_browser", payload: {} };
+        case "shortcut_help":
+            return { type: "receive_shortcut_help", payload: {} };
+        // Media controls
+        case "volume_up":
+            return { type: "receive_volume_up", payload: {} };
+        case "volume_down":
+            return { type: "receive_volume_down", payload: {} };
+        case "mute":
+            return { type: "receive_mute", payload: {} };
+        case "play_pause":
+            return { type: "receive_play_pause", payload: {} };
+        case "stop":
+            return { type: "receive_stop", payload: {} };
+        case "next_track":
+            return { type: "receive_next_track", payload: {} };
+        case "prev_track":
+            return { type: "receive_prev_track", payload: {} };
+        case "fast_forward":
+            return { type: "receive_fast_forward", payload: {} };
+        case "rewind":
+            return { type: "receive_rewind", payload: {} };
+        // Hardware
+        case "brightness_up":
+            return { type: "receive_brightness_up", payload: {} };
+        case "brightness_down":
+            return { type: "receive_brightness_down", payload: {} };
+        case "power":
+            return { type: "receive_power", payload: {} };
+        default:
+            throw new Error(`Unsupported system action: ${params.action}`);
+    }
+}
 export async function enqueueCommand(config, command) {
     const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands`;
     const body = { command: { ...command, message_id: command.messageId ?? nextMessageId() } };

package/dist/core/device.d.ts

@@ -43,5 +43,6 @@ export declare function extractDynamic(profile: Record<string, unknown>): Dynami
 export declare function updateDeviceProfile(raw: Record<string, unknown>): void;
 export declare function fetchDeviceProfile(config: ZhiHandConfig): Promise<void>;
 export declare function buildControlToolDescription(): string;
+export declare function buildSystemToolDescription(): string;
 export declare function buildScreenshotToolDescription(): string;
 export declare function formatDeviceStatus(): Record<string, unknown>;

package/dist/core/device.js

@@ -176,6 +176,28 @@ export function buildControlToolDescription() {
     }
     return desc;
 }
+export function buildSystemToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "System navigation and media controls. Actions: notification, recent, search, switch_input, siri (iOS), control_center (iOS), open_browser (Android), shortcut_help (Android), volume_up/down, mute, play_pause, stop, next/prev_track, fast_forward, rewind, brightness_up/down, power.";
+    }
+    const platform = staticCtx.platform;
+    const parts = [
+        `System navigation and media controls for ${platform} device (${staticCtx.model}).`,
+    ];
+    // Navigation
+    parts.push("Navigation: notification, recent, search (optional text query), switch_input.");
+    if (platform === "ios") {
+        parts.push("iOS: siri, control_center.");
+    }
+    else if (platform === "android") {
+        parts.push("Android: open_browser, shortcut_help.");
+    }
+    // Media
+    parts.push("Media: volume_up, volume_down, mute, play_pause, stop, next_track, prev_track, fast_forward, rewind.");
+    // Hardware
+    parts.push("Hardware: brightness_up, brightness_down, power.");
+    return parts.join(" ");
+}
 export function buildScreenshotToolDescription() {
     if (!loaded || staticCtx.platform === "unknown") {
         return "Take a screenshot of the phone screen.";

package/dist/daemon/dispatcher.js

@@ -372,6 +372,17 @@ function buildSystemContext() {
     else {
         openAppDoc = "- open_app: Open an app. Params: appPackage (Android, e.g. 'com.tencent.mm'), bundleId (iOS), urlScheme (e.g. 'weixin://')";
     }
+    // Platform-specific system actions
+    let platformSystemDoc;
+    if (static_?.platform === "ios") {
+        platformSystemDoc = "- siri: Activate Siri\n- control_center: Open Control Center";
+    }
+    else if (static_?.platform === "android") {
+        platformSystemDoc = "- open_browser: Launch default browser\n- shortcut_help: Show keyboard shortcuts overlay";
+    }
+    else {
+        platformSystemDoc = "- siri: Activate Siri (iOS only)\n- control_center: Open Control Center (iOS only)\n- open_browser: Launch default browser (Android only)\n- shortcut_help: Show keyboard shortcuts overlay (Android only)";
+    }
     return `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
 
 ## Device
@@ -401,13 +412,35 @@ ${openAppDoc}
 - screenshot: Capture screen via control (same as zhihand_screenshot)
 - wait: Wait before next action. Params: durationMs (default 1000)
 
+### zhihand_system
+System navigation and media controls. Requires "action" parameter.
+
+**System navigation:**
+- notification: Open notification shade/center
+- recent: Show app switcher / recent apps
+- search: Open system search. Optional "text" param to type query after opening
+- switch_input: Switch input method (only works in text input fields)
+${platformSystemDoc}
+
+**Media controls:**
+- volume_up / volume_down: Adjust volume
+- mute: Toggle mute
+- play_pause / stop: Playback control
+- next_track / prev_track: Skip track
+- fast_forward / rewind: Seek
+
+**Hardware:**
+- brightness_up / brightness_down: Adjust brightness
+- power: Press power button
+
 ### zhihand_status
 Get device status: platform, battery, network, BLE connection, dark mode, storage, etc.
 
 ## Rules
 - When the user asks to see their screen, ALWAYS call zhihand_screenshot first.
-- When the user asks to open an app (e.g. WeChat, Settings), use open_app action.
-- When the user asks to go back/home, use back/home actions.
+- When the user asks to open an app (e.g. WeChat, Settings), use open_app action with zhihand_control.
+- When the user asks to go back/home, use back/home actions with zhihand_control.
+- For system functions (notifications, volume, brightness, media), use zhihand_system.
 - For all tap/click operations, use xRatio and yRatio (0-1 normalized coordinates based on the screenshot).`;
 }
 /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const PACKAGE_VERSION = "0.26.4";
+export declare const PACKAGE_VERSION = "0.28.0";
 export declare function createServer(deviceName?: string): McpServer;
 export declare function startStdioServer(deviceName?: string): Promise<void>;

package/dist/index.js

@@ -1,12 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { resolveConfig } from "./core/config.js";
-import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { controlSchema, systemSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
 import { executeControl } from "./tools/control.js";
+import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.26.4";
+import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+export const PACKAGE_VERSION = "0.28.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",
@@ -18,6 +19,11 @@ export function createServer(deviceName) {
         const config = resolveConfig(deviceName);
         return await executeControl(config, params);
     });
+    // zhihand_system — system navigation + media controls (separate tool per Gemini design review)
+    server.tool("zhihand_system", buildSystemToolDescription(), systemSchema, async (params) => {
+        const config = resolveConfig(deviceName);
+        return await executeSystem(config, params);
+    });
     // zhihand_screenshot — capture current screen without any action
     server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
         const config = resolveConfig(deviceName);

package/dist/tools/schemas.d.ts

@@ -16,6 +16,10 @@ export declare const controlSchema: {
     bundleId: z.ZodOptional<z.ZodString>;
     urlScheme: z.ZodOptional<z.ZodString>;
 };
+export declare const systemSchema: {
+    action: z.ZodEnum<["notification", "recent", "search", "switch_input", "siri", "control_center", "open_browser", "shortcut_help", "volume_up", "volume_down", "mute", "play_pause", "stop", "next_track", "prev_track", "fast_forward", "rewind", "brightness_up", "brightness_down", "power"]>;
+    text: z.ZodOptional<z.ZodString>;
+};
 export declare const screenshotSchema: {};
 export declare const pairSchema: {
     forceNew: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;

package/dist/tools/schemas.js

@@ -23,6 +23,24 @@ export const controlSchema = {
     bundleId: z.string().optional().describe("iOS bundle ID, e.g. 'com.tencent.xin'"),
     urlScheme: z.string().optional().describe("URL scheme, e.g. 'weixin://'"),
 };
+// zhihand_system — system navigation + media controls (separate from UI control)
+export const systemSchema = {
+    action: z.enum([
+        // System navigation — cross-platform
+        "notification", "recent", "search", "switch_input",
+        // System navigation — iOS only
+        "siri", "control_center",
+        // System navigation — Android only
+        "open_browser", "shortcut_help",
+        // Media controls — cross-platform
+        "volume_up", "volume_down", "mute",
+        "play_pause", "stop", "next_track", "prev_track",
+        "fast_forward", "rewind",
+        // Hardware — cross-platform
+        "brightness_up", "brightness_down", "power",
+    ]).describe("System or media action to perform"),
+    text: z.string().optional().describe("Optional text, e.g. search query for 'search' action"),
+};
 export const screenshotSchema = {};
 export const pairSchema = {
     forceNew: z.boolean().default(false).optional().describe("Force new pairing even if already paired"),

package/dist/tools/system.d.ts

@@ -0,0 +1,17 @@
+/**
+ * zhihand_system tool handler — system navigation + media controls.
+ *
+ * Separated from zhihand_control to keep UI-control schema focused and
+ * reduce LLM parameter hallucination (Gemini design review recommendation).
+ */
+import type { ZhiHandConfig } from "../core/config.ts";
+import type { SystemParams } from "../core/command.ts";
+type TextContent = {
+    type: "text";
+    text: string;
+};
+type ToolResult = {
+    content: TextContent[];
+};
+export declare function executeSystem(config: ZhiHandConfig, params: SystemParams): Promise<ToolResult>;
+export {};

package/dist/tools/system.js

@@ -0,0 +1,11 @@
+import { createSystemCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
+import { waitForCommandAck } from "../core/sse.js";
+export async function executeSystem(config, params) {
+    const command = createSystemCommand(params);
+    const queued = await enqueueCommand(config, command);
+    const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
+    const summary = formatAckSummary(params.action, ack);
+    return {
+        content: [{ type: "text", text: summary }],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.26.4",
+  "version": "0.28.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",