免费额度与更新策略

推荐单设备使用 eco：每 120 秒推送，服务端 180 秒过期。 相比原来的 30 秒推送，定时写入减少 75%，给网络和调度留下约一分钟余量。

先算写入

每次成功的 /api/update 覆盖一个 KV 键，重复写相同内容也计数。

策略	每日定时写入	占免费写入额度	取舍
eco：120 秒 / TTL 180 秒	720	72%	新安装默认；最长约 3 分钟判离线
realtime：30 秒 / TTL 60 秒	2,880	288%	最长约 1 分钟判离线；需控制时长或自行选择套餐

计算为 86,400 ÷ 上报间隔秒数。Cloudflare KV 免费计划目前每天 1,000 次键写入、100,000 次键读取，UTC 00:00 重置；额度在同账户内共享。拆分命名空间不会增加账户额度。官方配额

720 次是全天持续运行的定时估算，不是强制上限。首次启动、反复重新登录、手动推送、测试和其他项目额外计数。额度用尽后相关操作失败，本项目不会自动付费，也没有账户级用量计数器。两台 Mac 都全天用 eco 仍会超过 1,000 次。

切换模式

必须同时调整 Worker 和本机。只延长 TTL 不减少写入，只减慢本机而保留短 TTL 会周期性离线。

切换到 eco

先在自己的 Wrangler 配置中设置：

"vars": { "STATUS_TTL_SECONDS": "180" }

npm run deploy
/bin/bash scripts/install.sh --profile eco

安装脚本复用已配置的 endpoint、token 和隐私选项，重新生成并加载 120 秒间隔的 plist。新安装默认 eco；老版本已存在但未声明 profile 的配置按 realtime 处理，因此升级时须显式传入 --profile eco。

切换到 realtime

将 Worker 的 STATUS_TTL_SECONDS 设为 "60" 并部署，然后执行：

/bin/bash scripts/install.sh --profile realtime

Worker 接受 60–3600 秒整数 TTL；本机提供上述两个受支持的 profile。手动选其他 TTL 不会自动改变本机间隔。未设置 Worker 变量时兼容旧部署，使用 60 秒；无效值返回 503。

每条新快照保存写入时的截止时间；旧版记录按 60 秒解释。读接口采用记录原截止时间和当前策略截止时间的较早值。提高配置不会把记录保留到其原定截止时间之后。客户端读取 expires_at，不要假定永远是 60 秒。

为什么不只在状态变化时上报

短 TTL 必须靠心跳续期。完全不变时停止写入，KV 仍会过期，在线的 Mac 会显示为离线。负载和电量也可能频繁变化，简单 JSON 去重不一定省写入。因此本版本使用明确的时间间隔，不做去重节流承诺。

读取也有额度

GET /api/now、/api/music、/api/apps/active、/api/apps/running、/api/device 与 /api/badge.svg 每次都读取一次 KV，不写入 KV。不要因 KV 内部有缓存就假定不计费；HTTP 响应仍使用 no-store，避免缓存超过状态截止时间。KV 读取规则

需要多类数据时，每轮只读一次 /api/now。如果每 120 秒分别调用四个分类接口，单页约读 2,880 次/日；调用一次完整接口约读 720 次/日。分类接口只是方便独立小组件，不会共享一次 KV 操作；并行调用还可能读到不同的快照。

首页每 120 秒读取一次状态，页面隐藏时暂停，切回页面不会突破同一页面的刷新间隔；其他文档页面不自动加载实时状态。一个持续打开的主页约读 720 次/日，多个访问者会累加，重新打开页面另计。静态文档、样式和本地搜索不访问 KV。

/api/health 不读 KV，但仍会消耗 Worker 请求配额。公开接口无法阻止第三方大量请求；本项目没有账户级硬额度保证。Workers 免费限制

封面查询的请求与缓存

首页封面由访客浏览器直接查询 Apple，并从 Apple 图片 CDN 加载，不经过 Worker，也不增加 KV 读写。只有新鲜的 playing / paused 状态同时具备歌名和歌手时才查询；美国商店没有可信匹配时显示占位。

每个页面使用最多 50 条的内存缓存：成功结果 1 小时，普通查询失败或无可信匹配 5 分钟；取消请求不缓存，不写入持久存储。下次查询不会复用过期记录。不同访客、重新打开页面仍可能产生独立请求；Apple 的服务限制与网络可用性不属于 Cloudflare 配额。封面缓存时长不延长设备状态的有效期。数据流与隐私

失败重试间隔至少 5 分钟，页面隐藏或设备快照失效时不重试。

音乐 API 的服务端匹配

/api/music 自身仍每次读取一次 KV；只有在线且具备歌名、歌手的播放／暂停状态需要匹配 Apple 目录。搜索结果在服务端内存与所在边缘节点的 Cache API 中复用：成功 1 小时，未匹配或失败 5 分钟，内存最多 50 条，同一运行实例的同曲目并发查询会合并。Apple 查询阶段限时 4.5 秒，接口总耗时还包含 KV 与缓存访问；查询失败返回空 URL，不消耗 KV 写入。

缓存的是公共目录匹配结果，API 状态响应仍 no-store。不同边缘节点、缓存淘汰和新的歌曲会再次查询 Apple，不能承诺全局命中率或固定的搜索次数。首页不额外轮询 /api/music，继续使用现有浏览器封面流程。避免反复刷新来强制补封面。音乐 API 隐私

应用图标的请求与额度

原生图标由 npm run icons:export 在开发用 Mac 上一次导出，不调用 macOSicons，不消耗其额度；普通构建直接使用仓库中的 PNG 与清单。

图标读取方式	Worker 执行	KV	第三方图标搜索
/app-icons/<id>.png、/app-icons/index.json 静态资源	无	无	无
/api/icons、/api/icons/<id>.png API	有，计 Worker 请求	无	无
可选 macOSicons 补充图片	浏览器直连 CDN	无	页面访问不搜索

首页使用静态图片路径；只需嵌入图标时也推荐该路径。API 成功响应允许缓存 1 小时并支持 ETag 条件请求，但实际进入 API 的请求仍计 Worker 请求，不能视为无限免费接口。Cloudflare 静态资源计费

可选 macOSicons 搜索只在维护者运行 npm run icons:sync 时发生。已有原生图标的配置项直接跳过，--force 也不会查询它们，因此当前仓库原生图标集不消耗搜索额度。只对缺少原生图标的配置项匹配；剩余有效期超过 2 天的补充记录会复用，每个需要查询的应用最多搜索一次且不自动重试。补充记录最多有效 30 天，过期后需重新同步并部署；--force 仅对这些补充项跳过复用，额外消耗额度。

macOSicons 的 GET /api/v1/usage 只读返回当前 Key 的月度 used、limit、remaining 和 UTC 重置时间，不消耗查询额度；以自己的返回值为准。例如搜索限额为 50 次/月时，只新增 3 个缺少原生图标的配置项，一次同步最多使用 3 次；反复强制同步仍可能耗尽额度。本项目不会自动升级套餐。官方用量接口 · 图标配置与同步

如果还需要更低消耗

• 缩短需要公开在线状态的时段，Mac 休眠、注销后自然停止推送。
• 减少网站轮询和不必要的手动上报；关闭采集字段能减少公开内容，但不减少每次推送的 KV 操作次数。
• 多设备或必须更快更新时，另行评估存储模型或套餐。Durable Objects 需要重新设计与核算，不能直接视为“无限免费 KV”。

KV 最终一致，eco 也不承诺跨地区秒级更新。一致性边界