minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/axSnap.js

@@ -0,0 +1,272 @@
+/**
+ * ============================================================
+ *  axSnap.ts —— AX 元素最近邻吸附 & 元素摘要生成
+ * ------------------------------------------------------------
+ *  设计原则：
+ *   1. 完全透明：所有吸附操作都返回元数据，调用方必须明确告知模型
+ *   2. 阈值保护：只有距离足够近才吸附，不强行吸
+ *   3. AX不可用直接跳过：自绘应用（微信等）完全不影响
+ *   4. 零黑盒：吸附结果可追溯、可调试
+ * ============================================================
+ */
+import { flattenAx } from './axSearch.js';
+/**
+ * 可交互AX角色白名单——只有这些角色会被考虑用于点击吸附和摘要
+ *
+ * 过滤原则：
+ * - 用户点击/输入/选择会直接生效的控件 → 保留
+ * - 纯布局容器、静态文本、滚动区域 → 过滤掉（点了没用）
+ */
+const INTERACTIVE_AX_ROLES = new Set([
+    // 按钮类
+    'AXButton',
+    'AXLink',
+    'AXMenuItem',
+    'AXMenuBarItem',
+    'AXPopUpButton',
+    'AXCheckBox',
+    'AXRadioButton',
+    'AXDisclosureTriangle',
+    'AXSlider',
+    'AXStepper',
+    // 输入类
+    'AXTextField',
+    'AXTextArea',
+    'AXComboBox',
+    'AXSearchField',
+    'AXSecureTextField',
+    'AXValueIndicator',
+    // 列表/表格/大纲类
+    'AXCell',
+    'AXRow',
+    'AXOutlineRow',
+    'AXColumn',
+    'AXList',
+    'AXTable',
+    'AXOutline',
+    'AXBrowser',
+    // 标签/页签
+    'AXTabGroup',
+    'AXToolbar',
+    'AXToolbarButton',
+    'AXTab',
+    // 其他可交互
+    'AXImage', // 工具栏里的图标按钮通常是AXImage
+    'AXDockItem',
+    'AXStatusItem',
+    'AXSplitter',
+    'AXDrawer',
+    'AXGrowArea',
+    'AXHandle',
+]);
+/**
+ * 即使角色不在白名单，但如果有这些actions，也算可交互
+ */
+const INTERACTIVE_ACTIONS = new Set([
+    'AXPress',
+    'AXPick',
+    'AXCancel',
+    'AXConfirm',
+    'AXShowMenu',
+    'AXDecrement',
+    'AXIncrement',
+    'AXRaise',
+]);
+/** 吸附距离阈值：点击点距离元素中心超过这个像素数，不吸附 */
+const SNAP_DISTANCE_THRESHOLD_PX = 28;
+/** 元素摘要最多展示多少个（避免note太长浪费token） */
+const MAX_SUMMARY_ELEMENTS = 18;
+/**
+ * 判断一个AX节点是否是用户可以直接交互的控件
+ */
+function isInteractiveElement(node) {
+    if (!node.elementId || !node.bounds)
+        return false;
+    if (node.bounds.width <= 0 || node.bounds.height <= 0)
+        return false;
+    // 角色在白名单里
+    if (node.role && INTERACTIVE_AX_ROLES.has(node.role))
+        return true;
+    // 或者有明确的交互动作
+    if (node.actions) {
+        for (const action of node.actions) {
+            if (INTERACTIVE_ACTIONS.has(action))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 从ComputerState提取所有可交互AX元素
+ */
+export function extractInteractiveElements(state) {
+    if (!state.accessibility || state.accessibility.truncated)
+        return [];
+    const allNodes = flattenAx(state.accessibility.root);
+    const windowNodes = allNodes.filter(n => n.role === 'AXWindow' && n.bounds);
+    const result = [];
+    for (const node of allNodes) {
+        if (!isInteractiveElement(node))
+            continue;
+        // 判断元素是否在某个窗口内（过滤掉离屏/不可见元素）
+        let isInWindow = false;
+        if (node.bounds) {
+            for (const win of windowNodes) {
+                if (!win.bounds)
+                    continue;
+                const cx = node.bounds.x + node.bounds.width / 2;
+                const cy = node.bounds.y + node.bounds.height / 2;
+                if (cx >= win.bounds.x && cx <= win.bounds.x + win.bounds.width &&
+                    cy >= win.bounds.y && cy <= win.bounds.y + win.bounds.height) {
+                    isInWindow = true;
+                    break;
+                }
+            }
+        }
+        result.push({
+            elementId: node.elementId,
+            role: node.role ?? 'AXUnknown',
+            label: node.name ?? node.value,
+            subrole: node.subrole,
+            frame: node.bounds,
+            enabled: node.enabled ?? true,
+            focused: node.focused ?? false,
+            isInWindow,
+        });
+    }
+    // 优先显示：聚焦的元素 > 启用的元素 > 在窗口内的元素
+    result.sort((a, b) => {
+        if (a.focused !== b.focused)
+            return a.focused ? -1 : 1;
+        if (a.enabled !== b.enabled)
+            return a.enabled ? -1 : 1;
+        if (a.isInWindow !== b.isInWindow)
+            return a.isInWindow ? -1 : 1;
+        // 按面积从小到大（小的按钮更可能是目标）
+        const areaA = a.frame.width * a.frame.height;
+        const areaB = b.frame.width * b.frame.height;
+        return areaA - areaB;
+    });
+    return result;
+}
+/**
+ * 计算点到矩形的最短距离（点在矩形内则距离为0）
+ */
+function distancePointToRect(px, py, rx, ry, rw, rh) {
+    const cx = rx + rw / 2;
+    const cy = ry + rh / 2;
+    // 点在矩形内部
+    if (px >= rx && px <= rx + rw && py >= ry && py <= ry + rh) {
+        return { distance: 0, closestX: cx, closestY: cy };
+    }
+    // 计算最近点
+    const closestX = Math.max(rx, Math.min(px, rx + rw));
+    const closestY = Math.max(ry, Math.min(py, ry + rh));
+    const dx = px - closestX;
+    const dy = py - closestY;
+    return {
+        distance: Math.hypot(dx, dy),
+        closestX: cx, // 我们吸附到矩形中心，不是最近边缘点
+        closestY: cy,
+    };
+}
+/**
+ * 最近邻吸附：将0-1000比例坐标吸附到最近的AX元素中心
+ *
+ * @param relX 模型输入的bbox中心点x（0-1000）
+ * @param relY 模型输入的bbox中心点y（0-1000）
+ * @param state 当前观测状态
+ * @param display 目标显示器
+ * @returns 吸附结果
+ */
+export function snapToNearestAxElement(relX, relY, state, display) {
+    // AX树不可用时直接返回原坐标
+    if (!state.accessibility || state.accessibility.truncated) {
+        return { snapped: false, x: relX, y: relY };
+    }
+    const elements = extractInteractiveElements(state);
+    if (elements.length === 0) {
+        return { snapped: false, x: relX, y: relY };
+    }
+    // 将比例坐标转换为逻辑像素
+    const screenX = display.logicalBounds.x + (relX / 1000) * display.logicalBounds.width;
+    const screenY = display.logicalBounds.y + (relY / 1000) * display.logicalBounds.height;
+    let bestMatch = null;
+    for (const el of elements) {
+        if (!el.enabled)
+            continue; // 忽略禁用控件
+        const { distance } = distancePointToRect(screenX, screenY, el.frame.x, el.frame.y, el.frame.width, el.frame.height);
+        // 如果点在元素内部，直接命中
+        const inside = distance === 0;
+        if (inside) {
+            bestMatch = { element: el, distance: 0 };
+            break;
+        }
+        // 否则找最近的
+        if (distance < SNAP_DISTANCE_THRESHOLD_PX) {
+            if (!bestMatch || distance < bestMatch.distance) {
+                bestMatch = { element: el, distance };
+            }
+        }
+    }
+    if (!bestMatch) {
+        return { snapped: false, x: relX, y: relY };
+    }
+    // 将元素中心转换回0-1000比例坐标
+    const centerX = bestMatch.element.frame.x + bestMatch.element.frame.width / 2;
+    const centerY = bestMatch.element.frame.y + bestMatch.element.frame.height / 2;
+    const snappedRelX = ((centerX - display.logicalBounds.x) / display.logicalBounds.width) * 1000;
+    const snappedRelY = ((centerY - display.logicalBounds.y) / display.logicalBounds.height) * 1000;
+    return {
+        snapped: true,
+        x: Math.max(0, Math.min(1000, snappedRelX)),
+        y: Math.max(0, Math.min(1000, snappedRelY)),
+        element: bestMatch.element,
+        distancePx: bestMatch.distance,
+    };
+}
+/**
+ * 生成AX元素摘要文本，追加到截图note里给LLM看
+ *
+ * 格式：
+ * 【AX可交互元素（原生应用可用，直接用 elementId:"@1" 点击，比坐标更准）】
+ *   [@1] AXButton "关闭" (34,42)→(64,72)
+ *   [@2] AXTextField "搜索网站" (120,40)→(680,74) [聚焦中]
+ *   ...
+ * 自绘应用（如微信/Electron）若列表为空，直接用bbox坐标即可。
+ */
+export function generateAxElementSummary(state) {
+    if (!state.accessibility || state.accessibility.truncated)
+        return null;
+    const elements = extractInteractiveElements(state);
+    if (elements.length === 0)
+        return null;
+    const idMap = new Map();
+    const lines = [];
+    lines.push('');
+    lines.push(`【AX可交互元素（共${elements.length}个，原生应用可直接用 elementId:"@N" 点击，比坐标更准）】`);
+    const shown = elements.slice(0, MAX_SUMMARY_ELEMENTS);
+    for (let i = 0; i < shown.length; i++) {
+        const el = shown[i];
+        const shortId = `@${i + 1}`;
+        idMap.set(shortId, el.elementId);
+        const name = el.label ? ` "${el.label.length > 25 ? el.label.slice(0, 25) + '…' : el.label}"` : '';
+        const x1 = Math.round(el.frame.x);
+        const y1 = Math.round(el.frame.y);
+        const x2 = Math.round(el.frame.x + el.frame.width);
+        const y2 = Math.round(el.frame.y + el.frame.height);
+        const focusMark = el.focused ? ' [聚焦中]' : '';
+        const disabledMark = !el.enabled ? ' [禁用]' : '';
+        lines.push(`  [${shortId}] ${el.role}${name} (${x1},${y1})→(${x2},${y2})${focusMark}${disabledMark}`);
+    }
+    if (elements.length > MAX_SUMMARY_ELEMENTS) {
+        lines.push(`  ... 还有 ${elements.length - MAX_SUMMARY_ELEMENTS} 个元素未显示`);
+    }
+    lines.push('提示：原生 AppKit 控件优先用 elementId，比 bbox 坐标更准；**自绘界面**（Electron、Qt、Flutter、游戏化 UI，以及微信/抖音这类跨端客户端）无障碍树基本是空的，直接用 bbox 坐标即可。');
+    return {
+        noteText: lines.join('\n'),
+        idMap,
+        elements,
+        shown,
+    };
+}

package/src/tools/computeruse/axSnap.ts

@@ -0,0 +1,349 @@
+/**
+ * ============================================================
+ *  axSnap.ts —— AX 元素最近邻吸附 & 元素摘要生成
+ * ------------------------------------------------------------
+ *  设计原则：
+ *   1. 完全透明：所有吸附操作都返回元数据，调用方必须明确告知模型
+ *   2. 阈值保护：只有距离足够近才吸附，不强行吸
+ *   3. AX不可用直接跳过：自绘应用（微信等）完全不影响
+ *   4. 零黑盒：吸附结果可追溯、可调试
+ * ============================================================
+ */
+
+import { flattenAx, describeNode, type AxSearchNode } from './axSearch.js';
+import type { ComputerState, ComputerUseDisplay, ComputerUseRect } from './protocol.js';
+
+/**
+ * 可交互AX角色白名单——只有这些角色会被考虑用于点击吸附和摘要
+ * 
+ * 过滤原则：
+ * - 用户点击/输入/选择会直接生效的控件 → 保留
+ * - 纯布局容器、静态文本、滚动区域 → 过滤掉（点了没用）
+ */
+const INTERACTIVE_AX_ROLES = new Set([
+  // 按钮类
+  'AXButton',
+  'AXLink',
+  'AXMenuItem',
+  'AXMenuBarItem',
+  'AXPopUpButton',
+  'AXCheckBox',
+  'AXRadioButton',
+  'AXDisclosureTriangle',
+  'AXSlider',
+  'AXStepper',
+  // 输入类
+  'AXTextField',
+  'AXTextArea',
+  'AXComboBox',
+  'AXSearchField',
+  'AXSecureTextField',
+  'AXValueIndicator',
+  // 列表/表格/大纲类
+  'AXCell',
+  'AXRow',
+  'AXOutlineRow',
+  'AXColumn',
+  'AXList',
+  'AXTable',
+  'AXOutline',
+  'AXBrowser',
+  // 标签/页签
+  'AXTabGroup',
+  'AXToolbar',
+  'AXToolbarButton',
+  'AXTab',
+  // 其他可交互
+  'AXImage',       // 工具栏里的图标按钮通常是AXImage
+  'AXDockItem',
+  'AXStatusItem',
+  'AXSplitter',
+  'AXDrawer',
+  'AXGrowArea',
+  'AXHandle',
+]);
+
+/**
+ * 即使角色不在白名单，但如果有这些actions，也算可交互
+ */
+const INTERACTIVE_ACTIONS = new Set([
+  'AXPress',
+  'AXPick',
+  'AXCancel',
+  'AXConfirm',
+  'AXShowMenu',
+  'AXDecrement',
+  'AXIncrement',
+  'AXRaise',
+]);
+
+/** 吸附距离阈值：点击点距离元素中心超过这个像素数，不吸附 */
+const SNAP_DISTANCE_THRESHOLD_PX = 28;
+
+/** 元素摘要最多展示多少个（避免note太长浪费token） */
+const MAX_SUMMARY_ELEMENTS = 18;
+
+export interface AxInteractiveElement {
+  elementId: string;
+  role: string;
+  label?: string;
+  subrole?: string;
+  frame: ComputerUseRect; // 逻辑像素坐标
+  enabled: boolean;
+  focused: boolean;
+  isInWindow: boolean;
+}
+
+export interface AxSnapResult {
+  /** 是否发生了吸附 */
+  snapped: boolean;
+  /** 吸附后的坐标（0-1000比例），如果没吸附就是原始坐标 */
+  x: number;
+  y: number;
+  /** 吸附到的元素（如果snapped=true） */
+  element?: AxInteractiveElement;
+  /** 原始点击点距离元素中心的像素距离 */
+  distancePx?: number;
+}
+
+export interface AxElementSummary {
+  noteText: string;
+  /** 短id（@1,@2...）→ 真实elementId映射 */
+  idMap: Map<string, string>;
+  /** 所有提取到的元素 */
+  elements: AxInteractiveElement[];
+  /**
+   * **实际编了号的那批**（`elements` 截断到 MAX_SUMMARY_ELEMENTS 之后）。
+   *
+   * 图上的编号徽标必须画这一批、按这个顺序 —— 编号是文字清单与图像标注之间唯一的
+   * 桥。让绘图侧拿 `elements` 自己再截一次，两边的截断规则一旦不同步，图上的 ③ 就
+   * 会指向清单里的另一个控件，而这种错位在截图上完全看不出来。
+   */
+  shown: AxInteractiveElement[];
+}
+
+/**
+ * 判断一个AX节点是否是用户可以直接交互的控件
+ */
+function isInteractiveElement(node: AxSearchNode): boolean {
+  if (!node.elementId || !node.bounds) return false;
+  if (node.bounds.width <= 0 || node.bounds.height <= 0) return false;
+  
+  // 角色在白名单里
+  if (node.role && INTERACTIVE_AX_ROLES.has(node.role)) return true;
+  
+  // 或者有明确的交互动作
+  if (node.actions) {
+    for (const action of node.actions) {
+      if (INTERACTIVE_ACTIONS.has(action)) return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * 从ComputerState提取所有可交互AX元素
+ */
+export function extractInteractiveElements(state: ComputerState): AxInteractiveElement[] {
+  if (!state.accessibility || state.accessibility.truncated) return [];
+  
+  const allNodes = flattenAx(state.accessibility.root as AxSearchNode);
+  const windowNodes = allNodes.filter(n => n.role === 'AXWindow' && n.bounds);
+  
+  const result: AxInteractiveElement[] = [];
+  for (const node of allNodes) {
+    if (!isInteractiveElement(node)) continue;
+    
+    // 判断元素是否在某个窗口内（过滤掉离屏/不可见元素）
+    let isInWindow = false;
+    if (node.bounds) {
+      for (const win of windowNodes) {
+        if (!win.bounds) continue;
+        const cx = node.bounds.x + node.bounds.width / 2;
+        const cy = node.bounds.y + node.bounds.height / 2;
+        if (cx >= win.bounds.x && cx <= win.bounds.x + win.bounds.width &&
+            cy >= win.bounds.y && cy <= win.bounds.y + win.bounds.height) {
+          isInWindow = true;
+          break;
+        }
+      }
+    }
+    
+    result.push({
+      elementId: node.elementId!,
+      role: node.role ?? 'AXUnknown',
+      label: node.name ?? node.value,
+      subrole: (node as { subrole?: string }).subrole,
+      frame: node.bounds!,
+      enabled: (node as { enabled?: boolean }).enabled ?? true,
+      focused: node.focused ?? false,
+      isInWindow,
+    });
+  }
+  
+  // 优先显示：聚焦的元素 > 启用的元素 > 在窗口内的元素
+  result.sort((a, b) => {
+    if (a.focused !== b.focused) return a.focused ? -1 : 1;
+    if (a.enabled !== b.enabled) return a.enabled ? -1 : 1;
+    if (a.isInWindow !== b.isInWindow) return a.isInWindow ? -1 : 1;
+    // 按面积从小到大（小的按钮更可能是目标）
+    const areaA = a.frame.width * a.frame.height;
+    const areaB = b.frame.width * b.frame.height;
+    return areaA - areaB;
+  });
+  
+  return result;
+}
+
+/**
+ * 计算点到矩形的最短距离（点在矩形内则距离为0）
+ */
+function distancePointToRect(
+  px: number, py: number,
+  rx: number, ry: number, rw: number, rh: number
+): { distance: number; closestX: number; closestY: number } {
+  const cx = rx + rw / 2;
+  const cy = ry + rh / 2;
+  
+  // 点在矩形内部
+  if (px >= rx && px <= rx + rw && py >= ry && py <= ry + rh) {
+    return { distance: 0, closestX: cx, closestY: cy };
+  }
+  
+  // 计算最近点
+  const closestX = Math.max(rx, Math.min(px, rx + rw));
+  const closestY = Math.max(ry, Math.min(py, ry + rh));
+  const dx = px - closestX;
+  const dy = py - closestY;
+  
+  return {
+    distance: Math.hypot(dx, dy),
+    closestX: cx, // 我们吸附到矩形中心，不是最近边缘点
+    closestY: cy,
+  };
+}
+
+/**
+ * 最近邻吸附：将0-1000比例坐标吸附到最近的AX元素中心
+ * 
+ * @param relX 模型输入的bbox中心点x（0-1000）
+ * @param relY 模型输入的bbox中心点y（0-1000）
+ * @param state 当前观测状态
+ * @param display 目标显示器
+ * @returns 吸附结果
+ */
+export function snapToNearestAxElement(
+  relX: number,
+  relY: number,
+  state: ComputerState,
+  display: ComputerUseDisplay,
+): AxSnapResult {
+  // AX树不可用时直接返回原坐标
+  if (!state.accessibility || state.accessibility.truncated) {
+    return { snapped: false, x: relX, y: relY };
+  }
+  
+  const elements = extractInteractiveElements(state);
+  if (elements.length === 0) {
+    return { snapped: false, x: relX, y: relY };
+  }
+  
+  // 将比例坐标转换为逻辑像素
+  const screenX = display.logicalBounds.x + (relX / 1000) * display.logicalBounds.width;
+  const screenY = display.logicalBounds.y + (relY / 1000) * display.logicalBounds.height;
+  
+  let bestMatch: { element: AxInteractiveElement; distance: number } | null = null;
+  
+  for (const el of elements) {
+    if (!el.enabled) continue; // 忽略禁用控件
+    
+    const { distance } = distancePointToRect(
+      screenX, screenY,
+      el.frame.x, el.frame.y, el.frame.width, el.frame.height
+    );
+    
+    // 如果点在元素内部，直接命中
+    const inside = distance === 0;
+    
+    if (inside) {
+      bestMatch = { element: el, distance: 0 };
+      break;
+    }
+    
+    // 否则找最近的
+    if (distance < SNAP_DISTANCE_THRESHOLD_PX) {
+      if (!bestMatch || distance < bestMatch.distance) {
+        bestMatch = { element: el, distance };
+      }
+    }
+  }
+  
+  if (!bestMatch) {
+    return { snapped: false, x: relX, y: relY };
+  }
+  
+  // 将元素中心转换回0-1000比例坐标
+  const centerX = bestMatch.element.frame.x + bestMatch.element.frame.width / 2;
+  const centerY = bestMatch.element.frame.y + bestMatch.element.frame.height / 2;
+  const snappedRelX = ((centerX - display.logicalBounds.x) / display.logicalBounds.width) * 1000;
+  const snappedRelY = ((centerY - display.logicalBounds.y) / display.logicalBounds.height) * 1000;
+  
+  return {
+    snapped: true,
+    x: Math.max(0, Math.min(1000, snappedRelX)),
+    y: Math.max(0, Math.min(1000, snappedRelY)),
+    element: bestMatch.element,
+    distancePx: bestMatch.distance,
+  };
+}
+
+/**
+ * 生成AX元素摘要文本，追加到截图note里给LLM看
+ * 
+ * 格式：
+ * 【AX可交互元素（原生应用可用，直接用 elementId:"@1" 点击，比坐标更准）】
+ *   [@1] AXButton "关闭" (34,42)→(64,72)
+ *   [@2] AXTextField "搜索网站" (120,40)→(680,74) [聚焦中]
+ *   ...
+ * 自绘应用（如微信/Electron）若列表为空，直接用bbox坐标即可。
+ */
+export function generateAxElementSummary(state: ComputerState): AxElementSummary | null {
+  if (!state.accessibility || state.accessibility.truncated) return null;
+  
+  const elements = extractInteractiveElements(state);
+  if (elements.length === 0) return null;
+  
+  const idMap = new Map<string, string>();
+  const lines: string[] = [];
+  lines.push('');
+  lines.push(`【AX可交互元素（共${elements.length}个，原生应用可直接用 elementId:"@N" 点击，比坐标更准）】`);
+  
+  const shown = elements.slice(0, MAX_SUMMARY_ELEMENTS);
+  for (let i = 0; i < shown.length; i++) {
+    const el = shown[i];
+    const shortId = `@${i + 1}`;
+    idMap.set(shortId, el.elementId);
+    const name = el.label ? ` "${el.label.length > 25 ? el.label.slice(0, 25) + '…' : el.label}"` : '';
+    const x1 = Math.round(el.frame.x);
+    const y1 = Math.round(el.frame.y);
+    const x2 = Math.round(el.frame.x + el.frame.width);
+    const y2 = Math.round(el.frame.y + el.frame.height);
+    const focusMark = el.focused ? ' [聚焦中]' : '';
+    const disabledMark = !el.enabled ? ' [禁用]' : '';
+    
+    lines.push(`  [${shortId}] ${el.role}${name} (${x1},${y1})→(${x2},${y2})${focusMark}${disabledMark}`);
+  }
+  
+  if (elements.length > MAX_SUMMARY_ELEMENTS) {
+    lines.push(`  ... 还有 ${elements.length - MAX_SUMMARY_ELEMENTS} 个元素未显示`);
+  }
+  lines.push('提示：原生 AppKit 控件优先用 elementId，比 bbox 坐标更准；**自绘界面**（Electron、Qt、Flutter、游戏化 UI，以及微信/抖音这类跨端客户端）无障碍树基本是空的，直接用 bbox 坐标即可。');
+  
+  return {
+    noteText: lines.join('\n'),
+    idMap,
+    elements,
+    shown,
+  };
+}