agentpage 0.0.2 → 0.0.4

package/dist/index.d.mts

@@ -68,6 +68,15 @@ type AgentLoopCallbacks = {
   onToolCall?: (name: string, input: unknown) => void; /** 工具执行完成时触发 */
   onToolResult?: (name: string, result: ToolCallResult) => void; /** 每轮循环开始时触发（round 从 0 开始） */
   onRound?: (round: number) => void;
+  /**
+   * 恢复快照生成前触发（页面 URL 变化或元素定位失败时）。
+   *
+   * 用于 WebAgent 重置 RefStore（清空旧的 hash ID → Element 映射，
+   * 用新 URL 重新生成确定性 hash），确保恢复快照中的 ID 有效。
+   *
+   * @param newUrl 当前页面 URL（URL 变化时传入；元素定位失败时为 undefined）
+   */
+  onBeforeRecoverySnapshot?: (newUrl?: string) => void;
 };
 type AgentLoopResult = {
   /** AI 的最终文本回复 */reply: string; /** 所有工具调用记录 */
@@ -79,6 +88,73 @@ type AgentLoopResult = {
   messages: AIMessage[];
 };
 //#endregion
+//#region src/web/ref-store.d.ts
+/**
+ * RefStore — 快照 hash ID 与 DOM 元素的映射表。
+ *
+ * 快照生成时，根据元素的 DOM 路径 + 页面 URL 生成确定性 hash ID，
+ * 同时保存 ID → Element 的映射。AI 使用 hash ID 作为 selector 定位元素，
+ * 免去超长 XPath 路径，大幅减少 token 消耗。
+ *
+ * 优势：
+ * - **确定性**：同一元素无论快照顺序，始终得到相同 ID
+ * - **并发安全**：多次快照不会产生 ID 冲突
+ * - **跨页面隔离**：URL hash 作为命名空间，不同页面元素 ID 互不碰撞
+ *
+ * 生命周期：每次 WebAgent.chat() 调用时创建，对话结束后清空。
+ *
+ * 使用方：
+ *   page-info-tool.ts — generateSnapshot() 写入映射
+ *   dom-tool.ts       — queryElement() 读取映射
+ *   index.ts          — WebAgent 持有实例，管理生命周期
+ */
+/**
+ * hash ID → DOM 元素的映射存储。
+ *
+ * - `set(el, path)` 由快照生成时调用，返回确定性 hash ID
+ * - `get(id)` 由 dom-tool 查询时调用，根据 hash ID 取回元素
+ * - `has(id)` 检查 ID 是否存在（用于 selector 类型判断）
+ * - `clear()` 每次对话结束后清空
+ */
+declare class RefStore {
+  private map;
+  /** 页面 URL 的 hash 前缀，用于跨页面命名空间隔离 */
+  private urlKey;
+  /**
+   * @param url 当前页面 URL（可选）。传入后作为 hash 命名空间，
+   *            使不同页面的相同 DOM 路径产生不同 ID。
+   */
+  constructor(url?: string);
+  /**
+   * 注册一个元素，返回确定性 hash ID。
+   * 相同 URL + path 始终产生相同 ID（并发安全）。
+   *
+   * @param el   DOM 元素引用
+   * @param path 元素的 XPath-like 路径（如 "/body/div[1]/main/button"）
+   */
+  set(el: Element, path: string): string;
+  /**
+   * 根据 hash ID 获取 DOM 元素。
+   * 返回 Element 或 undefined（ID 不存在或元素已被移除）。
+   */
+  get(id: string): Element | undefined;
+  /** 检查 hash ID 是否存在 */
+  has(id: string): boolean;
+  /** 清空所有映射 */
+  clear(): void;
+  /**
+   * 重置映射表：清空所有映射，并可选更新 URL 命名空间。
+   *
+   * 用于页面导航后刷新 RefStore：旧的 hash ID → Element 映射已失效，
+   * 需要用新 URL 重新生成确定性 hash。
+   *
+   * @param url 新的页面 URL（不传则保持原 URL 命名空间）
+   */
+  reset(url?: string): void;
+  /** 当前映射数量 */
+  get size(): number;
+}
+//#endregion
 //#region src/web/page-info-tool.d.ts
 /** 快照配置选项 */
 type SnapshotOptions = {
@@ -95,31 +171,29 @@ type SnapshotOptions = {
    * 如果自身无意义，会被折叠——子元素直接提升到父级输出，减少嵌套噪音。
    */
   pruneLayout?: boolean;
+  /**
+   * hash ID 映射表（可选）。
+   * 传入 RefStore 实例后，每个元素使用确定性 hash ID 替代完整 XPath，
+   * 大幅减少 token 消耗。dom-tool 通过 RefStore.get(id) 解析回 DOM 元素。
+   */
+  refStore?: RefStore;
 };
 /**
  * 生成页面 DOM 快照 — 将 DOM 树转为 AI 可理解的文本描述。
  *
- * 类似 Playwright 的 ariaSnapshot()，但基于 Web API 实现。
- * 只遍历可见元素，跳过 script/style/svg 等无意义节点。
- *
- * 每个元素自动生成基于层级位置的 XPath 引用（ref），
- * AI 可以通过 ref 精确定位元素，无需猜测 CSS 选择器。
+ * 基于 Web API 实现，只遍历可见元素，跳过 script/style/svg 等无意义节点。
+ * 传入 RefStore 时，每个元素生成确定性 hash ID（如 #a1b2c），
+ * AI 通过 hash ID 精确定位元素，无需猜测 CSS 选择器。
  *
  * 输出格式示例：
- *   [header] ref="/body/header"
- *     [nav] ref="/body/header/nav"
- *       [a] "首页" href="/" ref="/body/header/nav/a[1]"
- *       [a] "关于" href="/about" ref="/body/header/nav/a[2]"
- *   [main] ref="/body/main"
- *     [h1] "欢迎来到示例网站" ref="/body/main/h1"
- *     [input] type="text" placeholder="搜索..." ref="/body/main/input"
- *     [button] "搜索" id="search-btn" onclick ref="/body/main/button"
- *
- * 增强信息：
- * - id：元素的 id 属性
- * - placeholder：输入框的占位文本
- * - 事件绑定：onclick/onchange 等内联事件处理器
- * - 状态属性：disabled/checked/readonly/required 等
+ *   [header] #k9f2a
+ *     [nav] #m3d7e
+ *       [a] "首页" href="/" #p1c4b
+ *       [a] "关于" href="/about" #q8e5f
+ *   [main] #r2a6d
+ *     [h1] "欢迎" #s7g3h
+ *     [input] type="text" placeholder="搜索..." #t4j8k
+ *     [button] "搜索" id="search-btn" onclick #u5n2m
  *
  * @param root - 快照根元素（默认 document.body）
  * @param options - 快照选项对象，或传入数字作为 maxDepth（向后兼容）

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/index.ts","../src/web/page-info-tool.ts","../src/web/dom-tool.ts","../src/web/navigate-tool.ts","../src/web/wait-tool.ts","../src/web/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/index.ts","../src/web/ref-store.ts","../src/web/page-info-tool.ts","../src/web/dom-tool.ts","../src/web/navigate-tool.ts","../src/web/wait-tool.ts","../src/web/evaluate-tool.ts","../src/web/messaging.ts","../src/web/index.ts"],"mappings":"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"}