脚本 API

本页按使用场景整理脚本 API。需要在 VSCode 中查看实时自动补全和完整签名时，请在脚本首行加入：

/// <reference path="./.cursorcrane/cursorcrane.d.ts" />

脚本开头

每个脚本都需要 meta 和 run(ctx)：

/** @type {CursorCrane.Meta} */
const meta = {
    type: "action",
    name: "Example",
    permissions: [],
};

/** @param {CursorCrane.Context} ctx */
async function run(ctx) {
    ctx.toast("Done");
}

meta 字段	说明
type	"action" 执行一次动作；"form" 打开表单。
presentation	form 可选。"panel" 适合持续使用；"transient" 失焦后关闭。
name	脚本在 Cursor Crane 中显示的名称。
permissions	脚本需要的权限。

可用权限是 "accessibilityAPI"、"keyboard" 与 "mouse"。没有声明某项权限时，对应 API 不可使用。

找到应用和窗口

ctx.applicationManager 用于查看运行中的应用：

成员	用途
applications	所有可用应用。
getApplicationByBundleIdentifier(id)	按 bundle identifier 找应用。
getApplicationByPid(pid)	按进程 ID 找应用。

每个 Application 都有 name、bundleIdentifier 和 pid。

ctx.windowManager 用于寻找和切换窗口：

方法	用途
getWindowsByPid(pid)	取得某个应用的窗口。
getWindowsByBundleIdentifier(id)	按应用查窗口。
getWindowById(windowId)	按窗口 ID 查找。
getActiveWindow()	当前正在使用的窗口。
getPreviousWindow()	上一个使用过的窗口。
activateWindow(windowId)	切换到指定窗口。

Window 包含 title、windowId 和所属的 application。

找到和操作界面元素

ctx.elementInspector.getElementByPid(pid) 取得一个应用的界面元素入口，需要 accessibilityAPI 权限。之后可以从应用的 getWindows() 找到窗口，再继续查找按钮、文本框或列表项。

const application = ctx.elementInspector.getElementByPid(window.application.pid);
const root = application?.getWindows().find(
    item => item.windowId === window.windowId
);
const saveButton = root?.queryElements('Button[title="Save"]')[0];

Element 信息

属性	用途
title	元素提供的标题。
displayTitle	更适合展示给用户看的标题。
label、description	元素的补充说明。
kind	元素类型，例如 Button 或 TextField。
windowId	元素所在窗口的 ID。
rect / frame	元素在屏幕上的位置与尺寸。

Element 遍历与查询

方法	用途
getChildren()	取得直接子元素。
getVisibleChildren()	取得当前可见的子元素。
getParent()	取得父元素。
getFocusedWindow()	取得应用当前聚焦的窗口。
getWindows()	取得应用的窗口。
getWindow()	取得元素所在窗口。
queryElements(selector, maxCount?)	搜索窗口中的所有元素。会遍历 children；元素层级很大时，可能造成明显阻塞。
queryVisibleElement(selector, maxCount?)	只搜索当前可见的内容。
getStringValue()	以文字读取元素当前的值，例如文本框中的内容。
getIntValue()	以整数读取元素当前的值。
getDoubleValue()	以小数读取元素当前的值。

选择器写法见元素选择器。

Element 操作

以下方法需要 accessibilityAPI 权限，并且可以 await：

方法	用途
performPress()	触发元素的主要操作。
setStringValue(value)	以文字为元素设置新值。
setIntValue(value)	以整数为元素设置新值。
setDoubleValue(value)	以小数为元素设置新值。
performClick()	移动到元素并点击。
performMoveCursorTo()	移动到元素。
performShowMenu()	打开元素的菜单。
getActions()	查看元素支持的操作。
performAction(identifier)	触发指定操作。

读取或设置元素的值时，请按元素实际使用的值类型选择相应的方法。

键盘、鼠标和提示

ctx.keyboard

需要 keyboard 权限。三个方法都返回 Promise：

await ctx.keyboard.pressKey("a", ["command"]);
await ctx.keyboard.releaseKey("a", ["command"]);
await ctx.keyboard.pressAndReleaseKey("return", []);

修饰键可使用 "shift"、"control"、"option" 和 "command"。

ctx.mouse

需要 mouse 权限：

方法	用途
moveTo(x, y)	平滑移动指针。
warpTo(x, y)	立即移动指针。
click(button, modifiers?)	点击；0 为左键、1 为右键、2 为中键。
doubleClick(button, modifiers?)	双击。
rightClick(modifiers?)	右键点击。

ctx.shell

需要 shell 权限。execute(command) 会运行一条非交互式 zsh 命令，并返回其输出：

const result = await ctx.shell.execute("git status --short");
if (result.exitCode === 0) {
  ctx.toast(result.stdout || "Working tree is clean");
}

返回值包含 stdout、stderr 和 exitCode。命令与脚本共用执行超时，每一路输出最多保留 1 MiB。

ctx.toast 与 ctx.logger

ctx.toast(message) 用于简短反馈。ctx.toast.highlight(rect, text?, timeout?) 会高亮屏幕上的一个范围，并在下方显示可选提示文字。

ctx.toast("Finished");
ctx.toast.highlight(element.rect, "Save button", 3);

ctx.logger.log()、error()、warn()、info() 和 debug() 会写入脚本日志，适合在开发脚本时查看过程与错误。

创建表单

form 脚本从 run(ctx) 返回一个数组。每项都需要唯一的 id：

function run(ctx) {
    return [
        {
            id: "selector",
            kind: "textInput",
            title: "Selector",
            value: "Button",
        },
        {
            id: "run",
            kind: "button",
            title: "Query",
            submit: true,
            onClick: formCtx => {
                formCtx.toast(`Searching for ${formCtx.formData.selector}`);
            },
        },
    ];
}

kind	常用字段	适合什么
label	text、value?	展示说明或结果。
numberInput	title、value?、min?、max?、step?	输入数字。
textInput	title、value?、placeholder?	输入单行文字。
select	title、value?、options	从列表中选择。
checkbox	title?、value?	勾选一个选项。
toggle	title?、value?	开关一个选项。
button	title、submit?、onClick?	执行操作。

可编辑项可以提供 onChange(newValue, ctx)；按钮使用 onClick(ctx)。两者都可以是 async 函数。

form 的 ctx 还提供：

成员	用途
formData	读取当前表单的值。
updateForm(items)	用新的表单内容替换当前表单。未提供 value 的同名项目会保留用户当前输入。
closeForm()	关闭当前表单。

用户可以使用 Tab、Shift + Tab 和方向键在表单中移动焦点。聚焦按钮后按 Enter 或 Space 会触发它；标记为 submit: true 的按钮可用 Command + Enter 从任意位置触发。

出错时

在开发脚本时，可以用 try / catch 显示清楚的提示：

try {
    await ctx.mouse.moveTo(100, 100);
} catch (error) {
    ctx.toast(String(error));
}

如果调用了没有声明权限的 API、选择器写错，或目标暂时不可用，Cursor Crane 会让这次调用失败。给常见失败情况加上 toast 或表单中的说明，脚本会更容易使用。