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）​

驗證是否正常工作​

常見陷阱​

參考​