Ekko Studio 苹果 Live Activity 注册恢复与优先级滚动发布：实现原理、配置开关与升级注意事项

AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载本文是 Ekko Studio本地优先的多 Agent 聊天、编码与可视化工作流工作台中苹果 iOS Live Activity灵动岛/锁屏实时活动推送能力在「注册恢复registration recovery / catch-up」与「优先级滚动priority rollout / relevance」两个方向的实现与运维指南。内容以仓库 docs/live-activity/recovery-and-priority.md 为核心骨架并结合服务端源码与测试用例展开。读完本文你将掌握Live Activity 注册补发机制的边界条件、防抖与限流策略、30 分钟启动预算抑制规则以及liveActivityRelevanceEnabled配置开关的语义、网关契约与升级注意事项。一、文档定位与核心结论速览recovery-and-priority.md是一份高度凝练的设计决策与发布约束文档它不讲解 Live Activity 从零搭建而是聚焦两个已经落地/正在落地的能力注册恢复catch-up当 iOS 设备重新注册 Live Activity 推送目标后服务端在受控范围内补发当前运行中的任务快照避免注册前已经跑起来的任务在灵动岛上永远不出现。优先级滚动priority通过给 APNs 推送附加relevance-score字段让 iOS 在灵动岛/锁屏上对实时活动做排序提示该能力默认开启但允许通过持久化配置显式关闭。文档给出的核心约束可以概括为 8 条下文逐一展开补发范围仅限普通活跃聊天任务含 coding agent排除群聊group与工作流workflow绑定补发对象先授权调用方最多选择一个最近更新的已授权任务且只针对该任务注册的 connection 投递快照要求运行态快照必须匹配当前回合turn且不能处于 aborting 状态状态机已有活跃 activity 走更新终态记录绝不因注册而被复活并发与节流在途重复补发被合并coalesced注册触发的补发 2 分钟内节流目的地在有记录的 start 后 30 分钟内抑制补发启动全局影响普通 live start 不受本变更的全局预算限制优先级开关liveActivityRelevanceEnabled缺省或为true时启用config.json中显式false关闭传输且升级后保留免责边界以上防护不揭示也不重置 Apple 的预算也不保证创建成功relevance-score只是排序提示不是显示顺序保证更不增加推送预算。二、注册恢复Catch-up受控补发而非无脑重放2.1 触发点注册即补发恢复流程由 live-activity-registration.ts 的updateLiveActivityDestination驱动当移动端完成一次合法的 Live Activity 目标注册updateLiveActivityDestination(token, value)并落库后代码会立即异步触发saveLiveActivityDestination({ ... }) void catchUpLiveActivities(connection.id).catch(() { console.warn([live-activity] catchup_failed) })也就是说每次成功的注册/重注册都会尝试一次补发。注册入口本身还会校验appearance仅light/dark、locale白名单zh|zh-TW|en|ja|ko|fr|es|de|pt|ru|ar、push_tokenpush_ 43 位、apns_environmentdevelopment/production等字段非法注册直接 400从源头避免脏数据进入补发流程。2.2 补发实现单连接、单快照、立即中止核心实现在 live-activity-catchup.ts 的catchUpLiveActivities(connectionId)export async function catchUpLiveActivities(connectionId: number): Promisevoid { if (!deliver || pending.has(connectionId)) return if (Date.now() - (lastAttempt.get(connectionId) || 0) 120_000) return const device listLiveActivityDestinations().find(row row.connection_id connectionId row.enabled) const user device findUserById(device.user_id) if (!user || user.status ! active) return lastAttempt.set(connectionId, Date.now()) ... const snapshots getChatRunServer()?.getLiveActivityPlans?.() || [] for (const entry of snapshots) { const plan taskPlanWebhookSnapshot(entry.snapshot) if (!plan || plan.execution_state ! running) continue const event: BusinessEvent { ... } if (!canReceiveAppEvent(user, event)) continue await deliver(event, connectionId) break // At most one latest authorized task; do not burst push-to-start on reconnect. } }结合文档约束可以还原完整语义仅活跃普通聊天任务只处理execution_state running的快照running即未 aborting满足不处于 aborting的约束快照经taskPlanWebhookSnapshot转成chat.plan.updated业务事件天然只覆盖 chat 类任务。授权先行findUserById校验用户为activecanReceiveAppEvent再做事件级授权过滤——补发不会绕过消费者侧的权限检查与重放防护源码注释明确Snapshot events bypass neither consumer permission checks nor replay protection。单任务投递循环中break只投递第一个匹配的活跃快照配合deliver(event, connectionId)只针对该连接实现至多选择一个最近更新的已授权任务。不复活终态投递目标deliver即主消费者consume(event, heartbeatfalse, targetConnectionId)消费者内对targetConnectionId ! undefined的分支会执行const stored getLiveActivityRun(key) if (stored?.terminal) return // registration never revives a terminal activity已终态的 Live Activity 记录直接跳过因此注册永远不会复活一张已经结束的卡片。去重与串行同一个 activity key 的投递经由serialized队列串行执行latest/polling机制保证最新快照优先重复的在途补发天然被合并。2.3 防抖与预算抑制文档中的三条时间约束都能在代码中找到对应实现约束实现位置语义注册触发补发 2 分钟节流lastAttemptMap 120_000直接返回同一 connection 两次补发至少间隔 2 分钟在途重复补发合并pendingSet同一 connection 的补发并发去重coalesced记录 start 后 30 分钟抑制补发启动主消费者Date.now() - getLiveActivityLastStart(...) 30 * 60_000见下文 2.4lastAttempt还做了容量保护超过 1000 个条目时淘汰最旧防止长运行实例内存无限增长。2.4 30 分钟启动抑制的真实含义在 live-activity.ts 的补发分支targetConnectionId ! undefined中if (targetConnectionId ! undefined Date.now() - getLiveActivityLastStart(device.destination_id) 30 * 60_000) return await dispatch(event, device, registration, key, start)getLiveActivityLastStart读取的是 live-activity-runtime-store.ts 中live_activity_start_budget表destination_id主键 last_start_at该表在每次成功start时由recordLiveActivityStart(device.destination_id, Date.now())写入。含义若该 destination 在最近 30 分钟内已经成功启动过 Live Activity则注册补发不会再次发起 start——因为卡片很可能仍然活跃在锁屏/灵动岛上重复 start 只会白白消耗推送预算。注意这是有记录的 start成功收到网关 2xx 后才记录未记录的成功不构成抑制条件。同时文档明确正常 live start 不受本变更全局预算限制——该 30 分钟窗口只作用于注册补发路径不影响任务自然流转中的 start/update/end。2.5 消费者侧对补发的最终校验即使补发事件进入主消费者consume仍会二次确认if (targetConnectionId ! undefined) { if (!active(event)) return const stored getLiveActivityRun(key) if (stored?.terminal) return }其中active(event)要求runKind(event) chat排除 group/workflow 绑定且isLiveActivityRunActive(...) true——运行态快照必须与当前回合匹配且未 aborting。这一层消费者 ownership/connection 检查重复正是文档所述Consumer ownership/connection checks are repeated的体现设备连接有效性validConnectionconnection_id/user_id/device_code/token_hash 全匹配、未吊销、未过期与运行态在补发时都会被重新验证。三、优先级滚动Priority / Relevance默认开启的排名提示3.1 配置开关语义优先级传输由持久化配置liveActivityRelevanceEnabled控制定义于 app-config.ts 的AppConfig接口export interface AppConfig { // Defaults on for supported gateways. Explicit false opts out for old gateways; persisted in appHome/config.json. liveActivityRelevanceEnabled?: boolean ... }语义缺省或true启用优先级传输default-on显式false禁用传输并跨升级保留persisted。该配置位于 Studio 持久化用户数据目录的config.jsonconfig.appHome/config.json见 app-config.ts 的APP_HOME/APP_CONFIG_FILE。全局配置的读写走readAppConfig/writeAppConfig读端带进程内缓存写端使用safeFileStore.updateText实现锁定读-合并-写 备份{ backup: true }并最终chmod 0o600收紧权限。数据库类设置如live_activity_runs、live_activity_start_budget表则落在持久化 appHome 下与配置文件同源同目录。3.2 默认开启的前提网关必须支持 relevance_score文档强调默认开启要求网关支持顶层relevance_score字段使用旧版/自托管网关的部署必须先在升级前显式设置false否则可能出现网关不识别字段的情况。这是 default-on 策略对部署方的硬性前置条件。3.3 网关契约maintainer 已确认文档给出已部署提交43c870356b4aebb57a57b8e01f65b31d36e8fb79的网关契约要点relevance_score可选的有界有限数字范围0..9007199254740991即Number.MAX_SAFE_INTEGER生命周期start/update/end三个动作都会携带/处理持久化网关持久化该值并透传给 APNs 的aps[relevance-score]幂等与大小校验relevance_score参与网关的幂等键与消息大小检查非法值返回400 invalid_relevance_score取值约定Studio 使用业务 Unix 秒心跳heartbeat与补发catch-up保留原始业务时间end动作发送0。这些约定与源码一一对应live-activity.tsif ((await readAppConfig()).liveActivityRelevanceEnabled ! false) { const businessAt event.chat?.task_plan?.updated_at ?? Date.parse(event.occurred_at) const score action end ? 0 : businessAt / 1000 if (Number.isFinite(score) score 0 score Number.MAX_SAFE_INTEGER) body.relevance_score score }业务时间而非派发时间score task_plan.updated_at / 1000业务 Unix 秒注释明确Business event time, not dispatch/heartbeat time: heartbeats cannot steal priority——心跳2 分钟刷新沿用原值不会因为刷新而偷到更高的优先级。end 归零action end ? 0。范围防护Number.isFinite0 score MAX_SAFE_INTEGER与网关的 400 边界完全一致。显式 false 兼容旧网关! false的判断意味着只有显式false才整体移除relevance_score字段。测试 tests/server/live-activity.test.ts 覆盖了完整语义sends business priority by default when the setting is absent——配置缺省时 start 携带relevance_score Date.now()/1000preserves explicit opt-out for old gateways on start update and end——显式false时 start/update/end 三动作均无relevance_score字段gates priority and preserves business priority across heartbeat——心跳沿用task_plan.updated_at/1000end 发送0且 update/end 与 start 的值语义正确。3.4 定位排名提示而非保证文档与代码都反复强调边界relevance-score只是给 iOS 的排序提示ranking hint不保证显示顺序也不代表 push-to-start 预算增加注册恢复与优先级机制都不揭示也不重置 Apple 的 Live Activity 预算live_activity_start_budget只是 Studio 自身的启动记录而非 Apple 配额更不保证卡片一定创建成功。文档明确No claim of immediate display or iOS forced ordering.四、发布前验收清单与已知边界文档列出的发布前置条件网关审批与部署relevance_score契约含 400 校验、幂等/大小检查、APNs 透传需先上线补发授权测试catch-up的授权/权限/重放防护路径需完整覆盖真机多活动验收实际设备上多 activity 并存的端到端验收对应测试 live-activity.test.ts 中separate activities for separate sessions等用例持久化 appHome 挂载与重启检查config.json与数据库在挂载/重启后保持一致。已知边界务必向用户/测试人员明确前台重复注册仍可能返回 accepted但Apple 预算耗尽时不创建卡片不做立即显示或iOS 强制排序的承诺正常升级保留已配置的 user-data 挂载卸载/清除数据或挂载连续性受损时不保留配置随数据目录走liveActivityRelevanceEnabled: false也不例外。五、配置实操示例5.1 查看当前配置# appHome 指向持久化用户数据目录由 config.appHome 决定 cat $APP_HOME/config.json5.2 显式关闭优先级传输旧网关/自托管网关升级前编辑持久化用户数据目录下的config.json路径为config.appHome/config.json即 app-config.ts 中join(APP_HOME, config.json)加入{ liveActivityRelevanceEnabled: false }保存后可通过writeAppConfig读-合并-写 备份 0o600权限路径更新该值显式保留升级后不丢失。恢复默认行为只需删除该键或置为true。5.3 行为验证对应测试用例期望行为测试用例tests/server/live-activity.test.ts缺省即发优先级sends business priority by default when the setting is absent显式关闭后三动作均不带字段preserves explicit opt-out for old gateways on start update and end心跳不窃取优先级、end 归零gates priority and preserves business priority across heartbeat注册不复活终态活动does not start cards for terminal-only or unknown-total work、补发分支stored?.terminal判断六、关键源码速查注册入口与补发触发live-activity-registration.tsupdateLiveActivityDestination→catchUpLiveActivities(connection.id)补发实现live-activity-catchup.ts授权校验、单任务 break、lastAttempt/pending节流主消费者与优先级传输live-activity.tsconsume补发分支、30 分钟抑制、relevance_score计算、serialized串行与polling回执轮询运行态/启动预算存储live-activity-runtime-store.tslive_activity_runs、live_activity_start_budget表全局配置app-config.tsliveActivityRelevanceEnabled、锁定读-合并-写与备份测试覆盖tests/server/live-activity.test.ts以上实现共同保证注册恢复永远在授权 → 校验 → 去重 → 节流 → 预算抑制的护栏内运行优先级永远是可关闭的提示而非承诺——这正是本方案可以放心默认开启、安全滚动的设计根基。赞分享AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐Ekko Studio 用户级移动推送注册与路由机制详解从设备注册到 APNs 事件投递Ekko Studio 用户级移动推送注册与路由机制详解从设备注册到 APNs 事件投递 本文围绕 Ekko Studio 仓库中的核心设计文档 docs/rAI 应用人工智能AI Agent本地部署前端后端工作流自动化Kong版本发布新特性介绍与升级注意事项Kong版本发布新特性介绍与升级注意事项 你还在为API网关性能瓶颈、AI服务集成复杂而困扰吗一文解决Kong 3.8.0 3.9.1版本升级难题 读完本文API网关后端LLM 网关微服务人工智能FluentAssertions版本发布新特性介绍与升级注意事项FluentAssertions版本发布新特性介绍与升级注意事项 概述 FluentAssertions作为.NET生态系统中广受欢迎的测试断言库近期发布了测试创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考