自動化指南

自動化接入

當本地腳本、工具或自動化流程還在使用某個 App 時，讓靈汐不要把它當成閒置 App 關掉。

只在本機，不經雲端適合腳本和本地 Agent關閉前可確認

適用對象

告訴靈汐：這個 App 還在忙

當你的本地工具會啟動或控制某個 App，並希望靈汐等任務真正結束後再清理它時，就看這頁。

給本地自動化開發者

當本地腳本或 Agent 正在驅動瀏覽器、編輯器、終端機或上傳工具時，可以用這頁讓靈汐在任務完成前保持目標 App 開啟。

給一般靈汐使用者

日常使用不需要看這頁。除非你要把自己的本地自動化工具接入靈汐，否則直接看使用指南就夠了。

傳輸方式

目前公開入口

本地保護通道

靈汐在本機提供同一使用者可存取的 Unix domain socket。你的工具可以透過它告訴靈汐：哪個 App 還在忙。

~/Library/Application Support/Aion/ipc/ai-protection.sock

可選 URL 指令

靈汐 2.11 也可以接收 aion:// 指令，用於切換場景、開關保護、管理清單、讀取狀態和控制視窗。預設關閉，需要在「設定 → 進階」手動啟用。

aion://scene/activate?name=Coding

Agent Skill 包

使用內建的 SKILL.md 包，讓相容的 Agent 能發現 Aion CLI，並在長任務期間主動申請保護。

aion install-skill 開啟 SKILL.md

協定流程

一條正常會話應該怎麼走

  1. 以和靈汐相同的 macOS 使用者身分連線 socket。
  2. 送出 `session.hello`，其中帶上 `protocolVersion: 1`、你的 `holderId`、可讀的 `clientName` 與程序 `pid`。
  3. 收到 `session.ready` 之後再送出業務訊息。
  4. 業務訊息繼續使用現有的 `AIAppLeaseEnvelope` 結構。
  5. 如果 lease 過期並走完 grace 之後靈汐仍需要最後確認，它會向對應 `holderId` 的活躍連線推送一條 `lease.can_close.request`。
  6. 收到 close-check 後，用 `lease.can_close.reply` 回覆「允許關閉」或「延長 lease」。

動作

你可以送出的業務訊息

  • session.hello
  • lease.begin
  • lease.renew
  • lease.end
  • lease.list
  • lease.can_close.reply
靈汐可能反推

lease.can_close.request

握手與傳輸錯誤

業務訊息開始前的協定層回饋

  • session.hello
  • session.ready
  • session.error
invalid_handshakeunsupported_protocol_versionholder_id_mismatchunauthenticated

應用識別

目前 `appKey` 的規則

  • 大多數 App 的 `appKey` 就是 bundle identifier，例如 `com.google.Chrome`。
  • 帶 Profile 或變體區分的 App 可能會使用帶後綴的 key，例如 `com.google.Chrome#profile-work`。
  • 未知 App key 會以 `unknown_app` 拒絕。

策略限制

目前時序邊界

  • 最短 lease：60 秒
  • 最長 lease：1800 秒
  • active lease 結束後的 grace：60 秒
  • close-check 超時：3 秒
  • close-check 冷卻：15 秒

範例

最小可用訊息範例

握手

{
  "action": "session.hello",
  "protocolVersion": 1,
  "holderId": "agent.local.test",
  "clientName": "Test Agent",
  "pid": 42
}

開始 lease

{
  "action": "lease.begin",
  "requestId": "req_123",
  "holderId": "agent.local.test",
  "appKey": "com.google.Chrome",
  "leaseSeconds": 600
}

回覆 close-check

{
  "action": "lease.can_close.reply",
  "requestId": "close_777",
  "holderId": "agent.local.test",
  "appKey": "com.google.Chrome",
  "result": "extend_lease",
  "leaseSeconds": 300
}

業務回應碼

目前業務回應碼

acceptedinvalid_payloadunknown_actionunknown_appnot_entitledholder_mismatchrequest_expiredlease_conflict

邊界

這頁穩定公開什麼，不公開什麼

穩定公開部分

  • socket 路徑以及「同一使用者本地傳輸」這個模型。
  • 握手訊息：`session.hello`、`session.ready` 和 `session.error`。
  • 這頁列出的 lease actions 與目前回應碼。
  • 租期到期後，靈汐在強退應用前發起的確認請求。

只使用文件裡的公開入口

  • 內部 store 結構、actor 邊界與 UI 接線方式。
  • 未寫在這裡的 transport 或 debug-only 入口。
  • 不會承諾所有內部狀態變化都會成為穩定的公開 API 事件。

實務頁

給特定工具的實作說明

先看這頁裡的穩定接入方式。如果某個工具有額外設定細節，再看對應實作頁，不把所有邊緣問題都塞進基礎指南。

本地自動化執行環境整合

一篇面向本地自動化執行環境的接入實務，適合在執行環境正在主動驅動某個 App，而你希望靈汐繼續把它視為「正在使用中」而不是普通閒置背景時查看。

查看執行環境接入實務

2.11 新功能

給可信本地工具的可選 URL 指令

Socket 用來保護正在忙的 App；可選的 aion:// 指令用於更廣的控制：切換場景、開關保護、更新清單、讀取狀態和控制視窗。除非你信任要呼叫它的本地工具，否則保持關閉。

1
在「進階」設定中啟用

打開靈汐 → 設定 → 進階 → External Agent Control，開啟開關。預設關閉。

2
從任何本地 App 或腳本發送 URL 指令

在終端用 open "aion://..." 呼叫，或在程式碼中使用 NSWorkspace.shared.open(url)。

open "aion://scene/activate?name=Coding"
3
需要狀態快照時再更新

~/.aion_status.json 僅由 status 指令及相關狀態請求更新。租約指令透過 Unix socket 直接回傳，不依賴此檔案。

~/.aion_status.json

URL 指令參考

所有可用的 aion:// 指令

場景管理

aion://scene/activate?name=Coding 以名稱啟動場景
aion://scene/activate?id=<uuid> 以 UUID 啟動場景
aion://scene/deactivate 回到標準模式
aion://scene/toggle 切換場景啟用狀態

保護開關

aion://protect/video?on=true 切換全螢幕影片鎖
aion://protect/smart-guards?on=false 切換智慧守衛保護
aion://protect/focus-sync?on=true 切換 macOS 專注模式同步
aion://protect/instant?on=true 切換瞬時任務保護
aion://protect/clean-now 立即觸發閒置 App 清理

黑名單管理

aion://blacklist/add?bundleId=com.apple.Safari 加入黑名單（優先快速關閉）
aion://blacklist/remove?bundleId=com.apple.Safari 從黑名單移除
aion://blacklist/toggle?bundleId=<id> 切換黑名單狀態

白名單管理

aion://whitelist/add?bundleId=com.apple.dt.Xcode 加入白名單（永遠保持執行）
aion://whitelist/remove?bundleId=com.apple.dt.Xcode 從白名單移除
aion://whitelist/toggle?bundleId=<id> 切換白名單狀態

UI 視窗控制

aion://ui/popover 開啟/關閉選單列浮窗
aion://ui/settings?tab=blacklist 開啟設定並切換到指定頁籤
aion://ui/history 開啟活動記錄視窗

狀態查詢

aion://status 將目前狀態寫入 ~/.aion_status.json

狀態 JSON

~/.aion_status.json 欄位說明

  • activeScene — 目前啟用的場景名稱
  • scenes — 所有場景列表（含 id 與名稱）
  • protections.autoQuit — 是否啟用自動退出
  • protections.fullScreenVideoLock — 是否啟用全螢幕影片鎖
  • protections.smartGuards — 是否啟用智慧守衛
  • protections.focusIntegration — 是否啟用專注模式同步
  • protections.instantTask — 是否啟用瞬時任務保護
  • blacklist — 黑名單 Bundle ID 列表
  • whitelist — 白名單列表
  • aiLeases — 活躍的 AI 保護租約列表
  • demoModeActive — 演示模式是否啟用
  • version — 目前 App 版本

範例

狀態檔案範例

{
  "activeScene": "Coding",
  "aiLeases": {
    "com.google.Chrome": {
      "holderId": "aion.cli",
      "leaseUntil": "2026-08-07T13:00:00Z",
      "status": "active"
    }
  },
  "blacklist": ["com.apple.Safari"],
  "demoModeActive": false,
  "protections": {
    "autoQuit": true,
    "focusIntegration": true,
    "fullScreenVideoLock": true,
    "instantTask": true,
    "smartGuards": true
  },
  "scenes": [
    { "id": "...", "name": "Coding" },
    { "id": "...", "name": "Meeting" }
  ],
  "version": "2.11.2",
  "whitelist": ["com.apple.finder", "com.apple.dt.Xcode"]
}

CLI 工具

aion-cli.sh — 腳本與 Agent

Aion 專案附帶 Scripts/aion-cli.sh。租約指令使用靈汐的本地 Unix socket 並直接回傳；其他支援的指令使用需手動啟用的 aion:// URL Scheme。狀態 JSON 僅由 status 指令及相關狀態請求更新。

未指定 holder 的 begin/end 範例可跨獨立程序配對，因為 CLI 使用穩定的預設 holder：aion.cli。多個 Agent 需要隔離租約所有權時，請明確傳入 holder。

防止 App 被自動關閉

./Scripts/aion lease begin com.google.Chrome 600

任務完成後釋放租約

./Scripts/aion lease end com.google.Chrome

列出目前活躍的 AI 保護租約

./Scripts/aion lease list

啟動場景

./Scripts/aion scene activate "Coding"

開啟影片鎖

./Scripts/aion protect video on

加入黑名單

./Scripts/aion blacklist add com.apple.Safari

讀取目前狀態

./Scripts/aion status

需要人工協助？

如果你在做本地 Agent 整合，而目前公開說明還不夠，請把你的使用情境與需要的具體訊息流寄給我們。一般安裝與使用問題，還是先看使用指南會更快。

查看使用指南 [email protected]