AI 编程工作流中的推送通知：可靠交付的工程实践

Claude Code 处理一个复杂任务可能需要几分钟甚至几个小时。如果没有通知，你要么盯着终端看，要么隔一会儿回来检查一下，祈祷自己没有错过什么重要的事情。这两种方式都不尊重你的时间。

推送通知让 Tactic Remote 成为了一个工作流工具，而不仅仅是远程查看器。本文介绍我们如何构建通知系统、与 Claude Code hook 的集成、交付可靠性工程，以及我们从真实开发者中观察到的使用模式。

核心洞察

Tactic Remote 中推送通知的价值不在于"你的手机震动了"，而在于通知改变了你与 AI 编程代理交互的时间和方式。你不再需要同步地监控终端，而是获得了异步的任务管理能力：

1. 从 Mac（或 iPhone 应用）启动一个 Claude Code 任务。
2. 离开座位。去泡杯咖啡，参加会议，通勤回家。
3. 当任务完成、遇到错误或需要你审批时，手机会通知你。
4. 你在几秒内完成审查和响应，然后继续做之前的事情。

我们称之为"看手机，不看桌面"的工作流。这与 CI/CD 通知的心智模型一致——你不会盯着构建流水线看，你等它告诉你结果。

Claude Code Hook 集成

通知系统由 Claude Code 的 hook 机制驱动。Hook 是用户可配置的脚本，Claude Code 会在其生命周期的特定节点执行这些脚本。Tactic Remote 的 Mac 伴侣应用注册了三种事件类型的 hook：

任务完成 — 当 Claude Code 完成请求处理时触发。Hook 会捕获退出状态、所做更改的摘要，以及终端输出的最后几行。

需要审批 — 当 Claude Code 遇到需要人工确认的操作时触发（项目目录外的文件写入、Shell 命令、网络请求等）。Hook 会捕获待处理操作的描述和唯一的审批 ID。

错误 — 当 Claude Code 遇到致命错误、工具故障或 API 超时时触发。Hook 会捕获错误信息和相关上下文。

每次 hook 调用都会向 Mac 伴侣服务器发送结构化的 payload，由其决定通知路由、构建 APNs（Apple Push Notification service）payload 并通过我们的通知中继服务分发。

通知类型的实际应用

每种通知类型都针对特定的交互模式设计：

任务完成通知 包含任务摘要和状态指示器（成功或部分完成）。点击通知会直接打开 Tactic Remote 应用并跳转到已完成会话的终端视图，方便你查看输出。

审批通知 具有最高优先级。它们包含操作描述（"Claude 想要在项目目录中运行 rm -rf build/"）并直接在通知横幅上呈现"批准/拒绝"操作。在 iPhone 上，你可以不打开应用就响应审批——长按通知即可看到内联操作。我们的遥测数据显示，62% 的审批是通过通知操作完成的，无需完全打开应用。

错误通知 包含错误类别和截断的消息。它们是可操作的——点击后会打开会话视图，你可以查看完整的错误上下文并决定是重启还是修改任务。

交付可靠性

APNs 并不保证推送通知的送达。Apple 的文档指出通知是"尽力而为"的，可能因设备电量管理、网络条件或速率限制而被丢弃。对于一个开发者工具来说，错过一条审批通知意味着任务停滞，"尽力而为"是不够的。

我们在 APNs 之上叠加了多层可靠性机制：

服务端状态追踪。 Mac 伴侣服务器为每条通知维护一个交付台账。每条通知都有唯一 ID、时间戳和交付状态（待发送、已发送、已确认、已过期）。

客户端确认。 当 iPhone 应用接收并显示通知后，会向 Mac 伴侣服务器发送确认回执。如果 30 秒内未收到确认，服务器会重新发送。

指数退避重传。 未确认的通知会在 30 秒、60 秒和 120 秒间隔后重试。三次失败后，通知被标记为可能无法送达，并在 Mac 伴侣的状态界面中标注。

应用内同步。 当 iPhone 应用打开（或从后台恢复）时，会向 Mac 伴侣查询所有未确认的通知并在通知中心显示。这可以捕获 APNs 完全丢弃的任何通知。

去重。 重传机制带来了重复送达的风险。每条通知携带一个唯一 ID，iPhone 客户端会进行追踪。重复的通知会被静默丢弃——你不会看到同一个审批请求两次。

在实际使用中，我们的交付成功率（从通知发送到通知确认）在 beta 用户群中 10 秒内达到 97.3%，60 秒内达到 99.6%。

通知去重细节

去重值得特别关注，因为它影响用户信任。如果开发者看到同一个"批准文件写入"通知两次，他们会质疑自己是否已经批准过了。如果他们看到一个自己已经批准的操作的审批通知，他们会质疑自己的批准是否已被接收。

我们的去重在两个层面工作：

传输层。 每条通知有一个在重传中保持不变的 UUID。iPhone 客户端维护一个包含最近 500 个已见 UUID 的滚动窗口。任何携带已见 UUID 的通知在显示前即被丢弃。

语义层。 特别针对审批通知，客户端会检查审批 ID 是否已经被处理。如果你通过第一次通知送达批准了操作，而后续重传到达时，即使其传输 UUID 不同（这在服务器为重试生成新推送 payload 时可能发生），重传也会被抑制。

开发者实际使用模式

经过四个月的 beta 数据，清晰的模式已经浮现：

通知高峰时段 是用户当地时间上午 9-11 点和下午 2-4 点——对应编程会话的开始和午餐后的高效时段。

审批通知的平均响应时间 为 12 秒。P95 为 47 秒。这意味着即使在尾部延迟下，人工审批也只为任务执行增加不到一分钟——为安全保障付出的代价很小。

最常见的通知驱动工作流：启动一个多步骤重构任务，离开座位去开会，在会议中通过通知操作批准 2-3 个文件操作，回来后发现任务已完成。

通知量：活跃用户每天收到的通知中位数为 8 条。重度用户（P95）约 30 条。我们在调查中没有观察到通知疲劳——可能是因为每条通知都代表一个可操作的事件，而不是状态更新。

静音模式：15% 的用户配置了"专注模式"规则，在特定时段批量处理非审批通知。审批通知始终会立即送达，不受专注模式影响，因为停滞的审批会阻塞整个任务。

下一步计划

我们正在开发几项通知改进：

• 带代码预览的富通知 — 审批通知直接在通知上显示 diff 预览，让你无需打开应用即可做出知情的批准/拒绝决定。
• 通知分组 — 将快速连续的任务完成通知（在多会话工作流中常见）批量合并为一条摘要通知。
• 自定义通知音效 — 为完成、审批和错误设置不同的声音提示，让你无需看手机就能通过声音分流。

关于通知配置选项，请参阅通知设置指南。关于驱动此系统的 Claude Code hook 参考，请参阅 Hook 集成。