minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/computeruse.ts

@@ -0,0 +1,3265 @@
+import { appendFile, mkdir, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { pathContainedByAny } from '../../utils/pathContains.js';
+import { hasAskHandler, requestUserChoice } from '../../askBridge.js';
+import { configService } from '../../config/configService.js';
+import type { ImageInputSpec, Tool, ToolResult } from '../../types.js';
+import {
+  getPermissionTargetName,
+  isRunningInAppBundle,
+  openAccessibilitySettings,
+  openScreenCaptureSettings,
+} from './accessibilityPermission.js';
+import {
+  type AxSearchNode,
+  describeNode,
+  findClickableByText,
+  flattenAx,
+} from './axSearch.js';
+import {
+  computerUseService,
+  computerUseStateDir,
+} from './computerUseService.js';
+import { looksLikeIrreversibleRequest } from './grants.js';
+import {
+  classifyIntent,
+  isGlobalCriticalIntent,
+  type RiskHit,
+} from '../../irreversible/rules.js';
+import {
+  type ComputerHumanBoundary,
+  classifyPixelChange,
+  detectComputerHumanBoundary,
+  detectPixelHumanBoundary,
+} from './humanBoundary.js';
+import {
+  EMPTY_MANUAL,
+  renderManualDigest,
+  unmetPreconditionsFor,
+  type AppManual,
+} from './manualSchema.js';
+import {
+  DEFAULT_OBSERVE_FRAMES,
+  type ReplayFrame,
+  buildObservationImages,
+  buildReplayImages,
+  modelFacingImageSize,
+  resolveObservationFrames,
+} from './observationImages.js';
+import {
+  type AccessibilityNode,
+  COMPUTER_USE_TOOL_ACTIONS,
+  type ComputerState,
+  type ComputerUseRect,
+  type ComputerUseRequest,
+  type ComputerUseResponse,
+  isMutatingComputerUseAction,
+  requiredCapability,
+} from './protocol.js';
+import {
+  CONSECUTIVE_FAILURE_LIMIT,
+  recordComputerUseCall,
+} from './telemetryLog.js';
+import { recordComputerUseDiagnosticStep } from './diagnosticTrace.js';
+import {
+  type AppGuide,
+  describeMatch,
+  loadAllAppManuals,
+  matchGuide,
+  matchIrreversible,
+} from './vision/appGuide.js';
+import {
+  FOCUS_CHANGE,
+  deriveFocusSnapshot,
+  describeFocus,
+  describeFocusChange,
+  recommendedAction,
+} from './vision/focus.js';
+import { evaluateSettle } from './vision/settle.js';
+import {
+  type WaitAction,
+  isSimpleWaitAction,
+  isWaitAction,
+  waitForCondition,
+} from './waitFor.js';
+
+/**
+ * 「翻阅长内容」这段指导的**唯一出处**。
+ *
+ * ⚠️ 它此前有两份几乎逐字重复的拷贝：工具描述里一份、`GENERIC_INTERACTION_GUIDE`
+ * 里一份。两份各自演进就会漂移 —— 实测代价：给 `repeat` 补 `repeatFrames` 说明时
+ * 必须记得改两个地方，漏一个模型就只在某些场景看得到那条约束。
+ *
+ * 现在两处都引用这一份。`computerUseGuideSingleSource.test.ts` 钉住这条不变量。
+ */
+/**
+ * 遍历长内容的通用指引。**每次观测都会注入**，所以这里的每一行都要付 token。
+ *
+ * ⚠️ 写作原则：只写**模型要照做的规则**，不写我们的事故复盘 —— 后者是给维护者的，
+ * 放进来只会挤占预算（`computerUseManuals.test.ts` 用 2000 字上限守着这条）。
+ *
+ * 第 5 条的来历：一次「读 20 条聊天记录」的真机任务里，模型 `pageup` 翻到起点读完后，
+ * 又 `pagedown` 原路翻回去 —— 多花 4 轮往返约 104 秒（占全程 31%）和 4 张全屏图的
+ * token，**零新增信息**。早先的措辞是「只读遍历读完后不必翻回原位」，它回答的是
+ * 「有没有必要」，没回答模型心里真正的问题：「我逆序看的，是不是得再顺序看一遍
+ * 才算读全？」现在改成讲清**方向即顺序**，那个疑问才被正面消掉。
+ */
+export const TRAVERSAL_GUIDE_LINES = [
+  '  1. `scroll` + x/y（首选）：坐标必须框在**内容区中心**，不是边缘、不是滚动条。',
+  '     滚轮事件投递给**鼠标所在**的视图，坐标落在哪就滚哪 —— 落在旁边的列表上，',
+  '     滚的就是那个列表（实测发生过：连滚多次，目标区一行没动、旁边的列表滚了一大截）。',
+  '  2. `scroll` 无效时改键盘：先 click 内容区中心让它获得焦点，再 `key` 发',
+  '     `pageup` / `pagedown`（整页），或 `home` / `end`（跳到最开头 / 最末尾）。',
+  '     键盘事件走**焦点控件**，不依赖鼠标位置，在滚轮失效的自绘应用上往往反而更稳。',
+  '  3. **用 `repeat` 一次翻多页，不要一页一轮。** 一页一轮的开销比是 15:1 ——',
+  '     翻页本身约 1 秒，而每轮完整思考约 20 秒。`key`/`scroll` 都支持 `repeat`（上限 8），',
+  '     一轮内连做 N 次、把**每次之后的画面**一起带回，翻到边界自动停并告诉你停在第几次。',
+  '     ⚠️ 只是想**快速定位**（翻到第 N 页、跳到列表末尾）而不读中间内容时，务必加',
+  '     `repeatFrames:"last"` 只取终点一张 —— 否则 repeat:8 会一次回 8 张全屏图',
+  '     （约 1 万 token），中间那些页你根本不看。',
+  '  4. 回执里的变化率优先报**目标区域**（标注了是「目标区域」还是「全屏」）。',
+  '     提示「目标区域没有变化」= 这一路没生效，**换第 2 条，不要加大滚动距离重试**。',
+  '  5. ⭐ **翻页方向就是顺序信息：往回翻的过程本身就是阅读，别再顺序翻一遍。**',
+  '     每翻一次那一屏都已截图给你，加上你自己发出的方向，先后顺序就是确定的 ——',
+  '     `pageup`/上滚 = 看到的是**从新到旧**，`pagedown`/下滚 = **从旧到新**。',
+  '     看到 4 3 2 1、确认 1 是起点就**读完了**；要正序输出自己倒排即可，不必回翻。',
+  '     ⛔ 这条同样管 `end` / `home`：往回读到一半按 `end` 跳回底部，跟原路翻回去',
+  '     是同一种浪费（实测一次任务里 3 次 `end`，白花约 84 秒），而且会丢失读到哪儿了。',
+  '     只有某一屏当时确实没看清（被挡住／正在加载）才单独回到**那一屏**。',
+  '  6. ⛔ **任何情况下都不要用 `drag` 去拖滚动条，也不要去点那条细边。**',
+  '     现代应用的滚动条通常是隐藏的、只有几像素宽；拖偏或点偏就落到内容上 ——',
+  '     在聊天/文档里那不是滚动，是**框选文本**，属于误操作，而且看起来还像"成功了"。',
+];
+
+const actionValues = COMPUTER_USE_TOOL_ACTIONS;
+
+/**
+ * 模型能自报的动作类别形状。**只允许 `intent:` 前缀**。
+ *
+ * `key:` / `region:` 是引擎自己就能验证的模式（按了哪个键、点在哪个矩形里，
+ * 都是它手里的事实），接受模型自报这两类等于把可验证的判据换成不可验证的
+ * 声明 —— 一个想绕过审批的模型只要少报一句就行，而引擎本来能自己看见。
+ * 所以自报通道只开给引擎**本来就看不见**的那一类：意图。
+ */
+const MODEL_DECLARABLE_ACTION_CLASS = /^intent:[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * 可选**字符串**字段里，空串一律等同「没给」。
+ *
+ * ⚠️ 这不是宽松，是修一个真实的调不动问题：不少模型（GPT 系尤其明显）会把 schema 里
+ * **每个**可选字段都填上默认值再发过来 —— `appId:"" / elementId:"" / textTarget:"" /
+ * actionClass:""`。而下游全都按 `!== undefined` 判断「有没有给」，于是空串被当成
+ * 「你要用它」：`textTarget:""` 去按空文字找控件、`actionClass:""` 撞格式校验……
+ *
+ * 实测代价（用户 Desktop 实机）：连 `observe` 都调不动，而且报错一路歪 ——
+ * 最外层显示的是「Computer Use 运行身份与当前宿主会话不匹配」，
+ * 照那个方向根本查不到是参数问题。
+ *
+ * 空串对这些字段**从来没有过意义**（没有哪个应用的 bundleId 是空串），
+ * 所以归一成 undefined 不丢任何表达力。数值字段不做这种归一 ——
+ * `x:0` 是屏幕最左边，是**合法坐标**，不能当成"没给"。
+ */
+const BLANKABLE_STRING_FIELDS = [
+  'appId', 'windowId', 'displayId', 'elementId', 'expectedRevision',
+  'text', 'key', 'role', 'textTarget', 'actionClass',
+] as const;
+
+const inputSchema = z
+  .object({
+    action: z.enum(actionValues),
+    appId: z.string().optional(),
+    windowId: z.string().optional(),
+    displayId: z.string().optional(),
+    elementId: z.string().optional(),
+    expectedRevision: z.string().optional(),
+    expectedEpoch: z.number().int().nonnegative().optional(),
+    x: z.number().min(0).max(1000).optional(),
+    y: z.number().min(0).max(1000).optional(),
+    /** ★ UI-TARS bbox 支持：框选右下角坐标（0-1000），系统自动取中心点点击，容错率更高 */
+    x2: z.number().min(0).max(1000).optional(),
+    y2: z.number().min(0).max(1000).optional(),
+    toX: z.number().min(0).max(1000).optional(),
+    toY: z.number().min(0).max(1000).optional(),
+    dx: z.number().optional(),
+    dy: z.number().optional(),
+    text: z.string().max(100_000).optional(),
+    key: z.string().max(100).optional(),
+    /**
+     * 把同一个动作连做几次，**一轮往返内完成**（只对 `key` / `scroll` 生效）。
+     *
+     * 存在的理由是实测出来的：一次「翻阅聊天记录」的任务里 14 次翻页键花了 270 秒，
+     * 而这些按键的工具执行总耗时只有 18 秒 —— 开销比 15:1，全部花在「每按一次就要
+     * 完整地想一轮」上。遍历任何可滚动区域（长列表、文档、邮件、diff）都是这个形状。
+     *
+     * 上限 8：再大就等于把「翻到哪了」的判断权整个交给一次盲目重复，
+     * 而模型看不到中间过程就无法纠偏。到边界会自动提前停（见 runRepeatedAction）。
+     */
+    repeat: z.number().int().min(1).max(8).optional(),
+    repeatFrames: z.enum(['all', 'last']).optional(),
+    direction: z.enum(['up', 'down', 'left', 'right']).optional(),
+    /** AX 角色。`wait_for_element` 用它；点击类动作用 `textTarget` 而不是它。 */
+    role: z.string().max(64).optional(),
+    /** 按可见文字定位点击目标（与 elementId / x,y 三选一）。 */
+    textTarget: z.string().max(200).optional(),
+    pixelX: z.number().min(0).optional(),
+    pixelY: z.number().min(0).optional(),
+    pixelX2: z.number().min(0).optional(),
+    pixelY2: z.number().min(0).optional(),
+    filePaths: z.array(z.string()).max(20).optional(),
+    rect: z
+      .object({
+        x: z.number(),
+        y: z.number(),
+        width: z.number().positive(),
+        height: z.number().positive(),
+      })
+      .optional(),
+    magnify: z
+      .object({
+        x: z.number(),
+        y: z.number(),
+        width: z.number().positive(),
+        height: z.number().positive(),
+      })
+      .optional(),
+    magnifyAnchor: z.enum(['screen', 'window']).optional(),
+    timeoutMs: z.number().int().min(100).max(120_000).optional(),
+    quietMs: z.number().int().min(100).max(5_000).optional(),
+    /** 简单 wait 动作的等待时间（毫秒），默认 1000ms */
+    waitMs: z.number().int().min(10).max(30_000).optional(),
+    intent: z.enum(['normal', 'submit']).optional(),
+    actionClass: z.string().optional(),
+    frames: z.number().int().min(1).max(6).optional(),
+    force: z.boolean().optional(),
+    windowOperation: z
+      .enum(['focus', 'minimize', 'restore', 'close', 'move_resize', 'center'])
+      .optional(),
+    dropMethod: z.enum(['paste', 'open_panel']).optional(),
+  })
+  .superRefine((input, ctx) => {
+    // ⚠️ 这里必须自己判空串：zod 的执行顺序是 object → superRefine → transform，
+    // 而归一空串的 transform 排在**后面**，所以 superRefine 看到的仍是原始的 ""。
+    // （transform 不能提到前面：那样 superRefine 就拿不到 ZodObject 的类型推断。）
+    if (input.actionClass === undefined || input.actionClass === '') return;
+    if (!MODEL_DECLARABLE_ACTION_CLASS.test(input.actionClass)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['actionClass'],
+        message:
+          'actionClass 只能是 `intent:<小写短横线名>` 形式，取值必须来自当前应用说明书的 ' +
+          'irreversible: 清单（引擎已把该清单写进观测回执）。key:/region: 由引擎自行判定，不接受自报。',
+      });
+    }
+    // 类别是「这次提交属于哪一类」的限定语，没有提交就没有可限定的东西。
+    // 允许它单独出现会造出一个看着像在申报、实际什么也没申报的调用形状。
+    if (input.intent !== 'submit') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['actionClass'],
+        message:
+          'actionClass 必须与 intent:"submit" 一起给出 —— 它是对这次提交属于哪一类的限定，' +
+          '单独出现没有意义。',
+      });
+    }
+  })
+  // 空串归一成「没给」——必须在 superRefine **之后**、且用 transform 而不是
+  // preprocess：preprocess 会把 schema 的输入类型抹成 unknown，与 Tool 接口不兼容。
+  .transform((input) => {
+    const out = { ...input } as Record<string, unknown>;
+    for (const field of BLANKABLE_STRING_FIELDS) {
+      if (out[field] === '') delete out[field];
+    }
+    // ⚠️ `expectedEpoch` 不再是模型的责任 —— 整个字段一律丢弃。
+    //
+    //    它是我们发明的并发令牌，可它**每次 observe 都会 +1，包括工具内部
+    //    自己发起的那些**（verified transaction 的 before 快照、probe、
+    //    settle 轮询…）。模型只能看到自己显式 observe 的回执，中间被我们
+    //    推走的部分它无从得知 —— 这是一个物理上无法履行的契约。
+    //
+    //    实测代价（两次真机 trace）：`stale epoch: expected 4, current 10`
+    //    这类失败 7 次，全部是模型如实转述了它上次看到的数。
+    //
+    //    正确性并没有因此损失：`runVerifiedTransaction` 本来就用
+    //    `input.expectedEpoch ?? before.epoch` 兜底，而 `before` 是它在动作
+    //    前**当场拍的**那一张 —— 模型给的数从未参与过任何有效判断。
+    //    「别基于过期坐标动手」这件事由 verified transaction 的前后差分
+    //    （movedRatio / probeRegion）真正把关，不靠一个计数器。
+    delete out.expectedEpoch;
+    // ⚠️ `pixelX/pixelY` 同为 0、且又给了比例坐标时，按「模型填了默认值」处理。
+    //    像素坐标 (0,0) 是截图最左上角那一个像素 —— 作为点击目标几乎不可能是真实意图，
+    //    而同时又给出 x/y 更说明它只是在填字段。
+    //    实测代价：GPT 因此**连撞 9 次**坐标互斥，9 轮 LLM 往返全部作废，
+    //    而它每次都照原样重发 —— 报错没能让它改对。
+    if (out.pixelX === 0 && out.pixelY === 0 && (out.x !== undefined || out.y !== undefined)) {
+      delete out.pixelX;
+      delete out.pixelY;
+      if (out.pixelX2 === 0) delete out.pixelX2;
+      if (out.pixelY2 === 0) delete out.pixelY2;
+    }
+    return out as typeof input;
+  });
+type ComputerUseInput = z.infer<typeof inputSchema>;
+
+function capabilityForInput(input: ComputerUseInput) {
+  return requiredCapability(input.action, input.intent ?? 'normal');
+}
+
+/**
+ * 关闭窗口算不可逆：未保存的内容会丢，而且没有「撤销关闭」。
+ *
+ * 它与模型自报的 `intent:'submit'` 走同一条准入，因为后果是同一类的 ——
+ * 一个动作发生后就收不回来了。
+ */
+function isIrreversible(input: ComputerUseInput): boolean {
+  if (input.intent === 'submit') return true;
+  return input.action === 'window' && input.windowOperation === 'close';
+}
+
+function actionDescription(
+  input: ComputerUseInput,
+): NonNullable<
+  Parameters<NonNullable<import('../../toolGate.js').ToolGate>>[0]['action']
+> {
+  const capability = capabilityForInput(input);
+  return {
+    kind: input.action,
+    targetApp: input.appId,
+    transmitsData: ['type', 'clipboard_write', 'file_drop'].includes(
+      input.action,
+    ),
+    irreversible: isIrreversible(input),
+    capability,
+  };
+}
+
+export const computerUseTool: Tool<ComputerUseInput> = {
+  name: 'ComputerUse',
+  description: `观察和操作宿主支持的原生桌面应用。网页 DOM 交互应使用 WebBrowser。
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+【 核心铁律 #0：先 Observe 截图看清现状，再做任何操作 —— 没有例外 】
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+这和 Edit 工具要求「先 Read 文件再编辑」是同一个级别的强制规则：
+  ✅ Edit 工具：不 Read 文件内容就 Edit = 盲改，会把代码改坏
+  ✅ ComputerUse：不 Observe 看截图就操作 = 盲打，会点错按钮、发错消息、汇错钱
+
+规则适用范围：**所有鼠标/键盘写操作，没有例外**
+  - click / double_click / right_click（点击任何位置前）
+  - type / key / hotkey（打字、按快捷键前）
+  - drag / scroll（拖拽、滚动前）
+  - activate_app / window 操作（切应用、关窗口前）
+  - 任何会改变界面状态的动作
+
+强制要求：
+  1. 每次动手前，必须基于「最新的一张 observe 截图」判断坐标和目标，不能凭记忆、不能想当然、不能沿用上一次的结论
+  2. 界面随时可能变：新消息弹窗、别的应用抢焦点、窗口被拖动、输入法候选框弹出来——上一秒的结论下一秒可能就失效了
+  3. ⛔ 绝对禁止连续多个写操作不看截图：比如 click 完直接 type 不 observe = 错误；click → observe 确认焦点对了 → type → observe 确认输入正确 → key(submit) → observe 确认发送成功，才是正确流程
+  4. ⛔ 一次只做一个写操作，做完必须 observe 看结果，再决定下一步做什么
+  5. 动作执行完后，系统会自动返回新截图；下一个动作必须基于那张最新截图来判断，而不是继续盲操作
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+【 核心铁律 #1：看截图是为了核对目标进度，不是为了验证动作执行 】
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+每次拿到截图后，不要只看"我刚才的动作有没有执行成功"，要问自己：
+- 当前界面状态是什么？标题/聊天对象/页面是什么？
+- 最终目标是什么？当前状态是否已经达成了？（比如右侧对话框已经是目标联系人，搜索这步就完成了，直接进入下一步）
+- 如果目标已达成，立即继续下一步，不要重复执行已完成的步骤。
+
+⛔ 禁止轻易自我否定：操作后如果系统返回 ok=true 且 focus 信息显示前台正确，不要仅凭截图的模糊印象判定"点错了""误点了"。只有在focus信息或截图明确显示状态与预期矛盾时才重试。拿不准时先描述当前状态，不急于下"失败"结论。
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+定位方式：
+- 主要靠 VLM 视觉模型直接识别截图中的文字与控件位置。
+- ⛔⛔⛔ **强制要求：所有点击/双击/右键/拖拽/悬停动作，必须使用 bbox 框选（同时提供 x/y 左上角 + x2/y2 右下角）**，系统自动取中心点点击。
+  - 不需要精确框选！只需要大致框住目标按钮/条目/控件即可，即使框大一点、框歪一点也没关系，中心点通常都会落在目标上。
+  - **绝对不要只输出单点 x/y**——单点坐标要求像素级精确，很容易因为视觉估算误差点偏，bbox 容错率高一个数量级。
+  - 只有 drag 动作需要额外提供 toX/toY（拖拽终点，也是0-1000比例）。
+- ⚠️ scroll 滚动也必须提供 x/y（框住要滚动的区域，系统会移动鼠标到那里再滚），否则滚轮会作用在当前鼠标位置——如果鼠标在别的应用窗口上，就会滚错地方。
+
+**翻阅长列表 / 聊天记录 / 文档，按这个顺序：**
+${TRAVERSAL_GUIDE_LINES.join('\n')}
+- 坐标系统：0-1000 是**全屏比例坐标**（不是像素坐标！）：
+  - x=0 是屏幕最左，x=1000 是屏幕最右
+  - y=0 是屏幕最上，y=1000 是屏幕最下
+  - **换算方法（必须按此换算，不要直接输出像素值！）**：
+    1. 在截图上目测目标控件的位置
+    2. 目测估计：目标左边距离左边缘占屏幕宽度的百分比 → ×1000 得到 x
+    3. 目标右边距离左边缘占屏幕宽度的百分比 → ×1000 得到 x2
+    4. 目标上边距离上边缘占屏幕高度的百分比 → ×1000 得到 y
+    5. 目标下边距离上边缘占屏幕高度的百分比 → ×1000 得到 y2
+  - 简单记法：整个屏幕的宽和高都被分成1000份，左0右1000、上0下1000。
+- 辅助定位：macOS AX 无障碍树（elementId / textTarget）。**自绘界面**（Electron、Qt、Flutter、Unity，以及多数跨端客户端）常常拿不到，这时只能用坐标 —— 那不是故障，是常态。
+- 不提供本地 OCR；所有文字识别由 VLM 直接完成。
+
+动作类型（已实现）：
+${actionValues.join('、')}
+（window 的子操作：focus / minimize / restore / close / move_resize / center）
+
+截图与稳定性：
+- ★ 截图自动缩放到约100万像素（对齐UI-TARS MAX_PIXELS），保持宽高比，发给模型的图尺寸固定。
+- 永远返回全屏截图，不返回裁剪图（避免坐标错觉）。
+- 坐标 0-1000 是全屏比例，不需要考虑Retina缩放、不需要考虑图片实际像素尺寸——只需要按比例估算。
+- 动作后系统会自动画红色十字标记你上次点击的位置：如果十字正好在目标上，说明坐标对了；如果十字偏了，根据偏移方向和距离调整下一次的坐标。
+- 改变界面的动作后会快速返回一张最新截图（~150ms），type/key后等待仅50ms。
+- wait 后会自动返回一张最新截图。
+
+输入框操作通用规范（所有应用适用，关键！）：
+
+【第一步：点击输入框后先 observe】
+点击输入框获得焦点后，**必须先 observe 一次**，看清输入框里当前有没有内容、有什么内容。
+
+【第二步：判断是「替换」还是「追加/补全」】
+根据当前任务目标语义判断，**判断原则是：这个输入框要填的是一个完整值，还是在已有内容基础上添加？**
+
+- **✅ 必须清空后输入（替换模式）—— 90% 的表单输入场景都是这个模式**：
+  - 【金融/数字类：高危！】汇款金额、转账金额、支付密码、手机号、身份证号、数量、价格：输入框里有任何残留数字都会造成严重错误（比如原有100，再输100变成100100，多汇了钱）
+  - 【全新内容类】发送新消息、搜索新关键词、填写新表单字段（姓名、地址、邮箱、标题）、新建文件名
+  - 【内容无关类】输入框里已有内容与本次要输入的内容无关（比如上次测试残留、旧草稿、别人留下的内容）
+  - → 标准操作：hotkey:"command+a" 全选 → key:"delete" 删除 → observe 确认输入框为空 → 再输入新内容
+
+- **❌ 不清空，直接追加/编辑（追加模式）—— 少数场景**：
+  - 【内容创作类】续写小说、续写文章、在现有文档末尾添加内容、补充留言、补全句子
+  - 【编辑修改类】修改已有文字（光标定位到要改的位置，只改那部分）、在已有文本中间插入内容
+  - 【连续操作类】在同一个输入框里连续追加内容（如逐条添加列表项）
+  - → 操作：直接在当前光标位置输入即可，不要全选删除
+
+**判断口诀：拿不准的时候，清空了再输——删了重输最多麻烦一次，没清空导致发错/汇错/填错，代价大得多。**
+
+【第三步：输入后核对】
+输入文字完成后，**必须 observe 确认**：
+- 屏幕上显示的文字与目标内容完全一致
+- 输入法候选框已消失（没有未上屏的拼音/候选词）
+- 如果内容不对，不要继续提交，重新定位、修正
+
+【第四步：提交--果断执行】
+按发送/确认键之前，看一眼最新截图和系统返回的焦点信息：
+- 系统返回的「前台」和「焦点」信息是准确的（比截图可靠，截图可能慢半拍）
+- 只要焦点信息显示前台正确、焦点在输入框、输入框文字正确，就果断按发送，不要反复确认
+- 如果截图和焦点信息有矛盾（比如截图看着像别的应用，但focus信息说前台是目标应用），以focus信息为准--截图可能拍到了窗口切换的中间帧
+
+【第五步：提交后确认结果】
+提交（发送、确认）后，**必须 observe 确认动作已生效**：
+- 消息出现在聊天记录里（右侧自己发出的气泡）
+- 表单已提交/关闭/跳转
+- 没有报错提示
+- 无法确认成功时，**只报告状态，禁止重复提交**——重复提交可能导致重复发送消息、重复下单等严重问题。
+
+安全性：
+- 登录、密码、OTP、CAPTCHA 等敏感场景会触发人工边界检测，交由宿主接管。
+- 不可逆操作强制声明规则：**任何会造成外部可见、不可撤销后果的动作，必须显式声明 intent:"submit"**，否则引擎无法识别为不可逆操作，会按普通操作处理（但你绝不能依赖这个漏洞绕过检查）。典型需要声明 intent:"submit" 的场景：
+  - 按回车/ Cmd+Enter 发送消息、发送表单、提交订单、确认付款
+  - 点击"发送""确认""删除""支付""提交"按钮
+  - 关闭窗口（window action with close 操作，引擎自动识别，不需要你声明）
+- 不可逆操作采用风险分级机制：
+  - critical（高危红线：转账付款、永久删除、删好友、格式化、清空数据等）：必须声明 intent:"submit" + 对应 actionClass，需要人工批准；
+  - normal（一般不可逆：发消息、发文件、建群、加好友等）：声明 intent:"submit" + 正确的 actionClass 即可自动放行，无需人工确认弹窗；
+  - 当前应用说明书的 irreversible 清单会随观测结果注入到每次回执里，**只能从那份清单里原样抄 actionClass**。
+    清单里没有的、或者当前应用压根没有说明书 —— 就**不要填 actionClass**，只给 intent:"submit"，走通用审批即可；
+    编一个名字出来不会让它更容易通过，只会退回通用审批还多错一次。
+  - 形状：action:"key", key:"return", intent:"submit", actionClass:"<从回执清单里抄的那一条>"
+- permission_denied/permission_required 交由宿主引导授权；stale_state 重新 observe；verification_failed 说明动作未达预期，应根据返回的新截图重新定位后再试，不得重复同一坐标，不得声称成功。
+- 不得用 Bash 或其它工具绕过 Helper。`,
+  inputSchema,
+  parameters: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: actionValues },
+      appId: {
+        type: 'string',
+        description:
+          '用于 activate_app：应用的 bundleId。形如 com.apple.mail（邮件）、com.apple.Safari（浏览器）、'
+          + 'com.tencent.xinWeChat（微信）、com.microsoft.Excel（Excel）—— 任何 macOS 应用都适用，不限于某几个。' +
+          'activate_app 用 appId 激活应用，不需要先 observe，也不需要 textTarget。' +
+          '如果不知道 bundleId，可以先用 observe 看截图中的 Dock 图标，或用应用名猜测常见格式。',
+      },
+      // ⚠️ 这五个字段此前**一个描述都没有**，模型只能靠撞 invalid_request 才知道
+      // 哪个必填、值从哪来。实测代价：一次 `window` focus 直接报
+      // 「window 必须提供 windowId」，白费一整轮往返。
+      windowId: {
+        type: 'string',
+        description:
+          '⛔ window 动作**必填**。取值必须原样来自上一次 observe 返回的窗口列表（形如 '
+          + '"com.apple.mail:0"，即 "<bundleId>:<序号>"），不要自己拼。'
+          + '拿不到窗口列表说明该应用没有可操作窗口，应先 activate_app 再 observe。',
+      },
+      displayId: {
+        type: 'string',
+        description:
+          '显示器 id，取自 observe 返回的 displays 列表。单显示器时可省略，系统用主屏。',
+      },
+      elementId: {
+        type: 'string',
+        description:
+          '无障碍元素 id。可用观测返回的短引用 @1/@2（系统自动换成真实 id）。'
+          + '使用时必须同时提供 expectedRevision。自绘界面（Electron / Qt / 跨端客户端）无障碍树为空，这条路走不通，改用坐标。',
+      },
+      expectedRevision: {
+        type: 'string',
+        description:
+          '配合 elementId 使用：上一次 observe 返回的 revision，用于确认元素没有过期。'
+          + '与观测不符会返回 stale_state，此时重新 observe 再试。',
+      },
+      x: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description:
+          '⛔ 强制bbox：左上角X坐标（0-1000比例坐标，左=0，右=1000）。必须同时提供 x2 和 y2，系统自动取中心点点击。',
+      },
+      y: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description:
+          '⛔ 强制bbox：左上角Y坐标（0-1000比例坐标，上=0，下=1000）。必须同时提供 x2 和 y2，系统自动取中心点点击。',
+      },
+      x2: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description:
+          '⛔ 强制bbox：右下角X坐标（0-1000比例坐标）。大致框住目标按钮/条目即可，不需要精确，系统自动计算中心点点击，容错率极高。',
+      },
+      y2: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description:
+          '⛔ 强制bbox：右下角Y坐标（0-1000比例坐标）。大致框住目标即可，不需要精确，系统自动点中心点。',
+      },
+      toX: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description: '仅用于 drag 动作：拖拽目标X坐标。',
+      },
+      toY: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1000,
+        description: '仅用于 drag 动作：拖拽目标Y坐标。',
+      },
+      dx: {
+        type: 'number',
+        description:
+          '仅用于 scroll：横向滚动像素（正=向右）。一般用 direction 即可，需要精确距离时才用它。',
+      },
+      dy: {
+        type: 'number',
+        description:
+          '仅用于 scroll：纵向滚动像素（正=向下，负=向上）。一般用 direction 即可；'
+          + 'direction 与 dx/dy 同时给出时以 direction 为准。',
+      },
+      text: {
+        type: 'string',
+        description:
+          '用于 type / clipboard_write：要输入的文本。'
+          + '⛔ **原样给出要输入的文字，不要自己转写**（不要把中文名转成拼音、不要翻译成英文）。'
+          + '中文/emoji 由工具负责送达：系统装着输入法时合成按键到不了控件，'
+          + '工具会**自动整串走剪贴板粘贴**（并还原用户原剪贴板），回执里会说明走了哪条路 —— '
+          + '你不需要为此改写文字 —— 自己转写只会把一个工具已经处理好的问题，'
+          + '变成一个搜不到、点不中的问题。'
+          + '输入前务必按「输入框操作通用规范」确认是否需要先清空残留内容。',
+      },
+      key: {
+        type: 'string',
+        description:
+          'action="key"：单个按键（如 "return", "tab", "escape", "delete", "up", "down", "left", "right"）。' +
+          'action="hotkey"：组合键，格式为"修饰键+按键"（如 "command+c", "command+v", "command+a", "command+shift+4"）。' +
+          '组合键必须用 hotkey，不要用 key。',
+      },
+      direction: {
+        type: 'string',
+        enum: ['up', 'down', 'left', 'right'],
+        description:
+          '仅用于 scroll 动作：滚动方向。每次滚动约500像素（约5行）。' +
+          '⚠️ scroll 必须同时提供 x/y（0-1000相对坐标，指向要滚动的区域中心），' +
+          '否则滚轮会作用在当前鼠标位置（可能在错误的窗口上）。',
+      },
+      repeat: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 8,
+        description:
+          '仅用于 key / scroll：把同一动作连做 N 次，**一轮内完成**，每次后各截一张图一起返回。' +
+          '遍历长列表/聊天记录/文档时请用它，不要一页一轮——一页一轮的开销是工具执行的 15 倍。' +
+          '翻到边界（目标区域不再变化）会自动提前停止并如实告诉你停在第几次。',
+      },
+      repeatFrames: {
+        type: 'string',
+        enum: ['all', 'last'],
+        description:
+          '配合 repeat 用，决定连做 N 次之后回给你几张图。缺省 all。\n'
+          + '- all（默认）：每一次之后各截一张，全部返回。**遍历读内容**时要用它 —— '
+          + '中间翻过去的那些页正是你要读的，只给终点等于全丢。\n'
+          + '- last：只返回最后一张。**快速定位/翻到某一页**时用它 —— 中间过程没有阅读价值，'
+          + '而 repeat:8 会一次回 8 张全屏图（约 1 万 token），纯属浪费还挤占上下文。',
+      },
+      role: {
+        type: 'string',
+        description:
+          'wait_for_element 使用的无障碍角色，例如 "AXButton"、"AXTextField"。可配合 text 同时要求文字片段。',
+      },
+      textTarget: {
+        type: 'string',
+        description:
+          '通过可见文字点击控件，无需坐标。根据上一次观测的无障碍树解析为 elementId，自动保持状态新鲜度检查。' +
+          '当多个控件匹配时会拒绝而不是猜测。自绘应用（如部分国产软件）无无障碍树时不可用。' +
+          '与 elementId 和 x/y 互斥，优先使用。',
+      },
+      pixelX: {
+        type: 'number',
+        minimum: 0,
+        description:
+          '【像素坐标模式】以截图像素为单位的X坐标。比 0-1000 比例坐标更直观，省去心算换算。' +
+          '需要与 pixelY 同时提供。系统会根据截图尺寸自动换算为屏幕坐标。' +
+          '不能与 x/y（比例坐标）同时使用。',
+      },
+      pixelY: {
+        type: 'number',
+        minimum: 0,
+        description: '【像素坐标模式】以截图像素为单位的Y坐标。见 pixelX。',
+      },
+      pixelX2: {
+        type: 'number',
+        minimum: 0,
+        description:
+          '【像素坐标模式】bbox 右下角X坐标（像素）。与 pixelY2 同时提供时系统自动取中心点。',
+      },
+      pixelY2: {
+        type: 'number',
+        minimum: 0,
+        description: '【像素坐标模式】bbox 右下角Y坐标（像素）。见 pixelX2。',
+      },
+      filePaths: {
+        type: 'array',
+        items: { type: 'string' },
+        maxItems: 20,
+        description:
+          '仅用于 file_drop：要投放的文件绝对路径。必须落在本次任务已获批的目录范围内，'
+          + '超出会被拒绝。投放后必须 observe 确认文件真的到了目标位置。',
+      },
+      magnify: {
+        type: 'object',
+        description:
+          '🔍 放大镜（0-1000 相对坐标区域），**只能配 observe 用**。在全屏截图之外**额外**附一张'
+          + '该区域从原始高分辨率帧裁出、放大后的图，专门用来读小字/小数字。'
+          + '为什么需要它：5K 屏原图 5120×2880 会被压到约 1371×771 才发给你，'
+          + '原本 20px 高的小字只剩约 5px —— 那是一团马赛克，靠猜必然出错（实测页码就栽在这里）。'
+          + '⛔ 放大镜只许**读**，不许**定位**：所有点击坐标一律以第 1 张全屏图为准。'
+          + '例：读页面底部中间的页码 → magnify:{x:400,y:800,width:200,height:60}',
+        properties: {
+          x: { type: 'number' },
+          y: { type: 'number' },
+          width: { type: 'number', exclusiveMinimum: 0 },
+          height: { type: 'number', exclusiveMinimum: 0 },
+        },
+        required: ['x', 'y', 'width', 'height'],
+      },
+      magnifyAnchor: {
+        type: 'string',
+        enum: ['screen', 'window'],
+        description:
+          '🔍 magnify 的坐标参照系，默认 screen。\n'
+          + '- screen（默认）：magnify 的 x/y/width/height 是**全屏**比例坐标\n'
+          + '- window：是**相对前台窗口**的比例坐标，引擎自己按当前窗口位置换算。\n'
+          + '★ 应用窗口常常不是全屏的，"窗口底部那一条"用 screen 坐标每次都得先抠窗口范围再手算，'
+          + '算错就框空。窗口在哪是引擎手里的事实 —— 用 window 让它替你算。\n'
+          + '例：读页脚页码（窗口底部通宽一条）→ magnify:{x:0,y:945,width:1000,height:55}, magnifyAnchor:"window"',
+      },
+      rect: {
+        type: 'object',
+        description:
+          '0-1000相对坐标区域。★ observe动作永远返回全屏截图（不裁剪，避免坐标错觉），rect仅用于：' +
+          'grab_region_to_clipboard（区域截图到剪贴板）和 window move_resize（窗口移动/调整大小）。'
+          + '想放大看清小字请用 magnify，不是这个。',
+        properties: {
+          x: { type: 'number' },
+          y: { type: 'number' },
+          width: { type: 'number', exclusiveMinimum: 0 },
+          height: { type: 'number', exclusiveMinimum: 0 },
+        },
+        required: ['x', 'y', 'width', 'height'],
+      },
+      timeoutMs: {
+        type: 'integer',
+        minimum: 100,
+        maximum: 120000,
+        description:
+          'wait_for_* 动作使用：轮询超时时间（默认5000ms）。轮询仅获取元数据（不截图），成本很低。',
+      },
+      quietMs: {
+        type: 'integer',
+        minimum: 100,
+        maximum: 5000,
+        description:
+          'settle 动作使用：区域需要静止多长时间才算稳定（点击后200ms，页面跳转后800ms）。',
+      },
+      waitMs: {
+        type: 'integer',
+        minimum: 10,
+        maximum: 30000,
+        description:
+          'wait 动作使用：等待多少毫秒（默认2000ms）。等待结束后自动返回一张最新截图查看结果。' +
+          '在动作后等待UI响应时使用（如activate_app、click、type之后）。',
+      },
+      intent: {
+        type: 'string',
+        enum: ['normal', 'submit'],
+        description:
+          '当此步骤会造成外部可见、不可逆后果时设为"submit"（如发送消息、下单、永久删除）。' +
+          '需要单独授权，无人批准时会被拒绝。',
+      },
+      actionClass: {
+        type: 'string',
+        description:
+          '此submit对应的不可逆操作类别，例如 "intent:send-message"。仅在 intent:"submit" 时有效。' +
+          '值必须从匹配的应用说明书的 irreversible 列表中原样复制（引擎会自动注入到观测回执中），不要编造。' +
+          '不在列表中的值会被忽略（回退到通用 intent:submit 审批）。此处只接受 "intent:*" 类别。',
+      },
+      frames: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 6,
+        description: `请求多少帧1Hz画面（默认${DEFAULT_OBSERVE_FRAMES}帧）。第1帧是完整关键帧；后续帧会变暗未变化区域。除非需要看动作过程，否则请求1帧即可。`,
+      },
+      force: {
+        type: 'boolean',
+        description:
+          'window center 用：true = 无条件把窗口摆到可用区正中；'
+          + '缺省（false）只在窗口有一部分在屏外、或被 Dock/菜单栏压住时才动它 —— '
+          + '已经摆得好好的就不折腾，给「同屏多应用」留空间。',
+      },
+      windowOperation: {
+        type: 'string',
+        enum: ['focus', 'minimize', 'restore', 'close', 'move_resize', 'center'],
+        description:
+          'window 动作使用。'
+          + '"center"＝把窗口摆进**可用区**（扣掉顶部菜单栏与底部 Dock）的正中，装不下就先缩小；'
+          + '它不是最大化也不是全屏（全屏会独占一个 Space，多应用来回切就废了）。'
+          + '窗口有一部分在屏外、或底部被 Dock 压住时用它 —— 被压住的往往正是输入框或提交按钮，'
+          + '坐标点得到、实际点不着。`activate_app` 已经会在必要时自动做一次，'
+          + '只有想无条件摆正中时才需要显式调。'
+          + '"close"（关闭窗口）被视为不可逆操作（未保存工作会丢失），需要与 intent:"submit" 相同的授权。'
+          + '"move_resize"需要 rect 参数。',
+      },
+      dropMethod: {
+        type: 'string',
+        enum: ['paste', 'open_panel'],
+        description:
+          'file_drop 动作使用。"paste"（默认）：将文件放到剪贴板然后发送Cmd+V粘贴，兼容性最广。' +
+          '"open_panel"：通过Cmd+Shift+G操作**已打开**的文件对话框（不能帮你打开对话框）。' +
+          '两者都不是真正的拖拽（macOS要求源应用发起拖拽，只接受真拖拽的应用无法使用）。操作后务必验证文件是否已到达。',
+      },
+    },
+    required: ['action'],
+  },
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  interruptBehavior: () => 'cancel',
+  gateRequest(input, context) {
+    const run = context.computerRun;
+    const identity = run
+      ? {
+          runContext: {
+            ownerId: run.ownerId,
+            conversationKey: run.conversationKey,
+            runId: run.runId,
+            surface: run.surface,
+          },
+        }
+      : {};
+    // 参数没通过校验（input === undefined）时**仍然给出身份** —— 见 Tool.gateRequest
+    // 的注释：身份来自宿主，与参数无关。只省掉依赖参数的 action / isReadOnly，
+    // 让真正的 zod 错误由工具层报给模型（那里有完整的 issue 文案，模型能自己改）。
+    if (!input) return identity;
+    return {
+      isReadOnly: !isMutatingComputerUseAction(input.action),
+      ...identity,
+      action: actionDescription(input),
+    };
+  },
+  async call(): Promise<ToolResult> {
+    return {
+      ok: false,
+      error: 'ComputerUse 必须由提供运行身份和权限的宿主调用',
+    };
+  },
+  /**
+   * 每次调用都记一条遥测，并在此之前做连续失败熔断。
+   *
+   * 包一层而不是在十几个 return 点各写一遍：漏一个点，失败率统计就是错的，
+   * 而熔断恰好依赖那个统计。
+   */
+  async callWithContext(input, signal, context): Promise<ToolResult> {
+    // 熔断判定放在**记录之前且提前返回**，而不是放进 runComputerUse。
+    //
+    // 这不是代码组织偏好，是正确性要求：熔断的判据来自遥测里的失败计数，
+    // 如果它自己的拒绝也被记成一次失败，计数就会每被拒一次涨一格 ——
+    // 熔断变成永久闭锁，谁都解不开。放在这里，结构上就不可能记到自己。
+    // （单测锁定：拒绝前后遥测行数必须相等。）
+    const breaker = refuseWhenStuck(input, context);
+    if (breaker) {
+      if (context.computerRun) {
+        await recordComputerUseDiagnosticStep({
+          context: context.computerRun,
+          request: input,
+          result: breaker,
+          elapsedMs: 0,
+          diagnostics: { circuitBreaker: true },
+        }).catch(() => {});
+      }
+      return breaker;
+    }
+
+    const startedAt = Date.now();
+    const extra: Record<string, unknown> = {};
+    const result = await runComputerUse(input, signal, context, extra);
+    // 熔断计数（内存、按运行隔离）与遥测（磁盘、纯观测）是两件事，分开记。
+    // 把安全策略押在一个全机共享的日志文件上，是这条修复要纠正的错误。
+    if (context.computerRun) {
+      computerUseService.recordActionOutcome(
+        context.computerRun,
+        input,
+        result.ok,
+      );
+    }
+    void recordComputerUseCall({
+      cmd: input.action,
+      ms: Date.now() - startedAt,
+      ok: result.ok,
+      images: result.visionImages?.length ?? 0,
+      ...extra,
+    });
+    if (context.computerRun) {
+      const observation = computerUseService.lastObservation(
+        context.computerRun,
+      );
+      await recordComputerUseDiagnosticStep({
+        context: context.computerRun,
+        request: input,
+        result,
+        elapsedMs: Date.now() - startedAt,
+        diagnostics: {
+          ...extra,
+          ...(observation?.activeApp?.id
+            ? { activeAppId: observation.activeApp.id }
+            : {}),
+          ...(observation?.revision ? { revision: observation.revision } : {}),
+          ...(observation?.epoch !== undefined
+            ? { epoch: observation.epoch }
+            : {}),
+        },
+      }).catch(() => {});
+    }
+    return result;
+  },
+};
+
+/**
+ * 人工接管的统一处置。AX 判据与像素兜底共用这一份 —— 两条判据只是**怎么发现**
+ * 不同，「发现之后怎么办」必须完全一致，否则弱判据那条路迟早会漏掉某一步。
+ *
+ * 返回 `refusal` 表示要终止；返回 `state` 表示人工处理后拿到了新观测。
+ */
+async function handleHumanBoundary(
+  boundary: ComputerHumanBoundary | null,
+  state: ComputerState,
+  context: import('../../types.js').ToolCallContext,
+  signal?: AbortSignal,
+): Promise<{ refusal?: ToolResult; state?: ComputerState }> {
+  if (boundary && !context.computerIntervention) {
+    const weak =
+      boundary.confidence === 'pixel-only'
+        ? '（这条判断来自像素变化，无法确定弹出的到底是什么）'
+        : '';
+    return {
+      refusal: {
+        ok: false,
+        error: `human_intervention_required: ${boundary.summary}${weak}。当前宿主没有安全的人工接管通道，任务已停止。`,
+      },
+    };
+  }
+  if (!context.computerIntervention) return {};
+  const intervention = await context.computerIntervention.inspect(
+    state,
+    signal,
+  );
+  if (intervention.resolution === 'cancelled') {
+    return {
+      refusal: {
+        ok: false,
+        error:
+          'human_intervention_required: 人工处理已取消，Computer Use 任务已停止',
+      },
+    };
+  }
+  if (intervention.resolution === 'resumed' && intervention.state) {
+    return { state: intervention.state };
+  }
+  return {};
+}
+
+interface WindowBoundsRatio {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/**
+ * 将窗口逻辑像素 bounds 转换为 0-1000 屏幕比例坐标（相对指定显示器）。
+ *
+ * 必须减去 display.logicalBounds 的原点：
+ * - 单屏时 bounds.x 通常为 0，减不减看起来一样；
+ * - 多屏时副屏可能在主屏左边（x 为负）或右边（x 大于主屏宽度），
+ *   不减去 display origin 会得到完全错误的比例值。
+ */
+/**
+ * 挑出某个应用的「主窗口」。
+ *
+ * ⚠️ 两处调用点原来各写各的 `find(...)`，都等价于「取列表里第一个」。这在单窗口
+ * 应用上看不出问题，多窗口应用上必错：微信的窗口列表首项是一块 678pt 宽的辅助
+ * 面板（图片查看器 / 侧栏），2560pt 的主窗口排在后面。后果是模型每次点对了都被
+ * 警告「点到窗口外面去了」——它不是提示错了，是把对的坐标算错了。
+ *
+ * 顺序：先认 `focused`（守护进程的权威答案），再退到面积最大的那个（主窗口几乎
+ * 总是最大的），最后才是第一个。
+ */
+export function pickFrontWindow<
+  W extends {
+    appId: string;
+    minimized?: boolean;
+    focused?: boolean;
+    bounds: { width: number; height: number };
+  },
+>(windows: W[] | undefined, appId: string | undefined): W | undefined {
+  if (!windows?.length || !appId) return undefined;
+  const candidates = windows.filter(
+    (w) =>
+      w.appId === appId
+      && !w.minimized
+      && w.bounds.width > 0
+      && w.bounds.height > 0,
+  );
+  if (!candidates.length) return undefined;
+  return (
+    candidates.find((w) => w.focused === true)
+    ?? candidates.reduce((biggest, w) =>
+      w.bounds.width * w.bounds.height
+      > biggest.bounds.width * biggest.bounds.height
+        ? w
+        : biggest,
+    )
+  );
+}
+
+function windowBoundsToRatio(
+  bounds: { x: number; y: number; width: number; height: number },
+  display: {
+    logicalBounds: { x: number; y: number; width: number; height: number };
+  },
+): WindowBoundsRatio {
+  const screenW = display.logicalBounds.width;
+  const screenH = display.logicalBounds.height;
+  const originX = bounds.x - display.logicalBounds.x;
+  const originY = bounds.y - display.logicalBounds.y;
+  return {
+    left: (originX / screenW) * 1000,
+    top: (originY / screenH) * 1000,
+    right: ((originX + bounds.width) / screenW) * 1000,
+    bottom: ((originY + bounds.height) / screenH) * 1000,
+  };
+}
+
+/**
+ * 把 `magnify` 的框换算成**全屏**比例坐标。
+ *
+ * `magnifyAnchor:'window'` 时，传进来的 x/y/width/height 是**相对前台窗口**的
+ * 0–1000 比例，这里用当前观测里的窗口位置换算成全屏比例。
+ *
+ * ⚠️ 为什么值得让引擎来算：应用窗口常常不是全屏的。「窗口底部那一条」用全屏坐标表达，
+ * 模型每次都得先从回执里抠出窗口范围、再手算 `L + W×0.25` 这类式子 —— 算错就框空，
+ * 而框空的表现是「读不到页码」，一路指不向真因。窗口在哪是**引擎手里的事实**，
+ * 不该让模型每次重算。这也让确定性的 `tool` 步用得上放大镜（那里根本没有模型来算）。
+ *
+ * 拿不到窗口时**原样返回**并当作全屏坐标 —— 宁可框偏，也不要静默不给放大镜
+ * （后者的表现是「放大镜时有时无」，比框偏难查得多）。
+ */
+/** @internal 导出仅供单测钉住窗口锚定的换算。 */
+export function _resolveMagnifyRect(
+  magnify: ComputerUseRect | undefined,
+  anchor: 'screen' | 'window' | undefined,
+  observation: ComputerState | undefined,
+): ComputerUseRect | undefined {
+  if (!magnify || anchor !== 'window') return magnify;
+  const appId = observation?.activeApp?.id;
+  const win = pickFrontWindow(
+    observation?.windows as unknown as {
+      appId: string;
+      minimized?: boolean;
+      focused?: boolean;
+      bounds: { x: number; y: number; width: number; height: number };
+    }[],
+    appId,
+  );
+  const display =
+    observation?.displays?.find((d) => d.primary) ?? observation?.displays?.[0];
+  if (!win || !display?.logicalBounds) return magnify;
+  const ratio = windowBoundsToRatio(win.bounds, display);
+  const w = ratio.right - ratio.left;
+  const h = ratio.bottom - ratio.top;
+  if (!(w > 0 && h > 0)) return magnify;
+  return {
+    x: ratio.left + (magnify.x / 1000) * w,
+    y: ratio.top + (magnify.y / 1000) * h,
+    width: Math.max(1, (magnify.width / 1000) * w),
+    height: Math.max(1, (magnify.height / 1000) * h),
+  };
+}
+
+/** 从 ActionResult 里取某个变化率。没测就是 undefined —— 与「测了但是 0」不同。 */
+/** @internal 导出仅供单测钉住「取哪一层」这个反复踩的坑。 */
+export function _actionChangeRatio(
+  data: unknown,
+  field: 'changeRatio' | 'regionChangeRatio' | 'movedRatio',
+): number | undefined {
+  return actionChangeRatio(data, field);
+}
+
+function actionChangeRatio(
+  data: unknown,
+  field: 'changeRatio' | 'regionChangeRatio' | 'movedRatio',
+): number | undefined {
+  const record = data as Record<string, unknown> | null | undefined;
+  const finite = (value: unknown): number | undefined =>
+    typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+  // ⚠️ **两层都要看。** `verified_action` 的载荷是三段式 `{ type, action, settle,
+  // observation }`，变化率在 `data.action.<field>`；只有未走验证事务的普通动作才把它
+  // 放在 `data.<field>`。
+  //
+  // 这里原先只读外层，于是绝大多数动作（写操作都走验证事务）恒得 undefined ——
+  // 而取错一层**不会报错**，只会让所有依赖它的东西安静失效：滚动边界判定恒 unknown、
+  // trace 里的 changeRatio/regionChangeRatio 恒缺席、「滚动没生效」提示恒不触发。
+  // 同一个坑本文件里已经踩过一次（`data.summary` vs `data.action.summary`，
+  // 那次是取 type 的剪贴板还原提示），这是第二次 —— 所以判据收在这一个函数里，
+  // 别再各自取。
+  const nested = isRecord(record?.action) ? finite(record.action[field]) : undefined;
+  return nested ?? finite(record?.[field]);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * 焦点控件占全屏的面积比例，用于把变化率归一化。
+ *
+ * 在输入框里打字必然改变输入框本身；只有当变化面积**超出控件能解释的范围**
+ * 时才说明控件之外多了东西。这个比例 TS 自己就能算（AX 给了控件矩形、
+ * 观测给了显示器尺寸），不必让原生再测一遍。
+ */
+function focusAreaRatio(state: ComputerState): number | undefined {
+  const caret = deriveFocusSnapshot(state)?.caret;
+  if (!caret) return undefined;
+  const display = state.displays.find((d) => d.primary) ?? state.displays[0];
+  const screenArea =
+    (display?.logicalBounds.width ?? 0) * (display?.logicalBounds.height ?? 0);
+  if (screenArea <= 0) return undefined;
+  const ratio = (caret.width * caret.height) / screenArea;
+  return Number.isFinite(ratio) && ratio > 0 ? Math.min(ratio, 1) : undefined;
+}
+
+/**
+ * 连续失败熔断（R6）。返回非 null 表示拒绝执行。
+ *
+ * 模型在困惑时最容易反复重试同一个失败动作，而它自己看不出自己在打转 ——
+ * 这是引擎级兜底，不指望它自觉停。
+ *
+ * 三条刻意的边界：
+ *   - **只拦写类**。观测类必须放行，否则模型连「我卡在哪」都看不到，
+ *     而看清现状正是它需要做的下一件事。
+ *   - **按运行 + 动作指纹隔离**。别的会话在失败不该影响这个会话；
+ *     换个目标重试也不该继承上一个目标的计数。
+ *   - **自己的拒绝不记录**（由调用点的位置保证：判定在登记之前且提前返回）。
+ *
+ * ★ 一条被推翻的旧论断，留在这里免得有人再推一遍：曾经的写法是「一次成功的
+ *   observe 就清零，因为『先看清楚再动手』正好是我们希望模型做的事」。
+ *   听着合理，实际是个洞 —— `失败 → observe → 失败 → observe …` 是模型打转
+ *   时**最常见**的形状，于是熔断永远数不到 3。现在清零的条件是「**这个动作**
+ *   成功了一次」，observe 成功不清写操作的账。
+ */
+function refuseWhenStuck(
+  input: ComputerUseInput,
+  context: import('../../types.js').ToolCallContext,
+): ToolResult | null {
+  const run = context.computerRun;
+  if (!run) return null;
+  if (!isMutatingComputerUseAction(input.action)) return null;
+  const failures = computerUseService.consecutiveFailuresFor(run, input);
+  if (failures < CONSECUTIVE_FAILURE_LIMIT) return null;
+  return {
+    ok: false,
+    error: `这个动作（${input.action}${input.elementId ? ` ${input.elementId}` : ''}）已经连续失败 ${failures} 次，引擎暂停了对同一目标的重试。请先用 observe 看清楚当前屏幕到底是什么状态（观测不受限制），换一条路径或换一个目标再试；如果判断不出来，就把现状如实告诉用户，不要继续盲试。`,
+  };
+}
+
+/**
+ * 工具主体。返回值与 `callWithContext` 一致；`extra` 用来把只有这里才知道的
+ * 遥测字段（帧数、AX 节点数、变化率…）带给外层的记录点。
+ */
+async function runComputerUse(
+  input: ComputerUseInput,
+  signal: AbortSignal | undefined,
+  context: import('../../types.js').ToolCallContext,
+  extra: Record<string, unknown>,
+): Promise<ToolResult> {
+  const run = context.computerRun;
+  if (!run) return { ok: false, error: '当前宿主未启用 Computer Use' };
+
+  // 不可逆审批必须排在能力检查**之前**。
+  //
+  // `requiredCapability` 把 `intent:'submit'` 映射成 `submit` 能力，而没有
+  // 任何路径会预先授予 submit（`grants.ts` 有意不再从用户措辞里猜它）。
+  // 于是审批一旦排在能力检查之后，就永远跑不到：模型报了 submit → 能力检查
+  // 拒 → 人根本没被问过。这不是「更严格」，是把一条产品能力做成了死路。
+  const authorization = await authorizeIrreversibleAction(input, run, signal);
+  if (authorization.error) {
+    return attachNotice(
+      { ok: false, error: authorization.error },
+      authorization.notice,
+    );
+  }
+
+  // 「你自报的类别没被说明书认领」必须回到模型手上，成败两条路都要说。
+  // 只在拒绝时说会漏掉最要紧的那种情况：降级后的通用审批**通过了**，模型于是
+  // 以为自己那个类别生效了，下次继续报同一个错名字，而它拿到的授权其实一直
+  // 是最宽的 intent:submit。
+  const result = await runAuthorizedComputerUse(
+    input,
+    signal,
+    context,
+    extra,
+    run,
+    authorization.authorized,
+  );
+  return attachNotice(result, authorization.notice);
+}
+
+/**
+ * 语义等待。轮询**元数据观测**（不组装图），命中或超时即返回。
+ *
+ * `list_apps` 是既有的「只要状态、不要截图」路径（`includeScreenshot:false`），
+ * 直接复用 —— 不为轮询新造一个动作。
+ *
+ * 简单 `wait` 动作是纯 sleep，不截图不查 AX 树，用于动作后等待 UI 响应。
+ */
+async function runWait(
+  input: ComputerUseInput,
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+  extra: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  // 简单 wait 动作：sleep 后自动截一张图返回，保证模型能看到等待后的界面状态
+  // （参考 UI-TARS 的 onAfterToolCall 强制截图闭环：wait 后不截图，模型就看不到 UI 响应结果）
+  if (isSimpleWaitAction(input.action)) {
+    const outcome = await waitForCondition(
+      {
+        action: 'wait',
+        ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}),
+      },
+      {
+        observeOnce: async () => null, // 不会被调用
+        ...(signal ? { signal } : {}),
+      },
+    );
+    extra.ms = outcome.waitedMs;
+    extra.polls = 0;
+    if (!outcome.ok) {
+      return { ok: false, error: outcome.content };
+    }
+    // wait 完成后自动截图，让模型看到等待后的界面
+    const obsResponse = await computerUseService.request(
+      run,
+      { action: 'observe', frames: 1 },
+      signal,
+    );
+    if (obsResponse.ok && obsResponse.state) {
+      const assembled = await buildObservationImages(obsResponse.state);
+      // ★ AX吸附：存储短id->真实id映射
+      if (assembled?.axIdMap) {
+        computerUseService.updateAxIdMap(run, assembled.axIdMap);
+      }
+      const lines = [
+        outcome.content,
+        '等待完成，下面是当前界面截图，请根据实际界面状态决定下一步操作。',
+        ...(assembled?.summary ?? []),
+      ].filter(Boolean);
+      return {
+        ok: true,
+        content: lines.join('\n'),
+        ...(assembled?.images.length
+          ? { visionImages: assembled.images, visionNote: assembled.note }
+          : {}),
+      };
+    }
+    return { ok: true, content: outcome.content };
+  }
+
+  // wait_for_* 动作：轮询元数据观测
+  const outcome = await waitForCondition(
+    {
+      action: input.action as WaitAction,
+      ...(input.role !== undefined ? { role: input.role } : {}),
+      ...(input.text !== undefined ? { text: input.text } : {}),
+      ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+    },
+    {
+      observeOnce: async () => {
+        const response = await computerUseService.request(
+          run,
+          { action: 'list_apps' },
+          signal,
+        );
+        return response.ok ? (response.state ?? null) : null;
+      },
+      ...(signal ? { signal } : {}),
+    },
+  );
+  extra.ms = outcome.waitedMs;
+  extra.polls = outcome.polls;
+  return outcome.ok
+    ? {
+        ok: true,
+        content: outcome.elementId
+          ? `${outcome.content}\n可直接用 elementId=${outcome.elementId} 作为下一步的目标。`
+          : outcome.content,
+      }
+    : { ok: false, error: outcome.content };
+}
+
+/**
+ * 把 `textTarget` 换成 `elementId`。
+ *
+ * ★ **不新增定位通道**：文字只负责**解析出** elementId，之后仍走既有的
+ *   `ax:<路径>#<指纹>` 路径 —— 动作前会重算指纹比对，滚过的列表报
+ *   `stale_state` 而不是点错行。新造一条「按文字直接点」的通道会绕过这层自证。
+ *
+ * 三条边界都是**拒绝**而不是猜：
+ *   · 多个匹配 → 列出候选让模型自己选。点错东西的代价远大于多问一轮
+ *   · 零匹配 → 建议 `wait_for_text`（很可能只是还没渲染出来）
+ *   · AX 不可用 → 明说这是 AX 能力，自绘应用上没有；别让模型以为是自己写错了
+ */
+function resolveTextTarget(
+  input: ComputerUseInput,
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+):
+  | { input: ComputerUseInput; info?: string }
+  | { error: string; fallbackToCoord?: boolean } {
+  const text = input.textTarget?.trim() ?? '';
+  if (!text) return { error: 'textTarget 不能是空字符串。' };
+  if (input.elementId) {
+    return {
+      error: 'textTarget 与 elementId 是二选一的定位方式，不要同时给。',
+    };
+  }
+
+  const hasCoord = input.x !== undefined && input.y !== undefined;
+
+  // ★ 输入形状校验**先于**状态校验。
+  //
+  // 参数自相矛盾时要直说，而不是先怪「你还没 observe」—— 后者会把模型引向
+  // 「那我先 observe 一次再原样重发」，而它下一次仍然是同样矛盾的参数。
+  //
+  // schema 里 `textTarget` 的说明本来就写着「与 elementId / x,y **三选一**」，
+  // 而这里的实现却在点击类动作上把坐标当成静默 fallback，等于代码违反自己
+  // 文档化的契约。低风险动作（hover/scroll）保留 fallback：最坏只是悬停位置
+  // 不准；点击类不行，点错东西的代价太高（见调用处 `canFallbackToCoord`）。
+  const LOW_RISK_FALLBACK_ACTIONS = ['hover', 'scroll'];
+  if (hasCoord && !LOW_RISK_FALLBACK_ACTIONS.includes(input.action)) {
+    return {
+      error:
+        'textTarget 与 elementId、x/y 坐标是三选一的定位方式，不要同时给。'
+        + '想按文字点就只给 textTarget；确实要用坐标就去掉 textTarget。',
+    };
+  }
+
+  const fallbackFields = hasCoord ? { fallbackToCoord: true as const } : {};
+
+  const state = computerUseService.lastObservation(run);
+  if (!state) {
+    return {
+      error: '还没有可用的观测 —— 先 observe 一次再用 textTarget 定位。',
+      ...fallbackFields,
+    };
+  }
+  if (!state.accessibility || state.accessibility.truncated === true) {
+    return {
+      error:
+        '按文字定位需要无障碍树，而当前应用没有提供 —— 自绘界面（Electron / Qt / 跨端客户端）的常态。',
+      ...fallbackFields,
+    };
+  }
+
+  const allNodes = flattenAx(state.accessibility.root as AxSearchNode);
+  let candidates = findClickableByText(allNodes, text);
+
+  if (candidates.length === 0) {
+    return {
+      error: `无障碍树里没有文字含「${text}」的可点控件。如果它可能还没渲染出来，先用 wait_for_text 等；否则换个更短的片段。`,
+      ...fallbackFields,
+    };
+  }
+  if (candidates.length > 1) {
+    // 如果同时提供了 x/y 坐标，选距离最近的那个（模型的坐标作为"大概位置"的提示）
+    const primaryDisplay =
+      state.displays?.find((d) => d.primary) ?? state.displays?.[0];
+    if (hasCoord && primaryDisplay) {
+      const display = primaryDisplay;
+      const px =
+        display.logicalBounds.x +
+        (input.x! / 1000) * display.logicalBounds.width;
+      const py =
+        display.logicalBounds.y +
+        (input.y! / 1000) * display.logicalBounds.height;
+      const scored = candidates.map((node) => {
+        const b = node.bounds!;
+        const cx = b.x + b.width / 2;
+        const cy = b.y + b.height / 2;
+        return { node, dist: Math.hypot(cx - px, cy - py) };
+      });
+      scored.sort((a, b) => a.dist - b.dist);
+      const nearest = scored[0]!;
+      // 最近的距离在 200 逻辑点以内才接受，否则还是列出候选让模型确认
+      if (nearest.dist <= 200) {
+        const target = nearest.node;
+        return {
+          input: {
+            ...input,
+            elementId: target.elementId!,
+            expectedRevision: input.expectedRevision ?? state.revision,
+            textTarget: undefined,
+            x: undefined,
+            y: undefined,
+          },
+          info: `textTarget「${text}」匹配到 ${candidates.length} 个，按坐标邻近度选择了最近的：${describeNode(target)}`,
+        };
+      }
+    }
+    return {
+      error: `文字「${text}」匹配到 ${candidates.length} 个可点控件，不替你猜是哪一个：\n${candidates
+        .slice(0, 8)
+        .map((node) => `  - ${describeNode(node)}`)
+        .join(
+          '\n',
+        )}\n用更长的片段区分，或直接给上面某个 elementId，或同时提供 x/y 大致坐标让系统选最近的。`,
+    };
+  }
+
+  const target = candidates[0]!;
+  return {
+    input: {
+      ...input,
+      elementId: target.elementId!,
+      expectedRevision: input.expectedRevision ?? state.revision,
+      textTarget: undefined,
+      x: undefined,
+      y: undefined,
+    },
+  };
+}
+
+/** 把一条引擎侧提示贴到工具回执上。成功走 content、失败走 error，两条都不能漏。 */
+function attachNotice(
+  result: ToolResult,
+  notice: string | undefined,
+): ToolResult {
+  if (!notice) return result;
+  return result.ok
+    ? {
+        ...result,
+        content: [notice, result.content].filter(Boolean).join('\n'),
+      }
+    : { ...result, error: `${result.error}\n${notice}` };
+}
+
+/** 审批已过之后的主体：能力检查、发请求、组装回执。 */
+async function runAuthorizedComputerUse(
+  input: ComputerUseInput,
+  signal: AbortSignal | undefined,
+  context: import('../../types.js').ToolCallContext,
+  extra: Record<string, unknown>,
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+  authorized: boolean,
+): Promise<ToolResult> {
+  const capability = capabilityForInput(input);
+  // `submit` 不查 `capabilities` 数组：它的授权来自上面那次人工批准，且**限定
+  // 到 (应用, 动作类别)**。查数组等于回到「批准一次 = 本回合任何不可逆动作
+  // 都放行」的老路 —— 那正是这条修复要收窄掉的东西。
+  if (capability === 'submit') {
+    if (!authorized) {
+      return {
+        ok: false,
+        error: '这一步被判为不可逆动作，但没有取得对应的人工批准',
+      };
+    }
+  } else if (!run.capabilities.includes(capability)) {
+    return {
+      ok: false,
+      error: `当前运行未获得 Computer Use ${capability} 权限`,
+    };
+  }
+  if (
+    input.appId &&
+    run.allowedApps.length > 0 &&
+    !run.allowedApps.includes(input.appId)
+  ) {
+    return { ok: false, error: '目标应用不在当前 Computer Use 授权范围内' };
+  }
+  if (
+    input.filePaths?.length &&
+    capability === 'file-drop' &&
+    (run.allowedFileRoots?.length ?? 0) === 0
+  ) {
+    return { ok: false, error: '当前运行没有可拖入文件的授权目录' };
+  }
+  let authorizedFilePaths: string[] | undefined;
+  if (input.filePaths?.length && capability === 'file-drop') {
+    const authorization = await authorizeComputerUseFileDropPaths(
+      input.filePaths,
+      run.allowedFileRoots ?? [],
+    );
+    if (!authorization.ok) return { ok: false, error: authorization.error };
+    authorizedFilePaths = authorization.paths;
+  }
+
+  // 语义等待在这里接管：它是**观测的编排**，不是一个守护进程动作。
+  // 放在能力检查之后，是因为它照样要 observe 权限。
+  if (isWaitAction(input.action)) {
+    return runWait(input, run, extra, signal);
+  }
+
+  // 像素坐标模式：把 pixelX/pixelY（截图像素）换算为 0-1000 比例坐标。
+  // 必须在 textTarget 解析之前完成，因为它依赖比例坐标。
+  let resolvedInput = input;
+  const usesCoordinates = POINTING_ACTIONS.has(input.action);
+  const hasPixelCoord =
+    usesCoordinates && (input.pixelX !== undefined || input.pixelY !== undefined);
+  const hasRatioCoord =
+    usesCoordinates && (input.x !== undefined || input.y !== undefined);
+  if (hasPixelCoord && hasRatioCoord) {
+    return {
+      ok: false,
+      error:
+        'pixelX/pixelY（像素坐标）与 x/y（比例坐标）不能同时提供，选一种即可。',
+    };
+  }
+  if (hasPixelCoord) {
+    if (input.pixelX === undefined || input.pixelY === undefined) {
+      return { ok: false, error: 'pixelX 和 pixelY 必须同时提供。' };
+    }
+    const state = computerUseService.lastObservation(run);
+    // ⚠️ 分母必须是**模型实际看到的那张图**的尺寸，不是 daemon 的原始截图尺寸。
+    // 5K 屏上原始截图 5120×2880，压进预算后模型看到 1371×771 —— 差 3.73 倍。
+    // 用原始尺寸做分母，模型量出来的每一个像素坐标都会朝左上偏出近四倍距离，
+    // 在多窗口叠放的桌面上通常意味着点到目标窗口后面的另一个应用。
+    const shown =
+      state?.screenshot?.width && state?.screenshot?.height
+        ? modelFacingImageSize(state.screenshot.width, state.screenshot.height)
+        : undefined;
+    const imgW = shown?.width;
+    const imgH = shown?.height;
+    if (!imgW || !imgH) {
+      return {
+        ok: false,
+        error: '像素坐标模式需要先 observe 一次（获取截图尺寸用于换算）。',
+      };
+    }
+    const ratioX = (input.pixelX / imgW) * 1000;
+    const ratioY = (input.pixelY / imgH) * 1000;
+    resolvedInput = { ...resolvedInput, x: ratioX, y: ratioY };
+    if (input.pixelX2 !== undefined && input.pixelY2 !== undefined) {
+      const ratioX2 = (input.pixelX2 / imgW) * 1000;
+      const ratioY2 = (input.pixelY2 / imgH) * 1000;
+      resolvedInput = { ...resolvedInput, x2: ratioX2, y2: ratioY2 };
+    }
+  }
+
+  // click-by-text：把文字换成 elementId，再走既有的带指纹定位路径。
+  // 放在像素坐标换算之后，因为多匹配选最近时用换算后的坐标作为"大概位置"提示。
+  let textTargetNotice: string | undefined;
+  if (resolvedInput.textTarget !== undefined) {
+    const resolved = resolveTextTarget(resolvedInput, run);
+    if ('error' in resolved) {
+      // 点击类动作不允许 fallback：模型明确想用文字定位，
+      // 没找到就是没找到，不能瞎点（误点击风险太高）。
+      // hover/scroll 等低风险动作允许 fallback，最多只是悬停位置不准或滚错区域。
+      const lowRiskActions = ['hover', 'scroll'];
+      const canFallbackToCoord =
+        resolved.fallbackToCoord &&
+        resolvedInput.x !== undefined &&
+        resolvedInput.y !== undefined &&
+        lowRiskActions.includes(resolvedInput.action);
+      if (canFallbackToCoord) {
+        textTargetNotice = `⚠️ textTarget「${resolvedInput.textTarget}」未找到匹配，已 fallback 到坐标（${resolved.error}）`;
+        resolvedInput = { ...resolvedInput, textTarget: undefined };
+      } else {
+        return { ok: false, error: resolved.error };
+      }
+    } else {
+      resolvedInput = resolved.input;
+      extra.textTarget = 'resolved';
+      if (resolved.info) textTargetNotice = `✅ ${resolved.info}`;
+    }
+  }
+
+  // 长文本 / 非 ASCII 的输入路径：**先直接合成 Unicode 键盘事件，粘贴只做兜底**。
+  //
+  // ⚠️ 这里原来是反的，注释写着「Unicode keyboard synthesis is not reliable across
+  // native macOS controls (notably WeChat's self-drawn inputs)」。在这台机器上实测
+  // 的结论正相反，而且恰恰是在被点名的微信上：
+  //   · 微信**搜索框**：直接打字 ✅（打 "wanglei" 立刻搜出联系人）；Cmd+V ❌ ——
+  //     换成带 flagsChanged 的完整 chord + 真 HID 事件源重试，仍然 ❌
+  //   · 微信**消息输入框**：直接打字 ✅（CJK 也正常）；Cmd+V ✅
+  // 也就是说打字在两处都成立，粘贴只在一处成立。把粘贴摆在前面，等于让中文输入在
+  // 搜索框里必然失败 —— 而这条改写路径**不做验证**就回「已通过剪贴板粘贴输入 N 个
+  // 字符」，模型于是永远不知道自己没打进去，只会换个坐标一遍遍重试。
+  //
+  // 保留粘贴作为兜底而不是删掉：确实存在只吃粘贴不吃合成按键的控件，而且超长文本
+  // 逐字符合成有其代价。顺序按「哪个被实测证明覆盖面更广」排，不按猜测排。
+  // 正文本身不进结果文案，也不进审计记录。
+  let pasteUsed = false;
+  if (
+    resolvedInput.action === 'type' &&
+    resolvedInput.text &&
+    shouldUseClipboardPaste(resolvedInput.text)
+  ) {
+    const textToPaste = resolvedInput.text;
+
+    // 第一路：直接打字。验证判失败（确定性的「屏幕没动」）才继续往下走兜底。
+    const typedResponse = await computerUseService.executeVerifiedAction(
+      run,
+      { action: 'type', text: textToPaste } as Omit<
+        ComputerUseRequest,
+        'protocolVersion' | 'requestId' | 'context'
+      >,
+      signal,
+    );
+    // ⚠️ 判断成败之前，先问「守护进程是不是已经用确定性路径做成了」。
+    //
+    // ⛔ **`probe_change` 对剪贴板粘贴是错的仪器。** 它测的是
+    //    `settle_timeline` —— 动作**之后**一个窗口内的逐帧 churn，回答「画面还在不在动」。
+    //    逐字打字有持续重绘所以适用；**粘贴是瞬间完成的**，采样开始时重绘早已结束，
+    //    于是恒测出 0.0000 并断言「这次操作很可能根本没有落到界面上」。
+    //    这和 `computerUseService.ts` 里把 `click` 排除在 PROBE_CHANGE_ACTIONS 之外
+    //    是同一个理由、同一个坑。
+    //
+    //    实测代价：微信搜索框里「王磊」已经**成功输入并弹出了联系人列表**，回执却说
+    //    变化率 0.0000；模型据此判定输入失败，只试一次就整个任务放弃 ——
+    //    用户看到的是「点中了输入框就是不输入，干着急」。
+    //
+    // 守护进程报告的路径是权威证据（它自己知道走了哪条路、每步都有真实返回值），
+    // 优先于一个已知不适用的屏幕判据。
+    const typedAction = (
+      typedResponse.data as
+        | { action?: { summary?: unknown; inputPath?: unknown } }
+        | undefined
+    )?.action;
+    const typedSummary =
+      typeof typedAction?.summary === 'string' ? typedAction.summary : '';
+    // 结构化契约（protocol::TextInputPath），**不是**匹配 summary 里的中文。
+    // 第一版就是 `summary.includes('剪贴板')` —— Rust 那边改一个字，这里就静默
+    // 失效，而且没有任何编译期或测试期信号。人话给人看，判据走字段。
+    const daemonUsedClipboard = typedAction?.inputPath === 'clipboard';
+    // ⚠️ 这里**不能**再要求 `typedResponse.ok` —— 走剪贴板成功时它恰恰是 `false`，
+    //    因为 ok 被同一个不适用的 churn 判据拉下来了（实测：summary 明写
+    //    「已粘贴 2 个字符（剪贴板路径）；原剪贴板内容已还原」，ok 仍是 false）。
+    if (daemonUsedClipboard) {
+      const assembled = typedResponse.state
+        ? await buildObservationImages(
+            typedResponse.state,
+            typedResponse.actionMarker,
+          )
+        : undefined;
+      return {
+        ok: true,
+        content: `已输入 ${textToPaste.length} 个字符。${typedSummary}`,
+        ...(assembled?.images.length
+          ? { visionImages: assembled.images, visionNote: assembled.note }
+          : {}),
+      };
+    }
+    if (typedResponse.ok && typedResponse.verification?.status !== 'failed') {
+      const assembled = typedResponse.state
+        ? await buildObservationImages(
+            typedResponse.state,
+            typedResponse.actionMarker,
+          )
+        : undefined;
+      // ⚠️ **只有验证真的通过时才敢说「已输入」。**
+      //
+      // `verification.status` 有三态，而这个分支收的是 `!== 'failed'` —— 也就是
+      // `inconclusive` 也走这里。以前它和 passed 说同一句「已直接输入 N 个字符」，
+      // 于是「没验出来」被讲成了「做成了」。模型据此往下走，下一步看截图发现输入框
+      // 是空的，只能重新点、重新打；实测一次任务因此多跑 5 轮 click→type，
+      // 每轮都是一次完整的 LLM 往返（含截图），约占总耗时三分之一。
+      //
+      // 措辞要能让模型直接决定下一步：确认了就往下走，没确认就先核对。
+      const verified = typedResponse.verification?.status === 'passed';
+      return {
+        ok: true,
+        content: verified
+          ? `已输入 ${textToPaste.length} 个字符（已确认落到界面上）。`
+          : `已发出 ${textToPaste.length} 个字符的输入，但**未能确认**它真的进了目标控件`
+            + `（${typedResponse.verification?.reason ?? '缺少目标区域的变化证据'}）。\n`
+            + `请对照下面的最新截图确认内容是否已经出现：出现了就继续；没出现就重新定位`
+            + `输入框，不要按「已经输入过」继续往下走。`,
+        ...(assembled?.images.length
+          ? { visionImages: assembled.images, visionNote: assembled.note }
+          : {}),
+      };
+    }
+
+    // ⛔ **不再有「TS 层剪贴板兜底」这条路。**
+    //
+    // 它原本是为了救「中文输不进去」，但真实成因不在这里，而且它自己会造成更坏的后果：
+    //
+    // ① 真实成因有两条，都已在守护进程侧确定性解决：
+    //    · 输入法激活时合成按键到不了控件 → `macos.rs::input_method_is_active` 直接改走剪贴板
+    //    · `pbcopy` 无 locale 时丢掉全部非 ASCII → `clipboard_write_text` 显式带 `LC_CTYPE=UTF-8`
+    //    （还有第三条：修饰键卡在按下状态让每个字符变成快捷键，见 `post_key`）
+    //
+    // ② 这条兜底的触发判据是**屏幕变化率**，而它在这个场景里恰恰最不可信：
+    //    搜索框里多两个字，在全屏差分上远低于阈值 → 判 `failed` → 再粘一遍。
+    //    实测微信搜索框出现 **「王磊王磊」**：直接输入本来就成功了，兜底又补了一次。
+    //    静默重复输入比失败更糟 —— 它看起来成功，然后搜不到人，而且没人知道为什么。
+    //
+    // 现在的契约：输入走哪条路由守护进程按**输入源**确定性决定，只走一次；
+    // 验证测不出来就在回执里如实说「未能确认」并附截图，让模型自己看，不替它猜。
+    const unverified = typedResponse.state
+      ? await buildObservationImages(
+          typedResponse.state,
+          typedResponse.actionMarker,
+        )
+      : undefined;
+    return {
+      ok: true as const,
+      content:
+        `已发出 ${textToPaste.length} 个字符的输入，但**未能确认**它真的进了目标控件`
+        + `（${typedResponse.verification?.reason ?? '缺少目标区域的变化证据'}）。\n`
+        + `请对照下面的最新截图确认内容是否已经出现：出现了就继续；没出现就先 click`
+        + `聚焦输入框再 type，不要直接重复调用 type —— 重复会把文字输入两遍。`,
+      ...(unverified?.images.length
+        ? { visionImages: unverified.images, visionNote: unverified.note }
+        : {}),
+    };
+  }
+
+  const observationFrames =
+    input.action === 'observe'
+      ? await configService
+          .computerUse()
+          .then((config) =>
+            resolveObservationFrames(input.frames, config.observationFrames),
+          )
+      : undefined;
+  const requestInput = {
+    ...resolvedInput,
+    // `actionClass` 只服务本进程的授权判定，守护进程不认识它 ——
+    // 置 undefined 让它在序列化时消失，别往线路协议里塞私货字段。
+    actionClass: undefined,
+    // 观测默认带帧序列。模型显式要 1 帧时尊重它（只想看当前状态、省 token）。
+    ...(input.action === 'observe' ? { frames: observationFrames! } : {}),
+    ...(authorizedFilePaths ? { filePaths: authorizedFilePaths } : {}),
+  } as Omit<ComputerUseRequest, 'protocolVersion' | 'requestId' | 'context'>;
+  let response = isMutatingComputerUseAction(requestInput.action)
+    ? await computerUseService.executeVerifiedAction(run, requestInput, signal)
+    : await computerUseService.request(run, requestInput, signal);
+
+  // ===== repeat：一轮往返内把同一动作连做 N 次（见 inputSchema.repeat 的注释）=====
+  //
+  // 只有第一次已经成功才继续 —— 首次就失败时重复毫无意义，而且会把一个错误动作
+  // 连做 8 遍。到边界（目标区域不再变化）立刻停，剩下的次数不做。
+  const repeatTimes = REPEATABLE_ACTIONS.has(input.action)
+    ? Math.min(input.repeat ?? 1, MAX_REPEAT)
+    : 1;
+  let repeatDone = 1;
+  let repeatStoppedAtEdge = false;
+  /** 一次都没测出 ROI —— 到底有没有到边界，我们不知道，回执里要说。 */
+  let repeatEdgeUnknown = false;
+  /** 连续多少次目标区域没动。单次可能只是动画没稳，两次才算到底。 */
+  let stillStreak = 0;
+  const repeatFrames: ImageInputSpec[] = [];
+  /**
+   * 把「连做 N 次」抽成一份：**正常路径与焦点恢复之后都要用它**。
+   *
+   * ⚠️ 恢复路径此前直接 `return`，剩余次数被静默丢弃 —— 实测事故：
+   *    模型请求 `repeat:8`，第一次按键撞上前台被别的窗口抢走，于是
+   *    `if (repeatTimes > 1 && response.ok)` 判假、整个批量循环被跳过；
+   *    错误路径里 `recoverLostFocus` 重新激活并**只重试一次**就早返回。
+   *    净效果是 8 次变 1 次，而回执里一个字都没提（那句「repeat：已连续执行 M/N 次」
+   *    在下面的正常返回路径上，早返回够不到它）。
+   *    在 seek 循环里这能自愈（下一轮重读页码），但在「翻 20 条聊天记录」这类遍历里
+   *    表现是**静默少读** —— 看起来像「内容只有这么多」，一个像事实的错误结论。
+   *
+   * 从 `fromRound` 开始跑到 `repeatTimes`，就地更新外层的
+   * `response / repeatDone / repeatStoppedAtEdge / repeatEdgeUnknown / repeatFrames`。
+   */
+  const runRepeatRounds = async (fromRound: number): Promise<void> => {
+    for (let round = fromRound; round <= repeatTimes; round += 1) {
+      if (signal?.aborted) break;
+      // 连续两次「目标区域没动」= 到头了。继续按只是白费往返，
+      // 而且会让模型误以为自己还在前进。
+      // 只判一次容易被动画未稳误伤（第一下正在渲染，ROI 恰好没变）。
+      const edge = isAtScrollEdge(response);
+      if (edge === 'unknown') repeatEdgeUnknown = true;
+      stillStreak = edge === 'at-edge' ? stillStreak + 1 : 0;
+      if (stillStreak >= EDGE_CONFIRM_ROUNDS) {
+        repeatStoppedAtEdge = true;
+        break;
+      }
+      const next = isMutatingComputerUseAction(requestInput.action)
+        ? await computerUseService.executeVerifiedAction(run, requestInput, signal)
+        : await computerUseService.request(run, requestInput, signal);
+      if (!next.ok) break; // 半路失败：保留已采到的内容，按已完成次数如实汇报
+      // 每一次的画面都要留下来 —— 遍历类任务要读的正是中间过程，
+      // 只给最后一张等于只给终点，中间翻过的内容全丢。
+      //
+      // ⚠️ 但「快速翻到第 N 页」不是遍历：中间那些页没有阅读价值，而 repeat:8
+      //    会一次回 8 张全屏图（约 1 万 token）。所以给调用方一个开关，
+      //    默认仍是 all（遍历是 repeat 的主要用途，不能因为定位场景改默认值）。
+      if (next.state && input.repeatFrames !== 'last') {
+        const shot = await buildObservationImages(next.state, next.actionMarker);
+        if (shot?.images.length) repeatFrames.push(...shot.images);
+      }
+      response = next;
+      repeatDone = round;
+    }
+    if (!repeatStoppedAtEdge) {
+      const edge = isAtScrollEdge(response);
+      if (edge === 'unknown') repeatEdgeUnknown = true;
+      else if (edge === 'at-edge' && stillStreak + 1 >= EDGE_CONFIRM_ROUNDS) {
+        repeatStoppedAtEdge = true;
+      }
+    }
+  };
+  if (repeatTimes > 1 && response.ok) await runRepeatRounds(2);
+
+  /** 焦点被抢后自动恢复了 —— 这句要并进回执，让模型知道中间出过岔子。 */
+  let focusRecoveryNote: string | null = null;
+
+  // ⚠️ 带标签是为了让**焦点恢复成功**这一支能跳出整个错误处理块、汇回主流程，
+  //    而不是像以前那样自己拼一个 ToolResult 早返回。汇回来才拿得到：
+  //    补跑剩余 repeat 次数、「repeat：M/N 次」文本、extra 诊断、movedRatio、图片组装。
+  errorHandling: if (!response.ok) {
+    const errorCode = response.error?.code ?? 'failed';
+    const failure = `${errorCode}: ${response.error?.message ?? 'Computer Use 操作失败'}`;
+    const hint = response.error?.hint ? `\n${response.error.hint}` : '';
+
+    const focusLost =
+      errorCode === 'target_not_found' &&
+      response.error?.details?.reason === 'target_focus_lost';
+    if (errorCode === 'human_input_detected' || focusLost) {
+      if (!context.computerIntervention) {
+        // ⚠️ **无人接管 ≠ 只能放弃。**
+        //
+        // 这条闸门是为有人值守的桌面端设计的：焦点被抢 → 暂停 → 等人处理。但 `-p`
+        // 模式下根本没有人，于是它退化成「直接终止整个任务」。实测代价：两次读取任务的
+        // **全部失败**都出自这里（cu-read2 9 步里 3 次、cu-read3 5 步里 2 次）。
+        //
+        // 而焦点丢失的恢复动作极其简单 —— 重新激活目标应用即可，模型在别的运行里
+        // 正是这么自己救回来的。与其让它多烧一轮往返去做同一件事，不如就地做掉。
+        //
+        // 只对**焦点丢失**自恢复：`human_input_detected` 是真人正在动鼠标键盘，
+        // 那种情况下抢回前台是在和用户打架，必须让路。
+        const recovery = focusLost
+          ? await recoverLostFocus(run, requestInput, signal)
+          : null;
+        if (recovery) {
+          response = recovery.response;
+          focusRecoveryNote = recovery.note;
+          // 恢复只重试了**这一次**动作。批量的剩余次数必须在这里补完 ——
+          // 不补的话 repeat:8 就静默变成 1 次（见 runRepeatRounds 头注的实测事故）。
+          if (repeatTimes > 1) await runRepeatRounds(repeatDone + 1);
+          break errorHandling;
+        }
+        return {
+          ok: false,
+          error: `human_intervention_required: ${focusLost ? '目标应用已失去焦点，且自动重新激活未成功' : '检测到用户正在操作电脑'}。当前宿主没有可用的人工接管通道，任务已停止。`,
+        };
+      }
+      const resumed = await context.computerIntervention.pause(
+        'manual',
+        focusLost
+          ? '目标应用已失去焦点，AI 已暂停电脑操作'
+          : '检测到你正在使用鼠标或键盘，AI 已暂停电脑操作',
+        signal,
+      );
+      if (resumed.resolution !== 'resumed' || !resumed.state) {
+        return {
+          ok: false,
+          error: 'human_intervention_required: 用户已结束本次电脑操作任务。',
+        };
+      }
+      const refreshed = await buildObservationImages(resumed.state);
+      return {
+        ok: true,
+        content:
+          '用户已完成接管，旧动作已取消。下面是重新观察后的界面；请重新定位并决定下一步，不能假设旧动作已经完成。',
+        ...(refreshed?.images.length
+          ? { visionImages: refreshed.images, visionNote: refreshed.note }
+          : {}),
+      };
+    }
+
+    // permission_denied 特殊处理：自动打开对应权限的系统设置页面，并给出清晰引导
+    if (errorCode === 'permission_denied') {
+      const errMsg = response.error?.message ?? '';
+      const errHint = response.error?.hint ?? '';
+      // 通过错误消息区分是屏幕录制权限还是辅助功能权限
+      // Rust 侧消息: "Screen Recording permission" / "Accessibility permission"
+      // 以及 screencapture 命令失败的各种提示
+      const isScreenCapture =
+        /Screen Recording|screen.?capture|屏幕录制|screencapture/i.test(
+          errMsg,
+        ) || /Screen Recording/i.test(errHint);
+
+      // 打开对应的系统设置页面
+      if (isScreenCapture) {
+        openScreenCaptureSettings();
+      } else {
+        openAccessibilitySettings();
+      }
+
+      // 生成引导信息
+      const targetName = getPermissionTargetName();
+      const inAppBundle = isRunningInAppBundle();
+      const permType = isScreenCapture ? '屏幕录制' : '辅助功能';
+      const settingsPath = isScreenCapture
+        ? '隐私与安全性 → 屏幕录制'
+        : '隐私与安全性 → 辅助功能';
+
+      let guidance: string;
+      if (inAppBundle) {
+        // 生产模式：在 .app 内运行，告诉用户找 KakadeAI
+        guidance = [
+          '',
+          `【${permType}权限未授权 - 已为你打开系统设置】`,
+          `请在系统设置 → ${settingsPath} 中，找到并勾选「${targetName}」。`,
+          '勾选后回来告诉我「已授权」即可继续操作。',
+          '',
+          `提示：如果在列表中没看到 ${targetName}，可以先尝试执行一个操作（如点击），`,
+          '系统会自动弹出授权请求对话框。',
+        ].join('\n');
+      } else {
+        // 开发模式：告诉用户这是正常的，以及怎么授权 cu-helperd
+        guidance = [
+          '',
+          `【${permType}权限未授权 - 已为你打开系统设置】`,
+          '当前是开发模式（bun run dev），cu-helperd 作为独立进程运行，',
+          `没有 .app 包裹，所以权限弹窗会显示 "cu-helperd" 而不是 "KakadeAI"。`,
+          '这是正常现象——打包成 .app 安装后弹窗会正确显示 KakadeAI。',
+          '',
+          `请在系统设置 → ${settingsPath} 中：`,
+          '  1. 点击左下角锁图标解锁',
+          `  2. 点击 "+" 号添加 cu-helperd（位于 computer-use-native/target/release/ 下）`,
+          `     或者直接勾选列表中已出现的 "cu-helperd"`,
+          '  3. 确保它前面的开关是打开的',
+          '',
+          '授权一次后权限会保留（直到重新编译 cu-helperd）。',
+        ].join('\n');
+      }
+
+      const salvagedPerm = response.state
+        ? await buildObservationImages(response.state, response.actionMarker)
+        : null;
+      return {
+        ok: false,
+        error: `❌ ${failure}${hint}${guidance}`,
+        ...(salvagedPerm?.images.length
+          ? { visionImages: salvagedPerm.images, visionNote: salvagedPerm.note }
+          : {}),
+      };
+    }
+    // verification_failed 特殊引导：动作已执行但未达到预期效果（点偏了/没点中/界面没变化），
+    // 给出的截图里包含最新界面状态，引导模型重新定位
+    if (errorCode === 'verification_failed' && response.state) {
+      const salvagedVf = await buildObservationImages(
+        response.state,
+        response.actionMarker,
+      );
+      const guidance =
+        resolvedInput.x !== undefined && resolvedInput.y !== undefined
+          ? ` 提示：上一次点击坐标(${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)})可能偏了，请根据截图仔细观察界面实际状态，重新定位目标后再操作，不要重复上一次的坐标。`
+          : '';
+      return {
+        ok: false,
+        error: `❌ ${failure}${hint}${guidance}\n\n下面是动作后的最新截图，请仔细观察界面实际状态，重新定位目标后再操作，不要重复上一次的坐标。`,
+        ...(salvagedVf?.images.length
+          ? { visionImages: salvagedVf.images, visionNote: salvagedVf.note }
+          : {}),
+      };
+    }
+    const salvaged = response.state
+      ? await buildObservationImages(response.state, response.actionMarker)
+      : null;
+    return {
+      ok: false,
+      error: `❌ ${failure}${hint}`,
+      ...(salvaged?.images.length
+        ? { visionImages: salvaged.images, visionNote: salvaged.note }
+        : {}),
+    };
+  }
+
+  if (response.state) {
+    // 跨进程打断：前台被别的进程（或用户自己）抢走了。
+    //
+    // 这条判据的价值在于**它不依赖目标应用配合** —— 前台窗口归 OS 管，
+    // 微信可以拒绝暴露控件树，它拒绝不了「我这个窗口还是不是前台」。
+    // 于是自绘/Electron 应用上其它判据全瞎时，这一条依然成立（focus.ts 头注 ①）。
+    // 继续按旧观测的坐标点下去，就是在别人刚切过来的窗口上闭眼操作。
+    const boundary =
+      response.focusChange === FOCUS_CHANGE.OTHER_PROCESS
+        ? {
+            reason: 'blocked' as const,
+            summary: `前台应用已变成「${response.state.activeApp?.name ?? '未知应用'}」（可能是你自己切了窗口，或别的程序抢了前台）：${recommendedAction(response.focusChange).advice}`,
+            confidence: 'ax' as const,
+          }
+        : detectComputerHumanBoundary(
+            response.state,
+            await manualForState(response.state),
+          );
+    const handled = await handleHumanBoundary(
+      boundary,
+      response.state,
+      context,
+      signal,
+    );
+    if (handled.refusal) return handled.refusal;
+    if (handled.state) response = { ...response, state: handled.state };
+    if (response.focus) extra.focusLevel = response.focus.level;
+    if (response.focusChange) extra.focusChange = response.focusChange;
+  } else {
+    // 动作返回的是 ActionResult 而不是 Observation，所以上面那条基于 AX 的
+    // 判据在动作之后根本跑不到 —— 而「输入到一半界面突然变了」恰好只发生
+    // 在动作之后。这条像素兜底就是为这个缺口存在的。
+    //
+    // 变化率来自守护进程（`probeChange`，仅在「输入动作 + 上次观测 AX 树
+    // 不可用」时才请求，见 computerUseService::shouldProbeChange）。判定用
+    // **上一次观测**的状态：那正是决定要不要探测的那次观测，天然配对。
+    const changeRatio = actionChangeRatio(response.data, 'changeRatio');
+    if (changeRatio !== undefined) {
+      extra.changeRatio = changeRatio;
+      const observed = computerUseService.observationAtAction(run);
+      if (observed) {
+        const regionChangeRatio = actionChangeRatio(
+          response.data,
+          'regionChangeRatio',
+        );
+        if (regionChangeRatio !== undefined)
+          extra.regionChangeRatio = regionChangeRatio;
+        const evidence = {
+          // `typing` 如实反映这次是不是文本输入 —— 曾经无条件传 true，
+          // 于是所有被探测的动作都按「正在打字」判，把判据的前提架空了。
+          typing: input.action === 'type',
+          changeRatio,
+          ...(regionChangeRatio !== undefined ? { regionChangeRatio } : {}),
+          ...(focusAreaRatio(observed) !== undefined
+            ? { focusAreaRatio: focusAreaRatio(observed)! }
+            : {}),
+        };
+        const verdict = classifyPixelChange(observed, evidence);
+        if (verdict === 'suspicious') {
+          const boundary = detectPixelHumanBoundary(observed, evidence);
+          if (boundary) {
+            const handled = await handleHumanBoundary(
+              boundary,
+              observed,
+              context,
+              signal,
+            );
+            if (handled.refusal) return handled.refusal;
+          }
+        } else if (verdict === 'no-effect') {
+          // 不是安全问题，但把它当「一切正常」会让模型接着往下打，越走越偏。
+          extra.pixelVerdict = 'no-effect';
+          return {
+            ok: true,
+            content:
+              '动作已发出，但屏幕上（含焦点控件内）没有任何像素变化 ——' +
+              '这次输入很可能没有落到目标控件上（焦点丢了、或应用没响应）。' +
+              '先 observe 确认焦点在哪，再决定要不要重来，别接着往下输入。',
+          };
+        }
+      }
+    }
+  }
+  // replay 返回的是裸灰度帧，必须在这里解码成少量图。
+  //
+  // 不接这条路会把守护进程的 base64 原样塞进 content —— 30 帧 480×270 灰度
+  // 约 520 万字符（≈130 万 token），一次调用就把上下文炸穿。
+  if (input.action === 'replay') {
+    const replay = await buildReplayImages(extractReplayFrames(response.data));
+    if (!replay) {
+      return {
+        ok: true,
+        content: '回放缓冲里还没有可用的帧（采样器可能刚启动）。',
+      };
+    }
+    return {
+      ok: true,
+      content: replay.summary.join('\n'),
+      visionImages: replay.images,
+      visionNote: replay.note,
+    };
+  }
+
+  // settle 的像素时间线由原生侧算（0.24ms/帧，跨 IPC 传像素反而更贵），
+  // 但**分级留在这里** —— confidence、焦点三分类、给模型看的话术都是策略，
+  // 不是算术。两边各管一半，谁都不重复实现。
+  if (input.action === 'settle') {
+    return { ok: true, content: describeSettle(response.data) };
+  }
+
+  if (!response.state) {
+    return {
+      ok: true,
+      content:
+        response.content ?? JSON.stringify(response.data ?? { ok: true }),
+    };
+  }
+
+  // A mutating response reaches this branch only after the native transaction
+  // returned a fresh observation. A busy remote desktop can leave settle
+  // inconclusive even when the atomic action was applied, so never call that
+  // state "verified" in the model-visible feedback.
+  const actionFeedback: string[] = [];
+  // 焦点被抢并自动恢复过 —— 排在最前面说，因为它解释了后面所有数字为什么可能异常
+  // （比如 repeat 的实际次数少于请求次数）。
+  if (focusRecoveryNote) actionFeedback.push(focusRecoveryNote);
+  // ⚠️ **有确定性证据时就说确认，别让屏幕判据把它拉下来。**
+  //
+  // `activate_app` 的目标是「让这个 app 到前台」，而观测里的 `activeApp.id`
+  // 就是这件事的**直接证据** —— 与画面动没动无关。可窗口切换本来就带动画，
+  // settle 判据几乎必然是 inconclusive，于是回执长期是
+  // 「已执行（稳定性尚未确认）· 画面稳定度：仍在变化中」。
+  //
+  // 实测代价（真机 trace）：模型据此认为没成功，**紧接着又调了一次
+  // activate_app** —— 一整轮 LLM 往返 30.2s 全部作废，占那次任务总耗时的 22%。
+  // 与 type 走剪贴板那次是同一类错误：一个不适用的判据盖过了确定性事实。
+  const activationConfirmed =
+    resolvedInput.action === 'activate_app'
+    && resolvedInput.appId !== undefined
+    && response.state.activeApp?.id === resolvedInput.appId;
+  const actionOutcome =
+    response.verification?.status === 'passed' || activationConfirmed
+      ? '已核验'
+      : '已执行（稳定性尚未确认）';
+  // ⚠️ **顺带挪了窗口就必须说。**
+  //
+  // `activate_app` 会在窗口越出可用区（被 Dock/菜单栏压住、或伸到屏外）时自动摆正。
+  // 那是对用户环境的真实副作用，而且**模型手里上一轮观测得到的坐标会全部失效** ——
+  // 不说等于让它闭眼点旧坐标。读结构化字段，不嗅探 summary 文案（见 TextInputPath）。
+  const repositioned = (
+    response.data as { action?: { windowRepositioned?: unknown } } | undefined
+  )?.action?.windowRepositioned;
+  if (isRecord(repositioned)) {
+    const { x, y, width, height } = repositioned as Record<string, number>;
+    actionFeedback.push(
+      `🪟 该窗口原先超出可用区（被 Dock/菜单栏压住或伸到屏外），已自动摆正到 `
+      + `(${Math.round(x)}, ${Math.round(y)}) ${Math.round(width)}×${Math.round(height)} 逻辑像素。`
+      + `**之前观测得到的坐标已经全部失效**，请按下面这张最新截图重新定位。`,
+    );
+  }
+
+  const activeAppName =
+    response.state.activeApp?.name ??
+    response.state.activeApp?.id ??
+    '未知应用';
+
+  // 点击类动作反馈
+  if (
+    ['click', 'double_click', 'right_click', 'middle_click', 'hover'].includes(
+      resolvedInput.action,
+    )
+  ) {
+    if (resolvedInput.x !== undefined && resolvedInput.y !== undefined) {
+      const snapResult = computerUseService.consumeLastSnapResult(run);
+      if (resolvedInput.action === 'hover') {
+        // hover 动作：突出显示悬停位置，供模型确认坐标后再点击
+        if (snapResult?.snapped && snapResult.element) {
+          const el = snapResult.element;
+          const elName = el.label ? `「${el.label}」` : '';
+          actionFeedback.push(
+            `🖱️ 鼠标已悬停在 ${el.role} ${elName}（实际坐标 (${Math.round(snapResult.x)}, ${Math.round(snapResult.y)})）`,
+          );
+          actionFeedback.push(
+            `📍 原始目标坐标 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)})，AX吸附偏移约 ${Math.round(snapResult.distancePx ?? 0)} 像素`,
+          );
+          actionFeedback.push(
+            '👉 如果这是你想点的位置，下一步直接 click 相同坐标即可（AX吸附会保证精准）。',
+          );
+        } else {
+          actionFeedback.push(
+            `🖱️ 鼠标已悬停在坐标 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)})`,
+          );
+          actionFeedback.push(
+            '⚠️ 附近 28 像素内未检测到可交互控件，请确认这是正确位置。如果是输入框/文本区域等不可AX识别的控件也可以直接点击。',
+          );
+        }
+      } else {
+        if (snapResult?.snapped && snapResult.element) {
+          const el = snapResult.element;
+          const elName = el.label ? `「${el.label}」` : '';
+          actionFeedback.push(
+            `${resolvedInput.action} ${actionOutcome}：在「${activeAppName}」中操作坐标 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)})`,
+          );
+          actionFeedback.push(
+            `🎯 AX吸附：已自动吸附到 ${el.role} ${elName}（偏移约${Math.round(snapResult.distancePx ?? 0)}像素，实际点击坐标 (${Math.round(snapResult.x)}, ${Math.round(snapResult.y)})）`,
+          );
+        } else {
+          actionFeedback.push(
+            `${resolvedInput.action} ${actionOutcome}：在「${activeAppName}」中操作坐标 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)})`,
+          );
+        }
+      }
+    }
+  }
+  // 拖拽动作反馈
+  else if (resolvedInput.action === 'drag') {
+    if (
+      resolvedInput.x !== undefined &&
+      resolvedInput.y !== undefined &&
+      resolvedInput.toX !== undefined &&
+      resolvedInput.toY !== undefined
+    ) {
+      actionFeedback.push(
+        `drag ${actionOutcome}：从 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)}) 拖到 (${Math.round(resolvedInput.toX)}, ${Math.round(resolvedInput.toY)})`,
+      );
+    }
+  }
+  // 滚动动作反馈
+  else if (resolvedInput.action === 'scroll') {
+    const direction = resolvedInput.direction ?? 'unknown';
+    if (resolvedInput.x !== undefined && resolvedInput.y !== undefined) {
+      actionFeedback.push(
+        `scroll ${actionOutcome}：在 (${Math.round(resolvedInput.x)}, ${Math.round(resolvedInput.y)}) 位置向「${direction}」滚动`,
+      );
+    } else {
+      actionFeedback.push(`scroll ${actionOutcome}：向「${direction}」滚动`);
+      actionFeedback.push(
+        '⚠️ scroll 未指定 x/y 坐标，滚轮作用在当前鼠标位置（可能不在目标窗口内）。下次请提供要滚动的区域坐标。',
+      );
+    }
+  }
+  // 输入动作反馈
+  else if (resolvedInput.action === 'type' && resolvedInput.text) {
+    actionFeedback.push(
+      `type ${actionOutcome}：向「${activeAppName}」输入了 ${resolvedInput.text.length} 个字符`,
+    );
+  }
+  // 按键动作反馈
+  else if (resolvedInput.action === 'key' && resolvedInput.key) {
+    actionFeedback.push(
+      `key ${actionOutcome}：按下按键「${resolvedInput.key}」`,
+    );
+  }
+  // 应用激活反馈
+  else if (resolvedInput.action === 'activate_app' && resolvedInput.appId) {
+    actionFeedback.push(
+      `activate_app ${actionOutcome}：前台应用为 ${resolvedInput.appId}`,
+    );
+  }
+  // 剪贴板写入反馈
+  else if (resolvedInput.action === 'clipboard_write' && resolvedInput.text) {
+    actionFeedback.push(
+      `clipboard_write ${actionOutcome}：写入了 ${resolvedInput.text.length} 个字符到剪贴板`,
+    );
+  }
+
+  // ★ 窗口边界坐标转换 + 越界警告（参考 UI-TARS 闭环设计）：
+  // 把逻辑像素窗口边界转换成 0-1000 相对坐标，模型可直接使用无需心算；
+  // 同时检测点击坐标是否落在前台窗口范围内，不在则发出警告。
+  const stateForRect = response.state;
+  const primaryDisplay =
+    stateForRect?.displays?.find((d) => d.primary) ??
+    stateForRect?.displays?.[0];
+  const screenW = primaryDisplay?.logicalBounds?.width ?? 0;
+  const screenH = primaryDisplay?.logicalBounds?.height ?? 0;
+  const activeAppId = stateForRect?.activeApp?.id;
+
+  // 检测点击坐标是否落在前台窗口外（仅对有坐标的点击/滚动类动作）
+  const isClickWithPoint =
+    ['click', 'double_click', 'right_click', 'middle_click', 'scroll'].includes(
+      resolvedInput.action,
+    ) &&
+    resolvedInput.x !== undefined &&
+    resolvedInput.y !== undefined;
+  const frontWindow = pickFrontWindow(stateForRect?.windows, activeAppId);
+  if (
+    isClickWithPoint &&
+    frontWindow &&
+    primaryDisplay &&
+    screenW > 0 &&
+    screenH > 0
+  ) {
+    const clickRx = resolvedInput.x as number; // 0-1000 相对坐标
+    const clickRy = resolvedInput.y as number;
+    // 前台窗口边界（逻辑像素 → 0-1000 相对坐标）
+    const winRatio = windowBoundsToRatio(frontWindow.bounds, primaryDisplay);
+    const winRxLeft = Math.round(winRatio.left);
+    const winRyTop = Math.round(winRatio.top);
+    const winRxRight = Math.round(winRatio.right);
+    const winRyBottom = Math.round(winRatio.bottom);
+    // 判断是否在窗口内（留一点容差）
+    const margin = 5; // 0-1000 相对坐标容差
+    const inWindow =
+      clickRx >= winRxLeft - margin &&
+      clickRx <= winRxRight + margin &&
+      clickRy >= winRyTop - margin &&
+      clickRy <= winRyBottom + margin;
+    if (!inWindow) {
+      const actionName =
+        resolvedInput.action === 'scroll' ? '滚动坐标' : '点击坐标';
+      actionFeedback.push(
+        `⚠️ ${actionName} (${Math.round(clickRx)}, ${Math.round(clickRy)}) 不在当前前台应用「${activeAppId}」的窗口范围内（窗口相对边界 x:${winRxLeft}-${winRxRight}, y:${winRyTop}-${winRyBottom}），可能作用到了别的应用或桌面。请仔细核对截图中的位置。`,
+      );
+    }
+  }
+
+  // 组装图与文本摘要。
+  //
+  // `detail` 不用 'low'：那是 WebBrowser 的设定，浏览器有 DOM 兜底、截图只是
+  // 核验；桌面这边截图是**唯一**信息通道，而 OpenAI 系的 'low' 固定
+  // 512×512 / 85tok，屏幕上的字根本读不出来。
+  const hasBeforeAfter =
+    isMutatingComputerUseAction(resolvedInput.action) &&
+    response.beforeState?.screenshot &&
+    response.state?.screenshot;
+
+  const beforeAssembled = hasBeforeAfter
+    ? await buildObservationImages(response.beforeState!)
+    : null;
+
+  // 放大镜只在 observe 上供货：它的成本是**额外一张图**，而写类动作本来就已经
+  // 附了「操作前+操作后」两张。三张图一起发既贵又容易让模型看串。
+  // 想读小字就单独 observe 一次带 magnify —— 那一步的语义本来就是「我要看清楚」。
+  const magnifyRect =
+    resolvedInput.action === 'observe'
+      ? _resolveMagnifyRect(
+          resolvedInput.magnify,
+          resolvedInput.magnifyAnchor,
+          stateForRect ?? computerUseService.lastObservation(run),
+        )
+      : undefined;
+  const assembled = stateForRect
+    ? await buildObservationImages(stateForRect, response.actionMarker, magnifyRect)
+    : null;
+  if (assembled?.axIdMap) {
+    computerUseService.updateAxIdMap(run, assembled.axIdMap);
+  }
+  const guidance = stateForRect
+    ? await describeAppGuidance(stateForRect, run)
+    : undefined;
+
+  const beforeFocus = response.beforeState
+    ? deriveFocusSnapshot(response.beforeState)
+    : null;
+  const afterFocus = response.focus ?? null;
+  const focusChangeText =
+    hasBeforeAfter && beforeFocus && afterFocus
+      ? describeFocusChange(beforeFocus, afterFocus)
+      : '';
+
+  const allImages = [
+    ...(beforeAssembled?.images ?? []),
+    // repeat 的中间帧按发生顺序插在中间：遍历类任务要读的**正是中间过程**，
+    // 只给首尾等于把翻过的内容全丢了。最后一张仍是 assembled（当前状态）。
+    ...repeatFrames,
+    ...(assembled?.images ?? []),
+  ];
+  const combinedNote = hasBeforeAfter
+    ? [
+        `以上 ${allImages.length} 张图按时间顺序排列：`,
+        '  第 1 张 = 操作前截图（动作发生前的界面）',
+        '  第 2 张 = 操作后截图（动作发生后的界面，红色十字是点击位置）',
+        '',
+        '判断操作效果时，直接对比两张图的差异，不要只看一张图凭记忆猜。',
+        '',
+        ...(assembled?.note ? [assembled.note] : []),
+      ].join('\n')
+    : (assembled?.note ?? '');
+
+  // 屏幕变化检测（比"稳态"更能反映操作是否真的生效）
+  //
+  // ⚠️ **优先看目标区域（ROI），全屏只作回落。** 这里以前只读全屏 `changeRatio`，
+  // 于是在微信这类界面上永远走「✅ 界面有变化」那一支 —— 它的会话列表、未读角标、
+  // 时间戳几乎一直在动，全屏变化率恒超 1%。后果是下面那条「滚动没生效，改用 PageUp」
+  // 的建议**从来没有触发过**：实测一次读聊天记录的任务里连滚 8 次、聊天区一行没动，
+  // 模型每次都收到「操作似乎生效了」，最后只好自己去拖那条隐藏的细滚动条 ——
+  // 拖偏就是在聊天区框选文本，属于危险误操作。
+  //
+  // ⚠️⚠️ **`movedRatio` 必须排在两个 settle 通道之前** —— 它们回答的不是同一个问题：
+  //   · movedRatio          = 动作前抓的基线 vs 动作后的画面 → 「内容变了没有」★这才是问题本身
+  //   · regionChange/change = settle 期间的帧间抖动         → 「画面还在不在动」
+  // 翻页/切页这类**瞬时**变化，动画在测量时早已停住 → settle 恒为 0.0。
+  // 之前这里只读 settle，于是每按一次方向键，模型都收到
+  // 「⚠️ 操作后界面变化很小（变化率 0.0%），请仔细核对是否达到预期效果」。
+  // 那**不是缺证据，是一条错误的否定证据**：实测同一时刻书从 15/106 翻到了 21/106，
+  // 按键一直是好使的。模型据此反复怀疑、重试、最后跑去乱点碰运气 —— 全是这句话害的。
+  // （同一个坑在 isAtScrollEdge 上修过一次，漏了模型真正读的这条消息。）
+  const movedRatio = actionChangeRatio(response.data, 'movedRatio');
+  const roiRatio = actionChangeRatio(response.data, 'regionChangeRatio');
+  const fullRatio = actionChangeRatio(response.data, 'changeRatio');
+  const changeRatio = movedRatio ?? roiRatio ?? fullRatio;
+  const ratioScope =
+    movedRatio !== undefined
+      ? '画面前后对比'
+      : roiRatio !== undefined
+        ? '目标区域'
+        : '全屏';
+  let changeWarning: string | null = null;
+  if (changeRatio !== undefined) {
+    const changePercent = (changeRatio * 100).toFixed(1);
+    if (changeRatio > 0.01) {
+      changeWarning = `✅ ${ratioScope}有变化（变化率约 ${changePercent}%），操作似乎生效了`;
+    } else {
+      if (resolvedInput.action === 'scroll') {
+        changeWarning = `⚠️ 滚动后${ratioScope}几乎没变化（变化率 ${changePercent}%）——这一路没生效。\n`
+          + `请改用「点一下内容区中心 → key: pageup / pagedown」翻页，键盘事件走焦点控件，不依赖鼠标位置。\n`
+          + `⛔ 不要加大滚动距离重试，也**绝对不要用 drag 去拖滚动条**：滚动条通常是隐藏的细条，`
+          + `拖偏就落到内容区上，在聊天/文档里那是框选文本，不是滚动。`;
+      } else if (
+        ['click', 'double_click', 'right_click', 'middle_click'].includes(
+          resolvedInput.action,
+        )
+      ) {
+        changeWarning = `⚠️ 点击后界面无变化（变化率 ${changePercent}%），可能点在了空白区域或未点中目标。请根据截图仔细观察界面实际状态，重新定位后再操作。`;
+      } else {
+        changeWarning = `⚠️ 操作后界面变化很小（变化率 ${changePercent}%），请仔细核对是否达到预期效果。`;
+      }
+    }
+  }
+
+  const lines = [
+    ...(response.focus ? [`★ ${describeFocus(response.focus)}`] : []),
+    ...(focusChangeText ? [`📊 ${focusChangeText}`] : []),
+    ...(textTargetNotice ? [textTargetNotice] : []),
+    ...actionFeedback,
+    ...(changeWarning ? [changeWarning] : []),
+    ...(response.settle
+      ? [
+          `画面稳定度：${response.settle.settled ? '已稳定' : '仍在变化中'}${response.settle.reason ? ` · ${response.settle.reason}` : ''}`,
+        ]
+      : []),
+    ...(hasBeforeAfter
+      ? ['🖼️ 已附上操作前+操作后两张截图，直接对比判断效果。']
+      : []),
+    ...(assembled?.summary ?? []),
+    ...(stateForRect?.windows?.length &&
+    primaryDisplay &&
+    screenW > 0 &&
+    screenH > 0
+      ? [
+          '窗口列表（所有可见窗口，坐标为「(逻辑像素) [0-1000相对坐标]」，★=当前前台窗口）：' +
+            stateForRect.windows
+              .filter((w) => !w.minimized)
+              .slice(0, 10)
+              .map((w) => {
+                const b = w.bounds;
+                const label = w.title
+                  ? `「${w.title}」`
+                  : `[${w.id.split(':').pop() ?? '?'}]`;
+                const r = windowBoundsToRatio(b, primaryDisplay);
+                const rx1 = Math.round(r.left);
+                const ry1 = Math.round(r.top);
+                const rx2 = Math.round(r.right);
+                const ry2 = Math.round(r.bottom);
+                const isFront = w.appId === activeAppId;
+                return `${isFront ? '★' : ''}${label}(${b.x},${b.y})-(${b.x + b.width},${b.y + b.height}) [${rx1},${ry1}]-[${rx2},${ry2}] ${b.width}×${b.height}`;
+              })
+              .join('；'),
+        ]
+      : stateForRect?.windows?.length
+        ? [
+            '窗口列表（所有可见窗口）：' +
+              stateForRect.windows
+                .filter((w) => !w.minimized)
+                .slice(0, 10)
+                .map((w) => {
+                  const b = w.bounds;
+                  const label = w.title
+                    ? `「${w.title}」`
+                    : `[${w.id.split(':').pop() ?? '?'}]`;
+                  return `${label}(${b.x},${b.y})-(${b.x + b.width},${b.y + b.height}) ${b.width}×${b.height}`;
+                })
+                .join('；'),
+          ]
+        : []),
+    ...(stateForRect?.accessibility?.truncated
+      ? [
+          '⚠️ 无障碍树不完整（权限不足或元素过多），控件信息可能缺失，别把「没看到」当成「不存在」。',
+        ]
+      : []),
+    guidance,
+    response.content ?? '',
+  ].filter(Boolean);
+
+  // repeat 的实际次数必须如实汇报：模型要用它判断「还要不要再翻」。
+  // 报「按了 N 次」而实际只按了 3 次就到底了，会让它以为内容真的只有这么多。
+  if (repeatTimes > 1) {
+    // 诊断字段：这次排查 repeat 是否生效只能靠「一个 key 动作带回 7 张图」反推 ——
+    // 真实执行次数与边界判定结果必须落进 trace，否则下次还得猜。
+    // ⚠️ 恢复路径以前从这里之前就 return 掉了，trace 里连 repeat 字段都没有 ——
+    //    我正是靠「这一步的诊断字段比别的少 10 个」才反推出批量被腰斩。
+    //    现在恢复路径汇回主流程，这段对它同样生效。
+    extra.repeat = repeatDone;
+    extra.repeatRequested = repeatTimes;
+    extra.repeatEdge = repeatStoppedAtEdge
+      ? 'at-edge'
+      : repeatEdgeUnknown
+        ? 'unknown'
+        : 'moving';
+    // 三态都要如实说。把「没测出来」讲成「还能翻」，模型会拿一个我们没有的
+    // 确认当依据；讲成「到底了」则会让它提前收工 —— 实测出现过后者：
+    // 模型靠肉眼判定「只有 6 条」，而截图证明视图还停在底部。
+    actionFeedback.push(
+      repeatStoppedAtEdge
+        ? `repeat：请求 ${repeatTimes} 次，实际执行 ${repeatDone} 次后**目标区域连续 `
+          + `${EDGE_CONFIRM_ROUNDS} 次没有变化**，判定已到边界，剩余次数未执行。`
+          + `已经翻到头了，不要再往同方向重复。`
+        : repeatEdgeUnknown
+          ? `repeat：已连续执行 ${repeatDone}/${repeatTimes} 次，随附每次之后的画面（按时间顺序）。`
+            + `⚠️ 本次**未能测得目标区域的变化率**，因此**无法判断是否已到边界** —— `
+            + `这是工具的限制，不代表已经到底。要下「没有更多内容」的结论，`
+            + `必须自己拿出证据（比如再翻一次、对比画面确认内容不再变化）。`
+          : `repeat：已连续执行 ${repeatDone}/${repeatTimes} 次，随附每次之后的画面（按时间顺序）。`
+            + `目标区域仍在变化，说明还没到边界。`,
+    );
+  }
+
+  // movedRatio 无条件记进诊断（不只在 repeat 时）：它是「动作有没有真的推动内容」
+  // 的唯一确定性证据，单发动作同样需要它才排查得动。这次修 bug 就吃过亏 ——
+  // repeat 是否生效只能靠「一个动作带回 7 张图」反推。
+  const movedForTrace = actionChangeRatio(response.data, 'movedRatio');
+  if (movedForTrace !== undefined) extra.movedRatio = movedForTrace;
+
+  extra.axNodes = stateForRect ? countAxNodes(stateForRect) : 0;
+  extra.axTruncated = stateForRect?.accessibility?.truncated === true;
+  extra.frames = stateForRect?.sequence?.length ?? 0;
+  if (assembled) extra.estTokens = assembled.estimatedTokens;
+  if (stateForRect?.backend) extra.backend = stateForRect.backend;
+
+  return {
+    ok: true,
+    content: lines.join('\n'),
+    ...(allImages.length
+      ? { visionImages: allImages, visionNote: combinedNote }
+      : {}),
+  };
+}
+
+/** Exported for the input-path regression matrix. */
+export function shouldUseClipboardPaste(text: string): boolean {
+  return text.length > 50 || /[^\x00-\x7F]/.test(text);
+}
+
+/** 无障碍树节点数。遥测用 —— 只数个数，不看内容。 */
+function countAxNodes(state: ComputerState): number {
+  const walk = (node: AccessibilityNode | undefined): number => {
+    if (!node) return 0;
+    let total = 1;
+    for (const child of node.children ?? []) total += walk(child);
+    return total;
+  };
+  return walk(state.accessibility?.root);
+}
+
+/**
+ * 把原生 settle 的时间线翻译成模型看得懂的一句话。
+ *
+ * 判据分级走 `vision/settle.ts::evaluateSettle` —— 它是 R1 重构的产物，
+ * 核心是「ROI 像素为主判据、焦点只作增强」，且 L2 拿不到时**必须如实报
+ * `pixel-only`**，不能让模型把「没检测到焦点变化」当成「焦点没变」。
+ *
+ * 当前协议不携带焦点快照，所以这里恒为 pixel-only —— 这不是缺陷而是事实，
+ * 而 evaluateSettle 的设计正是为了让这个事实能被说出来。
+ */
+function describeSettle(data: unknown): string {
+  const payload = (data ?? {}) as {
+    timeline?: { t: number; ratio: number }[];
+    changedRegions?: { x: number; y: number; width: number; height: number }[];
+    settled?: boolean;
+    stableMs?: number;
+    reason?: string;
+  };
+  const timeline = Array.isArray(payload.timeline) ? payload.timeline : [];
+  if (timeline.length === 0) {
+    return '未采到任何帧，无法判断界面是否稳定。别把这当成「已稳定」。';
+  }
+  const now = timeline[timeline.length - 1]!.t;
+  const verdict = evaluateSettle({ timeline, now });
+  const regions = payload.changedRegions ?? [];
+  return [
+    verdict.reason,
+    `采样 ${timeline.length} 次 · 判据强度 ${verdict.confidence}`,
+    regions.length > 0
+      ? `变化区（相对坐标）：${regions.map((r) => `(${Math.round(r.x)},${Math.round(r.y)})-(${Math.round(r.x + r.width)},${Math.round(r.y + r.height)})`).join('、')}`
+      : '未检出变化区。',
+  ].join('\n');
+}
+
+/** 从守护进程的 replay 响应里取出帧数组，形状不对就当没有帧。 */
+function extractReplayFrames(data: unknown): ReplayFrame[] {
+  if (!data || typeof data !== 'object') return [];
+  const frames = (data as { frames?: unknown }).frames;
+  if (!Array.isArray(frames)) return [];
+  return frames.flatMap((frame) => {
+    if (!frame || typeof frame !== 'object') return [];
+    const f = frame as Record<string, unknown>;
+    return typeof f.width === 'number' && typeof f.height === 'number'
+      ? [
+          {
+            capturedAtMs:
+              typeof f.capturedAtMs === 'number' ? f.capturedAtMs : 0,
+            width: f.width,
+            height: f.height,
+            ...(typeof f.grayBase64 === 'string'
+              ? { grayBase64: f.grayBase64 }
+              : {}),
+          },
+        ]
+      : [];
+  });
+}
+
+/**
+ * ★ 对齐 UI-TARS：永远返回全屏截图，不再自动裁剪。
+ *
+ * 裁剪图会造成"坐标错觉"——模型在裁剪图内看到目标，
+ * 却需要计算整屏坐标，容易算错偏移。UI-TARS 只给全屏，
+ * 截图自动缩放到 MAX_PIXELS（~100万像素），模型直接看图定位，坐标一一对应。
+ *
+ * 保留此函数导出是为了显式表达"永远全屏"的语义，供测试和调用方确认这一行为。
+ */
+export function imageRect(_input: ComputerUseInput) {
+  return undefined;
+}
+
+/**
+ * 不可逆动作的准入：命中 → 定类别 → 问人 → 批准后本回合有效。
+ *
+ * ★★ **动作类别的三级来源，优先级从高到低**（这是本次修复的核心）：
+ *
+ *   1. **引擎自主推导** —— `matchIrreversible` 的 `key:` / `region:` 模式命中。
+ *      按了哪个键、点在哪个矩形里都是引擎手里的事实，不需要模型配合，因此最可信，
+ *      必须排在最前面。（旧实现先试硬编码的 `intent:submit` / `window:close`，
+ *      于是模型只要报了 submit，说明书里可验证的那一条就永远轮不到 —— 拿可验证
+ *      的判据去让位给自报，方向是反的。）
+ *   2. **模型自报的 `actionClass`** —— 且**必须出现在当前应用说明书的
+ *      `irreversible:` 清单里**。不在清单里就忽略这条声明、降级到第 3 级，
+ *      并把「你报的类别不在该应用说明书中」写回给模型。
+ *   3. **回落** —— `intent:submit`（模型自报提交）或 `window:close`（引擎判定）。
+ *
+ *   ⚠️ 安全不变量：伪造的、拼错的、跨应用的 `actionClass` **拿不到更窄的授权，也
+ *   绕不过通用确认** —— 它们一律落到第 3 级的 `intent:submit`，走完整审批。所需
+ *   能力（`requiredCapability`）完全不看 `actionClass`，能力提升仍只由
+ *   `intent:'submit'` 驱动。换句话说，自报类别只能让审批**更精确**，不能让它更松。
+ *
+ * 有效类别决定两件事：写进 grant 的 `actionClass`（授权范围），以及去说明书里
+ * 挑哪些步骤的前置条件来验（`unmetPreconditionsFor`）。
+ *
+ * 命中后按顺序走三层，**顺序本身就是安全设计**：
+ *   1. `supervised !== true`（无人可确认）→ **无条件拒绝**。没人能批准的时候
+ *      不做不可撤销的事，比「先做了再说」安全。这是最硬的一层，不经过任何询问。
+ *   2. 本回合已批准过**同一 (应用, 动作类别)** → 放行，不重复打扰。
+ *   3. 问真人（`askBridge`）。批准 → 写一条限定范围的 grant 后放行。
+ *
+ * ★ 授权范围是 **(应用, 动作类别)**，不是「本回合所有不可逆动作」。
+ *   早先的实现批准后往 `capabilities` 里 push `'submit'`，于是「批准给张三
+ *   发这条消息」顺带放开了同一回合里的关窗口、删除、其它应用的提交——
+ *   用户点头的是一件事，拿到的是一类权力。收窄之后两件事可以同时成立：
+ *   同一 (应用, 类别) 的后续动作不再逐个弹窗（一个回合里连发几条消息只问
+ *   一次），而换了类别或换了应用仍然要单独点头。
+ *
+ * ★ 生命周期仍是回合级：`computerRun` 由宿主每回合新建（TUI `useChat.ts`、
+ *   Desktop `localServer.ts`），所以授权不会渗到下一回合。
+ *
+ * ★ 为什么敢在这里问：`requestUserChoice` 在没有交互 UI 的宿主会**自动选首项**。
+ *   三重保险保证那不会变成静默批准：(a) 第 1 层已经拦掉所有非交互宿主
+ *   （`print.ts`/`streamJson.ts` 都传 `supervised:false`）；(b) 进 ask 前查
+ *   `hasAskHandler()`；(c) 首项固定是「取消」。任一层单独成立即 fail-closed。
+ */
+async function authorizeIrreversibleAction(
+  input: ComputerUseInput,
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+  signal?: AbortSignal,
+): Promise<{ error?: string; authorized: boolean; notice?: string }> {
+  if (!isMutatingComputerUseAction(input.action)) return { authorized: false };
+
+  const state = computerUseService.lastObservation(run);
+  const guides = await loadAllGuides();
+  const matched = matchGuide(guides, {
+    id: state?.activeApp?.id,
+    name: state?.activeApp?.name,
+  });
+  const declared = matched?.guide.irreversible ?? [];
+
+  // 第 1 级：引擎自主推导。**刻意不传 `intent`** —— 传了会让说明书里的
+  // `intent:` 条目在这一级命中，而这一级的全部意义正是「不依赖模型说什么」。
+  // 自报的那条路在第 2 / 3 级，位置比它低。
+  let hit: { entry: string; why: string } | null = matchIrreversible(
+    matched?.guide ?? null,
+    {
+      command: input.action,
+      combo: input.key,
+      ...(input.x !== undefined && input.y !== undefined
+        ? { point: { x: input.x, y: input.y } }
+        : {}),
+    },
+  );
+
+  // 第 2 级：模型自报的类别，且必须被当前说明书认领。
+  //
+  // 认领这一关不能省：不查清单的话，模型报什么类别就得到什么类别的 grant，
+  // 于是它可以自造一个只有自己知道的类别名，让「同一 (应用, 类别) 不重复询问」
+  // 变成一次点头换一整类自定义权力；跨应用的类别名也会污染别的应用的授权面。
+  let unclaimed: string | undefined;
+  if (!hit && input.actionClass) {
+    if (declared.includes(input.actionClass)) {
+      hit = {
+        entry: input.actionClass,
+        why: `你自报的动作类别「${input.actionClass}」在${matched!.guide.name} 说明书中被声明为不可逆`,
+      };
+    } else {
+      unclaimed = input.actionClass;
+    }
+  }
+
+  // 第 3 级：回落。走到这里的自报类别一律不生效，拿到的是最宽的通用审批。
+  if (!hit) {
+    // ★ 全局高危黑名单必须**够得着**。
+    //
+    // 修的是一个真缺口：`intent:payment` / `intent:format-disk` 这类全局高危条目，
+    // 此前**只有**在某份应用说明书恰好声明过它时才可能成为 `hit.entry`；否则模型
+    // 自报的类别落进 `unclaimed`，`hit` 为空 → 函数返回 `{authorized:false}`
+    // 且不带 error → 调用方视为「无需审批」**照常执行**。
+    // 于是黑名单只在「恰好有说明书」时生效，而最危险的场景（陌生应用、
+    // 没有说明书）恰恰是它最该生效的时候。全局黑名单本来的语义是
+    // 「不可被应用级降级」，不该连「够不够得着」都取决于说明书。
+    if (input.actionClass && isGlobalCriticalIntent(input.actionClass)) {
+      hit = {
+        entry: input.actionClass,
+        why: '你自报的动作属于全局高危类别：后果不可撤销，且涉及财产或数据安全',
+      };
+      // 它不是「没被认领」——是被全局黑名单直接认领了，不该再提示类别名写错。
+      unclaimed = undefined;
+    } else if (input.intent === 'submit') {
+      hit = { entry: 'intent:submit', why: '你把这一步自报为最终提交' };
+    } else if (input.action === 'window' && input.windowOperation === 'close') {
+      hit = {
+        entry: 'window:close',
+        why: '关闭窗口会丢失未保存的内容，且无法撤销',
+      };
+    }
+  }
+  if (!hit) return { authorized: false };
+
+  const notice = unclaimed
+    ? `⚠️ 你报的 actionClass「${unclaimed}」不在${
+        matched
+          ? `${matched.guide.name} 说明书的 irreversible: 清单里（清单：${declared.join('、') || '空'}）`
+          : '任何已匹配的应用说明书中（当前前台应用没有匹配到说明书）'
+      }，已忽略该声明，按通用类别「${hit.entry}」处理。要拿到精确到这一类的授权与前置条件检查，请从回执里注入的清单中原样抄一个类别名。`
+    : undefined;
+  // 下面每条出口都要带上 notice —— 这是「模型报错了类别」这件事的唯一回传通道，
+  // 漏在任何一条分支上，模型就会在那条路上一直用错名字而永远收不到反馈。
+  const deny = (error: string) => ({
+    authorized: false as const,
+    error,
+    ...(notice ? { notice } : {}),
+  });
+  const allow = () => ({
+    authorized: true as const,
+    ...(notice ? { notice } : {}),
+  });
+
+  // 说明书声明的前置条件：**在问人之前**检查。
+  //
+  // 不该拿一个「作者已经写明前提不成立」的动作去请用户点头 —— 人在弹窗上
+  // 看不到「聊天标题跟目标对象对不上」这种事，点了同意就真发出去了。
+  // 这是本批把知识从 skill 搬进插件后真正多出来的**强制力**：说明书里
+  // 写下的约束不再只是给模型看的建议。
+  //
+  // 查的是**有效类别**那一类的前提，不是整份说明书的所有不可逆步骤 ——
+  // 后者是旧实现的错，理由见 `manualSchema.ts::unmetPreconditionsFor` 头注。
+  const unmet = unmetPreconditionsFor(
+    matched?.guide.manual ?? EMPTY_MANUAL,
+    hit.entry,
+    state,
+  );
+  if (unmet.length > 0) {
+    const detail = unmet
+      .map(
+        (item) =>
+          `「${item.flowId}」第 ${item.stepIndex} 步（${item.step}）要求：${item.precondition}`,
+      )
+      .join('；');
+    return deny(
+      `这是不可逆动作（${hit.entry}：${hit.why}），但${matched!.guide.name} 说明书声明的前置条件当前**不成立**：${detail}。先把这些条件弄成立（通常是重新 observe 确认目标对象/焦点），再执行这一步。条件没满足就不会向用户发起确认 —— 用户在弹窗上看不出这类问题。`,
+    );
+  }
+
+  // ★ 风险分级判定。
+  //
+  // 设计原则：黑名单制。
+  //   - critical（高危红线）：全局黑名单 + 应用级 critical 列表 → 必须人工确认
+  //   - normal（一般不可逆）：其余全部 → 自动放行，保留审计记录
+  //
+  // 这是把发消息这种操作和删库格式化区分开的关键。
+  // 判定住在内核的 `src/irreversible/rules.ts`，与 Bash 共用同一套词汇表。
+  // （原先传的 `guideAll` 是**死参数**——函数体从来没读过它，一并去掉。）
+  const riskHit: RiskHit = classifyIntent({
+    entry: hit.entry,
+    guideCritical: matched?.guide.irreversibleCritical ?? [],
+    why: hit.why,
+  });
+
+  // normal 级：直接放行。
+  //
+  // 仍然写一条 grant（审计用），这样后续同一 (应用, 类别) 的动作也能命中 grant，
+  // 保持行为一致性。
+  if (riskHit.riskLevel === 'normal') {
+    const appId =
+      input.appId ?? state?.activeApp?.id ?? state?.activeApp?.name ?? '*';
+    (run.irreversibleGrants ??= []).push({
+      appId,
+      actionClass: hit.entry,
+      grantedAtMs: Date.now(),
+    });
+    return allow();
+  }
+
+  // 授权范围的两个维度。appId 取当时的前台应用；拿不到就用 `'*'` ——
+  // 那种情况下这条 grant 覆盖面更宽，但第 1 层仍要求有人在场。
+  const appId =
+    input.appId ?? state?.activeApp?.id ?? state?.activeApp?.name ?? '*';
+  const actionClass = hit.entry;
+
+  // 第 1 层：无人可确认 → 无条件拒绝，连问都不问。
+  if (run.supervised !== true) {
+    return deny(
+      `这是不可逆动作（${hit.entry}：${hit.why}），而当前运行没有可确认的人。不可撤销的操作不能在无人监督时执行 —— 请把结果告诉用户，由用户自己完成这一步。`,
+    );
+  }
+
+  // 第 2 层：本回合已经批准过同一 (应用, 类别)，不重复打扰。
+  if (hasGrant(run, appId, actionClass)) return allow();
+
+  // 第 3 层：问真人。没有交互 UI 就当没批准。
+  if (!hasAskHandler()) {
+    return deny(
+      `这是不可逆动作（${hit.entry}：${hit.why}），但当前宿主没有可用的确认界面，无法取得用户同意。请把你要做的事告诉用户，由用户自己完成这一步。`,
+    );
+  }
+
+  const appLabel =
+    state?.activeApp?.name ?? state?.activeApp?.id ?? '当前前台应用';
+  const target = describeActionTarget(input);
+  // 用户本回合的原话里根本没有不可逆意向，模型却要提交 —— 这本身就值得多看一眼。
+  // 这也是 `looksLikeIrreversibleRequest` 的正确用法：提示，不是授权判据。
+  const unprompted =
+    run.userInput !== undefined && !looksLikeIrreversibleRequest(run.userInput);
+
+  let answers: Awaited<ReturnType<typeof requestUserChoice>>;
+  try {
+    answers = await requestUserChoice(
+      [
+        {
+          header: '不可逆操作',
+          question: `Agent 要在「${appLabel}」执行一个**收不回来**的操作：${target}\n判定依据：${hit.entry} —— ${hit.why}\n${
+            unprompted
+              ? '⚠️ 你这一轮的原话里并没有要求做不可逆的事，请确认这是你想要的。\n'
+              : ''
+          }批准后，本回合内「${appLabel}」的同类操作（${actionClass}）不再逐个询问；换一类操作或换一个应用仍会再问你一次。`,
+          options: [
+            {
+              label: '取消，我自己来 (推荐)',
+              description:
+                '拒绝这次操作。Agent 会把该做什么告诉你，由你手动完成。',
+            },
+            {
+              label: '批准，本回合内执行',
+              description: `允许本回合内「${appLabel}」的 ${actionClass} 类操作。下一轮对话会重新询问。`,
+            },
+          ],
+        },
+      ],
+      signal,
+    );
+  } catch {
+    // 询问本身失败（中断、通道断了）一律按未批准处理。
+    return deny(
+      `这是不可逆动作（${hit.entry}：${hit.why}），向你确认的过程被中断，未获批准。`,
+    );
+  }
+
+  const approved =
+    answers[0]?.selected.some((label) => label.startsWith('批准')) === true;
+  void recordIrreversibleDecision({
+    approved,
+    appId,
+    actionClass,
+    surface: run.surface,
+  });
+  if (!approved) {
+    return deny(
+      `这是不可逆动作（${hit.entry}：${hit.why}），用户没有批准。请不要再尝试这一步，把需要用户自己完成的部分说清楚。`,
+    );
+  }
+
+  // 批准写回本回合授权。`run` 与两处 host gate 闭包持的是同一个对象引用，
+  // 所以这一次赋值同时对工具和 gate 生效，不必两边各记一份状态。
+  (run.irreversibleGrants ??= []).push({
+    appId,
+    actionClass,
+    grantedAtMs: Date.now(),
+  });
+  return allow();
+}
+
+/** 本回合是否已批准过这个 (应用, 类别)。`'*'` 的 grant 覆盖任意应用。 */
+function hasGrant(
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+  appId: string,
+  actionClass: string,
+): boolean {
+  return (run.irreversibleGrants ?? []).some(
+    (grant) =>
+      grant.actionClass === actionClass &&
+      (grant.appId === appId || grant.appId === '*'),
+  );
+}
+
+/**
+ * 把一次不可逆审批的结局落审计（fire-and-forget，不阻塞审批）。
+ *
+ * 落**独立的** `authorizations.jsonl`，不混进 `telemetry.jsonl`：
+ *   - 遥测有隐私白名单，`appId` 这类字段本来就会被丢掉，而审计恰恰需要它
+ *     ——「批准了哪个应用的什么」是审计的全部意义
+ *   - 遥测会按大小轮转（旧的直接丢），审计不该跟着一起被冲掉
+ *
+ * ⚠️ **它不是守护进程的 `audit.jsonl`。** 那个文件由 daemon 拥有并写入，
+ *   TS 侧往里追加会破坏它的所有权与格式假设。`/computeruse audit` 把两份
+ *   并排显示，不假装它们是同一份。
+ */
+async function recordIrreversibleDecision(input: {
+  approved: boolean;
+  appId: string;
+  actionClass: string;
+  surface: string;
+}): Promise<void> {
+  try {
+    const line = `${JSON.stringify({
+      t: Date.now(),
+      decision: input.approved ? 'approved' : 'denied',
+      appId: input.appId,
+      actionClass: input.actionClass,
+      surface: input.surface,
+    })}\n`;
+    const path = join(computerUseStateDir(), 'authorizations.jsonl');
+    await mkdir(dirname(path), { recursive: true }).catch(() => {});
+    await appendFile(path, line, { mode: 0o600 });
+  } catch {
+    /* 审计写不进去不能阻断已经取得的人工批准 —— 那会把「用户点了同意」
+       变成「因为磁盘满了所以不算」。写失败是运维问题，不是授权问题。 */
+  }
+}
+
+/** 给人看的一句话动作描述。只用结构化字段，不回显任何屏幕内容。 */
+function describeActionTarget(input: ComputerUseInput): string {
+  const parts = [`动作 ${input.action}`];
+  if (input.windowOperation) parts.push(`窗口操作 ${input.windowOperation}`);
+  if (input.key) parts.push(`按键 ${input.key}`);
+  if (input.elementId) parts.push(`目标元素 ${input.elementId}`);
+  else if (input.x !== undefined && input.y !== undefined) {
+    parts.push(`坐标 (${Math.round(input.x)}, ${Math.round(input.y)})`);
+  }
+  // 输入的文本可能是隐私内容，只报长度不报内容。
+  if (input.text) parts.push(`输入 ${input.text.length} 个字符`);
+  return parts.join(' · ');
+}
+
+/**
+ * 加载全部应用说明书。来源与优先级见 `appGuide.ts::appManualProviders`
+ * （工作区 `app-manuals/` > cwd 插件 > 包内插件，逐文件覆盖）。
+ *
+ * 合并逻辑住在 appGuide 而不是这里：插件命令面要用同一份结果，两处各写一遍
+ * 会让「哪份说明书生效」在工具与诊断命令之间给出不同答案。
+ */
+async function loadAllGuides(): Promise<AppGuide[]> {
+  return (await loadAllAppManuals()).guides;
+}
+
+/**
+ * 当前观测对应的那份说明书（没有就 undefined）。
+ *
+ * 存在的唯一理由是把**应用专属知识**喂给通用判定器，而不是让通用判定器自己去
+ * 认识某个应用 —— 内核里曾经写死过一段微信 bundleId 的判断，见
+ * `humanBoundary.ts` 里那段注释。
+ */
+async function manualForState(
+  state: ComputerState,
+): Promise<AppManual | undefined> {
+  const matched = matchGuide(await loadAllGuides(), {
+    id: state.activeApp?.id,
+    name: state.activeApp?.name,
+  });
+  return matched?.guide.manual;
+}
+
+/** 首次注入的完整摘要预算（字符）。中文约 2 字/token，故上限约 2k token。 */
+/**
+ * 真正**消费坐标**的动作。只有它们才谈得上「像素坐标还是比例坐标」。
+ *
+ * ⚠️ 为什么需要这个集合：不少模型（GPT 系尤其明显）会把 schema 里每个字段都填上
+ * 默认值再发过来 —— `x:0, y:0, pixelX:0, pixelY:0` 同时出现。对 `observe` 这种
+ * 压根不看坐标的动作，拿互斥约束去拦它毫无意义，却会让整次调用失败。
+ * 实测：Desktop 侧连 observe 都调不动就卡在这里（前一道是 `actionClass: ""`）。
+ */
+const POINTING_ACTIONS = new Set([
+  'click', 'double_click', 'right_click', 'middle_click', 'hover',
+  'pointer_down', 'pointer_move', 'pointer_up', 'drag', 'scroll',
+]);
+
+/**
+ * 说明书摘要的注入预算。
+ *
+ * ⚠️ 这个数字**只在每次运行的第一次 ComputerUse 调用**花一次（之后只注入一行提醒 + 路径），
+ * 而上下文窗口是几十万 token 级 —— 省这一点点换来的是实打实的成功率损失。
+ *
+ * 实测：4000 时 `wechat.md` 需要 5283 字符，降级阶梯把**全部「流程中的坑」砍掉**，
+ * 包括「发错对象无法挽回」「输入框右下角是麦克风不是发送按钮」这些最贵的经验。
+ * 而那些坑正是说明书存在的理由 —— 步骤列表模型自己也能猜个八九不离十，
+ * 坑不告诉它就一定会踩。
+ *
+ * 所以放宽到 12000：给现有说明书留足余量，也给「实测记录不断长出来」留空间。
+ * 降级阶梯仍在（真写爆了还是会如实告诉你丢了什么），只是不再在正常尺寸上误伤。
+ */
+const MANUAL_DIGEST_BUDGET_CHARS = 12_000;
+
+/** 可以 `repeat` 的动作：效果可累加、且中间态对调用方有意义的那些。 */
+const REPEATABLE_ACTIONS = new Set(['key', 'scroll']);
+
+/** `repeat` 的硬上限。见 inputSchema.repeat 注释。 */
+const MAX_REPEAT = 8;
+
+/** 一次遍历后「到边界了没有」的三态。`unknown` 是有意保留的。 */
+type ScrollEdge = 'at-edge' | 'moving' | 'unknown';
+
+/**
+ * 遍历有没有到边界。
+ *
+ * ⚠️ **只认 `movedRatio`（动作前基线 vs 动作后画面），不认 `changeRatio` /
+ * `regionChangeRatio`。** 这三个数长得像，回答的却是两个不同的问题：
+ *
+ *   · `change/regionChangeRatio` —— 来自 `settle_timeline`，在动作后的窗口里逐帧
+ *     对比**相邻采样**，答的是「画面**还在不在动**」；
+ *   · `movedRatio` —— 动作前抓的基线对动作后的画面，答的是「内容相对之前
+ *     **有没有移动**」。
+ *
+ * 曾经用前者判边界，实测是**每一次翻页都报「已到边界」**而内容还在往前翻：
+ * `pageup` / 滚轮是瞬时跳转、没有动画，采样启动时画面早已静止，测出 0 属于正常。
+ * 假的边界信号比没有更糟 —— 它会告诉模型「已经翻到头了」，直接诱导提前收工，
+ * 那正是这轮要修的原始症状（「只有约 6 条」，而截图证明视图还停在底部）。
+ *
+ * 拿不到 `movedRatio` 时返回 `unknown` 并如实说明，不用别的数顶替。
+ */
+function isAtScrollEdge(response: { data?: unknown }): ScrollEdge {
+  const moved = actionChangeRatio(response.data, 'movedRatio');
+  if (moved === undefined) return 'unknown';
+  return moved < EDGE_CHANGE_RATIO ? 'at-edge' : 'moving';
+}
+
+/** 低于这个变化率就认为「这一下什么都没翻动」。与验证器同一量级。 */
+const EDGE_CHANGE_RATIO = 0.001;
+
+/**
+ * 每个 run 最多自动抢回几次前台。
+ *
+ * 有上限是必须的：如果前台是被**用户自己**占着（他真的在用电脑），一直抢回去就是
+ * 和用户抢鼠标。次数用完就老实停下，把情况如实报出来。
+ */
+const MAX_FOCUS_RECOVERIES = 3;
+const focusRecoveryCounts = new Map<string, number>();
+
+/**
+ * 焦点被抢走后就地抢回来，然后重试一次原动作。
+ *
+ * 只在**没有人工接管通道**（`-p` 之类的无人宿主）时走这条路：有人值守时应该让人处理，
+ * 那才是这条闸门的本意。
+ *
+ * 返回 null = 没能恢复（不知道该激活哪个应用 / 激活失败 / 重试仍失败 / 次数用尽），
+ * 调用方据此走原来的终止路径，并在错误里说明已经尝试过。
+ */
+async function recoverLostFocus(
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+  requestInput: Omit<ComputerUseRequest, 'protocolVersion' | 'requestId' | 'context'>,
+  signal?: AbortSignal,
+): Promise<{ response: ComputerUseResponse; note: string } | null> {
+  const key = `${run.conversationKey}:${run.runId}`;
+  const used = focusRecoveryCounts.get(key) ?? 0;
+  if (used >= MAX_FOCUS_RECOVERIES) return null;
+
+  // 目标应用：优先用本次动作显式声明的，否则用上一次观测里的前台应用 ——
+  // 那正是焦点被抢走**之前**我们在操作的那个。
+  const targetApp =
+    requestInput.appId ?? computerUseService.lastObservation(run)?.activeApp?.id;
+  if (!targetApp) return null;
+  focusRecoveryCounts.set(key, used + 1);
+
+  const activated = await computerUseService.executeVerifiedAction(
+    run,
+    { action: 'activate_app', appId: targetApp } as Omit<
+      ComputerUseRequest,
+      'protocolVersion' | 'requestId' | 'context'
+    >,
+    signal,
+  );
+  if (!activated.ok) return null;
+
+  // 重新激活会让 epoch 前进，原来那份 expectedEpoch 已经过期 —— 必须换成最新的，
+  // 否则重试必然撞 stale_state（换个说法失败，等于没恢复）。
+  const freshEpoch = computerUseService.lastObservation(run)?.epoch;
+  const retried = await computerUseService.executeVerifiedAction(
+    run,
+    {
+      ...requestInput,
+      ...(freshEpoch !== undefined ? { expectedEpoch: freshEpoch } : {}),
+    },
+    signal,
+  );
+  if (!retried.ok || !retried.state) return null;
+
+  // ⚠️ **返回「恢复后的响应」，不要在这里拼成品 ToolResult。**
+  //    此前这里直接返回 ToolResult 并被调用方 `return` 掉，于是恢复路径成了一条
+  //    并行的早返回 —— 拿不到批量剩余次数的补跑、拿不到「repeat：M/N 次」文本、
+  //    拿不到 extra 诊断与 movedRatio。实测代价：repeat:8 静默塌缩成 1 次。
+  //    现在交回响应，由调用方汇进主流程，上面那些一次都不落。
+  return {
+    response: retried,
+    note:
+      `⚠️ 前台曾被别的窗口抢走，已自动重新激活「${targetApp}」并重试了这个动作`
+      + `（本次任务第 ${used + 1}/${MAX_FOCUS_RECOVERIES} 次自动恢复）。`
+      + '请对照画面确认动作确实落在了目标应用上；'
+      + '如果反复出现，说明有别的程序在抢前台，应如实告诉用户而不是继续硬抢。',
+  };
+}
+
+/**
+ * 连续这么多次「目标区域没动」才判定到边界。
+ *
+ * 取 2 而不是 1：单次没动完全可能是动画还没渲染完（尤其带惯性滚动的列表），
+ * 按 1 次就收手会在内容还没翻完时提前停下 —— 而提前停下的表现是「内容只有这么多」，
+ * 一个看起来像事实的错误结论。
+ */
+const EDGE_CONFIRM_ROUNDS = 2;
+
+/**
+ * 跨应用通用的交互模式，随应用说明书走**同一条注入通道**。
+ *
+ * ⚠️ 为什么必须走这条通道，而不是写进工具描述：**同样的内容，通道不同，结果相反。**
+ * 实测过一次 —— 把「翻页阶梯」写进工具描述，模型跑一整轮**一次都没照做**，反而去
+ * 拖那条隐藏的滚动条（拖偏就是在聊天区框选文本）；把同样几句写进应用说明书的 flow，
+ * 模型立刻照做，14 次 pageup 翻到了三天前的记录。差别只在于说明书**每次观测都注入**，
+ * 而工具描述只在开头出现一次 —— 跑到第 10 步时早被淹没了。
+ *
+ * ⚠️ 为什么放在引擎里，而不是放进 `plugins/computer_use/app/` 当数据：
+ * 这里写的是**本工具自身的行为**（滚轮事件投递给鼠标所在视图、变化率报的是目标区域
+ * 还是全屏、哪些动作会被验证）。它必须和实现绑在一起，作为插件数据会各自漂移 ——
+ * 而一份和实现对不上的说明书比没有更糟。应用特有的事实仍然留在各自的 app 手册里。
+ *
+ * ⚠️ 只写**有实测支撑**的条目。宁可少，也不写一大本没验证过的通则 —— 那正是
+ * 「说明书写得像真的、模型照做却撞墙」的来源。目前只有滚动区这一节够格。
+ */
+const GENERIC_INTERACTION_GUIDE = [
+  '【通用交互模式】（跨应用成立，与具体应用无关）',
+  '',
+  '▸ 翻阅长列表 / 聊天记录 / 文档等可滚动区域，按这个顺序：',
+  ...TRAVERSAL_GUIDE_LINES,
+  '',
+  '▸ 判断「翻动了没有」只能靠**对比截图内容**，不能靠动作返回成功：',
+  '  自绘界面（Electron / Qt / 跨端客户端）无障碍树为空，动作层面永远是"成功"的。',
+  '',
+  '▸ **「到顶了 / 没有更多了」是一个需要证据的结论，不能靠一眼看。**',
+  '  可接受的证据只有两种：① 回执明确报告「已到边界」；② 你连续两次翻动后对比画面，',
+  '  内容确实没有变化。除此之外一律按「还没到底」处理。',
+  '  回执说「未能判断是否已到边界」时，那是工具的限制 —— **不要替它下结论**。',
+  '',
+  '▸ 目标数量达不到时（比如要 20 条只看到 6 条），如实报告「只找到 N 条」并说明依据：',
+  '  是已经翻到边界，还是没能继续翻。**不要把「我没找到更多」讲成「只有这么多」** ——',
+  '  这两句话对用户的意义完全不同，而后者是一个看起来像事实的错误结论。',
+].join('\n');
+
+/**
+ * 把对应应用的说明书**注入**观测回执。
+ *
+ * ★ 这里曾经只是「指路」：回执写一句「已找到应用指南：<path>，先 Read 它」，
+ *   然后指望模型照做。那正是把 skill 变成插件要解决的问题 —— 模型可以不读，
+ *   引擎也不知道它读没读，于是所有沉淀下来的事实都是「可参考可不参考」。
+ *
+ *   现在改成引擎直接把结构化内容写进回执：模型没有「不看」这个选项。
+ *
+ * 成本由两件事控住：
+ *   ① **本运行内首次命中才发完整摘要**，之后只剩一行提醒 + 路径
+ *      （`shouldInjectFullManual`，状态住在服务里）
+ *   ② 完整摘要有字符预算与确定性降级阶梯，且丢了什么会如实说
+ *      （`renderManualDigest`，语义抄 skillList 的那套）
+ *
+ * 匹配不上时**如实说「没找到」**并列出已有的 —— 静默降级会让模型以为自己
+ * 有该应用的知识、实际在裸奔，而没人知道。
+ */
+async function describeAppGuidance(
+  state: ComputerState,
+  run: NonNullable<import('../../types.js').ToolCallContext['computerRun']>,
+): Promise<string> {
+  const { guides, rejected } = await loadAllAppManuals();
+  const identity = { id: state.activeApp?.id, name: state.activeApp?.name };
+  const matched = matchGuide(guides, identity);
+
+  // 本应命中却被拒的那份，必须**如实说出来**。
+  //
+  // 说明书写错时它不进匹配池（见 appGuide.ts::rejectionOf），此时若只报
+  // 「没找到说明书」，用户会以为自己压根没写过，而实际上写了、只是坏了 ——
+  // 一个能修的问题被表现成一个不存在的问题。
+  const blocked = matched
+    ? null
+    : matchGuide(
+        rejected.map((item) => item.guide),
+        identity,
+      );
+  if (blocked) {
+    const entry = rejected.find(
+      (item) => item.guide.name === blocked.guide.name,
+    )!;
+    return [
+      `⚠️ 「${identity.name ?? identity.id ?? '当前应用'}」**有**说明书，但它写错了，已被隔离，不会进入你的上下文：`,
+      `  ${entry.guide.path}`,
+      ...entry.errors.map((message) => `  - ${message}`),
+      '在它修好之前，你对这个应用没有可用知识 —— 每个动作后都要观测核实，不要连续盲操作。',
+    ].join('\n');
+  }
+
+  if (guides.length === 0) return '';
+  return buildGuidanceText({
+    guides,
+    identity,
+    // 只有真命中了才登记「已注入」—— 否则没找到说明书的那几次会白白吃掉配额，
+    // 等真找到时反而只给一行提醒。
+    firstTime: matched
+      ? computerUseService.shouldInjectFullManual(run, matched.guide.name)
+      : false,
+    // 通用交互模式不依赖匹配结果：没有应用说明书时它反而最该出现。
+    // 用一个不可能与真实说明书重名的键占配额（说明书名来自文件名，不含 `__`）。
+    genericFirstTime: computerUseService.shouldInjectFullManual(
+      run,
+      '__generic_interaction__',
+    ),
+  });
+}
+
+/**
+ * 纯函数版本，供单测直接断言（注入策略是本批的核心行为，必须可测）。
+ * @internal
+ */
+export function buildGuidanceText(input: {
+  guides: AppGuide[];
+  identity: { id?: string; name?: string };
+  firstTime: boolean;
+  budgetChars?: number;
+  /**
+   * 本回合是否还没注入过通用交互模式。
+   *
+   * 与应用说明书共用同一套「每回合一次」的配额纪律：通用手册每次观测都灌一遍会
+   * 白烧上下文，而它的内容在一个回合内不会变。
+   */
+  genericFirstTime?: boolean;
+}): string {
+  // 通用交互模式与应用说明书是**互补**的，不是二选一：
+  // 前者管「这类控件怎么操作」，后者管「这个应用的东西在哪、有什么坑」。
+  // 没有应用说明书时它尤其重要 —— 那正是模型最容易自己瞎试的时候。
+  const generic = input.genericFirstTime ? GENERIC_INTERACTION_GUIDE : '';
+  const withGeneric = (body: string): string =>
+    generic ? `${generic}\n\n${body}` : body;
+
+  const matched = matchGuide(input.guides, input.identity);
+  if (!matched) {
+    return withGeneric(describeMatch(null, input.guides, input.identity));
+  }
+
+  if (!input.firstTime) {
+    return withGeneric(
+      `应用说明书 **${matched.guide.name}** 本回合已注入过（完整内容：${matched.guide.path}）。`,
+    );
+  }
+
+  const confidence =
+    matched.matchedBy === 'displayName'
+      ? '（靠显示名命中，置信度较低：显示名会随系统语言/版本变化）'
+      : '';
+  return withGeneric(
+    renderManualDigest({
+      name: matched.guide.name,
+      path: matched.guide.path,
+      manual: matched.guide.manual ?? EMPTY_MANUAL,
+      irreversible: matched.guide.irreversible,
+      matchedBy: `${matched.matchedBy}${confidence}`,
+      budgetChars: input.budgetChars ?? MANUAL_DIGEST_BUDGET_CHARS,
+    }).text,
+  );
+}
+
+export async function authorizeComputerUseFileDropPaths(
+  paths: string[],
+  allowedRoots: string[],
+): Promise<{ ok: true; paths: string[] } | { ok: false; error: string }> {
+  let canonicalRoots: string[];
+  try {
+    canonicalRoots = await Promise.all(
+      allowedRoots.map((root) => realpath(resolve(root))),
+    );
+  } catch {
+    return { ok: false, error: 'Computer Use 授权目录不存在或无法解析' };
+  }
+
+  const canonicalPaths: string[] = [];
+  for (const path of paths) {
+    if (!isAbsolute(path))
+      return { ok: false, error: '拖入文件必须使用绝对路径' };
+    let canonicalPath: string;
+    try {
+      canonicalPath = await realpath(path);
+      if (!(await stat(canonicalPath)).isFile()) {
+        return { ok: false, error: `拖入目标不是普通文件：${path}` };
+      }
+    } catch {
+      return { ok: false, error: `拖入文件不存在或无法读取：${path}` };
+    }
+    if (!pathContainedByAny(canonicalRoots, canonicalPath))
+      return { ok: false, error: `拖入文件超出当前运行授权范围：${path}` };
+    canonicalPaths.push(canonicalPath);
+  }
+  return { ok: true, paths: canonicalPaths };
+}
+
+export async function validateComputerUseFileDropPaths(
+  paths: string[],
+  allowedRoots: string[],
+): Promise<string | null> {
+  const result = await authorizeComputerUseFileDropPaths(paths, allowedRoots);
+  return result.ok ? null : result.error;
+}