feat(device-link): notify 帧与 hello-ack capabilities 能力协商(移动推送)

[dashhuang]

动机 / Motivation

给「桌面任务终态 → 手机系统推送」提供中继层协议支撑:桌面端在会话完成 / 出错 / 待回复时,经已有的 device-link relay 长连接请求 server 给本账号已注册推送 token 的移动设备下发 APNs 推送。手机端后台 WS 会被 iOS 挂起,系统推送是唯一可靠的后台触达通道。

变更类型 / Change type

• 协议变更(类型/字段/信封/路由语义/常量) / Protocol change
• 文档 / Docs

兼容性影响 / Compatibility impact

全部 append-only,不 bump PROTOCOL_VERSION:

• EnvelopeKind 新增连接层 'notify'(client→server,relay 消费不转发)。relay 对未知 kind 静默丢弃(黑洞),因此引入 hello-ack.capabilities 能力协商:server 声明 'notify'(常量 SERVER_CAPABILITY_NOTIFY)后客户端才允许发送。
  • 新客户端 + 老 server:hello-ack 无 capabilities = 空集 → 不发送(降级为无手机推送);
  • 老客户端 + 新 server:忽略新增可选字段,行为不变。
• HelloAckPayload.capabilities?: string[](可选新增字段)。
• RelayErrorCode 新增 'RATE_LIMITED'(notify 频控):只会发给已声明 notify capability 的 server 的对话方,老客户端不发 notify、不会收到。
• NotifyPayload 类型 + NOTIFY_*_MAX_LENGTH 字段上限常量。
• docs/device-link-protocol.md §9 版本纪律补充「relay 消费(不转发)的连接层新 kind 可用 capability 协商代替 version bump」的例外条款。

两侧同步升级安排:server(cindy-server)先合入部署(声明能力),客户端仓(cindy-moved)随后 bump 指针接入;两个消费方 PR 均已就绪,合并本 PR 后跟进。

「三件套」自查 / The "trio"

• 类型定义 / Type definitions
• parse 运行时校验 / Runtime parse validation —— 按本仓 docs/device-link-protocol.md §9 的承载范围约定,device-link-protocol 包只承载类型与常量,parse 校验由消费方实现:relay 侧校验在 cindy-server device-link-server/src/device-link/notify.ts(错误信息带字段名)
• 测试 / Tests —— 同上,在消费方:cindy-server notify.test.ts(roundTrip + 坏帧拒收,fixture 全部中性占位值)与 deviceLinkRelay.test.ts(能力声明 / 下发 / BAD_REQUEST / RATE_LIMITED)
• 文档 / Docs —— docs/device-link-protocol.md kind 表、能力协商、错误码、payload 参考、版本纪律

检查项 / Checklist

• 遵循 CONTRIBUTING 的协议演进纪律
• commit message 符合规范
• 一个 PR 只做一个逻辑变更
• 测试 fixture 使用中性占位值
• pnpm test 与 pnpm typecheck 通过(本地全绿)

🤖 Generated with Claude Code

[dashhuang]

合并方式请求(维护者注意):消费方 xindong/cindy-moved#586 已先行合入,其 submodule 指针指向本分支的 88e69f6;xindong/cindy-server#100 指向 4468730。请用 merge commit 方式合并本 PR(保留分支上这两个 commit 在 main 可达),或告知采用 squash——届时我会跟进给两个消费方仓提指针 re-bump PR。在此之前请勿删除本分支,否则两个消费方的 submodule fetch 会断。