Desktop Agent SDK

用于操作天翼云电脑的一套SDK，支持鼠标控制、键盘输入、屏幕截图等操作。

项目简介

@ctyun/desktop-agent-sdk 是天翼云电脑远程操作 SDK，第三方开发者可以通过该 SDK 以编程方式控制远程桌面。支持以下功能：

• 鼠标移动、点击、拖拽和滚动
• 键盘按键和文本输入
• 屏幕截图
• 获取鼠标位置

安装方法

npm 安装

npm install @ctyun/desktop-agent-sdk

yarn 安装

yarn add @ctyun/desktop-agent-sdk

pnpm 安装

pnpm add @ctyun/desktop-agent-sdk

基本使用方法

1、 创建 Client 实例

首先导入并创建 Client 实例。创建实例时需要提供以下参数：

• apiKey (必需): 控制台上的AccessKey ID
• apiSecret (必需): 控制台上的AccessKey Secret
• desktopCode (必需): 桌面编码
• serviceURL (可选): 服务地址，默认为 https://desk.ctyun.cn:8816

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

const client = new Client({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  desktopCode: 'your-desktop-code',
  serviceURL: 'https://desk.ctyun.cn:8816' // 可选，使用默认值
});

2、 创建会话

使用 createSession() 方法创建会话，会话创建成功后将返回会话对象，包含 sessionId 和操作方法。

const session = await client.createSession();
console.log('会话创建成功，sessionId:', session.sessionId);

3、 使用 computer 方法

创建会话后，可以通过 session.computer 对象调用各种计算机控制方法。

移动鼠标

// 将鼠标移动到指定坐标
await session.computer.move_mouse(500, 300);

点击鼠标

// 在指定坐标点击鼠标（默认左键、按下并释放）
await session.computer.click_mouse(500, 300);

// 点击右键
await session.computer.click_mouse(500, 300, 'right');

// 仅按下鼠标（不释放）
await session.computer.click_mouse(500, 300, 'left', 'down');

// 仅释放鼠标
await session.computer.click_mouse(500, 300, 'left', 'up');

按下和释放鼠标

// 按下鼠标
await session.computer.press_mouse(500, 300, 'left');

// 释放鼠标
await session.computer.release_mouse(500, 300, 'left');

拖拽鼠标

// 从起始坐标拖拽到目标坐标
await session.computer.drag_mouse(500, 300, 800, 500);

滚动

// 在指定位置滚动（Direction: 'up' 或 'down'）
await session.computer.scroll(500, 300, 'down', 3);

按下键盘按键

// 按下键盘按键（如 Enter）
await session.computer.press_key('Enter');

输入文本

// 输入文本
await session.computer.type_text('Hello World');

屏幕截图

// 截取屏幕
await session.computer.screen_shot();

获取鼠标位置

// 获取当前鼠标位置
await session.computer.get_cursor_position();

4、 关闭会话

使用完成后，应该关闭会话以释放资源。

await session.close();
console.log('会话已关闭');

完整示例

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

async function main() {
  // 创建 Client 实例
  const client = new Client({
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret',
    desktopCode: 'your-desktop-code'
  });

  let session=null;
  try {
    // 创建会话
    session = await client.createSession();
    console.log('会话创建成功:', session.sessionId);

    // 移动鼠标并点击
    await session.computer.move_mouse(500, 300);
    await session.computer.click_mouse(500, 300);

    // 输入文本
    await session.computer.type_text('Hello from Desktop Agent SDK!');

    // 截图
    await session.computer.screen_shot();
  } catch (error) {
    console.error('操作失败:', error);
  } finally {
    // 关闭会话
    await session.close();
  }
}

main();

API 参考

Client 类

构造函数

new Client(options: ClientOptions): Client

ClientOptions 参数说明：

| 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | apiKey | string | 是 | 控制台上的AccessKey ID 打开控制台 | | apiSecret | string | 是 | 控制台上的AccessKey Secret | | desktopCode | string | 是 | 桌面编码，控制台可查看 | | serviceURL | string | 否 | 服务地址，默认 https://desk.ctyun.cn:8816 |

方法

createSession()

创建会话并返回会话对象。

async createSession(): Promise<Session>

返回值：

| 属性名 | 类型 | 说明 | |--------|------|------| | sessionId | string | 会话唯一标识 | | computer | ComputerAPI | 计算机控制方法集合 | | close | Function | 关闭会话方法 |

Session 对象

• computer 对象

返回值说明

对computer类下面的所有方法的调用都是异步调用，返回值遵循相同的返回格式：

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

| 参数名 | 类型 | 说明 | |--------|------|------| | code | number | 状态码，为0代表成功，其他表示失败 | | data | number | 结果，code为0时不为空 | | msg | number | code不为0时记录错误信息 |

move_mouse(x, y)

移动鼠标到指定坐标。

| 参数名 | 类型 | 说明 | |--------|------|------| | x | number | 目标 X 坐标 | | y | number | 目标 Y 坐标 |

click_mouse(x, y, clickMode?, pressMode?)

在指定位置点击鼠标。

| 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | x | number | 是 | X 坐标 | | y | number | 是 | Y 坐标 | | clickMode | string | 否 | 点击模式：'left'(默认)、'right'、'middle'、double_left | | pressMode | string | 否 | 按下模式：'down'、'up'，不传则按下并释放 |

press_mouse(x, y, pressMode?)

按下鼠标。

| 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | x | number | 是 | X 坐标 | | y | number | 是 | Y 坐标 | | pressMode | string | 否 | 按键模式：'left'(默认)、'right'、'middle' |

release_mouse(x, y, releaseMode?)

释放鼠标。

| 参数名 | 类型 | 必需 | 说明 | |--------|------|------|------| | x | number | 是 | X 坐标 | | y | number | 是 | Y 坐标 | | releaseMode | string | 否 | 释放模式：'left'(默认)、'right'、'middle' |

drag_mouse(startX, startY, endX, endY)

拖拽鼠标。

| 参数名 | 类型 | 说明 | |--------|------|------| | startX | number | 起始 X 坐标 | | startY | number | 起始 Y 坐标 | | endX | number | 目标 X 坐标 | | endY | number | 目标 Y 坐标 |

scroll(startX, startY, direction, amount)

滚动页面。

| 参数名 | 类型 | 说明 | |--------|------|------| | startX | number | 滚动位置 X 坐标 | | startY | number | 滚动位置 Y 坐标 | | direction | string | 滚动方向：'up' 或 'down' | | amount | number | 滚动量，单位：px |

press_key(key)

按下键盘按键。

| 参数名 | 类型 | 说明 | |--------|------|------| | key | string | 按键名称，如 'Enter'、'Escape' 等 |

type_text(text)

输入文本。

| 参数名 | 类型 | 说明 | |--------|------|------| | text | string | 要输入的文本内容 |

screen_shot()

截取屏幕。

get_cursor_position()

获取当前鼠标位置。

• close()

关闭当前会话。

返回值： 关闭结果