minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/vision/focus.js

@@ -0,0 +1,291 @@
+/**
+ * ============================================================
+ *  vision/focus.ts —— 焦点通道（纯函数）
+ * ------------------------------------------------------------
+ *  焦点是与像素并列的**辅助**通道（不是主判据，原因见下）：
+ *
+ *  ① L1 绕开了「应用不暴露 UI 结构」这个前提。
+ *     前台窗口/进程不归应用管、归 OS 管。微信可以拒绝暴露控件树，它拒绝不了
+ *     「我这个窗口是不是前台窗口」。**跨进程打断因此永远可检出**。
+ *
+ *  ② 它比截图便宜 20 倍。
+ *     一次焦点采样约 50 token，一张全屏截图约 1100 token。
+ *
+ *  ★ 一条已被推翻的旧论断，留在这里免得有人再推一遍：
+ *
+ *    曾经的说法是「输入法必须知道 caret 矩形才能画候选词框，所以只要支持中文
+ *    输入，自绘应用也堵不上 caret 泄漏」。**这是错的。** IME 通道（TSF/IMM、
+ *    TSM）与无障碍通道（GetGUIThreadInfo、AX）是两条独立路径，前者不向第三方
+ *    进程暴露。已查证：
+ *      - Windows：`GetGUIThreadInfo.hwndCaret` 对 Chromium/Electron 恒为 NULL
+ *      - macOS：`AXSelectedTextRange` 在 MAS 版 Electron 被整体 patch 掉
+ *    而 Electron / 自绘控件正是目标场景。本仓库实测也确认：Claude 桌面端
+ *    只暴露窗口与三个窗口按钮，内容对 AX 完全不可见。
+ *
+ *    **因此 L2 不可假定可用**，settle 的主判据必须是像素（见 settle.ts），
+ *    焦点只做增强与跨进程打断检测。
+ * ============================================================
+ */
+/** 层级语义。原生侧拿不到高层就降级，但必须**如实报告拿到了哪层**。 */
+export const FOCUS_LEVELS = {
+    1: '前台窗口/进程（总是可用）',
+    2: '焦点控件 + caret 矩形（自绘/Electron 应用上常常拿不到）',
+    3: '输入法合成状态（看应用）',
+};
+/**
+ * 焦点变化的三种语义。这是**引擎级通用对策**，不是任何 app 的特判 ——
+ * `other-process` 只用 L1 就能算，所以对自绘应用同样成立。
+ *
+ *   same-window   → app 自己的交互反馈（弹联想、展开面板、切 tab）；需 L2
+ *   other-process → 外部打断（通知、别的 app 抢前台）；L1 即可
+ *   expected      → 就是我刚点的目标，正常
+ *   none          → 没变
+ */
+export const FOCUS_CHANGE = {
+    NONE: 'none',
+    EXPECTED: 'expected',
+    SAME_WINDOW: 'same-window',
+    OTHER_PROCESS: 'other-process',
+};
+/** 比较两个焦点快照，判定变化语义。 */
+export function classifyFocusChange(before, after, expectation = {}) {
+    if (!before || !after)
+        return FOCUS_CHANGE.NONE;
+    // 进程换了就是换了 —— 这一项**必须**独立参与判定。
+    //
+    // 曾经的写法只看窗口键/caret/role，于是当两个应用的窗口键恰好相同（或两边
+    // 都拿不到窗口 id、标题也一样）时，一次真实的跨进程抢前台会被判成 `none`。
+    // 而 L1 的全部价值就在于「进程身份是最可靠的那一层」，让它取决于更弱的
+    // 窗口信息是把依赖关系倒过来了。
+    const processChanged = (before.pid ?? '') !== (after.pid ?? '')
+        || before.app !== after.app;
+    const windowChanged = keyOf(before) !== keyOf(after);
+    const caretMoved = !sameRect(before.caret, after.caret);
+    const roleChanged = (before.role ?? '') !== (after.role ?? '');
+    if (!processChanged && !windowChanged && !caretMoved && !roleChanged) {
+        return FOCUS_CHANGE.NONE;
+    }
+    // 预期之内：这次动作本来就是要把焦点挪过去
+    if (expectation.expectWindowId &&
+        after.windowId === expectation.expectWindowId &&
+        (!expectation.expectRole || after.role === expectation.expectRole)) {
+        return FOCUS_CHANGE.EXPECTED;
+    }
+    if (expectation.expectAppId && matchesApp(after, expectation.expectAppId)) {
+        return FOCUS_CHANGE.EXPECTED;
+    }
+    if (processChanged)
+        return FOCUS_CHANGE.OTHER_PROCESS;
+    return FOCUS_CHANGE.SAME_WINDOW;
+}
+/**
+ * 变化语义 → 建议动作。写死在引擎里当默认，`apps/<app>.md` 可以描述例外
+ * （但那是**事实**描述，覆盖策略由模型读了 md 之后自己决定，不是这里加分支）。
+ */
+export function recommendedAction(change) {
+    switch (change) {
+        case FOCUS_CHANGE.SAME_WINDOW:
+            return { abortTyping: true, advice: '应用弹出了新界面元素，先观察再继续，不要盲目输入' };
+        case FOCUS_CHANGE.OTHER_PROCESS:
+            return { abortTyping: true, advice: '被其它进程抢走焦点，需先抢回前台再重试' };
+        case FOCUS_CHANGE.EXPECTED:
+            return { abortTyping: false, advice: '焦点如期落位' };
+        default:
+            return { abortTyping: false, advice: '焦点未变' };
+    }
+}
+/**
+ * 从一次观测里派生焦点快照。
+ *
+ * **零协议改动**：协议里没有专门的焦点快照字段，但需要的两件事都已经在观测里了 ——
+ * `activeApp`/`windows` 给 L1，`AccessibilityNode.focused`（原生侧从 `AXFocused` 采集）
+ * 给 L2。所以这里是纯派生，不需要多跑一次原生调用。
+ *
+ * `level` 必须如实：
+ *   - 找到带 bounds 的焦点控件 → **L2**（能说出焦点落在哪个控件、在哪）
+ *   - 只有前台应用/窗口 → **L1**
+ * 刻意不产出 L3：输入法合成状态在本项目里根本没有采集通道，报 L3 就是撒谎
+ * （本文件头注记录了「IME 能拿到 caret」这个已被推翻的论断，别再往回走）。
+ *
+ * 拿不到前台应用时返回 null，不造一个空壳 —— 「不知道」和「没有焦点」是两件事。
+ */
+/**
+ * 这次观测的无障碍树**给不给得出控件级信息**（而不是「有没有一棵树」）。
+ *
+ * ⚠️ 这是「要不要退回像素判据」的唯一判据，此前在两处各自手写成
+ * `accessibility !== undefined && !truncated` —— 那测的是「树存在」，不是「树有用」。
+ * 微信的 AX 树有 5 个节点（纯窗口壳）、未截断，于是两处都判「可用」，
+ * 像素探测因此从未发生，整条效果反馈链路（生效判定、滚动边界、no-effect 回执、
+ * 像素级人工接管）全部失效。
+ *
+ * 正确的谓词就是 `deriveFocusSnapshot` 已经算好的 `level`：L2 才代表「说得出焦点
+ * 落在哪个控件、在哪」。判据只写这一遍，两个调用方不会再各自漂移。
+ */
+export function axGivesControlDetail(state) {
+    if (!state)
+        return false;
+    if (state.accessibility?.truncated === true)
+        return false;
+    return axFocusIsConcreteControl(state);
+}
+/**
+ * 焦点落在一个**具体控件**上（有 bounds、且不是纯容器）。
+ *
+ * 与 `axGivesControlDetail` 只差一个 `truncated` 条件，而这个差是有意的 ——
+ * 两个调用方问的不是同一个问题：
+ *   · 「要不要退回像素探测」→ 树被截断就不能信 AX，`truncated` 必须一票否决
+ *   · 「ROI 取哪块」        → 只要这个节点本身是真控件，它的矩形就是有效的，
+ *                              别处截没截断与它无关
+ * 把两者硬绑成一个判据，会让「微信的树被截断、但焦点确实在输入框上」这种
+ * 常见形态丢掉本来拿得到的 ROI。
+ */
+export function axFocusIsConcreteControl(state) {
+    if (!state)
+        return false;
+    const snapshot = deriveFocusSnapshot(state);
+    if ((snapshot?.level ?? 0) < 2)
+        return false;
+    // ⚠️ **L2 还不够 —— 焦点节点必须是个「说得出事」的控件。**
+    //
+    // 实测：微信读书（iOS 套壳）报的是 `AXGroup · caret(51,98)` —— 一个位于窗口左上角的
+    // 无用包装容器。它满足「有 bounds 的焦点节点」= L2，于是这里判「AX 可用」→ 跳过像素
+    // 探测 → 按键之后**变化率恒为「未测」**。
+    //
+    // 后果不是少个数字：agent 拿不到「这一下有没有生效」的任何证据，只能干等、反复
+    // observe、最后去乱点碰运气。而实测证明按键**一直是好使的**（连按 3 次 right，
+    // 书从 15/106 翻到 21/106）—— 纯粹是反馈缺席造成的瞎折腾。
+    //
+    // 容器角色不构成「控件级信息」：它们回答不了「焦点在哪个可交互控件上」这个问题。
+    return !CONTAINER_ROLES.has(snapshot.role ?? '');
+}
+/**
+ * 纯容器角色 —— 有它们当焦点等于没有焦点信息。
+ *
+ * 自绘 / 套壳应用常把整个画布报成一个 AXGroup，看起来像 L2 实则零信息量。
+ * 这里只列**明确的容器**，不列未知角色：拿不准的角色宁可当作有信息（少做一次
+ * 像素探测的代价，远小于把一个真有 AX 的应用误判成瞎子）。
+ */
+const CONTAINER_ROLES = new Set([
+    'AXGroup',
+    'AXWindow',
+    'AXScrollArea',
+    'AXSplitGroup',
+    'AXUnknown',
+    'AXLayoutArea',
+]);
+export function deriveFocusSnapshot(state) {
+    const app = state.activeApp?.name ?? state.activeApp?.id;
+    if (!app)
+        return null;
+    const windows = state.windows ?? [];
+    const window = windows.find((candidate) => candidate.focused) ?? windows[0];
+    const node = findFocusedNode(state.accessibility?.root);
+    const snapshot = {
+        // 有控件级信息才敢报 L2。只有窗口壳（Electron/自绘应用的常态）就是 L1。
+        level: node?.bounds ? 2 : 1,
+        app,
+        ...(state.activeApp?.id ? { appId: state.activeApp.id } : {}),
+        ...(state.activeApp?.pid !== undefined ? { pid: String(state.activeApp.pid) } : {}),
+        ...(window?.id ? { windowId: window.id } : {}),
+        ...(window?.title ? { windowTitle: window.title } : {}),
+        ...(window?.bounds ? { windowRect: window.bounds } : {}),
+        ...(node?.role ? { role: node.role } : {}),
+        // AX 给的是控件矩形，不是插入点。当 caret 的近似值用，够 classifyFocusChange
+        // 判「焦点挪没挪」，但别当成真 caret —— 真 caret 这条通道拿不到（见头注）。
+        ...(node?.bounds ? { caret: node.bounds } : {}),
+    };
+    return snapshot;
+}
+function findFocusedNode(node) {
+    if (!node)
+        return undefined;
+    if (node.focused === true)
+        return node;
+    for (const child of node.children ?? []) {
+        const hit = findFocusedNode(child);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * 快照是否就是期待的那个应用。
+ *
+ * 双向包含匹配，因为调用方手里的标识形态不定：`activate_app` 可能收到
+ * bundleId（`com.tencent.xinWeChat`）、进程名（`WeChat`）或显示名（`微信`），
+ * 而快照拿到的是另一种。宁可宽一点 —— 判错的方向是「把一次真实抢占当成
+ * 预期之内」，但那要求抢占者的名字恰好包含目标名，概率极低；反过来判严了
+ * 就是每次切应用都卡住，那是必然发生的。
+ */
+function matchesApp(snapshot, expected) {
+    const needle = expected.trim().toLowerCase();
+    if (!needle)
+        return false;
+    return [snapshot.appId, snapshot.app]
+        .filter((value) => typeof value === 'string' && value.length > 0)
+        .some((value) => {
+        const hay = value.toLowerCase();
+        return hay === needle || hay.includes(needle) || needle.includes(hay);
+    });
+}
+/** 窗口身份键。windowId 缺失时退回 pid+标题 —— 有的平台给不出稳定 id。 */
+function keyOf(snapshot) {
+    return snapshot.windowId ?? `${snapshot.pid ?? ''}::${snapshot.windowTitle ?? ''}`;
+}
+function sameRect(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+/**
+ * 人话渲染，供文本通道输出。刻意做得**短** —— 这条通道的全部价值就是便宜，
+ * 写成一大段就失去了相对截图 20 倍的优势。
+ */
+export function describeFocus(snapshot) {
+    if (!snapshot)
+        return '焦点: 不可用';
+    const parts = [`前台: ${snapshot.app}`];
+    if (snapshot.windowTitle)
+        parts.push(`窗口「${snapshot.windowTitle}」`);
+    if (snapshot.role)
+        parts.push(`控件 ${snapshot.role}`);
+    if (snapshot.caret)
+        parts.push(`caret(${snapshot.caret.x},${snapshot.caret.y})`);
+    if (snapshot.composing)
+        parts.push('输入法合成中');
+    parts.push(`[L${snapshot.level}]`);
+    return parts.join(' · ');
+}
+export function describeFocusChange(before, after) {
+    if (!before || !after)
+        return '';
+    const changes = [];
+    if (before.app !== after.app) {
+        changes.push(`前台: ${before.app} → ${after.app}`);
+    }
+    const beforeTitle = before.windowTitle ?? '(无标题)';
+    const afterTitle = after.windowTitle ?? '(无标题)';
+    if (beforeTitle !== afterTitle) {
+        changes.push(`窗口标题: ${beforeTitle} → ${afterTitle}`);
+    }
+    const beforeRole = before.role ?? '(无焦点控件)';
+    const afterRole = after.role ?? '(无焦点控件)';
+    if (beforeRole !== afterRole) {
+        changes.push(`焦点控件: ${beforeRole} → ${afterRole}`);
+    }
+    if (changes.length === 0)
+        return '焦点状态未变化';
+    return `状态变化：${changes.join('；')}`;
+}
+/**
+ * 焦点是否稳定。
+ *
+ * ⚠️ 它**不是** settle 的判据之一 —— 那是 R1 之前的设计，已被推翻（见本文件
+ * 头注与 settle.ts）。保留它是给需要单独问「焦点动没动」的调用方用的。
+ */
+export function focusStable(before, after, expectation) {
+    const change = classifyFocusChange(before, after, expectation);
+    return change === FOCUS_CHANGE.NONE || change === FOCUS_CHANGE.EXPECTED;
+}

package/src/tools/computeruse/vision/focus.ts

@@ -0,0 +1,382 @@
+/**
+ * ============================================================
+ *  vision/focus.ts —— 焦点通道（纯函数）
+ * ------------------------------------------------------------
+ *  焦点是与像素并列的**辅助**通道（不是主判据，原因见下）：
+ *
+ *  ① L1 绕开了「应用不暴露 UI 结构」这个前提。
+ *     前台窗口/进程不归应用管、归 OS 管。微信可以拒绝暴露控件树，它拒绝不了
+ *     「我这个窗口是不是前台窗口」。**跨进程打断因此永远可检出**。
+ *
+ *  ② 它比截图便宜 20 倍。
+ *     一次焦点采样约 50 token，一张全屏截图约 1100 token。
+ *
+ *  ★ 一条已被推翻的旧论断，留在这里免得有人再推一遍：
+ *
+ *    曾经的说法是「输入法必须知道 caret 矩形才能画候选词框，所以只要支持中文
+ *    输入，自绘应用也堵不上 caret 泄漏」。**这是错的。** IME 通道（TSF/IMM、
+ *    TSM）与无障碍通道（GetGUIThreadInfo、AX）是两条独立路径，前者不向第三方
+ *    进程暴露。已查证：
+ *      - Windows：`GetGUIThreadInfo.hwndCaret` 对 Chromium/Electron 恒为 NULL
+ *      - macOS：`AXSelectedTextRange` 在 MAS 版 Electron 被整体 patch 掉
+ *    而 Electron / 自绘控件正是目标场景。本仓库实测也确认：Claude 桌面端
+ *    只暴露窗口与三个窗口按钮，内容对 AX 完全不可见。
+ *
+ *    **因此 L2 不可假定可用**，settle 的主判据必须是像素（见 settle.ts），
+ *    焦点只做增强与跨进程打断检测。
+ * ============================================================
+ */
+
+import type { Rect } from './raster.js';
+
+/**
+ * 归一化后的焦点快照。各平台原生实现须产出这个形状。
+ *
+ * `level` 是**实际拿到的层级**，必须如实报告，不许假装。
+ */
+export interface FocusSnapshot {
+  /** 1 = 前台窗口/进程；2 = 焦点控件 + caret；3 = 输入法合成状态 */
+  level: 1 | 2 | 3;
+  /** 前台应用名（L1） */
+  app: string;
+  /** 前台应用的稳定标识（macOS bundleId / Windows 可执行名）。显示名会随系统语言变。 */
+  appId?: string;
+  pid?: string;
+  windowId?: string;
+  windowTitle?: string;
+  /** 逻辑点 */
+  windowRect?: Rect;
+  /** 焦点控件角色，如 AXTextField（L2） */
+  role?: string;
+  /** 插入点矩形，逻辑点（L2） */
+  caret?: Rect;
+  /** 输入法正在合成（L3） */
+  composing?: boolean;
+}
+
+/** 层级语义。原生侧拿不到高层就降级，但必须**如实报告拿到了哪层**。 */
+export const FOCUS_LEVELS: Record<number, string> = {
+  1: '前台窗口/进程（总是可用）',
+  2: '焦点控件 + caret 矩形（自绘/Electron 应用上常常拿不到）',
+  3: '输入法合成状态（看应用）',
+};
+
+/**
+ * 焦点变化的三种语义。这是**引擎级通用对策**，不是任何 app 的特判 ——
+ * `other-process` 只用 L1 就能算，所以对自绘应用同样成立。
+ *
+ *   same-window   → app 自己的交互反馈（弹联想、展开面板、切 tab）；需 L2
+ *   other-process → 外部打断（通知、别的 app 抢前台）；L1 即可
+ *   expected      → 就是我刚点的目标，正常
+ *   none          → 没变
+ */
+export const FOCUS_CHANGE = {
+  NONE: 'none',
+  EXPECTED: 'expected',
+  SAME_WINDOW: 'same-window',
+  OTHER_PROCESS: 'other-process',
+} as const;
+
+export type FocusChange = (typeof FOCUS_CHANGE)[keyof typeof FOCUS_CHANGE];
+
+export interface FocusExpectation {
+  /** 动作发起方对「焦点应该落到哪」的预期。 */
+  expectWindowId?: string;
+  expectRole?: string;
+  /**
+   * 预期落到的应用（bundleId、进程名或显示名皆可，做包含匹配）。
+   *
+   * 没有这一项时，agent **自己**执行 `activate_app` 切过去的应用会在下一次
+   * 观测里被判成「别的进程抢了前台」，进而触发人工介入 —— 一次正常的、
+   * 由 agent 主动发起的切换变成了需要人来处理的事故。这不是理论问题：
+   * 只要工作流里有一步切应用，接下来就必然卡住。
+   */
+  expectAppId?: string;
+}
+
+/** 比较两个焦点快照，判定变化语义。 */
+export function classifyFocusChange(
+  before: FocusSnapshot | null | undefined,
+  after: FocusSnapshot | null | undefined,
+  expectation: FocusExpectation = {},
+): FocusChange {
+  if (!before || !after) return FOCUS_CHANGE.NONE;
+
+  // 进程换了就是换了 —— 这一项**必须**独立参与判定。
+  //
+  // 曾经的写法只看窗口键/caret/role，于是当两个应用的窗口键恰好相同（或两边
+  // 都拿不到窗口 id、标题也一样）时，一次真实的跨进程抢前台会被判成 `none`。
+  // 而 L1 的全部价值就在于「进程身份是最可靠的那一层」，让它取决于更弱的
+  // 窗口信息是把依赖关系倒过来了。
+  const processChanged = (before.pid ?? '') !== (after.pid ?? '')
+    || before.app !== after.app;
+  const windowChanged = keyOf(before) !== keyOf(after);
+  const caretMoved = !sameRect(before.caret, after.caret);
+  const roleChanged = (before.role ?? '') !== (after.role ?? '');
+
+  if (!processChanged && !windowChanged && !caretMoved && !roleChanged) {
+    return FOCUS_CHANGE.NONE;
+  }
+
+  // 预期之内：这次动作本来就是要把焦点挪过去
+  if (
+    expectation.expectWindowId &&
+    after.windowId === expectation.expectWindowId &&
+    (!expectation.expectRole || after.role === expectation.expectRole)
+  ) {
+    return FOCUS_CHANGE.EXPECTED;
+  }
+  if (expectation.expectAppId && matchesApp(after, expectation.expectAppId)) {
+    return FOCUS_CHANGE.EXPECTED;
+  }
+
+  if (processChanged) return FOCUS_CHANGE.OTHER_PROCESS;
+  return FOCUS_CHANGE.SAME_WINDOW;
+}
+
+export interface FocusAdvice {
+  abortTyping: boolean;
+  advice: string;
+}
+
+/**
+ * 变化语义 → 建议动作。写死在引擎里当默认，`apps/<app>.md` 可以描述例外
+ * （但那是**事实**描述，覆盖策略由模型读了 md 之后自己决定，不是这里加分支）。
+ */
+export function recommendedAction(change: FocusChange): FocusAdvice {
+  switch (change) {
+    case FOCUS_CHANGE.SAME_WINDOW:
+      return { abortTyping: true, advice: '应用弹出了新界面元素，先观察再继续，不要盲目输入' };
+    case FOCUS_CHANGE.OTHER_PROCESS:
+      return { abortTyping: true, advice: '被其它进程抢走焦点，需先抢回前台再重试' };
+    case FOCUS_CHANGE.EXPECTED:
+      return { abortTyping: false, advice: '焦点如期落位' };
+    default:
+      return { abortTyping: false, advice: '焦点未变' };
+  }
+}
+
+/**
+ * 从一次观测里派生焦点快照。
+ *
+ * **零协议改动**：协议里没有专门的焦点快照字段，但需要的两件事都已经在观测里了 ——
+ * `activeApp`/`windows` 给 L1，`AccessibilityNode.focused`（原生侧从 `AXFocused` 采集）
+ * 给 L2。所以这里是纯派生，不需要多跑一次原生调用。
+ *
+ * `level` 必须如实：
+ *   - 找到带 bounds 的焦点控件 → **L2**（能说出焦点落在哪个控件、在哪）
+ *   - 只有前台应用/窗口 → **L1**
+ * 刻意不产出 L3：输入法合成状态在本项目里根本没有采集通道，报 L3 就是撒谎
+ * （本文件头注记录了「IME 能拿到 caret」这个已被推翻的论断，别再往回走）。
+ *
+ * 拿不到前台应用时返回 null，不造一个空壳 —— 「不知道」和「没有焦点」是两件事。
+ */
+/**
+ * 这次观测的无障碍树**给不给得出控件级信息**（而不是「有没有一棵树」）。
+ *
+ * ⚠️ 这是「要不要退回像素判据」的唯一判据，此前在两处各自手写成
+ * `accessibility !== undefined && !truncated` —— 那测的是「树存在」，不是「树有用」。
+ * 微信的 AX 树有 5 个节点（纯窗口壳）、未截断，于是两处都判「可用」，
+ * 像素探测因此从未发生，整条效果反馈链路（生效判定、滚动边界、no-effect 回执、
+ * 像素级人工接管）全部失效。
+ *
+ * 正确的谓词就是 `deriveFocusSnapshot` 已经算好的 `level`：L2 才代表「说得出焦点
+ * 落在哪个控件、在哪」。判据只写这一遍，两个调用方不会再各自漂移。
+ */
+export function axGivesControlDetail(
+  state:
+    | {
+        activeApp?: { id?: string; name?: string; pid?: number };
+        windows?: { id: string; title?: string; bounds?: Rect; focused?: boolean }[];
+        accessibility?: { root?: FocusableNode; truncated?: boolean };
+      }
+    | undefined,
+): boolean {
+  if (!state) return false;
+  if (state.accessibility?.truncated === true) return false;
+  return axFocusIsConcreteControl(state);
+}
+
+/**
+ * 焦点落在一个**具体控件**上（有 bounds、且不是纯容器）。
+ *
+ * 与 `axGivesControlDetail` 只差一个 `truncated` 条件，而这个差是有意的 ——
+ * 两个调用方问的不是同一个问题：
+ *   · 「要不要退回像素探测」→ 树被截断就不能信 AX，`truncated` 必须一票否决
+ *   · 「ROI 取哪块」        → 只要这个节点本身是真控件，它的矩形就是有效的，
+ *                              别处截没截断与它无关
+ * 把两者硬绑成一个判据，会让「微信的树被截断、但焦点确实在输入框上」这种
+ * 常见形态丢掉本来拿得到的 ROI。
+ */
+export function axFocusIsConcreteControl(
+  state:
+    | {
+        activeApp?: { id?: string; name?: string; pid?: number };
+        windows?: { id: string; title?: string; bounds?: Rect; focused?: boolean }[];
+        accessibility?: { root?: FocusableNode; truncated?: boolean };
+      }
+    | undefined,
+): boolean {
+  if (!state) return false;
+  const snapshot = deriveFocusSnapshot(state);
+  if ((snapshot?.level ?? 0) < 2) return false;
+  // ⚠️ **L2 还不够 —— 焦点节点必须是个「说得出事」的控件。**
+  //
+  // 实测：微信读书（iOS 套壳）报的是 `AXGroup · caret(51,98)` —— 一个位于窗口左上角的
+  // 无用包装容器。它满足「有 bounds 的焦点节点」= L2，于是这里判「AX 可用」→ 跳过像素
+  // 探测 → 按键之后**变化率恒为「未测」**。
+  //
+  // 后果不是少个数字：agent 拿不到「这一下有没有生效」的任何证据，只能干等、反复
+  // observe、最后去乱点碰运气。而实测证明按键**一直是好使的**（连按 3 次 right，
+  // 书从 15/106 翻到 21/106）—— 纯粹是反馈缺席造成的瞎折腾。
+  //
+  // 容器角色不构成「控件级信息」：它们回答不了「焦点在哪个可交互控件上」这个问题。
+  return !CONTAINER_ROLES.has(snapshot!.role ?? '');
+}
+
+/**
+ * 纯容器角色 —— 有它们当焦点等于没有焦点信息。
+ *
+ * 自绘 / 套壳应用常把整个画布报成一个 AXGroup，看起来像 L2 实则零信息量。
+ * 这里只列**明确的容器**，不列未知角色：拿不准的角色宁可当作有信息（少做一次
+ * 像素探测的代价，远小于把一个真有 AX 的应用误判成瞎子）。
+ */
+const CONTAINER_ROLES = new Set([
+  'AXGroup',
+  'AXWindow',
+  'AXScrollArea',
+  'AXSplitGroup',
+  'AXUnknown',
+  'AXLayoutArea',
+]);
+
+export function deriveFocusSnapshot(state: {
+  activeApp?: { id?: string; name?: string; pid?: number };
+  windows?: { id: string; title?: string; bounds?: Rect; focused?: boolean }[];
+  accessibility?: { root?: FocusableNode };
+}): FocusSnapshot | null {
+  const app = state.activeApp?.name ?? state.activeApp?.id;
+  if (!app) return null;
+
+  const windows = state.windows ?? [];
+  const window = windows.find((candidate) => candidate.focused) ?? windows[0];
+  const node = findFocusedNode(state.accessibility?.root);
+
+  const snapshot: FocusSnapshot = {
+    // 有控件级信息才敢报 L2。只有窗口壳（Electron/自绘应用的常态）就是 L1。
+    level: node?.bounds ? 2 : 1,
+    app,
+    ...(state.activeApp?.id ? { appId: state.activeApp.id } : {}),
+    ...(state.activeApp?.pid !== undefined ? { pid: String(state.activeApp.pid) } : {}),
+    ...(window?.id ? { windowId: window.id } : {}),
+    ...(window?.title ? { windowTitle: window.title } : {}),
+    ...(window?.bounds ? { windowRect: window.bounds } : {}),
+    ...(node?.role ? { role: node.role } : {}),
+    // AX 给的是控件矩形，不是插入点。当 caret 的近似值用，够 classifyFocusChange
+    // 判「焦点挪没挪」，但别当成真 caret —— 真 caret 这条通道拿不到（见头注）。
+    ...(node?.bounds ? { caret: node.bounds } : {}),
+  };
+  return snapshot;
+}
+
+/** 只关心 focused/role/bounds/children 四件事，不绑具体协议类型。 */
+export interface FocusableNode {
+  role?: string;
+  focused?: boolean;
+  bounds?: Rect;
+  children?: FocusableNode[];
+}
+
+function findFocusedNode(node: FocusableNode | undefined): FocusableNode | undefined {
+  if (!node) return undefined;
+  if (node.focused === true) return node;
+  for (const child of node.children ?? []) {
+    const hit = findFocusedNode(child);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/**
+ * 快照是否就是期待的那个应用。
+ *
+ * 双向包含匹配，因为调用方手里的标识形态不定：`activate_app` 可能收到
+ * bundleId（`com.tencent.xinWeChat`）、进程名（`WeChat`）或显示名（`微信`），
+ * 而快照拿到的是另一种。宁可宽一点 —— 判错的方向是「把一次真实抢占当成
+ * 预期之内」，但那要求抢占者的名字恰好包含目标名，概率极低；反过来判严了
+ * 就是每次切应用都卡住，那是必然发生的。
+ */
+function matchesApp(snapshot: FocusSnapshot, expected: string): boolean {
+  const needle = expected.trim().toLowerCase();
+  if (!needle) return false;
+  return [snapshot.appId, snapshot.app]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    .some((value) => {
+      const hay = value.toLowerCase();
+      return hay === needle || hay.includes(needle) || needle.includes(hay);
+    });
+}
+
+/** 窗口身份键。windowId 缺失时退回 pid+标题 —— 有的平台给不出稳定 id。 */
+function keyOf(snapshot: FocusSnapshot): string {
+  return snapshot.windowId ?? `${snapshot.pid ?? ''}::${snapshot.windowTitle ?? ''}`;
+}
+
+function sameRect(a?: Rect, b?: Rect): boolean {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
+/**
+ * 人话渲染，供文本通道输出。刻意做得**短** —— 这条通道的全部价值就是便宜，
+ * 写成一大段就失去了相对截图 20 倍的优势。
+ */
+export function describeFocus(snapshot: FocusSnapshot | null | undefined): string {
+  if (!snapshot) return '焦点: 不可用';
+  const parts = [`前台: ${snapshot.app}`];
+  if (snapshot.windowTitle) parts.push(`窗口「${snapshot.windowTitle}」`);
+  if (snapshot.role) parts.push(`控件 ${snapshot.role}`);
+  if (snapshot.caret) parts.push(`caret(${snapshot.caret.x},${snapshot.caret.y})`);
+  if (snapshot.composing) parts.push('输入法合成中');
+  parts.push(`[L${snapshot.level}]`);
+  return parts.join(' · ');
+}
+
+export function describeFocusChange(
+  before: FocusSnapshot | null | undefined,
+  after: FocusSnapshot | null | undefined,
+): string {
+  if (!before || !after) return '';
+  const changes: string[] = [];
+  if (before.app !== after.app) {
+    changes.push(`前台: ${before.app} → ${after.app}`);
+  }
+  const beforeTitle = before.windowTitle ?? '(无标题)';
+  const afterTitle = after.windowTitle ?? '(无标题)';
+  if (beforeTitle !== afterTitle) {
+    changes.push(`窗口标题: ${beforeTitle} → ${afterTitle}`);
+  }
+  const beforeRole = before.role ?? '(无焦点控件)';
+  const afterRole = after.role ?? '(无焦点控件)';
+  if (beforeRole !== afterRole) {
+    changes.push(`焦点控件: ${beforeRole} → ${afterRole}`);
+  }
+  if (changes.length === 0) return '焦点状态未变化';
+  return `状态变化：${changes.join('；')}`;
+}
+
+/**
+ * 焦点是否稳定。
+ *
+ * ⚠️ 它**不是** settle 的判据之一 —— 那是 R1 之前的设计，已被推翻（见本文件
+ * 头注与 settle.ts）。保留它是给需要单独问「焦点动没动」的调用方用的。
+ */
+export function focusStable(
+  before: FocusSnapshot | null | undefined,
+  after: FocusSnapshot | null | undefined,
+  expectation?: FocusExpectation,
+): boolean {
+  const change = classifyFocusChange(before, after, expectation);
+  return change === FOCUS_CHANGE.NONE || change === FOCUS_CHANGE.EXPECTED;
+}