agentpage 0.0.54 → 0.0.55

package/README.md

@@ -79,7 +79,8 @@ npm install agentpage
 
 - **Prompt + Tools + 路由三层解耦**：可以快速把"可执行 AI 能力"植入现有前端系统，按路由渐进式接入，支持"项目级工具 + 路由级工具"组合。
 - **增量任务消费协议（REMAINING）**：任务不是一次性执行，而是逐轮消费收敛。每轮只做当前快照可执行的动作，通过 `REMAINING` 协议跟踪进度，支持协议修复和启发式回退，确保复杂多步任务稳定收敛。
-- **9 层保护机制**：冗余拦截、快照防抖、元素恢复、Not-found 重试对话流、导航刷新、空转检测、重复批次防自转、协议修复、快照指纹变化检测 —— 目标是**稳定收敛**，而不是偶然成功。
+- **原始目标锚定（Original Goal Anchor）**：Round 1+ 每轮消息注入用户原始输入作为任务对照组，防止模型在多步执行过程中偏航（如把“去 X 仓库创建 issue”误解为“创建 X 仓库”）。
+- **12 层保护机制**：冗余拦截、快照防抖、元素恢复、Not-found 重试对话流、导航刷新、空转检测、重复批次防自转、协议修复、快照指纹变化检测、无效点击拦截与循环检测、附近可点击元素推荐、原始目标锚定 —— 目标是**稳定收敛**，而不是偶然成功。
 - **Playwright 级别交互语义**：完整 pointer/mouse 事件链、4 种 scrollIntoView 策略轮换、actionability 五重检查（可见/稳定/可用/可编辑/遮挡）、智能重定向 retarget、隐藏控件代理点击（ElementPlus/AntD）、`select_option` value/label/index 三策略。
 - **运行时事件信号追踪**：通过 `EventTarget.prototype` 补丁全局追踪事件绑定，快照中输出 `listeners="clk,inp,chg"` 信号，帮助 AI 精准识别真实可交互元素，而非猜测。
 - **效果验证机制（Effect Check）**：每轮行动前自动检查上轮操作是否在当前快照中生效，未生效则尝试邻近元素，避免重复点击无效目标。
@@ -233,6 +234,9 @@ Round 3: 执行 C → REMAINING: DONE
 | 协议修复回合 | remaining 未完成却无工具调用 | 注入强约束提示 |
 | 轮次稳定等待 | 本轮有 DOM 变化动作 | loading hidden + DOM quiet（200ms/4s） |
 | 快照指纹变化检测 | 本轮有 DOM 变更动作且行动后指纹不变 | 注入 `Snapshot unchanged` 提示，强制模型换目标 |
+| 无效点击拦截与循环检测 | 快照未变时记录无效 click；近 4 轮在 ≤2 个目标间循环 | 拦截重复无效点击；循环检测后将所有循环目标加入拦截集 |
+| 附近可点击元素推荐 | 点击被拦截或证实无效 | 从快照中查找目标附近 15 行内有点击信号的元素，按距离推荐 |
+| 原始目标锚定 | Round 1+ 每轮 | 注入用户原始任务作为对照组，防止多步执行中偏航 |
 
 ### 5. 停机条件
 

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/core/tool-registry.ts","../src/core/types.ts","../src/core/agent-loop/types.ts","../src/web/ref-store.ts","../src/web/tools/page-info-tool.ts","../src/web/ui/panel.ts","../src/web/tools/dom-tool.ts","../src/web/tools/navigate-tool.ts","../src/web/tools/wait-tool.ts","../src/web/tools/evaluate-tool.ts","../src/web/messaging.ts","../src/web/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/core/tool-registry.ts","../src/core/types.ts","../src/core/agent-loop/types.ts","../src/web/ref-store.ts","../src/web/tools/page-info-tool.ts","../src/web/ui/panel.ts","../src/web/tools/dom-tool.ts","../src/web/tools/navigate-tool.ts","../src/web/tools/wait-tool.ts","../src/web/tools/evaluate-tool.ts","../src/web/messaging.ts","../src/web/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -7,13 +7,32 @@ import { computePosition, flip, offset, shift } from "@floating-ui/dom";
 *
 * 统一集中在该文件，避免在主循环中散落“魔法数字”。
 */
+/** 单次 chat 最大循环轮次（超过后强制停机） */
 const DEFAULT_MAX_ROUNDS = 40;
+/** 元素未找到恢复时的等待时长（毫秒），等待后刷新快照重新定位目标 */
 const DEFAULT_RECOVERY_WAIT_MS = 100;
+/** 同一工具调用（相同 name + input）命中元素未找到时的最大自动恢复轮次 */
 const DEFAULT_ACTION_RECOVERY_ROUNDS = 2;
+/** 元素未找到重试对话流的最大尝试次数（聚合失败工具 + 快照 + attempt 标注发给 AI） */
 const DEFAULT_NOT_FOUND_RETRY_ROUNDS = 2;
+/** 元素未找到重试对话流中每次重试前的等待时长（毫秒），等待页面异步渲染完成 */
 const DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 1e3;
+/** 轮次后稳定等待的总超时（毫秒）：包含 loading 隐藏等待 + DOM 静默等待的总上限 */
 const DEFAULT_ROUND_STABILITY_WAIT_TIMEOUT_MS = 4e3;
+/** 轮次后 DOM 静默窗口（毫秒）：DOM 在此时间内无变化视为稳定 */
 const DEFAULT_ROUND_STABILITY_WAIT_QUIET_MS = 200;
+/**
+* 轮次后稳定等待的默认 loading 指示器选择器列表。
+*
+* 覆盖主流 UI 框架的加载态组件：
+* - AntD：`.ant-spin` / `.ant-spin-spinning` / `.ant-skeleton`
+* - Element Plus：`.el-loading-mask`
+* - BK（蓝鲸）：`.bk-loading` / `.bk-spin-loading` / `.bk-skeleton` / `.bk-sideslider-loading`
+* - TDesign（TD）：`.t-loading` / `.t-skeleton` / `.t-skeleton__row`
+* - 通用：`[aria-busy="true"]` / `.skeleton` / `.loading`
+*
+* 用户自定义的 `roundStabilityWait.loadingSelectors` 会与此列表合并去重，不会覆盖默认值。
+*/
 const DEFAULT_ROUND_STABILITY_WAIT_LOADING_SELECTORS = [
 	".ant-spin",
 	".ant-spin-spinning",
@@ -30,11 +49,11 @@ const DEFAULT_ROUND_STABILITY_WAIT_LOADING_SELECTORS = [
 	".skeleton",
 	".loading"
 ];
-/** 快照起始标记 — 用于在消息中识别快照边界 */
+/** 快照起始标记 — 用于在消息中定位快照边界，配合 stripSnapshotFromPrompt() 实现旧快照剥离 */
 const SNAPSHOT_START = "<!-- SNAPSHOT_START -->";
-/** 快照结束标记 */
+/** 快照结束标记 — 与 SNAPSHOT_START 配对使用 */
 const SNAPSHOT_END = "<!-- SNAPSHOT_END -->";
-/** 旧快照被替换后的占位文本 */
+/** 旧快照被替换后的占位文本 — 防止过期快照干扰模型决策 */
 const SNAPSHOT_OUTDATED = "[此快照已过期，请参考对话中最新的快照]";
 
 //#endregion
@@ -43,6 +62,12 @@ const SNAPSHOT_OUTDATED = "[此快照已过期，请参考对话中最新的快
 * 异步睡眠。
 *
 * 用于重试等待、节流等待等场景。
+*
+* @example
+* ```ts
+* await sleep(1000); // 等待 1 秒
+* await sleep(100);  // 元素恢复前等待 100ms
+* ```
 */
 function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
@@ -52,6 +77,12 @@ function sleep$1(ms) {
 *
 * 工具返回 content 可能是 string 或 object；这里统一转成 string，
 * 便于日志、错误判定、摘要拼接。
+*
+* @example
+* ```ts
+* toContentString("已点击按钮")          // → "已点击按钮"
+* toContentString({ code: "OK", n: 1 }) // → '{\n  "code": "OK",\n  "n": 1\n}'
+* ```
 */
 function toContentString(content) {
 	return typeof content === "string" ? content : JSON.stringify(content, null, 2);
@@ -62,6 +93,15 @@ function toContentString(content) {
 * 约定格式：`SNAPSHOT_HINT: EXPAND_CHILDREN #ref1 #ref2`
 *
 * 返回：去掉 `#` 前缀后的 ref id 列表。
+*
+* @example
+* ```ts
+* parseSnapshotExpandHints("SNAPSHOT_HINT: EXPAND_CHILDREN #a1b2c #x9k3d")
+* // → ["a1b2c", "x9k3d"]
+*
+* parseSnapshotExpandHints("REMAINING: DONE")
+* // → []（无匹配）
+* ```
 */
 function parseSnapshotExpandHints(text) {
 	if (!text) return [];
@@ -78,8 +118,14 @@ function parseSnapshotExpandHints(text) {
 * 提取 hash selector 的 ref。
 *
 * 仅处理“纯 hash 选择器”，例如 `#1rv01x`。
-* 如果是复杂 CSS（如 `.x #id`）会返回 null，避免误判。
-*/
+* 如果是复杂 CSS（如 `.x #id`）会返回 null，避免误判。 *
+* @example
+* ```ts
+* extractHashSelectorRef({ selector: "#1rv01x" })   // → "1rv01x"
+* extractHashSelectorRef({ selector: ".btn #id" })  // → null（复杂选择器）
+* extractHashSelectorRef({ selector: "div" })        // → null（非 hash）
+* extractHashSelectorRef({})                          // → null
+* ``` */
 function extractHashSelectorRef(toolInput) {
 	if (!toolInput || typeof toolInput !== "object") return null;
 	const selector = toolInput.selector;
@@ -95,6 +141,16 @@ function extractHashSelectorRef(toolInput) {
 * 再计算 djb2 哈希，确保指纹只反映真实页面结构和文本差异。
 *
 * 用途：轮次行动前后各算一次指纹，若一致说明操作未产生任何可见效果。
+*
+* @example
+* ```ts
+* const before = computeSnapshotFingerprint('[button] "提交" #a1b2c');
+* const after  = computeSnapshotFingerprint('[button] "提交" #x9y8z');
+* before === after  // → true（内容相同，仅 hashID 变化）
+*
+* const changed = computeSnapshotFingerprint('[button] "已提交" #a1b2c');
+* before === changed  // → false（文本变化 → 指纹不同）
+* ```
 */
 function computeSnapshotFingerprint(snapshot) {
 	if (!snapshot) return "";
@@ -129,6 +185,25 @@ function _djb2(str) {
 * - `INEFFECTIVE_CLICK_BLOCKED` 拦截消息中附带推荐
 * - "Snapshot unchanged" 提示中附带推荐
 * - 交替循环检测提示中附带推荐
+*
+* @example
+* ```ts
+* // 假设快照片段：
+* //  [tr] listeners="clk" #14d1zek
+* //    [td]
+* //      [span] "forkCte" listeners="blr,fcs" #fkbidm
+* //    [td]
+* //      [a] "admin/forkCte" href="/repo/1" listeners="clk" #c3hyqd
+*
+* findNearbyClickTargets(snapshot, "#fkbidm")
+* // → [
+* //   '#c3hyqd ([a] "admin/forkCte" listeners="clk")',   // 距离近
+* //   '#14d1zek ([tr] "" listeners="clk")',                // 距离稍远
+* // ]
+*
+* findNearbyClickTargets(snapshot, "#fkbidm", new Set(["#14d1zek"]))
+* // → ['#c3hyqd ([a] "admin/forkCte" listeners="clk")']  // 排除 #14d1zek
+* ```
 */
 function findNearbyClickTargets(snapshot, selector, excludeSelectors, windowSize = 15) {
 	if (!snapshot || !selector) return [];
@@ -183,8 +258,18 @@ function findNearbyClickTargets(snapshot, selector, excludeSelectors, windowSize
 * 构建任务数组。
 *
 * 作用：把一轮工具调用规整成稳定字符串数组，
-* 用于“上一轮任务回显”和“重复批次检测”。
-*/
+* 用于“上一轮任务回显”和“重复批次检测”。 *
+* @example
+* ```ts
+* buildTaskArray([
+*   { name: "dom", input: { action: "click", selector: "#a1b2c" } },
+*   { name: "dom", input: { action: "fill", selector: "#x9k3d", value: "hello" } },
+* ])
+* // → [
+* //   'dom:{"action":"click","selector":"#a1b2c"}',
+* //   'dom:{"action":"fill","selector":"#x9k3d","value":"hello"}',
+* // ]
+* ``` */
 function buildTaskArray(toolCalls) {
 	return toolCalls.map((tc) => `${tc.name}:${JSON.stringify(tc.input)}`);
 }
@@ -193,8 +278,17 @@ function buildTaskArray(toolCalls) {
 *
 * 优先保留 REMAINING；否则保留首段摘要，避免长文本污染上下文。
 *
-* 返回字符串会被注入下一轮消息，作为“上一轮模型输出摘要”。
-*/
+* 返回字符串会被注入下一轮消息，作为“上一轮模型输出摘要”。 *
+* @example
+* ```ts
+* normalizeModelOutput("操作完成\nREMAINING: 填写表单")
+* // → "REMAINING: 填写表单"
+*
+* normalizeModelOutput("已点击按钮，等待页面跳转...")
+* // → "已点击按钮，等待页面跳转..."（首段摘要，最多 220 字符）
+*
+* normalizeModelOutput(undefined)  // → ""
+* ``` */
 function normalizeModelOutput(text) {
 	if (!text) return "";
 	const trimmed = text.trim();
@@ -218,6 +312,21 @@ function normalizeModelOutput(text) {
 * - `REMAINING: DONE` → 返回 `""`（任务完成）
 * - `REMAINING: <text>` → 返回 `<text>`
 * - DONE 后面尾随的摘要文本会被忽略（模型常在 DONE 后附加总结）
+*
+* @example
+* ```ts
+* parseRemainingInstruction("REMAINING: 填写表单并提交")
+* // → "填写表单并提交"
+*
+* parseRemainingInstruction("REMAINING: DONE")
+* // → ""（任务完成）
+*
+* parseRemainingInstruction("REMAINING: DONE - 已完成所有操作")
+* // → ""（DONE 后的摘要被忽略）
+*
+* parseRemainingInstruction("我已经点击了按钮")
+* // → null（无 REMAINING 协议）
+* ```
 */
 function parseRemainingInstruction(text) {
 	if (!text) return null;
@@ -238,6 +347,18 @@ function parseRemainingInstruction(text) {
 * 策略：
 * - 有 REMAINING 协议 -> 使用模型给出的 nextInstruction
 * - 无协议 -> 保持 currentInstruction 不变（由上层决定是否启发式推进）
+*
+* @example
+* ```ts
+* deriveNextInstruction("REMAINING: 提交表单", "填写表单并提交")
+* // → { nextInstruction: "提交表单", hasRemainingProtocol: true }
+*
+* deriveNextInstruction("REMAINING: DONE", "提交表单")
+* // → { nextInstruction: "", hasRemainingProtocol: true }
+*
+* deriveNextInstruction("已点击按钮", "填写表单并提交")
+* // → { nextInstruction: "填写表单并提交", hasRemainingProtocol: false }
+* ```
 */
 function deriveNextInstruction(text, currentInstruction) {
 	const parsed = parseRemainingInstruction(text);
@@ -255,8 +376,21 @@ function deriveNextInstruction(text, currentInstruction) {
 *
 * 用于协议缺失但本轮有执行动作时，按线性步骤剔除已执行数量。
 *
-* 这是“保守推进”策略，不保证语义完美，但能避免 remaining 长期不变。
-*/
+* 这是“保守推进”策略，不保证语义完美，但能避免 remaining 长期不变。 *
+* @example
+* ```ts
+* reduceRemainingHeuristically("点击按钮 然后 填写表单 然后 提交", 1)
+* // → "填写表单 -> 提交"（剔除第 1 步）
+*
+* reduceRemainingHeuristically("点击按钮 然后 填写表单 然后 提交", 2)
+* // → "提交"（剔除前 2 步）
+*
+* reduceRemainingHeuristically("点击按钮 然后 填写表单 然后 提交", 5)
+* // → ""（所有步骤已完成）
+*
+* reduceRemainingHeuristically("完成任务", 1)
+* // → "完成任务"（无法拆分，原样返回）
+* ``` */
 function reduceRemainingHeuristically(currentInstruction, executedCount) {
 	if (!currentInstruction.trim() || executedCount <= 0) return currentInstruction;
 	const parts = currentInstruction.replace(/\s+/g, " ").replace(/(->|=>|→)/g, " 然后 ").replace(/[，,。；;]/g, " 然后 ").split(/\s*(?:然后|再|并且|并|接着|随后|之后)\s*/g).map((part) => part.trim()).filter(Boolean);
@@ -272,9 +406,20 @@ function reduceRemainingHeuristically(currentInstruction, executedCount) {
 *
 * 当前规则：
 * - `navigate.*` 一律断轮
+* - `dom.click` 断轮
 * - `dom.press` 仅 Enter 断轮
 * - `evaluate` 断轮
 * - 其他动作默认不断轮
+*
+* @example
+* ```ts
+* shouldForceRoundBreak("dom", { action: "click", selector: "#btn" })  // → true
+* shouldForceRoundBreak("dom", { action: "fill", selector: "#in" })    // → false
+* shouldForceRoundBreak("dom", { action: "press", key: "Enter" })      // → true
+* shouldForceRoundBreak("dom", { action: "press", key: "Tab" })        // → false
+* shouldForceRoundBreak("navigate", { action: "goto", url: "/home" })  // → true
+* shouldForceRoundBreak("evaluate", { expression: "alert(1)" })        // → true
+* ```
 */
 function shouldForceRoundBreak(toolName, toolInput) {
 	const action = getToolAction(toolInput);
@@ -287,11 +432,20 @@ function shouldForceRoundBreak(toolName, toolInput) {
 	return toolName === "evaluate";
 }
 /**
-* 判定动作是否可能引发页面结构或状态变化。
+* 判定动作是否可能引发页面结构或状态变化（宽泛判定）。
 *
-* 用于“轮次后稳定等待”触发条件：
+* 用于"轮次后稳定等待"触发条件：
 * - 命中 true：本轮结束后执行加载态 + DOM 静默双重等待
 * - 命中 false：跳过等待，直接进入下一轮
+*
+* @example
+* ```ts
+* isPotentialDomMutation("dom", { action: "click" })    // → true
+* isPotentialDomMutation("dom", { action: "fill" })     // → true
+* isPotentialDomMutation("dom", { action: "get_text" }) // → false（只读）
+* isPotentialDomMutation("navigate", { action: "goto" }) // → true
+* isPotentialDomMutation("page_info", { action: "snapshot" }) // → false
+* ```
 */
 function isPotentialDomMutation(toolName, toolInput) {
 	const action = getToolAction(toolInput);
@@ -330,6 +484,18 @@ function isPotentialDomMutation(toolName, toolInput) {
 *
 * 用途：协议缺失计数重置与豁免。仅当本轮有"确定性推进"时才重置协议缺失计数器，
 * 避免模型反复点击无效目标导致死循环。
+*
+* @example
+* ```ts
+* isConfirmedProgressAction("dom", { action: "fill" })           // → true
+* isConfirmedProgressAction("dom", { action: "type" })           // → true
+* isConfirmedProgressAction("dom", { action: "select_option" })  // → true
+* isConfirmedProgressAction("dom", { action: "press" })          // → true
+* isConfirmedProgressAction("dom", { action: "click" })          // → false（不确定是否有效）
+* isConfirmedProgressAction("navigate", { action: "goto" })      // → true
+* isConfirmedProgressAction("my_custom_tool", { query: "..." })  // → true（自定义工具）
+* isConfirmedProgressAction("page_info", { action: "snapshot" }) // → false（只读）
+* ```
 */
 function isConfirmedProgressAction(toolName, toolInput) {
 	if (toolName === "navigate") return true;
@@ -357,8 +523,20 @@ function isConfirmedProgressAction(toolName, toolInput) {
 * 采集找不到元素任务。
 *
 * 返回 null 表示当前结果不属于“元素未找到”，
-* 返回对象表示可进入 not-found retry 对话流。
-*/
+* 返回对象表示可进入 not-found retry 对话流。 *
+* @example
+* ```ts
+* collectMissingTask("dom", { action: "click", selector: "#xyz" }, {
+*   content: "未找到 #xyz 对应的元素",
+*   details: { error: true, code: "ELEMENT_NOT_FOUND" },
+* })
+* // → { name: "dom", input: {...}, reason: "未找到 #xyz 对应的元素" }
+*
+* collectMissingTask("dom", { action: "click", selector: "#btn" }, {
+*   content: "已点击按钮",
+* })
+* // → null（操作成功，非元素未找到）
+* ``` */
 function collectMissingTask(name, input, result) {
 	if (!isElementNotFoundResult(result)) return null;
 	return {
@@ -373,6 +551,18 @@ function collectMissingTask(name, input, result) {
 * 判定顺序：
 * 1) 优先看结构化错误码 `ELEMENT_NOT_FOUND`
 * 2) 回退看中文错误文本关键词（兼容历史结果格式）
+*
+* @example
+* ```ts
+* isElementNotFoundResult({ content: "...", details: { code: "ELEMENT_NOT_FOUND" } })
+* // → true（结构化错误码命中）
+*
+* isElementNotFoundResult({ content: "未找到 #abc 对应的元素" })
+* // → true（中文关键词回退命中）
+*
+* isElementNotFoundResult({ content: "已点击按钮" })
+* // → false
+* ```
 */
 function isElementNotFoundResult(result) {
 	const details = result.details;
@@ -386,15 +576,29 @@ function isElementNotFoundResult(result) {
 * 生成稳定调用键。
 *
 * 用于 recoveryAttempts 的 map key（同名 + 同参数视为同一调用）。
+*
+* @example
+* ```ts
+* buildToolCallKey("dom", { action: "click", selector: "#a1b2c" })
+* // → 'dom:{"action":"click","selector":"#a1b2c"}'
+* ```
 */
 function buildToolCallKey(name, input) {
 	return `${name}:${JSON.stringify(input)}`;
 }
 /**
 * 解析恢复等待时长。
-* 优先级：waitMs > waitSeconds > 默认值。
+* 优先级：waitMs > waitSeconds > 默认值（100ms）。
 *
 * 统一返回毫秒整数，且最小为 0。
+*
+* @example
+* ```ts
+* resolveRecoveryWaitMs({ waitMs: 500 })      // → 500
+* resolveRecoveryWaitMs({ waitSeconds: 2 })    // → 2000
+* resolveRecoveryWaitMs({})                     // → 100（DEFAULT_RECOVERY_WAIT_MS）
+* resolveRecoveryWaitMs(null)                   // → 100
+* ```
 */
 function resolveRecoveryWaitMs(input) {
 	if (!input || typeof input !== "object") return DEFAULT_RECOVERY_WAIT_MS;
@@ -409,6 +613,13 @@ function resolveRecoveryWaitMs(input) {
 * 读取工具 action。
 *
 * 仅在 input 是对象且 action 为字符串时返回值，否则返回 undefined。
+*
+* @example
+* ```ts
+* getToolAction({ action: "click", selector: "#btn" }) // → "click"
+* getToolAction({ selector: "#btn" })                   // → undefined（无 action）
+* getToolAction(null)                                    // → undefined
+* ```
 */
 function getToolAction(input) {
 	if (!input || typeof input !== "object") return void 0;
@@ -419,6 +630,15 @@ function getToolAction(input) {
 * 判定错误标记。
 *
 * 约定：`result.details.error === true` 视为错误结果。
+*
+* @example
+* ```ts
+* hasToolError({ content: "...", details: { error: true, code: "ELEMENT_NOT_FOUND" } })
+* // → true
+*
+* hasToolError({ content: "已点击按钮" })
+* // → false（无 details 或 error 不为 true）
+* ```
 */
 function hasToolError(result) {
 	return result.details && typeof result.details === "object" ? Boolean(result.details.error) : false;
@@ -2435,7 +2655,6 @@ function normalizeExtraInstructions(input) {
 *    - hash ID 定位：仅交互元素携带 #hashID，非交互元素为上下文
 *    - 事件信号：listeners="..." 标注运行时事件绑定
 *    - 批量执行：同轮完成所有独立可见操作
-*    - 输入顺序：fill/type 前必须先 focus/click 同一目标
 *    - DOM 变化断轮：会改变 DOM 的动作执行后等待下一轮新快照
 *    - 停机规则：任务完成后输出 REMAINING: DONE
 *
@@ -2471,9 +2690,8 @@ function buildSystemPrompt(params = {}) {
 		"- If the text you want to click has no click signal, look at its parent row/container or nearby sibling that does have clk listener.",
 		"- No-effect fallback: if a click produced no page change (snapshot unchanged), do NOT repeat the same target. Instead: (1) look for <a> links or <button> inside the clicked container; (2) try a parent or sibling with stronger click signal; (3) try a completely different approach (e.g., search, filter, sidebar navigation, or use evaluate to trigger the action programmatically).",
 		"- Batch fill/type/check/select_option freely within one round. A click always ends the round — send at most ONE click as the LAST action in a batch.",
-		"- Input order (MANDATORY): focus/click → fill/type/select_option per target. Multi-field: focus A→fill A→focus B→fill B.",
+		"- fill/type/select_option auto-focus: these actions automatically click and focus the target before input — do NOT send a separate focus/click before them.",
 		"- Search/filter inputs: after fill, press Enter (or click search button) to trigger the search. Do not assume fill alone submits.",
-		"- Do NOT run focus-only batches. Each focus must be immediately followed by its fill/type/select_option.",
 		"- Steppers: compute delta from visible value, click exactly |delta| times. Check/uncheck: target real input control.",
 		"- DOM-changing action (click/modal/navigate): ends the round, next snapshot follows. Actions sent after a click in the same batch are discarded.",
 		"- Intermediate progress is NOT completion: if an action only opens, expands, reveals, filters, paginates, switches context, or loads the next step, keep REMAINING on the final user goal until the requested end state/value/content is visible in the snapshot.",
@@ -3084,7 +3302,7 @@ function executeFillOnResolvedTarget(target, value, selector, action, sourceHint
 			}
 		};
 		scrollIntoViewIfNeeded(target);
-		target.focus();
+		dispatchClickEvents(target);
 		selectText(target);
 		setNativeValue(target, value);
 		dispatchInputEvents(target);
@@ -3102,7 +3320,7 @@ function executeFillOnResolvedTarget(target, value, selector, action, sourceHint
 	}
 	if (target instanceof HTMLTextAreaElement) {
 		scrollIntoViewIfNeeded(target);
-		target.focus();
+		dispatchClickEvents(target);
 		selectText(target);
 		setNativeValue(target, value);
 		dispatchInputEvents(target);
@@ -3124,7 +3342,7 @@ function executeFillOnResolvedTarget(target, value, selector, action, sourceHint
 		return { content: `已填写 ${describeElement(target)}: "${value}"${suffix}` };
 	}
 	if (target instanceof HTMLElement && target.isContentEditable) {
-		target.focus();
+		dispatchClickEvents(target);
 		selectText(target);
 		if (value) document.execCommand("insertText", false, value);
 		else document.execCommand("delete", false, void 0);
@@ -3616,7 +3834,8 @@ function createDomTool() {
 							dispatchClickEvents(option);
 							return { content: `已在自定义下拉中选择 "${wanted}"` };
 						}
-						target.focus();
+						scrollIntoViewIfNeeded(target);
+						dispatchClickEvents(target);
 						const options = Array.from(target.options);
 						let selected;
 						if (value !== void 0) selected = options.find((o) => o.value === value);
@@ -3711,7 +3930,8 @@ function createDomTool() {
 						if (value === void 0) return { content: "缺少 value 参数" };
 						const target = retarget(el, "follow-label");
 						scrollIntoViewIfNeeded(target);
-						if (target instanceof HTMLElement) target.focus();
+						if (target instanceof HTMLElement) dispatchClickEvents(target);
+						else if (target instanceof SVGElement) target.focus();
 						for (const char of value) {
 							const init = {
 								key: char,