在实际 Web 开发中，为产品快速集成一个智能的、能理解用户自然语言指令并操作页面元素的 AI 助手，通常意味着复杂的后端服务、浏览器插件开发或对无头浏览器的深度集成。这些方案不仅技术栈复杂、部署成本高，还可能涉及用户隐私和数据安全等棘手问题。阿里开源的 Page Agent 项目提供了一种截然不同的思路：一个纯前端、基于 JavaScript 的页面内 GUI 智能体。它允许开发者仅通过几行代码，就将一个能“听懂人话”并操作 DOM 的 AI 助手嵌入到任何网页中，无需后端重写、无需浏览器扩展，也无需处理复杂的多模态模型。对于希望为 SaaS 产品、内部管理系统或复杂表单页面快速添加 AI 交互能力的开发者而言，这无疑是一个极具吸引力的解决方案。
本文将带你从零开始，深入理解 Page Agent 的核心机制，并完成一个可运行的集成案例。你将学习到它的工作原理、如何选择合适的模型、如何进行本地化部署以规避网络问题，以及在实际项目中集成时需要注意的关键细节和常见陷阱。无论你是前端工程师、全栈开发者，还是对 AI 与 Web 交互结合感兴趣的技术爱好者，都能通过本文获得一个清晰、可复现的实践路径。
1. 理解 Page Agent：它如何让网页“听懂”并“执行”指令
在深入代码之前，我们必须先厘清 Page Agent 的核心工作模式。它不是一个远程控制的机器人，也不是一个需要截屏识图的视觉模型。它的核心能力建立在两个关键设计之上：文本化的 DOM 理解与指令分解执行。
1.1 文本化 DOM 操作：告别截图与复杂权限
传统基于视觉或多模态模型的网页自动化方案，通常需要获取页面截图，由 AI 模型识别图中的按钮、输入框等元素，再模拟点击坐标。这种方式不仅计算开销大、响应慢，而且往往需要申请额外的浏览器权限（如activeTab、<all_urls>），在隐私至上的今天，这极大地增加了集成的复杂度和用户接受门槛。
Page Agent 采用了更“朴素”但更高效的方式：直接读取并理解页面的 DOM 树文本信息。它通过 JavaScript 访问当前页面的document对象，获取元素的标签名、ID、类名、aria-label、文本内容、placeholder等属性，并将这些信息结构化成一段描述性的文本。例如，一个登录按钮可能被描述为“<button> with id ‘submit-btn’ and text ‘登录’ located inside a <form>”。
然后，这个文本化的“页面状态描述”会与用户的自然语言指令（如“点击登录按钮”）一起，发送给后端的大语言模型（LLM）。LLM 的任务是理解指令，并基于对页面结构的文本描述，规划出一系列具体的、可执行的原子操作步骤，例如[‘click’, ‘#submit-btn’]。Page Agent 再接收并执行这些原子操作。整个过程完全在页面上下文内完成，无需截图，也无需超出页面本身范围的任何特殊权限。
1.2 架构与数据流：一次完整的交互是如何发生的
理解数据流是排查问题和进行深度定制的基础。一次典型的 Page Agent 交互遵循以下步骤：
- 用户输入：用户在网页上的某个输入框（由 Page Agent 提供或集成）中输入自然语言指令，如“在搜索框里输入‘开源项目’并搜索”。
- 页面状态捕获：Page Agent 启动，它不会捕获整个页面，而是根据策略（可能是聚焦于视口区域或特定容器）收集相关 DOM 元素的文本化信息。
- 指令规划：将“页面状态描述”和“用户指令”组合成一个精心设计的提示词（Prompt），发送给配置好的 LLM API（如通义千问、GPT 等）。
- 动作解析：LLM 返回一个结构化的动作序列，这个序列是 Page Agent 能理解的内部 DSL（领域特定语言）。例如：
[ {"action": "type", "selector": "#search-input", "text": "开源项目"}, {"action": "click", "selector": "#search-btn"} ] - 动作执行：Page Agent 的运行时引擎解析这个动作序列，通过
document.querySelector找到对应元素，并执行element.click()或element.value = ‘...’等原生 DOM 操作。 - 结果反馈与迭代：执行后，Page Agent 可能会再次捕获页面状态，检查动作是否成功（例如，检查输入框的值是否已改变），并根据需要决定是否继续执行下一个动作或向用户反馈结果。
这个流程的关键在于，LLM 并不直接操作浏览器，它只负责“思考”和“规划”。实际的 DOM 操作由 Page Agent 的轻量级 JavaScript 引擎安全地执行在沙盒化的页面环境中。这种职责分离使得系统更安全、更可控，也降低了对 LLM 能力的要求——它不需要理解像素坐标，只需要理解文本描述的语义。
1.3 核心概念：模型、技能与 MCP 服务器
要有效使用 Page Agent，你需要熟悉它的几个核心概念：
- 模型（Model）：Page Agent 本身不提供 AI 能力，它是一个“驱动程序”，需要接入一个后端 LLM 来提供“大脑”。你可以使用阿里云的通义千问、OpenAI 的 GPT 系列，或任何兼容 OpenAI API 格式的模型服务。模型的选择直接决定了智能体的理解能力和执行准确性。
- 技能（Skills）：这是 Page Agent 的可扩展性所在。除了基础的点击、输入、滚动等操作，你还可以定义自定义技能。例如，一个“获取表格数据”的技能，可以教会智能体如何识别页面上的表格元素并将其数据提取为 JSON 格式。技能以插件形式存在，大大增强了智能体处理复杂任务的能力。
- MCP 服务器（Model Context Protocol Server - Beta）：这是一个更高级的特性。MCP 允许 Page Agent 被外部的 AI 智能体客户端（例如运行在服务器上的另一个 AI 进程）所控制。这意味着你可以构建一个中心化的 AI 系统，来远程指挥多个浏览器页面中的 Page Agent 协同工作，实现跨页面的复杂自动化流程。
2. 环境准备与依赖配置：从零搭建可运行环境
在开始集成之前，我们需要准备好开发环境和必要的依赖。本节将详细说明从创建一个干净项目到引入 Page Agent 所需的每一步。
2.1 项目初始化与基础环境
首先，创建一个新的项目目录并初始化一个前端项目。这里我们使用 Vite 作为构建工具，因为它能提供快速的开发体验和清晰的模块化支持。
# 创建一个新的项目目录 mkdir my-page-agent-demo cd my-page-agent-demo # 使用 npm 初始化项目，并安装 Vite 和基础依赖 npm create vite@latest . -- --template vanilla # 选择 Vanilla JavaScript 模板即可，无需复杂框架 # 安装 Page Agent 核心库 npm install page-agent如果你的网络环境访问 npm 官方仓库较慢，可以配置阿里云镜像源来加速依赖安装：
# 临时使用阿里云镜像安装 npm install page-agent --registry=https://registry.npmmirror.com # 或配置为默认镜像源 npm config set registry https://registry.npmmirror.com项目初始化后，你的package.json应该包含类似以下内容：
{ "name": "my-page-agent-demo", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview" }, "devDependencies": { "vite": "^5.0.0" }, "dependencies": { "page-agent": "^1.10.0" } }2.2 获取并配置 LLM API 密钥
Page Agent 需要一个大语言模型作为“大脑”。你可以根据实际情况选择以下任一服务：
| 模型服务商 | 获取 API Key 地址 | 特点 | 适用场景 |
|---|---|---|---|
| 阿里云 DashScope | 阿里云控制台 - 灵积 | 国内访问稳定，与 Page Agent 同源，有免费额度。 | 国内项目，快速启动。 |
| OpenAI | OpenAI Platform | 模型能力强，但需要处理网络访问问题。 | 对模型能力要求高，且有稳定访问方式的项目。 |
| 其他兼容 OpenAI API 的服务(如 LocalAI, Ollama) | 对应服务文档 | 可本地部署，数据不出域，成本可控。 | 对数据隐私要求极高，或需要离线使用的内部系统。 |
以阿里云 DashScope 为例，获取 API Key 的步骤：
- 登录阿里云账号，进入 DashScope 控制台 。
- 在左侧菜单选择“API-KEY 管理”。
- 点击“创建新的 API-KEY”，并妥善保存生成的密钥。它通常以
sk-开头。
重要安全提示：API Key 是访问模型的凭证，具有消费权限。绝对不要将其直接硬编码在客户端 JavaScript 代码中并发布到线上。在开发测试阶段，我们可以暂时将其放在前端代码中，但生产环境必须通过你自己的后端服务进行中转，由后端来保管和调用 API Key。Page Agent 支持配置自定义的baseURL和请求头，这为你实现后端代理提供了可能。
2.3 创建基础 HTML 与 JavaScript 文件
我们将创建一个简单的待操作页面。在项目根目录下，找到或创建index.html和main.js文件。
index.html内容如下，它包含了一些常见的表单元素供 Page Agent 操作：
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Page Agent 集成演示</title> <style> body { font-family: sans-serif; padding: 2rem; max-width: 800px; margin: auto; } .container { border: 1px solid #ccc; padding: 2rem; border-radius: 8px; margin-top: 2rem; } input, button, textarea { margin: 0.5rem 0; padding: 0.5rem; display: block; width: 100%; box-sizing: border-box; } .agent-controls { background: #f5f5f5; padding: 1rem; border-radius: 4px; margin-bottom: 1rem; } #status { margin-top: 1rem; padding: 0.5rem; border-radius: 4px; } .success { background-color: #d4edda; color: #155724; } .error { background-color: #f8d7da; color: #721c24; } </style> </head> <body> <h1>Page Agent 功能演示</h1> <p>这是一个模拟的用户信息表单，Page Agent 将学习操作它。</p> <div class="agent-controls"> <h3>控制 Page Agent</h3> <label for="instruction">输入指令 (例如：填写表单，姓名写张三，邮箱写 test@example.com，然后提交):</label> <textarea id="instruction" rows="3" placeholder="用自然语言告诉我你想做什么..."></textarea> <button id="execute-btn">执行指令</button> <div id="status">就绪</div> </div> <div class="container"> <h2>用户信息表单</h2> <form id="demo-form"> <label for="name">姓名:</label> <input type="text" id="name" name="name" placeholder="请输入姓名"> <label for="email">电子邮箱:</label> <input type="email" id="email" name="email" placeholder="example@domain.com"> <label for="newsletter">订阅新闻:</label> <input type="checkbox" id="newsletter" name="newsletter"> <label>用户类型:</label> <div> <input type="radio" id="type-user" name="userType" value="user" checked> <label for="type-user" style="display: inline;">普通用户</label> <input type="radio" id="type-admin" name="userType" value="admin"> <label for="type-admin" style="display: inline;">管理员</label> </div> <label for="comments">备注:</label> <textarea id="comments" name="comments" rows="3" placeholder="可选"></textarea> <button type="submit" id="submit-btn">提交表单</button> <button type="button" id="reset-btn">重置</button> </form> <div id="form-output" style="margin-top: 1rem; white-space: pre-wrap; background: #eee; padding: 1rem;"></div> </div> <script type="module" src="/main.js"></script> </body> </html>main.js文件我们暂时留空，下一节将在这里编写 Page Agent 的集成代码。
3. 核心集成：将 Page Agent 嵌入你的网页
现在，我们进入最核心的部分：编写 JavaScript 代码来初始化和使用 Page Agent。
3.1 初始化 Page Agent 实例
在main.js中，我们首先导入 Page Agent 并创建一个实例。这里我们将使用阿里云 DashScope 的通义千问模型作为示例。
// main.js import { PageAgent } from 'page-agent'; // 注意：在生产环境中，API_KEY 必须通过后端服务获取，绝不能硬编码在前端。 // 此处仅为演示。你可以通过环境变量或构建时注入的方式在开发环境使用。 const API_KEY = 'sk-your-dashscope-api-key-here'; // 替换为你的真实 API Key const MODEL_NAME = 'qwen-plus'; // 或 'qwen-max', 'qwen-turbo' 等，根据你的 DashScope 权限选择 // 初始化 Page Agent 实例 const agent = new PageAgent({ // 使用的模型名称，对应 DashScope 的模型 model: MODEL_NAME, // DashScope 兼容 OpenAI 的接口地址 baseURL: 'https://dashscope.aliyuncr.com/compatible-mode/v1', // 你的 API Key apiKey: API_KEY, // 界面语言 language: 'zh-CN', // 设置为中文界面 // 可选：是否在控制台输出详细日志，调试时非常有用 verbose: true, // 可选：自定义请求头，可用于传递认证信息（如果使用后端代理） // headers: { 'Authorization': `Bearer ${YOUR_BACKEND_TOKEN}` }, // 可选：设置超时时间（毫秒） timeout: 60000, }); console.log('Page Agent 初始化完成。');关键参数解释：
model: 指定要使用的 LLM 模型。对于 DashScope，常见值有qwen-plus（通用能力强）、qwen-max（最新长文本模型）、qwen-turbo（速度快，成本低）。你需要确保你的 API Key 有对应模型的调用权限。baseURL: API 端点。Page Agent 使用兼容 OpenAI 的接口格式，DashScope 提供了compatible-mode/v1这个兼容端点。apiKey: 最重要的凭证。再次强调，开发完成后务必移除前端硬编码的 Key。language: 设置智能体界面和部分内部提示词的语言，zh-CN会让按钮和提示更友好。verbose: 调试神器。开启后会在浏览器控制台输出详细的思考过程、发送的提示词和接收的动作序列，帮助你理解智能体为何做出某个决策。
3.2 绑定 UI 与执行指令
接下来，我们需要将页面上的输入框和按钮与 Page Agent 的execute方法绑定。
// main.js (续) // 获取 DOM 元素 const instructionInput = document.getElementById('instruction'); const executeButton = document.getElementById('execute-btn'); const statusDiv = document.getElementById('status'); const formOutput = document.getElementById('form-output'); const demoForm = document.getElementById('demo-form'); // 更新状态显示的函数 function updateStatus(message, isError = false) { statusDiv.textContent = message; statusDiv.className = isError ? 'error' : 'success'; } // 为执行按钮绑定点击事件 executeButton.addEventListener('click', async () => { const instruction = instructionInput.value.trim(); if (!instruction) { updateStatus('请输入指令。', true); return; } updateStatus('智能体思考中...'); executeButton.disabled = true; try { // 核心：执行指令 const result = await agent.execute(instruction); // result 对象包含执行详情 console.log('执行结果:', result); updateStatus(`指令执行完成。共执行了 ${result.steps?.length || 0} 个步骤。`); // 可选：演示获取表单数据 simulateFormDataDisplay(); } catch (error) { console.error('执行指令时出错:', error); updateStatus(`出错: ${error.message}`, true); } finally { executeButton.disabled = false; } }); // 一个模拟函数，用于展示表单当前的数据状态 function simulateFormDataDisplay() { const formData = { name: document.getElementById('name').value, email: document.getElementById('email').value, newsletter: document.getElementById('newsletter').checked, userType: document.querySelector('input[name="userType"]:checked')?.value, comments: document.getElementById('comments').value, }; formOutput.textContent = JSON.stringify(formData, null, 2); } // 为表单的提交和重置按钮添加简单的事件，防止页面跳转并展示数据 demoForm.addEventListener('submit', (event) => { event.preventDefault(); // 阻止表单实际提交 updateStatus('表单提交动作被触发（演示中已阻止实际提交）。'); simulateFormDataDisplay(); }); document.getElementById('reset-btn').addEventListener('click', () => { demoForm.reset(); formOutput.textContent = ''; updateStatus('表单已重置。'); }); // 初始状态 updateStatus('Page Agent 已就绪，请输入指令。');3.3 运行与验证
现在，启动开发服务器并验证集成是否成功。
# 在项目根目录下运行 npm run devVite 会启动一个本地开发服务器（通常是http://localhost:5173）。在浏览器中打开该地址。
- 初始检查：打开浏览器开发者工具（F12）的“控制台”(Console)标签页。你应该能看到
Page Agent 初始化完成。的日志。如果没有错误，说明库加载成功。 - 执行测试指令：
- 在“输入指令”文本框中输入：
填写表单，姓名写李四，邮箱写 lisi@demo.com，勾选订阅新闻，选择管理员，在备注里写“测试用户”，然后点击提交表单按钮。 - 点击“执行指令”按钮。
- 在“输入指令”文本框中输入：
- 观察过程：
- 状态栏会变为“智能体思考中...”。
- 由于我们设置了
verbose: true，在控制台你会看到大量日志。Page Agent 会打印它发送给 LLM 的提示词（包含页面 DOM 的文本化摘要），以及从 LLM 返回的规划好的动作序列。 - 你会看到页面上的表单被自动填写：姓名和邮箱框出现文字，复选框被勾选，管理员单选按钮被选中，备注框被填写。
- 最后，“提交表单”按钮被点击，状态栏更新，下方的表单数据展示区域会显示出当前表单的所有值。
- 验证结果：表单数据展示区域应该显示如下格式的 JSON：
{ "name": "李四", "email": "lisi@demo.com", "newsletter": true, "userType": "admin", "comments": "测试用户" }
至此，一个最基本的 Page Agent 集成已经完成。你的网页现在可以通过自然语言指令来操作了。
4. 进阶配置与生产环境考量
基础集成跑通后，我们需要考虑更复杂的场景和将项目推向生产环境时必须解决的问题。
4.1 安全地管理 API Key：使用后端代理
前端硬编码 API Key 是严重的安全漏洞。任何用户查看页面源代码或网络请求都能窃取它。正确的做法是搭建一个简单的后端代理。
后端代理示例（Node.js + Express）：
- 在项目根目录创建
server文件夹，并初始化一个新的 Node.js 项目。mkdir server && cd server npm init -y npm install express axios dotenv cors - 创建
server/.env文件，存放你的 DashScope API Key：DASHSCOPE_API_KEY=sk-your-real-secret-key-here - 创建
server/index.js：// server/index.js require('dotenv').config(); const express = require('express'); const axios = require('axios'); const cors = require('cors'); const app = express(); const port = 3001; // 允许前端跨域请求 app.use(cors()); app.use(express.json()); // 代理端点，转发到 DashScope app.post('/v1/chat/completions', async (req, res) => { try { const response = await axios({ method: 'post', url: 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions', headers: { 'Authorization': `Bearer ${process.env.DASHSCOPE_API_KEY}`, 'Content-Type': 'application/json', }, data: req.body, }); res.json(response.data); } catch (error) { console.error('代理请求失败:', error.response?.data || error.message); res.status(error.response?.status || 500).json({ error: { message: '代理服务请求上游 API 失败', details: error.response?.data || error.message } }); } }); app.listen(port, () => { console.log(`API 代理服务器运行在 http://localhost:${port}`); }); - 启动代理服务器：
cd server node index.js - 修改前端的
main.js中的 Page Agent 配置：const agent = new PageAgent({ model: 'qwen-plus', // 模型名仍需指定 baseURL: 'http://localhost:3001', // 指向你的代理服务器 apiKey: 'dummy-key-or-empty', // 前端不再需要真实的 Key，可以传一个占位符或不传 // 如果代理需要额外的认证，可以在这里添加 headers // headers: { 'X-Client-Token': 'your-client-token' }, language: 'zh-CN', verbose: true, });
这样，所有对 LLM 的请求都会先发送到你的后端服务器，由服务器附加真实的 API Key 后再转发给 DashScope。前端代码中不再包含敏感信息。
4.2 性能与成本优化：模型选择与上下文管理
LLM API 调用是按 Token 计费的，并且响应速度直接影响用户体验。
- 模型选型：对于表单填写、简单点击等任务，
qwen-turbo或qwen-plus通常足够且成本更低、速度更快。对于需要复杂逻辑推理或多步骤规划的任务，再考虑qwen-max。 - 限制 DOM 上下文：默认情况下，Page Agent 会发送整个可视区域或页面的 DOM 摘要，这可能非常冗长。你可以通过配置来限制它只关注特定的容器，减少 Token 消耗并提升模型处理速度。
const agent = new PageAgent({ // ... 其他配置 // 将智能体的操作范围限制在 id 为 ‘demo-form’ 的表单内 rootElement: document.getElementById('demo-form'), }); - 启用缓存：如果页面结构在单次会话中变化不大，可以考虑启用动作缓存（如果 Page Agent 未来版本支持），避免对相同指令和页面状态进行重复的 LLM 调用。
4.3 错误处理与用户体验增强
在生产环境中，健壮的错误处理和友好的用户反馈至关重要。
executeButton.addEventListener('click', async () => { const instruction = instructionInput.value.trim(); if (!instruction) { showToast('请输入指令。', 'warning'); return; } setLoadingState(true); updateStatus('正在解析您的指令...'); try { const result = await agent.execute(instruction, { // 可选：设置执行超时 timeout: 45000, }); if (result.success) { updateStatus('任务执行成功！'); showToast('智能体已完成操作。', 'success'); } else { // 处理执行过程中的部分失败 updateStatus(`任务完成，但部分步骤可能未成功。`); console.warn('执行结果有警告:', result); } } catch (error) { // 分类处理常见错误 let userMessage = '执行指令时发生未知错误。'; if (error.message.includes('timeout')) { userMessage = '指令执行超时，可能是网络或模型响应慢，请重试。'; } else if (error.message.includes('Network Error') || error.message.includes('Failed to fetch')) { userMessage = '网络连接失败，请检查网络或代理服务状态。'; } else if (error.message.includes('Incorrect API key')) { userMessage = '服务配置错误，请联系管理员。'; // 对用户隐藏具体细节 } else if (error.message.includes('rate limit')) { userMessage = '操作过于频繁，请稍后再试。'; } updateStatus(userMessage, true); showToast(userMessage, 'error'); console.error('Page Agent 执行错误详情:', error); } finally { setLoadingState(false); } }); function setLoadingState(isLoading) { executeButton.disabled = isLoading; instructionInput.disabled = isLoading; executeButton.textContent = isLoading ? '执行中...' : '执行指令'; } // 一个简单的 Toast 提示函数 function showToast(message, type = 'info') { // 实现一个简单的 Toast 提示，例如使用 alert 或自定义 UI 组件 console.log(`[${type.toUpperCase()}] ${message}`); // 实际项目中可以集成像 SweetAlert2, Toastify 等库 }5. 常见问题排查与最佳实践
即使按照步骤操作，你也可能会遇到一些问题。以下是集成 Page Agent 时最常见的坑及其解决方案。
5.1 问题排查清单
| 问题现象 | 可能原因 | 检查步骤与解决方案 | ||
|---|---|---|---|---|
控制台报错Failed to fetch或Network Error | 1. API Key 或baseURL错误。2. 网络问题（如跨域、代理服务器未启动）。 3. 模型服务商接口限制（如地域限制）。 | 1. 检查baseURL是否正确，特别是 DashScope 的兼容端点地址。2. 打开浏览器开发者工具的“网络”(Network)标签页，查看对 baseURL的请求是否发出、状态码是什么（如 401、403、404、429）。3. 确认代理服务器（如果用了）是否运行且端口正确。 4. 尝试在浏览器直接访问 baseURL看是否通。 | ||
| 智能体无法找到页面元素（如“找不到登录按钮”） | 1. DOM 结构在智能体分析后发生了变化（动态渲染）。 2. 元素选择器过于复杂或模糊。 3. rootElement配置限制了查找范围。 | 1. 开启verbose: true，查看智能体发送给模型的页面描述中是否包含目标元素。2. 确保在调用 agent.execute()时，目标元素已经渲染在页面上。对于 SPA（如 React, Vue），可能需要等待组件挂载完成。3. 为关键元素添加更明确的 id或>指令执行结果不符合预期（如点错按钮） | 1. 指令描述模糊。 2. 模型能力或理解偏差。 3. 页面有多个相似元素。 | 1. 使用更精确的指令，例如“点击那个写着‘登录’的蓝色按钮”比“点击登录按钮”更好。 2. 尝试换用更强的模型（如从 qwen-turbo切换到qwen-plus）。3. 在 verbose日志中检查模型返回的动作序列，看它的“思考”过程是否合理。 |
| 执行速度非常慢 | 1. 网络延迟高。 2. 模型响应慢（如使用了较慢的模型）。 3. 页面 DOM 过于复杂，上下文太长。 | 1. 使用rootElement限制操作范围。2. 考虑使用响应更快的模型。 3. 检查代理服务器或自身网络链路。 | ||
| 在本地开发正常，部署后失效 | 1. 生产环境 API Key 未正确配置（后端代理）。 2. 生产环境跨域策略（CORS）问题。 3. 生产环境页面 DOM 结构与开发环境不同。 | 1. 确保生产环境的后端服务正常运行且能访问模型 API。 2. 检查后端代理的 CORS 配置是否正确允许了生产前端的域名。 3. 使用构建工具确保前端资源路径正确。 |
5.2 生产环境最佳实践
- 永远不要在前端暴露真实 API Key：这是铁律。必须通过你自己的后端服务进行中转。
- 实施请求限流与鉴权：在你的后端代理上，对调用 Page Agent 接口的请求进行用户鉴权和频率限制，防止滥用和产生意外高额费用。
- 使用环境变量管理配置：将
baseURL、模型名称等配置项通过构建工具（如 Vite 的import.meta.env）注入，区分开发、测试、生产环境。 - 提供明确的用户引导：不是所有用户都知道如何用自然语言有效下达指令。在 UI 上提供一些示例指令或按钮（如“帮我填写示例”、“清空表单”），引导用户使用。
- 设计降级与回退方案：AI 服务可能不稳定。确保当 Page Agent 失败时，用户仍然能通过传统方式（手动点击、输入）完成操作。可以设置一个开关，允许用户禁用 AI 助手功能。
- 监控与日志：在后端代理服务中记录所有的请求和响应（注意脱敏敏感信息），便于监控使用量、分析错误和优化提示词。
- 持续优化提示词：Page Agent 的内部提示词可能对某些特定页面结构不友好。如果发现智能体在特定任务上表现不佳，可以考虑 fork 其仓库，根据你的页面特点微调其提示词模板（涉及
packages/core中的代码），但这属于高级用法。
Page Agent 为 Web 应用带来了全新的交互可能性。它降低了为产品添加 AI 能力的门槛，但其效果严重依赖于底层 LLM 的能力和页面本身的结构清晰度。在简单、标准的 Web 表单和界面中，它能表现出惊人的效率；而在高度动态、视觉化或自定义组件复杂的页面中，可能需要更多的引导和定制。从今天这个简单的 demo 开始，尝试将它集成到你的下一个项目中，探索自然语言驱动界面的未来。
