每一个做过 B2B 产品的人，大概都遇到过同一类工单：用户说"我不知道怎么操作"，客服回答"请点击左侧菜单第三项，展开后找到'配置'，再点右上角的保存按钮……"。这条消息发出去，用户可能已经关掉了页面。
更深的问题不是文档写得不够好，也不是用户不够聪明。而是我们设计软件的基本假设从来没有被质疑过——界面是给人看的，操作是由人来做的。复杂的系统只能靠"教会人"来解决，而不能靠"替人做"来解决。于是界面越堆越厚，引导越写越长，支持成本越来越高，但用户完成一件事所需要的点击次数，从来没有真正少过。
AI 助手的出现让人们燃起了希望，但大多数产品里的 AI 停留在"说"的层面——它能告诉你下一步该做什么，却不能替你动手。本质上，它还是一个更聪明的文档。
想象一下，你第一次使用一套陌生的财务报销系统。旁边坐着一个熟悉这套系统多年的同事，她没有对你说"你先点这里，再点那里"，而是直接把手伸过来，用你的账号，一步步把这张单子填完提交了。你看着整个过程，知道下次该怎么做，这次的事也当场解决了。
这个类比精准对应了 page-agent 的核心直觉：不是在你旁边读说明书给你听的助手，而是直接上手操作的那个人。区别不在于智商，在于是否真的能触碰到界面。
实现"能触碰界面"这件事，在技术上有两条路。一条是从外部控制浏览器，像 browser-use 或 Playwright 那样，通过截图或 CDP 协议远程操作整个浏览器——这是自动化测试和爬虫的思路，强大但重，且天然是开发者工具，不适合嵌进一个给终端用户用的产品。
page-agent 选了另一条路：把 Agent 直接嵌入网页本身。它以一段 JavaScript 的形式活在页面内部，通过高强度脱水的 DOM 分析理解当前页面结构——不依赖视觉识别，不截图，纯文本解析，速度快且精准。它的边界也是刻意设定的：只工作在当前页面，不跨 Tab，不碰浏览器全局。这不是能力不足，而是一个关于"嵌入式增强"而非"外部自动化"的设计判断。
接入：从一行脚本开始
想最快体验，直接在页面里加一行 CDN 引用，page-agent 会使用内置的免费测试 LLM 自动初始化：
<!-- 国内镜像 --> <script src="https://registry.npmmirror.com/page-agent/1.10.0/files/dist/iife/page-agent.demo.js" crossorigin="true"></script>
正式项目则推荐 NPM 安装，以获得完整的类型支持和版本控制：
npm install page-agent
配置 Page-Agent
接入之后，真正决定 Agent 能力边界的是初始化配置。Page-Agent 是最常用的完整类，它内置了一个 UI 面板，会在页面中自动显示任务进度、Agent 的思考链路和每步操作结果。核心配置只需要三个字段：LLM 的接口地址、API Key，以及使用的模型名称：
import { PageAgent } from 'page-agent'
const agent = new PageAgent({
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1', // 兼容 OpenAI 格式的任意端点
apiKey: 'YOUR_API_KEY',
model: 'qwen3.5-plus',
language: 'zh-CN'
})
这里值得注意的一个设计选择是：LLM 端点完全由开发者自己控制，page-agent 不托管任何模型调用，数据不经过第三方转发。对有数据合规要求的 B2B 场景，这一点尤为关键。
两种使用方式
配置完成后，Agent 有两种调用姿势，分别对应不同的产品集成场景。第一种是程序化调用，适合在特定业务流程节点触发固定动作：
const result = await agent.execute('点击提交按钮，然后将用户名填写为 John')
console.log(result.success) // true or false
console.log(result.history) // 完整执行步骤记录
第二种是唤起面板，让用户自己用自然语言输入指令，适合作为产品内置的 AI 助手入口：
agent.panel.show() // 在页面中显示交互面板，等待用户输入
如果你需要无界面的 Headless 模式——比如在 Node 环境或自定义 UI 场景下——可以改用 PageAgentCore，它去掉了内置 UI 层，只保留核心的 DOM 解析和动作执行能力，适合需要完全掌控渲染逻辑的团队。
我们已经习惯了"界面是给人操作的"这个前提太久，以至于忘了它只是一个设计选择，而不是一条物理定律。