Desktop Agent 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, 'left');

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

// 双击一下鼠标
await session.computer.click_mouse(500, 300, 'double_left');

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

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

拖拽鼠标

// 从起始坐标拖拽到目标坐标
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 参数说明：

方法

createSession()

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

async createSession(): Promise<Session>

返回值：

Session 对象

• computer 对象

返回值说明

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

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

move_mouse(x, y)

移动鼠标到指定坐标。

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

在指定位置点击鼠标。

提示

• pressMode=true&releaseMode=true：鼠标点下又松开

• pressMode=false&releaseMode=false：鼠标点下又松开

• pressMode=true&releaseMode=false`：鼠标点下不松开

• pressMode=false&releaseMode=true：鼠标松开

drag_mouse(startX, startY, endX, endY)

拖拽鼠标。

scroll(startX, startY, direction, amount)

滚动页面。

press_key(key)

按下键盘按键。

type_text(text)

输入文本。

screen_shot()

截取屏幕。

get_cursor_position()

获取当前鼠标位置。

• close()

• 关闭当前会话。

• 返回值： 关闭结果

FAQ

常见错误码

Keywords

none