PC 桌面入门指南

本指南将引导您完成使用 Midscene 自动化 PC 桌面应用所需的一切：安装依赖、配置模型凭据并运行您的第一个 JavaScript 脚本。

示例项目

使用 JavaScript 控制 PC 桌面：https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo

集成 Vitest 进行测试：https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo

配置 AI 模型服务

将你的模型配置写入环境变量，可参考模型策略了解更多细节。

export MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
export MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
export MIDSCENE_MODEL_NAME="替换为你的模型名称"
export MIDSCENE_MODEL_FAMILY="替换为你的模型系列"

更多配置信息请参考模型策略和模型配置。

系统要求

Node.js

需要 Node.js 18.19.0 或更高版本。

平台特定依赖

macOS：需要辅助功能权限才能控制键盘和鼠标。首次运行脚本时，macOS 会提示你授予访问权限。前往 系统设置 > 隐私与安全性 > 辅助功能，为运行脚本的应用程序（如 Terminal、iTerm2、VS Code、WebStorm 或其他 IDE）启用权限。更多详情请参阅 nut.js macOS 设置。

Linux：需要安装 ImageMagick 用于截图功能。

试用 Playground（零代码）

Playground 是验证连接、观察 AI Agent 的最快方式，无需编写代码。它与 @midscene/computer 共享相同的代码实现，因此在 Playground 上验证通过的流程，用脚本运行时也完全一致。

启动 Playground CLI：

npx --yes @midscene/computer-playground

点击 Playground 窗口中的齿轮按钮，粘贴你的 API Key 配置。如果还没有 API Key，请回到模型配置获取。

开始体验

配置完成后，你可以立即开始体验 Midscene。它提供了多个关键操作 Tab：

Act: 与网页进行交互，这就是自动规划（Auto Planning），对应于 aiAct 方法。比如

在搜索框中输入 Midscene，执行搜索，跳转到第一条结果

填写完整的注册表单，注意主要让所有字段通过校验

Query: 从界面中提取 JSON 结构的数据，对应于 aiQuery 方法。

类似的方法还有 aiBoolean(), aiNumber(), aiString()，用于直接提取布尔值、数字和字符串。

提取页面中的用户 ID，返回 { id: string } 结构的 JSON 数据

Assert: 理解页面，进行断言，如果不满足则抛出错误，对应于 aiAssert 方法。

页面上存在一个登录按钮，它的下方有一个用户协议的链接

Tap: 在某个元素上点击，这就是即时操作（Instant Action），对应于 aiTap 方法。

点击登录按钮

关于自动规划（Auto Planning）和即时操作（Instant Action）的区别，请参考 API 文档。

与 Midscene Agent 集成

当 Playground 运行正常后，就可以切换到可复用的 JavaScript 脚本。

步骤 1. 安装依赖

npm

yarn

pnpm

bun

deno

npm install @midscene/computer

步骤 2. 编写您的第一个脚本

创建 example.ts：

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

(async () => {
  // 创建 agent
  const agent = await agentFromComputer({
    aiActionContext: '你正在控制一台桌面计算机。',
  });

  // 截图并查询信息
  const screenInfo = await agent.aiQuery(
    '{width: number, height: number}, 获取屏幕分辨率'
  );
  console.log('屏幕分辨率:', screenInfo);

  // 移动鼠标到中心
  await agent.aiAct('将鼠标移动到屏幕中心');

  // 断言屏幕有内容
  await agent.aiAssert('屏幕有可见内容');

  console.log('桌面自动化完成！');
})();

步骤 3. 运行脚本

npx tsx example.ts

多显示器支持

如果您有多个显示器，可以控制特定的显示器：

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

// 列出所有显示器
const displays = await ComputerDevice.listDisplays();
console.log('可用显示器:', displays);

// 连接到特定显示器
const agent = await agentFromComputer({
  displayId: displays[0].id,
});

使用示例

基本鼠标操作

// 在屏幕中心点击
await agent.aiAct('在屏幕中心点击鼠标');

// 移动鼠标到特定位置
await agent.aiAct('将鼠标移动到左上角');

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

// 右键
await agent.aiAct('右键打开上下文菜单');

键盘操作

// 输入文本
await agent.aiAct('输入 "你好世界"');

// 按快捷键
if (process.platform === 'darwin') {
  await agent.aiAct('按 Cmd+Space 打开 Spotlight');
  await agent.aiAct('输入 "计算器" 并按回车');
} else {
  await agent.aiAct('按 Windows 键');
  await agent.aiAct('输入 "计算器" 并按回车');
}

// 按功能键
await agent.aiAct('按 Escape');
await agent.aiAct('按 Enter');

查询信息

// 提取屏幕信息
const info = await agent.aiQuery(
  '{hasDesktop: boolean, visibleApps: string[]}, 检查桌面是否可见并列出可见应用'
);

// 定位元素
const position = await agent.aiLocate('文件菜单');
console.log('文件菜单位置:', position);

复杂工作流

// 打开应用并与之交互
await agent.aiAct('打开访达');
await agent.aiWaitFor('访达窗口可见');

await agent.aiAct('点击文稿文件夹');
await agent.aiAct('按 Cmd+N 创建新文件夹');
await agent.aiAct('输入 "我的项目"');
await agent.aiAct('按回车');

await agent.aiAssert('存在名为 "我的项目" 的文件夹');

环境检查

您可以检查系统是否正确配置：

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

const env = await checkComputerEnvironment();
console.log('平台:', env.platform);
console.log('可用:', env.available);
console.log('显示器数量:', env.displays);

if (!env.available) {
  console.error('环境不可用:', env.error);
}

#PC 桌面入门指南

#配置 AI 模型服务

#系统要求

#Node.js

#平台特定依赖

#试用 Playground（零代码）

#开始体验

#与 Midscene Agent 集成

#步骤 1. 安装依赖

#步骤 2. 编写您的第一个脚本

#步骤 3. 运行脚本

#多显示器支持

#使用示例

#基本鼠标操作

#键盘操作

#查询信息

#复杂工作流

#环境检查

#下一步