开发者指南

AI 集成

让灵汐在你的本地 AI / Agent 工作流正在使用某个应用时，不把它当成普通闲置应用自动关掉。

本地接入，不走云端同一用户本地 socket 传输自动退出前会先做一次 close-check

适用对象

这里公开的是稳定的接入边界，不是隐藏控制面板

这页的目标，是让本地自动化开发者和技术用户能接入灵汐，同时避免把内部实现细节误写成长期兼容承诺。

给本地 Agent / AI 工作流开发者

当你的本地 Agent 正在驱动浏览器、编辑器或其他应用，而你不希望灵汐把它当成普通后台闲置应用时，就看这页接入说明。

给普通灵汐用户

这页说明的是灵汐 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` 的规则

  • 大多数应用的 `appKey` 就是 bundle identifier，比如 `com.google.Chrome`。
  • 带 Profile 或变体区分的应用可能会使用带后缀的 key，例如 `com.google.Chrome#profile-work`。
  • 未知应用 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 事件。

实践页

给特定接入面的实现说明

先把这页里的基础接入说明吃透。如果某个接入面还有额外的实践细节，优先看对应的实践页，而不是把基础页无限扩展成排查大全。

本地自动化运行时集成

一篇面向本地自动化运行时的接入实践，适合在运行时正在主动驱动某个应用，而你希望灵汐继续把它视为“正在使用中”时查看。

查看运行时接入实践

需要人工协助？

如果你在做本地 Agent 集成，而当前公开说明还不够，请把你的使用场景和需要的具体消息流发邮件给我们。普通安装和使用问题，还是先看用户指南会更快。

查看用户指南 [email protected]