Mac快捷指令自动化：实践者参考指南（2026）

简而言之：自macOS Monterey（2021年）起，每台Mac都预装了Shortcuts；而macOS Tahoe（26）终于补上了Mac自动化用户苦等4年的关键能力：个人自动化，并支持文件夹变化、外置驱动器、Wi-Fi、显示器和应用启动等触发条件。³⁴该应用可通过菜单栏、Spotlight、Finder快速操作和键盘快捷键运行快捷指令，还提供了真正的命令行工具（shortcuts run、list、view、sign）。¹²任何应用都能通过App Intents框架添加操作；Siri、Spotlight和Apple Intelligence调用的也是同一套接口。¹³脚本和AI智能体可通过3种方式驱动快捷指令：CLI、shortcuts:// URL scheme，以及支持脚本控制的Shortcuts Events后台进程。¹⁹¹¹权限模型是首先需要掌握的部分：在应用中可见的同意提示，在无人值守运行时不会显示，却会导致任务悄然停滞。

Apple在WWDC 2021上向开发者表示：“Shortcuts是Mac自动化的未来。”⁵这个未来分两阶段到来。第一阶段随即落地：macOS Monterey带来原生SwiftUI应用、iCloud同步、Automator迁移工具，并在编辑器中全面支持shell脚本和AppleScript。⁵第二阶段又经历了4个macOS版本才得以实现。在macOS Tahoe之前，Mac上的快捷指令只有在被主动调用时才会运行；由于没有触发条件，所谓“自动化”仍意味着您必须记得点击。Tahoe补齐了这块短板：除熟悉的iOS触发条件（Time of Day、Bluetooth）外，还加入了专为Mac设计的个人自动化（文件夹和外置驱动器触发条件），并新增Use Model操作，让Apple Intelligence能够介入快捷指令的数据流。³⁴

由此形成的系统值得深入掌握。2026年的Mac版Shortcuts同时具备4重身份：

1. 无代码编辑器，内置数百种操作，涵盖文件操作、窗口管理和设备端AI等功能
2. 自动化引擎，支持macOS Tahoe新引入的系统事件触发条件
3. 命令行工具体系中的一员：shortcuts run与其他Unix工具一样，支持stdin、stdout、退出代码和管道¹
4. 所有应用的操作注册中心：应用通过App Intents公开的任何功能都会自动出现在Shortcuts中，在Mac和其他平台上皆是如此¹³⁴

从浅尝辄止到熟练运用，关键在于掌握5套系统：操作目录（有哪些功能）、自动化触发条件（何时运行）、CLI和脚本桥接（代码如何调用）、签名与共享（快捷指令如何分发），以及权限模型（无人值守运行为何会停滞）。下文将逐一介绍。

本指南中的每一项论述均以Apple文档、WWDC会议内容，或在撰写本文所用设备上对macOS 26.5（Shortcuts 7.0）的直接检查为依据。如果某项事实直接来自操作系统本身（shortcuts(1)手册页、Shortcuts Events脚本字典、WorkflowKit框架中的操作），引用中会明确说明。

核心要点

• 自动化是重头戏。macOS Tahoe 将个人自动化带到 Mac：文件夹变更、外接驱动器、显示器、Wi-Fi、Bluetooth、Stage Manager、app 启动/退出、一天中的时间等；每项都可立即运行或在确认后运行。³⁴
• CLI 货真价实，并非玩具。shortcuts run "Name" -i input -o output 支持 stdin（-i -）、stdout（-o -）、通过 Uniform Type Identifiers 提供类型化输出，并在成功时退出 0、出错时退出 1。像使用任何 Unix 工具一样通过管道调用即可。¹²
• 三个脚本入口，一条原则。从 shell 和 CI 使用 CLI；仅从其他 app 使用 shortcuts:// URL scheme；当需要在脚本上下文中获取返回结果且不打开 app 时，使用 Shortcuts Events（AppleScript/ScriptingBridge）。¹⁹¹¹
• 签名决定分发。.shortcut 文件必须经过签名才能传播：shortcuts sign -m anyone 会通过 iCloud 进行公证，因此任何人都可导入；默认的 people-who-know-me 模式在本地签名，并将导入限制为在 Contacts 中拥有您联系信息的人员。²⁷
• App Intents 是开发者接口。提供 App Intents 的 app 可免费获得 Mac 上的 Shortcuts actions；这些 intents 同样支持 Spotlight 和自动化，包括安装在 Apple silicon Mac 上的 iOS app。⁴¹³
• 同意授权才是常见故障点。Shortcuts 会针对每个 shortcut、每种数据类型请求“允许一次”/“始终允许”/“不允许”。运行脚本的 actions 受全局“允许运行脚本”开关控制。无人值守运行若遇到尚未回答的提示，只会一直等待。¹⁶⁸

如何使用本指南

目录

第 1 部分：基础

1. Mac 上的 Shortcuts 是什么
2. 运行 Shortcut 的方式
3. Shortcuts 与 Automator、AppleScript 的比较

第 2 部分：Actions

1. Actions 如何组合
2. Actions 目录
3. 脚本 Actions
4. 窗口管理 Actions
5. Use Model Action

第 3 部分：自动化

1. macOS 上的自动化触发器
2. 行之有效的自动化模式

第 4 部分：命令行与 URL Schemes

1. shortcuts CLI
2. 使用 Shortcuts Events 编写 app 脚本
3. URL Schemes

第 5 部分：共享与分发

1. 共享格式与签名

第 6 部分：开发者接口

1. App Intents：app 如何添加 Actions
2. Spotlight 和自动化如何运行您的 Intents
3. 从脚本和 agents 驱动 Shortcuts

第 7 部分：运维与参考

1. 权限与同意授权（TCC）
2. 故障排除
3. 快速参考卡
4. 常见问题
5. 变更日志
6. 参考资料

Mac 上的 Shortcuts 是什么

Shortcuts 是 Apple 的自动化 app：将actions（单一用途的步骤）串联成shortcut（已保存的工作流），然后通过点击、语音、按键、触发器或命令行运行它。Apple 自己的定义值得牢记，因为它解释了整个设计：“Action 是 shortcut 的构建单元。每个 shortcut 由一系列 actions 构成，而每个 action 都是执行特定功能的单一步骤。”¹²

该 app 于 2021 年随 macOS Monterey 登陆 Mac，从 iOS 移植而来，但几乎完全采用 SwiftUI 编写，因此同一套代码库可服务于两个平台。⁵首次发布时的三项设计决策，至今仍定义着 2026 年的 Mac 使用体验：

• iCloud 同步默认开启。在新 Mac 上打开 Shortcuts，您现有的资料库便会出现，并从 iPhone 和 iPad 同步而来。在一台设备上创建的 shortcut 可在其他设备上运行，但平台特有 actions 除外。⁵¹²
• app 提供 actions。“与 iOS 一样，Mac 上的任何 app 都可以为 Shortcuts 提供 actions。”⁵到 2026 年，这条管线由 App Intents framework 提供支持，详见第 6 部分。
• 脚本是一等公民。Monterey 提供“对 AppleScripts 和 Shell Scripting 的完整支持”，并带来“直接内置于 Shortcuts 的新 actions，让您可直接在 Shortcuts 编辑器中编写和运行脚本”。因此，Shortcuts 是对旧有自动化技术栈的封装，而非替代。⁵

Monterey 没有提供的是触发器。从 2021 年到 2024 年，Mac shortcut 只有在被某项操作调用时才会运行。macOS Tahoe（26）在 2025 年改变了这一点：它将个人自动化带到 Mac，新增专为桌面工作流设计的触发器类型（文件夹内容变更、外接驱动器已连接），以及既有的 iOS 触发器集合。³⁴Tahoe 还新增了 Use Model action，可在 shortcut 执行过程中通过 Apple Intelligence models 处理数据。³⁴

版本里程碑：

在本指南中，“已在 macOS 26.5 上验证”表示已直接在用于撰写本指南的 Mac 上，使用 Shortcuts 7.0 进行检查。

运行 Shortcut 的方式

Mac 上的 Shortcuts 提供了异常丰富的入口。以下所有方式都会调用同一个 shortcut；区别在于输入来自何处以及输出落在何处。¹²¹⁰

两个细节能帮您节省后续时间。第一，Quick Action 和 Services 条目会将当前选择内容作为 shortcut 输入，因此文件处理 shortcuts 应声明其可接受的输入类型（编辑器中的“Receive”配置），而不是假定输入为文本。第二，最后三行构成可编程接口；由于它们的输入/输出约定不同，后文将分别介绍。

Shortcuts 与 Automator、AppleScript 的对比

2026年，这3套 Apple 自动化系统仍随 macOS 一同提供（经 macOS 26.5 验证，Automator 仍位于 /System/Applications），而且各有用武之地。一个经得起推敲的定位是：Shortcuts 是集成层，AppleScript 是应用控制语言，Shell 脚本则是计算层。Automator 已进入维护阶段：功能可用、保持不变，并已明确由 Shortcuts 接替。⁵¹⁴

迁移路径确实存在，但在边缘场景中会有所损失。 Apple 在 Shortcuts 中内置了转换器：将 .workflow 文件拖入应用（或按住 Control 点击 → Open With → Shortcuts），即可让“Shortcuts 将大多数 Automator 工作流程转换为可执行相同功能、事件和自动化的快捷指令”。¹⁴¹⁵“大多数”是 Apple 的原话。实际可以理解为：标准的文件、图像和文本操作通常能够顺利转换；生僻的第三方 Automator 操作和 Watch Me Do 录制则容易出现转换效果下降。作为这套兼容机制的一部分，Shortcuts 的内部甚至仍保留了 Watch Me Do 操作名称（可在框架的操作表中看到，经 macOS 26.5 验证）。¹⁶

何时需要超越 Shortcuts。 深入控制单个应用（遍历 Mail 邮件、以编程方式操控 Finder 窗口、驱动具有丰富脚本字典的应用）仍是 AppleScript 的主场。复杂文本处理、API 编排，以及任何本来就适合用 Python 或 zsh 编写的任务，都应交给脚本。实践中应组合运用，而非拘泥于某一种工具：由快捷指令通过触发器收集输入，交给 Shell 脚本完成繁重工作，再使用原生操作发送通知和放置文件，便能取长补短。脚本操作一节将介绍具体方法。

操作如何组合

每个快捷指令都是一条流水线。每项操作接收输入（通常是上一项操作的输出），完成一项任务，然后生成输出。以下3种机制让流水线具备强大的表达能力：

• 魔法变量。 每项操作的输出都会自动作为变量供后续操作使用，无需声明。点击参数字段，选择 Select Magic Variable，再选择任意先前操作的输出。Set Variable 和 Get Variable 可用于显式命名，Add to Variable 则用于累积列表（这3项均为内置操作，经 macOS 26.5 验证）。¹⁶
• 内容类型，按需转换。 操作会声明其接受的内容类型（文件、图像、文本、URL、日期）。当输出与输入类型不同时，Shortcuts 会尽可能自动转换：例如，将网页传给文本操作，即可获得页面文本。快捷指令编辑器顶部的“Receive”配置用于声明整个快捷指令可从 Quick Actions、Services 或 CLI 的 --input-path 接收哪些内容。
• 将流程控制作为操作。 If、Repeat、Repeat with Each、Choose from Menu、Wait to Return、Stop This Shortcut 和 Stop and Output 都是普通操作。¹⁶ Stop and Output 在 Mac 上尤为重要：它定义了快捷指令向命令行、管道或调用脚本返回的内容。¹

组合操作的基础是 Run Shortcut：一个快捷指令按名称调用另一个快捷指令，并向其传递输入。¹⁶ Apple 明确建议，嵌套快捷指令时应使用该操作，而非 URL scheme：“如果要从一个快捷指令运行另一个快捷指令，请使用 Run Shortcut 操作，而不是 URL scheme。”⁹ 不妨将快捷指令视为函数：创建单一用途的小型快捷指令（如规范化文件名、向 Webhook 发帖、缩放为缩略图），再由一个协调快捷指令进行组合。这种方式远比包含60项操作的单体快捷指令更具扩展性，而且每个部分都能通过 CLI 独立测试。

操作目录

内置操作库规模庞大：macOS 26.5 的 WorkflowKit 框架（Shortcuts 背后的私有框架）内部英文字符串表列出了361个不同的操作名称。¹⁶ 这个数字高于您在编辑器中实际看到的数量，因为该表还包含仅适用于 iOS 的操作，以及应用在 Workflow 时代遗留的集成。以下是与 Mac 相关的操作目录，并按自动化使用者的实际需求进行分类。下列每个操作名称均逐字出现在该表中，经 macOS 26.5 验证。¹⁶

文件与 Finder

系统与应用

Web 与数据

Get Contents of URL 与 Dictionary 操作可以组成一个实用的 REST 客户端：发出请求、解析 JSON 并提取值，全程无需编写代码。负载变得复杂时，建议将任务交给使用 curl 和 jq 的 Shell 脚本，不必在编辑器中费力处理嵌套字典。

文本、图像与媒体

Calendar、Reminders、Contacts、Notes

Find Calendar Events、Add New Calendar、Edit Calendar Event、Find Reminders、New Reminder、Edit Reminder、Find Contacts、Edit Contact、Create New Note、Get Notes、Delete Notes，以及对应的 Get Details of… 操作涵盖了各类生产力应用。¹⁶ Find/Filter + Get Details 是一套典型模式：先查询集合，再从匹配结果中提取字段。

Shortcuts、元操作与流程

关于第6部分中的元自动化，有一点值得注意：Get My Shortcuts 和 Get Details of Shortcut 可让快捷指令枚举指令库，并可与 CLI 端的 shortcuts list 配合，为您的快捷指令集合构建工具。¹⁶²

脚本操作

有5项操作可将 Shortcuts 接入传统自动化体系，而它们全都受同一个全局开关控制。在 Shortcuts → Settings → Advanced 中，必须开启“Allow Running Scripts”，这些操作才能运行；该设置在应用内的说明明确列出了它控制的操作：“启用后，可以运行‘Run AppleScript’、‘Run Shell Script’、‘Run JavaScript for Mac Automation’、‘Run JavaScript on Web Page’和‘Run Script Over SSH’操作”（已在 macOS 26.5 上验证）。⁸¹⁷ Apple 的文档还警告，运行包含脚本的快捷指令可能导致数据丢失——之所以需要此设置，是因为这5项操作会使用完整的用户权限运行，不受普通操作的安全限制保护。⁸

Run Shell Script

主力操作。您可以选择 shell、粘贴脚本，并决定输入的传递方式。这两种输入模式直接来自操作自身的文档：“to stdin：输入将转换为文件并定向到脚本的 stdin 管道。as arguments：输入将转换为字符串列表，并作为参数传递给脚本。”¹⁷

这两种模式的实际含义：

• stdin 模式适合文本和单个文件：类似 pbpaste 的处理方式、通过 jq 处理 JSON，以及任何读取数据流的任务。
• arguments 模式适合多个文件：每个输入项都会进入 "$@"，因此 for f in "$@"; do ... done 能正确处理 Finder 中的选定文件，包括带空格的文件名。
• 输出即脚本写入 stdout 的内容，并会像其他输出一样流向下一项操作。

Run AppleScript 和 Run JavaScript for Mac Automation

两者都会嵌入 Open Scripting Architecture 脚本，分别使用 on run {input, parameters} 入口点（AppleScript）或 run(input, parameters) 函数（JXA）。当任务需要控制其他应用时，应使用它们：例如排列 Finder 窗口、设置 Mail 规则，或处理任何带有脚本字典的应用。返回值会成为该操作的输出。

Run Script Over SSH

在远程主机上运行 shell 脚本，主机、端口、用户和认证信息均在操作中配置。它与 CLI 的强大用途相互呼应：办公室中的 Mac 可以向任何能够通过 SSH 访问它的设备提供可重复执行的操作；而快捷指令无需离开 Shortcuts 编辑器，就能将任务推送到 Linux 主机。

Run JavaScript on Web Page

针对当前 Safari 页面运行 JavaScript 并返回结果。Apple 同时通过脚本开关和每次运行时的权限提示来限制它，因为在任意页面上下文中运行 JavaScript 存在数据外泄风险。⁸

窗口管理操作

Shortcuts 在 Mac 上提供原生窗口控制：Find Windows、Move Window 和 Resize Window。¹⁶ 它们看似只是目录中的普通条目，实际上却是不依赖第三方工具、通过键盘驱动窗口布局的基础模块。

• Find Windows 查询打开的窗口（可在编辑器中排序和筛选），并输出窗口对象。
• Move Window 接收一个窗口和一个位置。其参数摘要为“Move ⟨Window⟩ to ⟨Position⟩”，还提供可选的自定义变体：“Move ⟨Window⟩ to ⟨Position⟩ ⟨X Coordinate⟩, ⟨Y Coordinate⟩”（已在 macOS 26.5 上验证）。¹⁶
• Resize Window 接收一个窗口和一个目标：“Resize ⟨Window⟩ to ⟨Configuration⟩”，自定义变体则接受明确的⟨Width⟩×⟨Height⟩。¹⁶

框架字符串表中的内置窗口位置包括：Full Screen、Left、Right、Top、Bottom、三分之一布局（Left Third、Middle Third、Right Third）、角落变体（Top/Bottom Leading 和 Trailing），以及自定义的 Window Location and Size 格式（已在 macOS 26.5 上验证）。¹⁶ 将 Find Windows（最前方窗口）→ Resize Window（Left）与键盘快捷键组合，即可获得一键窗口命令。Split Screen Apps 则能用一项操作处理双应用场景。¹⁶

Use Model 操作

Use Model 是 macOS Tahoe 中新增的操作，也是自移植到 Mac 以来 Apple 加入的最重要单项操作：它会在快捷指令运行过程中将数据发送给 Apple Intelligence 模型，并把响应交给下一项操作。³⁴

根据 Apple 在 WWDC 相关会议中的说明，提供3种模型选择：在 Private Cloud Compute 上运行的大型服务器端模型；用于“无需网络连接的简单请求”的设备端模型；以及适用于“广泛世界知识”的 ChatGPT。⁴

提供3种输出形态，关键在于有意识地选择：⁴

1. 文本（包括富文本），适用于摘要和改写。
2. 字典，适用于结构化提取；Apple 的示例是从发票中提取供应商、金额和日期。字典输出使 Use Model 可组合：下游操作读取字段，而非解析自然语言。
3. App 实体：来自通过 App Intents 暴露实体的应用的内容对象。Apple 将两者的关系概括为：“如果 App Intents 是应用中的操作或动词，那么 App Entities 就是名词。”⁴Use Model 可以直接针对这些名词进行推理（筛选这些笔记、选择相关日历事件）。

Follow Up 开关允许在同一次运行中继续迭代模型响应。⁴

有一项工程上的注意事项：模型输出并不确定，因此相同输入在不同运行中可能产生不同结果。对于自动化，建议使用字典输出形态（受 schema 约束）、简短聚焦的提示词，并在结果接触文件或消息前加入验证步骤（使用 If 操作检查必填字段）。应将 Use Model 视为不稳定的网络调用：很有用，但必须用检查机制包裹起来。

如需了解同一功能的开发者视角（应用应暴露什么，以便 Use Model 能够对其进行推理），请参阅第6部分以及本站的 App Intents 系列，起始文章为App Intents Are Apple’s New API to Your App。

macOS 上的自动化触发器

自动化是附带触发器的快捷指令：“当某事发生时运行此操作”，无需点击。它们在 macOS Tahoe 中来到 Mac；Apple 并未照搬完整的 iOS 列表，而是构建了 Mac 专属触发器：“我们正将个人自动化带到 Mac，提供专为 Mac 构建的文件夹和外置硬盘等新自动化类型，以及您可能已在 iOS 上熟悉的自动化类型，例如 Time of Day 和 Bluetooth。”⁴

可从 Shortcuts app 的 Automation 区域创建。每项自动化将一个触发器、一组操作和一项策略选择结合在一起：Run Immediately（无需交互，这是自动化的核心）或 Run After Confirmation（先通过通知询问）。³¹⁸ 新建自动化时，建议先使用确认模式；待其值得信赖后，再切换为立即运行。

macOS Tahoe 中的触发器目录：³⁴¹⁸

这一设计带来两项变化。首先，Mac 终于拥有 Apple 原生的方案来实现“监视此文件夹并处理其中新增内容”；它能像其他快捷指令一样同步和编辑（Automator 的 Folder Actions 能监视，但无法完成其余部分）。其次，由于自动化会运行快捷指令，本指南中的所有内容都能叠加组合：Folder 触发器可以接入 Run Shell Script；App 触发器可以调用 Use Model；External Drive 触发器可以启动 SSH 任务。

行之有效的自动化模式

以下模式完全由文档中已有的组件组合而成，足以应对日常使用：

热文件夹。 针对~/Inbox的文件夹触发器 → 筛选文件（扩展名为pdf）→ 从图像中提取文本或从 PDF 获取文本 → 使用 Use Model 输出字典（供应商、日期、总额）→ 重命名文件，并将文件移动到分层归档目录中。这个经典的 Automator 用例如今借助设备端提取和模型生成的命名方式焕然一新。³⁴¹⁶

桌面工作坞。 显示器触发器（外接显示器连接）→ 打开工作所需的一组 App → 将窗口移动并调整到预设布局 → 将专注模式设为工作。断开连接时则反向执行。只需一个触发器，无须手动拖动，即可重建整个桌面布局。³¹⁶

素材导入盘。 外置驱动器触发器 → 获取存储卡 DCIM 文件夹的内容 → 按日期筛选文件 → 将文件保存到以日期命名的文件夹 → 显示包含文件数量的通知。此处建议采用确认模式：意外连接的驱动器不应触发批量复制。³¹⁸

通往真正代码的应急出口。 任意触发器 → 运行 Shell 脚本并将输入作为参数传入 → 您现有的脚本。真正有价值的是触发器系统，并不要求逻辑必须由 Shortcuts actions 实现。仅包含两个 actions（触发器 + 脚本）的自动化，即可获得类似 launchd 的事件处理能力，并附带 UI、同步和授权管理。⁸¹⁷

与会议相关的情境。 专注模式触发器（开启工作专注模式）¹⁸ → 设置音量、退出会分散注意力的 App、打开笔记 App。在 System Settings 中启用跨设备共享专注模式后，从 iPhone 开启专注模式时，Mac 也会随之响应。

设计时需要考虑以下限制：自动化仅存在于创建它的 Mac 上。因此，即使快捷指令库本身会同步，在 MacBook 上创建的文件夹自动化也不会在 Mac mini 上触发（每台需要该功能的设备都必须单独设置触发器）。此外，触发器列表中没有“收到 Web 请求”选项（可以从发送端通过 Run Script Over SSH 衔接，或使用由云同步客户端监视的文件夹）。³¹⁸

shortcuts CLI

自 Monterey 起，macOS 就为 Shortcuts 提供了真正的命令行界面：/usr/bin/shortcuts。相关说明见shortcuts(1)和 Apple 用户指南。¹²它包含4个子命令。以下内容均已在 macOS 26.5 上验证。

shortcuts run <shortcut-name-or-identifier> [-i <input-path> ...] [-o <output-path>] [--output-type <UTI>]
shortcuts list [-f <folder-name>] [--folders] [--show-identifiers]
shortcuts view <shortcut-name>
shortcuts sign [-m <mode>] -i <input> -o <output>

shortcuts run

按名称或标识符运行快捷指令。“从命令行运行快捷指令与在 Shortcuts app 中运行并无不同”，¹这意味着它既能完整访问所有 actions，也会显示全部权限提示（请参阅权限）。

Apple 的标准示例会对文件夹中的 JPEG 文件运行一个图像合并快捷指令：¹

shortcuts run "Combine Images" -i ~/Desktop/*.jpg -o ~/Desktop/combined.png

该 CLI 在输入和输出两端都遵循 Unix 约定。退出状态：“shortcuts 命令运行成功时退出状态为0，发生错误时为1。”¹当快捷指令以输出结束，或包含 Stop and Output 时，可以通过管道传递输出：¹

# Pipe shortcut output onward, typed as RTFD
shortcuts run "Make Meeting Notes" --output-type com.apple.rtfd | ...

# Feed stdin in, capture stdout out
echo "quarterly report" | shortcuts run "Slugify" -i - -o -

有一个文档明确指出的陷阱：通过管道将文本传入shortcuts run时，输入内容会被视为文本。“通过管道传递文件路径时，该路径会被视为文本。请使用-i标志，确保输入被视为文件路径。”¹

Apple 还提出了一条值得铭记的设计准则：“最高效的快捷指令不会显示提醒，也不会请求输入。当快捷指令请求输入时，命令行进程会暂停并等待用户输入。”¹对于任何无头运行场景，这种暂停就意味着进程卡死。面向 CLI 的快捷指令应从输入中获取全部参数。

shortcuts list

逐行列出快捷指令名称。--folders改为列出文件夹；-f <folder>将范围限定到某个文件夹（使用“none”表示不属于任何文件夹的快捷指令）；--show-identifiers则在每个快捷指令后附加其 UUID。²标识符对自动化至关重要：名称可能重复，也可能被重命名，而 UUID 不会。shortcuts run接受这两种形式。²

shortcuts list --show-identifiers | grep "Deploy"

shortcuts view

在 Shortcuts 编辑器中打开指定的快捷指令。²这在工具流程末端非常实用：检测到快捷指令失败后，脚本可直接将您带到对应的编辑器中。

shortcuts sign

为.shortcut文件签名以便分发；相关内容与共享格式一并在第5部分介绍。²

使用 Shortcuts Events 编写 App 脚本

第3个程序化接口是脚本接口。Mac 上的 Shortcuts 注册了两个可编写脚本的目标：Shortcuts app 本身，以及一个没有界面的后台辅助程序 Shortcuts Events（bundle identifier 为com.apple.shortcuts.events，已在 macOS 26.5 上验证）。¹¹脚本字典直接说明了为何需要将二者分开：“若要在后台运行快捷指令而不打开 Shortcuts app，请将指令发送给‘Shortcuts Events’，而不是‘Shortcuts’。”¹¹

该字典精简而稳定。快捷指令提供以下可读属性：name、subtitle、id、folder、color、icon、accepts input和action count；文件夹提供name和id；唯一的动词是run，可选传入with input参数，并会返回结果。¹¹

AppleScript：

tell application "Shortcuts Events"
    run shortcut "Slugify" with input "Quarterly Report Draft"
end tell

JXA：

const se = Application("Shortcuts Events");
const result = se.shortcuts.byName("Slugify").run({withInput: "Quarterly Report Draft"});

通过 ScriptingBridge 或 py-applescript 使用 Python 时，针对的是同一接口；使用 PyObjC 的 ScriptingBridge 时，SBApplication.applicationWithBundleIdentifier_("com.apple.shortcuts.events")会返回 App 对象，其shortcuts()集合与上述字典相对应。¹¹

以下情况宜优先使用此接口而非 CLI：当前已处于 AppleScript/JXA 上下文中；希望以原生对象而非序列化 stdout 的形式获取快捷指令结果；或者从能够发送 Apple Events、但不应调用 shell 的 App 中发起运行。宿主进程首次向 Shortcuts Events 发送 Apple Event 时，会触发 macOS 标准的自动化授权提示（System Settings → Privacy & Security → Automation）。在实现无人值守运行之前，还需要先完成这项授权。⁶

该字典还提供整理层面的访问能力（文件夹和快捷指令元数据可读，文件夹归属可写），因此无须操作 UI，即可通过脚本完成快捷指令库的日常维护，例如生成清单报告和审核文件夹。¹¹

URL scheme

Shortcuts 注册了shortcuts:// URL scheme，同时还保留了源自该 App 被收购前历史的旧版workflow://（已在 macOS 26.5 上验证）。¹⁹URL 是供其他 App使用的集成途径，包括启动器、带链接字段的笔记 App，以及任何能够打开 URL 的工具。Apple 的建议直截了当：“只有从 Shortcuts 之外的其他 App 进行集成时，才应通过 URL 运行快捷指令。”⁹

运行快捷指令：⁹

shortcuts://run-shortcut?name=[name]&input=[input]&text=[text]

• name（必需）：经过百分号编码的快捷指令名称。
• input：取值为text或clipboard。使用text时，text参数的值将成为快捷指令输入；使用clipboard时，“将使用剪贴板中的内容”，并忽略text。⁹

shortcuts://run-shortcut?name=Lookup%20Goetta&input=text&text=goetta%20is%20great
shortcuts://run-shortcut?name=Add%20to%20Notes&input=clipboard

x-callback-url 为往返调用增加了响应处理能力：²⁰

shortcuts://x-callback-url/run-shortcut?name=Calculate%20Tip&input=text&text=24.99&x-success=...&x-error=...&x-cancel=...

• 成功时打开x-success，并将快捷指令的文本输出作为result参数附加到 URL。
• 失败时打开x-error，并附带errorMessage参数。
• 用户取消时打开x-cancel，且不提供任何输出。²⁰

在 shell 中也可以使用open "shortcuts://run-shortcut?..."，但此处更推荐shortcuts run：该 CLI 会直接返回退出代码和输出，无须通过 URL 回调迂回传递。此 scheme 在 Mac 上其余的用武之地，主要是 App 间集成以及文档内的链接。

共享格式与签名

Shortcuts有两种传播方式，而两者最终都需要作出信任决定。⁷

iCloud链接。 在应用中：共享→拷贝iCloud链接。任何获得链接的人都能将该快捷指令添加到自己的资料库，因此链接是面向公众发布时门槛最低的方式。链接一经发送，就应视为公开内容。⁷

快捷指令文件。 文件→导出会生成.shortcut文件（UTI为com.apple.shortcut，已在macOS 26.5上验证）。¹⁹⁷ 导出时必须选择信任范围：

• 任何人：“任何人都可以运行您的快捷指令。”Apple会收到快捷指令的副本并进行验证。⁷
• 认识我的人：“只有通讯录中存有您联系信息的人才能运行您的快捷指令。”您的联系信息会嵌入文件，以便执行此项检查。⁷

根据macOS 26.5上的shortcuts(1)，CLI提供相同的两种模式，并明确说明了其工作机制：people-who-know-me“将在本地签名，但只有您的设备或通讯录中存有您联系信息的人才能导入该快捷指令”；而anyone“将通过iCloud进行公证，并允许任何人导入该快捷指令”。²

shortcuts sign -m anyone -i "Deploy Notes.shortcut" -o "Deploy Notes-signed.shortcut"

对于团队和CI，这条命令解决了分发问题：使用-m anyone签名的已导出快捷指令，即使接收者与您素未谋面，也能顺利导入。由于anyone模式通过iCloud进行公证，在将其接入构建流水线之前，请确保会话已登录iCloud并具备网络访问权限。²

导入采用拖放方式：双击.shortcut文件、将其拖入应用，或拖放到Dock图标上；.workflow文件会在导入过程中从Automator格式完成转换。¹⁵ 对于Gallery之外共享的Shortcuts，Apple明确提示：“Apple无法验证私下共享的快捷指令是否真实可信，也无法验证其行为。”⁶ 企业设备群另有专用方式：Apple Configurator支持面向托管工作流的Shortcuts自动化。²¹

设置→高级中还提供了私密共享开关，用于控制是否允许导入私下共享（受联系人限制）的快捷指令；同一位置还包含允许运行脚本和允许共享大量数据。⁶⁸ 收到的快捷指令无法导入，通常可归因于以下原因之一：文件未签名、文件受联系人限制而发送者不在您的通讯录中，或私密共享已停用。

App Intents：应用如何添加操作

到目前为止，目录中的所有内容都来自Apple。资料库的另一半则来自已安装的应用；自2022年以来，实现这套机制统一使用一个框架：App Intents（iOS 16、macOS 13）。¹³ 应用可以定义遵循AppIntent的类型（动词：参数加perform()方法），也可以选择定义AppEntity（名词：应用中具有标识符和显示形式的强类型内容），其余工作交由系统完成。同一套定义会呈现在Shortcuts、Siri、Spotlight、组件和Apple Intelligence中；Shortcuts只是应用意图架构的一种呈现形式，并非独立的集成。¹³⁴

应用在Mac上的呈现方式主要取决于两种采用层级：

• 操作：每个未隐藏的意图都会以操作形式出现在Shortcuts编辑器中，并归于相应应用名称之下，可与本指南介绍的所有内容组合使用。
• App Shortcuts：封装在AppShortcutsProvider中的意图，会在应用安装后立即作为开箱即用的快捷指令提供，无需用户自行组装，同时附带Siri触发短语。¹³

该框架的覆盖范围逐年扩大。WWDC25关于Shortcuts和Spotlight的专题明确说明了当前Mac端的规则：“只要您的意图可在macOS上使用，它们也能在Shortcuts中使用，并作为Mac自动化的一部分运行。这也包括可安装在macOS上的iOS应用。”⁴ 在Apple芯片Mac上运行的iPhone应用，无需编写任何Mac专用代码，就能为Mac自动化提供操作。

同一专题中的Apple采用建议可归纳为：将内容公开为实体，并包含“您希望模型能够据以推理的关键属性”（Use Model操作会使用这些属性）；提供查找操作以支持查询；在适合富文本的场景中使用带属性字符串；同时确保参数摘要清晰易读。⁴

以下是从生产应用交付App Intents的实践中提炼出的意图设计建议：

• 意图就是API。 应将名称、参数和实体标识符视为契约；重命名会破坏用户的快捷指令，就像重命名端点会导致客户端失效一样。
• 后台优于前台。 无需打开应用即可运行的意图能够融入自动化；必须切换到前台的意图则会打断用户当前正在进行的工作。应有意识地将二者分开。⁴
• 返回值为流水线提供输入。 返回实体或值的意图能让Shortcuts用户继续串联后续操作；不返回任何内容的意图则会成为流程图中的死路。

本站在App Intents系列文章中深入介绍了开发者侧的内容：App Intents是Apple为应用提供的新API（采用理由与生产实践演练）、iOS 26中的App Intents 2.0（Visual Intelligence、摘要片段、延迟属性）、iOS 27中的App Intents（长时间运行的后台意图、可同步实体、Spotlight重新索引），以及App Intents与MCP对比（何时应将同一项能力同时作为智能体工具提供）。

Spotlight与自动化运行您的意图

macOS Tahoe扩展了意图的执行场景，其中两项新增能力改变了“采用App Intents”能为Mac带来的价值。⁴

Spotlight以内联方式运行意图。 “今年，您现在可以直接从Mac上的Spotlight运行应用中的操作。应用只需采用App Intents，就能像适配Shortcuts一样在Spotlight中显示操作。”⁴ 相关要求十分明确，可直接据此审核：

1. 参数摘要（“对应用意图功能的简短自然语言描述”）“必须包含所有没有默认值的必填参数”。⁴
2. 意图不得选择退出发现机制：将isDiscoverable设为false或将assistantOnly设为true，都会使其从Spotlight中移除。⁴
3. 建议和搜索来自实体层：为选择器实现建议实体或可枚举实体查询，并为输入时即时搜索实现实体字符串查询或已索引实体。⁴

自动化以无人值守方式运行意图。 由于Tahoe自动化会执行快捷指令，而快捷指令又会执行意图，因此文件夹变化或驱动器挂载如今都能在无人操作的情况下调用应用意图。⁴ 对意图作者而言，这进一步提高了上一节所述的要求：如果意图假定用户正在前台操作（例如显示UI或要求确认），它在立即运行的自动化中就会悄然失效。应逐一审核每个意图能否无人值守执行：屏幕前无人观察时会发生什么？

二者共同传达了Apple低调而明确的架构理念：在Mac上，功能的基本单元是意图，而非应用窗口。Spotlight是交互式调用方，自动化是无人值守调用方，Shortcuts则是二者之间的组合层。

从脚本和智能体驱动 Shortcuts

在智能体和脚本架构中，Shortcuts 占据着一个独特的位置：外部代码可通过它调用 Mac 功能，同时最大限度地降低权限，并让用户最容易审查操作。拥有 shell 访问权限的 AI 智能体可以直接完成大多数任务，但通过快捷指令执行操作具备原始 shell 所不具备的特性：操作由用户定义且可由用户编辑；权限按快捷指令授予，并可一键撤销；影响范围也能在编辑器中一目了然。⁶可以将快捷指令层视为由用户维护、供智能体调用的能力目录。

要实现上述功能，有一项硬性要求：CLI需要已登录的 GUI 会话。每个shortcuts子命令（包括list）都会与用户 Aqua 会话中的辅助应用程序通信。如果该会话不存在，命令将失败并显示“Couldn’t communicate with a helper application”（已在 macOS 26.5 上验证）。仅有SSH的会话、无头 CI 运行器和 launch daemons 都会遇到这一限制；请在已登录的用户会话中运行智能体和计划任务，即使用 launchd agent，而非 daemon。

以智能体术语描述的调用约定：¹²

结构化数据以文本形式跨越边界。切实可行的模式是通过 stdin/stdout 传输JSON：调用方通过管道传入JSON文档（-i -）；快捷指令使用 Get Dictionary from Input 解析数据并执行任务，最后通过 Stop and Output 将字典作为文本返回。¹¹⁶这样，快捷指令就成为具有明确类型和文档化模式的函数；建议在调用它的智能体配置旁，为每个快捷指令保留一份 README，说明预期的输入和输出结构。

超时由调用方负责。如果快捷指令显示提醒，CLI进程会无限期暂停，¹因此每个无人值守的调用方都应设置超时，并将超时视为失败：

# macOS ships no timeout(1); gtimeout comes from `brew install coreutils`
if ! output=$(gtimeout 120 shortcuts run "$UUID" -i - -o - <<<"$payload"); then
  echo "shortcut failed or timed out" >&2
fi
# no-Homebrew alternative using the system perl:
#   perl -e 'alarm shift; exec @ARGV' 120 shortcuts run "$UUID" -i - -o - <<<"$payload"

在无人值守运行前预先授予权限。先以交互方式运行每个快捷指令一次，并对其提示选择 Always Allow；在智能体或 launchd 任务调用之前，请从 Terminal 确认运行过程中不再出现提示。⁶¹权限部分说明了需要预先授权的内容。

根据调用方类型选择入口点。支持 shell 的调用方（智能体、CI、launchd agents、Makefiles——均须位于已登录的会话中）使用CLI。Apple Event 上下文（AppleScript 应用、PyObjC daemons）使用 Shortcuts Events，并可获得原生返回值。¹¹沙盒环境或仅支持 URL 的上下文使用shortcuts://run-shortcut，并通过 x-callback 获取结果。⁹²⁰这3种方式运行的是同一个快捷指令，区别仅在于传输机制。

反向模式同样可行：将快捷指令作为智能体的前端。快捷指令可通过键盘快捷键或菜单栏入口启动，收集上下文（所选内容、剪贴板、最前方应用），将其传给 Run Shell Script 以调用智能体CLI，然后显示结果。这样一来，操作系统的输入界面就成为底层工具的 UI。¹⁰¹⁷

权限与同意（TCC）

Shortcuts 沿用了 macOS 以用户同意为先的安全模型。凡非逻辑缺陷导致的自动化失败，最终几乎都可追溯至此。该模型分为4层；只要明确是哪一层发出提示，修复过程便可按部就班。

1. 按快捷指令授予数据访问权限。快捷指令首次访问受保护资源时，Shortcuts 会提示：“If a Privacy dialog appears requesting access to data, choose Allow Once, Always Allow, or Don’t Allow.”选择 Always Allow 意味着“the Shortcuts app won’t ask you for access the next time you run the shortcut.”⁶权限按快捷指令、按资源分别授予，并可随时检查：每个快捷指令的详细信息窗格中都有 Privacy 标签页，可撤销单项权限；如需撤销该快捷指令对所有数据的访问权限，请点击 Reset Privacy。⁶

2. 脚本开关。只有在 Settings → Advanced → Allow Running Scripts 启用后，5个脚本操作才能运行（完整列表见上文）。⁸此设置为全局设置，而非按快捷指令设置；为一个热文件夹脚本启用后，所有导入的快捷指令也都能运行脚本。因此，运行导入的快捷指令前应先审阅其内容。⁶

3. 系统 TCC 提示。涉及受保护操作系统资源的操作（Files and Folders、用于控制其他应用脚本的 Automation/Apple Events，以及用于输入控制的 Accessibility）会触发由 System Settings → Privacy & Security 管理的系统级对话框。这些权限与负责执行操作的进程绑定，因此同一个快捷指令在应用内、通过CLI以及在自动化中运行时，表现可能不同：不同启动上下文需要分别授权。⁶

4. 自动化运行策略。每项自动化的 Run Immediately 或 Run After Confirmation 设置决定触发操作本身是否需要人工确认。¹⁸

由此可得以下操作准则：

• 无人查看时，提示不会自行处理。无头上下文（SSH会话、CI 运行器、智能体）同样受CLI部分第一条规则约束：无人响应的权限对话框会导致进程无限期暂停。¹请提前以交互方式完成授权。
• Reset Privacy 是恢复初始状态的调试手段。快捷指令编辑后出现异常时，可重置其权限，再以交互方式重新运行，使所有提示依次重新出现。⁶
• 导入的快捷指令值得仔细审阅。Apple 会验证以“Anyone”模式签名的快捷指令，但“cannot verify the authenticity or behavior of shortcuts shared privately.”⁶⁷Privacy 标签页显示快捷指令已获得的权限，编辑器则显示它具体执行的操作。检查两者只需一分钟。

故障排除

快速参考卡

# Run
shortcuts run "Name"                          # by name
shortcuts run 8F3A...-UUID                    # by identifier (stable)
shortcuts run "Name" -i file.jpg -o out.png   # file in, file out
echo data | shortcuts run "Name" -i - -o -    # stdin → stdout
shortcuts run "Name" --output-type public.plain-text | pbcopy

# Inspect
shortcuts list                                # names
shortcuts list --show-identifiers             # names + UUIDs
shortcuts list --folders                      # folders
shortcuts list -f "Folder"                    # scoped
shortcuts view "Name"                         # open in editor

# Distribute
shortcuts sign -m anyone -i in.shortcut -o out.shortcut
shortcuts sign -m people-who-know-me -i in.shortcut -o out.shortcut

# Exit codes: 0 success, 1 error

-- Background run with result (no app window)
tell application "Shortcuts Events" to run shortcut "Name" with input "payload"

shortcuts://run-shortcut?name=Name&input=text&text=payload
shortcuts://run-shortcut?name=Name&input=clipboard
shortcuts://x-callback-url/run-shortcut?name=Name&x-success=app://ok&x-error=app://fail

检查清单。适合无人值守运行的快捷指令：不包含提醒或 Ask Each Time 参数；已通过 Always Allow 预先授予权限；使用 UUID 调用；调用方强制执行超时；以 Stop and Output 结束。¹⁶适合分发的文件：已导出、使用-m anyone签名，并已记录输入约定。²⁷

常见问题

如何从 Terminal 运行 Mac Shortcuts？ 使用shortcuts run "Shortcut Name"，可选配合-i传入输入文件（或使用-读取stdin）、使用-o输出结果（或使用-写入stdout），以及结合 Uniform Type Identifier 的--output-type。命令成功时退出码为0，出错时为1，因此可像任何 Unix 工具一样与&&、if和make组合使用。¹²

macOS 终于拥有像 iOS 一样的 Shortcuts 自动化了吗？ 是的，自 macOS Tahoe（26）起即可使用。触发器包括一天中的时间、闹钟、电子邮件、信息、文件夹变更、外部驱动器、显示器、Wi-Fi、Bluetooth、电池电量、充电器、App 打开/退出、专注模式和 Stage Manager；每项均可配置为立即运行或确认后运行。³⁴¹⁸

shortcuts sign -m anyone实际做了什么？ 它会通过 iCloud 对快捷指令文件进行公证，使任何人都能导入。默认模式people-who-know-me会在本地签名，并将导入限制为您自己的设备，以及在 Contacts 中拥有您联系信息的人员。²

App 如何将自己的 actions 添加到 Mac 上的 Shortcuts？ 通过采用 App Intents 框架。Intents 会自动显示为 Shortcuts actions，而AppShortcutsProvider可随 App 提供无需设置的 App Shortcuts。在 macOS 上可用的 Intents 也可从 Spotlight 和 Tahoe 自动化中运行，包括安装在 Apple silicon Mac 上的 iOS App 所提供的 intents。¹³⁴

脚本或 AI agent 应如何调用 shortcuts？ 使用CLI：通过shortcuts list --show-identifiers发现快捷指令，按 UUID 调用，经stdin传递JSON，从stdout读取结果。每次调用都应设置超时，因为会发出提示的快捷指令将无限暂停（macOS 未提供timeout(1)——请使用 coreutils 中的gtimeout或您所用语言的进程超时机制）。在无人值守使用前，请先以交互方式预先授权每个快捷指令的权限提示。从 AppleScript 上下文调用时，可将目标设为Shortcuts Events，以便在不打开 App 的情况下运行。¹²¹¹

Shortcuts 能取代 Automator 吗？ 对于大多数工作流程，可以；Apple 将 Shortcuts 称为 Mac 自动化的未来，并构建了一个转换器，可直接导入大多数.workflow文件。Automator 仍随系统提供，也仍可运行现有工作流程，因此迁移是选择，而非截止期限。⁵¹⁴¹⁵

更新日志

参考资料