開發者指南

AI 整合

讓靈汐在你的本地 AI / Agent 工作流程正在使用某個 App 時，不把它當成普通閒置 App 自動關掉。

本地接入，不經雲端同一使用者本地 socket 傳輸自動退出前會先做一次 close-check

適用對象

這裡公開的是穩定的接入邊界，不是隱藏控制面板

這頁的目標，是讓本地自動化開發者和技術使用者能接入靈汐，同時避免把內部實作細節誤寫成長期相容承諾。

給本地 Agent / AI 工作流開發者

當你的本地 Agent 正在驅動瀏覽器、編輯器或其他 App，而你不希望靈汐把它當成普通背景閒置 App 時，就看這頁接入說明。

給一般靈汐使用者

這頁說明的是靈汐 AI 保護能力背後的公開接入方式。一般使用者不需要手動設定，除非你要接自己的本地自動化執行環境。

傳輸方式

目前公開入口

公開傳輸入口

靈汐目前透過「同一使用者」的 Unix domain socket 提供 AI lease 通道。

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

目前沒有公開的入口

目前沒有 localhost HTTP 服務、沒有獨立 XPC 端點、沒有自訂 URL Scheme，也沒有 DistributedNotification 傳輸層。

協定流程

一條正常會話應該怎麼走

  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」。

動作

你可以送出的業務訊息

  • lease.begin
  • lease.renew
  • lease.end
  • 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 與目前回應碼。
  • lease 過期並走完 grace 之後，靈汐在自動退出前可能會推送一條 `lease.can_close.request`。

不是相容承諾

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

實務頁

給特定接入面的實作說明

先把這頁裡的基礎接入說明吃透。如果某個接入面還有額外的實務細節，優先看對應的實務頁，而不是把基礎頁無限擴展成排查大全。

本地自動化執行環境整合

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

查看執行環境接入實務

需要人工協助？

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

查看使用指南 [email protected]