自动化指南

自动化接入

当本地脚本、工具或自动化流程还在使用某个应用时，让灵汐不要把它当成闲置应用关掉。

纯本地，不走云端适合脚本和本地 Agent关闭前可确认

适用对象

告诉灵汐：这个应用还在忙

当你的本地工具会启动或控制某个应用，并希望灵汐等任务真正结束后再清理它时，就看这页。

适用于本地自动化开发者

如果本地脚本或 Agent 正在控制浏览器、编辑器、终端或上传工具，可以用这页让灵汐在任务完成前保持目标应用打开。

给普通灵汐用户

日常使用不需要看这页。除非你要把自己的本地自动化工具接入灵汐，否则直接看使用指南就够了。

传输方式

当前公开入口

本地保护通道

灵汐在本机提供同一用户可访问的 Unix domain socket。你的工具可以通过它告诉灵汐：哪个应用还在忙。

~/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` 以及你所代表的 Agent 身份标识 (`holderId` / `clientName` / `pid`)。
  3. 收到 `session.ready` 握手成功确认后，即可发送具体指令。
  4. 申请租约时，使用标准的 `AIAppLeaseEnvelope` 结构体。
  5. 如果保护租约过期且没有续期，灵汐在关闭应用前，会向你的 Socket 连接发送一条 `lease.can_close.request` 进行确认。
  6. 收到确认请求后，通过 `lease.can_close.reply` 告知灵汐是否允许关掉应用，或者是否需要临时追加租约。

动作

你可以发送的业务消息

  • 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` 的规则

  • 默认的 `appKey` 即应用的 Bundle ID，例如 `com.google.Chrome`。
  • 支持 Profile 或多开的应用，可以使用带后缀的格式以区分实例，如 `com.google.Chrome#profile-work`。
  • 不支持或未被灵汐识别的 `appKey`，连接会返回 `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 文件路径及其安全通信模型。
  • 标准的握手控制协议。
  • 本文档列出的 Lease 动作及相应的返回状态码。
  • 租期到期后，灵汐在强退应用前发起的确认请求。

只使用文档里的公开入口

  • 灵汐内部的状态存储、Actor 模型边界和 UI 代码实现。
  • 任何未在此公开说明中登记的通道或调试接口。
  • 我们无法保证 any 内部状态的改动都会发出稳定的 API 通知。

实践页

给特定工具的实践说明

先看这页里的稳定接入方式。如果某个工具有额外设置细节，再看对应实践页，不把所有边缘问题都塞进基础指南。

自动化运行时接入细节

针对 Playwright、Puppeteer 等本地自动化运行时的避让与配置细节，帮助 Agent 顺畅地与灵汐并存。

阅读实践指南

2.11 新功能

给可信本地工具的可选 URL 指令

Socket 用来保护正在忙的应用；可选的 aion:// 指令用于更广的控制：切换场景、开关保护、更新列表、读取状态和控制窗口。除非你信任要调用它的本地工具，否则保持关闭。

1
在「高级」设置中开启

打开灵汐 → 设置 → 高级 → External Agent Control / 外部控制，开启开关。默认关闭，需手动开启。

2
从任何本地应用或脚本发送 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 立刻触发一轮闲置应用清理

黑名单管理

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 — 当前激活的场景名称（或 "Standard Mode"）
  • scenes — 全部场景列表（包含 id 和名称）
  • protections.autoQuit — 是否启用自动退出
  • protections.fullScreenVideoLock — 是否启用全屏视频锁
  • protections.smartGuards — 是否启用智能守卫
  • protections.focusIntegration — 是否启用专注模式联动
  • protections.instantTask — 是否启用瞬时任务保护
  • blacklist — 黑名单 Bundle ID 列表
  • whitelist — 白名单 Bundle ID 列表
  • aiLeases — 活跃的 AI 保护租约列表（按 Bundle ID 索引）
  • demoModeActive — 演示模式是否激活
  • version — 当前应用版本号

示例

状态文件样例

{
  "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 被自动关闭（AI 租约）

./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

仍有疑问？

如果你在接入本地自动化工具时遇到瓶颈，或者当前文档无法覆盖你的使用场景，欢迎发邮件联系我们。如果是日常使用问题，查看用户指南能更快获得解答。

查看用户指南 [email protected]