API 参考（PC 桌面）

本页记录了 @midscene/computer 提供的 PC 桌面特定 API。

有关适用于所有平台的通用 API，请参阅通用 API 参考。

Agent 创建

agentForComputer(opts?): Promise<ComputerAgent>

创建用于本机桌面自动化的 agent。

向后兼容：agentFromComputer 仍可作为别名使用。

agentForRDPComputer(opts): Promise<ComputerAgent<RDPDevice>>

创建用于通过 RDP 控制远程 Windows 桌面的 agent。

参数：

interface BaseComputerAgentOpt {
  // Agent 选项（继承自 AgentOpt）
  aiActionContext?: string;
  cache?: boolean;
  // ... 其他 AgentOpt 属性

  customActions?: DeviceAction<any>[];
  keyboardTypeDelay?: number;
}

interface LocalComputerAgentOpt extends BaseComputerAgentOpt {

  // 本机桌面选项
  displayId?: string;
  headless?: boolean;
  xvfbResolution?: string;
}

interface RDPComputerAgentOpt extends BaseComputerAgentOpt {
  host: string;
  port?: number;
  username?: string;
  password?: string;
  domain?: string;
  adminSession?: boolean;
  ignoreCertificate?: boolean;
  securityProtocol?: 'auto' | 'tls' | 'nla' | 'rdp';
  desktopWidth?: number;
  desktopHeight?: number;
}

本机桌面选项

displayId（可选）：指定要控制的显示器。使用 ComputerDevice.listDisplays() 获取可用显示器。
customActions（可选）：向设备添加自定义操作。
headless（可选，仅 Linux）：设为 true 时通过 Xvfb 启动虚拟显示器，使桌面自动化能在无物理显示器的 Linux 服务器和 CI 环境中运行。也可通过环境变量 MIDSCENE_COMPUTER_HEADLESS_LINUX=true 设置。
xvfbResolution（可选）：Xvfb 虚拟显示器的分辨率，默认为 '1920x1080x24'。

键盘输入选项

keyboardTypeDelay（可选）：每次按键之间的最小延迟，单位为毫秒。设为正数后，本机和 RDP Computer Agent 会逐个 Unicode 字符发送文本，不再使用默认的整串输入。本机 Computer 会发送真实按键事件；未设置或设为 0 时，仍使用剪贴板粘贴，以免受到当前输入法的干扰。通过 aiInput() 传入的动作级 keyboardTypeDelay 优先于 Agent 级默认值，也可以传 0，只对当前动作恢复剪贴板输入。

Agent 级选项同样会作用于 agent.ai() 自动规划生成的 Input 动作，因此不要求用户单独调用 aiInput()：

const agent = await agentForComputer({ keyboardTypeDelay: 80 });

await agent.ai('把账号信息输入表单');

// 只覆盖这一次确定性输入，恢复整串粘贴。
await agent.aiInput('备注输入框', {
  value: '整串粘贴的内容',
  keyboardTypeDelay: 0,
});

RDP 选项

host：远程 Windows 主机名或 IP。
port：RDP 端口，默认是 3389。
username / password：远程会话凭据。
domain：可选的 Windows 域。
adminSession：当服务端允许时，请求远程管理员会话。
ignoreCertificate：用于跳过自签名证书校验。
securityProtocol：可选 'auto'、'tls'、'nla' 或 'rdp'。
desktopWidth / desktopHeight：请求指定远程桌面分辨率。

示例：在无头 Linux CI 中测试 Electron 应用

使用 @midscene/computer 在无头 Linux CI 中测试 Obsidian（Electron 应用）的完整示例：https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo

示例：

import { agentForComputer } from '@midscene/computer';

// 连接到主显示器
const agent = await agentForComputer({
  aiActionContext: '你正在自动化一个桌面应用。',
});

// 连接到特定显示器
const displays = await ComputerDevice.listDisplays();
const agent2 = await agentForComputer({
  displayId: displays[1].id,
});

示例：通过 RDP 连接远程 Windows 桌面

import { agentForRDPComputer } from '@midscene/computer';

const agent = await agentForRDPComputer({
  aiActionContext:
    'You are controlling a remote Windows desktop over the RDP protocol.',
  host: '10.75.166.249',
  port: 3389,
  username: 'Admin',
  password: 'replace-with-your-password',
  // 可选：把 TCP 连接绑定到这个本地源 IP。
  localAddress: '10.75.166.10',
  ignoreCertificate: true,
});

await agent.aiWaitFor('The remote Windows desktop is visible');
await agent.aiAct('Click the Windows Start button');
await agent.aiAct('Open Settings');

示例：通过 RDP 控制远程 Windows 桌面

一个可直接运行的 Demo：连接远程 Windows，打开「设置」并进入「Windows 更新」，最后输出一份结构化报告：https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo

当运行 Midscene 的机器存在多条出站路由，且 RDP 服务器要求从指定本地源 IP 访问时，可以使用 localAddress。这里传入的是 IP 地址，不是网卡名。

设备管理

ComputerDevice.listDisplays(): Promise<DisplayInfo[]>

列出所有可用显示器。

返回：

interface DisplayInfo {
  id: string;
  name: string;
  primary?: boolean;
}

示例：

import { ComputerDevice } from '@midscene/computer';

const displays = await ComputerDevice.listDisplays();
console.log('可用显示器:', displays);
// [
//   { id: '0', name: '内置显示器', primary: true },
//   { id: '1', name: '外接显示器', primary: false }
// ]

checkComputerEnvironment(): Promise<EnvironmentCheck>

检查计算机环境是否正确配置。

返回：

interface EnvironmentCheck {
  available: boolean;
  error?: string;
  platform: string;
  displays: number;
}

示例：

import { checkComputerEnvironment } from '@midscene/computer';

const env = await checkComputerEnvironment();
console.log('环境检查:', env);

if (!env.available) {
  console.error('环境错误:', env.error);
}

ComputerAgent

ComputerAgent 类继承自 PageAgent<ComputerDevice>，并继承所有通用 agent 方法：

aiAct(action: string)：使用 AI 执行操作
aiQuery(query: string)：使用 AI 提取信息
aiAssert(assertion: string)：使用 AI 断言条件
aiWaitFor(condition: string)：等待条件
aiLocate(description: string)：定位元素
更多...

定位元素后，还可以使用即时操作（Instant Action）进行直接、确定性的控制：

aiTap()、aiDoubleClick()、aiRightClick()、aiHover()：鼠标操作
aiInput()、aiClearInput()、aiKeyboardPress()：键盘操作
aiScroll()：滚动操作

详见通用 API 参考。

可用操作

ComputerDevice 支持以下操作：

鼠标操作

Tap（点击）

在目标位置单击。

await agent.aiAct('点击文件菜单');
await agent.aiAct('点击屏幕中心');

DoubleClick（双击）

在目标位置双击。

await agent.aiAct('双击桌面图标');

RightClick（右键）

右键点击打开上下文菜单。

await agent.aiAct('右键点击桌面');
await agent.aiAct('右键点击文件');

MouseMove（移动鼠标 / 悬停）

将鼠标移动到目标元素上，也就是鼠标悬停（hover），例如用于触发悬停菜单或提示框。

// 自然语言形式（移动鼠标 / 悬停）
await agent.aiAct('移动鼠标到菜单项');

// 即时操作：一次调用完成定位并悬停
await agent.aiHover('菜单项「Products」');

DragAndDrop（拖放）

从一个位置拖动并放到另一个位置。

await agent.aiAct('将文件拖到文件夹');

键盘操作

KeyboardPress（按键）

按键盘按键，可选修饰键。

支持的按键：

普通键：a-z、0-9、Enter、Escape、Space、Tab 等
方向键：ArrowUp、ArrowDown、ArrowLeft、ArrowRight
功能键：F1-F12
修饰键：Command/Cmd（macOS）、Control/Ctrl、Alt、Shift、Win（Windows）
媒体键：VolumeUp、VolumeDown、Mute 等

示例：

// 简单按键
await agent.aiAct('按 Enter');
await agent.aiAct('按 Escape');

// 组合键（平台特定）
if (process.platform === 'darwin') {
  // macOS
  await agent.aiAct('按 Cmd+Space');  // 打开 Spotlight
  await agent.aiAct('按 Cmd+Tab');    // 应用切换器
  await agent.aiAct('按 Cmd+C');      // 复制
  await agent.aiAct('按 Cmd+V');      // 粘贴
} else {
  // Windows/Linux
  await agent.aiAct('按 Windows 键'); // 开始菜单
  await agent.aiAct('按 Alt+Tab');    // 应用切换器
  await agent.aiAct('按 Ctrl+C');     // 复制
  await agent.aiAct('按 Ctrl+V');     // 粘贴
}

// 方向键
await agent.aiAct('按 ArrowDown');
await agent.aiAct('按 ArrowUp');

// 功能键
await agent.aiAct('按 F5');  // 刷新

Input（输入）

在输入框中输入文本。

await agent.aiAct('在搜索框输入 "你好世界"');
await agent.aiAct('输入 "我的文档.txt"');

ClearInput（清空输入）

清空输入框内容。

await agent.aiAct('清空文本框');

滚动操作

滚动屏幕或特定区域。

// 滚动方向
await agent.aiAct('向下滚动');
await agent.aiAct('向上滚动');
await agent.aiAct('向左滚动');
await agent.aiAct('向右滚动');

// 滚动到位置
await agent.aiAct('滚动到顶部');
await agent.aiAct('滚动到底部');

显示器操作

ListDisplays（列出显示器）

获取所有已连接显示器的信息。

const displays = await ComputerDevice.listDisplays();

使用 RDP 时，ListDisplays 会把当前远程会话视为单个显示器返回。

示例

打开应用并导航

import { agentForComputer } from '@midscene/computer';

const agent = await agentForComputer();

// 打开应用
if (process.platform === 'darwin') {
  await agent.aiAct('按 Cmd+Space');
  await agent.aiAct('输入 "文本编辑" 并按回车');
} else {
  await agent.aiAct('按 Windows 键');
  await agent.aiAct('输入 "记事本" 并按回车');
}

await agent.aiWaitFor('文本编辑器窗口可见');

// 输入内容
await agent.aiAct('输入 "你好，Midscene！"');

// 保存文件
if (process.platform === 'darwin') {
  await agent.aiAct('按 Cmd+S');
} else {
  await agent.aiAct('按 Ctrl+S');
}

多显示器工作流

import { ComputerDevice, agentForComputer } from '@midscene/computer';

// 列出显示器
const displays = await ComputerDevice.listDisplays();
console.log(`找到 ${displays.length} 个显示器`);

// 控制主显示器
const agent1 = await agentForComputer({
  displayId: displays[0].id,
});
await agent1.aiAct('将鼠标移动到屏幕中心');

// 控制副显示器
if (displays.length > 1) {
  const agent2 = await agentForComputer({
    displayId: displays[1].id,
  });
  await agent2.aiAct('将鼠标移动到屏幕中心');
}

Web 浏览器自动化

import { agentForComputer } from '@midscene/computer';

const agent = await agentForComputer();

// 打开浏览器
if (process.platform === 'darwin') {
  await agent.aiAct('按 Cmd+Space');
  await agent.aiAct('输入 "Safari" 并按回车');
} else {
  await agent.aiAct('按 Windows 键');
  await agent.aiAct('输入 "Chrome" 并按回车');
}

await agent.aiWaitFor('浏览器窗口已打开');

// 导航
await agent.aiAct('点击地址栏');
await agent.aiAct('输入 "example.com" 并按回车');
await agent.aiWaitFor('页面已加载');

// 提取信息
const title = await agent.aiQuery('string, 获取页面标题');
console.log('页面标题:', title);

TypeScript 类型

import type {
  ComputerAgent,
  ComputerAgentOpt,
  ComputerDevice,
  ComputerDeviceOpt,
  DisplayInfo,
  EnvironmentCheck,
} from '@midscene/computer';

另请参阅

通用 API 参考 - 适用于所有平台的 API
模型配置 - 配置 AI 模型
缓存 - 使用缓存提高性能

#API 参考（PC 桌面）

#Agent 创建

#本机桌面选项

#键盘输入选项

#RDP 选项

#设备管理

#ComputerAgent

#可用操作

#鼠标操作

#Tap（点击）

#DoubleClick（双击）

#RightClick（右键）

#MouseMove（移动鼠标 / 悬停）

#DragAndDrop（拖放）

#键盘操作

#KeyboardPress（按键）

#Input（输入）

#ClearInput（清空输入）

#滚动操作

#显示器操作

#ListDisplays（列出显示器）

#示例

#打开应用并导航

#多显示器工作流

#Web 浏览器自动化

#TypeScript 类型

#另请参阅

API 参考（PC 桌面）

Agent 创建

本机桌面选项

键盘输入选项

RDP 选项

设备管理

ComputerAgent

可用操作

鼠标操作

Tap（点击）

DoubleClick（双击）

RightClick（右键）

MouseMove（移动鼠标 / 悬停）

DragAndDrop（拖放）

键盘操作

KeyboardPress（按键）

Input（输入）

ClearInput（清空输入）

滚动操作

显示器操作

ListDisplays（列出显示器）

示例

打开应用并导航

多显示器工作流

Web 浏览器自动化

TypeScript 类型

另请参阅