page-agent性能调优指南maxSteps、stepDelay、viewportExpansion参数全解析【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent 是一个用自然语言操控网页界面的 JavaScript GUI Agent智能体无需浏览器插件、截图或多模态模型直接在你自己的网页里运行。当它跑得太慢、步数跑飞、或 AI 总是找不到视口外的按钮时maxSteps、stepDelay、viewportExpansion这三个参数就是性能调优的核心开关。本文带你逐个吃透它们的作用、默认值与调优技巧 1 分钟看懂 page-agent 的执行模型page-agent 的工作是一个「观察 → 思考 → 行动」的循环每1 步step 抓取一次页面 DOM 调用一次 LLM 执行一个动作。三个参数恰好分别控制这个循环的深度、节奏和视野参数一句话作用默认值maxSteps每个任务最多允许多少步40stepDelay相邻两步之间的等待时间秒0.4viewportExpansionDOM 提取时超出当前视口的像素范围-1整个页面三个参数都通过构造配置传入见 PageAgent.tsnew PageAgent({ model: qwen3.5-plus, baseURL: ..., apiKey: ..., maxSteps: 20, // 每任务步数上限 stepDelay: 0.6, // 步间延迟秒 viewportExpansion: 0 // 0仅当前视口-1整个页面 })maxSteps 参数怎么设给 AI 任务装上刹车工作机制默认 40 步剩 5 步开始警告maxSteps在 types.ts 中定义为每个任务的最大步骤数。它在执行循环里有多重作用每步提示词都会写入Step X of 40 max possible steps让模型心里有数PageAgentCore.ts剩 5 步时注入观察信息考虑收尾或带着部分结果调用 done剩 2 步时升级为紧急提醒必须立即收尾PageAgentCore.ts超限后任务以Step count exceeded maximum limit失败结束不会无限循环烧钱PageAgentCore.ts。快速选择建议经验值单页点击 / 填写类任务10–15多页流转、含表单校验25–40高频批量跑任务、控成本设小一点失败快速重试比跑满 40 步更划算 stepDelay 延迟配置0.4 秒默认值背后的原理它延迟的是什么在 PageAgentCore.ts 的执行循环中从第 2 步开始每个新步骤正式开始前会先等待stepDelay秒第 1 步除外。这相当于给单页应用渲染、异步数据请求一点缓冲时间避免 AI 在页面上一次没点到位。调大还是调小看你的页面页面特征建议值原因接口慢、动画多、数据异步加载0.8 – 1.5减少点了没反应 → AI 重复点击的浪费步数普通页面默认即可0.4平衡等待与稳定性静态页面、追求低延迟0页面早已就绪等待纯浪费⚠️ 注意延迟是线性累加的10 步 × 1 秒 白等 10 秒。不要为了保险盲目调大。viewportExpansion 视口扩展-1、0 还是正数三种取值的含义viewportExpansion定义在 dom/index.ts控制每步 DOM 提取时看得多宽取值行为-1提取整个页面无视视口限制默认0只提取当前视口内的交互元素正数视口向外扩展 N 像素它还会改变发给 LLM 的提示词头部设为-1时显示Interactive elements ... (full page)且不再给出滚动提示设为0时则会出现... 300 pixels below - scroll to see more ...引导 AI 主动滚动PageController.ts。关键细节真正有意义的只有 -1 和 0源码中有一段耐人寻味的注释判断元素是否顶层可见依赖elementFromPoint而该 API 对视口外的元素会返回nulldom_tree/index.js。因此正数外扩在实践中效果基本等同于 0实际可用的就是两个开关长页面、需要跨屏找元素 →-1AI 直接看到全页省去反复滚动步数固定视口界面仪表盘、后台管理→0提示词更短token 消耗显著降低模型注意力也更集中。组合调优速查表使用场景推荐配置核心理由后台管理 / 仪表盘无滚动maxSteps: 20stepDelay: 0.4viewportExpansion: 0Token 最省、最稳 ✅长表单 / 长文档页面maxSteps: 30–40stepDelay: 0.6viewportExpansion: -1全页可见步数省慢接口 SPAmaxSteps: 20stepDelay: 1.0viewportExpansion: 0等渲染完再动手高频批量任务maxSteps: 10–15stepDelay: 0.2–0.4viewportExpansion: 0控成本、快速失败三个常见调优误区以为调大 maxSteps 会让任务更聪明— 它只是放宽上限成功率主要取决于模型能力和页面可访问性。stepDelay 设 0 就一定更快— 页面没渲染完就进入下一步AI 反而浪费步数重试总耗时可能更长。viewportExpansion 设 400 之类的正数有奇效— 如前所述实际效果与0相同直接用0即可。延伸阅读参数类型定义types.ts、types.ts执行循环与步数上限逻辑PageAgentCore.ts视口可见性判断实现dom_tree/index.jsPageController 官方文档页page-controller/page.tsx【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 page-agent性能调优指南：maxSteps、stepDelay、viewportExpansion参数全解析
page-agent性能调优指南maxSteps、stepDelay、viewportExpansion参数全解析【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent 是一个用自然语言操控网页界面的 JavaScript GUI Agent智能体无需浏览器插件、截图或多模态模型直接在你自己的网页里运行。当它跑得太慢、步数跑飞、或 AI 总是找不到视口外的按钮时maxSteps、stepDelay、viewportExpansion这三个参数就是性能调优的核心开关。本文带你逐个吃透它们的作用、默认值与调优技巧 1 分钟看懂 page-agent 的执行模型page-agent 的工作是一个「观察 → 思考 → 行动」的循环每1 步step 抓取一次页面 DOM 调用一次 LLM 执行一个动作。三个参数恰好分别控制这个循环的深度、节奏和视野参数一句话作用默认值maxSteps每个任务最多允许多少步40stepDelay相邻两步之间的等待时间秒0.4viewportExpansionDOM 提取时超出当前视口的像素范围-1整个页面三个参数都通过构造配置传入见 PageAgent.tsnew PageAgent({ model: qwen3.5-plus, baseURL: ..., apiKey: ..., maxSteps: 20, // 每任务步数上限 stepDelay: 0.6, // 步间延迟秒 viewportExpansion: 0 // 0仅当前视口-1整个页面 })maxSteps 参数怎么设给 AI 任务装上刹车工作机制默认 40 步剩 5 步开始警告maxSteps在 types.ts 中定义为每个任务的最大步骤数。它在执行循环里有多重作用每步提示词都会写入Step X of 40 max possible steps让模型心里有数PageAgentCore.ts剩 5 步时注入观察信息考虑收尾或带着部分结果调用 done剩 2 步时升级为紧急提醒必须立即收尾PageAgentCore.ts超限后任务以Step count exceeded maximum limit失败结束不会无限循环烧钱PageAgentCore.ts。快速选择建议经验值单页点击 / 填写类任务10–15多页流转、含表单校验25–40高频批量跑任务、控成本设小一点失败快速重试比跑满 40 步更划算 stepDelay 延迟配置0.4 秒默认值背后的原理它延迟的是什么在 PageAgentCore.ts 的执行循环中从第 2 步开始每个新步骤正式开始前会先等待stepDelay秒第 1 步除外。这相当于给单页应用渲染、异步数据请求一点缓冲时间避免 AI 在页面上一次没点到位。调大还是调小看你的页面页面特征建议值原因接口慢、动画多、数据异步加载0.8 – 1.5减少点了没反应 → AI 重复点击的浪费步数普通页面默认即可0.4平衡等待与稳定性静态页面、追求低延迟0页面早已就绪等待纯浪费⚠️ 注意延迟是线性累加的10 步 × 1 秒 白等 10 秒。不要为了保险盲目调大。viewportExpansion 视口扩展-1、0 还是正数三种取值的含义viewportExpansion定义在 dom/index.ts控制每步 DOM 提取时看得多宽取值行为-1提取整个页面无视视口限制默认0只提取当前视口内的交互元素正数视口向外扩展 N 像素它还会改变发给 LLM 的提示词头部设为-1时显示Interactive elements ... (full page)且不再给出滚动提示设为0时则会出现... 300 pixels below - scroll to see more ...引导 AI 主动滚动PageController.ts。关键细节真正有意义的只有 -1 和 0源码中有一段耐人寻味的注释判断元素是否顶层可见依赖elementFromPoint而该 API 对视口外的元素会返回nulldom_tree/index.js。因此正数外扩在实践中效果基本等同于 0实际可用的就是两个开关长页面、需要跨屏找元素 →-1AI 直接看到全页省去反复滚动步数固定视口界面仪表盘、后台管理→0提示词更短token 消耗显著降低模型注意力也更集中。组合调优速查表使用场景推荐配置核心理由后台管理 / 仪表盘无滚动maxSteps: 20stepDelay: 0.4viewportExpansion: 0Token 最省、最稳 ✅长表单 / 长文档页面maxSteps: 30–40stepDelay: 0.6viewportExpansion: -1全页可见步数省慢接口 SPAmaxSteps: 20stepDelay: 1.0viewportExpansion: 0等渲染完再动手高频批量任务maxSteps: 10–15stepDelay: 0.2–0.4viewportExpansion: 0控成本、快速失败三个常见调优误区以为调大 maxSteps 会让任务更聪明— 它只是放宽上限成功率主要取决于模型能力和页面可访问性。stepDelay 设 0 就一定更快— 页面没渲染完就进入下一步AI 反而浪费步数重试总耗时可能更长。viewportExpansion 设 400 之类的正数有奇效— 如前所述实际效果与0相同直接用0即可。延伸阅读参数类型定义types.ts、types.ts执行循环与步数上限逻辑PageAgentCore.ts视口可见性判断实现dom_tree/index.jsPageController 官方文档页page-controller/page.tsx【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考