Midscene.js API完全指南：从Interaction到Data Extraction全解析
项目地址: https://gitcode.com/GitHub_Trending/mid/midscene Midscene.js作为AI驱动的浏览器自动化工具，提供了从界面交互到数据提取的完整解决方案。本文将系统解析其核心API，帮助开发者快速掌握自动化脚本编写、元素定位与数据提取技巧。
核心架构概览
Midscene.js采用模块化设计，核心功能分布在packages/core/与packages/web-integration/目录。主要模块包括：
- Agent模块：负责AI决策与任务调度，定义于packages/core/src/agent.ts
- Web交互层：提供标准化的页面操作接口，实现于packages/web-integration/src/web-page.ts
- YAML解析器：支持声明式脚本编写，语法定义见packages/core/src/yaml.ts
基础交互API详解
元素定位系统
Midscene.js提供多模态定位能力，核心API为aiLocate方法：
// 基础定位示例
const element = await agent.aiLocate({
prompt: "查找搜索框",
deepThink: true
});
定位选项支持XPath精确匹配与AI语义理解，详细参数定义见LocateOption接口。
鼠标操作
支持完整的鼠标事件模拟，包括：
// 单击操作
await page.mouse.click(x, y, { button: 'left' });
// 拖拽示例
await page.mouse.drag(
{ x: 100, y: 200 },
{ x: 300, y: 400 }
);
所有鼠标操作封装于MouseAction接口，支持左键/右键点击、双击与拖拽功能。
键盘输入
提供两种文本输入模式：
// 直接输入
await page.keyboard.type("搜索关键词");
// 热键组合
await page.keyboard.press([
{ key: 'Control' },
{ key: 'v' }
]);
支持的按键列表定义于KeyInput类型，包含从字母数字到功能键的完整映射。
数据提取高级应用
结构化数据提取
通过aiQuery方法实现智能数据提取：
# YAML脚本示例
- aiQuery: "提取商品列表"
name: products
domIncluded: visible-only
该API会自动识别页面结构并返回JSON结果，详细配置见InsightExtractOption接口。
视觉定位与断言
结合AI视觉理解的元素定位：
const element = await agent.aiLocate({
prompt: "查找登录按钮",
referenceImage: {
base64: "iVBORw0KGgoAAAANSUhEUgAA...",
rect: { x: 0, y: 0, width: 100, height: 50 }
}
});
支持参考图定位功能，特别适用于动态加载内容，定义于DetailedLocateParam接口。
实战脚本示例
电商搜索自动化
name: 商品搜索流程
flow:
- aiLocate: "搜索框"
name: searchBox
- input:
locate: ${searchBox}
value: "无线耳机"
- aiAction: "点击搜索按钮"
- aiWaitFor: "商品列表加载完成"
- aiQuery: "提取前5个商品的名称和价格"
name: results
此脚本实现完整的商品搜索-结果提取流程，关键API包括：
aiLocate：语义化元素定位aiAction：AI驱动的动作执行aiQuery：结构化数据提取
表单自动填写
// 清除输入框
await agent.clearInput(await agent.aiLocate({ prompt: "邮箱输入框" }));
// 智能填写
await agent.input({
locate: await agent.aiLocate({ prompt: "邮箱输入框" }),
value: "user@example.com"
});
// 提交表单
await agent.aiAction("点击注册按钮");
表单操作核心API封装于commonWebActionsForWebPage函数，包含输入清除、文本填写等标准化方法。
扩展资源与最佳实践
调试工具
- Chrome扩展调试器：提供实时元素定位与事件录制功能
- Playground应用：可视化脚本编辑器与执行环境
性能优化建议
- 缓存策略：设置
cacheable: true减少重复AI计算 - 批量操作：使用
batch-runner.ts实现任务并行执行 - 选择器优化：优先使用XPath定位静态元素
完整API文档见官方文档，更多示例可参考tests目录下的自动化测试用例。
通过合理组合Interaction与Data Extraction API，Midscene.js可实现从简单表单填写到复杂数据爬取的各类自动化场景。建议配合YAML脚本格式与AI辅助定位，大幅提升开发效率。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
