用 Page Agent 给网页内置一个 AI 助手：一段页内脚本、纯文本 DOM、自带模型实操

<!-- 加到任意网页的 body 尾部（demo 模型，仅供技术评估） -->
<script
    src="https://cdn.jsdelivr.net/npm/[email protected]/dist/iife/page-agent.demo.js"
    crossorigin="anonymous"
></script>
<!-- 国内访问 jsDelivr 慢可换 npmmirror 镜像:
     https://registry.npmmirror.com/page-agent/1.12.4/files/dist/iife/page-agent.demo.js -->

刷新页面，右下角出现 Agent 悬浮聊天框，直接用自然语言下指令（比如「把这个输入框填上某某」），看它逐步操作页面元素。这一步零安装零配置，用来快速判断「文本化 DOM」方案对你的页面复杂度够不够用：表单、列表、常规后台页面效果通常很好；重度 Canvas/虚拟滚动的自定义渲染要降低预期。确认方案可行后，马上进 Step 2 换成自己的模型——别让业务数据流经 demo 端点。

npm create vite@latest my-page-agent-demo -- --template vanilla
cd my-page-agent-demo
npm install page-agent
npm run dev

// main.js
import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',   // 模型名以你的服务商文档为准
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: import.meta.env.VITE_LLM_API_KEY,  // 从环境变量读，别硬编码
    language: 'zh-CN',
})

await agent.initialize()
window.agent = agent   // 挂到 window，方便浏览器控制台调试

初始化参数就是一套标准的 OpenAI 兼容配置：model、baseURL、apiKey 加界面语言。官方支持主流模型供应商与本地部署模型（本地模型同样走 OpenAI 兼容端点），所以已有大模型接入的团队基本零迁移成本。控制台里 window.agent.execute('...') 随手下指令验证效果，预期效果：指令下达后能看到 Agent 高亮当前操作的元素并逐步执行，全程没有一次截图调用。

// 场景一：智能填表（ERP/CRM/后台系统的典型痛点）
await agent.execute('收货人填张三，电话 13800000000，地址选「上海市浦东新区」，备注写「工作日送达」')

// 场景二：跨字段联动操作
await agent.execute('在「所属行业」下拉框选中「智能制造」，把不相关的高级选项全部收起')

// 场景三：让 Agent 先读页面再干活
await agent.execute('看一下这个表格里状态为「异常」的行，把单号汇总到搜索框里')

拿一个真实业务页面验收，指令遵循官方给的场景设计：「20 次点击变一句话」。观察三件事：准确性——字段定位是否精准（这是文本 DOM 方案的核心优势，元素名和占位符都是现成语义）；边界——遇到下拉框、日期选择器这类非原生控件时表现如何；反馈——操作过程与结果是否有清晰的 UI 呈现。哪类控件老出错，就把对应控件的 label/aria 属性补规范，Page Agent 读的是语义化 DOM，页面可访问性做得越好，它就越准——这也是它被列为无障碍场景用途的原因。

const agent = new PageAgent({
    // ...模型配置同 Step 2
    showUI: false,   // 不渲染悬浮聊天框，纯编程控制
})

// 绑到你自己的产品按钮/快捷指令上
document.querySelector('#btn-autofill')
    .addEventListener('click', () =>
        agent.execute('用已登录用户的档案信息填完整个报名表单'))

// 也可以按页面状态动态组装指令
const mode = new URLSearchParams(location.search).get('mode')
if (mode === 'renew') {
    await agent.execute('进入续费流程，保留原套餐档位，只改支付方式')   // 示例
}

做产品嵌入时，悬浮聊天框通常不是你想要的形态——showUI: false 把 Agent 降级成纯能力层，入口、触发时机、指令内容全部由你的产品代码掌控：可以是一个「帮我填表」按钮、一条命令面板动作，也可以是特定页面状态下的自动辅助。这个模式下指令模板建议放进配置中心统一管理：改文案、改流程不用发版，还能按租户/角色下发自不同的辅助能力。

// 通道一（可选安装）：官方 Chrome 扩展
// 让 Agent 的触达范围从「当前页」扩展到「多标签页任务」

// 通道二（Beta）：官方 MCP Server
// 把浏览器里的 Page Agent 暴露给外部 Agent 客户端控制
// 适合让 Claude Code / OpenClaw 这类桌面 Agent 远程指挥浏览器干活

单页内嵌是 Page Agent 的主场，但官方准备了两条可选通道应对更大的场景：Chrome 扩展面向「任务横跨多个标签页」的用户侧场景（比如从列表页逐个打开详情处理）；MCP Server（Beta）面向开发者侧集成——把浏览器中的 Page Agent 作为 MCP 工具暴露出去，你的桌面 Agent 就能指挥它操作浏览器。两条通道都是可选项，纯页内方案不装它们也完整可用；生产环境启用 Beta 通道前先在小范围验证稳定性。

// 1) 密钥进后端：前端只请求你自己的代理端点
const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: '/api/llm-proxy',   // 你的后端代理：持有真实 Key 调服务商
    language: 'zh-CN',
})

// 2) 范围约束：指令白名单 + 数据脱敏在代理层做
//    代理层校验 system 约束、限流、审计后再转发给模型

// 3) 失败兜底：execute 返回后校验页面状态，失败引导人工
const ok = await agent.execute('把审批意见填为「同意」并提交')
if (!ok) showFallbackToast('自动操作未完成，请手动检查表单')

生产化的底线清单：密钥不落地前端——模型请求走自家后端代理，代理层顺便做限流、审计与数据脱敏（页面上的敏感字段是否要进入模型上下文，这个决策必须在代理层可配置）；能力范围有闸门——用指令模板约束 Agent 只做产品设计的辅助动作，删除、支付等高风险操作保持用户手动确认；失败有出口——每次 execute 后校验预期页面状态，失败时给用户明确提示与人工路径。做完这三件，这个「住在网页里的 Agent」才能从 demo 变成功能。