Mac捷徑自動化：實務工作者參考指南（2026）

重點摘要：自macOS Monterey（2021年）起，每台Mac皆內建Shortcuts；macOS Tahoe（26）終於補上Mac自動化使用者苦候4年的關鍵功能：個人自動化，可透過資料夾變更、外接磁碟、Wi-Fi、顯示器及app啟動等事件觸發。³⁴這款app可從選單列、Spotlight、Finder快速動作、鍵盤快速鍵，以及真正的命令列工具（shortcuts run、list、view、sign）執行捷徑。¹²任何app皆可透過App Intents框架加入動作；Siri、Spotlight與Apple Intelligence使用的也是同一套介面。¹³指令碼與AI代理程式可透過3種方式驅動捷徑：CLI、shortcuts:// URL scheme，以及可供指令碼控制的Shortcuts Events背景程序。¹⁹¹¹權限模型是最應優先掌握的部分：在app中不易察覺的同意提示，會讓無人值守的執行作業悄然停滯。

Apple在WWDC 2021向開發者表示：「Shortcuts是Mac自動化的未來。」⁵這個未來分成兩階段到來。第一階段隨即推出：macOS Monterey內建原生SwiftUI app，支援iCloud同步、Automator移轉工具，並可在編輯器中完整使用shell指令碼與AppleScript。⁵第二階段則又歷經4次macOS版本更新才實現。在macOS Tahoe之前，Mac捷徑只有在其他功能要求執行時才會啟動；由於沒有觸發條件，所謂的「自動化」其實仍得記得手動點選。Tahoe填補了這項缺口，除了熟悉的iOS觸發條件（特定時間、Bluetooth），還加入專為Mac打造的個人自動化（資料夾與外接磁碟觸發條件），並新增Use Model動作，將Apple Intelligence置於捷徑資料流程的核心。³⁴

最終呈現的是一套值得深入學習的系統。2026年的Mac版Shortcuts同時具備4種角色：

1. 無程式碼編輯器，內建數百種動作，涵蓋檔案操作、視窗管理與裝置端AI等功能
2. 自動化引擎，可由系統事件觸發，是macOS Tahoe新增的功能
3. 命令列的一等公民：shortcuts run如同其他Unix工具，可使用stdin、stdout、結束代碼與管線¹
4. 所有app的動作登錄中心：app透過App Intents公開的任何功能，都會自動出現在Shortcuts中；Mac與其他平台皆是如此¹³⁴

入門與進階用法之間的差異，歸結於5套系統：動作目錄（有哪些功能）、自動化觸發條件（何時執行）、CLI與指令碼橋接機制（程式碼如何呼叫）、簽署與分享（捷徑如何流通），以及權限模型（無人值守的執行作業為何停滯）。以下將分別說明。

本指南中的每項論述，皆以Apple文件、WWDC議程，或在撰寫本文的電腦上直接檢視macOS 26.5（Shortcuts 7.0）的結果為依據。若資訊直接來自作業系統本身（shortcuts(1) man page、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工具一樣用管線串接。¹²
• 3個指令碼進入點，一條原則。從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會針對每個捷徑、每種資料類型，要求選擇「允許一次／一律允許／不允許」。執行指令碼的actions則受全域「Allow Running Scripts」開關控管。無人值守執行若遇到尚未回應的提示，只會持續等待。¹⁶⁸

如何使用本指南

目錄

第1部分：基礎

1. Mac上的Shortcuts是什麼
2. 執行捷徑的方式
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. 從指令碼與代理程式驅動Shortcuts

第7部分：操作與參考資料

1. 權限與同意（TCC）
2. 疑難排解
3. 快速參考卡
4. 常見問題
5. 變更紀錄
6. 參考資料

Mac上的Shortcuts是什麼

Shortcuts是Apple的自動化App：將actions（單一用途的步驟）串連成捷徑（儲存的工作流程），接著透過點按、語音、按鍵、觸發條件或命令列執行。Apple本身的定義值得牢記，因為它說明了整體設計：「Action是捷徑的建構區塊。每個捷徑都由一連串actions構成，而每個action都是執行特定功能的單一步驟。」¹²

此App於2021年隨macOS Monterey登上Mac，雖從iOS移植而來，卻幾乎完全以SwiftUI撰寫，因此同一套程式碼可服務兩個平台。⁵首個版本的3項設計決策，至今仍定義著2026年的Mac體驗：

• iCloud同步為預設。在新的Mac開啟Shortcuts，既有資料庫便會出現，並從iPhone與iPad同步而來。在其中一部裝置建立的捷徑，可在其他裝置執行，平台專屬actions除外。⁵¹²
• App提供actions。「如同在iOS上，Mac上的任何App都能為Shortcuts提供actions。」⁵在2026年，這條流程採用App Intents framework，將在第6部分說明。
• 指令碼是一等公民。Monterey提供「完整支援AppleScripts與Shell Scripting」，並加入「直接內建於Shortcuts、可讓您直接在Shortcuts編輯器中撰寫與執行指令碼的新actions」，因此Shortcuts是包裝既有自動化堆疊，而非取而代之。⁵

Monterey未提供的是觸發條件。從2021年至2024年，Mac捷徑只有在某項機制呼叫時才會執行。macOS Tahoe（26）在2025年改變了這點，將個人自動化帶到Mac；除了既有的iOS觸發條件，也新增專為桌面工作流程設計的觸發類型，例如資料夾內容變更與外接磁碟連接。³⁴Tahoe也加入Use Model action，可在捷徑執行途中透過Apple Intelligence模型處理資料。³⁴

版本里程碑：

在本指南中，「已於macOS 26.5驗證」表示已直接在撰寫本指南所使用的Mac上，針對Shortcuts 7.0進行檢查。

執行捷徑的方式

Mac上的Shortcuts提供了異常豐富的進入點。以下所有方式都會呼叫同一個捷徑；差異在於輸入來源與輸出位置。¹²¹⁰

有兩項細節可在之後節省時間。第一，Quick Action與Services項目會將目前選取內容作為捷徑輸入，因此檔案處理捷徑應宣告可接受的輸入類型（編輯器中的「Receive」設定），而非假設輸入一定是文字。第二，最後3列是可程式化介面；由於其輸入／輸出契約不同，將各自設有章節說明。

Shortcuts、Automator 與 AppleScript 的比較

到了2026年，這3套Apple自動化系統仍隨macOS提供（Automator仍位於/System/Applications，已在macOS 26.5上驗證），而且各有用武之地。經得起考驗的定位如下：Shortcuts是整合層、AppleScript是應用程式控制語言，而shell scripts則是運算層。Automator已進入維護階段：功能仍可正常使用、未再變動，且Apple明確以Shortcuts作為其後繼方案。⁵¹⁴

遷移途徑確實存在，但在邊緣情境下會有所折損。 Apple在Shortcuts中內建了轉換器：將.workflow檔案拖入應用程式（或按住Control鍵並按一下→Open With→Shortcuts），「Shortcuts可將大多數Automator工作流程轉換成能執行相同功能、事件與自動化作業的捷徑。」¹⁴¹⁵「大多數」是Apple的原話。實務上可理解為：標準的檔案、影像與文字動作通常能順利轉換；冷門的第三方Automator動作及Watch Me Do錄製內容，轉換效果則較差。Shortcuts甚至在內部保留Watch Me Do動作名稱，作為相容性機制的一環（可在framework的動作表中看到，已在macOS 26.5上驗證）。¹⁶

何時該採用Shortcuts以外的工具。 深入控制個別應用程式（逐一處理Mail郵件、以程式化方式操作Finder視窗、透過內容豐富的指令碼字典操控應用程式），至今仍是AppleScript的主場。複雜的文字處理、API協調作業，以及任何原本就會用Python或zsh撰寫的工作，都適合交給指令碼。實務高手講究的是組合，而非選邊站：由捷徑透過觸發條件收集輸入，交給shell script處理繁重工作，再使用原生動作傳送通知及放置檔案，便能集各家之長。指令碼動作一節將說明具體做法。

動作的組合方式

每個捷徑都是一條管線。每個動作接收輸入（通常是上一個動作的輸出）、執行一項工作，然後產生輸出。以下3項機制讓管線具備靈活的表達能力：

• Magic variables。 每個動作的輸出都會自動成為變數，供後續動作使用，無須事先宣告。按一下參數欄位、選擇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 framework（Shortcuts背後的私有framework）內部英文字串表列出361個不同的動作名稱。¹⁶ 這個數字高估了您在編輯器中實際看到的數量，因為該表也包含僅限iOS使用的動作，以及源自這款應用程式Workflow時期的舊式整合功能。以下整理與Mac相關的動作，並依自動化工作者的實際需求分類。下列每個動作名稱都逐字出現在該表中，且已在macOS 26.5上驗證。¹⁶

檔案與Finder

系統與應用程式

網頁與資料

Get Contents of URL搭配Dictionary動作，即可組成實用的REST用戶端：提出要求、剖析JSON、擷取值，全程無須撰寫程式碼。當承載資料變得複雜時，建議交由使用curl與jq的shell script處理，不必在編輯器中苦戰於多層巢狀字典。

文字、影像與媒體

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→設定→進階，在任一動作執行前必須開啟「允許執行腳本」；App對此設定的說明明確列出它所管控的動作：「啟用後，即可執行『執行AppleScript』、『執行Shell腳本』、『執行JavaScript進行Mac自動化』、『在網頁上執行JavaScript』及『透過SSH執行腳本』動作」（已於macOS26.5驗證）。⁸¹⁷Apple文件進一步警告，執行含有腳本的捷徑可能導致資料遺失——此設定之所以存在，是因為這5個動作會以完整使用者權限執行，不受一般動作防護機制的約束。⁸

執行Shell腳本

主力工具。選擇Shell、貼上腳本，接著決定輸入的傳遞方式。兩種輸入模式直接取自動作本身的文件：「傳送至stdin：輸入會轉換為檔案，並導向腳本的stdin管線。作為引數：輸入會轉換為字串清單，並作為引數傳遞給腳本。」¹⁷

這兩種模式的實務意涵如下：

• stdin模式適合文字與單一檔案：類似pbpaste的處理方式、透過jq處理JSON，以及任何讀取串流的工作。
• arguments模式適合多個檔案：每個輸入項目都會放入"$@"，因此for f in "$@"; do ... done可正確處理Finder選取內容，連同空格也不例外。
• 輸出即為腳本寫入stdout的內容，並會像其他輸出一樣流向下一個動作。

執行AppleScript與執行JavaScript進行Mac自動化

兩者都內嵌OpenScriptingArchitecture腳本，分別使用on run {input, parameters}進入點（AppleScript）或run(input, parameters)函式（JXA）。當工作需要控制其他App時就適合使用，例如排列Finder視窗、設定Mail規則，或操作任何具有腳本字典的App。傳回值會成為動作輸出。

透過SSH執行腳本

在遠端主機上執行Shell腳本，並在動作中設定主機、連接埠、使用者與驗證方式。最關鍵的用途與CLI相互對稱：辦公室中的Mac可將可重複執行的操作提供給任何能透過SSH連線的機器；而捷徑也能將工作推送到Linux主機，無須離開Shortcuts編輯器。

在網頁上執行JavaScript

針對目前的Safari頁面執行JavaScript，並傳回結果。Apple同時以腳本開關及每次執行時的權限提示加以控管，因為任意頁面內容環境中的JavaScript可能成為資料外洩的途徑。⁸

視窗管理動作

Shortcuts在Mac上提供原生視窗控制：尋找視窗、移動視窗與調整視窗大小。¹⁶它們看似只是動作目錄中的小項目，實則是不用第三方工具便能建立鍵盤驅動視窗版面的基石。

• 尋找視窗會查詢已開啟的視窗（可在編輯器中排序及篩選），並輸出視窗物件。
• 移動視窗接受視窗與位置。其參數摘要為「將⟨視窗⟩移至⟨位置⟩」，另有可選的自訂變體：「將⟨視窗⟩移至⟨位置⟩⟨X座標⟩、⟨Y座標⟩」（已於macOS26.5驗證）。¹⁶
• 調整視窗大小接受視窗與目標：「將⟨視窗⟩調整為⟨設定⟩」，自訂變體則可接受明確的⟨寬度⟩×⟨高度⟩。¹⁶

框架字串表中內建的視窗位置包括：全螢幕、左、右、上、下、三等分（左側三分之一、中間三分之一、右側三分之一）、角落變體（上／下前導與尾端），以及自訂視窗位置與大小格式（已於macOS26.5驗證）。¹⁶將尋找視窗（最前方視窗）→調整視窗大小（左）搭配鍵盤快速鍵，就能得到一鍵視窗指令。SplitScreenApps則能以一個動作處理雙App情境。¹⁶

UseModel動作

UseModel是macOSTahoe新增、也是自Mac版本推出以來Apple加入最具影響力的單一動作：它會在捷徑執行途中將資料傳送至AppleIntelligence模型，並把回應交給下一個動作。³⁴

依據Apple在WWDC介紹此功能的場次，共有3種模型可選：位於PrivateCloudCompute上的大型伺服器型模型、適用於「沒有網路連線的簡單請求」的裝置端模型，以及具備「廣泛世界知識」的ChatGPT。⁴

共有3種輸出形式，而有意識地選擇正是關鍵技能：⁴

1. 文字（包括RTF格式文字），適用於摘要與改寫。
2. 字典，適用於結構化擷取；Apple的範例是從發票擷取供應商、金額與日期。字典輸出使UseModel能夠組合：後續動作讀取欄位，而非剖析散文。
3. App實體：由透過AppIntents公開此類內容的App提供的內容物件。Apple將這層關係描述為：「若AppIntents是App中的動作或動詞，AppEntities就是名詞。」⁴UseModel可直接針對這些名詞推理（篩選這些備忘錄、選擇相關的行事曆事件）。

後續追問切換可讓您在同一次執行中反覆處理模型回應。⁴

有一項工程上的注意事項：模型輸出並非決定性的，因此相同輸入每次執行可能產生不同結果。對自動化而言，這表示應採用字典輸出形式（受結構描述約束）、小而聚焦的提示，並在結果接觸檔案或訊息前加入驗證步驟（以If動作檢查必要欄位）。請將UseModel視為不穩定的網路呼叫：很有用，但必須以檢查機制包裝。

如需從開發者角度了解同一功能（您的App應公開哪些內容，讓UseModel能據此推理），請參閱第6部分及本站的AppIntents系列，從AppIntentsAreApple’sNewAPItoYourApp開始。

macOS上的自動化觸發條件

自動化是附加觸發條件的捷徑：「當某事發生時執行此項作業」，不需點按。它們在macOSTahoe登上Mac，Apple沒有完整照搬iOS清單，而是打造Mac專屬觸發條件：「我們正將個人自動化帶到Mac，推出專為Mac建立的新自動化類型，例如資料夾與外接硬碟自動化，也包含您可能已從iOS熟悉的自動化類型，例如一天中的時間與Bluetooth。」⁴

請從ShortcutsApp的自動化區域建立。每項自動化都將一個觸發條件與一組動作配對，並包含一項政策選擇：立即執行（無需互動，正是自動化的目的）或確認後執行（先以通知詢問）。³¹⁸建立新的自動化時，建議先使用確認模式；確認可信任後，再切換為立即執行。

macOSTahoe的觸發條件目錄：³⁴¹⁸

此設計帶來兩項轉變。第一，Mac終於有了Apple原生方案，可「監看此資料夾並處理放入其中的內容」，而且能像其他捷徑一樣同步及編輯（Automator的FolderActions能監看，但做不到後續工作）。第二，由於自動化會執行捷徑，本指南中的一切皆可層層疊加：資料夾觸發條件可串接執行Shell腳本；App觸發條件可呼叫UseModel；外接硬碟觸發條件可啟動SSH工作。

行之有效的自動化模式

以下模式完全由文件記載的元件組成，足以應付日常使用：

熱門資料夾。在~/Inbox上設定資料夾觸發條件→使用Filter Files（副檔名為pdf）→使用Extract Text from Image或Get Text from PDF→使用Use Model並輸出字典（供應商、日期、總額）→使用Rename File，再將檔案透過Move File移至封存階層。這是經典的Automator使用情境，並透過裝置端擷取與模型產生的命名方式加以升級。³⁴¹⁶

桌面工作站。顯示器觸發條件（外接顯示器連線）→使用Open App開啟工作所需的一組App→透過Move Window與Resize Window排成您的版面配置→使用Set Focus切換至「工作」。中斷連線時則反向執行。一個觸發條件即可重建整個桌面配置，無須手動拖曳。³¹⁶

匯入磁碟。外接磁碟觸發條件→在記憶卡的DCIM資料夾上使用Get Contents of Folder→依日期使用Filter Files→透過Save File存入按日期命名的資料夾→使用Show Notification顯示檔案數量。此處建議採用確認模式：未預期連接的磁碟不應觸發大量複製。³¹⁸

通往真正程式碼的後路。任意觸發條件→使用Run Shell Script並以引數形式傳入輸入→執行您現有的指令碼。真正有價值的是觸發系統；邏輯並不需要存在Shortcuts actions之中。僅含2個action（觸發條件＋指令碼）的自動化，即可免費獲得具備UI、同步與同意管理功能，並且類似launchd的事件處理機制。⁸¹⁷

會議相關情境。Focus觸發條件（開啟「工作」Focus）¹⁸→使用Set Volume、透過Quit App關閉會造成干擾的App，並使用Open App開啟筆記App。在System Settings啟用跨裝置Focus共享後，即使從iPhone開啟Focus，Mac也會隨之回應。

設計時需要考量以下限制：自動化只存在於建立它的Mac上。因此，即使捷徑資料庫本身會同步，在MacBook上建立的資料夾自動化也不會於Mac mini上觸發（每台需要執行的機器都必須各自設定觸發條件）。此外，觸發條件清單中沒有「收到網路要求」項目（可從傳送端使用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中執行並無不同。」¹這同時帶來利弊：既能完整使用所有action，也會完整顯示權限提示（請參閱權限）。

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註冊了2個可編寫指令碼的目標：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參數。
• 失敗時開啟x-error，並附帶errorMessage參數。
• 使用者取消時開啟x-cancel，且不提供任何輸出。²⁰

在shell中，open "shortcuts://run-shortcut?..."確實可用，但此處仍應優先使用shortcuts run：CLI會直接傳回結束碼與輸出，不必透過URL回呼繞道處理。此scheme在Mac上剩餘的主要用途，是App對App整合，以及文件內的連結。

分享格式與簽署

Shortcuts 有兩種分享方式，最終都取決於信任抉擇。⁷

iCloud 連結。在 App 中選擇「分享」→「Copy iCloud Link」（拷貝 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 檔案、將其拖入 App，或拖放至 Dock 圖示；.workflow 檔案則會在匯入過程中由 Automator 格式轉換而來。¹⁵對於 Gallery 以外分享的 Shortcuts，Apple 明確提醒：「Apple 無法驗證私下分享之捷徑的真實性或行為。」⁶企業裝置群另有專用途徑：Apple Configurator 支援受管理工作流程中的 Shortcuts 自動化。²¹

「設定」→「進階」中也提供 Private Sharing（私人分享）開關，用於控制是否能匯入私下分享、受聯絡人限制的捷徑；同一處還有「允許執行指令碼」與「允許分享大量資料」選項。⁶⁸收到的捷徑若無法匯入，通常可歸因於下列原因之一：檔案未簽署、檔案受聯絡人限制但傳送者不在您的通訊錄中，或 Private Sharing 已停用。

App Intents：App 如何加入動作

到目前為止，目錄中的內容全都來自 Apple。捷徑庫的另一半則來自已安裝的 App；自 2022 年起，這條整合管線統一由一套框架負責：App Intents（iOS 16、macOS 13）。¹³App 會定義符合 AppIntent 的型別（一個動詞：參數加上 perform() 方法），也可選擇定義 AppEntity（一個名詞：App 內容中具有識別碼與顯示表示法的型別化項目），其餘工作交由系統處理。相同的定義會呈現在 Shortcuts、Siri、Spotlight、小工具與 Apple Intelligence 中；Shortcuts 只是 App 意圖結構的一種呈現方式，而非獨立整合。¹³⁴

App 在 Mac 上的呈現方式主要取決於兩種採用層級：

• 動作：每個未隱藏的意圖，都會以動作形式顯示在 Shortcuts 編輯器中該 App 的名稱之下，並可與本指南介紹的所有功能自由組合。
• App Shortcuts：封裝於 AppShortcutsProvider 中的意圖，會在 App 安裝後立即以現成可執行的捷徑提供，無須使用者自行組裝，並附帶 Siri 觸發詞句。¹³

此框架的涵蓋範圍每年持續擴大。WWDC25 的 Shortcuts 與 Spotlight 場次直接說明目前 Mac 上的運作規則：「只要您的意圖可在 macOS 上使用，也能在 Shortcuts 中使用，並作為 Mac 自動化的一部分執行。這也包括可安裝於 macOS 的 iOS App。」⁴在 Apple silicon Mac 上執行的 iPhone App，無須撰寫任何 Mac 專用程式碼，就能為 Mac 自動化提供動作。

同一場次中的 Apple 採用指南可濃縮如下：將內容公開為實體，並納入「您希望模型能夠據以推理的重要屬性」（Use Model 動作會使用這些屬性）；提供尋找動作以支援查詢；在適合使用 Rich Text 的情境中採用 attributed string；並確保參數摘要清楚易讀。⁴

以下是根據正式 App 中 App Intents 的實際導入經驗，為意圖作者歸納的設計指南：

• 意圖就是 API。名稱、參數與實體識別碼都應視為契約；重新命名會破壞使用者的捷徑，就像重新命名端點會導致用戶端失效。
• 背景執行優於前景執行。能在不開啟 App 的情況下執行的意圖，可以整合至自動化；必須切換至前景的意圖，則會中斷使用者當下的工作。請刻意區分兩者。⁴
• 回傳值可串接管線。回傳實體或值的意圖，能讓 Shortcuts 使用者繼續串接後續動作；不回傳任何內容的意圖，則會成為流程圖中的死路。

本站在 App Intents 系列中深入介紹開發端實作：App Intents 是 Apple 為您的 App 打造的新 API（採用理由與正式環境實作導覽）、iOS 26 中的 App Intents 2.0（Visual Intelligence、snippets、deferred properties）、iOS 27 中的 App Intents（長時間執行的背景意圖、可同步實體、Spotlight 重新建立索引），以及 App Intents 與 MCP 的比較（判斷同一項功能何時也應作為代理工具提供）。

Spotlight 與自動化執行您的意圖

macOS Tahoe 擴展了意圖的執行場域，而新增的兩項功能，也改變了「採用 App Intents」能為 Mac 帶來的價值。⁴

Spotlight 可直接執行意圖。「今年起，您可以直接從 Mac 的 Spotlight 執行 App 動作。只要採用 App Intents，App 就能在 Spotlight 中顯示動作，做法與 Shortcuts 相同。」⁴相關要求相當明確，可逐項稽核：

1. 參數摘要（「以簡短自然語言描述 App 意圖用途」）「必須包含所有沒有預設值的必要參數」。⁴
2. 意圖不得選擇退出探索機制：將 isDiscoverable 設為 false 或將 assistantOnly 設為 true，會使其無法出現在 Spotlight 中。⁴
3. 建議與搜尋來自實體層：為選擇器實作建議實體或可列舉的實體查詢，並為即打即搜功能提供實體字串查詢或已建立索引的實體。⁴

自動化可在無人操作時執行意圖。Tahoe 自動化能執行捷徑，而捷徑又能執行意圖，因此資料夾異動或磁碟掛載如今都能在沒有使用者操作的情況下呼叫 App 意圖。⁴對意圖作者而言，這也提高了上一節所述的標準：假設使用者正在前景操作的意圖（例如顯示 UI 或要求確認），在「立即執行」自動化中可能悄然失敗。請逐一稽核每個意圖是否適合無人值守執行：當沒有人注視螢幕時，會發生什麼事？

兩者共同構成 Apple 低調而明確的架構宣言：在 Mac 上，功能的基本單位是意圖，而非 App 視窗。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（永遠允許）；接著從 Terminal 確認執行時不會再出現提示，再交由代理程式或 launchd 工作呼叫。⁶¹權限章節說明了預先核准的具體內容。

請依呼叫端類型選擇進入點。具備 shell 能力的呼叫端（代理程式、CI、launchd agents、Makefiles，且全都必須位於已登入的工作階段中）使用 CLI。Apple Event 環境（AppleScript 應用程式、PyObjC daemons）使用 Shortcuts Events，並取得原生回傳值。¹¹沙盒化或僅能使用 URL 的環境，則透過 shortcuts://run-shortcut 搭配 x-callback 取得結果。⁹²⁰這三種方式都會執行同一個捷徑，差別僅在傳輸機制。

反向運作同樣可行：將捷徑作為代理程式的前端。捷徑可透過鍵盤快速鍵或選單列項目啟動，收集選取內容、剪貼簿及最前方應用程式等情境資訊，再傳給 Run Shell Script（執行 Shell 指令碼）以呼叫代理程式 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（永遠允許）表示「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 分頁會顯示捷徑已獲得哪些授權，編輯器則會顯示捷徑執行哪些操作。兩者都只需花1分鐘檢查。

疑難排解

快速參考卡

# 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 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開啟／結束、專注模式與幕前調度；每一項都可設定為立即執行或確認後執行。³⁴¹⁸

shortcuts sign -m anyone實際上做了什麼？ 它會透過iCloud對快捷指令檔案進行公證，讓任何人都能匯入。預設模式people-who-know-me會在本機簽署，並將匯入限制為您自己的裝置，以及Contacts中擁有您聯絡資訊的人員。²

App如何將自己的actions加入Mac上的Shortcuts？ 透過採用App Intents framework。Intents會自動顯示為Shortcuts actions，而AppShortcutsProvider會隨App提供無須設定的App Shortcuts。macOS可用的Intents也能從Spotlight及Tahoe自動化中執行，包括安裝於Apple silicon Mac上的iOS App所提供的intents。¹³⁴

指令碼或AI agent應如何呼叫快捷指令？ 使用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仍隨系統提供，也仍可執行既有工作流程，因此遷移是選擇，不是期限。⁵¹⁴¹⁵

變更記錄

參考資料