\{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

Đại lý trang

Nhúng alibaba/page-agent vào ứng dụng web của riêng bạn — một tác nhân GUI trong trang thuần JavaScript được vận chuyển dưới dạng một thẻ <script> hoặc gói npm duy nhất và cho phép người dùng cuối trang web của bạn điều khiển giao diện người dùng bằng ngôn ngữ tự nhiên ("nhấp đăng nhập, điền tên người dùng là John"). Không có Python, không có trình duyệt không đầu, không cần tiện ích mở rộng. Sử dụng kỹ năng này khi người dùng là nhà phát triển web muốn thêm AI copilot vào công cụ SaaS / bảng quản trị / B2B của họ, làm cho ứng dụng web cũ có thể truy cập được thông qua ngôn ngữ tự nhiên hoặc đánh giá tác nhân trang so với LLM cục bộ (OLlama) hoặc đám mây (Qwen / OpenAI / OpenRouter). KHÔNG dành cho tự động hóa trình duyệt phía máy chủ - thay vào đó hãy hướng những người dùng đó đến công cụ trình duyệt tích hợp của Hermes.

Siêu dữ liệu kỹ năng


Nguồn	Tùy chọn — cài đặt với
`Hermes skills install official/web-development/page-agent
`
Đường dẫn

optional-skills/web-development/page-agent ` | | Phiên bản |

web

, `JavaScript

, `agent

, `browser

, `gui

, `alibaba

, `embed

, `copilot

, saas |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

đại lý trang`alibaba/page-agent (https://GitHub.com/alibaba/page-agent, 17k+ stars, MIT) là một tác nhân GUI trong trang được viết bằng TypeScript. Nó tồn tại bên trong một trang web, đọc DOM dưới dạng văn bản (không có ảnh chụp màn hình, không có LLM đa phương thức) và thực thi các hướng dẫn bằng ngôn ngữ tự nhiên như "nhấp vào nút đăng nhập, sau đó điền tên người dùng là John" đối với trang hiện tại. Phía máy khách thuần túy - trang chủ chỉ bao gồm một tập lệnh và chuyển điểm cuối LLM tương thích với OpenAI.

Khi nào nên sử dụng kỹ năng này

Tải kỹ năng này khi người dùng muốn:

Gửi một AI đồng hành bên trong ứng dụng web của riêng họ (SaaS, bảng quản trị, công cụ B2B, ERP, CRM) — "người dùng trên trang tổng quan của tôi có thể nhập 'tạo hóa đơn cho Acme Corp và gửi email' thay vì nhấp qua năm màn hình"
Hiện đại hóa một ứng dụng web cũ mà không cần viết lại giao diện người dùng — tác nhân trang được thả lên trên DOM hiện có
Thêm khả năng truy cập thông qua ngôn ngữ tự nhiên — người dùng giọng nói/trình đọc màn hình điều khiển giao diện người dùng bằng cách mô tả những gì họ muốn
Trình diễn hoặc đánh giá tác nhân trang so với LLM cục bộ (OLlama) hoặc được lưu trữ (Qwen, OpenAI, OpenRouter)
Xây dựng chương trình đào tạo tương tác/bản giới thiệu sản phẩm — để AI hướng dẫn người dùng về "cách gửi báo cáo chi phí" trực tiếp trong giao diện người dùng thực

Khi nào KHÔNG nên sử dụng kỹ năng này

Người dùng muốn Hermes tự điều khiển trình duyệt → sử dụng công cụ trình duyệt tích hợp của Hermes (Browserbase / Camofox). tác nhân trang là hướng ngược lại.
Người dùng muốn tự động hóa nhiều tab mà không cần nhúng → sử dụng Playwright, sử dụng trình duyệt hoặc tiện ích mở rộng Chrome dành cho tác nhân trang
Người dùng cần nền tảng trực quan / ảnh chụp màn hình → tác nhân trang chỉ là văn bản-DOM; thay vào đó hãy sử dụng tác nhân trình duyệt đa phương thức

Điều kiện tiên quyết

Nút 22.13+ hoặc 24+, npm 10+ (tài liệu yêu cầu 11+ nhưng 10.9 hoạt động tốt)
Điểm cuối LLM tương thích với OpenAI: Qwen (DashScope), OpenAI, OLlama, OpenRouter hoặc bất kỳ thứ gì nói

/v1/chat/completions

Trình duyệt có devtools (để gỡ lỗi)

Đường dẫn 1 - Bản demo 30 giây qua CDN (không cần cài đặt)

Cách nhanh nhất để thấy nó hoạt động. Sử dụng proxy LLM thử nghiệm miễn phí của alibaba — chỉ để đánh giá, tuân theo các điều khoản của họ.

Thêm vào bất kỳ trang HTML nào (hoặc dán vào bảng điều khiển devtools dưới dạng bookmarklet):

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

`
``Một bảng điều khiển xuất hiện. Nhập một hướng dẫn. Xong.

Dạng Bookmarklet (thả vào thanh bookmark, CLIck vào trang bất kỳ):

`JavaScript
JavaScript:(function()\\\&#123;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);&#125;)();

`

## Đường dẫn 2 - cài đặt npm vào ứng dụng web của riêng bạn (sử dụng sản xuất)

Bên trong một dự án web hiện có (React/Vue/Svelte/plain):

`bash
npm install page-agent

`
``Kết nối nó với điểm cuối LLM của riêng bạn — **không bao giờ gửi CDN demo cho người dùng thực**:

`JavaScript
 import \\&#123; PageAgent &#125; from 'page-agent'`const agent = new PageAgent(\&#123;
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    APIKey: process.env.LLM_API_KEY,   // never hardcode
    language: 'en-US',
&#125;)`// Show the panel for end users:
agent.panel.show()`// Or drive it programmatically:
await agent.execute('CLIck submit button, then fill username as John')

`
``Ví dụ về nhà cung cấp (mọi điểm cuối tương thích với OpenAI đều hoạt động):

| Nhà cung cấp |

baseURL
` | 
`model
` |
|----------|-------------|----------|
| Qwen / DashScope |

https://dashscope.aliyuncs.com/compatible-mode/v1
` | 
`qwen3.5-plus
` |
| OpenAI |

https://API.OpenAI.com/v1
` | 
`GPT-4o-mini
` |
| OLlama (địa phương) |

http://localhost:11434/v1
` | 
`qwen3:14b
` |
| OpenRouter |

https://OpenRouter.ai/API/v1
` | 
`Anthropic/Claude-sonnet-4.6
` |**Các trường cấu hình chính** (được chuyển tới 
`new PageAgent(\\\&#123;...&#125;)

):
- 
`model

, 
`baseURL

, 
`APIKey
` — Kết nối LLM

- 
`language
` — Ngôn ngữ giao diện người dùng (
`en-US

, 
`zh-CN

, v.v.)
- Danh sách cho phép và móc che dữ liệu tồn tại để khóa những gì tác nhân có thể chạm vào — xem https://alibaba.GitHub.io/page-agent/ để biết danh sách tùy chọn đầy đủ`**Bảo mật.** Đừng đặt 
`APIKey
` của bạn trong mã phía máy khách để triển khai thực sự — các cuộc gọi LLM proxy thông qua chương trình phụ trợ của bạn và trỏ 
`baseURL
` vào proxy của bạn. CDN demo tồn tại vì alibaba chạy proxy đó để đánh giá.

## Đường dẫn 3 - sao chép kho lưu trữ nguồn (đóng góp hoặc hack vào nó)

Sử dụng tính năng này khi người dùng muốn tự sửa đổi tác nhân trang, kiểm tra nó trên các trang web tùy ý thông qua gói IIFE cục bộ hoặc phát triển tiện ích mở rộng trình duyệt.

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

`
``Tạo 

.env
` trong thư mục gốc repo bằng điểm cuối LLM. Ví dụ:

`
LLM_MODEL_NAME=GPT-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://API.OpenAI.com/v1

`
``Hương vị Olama:

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

`
``Các lệnh phổ biến:

`bash
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

`
``**Kiểm tra trên bất kỳ trang web nào** bằng gói IIFE cục bộ. Thêm bookmarklet này:

`JavaScript
JavaScript:(function()\\\&#123;var s=document.createElement('script');s.src=
`http://localhost:5174/page-agent.demo.js?t=$\\\&#123;Math.random()&#125;

;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);&#125;)();

`
``Sau đó: 
`npm run dev:demo

, nhấp vào bookmarklet trên bất kỳ trang nào và bản dựng cục bộ sẽ được đưa vào. Tự động xây dựng lại khi lưu.

**Cảnh báo:** 

.env
` 
`LLM_API_KEY
` của bạn được đưa vào gói IIFE trong quá trình xây dựng nhà phát triển. Không chia sẻ gói. Đừng phạm phải điều đó. Đừng dán URL vào Slack. (Đã xác minh: việc lấy gói nhà phát triển công khai trả về các giá trị bằng chữ từ 

.env

.)

## Bố cục Repo (Đường dẫn 3)

Monorepo với không gian làm việc npm. Các gói chính:

| Trọn gói | Đường dẫn | Mục đích |
|----------|------|----------|
| 
`page-agent
` | 
`packages/page-agent/
` | Mục chính có bảng điều khiển UI |
| 

@page-agent/core
` | 
`packages/core/
` | Logic tác nhân cốt lõi, không có giao diện người dùng |
| 

@page-agent/MCP
` | 
`packages/MCP/
` | Máy chủ MCP (beta) |
| — |

packages/LLMs/
` | Khách hàng LLM |
| — |

packages/page-controller/
` | Hoạt động DOM + phản hồi trực quan |
| — |

packages/ui/
` | Bảng điều khiển + i18n |
| — |

packages/extension/
` | Tiện ích mở rộng Chrome/Firefox |
| — |

packages/website/
` | Tài liệu + trang đích |

## Xác minh nó hoạt động

Sau Đường dẫn 1 hoặc Đường dẫn 2:

1. Mở trang trong trình duyệt có mở devtools
2. Bạn sẽ thấy một bảng điều khiển nổi. Nếu không, hãy kiểm tra bảng điều khiển để tìm lỗi (phổ biến nhất: CORS trên điểm cuối LLM, sai 
`baseURL
` hoặc khóa API không đúng)
3. Nhập một hướng dẫn đơn giản khớp với nội dung hiển thị trên trang ("nhấp vào liên kết Đăng nhập")
4. Xem tab Mạng - bạn sẽ thấy yêu cầu gửi tới 
`baseURL
` của mình

Sau Đường dẫn 3:
1. 
`npm run dev:demo
` in 
`Accepting connections at http://localhost:5174

2. 
`curl -I http://localhost:5174/page-agent.demo.js
` trả về 
`HTTP/1.1 200 OK
` với 
`Content-Type: application/JavaScript

3. Nhấp vào bookmarklet trên bất kỳ trang web nào; bảng điều khiển xuất hiện

## Cạm bẫy
- **CDN demo đang được sản xuất** — không. Nó bị giới hạn tỷ lệ, sử dụng proxy miễn phí của alibaba và các điều khoản của họ cấm sử dụng sản xuất.
- **Hiển thị khóa API** — bất kỳ khóa nào được chuyển tới 
`new PageAgent(\\\&#123;APIKey: ...&#125;)
` sẽ được gửi trong gói JS của bạn. Luôn ủy quyền thông qua chương trình phụ trợ của riêng bạn để triển khai thực sự.
- **Các điểm cuối không tương thích với OpenAI** bị lỗi âm thầm hoặc có lỗi khó hiểu. Nếu nhà cung cấp của bạn cần định dạng Anthropic/Gemini gốc, hãy sử dụng proxy tương thích OpenAI (LiteLLM, OpenRouter) ở phía trước.
- **Chặn CSP** — các trang web có Chính sách bảo mật nội dung nghiêm ngặt có thể từ chối tải tập lệnh CDN hoặc không cho phép đánh giá nội tuyến. Trong trường hợp đó, hãy tự lưu trữ từ nguồn gốc của bạn.
- **Khởi động lại máy chủ dev** sau khi chỉnh sửa 

.env
` trong Đường dẫn 3 — Vite chỉ đọc env khi khởi động.
- **Phiên bản nút** — repo khai báo 

^22.13.0 || >=24

. Nút 20 sẽ bị lỗi 
`npm ci
` do lỗi động cơ.
- **npm 10 vs 11** — tài liệu nói npm 11+; npm 10.9 thực sự hoạt động tốt.

## Tham khảo
- Repo: https://GitHub.com/alibaba/page-agent
- Tài liệu: https://alibaba.GitHub.io/page-agent/
- Giấy phép: MIT (được xây dựng dựa trên nội bộ xử lý DOM của trình duyệt, Bản quyền 2024 Gregor Zunic)

Siêu dữ liệu kỹ năng​

Tham khảo: đầy đủ SKILL.md​

Khi nào nên sử dụng kỹ năng này​

Khi nào KHÔNG nên sử dụng kỹ năng này​

Điều kiện tiên quyết​

Đường dẫn 1 - Bản demo 30 giây qua CDN (không cần cài đặt)​