agentpage 0.0.46 → 0.0.50

package/README.md

@@ -9,7 +9,10 @@
 > 核心主张：通过 **Prompt + Tools + 路由**，快速为网站实现 AI 赋能，并构建**前端运行时 AI Skill**。AutoPilot 本质上是一个运行在前端浏览器中的 AI Agent。
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/language-TypeScript-3178C6" alt="TypeScript" /></a>
 <a href="https://www.npmjs.com/package/agentpage"><img src="https://img.shields.io/npm/v/agentpage" alt="npm" /></a>
+<a href="https://www.npmjs.com/package/agentpage"><img src="https://img.shields.io/npm/dm/agentpage" alt="downloads" /></a>
+<a href="https://bundlephobia.com/package/agentpage"><img src="https://img.shields.io/bundlephobia/minzip/agentpage" alt="minzipped size" /></a>
 
 AutoPilot 的目标不是生成文本，而是在浏览器中完成真实任务：点击、填写、导航、等待、执行脚本，并在每一轮根据最新页面状态持续推进。
 
@@ -76,7 +79,7 @@ npm install agentpage
 
 - **Prompt + Tools + 路由三层解耦**：可以快速把"可执行 AI 能力"植入现有前端系统，按路由渐进式接入，支持"项目级工具 + 路由级工具"组合。
 - **增量任务消费协议（REMAINING）**：任务不是一次性执行，而是逐轮消费收敛。每轮只做当前快照可执行的动作，通过 `REMAINING` 协议跟踪进度，支持协议修复和启发式回退，确保复杂多步任务稳定收敛。
-- **8 层保护机制**：冗余拦截、快照防抖、元素恢复、Not-found 重试对话流、导航刷新、空转检测、重复批次防自转、协议修复 —— 目标是**稳定收敛**，而不是偶然成功。
+- **9 层保护机制**：冗余拦截、快照防抖、元素恢复、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）**：每轮行动前自动检查上轮操作是否在当前快照中生效，未生效则尝试邻近元素，避免重复点击无效目标。
@@ -229,6 +232,7 @@ Round 3: 执行 C → REMAINING: DONE
 | 重复批次防自转 | 连续两轮相同任务批次 | 直接终止 |
 | 协议修复回合 | remaining 未完成却无工具调用 | 注入强约束提示 |
 | 轮次稳定等待 | 本轮有 DOM 变化动作 | loading hidden + DOM quiet（200ms/4s） |
+| 快照指纹变化检测 | 本轮有 DOM 变更动作且行动后指纹不变 | 注入 `Snapshot unchanged` 提示，强制模型换目标 |
 
 ### 5. 停机条件
 

package/dist/index.mjs

@@ -88,6 +88,29 @@ function extractHashSelectorRef(toolInput) {
 	return m ? m[1] : null;
 }
 /**
+* 快照指纹计算 — 用于轮次间快照变化检测。
+*
+* 元素的 #hashID（如 `#1kry9hw`）可能因 DOM 重新渲染而变化，
+* 但页面实际内容并未改变。因此先将 hashID 替换为占位符 `#_`，
+* 再计算 djb2 哈希，确保指纹只反映真实页面结构和文本差异。
+*
+* 用途：轮次行动前后各算一次指纹，若一致说明操作未产生任何可见效果。
+*/
+function computeSnapshotFingerprint(snapshot) {
+	if (!snapshot) return "";
+	return _djb2(snapshot.replace(/#[a-z0-9]{4,}/gi, "#_"));
+}
+/**
+* djb2 字符串哈希（非加密）。
+*
+* 纯粹用于快照指纹比对，不用于安全场景。
+*/
+function _djb2(str) {
+	let hash = 5381;
+	for (let i = 0; i < str.length; i++) hash = (hash << 5) + hash + str.charCodeAt(i) | 0;
+	return (hash >>> 0).toString(36);
+}
+/**
 * 构建任务数组。
 *
 * 作用：把一轮工具调用规整成稳定字符串数组，
@@ -542,7 +565,7 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 	];
 	if (hasErrors) contextParts.push("", "Last step failed. Retry differently or skip to other targets.");
 	else contextParts.push("", "If fully done, reply summary only (no tools).");
-	if (previousRoundTasks && previousRoundTasks.length > 0) contextParts.push("", "Previous executed:", ...previousRoundTasks.map((task, index) => `${index + 1}. ${task}`), "If any had no visible effect, try a different nearby element instead of repeating.");
+	if (previousRoundTasks && previousRoundTasks.length > 0) contextParts.push("", "Previous executed:", ...previousRoundTasks.map((task, index) => `${index + 1}. ${task}`), "If any had no visible effect (snapshot unchanged), do NOT repeat — try a child <a>/<button> inside the target, or a sibling/parent with stronger click signal.");
 	if (previousRoundPlannedTasks && previousRoundPlannedTasks.length > 0) contextParts.push("", "Previous planned:", ...previousRoundPlannedTasks.map((task, index) => `${index + 1}. ${task}`));
 	if (previousRoundModelOutput) contextParts.push("", "Previous model output:", previousRoundModelOutput);
 	const lastEntry = trace[trace.length - 1];
@@ -894,6 +917,7 @@ async function executeAgentLoop(params) {
 		callbacks?.onRound?.(round);
 		usedRounds = round + 1;
 		if (!pageContext.latestSnapshot) await refreshSnapshot();
+		const roundStartFingerprint = computeSnapshotFingerprint(pageContext.latestSnapshot || "");
 		const effectivePrompt = stripSnapshotFromPrompt(systemPrompt);
 		const chatMessages = buildCompactMessages(message, fullToolTrace, pageContext.latestSnapshot, pageContext.currentUrl, history, remainingInstruction, previousRoundTasks, previousRoundModelOutput, previousRoundPlannedTasks, protocolViolationHint);
 		if (pendingNotFoundRetry && pendingNotFoundRetry.tasks.length > 0) chatMessages.push({
@@ -972,10 +996,12 @@ async function executeAgentLoop(params) {
 		}
 		if (consecutiveSamePlannedBatch >= 2 && !lastRoundHadError) protocolViolationHint = [
 			"Repeated action warning:",
-			"- You performed the EXACT same tool call(s) as the previous round, but no visible change occurred.",
-			"This round you MUST do ONE of:",
-			"1) Try a DIFFERENT element or approach (e.g., look for an alternative button, link, or parent container);",
-			"2) If the task is truly complete, return REMAINING: DONE with no tool calls.",
+			"- You performed the EXACT same tool call(s) as the previous round, but NO visible change occurred in the snapshot.",
+			"The clicked element did not trigger navigation or DOM change. This round you MUST do ONE of:",
+			"1) Look INSIDE the clicked container for an <a> link, <button>, or child element with clk/pdn/mdn listener, and click THAT instead;",
+			"2) Try a parent or sibling element with stronger click signal (clk/pdn/mdn listener);",
+			"3) Try a completely different approach (e.g., search, filter, or navigate via sidebar);",
+			"4) If the task is truly complete, return REMAINING: DONE with no tool calls.",
 			"Do NOT repeat the same action again."
 		].join("\n");
 		if (dryRun) {
@@ -1061,16 +1087,6 @@ async function executeAgentLoop(params) {
 			if (finalReply) callbacks?.onText?.(finalReply);
 			break;
 		}
-		if (consecutiveNoProtocolRounds >= 5) {
-			finalReply = response.text?.trim() || "任务已完成。";
-			if (finalReply) callbacks?.onText?.(finalReply);
-			break;
-		}
-		if (consecutiveNoProtocolRounds >= 3) protocolViolationHint = [
-			"Protocol reminder: REMAINING protocol missing for 3+ rounds with tool calls.",
-			"You MUST include REMAINING: <text> or REMAINING: DONE in every response.",
-			"If the task is fully complete, return REMAINING: DONE with no tool calls."
-		].join("\n");
 		const idleResult = detectIdleLoop(executedTaskCalls, consecutiveReadOnlyRounds);
 		if (idleResult === -1) {
 			finalReply = response.text?.trim() || "任务已完成。";
@@ -1080,6 +1096,31 @@ async function executeAgentLoop(params) {
 		consecutiveReadOnlyRounds = idleResult;
 		if (roundHasPotentialDomMutation) await runRoundStabilityBarrier();
 		await refreshSnapshot();
+		if (roundHasPotentialDomMutation) {
+			const roundEndFingerprint = computeSnapshotFingerprint(pageContext.latestSnapshot || "");
+			if (roundEndFingerprint === roundStartFingerprint && roundStartFingerprint !== "") {
+				const unchangedHint = [
+					"Snapshot unchanged after action:",
+					"- The page snapshot is IDENTICAL before and after your action(s) this round.",
+					"- Your click/action had NO visible effect on the page. Do NOT repeat it.",
+					"- Look INSIDE the target for <a>/<button>/child with clk listener, or try a parent/sibling with stronger signal, or use a completely different approach."
+				].join("\n");
+				protocolViolationHint = protocolViolationHint ? protocolViolationHint + "\n\n" + unchangedHint : unchangedHint;
+			} else if (roundEndFingerprint !== roundStartFingerprint) consecutiveNoProtocolRounds = 0;
+		}
+		if (consecutiveNoProtocolRounds >= 5) {
+			finalReply = response.text?.trim() || "任务已完成。";
+			if (finalReply) callbacks?.onText?.(finalReply);
+			break;
+		}
+		if (consecutiveNoProtocolRounds >= 3) {
+			const noProtocolHint = [
+				"Protocol reminder: REMAINING protocol missing for 3+ rounds with tool calls.",
+				"You MUST include REMAINING: <text> or REMAINING: DONE in every response.",
+				"If the task is fully complete, return REMAINING: DONE with no tool calls."
+			].join("\n");
+			protocolViolationHint = protocolViolationHint ? protocolViolationHint + "\n\n" + noProtocolHint : noProtocolHint;
+		}
 	}
 	const resultMessages = [...history ?? [], {
 		role: "user",
@@ -1252,12 +1293,33 @@ var BaseAIClient = class {
 };
 
 //#endregion
-//#region src/core/ai-client/openai.ts
+//#region src/core/ai-client/models/openai.ts
+/** 单次请求默认超时时间（毫秒） */
 const DEFAULT_REQUEST_TIMEOUT_MS = 45e3;
+/** JSON（非流式）模式超时后的最大重试次数 */
 const JSON_TIMEOUT_RETRY_COUNT = 1;
+/**
+* 判断错误是否为请求超时错误（中）/ Check if error is a request timeout (EN).
+* 仅匹配 `fetchWithTimeout` 抛出的特定格式错误消息。
+*/
 function isRequestTimeoutError(error) {
 	return error instanceof Error && /^AI request timeout \(\d+ms\)$/.test(error.message);
 }
+/**
+* 带超时的 fetch 封装（中）/ Fetch wrapper with AbortController-based timeout (EN).
+*
+* 工作原理：
+* 1. 创建 AbortController，设置 setTimeout 在超时后调用 controller.abort()
+* 2. 将 controller.signal 注入 fetch 请求
+* 3. 若 fetch 被 abort，捕获 AbortError 并转换为语义明确的超时错误
+* 4. 无论成功或失败，finally 中清除定时器避免泄漏
+*
+* @param input - 请求 URL 或 Request 对象
+* @param init - fetch 请求配置
+* @param timeoutMs - 超时毫秒数（<=0 或非有限数时不设超时）
+* @returns fetch Response
+* @throws Error - 超时时抛出 "AI request timeout (Xms)"
+*/
 async function fetchWithTimeout(input, init, timeoutMs) {
 	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return fetch(input, init);
 	const controller = new AbortController();
@@ -1275,11 +1337,30 @@ async function fetchWithTimeout(input, init, timeoutMs) {
 	}
 }
 /**
-* OpenAIClient 类（中）/ OpenAIClient class for OpenAI & Copilot (EN).
+* OpenAIClient 类（中）/ OpenAI & Copilot client implementation (EN).
+*
+* 继承 BaseAIClient，通过注入 chatHandler 实现 OpenAI Chat Completions 协议。
+* 根据 `config.stream`（默认 true）自动选择流式（SSE）或非流式（JSON）模式。
+*
+* 非流式模式特性：
+* - 使用 `fetchWithTimeout` + AbortController 实现请求级超时
+* - 超时后自动重试 1 次（`JSON_TIMEOUT_RETRY_COUNT`），应对单次网络抖动
+* - 非超时错误不重试，直接抛出
+*
+* 流式模式特性：
+* - 通过 SSE 逐 chunk 接收 delta 内容和工具调用片段
+* - 若服务端返回 application/json（如模型降级），自动回退为 JSON 解析
+* - 单次 chunk 读取超时 20s（`readTimeoutMs`）
+*
+* 本类也是 DeepSeek / Doubao / Qwen / MiniMax 等兼容 provider 的基类。
 */
 var OpenAIClient = class extends BaseAIClient {
 	/** AI 客户端配置（provider / model / apiKey / baseURL） */
 	config;
+	/**
+	* 构造 OpenAIClient 实例。
+	* @param config - AI 客户端配置，需包含 provider / model / apiKey
+	*/
 	constructor(config) {
 		super({ chatHandler: async (params) => {
 			const req = buildOpenAIRequest(this.config, params);
@@ -1320,7 +1401,48 @@ var OpenAIClient = class extends BaseAIClient {
 	}
 };
 /**
-* 构建 OpenAI 请求（中）/ Build OpenAI chat request payload (EN).
+* 构建 OpenAI Chat Completions 请求（中）/ Build OpenAI chat request payload (EN).
+*
+* 将统一的 ChatParams 转换为 OpenAI 协议格式：
+* - system prompt 作为 messages 数组首条 system 消息
+* - 工具定义转换为 `{ type: "function", function: { name, description, parameters } }` 格式
+* - 流式模式设置 `stream: true` + `stream_options: { include_usage: true }` 获取用量
+* - 有工具时设置 `tool_choice: "auto"` + `parallel_tool_calls`（默认允许并行）
+* - temperature 固定 0.3（偏确定性，适合工具调用场景）
+* - 认证使用 `Authorization: Bearer <apiKey>`
+*
+* 构建后的请求体示例（流式 + 含工具）：
+* ```json
+* // POST https://api.openai.com/v1/chat/completions
+* // Headers: { "Authorization": "Bearer sk-xxx", "Content-Type": "application/json" }
+* {
+*   "model": "gpt-4o",
+*   "messages": [
+*     { "role": "system", "content": "You are a browser automation agent..." },
+*     { "role": "user", "content": "Click the submit button" }
+*   ],
+*   "tools": [
+*     {
+*       "type": "function",
+*       "function": {
+*         "name": "dom",
+*         "description": "DOM interaction tool. Actions: click, fill, ...",
+*         "parameters": { "type": "object", "properties": { "action": { ... }, "selector": { ... } } }
+*       }
+*     }
+*   ],
+*   "tool_choice": "auto",
+*   "parallel_tool_calls": true,
+*   "temperature": 0.3,
+*   "max_tokens": 4096,
+*   "stream": true,
+*   "stream_options": { "include_usage": true }
+* }
+* ```
+*
+* @param config - AI 客户端配置
+* @param params - 统一聊天参数（systemPrompt / messages / tools）
+* @returns 构建好的 HTTP 请求对象（url / method / headers / body）
 */
 function buildOpenAIRequest(config, params) {
 	const baseURL = resolveBaseURL(config);
@@ -1360,7 +1482,43 @@ function buildOpenAIRequest(config, params) {
 	};
 }
 /**
-* 解析 OpenAI 响应（中）/ Parse raw OpenAI response into AIChatResponse (EN).
+* 解析 OpenAI JSON 响应（中）
+*
+* 从 choices[0].message 中提取文本和工具调用，并映射 usage 统计。
+* 工具调用的 `arguments` 字段为 JSON 字符串，此处解析为对象。
+*
+* 输入示例（非流式 JSON 响应）：
+* ```json
+* {
+*   "choices": [{
+*     "message": {
+*       "content": null,
+*       "tool_calls": [{
+*         "id": "call_abc123",
+*         "type": "function",
+*         "function": {
+*           "name": "dom",
+*           "arguments": "{\"action\":\"click\",\"selector\":\"#submit-btn\"}"
+*         }
+*       }]
+*     }
+*   }],
+*   "usage": { "prompt_tokens": 1200, "completion_tokens": 45 }
+* }
+* ```
+*
+* 输出（统一 AIChatResponse）：
+* ```json
+* {
+*   "text": undefined,
+*   "toolCalls": [{ "id": "call_abc123", "name": "dom", "input": { "action": "click", "selector": "#submit-btn" } }],
+*   "usage": { "inputTokens": 1200, "outputTokens": 45 }
+* }
+* ```
+*
+* @param data - OpenAI API 返回的原始 JSON 对象
+* @returns 统一的 AIChatResponse
+* @throws Error - choices 为空时抛出 "AI 未返回有效响应"
 */
 function parseOpenAIResponse(data) {
 	const d = data;
@@ -1382,7 +1540,42 @@ function parseOpenAIResponse(data) {
 	};
 }
 /**
-* 消息转换（中）/ Convert unified messages to OpenAI format (EN).
+* 统一消息格式转换为 OpenAI 格式（中）/ Convert unified AIMessage[] to OpenAI message format (EN).
+*
+* 转换规则：
+* - system prompt → 首条 `{ role: "system", content }` 消息
+* - `tool` 角色 → 展开为多条 `{ role: "tool", tool_call_id, content }` 消息（OpenAI 要求每个结果独立一条）
+* - `assistant` 带 toolCalls → `{ role: "assistant", content, tool_calls }` 消息
+* - 其他（user / assistant 纯文本）→ 直接映射
+*
+* 输入示例（统一 AIMessage[]）：
+* ```ts
+* messages = [
+*   { role: "user", content: "帮我点击提交按钮" },
+*   { role: "assistant", content: "好的", toolCalls: [
+*     { id: "call_abc", name: "dom", input: { action: "click", selector: "#btn" } }
+*   ]},
+*   { role: "tool", content: [
+*     { toolCallId: "call_abc", result: "点击成功" }
+*   ]}
+* ]
+* ```
+*
+* 输出示例（OpenAI 格式）：
+* ```json
+* [
+*   { "role": "system", "content": "You are a browser automation agent..." },
+*   { "role": "user", "content": "帮我点击提交按钮" },
+*   { "role": "assistant", "content": "好的", "tool_calls": [
+*     { "id": "call_abc", "type": "function", "function": { "name": "dom", "arguments": "{\"action\":\"click\",\"selector\":\"#btn\"}" } }
+*   ]},
+*   { "role": "tool", "tool_call_id": "call_abc", "content": "点击成功" }
+* ]
+* ```
+*
+* @param systemPrompt - 系统提示词
+* @param messages - 统一消息列表
+* @returns OpenAI 格式的消息数组
 */
 function convertMessages$1(systemPrompt, messages) {
 	const result = [{
@@ -1413,7 +1606,52 @@ function convertMessages$1(systemPrompt, messages) {
 	return result;
 }
 /**
-* 解析 OpenAI SSE（中）/ Parse OpenAI SSE stream into unified response (EN).
+* 解析 OpenAI SSE 流式响应（中）/ Parse OpenAI SSE stream into unified AIChatResponse (EN).
+*
+* 工作原理：
+* 1. 通过 `consumeSSEJSON` 逐 chunk 消费 SSE 事件
+* 2. 文本内容（`delta.content`）逐 chunk 拼接为完整字符串
+* 3. 工具调用按 `delta.tool_calls[].index` 累积：
+*    - 首个 delta 包含 id 和 name
+*    - 后续 delta 只包含 arguments 片段，需要拼接
+*    - 最终按 index 排序，逐个 JSON.parse 解析 arguments
+* 4. usage 信息来自最终 chunk（需 `stream_options.include_usage=true`）
+* 5. 遇到 `[DONE]` 信号自动结束（`stopOnDone: true`）
+*
+* SSE 流示例（含工具调用）：
+* ```
+* data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_abc","function":{"name":"dom","arguments":""}}]}}]}
+* data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"action"}}]}}]}
+* data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":":\"click\",\"selector"}}]}}]}
+* data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":":\"#submit-btn\"}"}}]}}]}
+* data: {"choices":[{"delta":{}}],"usage":{"prompt_tokens":1200,"completion_tokens":45}}
+* data: [DONE]
+* ```
+*
+* SSE 流示例（纯文本）：
+* ```
+* data: {"choices":[{"delta":{"content":"我"}}]}
+* data: {"choices":[{"delta":{"content":"已经"}}]}
+* data: {"choices":[{"delta":{"content":"完成了"}}]}
+* data: {"choices":[{"delta":{"content":"任务。"}}]}
+* data: {"choices":[{"delta":{}},"usage":{"prompt_tokens":800,"completion_tokens":12}]}
+* data: [DONE]
+* ```
+*
+* 最终输出（统一 AIChatResponse）：
+* ```json
+* {
+*   "text": "我已经完成了任务。",
+*   "toolCalls": undefined,
+*   "usage": { "inputTokens": 800, "outputTokens": 12 }
+* }
+* ```
+*
+* 回退：若 response.body 不可用（无 ReadableStream 支持），回退为 JSON 解析。
+*
+* @param response - OpenAI API 的流式 HTTP 响应
+* @param readTimeoutMs - 单次 chunk 读取超时（毫秒，默认 20000）
+* @returns 统一的 AIChatResponse（文本 + 工具调用 + usage）
 */
 async function parseOpenAIStream(response, readTimeoutMs = 2e4) {
 	if (!response.body) return parseOpenAIResponse(await response.json());
@@ -1459,13 +1697,22 @@ async function parseOpenAIStream(response, readTimeoutMs = 2e4) {
 }
 
 //#endregion
-//#region src/core/ai-client/anthropic.ts
+//#region src/core/ai-client/models/anthropic.ts
 /**
 * AnthropicClient 类（中）/ AnthropicClient class (EN).
+*
+* 继承 BaseAIClient，通过注入 chatHandler 实现 Anthropic Messages API 的请求与响应处理。
+* 根据 `config.stream`（默认 true）自动选择 SSE 流式 或 JSON 非流式模式。
+*
+* 流式模式下，若服务端返回 `application/json`（如模型降级），自动回退为 JSON 解析。
 */
 var AnthropicClient = class extends BaseAIClient {
 	/** AI 客户端配置（provider / model / apiKey / baseURL） */
 	config;
+	/**
+	* 构造 AnthropicClient 实例。
+	* @param config - AI 客户端配置，需包含 provider="anthropic"、model、apiKey
+	*/
 	constructor(config) {
 		super({ chatHandler: async (params) => {
 			const req = buildAnthropicRequest(this.config, params);
@@ -1497,7 +1744,39 @@ var AnthropicClient = class extends BaseAIClient {
 	}
 };
 /**
-* 构建 Anthropic 请求（中）/ Build Anthropic Messages API request (EN).
+* 构建 Anthropic Messages API 请求（中）/ Build Anthropic Messages API request payload (EN).
+*
+* 将统一的 ChatParams 转换为 Anthropic 协议格式：
+* - system prompt 放顶层 `system` 字段（非消息数组）
+* - 工具定义使用 `input_schema`（非 `parameters`）
+* - max_tokens 根据模型名自动调整（opus 系列 16384，其他 8192）
+* - 认证头使用 `x-api-key` + `anthropic-version`
+*
+* 构建后的请求体示例（流式 + 含工具）：
+* ```json
+* // POST https://api.anthropic.com/v1/messages
+* // Headers: { "x-api-key": "sk-ant-xxx", "anthropic-version": "2023-06-01", "Content-Type": "application/json" }
+* {
+*   "model": "claude-sonnet-4-20250514",
+*   "max_tokens": 8192,
+*   "system": "You are a browser automation agent...",
+*   "messages": [
+*     { "role": "user", "content": "Click the submit button" }
+*   ],
+*   "tools": [
+*     {
+*       "name": "dom",
+*       "description": "DOM interaction tool. Actions: click, fill, ...",
+*       "input_schema": { "type": "object", "properties": { "action": { ... }, "selector": { ... } } }
+*     }
+*   ],
+*   "stream": true
+* }
+* ```
+*
+* @param config - AI 客户端配置
+* @param params - 统一聊天参数（systemPrompt / messages / tools）
+* @returns 构建好的 HTTP 请求对象（url / method / headers / body）
 */
 function buildAnthropicRequest(config, params) {
 	const baseURL = resolveBaseURL(config);
@@ -1528,7 +1807,38 @@ function buildAnthropicRequest(config, params) {
 	};
 }
 /**
-* 解析 Anthropic 响应（中）/ Parse raw Anthropic response (EN).
+* 解析 Anthropic JSON 响应（中）/ Parse raw Anthropic JSON response into unified AIChatResponse (EN).
+*
+* 从 content 数组中提取所有 text 块（合并为字符串）和 tool_use 块（转为 AIToolCall），
+* 并映射 usage 字段为统一的 inputTokens / outputTokens。
+*
+* 输入示例（非流式 JSON 响应）：
+* ```json
+* {
+*   "content": [
+*     { "type": "text", "text": "好的，我来点击提交按钮。" },
+*     {
+*       "type": "tool_use",
+*       "id": "toolu_01A09q90qw90lq917835lhds",
+*       "name": "dom",
+*       "input": { "action": "click", "selector": "#submit-btn" }
+*     }
+*   ],
+*   "usage": { "input_tokens": 1500, "output_tokens": 62 }
+* }
+* ```
+*
+* 输出（统一 AIChatResponse）：
+* ```json
+* {
+*   "text": "好的，我来点击提交按钮。",
+*   "toolCalls": [{ "id": "toolu_01A09q90qw90lq917835lhds", "name": "dom", "input": { "action": "click", "selector": "#submit-btn" } }],
+*   "usage": { "inputTokens": 1500, "outputTokens": 62 }
+* }
+* ```
+*
+* @param data - Anthropic API 返回的原始 JSON 对象
+* @returns 统一的 AIChatResponse
 */
 function parseAnthropicResponse(data) {
 	const d = data;
@@ -1548,7 +1858,43 @@ function parseAnthropicResponse(data) {
 	};
 }
 /**
-* 消息格式转换（中）/ Convert unified messages to Anthropic format (EN).
+* 统一消息格式转换为 Anthropic 格式（中）/ Convert unified AIMessage[] to Anthropic message format (EN).
+*
+* 转换规则：
+* - 过滤掉 `system` 角色消息（system prompt 已由顶层 `system` 字段处理）
+* - `tool` 角色 → Anthropic `user` 角色 + `tool_result` content blocks
+* - `assistant` 带 toolCalls → text block + tool_use blocks
+* - 其他 → 直接映射 role + content
+*
+* 输入示例（统一 AIMessage[]）：
+* ```ts
+* messages = [
+*   { role: "user", content: "帮我点击提交按钮" },
+*   { role: "assistant", content: "好的", toolCalls: [
+*     { id: "toolu_01A", name: "dom", input: { action: "click", selector: "#btn" } }
+*   ]},
+*   { role: "tool", content: [
+*     { toolCallId: "toolu_01A", result: "点击成功" }
+*   ]}
+* ]
+* ```
+*
+* 输出示例（Anthropic 格式）：
+* ```json
+* [
+*   { "role": "user", "content": "帮我点击提交按钮" },
+*   { "role": "assistant", "content": [
+*     { "type": "text", "text": "好的" },
+*     { "type": "tool_use", "id": "toolu_01A", "name": "dom", "input": { "action": "click", "selector": "#btn" } }
+*   ]},
+*   { "role": "user", "content": [
+*     { "type": "tool_result", "tool_use_id": "toolu_01A", "content": "点击成功" }
+*   ]}
+* ]
+* ```
+*
+* @param messages - 统一消息列表
+* @returns Anthropic 格式的消息数组
 */
 function convertMessages(messages) {
 	return messages.filter((m) => m.role !== "system").map((m) => {
@@ -1584,7 +1930,65 @@ function convertMessages(messages) {
 	});
 }
 /**
-* 解析 Anthropic SSE（中）/ Parse Anthropic SSE stream (EN).
+* 解析 Anthropic SSE 流式响应（中）/ Parse Anthropic SSE stream into unified AIChatResponse (EN).
+*
+* 事件处理流程：
+* - `message_start`    → 提取 input_tokens
+* - `content_block_start` → 识别 tool_use 块，开始累积工具参数 JSON
+* - `content_block_delta`  → 累积文本（text_delta）或工具参数片段（input_json_delta）
+* - `content_block_stop`   → 完成当前工具调用，解析参数 JSON
+* - `message_delta`        → 提取 output_tokens
+*
+* SSE 流示例（含工具调用）：
+* ```
+* event: message_start
+* data: {"type":"message_start","message":{"usage":{"input_tokens":1500}}}
+*
+* event: content_block_start
+* data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+*
+* event: content_block_delta
+* data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"好的，我来点"}}
+*
+* event: content_block_delta
+* data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"击提交按钮。"}}
+*
+* event: content_block_stop
+* data: {"type":"content_block_stop","index":0}
+*
+* event: content_block_start
+* data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01A09q","name":"dom"}}
+*
+* event: content_block_delta
+* data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"action\":"}}
+*
+* event: content_block_delta
+* data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"click\",\"selector\":\"#submit-btn\"}"}}
+*
+* event: content_block_stop
+* data: {"type":"content_block_stop","index":1}
+*
+* event: message_delta
+* data: {"type":"message_delta","usage":{"output_tokens":62}}
+*
+* event: message_stop
+* data: {"type":"message_stop"}
+* ```
+*
+* 最终输出（统一 AIChatResponse）：
+* ```json
+* {
+*   "text": "好的，我来点击提交按钮。",
+*   "toolCalls": [{ "id": "toolu_01A09q", "name": "dom", "input": { "action": "click", "selector": "#submit-btn" } }],
+*   "usage": { "inputTokens": 1500, "outputTokens": 62 }
+* }
+* ```
+*
+* 注意：Anthropic SSE 不发送 `[DONE]`，因此 `stopOnDone` 设为 false，
+* 依赖流关闭来结束消费。
+*
+* @param response - Anthropic API 的流式 HTTP 响应
+* @returns 统一的 AIChatResponse（文本 + 工具调用 + usage）
 */
 async function parseAnthropicStream(response) {
 	if (!response.body) return parseAnthropicResponse(await response.json());
@@ -1641,7 +2045,7 @@ async function parseAnthropicStream(response) {
 }
 
 //#endregion
-//#region src/core/ai-client/deepseek.ts
+//#region src/core/ai-client/models/deepseek.ts
 /**
 * DeepSeek 客户端封装（中）/ DeepSeek client wrapper (EN).
 *
@@ -1654,7 +2058,7 @@ async function parseAnthropicStream(response) {
 var DeepSeekClient = class extends OpenAIClient {};
 
 //#endregion
-//#region src/core/ai-client/doubao.ts
+//#region src/core/ai-client/models/doubao.ts
 /**
 * Doubao 客户端封装（中）/ Doubao client wrapper (EN).
 *
@@ -1667,7 +2071,7 @@ var DeepSeekClient = class extends OpenAIClient {};
 var DoubaoClient = class extends OpenAIClient {};
 
 //#endregion
-//#region src/core/ai-client/qwen.ts
+//#region src/core/ai-client/models/qwen.ts
 /**
 * Qwen 客户端封装（中）/ Qwen client wrapper (EN).
 *
@@ -1680,7 +2084,7 @@ var DoubaoClient = class extends OpenAIClient {};
 var QwenClient = class extends OpenAIClient {};
 
 //#endregion
-//#region src/core/ai-client/minimax.ts
+//#region src/core/ai-client/models/minimax.ts
 /**
 * MiniMax 客户端封装（中）/ MiniMax client wrapper (EN).
 *
@@ -1877,7 +2281,7 @@ function buildSystemPrompt(params = {}) {
 		"- listeners=\"...\" = bound event handlers (abbrevs below). Prefer targets with matching listeners.",
 		"- Click target MUST have click signal: listeners containing clk/pdn/mdn, or onclick attr, or native <a>/<button>, or role=button/link. NEVER click elements with only blr/fcs (focus/blur) — they are not click targets.",
 		"- 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: try nearest actionable sibling/ancestor in same semantic group instead of repeating.",
+		"- 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.",
 		"- Search/filter inputs: after fill, press Enter (or click search button) to trigger the search. Do not assume fill alone submits.",
@@ -1885,7 +2289,7 @@ function buildSystemPrompt(params = {}) {
 		"- 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.",
-		"- Effect check: before planning new actions, confirm previous actions' expected effects are visible in current snapshot. If not, the action failed — try a different target instead of repeating.",
+		"- Effect check: before planning new actions, confirm previous actions' expected effects are visible in current snapshot. If the snapshot is unchanged after a click, the click FAILED — you MUST pick a different element (e.g., an <a> or <button> child inside the row, or the link text itself).",
 		"- Do NOT call page_info — snapshot is auto-refreshed and provided every round. Do NOT use get_text/get_attr to read what is already visible in the snapshot.",
 		"- Never repeat the same tool call (same name + same args) on the same target. If it didn't work, try a different approach.",
 		"- Dropdown/select: prefer dom.select_option (works in one round). For custom dropdowns requiring click-to-open: click → wait for next snapshot → click option (two rounds).",