agentpage 0.0.1

package/README.md

@@ -0,0 +1,331 @@
+# AutoPilot
+
+> **浏览器内嵌 AI Agent SDK** — 让 AI 通过 tool-calling 操作你的网页。
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+一行代码给你的网站加上 AI Agent 能力：用户说一句话，AI 自动点击按钮、填写表单、读取数据、执行 JS。
+
+基于原生 `fetch` 的纯浏览器 AI 客户端，支持 **OpenAI** / **GitHub Copilot** / **Anthropic**。唯一运行时依赖：`@sinclair/typebox`。
+
+---
+
+## 核心特性
+
+- **内嵌式 Agent** — 运行在页面内部，直接操作 DOM，无需截图、无需外部浏览器进程
+- **零 SDK 依赖** — 使用原生 `fetch` 连接 AI，不引入 openai / anthropic SDK
+- **DOM 快照 + Ref 路径** — 自动生成页面结构快照，AI 通过 ref 路径精确定位元素，无需猜测选择器
+- **5 个内置工具** — DOM 操作、页面导航、页面信息、等待元素、JS 执行
+- **可扩展** — 通过 `registerTool()` 添加自定义工具
+- **多轮记忆** — 可开关的对话历史，Agent 能记住上下文
+- **Chrome Extension 支持** — 内置 Service Worker ↔ Content Script 消息桥
+- **~2000 行** — 轻量、可审计、无黑箱
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+pnpm install
+```
+
+### 使用
+
+```typescript
+import { WebAgent } from "autopilot/web";
+
+const agent = new WebAgent({
+  token: "your-api-key",
+  provider: "copilot",    // "copilot" | "openai" | "anthropic"
+  model: "gpt-4o",
+  memory: true,           // 开启多轮记忆
+  autoSnapshot: true,     // 每次对话前自动生成 DOM 快照（默认开启）
+});
+
+agent.registerTools();    // 注册 5 个内置 Web 工具
+
+agent.callbacks = {
+  onText: (text) => console.log("AI:", text),
+  onToolCall: (name, input) => console.log("🔧", name),
+  onToolResult: (name, result) => console.log("✅", name, result.content),
+  onSnapshot: (snapshot) => console.log("📸 快照已生成"),
+};
+
+const result = await agent.chat("把搜索框填上 'AutoPilot' 然后点搜索按钮");
+console.log(result.reply);
+```
+
+### 运行 Demo
+
+```bash
+pnpm demo  # 启动 Vite 开发服务器，端口 3000
+```
+
+Demo 页面提供开箱即用的聊天 UI（暗色主题），包含：
+- Token 输入（localStorage 持久化）
+- 模型选择（gpt-4o / gpt-4o-mini / o3-mini）
+- Dry-run 开关 & 多轮记忆开关
+- 6 个快捷测试按钮（页面信息、DOM 快照、点击、链接、滚动、DOM 计数）
+- 实时展示工具调用和结果
+
+---
+
+## 架构
+
+```
+src/
+├── core/                        # 🔷 共享引擎（零环境依赖，纯 TypeScript + fetch）
+│   ├── types.ts                 #    类型：AIClient, AIMessage, AIChatResponse, AIToolCall
+│   ├── tool-registry.ts         #    ToolRegistry 类 + 辅助函数（readStringParam 等）
+│   ├── agent-loop.ts            #    决策循环：executeAgentLoop()（ReAct 模式）
+│   ├── ai-client.ts             #    AI 客户端工厂：createAIClient()（纯 fetch）
+│   └── system-prompt.ts         #    系统提示词构建：buildSystemPrompt()
+│
+├── web/                         # 🌐 浏览器端 Agent（依赖 core）
+│   ├── index.ts                 #    WebAgent 类 — 浏览器端 AI Agent 入口
+│   └── tools/
+│       ├── register.ts          #    registerWebTools(registry) — 注册 5 个工具
+│       ├── dom-tool.ts          #    DOM 操作：click, fill, type, get_text, get_attr...
+│       ├── navigate-tool.ts     #    页面导航：goto, back, forward, reload, scroll
+│       ├── page-info-tool.ts    #    页面信息与 DOM 快照：url, title, snapshot...
+│       ├── wait-tool.ts         #    等待元素：waitForSelector（MutationObserver）
+│       ├── evaluate-tool.ts     #    JS 执行：在页面上下文中运行任意代码
+│       └── messaging.ts         #    Chrome Extension 消息桥（SW ↔ Content Script）
+│
+demo/                            # 🎨 Web Agent 演示
+├── index.html                   #    Chat UI（暗色主题 + 快捷测试按钮）
+├── main.ts                      #    WebAgent 实例 + UI 交互 + 回调绑定
+```
+
+两层结构：`core`（引擎，零环境依赖）+ `web`（浏览器工具 + DOM API），13 个源文件。
+
+### 设计原则
+
+| 层 | 目录 | 依赖 | 环境 |
+|----|------|------|------|
+| **core** | `src/core/` | 无（纯 TypeScript + fetch） | 任意（浏览器 / Worker） |
+| **web** | `src/web/` | core + DOM API | 浏览器 |
+
+- `web/` 只从 `core/` 导入，`core/` 不含任何 DOM/Node API
+- ToolRegistry 是实例化的（非全局 Map），每个 Agent 拥有独立的工具集
+- 全链路「容错不中断」— 单个工具失败不会中止 Agent 循环
+
+---
+
+## AI Provider 支持
+
+| Provider | 端点 | 认证头 |
+|----------|------|--------|
+| `copilot` | `https://models.inference.ai.azure.com` | `Authorization: Bearer <GitHub PAT>` |
+| `openai` | `https://api.openai.com/v1` | `Authorization: Bearer <API Key>` |
+| `anthropic` | `https://api.anthropic.com` | `x-api-key: <API Key>` |
+
+所有 provider 均使用原生 `fetch` 调用，支持 `baseURL` 自定义端点（如代理服务器）。
+
+### 两层 API
+
+**高层 API** — 一步到位：
+
+```typescript
+import { createAIClient } from "autopilot/core/ai-client";
+
+const client = createAIClient({ provider: "copilot", model: "gpt-4o", apiKey: "ghp_xxx" });
+const response = await client.chat({ systemPrompt, messages, tools });
+```
+
+**底层 API** — 自定义 fetch 逻辑（自定义 headers、超时、重试、代理等）：
+
+```typescript
+import { buildChatRequest, parseChatResponse } from "autopilot/core/ai-client";
+
+const config = { provider: "copilot", model: "gpt-4o", apiKey: "ghp_xxx" };
+const req = buildChatRequest(config, { systemPrompt, messages, tools });
+
+// 自定义修改请求
+req.headers["X-Custom"] = "value";
+
+// 自行 fetch 并解析
+const { url, ...init } = req;
+const res = await fetch(url, init);
+const data = await res.json();
+const response = parseChatResponse(config.provider, data);
+```
+
+---
+
+## 工具一览
+
+| 工具 | 动作 | 说明 |
+|------|------|------|
+| **dom** | `click`, `fill`, `type`, `get_text`, `get_attr`, `set_attr`, `add_class`, `remove_class` | DOM 操作（支持 ref 路径和 CSS 选择器） |
+| **navigate** | `goto`, `back`, `forward`, `reload`, `scroll` | 页面导航 |
+| **page_info** | `get_url`, `get_title`, `get_selection`, `get_viewport`, `snapshot`, `query_all` | 页面信息与 DOM 快照 |
+| **wait** | `wait_for_selector`, `wait_for_hidden`, `wait_for_text` | 等待元素变化（MutationObserver） |
+| **evaluate** | *expression* | 执行任意 JavaScript（`new Function`） |
+
+### DOM 快照与 Ref 路径
+
+这是 AutoPilot 的核心设计 — 让 AI **精确定位** DOM 元素，无需猜测 CSS 选择器。
+
+`generateSnapshot()` 将 DOM 树转为 AI 可理解的文本描述，每个元素自动生成基于层级位置的 ref 路径：
+
+```
+[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"
+```
+
+AI 使用 ref 路径调用 `dom` 工具，`resolveRef()` 在运行时将路径解析回 DOM 元素。采集的信息包括：id、class、交互属性、布尔状态、事件绑定、data-\* 属性、实时 value。
+
+### 添加自定义工具
+
+```typescript
+import { Type } from "@sinclair/typebox";
+
+agent.registerTool({
+  name: "my_tool",
+  description: "描述这个工具做什么",
+  schema: Type.Object({
+    param: Type.String({ description: "参数说明" }),
+  }),
+  async execute(params) {
+    return { content: "执行结果" };
+  },
+});
+```
+
+---
+
+## API
+
+### `WebAgent`
+
+```typescript
+new WebAgent(options: WebAgentOptions)
+```
+
+**配置选项：**
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `token` | `string` | 必填 | API Key（GitHub PAT / OpenAI key / Anthropic key） |
+| `provider` | `string` | `"copilot"` | AI 提供商：`"copilot"` \| `"openai"` \| `"anthropic"` |
+| `model` | `string` | `"gpt-4o"` | 模型名称 |
+| `baseURL` | `string` | — | 自定义 API 基础 URL |
+| `dryRun` | `boolean` | `false` | 干运行（只打印工具调用不执行） |
+| `systemPrompt` | `string` | — | 自定义系统提示词（不传则使用默认） |
+| `maxRounds` | `number` | `10` | 最大工具调用轮次 |
+| `memory` | `boolean` | `false` | 多轮对话记忆开关 |
+| `autoSnapshot` | `boolean` | `true` | 每次 chat 前自动生成 DOM 快照 |
+
+**方法：**
+
+| 方法 | 说明 |
+|------|------|
+| `registerTools()` | 注册 5 个内置 Web 工具 |
+| `registerTool(tool)` | 注册自定义工具 |
+| `getTools()` | 获取所有已注册工具定义 |
+| `chat(message)` | 发送消息，返回 `AgentLoopResult` |
+| `setToken(token)` | 更新 API Key |
+| `setProvider(provider)` | 更新 AI 提供商 |
+| `setModel(model)` | 更新模型 |
+| `setDryRun(enabled)` | 切换干运行模式 |
+| `setSystemPrompt(prompt)` | 设置自定义系统提示词 |
+| `setMemory(enabled)` | 开关多轮记忆（关闭时自动清空历史） |
+| `getMemory()` | 获取当前记忆开关状态 |
+| `setAutoSnapshot(enabled)` | 开关自动快照 |
+| `getAutoSnapshot()` | 获取当前自动快照开关 |
+| `clearHistory()` | 清空对话历史（不影响记忆开关） |
+
+**回调（`callbacks`）：**
+
+| 回调 | 触发时机 |
+|------|---------|
+| `onRound(round)` | 每轮循环开始（round 从 0 开始） |
+| `onText(text)` | AI 返回文本回复 |
+| `onToolCall(name, input)` | AI 请求调用工具（执行前） |
+| `onToolResult(name, result)` | 工具执行完成 |
+| `onSnapshot(snapshot)` | 自动快照生成完成 |
+
+### `AgentLoopResult`
+
+`chat()` 返回值：
+
+```typescript
+{
+  reply: string;                // AI 的最终文本回复
+  toolCalls: Array<{            // 所有工具调用记录
+    name: string;
+    input: unknown;
+    result: ToolCallResult;
+  }>;
+  messages: AIMessage[];        // 完整对话消息（用于多轮记忆累积）
+}
+```
+
+---
+
+## Chrome Extension 支持
+
+AutoPilot 内置 Service Worker ↔ Content Script 消息桥，解决 Chrome Extension 的作用域隔离：
+
+```
+Service Worker (后台)                    Content Script (页面)
+┌──────────────────┐                    ┌──────────────────────┐
+│  AI Agent 核心    │  AUTOPILOT_TOOL_CALL │  DOM 操作执行         │
+│  createProxy     │  ────────────────►  │  registerToolHandler │
+│  Executor()      │                    │                      │
+│                  │  AUTOPILOT_TOOL_RESULT│                     │
+│                  │  ◄────────────────  │                      │
+└──────────────────┘                    └──────────────────────┘
+```
+
+```typescript
+// Service Worker 端
+import { createProxyExecutor } from "agentpage";
+const execute = createProxyExecutor();
+
+// Content Script 端
+import { registerToolHandler } from "agentpage";
+registerToolHandler(executorMap);
+```
+
+---
+
+## 开发
+
+```bash
+pnpm install          # 安装依赖
+pnpm build            # 构建产物（tsdown → dist/）
+pnpm check            # 类型检查（tsc --noEmit）+ lint（oxlint）
+pnpm lint             # 代码检查（oxlint）
+pnpm format           # 代码格式化（oxfmt --write）
+pnpm format:check     # 检查格式（oxfmt --check，不修改）
+pnpm demo             # 启动 Demo（Vite，端口 3000）
+pnpm test             # 运行测试（vitest run，单次执行）
+pnpm test:watch       # 运行测试（vitest watch 模式）
+```
+
+### 工具链
+
+| 工具 | 用途 |
+|------|------|
+| **tsdown** | 构建打包（产出 `dist/`） |
+| **oxlint** | 代码检查（替代 ESLint） |
+| **oxfmt** | 代码格式化（替代 Prettier） |
+| **vitest** | 测试框架（覆盖率阈值 60%） |
+| **vite** | Demo 开发服务器 |
+| **TypeScript 5.9+** | 严格模式，`module: NodeNext` |
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,320 @@
+import { TObject } from "@sinclair/typebox";
+
+//#region src/core/tool-registry.d.ts
+/**
+ * 工具执行结果 — 每个工具的 execute() 必须返回此类型。
+ */
+type ToolCallResult = {
+  /** 返回内容（字符串文本或结构化对象，最终会序列化后发给 AI） */content: string | Record<string, unknown>; /** 可选的额外细节（用于日志记录、调试等，不直接发给 AI） */
+  details?: Record<string, unknown>;
+};
+/**
+ * 工具定义 — 注册工具时需要提供的完整描述。
+ *
+ * 这四个字段分别告诉 AI「叫什么名字」「能做什么」「需要什么参数」「怎么执行」：
+ * - name + description → AI 根据用户意图选择合适的工具
+ * - schema → AI 生成符合格式的参数 JSON
+ * - execute → 实际执行逻辑
+ */
+type ToolDefinition = {
+  /** 工具名称（AI 通过此名称调用，如 "exec"、"file_read"） */name: string; /** 工具描述（AI 据此判断何时使用这个工具） */
+  description: string; /** 参数的 JSON Schema（TypeBox 定义，描述工具接受哪些参数及其类型） */
+  schema: TObject; /** 执行函数 — 接收 AI 传入的参数，返回执行结果 */
+  execute: (params: Record<string, unknown>) => Promise<ToolCallResult>;
+};
+//#endregion
+//#region src/core/types.d.ts
+/** AI 模型返回的工具调用指令 */
+type AIToolCall = {
+  /** 调用 ID（用于将结果关联回此次调用） */id: string; /** 工具名称（如 "dom"、"page_info"） */
+  name: string; /** AI 传入的参数 */
+  input: unknown;
+};
+/** 对话消息（统一格式，支持 user / assistant / tool / system 角色） */
+type AIMessage = {
+  role: "user" | "assistant" | "tool" | "system"; /** 文本内容，或工具执行结果数组 */
+  content: string | Array<{
+    toolCallId: string;
+    result: string;
+  }>; /** assistant 消息中附带的工具调用列表 */
+  toolCalls?: AIToolCall[];
+};
+/** AI 聊天接口的返回值 */
+type AIChatResponse = {
+  /** AI 的文本回复 */text?: string; /** AI 请求的工具调用列表 */
+  toolCalls?: AIToolCall[]; /** Token 使用统计 */
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+};
+/**
+ * AI 客户端抽象接口。
+ *
+ * 通过 createAIClient() 工厂函数创建，基于原生 fetch 实现。
+ */
+type AIClient = {
+  chat(params: {
+    systemPrompt: string;
+    messages: AIMessage[];
+    tools?: ToolDefinition[];
+  }): Promise<AIChatResponse>;
+};
+//#endregion
+//#region src/core/agent-loop/index.d.ts
+/** 工具调用事件回调 — 用于 UI 层实时展示 Agent 进度 */
+type AgentLoopCallbacks = {
+  /** AI 返回文本回复时触发 */onText?: (text: string) => void; /** AI 请求调用工具时触发（执行前） */
+  onToolCall?: (name: string, input: unknown) => void; /** 工具执行完成时触发 */
+  onToolResult?: (name: string, result: ToolCallResult) => void; /** 每轮循环开始时触发（round 从 0 开始） */
+  onRound?: (round: number) => void;
+};
+type AgentLoopResult = {
+  /** AI 的最终文本回复 */reply: string; /** 所有工具调用记录 */
+  toolCalls: Array<{
+    name: string;
+    input: unknown;
+    result: ToolCallResult;
+  }>; /** 本轮完整对话消息（含历史 + 本轮，用于多轮记忆累积） */
+  messages: AIMessage[];
+};
+//#endregion
+//#region src/web/page-info-tool.d.ts
+/** 快照配置选项 */
+type SnapshotOptions = {
+  /** 最大遍历深度（默认 6） */maxDepth?: number;
+  /**
+   * 视口裁剪：只保留与视口相交的元素（默认 true）。
+   * 开启后，完全在视口外的元素会被跳过，大幅减少 token 消耗。
+   * 注意：祖先容器即使自身不在视口内，只要有子元素在视口内就会保留。
+   */
+  viewportOnly?: boolean;
+  /**
+   * 智能剪枝：折叠无意义的纯布局容器（默认 true）。
+   * 开启后，没有文本、没有 id、没有交互属性的纯布局元素（div/span/section 等）
+   * 如果自身无意义，会被折叠——子元素直接提升到父级输出，减少嵌套噪音。
+   */
+  pruneLayout?: boolean;
+};
+/**
+ * 生成页面 DOM 快照 — 将 DOM 树转为 AI 可理解的文本描述。
+ *
+ * 类似 Playwright 的 ariaSnapshot()，但基于 Web API 实现。
+ * 只遍历可见元素，跳过 script/style/svg 等无意义节点。
+ *
+ * 每个元素自动生成基于层级位置的 XPath 引用（ref），
+ * AI 可以通过 ref 精确定位元素，无需猜测 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 等
+ *
+ * @param root - 快照根元素（默认 document.body）
+ * @param options - 快照选项对象，或传入数字作为 maxDepth（向后兼容）
+ */
+declare function generateSnapshot(root?: Element, options?: SnapshotOptions | number): string;
+declare function createPageInfoTool(): ToolDefinition;
+//#endregion
+//#region src/web/dom-tool.d.ts
+declare function createDomTool(): ToolDefinition;
+//#endregion
+//#region src/web/navigate-tool.d.ts
+declare function createNavigateTool(): ToolDefinition;
+//#endregion
+//#region src/web/wait-tool.d.ts
+declare function createWaitTool(): ToolDefinition;
+//#endregion
+//#region src/web/evaluate-tool.d.ts
+declare function createEvaluateTool(): ToolDefinition;
+//#endregion
+//#region src/web/messaging.d.ts
+/**
+ * Web Tools 消息通信桥接层。
+ *
+ * 解决 Chrome Extension 的作用域隔离问题：
+ *
+ *   Service Worker (后台)                    Content Script (页面)
+ *   ┌──────────────────┐                    ┌──────────────────────┐
+ *   │ agent-core       │                    │ document / window    │
+ *   │ tool-registry    │  chrome.tabs       │                      │
+ *   │                  │  .sendMessage()    │ DOM 操作实际执行       │
+ *   │ tool.execute()   │ ─────────────────► │ handleToolMessage()  │
+ *   │   ↓              │                    │   ↓                  │
+ *   │ sendToContent()  │ ◄───────────────── │   返回执行结果        │
+ *   └──────────────────┘   response         └──────────────────────┘
+ *
+ * 使用方式：
+ *   Service Worker 端：
+ *     import { createProxyExecutor } from "./messaging.js";
+ *     const execute = createProxyExecutor();
+ *     // execute 会把调用转发到 content script
+ *
+ *   Content Script 端：
+ *     import { registerToolHandler } from "./messaging.js";
+ *     registerToolHandler(actualExecutors);
+ *     // 监听来自 service worker 的工具调用请求
+ */
+/** Service Worker → Content Script 的工具调用请求 */
+type ToolCallMessage = {
+  type: "AUTOPILOT_TOOL_CALL";
+  toolName: string;
+  params: Record<string, unknown>;
+  callId: string;
+};
+/** Content Script → Service Worker 的工具调用结果 */
+type ToolCallResponse = {
+  type: "AUTOPILOT_TOOL_RESULT";
+  callId: string;
+  result: {
+    content: string | Record<string, unknown>;
+    details?: Record<string, unknown>;
+  };
+};
+/**
+ * 创建代理执行器 — 在 Service Worker 端使用。
+ *
+ * 它不直接执行 DOM 操作，而是通过 chrome.tabs.sendMessage
+ * 把调用请求发给当前活动 tab 的 content script 执行。
+ *
+ * @returns execute 函数，签名与 ToolDefinition.execute 相同
+ */
+declare function createProxyExecutor(): (toolName: string, params: Record<string, unknown>) => Promise<{
+  content: string | Record<string, unknown>;
+  details?: Record<string, unknown>;
+}>;
+/** 工具执行器映射：toolName → execute 函数 */
+type ToolExecutorMap = Map<string, (params: Record<string, unknown>) => Promise<{
+  content: string | Record<string, unknown>;
+  details?: Record<string, unknown>;
+}>>;
+/**
+ * 在 Content Script 端注册工具执行处理器。
+ *
+ * 监听来自 Service Worker 的 AUTOPILOT_TOOL_CALL 消息，
+ * 根据 toolName 找到对应的执行函数，执行后返回结果。
+ *
+ * @param executors 工具名称 → 执行函数的映射
+ */
+declare function registerToolHandler(executors: ToolExecutorMap): void;
+//#endregion
+//#region src/web/index.d.ts
+/** WebAgent 事件回调（扩展 AgentLoopCallbacks，增加快照事件） */
+type WebAgentCallbacks = AgentLoopCallbacks & {
+  /** 自动快照生成完成时触发 */onSnapshot?: (snapshot: string) => void;
+};
+type WebAgentOptions = {
+  /**
+   * 自定义 AI 客户端实例（可选）。
+   *
+   * 传入后将直接使用该实例进行对话，忽略 token / provider / model / baseURL。
+   * 支持 BaseAIClient 或任何实现 AIClient 接口的对象。
+   *
+   * ```ts
+   * const client = new BaseAIClient({ chatHandler: async (params) => { ... } });
+   * const agent = new WebAgent({ client });
+   * ```
+   */
+  client?: AIClient; /** API 认证 Token (GitHub PAT / OpenAI key / Anthropic key) */
+  token?: string; /** AI 提供商: "copilot" | "openai" | "anthropic"（默认 "copilot"） */
+  provider?: string; /** 模型名称（默认 "gpt-4o"） */
+  model?: string; /** 自定义 API 基础 URL（可选，覆盖 provider 默认值） */
+  baseURL?: string; /** 是否启用干运行模式 */
+  dryRun?: boolean; /** 自定义系统提示词（不传则使用默认 Web 提示词） */
+  systemPrompt?: string; /** 最大工具调用轮次（默认 10） */
+  maxRounds?: number; /** 是否启用多轮对话记忆（默认 false） */
+  memory?: boolean; /** 是否在每次对话前自动生成页面快照（默认 true） */
+  autoSnapshot?: boolean; /** 快照选项（视口裁剪、智能剪枝等，autoSnapshot 开启时生效） */
+  snapshotOptions?: SnapshotOptions;
+};
+declare class WebAgent {
+  /** 用户传入的自定义 AI 客户端实例（优先级高于 token/provider） */
+  private client?;
+  private token;
+  private provider;
+  private model;
+  private baseURL?;
+  private dryRun;
+  private maxRounds;
+  private customSystemPrompt?;
+  /** 多轮对话记忆开关 */
+  private memory;
+  /** 对话历史（memory 开启时自动累积） */
+  private history;
+  /** 自动快照开关 */
+  private autoSnapshot;
+  /** 快照选项 */
+  private snapshotOptions;
+  /** 工具注册表实例 — 每个 WebAgent 拥有独立的工具集 */
+  private registry;
+  /** 事件回调 — 绑定后可实时获取 Agent 进度，用于 UI 展示 */
+  callbacks: WebAgentCallbacks;
+  constructor(options: WebAgentOptions);
+  /** 注册所有内置 Web 工具（dom, navigate, page_info, wait, evaluate） */
+  registerTools(): void;
+  /** 注册一个自定义工具 */
+  registerTool(tool: ToolDefinition): void;
+  /** 获取所有已注册的工具定义列表 */
+  getTools(): ToolDefinition[];
+  /** 设置 API Token */
+  setToken(token: string): void;
+  /**
+   * 设置自定义 AI 客户端实例。
+   *
+   * 传入后将优先使用该实例进行对话，忽略 token / provider / model / baseURL。
+   * 传入 undefined 可恢复使用内置客户端。
+   */
+  setClient(client: AIClient | undefined): void;
+  /** 设置 AI 提供商 */
+  setProvider(provider: string): void;
+  /** 设置模型 */
+  setModel(model: string): void;
+  /** 切换干运行模式 */
+  setDryRun(enabled: boolean): void;
+  /** 设置自定义系统提示词 */
+  setSystemPrompt(prompt: string): void;
+  /** 开启或关闭多轮对话记忆 */
+  setMemory(enabled: boolean): void;
+  /** 获取当前记忆开关状态 */
+  getMemory(): boolean;
+  /** 开启或关闭自动快照 */
+  setAutoSnapshot(enabled: boolean): void;
+  /** 获取当前自动快照开关状态 */
+  getAutoSnapshot(): boolean;
+  /** 设置快照选项（视口裁剪、智能剪枝等） */
+  setSnapshotOptions(options: SnapshotOptions): void;
+  /** 获取当前快照选项 */
+  getSnapshotOptions(): SnapshotOptions;
+  /** 清空对话历史（不影响记忆开关） */
+  clearHistory(): void;
+  /**
+   * 发送消息并获取 AI 回复（含完整工具调用循环）。
+   *
+   * 内部流程（全部复用 core）：
+   * 1. createAIClient() → 创建 fetch AI 客户端
+   * 2. buildSystemPrompt() → 构建系统提示词
+   * 3. executeAgentLoop() → 执行决策循环
+   * 4. callbacks → 实时通知 UI
+   */
+  chat(message: string): Promise<AgentLoopResult>;
+  /**
+   * 创建内置 AI 客户端（基于 token / provider / model 配置）。
+   *
+   * @throws 未设置 token 时抛出 Error
+   */
+  private createBuiltinClient;
+}
+//#endregion
+export { type SnapshotOptions, type ToolCallMessage, type ToolCallResponse, type ToolExecutorMap, WebAgent, WebAgentCallbacks, WebAgentOptions, createDomTool, createEvaluateTool, createNavigateTool, createPageInfoTool, createProxyExecutor, createWaitTool, generateSnapshot, registerToolHandler };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +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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"}