minimal-agent 0.10.0 → 0.12.0

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

@@ -0,0 +1,220 @@
+/**
+ * ============================================================
+ *  vision/settle.ts —— 稳态判定（纯函数）
+ * ------------------------------------------------------------
+ *  ★ 本模块存在的理由是一条**被推翻的假设**，写在这里防止后人改回去。
+ *
+ *  最初的设计是 `settle = ROI 稳态 AND 焦点未变`，把像素与焦点当**等权**信号。
+ *  支撑它的论证是：「输入法必须知道 caret 位置才能画候选词框，所以哪怕自绘应用
+ *  也堵不住这个泄漏点，焦点 L2 总能拿到」。
+ *
+ *  这个论证是**错的**。IME 通道（Windows TSF/IMM、macOS TSM）与无障碍通道
+ *  （GetGUIThreadInfo、AX API）是两条**独立**路径，前者不向第三方进程暴露：
+ *    - Windows：`GetGUIThreadInfo.hwndCaret` 对 Chromium/Electron 恒为 NULL
+ *      （自绘控件没有真实 HWND）—— Mozilla bug 275171
+ *    - macOS：`AXSelectedTextRange` 在 Mac App Store 版 Electron 被整体 patch 掉，
+ *      all-or-nothing，客户端再怎么查都没有 —— electron#22908
+ *  而 Electron / 自绘控件**正是本能力的目标场景**（微信、企业自研客户端）。
+ *
+ *  本仓库已实测确认这一点：Claude 桌面端（Electron）的 AX 树只暴露窗口本身与
+ *  三个窗口按钮，应用内容一个节点都没有。
+ *
+ *  所以判据必须重排：
+ *
+ *    settled     ← **只看 ROI 像素稳态**。像素永远可用，这是唯一可靠的主判据。
+ *    interrupted ← 焦点**跨进程**变化。L1 就能判（前台窗口归 OS 管），可靠，保留为硬信号。
+ *    enhanced    ← 焦点**同窗口内**变化（控件角色/caret 变）。只有 L2 可用时才有，
+ *                  拿不到就**不报**，绝不因为「没检测到」就断言「没发生」。
+ *    confidence  ← 如实告诉调用方这次判定有多硬。
+ *
+ *  关键取舍：**焦点不再能否决主判据。**
+ *  同窗口内弹层（微信搜索联想那类）在 L2 不可用时靠 ROI 像素变化检出 ——
+ *  弹层出现必然改变像素，所以 ROI 不稳定，settle 自然为假。焦点只是让我们
+ *  **更早、更明确**地知道原因，而不是唯一的发现途径。
+ * ============================================================
+ */
+
+import { type FrameDiff, diffFrames, type TimelinePoint } from './frames.js';
+import {
+  FOCUS_CHANGE,
+  type FocusExpectation,
+  type FocusSnapshot,
+  classifyFocusChange,
+} from './focus.js';
+import { stableMillis } from './frames.js';
+import type { Rect } from './raster.js';
+
+/** 判定强度。模型据此决定要不要再确认一次。 */
+export const CONFIDENCE = {
+  /** 没有连续帧时间线，无法判定稳定。 */
+  UNKNOWN: 'unknown',
+  /** 焦点 L2 可用：像素 + 焦点双通道 */
+  HIGH: 'high',
+  /** 只有像素通道（焦点退到 L1，看不见同窗口内的焦点迁移） */
+  PIXEL_ONLY: 'pixel-only',
+} as const;
+
+export type Confidence = (typeof CONFIDENCE)[keyof typeof CONFIDENCE];
+
+/** 默认静默窗口。点击 200ms 足够，页面跳转要 800ms —— 由调用方按动作类型指定。 */
+export const DEFAULT_QUIET_MS = 300;
+
+/** 低于此变化占比算「安静」。0.001 在 480×270 上约等于 130 像素。 */
+export const DEFAULT_QUIET_RATIO = 0.001;
+
+export interface SettleVerdict {
+  /** ROI 是否已稳定（**主判据**） */
+  settled: boolean;
+  /** ROI 已静止多久 */
+  stableMs: number;
+  /** 是否被跨进程打断（硬信号，L1 即可判） */
+  interrupted: boolean;
+  /** 同窗口内焦点变化（仅 L2 可用时非 null） */
+  enhanced: string | null;
+  confidence: Confidence;
+  /** 人话说明，直接给模型看 */
+  reason: string;
+}
+
+export interface EvaluateSettleArgs {
+  /** 时间线（**应已按 ROI 限定**）。原生 settle 返回的就是这个形状。 */
+  timeline: TimelinePoint[];
+  now: number;
+  focusBefore?: FocusSnapshot | null;
+  focusAfter?: FocusSnapshot | null;
+  expectation?: FocusExpectation;
+  quietMs?: number;
+  quietRatio?: number;
+}
+
+export function evaluateSettle(args: EvaluateSettleArgs): SettleVerdict {
+  const {
+    timeline,
+    now,
+    focusBefore = null,
+    focusAfter = null,
+    expectation = {},
+    quietMs = DEFAULT_QUIET_MS,
+    quietRatio = DEFAULT_QUIET_RATIO,
+  } = args;
+
+  // 单样本没有时间跨度，不能通过把 `now` 人为后移来伪造稳定时长。
+  if (!Array.isArray(timeline) || timeline.length < 2) {
+    return {
+      settled: false,
+      stableMs: 0,
+      interrupted: false,
+      enhanced: null,
+      confidence: CONFIDENCE.UNKNOWN,
+      reason: '稳态未知：缺少连续帧时间线',
+    };
+  }
+
+  // ---- 主判据：像素。永远可用，不依赖任何平台能力。
+  const stable = stableMillis(timeline, now, quietRatio);
+  const settled = stable >= quietMs;
+
+  // ---- 焦点通道：能拿到哪层就用哪层，拿不到就不报（不假装）
+  const level = focusAfter?.level ?? focusBefore?.level ?? 0;
+  const change = classifyFocusChange(focusBefore, focusAfter, expectation);
+
+  // 跨进程打断只需 L1（前台窗口/进程归 OS 管，任何应用都藏不住），故恒可信
+  const interrupted = change === FOCUS_CHANGE.OTHER_PROCESS;
+
+  // 同窗口内的焦点迁移需要 L2（控件角色 / caret）。L1 下**永远检测不到**，
+  // 此时必须报 null 而不是 'none' —— 后者会被误读成「确认没发生」。
+  const enhanced =
+    level >= 2 && change === FOCUS_CHANGE.SAME_WINDOW ? FOCUS_CHANGE.SAME_WINDOW : null;
+
+  const confidence = level >= 2 ? CONFIDENCE.HIGH : CONFIDENCE.PIXEL_ONLY;
+
+  return {
+    settled,
+    stableMs: stable,
+    interrupted,
+    enhanced,
+    confidence,
+    reason: describe({ settled, stable, quietMs, interrupted, enhanced, confidence }),
+  };
+}
+
+function describe(input: {
+  settled: boolean;
+  stable: number;
+  quietMs: number;
+  interrupted: boolean;
+  enhanced: string | null;
+  confidence: Confidence;
+}): string {
+  const parts: string[] = [];
+  parts.push(
+    input.settled
+      ? `界面已稳定（静止 ${input.stable}ms）`
+      : `界面仍在变化（静止仅 ${input.stable}ms，需 ${input.quietMs}ms）`,
+  );
+  if (input.interrupted) parts.push('⚠️ 焦点被**其它进程**抢走，属外部打断');
+  if (input.enhanced) parts.push('⚠️ 同窗口内焦点发生迁移（应用弹出了新界面元素）');
+  if (input.confidence === CONFIDENCE.PIXEL_ONLY) {
+    // 这句必须说：不说的话模型会把「没报焦点变化」当成「焦点没变」
+    parts.push('（仅像素判据：当前后端拿不到控件级焦点，同窗口内的焦点迁移无法检出）');
+  }
+  return parts.join('；');
+}
+
+export interface AbortTypingArgs {
+  focusBefore?: FocusSnapshot | null;
+  focusAfter?: FocusSnapshot | null;
+  expectation?: FocusExpectation;
+  roiDiff?: FrameDiff | null;
+  changeRatioLimit?: number;
+}
+
+/**
+ * 输入过程中的逐步判定 —— 「打字打到一半界面变了」的核心。
+ *
+ * 同样遵循「焦点不否决主判据」：
+ *   - 跨进程打断 → 必停（L1 可判，可靠）
+ *   - 同窗口迁移 → L2 可用时必停；L2 不可用时**退回像素**：目标区域出现显著
+ *     变化就停（弹层出现必然改变像素）
+ */
+export function shouldAbortTyping(args: AbortTypingArgs): { abort: boolean; reason: string | null } {
+  const {
+    focusBefore,
+    focusAfter,
+    expectation = {},
+    roiDiff = null,
+    changeRatioLimit = 0.02,
+  } = args;
+
+  const change = classifyFocusChange(focusBefore, focusAfter, expectation);
+  if (change === FOCUS_CHANGE.OTHER_PROCESS) {
+    return { abort: true, reason: '焦点被其它进程抢走' };
+  }
+
+  const level = focusAfter?.level ?? 0;
+  if (level >= 2 && change === FOCUS_CHANGE.SAME_WINDOW) {
+    return { abort: true, reason: '应用在同窗口内弹出了新界面元素并转移了焦点' };
+  }
+
+  // L2 拿不到时的像素兜底：输入过程中目标区域不该发生大面积变化
+  if (level < 2 && roiDiff && roiDiff.ratio > changeRatioLimit) {
+    return {
+      abort: true,
+      reason: `输入区域出现显著变化（${(roiDiff.ratio * 100).toFixed(1)}%），疑似弹出了联想/补全面板`,
+    };
+  }
+
+  return { abort: false, reason: null };
+}
+
+/** 便利封装：直接用两帧算 ROI 变化，供 shouldAbortTyping 的像素兜底使用。 */
+export function roiChange(
+  before: Uint8Array,
+  after: Uint8Array,
+  width: number,
+  height: number,
+  roi?: Rect,
+  threshold?: number,
+): FrameDiff {
+  return diffFrames(before, after, width, height, { roi, threshold });
+}

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

@@ -0,0 +1,196 @@
+/**
+ * ============================================================
+ *  vision/telemetry.ts —— 调用遥测与汇总
+ * ------------------------------------------------------------
+ *  存在的理由：整套设计里有两个**未经验证的假设**支撑着核心决策 ——
+ *
+ *    ① 「大多数动作不需要图」（成本模型建立其上，但从没实测过，
+ *       是从「人怎么操作电脑」类比来的。而 agent 没有连续感知、没有肌肉记忆，
+ *       很可能远比人更依赖看图）
+ *    ② 「焦点 L2 通常可用」（已查证在 Electron/自绘应用上大概率**不可用**，
+ *       本仓库实测也确认了这点；但到底多大比例，只有持续实测能答）
+ *
+ *  没有数据就只能靠推理，而推理已经错过一次（见 settle.ts 头注）。
+ *  本模块把每次调用的**元数据**记下来，汇总成可判定的数字。
+ *
+ *  ★ 隐私硬约束（不可放宽）：
+ *    只记命令名、耗时、枚举值、比例。
+ *    **绝不记录**：屏幕内容、截图路径、输入的文本、窗口标题、应用内数据。
+ *    持续截屏本身已经是隐私敏感的，日志再泄漏内容就无法向客户交代。
+ *    实现是**白名单**而不是调用方自觉，守护测试见 test/computerUseVision.test.ts。
+ * ============================================================
+ */
+import { appendFile, mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 连续失败/无效动作达到此数，引擎**强制**拒绝同类动作。 */
+export const CONSECUTIVE_FAILURE_LIMIT = 3;
+/** 只允许出现在遥测行里的字段。多一个都不行 —— 白名单而非黑名单。 */
+const ALLOWED_FIELDS = new Set([
+    't', 'cmd', 'ms', 'backend', 'degraded', 'focusLevel', 'images', 'estTokens',
+    'changeRatio', 'settled', 'stableMs', 'settleConfidence', 'focusChange',
+    'settleMode', 'interrupted', 'refused', 'ok',
+    'frames', 'axNodes', 'axTruncated',
+    // 不可逆动作审批的结局（短枚举，如 irreversible_approved / irreversible_denied）。
+    //
+    // 刻意**不**复用 `refused`：那个字段参与连续失败计数，而「用户不批准这次
+    // 提交」不该把后续无关的写操作一起熔断掉。审批结局要能被审计到，但不能
+    // 污染「模型是不是在原地打转」这个判断。
+    'gate',
+]);
+/** 字符串字段的长度上限：只允许短枚举值，杜绝有人把标题/文本塞进来。 */
+const MAX_STRING_CHARS = 64;
+/**
+ * 过滤成只含白名单字段的记录。**这是隐私防线的实现点** ——
+ * 调用方多传了什么都会被丢掉，而不是靠调用方自觉。
+ */
+export function sanitizeRecord(raw) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ALLOWED_FIELDS.has(key))
+            continue;
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === 'string') {
+            out[key] = value.length > MAX_STRING_CHARS ? value.slice(0, MAX_STRING_CHARS) : value;
+            continue;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean')
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * 单个日志文件的大小上限；超过就轮转成 `.1`（只留一代）。
+ *
+ * 有上限是必需的，不是优化：一台长期跑桌面自动化的机器会攒下越来越大的
+ * 隐私数据堆。遥测的用途是看比例和趋势，最近这些条完全够用。
+ */
+export const MAX_LOG_BYTES = 2 * 1024 * 1024;
+/**
+ * 追加一条记录。
+ *
+ * ★ **append-only，不是读改写。** 这里曾经是「整文件读进来 → 截断到 2000 行
+ *   → 原子 rename 写回」，有两个真问题：
+ *     ① 并发写互相覆盖 —— 两个进程同时读到同一份旧内容，各自加一行写回，
+ *        先写的那条就没了；临时文件名只有毫秒时间戳 + PID，同进程内并发
+ *        （本模块本来就是 fire-and-forget 调用）还可能撞名
+ *     ② 每条记录的成本随文件大小线性增长
+ *   `appendFile` 对单行小写入在 POSIX 上是原子的，正好是日志需要的语义。
+ *
+ * **永不抛异常**：遥测是观测手段不是功能，写不进去宁可少一条。
+ */
+export async function record(logPath, raw) {
+    const line = `${JSON.stringify({ t: Date.now(), ...sanitizeRecord(raw) })}\n`;
+    await mkdir(dirname(logPath), { recursive: true }).catch(() => { });
+    await rotateIfLarge(logPath);
+    await appendFile(logPath, line, { mode: 0o600 }).catch(() => { });
+}
+/** 超限就把当前文件挪成 `.1`（覆盖上一代）。失败静默 —— 轮转不了也要能记。 */
+async function rotateIfLarge(logPath) {
+    try {
+        const info = await stat(logPath);
+        if (info.size < MAX_LOG_BYTES)
+            return;
+        await rename(logPath, `${logPath}.1`);
+    }
+    catch {
+        /* 文件不存在或无法轮转，都不影响追加 */
+    }
+}
+export async function readRecords(logPath) {
+    const raw = await readFile(logPath, 'utf8').catch(() => '');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // 半行/损坏行跳过，不因日志问题打断主流程
+        }
+    }
+    return out;
+}
+export async function clearRecords(logPath) {
+    await rm(logPath, { force: true }).catch(() => { });
+}
+/** 汇总。产出的每一项都直接对应一个待验证的设计假设。 */
+export function summarize(records) {
+    const actions = records.filter((r) => ACTION_CMDS.has(String(r.cmd)));
+    const observes = records.filter((r) => r.cmd === 'observe');
+    const withImages = records.filter((r) => Number(r.images ?? 0) > 0);
+    const total = records.length;
+    const focusLevels = tally(records.map((r) => r.focusLevel).filter((v) => v !== undefined));
+    const confidences = tally(records.map((r) => r.settleConfidence).filter(Boolean));
+    const refusals = tally(records.map((r) => r.refused).filter(Boolean));
+    return {
+        total,
+        actions: actions.length,
+        observes: observes.length,
+        // ── 假设 ①：大多数动作不需要图
+        imageCallRatio: total ? withImages.length / total : 0,
+        estTokensTotal: records.reduce((sum, r) => sum + Number(r.estTokens ?? 0), 0),
+        // ── 假设 ②：焦点 L2 通常可用
+        focusLevels,
+        l2Ratio: ratioOf(focusLevels, '2'),
+        settleConfidence: confidences,
+        refusals,
+        failureRate: total ? records.filter((r) => r.ok === false).length / total : 0,
+        latency: latencyStats(records.map((r) => r.ms).filter((v) => typeof v === 'number')),
+    };
+}
+const ACTION_CMDS = new Set(['click', 'type', 'key', 'hotkey', 'scroll', 'drag', 'hover']);
+function tally(values) {
+    const out = {};
+    for (const v of values) {
+        if (v === undefined)
+            continue;
+        const key = String(v);
+        out[key] = (out[key] ?? 0) + 1;
+    }
+    return out;
+}
+function ratioOf(tallied, key) {
+    const total = Object.values(tallied).reduce((a, b) => a + b, 0);
+    return total ? (tallied[key] ?? 0) / total : 0;
+}
+function latencyStats(values) {
+    if (values.length === 0)
+        return { count: 0 };
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        count: sorted.length,
+        min: sorted[0],
+        p50: sorted[Math.floor(sorted.length * 0.5)],
+        p95: sorted[Math.floor(sorted.length * 0.95)],
+        max: sorted[sorted.length - 1],
+    };
+}
+/** 人话渲染。每项都标注它在验证什么假设。 */
+export function renderReport(summary) {
+    if (summary.total === 0)
+        return '尚无遥测记录。先跑几次 ComputerUse 再看。';
+    const pct = (v) => `${(v * 100).toFixed(1)}%`;
+    const lines = [
+        `# Computer Use 遥测汇总（${summary.total} 次调用）`,
+        '',
+        `动作类 ${summary.actions} 次 · 观测类 ${summary.observes} 次 · 失败率 ${pct(summary.failureRate)}`,
+        '',
+        '## 假设 ①：大多数动作不需要图',
+        `实测**带图调用占比 ${pct(summary.imageCallRatio)}**`,
+        `累计图像成本估算 ${summary.estTokensTotal} tokens`,
+        '',
+        '## 假设 ②：焦点 L2 通常可用',
+        `实测**L2 可用率 ${pct(summary.l2Ratio)}**；各层分布 ${JSON.stringify(summary.focusLevels)}`,
+        `settle 判据强度分布 ${JSON.stringify(summary.settleConfidence)}`,
+    ];
+    if (Object.keys(summary.refusals).length > 0) {
+        lines.push('', '## 引擎拒绝', JSON.stringify(summary.refusals));
+    }
+    if (summary.latency.count > 0) {
+        const l = summary.latency;
+        lines.push('', '## 耗时(ms)', `min ${l.min} · p50 ${l.p50} · p95 ${l.p95} · max ${l.max}`);
+    }
+    return lines.join('\n');
+}

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

@@ -0,0 +1,241 @@
+/**
+ * ============================================================
+ *  vision/telemetry.ts —— 调用遥测与汇总
+ * ------------------------------------------------------------
+ *  存在的理由：整套设计里有两个**未经验证的假设**支撑着核心决策 ——
+ *
+ *    ① 「大多数动作不需要图」（成本模型建立其上，但从没实测过，
+ *       是从「人怎么操作电脑」类比来的。而 agent 没有连续感知、没有肌肉记忆，
+ *       很可能远比人更依赖看图）
+ *    ② 「焦点 L2 通常可用」（已查证在 Electron/自绘应用上大概率**不可用**，
+ *       本仓库实测也确认了这点；但到底多大比例，只有持续实测能答）
+ *
+ *  没有数据就只能靠推理，而推理已经错过一次（见 settle.ts 头注）。
+ *  本模块把每次调用的**元数据**记下来，汇总成可判定的数字。
+ *
+ *  ★ 隐私硬约束（不可放宽）：
+ *    只记命令名、耗时、枚举值、比例。
+ *    **绝不记录**：屏幕内容、截图路径、输入的文本、窗口标题、应用内数据。
+ *    持续截屏本身已经是隐私敏感的，日志再泄漏内容就无法向客户交代。
+ *    实现是**白名单**而不是调用方自觉，守护测试见 test/computerUseVision.test.ts。
+ * ============================================================
+ */
+
+import { appendFile, mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/** 连续失败/无效动作达到此数，引擎**强制**拒绝同类动作。 */
+export const CONSECUTIVE_FAILURE_LIMIT = 3;
+
+/** 只允许出现在遥测行里的字段。多一个都不行 —— 白名单而非黑名单。 */
+const ALLOWED_FIELDS = new Set([
+  't', 'cmd', 'ms', 'backend', 'degraded', 'focusLevel', 'images', 'estTokens',
+  'changeRatio', 'settled', 'stableMs', 'settleConfidence', 'focusChange',
+  'settleMode', 'interrupted', 'refused', 'ok',
+  'frames', 'axNodes', 'axTruncated',
+  // 不可逆动作审批的结局（短枚举，如 irreversible_approved / irreversible_denied）。
+  //
+  // 刻意**不**复用 `refused`：那个字段参与连续失败计数，而「用户不批准这次
+  // 提交」不该把后续无关的写操作一起熔断掉。审批结局要能被审计到，但不能
+  // 污染「模型是不是在原地打转」这个判断。
+  'gate',
+]);
+
+/** 字符串字段的长度上限：只允许短枚举值，杜绝有人把标题/文本塞进来。 */
+const MAX_STRING_CHARS = 64;
+
+export type TelemetryRecord = Record<string, string | number | boolean>;
+
+/**
+ * 过滤成只含白名单字段的记录。**这是隐私防线的实现点** ——
+ * 调用方多传了什么都会被丢掉，而不是靠调用方自觉。
+ */
+export function sanitizeRecord(raw: Record<string, unknown>): TelemetryRecord {
+  const out: TelemetryRecord = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!ALLOWED_FIELDS.has(key)) continue;
+    if (value === undefined || value === null) continue;
+    if (typeof value === 'string') {
+      out[key] = value.length > MAX_STRING_CHARS ? value.slice(0, MAX_STRING_CHARS) : value;
+      continue;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 单个日志文件的大小上限；超过就轮转成 `.1`（只留一代）。
+ *
+ * 有上限是必需的，不是优化：一台长期跑桌面自动化的机器会攒下越来越大的
+ * 隐私数据堆。遥测的用途是看比例和趋势，最近这些条完全够用。
+ */
+export const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+/**
+ * 追加一条记录。
+ *
+ * ★ **append-only，不是读改写。** 这里曾经是「整文件读进来 → 截断到 2000 行
+ *   → 原子 rename 写回」，有两个真问题：
+ *     ① 并发写互相覆盖 —— 两个进程同时读到同一份旧内容，各自加一行写回，
+ *        先写的那条就没了；临时文件名只有毫秒时间戳 + PID，同进程内并发
+ *        （本模块本来就是 fire-and-forget 调用）还可能撞名
+ *     ② 每条记录的成本随文件大小线性增长
+ *   `appendFile` 对单行小写入在 POSIX 上是原子的，正好是日志需要的语义。
+ *
+ * **永不抛异常**：遥测是观测手段不是功能，写不进去宁可少一条。
+ */
+export async function record(logPath: string, raw: Record<string, unknown>): Promise<void> {
+  const line = `${JSON.stringify({ t: Date.now(), ...sanitizeRecord(raw) })}\n`;
+  await mkdir(dirname(logPath), { recursive: true }).catch(() => {});
+  await rotateIfLarge(logPath);
+  await appendFile(logPath, line, { mode: 0o600 }).catch(() => {});
+}
+
+/** 超限就把当前文件挪成 `.1`（覆盖上一代）。失败静默 —— 轮转不了也要能记。 */
+async function rotateIfLarge(logPath: string): Promise<void> {
+  try {
+    const info = await stat(logPath);
+    if (info.size < MAX_LOG_BYTES) return;
+    await rename(logPath, `${logPath}.1`);
+  } catch {
+    /* 文件不存在或无法轮转，都不影响追加 */
+  }
+}
+
+export async function readRecords(logPath: string): Promise<TelemetryRecord[]> {
+  const raw = await readFile(logPath, 'utf8').catch(() => '');
+  const out: TelemetryRecord[] = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as TelemetryRecord);
+    } catch {
+      // 半行/损坏行跳过，不因日志问题打断主流程
+    }
+  }
+  return out;
+}
+
+export async function clearRecords(logPath: string): Promise<void> {
+  await rm(logPath, { force: true }).catch(() => {});
+}
+
+// 这里曾有一个 `consecutiveFailures(records)`：从日志末尾往回数连续失败，
+// 给熔断当判据。它已被删除，因为把安全策略建在一个**全机共享的日志文件**上
+// 有三个绕不过去的问题：没有会话隔离（A 的失败熔断 B）、读改写有竞态、
+// 计数不分动作（一次成功 observe 就清零，于是「失败→观察→失败」这个最常见的
+// 打转模式可以无限绕过熔断）。
+//
+// 熔断现在住在 `ComputerUseService`：按 `运行 + 动作指纹` 分桶、内存态、同步
+// 无 IO。本模块退回**纯观测**职责。别再把判定搬回来。
+
+export interface LatencyStats {
+  count: number;
+  min?: number;
+  p50?: number;
+  p95?: number;
+  max?: number;
+}
+
+export interface TelemetrySummary {
+  total: number;
+  actions: number;
+  observes: number;
+  imageCallRatio: number;
+  estTokensTotal: number;
+  focusLevels: Record<string, number>;
+  l2Ratio: number;
+  settleConfidence: Record<string, number>;
+  refusals: Record<string, number>;
+  failureRate: number;
+  latency: LatencyStats;
+}
+
+/** 汇总。产出的每一项都直接对应一个待验证的设计假设。 */
+export function summarize(records: TelemetryRecord[]): TelemetrySummary {
+  const actions = records.filter((r) => ACTION_CMDS.has(String(r.cmd)));
+  const observes = records.filter((r) => r.cmd === 'observe');
+  const withImages = records.filter((r) => Number(r.images ?? 0) > 0);
+  const total = records.length;
+
+  const focusLevels = tally(records.map((r) => r.focusLevel).filter((v) => v !== undefined));
+  const confidences = tally(records.map((r) => r.settleConfidence).filter(Boolean));
+  const refusals = tally(records.map((r) => r.refused).filter(Boolean));
+
+  return {
+    total,
+    actions: actions.length,
+    observes: observes.length,
+    // ── 假设 ①：大多数动作不需要图
+    imageCallRatio: total ? withImages.length / total : 0,
+    estTokensTotal: records.reduce((sum, r) => sum + Number(r.estTokens ?? 0), 0),
+    // ── 假设 ②：焦点 L2 通常可用
+    focusLevels,
+    l2Ratio: ratioOf(focusLevels, '2'),
+    settleConfidence: confidences,
+    refusals,
+    failureRate: total ? records.filter((r) => r.ok === false).length / total : 0,
+    latency: latencyStats(
+      records.map((r) => r.ms).filter((v): v is number => typeof v === 'number'),
+    ),
+  };
+}
+
+const ACTION_CMDS = new Set(['click', 'type', 'key', 'hotkey', 'scroll', 'drag', 'hover']);
+
+function tally(values: (string | number | boolean | undefined)[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const v of values) {
+    if (v === undefined) continue;
+    const key = String(v);
+    out[key] = (out[key] ?? 0) + 1;
+  }
+  return out;
+}
+
+function ratioOf(tallied: Record<string, number>, key: string): number {
+  const total = Object.values(tallied).reduce((a, b) => a + b, 0);
+  return total ? (tallied[key] ?? 0) / total : 0;
+}
+
+function latencyStats(values: number[]): LatencyStats {
+  if (values.length === 0) return { count: 0 };
+  const sorted = [...values].sort((a, b) => a - b);
+  return {
+    count: sorted.length,
+    min: sorted[0]!,
+    p50: sorted[Math.floor(sorted.length * 0.5)]!,
+    p95: sorted[Math.floor(sorted.length * 0.95)]!,
+    max: sorted[sorted.length - 1]!,
+  };
+}
+
+/** 人话渲染。每项都标注它在验证什么假设。 */
+export function renderReport(summary: TelemetrySummary): string {
+  if (summary.total === 0) return '尚无遥测记录。先跑几次 ComputerUse 再看。';
+
+  const pct = (v: number): string => `${(v * 100).toFixed(1)}%`;
+  const lines = [
+    `# Computer Use 遥测汇总（${summary.total} 次调用）`,
+    '',
+    `动作类 ${summary.actions} 次 · 观测类 ${summary.observes} 次 · 失败率 ${pct(summary.failureRate)}`,
+    '',
+    '## 假设 ①：大多数动作不需要图',
+    `实测**带图调用占比 ${pct(summary.imageCallRatio)}**`,
+    `累计图像成本估算 ${summary.estTokensTotal} tokens`,
+    '',
+    '## 假设 ②：焦点 L2 通常可用',
+    `实测**L2 可用率 ${pct(summary.l2Ratio)}**；各层分布 ${JSON.stringify(summary.focusLevels)}`,
+    `settle 判据强度分布 ${JSON.stringify(summary.settleConfidence)}`,
+  ];
+
+  if (Object.keys(summary.refusals).length > 0) {
+    lines.push('', '## 引擎拒绝', JSON.stringify(summary.refusals));
+  }
+  if (summary.latency.count > 0) {
+    const l = summary.latency;
+    lines.push('', '## 耗时(ms)', `min ${l.min} · p50 ${l.p50} · p95 ${l.p95} · max ${l.max}`);
+  }
+  return lines.join('\n');
+}