@glittering0717/ai-browser 2.1.1 → 2.1.2

package/README.md

@@ -955,6 +955,10 @@ the single source for `evaluate` limits, enforced identically on both transports
 Issues and PRs are welcome, especially reproduction cases where the semantic tree gets a page wrong —
 those are the most useful bug reports this project can get.
 
+Questions, "the tree got this page wrong" reports, and agent run logs are best posted in
+[GitHub Discussions](https://github.com/Glittering/ai-browser/discussions) — that is where the most
+useful feedback for this project tends to land.
+
 What we try to hold the line on:
 
 - **Keep the core generic.** Site-specific knowledge belongs outside `src/main` and `src/preload`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -55,6 +55,7 @@
   "scripts": {
     "start": "node scripts/start.cjs",
     "test": "vitest run",
+    "release": "node scripts/release.cjs",
     "test:watch": "vitest",
     "smoke": "node e2e/smoke_ws.cjs",
     "capabilities": "node e2e/capabilities_ws.cjs",

package/scripts/marketing/data_snapshot.sh

@@ -33,7 +33,7 @@ NPM_DL=$(curl -s --max-time 15 "https://api.npmjs.org/downloads/point/last-week/
 mcp_fetch() {
   for i in 1 2 3; do
     local out
-    out=$(curl -s --max-time 20 "https://registry.modelcontextprotocol.io/v0/servers?search=ai-browser" 2>/dev/null)
+    out=$(curl -s --max-time 20 "https://registry.modelcontextprotocol.io/v0/servers/io.github.Glittering%2Fai-browser/versions" 2>/dev/null)
     if [ -n "$out" ] && echo "$out" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null; then
       echo "$out"
       return 0

package/scripts/release.cjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// scripts/release.cjs — 一条命令走完发版闭环：版本号 → 测试 → commit → tag →
+// push(GitHub) → npm publish → MCP registry publish。
+//
+// 为什么要这个脚本（而不是每次手工敲 8 条命令）：
+//   发版最容易漏的不是编译，是**同步**。版本号有 4 处（package.json、
+//   server.json 两处、src/shared/version.js），GitHub 有 2 条分支 + 1 个 tag，
+//   发布有 2 个仓库（npm、MCP registry）。漏一处不会报错，只会让用户在
+//   issue 里报一个不存在的版本、或者让 npx 拉到的还是旧版 —— 而且要到
+//   下一次有人装的时候才发现。机器不会漏，人会。
+//
+// 用法：
+//   node scripts/release.cjs patch          # 2.1.2 → 2.1.3
+//   node scripts/release.cjs minor --dry    # 只看会做什么
+//   node scripts/release.cjs patch --notes notes.txt
+//
+// 设计原则：**每一步失败都不静默**。git 成功但 npm 失败时，脚本以非零退出并
+// 打印"已完成的步骤 + 怎么补救"，而不是假装整条链路都成功了。
+'use strict';
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const args = process.argv.slice(2);
+const dry = args.includes('--dry');
+const bumpKind = args.find((a) => ['patch', 'minor', 'major'].includes(a)) || 'patch';
+const notesIdx = args.indexOf('--notes');
+const notesFile = notesIdx >= 0 ? args[notesIdx + 1] : null;
+// 全量测试 4 分钟起，发版时默认只跑"会拦住错误发版"的那几个：
+// 版本一致性、导入完整性、schema 预算。其余靠 CI / 平时。
+const fullTests = args.includes('--full-test');
+
+const c = (s) => `\x1b[${s}m`;
+const ok = (m) => console.log(`${c(32)}✓${c(0)} ${m}`);
+const warn = (m) => console.log(`${c(33)}!${c(0)} ${m}`);
+const fail = (m) => console.log(`${c(31)}✗${c(0)} ${m}`);
+const step = (m) => console.log(`\n${c(36)}▸ ${m}${c(0)}`);
+
+function run(cmd, argv, opts = {}) {
+  const r = spawnSync(cmd, argv, { cwd: ROOT, encoding: 'utf8', ...opts });
+  if (r.status !== 0 && !opts.allowFail) {
+    throw new Error(`${cmd} ${argv.join(' ')} 失败:\n${(r.stderr || r.stdout || '').trim()}`);
+  }
+  return r;
+}
+function git(...argv) { return run('git', argv); }
+function gitOut(...argv) { return run('git', argv).stdout.trim(); }
+
+const done = [];
+function mark(m) { done.push(m); }
+
+// ---- 0. 前置检查 ----------------------------------------------------------
+step('前置检查');
+const branch = gitOut('rev-parse', '--abbrev-ref', 'HEAD');
+if (branch !== 'main' && branch !== 'dev') {
+  fail(`当前分支是 ${branch}，发版只允许在 main 或 dev 上做`);
+  process.exit(1);
+}
+const dirty = gitOut('status', '--porcelain');
+if (dirty) {
+  fail('工作区不干净，先提交或 stash：');
+  console.log(dirty.split('\n').map((l) => '    ' + l).join('\n'));
+  process.exit(1);
+}
+ok(`分支 ${branch}，工作区干净`);
+
+// ---- 1. 版本号 ------------------------------------------------------------
+step('计算并写入版本号');
+const pkgPath = path.join(ROOT, 'package.json');
+const serverPath = path.join(ROOT, 'server.json');
+const verPath = path.join(ROOT, 'src', 'shared', 'version.js');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const from = pkg.version;
+const [maj, min, pat] = from.split('.').map(Number);
+const to = bumpKind === 'major' ? `${maj + 1}.0.0`
+  : bumpKind === 'minor' ? `${maj}.${min + 1}.0`
+  : `${maj}.${min}.${pat + 1}`;
+console.log(`    ${from} → ${to} (${bumpKind})`);
+
+if (dry) {
+  warn('--dry：只打印，不写文件、不提交、不发布');
+  process.exit(0);
+}
+
+function rewrite(file, fn) {
+  const p = path.join(ROOT, file);
+  const before = fs.readFileSync(p, 'utf8');
+  const after = fn(before);
+  if (after === before) throw new Error(`${file} 没发生替换 —— 版本号格式变了？请人工确认`);
+  fs.writeFileSync(p, after);
+}
+rewrite('package.json', (s) => s.replace(`"version": "${from}"`, `"version": "${to}"`));
+// server.json 里有两处（顶层 + packages[0]），必须都改：只改顶层会让
+// registry 认为"清单说 2.1.3、实际包是 2.1.2"，校验直接不通过。
+rewrite('server.json', (s) => s.split(`"version": "${from}"`).join(`"version": "${to}"`));
+rewrite('src/shared/version.js', (s) => s.replace(`VERSION = '${from}'`, `VERSION = '${to}'`));
+ok('4 处版本号已同步（package.json / server.json×2 / version.js）');
+mark('版本号');
+
+// ---- 2. 测试 --------------------------------------------------------------
+step(fullTests ? '全量测试' : '发版闸门测试');
+const testFiles = fullTests
+  ? []
+  : ['tests/test_version.js', 'tests/test_imports.js', 'tests/test_api_budget.js', 'tests/test_mcp_tools.js'];
+const t = spawnSync('npx', ['vitest', 'run', ...testFiles, '--no-file-parallelism'], {
+  cwd: ROOT, encoding: 'utf8',
+});
+if (t.status !== 0) {
+  fail('测试未通过，发版中止。版本号改动已写在工作区，可用 git checkout 撤销。');
+  console.log((t.stdout || '').split('\n').slice(-25).join('\n'));
+  process.exit(1);
+}
+ok('测试通过');
+mark('测试');
+
+// ---- 3. commit + tag ------------------------------------------------------
+step('提交并打 tag');
+const notes = notesFile && fs.existsSync(path.join(ROOT, notesFile))
+  ? fs.readFileSync(path.join(ROOT, notesFile), 'utf8').trim()
+  : `v${to}`;
+git('add', 'package.json', 'server.json', 'src/shared/version.js');
+git('commit', '-m', `chore(release): v${to}`);
+ok(`commit chore(release): v${to}`);
+mark('commit');
+
+// tag 打在 main 上（历史 v2.1.x 都在 main）。dev 上发版就先 ff 到 main。
+if (branch === 'dev') {
+  git('checkout', 'main');
+  try { git('merge', '--ff-only', 'dev'); } catch (e) {
+    fail('main 无法快进到 dev（有分叉），需要人工处理。tag 未创建。');
+    git('checkout', 'dev');
+    process.exit(1);
+  }
+  ok('main 已快进到 dev');
+}
+git('tag', '-a', `v${to}`, '-m', notes);
+ok(`tag v${to}`);
+mark('tag');
+
+// ---- 4. push --------------------------------------------------------------
+step('推送到 GitHub');
+try {
+  git('push', 'origin', 'main');
+  git('push', 'origin', 'dev');
+  git('push', 'origin', `v${to}`);
+  ok('main / dev / tag 已推送');
+  mark('git push');
+} catch (e) {
+  fail('推送失败（网络或权限）：' + String(e.message).split('\n')[0]);
+  warn(`本地 commit 与 tag 都在，网络恢复后执行：git push origin main dev v${to}`);
+}
+
+// ---- 5. npm ---------------------------------------------------------------
+step('发布到 npm');
+const npm = spawnSync('npm', ['publish'], { cwd: ROOT, encoding: 'utf8' });
+if (npm.status === 0) {
+  ok(`@glittering0717/ai-browser@${to} 已发布`);
+  mark('npm publish');
+} else {
+  const out = `${npm.stdout || ''}${npm.stderr || ''}`;
+  // token 失效的特征：whoami 401、PUT 404（npm 用 404 掩盖"没权限"）
+  if (/E401|E404|Unauthorized|Not found/i.test(out)) {
+    fail('npm 认证失效（401/404）。需要重新登录一次，之后本脚本可全自动：');
+    console.log('      npm login                      # 浏览器登录');
+    console.log('      或：把新的 granular access token 写进 ~/.npmrc 的 //registry.npmjs.org/:_authToken');
+  } else if (/EPUBLISHCONFLICT|cannot publish over/i.test(out)) {
+    fail(`npm 上已存在 ${to}，版本号需要再往上走一格`);
+  } else {
+    fail('npm publish 失败：' + out.split('\n').filter(Boolean).slice(-4).join(' | '));
+  }
+  warn(`补救：token 恢复后执行  npm publish  （当前目录版本已是 ${to}）`);
+}
+
+// ---- 6. MCP registry ------------------------------------------------------
+step('发布到 MCP registry');
+const publisher = ['mcp-publisher', '/tmp/mcp-pub/mcp-publisher', '/opt/homebrew/bin/mcp-publisher']
+  .find((p) => { try { return fs.existsSync(p) || execFileSync('which', [p]).length > 0; } catch { return false; } });
+if (!publisher) {
+  warn('未找到 mcp-publisher，跳过。安装：gh release download --repo modelcontextprotocol/registry \\');
+  console.log('      --pattern "mcp-publisher_darwin_arm64.tar.gz" && tar xzf ...');
+} else {
+  const pub = spawnSync(publisher, ['publish'], { cwd: ROOT, encoding: 'utf8' });
+  if (pub.status === 0) {
+    ok('MCP registry 已发布');
+    mark('mcp registry');
+  } else {
+    const out = `${pub.stdout || ''}${pub.stderr || ''}`;
+    fail('MCP registry 发布失败：' + out.split('\n').filter(Boolean).slice(-6).join(' | '));
+    if (/auth|login|token|unauthor/i.test(out)) {
+      warn('需要先登录一次：mcp-publisher login github（device flow，点一下浏览器）');
+    }
+    warn('补救：登录后执行  mcp-publisher publish');
+  }
+}
+
+// ---- 摘要 -----------------------------------------------------------------
+console.log(`\n${c(36)}── v${to} 发版摘要 ──${c(0)}`);
+console.log('   已完成: ' + (done.length ? done.join(' → ') : '（无）'));
+const skipped = ['版本号', '测试', 'commit', 'tag', 'git push', 'npm publish', 'mcp registry']
+  .filter((s) => !done.includes(s));
+if (skipped.length) console.log(`   未完成: ${skipped.join(', ')}`);
+process.exit(skipped.length ? 2 : 0);

package/src/main/axExtractor.js

@@ -42,7 +42,10 @@ function valueOf(pv) {
 // The only "rule" we keep (plan §5): fold that into a semantic `textbox`.
 function editorTypeFrom(role, editable) {
   if (editable === 'richtext' || editable === 'contenteditable') return 'richtext';
-  if (role === 'textbox') {
+  // searchbox 与 textbox 同为可输入面，只是语义上被标成搜索框。此前只认
+  // textbox，导致 role=searchbox 的输入框**完全不出现在树的可编辑索引里** ——
+  // 于是"两个 editable"的场景里少算了一个，primary 反而可能指错。
+  if (role === 'textbox' || role === 'searchbox') {
     if (editable === 'multiline') return 'textarea';
     if (editable === 'plaintext') return 'textbox';
   }
@@ -100,6 +103,14 @@ let nodeStore = null; // current normalize pass's node map (see normalizeAxTree)
 // wrappers (§buildThroughIgnored); an AX node that a wrapper re-parents must not
 // be emitted twice.
 let seenNodes = null;
+// 本次 pass 收集到的"可编辑节点"清单，pass 结束时汇总成 tree.editors（见
+// summarizeEditors）。为什么要在树根上放索引：一个页面上有多个 editable 时，
+// 树的结构本身**不告诉你哪个是正文**。2026-10-19 知乎实机：顶部搜索框和
+// 正文编辑器都带 editable，按 editable 过滤先抓到搜索框（DOM 顺序在前），
+// 第一次粘贴直接糊进搜索框，靠字数校验才拦住没提交。
+// 面积是这里唯一可靠的区分信号（搜索框 300×36 vs 正文 720×600，差 30 倍），
+// 而它已经在每个节点的 bounds 里 —— 不需要额外读 DOM。
+let editables = null;
 
 // Descendants of an AX node that is `ignored: true`. AX marks presentational
 // wrappers (a `span` in a flex row, `<b>` inside a paragraph) as ignored, but
@@ -138,7 +149,10 @@ function build(node, idFor) {
     },
   };
   if (node.backendDOMNodeId != null) tn.backendDOMNodeId = node.backendDOMNodeId;
-  if (editorType) tn.editor_type = editorType;
+  if (editorType) {
+    tn.editor_type = editorType;
+    noteEditable(tn, editorType, node);
+  }
 
   if (role === 'textbox' || role === 'combobox' || role === 'listbox' || role === 'searchbox') {
     let v = valueOf(node.value);
@@ -183,6 +197,74 @@ function build(node, idFor) {
   return tn;
 }
 
+// 「这个输入框是不是搜索框」的判据。role=searchbox 是最强信号；其次是
+// placeholder/label 里的词。两者都没有时就靠面积（搜索框永远比正文小得多）。
+// 只用来**标注**，不用来排除 —— 排除错一个真编辑器，代价是 agent 找不到
+// 能写的地方。
+const SEARCH_LIKE = /搜索|查找|检索|search|find/i;
+
+// 面积下限：AX 里存在 1px 的表单元素（隐藏 input、脚手架占位），它们的
+// bounds 是 0 或 1，算进清单里只会制造噪音。
+const EDITABLE_MIN_AREA = 800;
+// 「像个正文编辑器」的下限。200×100 是保守值：真实正文区都在 400×200 以上，
+// 而搜索框在 300×36 量级。达不到就不给 primary —— 宁可让调用方自己看图，
+// 也不要指错。
+const PRIMARY_MIN_AREA = 20000;
+
+function noteEditable(tn, editorType, node) {
+  if (!editables) return;
+  const b = tn.bounds || {};
+  const w = Number(b.width) || 0;
+  const h = Number(b.height) || 0;
+  const area = w * h;
+  if (area < EDITABLE_MIN_AREA) return;
+  const ph = String(valueOf(prop(nodeStore, node.nodeId, 'placeholder')) || '');
+  const label = String(tn.label || '');
+  const searchlike = tn.role === 'searchbox'
+    || SEARCH_LIKE.test(ph)
+    || SEARCH_LIKE.test(label);
+  editables.push({
+    ref: tn.id,
+    role: tn.role,
+    editor_type: editorType,
+    label: label.slice(0, 40),
+    ...(ph ? { placeholder: ph.slice(0, 40) } : {}),
+    w,
+    h,
+    area,
+    readonly: (tn.states || []).indexOf('readonly') >= 0,
+    ...(searchlike ? { searchlike: true } : {}),
+  });
+}
+
+/**
+ * 把本 pass 收集到的可编辑节点汇总成树根上的 `editors` 索引。
+ *
+ * 存在的唯一理由：**树的结构不告诉你哪个 editable 是正文**。按 DOM 顺序
+ * 过滤 `editable` 拿到的是页面上第一个可输入的东西 —— 在知乎是顶部搜索框，
+ * 在掘金是登录框。agent 没法从 `[textbox] editable=richtext` 这一行判断
+ * "这是不是我要写的那个"，于是它要么猜，要么一个个试，要么把自己的正文
+ * 糊进搜索框（2026-10-19 真实发生，靠字数校验才拦住）。
+ *
+ * 输出按面积降序，`primary: true` 标给最大的那个非搜索非只读编辑区。
+ * 只有 1 个可编辑节点时**不输出**：没有歧义就不该多花 token。
+ *
+ * @returns {Array|undefined} 0/1 个节点返回 undefined
+ */
+export function summarizeEditors(list) {
+  if (!Array.isArray(list) || list.length < 2) return undefined;
+  const sorted = list.slice().sort((a, b) => b.area - a.area).slice(0, 8);
+  let primary = null;
+  for (const e of sorted) {
+    if (e.readonly || e.searchlike) continue;
+    if (e.area < PRIMARY_MIN_AREA) break; // 最大的可用编辑区都不像正文
+    primary = e.ref;
+    break;
+  }
+  // area 不外露：w/h 已经够了，重复字段只多花 token。
+  return sorted.map(({ area, ...rest }) => (rest.ref === primary ? { ...rest, primary: true } : rest));
+}
+
 /**
  * `InlineTextBox` 是 CDP 把一个 `StaticText` 按**换行和样式**切出来的文字碎片：
  * 一段两行的正文会变成两个 inline box，一个加粗的词再切一个。
@@ -225,6 +307,7 @@ export function normalizeAxTree(rawNodes, opts = {}) {
   nodeStore = new Map(all.map((n) => [n.nodeId, n]));
   seenNodes = new Set();
   readValue = opts.readValue || null;
+  editables = [];
   const idFor = opts.idFor || ((n) => 'ax-' + n.nodeId);
 
   // Parent map over ALL nodes, so "is this a root?" accounts for ignored
@@ -249,6 +332,11 @@ export function normalizeAxTree(rawNodes, opts = {}) {
     ? built[0]
     : { id: 'root', role: 'generic', label: '', states: ['visible'], actions: [], bounds: { x: 0, y: 0, width: 0, height: 0 }, children: built };
   tree._debug = { layer: 'ax', version: VERSION_TAG };
+  // 有歧义时才给索引（见 summarizeEditors）。挂在树根而不是散在各节点上：
+  // 调用方读一次根就能挑好目标，不用把整棵树扫一遍再自己比面积。
+  const editors = summarizeEditors(editables);
+  if (editors) tree.editors = editors;
+  editables = null;
   nodeStore = null;
   seenNodes = null;
   readValue = null;

package/src/main/mcp_tools.js

@@ -26,7 +26,7 @@ export const MCP_TOOLS = [
   {
     name: 'browse_get_tree',
     title: 'Read semantic tree',
-    description: 'Return the page semantic UI tree (roles, labels, actions, bounds, urls).',
+    description: 'Return the page semantic tree (roles, labels, actions, bounds). Root adds editors (primary) when 2+ editable.',
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
@@ -42,7 +42,7 @@ export const MCP_TOOLS = [
   {
     name: 'browse_act',
     title: 'Act on element',
-    description: 'Act on a data-ai-id element. type appends at caret, setContent replaces all. Verb-specific params live in the group of the same name (click/read/press/wheel/drag).',
+    description: 'Act on a data-ai-id element. type appends at caret, setContent replaces all. page_changed:false = dispatched but page unchanged (wrapper).',
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
@@ -50,7 +50,7 @@ export const MCP_TOOLS = [
         action: { type: 'string', enum: ['click', 'type', 'setContent', 'clear', 'focus', 'hover', 'scroll_to', 'upload', 'get_value', 'drag', 'press', 'wheel', 'paste'], description: 'Verb. Verb-specific params live in the group of the same name.' },
         target: { type: 'string', description: 'data-ai-id from the tree (e.g. e:button-12) — NOT the visible label. Optional for press; drag may use drag.from; upload also takes a CSS selector.' },
         text: { type: 'string', description: 'type: appended at the caret. setContent: replaces all. paste: plain fallback when html is absent.' },
-        html: { type: 'string', description: 'paste: HTML, preferred — editors keep headings/lists/bold. Plain text loses formatting.' },
+        html: { type: 'string', description: 'paste: HTML, preferred (keeps headings/bold). landed_chars:null = unreadable.' },
         value: { type: 'string', description: 'Option value for a <select>.' },
         file: { type: 'string', description: 'upload: absolute path. target may be the input, the trigger, or a CSS selector.' },
         timeout_ms: { type: 'integer', description: 'Deadline ms (default 15000, 1s..300s). On timeout: success=false, timed_out=true, may have partially applied.' },

package/src/main/page_manager.js

@@ -15,6 +15,12 @@ import { WINDOW_OPEN_SHIM_SOURCE } from './window_open_shim_source.js';
 import { pickOpenedTab, openedTabGraceMs } from '../shared/opened_tab.js';
 // 动作回执自带的"页面到底动没动"三态，以及 ref 过期诊断（两个纯函数模块）。
 import { withEffectState, isTargetMiss as isTargetMissError } from '../shared/effect_state.js';
+// 前后快照探针：动作返回 success 只证明"命令发出去了"，不证明"页面接住了"。
+// 后者必须由掌握渲染进程的一侧给出（见 shared/page_probe.js 顶部事故说明）。
+import pageProbe from '../shared/page_probe.js';
+// 默认读法（DOM extractor）的"哪个 editable 才是正文"索引。AX 路径在
+// normalizeAxTree 里已经自带，这条补的是默认路径 —— 见文件内注释。
+import editorsProbe from '../shared/editors_probe.js';
 import { newTracker, noteTree, diagnoseMissingRef } from '../shared/ref_epoch.js';
 import { diffValues, previewOf, safeByteLength, DEFAULT_SNAPSHOT_JS, DIFF_MAX_ENTRIES, evictOldest } from './snapshot_diff.js';
 import { withDeadline, actionDeadlineMs } from '../shared/deadline.js';
@@ -753,9 +759,45 @@ class PageManager {
     // 「ref 过期了」（页面变过，重读树即可）和「ref 从来没对过」（改传参）。
     // 见 shared/ref_epoch.js 顶部注释。
     this._noteTreeRefs(tid, res && res.tree);
+    // 多编辑器的消歧索引（见 shared/editors_probe.js）。AX 路径的树根已经带
+    // `editors`，这里只补默认路径；focused_only 的子树没有"整页有哪几个编辑区"
+    // 这层语义，跳过。
+    if (res && res.tree && !res.tree.editors && !focusedOnly) {
+      const idx = await this._editorsIndex(tid, res.tree);
+      if (idx) res.tree.editors = idx;
+    }
     return res;
   }
 
+  /**
+   * 扫一遍页面上的可编辑区，按面积给出 primary。
+   * 失败静默返回 null —— 消歧索引是**增强**，读不到不该让 get_tree 失败。
+   */
+  async _editorsIndex(tid, tree) {
+    const view = this._getView(tid);
+    if (!view) return null;
+    let rows = null;
+    try {
+      const d = view.webContents.debugger;
+      if (!d || typeof d.isAttached !== 'function' || !d.isAttached()) return null;
+      const r = await d.sendCommand('Runtime.evaluate', {
+        expression: editorsProbe.EDITORS_PROBE_JS,
+        returnByValue: true,
+      });
+      rows = r && r.result && r.result.value;
+    } catch (_e) {
+      return null;
+    }
+    const known = new Set();
+    const walk = (n) => {
+      if (!n) return;
+      if (n.id) known.add(n.id);
+      for (const c of n.children || []) walk(c);
+    };
+    walk(tree);
+    return editorsProbe.buildEditorsIndex(rows, known);
+  }
+
   /** per-tab 的 ref 版本追踪器（懒建，避免动构造函数）。 */
   _refTracker(tid) {
     if (!this._refTrackers) this._refTrackers = new Map();
@@ -1369,16 +1411,59 @@ class PageManager {
    * 放在这一层而不是各个子路径里，是因为挂住的位置不止一个（AX handles、指针目标
    * 解析、拖拽按键分发都可能），逐个补等于逐个漏。
    */
+  /**
+   * 动作前后各拍一次页面指纹（只读、不写属性、不触发事件）。
+   *
+   * 探针失效一律返回 null 并让调用方跳过 —— 观测能力不足不能反过来让动作失败。
+   * 三种失效都真实发生过：debugger 没 attach、主线程被占住导致 CDP 不返回、
+   * 页面返回了 __err。全部走静默降级，但**绝不用 null 冒充"没变化"**：
+   * diffProbe 对 null 显式返回 changed:null，回执里就不会出现 page_changed。
+   */
+  async _pageProbe(tid, action) {
+    if (!pageProbe.shouldProbe(action)) return null;
+    const view = this._getView(tid);
+    if (!view) return null;
+    try {
+      const d = view.webContents.debugger;
+      if (!d || typeof d.isAttached !== 'function' || !d.isAttached()) return null;
+      // 1.5s 硬上限：主线程卡住时 sendCommand 永不返回，等它等于把 ui.act
+      // 又挂死一次（这一层存在的全部意义就是不许挂）。
+      const call = d.sendCommand('Runtime.evaluate', {
+        expression: pageProbe.PAGE_PROBE_JS,
+        returnByValue: true,
+      });
+      const timer = new Promise((r) => setTimeout(() => r(null), 1500));
+      const r = await Promise.race([call.catch(() => null), timer]);
+      const v = r && r.result && r.result.value;
+      return v && !v.__err ? v : null;
+    } catch (_e) {
+      return null;
+    }
+  }
+
   async executeAction(action, target, params = {}, tabId) {
     const ms = actionDeadlineMs(action, params);
     const tid = tabId !== undefined ? tabId : this.activeTab;
+    // 动作前先拍一张。为什么拍在 withDeadline 外面：deadline 只应该盖住动作
+    // 本身，探针有它自己的 1.5s 上限，混进同一个预算会让"动作超时"和
+    // "探针慢"两种完全不同的故障共用一个错误码。
+    const probeBefore = await this._pageProbe(tid, action);
     try {
       const res = await withDeadline(
         this._executeActionInner(action, target, params, tabId),
         ms,
         `action:${action}`
       );
-      return this._annotateActResult(res, action, target, tid);
+      let out = this._annotateActResult(res, action, target, tid);
+      // 动作后拍第二张。settle 是必须的：paste/type 内部已经等过一轮，但 click
+      // 触发的弹窗/路由要等框架提交 + 一帧渲染，立刻拍必然拿到旧指纹 ——
+      // 那会把每一次成功的弹窗点击都误报成"页面没变"，比不报更糟。
+      if (probeBefore) {
+        await new Promise((r) => setTimeout(r, pageProbe.settleMs(action)));
+        const probeAfter = await this._pageProbe(tid, action);
+        out = pageProbe.applyProbe(out, probeBefore, probeAfter, action);
+      }
+      return out;
     } catch (e) {
       if (e && e.__deadline) {
         // 明确告诉 agent 两件事：① 它该重试/换策略；② 这个动作**可能已经部分生效**
@@ -2490,6 +2575,30 @@ class PageManager {
     // 派发不会向下传播到子节点，监听器收不到，defaultPrevented 恒为 false。
     // 实测：B站 read-editor 拆两步派发 → 编辑器完全无反应；合并 + 选定最深层
     // 可编辑元素后成功。
+    // 页面内"读回编辑器正文"的共用片段。参数是**已经在前面的表达式里定义好的
+    // 变量名**（不是选择器），因为不同时机能拿到的句柄不同：paste 那一刻有
+    // `ed`，之后重采样只能重新按 ref 查。
+    //
+    // 取"多个候选里最长的那个"而不是"第一个非空的"：页面上同时存在搜索框、
+    // 标题框、正文编辑器时，第一个非空的很可能是别的东西（知乎顶部搜索框就
+    // 这么骗过一次粘性校验）。而正文的长度必然最大 —— 这条启发式在
+    // 知乎/掘金/CSDN/OSChina/B站 五个站上都成立。
+    const landedProbe = (v) =>
+      `var cands=[],push=function(n,s){if(n&&cands.length<6)cands.push([n,s]);};` +
+      `push(${v},'target');` +
+      // 深层 activeElement（穿透 shadow root）：编辑面常常在编辑器组件自己的
+      // shadow DOM 里，document.activeElement 只到宿主元素。
+      `try{var a=document.activeElement,g=0;while(a&&a.shadowRoot&&a.shadowRoot.activeElement&&g++<8)a=a.shadowRoot.activeElement;push(a,'active');}catch(_e){}` +
+      // 目标内部的第一个编辑面（Draft.js / ProseMirror 的正文都是容器里的子节点）
+      `try{var q=${v}&&${v}.querySelector&&${v}.querySelector('[contenteditable=true],textarea,.cm-content,.ProseMirror,[data-lexical-editor=true]');push(q,'inner');}catch(_e){}` +
+      // 上层编辑器容器：目标可能只是工具栏/占位层，正文在它的祖先里
+      `try{var hh=${v}&&${v}.closest&&${v}.closest('.cm-editor,.cm-scroller,.CodeMirror,.ProseMirror,.DraftEditor-root,[contenteditable=true],form,article,main');push(hh,'host');}catch(_e){}` +
+      `var best={n:0,src:'',p:''};` +
+      `for(var i=0;i<cands.length;i++){var e=cands[i][0],s=cands[i][1],t='';` +
+      `try{t=(e.value!=null)?String(e.value):String(e.innerText||e.textContent||'');}catch(_e){}` +
+      `t=t.replace(/\\s+/g,' ');var L=t.replace(/ /g,'').length;` +
+      `if(L>best.n)best={n:L,src:s,p:t.slice(0,200)};}`;
+
     const payload = JSON.stringify({ html, text });
     const res = await run(
       `var p=${payload};` +
@@ -2507,7 +2616,11 @@ class PageManager {
       `dt.setData('text/plain',p.text||p.html.replace(/<[^>]+>/g,' ').replace(/&nbsp;/g,' ').replace(/\\s+/g,' ').trim());` +
       `var ev=new ClipboardEvent('paste',{clipboardData:dt,bubbles:true,cancelable:true,composed:true});` +
       `var notPrevented=ed.dispatchEvent(ev);` +
-      `return {ok:true,prevented:!notPrevented,tag:ed.tagName};`
+      // 同步读一次：CodeMirror 6 / ProseMirror / Quill 都在 paste handler 里
+      // 同步写文档，这一刻就能读到；异步提交的（Draft.js 走 setTimeout）
+      // 读不到，交给后面的延迟采样。
+      landedProbe('ed') +
+      `return {ok:true,prevented:!notPrevented,tag:ed.tagName,landed0:best};`
     );
     if (!res || !res.ok) {
       return { success: false, error: (res && res.err) || 'paste failed', method: 'synthetic-clipboard-event' };
@@ -2522,19 +2635,45 @@ class PageManager {
         consumed: false,
       };
     }
-    // 落盘校验：读回编辑器内容。归一化沿用 P0-2 修过的口径（换行会被编辑器
-    // 膨胀，逐字比对必然失配）。只给 html 时无法文本比对，退而检查"有内容"。
-    await new Promise((r) => setTimeout(r, 350)); // 编辑器处理粘贴多为异步（React 提交）
-    const landed = await run(`var e=${deepActiveExpr()};return {text:(e&&(e.innerText||e.value||''))||'',html:(e&&e.innerHTML||'')};`);
-    const landedText = (landed && landed.text) || '';
-    const landedLen = landedText.replace(/\s+/g, '').length;
+    // 落盘校验：读回编辑器内容。
+    //
+    // 为什么不能只读一次、也不能只读 activeElement（2026-10-19 掘金实机）：
+    //   掘金（CodeMirror 6）粘贴成功、正文完整，回执却是 landed_chars: 0。
+    //   根因是读回走了 deepActive —— 那一刻 activeElement 并不是编辑面（编辑器
+    //   把焦点放在 .cm-scroller 上，真正的内容在 .cm-content），于是读到空。
+    //   调用方看到 0 就再粘一次，正文变成两份。**假阴性比漏报贵得多**：它直接
+    //   诱发重复写入，而重复写入是这件工具最不该制造的事故。
+    //
+    // 所以现在：① 以**刚粘贴的那个元素**为主，activeElement / 内部编辑面 /
+    // 上层容器依次兜底；② 三次采样（同步 / +350ms / +900ms）取最大值，覆盖
+    // 异步提交；③ 真读不到时给 landed_chars: null 而不是 0 —— 0 是"确定空"，
+    // null 是"读不到"，这两种事实对调用方的决策完全相反。
+    let landed = res.landed0 && res.landed0.n > 0 ? res.landed0 : null;
+    let samples = 1;
+    for (const wait of [350, 900]) {
+      if (landed) break;
+      await new Promise((r) => setTimeout(r, wait));
+      const again = await run(
+        `var t=${findRefExpr(JSON.stringify(aiId))}||document.activeElement;if(!t)return {n:0,src:'none',p:''};` +
+        landedProbe('t') + `return best;`
+      ).catch(() => null);
+      samples++;
+      if (again && again.n > 0) landed = again;
+    }
+    const landedLen = landed ? landed.n : 0;
     if (!landedLen) {
       return {
         success: false,
-        error: 'paste was consumed but nothing landed — the editor may have rejected the payload (unsanitized HTML?). Read the editor content back to confirm.',
+        // 措辞从 "nothing landed"（断言）改成 "could not be read back"（观测）。
+        // 前者在掘金那种场景里是错的 —— 它会把一次成功的粘贴报成失败，而
+        // agent 对 success:false 的标准反应就是重试一次。
+        error: 'paste was consumed but the editor content could not be read back — this is NOT proof that nothing landed (CodeMirror-style editors keep the document outside the focused node). '
+          + 'Verify with get_value on the same ref before doing anything else; re-pasting on a live editor duplicates the content.',
         method: 'synthetic-clipboard-event',
         consumed: true,
-        landed_chars: 0,
+        landed_chars: null,
+        landed_verified: false,
+        landed_samples: samples,
       };
     }
     return {
@@ -2543,8 +2682,11 @@ class PageManager {
       consumed: true,
       in_frame: inFrame,
       landed_chars: landedLen,
-      // 只给 html 时调用方无法预知文本形态，把读回内容捎上，省一轮查询。
-      ...(html && !text ? { landed_preview: landedText.slice(0, 200) } : {}),
+      landed_verified: true,
+      // 读回来源：'target' 最可信；'host' 是容器兜底，可能把页面别处的文字
+      // 算进来 —— 长度只用于"有没有落地"，不做逐字比对，所以偏大是安全方向。
+      landed_source: landed.src,
+      ...(html && !text ? { landed_preview: landed.p || '' } : {}),
     };
   }
 

package/src/preload/actions.cjs

@@ -160,10 +160,42 @@ function doPaste(el, params) {
   if (notPrevented) {
     return {
       success: false,
+      consumed: false,
       error: "paste event was not consumed by the page (defaultPrevented=false) — try a child node ref, or setContent for plain text"
     };
   }
-  return { success: true, method: "synthetic-clipboard-event" };
+  // 读回口径与 page_manager._pasteViaCdp 完全一致：候选里取最长，读不到给
+  // null 而不是 0。为什么必须有：preload 这条路以前**只要页面 preventDefault
+  // 就报 success**，连"有没有内容"都不看 —— 这正是"工具说成功、页面没变"
+  // 最纯粹的一种来源。0 表示确定空（可安全重试），null 表示读不到（先核对）。
+  var best = { n: 0, src: "target", p: "" };
+  var cands = [editor];
+  try {
+    if (document.activeElement && document.activeElement !== editor) cands.push(document.activeElement);
+  } catch (_e) {}
+  try {
+    var q = editor.querySelector && editor.querySelector("[contenteditable=true],textarea,.cm-content,.ProseMirror");
+    if (q) cands.push(q);
+  } catch (_e) {}
+  for (var i = 0; i < cands.length; i++) {
+    var e = cands[i], t = "";
+    try { t = (e.value != null) ? String(e.value) : String(e.innerText || e.textContent || ""); } catch (_e) {}
+    t = t.replace(/\s+/g, " ");
+    var L = t.replace(/ /g, "").length;
+    if (L > best.n) best = { n: L, src: (i === 0 ? "target" : "candidate"), p: t.slice(0, 200) };
+  }
+  var out = {
+    success: true,
+    method: "synthetic-clipboard-event",
+    consumed: true,
+    landed_chars: best.n > 0 ? best.n : null,
+    landed_verified: best.n > 0,
+  };
+  if (best.n > 0) out.landed_source = best.src;
+  if (!best.n) {
+    out.effect_hint = "paste was consumed but the editor content could not be read back — verify with get_value before retrying; re-pasting on a live editor duplicates the content.";
+  }
+  return out;
 }
 
 // setContent — write to any editor type including Draft.js/ProseMirror

package/src/shared/editors_probe.js

@@ -0,0 +1,96 @@
+// shared/editors_probe.js — DOM 侧的可编辑区清单，给**默认读法**补消歧信息。
+//
+// 为什么 AX 那边（main/axExtractor.js 的 summarizeEditors）已经有了一份、
+// 这里还要再来一份：两条读法覆盖的是同一批页面，但 browse_get_tree 的**默认**
+// 路径走 DOM extractor，不产出 `editable` 状态串，也就没有可编辑区索引。
+// 只在 AX 路径修，等于告诉用户"想知道哪个是正文请加 ax:true" —— 而默认路径
+// 恰恰是最常被用的那条。坑必须在自己所在的那条路上修掉。
+//
+// 只读、只碰四个属性（rect / placeholder / aria-label / data-ai-id），不写 DOM。
+export const EDITORS_PROBE_JS = `(function(){
+  try{
+    var sel='input,textarea,[contenteditable=true],[contenteditable=""],[role=searchbox]';
+    var all=document.querySelectorAll(sel),out=[];
+    for(var i=0;i<all.length&&out.length<40;i++){
+      var e=all[i],r;
+      try{r=e.getBoundingClientRect();}catch(_e){continue;}
+      var w=Math.round(r.width),h=Math.round(r.height);
+      if(w*h<800) continue;
+      var tag=e.tagName.toLowerCase();
+      if(tag==='input'){
+        var ty=String(e.type||'text').toLowerCase();
+        if(/^(hidden|submit|button|checkbox|radio|file|reset|image|color|range)$/.test(ty)) continue;
+      }
+      var ce=e.getAttribute('contenteditable');
+      var et=(ce==='true'||ce==='')?'richtext':(tag==='textarea'?'textarea':'textbox');
+      var ph=String(e.getAttribute('placeholder')||'').slice(0,40);
+      out.push({
+        ref:String(e.getAttribute('data-ai-id')||''),
+        role:String(e.getAttribute('role')||'textbox'),
+        editor_type:et,w:w,h:h,
+        label:String(e.getAttribute('aria-label')||'').slice(0,40),
+        placeholder:ph,
+        readonly:!!e.readOnly,
+        type:tag==='input'?String(e.type||'text').toLowerCase():''
+      });
+    }
+    return out;
+  }catch(e){return {__err:String((e&&e.message)||e)}}
+})()`;
+
+// 与 axExtractor 的 SEARCH_LIKE 必须一致 —— 两处口径分叉会让"同一个页面在
+// ax:true 与默认读法下给出相反的 primary"，那比没有索引更糟。这里不 import
+// 是因为 axExtractor 属于 main 进程模块，而本文件也被 preload 侧测试引用。
+export const SEARCH_LIKE = /搜索|查找|检索|search|find/i;
+
+const MIN_AREA = 800;
+const PRIMARY_MIN_AREA = 20000;
+
+/**
+ * 把 DOM 探针的原始行转换成与 AX 路径**同构**的 editors 数组。
+ * 纯函数，可直接单测（不需要 Electron）。
+ *
+ * @param {Array} rows      EDITORS_PROBE_JS 的返回值
+ * @param {Set}   knownRefs 树里真实存在的 ref（探针是全局扫的，包含被剪枝的节点）
+ * @returns {Array|null}    <2 个有效编辑区时返回 null
+ */
+export function buildEditorsIndex(rows, knownRefs) {
+  if (!Array.isArray(rows)) return null;
+  const known = knownRefs instanceof Set ? knownRefs : new Set(knownRefs || []);
+  const list = [];
+  for (const r of rows) {
+    if (!r || !r.ref || (known.size && !known.has(r.ref))) continue;
+    const w = Number(r.w) || 0;
+    const h = Number(r.h) || 0;
+    const area = w * h;
+    if (area < MIN_AREA) continue;
+    const ph = String(r.placeholder || '');
+    const label = String(r.label || '');
+    const searchlike = r.role === 'searchbox'
+      || r.type === 'search'
+      || SEARCH_LIKE.test(ph)
+      || SEARCH_LIKE.test(label);
+    list.push({
+      ref: r.ref,
+      role: r.role || 'textbox',
+      editor_type: r.editor_type || 'textbox',
+      label: label.slice(0, 40),
+      ...(ph ? { placeholder: ph.slice(0, 40) } : {}),
+      w, h, area,
+      readonly: !!r.readonly,
+      ...(searchlike ? { searchlike: true } : {}),
+    });
+  }
+  if (list.length < 2) return null;
+  const sorted = list.sort((a, b) => b.area - a.area).slice(0, 8);
+  let primary = null;
+  for (const e of sorted) {
+    if (e.readonly || e.searchlike) continue;
+    if (e.area < PRIMARY_MIN_AREA) break;
+    primary = e.ref;
+    break;
+  }
+  return sorted.map(({ area, ...rest }) => (rest.ref === primary ? { ...rest, primary: true } : rest));
+}
+
+export default { EDITORS_PROBE_JS, buildEditorsIndex, SEARCH_LIKE };

package/src/shared/effect_state.js

@@ -67,6 +67,11 @@ const PARTIAL_PATTERNS = [
   /may have partially applied/i,
   /not consumed by the page/i,
   /consumed but nothing landed/i,
+  // 2026-10-19 之后 paste 的读回口径：读不到 ≠ 没落地（CodeMirror 把正文放在
+  // 焦点节点之外）。这条必须落在 partial 而不是 no-effect 里 —— 判成 none 会
+  // 告诉 agent"照原样重试是安全的"，而在活着的编辑器上重试就是内容翻倍。
+  // 旧文案保留在上面，历史回执与日志仍要能被正确分类。
+  /could not be read back/i,
   /interrupted|disconnected|target closed|debugger detached/i,
   /deadline exceeded|timed? ?out/i,
 ];

package/src/shared/page_probe.js

@@ -0,0 +1,154 @@
+// shared/page_probe.js — "这一步到底改动了页面没有"必须由工具回答，不能让 agent 猜。
+//
+// 事故（2026-10-19，B站投稿）：
+//   browse_act click 返回 success:true，agent 以为投递成功，继续往下走。
+//   实际点中的是**外层** `<div class="submit-container">`，真正的可点元素是它
+//   里面的 `<span class="submit-add">`。页面一个字节都没变，回执却是一片绿。
+//   错误在第三步之后才暴露 —— 这时已经不可能靠"回头看"把因果连起来。
+//
+// 为什么这必须是原语而不是让调用方自查：
+//   调用方（模型）没有"我刚才那一手到底生效了吗"的直觉。它拿到的 success
+//   只说明**命令发出去了**，不说明**页面接住了**。中间这层语义只能由掌握
+//   渲染进程的工具补上。否则每个站点、每个动作都要调用方自己写一遍快照对比，
+//   而它连"该在什么时候拍快照"都不知道（拍早了页面还没渲染）。
+//
+// 设计取舍：
+//   1. 只读、极轻。一次 evaluate 拿 5 个标量，不碰 AX 树、不截图。
+//      动作用户关心的时延是"点击后多久有反馈"，多 2 次 evaluate（各 ~1ms）
+//      换掉一整类静默失败，值得。
+//   2. 指纹取**全量文本 hash + DOM 节点数 + 焦点元素内容长度 + URL**。
+//      只看文本会漏掉"弹窗打开但文案相同"，只看节点数会漏掉"同位置替换"。
+//      四个信号任一变化即视为 changed —— 宁可报 changed:true 放过，
+//      不可报 false 冤枉（false 会诱导 agent 重复提交）。
+//   3. changed:false 不等于失败。点击一个已选中的 radio、关闭一个已关的抽屉，
+//      都是合法的无变化。所以这里只**陈述观测**，把结论留给调用方，并配一句
+//      可执行的下一步。真正"该有变化却无变化"的判定放在 MUST_HAVE_EFFECT 里，
+//      只对写类动作（输入/粘贴/上传）生效 —— 那些动作没有"合法无变化"的情形。
+//
+// 4. 主文档视角的边界：探针只读 top document。OOPIF 子帧里的变化它看不见，
+//    因此 changed:false 的措辞是"主文档未变化"，不是"什么都没发生"。这个区别
+//    写进 hint 里，避免把 B站 read-editor 那种跨进程编辑器误判成失败。
+
+// 页面内执行的探针。纯读，不写任何属性，不触发任何事件。
+// 返回的字段都用单字母：它要跨 RPC 边界回传，越短越好，语义在下面注释里。
+//   t = body 全量文本长度（折叠空白后，与 DEFAULT_SNAPSHOT_JS 的口径一致）
+//   h = 该文本的 djb2 hash（base36）—— 长度相同的内容替换靠它抓
+//   d = 当前**可编辑**焦点元素的内容长度（深浅穿透 shadow root）—— 输入类动作的主信号。
+//       只算 input/textarea/select/contenteditable：点击一个普通 div 也会让
+//       activeElement 变过去，若把它的 innerText 算进来，每次"点了个没反应的
+//       按钮"都会因为焦点跑过去而报 page_changed:true —— 那等于把这个探针
+//       最该抓的场景（点了没反应）全丢掉。实测于 2026-10-22 的 fixture 回归。
+//   n = DOM 元素总数（粗粒度结构变化：弹窗、列表插入）
+//   u = location.href（SPA 路由跳转）
+export const PAGE_PROBE_JS = `(function(){
+  try{
+    var b=document.body||document.documentElement;
+    var t=(b&&(b.innerText||b.textContent))||'';
+    t=t.replace(/\\s+/g,' ');
+    var h=5381;
+    for(var i=0;i<t.length;i++)h=((h<<5)+h+t.charCodeAt(i))|0;
+    var a=document.activeElement,g=0;
+    try{ while(a&&a.shadowRoot&&a.shadowRoot.activeElement&&g++<8)a=a.shadowRoot.activeElement; }catch(_e){}
+    var dv='';
+    try{
+      if(a){
+        var tg=a.tagName;
+        var ed=(a.isContentEditable===true)||tg==='INPUT'||tg==='TEXTAREA'||tg==='SELECT';
+        if(ed) dv=(a.value!=null)?String(a.value):(a.innerText||a.textContent||'');
+      }
+    }catch(_e){}
+    var n=0;
+    try{ n=document.getElementsByTagName('*').length; }catch(_e){}
+    return {t:t.length,h:(h>>>0).toString(36),d:(dv||'').replace(/\\s+/g,'').length,n:n,u:String(location.href)};
+  }catch(e){ return {__err:String((e&&e.message)||e)}; }
+})()`;
+
+// 哪些动作值得拍前后快照。只读动作（get_value / focus / hover / scroll_to）
+// 不拍：它们本来就不该改页面，拍了只是白花两次往返。
+// wheel 也不拍：滚动会改变 scroll 位置但 body.innerText 不变，节点数也不变，
+// 必然报 false —— 那是个稳定的假阴性，不如不报。
+const PROBED_ACTIONS = new Set([
+  'click', 'type', 'setContent', 'clear', 'paste', 'upload', 'drag', 'press',
+]);
+
+// 这些动作**没有"合法无变化"的情形**：输入/粘贴/上传成功就一定有内容落地。
+// 它们报 page_changed:false 时给强提示（并说明先读回再决定）。
+const MUST_HAVE_EFFECT = new Set(['type', 'setContent', 'clear', 'paste', 'upload']);
+
+export function shouldProbe(action) {
+  return PROBED_ACTIONS.has(String(action || ''));
+}
+
+// 动作返回后到拍快照之间要等多久，让 React/Vue 的提交与路由跳转落地。
+// 写类动作内部已经等过一轮（paste 350ms、type 有 input 校验），只需短等；
+// click 触发弹窗/路由时框架往往在下一个 microtask + 一帧后才渲染，给足 220ms。
+export function settleMs(action) {
+  return MUST_HAVE_EFFECT.has(String(action || '')) ? 80 : 220;
+}
+
+const HINT_WRITE =
+  'page_changed=false: the action returned success but the main document is byte-identical '
+  + '(same text hash, same DOM node count, same focused-field length). The payload most likely '
+  + 'never landed — a wrapper element was targeted, or the editor listens on a child surface. '
+  + 'Read the element back with get_value BEFORE retrying: a second paste on a live editor '
+  + 'duplicates the content instead of fixing it.';
+
+const HINT_CLICK =
+  'page_changed=false: the action returned success but the main document did not change. Two '
+  + 'common causes: (a) the click hit a wrapper element and the real handler is on a deeper '
+  + 'node — re-read the tree and target the inner <span>/<a>/<button>; (b) the control was '
+  + 'already in the requested state, in which case there is nothing to retry. If the effect was '
+  + 'expected inside an out-of-process iframe, this probe cannot see it — verify with '
+  + 'get_tree/screenshot instead.';
+
+/**
+ * 比较前后两次探针。纯函数，无 Electron 依赖，可直接单测。
+ * @returns {{changed: boolean|null, delta: object|null}}
+ *          changed=null 表示数据不可比（某次探针失败），调用方应忽略而不是当成 false。
+ */
+export function diffProbe(before, after) {
+  const ok = (p) => p && typeof p === 'object' && !p.__err && typeof p.h === 'string';
+  if (!ok(before) || !ok(after)) return { changed: null, delta: null };
+  const delta = {
+    text_chars: (Number(after.t) || 0) - (Number(before.t) || 0),
+    dom_nodes: (Number(after.n) || 0) - (Number(before.n) || 0),
+    focused_chars: (Number(after.d) || 0) - (Number(before.d) || 0),
+  };
+  const changed = before.h !== after.h
+    || (Number(before.n) || 0) !== (Number(after.n) || 0)
+    || (Number(before.d) || 0) !== (Number(after.d) || 0)
+    || before.u !== after.u;
+  return { changed, delta };
+}
+
+/**
+ * 把观测结果写进动作回执。纯函数（返回新对象）。
+ *
+ * 只在 changed === false 时附加 page_delta 和 effect_hint：
+ * 正常路径（changed:true）不多说一个字，避免每步回执都多两行噪音。
+ */
+export function applyProbe(res, before, after, action) {
+  if (!res || typeof res !== 'object') return res;
+  const d = diffProbe(before, after);
+  if (d.changed === null) return res;
+  const out = { ...res, page_changed: d.changed };
+  if (d.changed) return out;
+  out.page_delta = d.delta;
+  const isWrite = MUST_HAVE_EFFECT.has(String(action || ''));
+  if (!out.effect_hint) {
+    out.effect_hint = isWrite ? HINT_WRITE : HINT_CLICK;
+  }
+  // 写类动作 + 主文档零变化 = 内容很可能没落地。把 effect_state 从 committed
+  // 降回 unknown，否则回执是自相矛盾的：success:true + effect_state:committed
+  // 等于告诉 agent"这一手已经生效，别重试"，而观测说它没生效。
+  //
+  // 为什么是 unknown 而不是 none：探针只看主文档，OOPIF 子帧里的编辑器
+  // （B站 read-editor）变化它看不见。unknown + verify_first 是唯一诚实的选择。
+  if (isWrite && out.success === true) {
+    out.effect_state = 'unknown';
+    out.retry = 'verify_first';
+  }
+  return out;
+}
+
+export default { PAGE_PROBE_JS, shouldProbe, settleMs, diffProbe, applyProbe };

package/src/shared/version.js

@@ -2,4 +2,4 @@
 // Kept in JS (not imported from package.json) to avoid Node import-attribute
 // (JSON module) compatibility issues inside Electron. package.json "version"
 // is manually synced to this value; tests assert they match.
-export const VERSION = '2.1.1';
+export const VERSION = '2.1.2';