# Page-Agent 安装与使用指南
## 环境要求
在安装 Page-Agent 之前，请确保您的环境满足以下要求：
– **浏览器**：支持 Chrome 90+ 或 Firefox 88+ 等现代浏览器
– **操作系统**：Windows、macOS 或 Linux
– **网络连接**：需要互联网连接以下载依赖和更新
– **开发环境**（可选）：Node.js 14+，npm 6+ 或 yarn
## 安装方法
Page-Agent 提供多种安装方式，您可以根据自己的需求选择合适的方法：
### 方法一：从浏览器扩展商店安装
1. **Chrome 用户**：
– 打开 Chrome 网上应用店
– 搜索 “Page-Agent”
– 点击 “添加至 Chrome”
– 确认安装
2. **Firefox 用户**：
– 打开 Firefox 附加组件商店
– 搜索 “Page-Agent”
– 点击 “添加到 Firefox”
– 确认安装
### 方法二：从源码构建安装
1. **克隆仓库**：
“`bash
git clone https://github.com/alibaba/page-agent.git
cd page-agent
“`
2. **安装依赖**：
“`bash
npm install
# 或使用 yarn
yarn install
“`
3. **构建项目**：
“`bash
npm run build
# 或使用 yarn
yarn build
“`
4. **加载扩展**：
– Chrome：打开 `chrome://extensions/`，开启 “开发者模式”，点击 “加载已解压的扩展程序”，选择 `dist` 目录
– Firefox：打开 `about:debugging`，点击 “此 Firefox”，点击 “临时载入附加组件”，选择 `dist/manifest.json` 文件
## 首次使用配置
安装完成后，首次使用 Page-Agent 需要进行以下配置：
1. **权限授权**：
– 首次启动时，Page-Agent 会请求必要的浏览器权限
– 请仔细阅读权限说明并授权
2. **基础设置**：
– 点击浏览器工具栏中的 Page-Agent 图标
– 在弹出的配置面板中设置基本参数
– 配置默认工作目录和存储位置
3. **API 密钥配置**（可选）：
– 如果需要使用外部 AI 服务，需配置相应的 API 密钥
– 支持 OpenAI、Anthropic 等多种 AI 服务
## 基本使用方法
### 启动 Page-Agent
– 点击浏览器工具栏中的 Page-Agent 图标
– 或使用快捷键 `Ctrl+Shift+P`（Windows）或 `Command+Shift+P`（Mac）
### 创建第一个 Agent
1. **点击 “新建 Agent” 按钮**
2. **填写 Agent 基本信息**：
– 名称：为您的 Agent 取一个有意义的名字
– 描述：简要描述 Agent 的功能
– 图标：选择或上传 Agent 图标
3. **配置 Agent 能力**：
– 选择需要的能力模块
– 配置触发条件
– 设置操作权限
4. **保存配置**：
– 点击 “保存” 按钮
– Agent 会自动加载到 Page-Agent 面板中
### 运行 Agent
1. **选择目标页面**：
– 导航到需要 Agent 操作的网页
– 确保页面已完全加载
2. **启动 Agent**：
– 在 Page-Agent 面板中选择您创建的 Agent
– 点击 “运行” 按钮
– 或使用右键菜单 “Run Page-Agent”
3. **监控执行过程**：
– Page-Agent 会在面板中显示执行进度
– 您可以随时暂停或停止执行
– 执行完成后会显示执行报告
## 高级使用技巧
### 使用命令行控制
Page-Agent 支持通过命令行控制：
“`bash
# 启动特定 Agent
page-agent run –agent=my-agent –url=https://example.com
# 批量执行任务
page-agent batch –config=batch.json
# 导出 Agent 配置
page-agent export –agent=my-agent –output=my-agent.json
# 导入 Agent 配置
page-agent import –file=my-agent.json
“`
### 编写自定义插件
1. **创建插件目录**：
“`bash
mkdir -p plugins/my-plugin
cd plugins/my-plugin
“`
2. **创建插件配置文件**：
“`json
{
“name”: “My Custom Plugin”,
“version”: “1.0.0”,
“description”: “A custom plugin for Page-Agent”,
“main”: “index.js”,
“permissions”: [“tabs”, “storage”]
}
“`
3. **实现插件逻辑**：
“`javascript
// index.js
module.exports = {
init: function(pageAgent) {
console.log(‘My plugin initialized’);
// 注册自定义命令
pageAgent.registerCommand(‘my-command’, function(params) {
console.log(‘Executing my command with params:’, params);
return ‘Command executed successfully’;
});
// 注册事件监听器
pageAgent.on(‘agent-start’, function(agent) {
console.log(‘Agent started:’, agent.name);
});
}
};
“`
4. **加载插件**：
– 在 Page-Agent 配置面板中，点击 “插件管理”
– 点击 “添加插件”，选择您的插件目录
– 启用插件
### 调试技巧
1. **开启调试模式**：
– 在 Page-Agent 配置中，开启 “开发者模式”
– 打开浏览器开发者工具
2. **查看日志**：
– 在浏览器开发者工具中，切换到 “Console” 标签
– 查看 Page-Agent 相关日志
3. **断点调试**：
– 在源代码中设置断点
– 运行 Agent 进行调试
## 常见问题与解决方案
### 安装失败
– **问题**：无法从扩展商店安装
**解决方案**：尝试从源码构建安装
– **问题**：构建失败
**解决方案**：确保 Node.js 版本符合要求，删除 `node_modules` 目录后重新安装依赖
### 权限错误
– **问题**：Agent 无法操作页面元素
**解决方案**：检查 Page-Agent 是否有足够的权限，在浏览器扩展管理中确认权限设置
### 执行失败
– **问题**：Agent 执行到一半停止
**解决方案**：查看执行日志，检查页面结构是否与 Agent 预期一致
– **问题**：Agent 无法识别页面元素
**解决方案**：调整 Agent 的元素识别策略，使用更稳定的选择器
## 最佳实践
1. **从简单任务开始**：
– 先创建执行简单任务的 Agent
– 逐步增加复杂度
2. **模块化设计**：
– 将复杂任务分解为多个小模块
– 每个模块专注于单一功能
3. **错误处理**：
– 为 Agent 添加错误处理逻辑
– 设置合理的超时和重试机制
4. **定期更新**：
– 及时更新 Page-Agent 到最新版本
– 关注官方更新日志
5. **社区贡献**：
– 分享您创建的 Agent 配置
– 参与社区讨论，贡献改进建议
通过本指南，您应该能够顺利安装和使用 Page-Agent。如果您在使用过程中遇到问题，建议查阅官方文档或在 GitHub 仓库中提交 issue。