使用脚本

脚本可以把 Cursor Crane 还没有内置的工作流，变成你自己的命令或小工具。例如你可以：

一键把指针移到当前窗口的中心，或移动到某个界面元素。
找到常用应用中的按钮、列表项或文本框，再点击或触发它的操作。
模拟一组按键或鼠标点击，把重复步骤收成一次触发。
做一个临时的小面板，让你输入条件、选择目标，再显示查询结果。

内置的两个示例分别展示了前两种方向：一个一次完成动作，另一个提供可交互的查询面板。你可以直接运行它们，也可以复制一份作为自己的起点。

脚本就是一个 .js 文件。它需要提供名称、所需权限和一个 run(ctx) 函数；需要等待操作完成时，直接使用 async / await 即可。

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

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

/** @param {CursorCrane.Context} ctx */
function run(ctx) {
    ctx.toast("Hello from Cursor Crane.");
}

添加脚本

打开 Settings > Scripts。这里会显示当前脚本文件夹、已经找到的脚本，以及每个脚本可用的命令序列和快捷键。

第一次使用默认文件夹时，Cursor Crane 会为你准备好：

两个可直接运行和修改的示例脚本。
VSCode 自动补全所需的类型声明。

你可以在设置中选择其他文件夹、在 Finder 中打开它，或在新增、修改脚本后点击刷新。脚本文件直接放在所选文件夹中即可。

用 VSCode 写得更轻松

在脚本第一行加入下面这句：

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

随后输入 ctx.、ctx.mouse. 或 element. 时，VSCode 会提示可用方法和参数。默认脚本文件夹会自动准备这份声明文件；使用自定义文件夹时，在 Settings > Scripts 点击 Install Type Declarations 即可。

让脚本成为命令

每个可用脚本都会出现在 Settings > Scripts。你可以像设置内置命令一样，为它录制命令序列或设置全局快捷键。

命令序列只能使用英文字母。
如果与已有命令或其他脚本冲突，设置界面会提示你。
脚本文件暂时移走后，对应命令不会触发；放回同名文件后即可继续使用。

脚本类型

通过 meta.type 选择脚本的体验：

类型	适合什么场景	`run(ctx)` 要做什么
`action`	一次完成的动作。	执行操作即可。
`form`	需要输入、选择或展示结果的小工具。	返回一个表单项数组。

动作脚本

动作脚本适合不需要额外输入的流程。触发后，它可以读取当前状态、完成操作，再用 toast 告诉用户结果。内置的 example.center-cursor-to-active-window.js 就是这种类型：它找到当前窗口，移动指针，并显示窗口信息。

表单脚本

form 适合把一个或多个窗口中的相关元素、选项和结果汇集起来，形成一个可交互的原生表单。它可以让用户输入条件、选择目标，并在同一个面板中继续查看和操作结果。run(ctx) 返回一组表单项，Cursor Crane 会将它渲染成原生界面。

你可以组合这些表单项：

label 用于显示说明、状态或结果。
numberInput 和 textInput 用于输入数字或文字。
select 用于从选项中选择。
checkbox 和 toggle 用于开关选项。
button 用于触发下一步操作。

form 的 ctx 除了常规 API 外，还提供三个重要能力：

能力	如何使用
读取当前输入	从 `ctx.formData` 按表单项的 `id` 读取值。
响应用户操作	为输入项提供 `onChange`，为按钮提供 `onClick`。回调会拿到当前 form `ctx`。
更新界面	调用 `ctx.updateForm(...)` 提供一整组新的表单项，例如把“正在查询”替换为结果按钮。
关闭面板	在完成、取消或发生无法恢复的错误后调用 `ctx.closeForm()`。

onChange 特别适合根据用户选择显示或隐藏更多输入项；onClick 则适合执行查询、提交或操作元素。更新表单时，保留相同 id 且不提供新 value 的项目，会继续保留用户已经输入的值。

form 默认使用 panel，适合可停留、可反复操作的小工具。将 presentation 设为 transient，它会更像一次短暂的输入面板：离开焦点后自动关闭。

使用场景

操作当前窗口中的特定元素

你可以为当前窗口编写“找到并操作某个元素”的脚本：例如寻找可用的按钮、特定标题的文本框，或列表中的一行。你可以自行通过子元素逐层查找，也可以使用元素选择器直接描述目标。找到后可以点击、触发它提供的操作，或者先高亮它，让用户确认目标无误。这样，某个应用里经常要找的按钮就可以变成一个命令；也可以先在 form 中列出多个结果，再让用户选择。

元素如何被描述和查找，见元素选择器。

激活某个应用的窗口

你可以按应用名称对应的 bundle identifier 找到应用，再选择并激活它的某个窗口。它适合在多个窗口之间来回切换的工作流，例如快速回到聊天窗口、笔记窗口或某个固定的开发工具窗口。

用 toast 提供即时反馈

你可以在动作完成后用 ctx.toast(...) 显示一句确认、错误原因或目标信息；也可以在 form 无法继续时告诉用户下一步该做什么。

你还可以用 ctx.toast.highlight(...) 高亮元素范围，并在高亮框下方显示提示文字。它很适合让用户确认脚本找到或操作的是屏幕上的哪个目标。

权限

脚本只需声明真正会用到的权限：

权限	用途
`accessibilityAPI`	查找应用、窗口和界面元素，或操作元素。
`keyboard`	模拟按键。
`mouse`	移动和点击指针。

例如，只显示 toast 的脚本可以使用 permissions: []；查询元素的脚本需要 accessibilityAPI。只运行你信任、看得懂来源的脚本。

更多 API 说明请查看脚本 API。