rootshell推送通知与Agent Hooks:让CI/构建通知从任意电脑端到端加密推送到手机
rootshell推送通知与Agent Hooks:让CI/构建通知从任意电脑端到端加密推送到手机
rootshell 是一款为 iPhone、iPad 和 Mac 打造的免费开源终端模拟器。它的推送通知(Push Notifications)功能允许你把任意一台电脑"配对"到手机,之后来自 CI、构建、部署脚本或 AI 编码 Agent(Claude Code、Codex 等)的通知,都会经过端到端加密(X-Wing 后量子混合密钥)推送到 rootshell 手机 App——中转服务器只能看到密文,连标题内容都无法被窥探。
核心关键词速览:rootshell 推送通知 · Agent Hooks · CI/构建通知 · 端到端加密 · rootshell-notify
为什么需要"电脑 → 手机"的加密通知通道?
日常开发场景里,你经常遇到这些问题:
- 在服务器或工作机上跑
make build/ CI 流水线,人却不在屏幕前,构建失败没人知道; - 用 Claude Code、Codex 这类编码 Agent 干活,Agent 完成一轮、或卡在"需要你批准/回答"时,没有及时的手机提醒;
- 普通推送服务(IM bot、邮件)会明文暴露你的标题、日志摘要和路由信息,隐私风险大。
rootshell 的推送体系正好解决这三点:一条免依赖的 Go 小工具 rootshell-notify + 一个只处理密文的无状态中转 + 手机端的解密扩展。
端到端加密是怎么工作的?
整体链路只有三步:
电脑(rootshell-notify) ──密封信封+发送方凭证──> 无状态中转(push.rootshell.com) ──APNs──> 手机(rootshell App)
关键设计(协议细节见 push/PROTOCOL.md):
- 后量子混合加密:每条通知都用 HPKE(RFC 9180)+ X-Wing(ML-KEM-768 + X25519) 密封到手机设备公钥,Go 端实现在 push/envelope/,Swift 端实现在 Packages/RootshellPushKit/Sources/RootshellPushKit/HPKE.swift;
- 中转不可信但诚实:
push.rootshell.com无状态、不落盘,只校验结构、限流并转发密文,永远看不到标题、正文和路由信息; - 防篡改与防重放:事件 ID 被绑入 AAD,重放的中转密文无法被重新解读;
eid同时用作 APNs 的 collapse-id,重试推送会在手机上合并而不是弹两次; - 手机端解密:由通知服务扩展 PushNotificationService/NotificationService.swift 在落锁屏前解密并替换占位文案,即使 App 在后台也能亮通知。
信任模型一句话总结:中转可以被"好奇",但拿不到明文;它最多丢弃、延迟或重放密文,无法伪造你能读到的通知。
三步配对:把电脑接入 rootshell 推送
第 1 步:在手机生成配对命令
在 rootshell 中打开 设置 → Notifications → Push Notifications → Pair a computer。App 会注册到中转、生成一个配对包(rspair1....,内含中转地址、发送方凭证和设备公钥),并显示一条可直接粘贴到终端的一行命令。
第 2 步:在电脑执行安装命令
把手机生成的命令复制到目标电脑执行:
curl -fsSL https://push.rootshell.com/install.sh | sh -s -- --pair 'rspair1....'
这条命令会:下载并校验(SHA-256)rootshell-notify 二进制 → 安装到 ~/.local/bin → 完成配对 → 发送一条测试通知 → 自动为它发现的 Agent 安装 Hook。常用参数:--hooks claude-code,codex 指定 Agent、--project 装到项目级、--system 装到 /usr/local/bin。
第 3 步:确认测试通知到达
手机收到测试通知即配对成功。之后可以用 rootshell-notify devices 查看已配对设备,并按设备单独开关"Agent 自动通知":
rootshell-notify devices toggle "Desk iPad" # 开关某台设备的 Agent 通知
配置保存在 ~/.config/rootshell-push/config.json(0600 权限)。如果手机重装后提示 410(设备重新注册),unpair 旧标签再重新配对即可。
Agent Hooks:Claude Code / Codex 等 5 个 Agent 自动上报
setup 会自动探测并安装各 Agent 的 Hook(幂等、不覆盖你已有的其他 Hook),源码见 push/installer/。各 Agent 支持的事件如下:
| Agent | 上报事件 | 状态 |
|---|---|---|
| Claude Code | 回合结束(Stop) | ✅ done |
| Claude Code | 权限请求、提问、等待输入 | ⏸ blocked |
| Codex | 回合完成(hooks 或 notify) | ✅ done |
| Pi / OMP | 最终成功响应;错误响应 | ✅ done / ❌ failed |
| Pi / OMP | 交互提问、工具审批等待超 2 秒 | ⏸ blocked |
| Hermes | 会话结束、失败回合、人工输入请求 | ✅/❌/⏸ |
几个值得注意的细节:
- Hook 只"报告",绝不"代答":它不会替你回答提问或批准命令;
- 点击通知直接跳回现场:通知携带 pane/tmux/herdr 路由信息,在手机上点一下就能跳回产生通知的那个 rootshell 窗口、标签页和分屏(含 tmux 控制模式);
- Codex 需要信任新 Hook:首次运行
codex后在/hooks中审查并信任 rootshell 条目; - 失败不影响 Agent:Hook 从不写 stdout、不会让 Agent 回合失败,错误只记录到
~/.config/rootshell-push/hook.log。
通知里到底发什么?隐私边界在哪里?
一条 Agent 通知包含(发送前全部加密):
- 标题:
[主机名] Agent · 项目目录,例如[build-mac] Codex · app(最长 120 字符); - 正文:Agent 最后一条消息的前 1-2 句(最多 200 字符),代码块、链接、URL 会被剥离;
- 路由提示:pane ID、tmux 会话、
user@host、工作目录等,用于手机上"点击跳回"; - 线程 ID / 事件 ID:用于分组和去重。
永远不会发送:你的提示词、终端输出、完整转录、文件内容、环境变量。发送前还会对正文做一次凭据形状清洗(api_key=...、Bearer ...、各家云/API key 格式、PEM 私钥、长 hex/base64 串),命中即抹除。
CI/构建/部署:一行命令发自定义通知
不依赖任何 Agent 时,rootshell-notify send 就是最通用的"手机告警器",适合塞进 CI、cron、部署脚本:
# 构建完成
rootshell-notify send --title "Deploy finished" --body "prod is green" --status done
# 构建失败,高优先级、指定设备
rootshell-notify send --title "Build" --status failed --device "Test iPhone" --priority high
--status 支持 done / blocked / failed / info,--priority high 会以高优先级 APNs 推送。配合 CI 的 after-success/after-failure 钩子,就能实现"构建一结束,手机立刻响"。
日常运维速查
| 场景 | 命令 |
|---|---|
| 查看二进制、配对设备、Hook 状态 | rootshell-notify status |
| 向所有设备发测试通知 | rootshell-notify test |
| 升级并刷新 Hook | rootshell-notify upgrade |
| 卸载某 Agent 的 Hook | rootshell-notify uninstall codex |
| 彻底清除本地配置 | rootshell-notify uninstall claude-code --purge |
排错技巧:Hook 出错不阻断 Agent,先看 ~/.config/rootshell-push/hook.log;加 ROOTSHELL_PUSH_DEBUG=1 可让错误打印到 stderr。若 Hook 不生效,通常是 Agent 的 PATH 里找不到 ~/.local/bin,在登录 shell 里导出即可。
想深入阅读?
- 推送协议全文:push/PROTOCOL.md(信封结构、凭证体系、限流与撤销)
- 完整功能指南与 FAQ:push/README.md
- 加密信封参考实现:push/envelope/(Go 端,含 Swift 测试向量)
- 手机端解密扩展:PushNotificationService/
- CLI 源码:push/cmd/rootshell-notify/
总结:rootshell 的推送通知 + Agent Hooks 组合,让你在"人离开屏幕"的每个时刻都能第一时间、且只对你可见地知道 CI 构建结果和 Agent 动态——配对只需一行命令,隐私由后量子端到端加密兜底。


