agentpage 0.0.13 → 0.0.16

package/dist/index.mjs

@@ -6,9 +6,11 @@ import { Type } from "@sinclair/typebox";
 *
 * 统一集中在该文件，避免在主循环中散落“魔法数字”。
 */
-const DEFAULT_MAX_ROUNDS = 10;
+const DEFAULT_MAX_ROUNDS = 40;
 const DEFAULT_RECOVERY_WAIT_MS = 100;
-const DEFAULT_ACTION_RECOVERY_ROUNDS = 5;
+const DEFAULT_ACTION_RECOVERY_ROUNDS = 2;
+const DEFAULT_NOT_FOUND_RETRY_ROUNDS = 2;
+const DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 2e3;
 /** 快照起始标记 — 用于在消息中识别快照边界 */
 const SNAPSHOT_START = "<!-- SNAPSHOT_START -->";
 /** 快照结束标记 */
@@ -18,15 +20,15 @@ const SNAPSHOT_OUTDATED = "[此快照已过期，请参考对话中最新的快
 
 //#endregion
 //#region src/core/agent-loop/helpers.ts
-/** 异步睡眠，确保恢复重试按顺序串行执行。 */
+/** 异步睡眠（中）/ Async sleep utility (EN). */
 function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/** 将工具返回内容统一转为字符串，便于拼接进消息。 */
+/** 统一内容为字符串（中）/ Normalize tool content to string (EN). */
 function toContentString(content) {
 	return typeof content === "string" ? content : JSON.stringify(content, null, 2);
 }
-/** 判定工具失败是否属于“元素不存在”，用于触发快照恢复。 */
+/** 元素不存在判定（中）/ Detect element-not-found failure (EN). */
 function isElementNotFoundResult(result) {
 	const details = result.details;
 	if (details && typeof details === "object") {
@@ -35,15 +37,14 @@ function isElementNotFoundResult(result) {
 	const content = toContentString(result.content);
 	return content.includes("未找到") && content.includes("元素");
 }
-/** 为同一动作构造稳定 key，用于统计恢复重试次数。 */
+/** 生成稳定调用键（中）/ Build stable key for a tool call (EN). */
 function buildToolCallKey(name, input) {
 	return `${name}:${JSON.stringify(input)}`;
 }
 /**
-* 解析恢复等待时长：
-* - 优先 `waitMs`
-* - 其次 `waitSeconds`
-* - 最后回退默认值
+* 解析恢复等待时长（中）/ Resolve recovery wait duration (EN).
+* 优先级：waitMs > waitSeconds > 默认值。
+* Priority: waitMs > waitSeconds > default value.
 */
 function resolveRecoveryWaitMs(input) {
 	if (!input || typeof input !== "object") return DEFAULT_RECOVERY_WAIT_MS;
@@ -54,74 +55,93 @@ function resolveRecoveryWaitMs(input) {
 	if (typeof waitSeconds === "number" && Number.isFinite(waitSeconds)) return Math.max(0, Math.floor(waitSeconds * 1e3));
 	return DEFAULT_RECOVERY_WAIT_MS;
 }
-/** 将工具输入压缩成简短文本，用于轨迹展示。 */
-function formatToolInputBrief(input) {
-	if (!input || typeof input !== "object") return "";
-	const params = input;
-	const parts = [];
-	for (const key of [
-		"action",
-		"selector",
-		"waitMs",
-		"waitSeconds",
-		"url",
-		"text"
-	]) {
-		const value = params[key];
-		if (value === void 0 || value === null) continue;
-		if (typeof value === "string") parts.push(`${key}=${JSON.stringify(value).slice(0, 80)}`);
-		else if (typeof value === "number" || typeof value === "boolean") parts.push(`${key}=${String(value)}`);
-	}
-	if (parts.length === 0) return "";
-	return ` (${parts.join(", ")})`;
-}
-/** 从工具参数中读取 action。 */
+/** 读取工具 action（中）/ Read tool action from input (EN). */
 function getToolAction(input) {
 	if (!input || typeof input !== "object") return void 0;
 	const action = input.action;
 	return typeof action === "string" ? action : void 0;
 }
-/** 判定工具结果是否标记 error。 */
+/** 判定错误标记（中）/ Check whether result is marked as error (EN). */
 function hasToolError(result) {
 	return result.details && typeof result.details === "object" ? Boolean(result.details.error) : false;
 }
-/** 读取当前页面 URL（通过 page_info 工具）。 */
-async function readPageUrl(registry) {
-	const result = await registry.dispatch("page_info", { action: "get_url" });
-	return typeof result.content === "string" ? result.content : void 0;
-}
-/** 读取当前页面快照（通过 page_info 工具）。 */
-async function readPageSnapshot(registry, maxDepth = 8) {
+
+//#endregion
+//#region src/core/agent-loop/snapshot.ts
+/**
+* 读取页面快照（中）/ Read current page snapshot (EN).
+*
+* 默认关闭 viewportOnly，优先完整性。
+* viewportOnly defaults to false to prioritize completeness.
+*/
+async function readPageSnapshot(registry, options) {
 	return toContentString((await registry.dispatch("page_info", {
 		action: "snapshot",
-		maxDepth
+		maxDepth: options?.maxDepth ?? 8,
+		viewportOnly: options?.viewportOnly ?? false,
+		pruneLayout: options?.pruneLayout ?? true,
+		maxNodes: options?.maxNodes ?? 500,
+		maxChildren: options?.maxChildren ?? 30,
+		maxTextLength: options?.maxTextLength ?? 40
 	})).content);
 }
-/** 转义正则特殊字符 */
+/** 包裹快照（中）/ Wrap snapshot with boundary markers (EN). */
+function wrapSnapshot(snapshot) {
+	return `${SNAPSHOT_START}\n${snapshot}\n${SNAPSHOT_END}`;
+}
+/** 转义正则字符（中）/ Escape regex special chars (EN). */
 function escapeRegex(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** 匹配快照标记对及其内容的正则 */
+/** 快照块匹配正则（中）/ Regex for snapshot blocks (EN). */
 const SNAPSHOT_REGEX = new RegExp(`${escapeRegex(SNAPSHOT_START)}[\\s\\S]*?${escapeRegex(SNAPSHOT_END)}`, "g");
-/** 用标记包裹快照内容，便于后续去重识别。 */
-function wrapSnapshot(snapshot) {
-	return `${SNAPSHOT_START}\n${snapshot}\n${SNAPSHOT_END}`;
-}
-/** 检测文本中是否包含快照标记。 */
+/** 是否包含快照标记（中）/ Check whether text includes snapshot markers (EN). */
 function containsSnapshot(text) {
 	return text.includes(SNAPSHOT_START);
 }
 /**
-* 从 system prompt 中剥离已过期的快照内容。
-* 当消息历史中已有更新的快照时调用，避免 AI 参考过时信息。
+* 剥离旧快照（中）/ Strip outdated snapshot blocks from system prompt (EN).
 */
 function stripSnapshotFromPrompt(prompt) {
 	if (!containsSnapshot(prompt)) return prompt;
 	return prompt.replace(SNAPSHOT_REGEX, SNAPSHOT_OUTDATED);
 }
+
+//#endregion
+//#region src/core/agent-loop/messages.ts
 /**
-* 格式化工具结果为简短一行摘要。
-* 成功操作保留首行描述；失败操作标注错误代码。
+* 显式 UI 意图判定（中）/ Detect explicit intent to operate AutoPilot UI (EN).
+*/
+function isExplicitAgentUiRequest(userMessage) {
+	const lower = userMessage.toLowerCase();
+	const compact = lower.replace(/[\s\p{P}\p{S}]+/gu, "");
+	const hasAgentUiKeyword = /(chat|dock|chatinput|sendbutton|shortcut|quicktest)/i.test(lower) || /(聊天|对话|指令输入框|消息输入框|输入框|发送按钮|发送|快捷测试|测试按钮|聊天面板)/.test(compact);
+	const hasActionVerb = /(press|click|type|fill|send|input|submit|enter)/i.test(lower) || /(输入|点击|发送|填写|填入|操作|提交|回车|按下)/.test(compact);
+	return hasAgentUiKeyword && hasActionVerb;
+}
+/** 输入摘要（中）/ Build brief text for tool input (EN). */
+function formatToolInputBrief(input) {
+	if (!input || typeof input !== "object") return "";
+	const params = input;
+	const parts = [];
+	for (const key of [
+		"action",
+		"selector",
+		"waitMs",
+		"waitSeconds",
+		"url",
+		"text"
+	]) {
+		const value = params[key];
+		if (value === void 0 || value === null) continue;
+		if (typeof value === "string") parts.push(`${key}=${JSON.stringify(value).slice(0, 80)}`);
+		else if (typeof value === "number" || typeof value === "boolean") parts.push(`${key}=${String(value)}`);
+	}
+	if (parts.length === 0) return "";
+	return ` (${parts.join(", ")})`;
+}
+/**
+* 结果摘要（中）/ Build one-line summary for tool result (EN).
 */
 function formatToolResultBrief(result) {
 	const firstLine = toContentString(result.content).split("\n").find((l) => l.trim())?.trim().slice(0, 80) ?? "";
@@ -132,25 +152,37 @@ function formatToolResultBrief(result) {
 	return `✓ ${firstLine}`;
 }
 /**
-* 构建发送给 AI 的紧凑消息数组。
-*
-* 核心思路：保留用户原始消息与 system prompt 不变，
-* 只将循环中产出的 assistant（含 toolCalls）+ tool（结果）消息对
-* 压缩为一条 assistant 摘要 + 一条 user 上下文。
+* 构建紧凑消息数组（中）/ Build compact AI message array (EN).
 *
-* 消息结构：
-* - 首轮：[...history, { user: 原始消息 }]
-* - 后续：[...history, { user: 原始消息 }, { assistant: 工具执行摘要 }, { user: 当前状态+快照 }]
+* Round 0: task + snapshot.
+* Round 1+: master goal + done steps + execution context + latest snapshot.
 *
-* 固定最多 history.length + 3 条消息，不随轮次增长。
+* 新增渐进式语义（中）/ Progressive semantics (EN):
+* - `remainingInstruction`：当前轮次仍待执行的文本。
+* - `previousRoundTasks`：上一轮已执行的任务数组，避免重复计划。
+* - 消息中要求模型输出 `REMAINING: ...` 或 `REMAINING: DONE`，供下一轮继续消费。
 */
-function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, history) {
+function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, history, remainingInstruction, previousRoundTasks, previousRoundModelOutput, previousRoundPlannedTasks, protocolViolationHint) {
 	const messages = history ? [...history] : [];
-	messages.push({
-		role: "user",
-		content: userMessage
-	});
-	if (trace.length === 0) return messages;
+	const allowAgentUiInteraction = isExplicitAgentUiRequest(userMessage);
+	const activeInstruction = remainingInstruction && remainingInstruction.trim() ? remainingInstruction.trim() : userMessage;
+	if (trace.length === 0) {
+		const parts = [
+			userMessage,
+			"",
+			"## Progressive execution state",
+			"Current remaining instruction to execute this round:",
+			activeInstruction
+		];
+		if (currentUrl) parts.push("", `URL: ${currentUrl}`);
+		if (latestSnapshot) parts.push("", "## Current page snapshot", "Apply task-reduction model directly from this snapshot. Do NOT restate the task.", "Use hash IDs (e.g. #a1b2c) from the snapshot as selector params.", "Do NOT call page_info (get_url/get_title/query_all/snapshot).", "Batch independent visible actions in one round.", "If action changes DOM (open modal/navigate), stop that batch and continue next round.", "For dropdown/select fields, use dom with action=select_option (or fill on a select).", allowAgentUiInteraction ? "User explicitly asked to operate AutoPilot UI. You may interact with chat input/send/dock only as requested." : "Do NOT interact with any AI chat UI elements (chat input, send button, dock). Only operate on the actual page content.", "Output one line: REMAINING: <new remaining task after this round> or REMAINING: DONE", wrapSnapshot(latestSnapshot));
+		if (protocolViolationHint) parts.push("", protocolViolationHint);
+		messages.push({
+			role: "user",
+			content: parts.join("\n")
+		});
+		return messages;
+	}
 	const traceParts = [];
 	for (let i = 0; i < trace.length; i++) {
 		const entry = trace[i];
@@ -158,23 +190,43 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 		const brief = formatToolResultBrief(entry.result);
 		const status = isError ? "❌" : "✅";
 		const marker = entry.marker ? ` ${entry.marker}` : "";
-		traceParts.push(`${status} 步骤${i + 1}: ${entry.name}${formatToolInputBrief(entry.input)} → ${brief}${marker}`);
+		traceParts.push(`${status} ${i + 1}. ${entry.name}${formatToolInputBrief(entry.input)} → ${brief}${marker}`);
 	}
 	messages.push({
 		role: "assistant",
-		content: `## 已完成的操作步骤（以下步骤已执行，请勿重复）\n\n${traceParts.join("\n")}`
+		content: `Done steps (do NOT repeat):\n${traceParts.join("\n")}`
 	});
-	const contextParts = ["以上步骤已经执行完毕。请结合用户的原始请求、已完成的步骤和下方的当前页面快照，判断下一步该做什么。", "**注意：不要重复已成功（✅）的操作，只执行尚未完成的下一步。**"];
+	const hasErrors = trace.some((e) => hasToolError(e.result));
+	const contextParts = [
+		"## Execution context",
+		"Current remaining instruction:",
+		activeInstruction,
+		"",
+		"Task-reduction model:",
+		"Input: current remaining instruction + previous round executed actions + this-round actions.",
+		"Output: new remaining instruction after removing this-round actions.",
+		"Start from visible page state directly. Do NOT restate task. Do NOT output planning text.",
+		"Execute all independent visible sub-tasks in one round.",
+		"Do NOT act on elements not present in this snapshot yet.",
+		"If action changes DOM (open modal/navigate), stop after that batch and continue next round.",
+		"Do NOT call page_info (get_url/get_title/query_all/snapshot).",
+		"For dropdown/select fields, use dom with action=select_option (or fill on a select).",
+		allowAgentUiInteraction ? "User explicitly asked to operate AutoPilot UI. You may interact with chat input/send/dock only as requested." : "Do NOT interact with any AI chat UI elements (chat input, send button, dock). Only operate on the actual page content."
+	];
+	if (hasErrors) contextParts.push("", "The last step failed. Retry with a different approach, or skip and continue with other visible targets.");
+	else contextParts.push("", "If the goal is fully done, reply with a short summary (no tool calls).");
+	if (previousRoundTasks && previousRoundTasks.length > 0) contextParts.push("", "Previous round planned task array (already executed):", ...previousRoundTasks.map((task, index) => `${index + 1}. ${task}`));
+	if (previousRoundPlannedTasks && previousRoundPlannedTasks.length > 0) contextParts.push("", "Previous round model planned task array (before execution):", ...previousRoundPlannedTasks.map((task, index) => `${index + 1}. ${task}`));
+	if (previousRoundModelOutput) contextParts.push("", "Previous round model output (normalized, for task reduction input):", previousRoundModelOutput);
+	contextParts.push("", "After this round, include one plain text line:", "REMAINING: <new remaining instruction after this-round actions>", "or REMAINING: DONE");
 	const lastEntry = trace[trace.length - 1];
 	if (hasToolError(lastEntry.result)) {
 		const stripped = toContentString(lastEntry.result.content).replace(SNAPSHOT_REGEX, "").trim();
-		if (stripped && stripped.length < 500) {
-			contextParts.push("", "### 最近失败操作详情", stripped);
-			contextParts.push("请换一种方式完成该步骤，或跳过该步骤继续后续操作。");
-		}
+		if (stripped && stripped.length < 300) contextParts.push("", "Last error: " + stripped);
 	}
-	if (currentUrl) contextParts.push("", `当前页面：${currentUrl}`);
-	if (latestSnapshot) contextParts.push("", "## 当前页面 DOM 快照（这是页面的真实当前状态）", wrapSnapshot(latestSnapshot));
+	if (currentUrl) contextParts.push("", `URL: ${currentUrl}`);
+	if (protocolViolationHint) contextParts.push("", protocolViolationHint);
+	if (latestSnapshot) contextParts.push("", "## Latest DOM snapshot", "Use hash IDs from this snapshot. Do NOT call page_info — this is already the latest.", wrapSnapshot(latestSnapshot));
 	messages.push({
 		role: "user",
 		content: contextParts.join("\n")
@@ -182,39 +234,388 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 	return messages;
 }
 
+//#endregion
+//#region src/core/agent-loop/recovery.ts
+/** 冗余 page_info 动作（中）/ Redundant page_info actions to intercept (EN). */
+const REDUNDANT_PAGE_INFO_ACTIONS = new Set([
+	"snapshot",
+	"query_all",
+	"get_url",
+	"get_title",
+	"get_viewport"
+]);
+/**
+* 冗余 page_info 检查（中）/ Check whether page_info call is redundant (EN).
+*/
+function checkRedundantSnapshot(toolName, toolInput, _latestSnapshot, round) {
+	if (toolName !== "page_info") return null;
+	const action = getToolAction(toolInput);
+	if (action && REDUNDANT_PAGE_INFO_ACTIONS.has(action)) return {
+		content: `page_info.${action} is blocked in loop execution. A snapshot is provided by the framework; continue with actionable tools directly.`,
+		details: {
+			code: "REDUNDANT_PAGE_INFO_SKIPPED",
+			action,
+			round
+		}
+	};
+	return null;
+}
+/**
+* 快照防抖（中）/ Debounce repeated snapshot calls (EN).
+*/
+function applySnapshotDebounce(toolName, toolInput, result, consecutiveCount) {
+	if (toolName === "page_info" && getToolAction(toolInput) === "snapshot") {
+		const newCount = consecutiveCount + 1;
+		if (newCount >= 2) return {
+			consecutiveCount: newCount,
+			result: {
+				content: [toContentString(result.content), "Redundant snapshot detected. Continue with remaining actionable steps using the latest snapshot; avoid additional snapshot unless navigation or uncertainty changes."].join("\n"),
+				details: {
+					error: true,
+					code: "REDUNDANT_SNAPSHOT",
+					consecutiveSnapshotCalls: newCount
+				}
+			}
+		};
+		return {
+			result,
+			consecutiveCount: newCount
+		};
+	}
+	return {
+		result,
+		consecutiveCount: 0
+	};
+}
+/**
+* 元素未找到恢复（中）/ Recover from element-not-found failures (EN).
+*
+* 前两次自动恢复，超过上限后返回终止提示。
+* Auto-recovers for initial attempts, then returns max-recovery signal.
+*/
+async function handleElementRecovery(toolName, toolInput, result, recoveryAttempts, registry, pageContext, callbacks) {
+	if (toolName !== "dom" || !isElementNotFoundResult(result)) return null;
+	const key = buildToolCallKey(toolName, toolInput);
+	const attempts = (recoveryAttempts.get(key) ?? 0) + 1;
+	recoveryAttempts.set(key, attempts);
+	const recoveryWaitMs = resolveRecoveryWaitMs(toolInput);
+	if (attempts <= DEFAULT_ACTION_RECOVERY_ROUNDS) {
+		await sleep$1(recoveryWaitMs);
+		callbacks?.onBeforeRecoverySnapshot?.();
+		pageContext.latestSnapshot = await readPageSnapshot(registry);
+		return {
+			content: [toContentString(result.content), `Recovery ${attempts}/${DEFAULT_ACTION_RECOVERY_ROUNDS}: snapshot refreshed, re-locate target.`].join("\n"),
+			details: {
+				error: true,
+				code: "ELEMENT_NOT_FOUND_RECOVERY",
+				recoveryAttempt: attempts,
+				recoveryMaxRounds: DEFAULT_ACTION_RECOVERY_ROUNDS
+			}
+		};
+	}
+	return {
+		content: [toContentString(result.content), `Max recovery attempts (${DEFAULT_ACTION_RECOVERY_ROUNDS}) reached. Try a different target.`].join("\n"),
+		details: {
+			error: true,
+			code: "ELEMENT_NOT_FOUND_MAX_RECOVERY_REACHED",
+			recoveryAttempt: attempts,
+			recoveryMaxRounds: DEFAULT_ACTION_RECOVERY_ROUNDS
+		}
+	};
+}
+/** 导航后快照刷新（中）/ Refresh snapshot after navigation actions (EN). */
+async function handleNavigationUrlChange(toolName, toolInput, result, registry, pageContext, callbacks) {
+	if (toolName !== "navigate") return;
+	const action = getToolAction(toolInput);
+	if ((action === "goto" || action === "back" || action === "forward" || action === "reload") && !hasToolError(result)) {
+		callbacks?.onBeforeRecoverySnapshot?.();
+		pageContext.latestSnapshot = await readPageSnapshot(registry);
+	}
+}
+/** 只读工具集合（中）/ Read-only tool set (EN). */
+const READ_ONLY_TOOLS = new Set(["page_info"]);
+/**
+* 空转检测（中）/ Detect idle loops dominated by read-only actions (EN).
+* 返回 -1 表示应终止循环。
+* Returns -1 when loop should terminate.
+*/
+function detectIdleLoop(toolCallNames, consecutiveReadOnlyRounds) {
+	if (toolCallNames.every((name) => READ_ONLY_TOOLS.has(name))) {
+		const newCount = consecutiveReadOnlyRounds + 1;
+		return newCount >= 2 ? -1 : newCount;
+	}
+	return 0;
+}
+
 //#endregion
 //#region src/core/agent-loop/index.ts
 /**
-* 执行 Agent 决策循环（环境无关）。
+* Agent Loop 主流程（中）/ Core environment-agnostic agent loop (EN).
+*
+* 负责消息构建、AI 决策、工具执行、恢复保护与指标汇总。
+* Orchestrates message build, AI decisions, tool execution, recovery, and metrics.
+*
+* 流程图（文本）：
+*
+*   轮次开始
+*      │
+*      ├─ 确保快照可用
+*      ├─ 构建紧凑消息（目标 + 剩余任务 + 执行轨迹 + 快照）
+*      ├─ 调用模型
+*      ├─ 无 toolCalls ? 结束 : 执行工具
+*      ├─ 应用保护机制（冗余拦截/恢复/导航检测/空转/防自转）
+*      ├─ 刷新快照
+*      ▼
+*   下一轮或停机
+*/
+/**
+* 执行 Agent 循环（中）/ Execute the agent loop (EN).
 *
-* 完整流程：
-* 1. 获取已注册的工具列表
-* 2. 循环：发消息给 AI → 检查是否返回 tool_call → 执行 → 反馈 → 继续
-* 3. AI 不再调用工具时，返回最终回复
+* 每轮：确保快照 → 构建消息 → 调用 AI → 执行工具 → 保护处理 → 刷新快照。
+* Per round: ensure snapshot -> build messages -> call AI -> execute tools -> apply protections -> refresh snapshot.
 */
 async function executeAgentLoop(params) {
-	const { client, registry, systemPrompt, message, history, dryRun = false, maxRounds = DEFAULT_MAX_ROUNDS, callbacks } = params;
+	const { client, registry, systemPrompt, message, initialSnapshot, history, dryRun = false, maxRounds = DEFAULT_MAX_ROUNDS, callbacks } = params;
 	const tools = registry.getDefinitions();
 	const allToolCalls = [];
 	const fullToolTrace = [];
 	const actionRecoveryAttempts = /* @__PURE__ */ new Map();
-	const pageContext = {};
+	const pageContext = { latestSnapshot: initialSnapshot };
 	let finalReply = "";
+	let consecutiveSnapshotCalls = 0;
+	let consecutiveReadOnlyRounds = 0;
+	let usedRounds = 0;
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let remainingInstruction = message.trim();
+	let previousRoundTasks = [];
+	let previousRoundPlannedTasks = [];
+	let previousRoundModelOutput = "";
+	let lastPlannedBatchKey = "";
+	let consecutiveSamePlannedBatch = 0;
+	let lastRoundHadError = false;
+	let protocolViolationHint;
+	let recoveryCount = 0;
+	let redundantInterceptCount = 0;
+	let pendingNotFoundRetry;
+	let snapshotReadCount = 0;
+	let snapshotSizeTotal = 0;
+	let snapshotSizeMax = 0;
+	/**
+	* 记录快照统计（中）/ Record snapshot metrics (EN).
+	*
+	* 用于输出可观测指标：读取次数、平均长度、最大长度。
+	* Used for observability metrics: read count, avg size, max size.
+	*/
+	const recordSnapshotStats = (snapshot) => {
+		if (typeof snapshot !== "string") return;
+		snapshotReadCount += 1;
+		snapshotSizeTotal += snapshot.length;
+		if (snapshot.length > snapshotSizeMax) snapshotSizeMax = snapshot.length;
+	};
+	/**
+	* 刷新页面快照（中）/ Refresh page snapshot (EN).
+	*
+	* 只做两件事：读取最新快照 + 更新快照统计。
+	* Does exactly two things: read latest snapshot + update metrics.
+	*/
+	const refreshSnapshot = async () => {
+		pageContext.latestSnapshot = await readPageSnapshot(registry);
+		recordSnapshotStats(pageContext.latestSnapshot);
+	};
+	if (pageContext.latestSnapshot) recordSnapshotStats(pageContext.latestSnapshot);
+	/**
+	* 追加工具轨迹（中）/ Append tool trace entry (EN).
+	*
+	* 同时写入：
+	* - allToolCalls：对外返回结果
+	* - fullToolTrace：下一轮消息上下文
+	*/
+	const appendToolTrace = (round, name, input, result) => {
+		allToolCalls.push({
+			name,
+			input,
+			result
+		});
+		fullToolTrace.push({
+			round,
+			name,
+			input,
+			result
+		});
+	};
+	/**
+	* 生成任务数组（中）/ Build normalized task array (EN).
+	*
+	* 将本轮 toolCalls 归一化成稳定字符串数组，便于：
+	* - 回传到下一轮消息上下文（提醒已执行计划）
+	* - 进行“是否与上一轮完全相同”的比较
+	*/
+	const buildTaskArray = (toolCalls) => toolCalls.map((tc) => {
+		const inputText = JSON.stringify(tc.input);
+		return `${tc.name}:${inputText}`;
+	});
+	/**
+	* 规范化模型文本输出（中）/ Normalize model text for next-round input (EN).
+	*
+	* 优先保留 REMAINING 行；否则截断首段文本，避免长篇规划污染下一轮输入。
+	* Prefer REMAINING line; otherwise keep a short excerpt to avoid long planning spillover.
+	*/
+	const normalizeModelOutput = (text) => {
+		if (!text) return "";
+		const trimmed = text.trim();
+		if (!trimmed) return "";
+		const remainingMatch = trimmed.match(/REMAINING\s*:\s*([\s\S]*)$/i);
+		if (remainingMatch) return `REMAINING: ${remainingMatch[1].trim()}`;
+		return (trimmed.split(/\n\s*\n/)[0]?.trim() ?? trimmed).slice(0, 220);
+	};
+	/**
+	* 判定动作是否会触发 DOM 结构变化（中）/ Whether action may cause DOM-shape change (EN).
+	*
+	* 触发后应强制断轮，等待下一轮新快照继续。
+	* Force round break after such action and continue with refreshed snapshot next round.
+	*/
+	const shouldForceRoundBreak = (toolName, toolInput) => {
+		const action = getToolAction(toolInput);
+		if (toolName === "navigate") return action === "goto" || action === "back" || action === "forward" || action === "reload";
+		if (toolName === "dom") return action === "click" || action === "press";
+		if (toolName === "evaluate") return true;
+		return false;
+	};
+	/**
+	* 将“找不到元素”的失败任务整理成可重试清单（中）/ Build retry task list for not-found failures (EN).
+	*/
+	const collectMissingTask = (name, input, result) => {
+		if (!isElementNotFoundResult(result)) return null;
+		return {
+			name,
+			input,
+			reason: toContentString(result.content).slice(0, 240)
+		};
+	};
+	/**
+	* 解析 REMAINING 协议（中）/ Parse REMAINING protocol from model text (EN).
+	*
+	* 支持：
+	* - `REMAINING: <text>` → 继续下一轮消费该剩余文本
+	* - `REMAINING: DONE`   → 剩余任务为空
+	* 返回 null 表示本轮没有提供 REMAINING 标记。
+	*/
+	const parseRemainingInstruction = (text) => {
+		if (!text) return null;
+		const match = text.match(/REMAINING\s*:\s*([\s\S]*)$/i);
+		if (!match) return null;
+		const value = match[1].trim();
+		return /^done$/i.test(value) ? "" : value;
+	};
+	/**
+	* 推进下一轮描述（中）/ Derive next-round instruction from model text (EN).
+	*
+	* 优先 REMAINING 协议；若未提供，则保持当前 remaining 不变。
+	* Priority: REMAINING protocol first; otherwise keep current remaining instruction unchanged.
+	*/
+	const deriveNextInstruction = (text, currentInstruction) => {
+		const parsed = parseRemainingInstruction(text);
+		if (parsed !== null) return {
+			nextInstruction: parsed,
+			hasRemainingProtocol: true
+		};
+		return {
+			nextInstruction: currentInstruction,
+			hasRemainingProtocol: false
+		};
+	};
+	/**
+	* 启发式任务剔除（中）/ Heuristic remaining reduction for linear instructions (EN).
+	*
+	* 在 REMAINING 缺失但本轮有执行动作时，按“线性片段”剔除已执行步数，避免下一轮继续携带整段原任务。
+	* When REMAINING is missing but actions were executed, drop executed step count from a linearized instruction.
+	*/
+	const 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);
+		if (parts.length <= 1) return currentInstruction;
+		const nextParts = parts.slice(Math.min(executedCount, parts.length));
+		if (nextParts.length === 0) return "";
+		return nextParts.join(" -> ");
+	};
 	for (let round = 0; round < maxRounds; round++) {
 		callbacks?.onRound?.(round);
-		const effectivePrompt = pageContext.latestSnapshot ? stripSnapshotFromPrompt(systemPrompt) : systemPrompt;
-		const chatMessages = buildCompactMessages(message, fullToolTrace, pageContext.latestSnapshot, pageContext.currentUrl, history);
+		usedRounds = round + 1;
+		if (!pageContext.latestSnapshot) await refreshSnapshot();
+		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({
+			role: "user",
+			content: [
+				"## Not-found retry context",
+				`Retry attempt: ${pendingNotFoundRetry.attempt}/${DEFAULT_NOT_FOUND_RETRY_ROUNDS}`,
+				"These tool targets were not found in previous execution:",
+				...pendingNotFoundRetry.tasks.map((task, i) => `${i + 1}. ${task.name}(${JSON.stringify(task.input)}) -> ${task.reason}`),
+				"Only retry unresolved targets that are now visible in the latest snapshot.",
+				"If still not found, return no tool calls and include REMAINING with the unresolved part."
+			].join("\n")
+		});
 		const response = await client.chat({
 			systemPrompt: effectivePrompt,
 			messages: chatMessages,
 			tools
 		});
+		inputTokens += response.usage?.inputTokens ?? 0;
+		outputTokens += response.usage?.outputTokens ?? 0;
+		const parsedInstructionState = deriveNextInstruction(response.text, remainingInstruction);
 		if (!response.toolCalls || response.toolCalls.length === 0) {
+			if (pendingNotFoundRetry) {
+				const unresolvedHint = response.text?.toLowerCase() ?? "";
+				if ((unresolvedHint.includes("找不到") || unresolvedHint.includes("未找到") || unresolvedHint.includes("not found") || unresolvedHint.includes("cannot find") || unresolvedHint.includes("unable to locate")) && pendingNotFoundRetry.attempt < DEFAULT_NOT_FOUND_RETRY_ROUNDS) {
+					pendingNotFoundRetry = {
+						...pendingNotFoundRetry,
+						attempt: pendingNotFoundRetry.attempt + 1
+					};
+					callbacks?.onText?.(`未命中目标，准备第 ${pendingNotFoundRetry.attempt} 次重试（等待 ${DEFAULT_NOT_FOUND_RETRY_WAIT_MS}ms）...`);
+					await sleep$1(DEFAULT_NOT_FOUND_RETRY_WAIT_MS);
+					await refreshSnapshot();
+					continue;
+				}
+				pendingNotFoundRetry = void 0;
+			}
+			if (parsedInstructionState.hasRemainingProtocol) remainingInstruction = parsedInstructionState.nextInstruction;
+			if (remainingInstruction.trim().length > 0 && round < maxRounds - 1) {
+				protocolViolationHint = [
+					"Protocol violation in previous round:",
+					"- Remaining task is not DONE, but no tool calls were returned.",
+					"This round MUST do one of:",
+					"1) Return actionable tool calls for visible targets; or",
+					"2) If truly complete, return a short summary and EXACTLY `REMAINING: DONE`.",
+					"Do NOT output planning/explaining text."
+				].join("\n");
+				lastRoundHadError = true;
+				await refreshSnapshot();
+				continue;
+			}
 			finalReply = response.text ?? "";
 			if (finalReply) callbacks?.onText?.(finalReply);
 			break;
 		}
-		if (response.text) callbacks?.onText?.(response.text);
+		protocolViolationHint = void 0;
+		const plannedTasksCurrentRound = buildTaskArray(response.toolCalls.map((tc) => ({
+			name: tc.name,
+			input: tc.input
+		})));
+		const plannedBatchKey = JSON.stringify(response.toolCalls.map((tc) => ({
+			name: tc.name,
+			input: tc.input
+		})));
+		if (plannedBatchKey === lastPlannedBatchKey) consecutiveSamePlannedBatch += 1;
+		else {
+			consecutiveSamePlannedBatch = 1;
+			lastPlannedBatchKey = plannedBatchKey;
+		}
+		if (consecutiveSamePlannedBatch >= 2 && !lastRoundHadError) {
+			finalReply = response.text?.trim() || "任务已完成。";
+			if (finalReply) callbacks?.onText?.(finalReply);
+			break;
+		}
 		if (dryRun) {
 			finalReply = response.text ? response.text + "\n\n" : "";
 			finalReply += "🔧 AI 请求调用以下工具（dry-run 模式，未执行）：\n";
@@ -229,103 +630,64 @@ async function executeAgentLoop(params) {
 			}
 			break;
 		}
+		let roundHasError = false;
+		const executedTaskCalls = [];
+		const roundMissingTasks = [];
 		for (const tc of response.toolCalls) {
-			callbacks?.onToolCall?.(tc.name, tc.input);
-			const latestUrl = await readPageUrl(registry);
-			if (latestUrl) {
-				if (!pageContext.currentUrl) pageContext.currentUrl = latestUrl;
-				else if (latestUrl !== pageContext.currentUrl) {
-					pageContext.currentUrl = latestUrl;
-					callbacks?.onBeforeRecoverySnapshot?.(latestUrl);
-					pageContext.latestSnapshot = await readPageSnapshot(registry, 8);
-					if (tc.name === "dom") {
-						const result = {
-							content: `URL 已变更为 ${latestUrl}，请基于最新快照重新定位目标元素。`,
-							details: {
-								error: true,
-								code: "URL_CHANGED_REQUIRE_NEW_SNAPSHOT",
-								url: latestUrl
-							}
-						};
-						allToolCalls.push({
-							name: tc.name,
-							input: tc.input,
-							result
-						});
-						fullToolTrace.push({
-							round,
-							name: tc.name,
-							input: tc.input,
-							result,
-							marker: "[URL变化待重定位]"
-						});
-						callbacks?.onToolResult?.(tc.name, result);
-						continue;
-					}
-				}
+			const redundant = checkRedundantSnapshot(tc.name, tc.input, pageContext.latestSnapshot, round);
+			if (redundant) {
+				appendToolTrace(round, tc.name, tc.input, redundant);
+				redundantInterceptCount += 1;
+				callbacks?.onToolResult?.(tc.name, redundant);
+				continue;
 			}
+			callbacks?.onToolCall?.(tc.name, tc.input);
 			let result = await registry.dispatch(tc.name, tc.input);
-			if (tc.name === "dom" && isElementNotFoundResult(result)) {
-				const key = buildToolCallKey(tc.name, tc.input);
-				const attempts = (actionRecoveryAttempts.get(key) ?? 0) + 1;
-				actionRecoveryAttempts.set(key, attempts);
-				const recoveryWaitMs = resolveRecoveryWaitMs(tc.input);
-				if (attempts <= DEFAULT_ACTION_RECOVERY_ROUNDS) {
-					await sleep$1(recoveryWaitMs);
-					callbacks?.onBeforeRecoverySnapshot?.();
-					pageContext.latestSnapshot = await readPageSnapshot(registry, 8);
-					result = {
-						content: [
-							toContentString(result.content),
-							"",
-							`自动恢复 ${attempts}/${DEFAULT_ACTION_RECOVERY_ROUNDS}：已刷新快照，请重新定位目标元素。`
-						].join("\n"),
-						details: {
-							error: true,
-							code: "ELEMENT_NOT_FOUND_RECOVERY",
-							recoveryAttempt: attempts,
-							recoveryMaxRounds: DEFAULT_ACTION_RECOVERY_ROUNDS
-						}
-					};
-				} else result = {
-					content: [
-						toContentString(result.content),
-						"",
-						`已达到最大自动恢复次数（${DEFAULT_ACTION_RECOVERY_ROUNDS}）。请调整操作目标后重试。`
-					].join("\n"),
-					details: {
-						error: true,
-						code: "ELEMENT_NOT_FOUND_MAX_RECOVERY_REACHED",
-						recoveryAttempt: attempts,
-						recoveryMaxRounds: DEFAULT_ACTION_RECOVERY_ROUNDS
-					}
-				};
-			}
-			allToolCalls.push({
+			const debounced = applySnapshotDebounce(tc.name, tc.input, result, consecutiveSnapshotCalls);
+			result = debounced.result;
+			consecutiveSnapshotCalls = debounced.consecutiveCount;
+			const recovered = await handleElementRecovery(tc.name, tc.input, result, actionRecoveryAttempts, registry, pageContext, callbacks);
+			if (recovered) result = recovered;
+			if (recovered?.details && typeof recovered.details === "object" && recovered.details.code === "ELEMENT_NOT_FOUND_RECOVERY") recoveryCount += 1;
+			appendToolTrace(round, tc.name, tc.input, result);
+			executedTaskCalls.push({
 				name: tc.name,
-				input: tc.input,
-				result
-			});
-			fullToolTrace.push({
-				round,
-				name: tc.name,
-				input: tc.input,
-				result
+				input: tc.input
 			});
-			if (tc.name === "page_info" && getToolAction(tc.input) === "snapshot") pageContext.latestSnapshot = toContentString(result.content);
-			if (tc.name === "navigate") {
-				const action = getToolAction(tc.input);
-				if ((action === "goto" || action === "back" || action === "forward" || action === "reload") && !hasToolError(result)) {
-					const newUrl = await readPageUrl(registry);
-					if (newUrl && newUrl !== pageContext.currentUrl) {
-						pageContext.currentUrl = newUrl;
-						callbacks?.onBeforeRecoverySnapshot?.(newUrl);
-						pageContext.latestSnapshot = await readPageSnapshot(registry, 8);
-					}
-				}
+			const missingTask = collectMissingTask(tc.name, tc.input, result);
+			if (missingTask) roundMissingTasks.push(missingTask);
+			if (result.details && typeof result.details === "object") roundHasError = roundHasError || Boolean(result.details.error);
+			if (tc.name === "page_info" && getToolAction(tc.input) === "snapshot") {
+				pageContext.latestSnapshot = toContentString(result.content);
+				recordSnapshotStats(pageContext.latestSnapshot);
 			}
+			await handleNavigationUrlChange(tc.name, tc.input, result, registry, pageContext, callbacks);
 			callbacks?.onToolResult?.(tc.name, result);
+			if (shouldForceRoundBreak(tc.name, tc.input)) break;
+		}
+		if (roundMissingTasks.length > 0) pendingNotFoundRetry = {
+			attempt: 1,
+			tasks: roundMissingTasks
+		};
+		else pendingNotFoundRetry = void 0;
+		if (parsedInstructionState.hasRemainingProtocol) remainingInstruction = parsedInstructionState.nextInstruction;
+		else {
+			const nextByHeuristic = reduceRemainingHeuristically(remainingInstruction, executedTaskCalls.length);
+			if (nextByHeuristic !== remainingInstruction) remainingInstruction = nextByHeuristic;
+			else roundHasError = true;
 		}
+		previousRoundModelOutput = parsedInstructionState.hasRemainingProtocol ? normalizeModelOutput(response.text) : `REMAINING: ${remainingInstruction || "DONE"}`;
+		lastRoundHadError = roundHasError;
+		previousRoundTasks = buildTaskArray(executedTaskCalls);
+		previousRoundPlannedTasks = plannedTasksCurrentRound;
+		const idleResult = detectIdleLoop(executedTaskCalls.map((tc) => tc.name), consecutiveReadOnlyRounds);
+		if (idleResult === -1) {
+			finalReply = response.text || "任务已完成。";
+			if (finalReply) callbacks?.onText?.(finalReply);
+			break;
+		}
+		consecutiveReadOnlyRounds = idleResult;
+		await refreshSnapshot();
 	}
 	const resultMessages = [...history ?? [], {
 		role: "user",
@@ -335,70 +697,146 @@ async function executeAgentLoop(params) {
 		role: "assistant",
 		content: finalReply
 	});
+	const successfulToolCalls = allToolCalls.filter((tc) => {
+		const details = tc.result.details;
+		return !(details && typeof details === "object" && Boolean(details.error));
+	}).length;
+	const failedToolCalls = allToolCalls.length - successfulToolCalls;
+	const metrics = {
+		roundCount: usedRounds,
+		totalToolCalls: allToolCalls.length,
+		successfulToolCalls,
+		failedToolCalls,
+		toolSuccessRate: allToolCalls.length > 0 ? Number((successfulToolCalls / allToolCalls.length).toFixed(4)) : 1,
+		recoveryCount,
+		redundantInterceptCount,
+		snapshotReadCount,
+		latestSnapshotSize: pageContext.latestSnapshot?.length ?? 0,
+		avgSnapshotSize: snapshotReadCount > 0 ? Math.round(snapshotSizeTotal / snapshotReadCount) : 0,
+		maxSnapshotSize: snapshotSizeMax,
+		inputTokens,
+		outputTokens
+	};
+	callbacks?.onMetrics?.(metrics);
 	return {
 		reply: finalReply,
 		toolCalls: allToolCalls,
-		messages: resultMessages
+		messages: resultMessages,
+		metrics
 	};
 }
 
 //#endregion
 //#region src/core/ai-client/constants.ts
-/**
-* 各 Provider 的默认 API 端点。
-*
-* - openai   → OpenAI 官方 API
-* - copilot  → GitHub Models API（使用 OpenAI 兼容格式）
-* - anthropic → Anthropic Messages API
-*/
+/** 默认端点映射（中）/ Default API endpoints by provider (EN). */
 const PROVIDER_ENDPOINTS = {
 	openai: "https://api.openai.com/v1",
 	copilot: "https://models.inference.ai.azure.com",
 	anthropic: "https://api.anthropic.com",
 	deepseek: "https://api.deepseek.com"
 };
-/**
-* 校验 provider 是否受支持。
-*
-* @throws 不支持的 provider 抛出 Error，附带支持列表
-*/
+/** 校验 provider（中）/ Validate provider support (EN). */
 function validateProvider(provider) {
 	if (!PROVIDER_ENDPOINTS[provider]) {
 		const supported = Object.keys(PROVIDER_ENDPOINTS).join(", ");
 		throw new Error(`Unknown AI provider: ${provider}. Supported: ${supported}`);
 	}
 }
-/**
-* 解析 provider 对应的 API 基础 URL。
-*
-* 优先使用用户自定义的 baseURL（如本地 Ollama），
-* 其次使用 PROVIDER_ENDPOINTS 中的默认值。
-*/
+/** 解析 baseURL（中）/ Resolve API base URL (EN). */
 function resolveBaseURL(config) {
 	return config.baseURL ?? PROVIDER_ENDPOINTS[config.provider] ?? "";
 }
 /**
-* 清理 TypeBox Schema — 去除 Symbol 等不可序列化的属性。
-*
-* TypeBox 的 Type.Object() 产物包含 Symbol key（如 [Kind]、[Hint]），
-* 这些 Symbol 在 JSON.stringify 时会被忽略，但某些 AI API 端点
-* 对 JSON Schema 做严格校验时可能报错。
-*
-* 通过 JSON roundtrip（stringify → parse）清理掉所有不可序列化的属性。
+* 清理 schema（中）/ Clean non-serializable fields from schema (EN).
 */
 function cleanSchema(schema) {
 	return JSON.parse(JSON.stringify(schema));
 }
 
 //#endregion
-//#region src/core/ai-client/custom.ts
+//#region src/core/ai-client/sse.ts
 /**
-* 可继承的 AI 客户端基类 — 实现 AIClient 接口。
+* 通用 SSE(JSON) 消费器（中）/ Generic SSE(JSON) consumer (EN).
 *
-* 设计原则：
-* - 实现 `AIClient` 接口 → 可直接传入 `executeAgentLoop()` 和 `WebAgent`
-* - 构造时注入 `chatHandler` → 无需继承即可自定义对话逻辑
-* - `chat()` 方法可被子类覆盖 → 支持继承式扩展（添加中间件逻辑）
+* 读取 response.body，按 SSE 规则拼装并分发 JSON data 事件。
+* Reads response body, assembles SSE frames, and dispatches JSON data events.
+*/
+async function consumeSSEJSON(response, onEvent, options = {}) {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	const stopOnDone = options.stopOnDone ?? true;
+	let buffer = "";
+	let currentEvent;
+	let dataLines = [];
+	let stoppedByDone = false;
+	async function readChunk() {
+		const readTimeoutMs = options.readTimeoutMs;
+		if (!readTimeoutMs || readTimeoutMs <= 0) return reader.read();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`SSE read timeout (${readTimeoutMs}ms)`));
+			}, readTimeoutMs);
+			reader.read().then((value) => {
+				clearTimeout(timer);
+				resolve(value);
+			}, (error) => {
+				clearTimeout(timer);
+				reject(error);
+			});
+		});
+	}
+	async function flushEvent() {
+		if (dataLines.length === 0) {
+			currentEvent = void 0;
+			return true;
+		}
+		const rawData = dataLines.join("\n").trim();
+		const event = currentEvent;
+		dataLines = [];
+		currentEvent = void 0;
+		if (!rawData) return true;
+		if (stopOnDone && rawData === "[DONE]") {
+			stoppedByDone = true;
+			return false;
+		}
+		try {
+			if (await onEvent(JSON.parse(rawData), {
+				event,
+				rawData
+			}) === false) return false;
+		} catch {}
+		return true;
+	}
+	while (true) {
+		const { done, value } = await readChunk();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const rawLine of lines) {
+			const trimmed = (rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine).trim();
+			if (!trimmed) {
+				if (!await flushEvent()) break;
+				continue;
+			}
+			if (trimmed.startsWith(":")) continue;
+			if (trimmed.startsWith("event:")) {
+				currentEvent = trimmed.slice(6).trim() || void 0;
+				continue;
+			}
+			if (trimmed.startsWith("data:")) dataLines.push(trimmed.slice(5).trimStart());
+		}
+		if (stoppedByDone) break;
+	}
+	if (!stoppedByDone) await flushEvent();
+	else await reader.cancel().catch(() => void 0);
+}
+
+//#endregion
+//#region src/core/ai-client/custom.ts
+/**
+* BaseAIClient 实现（中）/ BaseAIClient implementation of AIClient (EN).
 */
 var BaseAIClient = class {
 	/** 用户提供的对话处理函数 */
@@ -407,47 +845,21 @@ var BaseAIClient = class {
 		this.chatHandler = options.chatHandler;
 	}
 	/**
-	* 发送对话请求并获取 AI 响应。
-	*
-	* 默认实现直接委托给 `chatHandler`。
-	* 子类可覆盖此方法添加中间件逻辑（日志、重试、缓存等）。
-	*
-	* @param params - 统一格式的聊天参数
-	* @returns 统一格式的 AI 响应
+	* 发送对话请求（中）/ Dispatch chat request via handler (EN).
 	*/
 	async chat(params) {
 		return this.chatHandler(params);
 	}
+	/** SSE 消费复用入口（中）/ Reusable SSE(JSON) consumer for subclasses (EN). */
+	async consumeSSEJSON(response, onEvent, options) {
+		return consumeSSEJSON(response, onEvent, options);
+	}
 };
 
 //#endregion
 //#region src/core/ai-client/openai.ts
 /**
-* OpenAI / Copilot AI 客户端 — 继承 BaseAIClient。
-*
-* 封装完整的 OpenAI Chat Completions API 调用流程：
-* 1. buildOpenAIRequest() → 构建 HTTP 请求
-* 2. fetch() → 发送请求
-* 3. parseOpenAIResponse() → 解析响应为统一格式
-*
-* 使用示例：
-* ```ts
-* const client = new OpenAIClient({
-*   provider: "openai",
-*   model: "gpt-4o",
-*   apiKey: "sk-xxx",
-* });
-* const response = await client.chat({ systemPrompt, messages, tools });
-* ```
-*
-* 也可用于 Copilot（GitHub Models）：
-* ```ts
-* const client = new OpenAIClient({
-*   provider: "copilot",
-*   model: "gpt-4o",
-*   apiKey: "ghp_xxx",
-* });
-* ```
+* OpenAIClient 类（中）/ OpenAIClient class for OpenAI & Copilot (EN).
 */
 var OpenAIClient = class extends BaseAIClient {
 	/** AI 客户端配置（provider / model / apiKey / baseURL） */
@@ -455,30 +867,35 @@ var OpenAIClient = class extends BaseAIClient {
 	constructor(config) {
 		super({ chatHandler: async (params) => {
 			const req = buildOpenAIRequest(this.config, params);
-			const res = await fetch(req.url, {
+			if (!(this.config.stream ?? true)) {
+				const res = await fetch(req.url, {
+					method: req.method,
+					headers: req.headers,
+					body: req.body
+				});
+				if (!res.ok) {
+					const errText = await res.text();
+					throw new Error(`AI API ${res.status}: ${errText.slice(0, 500)}`);
+				}
+				return parseOpenAIResponse(await res.json());
+			}
+			const streamRes = await fetch(req.url, {
 				method: req.method,
 				headers: req.headers,
 				body: req.body
 			});
-			if (!res.ok) {
-				const errText = await res.text();
-				throw new Error(`AI API ${res.status}: ${errText.slice(0, 500)}`);
+			if (!streamRes.ok) {
+				const errText = await streamRes.text();
+				throw new Error(`AI API ${streamRes.status}: ${errText.slice(0, 500)}`);
 			}
-			return parseOpenAIResponse(await res.json());
+			if ((streamRes.headers.get("content-type") ?? "").includes("application/json")) return parseOpenAIResponse(await streamRes.json());
+			return parseOpenAIStream(streamRes, 2e4);
 		} });
 		this.config = config;
 	}
 };
 /**
-* 将统一格式的 ChatParams 转换为 OpenAI Chat Completions API 请求。
-*
-* 转换逻辑：
-* - system prompt → `{ role: "system", content }` 消息
-* - 工具定义 → `tools` 数组（function calling 格式）
-* - 工具结果 → 拆分为多条 `{ role: "tool", tool_call_id }` 消息
-* - AI 回复含工具调用 → `tool_calls` 字段
-*
-* 默认参数：temperature=0.3, max_tokens=8192, tool_choice="auto"
+* 构建 OpenAI 请求（中）/ Build OpenAI chat request payload (EN).
 */
 function buildOpenAIRequest(config, params) {
 	const baseURL = resolveBaseURL(config);
@@ -496,11 +913,16 @@ function buildOpenAIRequest(config, params) {
 		model: config.model,
 		messages: openaiMessages,
 		temperature: .3,
-		max_tokens: 8192
+		max_tokens: 4096
 	};
+	if (config.stream ?? true) {
+		body.stream = true;
+		body.stream_options = { include_usage: true };
+	}
 	if (openaiTools && openaiTools.length > 0) {
 		body.tools = openaiTools;
 		body.tool_choice = "auto";
+		body.parallel_tool_calls = true;
 	}
 	return {
 		url: `${baseURL}/chat/completions`,
@@ -513,14 +935,7 @@ function buildOpenAIRequest(config, params) {
 	};
 }
 /**
-* 将 OpenAI Chat Completions API 原始响应解析为统一的 AIChatResponse。
-*
-* 解析要点：
-* - 文本回复 → `choice.message.content`
-* - 工具调用 → `choice.message.tool_calls`，arguments 为 JSON 字符串需 parse
-* - Token 用量 → `usage.prompt_tokens` / `usage.completion_tokens`
-*
-* @throws 无有效 choice 时抛出 Error
+* 解析 OpenAI 响应（中）/ Parse raw OpenAI response into AIChatResponse (EN).
 */
 function parseOpenAIResponse(data) {
 	const d = data;
@@ -542,12 +957,7 @@ function parseOpenAIResponse(data) {
 	};
 }
 /**
-* 将统一消息格式转换为 OpenAI 消息数组。
-*
-* 三种特殊消息的处理：
-* 1. tool 消息（工具结果）→ 每个结果拆分为单独的 `role: "tool"` 消息
-* 2. assistant 含 toolCalls → 附带 `tool_calls` 字段
-* 3. 其他消息 → 直接映射 role + content
+* 消息转换（中）/ Convert unified messages to OpenAI format (EN).
 */
 function convertMessages$1(systemPrompt, messages) {
 	const result = [{
@@ -577,26 +987,56 @@ function convertMessages$1(systemPrompt, messages) {
 	});
 	return result;
 }
+/**
+* 解析 OpenAI SSE（中）/ Parse OpenAI SSE stream into unified response (EN).
+*/
+async function parseOpenAIStream(response, readTimeoutMs = 2e4) {
+	if (!response.body) return parseOpenAIResponse(await response.json());
+	let text = "";
+	const toolCallMap = /* @__PURE__ */ new Map();
+	let usage;
+	await consumeSSEJSON(response, (event) => {
+		const chunk = event;
+		const delta = chunk.choices?.[0]?.delta;
+		if (delta?.content) text += delta.content;
+		if (delta?.tool_calls) for (const tc of delta.tool_calls) {
+			const idx = tc.index ?? 0;
+			const existing = toolCallMap.get(idx);
+			if (existing) {
+				if (tc.function?.arguments) existing.arguments += tc.function.arguments;
+			} else toolCallMap.set(idx, {
+				id: tc.id ?? "",
+				name: tc.function?.name ?? "",
+				arguments: tc.function?.arguments ?? ""
+			});
+		}
+		if (chunk.usage) usage = {
+			inputTokens: chunk.usage.prompt_tokens ?? 0,
+			outputTokens: chunk.usage.completion_tokens ?? 0
+		};
+	}, {
+		readTimeoutMs,
+		stopOnDone: true
+	});
+	const toolCalls = [];
+	for (const [, tc] of [...toolCallMap.entries()].sort((a, b) => a[0] - b[0])) try {
+		toolCalls.push({
+			id: tc.id,
+			name: tc.name,
+			input: JSON.parse(tc.arguments)
+		});
+	} catch {}
+	return {
+		text: text || void 0,
+		toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+		usage
+	};
+}
 
 //#endregion
 //#region src/core/ai-client/anthropic.ts
 /**
-* Anthropic AI 客户端 — 继承 BaseAIClient。
-*
-* 封装完整的 Anthropic Messages API 调用流程：
-* 1. buildAnthropicRequest() → 构建 HTTP 请求
-* 2. fetch() → 发送请求
-* 3. parseAnthropicResponse() → 解析响应为统一格式
-*
-* 使用示例：
-* ```ts
-* const client = new AnthropicClient({
-*   provider: "anthropic",
-*   model: "claude-sonnet-4-20250514",
-*   apiKey: "sk-ant-xxx",
-* });
-* const response = await client.chat({ systemPrompt, messages, tools });
-* ```
+* AnthropicClient 类（中）/ AnthropicClient class (EN).
 */
 var AnthropicClient = class extends BaseAIClient {
 	/** AI 客户端配置（provider / model / apiKey / baseURL） */
@@ -604,6 +1044,18 @@ var AnthropicClient = class extends BaseAIClient {
 	constructor(config) {
 		super({ chatHandler: async (params) => {
 			const req = buildAnthropicRequest(this.config, params);
+			if (!(this.config.stream ?? true)) {
+				const res = await fetch(req.url, {
+					method: req.method,
+					headers: req.headers,
+					body: req.body
+				});
+				if (!res.ok) {
+					const errText = await res.text();
+					throw new Error(`AI API ${res.status}: ${errText.slice(0, 500)}`);
+				}
+				return parseAnthropicResponse(await res.json());
+			}
 			const res = await fetch(req.url, {
 				method: req.method,
 				headers: req.headers,
@@ -613,22 +1065,14 @@ var AnthropicClient = class extends BaseAIClient {
 				const errText = await res.text();
 				throw new Error(`AI API ${res.status}: ${errText.slice(0, 500)}`);
 			}
-			return parseAnthropicResponse(await res.json());
+			if ((res.headers.get("content-type") ?? "").includes("application/json")) return parseAnthropicResponse(await res.json());
+			return parseAnthropicStream(res);
 		} });
 		this.config = config;
 	}
 };
 /**
-* 将统一格式的 ChatParams 转换为 Anthropic Messages API 请求。
-*
-* 关键格式差异（与 OpenAI 相比）：
-* - system prompt → body.system 字段（非消息数组元素）
-* - 工具定义 → input_schema（而非 parameters）
-* - 工具结果 → user 角色 + tool_result content block
-* - AI 工具调用 → assistant 角色 + tool_use content block
-*
-* max_tokens 策略：opus 模型 16384，其他模型 8192。
-* 认证头使用 `x-api-key`（而非 Authorization Bearer）。
+* 构建 Anthropic 请求（中）/ Build Anthropic Messages API request (EN).
 */
 function buildAnthropicRequest(config, params) {
 	const baseURL = resolveBaseURL(config);
@@ -645,6 +1089,7 @@ function buildAnthropicRequest(config, params) {
 		system: systemPrompt,
 		messages: anthropicMessages
 	};
+	if (config.stream ?? true) body.stream = true;
 	if (anthropicTools && anthropicTools.length > 0) body.tools = anthropicTools;
 	return {
 		url: `${baseURL}/v1/messages`,
@@ -658,13 +1103,7 @@ function buildAnthropicRequest(config, params) {
 	};
 }
 /**
-* 将 Anthropic Messages API 原始响应解析为统一的 AIChatResponse。
-*
-* Anthropic 使用 content block 数组返回多种内容：
-* - type="text"     → 文本回复（可能多个，合并为一个字符串）
-* - type="tool_use" → 工具调用（id + name + input）
-*
-* Token 用量字段名也不同：input_tokens / output_tokens（非 prompt_tokens）。
+* 解析 Anthropic 响应（中）/ Parse raw Anthropic response (EN).
 */
 function parseAnthropicResponse(data) {
 	const d = data;
@@ -684,12 +1123,7 @@ function parseAnthropicResponse(data) {
 	};
 }
 /**
-* 将统一消息格式转换为 Anthropic 消息数组。
-*
-* 关键差异处理：
-* 1. 过滤 system 消息（Anthropic 通过 body.system 传入）
-* 2. tool 角色消息 → user 角色 + tool_result content block
-* 3. assistant 含 toolCalls → text + tool_use content blocks
+* 消息格式转换（中）/ Convert unified messages to Anthropic format (EN).
 */
 function convertMessages(messages) {
 	return messages.filter((m) => m.role !== "system").map((m) => {
@@ -724,64 +1158,80 @@ function convertMessages(messages) {
 		};
 	});
 }
+/**
+* 解析 Anthropic SSE（中）/ Parse Anthropic SSE stream (EN).
+*/
+async function parseAnthropicStream(response) {
+	if (!response.body) return parseAnthropicResponse(await response.json());
+	let text = "";
+	const toolCalls = [];
+	let currentToolUse = null;
+	let inputTokens = 0;
+	let outputTokens = 0;
+	await consumeSSEJSON(response, (event) => {
+		switch (event.type) {
+			case "message_start":
+				inputTokens = event.message?.usage?.input_tokens ?? 0;
+				break;
+			case "content_block_start": {
+				const block = event.content_block;
+				if (block?.type === "tool_use") currentToolUse = {
+					id: block.id ?? "",
+					name: block.name ?? "",
+					inputJson: ""
+				};
+				break;
+			}
+			case "content_block_delta": {
+				const delta = event.delta;
+				if (delta?.type === "text_delta") text += delta.text ?? "";
+				else if (delta?.type === "input_json_delta" && currentToolUse) currentToolUse.inputJson += delta.partial_json ?? "";
+				break;
+			}
+			case "content_block_stop":
+				if (currentToolUse) {
+					try {
+						toolCalls.push({
+							id: currentToolUse.id,
+							name: currentToolUse.name,
+							input: JSON.parse(currentToolUse.inputJson || "{}")
+						});
+					} catch {}
+					currentToolUse = null;
+				}
+				break;
+			case "message_delta":
+				outputTokens = event.usage?.output_tokens ?? 0;
+				break;
+		}
+	}, { stopOnDone: false });
+	return {
+		text: text || void 0,
+		toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
+		usage: inputTokens > 0 || outputTokens > 0 ? {
+			inputTokens,
+			outputTokens
+		} : void 0
+	};
+}
 
 //#endregion
 //#region src/core/ai-client/deepseek.ts
 /**
-* DeepSeek AI 客户端。
-*
-* DeepSeek 使用 OpenAI 兼容的 Chat Completions API 格式，
-* 因此直接继承 OpenAIClient，复用请求构建和响应解析逻辑。
-*
-* 差异点（相对于 OpenAI）：
-* - 端点：https://api.deepseek.com（Constants 中配置）
-* - 模型：deepseek-chat（V3）、deepseek-reasoner（R1）等
-* - 认证：Authorization: Bearer <API Key>（与 OpenAI 相同）
-* - tool_calls 格式与 OpenAI 完全一致
-*
-* 继承关系：
-*   BaseAIClient（custom.ts）
-*     └── OpenAIClient（openai.ts）
-*           └── DeepSeekClient（本文件）— 可覆盖默认参数
+* DeepSeek 客户端封装（中）/ DeepSeek client wrapper (EN).
 *
-* 使用示例：
-* ```ts
-* const client = new DeepSeekClient({
-*   provider: "deepseek",
-*   model: "deepseek-chat",
-*   apiKey: "sk-xxx",
-* });
-* const response = await client.chat({ systemPrompt, messages, tools });
-* ```
-*
-* 参考文档：
-* - Tool Calls: https://api-docs.deepseek.com/zh-cn/guides/tool_calls
-* - Chat API:   https://api-docs.deepseek.com/zh-cn/api/create-chat-completion/
+* DeepSeek 与 OpenAI Chat Completions 兼容，直接复用 OpenAIClient。
+* DeepSeek is OpenAI-compatible, so it reuses OpenAIClient behavior.
 */
 /**
-* DeepSeek AI 客户端 — 继承 OpenAIClient。
-*
-* DeepSeek API 与 OpenAI Chat Completions API 完全兼容，
-* 包括 tool_calls、function calling、消息格式等。
-*
-* 如需自定义 DeepSeek 特有行为（如 strict 模式、思考模式等），
-* 可在此类中覆盖相关方法。
+* DeepSeek 客户端类（中）/ DeepSeek client class extending OpenAIClient (EN).
 */
 var DeepSeekClient = class extends OpenAIClient {};
 
 //#endregion
 //#region src/core/ai-client/index.ts
 /**
-* 创建 AI 客户端（高层 API）。
-*
-* 根据 provider 自动创建对应的客户端类实例：
-* - openai / copilot → new OpenAIClient(config)
-* - anthropic        → new AnthropicClient(config)
-*
-* 返回 AIClient 接口，调用 chat() 即可与 AI 对话。
-*
-* @param config - 包含 provider、model、apiKey 等配置
-* @returns AIClient 实例（OpenAIClient 或 AnthropicClient）
+* 创建 AI 客户端（中）/ Create AI client by provider (EN).
 */
 function createAIClient(config) {
 	validateProvider(config.provider);
@@ -849,31 +1299,78 @@ var ToolRegistry = class {
 //#endregion
 //#region src/core/system-prompt.ts
 /**
-* 构建系统提示词。
-* 由两部分组成：身份描述 + 可用工具列表。
+* 规范化额外指令（中）/ Normalize additional instructions (EN).
+*/
+function normalizeExtraInstructions(input) {
+	if (!input) return [];
+	return (Array.isArray(input) ? input : [input]).map((s) => s.trim()).filter(Boolean);
+}
+/**
+* 构建系统提示词（中）/ Build system prompt (EN).
+*
+* 约束：
+* - 输出给模型的提示词正文统一为英文。
+* - 中文仅用于代码注释，便于团队维护。
+*
+* Constraints:
+* - Prompt text sent to model stays English-only.
+* - Chinese content is used in code comments only for maintainability.
 */
 function buildSystemPrompt(params = {}) {
 	const sections = [];
-	sections.push("You are AutoPilot, an AI agent embedded in the user's web page.\nYou can click, fill forms, read content, navigate, and execute JavaScript.\n\n## 操作规则\n\n1. 快照中每个元素末尾的 `#xxxx` 是 hash ID。操作时**必须**用 `#xxxx` 作为 dom 工具的 selector 参数。\n2. **禁止**猜测 CSS 选择器，只用快照中的 hash ID。\n3. 多个相似元素时，根据层级结构、所在功能区域和用户意图判断目标。\n4. 快照看不到目标时，先滚动页面或用 snapshot 获取更深层级。\n5. 破坏性操作前先与用户确认。\n\n## 决策流程\n\n每一轮你都会收到：**用户的原始请求**、**已完成的操作步骤**、**当前页面 DOM 快照**。\n你必须严格按以下流程决策：\n\n1. **阅读用户请求** — 理解最终目标。\n2. **审查已完成步骤** — 标记 ✅ 的操作已成功执行，**不要重复**；标记 ❌ 的操作失败了，需要换一种方式。\n3. **对照当前快照** — 确认页面当前状态，找到下一步要操作的目标元素。\n4. **只执行下一步** — 基于以上判断，只调用完成目标所需的下一个工具调用，不跳步、不重复。\n\n**关键**：已完成的步骤代表页面已经发生了变化，当前快照才是页面的真实状态。");
+	sections.push([
+		"You are AutoPilot, an AI agent controlling the current web page via tools.",
+		"",
+		"## Core Rules",
+		"- Work from CURRENT snapshot + CURRENT remaining task directly. Do not restate the request.",
+		"- Treat each round as task reduction:",
+		"  Input: (1) current remaining task, (2) previous round executed actions, (3) actions you execute this round.",
+		"  Output: new remaining task after removing this-round actions.",
+		"- Use only visible targets from snapshot. Use #hashID as selector. Do not guess CSS selectors.",
+		"- Batch independent visible actions in one round. Do not split one form into many rounds unnecessarily.",
+		"- If an action will change DOM (open modal, navigate), stop after that action batch and continue next round with new snapshot.",
+		"- Do NOT call page_info (snapshot/query/get_url/get_title). Snapshot is already provided every round.",
+		"- For dropdown/select, use dom action=select_option (or fill on select).",
+		"- Do NOT interact with AutoPilot UI unless user explicitly asks.",
+		"",
+		"## Output Contract",
+		"- Return tool calls for this round.",
+		"- Also include one plain text line:",
+		"  REMAINING: <new remaining task after this round>",
+		"  or REMAINING: DONE",
+		"",
+		"## Minimal Example",
+		"Task: click button -> type \"abc\" in input -> send",
+		"Round1 execute: click button",
+		"Remaining: type \"abc\" in input -> send",
+		"Round2 execute: type \"abc\" in input",
+		"Remaining: send",
+		"Round3 execute: send",
+		"Remaining: DONE"
+	].join("\n"));
 	const tools = params.tools ?? [];
 	if (tools.length > 0) {
 		const toolLines = tools.map((t) => `- **${t.name}**: ${t.description}`);
 		sections.push("## Available Tools\n\n" + toolLines.join("\n") + "\n\nUse tools when needed to complete the user's request.");
 	}
+	if (params.thinkingLevel) sections.push(["## Reasoning Profile", `- Thinking level: ${params.thinkingLevel}`].join("\n"));
+	const extraInstructions = normalizeExtraInstructions(params.extraInstructions);
+	if (extraInstructions.length > 0) sections.push(["## Extra Instructions", ...extraInstructions.map((line) => `- ${line}`)].join("\n"));
 	return sections.join("\n\n");
 }
 
 //#endregion
-//#region src/web/dom-tool.ts
+//#region src/web/tools/dom-tool.ts
 /**
 * DOM Tool — 基于 Web API 的 DOM 操作工具。
 *
 * 替代 Playwright 的 click/fill/type 等操作，直接在页面上下文中执行。
 * 运行环境：浏览器 Content Script。
 *
-* 支持 11 种动作：
+* 支持 12 种动作：
 *   click        — 点击元素
-*   fill         — 填写输入框（清空后设值）
+*   fill         — 填写可编辑控件（input/textarea/select/contenteditable）
+*   select_option — 选择下拉框选项（value/label）
 *   type         — 逐字符模拟键入
 *   focus        — 聚焦元素
 *   hover        — 鼠标悬停（触发 mouseenter/mouseover）
@@ -910,7 +1407,7 @@ function queryElement(selector) {
 		const el = document.querySelector(selector);
 		if (!el) return `未找到匹配 "${selector}" 的元素`;
 		return el;
-	} catch (e) {
+	} catch {
 		return `选择器语法错误: ${selector}`;
 	}
 }
@@ -988,11 +1485,11 @@ function createDomTool() {
 		name: "dom",
 		description: [
 			"Perform DOM operations on the current page.",
-			"Actions: click, fill, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
+			"Actions: click, fill, select_option, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
 			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "DOM action: click | fill | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class" }),
+			action: Type.String({ description: "DOM action: click | fill | select_option | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class" }),
 			selector: Type.String({ description: "Element ref ID from snapshot (e.g. #r0, #r5) or CSS selector" }),
 			value: Type.Optional(Type.String({ description: "Value for fill/type/set_attr actions" })),
 			key: Type.Optional(Type.String({ description: "Key name for press action (e.g. Enter, Escape, Tab, ArrowDown, ArrowUp, Backspace, Delete, Space)" })),
@@ -1046,6 +1543,15 @@ function createDomTool() {
 			try {
 				switch (action) {
 					case "click":
+						if (el instanceof HTMLOptionElement) {
+							const parent = el.parentElement;
+							if (parent instanceof HTMLSelectElement) {
+								parent.focus();
+								parent.value = el.value;
+								dispatchInputEvents(parent);
+								return { content: `已选择 ${describeElement(parent)} 的选项 "${el.value}"` };
+							}
+						}
 						if (el instanceof HTMLElement) {
 							el.focus();
 							el.click();
@@ -1091,6 +1597,24 @@ function createDomTool() {
 							el.focus();
 							el.value = value;
 							dispatchInputEvents(el);
+						} else if (el instanceof HTMLSelectElement) {
+							el.focus();
+							let matched = false;
+							for (const option of Array.from(el.options)) if (option.value === value) {
+								el.value = option.value;
+								matched = true;
+								break;
+							}
+							if (!matched) {
+								const normalized = value.trim().toLowerCase();
+								for (const option of Array.from(el.options)) if (option.text.trim().toLowerCase() === normalized) {
+									el.value = option.value;
+									matched = true;
+									break;
+								}
+							}
+							if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
+							dispatchInputEvents(el);
 						} else if (el instanceof HTMLElement && el.isContentEditable) {
 							el.focus();
 							el.textContent = value;
@@ -1098,6 +1622,29 @@ function createDomTool() {
 						} else return { content: `"${selector}" 不是可编辑元素` };
 						return { content: `已填写 ${describeElement(el)}: "${value}"` };
 					}
+					case "select_option": {
+						const value = params.value;
+						if (value === void 0) return { content: "缺少 value 参数" };
+						if (!(el instanceof HTMLSelectElement)) return { content: `"${selector}" 不是下拉框元素` };
+						el.focus();
+						let matched = false;
+						for (const option of Array.from(el.options)) if (option.value === value) {
+							el.value = option.value;
+							matched = true;
+							break;
+						}
+						if (!matched) {
+							const normalized = value.trim().toLowerCase();
+							for (const option of Array.from(el.options)) if (option.text.trim().toLowerCase() === normalized) {
+								el.value = option.value;
+								matched = true;
+								break;
+							}
+						}
+						if (!matched) return { content: `"${selector}" 下拉框中不存在选项 "${value}"` };
+						dispatchInputEvents(el);
+						return { content: `已选择 ${describeElement(el)}: "${el.value}"` };
+					}
 					case "type": {
 						const value = params.value;
 						if (value === void 0) return { content: "缺少 value 参数" };
@@ -1166,7 +1713,7 @@ function createDomTool() {
 }
 
 //#endregion
-//#region src/web/page-info-tool.ts
+//#region src/web/tools/page-info-tool.ts
 /**
 * Page Info Tool — 基于 Web API 的页面信息获取工具。
 *
@@ -1206,6 +1753,11 @@ function generateSnapshot(root = document.body, options = {}) {
 	const maxDepth = opts.maxDepth ?? 6;
 	const viewportOnly = opts.viewportOnly ?? true;
 	const pruneLayout = opts.pruneLayout ?? true;
+	const maxNodes = opts.maxNodes ?? 220;
+	const maxChildren = opts.maxChildren ?? 25;
+	const maxTextLength = opts.maxTextLength ?? 40;
+	let emittedNodes = 0;
+	let truncatedByNodeBudget = false;
 	const refStore = opts.refStore;
 	const SKIP_TAGS = new Set([
 		"SCRIPT",
@@ -1247,14 +1799,18 @@ function generateSnapshot(root = document.body, options = {}) {
 		"title",
 		"for",
 		"action",
-		"method",
-		"target",
-		"min",
-		"max",
-		"pattern",
-		"maxlength",
-		"tabindex"
+		"method"
 	];
+	const INTERACTIVE_TAGS = new Set([
+		"A",
+		"BUTTON",
+		"INPUT",
+		"TEXTAREA",
+		"SELECT",
+		"OPTION",
+		"LABEL",
+		"SUMMARY"
+	]);
 	/** 布尔状态属性 — 只在存在时输出（无值），如 disabled、checked */
 	const BOOLEAN_ATTRS = [
 		"disabled",
@@ -1262,13 +1818,8 @@ function generateSnapshot(root = document.body, options = {}) {
 		"readonly",
 		"required",
 		"selected",
-		"hidden",
-		"multiple",
-		"autofocus",
-		"open"
+		"hidden"
 	];
-	/** 内联事件属性前缀 */
-	const EVENT_PREFIX = "on";
 	/**
 	* 计算元素在父节点中同标签兄弟里的序号（1-based，XPath 规范）。
 	* 如果同标签兄弟只有一个，返回空字符串（无需索引消歧）。
@@ -1311,9 +1862,22 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (directText) return false;
 		return true;
 	}
+	function isInteractiveElement(el) {
+		if (INTERACTIVE_TAGS.has(el.tagName)) return true;
+		if (el.hasAttribute("onclick")) return true;
+		if (el.hasAttribute("role")) return true;
+		if (el.hasAttribute("tabindex")) return true;
+		if (el.hasAttribute("aria-label")) return true;
+		return false;
+	}
 	function walk(el, depth, parentPath) {
+		if (emittedNodes >= maxNodes) {
+			truncatedByNodeBudget = true;
+			return "";
+		}
 		if (depth > maxDepth) return "";
 		if (SKIP_TAGS.has(el.tagName)) return "";
+		if (el.hasAttribute("data-autopilot-ignore")) return "";
 		const style = window.getComputedStyle(el);
 		if (style.display === "none" || style.visibility === "hidden") return "";
 		if (!isInViewport(el, depth)) return "";
@@ -1325,22 +1889,19 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (elId) attrs.push(`id="${elId}"`);
 		const className = el.getAttribute("class")?.trim();
 		if (className) {
-			const classes = className.split(/\s+/).filter((c) => c && !c.startsWith("data-v-") && c.length < 30).slice(0, 2).join(" ");
-			if (classes) attrs.push(`class="${classes}"`);
+			const cls = className.split(/\s+/).find((c) => c && !c.startsWith("data-v-") && c.length < 25 && !/^[a-z]{1,2}\d|^_|^css-/.test(c));
+			if (cls) attrs.push(`class="${cls}"`);
 		}
 		for (const attr of INTERACTIVE_ATTRS) {
 			const val = el.getAttribute(attr);
 			if (val) attrs.push(`${attr}="${val}"`);
 		}
 		for (const attr of BOOLEAN_ATTRS) if (el.hasAttribute(attr)) attrs.push(attr);
-		const events = [];
-		for (const attrObj of Array.from(el.attributes)) if (attrObj.name.startsWith(EVENT_PREFIX)) events.push(attrObj.name);
-		if (events.length > 0) attrs.push(`events=[${events.join(",")}]`);
-		const dataAttrs = [];
-		for (const attrObj of Array.from(el.attributes)) if (attrObj.name.startsWith("data-") && !attrObj.name.match(/^data-v-/) && dataAttrs.length < 2) dataAttrs.push(`${attrObj.name}="${attrObj.value.slice(0, 30)}"`);
-		if (dataAttrs.length > 0) attrs.push(...dataAttrs);
+		if (el.hasAttribute("onclick")) attrs.push("onclick");
+		const testId = el.getAttribute("data-testid") || el.getAttribute("data-test-id");
+		if (testId) attrs.push(`data-testid="${testId.slice(0, 25)}"`);
 		if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.value) {
-			const currentVal = el.value.slice(0, 60);
+			const currentVal = el.value.slice(0, 40);
 			if (el.getAttribute("value") !== currentVal) attrs.push(`val="${currentVal}"`);
 		}
 		let directText = "";
@@ -1353,28 +1914,45 @@ function generateSnapshot(root = document.body, options = {}) {
 		}
 		directText = directText.trim();
 		if (isEmptyLayoutContainer(el, directText)) {
+			const allChildren = Array.from(el.children);
+			const interactiveChildren = allChildren.filter(isInteractiveElement);
+			const nonInteractiveChildren = allChildren.filter((child) => !isInteractiveElement(child));
+			const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
+			const selectedChildren = orderedChildren.slice(0, maxChildren);
+			const omittedChildren = orderedChildren.length - selectedChildren.length;
 			const childLines = [];
-			for (let i = 0; i < el.children.length; i++) {
-				const childResult = walk(el.children[i], depth, currentPath);
+			for (let i = 0; i < selectedChildren.length; i++) {
+				const childResult = walk(selectedChildren[i], depth, currentPath);
 				if (childResult) childLines.push(childResult);
 			}
+			if (omittedChildren > 0) childLines.push(`${"  ".repeat(depth)}... (${omittedChildren} children omitted)`);
 			return childLines.join("\n");
 		}
 		let line = `${indent}[${tag}]`;
-		if (directText) line += ` "${directText.slice(0, 60)}"`;
+		if (directText) line += ` "${directText.slice(0, maxTextLength)}"`;
 		if (attrs.length) line += ` ${attrs.join(" ")}`;
 		if (refStore) {
 			const hashId = refStore.set(el, currentPath);
 			line += ` #${hashId}`;
 		} else line += ` ref="${currentPath}"`;
 		const lines = [line];
-		for (let i = 0; i < el.children.length; i++) {
-			const childResult = walk(el.children[i], depth + 1, currentPath);
+		emittedNodes++;
+		const allChildren = Array.from(el.children);
+		const interactiveChildren = allChildren.filter(isInteractiveElement);
+		const nonInteractiveChildren = allChildren.filter((child) => !isInteractiveElement(child));
+		const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
+		const selectedChildren = orderedChildren.slice(0, maxChildren);
+		const omittedChildren = orderedChildren.length - selectedChildren.length;
+		for (let i = 0; i < selectedChildren.length; i++) {
+			const childResult = walk(selectedChildren[i], depth + 1, currentPath);
 			if (childResult) lines.push(childResult);
 		}
+		if (omittedChildren > 0) lines.push(`${indent}  ... (${omittedChildren} children omitted)`);
 		return lines.join("\n");
 	}
-	return walk(root, 0, "") || "(空页面)";
+	const output = walk(root, 0, "") || "(空页面)";
+	if (!truncatedByNodeBudget) return output;
+	return `${output}\n... (snapshot truncated: maxNodes=${maxNodes})`;
 }
 /**
 * 查询所有匹配元素并返回摘要信息（标签、文本、关键属性）。
@@ -1395,7 +1973,7 @@ function queryAllElements(selector, limit = 20) {
 		}
 		if (elements.length > limit) results.push(`  ...还有 ${elements.length - limit} 个元素`);
 		return results.join("\n");
-	} catch (e) {
+	} catch {
 		return `选择器语法错误: ${selector}`;
 	}
 }
@@ -1412,7 +1990,10 @@ function createPageInfoTool() {
 			selector: Type.Optional(Type.String({ description: "CSS selector for query_all action" })),
 			maxDepth: Type.Optional(Type.Number({ description: "Max depth for snapshot (default: 6)" })),
 			viewportOnly: Type.Optional(Type.Boolean({ description: "Only snapshot elements visible in viewport (default: true)" })),
-			pruneLayout: Type.Optional(Type.Boolean({ description: "Collapse empty layout containers like div/span (default: true)" }))
+			pruneLayout: Type.Optional(Type.Boolean({ description: "Collapse empty layout containers like div/span (default: true)" })),
+			maxNodes: Type.Optional(Type.Number({ description: "Maximum nodes to include in snapshot (default: 220)" })),
+			maxChildren: Type.Optional(Type.Number({ description: "Maximum children per element (default: 25)" })),
+			maxTextLength: Type.Optional(Type.Number({ description: "Maximum text length per node (default: 40)" }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
@@ -1436,10 +2017,16 @@ function createPageInfoTool() {
 						const maxDepth = params.maxDepth ?? 6;
 						const viewportOnly = params.viewportOnly ?? true;
 						const pruneLayout = params.pruneLayout ?? true;
+						const maxNodes = params.maxNodes ?? 220;
+						const maxChildren = params.maxChildren ?? 25;
+						const maxTextLength = params.maxTextLength ?? 40;
 						return { content: generateSnapshot(document.body, {
 							maxDepth,
 							viewportOnly,
 							pruneLayout,
+							maxNodes,
+							maxChildren,
+							maxTextLength,
 							refStore: getActiveRefStore()
 						}) };
 					}
@@ -1464,7 +2051,7 @@ function createPageInfoTool() {
 }
 
 //#endregion
-//#region src/web/navigate-tool.ts
+//#region src/web/tools/navigate-tool.ts
 /**
 * Navigate Tool — 基于 Web API 的页面导航工具。
 *
@@ -1544,7 +2131,7 @@ function createNavigateTool() {
 }
 
 //#endregion
-//#region src/web/wait-tool.ts
+//#region src/web/tools/wait-tool.ts
 /**
 * Wait Tool — 基于 MutationObserver 的元素等待工具。
 *
@@ -1714,7 +2301,7 @@ function createWaitTool() {
 }
 
 //#endregion
-//#region src/web/evaluate-tool.ts
+//#region src/web/tools/evaluate-tool.ts
 /**
 * Evaluate Tool — 在页面上下文中执行任意 JavaScript 表达式。
 *
@@ -1734,7 +2321,7 @@ function createWaitTool() {
 function safeEvaluate(expression) {
 	try {
 		return { result: new Function(`"use strict"; return (${expression});`)() };
-	} catch (err) {
+	} catch {
 		try {
 			return { result: new Function(`"use strict"; ${expression}`)() };
 		} catch (err2) {
@@ -2000,6 +2587,7 @@ var WebAgent = class {
 	provider;
 	model;
 	baseURL;
+	stream;
 	dryRun;
 	maxRounds;
 	customSystemPrompt;
@@ -2021,8 +2609,9 @@ var WebAgent = class {
 		this.provider = options.provider ?? "copilot";
 		this.model = options.model ?? "gpt-4o";
 		this.baseURL = options.baseURL;
+		this.stream = options.stream ?? true;
 		this.dryRun = options.dryRun ?? false;
-		this.maxRounds = options.maxRounds ?? 10;
+		this.maxRounds = options.maxRounds ?? 40;
 		this.customSystemPrompt = options.systemPrompt;
 		this.memory = options.memory ?? false;
 		this.autoSnapshot = options.autoSnapshot ?? true;
@@ -2065,6 +2654,14 @@ var WebAgent = class {
 	setModel(model) {
 		this.model = model;
 	}
+	/** 设置是否启用流式输出（SSE） */
+	setStream(enabled) {
+		this.stream = enabled;
+	}
+	/** 获取当前流式输出开关状态 */
+	getStream() {
+		return this.stream;
+	}
 	/** 切换干运行模式 */
 	setDryRun(enabled) {
 		this.dryRun = enabled;
@@ -2116,14 +2713,19 @@ var WebAgent = class {
 		let systemPrompt = this.customSystemPrompt ?? buildSystemPrompt({ tools: this.registry.getDefinitions() });
 		const refStore = new RefStore(globalThis.location?.href);
 		setActiveRefStore(refStore);
-		if (this.autoSnapshot) try {
+		let initialSnapshot;
+		try {
 			const snapshot = generateSnapshot(document.body, {
 				maxDepth: 8,
+				viewportOnly: false,
+				maxNodes: 500,
+				maxChildren: 30,
 				...this.snapshotOptions,
 				refStore
 			});
-			this.callbacks.onSnapshot?.(snapshot);
-			systemPrompt += wrapSnapshot(`\n\n## 当前页面 DOM 快照\n\n\`\`\`\n${snapshot}\n\`\`\``);
+			initialSnapshot = snapshot;
+			if (this.autoSnapshot) this.callbacks.onSnapshot?.(snapshot);
+			systemPrompt += wrapSnapshot(`\n\n## DOM Snapshot\n\`\`\`\n${snapshot}\n\`\`\``);
 		} catch {}
 		const wrappedCallbacks = {
 			...this.callbacks,
@@ -2138,6 +2740,7 @@ var WebAgent = class {
 			registry: this.registry,
 			systemPrompt,
 			message,
+			initialSnapshot,
 			history: this.memory ? this.history : void 0,
 			dryRun: this.dryRun,
 			maxRounds: this.maxRounds,
@@ -2159,7 +2762,8 @@ var WebAgent = class {
 			provider: this.provider,
 			model: this.model,
 			apiKey: this.token,
-			baseURL: this.baseURL
+			baseURL: this.baseURL,
+			stream: this.stream
 		});
 	}
 };