computer-use 插件的API 和使用方法

现在我已经完整了解了 computer-use 插件的全部 API 和使用方法。以下是详细的使用示例说明：

Computer Use 插件使用指南

Computer Use 插件可以通过 @oai/sky 库自动化控制 Windows 应用程序的 UI，支持截图、点击、输入、滚动、拖拽等操作，即使窗口被遮挡也能工作。

初始化

每次使用前需要先初始化 sky 对象：

if (!globalThis.sky) {
  const { sky } = await import("@oai/sky");
  globalThis.sky = sky;
}

示例 1：列出所有已打开的应用和窗口

globalThis.apps = await sky.list_apps();
nodeRepl.write(JSON.stringify(apps, null, 2));

示例 2：选择目标窗口并激活

// 假设从 list_apps 结果中找到记事本
globalThis.targetApp = apps.find((app) => app.id === "notepad.exe");
globalThis.targetWindow = await sky.get_window({
  id: targetApp.windows[0].id,
  app: targetApp.windows[0].app,
});
await sky.activate_window({ window: targetWindow });

示例 3：获取窗口状态（截图 + 无障碍树）

globalThis.state = await sky.get_window_state({
  window: targetWindow,
  include_screenshot: true,
  include_text: true,
});
globalThis.targetWindow = state.window;
// 查看无障碍树中的元素索引
nodeRepl.write(String(state.accessibility?.tree || ""));

示例 4：点击元素（通过无障碍树索引）

// element_index 来自上一步无障碍树中看到的索引号
await sky.click({ window: targetWindow, element_index: 12 });

示例 4b：点击坐标

// 基于窗口相对坐标点击
await sky.click({ window: targetWindow, x: 200, y: 150 });

示例 5：输入文本

await sky.type_text({ window: targetWindow, text: "Hello, World!" });

示例 6：按键 / 快捷键

// 按回车
await sky.press_key({ window: targetWindow, key: "Return" });

// Ctrl+A 全选
await sky.press_key({ window: targetWindow, key: "Control_L+a" });

// Ctrl+C 复制
await sky.press_key({ window: targetWindow, key: "Control_L+c" });

// Ctrl+V 粘贴
await sky.press_key({ window: targetWindow, key: "Control_L+v" });

示例 7：滚动

// 在窗口内 (x:400, y:300) 位置向下滚动 600 像素
await sky.scroll({
  window: targetWindow,
  x: 400,
  y: 300,
  scrollX: 0,
  scrollY: 600,
});

示例 8：拖拽

// 从 (100, 200) 拖拽到 (300, 400)
await sky.drag({
  window: targetWindow,
  from_x: 100,
  from_y: 200,
  to_x: 300,
  to_y: 400,
});

示例 9：设置输入框的值

// 替换某个可编辑元素的值（element_index 来自无障碍树）
await sky.set_value({ window: targetWindow, element_index: 5, value: "新内容" });

示例 10：执行辅助操作（如展开/折叠）

await sky.perform_secondary_action({
  window: targetWindow,
  element_index: 8,
  action: "Expand",  // 可选: Raise, Scroll Up, Scroll Down, Expand, Collapse 等
});

示例 11：启动一个应用

// 通过 app id 启动
await sky.launch_app({ app: "notepad.exe" });

// 或通过完整 exe 路径启动
await sky.launch_app({ app: "C:\\Program Files\\MyApp\\app.exe" });

核心工作流模式（观察 → 操作 → 刷新）

这是最推荐的使用模式，每次操作后都要重新获取窗口状态：

// 第 1 步：观察
globalThis.state = await sky.get_window_state({
  window: targetWindow,
  include_screenshot: true,
  include_text: true,
});
nodeRepl.write(String(state.accessibility?.tree));

// 第 2 步：执行一个操作
await sky.click({ window: targetWindow, element_index: 12 });

// 第 3 步：刷新状态（必须！索引和坐标在状态变化后失效）
globalThis.state = await sky.get_window_state({
  window: targetWindow,
  include_screenshot: true,
  include_text: true,
});
nodeRepl.write(String(state.accessibility?.tree));

重要注意事项

• 每次操作后必须刷新状态：元素索引、截图 ID、坐标在窗口状态变化后都会失效
• 不要自动化终端应用（CMD、PowerShell、Windows Terminal）
• 不要使用 Windows 键或涉及 Windows 键的快捷键
• 不要自动化密码输入或安全对话框
• 对于浏览器自动化，推荐使用 Browser Use 插件而非 Computer Use
• 涉及删除数据、发送消息、财务操作等高风险动作需要用户确认