在以下文档中,你可能会看到带有
agent.
前缀的函数调用。如果你在 Playwright 中,这些调用是不带agent.
前缀的,如async ({ ai, aiQuery }) => { /* ... */}
。这只是解构语法的区别。
Midscene 中每个 Agent 都有自己的构造函数。
这些 Agent 有一些相同的构造参数:
generateReport: boolean
: 如果为 true,则生成报告文件。默认值为 true。autoPrintReportMsg: boolean
: 如果为 true,则打印报告消息。默认值为 true。cacheId: string | undefined
: 如果配置,则使用此 cacheId 保存或匹配缓存。默认值为 undefined,也就是不启用缓存。actionContext: string
: 调用 agent.aiAction()
时,发送给 AI 模型的背景知识,比如 '有 cookie 对话框时先关闭它',默认值为空。在 Playwright 和 Puppeteer 中,有以下共同的参数:
forceSameTabNavigation: boolean
: 如果为 true,则限制页面在当前 tab 打开。默认值为 true。waitForNetworkIdleTimeout: number
: 在执行每个操作后等待网络空闲的超时时间,默认值为 2000ms,设置为 0 则不做等待。waitForNavigationTimeout: number
: 在页面跳转后等待页面加载完成的超时时间,默认值为 5000ms,设置为 0 则不做等待。这些是 Midscene 中各类 Agent 的主要 API。
在 Midscene 中,你可以选择使用自动规划(Auto Planning)或即时操作(Instant Action)。
agent.ai()
是自动规划(Auto Planning):Midscene 会自动规划操作步骤并执行。它更智能,更像流行的 AI Agent 风格,但可能较慢,且效果依赖于 AI 模型的质量。agent.aiTap()
, agent.aiHover()
, agent.aiInput()
, agent.aiKeyboardPress()
, agent.aiScroll()
, agent.aiRightClick()
是即时操作(Instant Action):Midscene 会直接执行指定的操作,而 AI 模型只负责底层任务,如定位元素等。这种接口形式更快、更可靠。当你完全确定自己想要执行的操作时,推荐使用这种接口形式。agent.aiAction()
或.ai()
这个方法允许你通过自然语言描述一系列 UI 操作步骤。Midscene 会自动规划这些步骤并执行。
参数:
prompt: string
- 用自然语言描述的操作内容opt?: Object
- 可选,一个配置对象,包含:
cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
示例:
agent.aiTap()
点击某个元素。
参数:
locate: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
Promise<void>
示例:
agent.aiHover()
仅在 web 页面中可用,在 Android 下不可用
鼠标悬停某个元素上。
参数:
locate: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
Promise<void>
示例:
agent.aiInput()
在某个元素中输入文本。
参数:
text: string
- 要输入的文本内容。使用空字符串可以清空输入框。locate: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 TrueautoDismissKeyboard?: boolean
- 如果为 true,则键盘会在输入文本后自动关闭,仅在 Android 中有效。默认值为 true。返回值:
Promise<void>
示例:
agent.aiKeyboardPress()
按下键盘上的某个键。
参数:
key: string
- 要按下的键,如 Enter
、Tab
、Escape
等。不支持组合键。locate?: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
Promise<void>
示例:
agent.aiScroll()
滚动页面或某个元素。
参数:
scrollParam: PlanningActionParamScroll
- 滚动参数
direction: 'up' | 'down' | 'left' | 'right'
- 滚动方向scrollType: 'once' | 'untilBottom' | 'untilTop' | 'untilRight' | 'untilLeft'
- 滚动类型distance: number
- 滚动距离,单位为像素。locate?: string
- 用自然语言描述的元素定位。如果未传入,Midscene 会在当前鼠标位置滚动。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
Promise<void>
示例:
agent.aiRightClick()
仅在 web 页面中可用,在 Android 下不可用
右键点击某个元素。请注意,Midscene 在右键点击后无法与浏览器原生上下文菜单交互。这个接口通常用于已经监听了右键点击事件的元素。
参数:
locate: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
Promise<void>
示例:
deepThink
(深度思考)特性
deepThink
是一个强大的特性,它允许 Midscene 调用 AI 模型两次以精确定位元素。这在目标元素面积较小、难以和周围元素区分时非常有用。
agent.aiAsk()
使用此方法,你可以针对当前页面,直接向 AI 模型发起提问,并获得字符串形式的回答。
参数:
prompt: string
- 用自然语言描述的询问内容。options?: Object
- 可选,一个配置对象,包含:
domIncluded?: boolean | 'visible-only'
- 是否向模型发送精简后的 DOM 信息,一般用于提取 UI 中不可见的属性,比如图片的链接。如果设置为 'visible-only'
,则只发送可见的元素。默认值为 False。screenshotIncluded?: boolean
- 是否向模型发送截图。默认值为 True。返回值:
示例:
除了 aiAsk
方法,你还可以使用 aiQuery
方法,直接从 UI 提取结构化的数据。
agent.aiQuery()
使用此方法,你可以直接从 UI 提取结构化的数据。只需在 dataDemand
中描述期望的数据格式(如字符串、数字、JSON、数组等),Midscene 即返回相应结果。
参数:
dataDemand: T
: 描述预期的返回值和格式。options?: Object
- 可选,一个配置对象,包含:
domIncluded?: boolean | 'visible-only'
- 是否向模型发送精简后的 DOM 信息,一般用于提取 UI 中不可见的属性,比如图片的链接。如果设置为 'visible-only'
,则只发送可见的元素。默认值为 False。screenshotIncluded?: boolean
- 是否向模型发送截图。默认值为 True。返回值:
dataDemand
中描述它,Midscene 就会给你满足格式的返回。示例:
此外,我们还提供了 aiBoolean()
, aiNumber()
, aiString()
三个便捷方法,用于直接提取布尔值、数字和字符串。
agent.aiBoolean()
从 UI 中提取一个布尔值。
参数:
prompt: string
- 用自然语言描述的期望值。options?: Object
- 可选,一个配置对象,包含:
domIncluded?: boolean | 'visible-only'
- 是否向模型发送精简后的 DOM 信息,一般用于提取 UI 中不可见的属性,比如图片的链接。如果设置为 'visible-only'
,则只发送可见的元素。默认值为 False。screenshotIncluded?: boolean
- 是否向模型发送截图。默认值为 True。返回值:
示例:
agent.aiNumber()
从 UI 中提取一个数字。
参数:
prompt: string
- 用自然语言描述的期望值。options?: Object
- 可选,一个配置对象,包含:
domIncluded?: boolean | 'visible-only'
- 是否向模型发送精简后的 DOM 信息,一般用于提取 UI 中不可见的属性,比如图片的链接。如果设置为 'visible-only'
,则只发送可见的元素。默认值为 False。screenshotIncluded?: boolean
- 是否向模型发送截图。默认值为 True。返回值:
示例:
agent.aiString()
从 UI 中提取一个字符串。
参数:
prompt: string
- 用自然语言描述的期望值。options?: Object
- 可选,一个配置对象,包含:
domIncluded?: boolean | 'visible-only'
- 是否向模型发送精简后的 DOM 信息,一般用于提取 UI 中不可见的属性,比如图片的链接。如果设置为 'visible-only'
,则只发送可见的元素。默认值为 False。screenshotIncluded?: boolean
- 是否向模型发送截图。默认值为 True。返回值:
示例:
agent.aiAssert()
通过自然语言描述一个断言条件,让 AI 判断该条件是否为真。当条件不满足时,SDK 会抛出错误,并在错误信息中追加 AI 返回的详细原因。
参数:
返回值:
errorMsg
以及 AI 生成的原因。示例:
断言在测试脚本中非常重要。为了降低因 AI 幻觉导致错误断言的风险(例如遗漏错误),你也可以使用 .aiQuery
加上常规的 JavaScript 断言来替代 .aiAssert
。
例如,你可以这样替代上面的断言代码:
agent.aiLocate()
通过自然语言描述一个元素的定位。
参数:
locate: string
- 用自然语言描述的元素定位。options?: Object
- 可选,一个配置对象,包含:
deepThink?: boolean
- 是否开启深度思考。如果为 true,Midscene 会调用 AI 模型两次以精确定位元素。默认值为 Falsexpath?: string
- 目标元素的 xpath 路径,用于执行当前操作。如果提供了这个 xpath,Midscene 会优先使用该 xpath 来找到元素,然后依次使用缓存和 AI 模型。默认值为空cacheable?: boolean
- 当启用 缓存功能 时,是否允许缓存当前 API 调用结果。默认值为 True返回值:
示例:
agent.aiWaitFor()
等待某个条件达成。考虑到 AI 服务的成本,检查间隔不会超过 checkIntervalMs
毫秒。
参数:
assertion: string
- 用自然语言描述的断言条件options?: object
- 可选的配置对象
timeoutMs?: number
- 超时时间(毫秒),默认为 15000checkIntervalMs?: number
- 检查间隔(毫秒),默认为 3000返回值:
示例:
考虑到 AI 服务的时间消耗,.aiWaitFor
并不是一个特别高效的方法。使用一个普通的 sleep
可能是替代 waitFor
的另一种方式。
agent.runYaml()
执行一个 YAML 格式的自动化脚本。脚本中的 tasks
部分会被执行,并返回所有 .aiQuery
调用的结果。
参数:
yamlScriptContent: string
- YAML 格式的脚本内容返回值:
result
属性的对象,其中包含所有 aiQuery
调用的结果示例:
更多关于 YAML 脚本的信息,请参考 Automate with Scripts in YAML。
agent.setAIActionContext()
设置在调用 agent.aiAction()
时,发送给 AI 模型的背景知识。
参数:
actionContext: string
- 要发送给 AI 模型的背景知识。示例:
agent.evaluateJavaScript()
仅在 web 页面中可用,在 Android 下不可用
这个方法允许你在 web 页面上下文中执行一段 JavaScript 代码,并返回执行结果。
参数:
script: string
- 要执行的 JavaScript 代码。返回值:
示例:
agent.logScreenshot()
在报告文件中记录当前截图,并添加描述。
参数:
title?: string
- 可选,截图的标题,如果未提供,则标题为 'untitled'。options?: Object
- 可选,一个配置对象,包含:
content?: string
- 截图的描述。返回值:
Promise<void>
示例:
agent._unstableLogContent()
从报告文件中获取日志内容。日志内容的结构可能会在未来发生变化。
返回值:
示例:
.reportFile
报告文件的路径。
你可以通过 overrideAIConfig
方法在运行时设置环境变量。
设置 DEBUG=midscene:ai:profile:stats
环境变量,你可以看到每次调用 AI 的时间和 token 数量。
设置 MIDSCENE_RUN_DIR
变量,你可以自定义运行产物目录。
LangSmith 是一个用于调试大语言模型的平台。想要集成 LangSmith,请按以下步骤操作:
启动 Midscene 后,你应该会看到类似如下的日志: