• 简体中文

      • 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 用于截图功能。

      无头 Linux（CI 环境）：要在无头 Linux 服务器（如 GitHub Actions）上运行桌面自动化，需安装 Xvfb 及其依赖，然后启用 headless 模式：

      # 安装依赖
sudo apt-get install -y xvfb x11-xserver-utils imagemagick
      // 方式 1：传入 headless 选项
const agent = await agentFromComputer({ headless: true });

// 方式 2：设置环境变量
// MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts

      Xvfb 会创建一个虚拟显示器，使鼠标、键盘和截图操作在没有物理显示器的情况下正常工作。详见 API 参考。

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

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

      试用 Playground（零代码）

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

      1. 启动 Playground CLI：
      npx --yes @midscene/computer-playground
      1. 点击 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);
}

      下一步