Client

Client 是 SDK 的入口对象，用于保存服务地址、AccessKey、桌面编码等连接配置，并负责创建会话。

创建 Client 时通常需要传入以下参数：

示例：

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

const client = new Client({
  apiKey: process.env.AIUSE_API_KEY,
  apiSecret: process.env.AIUSE_API_SECRET,
  desktopCode: process.env.AIUSE_DESKTOP_CODE
});

Session

Session 表示一次与云电脑的操作会话。创建会话后，可以通过会话对象调用 Computer Use 或 FileSystem 能力。

const session = await client.createSession();

任务结束后，应主动关闭会话：

await session.close();

ComputerAPI

ComputerAPI 用于执行 GUI 操作，典型方法包括：

• move_mouse

• click_mouse

• press_mouse

• release_mouse

• drag_mouse

• scroll

• press_key

• type_text

• screen_shot

• get_cursor_position

FileSystemAPI

FileSystemAPI 用于执行文件操作，当前版本开放的接口包括：

• create_directory

• read_file

• write_file

• move_file

• search_files

会话生命周期

推荐的会话生命周期如下：

1. 创建 Client。

2. 创建 Session。

3. 调用工具方法。

4. 捕获并处理异常。

5. 在 finally 中关闭 Session。

let session;

try {
  session = await client.createSession();
  await session.computer.type_text({ text: 'hello' });
} finally {
  if (session) {
    await session.close();
  }
}

调用结果

SDK 方法通常返回结构化结果：

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

code 为 0 通常表示成功，非 0 表示失败。调用方应根据错误码、错误信息和任务上下文进行处理。

文件读写能力

FileSystem 的 read_file 和 write_file 面向文本文件读写场景：

• read_file 支持按偏移量和长度读取文本内容。

• write_file 支持覆盖、追加和仅新建写入。

• 较大文本内容由 SDK 和服务自动处理，调用方无需关注内部传输方式。

调用方通常只需要传入文件路径和文本内容即可。