使用脚本

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

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

内置示例包含一次完成的动作、可交互的元素查询面板、菜单项触发，以及声明式 workflow。你可以直接运行它们，也可以复制一份作为自己的起点。

脚本就是一个 .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.");
}

添加脚本

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

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

可直接运行和修改的示例脚本与 workflow。
供编辑器自动补全使用的类型声明。
一份 AGENTS.md，向 AI 编程助手说明脚本结构和 API 约定；你可以直接让它帮你创建或修改脚本。

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

用编辑器写得更轻松

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

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

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

让脚本成为命令

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

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

创建声明式 Workflow

当一个命令只是按顺序执行内置步骤，不需要 JavaScript 逻辑、state 或 form 时，可以使用 .workflow.json 文件。将它直接放在与 .js 文件相同的脚本文件夹中。workflow 需要 name、description 和 steps 数组：

{
  "name": "Open a menu item",
  "description": "Triggers a menu item in the active app.",
  "steps": [
    {
      "type": "triggerMenuItem",
      "menuPath": ["File", "New Window"]
    }
  ]
}

步骤会按顺序执行。可用的步骤类型是 keyCombination、mouseClick、mouseDown、mouseUp、elementMode 和 triggerMenuItem。

键盘步骤在 key 中使用 macOS 虚拟按键码；鼠标步骤在 button 中使用 left、right 或 middle。两者都可在 modifiers 中使用 command、control、option 和 shift。
elementMode 可选用 rootSelector 和 filterSelectors。workflow 会等待你选择元素；取消选择会取消整个 workflow。
triggerMenuItem 接受由菜单标题组成的完整 menuPath，并且只会触发当前应用中最后一个菜单项。

可以从内置的 example.toolbar-click.workflow.json 和 example.menu-item.workflow.json 开始。workflow 会和脚本一起显示在 设置 > 脚本 中，因此同样可以录制命令序列或设置快捷键。

脚本类型

通过 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.hideForm()` 隐藏面板，并保留会话和当前状态供下次触发时继续使用。
再次显示时刷新	在 `run(ctx)` 中调用 `ctx.onFormActivate(callback)`，在已隐藏的 `panel` 再次显示时运行同步或 `async` 回调。
关闭面板	在完成、取消或发生无法恢复的错误后调用 `ctx.closeForm()`。

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

form 默认使用 panel，适合可停留、可反复操作的小工具。按下 Esc 或标题栏的黄色按钮会隐藏 panel；再次触发同一个脚本时，会显示原来的表单并保留之前的状态。红色按钮与 Command + W 则会关闭 panel 并结束会话。

async form 会立即打开窗口，并在初始 run(ctx) 准备表单项期间显示加载指示器。这个初始 form run 没有超时限制。若已隐藏的 panel 在下次触发时需要刷新临时 state，请使用 ctx.onFormActivate(...)；它不会在首次显示时运行。

将 presentation 设为 transient，它会更像一次短暂的输入面板：离开焦点后自动关闭。Transient form 不会保留隐藏的会话。

使用场景

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

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

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

激活某个应用的窗口

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

用 toast 提供即时反馈

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

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

权限

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

权限	用途
`accessibilityAPI`	查找应用、窗口和界面元素，或操作元素。
`clipboard`	读取或替换系统剪贴板中的纯文本。
`keyboard`	模拟按键。
`mouse`	移动和点击指针。
`shell`	运行非交互式 zsh 命令。

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

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