minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,163 @@
+/**
+ * ============================================================
+ *  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 里写的位置描述若绑死像素就全废
+ *
+ *  **物理换算只发生在本文件里。** 其它模块一律只见相对坐标。
+ * ============================================================
+ */
+
+import type { Rect } from './raster.js';
+
+/** 相对坐标空间的边长。取 1000 而非 100 是为了保留亚百分点精度（小控件需要）。 */
+export const REL_SPAN = 1000;
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** 逻辑点空间里的一块屏幕。 */
+export interface Screen {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * scaleFactor = 物理像素 / 逻辑点。
+ * **必须实测算出，不能假设 1 或 2** —— 外接显示器、缩放设置、Sidecar
+ * 都会给出非整数或非 2 的值。
+ */
+export function scaleFactor(physical: Size, logical: Size): number {
+  if (!logical.width) return 1;
+  return physical.width / logical.width;
+}
+
+/** 相对点 → 逻辑点（鼠标事件用的坐标系）。越界钳住而非报错：模型偶尔给 1000 或轻微越界。 */
+export function relToLogical(rel: Point, screen: Screen): Point {
+  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: Point, screen: Screen): Point {
+  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: Rect, imageSize: Size): Rect {
+  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: Rect, imageSize: Size): Rect {
+  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: Rect, ratio = 0.2, bounds: Size | null = null): Rect {
+  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: Rect, bounds: Size): Rect {
+  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: Rect | null, b: Rect | null): Rect | null {
+  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: Rect, b: Rect): boolean {
+  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: Point, rect: Rect): boolean {
+  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: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+/** 人话描述一个相对矩形，供文本通道使用（比塞一张图便宜 20 倍）。 */
+export function describeRelRect(rect: Rect): string {
+  return `(${rect.x},${rect.y})-(${rect.x + rect.width},${rect.y + rect.height})`;
+}

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

@@ -0,0 +1,201 @@
+/**
+ * ============================================================
+ *  vision/imaging.ts —— 观测图组装（纯函数）
+ * ------------------------------------------------------------
+ *  把「像素」翻译成「模型看得懂、且付得起」的一组图。
+ *
+ *  ★ 为什么不拼接成一张大图（这个方向已被算术否掉，别再走回去）：
+ *    provider 按**像素**计费而非按张数，且 1920×1080 与 3840×2160 到达模型时
+ *    尺寸与计费完全相同（都会被服务端降采样到同一档）。多图是一等公民
+ *    （Claude 单请求 600 张），所以「一次回 N 张独立图、每张拿满分辨率」
+ *    严格优于「拼成九宫格/4K」。
+ *
+ *  ★ 「概览 + ROI 裁剪」的组装（buildObservation）曾在这里，已删除。
+ *    它从未被任何生产路径调用，而它要解决的「看不清小字」现在由
+ *    `observe { rect }` 在本机从完整原始帧裁出局部区域再缩放来解决 ——
+ *    更清晰（局部文字不会先随整屏缩小），同时保持模型输入只有一张图。
+ *    按项目的两次规则删掉，需要时 git 历史里有。
+ * ============================================================
+ */
+import { ANNOTATION_COLOR, cloneImage, drawRect, fadeOutside, fitLongSide, } from './raster.js';
+import { clampRectTo, describeRelRect, padRect, pixelRectToRel } from './geometry.js';
+import { GLOBAL_CHANGE_RATIO, clusterChanges } from './frames.js';
+/** 回放帧长边 —— 它回答「发生了什么」而非「写的什么」，做小是对的。 */
+export const REPLAY_LONG_SIDE = 683;
+/** 单帧最多标几块变化区。超过 3 块说明变化太散，该退化成全量了。 */
+export const MAX_ROIS = 3;
+/** 变化区外扩比例。包围盒常卡在控件边缘，不扩一圈会切掉半个按钮。 */
+export const ROI_PAD_RATIO = 0.2;
+/**
+ * 帧序列单帧的长边 = 720p。
+ *
+ * Claude：⌈1280/28⌉×⌈720/28⌉ = 46×26 = 1196 patch/帧，远在 1568 预算内，
+ * 因此**不会被服务端二次降采样**。比概览档的 1400 小一档是有意的：
+ * 帧序列一次给多张，单帧成本必须压住。
+ */
+export const SEQUENCE_LONG_SIDE = 1280;
+/** 默认帧数。3 帧覆盖 3 秒变化窗口。 */
+export const SEQUENCE_FRAMES = 3;
+/** 帧间隔（毫秒）。1Hz。 */
+export const SEQUENCE_INTERVAL_MS = 1000;
+/**
+ * 未变化区域保留的原色比例 = 0.3，即「70% 透明」。
+ *
+ * 必须是**合成到确定背景色**而不是 alpha 通道 —— 见 raster.ts::fadeOutside。
+ */
+export const SEQUENCE_FADE_ALPHA = 0.3;
+/**
+ * 组装 720p RGB 帧序列。
+ *
+ * 契约（与 SPEC §4.2 一致）：
+ *   [帧1]    关键帧：全量、100% 亮度、无遮罩
+ *   [帧2..N] 变化帧：变化区域（外扩 20%）原色 100% 并用红框标注，
+ *            其余像素合成到白色至 30% 保留度
+ *   时序：正序，帧1 最早、帧N 最新 = 当前状态
+ *
+ * ★ 变化是**逐帧增量**（帧 i vs 帧 i−1），不是「相对关键帧的累计差」——
+ *   需求是「变化**过程**」，累计差会把早期变化一直重复标到最后一帧。
+ */
+export function buildFrameSequence(args) {
+    const { frames: source, longSide = SEQUENCE_LONG_SIDE, fadeAlpha = SEQUENCE_FADE_ALPHA, padRatio = ROI_PAD_RATIO, maxRegionsPerFrame = MAX_ROIS, globalChangeRatio = GLOBAL_CHANGE_RATIO, } = args;
+    if (source.length === 0) {
+        return { frames: [], note: '（本次没有可用的画面帧。）', summary: ['无帧'] };
+    }
+    const scaled = source.map((f) => ({ t: f.t, image: fitLongSide(f.image, longSide) }));
+    const base = scaled[0];
+    const out = [{
+            index: 1,
+            t: base.t,
+            offsetSec: 0,
+            image: base.image,
+            changes: [],
+            degradedToFull: false,
+        }];
+    for (let i = 1; i < scaled.length; i += 1) {
+        const prev = scaled[i - 1];
+        const cur = scaled[i];
+        const bounds = { width: cur.image.width, height: cur.image.height };
+        const diff = diffRgba(prev.image, cur.image);
+        const degraded = diff.ratio >= globalChangeRatio;
+        // clusterChanges 吃时间线，这里把单次差分包成一个采样点复用同一套聚类逻辑，
+        // 避免帧序列与 settle 各写一份「相邻变化怎么合并」。
+        const timeline = diff.bbox
+            ? [{ t: cur.t, ratio: diff.ratio, bbox: diff.bbox }]
+            : [];
+        const regions = degraded
+            ? []
+            : clusterChanges(timeline, { maxClusters: maxRegionsPerFrame })
+                .map((rect) => clampRectTo(padRect(rect, padRatio, bounds), bounds));
+        const image = cloneImage(cur.image);
+        if (regions.length > 0) {
+            fadeOutside(image, regions, fadeAlpha);
+            const thickness = Math.max(2, Math.round(image.width / 400));
+            for (const rect of regions)
+                drawRect(image, rect, ANNOTATION_COLOR, thickness);
+        }
+        out.push({
+            index: i + 1,
+            t: cur.t,
+            offsetSec: Math.round((cur.t - base.t) / 100) / 10,
+            image,
+            changes: regions.map((r) => pixelRectToRel(r, bounds)),
+            degradedToFull: degraded,
+        });
+    }
+    const collapse = args.collapseWhenStatic ?? true;
+    const changedAtAll = out.some((f) => f.changes.length > 0 || f.degradedToFull);
+    const frames = collapse && !changedAtAll ? out.slice(0, 1) : out;
+    return {
+        frames,
+        note: buildSequenceNote(frames),
+        summary: summarizeSequence(frames),
+    };
+}
+/** 两张同尺寸 RGBA 的变化占比与包围盒（走亮度差，与灰度帧差同一判据）。 */
+function diffRgba(a, b, threshold = 8) {
+    if (a.width !== b.width || a.height !== b.height)
+        return { ratio: 1, bbox: null };
+    let changed = 0;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -1;
+    let maxY = -1;
+    for (let y = 0; y < b.height; y += 1) {
+        for (let x = 0; x < b.width; x += 1) {
+            const i = (y * b.width + x) * 4;
+            const la = (a.data[i] * 77 + a.data[i + 1] * 150 + a.data[i + 2] * 29) >> 8;
+            const lb = (b.data[i] * 77 + b.data[i + 1] * 150 + b.data[i + 2] * 29) >> 8;
+            if (Math.abs(la - lb) < 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 total = Math.max(1, b.width * b.height);
+    return {
+        ratio: changed / total,
+        bbox: maxX >= 0 ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 } : null,
+    };
+}
+/**
+ * 随图说明。
+ *
+ * ★ 末句「淡化 ≠ 禁用」是**必须的**：真实 UI 语义里变淡就是禁用/加载中，
+ *   不明说模型会把遮罩区描述成「灰显不可点击」并据此行动。
+ */
+function buildSequenceNote(frames) {
+    if (frames.length === 1) {
+        return [
+            '以上是当前屏幕的完整画面（原色、未做任何遮罩）。',
+            '这段时间内屏幕没有发生变化，因此只附了一帧。',
+            '坐标一律用 0–1000 相对值。',
+        ].join('\n');
+    }
+    const n = frames.length;
+    return [
+        `以上 ${n} 张图是同一块屏幕的连续帧，间隔 1 秒，按时间正序（第 1 张最早，第 ${n} 张 = 当前状态）。`,
+        '第 1 张是关键帧：完整画面、原色。',
+        `第 2–${n} 张是变化过程：只有发生变化的区域保持原色并用红框标注，其余区域已淡化至 30%`,
+        '（淡化只表示「这里没变」，**不表示该控件被禁用或不可点击**）。',
+        '坐标一律用 0–1000 相对值。',
+    ].join('\n');
+}
+function summarizeSequence(frames) {
+    const lines = [`帧序列 ${frames.length} 张 · ${frames[0].image.width}×${frames[0].image.height}`];
+    for (const frame of frames) {
+        if (frame.index === 1) {
+            lines.push('第 1 帧（关键帧，+0.0s）：完整画面');
+            continue;
+        }
+        if (frame.degradedToFull) {
+            lines.push(`第 ${frame.index} 帧（+${frame.offsetSec}s）：整屏变化，已给完整画面`);
+            continue;
+        }
+        if (frame.changes.length === 0) {
+            lines.push(`第 ${frame.index} 帧（+${frame.offsetSec}s）：无变化`);
+            continue;
+        }
+        lines.push(`第 ${frame.index} 帧（+${frame.offsetSec}s）：变化区 ${frame.changes.map(describeRelRect).join('、')}`);
+    }
+    return lines;
+}
+/**
+ * 预算估算：粗略换算一张图在 provider 侧的 token 成本，供调用方在超预算时降级。
+ *
+ * 两家的公式不同，取**较大者**保守估计：
+ *   Claude：⌈w/28⌉ × ⌈h/28⌉（上限 1568）
+ *   OpenAI：85 + 170 × ⌈w/512⌉⌈h/512⌉（先塞进 2048、短边压到 768）
+ * 这只是本地的粗算，真实值以 provider 的 usage 为准。
+ */
+export function estimateImageTokens(image) {
+    const claude = Math.ceil(image.width / 28) * Math.ceil(image.height / 28);
+    const openai = 85 + 170 * Math.ceil(image.width / 512) * Math.ceil(image.height / 512);
+    return Math.max(Math.min(claude, 1568), openai);
+}

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

@@ -0,0 +1,281 @@
+/**
+ * ============================================================
+ *  vision/imaging.ts —— 观测图组装（纯函数）
+ * ------------------------------------------------------------
+ *  把「像素」翻译成「模型看得懂、且付得起」的一组图。
+ *
+ *  ★ 为什么不拼接成一张大图（这个方向已被算术否掉，别再走回去）：
+ *    provider 按**像素**计费而非按张数，且 1920×1080 与 3840×2160 到达模型时
+ *    尺寸与计费完全相同（都会被服务端降采样到同一档）。多图是一等公民
+ *    （Claude 单请求 600 张），所以「一次回 N 张独立图、每张拿满分辨率」
+ *    严格优于「拼成九宫格/4K」。
+ *
+ *  ★ 「概览 + ROI 裁剪」的组装（buildObservation）曾在这里，已删除。
+ *    它从未被任何生产路径调用，而它要解决的「看不清小字」现在由
+ *    `observe { rect }` 在本机从完整原始帧裁出局部区域再缩放来解决 ——
+ *    更清晰（局部文字不会先随整屏缩小），同时保持模型输入只有一张图。
+ *    按项目的两次规则删掉，需要时 git 历史里有。
+ * ============================================================
+ */
+
+import {
+  ANNOTATION_COLOR,
+  type Rect,
+  cloneImage,
+  drawRect,
+  fadeOutside,
+  fitLongSide,
+} from './raster.js';
+import { clampRectTo, describeRelRect, padRect, pixelRectToRel } from './geometry.js';
+import { GLOBAL_CHANGE_RATIO, type TimelinePoint, clusterChanges } from './frames.js';
+import type { RgbaImage } from './png.js';
+
+/** 回放帧长边 —— 它回答「发生了什么」而非「写的什么」，做小是对的。 */
+export const REPLAY_LONG_SIDE = 683;
+
+/** 单帧最多标几块变化区。超过 3 块说明变化太散，该退化成全量了。 */
+export const MAX_ROIS = 3;
+
+/** 变化区外扩比例。包围盒常卡在控件边缘，不扩一圈会切掉半个按钮。 */
+export const ROI_PAD_RATIO = 0.2;
+
+/**
+ * 帧序列单帧的长边 = 720p。
+ *
+ * Claude：⌈1280/28⌉×⌈720/28⌉ = 46×26 = 1196 patch/帧，远在 1568 预算内，
+ * 因此**不会被服务端二次降采样**。比概览档的 1400 小一档是有意的：
+ * 帧序列一次给多张，单帧成本必须压住。
+ */
+export const SEQUENCE_LONG_SIDE = 1280;
+
+/** 默认帧数。3 帧覆盖 3 秒变化窗口。 */
+export const SEQUENCE_FRAMES = 3;
+
+/** 帧间隔（毫秒）。1Hz。 */
+export const SEQUENCE_INTERVAL_MS = 1000;
+
+/**
+ * 未变化区域保留的原色比例 = 0.3，即「70% 透明」。
+ *
+ * 必须是**合成到确定背景色**而不是 alpha 通道 —— 见 raster.ts::fadeOutside。
+ */
+export const SEQUENCE_FADE_ALPHA = 0.3;
+
+// ============================================================
+//  帧序列
+// ============================================================
+
+export interface SequenceSourceFrame {
+  /** 采样时刻（毫秒） */
+  t: number;
+  image: RgbaImage;
+}
+
+export interface SequenceFrame {
+  index: number;
+  t: number;
+  /** 相对首帧的秒数，供文案使用 */
+  offsetSec: number;
+  image: RgbaImage;
+  /** 本帧相对前一帧的变化区（相对坐标 0–1000）；关键帧为空 */
+  changes: Rect[];
+  /** 本帧变化过大而退化成全量 */
+  degradedToFull: boolean;
+}
+
+export interface FrameSequence {
+  frames: SequenceFrame[];
+  /** 随图发给模型的说明。帧数是变量，文案按实际帧数生成。 */
+  note: string;
+  summary: string[];
+}
+
+export interface BuildFrameSequenceArgs {
+  /** 按时间**正序**（最早在前）。 */
+  frames: SequenceSourceFrame[];
+  longSide?: number;
+  fadeAlpha?: number;
+  padRatio?: number;
+  maxRegionsPerFrame?: number;
+  /** 变化占比超过它，该帧退化成全量（整屏都变了，遮罩无意义） */
+  globalChangeRatio?: number;
+  /**
+   * 全程无变化时只保留关键帧。默认开启。
+   *
+   * 不开的话，静态屏幕会得到 N 张**一模一样**的全量图 —— 付 N 倍的 token
+   * 买零信息。这正是「注意力」的本意：有变化才值得多看几眼。
+   */
+  collapseWhenStatic?: boolean;
+}
+
+/**
+ * 组装 720p RGB 帧序列。
+ *
+ * 契约（与 SPEC §4.2 一致）：
+ *   [帧1]    关键帧：全量、100% 亮度、无遮罩
+ *   [帧2..N] 变化帧：变化区域（外扩 20%）原色 100% 并用红框标注，
+ *            其余像素合成到白色至 30% 保留度
+ *   时序：正序，帧1 最早、帧N 最新 = 当前状态
+ *
+ * ★ 变化是**逐帧增量**（帧 i vs 帧 i−1），不是「相对关键帧的累计差」——
+ *   需求是「变化**过程**」，累计差会把早期变化一直重复标到最后一帧。
+ */
+export function buildFrameSequence(args: BuildFrameSequenceArgs): FrameSequence {
+  const {
+    frames: source,
+    longSide = SEQUENCE_LONG_SIDE,
+    fadeAlpha = SEQUENCE_FADE_ALPHA,
+    padRatio = ROI_PAD_RATIO,
+    maxRegionsPerFrame = MAX_ROIS,
+    globalChangeRatio = GLOBAL_CHANGE_RATIO,
+  } = args;
+
+  if (source.length === 0) {
+    return { frames: [], note: '（本次没有可用的画面帧。）', summary: ['无帧'] };
+  }
+
+  const scaled = source.map((f) => ({ t: f.t, image: fitLongSide(f.image, longSide) }));
+  const base = scaled[0]!;
+  const out: SequenceFrame[] = [{
+    index: 1,
+    t: base.t,
+    offsetSec: 0,
+    image: base.image,
+    changes: [],
+    degradedToFull: false,
+  }];
+
+  for (let i = 1; i < scaled.length; i += 1) {
+    const prev = scaled[i - 1]!;
+    const cur = scaled[i]!;
+    const bounds = { width: cur.image.width, height: cur.image.height };
+    const diff = diffRgba(prev.image, cur.image);
+    const degraded = diff.ratio >= globalChangeRatio;
+
+    // clusterChanges 吃时间线，这里把单次差分包成一个采样点复用同一套聚类逻辑，
+    // 避免帧序列与 settle 各写一份「相邻变化怎么合并」。
+    const timeline: TimelinePoint[] = diff.bbox
+      ? [{ t: cur.t, ratio: diff.ratio, bbox: diff.bbox }]
+      : [];
+    const regions = degraded
+      ? []
+      : clusterChanges(timeline, { maxClusters: maxRegionsPerFrame })
+        .map((rect) => clampRectTo(padRect(rect, padRatio, bounds), bounds));
+
+    const image = cloneImage(cur.image);
+    if (regions.length > 0) {
+      fadeOutside(image, regions, fadeAlpha);
+      const thickness = Math.max(2, Math.round(image.width / 400));
+      for (const rect of regions) drawRect(image, rect, ANNOTATION_COLOR, thickness);
+    }
+
+    out.push({
+      index: i + 1,
+      t: cur.t,
+      offsetSec: Math.round((cur.t - base.t) / 100) / 10,
+      image,
+      changes: regions.map((r) => pixelRectToRel(r, bounds)),
+      degradedToFull: degraded,
+    });
+  }
+
+  const collapse = args.collapseWhenStatic ?? true;
+  const changedAtAll = out.some((f) => f.changes.length > 0 || f.degradedToFull);
+  const frames = collapse && !changedAtAll ? out.slice(0, 1) : out;
+
+  return {
+    frames,
+    note: buildSequenceNote(frames),
+    summary: summarizeSequence(frames),
+  };
+}
+
+/** 两张同尺寸 RGBA 的变化占比与包围盒（走亮度差，与灰度帧差同一判据）。 */
+function diffRgba(a: RgbaImage, b: RgbaImage, threshold = 8): { ratio: number; bbox: Rect | null } {
+  if (a.width !== b.width || a.height !== b.height) return { ratio: 1, bbox: null };
+  let changed = 0;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -1;
+  let maxY = -1;
+
+  for (let y = 0; y < b.height; y += 1) {
+    for (let x = 0; x < b.width; x += 1) {
+      const i = (y * b.width + x) * 4;
+      const la = (a.data[i]! * 77 + a.data[i + 1]! * 150 + a.data[i + 2]! * 29) >> 8;
+      const lb = (b.data[i]! * 77 + b.data[i + 1]! * 150 + b.data[i + 2]! * 29) >> 8;
+      if (Math.abs(la - lb) < 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 total = Math.max(1, b.width * b.height);
+  return {
+    ratio: changed / total,
+    bbox: maxX >= 0 ? { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 } : null,
+  };
+}
+
+/**
+ * 随图说明。
+ *
+ * ★ 末句「淡化 ≠ 禁用」是**必须的**：真实 UI 语义里变淡就是禁用/加载中，
+ *   不明说模型会把遮罩区描述成「灰显不可点击」并据此行动。
+ */
+function buildSequenceNote(frames: SequenceFrame[]): string {
+  if (frames.length === 1) {
+    return [
+      '以上是当前屏幕的完整画面（原色、未做任何遮罩）。',
+      '这段时间内屏幕没有发生变化，因此只附了一帧。',
+      '坐标一律用 0–1000 相对值。',
+    ].join('\n');
+  }
+  const n = frames.length;
+  return [
+    `以上 ${n} 张图是同一块屏幕的连续帧，间隔 1 秒，按时间正序（第 1 张最早，第 ${n} 张 = 当前状态）。`,
+    '第 1 张是关键帧：完整画面、原色。',
+    `第 2–${n} 张是变化过程：只有发生变化的区域保持原色并用红框标注，其余区域已淡化至 30%`,
+    '（淡化只表示「这里没变」，**不表示该控件被禁用或不可点击**）。',
+    '坐标一律用 0–1000 相对值。',
+  ].join('\n');
+}
+
+function summarizeSequence(frames: SequenceFrame[]): string[] {
+  const lines = [`帧序列 ${frames.length} 张 · ${frames[0]!.image.width}×${frames[0]!.image.height}`];
+  for (const frame of frames) {
+    if (frame.index === 1) {
+      lines.push('第 1 帧（关键帧，+0.0s）：完整画面');
+      continue;
+    }
+    if (frame.degradedToFull) {
+      lines.push(`第 ${frame.index} 帧（+${frame.offsetSec}s）：整屏变化，已给完整画面`);
+      continue;
+    }
+    if (frame.changes.length === 0) {
+      lines.push(`第 ${frame.index} 帧（+${frame.offsetSec}s）：无变化`);
+      continue;
+    }
+    lines.push(
+      `第 ${frame.index} 帧（+${frame.offsetSec}s）：变化区 ${frame.changes.map(describeRelRect).join('、')}`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * 预算估算：粗略换算一张图在 provider 侧的 token 成本，供调用方在超预算时降级。
+ *
+ * 两家的公式不同，取**较大者**保守估计：
+ *   Claude：⌈w/28⌉ × ⌈h/28⌉（上限 1568）
+ *   OpenAI：85 + 170 × ⌈w/512⌉⌈h/512⌉（先塞进 2048、短边压到 768）
+ * 这只是本地的粗算，真实值以 provider 的 usage 为准。
+ */
+export function estimateImageTokens(image: Pick<RgbaImage, 'width' | 'height'>): number {
+  const claude = Math.ceil(image.width / 28) * Math.ceil(image.height / 28);
+  const openai = 85 + 170 * Math.ceil(image.width / 512) * Math.ceil(image.height / 512);
+  return Math.max(Math.min(claude, 1568), openai);
+}