@ctyun/desktop-agent-sdk 0.0.1

package/README.md

@@ -0,0 +1,420 @@
+# Desktop Agent SDK
+
+用于操作天翼云电脑的一套SDK，支持鼠标控制、键盘输入、屏幕截图等操作。
+
+## 项目简介
+
+`@ctyun/desktop-agent-sdk` 是天翼云电脑远程操作 SDK，第三方开发者可以通过该 SDK 以编程方式控制远程桌面。支持以下功能：
+
+- 鼠标移动、点击、拖拽和滚动
+- 键盘按键和文本输入
+- 屏幕截图
+- 获取鼠标位置
+
+## 安装方法
+
+### npm 安装
+
+```bash
+npm install @ctyun/desktop-agent-sdk
+```
+
+### yarn 安装
+
+```bash
+yarn add @ctyun/desktop-agent-sdk
+```
+
+### pnpm 安装
+
+```bash
+pnpm add @ctyun/desktop-agent-sdk
+```
+
+## 基本使用方法
+
+### 3.1 创建 Client 实例
+
+首先导入并创建 Client 实例。创建实例时需要提供以下参数：
+
+- `apiKey` (必需): 控制台上的AccessKey ID
+- `apiSecret` (必需): 控制台上的AccessKey Secret
+- `desktopCode` (必需): 桌面编码
+- `serviceURL` (可选): 服务地址，默认为 `https://desk.ctyun.cn:8816`
+
+```javascript
+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' // 可选，使用默认值
+});
+```
+
+### 3.2 创建会话
+
+使用 `createSession()` 方法创建会话，会话创建成功后将返回会话对象，包含 sessionId 和操作方法。
+
+```javascript
+const session = await client.createSession();
+console.log('会话创建成功，sessionId:', session.sessionId);
+```
+
+### 3.3 使用 computer 方法
+
+创建会话后，可以通过 `session.computer` 对象调用各种计算机控制方法。
+
+#### 移动鼠标
+
+```javascript
+// 将鼠标移动到指定坐标
+await session.computer.move_mouse(500, 300);
+```
+
+#### 点击鼠标
+
+```javascript
+// 在指定坐标点击鼠标（默认左键、按下并释放）
+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');
+```
+
+#### 按下和释放鼠标
+
+```javascript
+// 按下鼠标
+await session.computer.press_mouse(500, 300, 'left');
+
+// 释放鼠标
+await session.computer.release_mouse(500, 300, 'left');
+```
+
+#### 拖拽鼠标
+
+```javascript
+// 从起始坐标拖拽到目标坐标
+await session.computer.drag_mouse(500, 300, 800, 500);
+```
+
+#### 滚动
+
+```javascript
+// 在指定位置滚动（Direction: 'up' 或 'down'）
+await session.computer.scroll(500, 300, 'down', 3);
+```
+
+#### 按下键盘按键
+
+```javascript
+// 按下键盘按键（如 Enter）
+await session.computer.press_key('Enter');
+```
+
+#### 输入文本
+
+```javascript
+// 输入文本
+await session.computer.type_text('Hello World');
+```
+
+#### 屏幕截图
+
+```javascript
+// 截取屏幕
+await session.computer.screen_shot();
+```
+
+#### 获取鼠标位置
+
+```javascript
+// 获取当前鼠标位置
+await session.computer.get_cursor_position();
+```
+
+### 3.4 查询任务状态
+
+对于异步执行的操作，可以使用 `query_job()` 方法查询任务执行状态和结果。
+
+```javascript
+// 假设某个操作返回了 jobId
+const jobId = 'your-job-id';
+
+// 查询任务状态
+const result = await session.query_job(jobId);
+console.log('任务状态:', result);
+```
+
+### 3.5 关闭会话
+
+使用完成后，应该关闭会话以释放资源。
+
+```javascript
+await session.close();
+console.log('会话已关闭');
+```
+
+## 完整示例
+
+```javascript
+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();
+```
+
+## 4、API 参考
+
+### Client 类
+
+#### 构造函数
+
+```typescript
+new Client(options: ClientOptions): Client
+```
+
+**ClientOptions 参数说明：**
+
+| 参数名 | 类型 | 必需 | 说明 |
+|--------|------|------|------|
+| apiKey | string | 是 | 控制台上的AccessKey ID [打开控制台](https://desk.ctyun.cn/cloudB/) |
+| apiSecret | string | 是 | 控制台上的AccessKey Secret |
+| desktopCode | string | 是 | 桌面编码，控制台可查看 |
+| serviceURL | string | 否 | 服务地址，默认 `https://desk.ctyun.cn:8816` |
+
+#### 方法
+
+##### createSession()
+
+创建会话并返回会话对象。
+
+```typescript
+async createSession(): Promise<Session>
+```
+
+**返回值：**
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| sessionId | string | 会话唯一标识 |
+| computer | ComputerAPI | 计算机控制方法集合 |
+| query_job | Function | 查询任务状态方法 |
+| close | Function | 关闭会话方法 |
+
+### Session 对象
+
+- #### computer 对象
+
+#### 返回值说明
+对computer类下面的所有方法的调用都是**异步调用**，返回值遵循相同的返回格式：
+``` json
+{
+   "code": 0,
+   "data": {
+      "requestId": "",
+      "sessionId": "",
+      "desktopCode": "",
+      "jobId": "",
+      "jobStatus": 1,
+      "jobRollInterval": 100,
+      "jobRollTimes": 16
+  }
+}
+```
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| requestId | string | 本次请求的ID |
+| sessionId | number | 会话ID，同`createSession`返回值相同 |
+| desktopCode | number | 桌面编码 |
+| jobId | number | 本次请求的任务ID，用于后续轮询查看结果 |
+| jobStatus | number | 任务状态:<br/>-1:未响应<br/> 1:接收成功<br/>2:接收失败<br/>3:执行成功<br/>4:执行失败|
+| jobRollIntervalMs | number | 建议的轮询间隔，单位：ms |
+| jobRollTimes | number | 建议的轮询次数 |
+
+你可以通过这里返回的`jobId`轮询调用query_job方法，拿到对应操作的执行结果。
+
+##### 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'` |
+| 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()
+
+截取屏幕。
+
+**返回值：** 
+通过query_job轮询查询结果
+
+##### get_cursor_position()
+
+获取当前鼠标位置。
+
+**返回值：** 
+通过query_job轮询查询结果
+
+- #### query_job(jobId)
+
+查询异步任务执行结果。
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| jobId | string | 任务 ID |
+
+**返回值：**
+``` json
+{
+    "code": 0,
+    "data": {
+        "requestId": "",
+        "desktopCode": "",
+        "sessionId": "",
+        "jobId": "",
+        "jobStatus": 1,
+        "resp": ""
+    }
+}
+```
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| requestId | string | 本次请求的ID |
+| sessionId | number | 会话ID，同`createSession`返回值相同 |
+| desktopCode | number | 桌面编码 |
+| jobId | number | 本次查询的任务ID |
+| jobStatus | number | 任务状态:<br/>-1:未响应<br/> 1:接收成功<br/>2:接收失败<br/>3:执行成功<br/>4:执行失败|
+| resp | string | 操作的执行结果返回值 |
+
+**示例：** 执行屏幕截图
+``` javascript
+  ...创建client和session
+  const res = await session.computer.screen_shot();
+  const {jobId,jobRollIntervalMs,jobRollTimes}=res.data
+
+  let n_roll_times=0
+  const do_query_job=async ()=>{
+      if(n_roll_times>jobRollTimes) return 
+      const result=await session.query_job(jobId)
+      const {jobStatus,resp}=result.data
+      if(resp) console.log("操作结果是："+resp)
+      else setTimeout(()=>do_query_job(),jobRollIntervalMs)
+  }
+  setTimeout(()=>do_query_job(),jobRollIntervalMs)
+  
+```
+
+- #### close()
+
+关闭当前会话。
+
+**返回值：** 关闭结果

package/dist/index.cjs.js

@@ -0,0 +1,2 @@
+/*! @ctyun/desktop-agent-sdk v0.0.1 | (c) 2026-02-05 zhangjiliang | https://desk.ctyun.cn/html/download/ */
+"use strict";var e=require("axios"),s=require("node:crypto");const t=e.create({baseURL:"/api/openApi"});var o={createSeesion:function(e,s){return t.post("/cdserv/aiUse/createSeesion",e,{...s})},sendMessage:function(e,s){return t.post("/cdserv/aiUse/sendMessage",e,{...s})},queryJob:function(e,s){return t.post("/cdserv/aiUse/queryJob",e,{...s})},deleteSession:function(e,s){return t.post("/cdserv/aiUse/deleteSession",e,{...s})}};const r=e=>{const t="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=s.randomBytes(e);let r="";for(let e=0;e<o.length;e++)r+=t[o[e]%62];return r.slice(0,e)},i=e=>{const{path:t,body:o,apiKey:i,apiSecret:n}=e;let a={};const c=t.indexOf("?");-1!==c&&(a=(e=>{if(!e)return{};let s={},t=e.split("&");for(let e=0;e<t.length;e++){let o=t[e].split("=");s[o[0]]=o[1]}return s})(t.slice(c+1)));const d={"x-ctg-ecpc-ak":i,"x-ctg-algorithm":"SHA256","x-ctg-timestamp":(new Date).getTime(),"x-ctg-nonStr":r(8)};o&&(d["x-ctg-reqJson"]=(e=>{const t=s.createHash("md5");return t.update(e),t.digest("hex")})(JSON.stringify(o)));const p=Object.assign({},a,d),u=[],h=Object.keys(p);h.sort(),h.forEach(e=>{u.push(`${e}=${p[e]}`)});const l=u.join("&")+n;return d.sign=(e=>{const t=s.createHash("sha256");return t.update(e),t.digest("hex")})(l),d},n=(e,t)=>{const o=s.createCipheriv("aes-256-cbc",t,"0000000000000000");let r=o.update(e,"utf8","base64");return r+=o.final("base64"),r};var a=Object.freeze({__proto__:null,click_mouse:(e,s,t="left",o="down")=>({action:"ClickMouse",params:{PositionX:e,PositionY:s,Button:t,Press:"down"==o,Release:"up"==o}}),drag_mouse:(e,s,t,o)=>({action:"DragMouse",params:{SourceX:e,SourceY:s,TargetX:t,TargetY:o}}),get_cursor_position:()=>({action:"GetCursorPosition"}),move_mouse:(e,s)=>({action:"MoveMouse",params:{PositionX:e,PositionY:s}}),press_key:e=>({action:"PressKey",params:{Key:e}}),press_mouse:(e,s,t="left")=>({action:"PressMouse",params:{PositionX:e,PositionY:s,Button:t}}),release_mouse:(e,s,t="left")=>({action:"ReleaseMouse",params:{PositionX:e,PositionY:s,Button:t}}),screen_shot:()=>({action:"TakeScreenshot"}),scroll:(e,s,t,o)=>({action:"Scroll",params:{PositionX:e,PositionY:s,Direction:t,Amount:o}}),type_text:e=>({action:"TypeText",params:{Text:e}})});const c=(e,s)=>{const{apiKey:t,apiSecret:o,path:r}=s;return{headers:i({path:r||"",body:e,apiKey:t,apiSecret:o}),body:e}};module.exports=class{constructor(e={}){this.options=Object.assign({serviceURL:"https://desk.ctyun.cn:8816"},e);const{apiKey:s,apiSecret:t,desktopCode:o,serviceURL:r}=this.options;if(!s||!t)throw new Error("apiKey或apiSecret不能为空");if(!r)throw new Error("serviceURL不能为空");if(!o)throw new Error("desktopCode不能为空")}async createSession(){const{apiKey:e,apiSecret:s,desktopCode:t,serviceURL:i}=this.options,d={requestId:r(32),desktopCode:t};c(d,{apiKey:e,apiSecret:s});const p=this.sessionId="test-session-id",u=Object.keys(a).reduce((d,u)=>(d[u]=async(...d)=>{if(!this.sessionId)throw new Error("会话已关闭或未创建");const h=a[u](...d),l=r(32),y={requestId:l,desktopCode:t,sessionId:p,message:n(JSON.stringify(h),l)},{headers:g,body:m}=c(y,{apiKey:e,apiSecret:s});return(await o.sendMessage(m,{headers:g,baseURL:i})).data},d),{});return{sessionId:p,query_job:async n=>{if(!this.sessionId)throw new Error("会话已关闭或未创建");const a={requestId:r(32),desktopCode:t,sessionId:p,jobId:n},{headers:d,body:u}=c(a,{apiKey:e,apiSecret:s});return(await o.queryJob(u,{headers:d,baseURL:i})).data},close:async()=>{if(!this.sessionId)return;const n={requestId:r(32),desktopCode:t,sessionId:p},{headers:a,body:d}=c(n,{apiKey:e,apiSecret:s}),u=await o.deleteSession(d,{headers:a,baseURL:i});return this.sessionId=null,u.data},computer:u}}};

package/dist/index.esm.js

@@ -0,0 +1,2 @@
+/*! @ctyun/desktop-agent-sdk v0.0.1 | (c) 2026-02-05 zhangjiliang | https://desk.ctyun.cn/html/download/ */
+import e from"axios";import s from"node:crypto";const t=e.create({baseURL:"/api/openApi"});var o={createSeesion:function(e,s){return t.post("/cdserv/aiUse/createSeesion",e,{...s})},sendMessage:function(e,s){return t.post("/cdserv/aiUse/sendMessage",e,{...s})},queryJob:function(e,s){return t.post("/cdserv/aiUse/queryJob",e,{...s})},deleteSession:function(e,s){return t.post("/cdserv/aiUse/deleteSession",e,{...s})}};const r=e=>{const t="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",o=s.randomBytes(e);let r="";for(let e=0;e<o.length;e++)r+=t[o[e]%62];return r.slice(0,e)},i=e=>{const{path:t,body:o,apiKey:i,apiSecret:n}=e;let a={};const c=t.indexOf("?");-1!==c&&(a=(e=>{if(!e)return{};let s={},t=e.split("&");for(let e=0;e<t.length;e++){let o=t[e].split("=");s[o[0]]=o[1]}return s})(t.slice(c+1)));const d={"x-ctg-ecpc-ak":i,"x-ctg-algorithm":"SHA256","x-ctg-timestamp":(new Date).getTime(),"x-ctg-nonStr":r(8)};o&&(d["x-ctg-reqJson"]=(e=>{const t=s.createHash("md5");return t.update(e),t.digest("hex")})(JSON.stringify(o)));const p=Object.assign({},a,d),u=[],h=Object.keys(p);h.sort(),h.forEach(e=>{u.push(`${e}=${p[e]}`)});const l=u.join("&")+n;return d.sign=(e=>{const t=s.createHash("sha256");return t.update(e),t.digest("hex")})(l),d},n=(e,t)=>{const o=s.createCipheriv("aes-256-cbc",t,"0000000000000000");let r=o.update(e,"utf8","base64");return r+=o.final("base64"),r};var a=Object.freeze({__proto__:null,click_mouse:(e,s,t="left",o="down")=>({action:"ClickMouse",params:{PositionX:e,PositionY:s,Button:t,Press:"down"==o,Release:"up"==o}}),drag_mouse:(e,s,t,o)=>({action:"DragMouse",params:{SourceX:e,SourceY:s,TargetX:t,TargetY:o}}),get_cursor_position:()=>({action:"GetCursorPosition"}),move_mouse:(e,s)=>({action:"MoveMouse",params:{PositionX:e,PositionY:s}}),press_key:e=>({action:"PressKey",params:{Key:e}}),press_mouse:(e,s,t="left")=>({action:"PressMouse",params:{PositionX:e,PositionY:s,Button:t}}),release_mouse:(e,s,t="left")=>({action:"ReleaseMouse",params:{PositionX:e,PositionY:s,Button:t}}),screen_shot:()=>({action:"TakeScreenshot"}),scroll:(e,s,t,o)=>({action:"Scroll",params:{PositionX:e,PositionY:s,Direction:t,Amount:o}}),type_text:e=>({action:"TypeText",params:{Text:e}})});const c=(e,s)=>{const{apiKey:t,apiSecret:o,path:r}=s;return{headers:i({path:r||"",body:e,apiKey:t,apiSecret:o}),body:e}};class d{constructor(e={}){this.options=Object.assign({serviceURL:"https://desk.ctyun.cn:8816"},e);const{apiKey:s,apiSecret:t,desktopCode:o,serviceURL:r}=this.options;if(!s||!t)throw new Error("apiKey或apiSecret不能为空");if(!r)throw new Error("serviceURL不能为空");if(!o)throw new Error("desktopCode不能为空")}async createSession(){const{apiKey:e,apiSecret:s,desktopCode:t,serviceURL:i}=this.options,d={requestId:r(32),desktopCode:t};c(d,{apiKey:e,apiSecret:s});const p=this.sessionId="test-session-id",u=Object.keys(a).reduce((d,u)=>(d[u]=async(...d)=>{if(!this.sessionId)throw new Error("会话已关闭或未创建");const h=a[u](...d),l=r(32),y={requestId:l,desktopCode:t,sessionId:p,message:n(JSON.stringify(h),l)},{headers:m,body:f}=c(y,{apiKey:e,apiSecret:s});return(await o.sendMessage(f,{headers:m,baseURL:i})).data},d),{});return{sessionId:p,query_job:async n=>{if(!this.sessionId)throw new Error("会话已关闭或未创建");const a={requestId:r(32),desktopCode:t,sessionId:p,jobId:n},{headers:d,body:u}=c(a,{apiKey:e,apiSecret:s});return(await o.queryJob(u,{headers:d,baseURL:i})).data},close:async()=>{if(!this.sessionId)return;const n={requestId:r(32),desktopCode:t,sessionId:p},{headers:a,body:d}=c(n,{apiKey:e,apiSecret:s}),u=await o.deleteSession(d,{headers:a,baseURL:i});return this.sessionId=null,u.data},computer:u}}}export{d as default};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ctyun/desktop-agent-sdk",
+  "version": "0.0.1",
+  "description": "the agent web sdk to interactive with your computer",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js",
+      "default": "./dist/index.cjs.js"
+    }
+  },
+  "author": "zhangjiliang",
+  "homepage": "https://desk.ctyun.cn/html/download/",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c rollup.config.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "rollup": "^4.55.1",
+    "rollup-plugin-delete": "^3.0.2",
+    "rollup-plugin-license": "^3.6.0"
+  },
+  "dependencies": {
+    "axios": "^1.13.4"
+  }
+}