agentpage 0.0.24 → 0.0.26

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,
@@ -173,6 +177,23 @@ console.log(result.reply);
 pnpm demo
 ```
 
+### Demo Prompt 建议（Element Plus）
+
+在 `demo/App.vue` 中，推荐为 Demo 场景单独注册一条 prompt（key: `demo`），以减少无效调用和重复验证：
+
+```ts
+agent.setSystemPrompt("demo", [
+  "You are operating the Element Plus demo page.",
+  "Prefer minimal action arrays and complete independent visible actions in one round.",
+  "Do not repeat verification calls unless the user explicitly asks for verification.",
+].join(" "));
+```
+
+这三条规则分别约束：
+- 最小化动作数组，减少冗余工具调用。
+- 同一轮优先完成当前可见且彼此独立的动作，提升收敛速度。
+- 非用户明确要求时，不重复做验证型调用，避免空转。
+
 ### 按路由构建 AI Skill（推荐范式）
 
 ```ts
@@ -227,9 +248,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 +259,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 +304,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 注册与维护）
 
@@ -364,6 +388,25 @@ agent.clearHistory();                       // 手动清空历史
 | `maxTextLength` | `number` | `40` | 单节点文本截断长度（字符数） |
 | `refStore` | `RefStore` | 自动创建 | hash ID 映射表（一般无需手动传入，WebAgent 自动管理） |
 
+### 全局事件监听追踪（默认开启）
+
+从 `0.0.26` 开始，`web` 入口会在模块加载时默认安装全局监听追踪补丁：
+
+- 劫持 `EventTarget.prototype.addEventListener/removeEventListener`
+- 先执行原生调用，再记录事件（不阻断业务逻辑）
+- 仅记录 `Element` 目标，使用 `WeakMap<Element, Set<string>>`
+
+快照侧联动：
+
+- `page_info.snapshot` 会为命中事件追踪的元素输出 `listeners="click,input,..."`
+- 交互优先级识别会把运行时监听事件纳入判断（不仅依赖 `onclick/role` 等静态属性）
+- 智能剪枝会保留带事件绑定的容器，避免把委托交互入口错误折叠
+
+边界说明：
+
+- 事件委托场景只能记录到父容器（这是浏览器事件机制本身决定的）
+- 补丁安装前已绑定的历史监听不会被回溯记录；建议尽早初始化 `WebAgent`
+
 ### 快照参数详细说明
 
 #### `maxDepth`（遍历深度）
@@ -702,7 +745,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 +855,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） |
 
 **动作详解：**
@@ -964,6 +1007,7 @@ src/
 │       └── sse.ts
 └── web/
   ├── index.ts
+  ├── event-listener-tracker.ts  # 全局事件监听追踪（WeakMap<Element, Set<string>>）
   ├── dom-tool.ts          # 兼容转发层（re-export）
   ├── navigate-tool.ts     # 兼容转发层（re-export）
   ├── page-info-tool.ts    # 兼容转发层（re-export）
@@ -972,7 +1016,14 @@ src/
   ├── ref-store.ts
   ├── messaging.ts
   └── tools/
-    ├── dom-tool.ts
+    ├── dom-tool/
+    │   ├── index.ts          # createDomTool 入口 + schema + execute 路由
+    │   ├── constants.ts       # 常量（DEFAULT_WAIT_MS, KEY_CODE_MAP 等）
+    │   ├── query.ts           # 元素查找、RefStore 管理、describeElement
+    │   ├── actionability.ts   # 可操作性检查（可见/禁用/可编辑/稳定/命中）
+    │   ├── events.ts          # 事件派发（click/hover/input 链、键盘 press）
+    │   ├── resolve.ts         # 目标解析（retarget、checkable/editable 穿透、ARIA widget→input 穿透）
+    │   └── dropdown.ts        # 自定义下拉增强（findVisibleOptionByText）
     ├── navigate-tool.ts
     ├── page-info-tool.ts
     ├── wait-tool.ts
@@ -1034,6 +1085,8 @@ AI 每一轮不是“凭记忆猜页面”，而是基于最新快照选择可
 例子：
 - 可同轮：同时填写两个已可见输入框
 - 不可同轮：点击“打开弹窗”后立即填写弹窗字段（应等下一轮新快照）
+- 当前实现：若本轮出现潜在 DOM 变化动作，轮次结束会自动执行双重等待（先 loading hidden，再 DOM quiet window），默认 `quietMs=200`、`timeoutMs=4000`。
+- `loadingSelectors` 默认内置 AntD / Element Plus / BK / TDesign（TD）及通用加载态选择器；用户自定义会在默认列表基础上追加并去重，不会覆盖默认值。
 
 ---
 
@@ -1083,12 +1136,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 +1153,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) 停机条件
 
@@ -1143,13 +1197,13 @@ loop 对本轮返回做以下处理：
 
 ### A. System Prompt（全局规则层）
 
-由 `src/core/system-prompt.ts` 生成，职责是定义不可变执行约束：
+由 `src/core/system-prompt.ts` 生成，采用 Decision Framework 架构：
 
-- 从当前快照直接执行，不复述任务
-- 任务按“剔除模型”推进（current + previous + this-round -> new remaining）
-- 禁止 `page_info` 作为规划手段
-- 可见目标尽量同轮批量执行
-- DOM 会变化的动作执行后在下一轮继续
+- 五阶段决策流：ANALYZE → ASSESS → CHOOSE → EXECUTE → OUTPUT
+- Targeting Rules：hash selector 优先、ordinal 1-based 视觉序
+- Constraints：form-input 顺序、DOM 变化断轮、禁止冗余 page_info
+- Listener Abbreviations：快照中缩写到原始事件的映射
+- 工具部分由各工具 `t.description` 动态注入，不在 prompt 正文重复
 - 统一输出 `REMAINING` 协议
 
 ### B. Round Messages（轮次状态层）
@@ -1429,7 +1483,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 +1577,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` |
 
@@ -1594,7 +1648,7 @@ agent.registerTool({
 
 ### 6. Tools 能力总表（详细）
 
-#### 6.1 `dom` 工具（`src/web/tools/dom-tool.ts`）
+#### 6.1 `dom` 工具（`src/web/tools/dom-tool/`）
 
 支持动作：
 
@@ -1703,7 +1757,9 @@ agent.registerTool({
 
 1. **System Prompt（稳定规则层）**
   - 由 `buildSystemPrompt()` 生成
-  - 永久规则：快照优先、批处理、输入顺序、禁止 page_info、REMAINING 协议
+  - 采用 Decision Framework 架构：ANALYZE → ASSESS → CHOOSE → EXECUTE → OUTPUT
+  - 包含 Targeting Rules、Constraints、Listener Abbreviations
+  - 工具部分由各工具 `t.description` 动态注入，prompt 不重复工具能力描述
 2. **Round Message（动态状态层）**
   - 由 `buildCompactMessages()` 生成
   - 包含当前 remaining、done steps、上轮计划、上轮输出归一化、最新快照
@@ -1713,17 +1769,14 @@ agent.registerTool({
 
 #### 7.2 System Prompt 的关键规则（当前实现）
 
-`buildSystemPrompt()` 中的核心约束（英文原文语义）：
+`buildSystemPrompt()` 采用 Decision Framework 架构，不再逐条罗列规则：
 
-- 从“当前快照 + 当前 remaining”直接执行，不复述任务
-- 每轮按 task reduction 推进
-- 使用 hash selector，不猜 CSS
-- 可见且互不依赖的动作同轮批量执行
-- 输入顺序强约束：`focus/click -> fill/type/select_option`
-- 多字段交替对执行（防止 focus-only 空轮）
-- DOM 结构变化动作后断轮
-- 禁用 `page_info` 作为规划手段
-- 输出 `REMAINING: ...` 或 `REMAINING: DONE`
+- 五阶段决策流：ANALYZE snapshot → ASSESS targets → CHOOSE action → EXECUTE → OUTPUT
+- Targeting Rules：hash selector 优先、ordinal 为 1-based 视觉序
+- Constraints：form-input 顺序约束（focus/click → fill/type/select_option）、DOM 结构变化后断轮
+- Listener Abbreviations：`clk`/`inp`/`chg`/`kdn`/`kup` 等缩写映射
+- 工具描述去重：工具部分完全由各工具 `t.description` 动态注入，prompt 不再重复
+- 统一输出 `REMAINING: <text>` 或 `REMAINING: DONE`
 
 #### 7.3 Round 0 与 Round 1+ 差异
 
@@ -1776,27 +1829,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 +1912,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpage",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "Embeddable AI Agent SDK for browsers — let AI operate your web pages via tool-calling",
   "keywords": [
     "ai",