4745 字
24 分钟
让 OpenCode 回完话时推送到手机:一条通知链路是怎么搭起来的

我用手机上的 Quetta 连家里电脑的 OpenCode 干活。方便是方便,就是它跑起来之后我完全不知道进度。有一回它吭哧吭哧跑了五分钟,手机一点动静都没有,我不知道它是在改代码、在等一个慢命令,还是已经卡死了,只能隔两分钟切回去刷一眼,对着一屏工具输出用眼睛扫。

所以我给自己加了个通知:它一回完话,手机弹通知、响一声。

先做的是长轮询,后来发现息屏就不灵,又把 Web Push 补上,顺带记一次「以为成功了其实是假象」的翻车。


什么才算「回完话」#

直觉上会去监听「消息结束」,但 OpenCode 的事件流里没有这么干净的东西。模型一轮回复常常是这样:

模型说:"我看看这个文件" → 调工具 → 拿到结果
模型说:"那我改一下" → 调工具 → 拿到结果
模型说:"改好了,你看看" → 没有工具调用了 → 这一轮才算完

中间每调一次工具,它都会「结束一次」。监听错了,我每改一个文件就给自己弹一次通知,两轮之内我就会把它关掉。

实际做法是连 /api/event,盯 session.step.ended。data.finish 是 tool-calls,说明模型还要调工具,话没说完;不含 tool 字样,这一轮才算完。抓到的真实事件长这样:

{"type":"session.step.ended","created":1792381403395,"location":{"directory":"C:\\Users\\ycx\\Documents\\OpenCodeProject"},
"data":{"sessionID":"ses_...","assistantMessageID":"msg_...","finish":"tool-calls",
"rawFinish":"tool_calls","cost":0,"tokens":{"input":41,"output":104}}}

判断就一行:

if (/tool/i.test(String(d.finish || ''))) return // 还要接着干活

我本来想把 finish 的取值全枚举出来写进文档,后来放弃了。我只抓到 tool-calls 这一种,「说完」那次的完整事件是在 watcher 起来之后才发生的,没留原文。所以现在用的是反向判断:不含 tool 就通知。供应商哪天换成 tool_use 之类的写法,也挡得住。

正文靠另一个事件攒:session.text.ended 每段带着 ordinal,按 assistantMessageID 收着,等 step.ended 确认说完了再拼起来,截到一百来字当通知内容。


为什么拆成三个进程#

flowchart LR OC["OpenCode 服务 49374"] -->|"api/event 长连接"| W["watcher.mjs"] W -->|"POST api/say"| S["oc-notify 中枢 5180"] CF["Cloudflare 隧道"] -->|"HTTP"| S PHONE["手机 Quetta 页面"] -->|"GET api/wait 长轮询"| CF S -->|"有动静立刻回"| PHONE

通知一开始是写在 OpenCode 插件里的。插件 API 有 ctx.event.subscribe(),写起来很干净。后来撞上两件事。

一是插件要重启 OpenCode 才加载。我改一行代码就得重启服务,而服务一重启,我正在聊的会话就断了。为了加一句日志截断去重启一次,不值当。

二是插件挂了之后通知全没了,而且是静默的,你只会觉得「怎么不响了」。

拆出来就顺了:改 watcher 只重启 watcher,OpenCode 一根汗毛都不动;watcher 崩了有守护进程拉起来;插件里只留一个 notify_user 工具,让我干活干到一半能主动喊你一声。


最大的坑:Cloudflare 把 SSE 整个吞了#

第一版是 SSE,服务端 text/event-stream 一路写,浏览器 new EventSource() 收,最标准的做法。本地测完美:

本地直连: 收到 3 条 ✅ 首块="retry: 3000\n\nid: 1\ndata: {\"id\":1,..."

同一个服务、同一个隧道地址,走公网:

公网隧道: 收到 0 条 ❌ 首块=null

连首块都没有。不是丢了几条,是一整块都没到。health 接口显示服务器那边的连接是建立的(waiters=1),请求到了,响应也发了,浏览器什么都没收到。

我先怀疑是 WebSocket 被代理挡了。这台机器上 QUIC 确实不通,拉 tunnel 第一次连就超时。但 WS 和 SSE 在 Chrome 里走的是同一条 QUIC/HTTP2 链路,不至于一个通一个不通。写了个对照脚本,分别打本地和隧道,才把变量隔离开:

/api/health 普通请求SSE 长连接
本地直连✅✅
Cloudflare 隧道✅ 86ms❌ 0 条

普通 HTTP 请求完好无损,只有流式响应被吞。基本只能是 Cloudflare 边缘做了响应缓冲:它攒够一定量或一定时间才往客户端吐,而 SSE 前几秒可能一个字节都没有。

解法很朴素,换成长轮询:

GET /api/wait?after=123 → 有新消息立刻返回,没有就挂着,最多等 25 秒

服务端把所有挂起的请求记在一个 Set 里,publish() 的时候挨个叫醒。浏览器拿到响应立刻发下一个请求。25 秒是兜底,万一中间有 bug 没叫醒,页面最多卡 25 秒,不会永远安静。改完再测:

本地直连: 挂上=是 | 端到端 6ms | 拿到 1 条 ✅
公网隧道: 挂上=是 | 端到端 277ms | 拿到 1 条 ✅

277 毫秒,经过一次公网往返、一层 Cloudflare 边缘、一次回源,用起来完全没感觉。

WARNING

以后要在 Cloudflare 隧道后面做实时推送,先测普通长轮询能不能穿透,别默认 SSE 可用。普通请求走的是完全不同的代码路径,前者通不代表后者通。


让标签页别被冻结#

Android 上有个绕不开的限制:标签页一旦息屏或被系统回收,JS 就不跑了。这时候不管是 SSE 还是长轮询,都收不到东西。

先说个土办法。Chrome 对正在播放媒体的标签页有优待,不冻结、不降频、不回收。所以只要让它一直在放,标签页就一直活着。关键在于这段音频得是真静音但真在播:

// 8kHz / 8bit / 单声道,2 秒纯零,volume 0.01
// 听不见,但浏览器认为你在放音频
const a = new Audio(silentWav(2, 8000))
a.loop = true
a.volume = 0.01
a.play()

WAV 头 44 字节加全零采样,运行时用 DataView 现拼,不用额外的资源文件。能覆盖到的场景:

场景长轮询能不能收到
正在看 OpenCode✅
切到别的 App,屏幕还亮着✅
屏幕常亮但没操作✅
锁屏 / 息屏❌
把 Quetta 从后台划掉❌

后面两条是下一节要解决的。


Web Push:加密写对了,送达没解决#

长轮询的极限就是「标签页还活着」。要真正锁屏可达,只能靠 Service Worker 加 Push Manager。浏览器会替你在后台唤醒 Service Worker,这一步不受页面死活影响。

为了保持整个项目零依赖,我没装 web-push,手写了两个规范:

  • VAPID(RFC 8292):生成一对 P-256 密钥,用 ES256 给每次请求签一个 JWT
  • aes128gcm(RFC 8291):加密通知正文

正文的结构是这样:

salt(16) │ rs(4) │ idlen(1) │ asPub(65) │ ciphertext │ tag(16)

推导链条:

shared = ECDH(临时私钥, 接收方公钥) // p256dh
ikm = HKDF(salt=auth, ikm=shared, info="WebPush: info\0" + uaPub + asPub)
cek = HKDF(salt, ikm, "Content-Encoding: aes128gcm\0", 16)
nonce = HKDF(salt, ikm, "Content-Encoding: nonce\0", 12)

明文末尾要补一个 0x02 当 padding 分隔符。三个 HKDF 的 info 字符串少一个 \0 或者顺序写反,密文就是废的,而且不会报错,只是对方解不出来。

ES256 还有个坑。JWT 里的签名是裸的 r || s(64 字节),不是 DER 编码。Node 默认给 DER,得显式说:

crypto.sign('sha256', data, { key, dsaEncoding: 'ieee-p1363' })

自己读规范写的东西,得找个参照。我把业界标准实现 web-push 装到临时目录当对照组,用它的底层库 http_ece 去解我自己加密的密文:

A aes128gcm 正文: OK 完全一致
B VAPID JWT : OK ES256 签名 / typ / aud / exp<=24h / sub 全部合规
C body 结构 : OK salt16 + rs4 + id65 + ciphertext+tag

这三条过了,说明 salt、rs 字段、HKDF 的 info 字符串、CEK 和 nonce 的推导顺序、ES256 的编码方式,全都和标准实现一致。web-push 只活在临时目录里,项目本身还是零依赖。

headless Chrome 验不了这一段#

想在本机自动化验证,思路是起一个 headless Chrome,用 CDP 的 Browser.grantPermissions 授权,再调 pushManager.subscribe() 拿真实订阅。

权限确实拿到了,Notification.permission 返回 granted,secure context 也正常。但 subscribe() 挂死不返回,逐步诊断下来卡在订阅这一步:

1 SW register {"ok":true,"v":"activating"}
2 getSubscription {"ok":true,"v":null}
3 取 vapid 公钥 {"ok":true,"v":"BKkc0uqXV95nUGeA9b1Q..."}
4 pushManager.subscribe {"ok":false,"e":"超时"}

headless 没有 GCM 注册,这条路是死的,最后只能拿真机试。顺带一个探测结果:直接往 FCM 旧端点打一个假订阅,返回 400 而不是 404,说明端点还在解析请求,当时算是半个好消息。

真机结果:我当时判断错了#

手机上点「开启息屏通知」,订阅存下来之后:

新增 push 订阅 https://fcm.googleapis.com/fcm/send/fAmlCqH0hhE:APA91bG75BNh…(共 1)
push 已下发 1/1

连发四条,FCM 全部接受。我锁了屏,然后看到了两条通知,当时的结论是「Web Push 穿透成功」。

这个结论是错的。 证据有三条,我当时手里就有,只是没去对:

第一,时间对不上。我发第一条是 12:39:43,第二条是 12:40:24。手机通知栏里两条都显示 12:41,挤在解锁打开浏览器的那一刻。这是长轮询恢复后从历史里补发的时间点,不是推送的即时投递。

第二,ack 一次都没到。我让 Service Worker 每弹一条通知就 POST 一次 /api/ack(下面会细说)。四条 push 全部 push 已下发 1/1,日志里零条 ack,而手动 curl 这个端点是通的。

第三,push 已下发 1/1 这个词骗了我。它只是 FCM 返回了 2xx,意思是「这条消息我收下了」。收下之后送不送到设备,是另一回事,旧版接口尤其容易悄悄丢掉。

所以那两条通知的真实来源是长轮询:页面一活过来,把积压的消息补发了一遍。Web Push 一次都没工作过。

flowchart TD P["publish 一条通知"] --> A["长轮询"] P --> B["Web Push"] A --> A1["页面活着 58ms 到"] A --> A2["页面冻结或息屏 收不到"] B --> B1["FCM 收了 2xx"] B1 --> B2["设备上没弹出来"]

至于为什么没弹出来,我到现在也没定位:可能是那个浏览器的 GCM 投递通道不工作,可能是设备上的 Service Worker 还是旧版本(没有 push 监听器,事件被静默丢弃),也可能 FCM 旧接口对纯 VAPID 认证只收不投。三条我在这里分不出来,因为我没有第二台设备做对照。

那个救了我一次的探针#

让 Service Worker 每弹一条通知就往服务器 POST 一次 /api/ack,本来是想证明「FCM 说收到」和「手机真弹了」是两回事。结果四条 push 全部 push 已下发 1/1,日志里一条 ack 都没有:

04:40:24 publish #4 "💬 Friendly greeting" -> 0 waiter(s)
04:40:24 push 已下发 1/1
(没有)push 已被浏览器接收

手动 curl 一下 /api/ack 端点是通的,说明不是服务端路由的问题。这条探针是我在写完加密、验证完交叉对照之后才加的,本来只是个辅助,恰恰是它把「其实一次都没送达」这件事摆在了日志里。

不过它自己也有毛病:SW 里那个 fetch 我写了 .catch(() => {}),静默吞掉一切。现在回头看,就算 ack 真的因为别的原因失败了,我也不会知道。一个为了查问题加的探针,因为错误处理写了空函数,反而把问题本身藏起来了。

后来我把它拆成三段回执(push-received / notified / notify-failed),这样至少能区分「推送压根没到」「到了但弹不出」「弹了但后续失败」。这次没再跑第二轮验证,所以它到底能不能区分,也还不知道。


同一个域名下的另一个坑:OpenCode 网页端会抢走所有导航#

临时地址用着好好的,我想把它固定下来。正好我给电脑上的 opencode 也是通过 https://oc.ycxdev.com 反向访问的,于是在 cloudflared 的 ingress 里加了一条路径分流,想让 oc.ycxdev.com/nt/ 指向通知中枢:

ingress:
- hostname: oc.ycxdev.com
path: ^/nt(/.*)?$
service: http://127.0.0.1:5180
- hostname: oc.ycxdev.com
service: http://127.0.0.1:49374 # 原来的 OpenCode,一行不动

配置改对、服务重启、curl 也测通了。手机上打开却是这个:

出了点问题 · 加载应用程序时发生错误 · Error: Unrecognised route!

打开的是 OpenCode 的 SPA,它不认识 /nt/<token>/ 这个路径。

原因是 PWA 的 Service Worker 把导航全换了#

oc.ycxdev.com/sw.js 是 OpenCode 网页端注册的 Service Worker,作用域是整个域名 /,用的是 Workbox。它对导航请求的匹配逻辑压缩后是这样:

if (request && "navigate" !== request.mode) return false // 所有导航都拦
for (const d of denylist) if (d.test(pathname + search)) return false
return allowlist.some(re => re.test(pathname + search)) // 默认 [/./] 匹配一切

配的是 createHandlerBoundToURL("/index.html"),denylist 只有四条:

[/^\/(?:api|auth)(?:\/|$)/, /^\/(?:_assets|assets)(?:\/|$)/]

也就是说,这个 origin 上除 /api/、/auth/、/_assets/、/assets/ 之外的每一个导航,都会被换成 OpenCode 的 index.html。我挂在 /nt/ 下面的页面,正好落在放行名单外。

怎么复现的#

这一步值得单说,因为我一开始在电脑上测是正常的。因为电脑上那个 Service Worker 还卡在 installing,没接管。等它变成 activated,一刷新,同样的地址就变成了:

{
controlledBy: "https://oc.ycxdev.com/sw.js",
isNotifyPage: false,
body: "出了点问题 | 加载应用程序时发生错误。 | ..."
}

和手机上一模一样。所以同一个地址在电脑上「能用」,只能说明那个 SW 还没激活,不能说明方案成立。

解法:前缀踩进 denylist#

规则写在 sw.js 里,改不了,那是 OpenCode 的产物。只能把自己的前缀塞进它的放行名单:

path: ^/api/nt(/.*)?$

/api/nt/… 命中第一条 /^\/(?:api|auth)(?:\/|$)/,SW 直接放行到网络,再由 cloudflared 分流给通知中枢。不需要新域名,不需要动 DNS,用的还是同一张证书。

验证时我特意没有开干净浏览器,而是在那个正在劫持的 SW 上测:

{
controlledBy: "https://oc.ycxdev.com/sw.js", // SW 还在控制
isNotifyPage: true, // 但我的页面正常
net: "已连接"
}

端到端 58ms。这条坑的适用范围比这篇博客大:只要你往一个已经部署了 PWA 的域名下挂别的东西,就得先看它的 Service Worker 有没有 fetch handler 和导航兜底。同一个 origin 下想共存,前缀通常得落在对方的放行名单里,或者干脆换个子域。


六个把我坑了的具体细节#

都是小 bug,查起来很费时间。

AbortSignal.timeout(0) 是立刻超时#

signal: AbortSignal.timeout(0) // ❌ 请求发出后 0 毫秒就 abort

我拿它当「不设超时」用。watcher 一连上去就 The operation was aborted due to timeout,日志刷了六次退避重试。长连接得自己拿 controller:

const ac = new AbortController()
fetch(url, { signal: ac.signal })
process.on('SIGTERM', () => ac.abort())

插件的 options.namespace 必须传字符串#

options: { namespace: true } // ❌
options: { namespace: 'oc-notify' } // ✅

传 true 的话,服务端会执行 (options.namespace).split("."),整个插件被禁用:

Plugin disabled after tool.transform failed.
cause="TypeError: e.split is not a function"

OpenCode 不会崩,它只是把这个插件悄悄关掉。配置改完去 /api/plugin 看一眼 state.status 就能确认。好消息是 OpenCode 会热加载配置文件,不用重启服务,我那次就是靠这个快速试出了几种写法。

OpenCode 的 API 响应包了一层#

(await res.json()).title // ❌ 永远是 undefined
(await res.json()).data.title // ✅

POST /api/session、GET /api/session/{id} 都返回 { data: { ... } }。通知标题一直是「OpenCode 回复了」而不是会话名,就是栽在这儿。

PowerShell 的 -Encoding UTF8 会写 BOM#

Terminal window
Set-Content -Value $json -Encoding UTF8 # ❌ 开头有 BOM
curl.exe --data-binary "@file.json" # → Expected a valid JSON body

Windows PowerShell 5.1 的 UTF8 是带 BOM 的。服务端剥掉 BOM 更容错:

Buffer.concat(chunks).toString('utf8').replace(/^\uFEFF/, '')

这台机器上 QUIC 不通#

cloudflared 默认走 QUIC,连 Cloudflare 边缘一直超时:

Failed to dial a quic connection error="timeout: no recent network activity"

它自己的诊断输出写得很清楚:

| UDP Connectivity | FAIL | QUIC connection failed |
| TCP Connectivity | PASS | HTTP/2 connection successful |

加 --protocol http2 就行。你现有的 cloudflared 服务配置里其实早就写了 protocol: http2,只是我新拉起的那个没照抄。

提权跑脚本之前忘了先做语法检查#

那个改 cloudflared 配置的脚本要管理员权限,我用 Start-Process -Verb RunAs 拉起来,然后等它报错来告诉我哪里写错了。它确实报错了:

At enable-permanent-route.ps1:113 char:103
+ ... 正常' } else { '仍然不通!...' + $backup }) -ForegroundColor $(if (...
+ ~~~~~~~~~~~~~~~~
Unexpected token '-ForegroundColor' in expression or statement.

我在字符串拼接里嵌了个 $(if …),括号位置放错了。而这件事本地就能查出来,根本不需要提权:

Terminal window
$errs = $null
$null = [System.Management.Automation.Language.Parser]::ParseFile($f, [ref]$null, [ref]$errs)
if ($errs.Count) { $errs } else { '语法检查通过' }

顺带两个同源的坑:Start-Process -Verb RunAs -ArgumentList '-Command', $长字符串 里的引号会被吃掉,得改成传 -File 一个包装脚本;Write-Host 走宿主不走管道,*>&1 | Out-File 捕获不到,要用 Start-Transcript。


三种触发方式#

触发谁发起什么时候用
reply自动我回完话,不需要你做任何事
manual插件的 notify_user 工具需要你授权、要你点东西、跑完长命令时
test页面上点「发个测试」自己验证链路

插件那边就两个注册,工具加命令:

export default {
id: 'oc-notify',
async setup(ctx) {
await ctx.tool.transform((editor) => {
editor.add({
name: 'notify_user',
description: '给用户手机推一条通知(系统通知 + 提示音)……',
input: {
type: 'object',
properties: { message: { type: 'string' }, title: { type: 'string' } },
required: ['message'],
additionalProperties: false,
},
options: { namespace: 'oc-notify' },
execute: async ({ message, title }) => {
const ok = await say({ title, body: message })
return { content: ok ? '通知已推送。' : '推送失败。' }
},
})
})
},
}

手机页面上那几行状态灯是我最常用的排障手段,一眼能看出是没连上、没权限、音频没解锁,还是推送没订阅:

flowchart TD A["手机点开启"] --> B{"通知权限 granted"} B -->|否| B1["系统通知不弹"] B -->|是| C{"AudioContext running"} C -->|否| C1["提示音不出"] C -->|是| D{"push 有订阅"} D -->|否| D1["息屏收不到"] D -->|是| E["全通"]

还没解决的#

息屏还是收不到。Web Push 的加密和鉴权我验证过了,设备上的订阅也拿到了,FCM 每次都收下,但通知一次都没弹出来,原因在第五节说了,没定位。

现在能用的只有长轮询那一路:页面开着 58ms 到,页面冻结或息屏就断。静音 WAV 保活能多撑一会儿,挡不住锁屏。要真正解决得换一条腿:Telegram bot 推送(不依赖浏览器,锁屏必达),或者换一个推送实现正常的浏览器。

至于 /api/ack 那套三段回执,改好了,但没跑第二轮验证,能不能真的区分「没到」「弹不出」「弹了但后续失败」,还不知道。调试代码的错误处理不能写空函数,这条不用验证也成立。

整条链路本身很轻:一个零依赖的 Node 中枢(5180)、一个独立进程的 watcher、一个手机上的静态页面,加一条 Cloudflare 隧道。没有数据库、消息队列或账号系统,加密和鉴权两个 RFC 加起来不到 150 行。

最后那个「响一声」,客观上确实比每两分钟切回去刷一次省事。

让 OpenCode 回完话时推送到手机:一条通知链路是怎么搭起来的
https://ycxdev.com/posts/opencode-phone-notify-push/
作者
YCX
发布于
2026-10-19
许可协议
CC BY-NC-SA 4.0