agentpage 0.0.16 → 0.0.19

package/README.md

@@ -16,6 +16,38 @@ AutoPilot 的目标不是生成文本，而是在浏览器中完成真实任务
   - `core`：环境无关引擎（Agent Loop、AI Client、Tool Registry）
   - `web`：浏览器能力实现（DOM/导航/快照/等待/执行）
 
+## 优势
+
+- 基于项目路由落地前端级 Agent：
+  - Agent 直接运行在真实业务页面，可感知当前路由上下文（列表页、详情页、弹窗页等）
+  - 同一套执行循环可在不同路由中持续推进任务，不依赖后端额外编排
+- 前端注册 Tools，快速接入复杂工程：
+  - 通过 `registerTools()` 和 `registerTool()` 把 DOM 操作、导航、等待、业务动作统一抽象为可调用能力
+  - 复杂页面中的“表单 + 下拉 + 弹窗 + 列表 + 路由跳转”可在同一 Agent 流程内组合执行
+- 对既有前端工程侵入低：
+  - 保持分层边界（`core` 环境无关、`web` 负责浏览器实现），便于在现有项目按需接入
+  - 通过快照驱动与工具调用机制，优先复用现有页面结构与交互逻辑
+
+## 企业项目接入建议（3 步）
+
+### 第 1 步：按路由划分 Agent 场景
+
+- 先选 1~2 个高价值页面（如“列表 + 详情 + 创建弹窗”）作为首批接入路由
+- 为每个路由定义“可执行动作清单”（查询、筛选、填写、提交、跳转）
+- 明确哪些区域需要排除在快照外（如自有 Agent 面板、调试浮层）
+
+### 第 2 步：注册工具并做业务动作封装
+
+- 基础能力先接入内置工具：DOM / navigate / wait / evaluate / page_info
+- 再补充业务工具：把常用复杂操作封装成稳定动作（如“创建仓库”“发布任务”）
+- 保持工具输入输出稳定：参数尽量结构化，错误码可观测，便于恢复重试
+
+### 第 3 步：上线前做最小闭环验证
+
+- 以真实路由跑通 3 类任务：表单填写、下拉选择、弹窗确认/列表结果校验
+- 对关键链路记录指标：工具成功率、恢复次数、快照体积、轮次收敛情况
+- 先灰度到内部场景，再逐步扩大覆盖页面与工具范围
+
 ---
 
 ## 快速开始
@@ -432,6 +464,26 @@ sequenceDiagram
 - 去重历史快照
 - 剥离旧 prompt 快照
 
+### 快照读取流程图
+
+```mermaid
+flowchart TD
+  A[chat 开始 / 新一轮开始] --> B{是否已有 latestSnapshot}
+  B -->|有| C[直接复用当前快照]
+  B -->|无| D[readPageSnapshot via page_info.snapshot]
+  D --> E[recordSnapshotStats 更新统计]
+  E --> F[wrapSnapshot 添加 SNAPSHOT_START/END]
+  C --> G[buildCompactMessages 注入 Latest DOM snapshot]
+  F --> G
+  G --> H[stripSnapshotFromPrompt 剥离 system prompt 旧快照]
+  H --> I[发送给模型并执行工具]
+  I --> J{是否触发恢复重拍}
+  J -->|导航成功/元素未找到恢复/每轮结束刷新| K[readPageSnapshot 刷新 latestSnapshot]
+  J -->|否| L[进入下一轮]
+  K --> E
+  L --> B
+```
+
 ---
 
 ## 保护机制

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":";;;;;;KA0BY,cAAA;EAuBV,qCArBA,OAAA,WAAkB,MAAA,mBAqBR;EAnBV,OAAA,GAAU,MAAA;AAAA;;;;;;ACfZ;;;KD0BY,cAAA;ECxBV,4CD0BA,IAAA,UCtBA;EDwBA,WAAA,UCxBK;ED0BL,MAAA,EAAQ,OAAA,ECpBW;EDsBnB,OAAA,GAAU,MAAA,EAAQ,MAAA,sBAA4B,OAAA,CAAQ,cAAA;AAAA;;;;KClC5C,UAAA;ED0BA,0BCxBV,EAAA;EAEA,IAAA,UD8BkB;EC5BlB,KAAA;AAAA;;KAMU,SAAA;EACV,IAAA,4CDiBA;ECfA,OAAA,WAAkB,KAAA;IAAQ,UAAA;IAAoB,MAAA;EAAA,IDmBpC;ECjBV,SAAA,GAAY,UAAA;AAAA;;KAMF,cAAA;iBAEV,IAAA;EAEA,SAAA,GAAY,UAAA,IA3BQ;EA6BpB,KAAA;IAAU,WAAA;IAAqB,YAAA;EAAA;AAAA;;;AAjBjC;;;KA2BY,QAAA;EACV,IAAA,CAAK,MAAA;IACH,YAAA;IACA,QAAA,EAAU,SAAA;IACV,KAAA,GAAQ,cAAA;EAAA,IACN,OAAA,CAAQ,cAAA;AAAA;;;KClDF,gBAAA;EACV,UAAA;EACA,cAAA;EACA,mBAAA;EACA,eAAA;EACA,eAAA;EACA,aAAA;EACA,uBAAA;EACA,iBAAA;EACA,kBAAA;EACA,eAAA;EACA,eAAA;EACA,WAAA;EACA,YAAA;AAAA;;KAMU,kBAAA;EFmBF,mBEjBR,MAAA,IAAU,IAAA,mBFmBQ;EEjBlB,UAAA,IAAc,IAAA,UAAc,KAAA,oBFiBkB;EEf9C,YAAA,IAAgB,IAAA,UAAc,MAAA,EAAQ,cAAA,WFe8B;EEbpE,OAAA,IAAW,KAAA;;;;ADrBb;;;;;EC8BE,wBAAA,IAA4B,MAAA,oBDxB5B;EC0BA,SAAA,IAAa,OAAA,EAAS,gBAAA;AAAA;AAAA,KA0BZ,eAAA;ED7BA,iBC+BV,KAAA,UD/B2C;ECiC3C,SAAA,EAAW,KAAA;IAAQ,IAAA;IAAc,KAAA;IAAgB,MAAA,EAAQ,cAAA;EAAA,IDnB/C;ECqBV,QAAA,EAAU,SAAA,IDpBN;ECsBJ,OAAA,EAAS,gBAAA;AAAA;;;;;;AFvDX;;;;;;;;;;AAeA;;;;;;;;;;;;;;cGAa,QAAA;EAAA,QACH,GAAA;EHOsC;EAAA,QGLtC,MAAA;EHK4D;;;;cGCxD,GAAA;EFnCF;;;;;;;EE8CV,GAAA,CAAI,EAAA,EAAI,OAAA,EAAS,IAAA;EFxCZ;AAMP;;;EEkDE,GAAA,CAAI,EAAA,WAAa,OAAA;EFjDjB;EEsDA,GAAA,CAAI,EAAA;EFpDc;EEyDlB,KAAA,CAAA;EFzD8C;;;;;AAQhD;;;EE6DE,KAAA,CAAM,GAAA;EF3DN;EAAA,IEmEI,IAAA,CAAA;AAAA;;;;KCvFM,eAAA;EJMc,mBIJxB,QAAA;EJQgB;;;;;EIFhB,YAAA;EJEgB;AAWlB;;;;EIPE,WAAA;EJesD;;;;;EITtD,QAAA,GAAW,QAAA,EJOX;EILA,QAAA,WJOA;EILA,WAAA,WJKU;EIHV,aAAA;AAAA;;;;;;AH/BF;;;;;;;;;AAYA;;;;;;iBG0CgB,gBAAA,CACd,IAAA,GAAM,OAAA,EACN,OAAA,GAAS,eAAA;AAAA,iBAkSK,kBAAA,CAAA,GAAsB,cAAA;;;iBC1NtB,aAAA,CAAA,GAAiB,cAAA;;;iBC/HjB,kBAAA,CAAA,GAAsB,cAAA;;;iBCmHtB,cAAA,CAAA,GAAkB,cAAA;;;iBCjElB,kBAAA,CAAA,GAAsB,cAAA;;;;;;ARxCtC;;;;;;;;;;AAeA;;;;;;;;;;;;;;KSXY,eAAA;EACV,IAAA;EACA,QAAA;EACA,MAAA,EAAQ,MAAA;EACR,MAAA;AAAA;;KAIU,gBAAA;EACV,IAAA;EACA,MAAA;EACA,MAAA;IACE,OAAA,WAAkB,MAAA;IAClB,OAAA,GAAU,MAAA;EAAA;AAAA;;;;ARhBd;;;;;iBQ8BgB,mBAAA,CAAA,IAEZ,QAAA,UACA,MAAA,EAAQ,MAAA,sBACP,OAAA;EAAU,OAAA,WAAkB,MAAA;EAAyB,OAAA,GAAU,MAAA;AAAA;;KAgCxD,eAAA,GAAkB,GAAA,UAE3B,MAAA,EAAQ,MAAA,sBAA4B,OAAA;EACnC,OAAA,WAAkB,MAAA;EAClB,OAAA,GAAU,MAAA;AAAA;;;;;;;;;iBAYE,mBAAA,CAAoB,SAAA,EAAW,eAAA;;;;KC1DnC,iBAAA,GAAoB,kBAAA;oBAE9B,UAAA,IAAc,QAAA;AAAA;AAAA,KAKJ,eAAA;ET3CU;;;;;;AAYtB;;;;;ES2CE,MAAA,GAAS,QAAA,ETxCS;ES0ClB,KAAA,WT1C8C;ES4C9C,QAAA,WT1CY;ES4CZ,KAAA,WT5CsB;ES8CtB,OAAA,WTxCwB;ES0CxB,MAAA,YTtCsB;ESwCtB,MAAA,YTxCA;ES0CA,YAAA,WTxCA;ES0CA,SAAA,WT1C+B;ES4C/B,MAAA,YT5C2C;ES8C3C,YAAA,YTpCkB;ESsClB,eAAA,GAAkB,eAAA;AAAA;AAAA,cAKP,QAAA;ETtCC;EAAA,QSwCJ,MAAA;EAAA,QACA,KAAA;EAAA,QACA,QAAA;EAAA,QACA,KAAA;EAAA,QACA,OAAA;EAAA,QACA,MAAA;EAAA,QACA,MAAA;EAAA,QACA,SAAA;EAAA,QACA,kBAAA;ETpDH;EAAA,QSuDG,MAAA;ETnDI;EAAA,QSqDJ,OAAA;ETrDkB;EAAA,QSuDlB,YAAA;;UAEA,eAAA;ER3GE;EAAA,QQ8GF,QAAA;;EAGR,SAAA,EAAW,iBAAA;cAEC,OAAA,EAAS,eAAA;ERjHrB;EQmIA,aAAA,CAAA;ERjIA;EQ0IA,YAAA,CAAa,IAAA,EAAM,cAAA;ERxInB;EQ6IA,QAAA,CAAA,GAAY,cAAA;ER3IZ;EQkJA,QAAA,CAAS,KAAA;ERhJT;;;;;;EQ0JA,SAAA,CAAU,MAAA,EAAQ,QAAA;ERjJU;EQsJ5B,WAAA,CAAY,QAAA;ERnI0B;EQwItC,QAAA,CAAS,KAAA;ERzJC;EQ8JV,SAAA,CAAU,OAAA;ER5JI;EQiKd,SAAA,CAAA;ER/JA;EQoKA,SAAA,CAAU,OAAA;ERpK4B;EQyKtC,eAAA,CAAgB,MAAA;ERvKhB;EQ4KA,SAAA,CAAU,OAAA;ERnKV;EQyKA,SAAA,CAAA;ERvKA;EQ4KA,eAAA,CAAgB,OAAA;ER5KH;EQiLb,eAAA,CAAA;ERjLsC;EQsLtC,kBAAA,CAAmB,OAAA,EAAS,eAAA;ER5JH;EQiKzB,kBAAA,CAAA,GAAsB,eAAA;ER7JmC;EQkKzD,YAAA,CAAA;ERhKU;;;;;;;;;EQ+KJ,IAAA,CAAK,OAAA,WAAkB,OAAA,CAAQ,eAAA;ERjLoB;;;;;EAAA,QQqQjD,mBAAA;AAAA"}
+{"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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"}