cortico-world-hands 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# cortico-world-hands
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 Coopanin 的桌宠一双手：看屏幕、点、长按、滑、敲字、按键——并且每一下都说明白成没成。
+
+这是 Cortico 的一个 `world` 扩展（`cortico.kind = "world"`，`api = 6`），和桌宠、cua 平级挂载，
+共用同一份会话和同一个工具表。它不画身体、不出声，只提供八个工具和一块状态灯：
+`hand_look`、`hand_tap`、`hand_long`、`hand_swipe`、`hand_type`、`hand_key`、`hand_status`、`hand_stop`。
+
+## 手怎么动：三条通道
+
+| 通道 | 需要什么 | 能做什么 |
+|---|---|---|
+| `root` | 本机有 root，并授权给 Coopanin | `su -c "input …"`：点、长按、滑、按键、敲 ASCII 文本 |
+| `eyes` | 安卓壳里的无障碍服务带 `/hand/*` 手势端点（`android/HAND_ROUTES.md`） | `dispatchGesture` + `ACTION_SET_TEXT`：不限 ASCII，中文也能进；还会画一只看得见的手 |
+| `shell` | 一条命令模板，例如 `rish -c "{cmd}"` 或 `adb -s … shell "{cmd}"` | 同 root 那套 `input`，只是换个执行者 |
+
+`actuator: "auto"`（默认）按 root → eyes → shell 的顺序探，探到能用为止；都不通时**不假装能干活**，
+工具会失败并说清缺什么。`actuator: "off"` 就是彻底关掉。
+
+默认 `enabled: false`：装上以后要自己打开。
+
+## 安全阀
+
+- **演练**（`dryRun`）：只把「本来要做什么」说出来，一个动作都不发。先在演练里看模型想干什么，再开真动。
+- **节流**（`maxActionsPerMinute`，默认 30）：一分钟到量就停手，防止模型在屏幕上乱戳。
+- **叫停**：`hand_stop` 之后一分钟内不再动任何一下。
+- **锁屏 / 黑屏不点**：动之前先问一下感觉桥（`/state`），锁着或黑着直接失败。
+- **越界不点**：能从眼睛拿到屏幕尺寸时，坐标超出就拒。
+- **只做校验过的命令**：坐标是整数、按键是固定表、文本先转义；拼出来的是 `input tap 512 1500` 这种
+  不可能注入的形状，`su -c` 里也没有管道、重定向、变量。
+
+## 装法
+
+两种，二选一：
+
+1. **并进 payload**（推荐，和桌宠一起长在应用里）：在 `app/coop-stage` 那层跑
+   `node apply-hands.mjs --stage . --apply`，然后把 payload 重新打包进 APK。
+2. **当扩展装**：把本包放到 `<stage>/data/extensions/` 下、在 `data/extensions/package.json` 的
+   `dependencies` 里加上 `"cortico-world-hands": "file:./…"`，重启 Core，然后在控制台「世界」里打开它。
+   （控制台的扩展页也支持「从本地目录安装」，路径要能被应用进程读到。）
+
+打开后到「手」的设置里选通道：没 root 就 `eyes`（要安卓壳带手势端点），有 root 就 `root`。
+
+## 环境提示词
+
+`src/ENV_PROMPT.md` 是这只手给模型看的说明书：先看再动、不替人做主、不碰密码和支付、点错要承认。
+它在控制台的「提示词」页可以改，改的是部署里的覆盖文件，不动包里的模板。

package/dist/ENV_PROMPT.md

@@ -0,0 +1,29 @@
+## 手
+
+你有一双手，能碰到对方手机屏幕上真的东西。手现在{{hands.state}}，走的是{{hands.actuator}}；模式是{{hands.mode}}；{{hands.window}}。
+
+手不像桌宠的身体那样被看见：对方只看到屏幕自己动了一下。所以**做完要说**：刚点了哪里、为什么点，一两句，别报流水账。
+
+### 先看，再动
+
+动手之前先用 `hand_look`（默认连画面一起给你）。它会告诉你前台是哪个应用、屏幕亮不亮、锁没锁、屏幕上的字各自在哪个坐标（`@(x,y)` 就是能点的位置）。看不清再看一眼；**别凭记忆去点**——应用会滚动、会弹窗、会自己跳走。
+
+### 能做什么
+
+| 工具 | 用途 |
+|---|---|
+| `hand_tap` | 点一下。给坐标，或给一段文字（只有一处对得上才点，多处会列出来让你选 `nth`）。 |
+| `hand_long` | 长按，默认 800 毫秒：弹菜单、选中、拖东西前按住。 |
+| `hand_swipe` | 从一点滑到另一点：滚动、翻页、下拉通知栏。 |
+| `hand_type` | 敲字。先点一下输入框把光标放进去。走 `input` 通道时只有可打印 ASCII（中文会失败并告诉你）；走无障碍通道时中文也能进。 |
+| `hand_key` | 按 back/home/recents/enter/delete 这些系统键，比在屏幕上找返回按钮稳。 |
+| `hand_status` | 手自己通不通、这一分钟动了几下、刚才成了没有。 |
+| `hand_stop` | 立刻停手一分钟。对方说「别动了」时用它。 |
+
+### 规矩
+
+- **别人的东西别替人做主**：发消息、下单、转账、删东西、改设置这类做完就收不回来的事，先把「要做什么」说清楚并等对方同意，再动手；对方没说清就只做第一步然后问。
+- **不输密码、不输验证码、不碰支付界面**。看到这类界面就停下来说明。
+- **点错就承认**：动作失败或点歪了不要编，说清楚点到了什么、现在屏幕是什么样。
+- 一次唤醒里别连点超过三下同一种动作；三下没进展就停下来问对方，别在屏幕上乱戳。
+- 对方在用手机（手自己动会被抢）时，动作可能被吃掉；结果是失败就照实说，不要重试同样的位置超过一次。

package/dist/index.js

@@ -0,0 +1,1079 @@
+// src/config.ts
+var HANDS_ID = "hands";
+var HANDS_DEFAULTS = {
+  enabled: false,
+  actuator: "auto",
+  eyesPort: 17898,
+  sensePort: 17899,
+  rootCommand: "su",
+  shellCommand: "",
+  token: "",
+  tokenFile: "/proc/self/root/data/data/com.palai.prootsmoke/files/hand.token",
+  dryRun: false,
+  maxActionsPerMinute: 30,
+  maxTextLength: 200,
+  lookAttach: true,
+  lookMaxWidth: 720,
+  lookQuality: 60
+};
+var KEY_CODES = {
+  back: 4,
+  home: 3,
+  recents: 187,
+  enter: 66,
+  delete: 67,
+  tab: 61,
+  escape: 111,
+  space: 62,
+  up: 19,
+  down: 20,
+  left: 21,
+  right: 22,
+  volumeup: 24,
+  volumedown: 25,
+  power: 26,
+  search: 84,
+  menu: 82
+};
+var K = `worlds.${HANDS_ID}`;
+var HANDS_CONFIG_GROUP = {
+  id: `world:${HANDS_ID}`,
+  owner: `world:${HANDS_ID}`,
+  schema: {
+    type: "object",
+    title: "\u624B",
+    properties: {
+      [`${K}.actuator`]: {
+        type: "string",
+        title: "\u624B\u8D70\u54EA\u6761\u901A\u9053",
+        enum: ["auto", "root", "eyes", "shell", "off"],
+        description: "auto \u4F9D\u6B21\u8BD5 root\uFF08su \u2192 input\uFF09\u3001\u773C\u775B\uFF08\u65E0\u969C\u788D\u624B\u52BF\u7AEF\u70B9\uFF09\u3001shell\uFF08\u81EA\u5B9A\u4E49\u547D\u4EE4\uFF09\uFF1Beyes \u9700\u8981 Coopanin \u7684\u65E0\u969C\u788D\u670D\u52A1\u5E26 /hand/* \u624B\u52BF\u7AEF\u70B9\uFF1Broot \u9700\u8981\u672C\u673A\u6709 root \u5E76\u6388\u6743\u7ED9 Coopanin\uFF1Bshell \u7528\u4E0B\u9762\u7684\u547D\u4EE4\u6A21\u677F\u3002",
+        "x-hot": false
+      },
+      [`${K}.rootCommand`]: {
+        type: "string",
+        title: "root \u547D\u4EE4",
+        description: "\u4E00\u822C\u662F su\uFF1B\u4E5F\u53EF\u662F su \u7684\u7EDD\u5BF9\u8DEF\u5F84\u3002\u53EA\u5728 actuator \u662F auto \u6216 root \u65F6\u7528\u3002",
+        "x-hot": false
+      },
+      [`${K}.shellCommand`]: {
+        type: "string",
+        title: "shell \u547D\u4EE4\u6A21\u677F",
+        description: '\u4F8B\u5982 rish -c "{cmd}" \u6216 adb -s 127.0.0.1:5555 shell "{cmd}"\u3002{cmd} \u4F1A\u6362\u6210\u4E00\u6761\u5DF2\u7ECF\u6821\u9A8C\u8FC7\u7684 input \u547D\u4EE4\u3002',
+        "x-hot": false
+      },
+      [`${K}.token`]: {
+        type: "string",
+        title: "\u624B\u52BF\u4EE4\u724C",
+        description: "\u72EC\u7ACB\u624B\u52BF App\uFF08\u624B\uFF09\u754C\u9762\u4E0A\u663E\u793A\u7684\u90A3\u4E32\u4EE4\u724C\u3002\u586B\u4E86\u5C31\u76F4\u63A5\u7528\uFF1B\u7559\u7A7A\u5219\u53BB\u8BFB\u4E0B\u9762\u7684\u4EE4\u724C\u6587\u4EF6\u3002",
+        "x-hot": false
+      },
+      [`${K}.tokenFile`]: {
+        type: "string",
+        title: "\u624B\u52BF\u4EE4\u724C\u6587\u4EF6",
+        description: "\u65E0\u969C\u788D\u670D\u52A1\u91CC\u5982\u679C\u6709\u4EBA\u5F80 files/hand.token \u5199\u4E86\u4EE4\u724C\uFF0C\u624B\u4F1A\u8BFB\u8FD9\u4E2A\u6587\u4EF6\u5E76\u5728\u6BCF\u4E2A\u624B\u52BF\u8BF7\u6C42\u4E0A\u5E26\u4E0A\u5B83\uFF1B\u7559\u7A7A\u5C31\u4E0D\u5E26\u3002\u88C5\u7684\u65F6\u5019\u6CA1\u751F\u6210\u8FD9\u4E2A\u6587\u4EF6\u4E5F\u80FD\u7528\u3002",
+        "x-hot": false
+      },
+      [`${K}.eyesPort`]: {
+        type: "integer",
+        title: "\u773C\u775B\u7AEF\u53E3",
+        minimum: 1024,
+        maximum: 65535,
+        description: "\u622A\u5C4F\u3001\u8BFB\u5B57\u548C\u624B\u52BF\u7AEF\u70B9\u90FD\u5728\u8FD9\u4E2A\u53E3\u4E0A\uFF0C\u968F\u5305\u7684\u65E0\u969C\u788D\u670D\u52A1\u7528 17898\u3002",
+        "x-hot": false
+      },
+      [`${K}.sensePort`]: {
+        type: "integer",
+        title: "\u611F\u89C9\u7AEF\u53E3",
+        minimum: 1024,
+        maximum: 65535,
+        description: "\u524D\u53F0\u5E94\u7528\u3001\u5C4F\u5E55\u4EAE\u7740\u6CA1\u6709\u3001\u7535\u91CF\u3002\u968F\u5305\u7684\u6865\u7528 17899\u3002",
+        "x-hot": false
+      },
+      [`${K}.dryRun`]: {
+        type: "boolean",
+        title: "\u6F14\u7EC3\uFF08\u53EA\u770B\u4E0D\u505A\uFF09",
+        description: "\u5F00\u7740\u65F6\u624B\u628A\u300C\u672C\u6765\u8981\u505A\u4EC0\u4E48\u300D\u8BF4\u51FA\u6765\uFF0C\u4F46\u4E00\u4E2A\u52A8\u4F5C\u90FD\u4E0D\u53D1\u3002",
+        "x-hot": true
+      },
+      [`${K}.maxActionsPerMinute`]: {
+        type: "integer",
+        title: "\u6BCF\u5206\u949F\u6700\u591A\u51E0\u4E2A\u52A8\u4F5C",
+        minimum: 1,
+        maximum: 300,
+        "x-suffix": "\u4E2A",
+        "x-hot": true
+      },
+      [`${K}.maxTextLength`]: {
+        type: "integer",
+        title: "\u4E00\u6B21\u6700\u591A\u8F93\u5165\u51E0\u4E2A\u5B57",
+        minimum: 1,
+        maximum: 1e3,
+        "x-suffix": "\u5B57",
+        description: "input text \u53EA\u5403\u5F97\u4E0B\u53EF\u6253\u5370 ASCII\uFF1B\u4E2D\u6587\u8981\u9760\u8F93\u5165\u6CD5\uFF0C\u624B\u53EA\u8D1F\u8D23\u6572\u952E\u76D8\u3002",
+        "x-hot": true
+      }
+    }
+  }
+};
+var HANDS_LOOK_CONFIG_GROUP = {
+  id: `world:${HANDS_ID}:look`,
+  owner: `world:${HANDS_ID}`,
+  schema: {
+    type: "object",
+    title: "\u770B\u5C4F\u5E55",
+    properties: {
+      [`${K}.lookAttach`]: {
+        type: "boolean",
+        title: "\u628A\u753B\u9762\u4E00\u8D77\u4EA4\u7ED9\u6A21\u578B",
+        description: "\u5173\u6389\u53EA\u9001\u5C4F\u5E55\u4E0A\u7684\u6587\u5B57\uFF0C\u7701 token\uFF1B\u5F00\u7740\u6A21\u578B\u80FD\u771F\u7684\u770B\u5230\u753B\u9762\uFF0C\u7784\u5F97\u66F4\u51C6\u3002",
+        "x-hot": true
+      },
+      [`${K}.lookMaxWidth`]: {
+        type: "integer",
+        title: "\u753B\u9762\u5BBD\u5EA6\u4E0A\u9650",
+        minimum: 240,
+        maximum: 1440,
+        "x-suffix": "px",
+        "x-hot": true
+      },
+      [`${K}.lookQuality`]: {
+        type: "integer",
+        title: "\u753B\u9762\u8D28\u91CF",
+        minimum: 30,
+        maximum: 90,
+        "x-suffix": "JPEG",
+        "x-hot": true
+      }
+    }
+  }
+};
+
+// src/world.ts
+import { fileURLToPath } from "node:url";
+
+// src/hands.ts
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { get as httpGet } from "node:http";
+var ACTION_TIMEOUT_MS = 15e3;
+var PROBE_TTL_MS = 2e4;
+var COORD_LIMIT = 2e4;
+var MIN_GESTURE_MS = 20;
+var MAX_GESTURE_MS = 2e4;
+var HandError = class extends Error {
+};
+function get(port, path, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = httpGet({ host: "127.0.0.1", port, path, timeout: timeoutMs }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        resolve({
+          status: res.statusCode ?? 0,
+          body: Buffer.concat(chunks),
+          header: (name) => {
+            const value = res.headers[name.toLowerCase()];
+            return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+          }
+        });
+      });
+    });
+    req.on("timeout", () => req.destroy(new Error(`\u7B49\u592A\u4E45\uFF08${timeoutMs}ms\uFF09`)));
+    req.on("error", (err) => reject(err));
+  });
+}
+async function getJson(port, path, timeoutMs = 6e3) {
+  try {
+    const res = await get(port, path, timeoutMs);
+    if (res.status !== 200) return null;
+    return JSON.parse(res.body.toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+var flat = (value, max = 200) => {
+  if (typeof value !== "string") return "";
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length <= max ? text : `${text.slice(0, max)}\u2026`;
+};
+function parseBounds(raw) {
+  if (!raw) return null;
+  const nums = raw.match(/-?\d+/g);
+  if (!nums || nums.length !== 4) return null;
+  const [l, t, r, b] = nums.map((n) => Number.parseInt(n, 10));
+  if (![l, t, r, b].every((n) => Number.isFinite(n))) return null;
+  if (r <= l || b <= t) return null;
+  return { l, t, r, b };
+}
+function coord(value, limit = COORD_LIMIT) {
+  const n = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(n)) throw new HandError("\u5750\u6807\u5F97\u662F\u6570\u5B57\u3002");
+  const rounded = Math.round(n);
+  if (rounded < -limit || rounded > limit) throw new HandError(`\u5750\u6807 ${rounded} \u4E0D\u53EF\u80FD\u5728\u5C4F\u5E55\u4E0A\u3002`);
+  return rounded;
+}
+function milliseconds(value, fallback) {
+  const n = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(MIN_GESTURE_MS, Math.min(MAX_GESTURE_MS, Math.round(n)));
+}
+function escapeInputText(text) {
+  if (!text) throw new HandError("\u8981\u8F93\u5165\u7684\u6587\u5B57\u662F\u7A7A\u7684\u3002");
+  for (const ch of text) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code < 32 || code > 126) throw new HandError(`\u300C${ch}\u300D\u4E0D\u662F\u53EF\u6253\u5370 ASCII\uFF1Binput text \u6572\u4E0D\u8FDB\u53BB\uFF0C\u8FD9\u6761\u901A\u9053\u53EA\u9002\u5408\u82F1\u6587\u3001\u6570\u5B57\u548C\u7B26\u53F7\u3002`);
+    if (ch === "'" || ch === "\\") throw new HandError(`\u300C${ch}\u300D\u4F1A\u88AB shell \u5403\u6389\uFF0C\u6362\u4E2A\u522B\u7684\u65B9\u5F0F\u8F93\u5165\u5B83\u3002`);
+  }
+  return text.replace(/ /g, "%s");
+}
+function keyCode(name) {
+  const key = String(name ?? "").trim().toLowerCase().replace(/[\s_-]/g, "");
+  const code = KEY_CODES[key];
+  if (code === void 0) throw new HandError(`\u4E0D\u8BA4\u8FD9\u4E2A\u6309\u952E\uFF1A${name || "(\u7A7A)"}\u3002\u80FD\u6309\u7684\u662F ${Object.keys(KEY_CODES).join("\u3001")}\u3002`);
+  return code;
+}
+function inputCommand(command) {
+  switch (command.kind) {
+    // 同一点上按住不放，对 input 就是一次等时长的 swipe
+    case "tap":
+      return command.ms >= 400 ? `input swipe ${command.x} ${command.y} ${command.x} ${command.y} ${command.ms}` : `input tap ${command.x} ${command.y}`;
+    case "swipe":
+      return `input swipe ${command.x1} ${command.y1} ${command.x2} ${command.y2} ${command.ms}`;
+    case "key":
+      return `input keyevent ${command.code}`;
+    // 文本在拼命令这一刻才转义：只有 input 这条路吃不下非 ASCII，无障碍那条能原样收
+    case "text":
+      return `input text '${escapeInputText(command.value)}'`;
+  }
+}
+var RootActuator = class {
+  kind = "root";
+  su;
+  log;
+  constructor(su, log) {
+    this.su = su;
+    this.log = log;
+  }
+  run(argv, timeoutMs = ACTION_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+      execFile(argv[0], argv.slice(1), { timeout: timeoutMs, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        const code = err ? typeof err.code === "number" ? err.code : 1 : 0;
+        resolve({ code, out: String(stdout ?? ""), err: String(stderr ?? "") });
+      });
+    });
+  }
+  async probe() {
+    const su = this.su().trim() || "su";
+    const r = await this.run([su, "-c", "id"], 8e3);
+    if (r.code !== 0) {
+      const why = flat(r.err || r.out, 120);
+      return { ok: false, detail: why ? `su \u8DD1\u4E0D\u8D77\u6765\uFF08${why}\uFF09` : "su \u8DD1\u4E0D\u8D77\u6765\uFF1A\u53EF\u80FD\u6CA1 root\uFF0C\u6216\u8005\u6CA1\u6388\u6743\u7ED9 Coopanin\u3002" };
+    }
+    const id = flat(r.out, 120);
+    if (!/\buid=0\b/.test(id)) return { ok: false, detail: `su \u7ED9\u7684\u4E0D\u662F root\uFF08${id || "\u6CA1\u6709\u8F93\u51FA"}\uFF09` };
+    return { ok: true, detail: "root \u53EF\u7528\uFF08su \u2192 input\uFF09" };
+  }
+  async apply(command) {
+    const line = inputCommand(command);
+    const su = this.su().trim() || "su";
+    const r = await this.run([su, "-c", line]);
+    if (r.code !== 0) {
+      const why = flat(r.err || r.out, 160);
+      throw new HandError(`input \u6CA1\u6210\u529F\uFF08${why || `\u9000\u51FA\u7801 ${r.code}`}\uFF09\u3002`);
+    }
+    this.log?.()?.debug("\u624B\uFF1Aroot \u52A8\u4F5C\u5DF2\u53D1\u51FA", { line });
+    return { ok: true, detail: "root" };
+  }
+};
+var ShellActuator = class {
+  kind = "shell";
+  template;
+  log;
+  constructor(template, log) {
+    this.template = template;
+    this.log = log;
+  }
+  argv(command) {
+    const template = this.template().trim();
+    if (!template) throw new HandError("shell \u901A\u9053\u6CA1\u6709\u914D\u547D\u4EE4\u6A21\u677F\uFF08\u8BBE\u7F6E \u2192 \u624B \u2192 shell \u547D\u4EE4\u6A21\u677F\uFF09\u3002");
+    const line = template.replace(/\{cmd\}/g, inputCommand(command));
+    return ["sh", "-c", line];
+  }
+  async probe() {
+    const template = this.template().trim();
+    if (!template) return { ok: false, detail: "shell \u901A\u9053\u6CA1\u914D\u6A21\u677F" };
+    if (!template.includes("{cmd}")) return { ok: false, detail: "shell \u6A21\u677F\u91CC\u6CA1\u6709 {cmd}\uFF0C\u4E0D\u77E5\u9053\u628A\u547D\u4EE4\u653E\u54EA" };
+    const probe = template.replace(/\{cmd\}/g, "id");
+    const r = await new Promise((resolve) => {
+      execFile("sh", ["-c", probe], { timeout: 8e3, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        const code = err ? typeof err.code === "number" ? err.code : 1 : 0;
+        resolve({ code, out: String(stdout ?? ""), err: String(stderr ?? "") });
+      });
+    });
+    if (r.code !== 0) return { ok: false, detail: flat(r.err || r.out, 140) || "\u6A21\u677F\u8DD1\u4E0D\u8D77\u6765" };
+    const id = flat(r.out, 120);
+    return { ok: true, detail: id ? `shell \u901A\u9053\u53EF\u7528\uFF08${id}\uFF09` : "shell \u901A\u9053\u53EF\u7528" };
+  }
+  async apply(command) {
+    const argv = this.argv(command);
+    const r = await new Promise((resolve) => {
+      execFile(argv[0], argv.slice(1), { timeout: ACTION_TIMEOUT_MS, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        const code = err ? typeof err.code === "number" ? err.code : 1 : 0;
+        resolve({ code, out: String(stdout ?? ""), err: String(stderr ?? "") });
+      });
+    });
+    if (r.code !== 0) throw new HandError(`\u901A\u9053\u547D\u4EE4\u6CA1\u6210\u529F\uFF08${flat(r.err || r.out, 160) || `\u9000\u51FA\u7801 ${r.code}`}\uFF09\u3002`);
+    this.log?.()?.debug("\u624B\uFF1Ashell \u52A8\u4F5C\u5DF2\u53D1\u51FA", { argv: argv.join(" ") });
+    return { ok: true, detail: "shell" };
+  }
+};
+var EyesActuator = class {
+  kind = "eyes";
+  port;
+  token;
+  log;
+  constructor(port, token, log) {
+    this.port = port;
+    this.token = token;
+    this.log = log;
+  }
+  /** 带令牌（服务里生成了才带）。 */
+  withToken(path) {
+    const token = this.token();
+    if (!token) return path;
+    return `${path}${path.includes("?") ? "&" : "?"}t=${encodeURIComponent(token)}`;
+  }
+  async send(raw) {
+    const path = this.withToken(raw);
+    const res = await get(this.port(), path, ACTION_TIMEOUT_MS);
+    if (res.status === 404) throw new HandError("\u65E0\u969C\u788D\u670D\u52A1\u6CA1\u6709\u624B\u52BF\u7AEF\u70B9\uFF08\u88C5\u7684\u662F\u300C\u53EA\u770B\u300D\u7684\u7248\u672C\uFF09\u3002");
+    if (res.status === 409) throw new HandError("\u5C4F\u5E55\u4E0A\u6CA1\u6709\u6B63\u5728\u8F93\u5165\u7684\u8F93\u5165\u6846\uFF0C\u5148\u70B9\u4E00\u4E0B\u8981\u5199\u7684\u5730\u65B9\u3002");
+    if (res.status !== 200) {
+      const body2 = flat(res.body.toString("utf8"), 140);
+      throw new HandError(`\u65E0\u969C\u788D\u670D\u52A1\u56DE\u4E86 ${res.status}${body2 ? `\uFF1A${body2}` : ""}\u3002`);
+    }
+    let body = {};
+    try {
+      body = JSON.parse(res.body.toString("utf8"));
+    } catch {
+      return { ok: true, detail: "" };
+    }
+    if (body.ok === false) throw new HandError(flat(body.error || body.detail, 160) || "\u65E0\u969C\u788D\u670D\u52A1\u6CA1\u505A\u6210\u8FD9\u4E2A\u52A8\u4F5C\u3002");
+    this.log?.()?.debug("\u624B\uFF1A\u65E0\u969C\u788D\u52A8\u4F5C\u5DF2\u53D1\u51FA", { path });
+    return { ok: true, detail: flat(body.detail, 60) };
+  }
+  async probe() {
+    const health = await getJson(this.port(), "/health", 4e3);
+    if (!health) return { ok: false, detail: "\u65E0\u969C\u788D\u670D\u52A1\u6CA1\u5728\u8DD1\uFF08\u7CFB\u7EDF\u8BBE\u7F6E \u2192 \u65E0\u969C\u788D\u91CC\u53EF\u80FD\u6CA1\u5F00\uFF09" };
+    if (health.canGesture !== true) return { ok: false, detail: "\u65E0\u969C\u788D\u670D\u52A1\u5728\u8DD1\uFF0C\u4F46\u8FD9\u4E2A\u7248\u672C\u53EA\u6709\u300C\u770B\u300D\uFF0C\u6CA1\u6709\u624B\u52BF\uFF08/hand/* \u7AEF\u70B9\uFF09" };
+    return { ok: true, detail: "\u65E0\u969C\u788D\u624B\u52BF\u53EF\u7528" };
+  }
+  async apply(command) {
+    switch (command.kind) {
+      case "tap":
+        return this.send(`/hand/tap?x=${command.x}&y=${command.y}&ms=${command.ms}`);
+      case "swipe":
+        return this.send(`/hand/swipe?x1=${command.x1}&y1=${command.y1}&x2=${command.x2}&y2=${command.y2}&ms=${command.ms}`);
+      case "key":
+        return this.send(`/hand/key?name=${encodeURIComponent(command.name)}&code=${command.code}`);
+      case "text":
+        return this.send(`/hand/text?value=${encodeURIComponent(command.value)}`);
+    }
+  }
+};
+var EyesClient = class {
+  port;
+  constructor(port) {
+    this.port = port;
+  }
+  health() {
+    return getJson(this.port(), "/health", 4e3);
+  }
+  async state(sensePort) {
+    const body = await getJson(sensePort, "/state", 4e3);
+    if (!body) return null;
+    return {
+      appPkg: flat(body.app?.pkg, 120),
+      appLabel: flat(body.app?.label, 60),
+      screenOn: body.screen?.on !== false,
+      locked: body.screen?.locked === true,
+      battery: typeof body.power?.level === "number" ? body.power.level : void 0
+    };
+  }
+  async ui() {
+    const body = await getJson(this.port(), "/ui", 6e3);
+    if (!body) return { ok: false, pkg: "", items: [], error: "\u8BFB\u4E0D\u5230\u5C4F\u5E55\u4E0A\u7684\u6587\u5B57" };
+    const items = [];
+    for (const raw of body.items ?? []) {
+      const text = flat(raw?.t, 160);
+      if (!text) continue;
+      const bounds = flat(raw?.b, 60) || void 0;
+      const box = parseBounds(bounds);
+      items.push({
+        text,
+        cls: flat(raw?.c, 40) || void 0,
+        bounds,
+        ...box ? { center: { x: Math.round((box.l + box.r) / 2), y: Math.round((box.t + box.b) / 2) } } : {}
+      });
+      if (items.length >= 120) break;
+    }
+    return { ok: body.ok !== false, pkg: flat(body.pkg, 120), items };
+  }
+  async frame(maxWidth, quality) {
+    try {
+      const w = Math.max(160, Math.min(2160, Math.round(maxWidth)));
+      const q = Math.max(20, Math.min(95, Math.round(quality)));
+      const res = await get(this.port(), `/screen.jpg?max=${w}&q=${q}`, 12e3);
+      if (res.status !== 200 || res.body.length === 0) return null;
+      return {
+        bytes: new Uint8Array(res.body),
+        width: Number.parseInt(res.header("x-width"), 10) || 0,
+        height: Number.parseInt(res.header("x-height"), 10) || 0,
+        pkg: flat(res.header("x-pkg"), 120),
+        ageMs: Number.parseInt(res.header("x-age-ms"), 10) || 0
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+var describeCommand = (command) => {
+  switch (command.kind) {
+    case "tap":
+      return `\u70B9 (${command.x},${command.y})`;
+    case "swipe":
+      return `\u4ECE (${command.x1},${command.y1}) \u6ED1\u5230 (${command.x2},${command.y2})`;
+    case "key":
+      return `\u6309 ${command.name}`;
+    case "text":
+      return `\u8F93\u5165\u300C${command.value}\u300D`;
+  }
+};
+var Hands = class {
+  eyes;
+  rootActuator;
+  shellActuator;
+  eyesActuator;
+  /** 每分钟的动作用时间戳记；超过上限就停手。 */
+  stamps = [];
+  actuatorState = { kind: "off", configured: "off", ok: false, detail: "\u8FD8\u6CA1\u63A2\u8FC7", checkedAt: 0 };
+  screen = null;
+  lastScreenAt = 0;
+  looks = 0;
+  acts = 0;
+  log;
+  cfg;
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.eyes = new EyesClient(() => this.port(this.cfg().eyesPort));
+    this.rootActuator = new RootActuator(() => this.cfg().rootCommand, () => this.log);
+    this.shellActuator = new ShellActuator(() => this.cfg().shellCommand, () => this.log);
+    this.eyesActuator = new EyesActuator(() => this.port(this.cfg().eyesPort), () => this.readToken(), () => this.log);
+  }
+  port(value) {
+    const n = Math.round(Number(value));
+    return Number.isFinite(n) && n >= 1024 && n <= 65535 ? n : 17898;
+  }
+  /** 世界挂上以后把日志接进来；探测和动作都写在这里。 */
+  attachLog(log) {
+    this.log = log;
+  }
+  /** 在屏幕上的字里找一段；只有读得出坐标的才算命中。 */
+  async findText(needle) {
+    const query = needle.trim().toLowerCase();
+    if (!query) return [];
+    const ui = await this.eyes.ui();
+    if (!ui.ok) throw new HandError(ui.error ?? "\u8BFB\u4E0D\u5230\u5C4F\u5E55\u4E0A\u7684\u5B57\u3002");
+    const hits = [];
+    for (const item of ui.items) {
+      if (!item.center) continue;
+      if (!item.text.toLowerCase().includes(query)) continue;
+      hits.push({ text: item.text, center: item.center });
+      if (hits.length >= 20) break;
+    }
+    return hits;
+  }
+  /** 手势令牌：文件里有就用它；读不到就是空（服务那边也不校验）。 */
+  tokenCache = { value: "", at: 0 };
+  readToken() {
+    const literal = this.cfg().token?.trim();
+    if (literal) return literal;
+    const file = this.cfg().tokenFile?.trim();
+    if (!file) return "";
+    if (Date.now() - this.tokenCache.at < 3e4) return this.tokenCache.value;
+    let value = "";
+    try {
+      const text = readFileSync(file, "utf8").trim();
+      if (text && text.length <= 200) value = text;
+    } catch {
+      value = "";
+    }
+    this.tokenCache = { value, at: Date.now() };
+    return value;
+  }
+  /** 通道现状；Probe 过就返回缓存。 */
+  state() {
+    return this.actuatorState;
+  }
+  stats() {
+    this.prune();
+    return { acts: this.acts, looks: this.looks, inWindow: this.stamps.length };
+  }
+  /** 选通道并验证。auto 依次试 root、眼睛、shell；结果缓存 20 秒。 */
+  async probe(force = false) {
+    const cfg = this.cfg();
+    const want = cfg.actuator;
+    const now = Date.now();
+    if (!force && want === this.actuatorState.configured && now - this.actuatorState.checkedAt < PROBE_TTL_MS) return this.actuatorState;
+    const candidates = want === "auto" ? ["root", "eyes", "shell"] : want === "off" ? [] : [want];
+    if (candidates.length === 0) {
+      this.actuatorState = { kind: "off", configured: want, ok: false, detail: "\u624B\u5173\u7740\uFF08actuator=off\uFF09", checkedAt: now };
+      return this.actuatorState;
+    }
+    const notes = [];
+    for (const kind of candidates) {
+      const actuator = kind === "root" ? this.rootActuator : kind === "eyes" ? this.eyesActuator : this.shellActuator;
+      let result;
+      try {
+        result = await actuator.probe();
+      } catch (err) {
+        result = { ok: false, detail: err instanceof Error ? err.message : String(err) };
+      }
+      notes.push(`${kind}: ${result.detail}`);
+      if (result.ok) {
+        this.actuatorState = { kind, configured: want, ok: true, detail: result.detail, checkedAt: now };
+        this.log?.info(`\u624B\u80FD\u7528\u4E86\uFF1A${kind}\uFF08${result.detail}\uFF09`);
+        return this.actuatorState;
+      }
+    }
+    this.actuatorState = { kind: want, configured: want, ok: false, detail: notes.join("\uFF1B"), checkedAt: now };
+    this.log?.warn(`\u624B\u6682\u65F6\u52A8\u4E0D\u4E86\uFF1A${this.actuatorState.detail}`);
+    return this.actuatorState;
+  }
+  async actuator() {
+    const state = await this.probe();
+    if (!state.ok) throw new HandError(`\u624B\u73B0\u5728\u52A8\u4E0D\u4E86\uFF1A${state.detail}`);
+    const picked = state.kind === "root" ? this.rootActuator : state.kind === "eyes" ? this.eyesActuator : state.kind === "shell" ? this.shellActuator : null;
+    if (!picked) throw new HandError(`\u624B\u73B0\u5728\u52A8\u4E0D\u4E86\uFF1A${state.detail}`);
+    return picked;
+  }
+  /** 屏幕尺寸；拿不到就不校验边界（root 通道下常见）。 */
+  async screenSize() {
+    if (this.screen && Date.now() - this.lastScreenAt < 6e4) return this.screen;
+    const health = await this.eyes.health();
+    if (health?.ok && health.frameWidth && health.frameHeight) {
+      this.screen = { w: health.frameWidth, h: health.frameHeight };
+      this.lastScreenAt = Date.now();
+      return this.screen;
+    }
+    const frame = await this.eyes.frame(240, 30);
+    if (frame && frame.width > 0 && frame.height > 0) {
+      this.screen = { w: frame.width, h: frame.height };
+      this.lastScreenAt = Date.now();
+      return this.screen;
+    }
+    return null;
+  }
+  prune() {
+    const cutoff = Date.now() - 6e4;
+    while (this.stamps.length && (this.stamps[0] ?? 0) < cutoff) this.stamps.shift();
+  }
+  /** 限速：一分钟内动作超过上限就停手，等窗口滑过去。 */
+  async throttle() {
+    const max = Math.max(1, Math.round(this.cfg().maxActionsPerMinute) || 30);
+    this.prune();
+    if (this.stamps.length >= max) {
+      const oldest = this.stamps[0] ?? Date.now();
+      const waitMs = Math.max(0, 6e4 - (Date.now() - oldest));
+      throw new HandError(`\u8FD9\u4E00\u5206\u949F\u5DF2\u7ECF\u52A8\u4E86 ${this.stamps.length} \u4E0B\uFF08\u4E0A\u9650 ${max}\uFF09\uFF0C${Math.ceil(waitMs / 1e3)} \u79D2\u540E\u518D\u6765\u3002`);
+    }
+  }
+  /** 动作前先看屏幕亮着没有、锁着没有；锁屏时不该动手。 */
+  async screenGuard() {
+    const state = await this.eyes.state(this.port(this.cfg().sensePort));
+    if (!state) return "";
+    if (state.locked) throw new HandError("\u624B\u673A\u9501\u7740\uFF0C\u624B\u70B9\u4E0D\u5230\u4E1C\u897F\uFF1B\u5148\u89E3\u5F00\u3002");
+    if (!state.screenOn) throw new HandError("\u5C4F\u5E55\u9ED1\u7740\uFF0C\u624B\u70B9\u4E0D\u5230\u4E1C\u897F\uFF1B\u5148\u70B9\u4EAE\u3002");
+    return state.appLabel ? `${state.appLabel}\uFF08${state.appPkg}\uFF09` : state.appPkg;
+  }
+  async bounds(x, y) {
+    const screen = await this.screenSize();
+    if (!screen) return;
+    if (x < 0 || y < 0 || x > screen.w || y > screen.h) {
+      throw new HandError(`(${x},${y}) \u5728\u5C4F\u5E55\u5916\uFF1A\u8FD9\u5757\u5C4F\u662F ${screen.w}\xD7${screen.h}\u3002`);
+    }
+  }
+  async tap(x, y, opts = {}) {
+    const px = coord(x);
+    const py = coord(y);
+    await this.bounds(px, py);
+    const ms = milliseconds(opts.ms, 60);
+    return this.perform({ kind: "tap", x: px, y: py, ms });
+  }
+  async longPress(x, y, opts = {}) {
+    const px = coord(x);
+    const py = coord(y);
+    await this.bounds(px, py);
+    const ms = milliseconds(opts.ms, 800);
+    return this.perform({ kind: "tap", x: px, y: py, ms });
+  }
+  async swipe(x1, y1, x2, y2, opts = {}) {
+    const a = coord(x1);
+    const b = coord(y1);
+    const c = coord(x2);
+    const d = coord(y2);
+    await this.bounds(a, b);
+    await this.bounds(c, d);
+    const ms = milliseconds(opts.ms, 300);
+    return this.perform({ kind: "swipe", x1: a, y1: b, x2: c, y2: d, ms });
+  }
+  async press(key) {
+    const name = String(key ?? "").trim().toLowerCase().replace(/[\s_-]/g, "");
+    const code = keyCode(name);
+    return this.perform({ kind: "key", name, code });
+  }
+  async type(text) {
+    const value = String(text ?? "");
+    const cfg = this.cfg();
+    const limit = Math.max(1, Math.round(cfg.maxTextLength) || 200);
+    if (value.length > limit) throw new HandError(`\u4E00\u6B21\u6700\u591A ${limit} \u4E2A\u5B57\uFF0C\u8FD9\u6BB5\u6709 ${value.length} \u4E2A\u3002`);
+    if (!value.trim()) throw new HandError("\u8981\u8F93\u5165\u7684\u6587\u5B57\u662F\u7A7A\u7684\u3002");
+    return this.perform({ kind: "text", value });
+  }
+  async perform(command) {
+    const state = await this.probe();
+    if (!state.ok) throw new HandError(`\u624B\u73B0\u5728\u52A8\u4E0D\u4E86\uFF1A${state.detail}`);
+    const where = await this.screenGuard();
+    await this.throttle();
+    const described = describeCommand(command);
+    const cfg = this.cfg();
+    if (cfg.dryRun) {
+      this.log?.info(`\u624B\uFF08\u6F14\u7EC3\uFF09\uFF1A${described}`, { actuator: state.kind });
+      return { text: `\u6F14\u7EC3\uFF1A\u672C\u6765\u8981${described}${where ? `\uFF08\u5728 ${where} \u4E0A\uFF09` : ""}\uFF0C\u4E00\u4E2A\u52A8\u4F5C\u90FD\u6CA1\u53D1\u3002`, performed: false };
+    }
+    const actuator = await this.actuator();
+    try {
+      const result = await actuator.apply(command);
+      this.stamps.push(Date.now());
+      this.acts += 1;
+      this.log?.info(`\u624B\uFF1A${described}`, { actuator: state.kind, where });
+      const via = state.kind === "root" ? "root \u7684 input" : state.kind === "shell" ? "\u4F60\u7ED9\u7684 shell \u901A\u9053" : "\u65E0\u969C\u788D\u624B\u52BF";
+      return {
+        text: `${described}${where ? `\uFF08\u5728 ${where} \u4E0A\uFF09` : ""}\uFF0C\u901A\u8FC7${via}\u53D1\u51FA\u53BB\u4E86${result.detail && state.kind === "eyes" ? `\uFF08${result.detail}\uFF09` : ""}\u3002`,
+        performed: true
+      };
+    } catch (err) {
+      this.actuatorState = { ...this.actuatorState, ok: false, detail: err instanceof Error ? err.message : String(err) };
+      throw err;
+    }
+  }
+  /** 看一眼屏幕。detail: both（画面加文字，默认）、screen（只要画面）、text（只要文字）。 */
+  async look(detail = "both") {
+    const cfg = this.cfg();
+    const health = await this.eyes.health();
+    if (!health?.ok) {
+      throw new HandError(`\u773C\u775B\u6CA1\u5F00\uFF1A${health?.error ?? "\u65E0\u969C\u788D\u670D\u52A1\u6CA1\u5728\u8DD1\uFF08\u7CFB\u7EDF\u8BBE\u7F6E \u2192 \u65E0\u969C\u788D\uFF09"}\u3002`);
+    }
+    const state = await this.eyes.state(this.port(cfg.sensePort));
+    const where = state?.appLabel && state.appPkg ? `${state.appLabel}\uFF08${state.appPkg}\uFF09` : state?.appPkg || "\u672A\u77E5\u5E94\u7528";
+    const parts = [`\u73B0\u5728\u524D\u53F0\u662F ${where}\u3002`];
+    if (state) {
+      parts.push(`${state.screenOn ? "\u5C4F\u5E55\u4EAE\u7740" : "\u5C4F\u5E55\u9ED1\u7740"}\u3001${state.locked ? "\u9501\u7740" : "\u6CA1\u9501"}${typeof state.battery === "number" ? `\u3001\u7535\u91CF ${state.battery}%` : ""}\u3002`);
+    }
+    let blob;
+    let frame;
+    if (detail !== "text") {
+      const f = await this.eyes.frame(cfg.lookMaxWidth, cfg.lookQuality);
+      if (f) {
+        frame = f;
+        parts.push(`\u753B\u9762 ${f.width}\xD7${f.height}${f.ageMs > 1200 ? `\uFF0C${(f.ageMs / 1e3).toFixed(1)} \u79D2\u524D\u62CD\u7684` : ""}\u3002`);
+        if (cfg.lookAttach) {
+          blob = { bytes: f.bytes, mime: "image/jpeg", name: "screen.jpg", fallbackText: "\uFF08\u8FD9\u662F\u624B\u673A\u73B0\u5728\u8FD9\u4E00\u5C4F\u7684\u622A\u56FE\uFF09" };
+        }
+      } else {
+        parts.push("\u8FD9\u6B21\u6CA1\u62FF\u5230\u753B\u9762\u3002");
+      }
+    }
+    if (detail !== "screen") {
+      const ui = await this.eyes.ui();
+      if (ui.ok && ui.items.length) {
+        const lines = ui.items.slice(0, 40).map((item) => {
+          const spot = item.center ? `@(${item.center.x},${item.center.y})` : "";
+          return `- \u300C${item.text}\u300D${spot}`;
+        });
+        parts.push(`\u5C4F\u5E55\u4E0A\u7684\u5B57\uFF08\u80FD\u8BFB\u5230\u7684\u524D ${lines.length} \u6761\uFF0C@ \u540E\u9762\u662F\u53EF\u4EE5\u70B9\u7684\u4F4D\u7F6E\uFF09\uFF1A
+${lines.join("\n")}`);
+      } else {
+        parts.push("\u5C4F\u5E55\u4E0A\u6CA1\u8BFB\u5230\u80FD\u70B9\u7684\u5B57\u3002");
+      }
+    }
+    const bounds = await this.screenSize();
+    if (bounds) parts.push(`\u5C4F\u5E55\u5C3A\u5BF8 ${bounds.w}\xD7${bounds.h}\u3002`);
+    this.looks += 1;
+    return { text: parts.join("\n"), ...blob ? { blob } : {}, ...frame ? { frame } : {} };
+  }
+};
+
+// src/tools.ts
+var HANDS_TOOL_DECLS = [
+  {
+    name: "hand_look",
+    tags: ["read", "snapshot"],
+    description: "\u770B\u4E00\u773C\u5BF9\u65B9\u624B\u673A\u73B0\u5728\u8FD9\u4E00\u5C4F\uFF1A\u524D\u53F0\u662F\u54EA\u4E2A\u5E94\u7528\u3001\u5C4F\u5E55\u4EAE\u4E0D\u4EAE\u3001\u9501\u6CA1\u9501\uFF0C\u5C4F\u5E55\u4E0A\u80FD\u8BFB\u5230\u7684\u5B57\u5404\u81EA\u5728\u4EC0\u4E48\u5750\u6807\uFF0C\u5E76\uFF08\u9ED8\u8BA4\uFF09\u628A\u753B\u9762\u4E00\u8D77\u7ED9\u4F60\u3002\u60F3\u70B9\u3001\u60F3\u6ED1\u4E4B\u524D\u5148\u7528\u5B83\u7784\u51C6\uFF1B\u770B\u4E0D\u6E05\u5C31\u518D\u770B\u4E00\u773C\uFF0C\u522B\u51ED\u8BB0\u5FC6\u70B9\u3002",
+    parameters: {
+      type: "object",
+      properties: {
+        detail: {
+          type: "string",
+          enum: ["both", "screen", "text"],
+          description: "both \u753B\u9762\u52A0\u6587\u5B57\uFF08\u9ED8\u8BA4\uFF09\uFF1Bscreen \u53EA\u8981\u753B\u9762\uFF1Btext \u53EA\u8981\u6587\u5B57\uFF0C\u7701\u6D41\u91CF\u4E5F\u4E0D\u5360\u4E0A\u4E0B\u6587\u3002"
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: "hand_tap",
+    tags: ["act"],
+    description: "\u7528\u6307\u5C16\u70B9\u4E00\u4E0B\u5C4F\u5E55\u3002\u53EF\u4EE5\u7ED9\u5750\u6807 (x,y)\uFF0C\u4E5F\u53EF\u4EE5\u7ED9\u4E00\u4E2A\u6587\u5B57\u2014\u2014\u624B\u4F1A\u5728\u5C4F\u5E55\u4E0A\u7684\u5B57\u91CC\u627E\uFF0C\u53EA\u6709\u4E00\u5904\u5BF9\u5F97\u4E0A\u624D\u70B9\uFF0C\u6709\u597D\u51E0\u5904\u5C31\u628A\u5019\u9009\u5217\u7ED9\u4F60\u5E76\u62D2\u7EDD\u52A8\u624B\u3002\u70B9\u4E4B\u524D\u6700\u597D\u5148 hand_look \u786E\u8BA4\u4F4D\u7F6E\u3002",
+    parameters: {
+      type: "object",
+      properties: {
+        x: { type: "integer", description: "\u6A2A\u5411\u5750\u6807\uFF08\u50CF\u7D20\uFF09\uFF0C\u548C hand_look \u91CC @(...) \u7684\u7B2C\u4E8C\u534A\u4E00\u81F4\u3002" },
+        y: { type: "integer", description: "\u7EB5\u5411\u5750\u6807\uFF08\u50CF\u7D20\uFF09\u3002" },
+        text: { type: "string", description: "\u8981\u70B9\u7684\u90A3\u4E2A\u63A7\u4EF6\u4E0A\u7684\u6587\u5B57\uFF0C\u4F8B\u5982\u300C\u53D1\u9001\u300D\u300C\u8BBE\u7F6E\u300D\u3002\u7ED9\u4E86 text \u5C31\u4E0D\u7528\u7ED9\u5750\u6807\u3002" },
+        nth: { type: "integer", minimum: 0, description: "\u540C\u4E00\u6BB5\u6587\u5B57\u6709\u597D\u51E0\u5904\u65F6\u70B9\u7B2C\u51E0\u4E2A\uFF08\u4ECE 0 \u6570\uFF09\uFF1B\u4E0D\u7ED9\u5C31\u662F\u5168\u90FD\u8981\uFF0C\u624B\u4F1A\u62D2\u7EDD\u3002" }
+      },
+      required: []
+    }
+  },
+  {
+    name: "hand_long",
+    tags: ["act"],
+    description: "\u5728\u4E00\u4E2A\u4F4D\u7F6E\u6309\u4F4F\u4E0D\u653E\uFF08\u957F\u6309\uFF09\uFF0C\u9ED8\u8BA4 800 \u6BEB\u79D2\u3002\u7528\u4E8E\u957F\u6309\u83DC\u5355\u3001\u62D6\u9009\u3001\u9009\u4E2D\u3002",
+    parameters: {
+      type: "object",
+      properties: {
+        x: { type: "integer", description: "\u6A2A\u5411\u5750\u6807\uFF08\u50CF\u7D20\uFF09\u3002" },
+        y: { type: "integer", description: "\u7EB5\u5411\u5750\u6807\uFF08\u50CF\u7D20\uFF09\u3002" },
+        ms: { type: "integer", minimum: 300, maximum: 5e3, description: "\u6309\u4F4F\u591A\u4E45\uFF0C\u9ED8\u8BA4 800 \u6BEB\u79D2\u3002" }
+      },
+      required: ["x", "y"]
+    }
+  },
+  {
+    name: "hand_swipe",
+    tags: ["act"],
+    description: "\u4ECE\u4E00\u70B9\u6ED1\u5230\u53E6\u4E00\u70B9\uFF1A\u7FFB\u9875\u3001\u6EDA\u52A8\u3001\u4E0B\u62C9\u901A\u77E5\u3001\u62D6\u4E1C\u897F\u3002\u9ED8\u8BA4 300 \u6BEB\u79D2\uFF1B\u60F3\u6162\u4E00\u70B9\u770B\u6E05\u5185\u5BB9\u5C31\u8C03\u5927\u3002",
+    parameters: {
+      type: "object",
+      properties: {
+        x1: { type: "integer", description: "\u8D77\u70B9\u6A2A\u5750\u6807\u3002" },
+        y1: { type: "integer", description: "\u8D77\u70B9\u7EB5\u5750\u6807\u3002" },
+        x2: { type: "integer", description: "\u7EC8\u70B9\u6A2A\u5750\u6807\u3002" },
+        y2: { type: "integer", description: "\u7EC8\u70B9\u7EB5\u5750\u6807\u3002" },
+        ms: { type: "integer", minimum: 50, maximum: 5e3, description: "\u6ED1\u591A\u4E45\uFF0C\u9ED8\u8BA4 300 \u6BEB\u79D2\u3002" }
+      },
+      required: ["x1", "y1", "x2", "y2"]
+    }
+  },
+  {
+    name: "hand_type",
+    tags: ["act"],
+    description: "\u5F80\u5F53\u524D\u5149\u6807\u5904\u6572\u5B57\u3002\u5148\u70B9\u4E00\u4E0B\u8981\u5199\u7684\u5730\u65B9\u628A\u8F93\u5165\u6846\u53EB\u8D77\u6765\u3002\u6CE8\u610F\uFF1A\u8D70 input \u8FD9\u7C7B\u901A\u9053\u65F6\u53EA\u8BA4\u53EF\u6253\u5370 ASCII\uFF08\u4E2D\u6587\u6572\u4E0D\u8FDB\u53BB\uFF0C\u4F1A\u76F4\u63A5\u5931\u8D25\u5E76\u8BF4\u660E\uFF09\uFF1B\u8D70\u65E0\u969C\u788D\u901A\u9053\u65F6\u4E2D\u6587\u4E5F\u80FD\u8FDB\u3002\u5BC6\u7801\u4E4B\u7C7B\u7684\u4E1C\u897F\u4E0D\u8981\u66FF\u5BF9\u65B9\u6572\u3002",
+    parameters: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "\u8981\u8F93\u5165\u7684\u6587\u5B57\uFF08\u4E0D\u542B\u56DE\u8F66\uFF09\u3002" }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "hand_key",
+    tags: ["act"],
+    description: `\u6309\u4E00\u4E2A\u7CFB\u7EDF\u6309\u952E\uFF1A${"back\u3001home\u3001recents\u3001enter\u3001delete\u3001tab\u3001escape\u3001space\u3001up\u3001down\u3001left\u3001right\u3001volumeup\u3001volumedown\u3001power\u3001search\u3001menu"}\u3002\u8FD4\u56DE\u3001\u56DE\u684C\u9762\u3001\u786E\u8BA4\u641C\u7D22\u8FD9\u7C7B\u64CD\u4F5C\u7528\u5B83\uFF0C\u6BD4\u5728\u5C4F\u5E55\u4E0A\u627E\u6309\u94AE\u7A33\u3002`,
+    parameters: {
+      type: "object",
+      properties: {
+        key: {
+          type: "string",
+          enum: ["back", "home", "recents", "enter", "delete", "tab", "escape", "space", "up", "down", "left", "right", "volumeup", "volumedown", "power", "search", "menu"],
+          description: "\u6309\u952E\u540D\u3002"
+        }
+      },
+      required: ["key"]
+    }
+  },
+  {
+    name: "hand_status",
+    tags: ["read", "snapshot"],
+    description: "\u770B\u624B\u81EA\u5DF1\u7684\u72B6\u6001\uFF1A\u8D70\u54EA\u6761\u901A\u9053\u3001\u901A\u4E0D\u901A\u3001\u8FD9\u4E00\u5206\u949F\u52A8\u4E86\u51E0\u4E2A\u52A8\u4F5C\u3001\u521A\u624D\u90A3\u4E00\u4E0B\u6210\u4E86\u6CA1\u6709\u3002\u5BF9\u65B9\u95EE\u300C\u624B\u80FD\u7528\u5417\u300D\u300C\u4F60\u521A\u624D\u70B9\u4E86\u4EC0\u4E48\u300D\u65F6\u7528\u5B83\u3002",
+    parameters: { type: "object", properties: {}, required: [] }
+  },
+  {
+    name: "hand_stop",
+    tags: ["flow"],
+    description: "\u7ACB\u523B\u505C\u624B\uFF1A\u4E00\u5206\u949F\u4E4B\u5185\u4E0D\u518D\u52A8\u4EFB\u4F55\u4E00\u4E0B\uFF08\u5DF2\u7ECF\u53D1\u51FA\u7684\u4E0D\u7B97\uFF09\u3002\u5BF9\u65B9\u8BF4\u300C\u522B\u52A8\u4E86\u300D\u300C\u505C\u4E0B\u300D\u6216\u8005\u4F60\u53D1\u73B0\u81EA\u5DF1\u70B9\u9519\u5730\u65B9\u65F6\u7528\u5B83\u3002",
+    parameters: { type: "object", properties: {}, required: [] }
+  }
+];
+
+// src/world.ts
+var ENV_PROMPT_FILE = fileURLToPath(new URL("./ENV_PROMPT.md", import.meta.url));
+function clock(tz) {
+  try {
+    return new Intl.DateTimeFormat("zh-CN", { timeZone: tz, hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false }).format(/* @__PURE__ */ new Date());
+  } catch {
+    return (/* @__PURE__ */ new Date()).toISOString().slice(11, 19);
+  }
+}
+var STOP_MS = 6e4;
+var HandsWorld = class {
+  id = HANDS_ID;
+  host = null;
+  log;
+  hands;
+  pausedUntil = 0;
+  recent = [];
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+    this.hands = new Hands(() => this.opts.cfg);
+  }
+  /* ---------- 生命周期 ---------- */
+  async start(host) {
+    this.host = host;
+    this.log = host.log;
+    this.hands.attachLog(host.log);
+    const state = await this.hands.probe(true);
+    this.log?.info(state.ok ? `\u624B\uFF1A${state.detail}` : `\u624B\u8FD8\u52A8\u4E0D\u4E86\uFF1A${state.detail}`);
+  }
+  async stop() {
+    this.host = null;
+  }
+  /* ---------- 给模型的说明书 ---------- */
+  envPromptVars() {
+    const cfg = this.opts.cfg;
+    const state = this.hands.state();
+    const stats = this.hands.stats();
+    const actuator = state.kind === "root" ? "root \u7684 input" : state.kind === "eyes" ? "\u65E0\u969C\u788D\u624B\u52BF" : state.kind === "shell" ? "\u4F60\u7ED9\u7684 shell \u901A\u9053" : "\u8FD8\u6CA1\u6709";
+    return {
+      "hands.state": cfg.enabled ? state.ok ? "\u80FD\u7528" : "\u88C5\u4E86\u4F46\u52A8\u4E0D\u4E86" : "\u5173\u7740",
+      "hands.actuator": state.ok ? actuator : `\u6CA1\u6709\u53EF\u7528\u7684\u901A\u9053\uFF08${state.detail}\uFF09`,
+      "hands.mode": cfg.dryRun ? "\u6F14\u7EC3\uFF08\u53EA\u770B\u4E0D\u505A\uFF09" : "\u771F\u52A8",
+      "hands.window": `\u8FD9\u4E00\u5206\u949F ${stats.inWindow}\uFF0F${Math.max(1, Math.round(cfg.maxActionsPerMinute) || 30)} \u4E0B`
+    };
+  }
+  /* ---------- 工具 ---------- */
+  tools() {
+    return HANDS_TOOL_DECLS.map((decl) => ({
+      ...decl,
+      handler: (args, ctx) => this.handle(decl.name, args, ctx)
+    }));
+  }
+  async handle(name, args, ctx) {
+    try {
+      await this.guard();
+      ctx.signal?.throwIfAborted();
+      switch (name) {
+        case "hand_look":
+          return await this.look(args);
+        case "hand_tap":
+          return await this.tap(args);
+        case "hand_long":
+          return await this.long(args);
+        case "hand_swipe":
+          return await this.swipe(args);
+        case "hand_type":
+          return await this.type(args);
+        case "hand_key":
+          return await this.key(args);
+        case "hand_status":
+          return this.statusText();
+        case "hand_stop":
+          return this.stopHands();
+        default:
+          return failed(`\u6CA1\u6709\u8FD9\u4E2A\u5DE5\u5177\uFF1A${name}`);
+      }
+    } catch (err) {
+      if (err instanceof HandError) return failed(err.message);
+      const detail = err instanceof Error ? err.message : String(err);
+      this.log?.warn(`\u624B\u51FA\u9519\uFF1A${detail}`);
+      return failed(`\u624B\u51FA\u4E86\u70B9\u95EE\u9898\uFF1A${detail}`);
+    }
+  }
+  /** 演练、叫停、总开关都在这里挡住。 */
+  async guard() {
+    if (!this.opts.cfg.enabled) throw new HandError("\u8FD9\u53EA\u624B\u8FD8\u6CA1\u6253\u5F00\uFF08\u8BBE\u7F6E \u2192 \u624B \u2192 \u542F\u7528\uFF09\u3002");
+    const left = this.pausedUntil - Date.now();
+    if (left > 0) throw new HandError(`\u624B\u88AB\u53EB\u505C\u4E86\uFF0C\u8FD8\u6709 ${Math.ceil(left / 1e3)} \u79D2\u624D\u80FD\u518D\u52A8\u3002`);
+  }
+  note(receipt) {
+    const stamp = clock(this.opts.timezone);
+    this.recent.unshift(`${stamp} ${receipt.text}`);
+    if (this.recent.length > 6) this.recent.length = 6;
+  }
+  async look(args) {
+    const detail = args.detail === "screen" || args.detail === "text" ? args.detail : "both";
+    const report = await this.hands.look(detail);
+    const blobs = report.blob ? [report.blob] : [];
+    return { text: report.text, ...blobs.length ? { blobs } : {} };
+  }
+  /** 给文字就先在屏幕上找，找到唯一一处才点；给坐标就直接点。 */
+  async tap(args) {
+    const text = typeof args.text === "string" ? args.text.trim() : "";
+    if (text) {
+      const hits = await this.hands.findText(text);
+      if (hits.length === 0) return failed(`\u5C4F\u5E55\u4E0A\u6CA1\u627E\u5230\u300C${text}\u300D\uFF0C\u5148 hand_look \u770B\u770B\u73B0\u5728\u662F\u4EC0\u4E48\u753B\u9762\u3002`);
+      const nth = args.nth === void 0 ? void 0 : Math.max(0, Math.round(Number(args.nth)));
+      if (nth === void 0) {
+        if (hits.length > 1) {
+          const list = hits.slice(0, 8).map((h, i) => `${i}. \u300C${h.text}\u300D@(${h.center.x},${h.center.y})`).join("\n");
+          return failed(`\u300C${text}\u300D\u5728\u5C4F\u5E55\u4E0A\u6709 ${hits.length} \u5904\uFF0C\u8BF4\u6E05\u695A\u70B9\u54EA\u4E2A\uFF08nth\uFF09\uFF1A
+${list}`);
+        }
+        const only = hits[0];
+        const receipt3 = await this.hands.tap(only.center.x, only.center.y);
+        this.note(receipt3);
+        return `${receipt3.text}\uFF08\u70B9\u7684\u662F\u300C${only.text}\u300D\uFF09`;
+      }
+      const hit = hits[nth];
+      if (!hit) return failed(`\u300C${text}\u300D\u53EA\u6709 ${hits.length} \u5904\uFF0C\u6CA1\u6709\u7B2C ${nth} \u4E2A\u3002`);
+      const receipt2 = await this.hands.tap(hit.center.x, hit.center.y);
+      this.note(receipt2);
+      return `${receipt2.text}\uFF08\u70B9\u7684\u662F\u300C${hit.text}\u300D\uFF09`;
+    }
+    const x = args.x;
+    const y = args.y;
+    if (x === void 0 || y === void 0) return failed("\u8981\u4E48\u7ED9 x \u548C y\uFF0C\u8981\u4E48\u7ED9 text\u3002");
+    const receipt = await this.hands.tap(Number(x), Number(y));
+    this.note(receipt);
+    return receipt.text;
+  }
+  async long(args) {
+    const receipt = await this.hands.longPress(Number(args.x), Number(args.y), { ms: args.ms === void 0 ? void 0 : Number(args.ms) });
+    this.note(receipt);
+    return receipt.text;
+  }
+  async swipe(args) {
+    const receipt = await this.hands.swipe(Number(args.x1), Number(args.y1), Number(args.x2), Number(args.y2), {
+      ms: args.ms === void 0 ? void 0 : Number(args.ms)
+    });
+    this.note(receipt);
+    return receipt.text;
+  }
+  async type(args) {
+    const receipt = await this.hands.type(String(args.text ?? ""));
+    this.note(receipt);
+    return receipt.text;
+  }
+  async key(args) {
+    const receipt = await this.hands.press(String(args.key ?? ""));
+    this.note(receipt);
+    return receipt.text;
+  }
+  statusText() {
+    const cfg = this.opts.cfg;
+    const state = this.hands.state();
+    const stats = this.hands.stats();
+    const lines = [
+      cfg.enabled ? "\u624B\uFF1A\u5F00\u7740" : "\u624B\uFF1A\u5173\u7740",
+      cfg.dryRun ? "\u6A21\u5F0F\uFF1A\u6F14\u7EC3\uFF08\u53EA\u770B\u4E0D\u505A\uFF09" : "\u6A21\u5F0F\uFF1A\u771F\u52A8",
+      state.ok ? `\u901A\u9053\uFF1A${state.kind}\uFF08${state.detail}\uFF09` : `\u901A\u9053\uFF1A\u6CA1\u6709\u53EF\u7528\u7684\uFF08${state.detail}\uFF09`,
+      `\u8FD9\u4E00\u5206\u949F\uFF1A${stats.inWindow}\uFF0F${Math.max(1, Math.round(cfg.maxActionsPerMinute) || 30)} \u4E0B\uFF1B\u7D2F\u8BA1\u52A8\u8FC7 ${stats.acts} \u6B21\u3001\u770B\u8FC7 ${stats.looks} \u6B21`
+    ];
+    if (this.pausedUntil > Date.now()) lines.push(`\u53EB\u505C\u4E2D\uFF1A\u8FD8\u6709 ${Math.ceil((this.pausedUntil - Date.now()) / 1e3)} \u79D2`);
+    if (this.recent.length) lines.push(`\u6700\u8FD1\uFF1A
+${this.recent.map((r) => `- ${r}`).join("\n")}`);
+    return lines.join("\n");
+  }
+  stopHands() {
+    this.pausedUntil = Date.now() + STOP_MS;
+    this.log?.info("\u624B\uFF1A\u88AB\u53EB\u505C\u4E00\u5206\u949F");
+    return `\u505C\u624B\u4E86\uFF1A${STOP_MS / 1e3} \u79D2\u4E4B\u5185\u4E0D\u4F1A\u518D\u52A8\u4EFB\u4F55\u4E00\u4E0B\u3002`;
+  }
+  /* ---------- 控制台 ---------- */
+  /**
+   * world 契约 v5 的名字。手要能装进还没升级的 payload（手机里那份就是 v5），
+   * 所以两个名字都给，返回同一张声明。
+   */
+  console(language = "zh") {
+    return this.webUi(language);
+  }
+  webUi(language = "zh") {
+    const zh = language === "zh";
+    const cfg = this.opts.cfg;
+    const state = this.hands.state();
+    const stats = this.hands.stats();
+    const max = Math.max(1, Math.round(cfg.maxActionsPerMinute) || 30);
+    return {
+      label: zh ? "\u624B" : "Hands",
+      lamps: [
+        {
+          label: zh ? "\u901A\u9053" : "Actuator",
+          state: state.ok ? "online" : cfg.actuator === "off" ? "offline" : "error",
+          hint: state.detail
+        },
+        {
+          label: zh ? "\u6A21\u5F0F" : "Mode",
+          state: cfg.dryRun ? "loading" : "online",
+          hint: cfg.dryRun ? zh ? "\u6F14\u7EC3\uFF1A\u53EA\u770B\u4E0D\u505A" : "Dry run" : zh ? "\u771F\u52A8" : "Live"
+        },
+        {
+          label: zh ? "\u8282\u6D41" : "Throttle",
+          state: stats.inWindow >= max ? "error" : "online",
+          hint: `${stats.inWindow}/${max} ${zh ? "\u6BCF\u5206\u949F" : "per minute"}`
+        }
+      ],
+      badges: [
+        { label: zh ? "\u52A8\u8FC7" : "actions", value: stats.acts, tone: "plain" },
+        { label: zh ? "\u770B\u8FC7" : "looks", value: stats.looks, tone: "plain" }
+      ],
+      config: [HANDS_CONFIG_GROUP, HANDS_LOOK_CONFIG_GROUP],
+      promptDocs: [
+        {
+          key: `worlds.${HANDS_ID}.envPrompt`,
+          title: zh ? "\u624B\u7684\u73AF\u5883" : "Hands environment",
+          description: zh ? "\u63CF\u8FF0\u8FD9\u53EA\u624B\u80FD\u600E\u4E48\u52A8\u3001\u8D70\u54EA\u6761\u901A\u9053\u3001\u4EE5\u53CA\u300C\u5148\u770B\u518D\u52A8\u624B\u300D\u7684\u89C4\u77E9\u3002" : "What the hands can do, which actuator they use, and the look-before-touch rule.",
+          path: ENV_PROMPT_FILE,
+          role: "envPrompt",
+          vars: [
+            { name: "hands.state", description: zh ? "\u80FD\u7528 / \u88C5\u4E86\u4F46\u52A8\u4E0D\u4E86 / \u5173\u7740" : "available / installed but dead / off" },
+            { name: "hands.actuator", description: zh ? "\u73B0\u5728\u8FD9\u6761\u901A\u9053\u662F\u4EC0\u4E48\u3001\u901A\u4E0D\u901A" : "which actuator, and whether it works" },
+            { name: "hands.mode", description: zh ? "\u6F14\u7EC3\u8FD8\u662F\u771F\u52A8" : "dry run or live" },
+            { name: "hands.window", description: zh ? "\u8FD9\u4E00\u5206\u949F\u5DF2\u7ECF\u52A8\u4E86\u51E0\u6B21\u3001\u4E0A\u9650\u591A\u5C11" : "actions in the last minute and the cap" }
+          ]
+        }
+      ]
+    };
+  }
+};
+function failed(text) {
+  return { text, failed: true };
+}
+
+// src/definition.ts
+function handsDefinition() {
+  return {
+    id: HANDS_ID,
+    label: "\u624B",
+    defaults: () => structuredClone(HANDS_DEFAULTS),
+    create: (ctx) => new HandsWorld({ cfg: ctx.cfg, timezone: ctx.timezone })
+  };
+}
+var HANDS = handsDefinition();
+var definition_default = HANDS;
+export {
+  HANDS,
+  HANDS_DEFAULTS,
+  HANDS_ID,
+  HANDS_TOOL_DECLS,
+  HandError,
+  Hands,
+  HandsWorld,
+  KEY_CODES,
+  definition_default as default,
+  handsDefinition
+};

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "cortico-world-hands",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cortico World: hands for the desktop pet — looks at the phone screen, then taps, swipes, types and presses keys through whatever actuator the device actually has",
+  "license": "MIT",
+  "keywords": [
+    "cortico-world",
+    "cortico",
+    "hands",
+    "automation",
+    "accessibility"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "cortico": {
+    "kind": "world",
+    "api": 5,
+    "displayName": "手"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {}
+}