浏览器内嵌 AI Agent SDK：让 AI 通过 tool-calling 操作网页。

核心主张：通过 Prompt + Tools + 路由，快速为网站实现 AI 赋能，并构建前端运行时 AI Skill。AutoPilot 本质上是一个运行在前端浏览器中的 AI Agent。

AutoPilot 的目标不是生成文本，而是在浏览器中完成真实任务：点击、填写、导航、等待、执行脚本，并在每一轮根据最新页面状态持续推进。

它的机制可以概括为三句话：

1. 极简、纯原生：不依赖后端执行引擎，不要求重型中台改造，直接在前端浏览器环境运行。
2. 易集成、低侵入：可以快速接入各类前端工程，通过少量配置就能落地可执行 Agent。
3. 可编排、可扩展：通过用户可自定义的 Prompt 规则 + Tools 注册 + 路由上下文，为网站渐进式构建 AI 能力（即前端运行时 AI Skill）。

AutoPilot 的定位是"Web 端原生 Agent 补充层"：在当前行业里，大多数 Agent 仍以"后端服务编排 + API 调用"为主，而真正长期驻留在前端浏览器、直接理解并操作真实页面状态的 Agent 仍然稀缺。AutoPilot 关注的正是这块空白能力。

npm install agentpage

• 角色定位：作为后端 Agent 的补充，而非替代
• 运行形态：完全运行在浏览器上下文（可扩展到 Chrome Extension）
• 核心机制：快照驱动 + 工具调用 + 增量消费
• 场景目标：让 AI 理解"当前路由能做什么"，并在该上下文内可靠执行
• 产品形态：可作为前端系统的"AI 插件层"，按项目逐步接入、按路由逐步增强
• 架构分层：
  • core：环境无关引擎（Agent Loop、AI Client、Tool Registry）
  • web：浏览器能力实现（DOM/导航/快照/等待/执行）

核心公式：

• Prompt（策略） + Tools（能力） + Route（上下文） = 前端运行时 AI Skill

三层职责：

1. Prompt 层（可自定义）：定义该页面的执行边界、风险约束、输出协议。
2. Tools 层（可注册）：定义 AI 在该页面可调用的动作集合（通用 + 业务专用）。
3. Route 层（运行时上下文）：告诉 AI 当前在哪个页面、允许做哪些任务、禁做哪些动作。

为什么这个模型对复杂业务有效：

• Prompt 解决"怎么做才安全可靠"。
• Tools 解决"能做什么动作"。
• Route 解决"现在应该做什么"。

因此它非常适合 DevOps/ERP 等高复杂前端系统：可按路由渐进式接入，不需要一次性重构全站。

• 传统后端 Agent 更擅长：流程编排、跨系统调用、数据聚合。
• 前端原生 Agent 更擅长：理解当前页面真实状态、直接操作复杂 UI 组件、处理路由内交互细节。
• 两者组合后可形成闭环：
  • 后端负责"全局计划与系统级动作"
  • 前端负责"页面级执行与交互落地"

对 DevOps / ERP 这类复杂系统尤其关键：

• 页面状态复杂（列表、筛选、弹窗、步骤流、权限态）且变化快。
• 纯后端视角很难精确知道"此刻页面上到底可点什么"。
• 前端 Agent 可以基于快照和路由上下文做增量消费，显著减少误操作与空转。

• Prompt + Tools + 路由三层解耦：可以快速把"可执行 AI 能力"植入现有前端系统，按路由渐进式接入，支持"项目级工具 + 路由级工具"组合。
• 增量任务消费协议（REMAINING）：任务不是一次性执行，而是逐轮消费收敛。每轮只做当前快照可执行的动作，通过 REMAINING 协议跟踪进度，支持协议修复和启发式回退，确保复杂多步任务稳定收敛。
• 原始目标锚定（Original Goal Anchor）：Round 1+ 每轮消息注入用户原始输入作为任务对照组，防止模型在多步执行过程中偏航（如把“去 X 仓库创建 issue”误解为“创建 X 仓库”）。
• 14 层保护机制：元素恢复、Not-found 重试对话流、导航刷新、空转检测、重复批次防自转、协议修复、轮次稳定等待、快照指纹变化检测、快照变化摘要（Snapshot Diff）、无效点击拦截与循环检测、附近可点击元素推荐、原始目标锚定、断言验证（三阶段快照 + 死循环防护）、停机原因可观测（stopReason） —— 目标是稳定收敛，而不是偶然成功。
• Playwright 级别交互语义：完整 pointer/mouse 事件链、4 种 scrollIntoView 策略轮换、actionability 五重检查（可见/稳定/可用/可编辑/遮挡）、智能重定向 retarget、隐藏控件代理点击（ElementPlus/AntD）、select_option value/label/index 三策略。
• 运行时事件信号追踪：通过 EventTarget.prototype 补丁全局追踪事件绑定，快照中输出 listeners="clk,inp,chg" 信号，帮助 AI 精准识别真实可交互元素，而非猜测。
• 效果验证机制（Effect Check）：每轮行动前自动检查上轮操作是否在当前快照中生效，未生效则尝试邻近元素，避免重复点击无效目标。
• AI 驱动的任务断言（Assertion）：执行 AI 主动调用 assert 触发独立断言 AI 判定任务完成。三阶段快照设计（初始/动作后/当前）覆盖创建、跳转、状态变更等全场景；断言死循环防护确保不会无限重试。
• 结构化可观测指标：每次 chat 输出 AgentLoopMetrics（轮次、成功率、恢复次数、快照体积、Token 消耗、停机原因 stopReason），可直接接入监控系统。
• core/web 分层架构：core 零 DOM 依赖，可在 Worker/Extension/Node 复用；web 封装浏览器能力。

对于企业前端系统（尤其是 DevOps / ERP），真正决定成败的不是"有没有 Agent"，而是是否能在真实路由中稳定收敛。AutoPilot 的价值在于它把落地拆成可持续演进的能力模型，而不是一次性大改造。

在工程实践中，建议围绕三条主线理解和建设：

• 路由主线（业务边界）：把每个关键路由看作独立能力域。列表页、详情页、弹窗流不是同一种执行上下文，AI 必须在当前路由下决策和执行。
• Prompt 主线（策略边界）：Prompt 不是文案，而是运行时策略。你可以按项目与路由自定义约束，定义允许动作、风险动作确认条件、输出协议和禁止区域。
• Tools 主线（动作边界）：内置工具负责通用交互，业务工具负责高价值动作封装。把高频复杂流程沉淀成稳定工具，是规模化 AI 赋能的关键。

为什么这种方式能在企业系统里成立：

• 它天然适配渐进式改造：先做高价值路由，再扩展到全站，不阻断原有业务。
• 它天然具备可观测性：每轮工具调用、恢复次数、快照体积、收敛轮次都能被记录和优化。
• 它天然支持协同：后端 Agent 负责全局流程编排，前端 AutoPilot 负责页面级"最后一公里"执行。

最终形态不是"在网页里放一个会聊天的助手"，而是"在前端运行时形成一套可配置、可执行、可演进的 AI Skill 网络"。

import { WebAgent } from "agentpage";

const agent = new WebAgent({
  token: "your-api-key",
  provider: "openai",       // openai | copilot | anthropic | deepseek | doubao | qwen
  model: "gpt-4o",
});

agent.registerTools();       // 注册内置 Web 工具

agent.callbacks = {
  onRound: (round) => console.log(`第 ${round + 1} 轮`),
  onToolCall: (name, input) => console.log("调用:", name, input),
  onToolResult: (name, result) => console.log("结果:", name, result.content),
  onText: (text) => console.log("回复:", text),
};

const result = await agent.chat("打开任务弹窗，填写标题和优先级，然后提交");
console.log(result.reply);
console.log(result.metrics);  // { roundCount, toolSuccessRate, inputTokens, ... }

const routeSkills: Record<string, { prompt: string; tools?: () => void }> = {
  "/tickets": {
    prompt: "You are on tickets page. Prioritize filtering and status updates.",
  },
  "/deploy": {
    prompt: "You are on deploy page. Confirm risky actions before release.",
    tools: () => agent.registerTool(createDeployTool()),
  },
};

function applyRouteSkill(path: string) {
  agent.clearCustomTools();
  agent.clearSystemPrompts();
  const skill = routeSkills[path];
  if (!skill) return;
  agent.setSystemPrompt(skill.prompt);
  skill.tools?.();
}

applyRouteSkill(location.pathname);

┌──────────────────────────────────────────────────────┐
│                    WebAgent (web)                      │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │ AI Client│  │  Agent Loop  │  │  Web Tools     │  │
│  │ (fetch)  │  │  (core 循环) │  │  (DOM/导航/等待)│  │
│  └──────────┘  └──────────────┘  └────────────────┘  │
└──────────────────────────────────────────────────────┘

AI 每轮不是"凭记忆猜页面"，而是基于最新 DOM 快照选择可执行动作：

输入：当前快照 S + 当前任务 R → 输出：可执行任务批次 T

快照包含：

• 元素标签与 ARIA role（[combobox]/[slider] 替代冗余 tag+role）
• hash 选择器（#a1b2c）— 仅交互元素携带，非交互元素作为上下文
• 运行态属性（checked/disabled/readonly/val/selected）
• 事件信号（listeners="clk,inp,chg"）— 基于运行时真实绑定
• 智能剪枝：布局容器折叠、collapsed-group 标记、视口裁剪、节点预算控制

用户任务被逐轮"吃掉"，不一次性硬做完：

总任务: A → B → C

Round 1: 执行 A → REMAINING: B → C
Round 2: 执行 B → REMAINING: C
Round 3: 执行 C → REMAINING: DONE

每轮消息携带：当前剩余任务 + 上轮已执行动作 + 效果检查提示 + 最新快照。

• Round 0 使用原始任务；Round 1+ 不再注入原始消息，避免"回头重做"
• 模型返回 REMAINING: <text> 表示还有剩余，REMAINING: DONE 表示完成
• REMAINING 缺失时自动启发式剔除已完成任务，或保持不推进
• "remaining 未完成 + 无工具调用" 触发协议修复回合

• 可同轮：同时填写多个已可见输入框（focus→fill→focus→fill）
• 不可同轮：点击"打开弹窗"后立即填写弹窗内容（应等下一轮新快照）
• click 始终是本轮最后一个动作，执行后强制断轮
• 轮次结束后自动执行"loading 隐藏 + DOM 静默"双重等待

每次停机时，metrics.stopReason 会输出精确的停机原因枚举值：

assert 是内置工具，AI 认为任务完成时主动调用 assert({}) 触发验证：

AI 执行动作 → 认为完成 → 调用 assert({})
    ↓
拍取动作后快照（捕获瞬态反馈）
    ↓
等待页面稳定 → 清除 hover → 刷新快照
    ↓
独立断言 AI（专用 Prompt，无 tools）基于三阶段快照判定
    ↓
全部通过 → stopReason: "assertion_passed"
部分失败 → 注入 Assertion Progress → 继续循环

断言 AI 同时接收三份快照，覆盖不同阶段的页面状态：

这个设计解决了真实 B 端场景中的关键问题：

• 创建类任务：Initial 快照显示 2 个实例，Current 显示 3 个 → 断言 AI 通过 before/after 对比判定创建成功
• 提交后跳转：点击“确认开通”后出现成功提示，然后自动跳转回列表页 → Post-Action 捕获到“实例已提交开通”，即使 Current 已是列表页也能判定通过
• 状态变更：Current 快照直接看到开关状态、勾选状态、评分等 UI 变化
• 无跳转场景：Post-Action 与 Current 相同时自动去重，不浪费 token

连续 2 轮执行 AI 仅调用 assert（无其他工具）且都失败时，自动停机 stopReason = "assertion_loop"，避免无限重试。

无自定义断言时，以用户原始消息作为整体断言依据。

const result = await agent.chat("关闭开关，满意度五星，标签选灰度", {
  assertionConfig: {
    taskAssertions: [
      { task: "关闭开关", description: "开关组件不应有 is-checked class" },
      { task: "满意度五星", description: "满意度 slider 的 5 个 star 均应有 is-active class" },
      { task: "标签选灰度", description: "灰度 checkbox 应有 checked 状态" },
    ],
  },
});

console.log(result.assertionResult);
// { allPassed: true, total: 3, passed: 3, failed: 0, details: [...] }

6 个内置工具通过 agent.registerTools() 一次注册。

Playwright 风格增强：

• Actionability 五重检查：可见性、帧稳定性（rAF 连续 3 帧）、可用性（disabled + aria-disabled 祖先链）、可编辑性、遮挡检测（elementFromPoint）
• 智能重定向（retarget）：非交互元素自动查找最近 button/link/label.control
• scrollIntoView 4 策略轮换：ifNeeded → end → center → start，解决 sticky 遮挡
• 隐藏控件代理点击：ElementPlus/AntD 的 switch/checkbox/radio 自动重定向到可见代理元素
• fill 分类型：date/color/range 走 value setter，text 类走 selectAll + 原生写入
• 完整事件链：pointermove→pointerdown→mousedown→focus→pointerup→mouseup→click

双通道检测：轮询（80ms）+ MutationObserver，确保快速响应又不遗漏。

get_url / get_title / get_selection / get_viewport / snapshot / query_all

page_info.snapshot 是框架内部动作；快照每轮自动刷新并注入给模型，模型无需主动调用。

执行页面上下文 JavaScript 表达式或语句块。兜底工具，适用于其他工具无法覆盖的场景。

AI 认为任务完成时主动调用 assert({})，框架发起独立 AI 判定（专用 Prompt、无 tools、不继承 system prompt），基于三阶段快照对比验证任务是否真正完成。

• 三阶段快照：初始快照（before）+ 动作后快照（捕获瞬态成功提示）+ 当前快照（最终状态）
• 默认行为：无自定义断言时，以用户原始消息作为整体断言依据
• 自定义断言：通过 ChatOptions.assertionConfig.taskAssertions 传入细粒度子任务断言
• 断言全通过：stopReason = "assertion_passed"，循环终止
• 部分失败：失败原因注入下一轮 ## Assertion Progress 区块，AI 聚焦修复后再次触发断言
• 死循环防护：连续 2 轮仅调 assert 且都失败时自动停机
• hover 清除：断言前自动派发 pointerleave/mouseleave 清除瞬态视觉状态，确保快照反映持久状态

// 方式 1：初始化单条
const agent = new WebAgent({
  systemPrompt: "Only operate deploy-related UI. Confirm before release.",
});

// 方式 2：key-value 多条
const agent = new WebAgent({
  systemPrompt: {
    safety: "Never delete data without confirmation.",
    deploy: "Confirm risky actions before triggering release.",
  },
});

// 方式 3：运行时维护
agent.setSystemPrompt("tickets", "Prioritize filtering and status updates.");
agent.removeSystemPrompt("tickets");
agent.keepOnlySystemPrompt("deploy");
agent.clearSystemPrompts();

已注册 Prompt 作为扩展段追加到内置系统提示词之后。内置 Prompt 包含：快照优先决策、REMAINING 协议、批量执行规则、Effect check、事件信号优先级、禁止 page_info 空转等核心约束。

import { Type } from "@sinclair/typebox";

agent.registerTool({
  name: "create_ticket",
  description: "Create a new ticket in the system",
  schema: Type.Object({
    title: Type.String({ description: "Ticket title" }),
    priority: Type.String({ enum: ["high", "medium", "low"] }),
  }),
  async execute(params) {
    await api.createTicket(params);
    return { content: `Ticket created: ${params.title}` };
  },
});

工具管理：registerTool() / removeTool() / hasTool() / getToolNames() / clearCustomTools() / getTools()

内置工具（dom/navigate/page_info/wait/evaluate/assert）受保护，不允许删除。

import { BaseAIClient } from "agentpage";

const agent = new WebAgent({
  client: new BaseAIClient({
    chatHandler: async ({ url, method, headers, body }) => {
      const res = await fetch("/api/ai-proxy", { method: "POST", body });
      return res;
    },
  }),
});

也可以实现 AIClient 接口直接传入：

type AIClient = {
  chat(params: {
    systemPrompt: string;
    messages: AIMessage[];
    tools?: ToolDefinition[];
  }): Promise<{ text?: string; toolCalls?: AIToolCall[]; usage?: { inputTokens: number; outputTokens: number } }>;
};

agent.callbacks = {
  onRound: (round) => console.log(`── Round ${round + 1} ──`),
  onText: (text) => ui.appendText(text),
  onToolCall: (name, input) => ui.showLoading(name),
  onToolResult: (name, result) => ui.showResult(name, result.content),
  onSnapshot: (snapshot) => console.log(`快照: ${snapshot.length} chars`),
  onMetrics: (metrics) => analytics.track("chat_complete", metrics),
};

chat(task) 触发
    │
    ├─ 创建 RefStore，生成首轮快照 S₀
    │
    └─ 进入 executeAgentLoop 循环
         │
         ├─ 1. Ensure Snapshot — 确保有最新快照
         ├─ 2. Build Messages — remaining + 上轮轨迹 + 效果检查 + 快照
         ├─ 3. Call AI — 拿到 text + toolCalls + REMAINING
         ├─ 4. Execute Tools — 逐个分发，应用保护机制
         ├─ 5. Reduce Remaining — 推进任务（协议优先，启发式回退）
         ├─ 6. Guard — 防空转/防自转/协议修复判定
         └─ 7. Refresh Snapshot → 下一轮
              │
              └─ 停机 → 返回 AgentLoopResult

src/
├── core/                          # 环境无关引擎
│   ├── index.ts                   # Core 入口
│   ├── types.ts                   # 共享类型
│   ├── system-prompt.ts           # 系统提示词构建
│   ├── tool-registry.ts           # 工具注册表
│   ├── tool-params.ts             # 参数辅助
│   ├── snapshot.ts                # 快照聚合出口（兼容）
│   ├── snapshot-engine.ts         # 兼容转发层（-> agent-loop/snapshot/engine）
│   ├── messaging.ts               # 消息桥接实现
│   ├── event-listener-tracker.ts  # 事件追踪实现
│   ├── agent-loop/                # Agent 循环
│   │   ├── index.ts               # 主流程编排
│   │   ├── messages.ts            # 紧凑消息构建
│   │   ├── snapshot.ts            # 兼容转发层（-> snapshot/lifecycle）
│   │   ├── snapshot/              # 快照子模块
│   │   │   ├── index.ts
│   │   │   ├── lifecycle.ts       # 快照读取/包裹/去重
│   │   │   └── engine.ts          # DOM 快照序列化引擎
│   │   ├── recovery.ts            # 兼容转发层（-> recovery/index）
│   │   ├── recovery/              # 恢复与拦截子模块
│   │   │   └── index.ts
│   │   ├── assertion/             # 断言子模块
│   │   │   ├── types.ts           # 断言类型定义
│   │   │   ├── prompt.ts          # 断言专用 Prompt
│   │   │   └── index.ts           # 断言引擎
│   │   ├── helpers.ts             # 纯函数工具
│   │   ├── constants.ts           # 默认常量
│   │   ├── types.ts               # 循环类型
│   │   └── LOOP_MECHANISM.md      # 机制权威说明
│   └── ai-client/                 # AI 客户端
│       ├── index.ts               # Provider 路由
│       ├── openai.ts              # OpenAI/Copilot
│       ├── anthropic.ts           # Anthropic
│       ├── deepseek.ts            # DeepSeek
│       ├── doubao.ts              # 豆包 (Ark)
│       ├── qwen.ts                # 通义千问
│       ├── custom.ts              # BaseAIClient 基类
│       ├── sse.ts                 # SSE 解析器
│       └── constants.ts           # 端点与校验
└── web/                           # 浏览器实现
    ├── index.ts                   # WebAgent 入口
    ├── ref-store.ts               # #hashID → Element 映射
  ├── event-listener-tracker.ts  # 兼容转发层（-> core）
  ├── messaging.ts               # 兼容转发层（-> core）
  ├── snapshot.ts                # 兼容转发层（-> core）
  ├── snapshot-engine.ts         # 兼容转发层（-> core）
    ├── ui/                        # 内置 UI 面板
    └── tools/                     # 工具实现
        ├── dom-tool.ts
        ├── navigate-tool.ts
        ├── page-info-tool.ts
        ├── wait-tool.ts
        └── evaluate-tool.ts

pnpm install       # 安装依赖
pnpm check         # 类型检查 + Lint
pnpm test          # 运行测试
pnpm demo          # 启动 Demo
pnpm build         # 构建

MIT