agentpage 0.0.23 → 0.0.25

package/README.md

@@ -1,5 +1,9 @@
 # AutoPilot
 
+<p align="center">
+  <img src="./assets/logo/contours%20(2).svg" alt="AutoPilot Logo" width="180" />
+</p>
+
 > 浏览器内嵌 AI Agent SDK：让 AI 通过 tool-calling 操作网页。
 
 > 核心主张：通过 **Prompt + Tools + 路由**，快速为网站实现 AI 赋能，并构建**前端运行时 AI Skill**。AutoPilot 本质上是一个运行在前端浏览器中的 AI Agent。
@@ -145,8 +149,8 @@ import { WebAgent } from "agentpage";
 
 const agent = new WebAgent({
   token: "your-api-key",
-  provider: "deepseek", // openai | copilot | anthropic | deepseek
-  model: "deepseek-chat",
+  provider: "doubao", // openai | copilot | anthropic | deepseek | doubao | qwen
+  model: "doubao-1.5-pro-32k",
   // 用户可自定义 Prompt 规则（项目级/路由级）
   systemPrompt: "You are an assistant for this route. Follow route safety constraints.",
   memory: true,
@@ -227,9 +231,9 @@ applyRouteSkill(location.pathname);
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `client` | `AIClient` | - | 自定义 AI 客户端；传入后优先使用该实例，忽略 token/provider/model/baseURL |
-| `token` | `string` | `""` | API Token（GitHub PAT / OpenAI API Key / Anthropic Key / DeepSeek Key） |
-| `provider` | `string` | `"copilot"` | AI 服务商：`copilot` / `openai` / `anthropic` / `deepseek` |
-| `model` | `string` | `"gpt-4o"` | 模型名称（需与 provider 匹配，如 `deepseek-chat`、`claude-sonnet-4-20250514`） |
+| `token` | `string` | `""` | API Token（GitHub PAT / OpenAI API Key / Anthropic Key / DeepSeek Key / Doubao Ark Key / DashScope Key） |
+| `provider` | `string` | `"copilot"` | AI 服务商：`copilot` / `openai` / `anthropic` / `deepseek` / `doubao` / `qwen` |
+| `model` | `string` | `"gpt-4o"` | 模型名称（需与 provider 匹配，如 `doubao-1.5-pro-32k`、`qwen-plus`、`deepseek-chat`） |
 | `baseURL` | `string` | - | 自定义 API 基础地址（用于代理/私有部署，覆盖 provider 默认端点） |
 | `stream` | `boolean` | `true` | 是否启用流式返回（SSE）；关闭后使用 JSON 非流式响应 |
 | `dryRun` | `boolean` | `false` | 干运行模式：仅输出 AI 计划调用的工具列表，不执行真实操作 |
@@ -238,6 +242,7 @@ applyRouteSkill(location.pathname);
 | `memory` | `boolean` | `false` | 是否开启多轮对话记忆（跨 chat 调用保留历史消息） |
 | `autoSnapshot` | `boolean` | `true` | chat 前是否自动生成首轮页面快照并注入 system prompt |
 | `snapshotOptions` | `SnapshotOptions` | `{}` | 快照生成参数覆盖（深度、裁剪、剪枝、节点上限等） |
+| `roundStabilityWait` | `RoundStabilityWaitOptions` | `{ enabled: true }` | 轮次后稳定等待配置（loading hidden + DOM stable）；`loadingSelectors` 为“与默认值合并去重”，不会覆盖默认列表 |
 
 ### 参数详细说明
 
@@ -282,6 +287,8 @@ type AIClient = {
 | `openai` | `https://api.openai.com/v1` | `gpt-4o` / `gpt-4o-mini` | 标准 OpenAI 接口 |
 | `anthropic` | `https://api.anthropic.com` | `claude-sonnet-4-20250514` | Anthropic 原生接口 |
 | `deepseek` | `https://api.deepseek.com` | `deepseek-chat` | DeepSeek 接口 |
+| `doubao` | `https://ark.cn-beijing.volces.com/api/v3` | `doubao-1.5-pro-32k` | 火山引擎 Ark（OpenAI 兼容） |
+| `qwen` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` | 阿里云百炼兼容模式（OpenAI 兼容） |
 
 #### `systemPrompt`（Prompt 注册与维护）
 
@@ -702,7 +709,7 @@ AutoPilot 内置 5 个工具，覆盖浏览器交互的核心能力。所有工
 | `attribute` | `string` | get_attr/set_attr | 属性名称 |
 | `className` | `string` | add_class/remove_class | CSS 类名（旧参数名，已被 `value` 兼容） |
 | `clickCount` | `number` | click | 点击次数（默认 1，双击传 2，三击传 3） |
-| `waitMs` | `number` | 所有动作 | 等待元素出现的超时时间（毫秒，默认 2000） |
+| `waitMs` | `number` | 所有动作 | 等待元素出现的超时时间（毫秒，默认 1200） |
 | `waitSeconds` | `number` | 所有动作 | 等待超时（秒，`waitMs` 优先级更高） |
 | `force` | `boolean` | 所有动作 | 跳过 actionability 检查（默认 false） |
 
@@ -812,7 +819,7 @@ AutoPilot 内置 5 个工具，覆盖浏览器交互的核心能力。所有工
 | `selector` | `string` | wait_for_selector/hidden | 目标元素选择器 |
 | `state` | `string` | wait_for_selector | 目标状态：`attached`/`visible`/`hidden`/`detached` |
 | `text` | `string` | wait_for_text | 要等待出现的文本内容 |
-| `timeout` | `number` | 所有动作 | 超时时间（毫秒，默认 10000） |
+| `timeout` | `number` | 所有动作 | 超时时间（毫秒，默认 6000） |
 | `quietMs` | `number` | wait_for_stable | DOM 静默窗口时长（毫秒，默认 300） |
 
 **动作详解：**
@@ -1034,6 +1041,8 @@ AI 每一轮不是“凭记忆猜页面”，而是基于最新快照选择可
 例子：
 - 可同轮：同时填写两个已可见输入框
 - 不可同轮：点击“打开弹窗”后立即填写弹窗字段（应等下一轮新快照）
+- 当前实现：若本轮出现潜在 DOM 变化动作，轮次结束会自动执行双重等待（先 loading hidden，再 DOM quiet window），默认 `quietMs=200`、`timeoutMs=4000`。
+- `loadingSelectors` 默认内置 AntD / Element Plus / BK / TDesign（TD）及通用加载态选择器；用户自定义会在默认列表基础上追加并去重，不会覆盖默认值。
 
 ---
 
@@ -1083,12 +1092,13 @@ loop 对本轮返回做以下处理：
 1. 执行工具调用批次
 2. 拦截 `page_info.*`（在 loop 内视为冗余，不让其成为主流程）
 3. 处理恢复（元素找不到时自动刷新快照）
-4. 刷新快照进入下一轮
-5. 更新下一轮任务文本：
+4. 若本轮存在潜在 DOM 变化动作：执行轮次后稳定等待（loading hidden + DOM stable）
+5. 刷新快照进入下一轮
+6. 更新下一轮任务文本：
   - 优先使用 `REMAINING`
   - 若缺失 `REMAINING` 且本轮有执行动作：按线性任务剔除做启发式推进（避免整段原任务重复）
   - 若缺失 `REMAINING` 且本轮无执行进展：保持当前任务不推进（按协议回退）
-6. 若“remaining 未完成 + 无工具调用”：
+7. 若“remaining 未完成 + 无工具调用”：
   - 不直接结束
   - 下一轮注入 `Protocol violation` 强约束提示，要求“要么给可执行工具调用，要么严格 `REMAINING: DONE`”
 
@@ -1099,12 +1109,12 @@ loop 对本轮返回做以下处理：
 1. 收集失败工具调用（name/input）及失败原因
 2. 将“失败工具集合 + 最新快照 + 当前任务”一起发给模型重试
 3. 在消息中标注重试次数：`attempt x/y`
-4. 若仍未命中，默认 `await 2000ms` 后刷新快照再重试
+4. 若仍未命中，默认 `await 1000ms` 后刷新快照再重试
 5. 超过最大尝试次数后退出重试流，交由模型给出剩余任务或结束
 
 默认参数：
 - `DEFAULT_NOT_FOUND_RETRY_ROUNDS = 2`
-- `DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 2000`
+- `DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 1000`
 
 ### 4) 停机条件
 
@@ -1429,7 +1439,7 @@ agent.registerTool({
   - `agent-loop`：轮次编排、停机判定、恢复/重试、指标汇总
   - `system-prompt`：系统规则模板
   - `tool-registry`：工具注册/分发/错误兜底
-  - `ai-client`：多 provider 协议适配（OpenAI/Copilot/Anthropic/DeepSeek）
+  - `ai-client`：多 provider 协议适配（OpenAI/Copilot/Anthropic/DeepSeek/Doubao/Qwen）
 - `web`（浏览器实现）：
   - `WebAgent`：入口编排、记忆、autoSnapshot、callbacks
   - `tools`：DOM/导航/页面信息/等待/evaluate
@@ -1523,7 +1533,7 @@ agent.registerTool({
 | 冗余 page_info 拦截 | `page_info.snapshot/query_all/get_url/get_title/get_viewport` | - | 直接返回拦截结果，不执行真实调用 | `recovery.ts#checkRedundantSnapshot` |
 | 连续 snapshot 防抖 | 连续 page_info.snapshot | 阈值=2 | 标记 `REDUNDANT_SNAPSHOT` | `recovery.ts#applySnapshotDebounce` |
 | 元素未找到自动恢复 | `dom` 且结果为 element not found | `DEFAULT_ACTION_RECOVERY_ROUNDS=2`，`DEFAULT_RECOVERY_WAIT_MS=100` | 等待 -> 刷新快照 -> 返回 recovery 结果 | `recovery.ts#handleElementRecovery` |
-| Not-found 重试对话流 | 本轮有 not-found 失败任务 | `DEFAULT_NOT_FOUND_RETRY_ROUNDS=2`，`DEFAULT_NOT_FOUND_RETRY_WAIT_MS=2000` | 注入失败任务上下文 + attempt x/y，必要时等待后重试 | `index.ts` 主循环 |
+| Not-found 重试对话流 | 本轮有 not-found 失败任务 | `DEFAULT_NOT_FOUND_RETRY_ROUNDS=2`，`DEFAULT_NOT_FOUND_RETRY_WAIT_MS=1000` | 注入失败任务上下文 + attempt x/y，必要时等待后重试 | `index.ts` 主循环 |
 | 导航后上下文刷新 | `navigate` 成功且动作为 goto/back/forward/reload | - | 立即刷新快照 | `recovery.ts#handleNavigationUrlChange` |
 | 空转检测 | 连续只读轮次 | 连续 2 轮 | 返回 -1 终止 | `recovery.ts#detectIdleLoop` |
 
@@ -1776,27 +1786,38 @@ agent.registerTool({
 - `DEFAULT_RECOVERY_WAIT_MS = 100`
 - `DEFAULT_ACTION_RECOVERY_ROUNDS = 2`
 - `DEFAULT_NOT_FOUND_RETRY_ROUNDS = 2`
-- `DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 2000`
+- `DEFAULT_NOT_FOUND_RETRY_WAIT_MS = 1000`
 
 `src/web/tools/wait-tool.ts`：
 
-- `DEFAULT_TIMEOUT = 10000`
+- `DEFAULT_TIMEOUT = 6000`
 
 ---
 
 ### 10. 文档与实现一致性清单（维护者必看）
 
+Agent Loop 机制权威文档：`src/core/agent-loop/LOOP_MECHANISM.md`。
+
 任何涉及“渐进式任务消费”的改动，至少同步以下文件：
 
 1. `src/core/agent-loop/messages.ts`（输入语义）
 2. `src/core/agent-loop/index.ts`（停机判定与推进逻辑）
-3. `README.md`（机制说明）
+3. `src/core/agent-loop/LOOP_MECHANISM.md`（机制权威说明）
+4. `README.md`（机制说明）
 
 任何涉及“找不到元素重试流”的改动，至少同步：
 
 1. `src/core/agent-loop/index.ts`
 2. `src/core/agent-loop/recovery.ts`
-3. `README.md`
+3. `src/core/agent-loop/LOOP_MECHANISM.md`
+4. `README.md`
+
+任何涉及 provider 新增/调整的改动，至少同步：
+
+1. `src/core/ai-client/index.ts`（provider 路由）
+2. `src/core/ai-client/constants.ts`（默认端点）
+3. `src/web/index.ts`（WebAgentOptions 注释/提示）
+4. `README.md`（配置示例与支持矩阵）
 
 这样才能保证“实现、提示词、文档”三者一致，不出现行为漂移。
 
@@ -1848,4 +1869,4 @@ MIT
 4. **RefStore - 生命周期图**：从 `chat()` 创建到 `clear()` 释放的完整流程
 5. **AI Client - 自定义接入**：`BaseAIClient` 和纯对象两种方式的代码示例
 6. **快照格式 - 生成管线**：从 `document.body` 到最终文本的 10 步管线流程
-7. **错误处理 - 恢复常量**：`DEFAULT_ACTION_RECOVERY_ROUNDS=2` / `DEFAULT_NOT_FOUND_RETRY_ROUNDS=2` / `DEFAULT_NOT_FOUND_RETRY_WAIT_MS=2000` 等关键参数说明
+7. **错误处理 - 恢复常量**：`DEFAULT_ACTION_RECOVERY_ROUNDS=2` / `DEFAULT_NOT_FOUND_RETRY_ROUNDS=2` / `DEFAULT_NOT_FOUND_RETRY_WAIT_MS=1000` 等关键参数说明

package/dist/index.d.mts

@@ -197,6 +197,17 @@ type SnapshotOptions = {
   maxNodes?: number; /** 每个父节点最多输出的子元素数（默认 25），超出部分会折叠。 */
   maxChildren?: number; /** 文本截断长度（默认 40）。 */
   maxTextLength?: number;
+  /**
+   * 是否对“选项列表”容器放宽子节点截断（默认 false）。
+   * 典型场景：时间选择器/下拉选项列表，避免关键选项被 `...children omitted` 折叠。
+   */
+  expandOptionLists?: boolean;
+  /**
+   * 仅对指定 hash ref 节点放宽子节点截断（优先级高于默认 maxChildren）。
+   * 例如：[#abc123, #def456]，用于 AI 在看到 children omitted 后定向请求放宽。
+   */
+  expandChildrenRefs?: string[]; /** 对 expandChildrenRefs 节点生效的子节点上限（默认 120）。 */
+  expandedChildrenLimit?: number;
 };
 /**
  * 生成页面 DOM 快照 — 将 DOM 树转为 AI 可理解的文本描述。

package/dist/index.d.mts.map

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

package/dist/index.mjs

@@ -111,7 +111,10 @@ async function readPageSnapshot(registry, options) {
 		pruneLayout: options?.pruneLayout ?? true,
 		maxNodes: options?.maxNodes ?? 500,
 		maxChildren: options?.maxChildren ?? 30,
-		maxTextLength: options?.maxTextLength ?? 40
+		maxTextLength: options?.maxTextLength ?? 40,
+		expandOptionLists: options?.expandOptionLists,
+		expandChildrenRefs: options?.expandChildrenRefs,
+		expandedChildrenLimit: options?.expandedChildrenLimit
 	})).content);
 }
 /**
@@ -216,7 +219,7 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 			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.", "Build the minimal action array from current snapshot to finish this remaining instruction in one round whenever possible.", "For deterministic increase/decrease controls, compute delta from current visible value and issue exactly that many clicks in one round (e.g., +2 => two increase clicks). Do not overshoot then undo.", "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).", "Stop rule: once requested state is reached, stop tool calls. If verification is needed, verify once and then output REMAINING: DONE.", 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 (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.", "Build the minimal action array from current snapshot to finish this remaining instruction in one round whenever possible.", "For deterministic increase/decrease controls, compute delta from current visible value and issue exactly that many clicks in one round (e.g., +2 => two increase clicks). Do not overshoot then undo.", "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).", "If a needed list shows `... (N children omitted)` under a specific container, output `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>` and wait for next round snapshot.", "Stop rule: once requested state is reached, stop tool calls. If verification is needed, verify once and then output REMAINING: DONE.", 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",
@@ -252,6 +255,7 @@ function buildCompactMessages(userMessage, trace, latestSnapshot, currentUrl, hi
 		"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).",
+		"If a needed list shows `... (N children omitted)` under a specific container, output `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>` and wait for next round snapshot.",
 		"Build the minimal action array from current snapshot to finish this remaining instruction in one round whenever possible.",
 		"For deterministic increase/decrease controls, compute delta from current visible value and issue exactly that many clicks in one round (e.g., +2 => two increase clicks). Do not overshoot then undo.",
 		"Stop rule: once requested state is reached, stop tool calls. If verification is needed, verify once and then output REMAINING: DONE.",
@@ -445,6 +449,7 @@ async function executeAgentLoop(params) {
 	let consecutiveSamePlannedBatch = 0;
 	let lastRoundHadError = false;
 	let protocolViolationHint;
+	const snapshotExpandRefIds = /* @__PURE__ */ new Set();
 	let recoveryCount = 0;
 	let redundantInterceptCount = 0;
 	let pendingNotFoundRetry;
@@ -470,9 +475,37 @@ async function executeAgentLoop(params) {
 	* Does exactly two things: read latest snapshot + update metrics.
 	*/
 	const refreshSnapshot = async () => {
-		pageContext.latestSnapshot = await readPageSnapshot(registry);
+		pageContext.latestSnapshot = await readPageSnapshot(registry, snapshotExpandRefIds.size > 0 ? {
+			expandChildrenRefs: Array.from(snapshotExpandRefIds),
+			expandedChildrenLimit: 120
+		} : void 0);
 		recordSnapshotStats(pageContext.latestSnapshot);
 	};
+	/**
+	* 解析模型文本中的快照放宽指令（中）/ Parse snapshot expansion hint from model text (EN).
+	*
+	* 约定：
+	* SNAPSHOT_HINT: EXPAND_CHILDREN #ref1 #ref2
+	*/
+	const parseSnapshotExpandHints = (text) => {
+		if (!text) return [];
+		const refs = [];
+		const regex = /^\s*SNAPSHOT_HINT\s*:\s*EXPAND_CHILDREN\s+(.+)$/gim;
+		let match;
+		while ((match = regex.exec(text)) !== null) {
+			const tokens = (match[1] ?? "").match(/#[A-Za-z0-9_-]+/g) ?? [];
+			for (const token of tokens) refs.push(token.replace(/^#/, ""));
+		}
+		return refs;
+	};
+	/** 从工具输入提取 hash selector（如 #1rv01x），用于定向快照放宽。 */
+	const extractHashSelectorRef = (toolInput) => {
+		if (!toolInput || typeof toolInput !== "object") return null;
+		const selector = toolInput.selector;
+		if (typeof selector !== "string") return null;
+		const m = selector.trim().match(/^#([A-Za-z0-9_-]+)$/);
+		return m ? m[1] : null;
+	};
 	if (pageContext.latestSnapshot) recordSnapshotStats(pageContext.latestSnapshot);
 	/**
 	* 追加工具轨迹（中）/ Append tool trace entry (EN).
@@ -617,6 +650,8 @@ async function executeAgentLoop(params) {
 		inputTokens += response.usage?.inputTokens ?? 0;
 		outputTokens += response.usage?.outputTokens ?? 0;
 		const parsedInstructionState = deriveNextInstruction(response.text, remainingInstruction);
+		const snapshotHintRefs = parseSnapshotExpandHints(response.text);
+		for (const ref of snapshotHintRefs.slice(0, 8)) snapshotExpandRefIds.add(ref);
 		if (!response.toolCalls || response.toolCalls.length === 0) {
 			if (pendingNotFoundRetry) {
 				const unresolvedHint = response.text?.toLowerCase() ?? "";
@@ -687,6 +722,10 @@ async function executeAgentLoop(params) {
 		const executedTaskCalls = [];
 		const roundMissingTasks = [];
 		for (const tc of response.toolCalls) {
+			if (tc.name === "dom" && getToolAction(tc.input) === "scroll") {
+				const ref = extractHashSelectorRef(tc.input);
+				if (ref) snapshotExpandRefIds.add(ref);
+			}
 			const redundant = checkRedundantSnapshot(tc.name, tc.input, pageContext.latestSnapshot, round);
 			if (redundant) {
 				appendToolTrace(round, tc.name, tc.input, redundant);
@@ -1397,6 +1436,8 @@ function buildSystemPrompt(params = {}) {
 		"- 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).",
+		"- If a required list shows `... (N children omitted)` under a specific container, request focused expansion by outputting `SNAPSHOT_HINT: EXPAND_CHILDREN #<containerRef>`.",
+		"- After outputting snapshot expansion hint, wait for the next refreshed snapshot before further scrolling/clicking on that list.",
 		"- Verification whitelist: do NOT use get_text/get_attr to verify input/select values unless the user explicitly asks for verification.",
 		"- Stop rule: when the requested state is achieved, stop calling tools. If verification is requested, verify once and then return REMAINING: DONE (no repeated get_text/get_attr on the same target).",
 		"- Do NOT interact with AutoPilot UI unless user explicitly asks.",
@@ -2013,7 +2054,7 @@ function createDomTool() {
 		name: "dom",
 		description: [
 			"Perform DOM operations on the current page.",
-			"Actions: click, fill, select_option, clear, check, uncheck, type, focus, hover, press, get_text, get_attr, set_attr, add_class, remove_class.",
+			"Actions: click, fill, select_option, clear, check, uncheck, type, focus, hover, scroll, press, get_text, get_attr, set_attr, add_class, remove_class.",
 			"Input/Select rule: before each fill/type/select_option, click or focus the same target immediately in the same round.",
 			"For multiple fields, use alternating pairs in one batch: focus/click A -> fill/type A -> focus/click B -> fill/type B.",
 			"Use the hash ID from DOM snapshot (e.g. #a1b2c) as selector.",
@@ -2022,10 +2063,11 @@ function createDomTool() {
 			"Ordinal/index rule: treat visual order as 1-based when the instruction says 'the Nth item' (e.g. 4th star = 4th visible icon from left to right), and avoid off-by-one mistakes.",
 			"Disambiguation rule: distinguish descriptive text/labels from actionable options. Do not click nearby label/help text; click the actual interactive option/control item (icon/button/option) that changes state.",
 			"Unknown/complex components: if a container element (e.g. role=slider, rating, custom widget) has multiple child icons/items in the snapshot but you don't know how to operate it directly, try clicking the appropriate child element instead. For example, a rating component with 5 star icon children — click the 4th icon child to set 4 stars. A slider with a runway — clicking the runway at the right position may work. Always prefer interacting with visible children when the parent container doesn't respond to fill/click as expected.",
-			"fill supports role=slider elements: use fill with a numeric value on a role=slider container (rating/slider) to set its value programmatically."
+			"fill supports role=slider elements: use fill with a numeric value on a role=slider container (rating/slider) to set its value programmatically.",
+			"For wheel/virtualized pickers where target option is not visible yet, use scroll on the picker column first, then click/select the newly visible option. scroll supports steps for repeated scrolling in one call."
 		].join(" "),
 		schema: Type.Object({
-			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | press | get_text | get_attr | set_attr | add_class | remove_class." }),
+			action: Type.String({ description: "DOM action: click | fill | select_option | clear | check | uncheck | type | focus | hover | scroll | 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 for press action. Supports combo: 'Enter', 'Control+a', 'Shift+Enter', 'Meta+c'" })),
@@ -2034,6 +2076,9 @@ function createDomTool() {
 			attribute: Type.Optional(Type.String({ description: "Attribute name for get_attr/set_attr" })),
 			className: Type.Optional(Type.String({ description: "CSS class name for add_class/remove_class" })),
 			clickCount: Type.Optional(Type.Number({ description: "Click count (default 1). 2 = double-click, 3 = triple-click." })),
+			deltaY: Type.Optional(Type.Number({ description: "Vertical scroll delta for scroll action. Positive = down, negative = up." })),
+			deltaX: Type.Optional(Type.Number({ description: "Horizontal scroll delta for scroll action." })),
+			steps: Type.Optional(Type.Number({ description: "Repeat count for scroll action (default 1, max 20)." })),
 			waitMs: Type.Optional(Type.Number({ description: "Wait timeout in ms before action (default: 2000)." })),
 			waitSeconds: Type.Optional(Type.Number({ description: "Wait timeout in seconds (fallback for waitMs)." })),
 			force: Type.Optional(Type.Boolean({ description: "Skip actionability checks (default false)." }))
@@ -2360,6 +2405,37 @@ function createDomTool() {
 						if (target instanceof HTMLElement) dispatchHoverEvents(target);
 						return { content: `已悬停 ${describeElement(target)}` };
 					}
+					case "scroll": {
+						const target = retarget(el, "none");
+						const deltaY = typeof params.deltaY === "number" ? params.deltaY : typeof params.value === "string" && !Number.isNaN(Number(params.value)) ? Number(params.value) : 180;
+						const deltaX = typeof params.deltaX === "number" ? params.deltaX : 0;
+						const rawSteps = typeof params.steps === "number" ? Math.floor(params.steps) : 1;
+						const steps = Math.min(20, Math.max(1, rawSteps));
+						if (target instanceof HTMLElement) {
+							scrollIntoViewIfNeeded(target);
+							for (let i = 0; i < steps; i++) {
+								target.scrollBy({
+									top: deltaY,
+									left: deltaX,
+									behavior: "auto"
+								});
+								target.dispatchEvent(new WheelEvent("wheel", {
+									bubbles: true,
+									cancelable: true,
+									deltaY,
+									deltaX
+								}));
+							}
+							return { content: `已滚动 ${describeElement(target)}: deltaY=${deltaY}, deltaX=${deltaX}, steps=${steps}` };
+						}
+						for (let i = 0; i < steps; i++) target.dispatchEvent(new WheelEvent("wheel", {
+							bubbles: true,
+							cancelable: true,
+							deltaY,
+							deltaX
+						}));
+						return { content: `已滚动 ${describeElement(target)}: deltaY=${deltaY}, deltaX=${deltaX}, steps=${steps}` };
+					}
 					case "press": {
 						const key = params.key || params.value;
 						if (!key) return { content: "缺少 key 参数（如 Enter, Escape, Tab, Control+a）" };
@@ -2447,6 +2523,31 @@ function createDomTool() {
 *   snapshot      — 获取页面 DOM 结构快照（AI 可读的文本描述）
 *   query_all     — 查询所有匹配选择器的元素，返回摘要信息
 */
+/** 快照属性值最大保留长度（超出截断）。 */
+const MAX_SNAPSHOT_ATTR_VALUE_LENGTH = 120;
+/** 选项列表放宽时的子节点上限（仍保留硬上限，避免快照无限膨胀）。 */
+const MAX_EXPANDED_LIST_CHILDREN = 120;
+/** 定向放宽 children 的硬上限。 */
+const MAX_EXPANDED_CHILDREN_LIMIT = 300;
+/**
+* 规整快照属性值，避免把长 base64/data URL 原样注入快照。
+*/
+function sanitizeSnapshotAttrValue(value) {
+	const trimmed = value.trim();
+	if (!trimmed) return "";
+	const dataUrlMatch = trimmed.match(/^data:([^,]*?),(.*)$/i);
+	if (dataUrlMatch) {
+		const meta = dataUrlMatch[1] || "";
+		const payload = dataUrlMatch[2] || "";
+		const isBase64 = /;base64/i.test(meta);
+		const payloadLength = payload.length;
+		const previewMeta = meta.slice(0, 48);
+		if (isBase64 || payloadLength > 64) return `data:${previewMeta},<omitted:${payloadLength}>`;
+	}
+	if (trimmed.match(/^[A-Za-z0-9+/]{80,}={0,2}$/)) return `<base64:${trimmed.length}>`;
+	if (trimmed.length > MAX_SNAPSHOT_ATTR_VALUE_LENGTH) return `${trimmed.slice(0, MAX_SNAPSHOT_ATTR_VALUE_LENGTH)}...`;
+	return trimmed;
+}
 /**
 * 生成页面 DOM 快照 — 将 DOM 树转为 AI 可理解的文本描述。
 *
@@ -2475,6 +2576,9 @@ function generateSnapshot(root = document.body, options = {}) {
 	const maxNodes = opts.maxNodes ?? 220;
 	const maxChildren = opts.maxChildren ?? 25;
 	const maxTextLength = opts.maxTextLength ?? 40;
+	const expandOptionLists = opts.expandOptionLists ?? false;
+	const expandedChildrenLimit = Math.min(MAX_EXPANDED_CHILDREN_LIMIT, Math.max(1, opts.expandedChildrenLimit ?? MAX_EXPANDED_LIST_CHILDREN));
+	const expandChildrenRefSet = new Set((opts.expandChildrenRefs ?? []).map((ref) => ref.trim().replace(/^#/, "")).filter(Boolean));
 	let emittedNodes = 0;
 	let truncatedByNodeBudget = false;
 	const refStore = opts.refStore;
@@ -2589,6 +2693,26 @@ function generateSnapshot(root = document.body, options = {}) {
 		if (el.hasAttribute("aria-label")) return true;
 		return false;
 	}
+	/** 判断是否为“选项列表”容器（时间/下拉/listbox 等）。 */
+	function isOptionListContainer(el) {
+		if (el.getAttribute("role") === "listbox") return true;
+		const cls = (el.getAttribute("class") || "").toLowerCase();
+		if (cls.includes("time-spinner__list") || cls.includes("select-dropdown") || cls.includes("virtual-list") || cls.includes("option")) return true;
+		if (el.tagName === "UL") {
+			const children = Array.from(el.children);
+			if (children.length >= 20) {
+				if (children.filter((child) => child.tagName === "LI").length / children.length >= .8) return true;
+			}
+		}
+		return false;
+	}
+	/** 针对子节点截断计算动态上限。 */
+	function resolveChildLimit(el, defaultLimit, hashId) {
+		let nextLimit = defaultLimit;
+		if (expandOptionLists && isOptionListContainer(el)) nextLimit = Math.max(nextLimit, MAX_EXPANDED_LIST_CHILDREN);
+		if (hashId && expandChildrenRefSet.has(hashId)) nextLimit = Math.max(nextLimit, expandedChildrenLimit);
+		return nextLimit;
+	}
 	function walk(el, depth, parentPath) {
 		if (emittedNodes >= maxNodes) {
 			truncatedByNodeBudget = true;
@@ -2603,6 +2727,7 @@ function generateSnapshot(root = document.body, options = {}) {
 		const indent = "  ".repeat(depth);
 		const tag = el.tagName.toLowerCase();
 		const currentPath = `${parentPath}/${tag}${getSiblingIndex(el)}`;
+		const hashId = refStore ? refStore.set(el, currentPath) : void 0;
 		const attrs = [];
 		const elId = el.getAttribute("id");
 		if (elId) attrs.push(`id="${elId}"`);
@@ -2613,7 +2738,10 @@ function generateSnapshot(root = document.body, options = {}) {
 		}
 		for (const attr of INTERACTIVE_ATTRS) {
 			const val = el.getAttribute(attr);
-			if (val) attrs.push(`${attr}="${val}"`);
+			if (val) {
+				const safeVal = sanitizeSnapshotAttrValue(val);
+				if (safeVal) attrs.push(`${attr}="${safeVal}"`);
+			}
 		}
 		for (const attr of BOOLEAN_ATTRS) if (el.hasAttribute(attr)) attrs.push(attr);
 		if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement || el instanceof HTMLButtonElement) {
@@ -2624,15 +2752,18 @@ function generateSnapshot(root = document.body, options = {}) {
 		}
 		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 (testId) {
+			const safeTestId = sanitizeSnapshotAttrValue(testId).slice(0, 25);
+			if (safeTestId) attrs.push(`data-testid="${safeTestId}"`);
+		}
 		if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.value) {
-			const currentVal = el.value.slice(0, 40);
+			const currentVal = sanitizeSnapshotAttrValue(el.value).slice(0, 40);
 			if (el.getAttribute("value") !== currentVal) attrs.push(`val="${currentVal}"`);
 		}
 		if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio") && el.checked) {
 			if (!attrs.includes("checked")) attrs.push("checked");
 		}
-		if (el instanceof HTMLSelectElement && el.value) attrs.push(`val="${el.value.slice(0, 40)}"`);
+		if (el instanceof HTMLSelectElement && el.value) attrs.push(`val="${sanitizeSnapshotAttrValue(el.value).slice(0, 40)}"`);
 		if (el instanceof HTMLOptionElement && el.selected) {
 			if (!attrs.includes("selected")) attrs.push("selected");
 		}
@@ -2650,7 +2781,8 @@ function generateSnapshot(root = document.body, options = {}) {
 			const interactiveChildren = allChildren.filter(isInteractiveElement);
 			const nonInteractiveChildren = allChildren.filter((child) => !isInteractiveElement(child));
 			const orderedChildren = [...interactiveChildren, ...nonInteractiveChildren];
-			const selectedChildren = orderedChildren.slice(0, maxChildren);
+			const childLimit = resolveChildLimit(el, maxChildren, hashId);
+			const selectedChildren = orderedChildren.slice(0, childLimit);
 			const omittedChildren = orderedChildren.length - selectedChildren.length;
 			const childBlocks = [];
 			for (let i = 0; i < selectedChildren.length; i++) {
@@ -2668,17 +2800,16 @@ function generateSnapshot(root = document.body, options = {}) {
 		let line = `${indent}[${tag}]`;
 		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}"`;
+		if (hashId) line += ` #${hashId}`;
+		else line += ` ref="${currentPath}"`;
 		const lines = [line];
 		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 childLimit = resolveChildLimit(el, maxChildren, hashId);
+		const selectedChildren = orderedChildren.slice(0, childLimit);
 		const omittedChildren = orderedChildren.length - selectedChildren.length;
 		for (let i = 0; i < selectedChildren.length; i++) {
 			const childResult = walk(selectedChildren[i], depth + 1, currentPath);
@@ -2737,7 +2868,10 @@ function createPageInfoTool() {
 			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)" }))
+			maxTextLength: Type.Optional(Type.Number({ description: "Maximum text length per node (default: 40)" })),
+			expandOptionLists: Type.Optional(Type.Boolean({ description: "Expand option-list containers to avoid child truncation (default: false)" })),
+			expandChildrenRefs: Type.Optional(Type.Array(Type.String({ description: "Hash refs to expand child truncation for (e.g. #abc123)" }))),
+			expandedChildrenLimit: Type.Optional(Type.Number({ description: "Child limit for expandChildrenRefs nodes (default: 120, max: 300)" }))
 		}),
 		execute: async (params) => {
 			const action = params.action;
@@ -2764,6 +2898,9 @@ function createPageInfoTool() {
 						const maxNodes = params.maxNodes ?? 220;
 						const maxChildren = params.maxChildren ?? 25;
 						const maxTextLength = params.maxTextLength ?? 40;
+						const expandOptionLists = params.expandOptionLists ?? false;
+						const expandChildrenRefs = Array.isArray(params.expandChildrenRefs) ? params.expandChildrenRefs.filter((ref) => typeof ref === "string") : void 0;
+						const expandedChildrenLimit = typeof params.expandedChildrenLimit === "number" ? params.expandedChildrenLimit : void 0;
 						return { content: generateSnapshot(document.body, {
 							maxDepth,
 							viewportOnly,
@@ -2771,6 +2908,9 @@ function createPageInfoTool() {
 							maxNodes,
 							maxChildren,
 							maxTextLength,
+							expandOptionLists,
+							expandChildrenRefs,
+							expandedChildrenLimit,
 							refStore: getActiveRefStore()
 						}) };
 					}