minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/accessibilityPermission.ts

@@ -0,0 +1,294 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * macOS 权限引导工具。
+ *
+ * 设计参考：UI-TARS-desktop/apps/ui-tars/src/main/utils/systemPermissions.ts
+ *
+ * 核心原则：
+ * 1. 实际调用系统 API（CGEventPost / CGDisplayCreateImage）的是 cu-helperd 守护进程，
+ *    因此 macOS TCC 权限数据库中记录的是 cu-helperd 二进制的权限状态。
+ * 2. 系统原生权限弹窗（AXIsProcessTrustedWithOptions / CGRequestScreenCaptureAccess）
+ *    由 cu-helperd 在首次需要时自动触发，但这种弹窗有局限性：
+ *    - 只在权限状态为 "not determined" 时弹出一次
+ *    - 用户如果点了"拒绝"，之后不会再弹，必须手动去系统设置
+ *    - 从后台进程触发弹窗有时会被其他窗口遮挡
+ * 3. 因此本模块的核心策略是：**主动探测 + 自动打开设置 + 明确文字引导**，
+ *    参考 UI-TARS 的 openSystemPreferences() 做法，不管什么状态，只要权限缺失
+ *    就直接打开系统设置页面，让用户一目了然该勾选什么。
+ */
+
+/**
+ * 打开 macOS 系统设置 → 隐私与安全性 → 辅助功能 页面。
+ */
+export function openAccessibilitySettings(): void {
+  if (process.platform !== 'darwin') return;
+  try {
+    execSync(
+      'open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"',
+      { stdio: 'ignore', timeout: 5000 },
+    );
+  } catch {
+    // fallback：如果系统设置URL scheme失效，尝试直接打开系统设置应用
+    try { execSync('open "x-apple.systempreferences:"', { stdio: 'ignore', timeout: 5000 }); } catch {}
+  }
+}
+
+/**
+ * 打开 macOS 系统设置 → 隐私与安全性 → 屏幕录制 页面。
+ */
+export function openScreenCaptureSettings(): void {
+  if (process.platform !== 'darwin') return;
+  try {
+    execSync(
+      'open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"',
+      { stdio: 'ignore', timeout: 5000 },
+    );
+  } catch {
+    try { execSync('open "x-apple.systempreferences:"', { stdio: 'ignore', timeout: 5000 }); } catch {}
+  }
+}
+
+/**
+ * 检测当前是否运行在一个 .app bundle 内部（即 Tauri/Electron 打包后的生产环境）。
+ */
+export function isRunningInAppBundle(): boolean {
+  if (process.platform !== 'darwin') return false;
+  return process.execPath.includes('.app/Contents/MacOS/');
+}
+
+/**
+ * 获取权限引导信息中应该告诉用户查找哪个应用名。
+ *
+ * **只有两种情况**，因为实际调用系统 API 的进程只有两种：
+ *   · 打包进 .app 时，TCC 记的是宿主 App → 让用户找 "KakadeAI"
+ *   · 其余（CLI / dev）由 cu-helperd 守护进程调用 → 让用户找 "cu-helperd"
+ *
+ * 这里曾有第三种「终端应用名（Terminal/iTerm/Warp…）」分支，服务于已移除的
+ * nut-js transport —— 它在主进程内直接调 CGEvent，于是 TCC 记的是终端。
+ * nut-js 移除后那条分支恒为误导（会让用户去给终端授权，而真正需要授权的是
+ * cu-helperd），所以一并删除。
+ */
+export function getPermissionTargetName(): string {
+  return isRunningInAppBundle() ? 'KakadeAI' : 'cu-helperd';
+}
+
+/**
+ * 权限状态（与 cu-helperd protocol 中的 PermissionState 对齐）。
+ */
+export type MacPermissionState = 'granted' | 'not_determined' | 'denied';
+
+export interface PermissionCheckResult {
+  accessibility: MacPermissionState;
+  screenCapture: MacPermissionState;
+  /** 是否有缺失的权限需要用户授权 */
+  hasMissingPermissions: boolean;
+  /** 缺失的权限列表描述 */
+  missingPermissions: Array<'accessibility' | 'screenCapture'>;
+  /**
+   * 这次**查询本身**失败了（守护进程报错、认证失败、响应形状不认识）。
+   *
+   * 与「查到了、结果是没授权」是两件完全不同的事，必须分开：前者要修的是我们自己，
+   * 后者才该去引导用户点系统设置。混为一谈的代价是真实发生过的 —— 见
+   * `parsePermissionResponse` 的注释。
+   */
+  queryFailed: boolean;
+}
+
+/**
+ * 解析 cu-helperd 返回的 permissions 响应，生成标准化的检查结果。
+ * 支持多种响应格式：
+ * - 原生 wire 格式：{ response: { Ok: { accessibility, screenCapture } } }
+ * - 高层 service 格式：{ ok: true, data: { accessibility, screenCapture } }
+ * - 纯数据格式：{ accessibility, screenCapture }
+ */
+const PERMISSION_STATES = new Set(['granted', 'denied', 'not_determined']);
+
+/**
+ * ⚠️ **「查不到」绝不能当成「没授权」。**
+ *
+ * 这里以前从任意形状的响应里挖 `accessibility` / `screenCapture`，挖不到就默认
+ * `not_determined`，于是**错误信封被当成了权限答案**：守护进程返回
+ * `{response:{Err:{code:'authentication_failed'}}}`，两个字段自然都不存在，函数愉快地
+ * 报告「两个权限都缺失」，调用方打印一整屏「请去系统设置授权」。
+ *
+ * 而它确实一直在返回这个错误 —— `probePermissions` 把 32 字节的二进制配对令牌按
+ * utf8 读，HMAC 必然对不上。也就是说这个自检**从未成功过一次**，却始终显得像是在工作。
+ * 真实代价：用户被反复引去检查根本没问题的系统设置，而真正的故障在完全不同的地方；
+ * 排查中先后错怪了 cdhash、用户的授权配置和另一处改动。
+ *
+ * 修法不是把那次读改对就完了 —— 那只堵住一个诱因。判据本身必须能表达「我不知道」。
+ */
+export function parsePermissionResponse(permResp: any): PermissionCheckResult {
+  const unknown = (): PermissionCheckResult => ({
+    accessibility: 'not_determined',
+    screenCapture: 'not_determined',
+    // 查询失败时**不**声称有权限缺失：那会把用户引向系统设置，而问题不在那儿。
+    hasMissingPermissions: false,
+    missingPermissions: [],
+    queryFailed: true,
+  });
+
+  // 明确的错误信封：直接判定为「查询失败」，不去它身上找权限字段。
+  if (permResp?.response?.Err || permResp?.ok === false) return unknown();
+
+  let perms: any = permResp;
+  if (permResp?.response?.Ok) {
+    perms = permResp.response.Ok; // 原生 wire 格式
+  } else if (permResp?.ok && permResp?.data) {
+    perms = permResp.data; // 高层 service 格式（diagnostics/request 返回）
+  }
+
+  // 两个字段**都**认不出来 = 这根本不是一份权限响应，而不是「两个权限都没授权」。
+  const knownAccessibility = PERMISSION_STATES.has(perms?.accessibility);
+  const knownScreenCapture = PERMISSION_STATES.has(perms?.screenCapture);
+  if (!knownAccessibility && !knownScreenCapture) return unknown();
+
+  const accessibility: MacPermissionState = knownAccessibility
+    ? perms.accessibility
+    : 'not_determined';
+  const screenCapture: MacPermissionState = knownScreenCapture
+    ? perms.screenCapture
+    : 'not_determined';
+
+  const missingPermissions: Array<'accessibility' | 'screenCapture'> = [];
+  if (accessibility !== 'granted') missingPermissions.push('accessibility');
+  if (screenCapture !== 'granted') missingPermissions.push('screenCapture');
+  return {
+    accessibility,
+    screenCapture,
+    hasMissingPermissions: missingPermissions.length > 0,
+    missingPermissions,
+    queryFailed: false,
+  };
+}
+
+/**
+ * 打印醒目的权限缺失提示，并自动打开系统设置。
+ * 参考 UI-TARS 的 wrapWithWarning + openSystemPreferences 模式。
+ *
+ * 引导文案遵循三层结构：
+ *   1. 为什么需要这些权限（让用户理解价值，减少抵触）
+ *   2. 具体要做什么（分步骤、目标明确）
+ *   3. 遇到问题怎么办（找不到应用、已勾选仍不行等常见坑）
+ */
+export function showPermissionGuidance(result: PermissionCheckResult): void {
+  if (process.platform !== 'darwin') return;
+  if (!result.hasMissingPermissions) return;
+
+  const targetName = getPermissionTargetName();
+  const lines: string[] = [];
+  const inAppBundle = isRunningInAppBundle();
+
+  lines.push('');
+  lines.push('╔════════════════════════════════════════════════════════════════╗');
+  lines.push('║  ⚠️  需要授予 macOS 系统权限才能使用「电脑操控」功能         ║');
+  lines.push('╚════════════════════════════════════════════════════════════════╝');
+  lines.push('');
+
+  // 第 1 层：需要什么权限、为什么需要
+  lines.push('—— 需要授予的权限 ——');
+  lines.push('');
+  if (result.missingPermissions.includes('accessibility')) {
+    lines.push('  🖱️  辅助功能（Accessibility）');
+    lines.push('     用途：控制鼠标移动/点击、模拟键盘输入、拖拽操作');
+    lines.push('     没有它：AI 无法操作你的鼠标和键盘');
+    lines.push('');
+  }
+  if (result.missingPermissions.includes('screenCapture')) {
+    lines.push('  📷  屏幕录制（Screen Recording）');
+    lines.push('     用途：读取屏幕画面，让 AI "看到" 你当前的界面');
+    lines.push('     没有它：AI 看不到屏幕，无法判断该点哪里、该做什么');
+    lines.push('');
+  }
+
+  lines.push('👉 已为你自动打开「系统设置 → 隐私与安全性」对应页面');
+  lines.push('');
+
+  // 第 2 层：具体操作步骤
+  lines.push('—— 授权步骤（只需 4 步，约 30 秒）——');
+  lines.push('');
+
+  const permLabels: string[] = [];
+  if (result.missingPermissions.includes('accessibility')) permLabels.push('辅助功能');
+  if (result.missingPermissions.includes('screenCapture')) permLabels.push('屏幕录制');
+
+  lines.push(`  1. 在系统设置中，依次点击「隐私与安全性」→「${permLabels[0]}」`);
+  if (permLabels.length > 1) {
+    lines.push(`     （两个权限都需要授权，授权完一个再切换到另一个）`);
+  }
+  lines.push('  2. 点击左下角 🔒 锁形图标，输入开机密码解锁');
+  lines.push(`  3. 在右侧应用列表中找到「${targetName}」，打开它的开关`);
+
+  if (!inAppBundle) {
+    lines.push('     ⓘ  这里要授权的是 cu-helperd（守护进程），不是你的终端 ——');
+    lines.push('        真正调用系统 API 的是它，所以 macOS 记录的也是它的权限。');
+  }
+
+  lines.push('  4. 完成后回到这里，继续让 AI 操作即可');
+  lines.push('');
+
+  // 第 3 层：常见问题 / 排错
+  lines.push('—— 常见问题 ——');
+  lines.push('');
+  lines.push('  Q: 列表里找不到「' + targetName + '」怎么办？');
+  lines.push('  A: 点击列表下方的 ➕ 按钮，手动添加' + targetName);
+  if (!inAppBundle) {
+    lines.push('     （cu-helperd 随包位于 vendor/computer-use/<arch>-<plat>/ 目录下；');
+    lines.push('      源码构建时在 computer-use-native/target/release/）');
+    lines.push('     也可以先让 AI 执行一次操作，cu-helperd 会主动弹出系统授权请求。');
+  }
+  lines.push('');
+  lines.push('  Q: 已经勾选了，但还是提示权限不足？');
+  lines.push('  A: 把开关先关掉再重新打开一次，macOS 有时需要重新确认。');
+  lines.push('     如果仍然不行，重启应用后再试。');
+  lines.push('');
+  lines.push('  Q: 这些权限安全吗？会不会泄露隐私？');
+  lines.push('  A: 权限只在本地使用，屏幕画面和操作都不会上传到任何服务器。');
+  lines.push('     AI 模型只接收截图用于分析操作，不做存储。');
+  lines.push('');
+
+  // 输出到 stderr，确保在 TUI/CLI 中都能看到
+  for (const line of lines) {
+    process.stderr.write(line + '\n');
+  }
+
+  // 自动打开对应的设置页面（优先屏幕录制，因为最直观）
+  if (result.missingPermissions.includes('screenCapture')) {
+    try {
+      openScreenCaptureSettings();
+    } catch {
+      process.stderr.write('  ⚠️  未能自动打开系统设置，请手动打开：系统设置 → 隐私与安全性 → 屏幕录制\n');
+    }
+  }
+  if (result.missingPermissions.includes('accessibility')) {
+    try {
+      openAccessibilitySettings();
+    } catch {
+      process.stderr.write('  ⚠️  未能自动打开系统设置，请手动打开：系统设置 → 隐私与安全性 → 辅助功能\n');
+    }
+  }
+}
+
+/**
+ * 一次性完成权限检查：解析响应、打印引导、打开设置。
+ * 返回 true 表示权限齐全可以继续，false 表示需要用户授权。
+ */
+export function ensureMacPermissions(permResp: any): boolean {
+  if (process.platform !== 'darwin') return true;
+  const result = parsePermissionResponse(permResp);
+  if (result.queryFailed) {
+    // 查询本身失败：说一句，然后**闭嘴**。既不打印权限引导（问题不在用户的设置里），
+    // 也不阻断（真正的动作走的是另一条通道，它自己会如实报错）。
+    process.stderr.write(
+      '[computer-use] 权限自检未能取得结果（守护进程没有返回可识别的权限响应）。'
+      + '这是自检本身的问题，不代表权限缺失；实际操作若受阻会单独报错。\n',
+    );
+    return true;
+  }
+  if (result.hasMissingPermissions) {
+    showPermissionGuidance(result);
+    return false;
+  }
+  return true;
+}

package/src/tools/computeruse/axSearch.js

@@ -0,0 +1,96 @@
+/**
+ * ============================================================
+ *  axSearch.ts —— 无障碍树里的查找原语（纯函数）
+ * ------------------------------------------------------------
+ *  三个消费方共用这一份：
+ *   · `manualSchema.ts::evaluatePrecondition` 的 element_exists / 文本谓词
+ *   · `waitFor.ts` 的 wait_for_element / wait_for_text
+ *   · `computeruse.ts` 的 click-by-text（`textTarget` → elementId）
+ *
+ *  分出来的理由不是「代码复用」，是**判据必须一致**：说明书里写
+ *  `precondition: element_exists AXButton:发送`，模型接着 `wait_for_element`
+ *  等同一个控件，然后 `textTarget:"发送"` 去点它 —— 这三步要是各用一套匹配
+ *  规则，就会出现「前提说成立、等待等不到」或者「等到了、点的是另一个」。
+ *
+ *  ★ 匹配一律**大小写不敏感的子串**，而不是相等。AX 的 name 常带修饰
+ *  （「发送 (⌘↩)」「Send Message」），要求相等等于要求调用方精确复述系统文案。
+ *  role 例外：它是枚举（AXButton/AXTextField…），用相等。
+ * ============================================================
+ */
+/** 大小写不敏感的子串包含。空 needle 视为不匹配（避免「搜空串命中一切」）。 */
+export function containsFold(haystack, needle) {
+    if (!needle)
+        return false;
+    return (haystack ?? '').toLowerCase().includes(needle.toLowerCase());
+}
+/** 去所有空白（空格/全角空格/制表符/换行）后再做大小写不敏感包含匹配。
+ *  用于中文场景：AX name 常带空格（如「发 送」「微信(3)」），模型输入可能不带空格。 */
+export function containsFoldLoose(haystack, needle) {
+    if (!needle)
+        return false;
+    const strip = (s) => s.replace(/[\s\u3000\u00a0\u200b]/g, '').toLowerCase();
+    return strip(haystack ?? '').includes(strip(needle));
+}
+/** 深度优先展平。顺序稳定 —— 多个候选时「第一个」必须可复现。 */
+export function flattenAx(node) {
+    if (!node || typeof node !== 'object')
+        return [];
+    return [node, ...(node.children ?? []).flatMap(flattenAx)];
+}
+/** role 相等（大小写不敏感）。缺 role 的节点永不匹配。 */
+export function matchesRole(node, role) {
+    if (!role)
+        return false;
+    return (node.role ?? '').toLowerCase() === role.toLowerCase();
+}
+/** 节点的可见文本：name 或 value 任一含给定片段。 */
+export function matchesText(node, text) {
+    return containsFold(node.name, text) || containsFold(node.value, text);
+}
+/** 宽松文本匹配：先按普通 containsFold，再试去空白的 loose 匹配（中文场景友好）。 */
+export function matchesTextLoose(node, text) {
+    if (matchesText(node, text))
+        return true;
+    return containsFoldLoose(node.name, text) || containsFoldLoose(node.value, text);
+}
+/**
+ * 按 role（+ 可选名字片段）找控件。
+ *
+ * `spec` 用说明书里 `element_exists` 的同一语法：`AXButton` 或 `AXButton:发送`。
+ * 共用语法是有意的 —— 模型在注入的摘要里见到的就是这个形状。
+ */
+export function findByElementSpec(nodes, spec) {
+    const [rawRole, ...rest] = spec.split(':');
+    const role = (rawRole ?? '').trim();
+    const namePart = rest.join(':').trim();
+    return nodes.filter((node) => matchesRole(node, role) && (!namePart || containsFold(node.name, namePart)));
+}
+/** 按 role + 可选名字片段找控件（结构化入参版本）。 */
+export function findByRole(nodes, role, nameFragment) {
+    return nodes.filter((node) => matchesRole(node, role) && (!nameFragment || containsFold(node.name, nameFragment)));
+}
+/**
+ * 按文字找**可点**的控件。
+ *
+ * 只返回带 `elementId` 且有 `bounds` 的节点：click-by-text 最终要走 elementId
+ * 定位，一个说得出名字却给不出位置的节点点不了，把它算进候选只会让「多个匹配」
+ * 的拒绝变得莫名其妙。
+ *
+ * 匹配策略：先精确包含匹配，命中为 0 时再试去空白的宽松匹配（中文场景下 AX name
+ * 常夹杂空格/全角空格，模型输入不会带这些）。
+ */
+export function findClickableByText(nodes, text) {
+    const eligible = nodes.filter((node) => Boolean(node.elementId) && Boolean(node.bounds));
+    const exact = eligible.filter((node) => matchesText(node, text));
+    if (exact.length > 0)
+        return exact;
+    return eligible.filter((node) => matchesTextLoose(node, text));
+}
+/** 人话描述一个候选，用于「多个匹配」时把选择权交回给模型。 */
+export function describeNode(node) {
+    const name = node.name ? `「${node.name}」` : '（无名字）';
+    const where = node.bounds
+        ? `位于 (${Math.round(node.bounds.x)},${Math.round(node.bounds.y)})`
+        : '无位置';
+    return `${node.role ?? '未知角色'} ${name} ${where}${node.elementId ? ` · ${node.elementId}` : ''}`;
+}

package/src/tools/computeruse/axSearch.ts

@@ -0,0 +1,120 @@
+/**
+ * ============================================================
+ *  axSearch.ts —— 无障碍树里的查找原语（纯函数）
+ * ------------------------------------------------------------
+ *  三个消费方共用这一份：
+ *   · `manualSchema.ts::evaluatePrecondition` 的 element_exists / 文本谓词
+ *   · `waitFor.ts` 的 wait_for_element / wait_for_text
+ *   · `computeruse.ts` 的 click-by-text（`textTarget` → elementId）
+ *
+ *  分出来的理由不是「代码复用」，是**判据必须一致**：说明书里写
+ *  `precondition: element_exists AXButton:发送`，模型接着 `wait_for_element`
+ *  等同一个控件，然后 `textTarget:"发送"` 去点它 —— 这三步要是各用一套匹配
+ *  规则，就会出现「前提说成立、等待等不到」或者「等到了、点的是另一个」。
+ *
+ *  ★ 匹配一律**大小写不敏感的子串**，而不是相等。AX 的 name 常带修饰
+ *  （「发送 (⌘↩)」「Send Message」），要求相等等于要求调用方精确复述系统文案。
+ *  role 例外：它是枚举（AXButton/AXTextField…），用相等。
+ * ============================================================
+ */
+
+/** 查找只关心这几件事，不绑具体协议类型（便于合成测试）。 */
+export interface AxSearchNode {
+  elementId?: string;
+  role?: string;
+  name?: string;
+  value?: string;
+  subrole?: string;
+  focused?: boolean;
+  enabled?: boolean;
+  actions?: string[];
+  bounds?: { x: number; y: number; width: number; height: number };
+  children?: AxSearchNode[];
+}
+
+/** 大小写不敏感的子串包含。空 needle 视为不匹配（避免「搜空串命中一切」）。 */
+export function containsFold(haystack: string | undefined, needle: string): boolean {
+  if (!needle) return false;
+  return (haystack ?? '').toLowerCase().includes(needle.toLowerCase());
+}
+
+/** 去所有空白（空格/全角空格/制表符/换行）后再做大小写不敏感包含匹配。
+ *  用于中文场景：AX name 常带空格（如「发 送」「微信(3)」），模型输入可能不带空格。 */
+export function containsFoldLoose(haystack: string | undefined, needle: string): boolean {
+  if (!needle) return false;
+  const strip = (s: string) => s.replace(/[\s\u3000\u00a0\u200b]/g, '').toLowerCase();
+  return strip(haystack ?? '').includes(strip(needle));
+}
+
+/** 深度优先展平。顺序稳定 —— 多个候选时「第一个」必须可复现。 */
+export function flattenAx(node: AxSearchNode | undefined | null): AxSearchNode[] {
+  if (!node || typeof node !== 'object') return [];
+  return [node, ...(node.children ?? []).flatMap(flattenAx)];
+}
+
+/** role 相等（大小写不敏感）。缺 role 的节点永不匹配。 */
+export function matchesRole(node: AxSearchNode, role: string): boolean {
+  if (!role) return false;
+  return (node.role ?? '').toLowerCase() === role.toLowerCase();
+}
+
+/** 节点的可见文本：name 或 value 任一含给定片段。 */
+export function matchesText(node: AxSearchNode, text: string): boolean {
+  return containsFold(node.name, text) || containsFold(node.value, text);
+}
+
+/** 宽松文本匹配：先按普通 containsFold，再试去空白的 loose 匹配（中文场景友好）。 */
+export function matchesTextLoose(node: AxSearchNode, text: string): boolean {
+  if (matchesText(node, text)) return true;
+  return containsFoldLoose(node.name, text) || containsFoldLoose(node.value, text);
+}
+
+/**
+ * 按 role（+ 可选名字片段）找控件。
+ *
+ * `spec` 用说明书里 `element_exists` 的同一语法：`AXButton` 或 `AXButton:发送`。
+ * 共用语法是有意的 —— 模型在注入的摘要里见到的就是这个形状。
+ */
+export function findByElementSpec(nodes: AxSearchNode[], spec: string): AxSearchNode[] {
+  const [rawRole, ...rest] = spec.split(':');
+  const role = (rawRole ?? '').trim();
+  const namePart = rest.join(':').trim();
+  return nodes.filter((node) =>
+    matchesRole(node, role) && (!namePart || containsFold(node.name, namePart)));
+}
+
+/** 按 role + 可选名字片段找控件（结构化入参版本）。 */
+export function findByRole(
+  nodes: AxSearchNode[],
+  role: string,
+  nameFragment?: string,
+): AxSearchNode[] {
+  return nodes.filter((node) =>
+    matchesRole(node, role) && (!nameFragment || containsFold(node.name, nameFragment)));
+}
+
+/**
+ * 按文字找**可点**的控件。
+ *
+ * 只返回带 `elementId` 且有 `bounds` 的节点：click-by-text 最终要走 elementId
+ * 定位，一个说得出名字却给不出位置的节点点不了，把它算进候选只会让「多个匹配」
+ * 的拒绝变得莫名其妙。
+ *
+ * 匹配策略：先精确包含匹配，命中为 0 时再试去空白的宽松匹配（中文场景下 AX name
+ * 常夹杂空格/全角空格，模型输入不会带这些）。
+ */
+export function findClickableByText(nodes: AxSearchNode[], text: string): AxSearchNode[] {
+  const eligible = nodes.filter((node) => Boolean(node.elementId) && Boolean(node.bounds));
+  const exact = eligible.filter((node) => matchesText(node, text));
+  if (exact.length > 0) return exact;
+  return eligible.filter((node) => matchesTextLoose(node, text));
+}
+
+/** 人话描述一个候选，用于「多个匹配」时把选择权交回给模型。 */
+export function describeNode(node: AxSearchNode): string {
+  const name = node.name ? `「${node.name}」` : '（无名字）';
+  const where = node.bounds
+    ? `位于 (${Math.round(node.bounds.x)},${Math.round(node.bounds.y)})`
+    : '无位置';
+  return `${node.role ?? '未知角色'} ${name} ${where}${node.elementId ? ` · ${node.elementId}` : ''}`;
+}