@midscene/computer 是一个强大的、基于视觉的PC桌面自动化工具。它允许你使用自然语言，通过AI来控制整个桌面——包括鼠标、键盘和屏幕——从而实现Windows、macOS和Linux上任何应用的自动化。

它的核心理念是让AI看懂屏幕并理解你的意图，而不是像传统工具那样依赖复杂的代码或元素定位器。你可以告诉它你的目标，比如"帮我发一条推文"，它就会自动规划和执行一系列操作（如打开浏览器、输入文字、点击按钮）。

核心功能：AI如何驱动你的桌面

@midscene/computer 的核心能力可以分为两大块：底层控制和上层AI驱动。

跨平台桌面控制

它封装了所有基础的桌面交互能力，让你可以直接通过代码或AI来控制-1-2：

• 鼠标操作：单击、双击、右键、移动、拖放。

• 键盘输入：输入文本，模拟 Cmd/Ctrl+C、Enter、Escape 等组合键。

• 屏幕：捕获任意显示器的截图。

• 多显示器支持：可以指定在哪个显示器上执行操作-2。

AI驱动的自动化

这是它最亮眼的部分。你不需要写详细的步骤，只需描述任务，AI就会理解并执行。// 告诉AI你的目标，它会自己规划步骤

await agent.aiAct('打开系统设置，找到并点击"显示器"');
await agent.aiAct('在文件管理器中，帮我创建一个名叫"周报"的文件夹');

• 提取信息 (aiQuery)：让AI看懂屏幕，并返回结构化的数据。

  // 提取屏幕信息
  const screenInfo = await agent.aiQuery('{width: number, height: number}, 当前屏幕的分辨率是多少？');
  console.log('屏幕分辨率:', screenInfo);
  
  // 或者定位特定元素的位置
  const fileMenuPos = await agent.aiLocate('屏幕顶部的"文件"菜单');

• 智能断言 (aiAssert)：验证屏幕上是否出现了预期的内容。

  await agent.aiAssert('桌面上是否有一个名为 "新建文件夹" 的图标？');

快速上手

使用 @midscene/computer 在你的项目中进行自动化，通常只需要简单的三步。

环境准备

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

• 平台权限：

  • macOS：需要为运行脚本的终端或IDE（如 VS Code、iTerm2）开启"辅助功能"权限。

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

  • 无头Linux环境：如果需要在CI服务器上运行，还需要配置 Xvfb 来创建虚拟显示器。

安装与配置

1. 在项目中安装核心包：

   npm install @midscene/computer

2. 配置AI模型的API密钥。你需要通过环境变量告诉它使用哪个视觉模型：

   export MIDSCENE_MODEL_API_KEY="你的API密钥"
   export MIDSCENE_MODEL_NAME="你的模型名称" # 例如 qwen-vl-max
   export MIDSCENE_MODEL_BASE_URL="你的服务地址/v1"

编写第一个脚本

创建一个 example.ts 文件，写下这段代码，你就能感受到AI自动化的魅力：

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

(async () => {
  // 1. 创建一个"代理"来控制你的电脑
  const agent = await agentFromComputer({
    aiActionContext: '你现在控制着一台电脑。',
  });

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

  // 3. 让AI移动鼠标到屏幕中心
  await agent.aiAct('把鼠标移动到屏幕正中间');

  // 4. 断言屏幕上是否能看到内容
  await agent.aiAssert('屏幕上应该能看到内容');

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

运行脚本 npx tsx example.ts，你会看到AI开始一步步执行你的指令。

API概览

@midscene/computer 提供了非常直观的API，主要分为两类：AI驱动的智能接口和底层控制接口。

• AI驱动接口（核心）

 agent.aiAct(prompt)：执行一个由自然语言描述的任务或步骤。

agent.aiQuery(prompt)：从屏幕中提取结构化的JSON数据。

agent.aiAssert(assertion)：断言屏幕状态，失败则抛出错误。

agent.aiLocate(prompt)：定位屏幕上特定元素的位置坐标。

agent.aiWaitFor(assertion)：等待直到某个断言条件成立。 

• 底层控制接口（精确操作）

 agent.mouse.move(x, y)：将鼠标移动到绝对坐标。

agent.keyboard.type(text)：直接输入一段文本。

agent.screenshot()：捕获当前屏幕截图。 

高级玩法：MCP集成

除了作为JavaScript库使用，@midscene/computer 还是一个 MCP (Model Context Protocol) 服务器。

这意味着它可以作为一套标准的"工具"，被任何支持MCP的AI助手（如 Claude Desktop、Cursor IDE）所调用。

• 工作原理：@midscene/computer/mcp-server 会将 aiTap, aiInput, aiQuery 等能力封装成一个个MCP工具。

• 应用场景：你可以在Cursor中直接对AI说："帮我把这个文件夹里的所有图片重命名"，AI助手就会通过MCP调用 @midscene/computer 来操作你的电脑文件管理器，真正实现"用嘴编程。

总的来说，@midscene/computer 通过AI视觉技术，将复杂的UI自动化从"告诉计算机怎么做"变成了"告诉计算机做什么"，极大地降低了门槛并提高了效率。