minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/visionOcr.js

@@ -0,0 +1,115 @@
+/**
+ * 前台应用检测模块
+ *
+ * 本文件的核心职责是获取 macOS 前台应用信息（应用名、PID、Bundle ID、窗口尺寸），
+ * 供 computer-use 模块在每个观察周期填充 ComputerState.activeApp 字段。
+ *
+ * 历史背景：文件最初规划为本地 OCR（基于 tesseract.js），后按 SPEC §8 调整为
+ * 「文字识别由 VLM 视觉模型直接完成，不做本地 OCR」。tesseract.js 依赖已移除，
+ * 原 OCR 相关导出（recognizeText、recognizeScreenshot）已删除，文件名保留为
+ * visionOcr.ts 仅为向后兼容引用路径。
+ *
+ * 当前仅导出：
+ *   - getFrontmostApp(): Promise<ComputerUseApp | undefined>
+ *
+ * 实现方式：调用系统 `osascript` 执行 AppleScript，读取 System Events
+ * 中 frontmost 进程的 name / unix id / bundle identifier / front window size。
+ * 失败时返回 undefined，绝不抛出 —— 前台应用信息是增强字段，不应阻塞主流程。
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+let frontAppAvailableCache = null;
+// 这里曾留着 `isOcrAvailable()`（恒 false）与 `performOcr()`（恒 []）两个空壳，
+// 注释写着"保留仅为接口兼容"。实测**全仓库零调用方** —— 兼容的是不存在的调用者。
+// 按 SPEC §8，文字识别由 VLM 直接完成，本地 OCR 是被明确否决的方向；
+// 留着恒定返回值的函数只会让人误以为"接上就能用"。一并删除，连同
+// `protocol.ts` 里同样从未被填充过的 `ocrBlocks?` 字段。
+/**
+ * 检查前台应用检测是否可用（macOS + 辅助功能权限）
+ */
+async function isFrontAppAvailable() {
+    if (frontAppAvailableCache !== null)
+        return frontAppAvailableCache;
+    if (process.platform !== 'darwin') {
+        frontAppAvailableCache = false;
+        return false;
+    }
+    try {
+        await execFileAsync('osascript', [
+            '-e',
+            'tell application "System Events"',
+            '-e',
+            'return name of first application process whose frontmost is true',
+            '-e',
+            'end tell',
+        ], {
+            timeout: 2000,
+        });
+        frontAppAvailableCache = true;
+    }
+    catch {
+        frontAppAvailableCache = false;
+    }
+    return frontAppAvailableCache;
+}
+/**
+ * 获取当前前台应用（使用 osascript，纯系统命令，无 Swift 依赖）
+ */
+export async function getFrontmostApp() {
+    if (process.platform !== 'darwin')
+        return undefined;
+    try {
+        const available = await isFrontAppAvailable();
+        if (!available)
+            return undefined;
+        const { stdout } = await execFileAsync('osascript', [
+            '-e',
+            'tell application "System Events"',
+            '-e',
+            'set frontApp to first application process whose frontmost is true',
+            '-e',
+            'set appName to name of frontApp',
+            '-e',
+            'set appBundleId to bundle identifier of frontApp',
+            '-e',
+            'set appPid to unix id of frontApp',
+            '-e',
+            'return appName & "|" & appBundleId & "|" & appPid',
+            '-e',
+            'end tell',
+        ], {
+            timeout: 3000,
+        });
+        const trimmed = stdout.trim();
+        if (!trimmed)
+            return undefined;
+        const parts = trimmed.split('|');
+        if (parts.length >= 3) {
+            const pid = parseInt(parts[2], 10);
+            return {
+                name: parts[0],
+                id: parts[1] || parts[0],
+                pid: Number.isFinite(pid) ? pid : undefined,
+            };
+        }
+        if (parts.length >= 1 && parts[0]) {
+            return {
+                name: parts[0],
+                id: parts[0],
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 清理 OCR 临时资源（保留空实现，接口兼容）。
+ *
+ * 移除 tesseract.js 后没有任何临时文件或 worker 需要清理。
+ */
+export function cleanupOcrTemp() {
+    // no-op：本地 OCR 已移除，无资源需释放
+}

package/src/tools/computeruse/visionOcr.ts

@@ -0,0 +1,128 @@
+/**
+ * 前台应用检测模块
+ *
+ * 本文件的核心职责是获取 macOS 前台应用信息（应用名、PID、Bundle ID、窗口尺寸），
+ * 供 computer-use 模块在每个观察周期填充 ComputerState.activeApp 字段。
+ *
+ * 历史背景：文件最初规划为本地 OCR（基于 tesseract.js），后按 SPEC §8 调整为
+ * 「文字识别由 VLM 视觉模型直接完成，不做本地 OCR」。tesseract.js 依赖已移除，
+ * 原 OCR 相关导出（recognizeText、recognizeScreenshot）已删除，文件名保留为
+ * visionOcr.ts 仅为向后兼容引用路径。
+ *
+ * 当前仅导出：
+ *   - getFrontmostApp(): Promise<ComputerUseApp | undefined>
+ *
+ * 实现方式：调用系统 `osascript` 执行 AppleScript，读取 System Events
+ * 中 frontmost 进程的 name / unix id / bundle identifier / front window size。
+ * 失败时返回 undefined，绝不抛出 —— 前台应用信息是增强字段，不应阻塞主流程。
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { ComputerUseApp } from './protocol.js';
+
+const execFileAsync = promisify(execFile);
+
+let frontAppAvailableCache: boolean | null = null;
+
+// 这里曾留着 `isOcrAvailable()`（恒 false）与 `performOcr()`（恒 []）两个空壳，
+// 注释写着"保留仅为接口兼容"。实测**全仓库零调用方** —— 兼容的是不存在的调用者。
+// 按 SPEC §8，文字识别由 VLM 直接完成，本地 OCR 是被明确否决的方向；
+// 留着恒定返回值的函数只会让人误以为"接上就能用"。一并删除，连同
+// `protocol.ts` 里同样从未被填充过的 `ocrBlocks?` 字段。
+
+/**
+ * 检查前台应用检测是否可用（macOS + 辅助功能权限）
+ */
+async function isFrontAppAvailable(): Promise<boolean> {
+  if (frontAppAvailableCache !== null) return frontAppAvailableCache;
+  if (process.platform !== 'darwin') {
+    frontAppAvailableCache = false;
+    return false;
+  }
+  try {
+    await execFileAsync(
+      'osascript',
+      [
+        '-e',
+        'tell application "System Events"',
+        '-e',
+        'return name of first application process whose frontmost is true',
+        '-e',
+        'end tell',
+      ],
+      {
+        timeout: 2000,
+      },
+    );
+    frontAppAvailableCache = true;
+  } catch {
+    frontAppAvailableCache = false;
+  }
+  return frontAppAvailableCache;
+}
+
+/**
+ * 获取当前前台应用（使用 osascript，纯系统命令，无 Swift 依赖）
+ */
+export async function getFrontmostApp(): Promise<ComputerUseApp | undefined> {
+  if (process.platform !== 'darwin') return undefined;
+
+  try {
+    const available = await isFrontAppAvailable();
+    if (!available) return undefined;
+
+    const { stdout } = await execFileAsync(
+      'osascript',
+      [
+        '-e',
+        'tell application "System Events"',
+        '-e',
+        'set frontApp to first application process whose frontmost is true',
+        '-e',
+        'set appName to name of frontApp',
+        '-e',
+        'set appBundleId to bundle identifier of frontApp',
+        '-e',
+        'set appPid to unix id of frontApp',
+        '-e',
+        'return appName & "|" & appBundleId & "|" & appPid',
+        '-e',
+        'end tell',
+      ],
+      {
+        timeout: 3000,
+      },
+    );
+
+    const trimmed = stdout.trim();
+    if (!trimmed) return undefined;
+
+    const parts = trimmed.split('|');
+    if (parts.length >= 3) {
+      const pid = parseInt(parts[2], 10);
+      return {
+        name: parts[0],
+        id: parts[1] || parts[0],
+        pid: Number.isFinite(pid) ? pid : undefined,
+      };
+    }
+    if (parts.length >= 1 && parts[0]) {
+      return {
+        name: parts[0],
+        id: parts[0],
+      };
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 清理 OCR 临时资源（保留空实现，接口兼容）。
+ *
+ * 移除 tesseract.js 后没有任何临时文件或 worker 需要清理。
+ */
+export function cleanupOcrTemp(): void {
+  // no-op：本地 OCR 已移除，无资源需释放
+}

package/src/tools/computeruse/waitFor.js

@@ -0,0 +1,237 @@
+/**
+ * ============================================================
+ *  waitFor.ts —— 语义等待（wait_for_element / text / window）
+ * ------------------------------------------------------------
+ *  ★ **零协议改动、零 vendor 重编。** 这三个动作本质是「轮询观测直到条件
+ *    成立」，而观测与 AX 树原生侧早已提供 —— 编排是 TS 的事，符合
+ *    「Rust 出像素，TS 做判断」总纲。
+ *
+ *  它们解决的是一个真实的成本问题：在此之前模型只能
+ *  `observe → 看 → observe` 地轮询，而每次 observe 都要组装图（约 1100 token）。
+ *  这里改用**元数据观测**（`includeScreenshot:false`，`list_apps` 已经在走这条
+ *  路径），一轮几乎不花 token，命中才返回。
+ *
+ *  三条刻意的边界，缺任一条都会变成新的故障源：
+ *
+ *   ① **超时不抛异常，而且要说清现场。** 只回一句「等了 5 秒没等到」，模型
+ *      只能盲试；带上「现在前台是谁、有哪些窗口、AX 里有哪些角色」，它才有
+ *      下一步可走。
+ *   ② **AX 不可用时立刻返回**，不空转到超时。微信这类自绘应用的树整棵是空的，
+ *      `wait_for_element` 在那里等多久都不会成立 —— 等 5 秒再报一个含糊的超时
+ *      是纯粹的浪费，且会把「这个能力用不了」误导成「这次没等到」。
+ *   ③ **条件已成立就首轮返回**，不为了「像在等」而先睡一轮。
+ * ============================================================
+ */
+import { containsFold, describeNode, findByRole, flattenAx, matchesText, } from './axSearch.js';
+/** 本模块接管的动作。 */
+export const WAIT_ACTIONS = [
+    'wait',
+    'wait_for_element',
+    'wait_for_text',
+    'wait_for_window',
+];
+export function isWaitAction(action) {
+    return WAIT_ACTIONS.includes(action);
+}
+export function isSimpleWaitAction(action) {
+    return action === 'wait';
+}
+/** 轮询间隔。200ms 是「人眼觉得即时」与「别把守护进程压满」之间的常用折中。 */
+export const WAIT_POLL_INTERVAL_MS = 200;
+/** 默认等待上限。模型可用 `timeoutMs` 覆盖（schema 限 100–120000）。 */
+export const WAIT_DEFAULT_TIMEOUT_MS = 5_000;
+function axNodes(state) {
+    return flattenAx(state.accessibility?.root);
+}
+function axUsable(state) {
+    return state.accessibility !== undefined && state.accessibility.truncated !== true;
+}
+const AX_BLIND_HINT = '这个应用没有可用的无障碍树（自绘/Electron 应用的常态），按控件等待在这里永远不会成立。'
+    + '改用 `settle` 判断界面稳没稳，再 `observe` 看图确认。';
+function evaluate(input, state) {
+    switch (input.action) {
+        case 'wait':
+            // 简单 wait 不需要评估条件，直接返回 hit（它只 sleep）
+            return { kind: 'hit', description: '等待完成' };
+        case 'wait_for_window': {
+            // 窗口列表不依赖 AX 树的完整性，自绘应用上照样可用 —— 这是三个 wait
+            // 里唯一对微信这类应用有效的那个。
+            const needle = input.text ?? '';
+            const hit = state.windows.find((window) => containsFold(window.title, needle));
+            if (hit) {
+                return { kind: 'hit', description: `窗口「${hit.title ?? '(无标题)'}」（${hit.appId}）` };
+            }
+            return { kind: 'miss' };
+        }
+        case 'wait_for_element': {
+            if (!axUsable(state))
+                return { kind: 'unavailable', reason: AX_BLIND_HINT };
+            const matches = findByRole(axNodes(state), input.role ?? '', input.text);
+            const hit = matches[0];
+            if (!hit)
+                return { kind: 'miss' };
+            return {
+                kind: 'hit',
+                description: describeNode(hit)
+                    + (matches.length > 1 ? `（另有 ${matches.length - 1} 个同样匹配的控件）` : ''),
+                ...(hit.elementId ? { elementId: hit.elementId } : {}),
+            };
+        }
+        case 'wait_for_text': {
+            if (!axUsable(state))
+                return { kind: 'unavailable', reason: AX_BLIND_HINT };
+            const hit = axNodes(state).find((node) => matchesText(node, input.text ?? ''));
+            if (!hit)
+                return { kind: 'miss' };
+            return {
+                kind: 'hit',
+                description: describeNode(hit),
+                ...(hit.elementId ? { elementId: hit.elementId } : {}),
+            };
+        }
+        default:
+            return { kind: 'miss' };
+    }
+}
+/**
+ * 超时时给模型看的现场。
+ *
+ * 这段是本模块最容易被写敷衍的地方，也是最要紧的：模型拿不到现场就只能重试
+ * 同一件事，而重试同一件事正是熔断要拦的行为。
+ */
+function describeScene(input, state) {
+    if (!state)
+        return ['  等待期间一次观测都没成功 —— 先检查权限与守护进程。'];
+    const lines = [
+        `  当前前台：${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+        `  窗口：${state.windows.length > 0
+            ? state.windows.map((w) => `「${w.title ?? '(无标题)'}」`).slice(0, 6).join('、')
+            : '（一个都没有）'}`,
+    ];
+    if (input.action !== 'wait_for_window') {
+        const nodes = axNodes(state);
+        const roles = [...new Set(nodes.map((node) => node.role).filter(Boolean))].slice(0, 12);
+        lines.push(`  无障碍树：${axUsable(state) ? `${nodes.length} 个节点` : '不可用'}`);
+        if (roles.length > 0)
+            lines.push(`  树里出现过的角色：${roles.join('、')}`);
+    }
+    return lines;
+}
+function requirementOf(input) {
+    switch (input.action) {
+        case 'wait':
+            return '等待时间结束';
+        case 'wait_for_element':
+            return `控件 ${input.role}${input.text ? `（名字含「${input.text}」）` : ''}`;
+        case 'wait_for_text':
+            return `文本「${input.text}」`;
+        case 'wait_for_window':
+            return `标题含「${input.text}」的窗口`;
+        default:
+            return '未知条件';
+    }
+}
+/** 入参校验。返回非 null 表示参数本身就不成立，不必去等。 */
+export function validateWaitInput(input) {
+    // 简单 wait 不需要任何参数，只需要可选的等待时间
+    if (input.action === 'wait') {
+        if (input.waitMs !== undefined && (input.waitMs < 10 || input.waitMs > 30000)) {
+            return 'wait 的 waitMs 参数必须在 10-30000 毫秒之间（默认 1000ms）。';
+        }
+        return null;
+    }
+    if (input.action === 'wait_for_element' && !input.role?.trim()) {
+        return 'wait_for_element 需要 role（AX 角色，如 AXButton）；只给文本请用 wait_for_text。';
+    }
+    if (input.action !== 'wait_for_element' && !input.text?.trim()) {
+        return `${input.action} 需要 text（要等的文本/窗口标题片段）。`;
+    }
+    return null;
+}
+/**
+ * 轮询直到条件成立或超时。
+ *
+ * `observeOnce` 由调用方注入（生产里是一次元数据观测），便于单测用合成状态
+ * 驱动而不碰真实守护进程。
+ */
+export async function waitForCondition(input, deps) {
+    const invalid = validateWaitInput(input);
+    if (invalid)
+        return { ok: false, content: invalid, waitedMs: 0, polls: 0 };
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    // 简单 wait：纯 sleep，不截图不查 AX 树
+    if (input.action === 'wait') {
+        const waitMs = input.waitMs ?? 2000;
+        const startedAt = now();
+        if (deps.signal) {
+            // 支持中断：用 Promise.race 实现可取消的 sleep
+            await Promise.race([
+                sleep(waitMs),
+                new Promise((_, reject) => {
+                    deps.signal?.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+                }).catch(() => { }),
+            ]);
+        }
+        else {
+            await sleep(waitMs);
+        }
+        const waitedMs = now() - startedAt;
+        if (deps.signal?.aborted) {
+            return { ok: false, content: '等待被中断。', waitedMs, polls: 0 };
+        }
+        return {
+            ok: true,
+            content: `已等待 ${waitMs}ms`,
+            waitedMs,
+            polls: 0,
+        };
+    }
+    const timeoutMs = input.timeoutMs ?? WAIT_DEFAULT_TIMEOUT_MS;
+    const startedAt = now();
+    let polls = 0;
+    let last = null;
+    // do-while：**先判一次再睡**。条件已经成立时不该白等一个间隔。
+    do {
+        if (deps.signal?.aborted) {
+            return { ok: false, content: '等待被中断。', waitedMs: now() - startedAt, polls };
+        }
+        polls += 1;
+        last = await deps.observeOnce();
+        if (last) {
+            const verdict = evaluate(input, last);
+            if (verdict.kind === 'hit') {
+                return {
+                    ok: true,
+                    content: `已等到${requirementOf(input)}：${verdict.description}（用时 ${now() - startedAt}ms）`,
+                    ...(verdict.elementId ? { elementId: verdict.elementId } : {}),
+                    waitedMs: now() - startedAt,
+                    polls,
+                };
+            }
+            if (verdict.kind === 'unavailable') {
+                // 立刻返回，不空转到超时 —— 等下去也不会变成立。
+                return {
+                    ok: false,
+                    content: `无法等待${requirementOf(input)}：${verdict.reason}`,
+                    waitedMs: now() - startedAt,
+                    polls,
+                };
+            }
+        }
+        if (now() - startedAt >= timeoutMs)
+            break;
+        await sleep(WAIT_POLL_INTERVAL_MS);
+    } while (now() - startedAt < timeoutMs);
+    const waitedMs = now() - startedAt;
+    return {
+        ok: false,
+        content: [
+            `等了 ${waitedMs}ms（${polls} 次观测）仍未出现${requirementOf(input)}。当前实际看到的是：`,
+            ...describeScene(input, last),
+            '别用同样的参数再等一次 —— 要么条件写错了，要么这一步的前置操作没生效。',
+        ].join('\n'),
+        waitedMs,
+        polls,
+    };
+}