本文介绍如何通过 AIuse 云电脑 SDK 接入桌面自动化能力。SDK 适合由业务服务主动创建会话、编排桌面操作流程、批量执行标准化任务的场景。

当前 SDK 面向 Node.js 服务端或可信 Node.js 运行环境，不建议直接在浏览器前端、移动端客户端或用户可反编译的安装包中保存 AccessKey Secret。

适用场景

• 业务系统需要主动创建会话并执行桌面操作。

• 需要在代码中编排鼠标、键盘、截图和文件操作。

• 需要将 AIuse 云电脑能力集成到自有调度系统、自动化平台或智能应用服务中。

• 需要对任务流程、错误处理、重试策略和资源释放进行精细控制。

如果使用 Qoder 或其他支持 MCP 的客户端直接调用工具，建议参考《通过 MCP 接入》。

前提条件

Node.js 安装方式如下：

1. 打开 Node.js 官网下载页面

2. 选择维护期内的 LTS 版本安装包

3. 按安装向导完成安装

4. 安装完成后重新打开终端

5. 依次执行 node -v 和 npx -v，确认命令可正常使用

如果本地已安装 Node.js，但仍无法执行 npx，请检查：

1. Node.js 是否安装完整

2. 当前终端是否已重新打开

3. Node.js 安装目录是否已加入系统 PATH

接入流程

1. 开通 AIuse 云电脑服务。

2. 创建 AccessKey，并关联可操作的云电脑。

3. 在项目中安装 SDK。

4. 创建 Client 实例。

5. 创建 Session。

6. 调用 Computer Use 或 FileSystem 能力。

7. 任务完成后关闭 Session。

安装 SDK

npm install @ctyun/desktop-agent-sdk

也可以使用 yarn 或 pnpm：

yarn add @ctyun/desktop-agent-sdk
pnpm add @ctyun/desktop-agent-sdk

基础示例

import Client from '@ctyun/desktop-agent-sdk';

async function main() {
  const client = new Client({
    apiKey: process.env.AIUSE_API_KEY,
    apiSecret: process.env.AIUSE_API_SECRET,
    desktopCode: process.env.AIUSE_DESKTOP_CODE,
    serviceURL: process.env.AIUSE_SERVICE_URL || 'https://desk.ctyun.cn:8816'
  });

  const session = await client.createSession();

  try {
    await session.computer.move_mouse({ x: 500, y: 300 });
    await session.computer.click_mouse({ x: 500, y: 300 });
    await session.computer.type_text({ text: 'Hello from AIuse' });
    const screenshot = await session.computer.screen_shot();
    console.log('screenshot result:', screenshot);
  } finally {
    await session.close();
  }
}

main().catch(console.error);

关键配置

返回结构

SDK 方法通常返回如下结构：

{
  "code": 0,
  "data": null,
  "msg": null
}

code 为 0 通常表示调用成功，data 为业务结果，msg 为失败时的错误信息。

安全建议

• 不要将 AccessKey ID 和 AccessKey Secret 写入前端页面、客户端安装包或公开代码仓库。

• 建议通过环境变量、密钥管理系统或服务端配置中心注入密钥。

• 不同项目、环境和任务批次建议使用不同 AccessKey，便于权限隔离和审计。

• AccessKey 不再使用时，应先禁用并确认无任务依赖后再删除。

下一步

• 了解 SDK 中的关键对象，请参见《核心概念》。

• 查看鼠标、键盘和截图能力，请参见《图形用户界面自动化》。

• 查看文件读写能力，请参见《文件系统》。

• 查看完整 API，请参见《方法参考》。