minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,248 @@
+/**
+ * ============================================================
+ *  vision/frames.ts —— 帧差、稳态、事件锚点（纯函数）
+ * ------------------------------------------------------------
+ *  这是「把判断从慢循环下沉到快循环」的落点：
+ *
+ *      慢循环（模型）Think→Act→Observe→Review   秒级，千 token
+ *      快循环（本模块）采帧→判变化→判稳态         毫秒级，零 token
+ *
+ *  全部运算在 **1/16 分辨率的灰度帧**（480×270）上做 —— 13 万像素的
+ *  absdiff + 阈值 + 包围盒在 typed array 上约 0.3ms，而 30fps 的预算是 33ms。
+ *  这就是「不需要 GPU、也不需要 OpenCV」的全部依据。
+ *
+ *  职责边界（与 Rust 原生侧的分工）：
+ *    - 高频采样与逐帧 absdiff 在原生侧做，跨 IPC 传时间线而不是像素
+ *    - 本模块消费**时间线**（`{t, ratio, bbox}[]`）做稳态/聚类/锚点判断，
+ *      并在 TS 侧直接比对 ring 帧时复用同一套 `diffFrames`
+ *
+ *  一条设计上的硬教训（写进代码免得后人改回去）：
+ *
+ *  ★ **稳态判据不能是「全屏静止」。**
+ *    微信有动图表情和视频预览、剪映有播放预览、任何带实时日志的界面都在动，
+ *    全屏判据在这些应用上**永远为假**，settle 退化成纯超时，闭环原语全废。
+ *    正确判据是「**我操作的那块区域**静止 AND 焦点未被抢走」——
+ *    前者在这里，后者在 focus.ts。
+ * ============================================================
+ */
+import { unionRect } from './geometry.js';
+/** 单像素灰度差超过它才算「变了」。8 足以滤掉视频压缩噪点与抗锯齿抖动，又能捕获真实 UI 变化。 */
+export const DEFAULT_PIXEL_THRESHOLD = 8;
+/** 变化面积占比超过它就判「全局变化」（切窗口/跳页/播放视频），观测形态随之切换。 */
+export const GLOBAL_CHANGE_RATIO = 0.4;
+/** 低于这个变化占比算「安静」（默认 ≈ 480×270 上 130 像素）。 */
+export const DEFAULT_QUIET_RATIO = 0.001;
+/** 两帧灰度差分。 */
+export function diffFrames(a, b, width, height, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_PIXEL_THRESHOLD;
+    const roi = options.roi;
+    const x0 = roi ? Math.max(0, roi.x) : 0;
+    const y0 = roi ? Math.max(0, roi.y) : 0;
+    const x1 = roi ? Math.min(width, roi.x + roi.width) : width;
+    const y1 = roi ? Math.min(height, roi.y + roi.height) : height;
+    let changed = 0;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -1;
+    let maxY = -1;
+    for (let y = y0; y < y1; y += 1) {
+        const row = y * width;
+        for (let x = x0; x < x1; x += 1) {
+            const i = row + x;
+            const av = a[i];
+            const bv = b[i];
+            const delta = av > bv ? av - bv : bv - av;
+            if (delta < threshold)
+                continue;
+            changed += 1;
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+        }
+    }
+    const totalPixels = Math.max(1, (x1 - x0) * (y1 - y0));
+    return {
+        changedPixels: changed,
+        totalPixels,
+        ratio: changed / totalPixels,
+        bbox: maxX >= 0
+            ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 }
+            : null,
+    };
+}
+/** 变化是否已经大到「整屏换了」的程度 —— 观测形态要从裁剪切成前后两张全屏。 */
+export function isGlobalChange(diff, ratio = GLOBAL_CHANGE_RATIO) {
+    return diff.ratio >= ratio;
+}
+/**
+ * 从一段帧序列算出变化时间线。相邻帧两两比较，产出每个时刻的变化量与位置。
+ * 输出长度 = frames.length - 1。
+ */
+export function buildTimeline(frames, width, height, options = {}) {
+    const out = [];
+    for (let i = 1; i < frames.length; i += 1) {
+        const diff = diffFrames(frames[i - 1].gray, frames[i].gray, width, height, options);
+        out.push({
+            t: frames[i].t,
+            changedPixels: diff.changedPixels,
+            ratio: diff.ratio,
+            bbox: diff.bbox,
+        });
+    }
+    return out;
+}
+/**
+ * 稳态判定：从**最后一帧往回**看，连续多久没有超过 quietRatio 的变化。
+ *
+ * 返回 stableMs 而不是布尔值，调用方自己比阈值 —— 因为不同动作需要的静默
+ * 窗口不同（点击后 200ms 够了，页面跳转要 800ms）。
+ */
+export function stableMillis(timeline, now, quietRatio = DEFAULT_QUIET_RATIO) {
+    if (timeline.length === 0)
+        return 0;
+    let lastNoisy = null;
+    for (let i = timeline.length - 1; i >= 0; i -= 1) {
+        if (timeline[i].ratio > quietRatio) {
+            lastNoisy = timeline[i].t;
+            break;
+        }
+    }
+    if (lastNoisy === null)
+        return now - timeline[0].t;
+    return now - lastNoisy;
+}
+/**
+ * 本段时间线里所有变化的合并包围盒 —— 用于「这几秒里屏幕的哪一块动过」。
+ * 多区域同时变化时会合并成一个大框；需要分开的场景用 clusterChanges。
+ */
+export function overallChangeBox(timeline, quietRatio = DEFAULT_QUIET_RATIO) {
+    let box = null;
+    for (const point of timeline) {
+        if (point.ratio <= quietRatio || !point.bbox)
+            continue;
+        box = unionRect(box, point.bbox);
+    }
+    return box;
+}
+/**
+ * 把时间线上的变化按「是否相邻/重叠」聚成若干独立区域。
+ *
+ * 存在的理由是**多 app 联合操作**：剪映在导出（进度条在动）、浏览器在上传
+ * （状态条在动），这两块离得很远，合并成一个大框等于把整屏都框进去、
+ * ROI 裁剪就失去意义了。
+ *
+ * 返回按面积降序，最多 maxClusters 个。
+ */
+export function clusterChanges(timeline, options = {}) {
+    const quietRatio = options.quietRatio ?? DEFAULT_QUIET_RATIO;
+    const maxClusters = options.maxClusters ?? 3;
+    const mergeSlack = options.mergeSlack ?? 0.5;
+    const clusters = [];
+    for (const point of timeline) {
+        if (point.ratio <= quietRatio || !point.bbox)
+            continue;
+        const hit = clusters.find((c) => nearby(c, point.bbox, mergeSlack));
+        if (hit) {
+            const merged = unionRect(hit, point.bbox);
+            hit.x = merged.x;
+            hit.y = merged.y;
+            hit.width = merged.width;
+            hit.height = merged.height;
+        }
+        else {
+            clusters.push({ ...point.bbox });
+        }
+    }
+    return clusters
+        .sort((p, q) => q.width * q.height - p.width * p.height)
+        .slice(0, maxClusters);
+}
+function nearby(a, b, slack) {
+    const gapX = Math.max(0, Math.max(a.x, b.x) - Math.min(a.x + a.width, b.x + b.width));
+    const gapY = Math.max(0, Math.max(a.y, b.y) - Math.min(a.y + a.height, b.y + b.height));
+    return (gapX <= Math.max(a.width, b.width) * slack &&
+        gapY <= Math.max(a.height, b.height) * slack);
+}
+/**
+ * 事件锚点：从帧序列里挑出**最有信息量的** N 个时刻。
+ *
+ * 为什么不等间隔采样：界面变化是**突发**的。8.5 秒静止、最后 0.5 秒发生全部
+ * 事情的情况下，等间隔 9 帧里有 8 帧是同一张图 —— 花了 9 倍的钱买到 1 帧的信息。
+ *
+ * 锚点语义：动作前 → 首次变化 → 变化峰值 → 稳定后。
+ */
+export function pickEventAnchors(frames, timeline, options = {}) {
+    const quietRatio = options.quietRatio ?? DEFAULT_QUIET_RATIO;
+    const max = options.max ?? 4;
+    if (frames.length === 0)
+        return [];
+    if (timeline.length === 0) {
+        return [{ label: '当前', index: frames.length - 1, t: frames[frames.length - 1].t }];
+    }
+    const anchors = [];
+    const push = (label, index) => {
+        if (index < 0 || index >= frames.length)
+            return;
+        anchors.push({ label, index, t: frames[index].t });
+    };
+    push('动作前', 0);
+    const firstChange = timeline.findIndex((p) => p.ratio > quietRatio);
+    if (firstChange >= 0)
+        push('首次变化', firstChange + 1);
+    let peakIndex = -1;
+    let peakRatio = quietRatio;
+    timeline.forEach((point, i) => {
+        if (point.ratio > peakRatio) {
+            peakRatio = point.ratio;
+            peakIndex = i;
+        }
+    });
+    if (peakIndex >= 0)
+        push('变化峰值', peakIndex + 1);
+    push('稳定后', frames.length - 1);
+    // 同一帧被多个语义命中时保留**最先**的标签（更能解释「为什么选它」）
+    const seen = new Set();
+    return anchors
+        .filter((a) => (seen.has(a.index) ? false : (seen.add(a.index), true)))
+        .sort((p, q) => p.index - q.index)
+        .slice(0, max);
+}
+/**
+ * 环形缓冲。帧**只在内存**，永不落盘 —— 持续截屏在客户机器上是隐私敏感的，
+ * 这条是产品要求不是性能优化。
+ */
+export class FrameRing {
+    capacity;
+    items = [];
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    push(record) {
+        this.items.push(record);
+        if (this.items.length > this.capacity) {
+            this.items.splice(0, this.items.length - this.capacity);
+        }
+    }
+    /** 取时间戳 ≥ since 的帧（升序）。 */
+    since(since) {
+        return this.items.filter((f) => f.t >= since);
+    }
+    /** 最近 n 帧（升序）。 */
+    recent(n) {
+        return n <= 0 ? [] : this.items.slice(-n);
+    }
+    get latest() {
+        return this.items[this.items.length - 1] ?? null;
+    }
+    get size() {
+        return this.items.length;
+    }
+    clear() {
+        this.items = [];
+    }
+}

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

@@ -0,0 +1,329 @@
+/**
+ * ============================================================
+ *  vision/frames.ts —— 帧差、稳态、事件锚点（纯函数）
+ * ------------------------------------------------------------
+ *  这是「把判断从慢循环下沉到快循环」的落点：
+ *
+ *      慢循环（模型）Think→Act→Observe→Review   秒级，千 token
+ *      快循环（本模块）采帧→判变化→判稳态         毫秒级，零 token
+ *
+ *  全部运算在 **1/16 分辨率的灰度帧**（480×270）上做 —— 13 万像素的
+ *  absdiff + 阈值 + 包围盒在 typed array 上约 0.3ms，而 30fps 的预算是 33ms。
+ *  这就是「不需要 GPU、也不需要 OpenCV」的全部依据。
+ *
+ *  职责边界（与 Rust 原生侧的分工）：
+ *    - 高频采样与逐帧 absdiff 在原生侧做，跨 IPC 传时间线而不是像素
+ *    - 本模块消费**时间线**（`{t, ratio, bbox}[]`）做稳态/聚类/锚点判断，
+ *      并在 TS 侧直接比对 ring 帧时复用同一套 `diffFrames`
+ *
+ *  一条设计上的硬教训（写进代码免得后人改回去）：
+ *
+ *  ★ **稳态判据不能是「全屏静止」。**
+ *    微信有动图表情和视频预览、剪映有播放预览、任何带实时日志的界面都在动，
+ *    全屏判据在这些应用上**永远为假**，settle 退化成纯超时，闭环原语全废。
+ *    正确判据是「**我操作的那块区域**静止 AND 焦点未被抢走」——
+ *    前者在这里，后者在 focus.ts。
+ * ============================================================
+ */
+
+import { unionRect } from './geometry.js';
+import type { Rect } from './raster.js';
+
+/** 单像素灰度差超过它才算「变了」。8 足以滤掉视频压缩噪点与抗锯齿抖动，又能捕获真实 UI 变化。 */
+export const DEFAULT_PIXEL_THRESHOLD = 8;
+
+/** 变化面积占比超过它就判「全局变化」（切窗口/跳页/播放视频），观测形态随之切换。 */
+export const GLOBAL_CHANGE_RATIO = 0.4;
+
+/** 低于这个变化占比算「安静」（默认 ≈ 480×270 上 130 像素）。 */
+export const DEFAULT_QUIET_RATIO = 0.001;
+
+export interface FrameDiff {
+  changedPixels: number;
+  totalPixels: number;
+  ratio: number;
+  bbox: Rect | null;
+}
+
+export interface DiffOptions {
+  threshold?: number;
+  /** 限定只看某块区域 —— settle 判据用它把「屏幕别处在放视频」排除掉。 */
+  roi?: Rect;
+}
+
+/** 两帧灰度差分。 */
+export function diffFrames(
+  a: Uint8Array,
+  b: Uint8Array,
+  width: number,
+  height: number,
+  options: DiffOptions = {},
+): FrameDiff {
+  const threshold = options.threshold ?? DEFAULT_PIXEL_THRESHOLD;
+  const roi = options.roi;
+
+  const x0 = roi ? Math.max(0, roi.x) : 0;
+  const y0 = roi ? Math.max(0, roi.y) : 0;
+  const x1 = roi ? Math.min(width, roi.x + roi.width) : width;
+  const y1 = roi ? Math.min(height, roi.y + roi.height) : height;
+
+  let changed = 0;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = y0; y < y1; y += 1) {
+    const row = y * width;
+    for (let x = x0; x < x1; x += 1) {
+      const i = row + x;
+      const av = a[i]!;
+      const bv = b[i]!;
+      const delta = av > bv ? av - bv : bv - av;
+      if (delta < threshold) continue;
+      changed += 1;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+    }
+  }
+
+  const totalPixels = Math.max(1, (x1 - x0) * (y1 - y0));
+  return {
+    changedPixels: changed,
+    totalPixels,
+    ratio: changed / totalPixels,
+    bbox:
+      maxX >= 0
+        ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 }
+        : null,
+  };
+}
+
+/** 变化是否已经大到「整屏换了」的程度 —— 观测形态要从裁剪切成前后两张全屏。 */
+export function isGlobalChange(diff: FrameDiff, ratio = GLOBAL_CHANGE_RATIO): boolean {
+  return diff.ratio >= ratio;
+}
+
+/** 一条帧记录。环形缓冲存的就是它。 */
+export interface FrameRecord {
+  t: number;
+  gray: Uint8Array;
+}
+
+/** 时间线上的一个采样点。原生 settle 返回的就是这个形状。 */
+export interface TimelinePoint {
+  t: number;
+  changedPixels?: number;
+  ratio: number;
+  bbox?: Rect | null;
+}
+
+/**
+ * 从一段帧序列算出变化时间线。相邻帧两两比较，产出每个时刻的变化量与位置。
+ * 输出长度 = frames.length - 1。
+ */
+export function buildTimeline(
+  frames: FrameRecord[],
+  width: number,
+  height: number,
+  options: DiffOptions = {},
+): TimelinePoint[] {
+  const out: TimelinePoint[] = [];
+  for (let i = 1; i < frames.length; i += 1) {
+    const diff = diffFrames(frames[i - 1]!.gray, frames[i]!.gray, width, height, options);
+    out.push({
+      t: frames[i]!.t,
+      changedPixels: diff.changedPixels,
+      ratio: diff.ratio,
+      bbox: diff.bbox,
+    });
+  }
+  return out;
+}
+
+/**
+ * 稳态判定：从**最后一帧往回**看，连续多久没有超过 quietRatio 的变化。
+ *
+ * 返回 stableMs 而不是布尔值，调用方自己比阈值 —— 因为不同动作需要的静默
+ * 窗口不同（点击后 200ms 够了，页面跳转要 800ms）。
+ */
+export function stableMillis(
+  timeline: TimelinePoint[],
+  now: number,
+  quietRatio = DEFAULT_QUIET_RATIO,
+): number {
+  if (timeline.length === 0) return 0;
+  let lastNoisy: number | null = null;
+  for (let i = timeline.length - 1; i >= 0; i -= 1) {
+    if (timeline[i]!.ratio > quietRatio) {
+      lastNoisy = timeline[i]!.t;
+      break;
+    }
+  }
+  if (lastNoisy === null) return now - timeline[0]!.t;
+  return now - lastNoisy;
+}
+
+/**
+ * 本段时间线里所有变化的合并包围盒 —— 用于「这几秒里屏幕的哪一块动过」。
+ * 多区域同时变化时会合并成一个大框；需要分开的场景用 clusterChanges。
+ */
+export function overallChangeBox(
+  timeline: TimelinePoint[],
+  quietRatio = DEFAULT_QUIET_RATIO,
+): Rect | null {
+  let box: Rect | null = null;
+  for (const point of timeline) {
+    if (point.ratio <= quietRatio || !point.bbox) continue;
+    box = unionRect(box, point.bbox);
+  }
+  return box;
+}
+
+export interface ClusterOptions {
+  quietRatio?: number;
+  maxClusters?: number;
+  /** 两框间距小于各自尺寸的这个比例就并成一簇。 */
+  mergeSlack?: number;
+}
+
+/**
+ * 把时间线上的变化按「是否相邻/重叠」聚成若干独立区域。
+ *
+ * 存在的理由是**多 app 联合操作**：剪映在导出（进度条在动）、浏览器在上传
+ * （状态条在动），这两块离得很远，合并成一个大框等于把整屏都框进去、
+ * ROI 裁剪就失去意义了。
+ *
+ * 返回按面积降序，最多 maxClusters 个。
+ */
+export function clusterChanges(timeline: TimelinePoint[], options: ClusterOptions = {}): Rect[] {
+  const quietRatio = options.quietRatio ?? DEFAULT_QUIET_RATIO;
+  const maxClusters = options.maxClusters ?? 3;
+  const mergeSlack = options.mergeSlack ?? 0.5;
+
+  const clusters: Rect[] = [];
+  for (const point of timeline) {
+    if (point.ratio <= quietRatio || !point.bbox) continue;
+    const hit = clusters.find((c) => nearby(c, point.bbox!, mergeSlack));
+    if (hit) {
+      const merged = unionRect(hit, point.bbox)!;
+      hit.x = merged.x;
+      hit.y = merged.y;
+      hit.width = merged.width;
+      hit.height = merged.height;
+    } else {
+      clusters.push({ ...point.bbox });
+    }
+  }
+
+  return clusters
+    .sort((p, q) => q.width * q.height - p.width * p.height)
+    .slice(0, maxClusters);
+}
+
+function nearby(a: Rect, b: Rect, slack: number): boolean {
+  const gapX = Math.max(0, Math.max(a.x, b.x) - Math.min(a.x + a.width, b.x + b.width));
+  const gapY = Math.max(0, Math.max(a.y, b.y) - Math.min(a.y + a.height, b.y + b.height));
+  return (
+    gapX <= Math.max(a.width, b.width) * slack &&
+    gapY <= Math.max(a.height, b.height) * slack
+  );
+}
+
+export interface EventAnchor {
+  label: string;
+  index: number;
+  t: number;
+}
+
+/**
+ * 事件锚点：从帧序列里挑出**最有信息量的** N 个时刻。
+ *
+ * 为什么不等间隔采样：界面变化是**突发**的。8.5 秒静止、最后 0.5 秒发生全部
+ * 事情的情况下，等间隔 9 帧里有 8 帧是同一张图 —— 花了 9 倍的钱买到 1 帧的信息。
+ *
+ * 锚点语义：动作前 → 首次变化 → 变化峰值 → 稳定后。
+ */
+export function pickEventAnchors(
+  frames: Pick<FrameRecord, 't'>[],
+  timeline: TimelinePoint[],
+  options: { quietRatio?: number; max?: number } = {},
+): EventAnchor[] {
+  const quietRatio = options.quietRatio ?? DEFAULT_QUIET_RATIO;
+  const max = options.max ?? 4;
+  if (frames.length === 0) return [];
+  if (timeline.length === 0) {
+    return [{ label: '当前', index: frames.length - 1, t: frames[frames.length - 1]!.t }];
+  }
+
+  const anchors: EventAnchor[] = [];
+  const push = (label: string, index: number): void => {
+    if (index < 0 || index >= frames.length) return;
+    anchors.push({ label, index, t: frames[index]!.t });
+  };
+
+  push('动作前', 0);
+
+  const firstChange = timeline.findIndex((p) => p.ratio > quietRatio);
+  if (firstChange >= 0) push('首次变化', firstChange + 1);
+
+  let peakIndex = -1;
+  let peakRatio = quietRatio;
+  timeline.forEach((point, i) => {
+    if (point.ratio > peakRatio) {
+      peakRatio = point.ratio;
+      peakIndex = i;
+    }
+  });
+  if (peakIndex >= 0) push('变化峰值', peakIndex + 1);
+
+  push('稳定后', frames.length - 1);
+
+  // 同一帧被多个语义命中时保留**最先**的标签（更能解释「为什么选它」）
+  const seen = new Set<number>();
+  return anchors
+    .filter((a) => (seen.has(a.index) ? false : (seen.add(a.index), true)))
+    .sort((p, q) => p.index - q.index)
+    .slice(0, max);
+}
+
+/**
+ * 环形缓冲。帧**只在内存**，永不落盘 —— 持续截屏在客户机器上是隐私敏感的，
+ * 这条是产品要求不是性能优化。
+ */
+export class FrameRing<T extends { t: number }> {
+  private items: T[] = [];
+
+  constructor(readonly capacity: number) {}
+
+  push(record: T): void {
+    this.items.push(record);
+    if (this.items.length > this.capacity) {
+      this.items.splice(0, this.items.length - this.capacity);
+    }
+  }
+
+  /** 取时间戳 ≥ since 的帧（升序）。 */
+  since(since: number): T[] {
+    return this.items.filter((f) => f.t >= since);
+  }
+
+  /** 最近 n 帧（升序）。 */
+  recent(n: number): T[] {
+    return n <= 0 ? [] : this.items.slice(-n);
+  }
+
+  get latest(): T | null {
+    return this.items[this.items.length - 1] ?? null;
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  clear(): void {
+    this.items = [];
+  }
+}

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

@@ -0,0 +1,131 @@
+/**
+ * ============================================================
+ *  vision/geometry.ts —— 坐标系（纯函数）
+ * ------------------------------------------------------------
+ *  整个 computer-use 只有**一个**对外坐标约定：
+ *
+ *      0–1000 相对值。左上 (0,0)，右下 (1000,1000)。
+ *
+ *  照抄 MiniMax M3 在 OSWorld computer-use 评测里的设置。它一次性绕开了
+ *  三类真实事故：
+ *    - macOS Retina：物理像素是逻辑点的 2 倍（scaleFactor=2），截图坐标
+ *      直接当鼠标坐标用会偏一半
+ *    - Windows 显示缩放：进程若没声明 per-monitor DPI aware，125%/150% 下
+ *      系统会悄悄给缩放过的坐标，落点系统性偏移（第三方普遍踩这个坑）
+ *    - 多显示器 / 换分辨率：apps/*.md 里写的位置描述若绑死像素就全废
+ *
+ *  **物理换算只发生在本文件里。** 其它模块一律只见相对坐标。
+ * ============================================================
+ */
+/** 相对坐标空间的边长。取 1000 而非 100 是为了保留亚百分点精度（小控件需要）。 */
+export const REL_SPAN = 1000;
+/**
+ * scaleFactor = 物理像素 / 逻辑点。
+ * **必须实测算出，不能假设 1 或 2** —— 外接显示器、缩放设置、Sidecar
+ * 都会给出非整数或非 2 的值。
+ */
+export function scaleFactor(physical, logical) {
+    if (!logical.width)
+        return 1;
+    return physical.width / logical.width;
+}
+/** 相对点 → 逻辑点（鼠标事件用的坐标系）。越界钳住而非报错：模型偶尔给 1000 或轻微越界。 */
+export function relToLogical(rel, screen) {
+    return {
+        x: screen.x + clamp((rel.x / REL_SPAN) * screen.width, 0, screen.width - 1),
+        y: screen.y + clamp((rel.y / REL_SPAN) * screen.height, 0, screen.height - 1),
+    };
+}
+/** 逻辑点 → 相对点（把 OS 报来的 caret/窗口位置翻译给模型看）。 */
+export function logicalToRel(point, screen) {
+    if (!screen.width || !screen.height)
+        return { x: 0, y: 0 };
+    return {
+        x: Math.round(((point.x - screen.x) / screen.width) * REL_SPAN),
+        y: Math.round(((point.y - screen.y) / screen.height) * REL_SPAN),
+    };
+}
+/** 相对矩形 → 某张图上的像素矩形（图可以是任意缩放尺寸，故传 imageSize 而非 screen）。 */
+export function relRectToPixels(rect, imageSize) {
+    const x = (rect.x / REL_SPAN) * imageSize.width;
+    const y = (rect.y / REL_SPAN) * imageSize.height;
+    return {
+        x: Math.round(x),
+        y: Math.round(y),
+        width: Math.max(1, Math.round((rect.width / REL_SPAN) * imageSize.width)),
+        height: Math.max(1, Math.round((rect.height / REL_SPAN) * imageSize.height)),
+    };
+}
+/** 像素矩形 → 相对矩形。 */
+export function pixelRectToRel(rect, imageSize) {
+    if (!imageSize.width || !imageSize.height)
+        return { x: 0, y: 0, width: 0, height: 0 };
+    return {
+        x: Math.round((rect.x / imageSize.width) * REL_SPAN),
+        y: Math.round((rect.y / imageSize.height) * REL_SPAN),
+        width: Math.round((rect.width / imageSize.width) * REL_SPAN),
+        height: Math.round((rect.height / imageSize.height) * REL_SPAN),
+    };
+}
+/**
+ * 向外扩边。变化区检出的包围盒往往刚好卡住控件边缘，裁出来会切掉半个按钮或
+ * 一圈阴影 —— 按比例外扩一圈（默认 20%）再裁，模型才看得到上下文。
+ */
+export function padRect(rect, ratio = 0.2, bounds = null) {
+    const dx = rect.width * ratio;
+    const dy = rect.height * ratio;
+    const padded = {
+        x: rect.x - dx,
+        y: rect.y - dy,
+        width: rect.width + dx * 2,
+        height: rect.height + dy * 2,
+    };
+    return bounds ? clampRectTo(padded, bounds) : padded;
+}
+/** 钳进边界（bounds 用 {width, height}，原点视为 0,0）。 */
+export function clampRectTo(rect, bounds) {
+    const x = clamp(rect.x, 0, bounds.width - 1);
+    const y = clamp(rect.y, 0, bounds.height - 1);
+    return {
+        x,
+        y,
+        width: Math.max(1, Math.min(bounds.width - x, Math.round(rect.width))),
+        height: Math.max(1, Math.min(bounds.height - y, Math.round(rect.height))),
+    };
+}
+/** 两个矩形的最小外接矩形。 */
+export function unionRect(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const x = Math.min(a.x, b.x);
+    const y = Math.min(a.y, b.y);
+    return {
+        x,
+        y,
+        width: Math.max(a.x + a.width, b.x + b.width) - x,
+        height: Math.max(a.y + a.height, b.y + b.height) - y,
+    };
+}
+/** 是否相交（用于判断「模型要点的地方」是否落在变化区里 —— epoch 陈旧性检查的核心）。 */
+export function rectsIntersect(a, b) {
+    return (a.x < b.x + b.width &&
+        b.x < a.x + a.width &&
+        a.y < b.y + b.height &&
+        b.y < a.y + a.height);
+}
+/** 点是否在矩形内。 */
+export function pointInRect(point, rect) {
+    return (point.x >= rect.x &&
+        point.x < rect.x + rect.width &&
+        point.y >= rect.y &&
+        point.y < rect.y + rect.height);
+}
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+/** 人话描述一个相对矩形，供文本通道使用（比塞一张图便宜 20 倍）。 */
+export function describeRelRect(rect) {
+    return `(${rect.x},${rect.y})-(${rect.x + rect.width},${rect.y + rect.height})`;
+}