Page Agent

将 alibaba/page-agent 嵌入到您自己的 Web 应用程序中——这是一个纯 JavaScript 的页面内 GUI 代理，以单个 <script> 标签或 npm 包的形式提供，让您网站的用户能够通过自然语言驱动 UI（例如“点击登录，将用户名填写为 John”）。无需 Python，无需无头浏览器，也无需扩展程序。当用户是希望为其 SaaS / 管理面板 / B2B 工具添加 AI 助手、通过自然语言使传统 Web 应用更易于访问，或者针对本地 (Ollama) 或云端 (Qwen / OpenAI / OpenRouter) LLM 评估 page-agent 的 Web 开发人员时，请使用此技能。不适用于服务器端浏览器自动化——请将那些用户引导至 Hermes 内置的浏览器工具。

技能元数据


来源	可选 — 使用 `hermes skills install official/web-development/page-agent` 安装
路径	`optional-skills/web-development/page-agent`
版本	`1.0.0`
作者	Hermes Agent
许可证	MIT
标签	`web`, `javascript`, `agent`, `browser`, `gui`, `alibaba`, `embed`, `copilot`, `saas`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

page-agent

alibaba/page-agent (https://github.com/alibaba/page-agent, 17k+ stars, MIT) 是一个用 TypeScript 编写的页面内 GUI 代理。它驻留在网页内部，将 DOM 作为文本读取（不使用截图，不使用多模态 LLM），并针对当前页面执行自然语言指令，如“点击登录按钮，然后将用户名填写为 John”。纯客户端实现——宿主站点只需包含一个脚本并传递一个兼容 OpenAI 的 LLM 端点。

何时使用此技能

当用户想要执行以下操作时，加载此技能：

在其自己的 Web 应用中部署 AI 助手（SaaS、管理面板、B2B 工具、ERP、CRM）——“我仪表板上的用户应该能够输入‘为 Acme Corp 创建发票并通过电子邮件发送’，而不是点击五个屏幕”
在不重写前端的情况下现代化传统 Web 应用——page-agent 可直接叠加在现有 DOM 之上
通过自然语言增加无障碍性——语音/屏幕阅读器用户通过描述他们想要的内容来驱动 UI
针对本地 (Ollama) 或托管 (Qwen, OpenAI, OpenRouter) LLM 演示或评估 page-agent
构建交互式培训/产品演示——让 AI 在真实 UI 中实时引导用户完成“如何提交费用报告”

何时不使用此技能

用户希望 Hermes 本身驱动浏览器 → 使用 Hermes 内置的浏览器工具（Browserbase / Camofox）。page-agent 的方向与此相反。
用户希望 在不嵌入的情况下进行跨标签页自动化 → 使用 Playwright、browser-use 或 page-agent Chrome 扩展程序
用户需要 视觉定位/截图 → page-agent 仅支持文本 DOM；请改用多模态浏览器代理

先决条件

Node 22.13+ 或 24+，npm 10+（文档声称需要 11+，但 10.9 也能正常工作）
一个兼容 OpenAI 的 LLM 端点：Qwen (DashScope)、OpenAI、Ollama、OpenRouter，或任何支持 /v1/chat/completions 的服务
带有开发者工具的浏览器（用于调试）

路径 1 — 通过 CDN 进行 30 秒演示（无需安装）

查看其工作原理的最快方式。使用阿里巴巴的免费测试 LLM 代理——仅用于评估，受其条款约束。

添加到任何 HTML 页面（或作为书签小工具粘贴到开发者工具控制台中）：

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

会出现一个面板。输入指令。完成。

书签小工具形式（拖放到书签栏，在任何页面上点击）：

javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();

路径 2 — 将 npm 安装到您自己的 Web 应用中（生产用途）

在现有的 Web 项目（React / Vue / Svelte / 原生）中：

npm install page-agent

使用您自己的 LLM 端点进行连接——切勿将演示 CDN 提供给真实用户：

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: process.env.LLM_API_KEY,   // never hardcode
    language: 'en-US',
})

// Show the panel for end users:
agent.panel.show()

// Or drive it programmatically:
await agent.execute('Click submit button, then fill username as John')

提供商示例（任何兼容 OpenAI 的端点均可工作）：

提供商	`baseURL`	`model`
Qwen / DashScope	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen3.5-plus`
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini`
Ollama (本地)	`http://localhost:11434/v1`	`qwen3:14b`
OpenRouter	`https://openrouter.ai/api/v1`	`anthropic/claude-sonnet-4.6`

关键配置字段（传递给 new PageAgent({...})）：

model, baseURL, apiKey — LLM 连接
language — UI 语言（en-US, zh-CN 等）
存在允许列表和数据掩码钩子，用于限制代理可以操作的内容——完整选项列表请参阅 https://alibaba.github.io/page-agent/

安全性。 在实际部署中，不要将您的 apiKey 放在客户端代码中——通过您的后端代理 LLM 调用，并将 baseURL 指向您的代理。演示 CDN 的存在是因为阿里巴巴运行该代理以供评估。

路径 3 — 克隆源代码仓库（贡献或修改）

当用户想要修改 page-agent 本身、通过本地 IIFE 包针对任意站点进行测试，或开发浏览器扩展程序时，请使用此方法。

git clone https://github.com/alibaba/page-agent.git
cd page-agent
npm ci              # exact lockfile install (or `npm i` to allow updates)

在仓库根目录创建包含 LLM 端点的 .env 文件。示例：

LLM_MODEL_NAME=gpt-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Ollama 风格：

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=NA
LLM_MODEL_NAME=qwen3:14b

常用命令：

npm start           # docs/website dev server
npm run build       # build every package
npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
npm run dev:ext     # develop the browser extension (WXT + React)
npm run build:ext   # build the extension

在任何网站上测试，使用本地 IIFE bundle。添加此书签小工具（bookmarklet）：

javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();

然后：运行 npm run dev:demo，在任何页面上点击书签小工具，本地构建版本将会注入。保存时自动重新构建。

警告： 你的 .env 中的 LLM_API_KEY 在开发构建期间会被内联到 IIFE bundle 中。不要分享该 bundle。不要提交它。不要将 URL 粘贴到 Slack 中。（已验证：对公共开发 bundle 进行 grep 搜索会返回 .env 中的字面值。）

仓库布局（路径 3）

带有 npm workspaces 的 monorepo。关键包：

包	路径	用途
`page-agent`	`packages/page-agent/`	主入口，包含 UI 面板
`@page-agent/core`	`packages/core/`	核心代理逻辑，无 UI
`@page-agent/mcp`	`packages/mcp/`	MCP 服务器（beta）
—	`packages/llms/`	LLM 客户端
—	`packages/page-controller/`	DOM 操作 + 视觉反馈
—	`packages/ui/`	面板 + i18n
—	`packages/extension/`	Chrome/Firefox 扩展
—	`packages/website/`	文档 + 落地页网站

验证是否正常工作

执行路径 1 或路径 2 后：

在浏览器中打开页面，并打开开发者工具
你应该能看到一个浮动面板。如果没有，请检查控制台是否有错误（最常见的是：LLM 端点的 CORS 问题、错误的 baseURL 或无效的 API 密钥）
输入一条与页面上可见内容匹配的简单指令（例如“点击登录链接”）
观察网络（Network）标签页 —— 你应该能看到向你的 baseURL 发出的请求

执行路径 3 后：

npm run dev:demo 打印 Accepting connections at http://localhost:5174
curl -I http://localhost:5174/page-agent.demo.js 返回 HTTP/1.1 200 OK 且 Content-Type: application/javascript
在任何网站上点击书签小工具；面板出现

常见陷阱

生产环境中使用演示 CDN —— 不要这样做。它受到速率限制，使用阿里巴巴的免费代理，且其服务条款禁止生产环境使用。
API 密钥暴露 —— 任何传递给 new PageAgent({apiKey: ...}) 的密钥都会打包到你的 JS bundle 中。对于真实部署，务必通过你自己的后端进行代理。
非 OpenAI 兼容的端点 会静默失败或产生晦涩的错误。如果你的提供商需要原生的 Anthropic/Gemini 格式，请在前面使用 OpenAI 兼容代理（LiteLLM、OpenRouter）。
CSP 阻止 —— 具有严格内容安全策略（Content-Security-Policy）的网站可能会拒绝加载 CDN 脚本或禁止内联 eval。在这种情况下，请从你的源站自托管。
编辑 .env 后重启开发服务器 —— 在路径 3 中，Vite 仅在启动时读取环境变量。
Node 版本 —— 仓库声明需要 ^22.13.0 || >=24。Node 20 会因为引擎错误导致 npm ci 失败。
npm 10 与 11 —— 文档称需要 npm 11+；但 npm 10.9 实际上也能正常工作。

参考

仓库：https://github.com/alibaba/page-agent
文档：https://alibaba.github.io/page-agent/

技能元数据​

参考：完整 SKILL.md​

page-agent

何时使用此技能​

何时不使用此技能​

先决条件​

路径 1 — 通过 CDN 进行 30 秒演示（无需安装）​

路径 2 — 将 npm 安装到您自己的 Web 应用中（生产用途）​

路径 3 — 克隆源代码仓库（贡献或修改）​

仓库布局（路径 3）​

验证是否正常工作​

常见陷阱​

参考​