持久提醒
提醒使用现有 notifications 声明与授权;拒绝不阻止组件启用。只在工坊运行(含收起托盘)时投递,彻底退出停止投递,重启恢复仍有效的提醒。不注册系统计划通知、后台任务或服务。
作者接口
本地提醒验证工具
计算画布的提醒面板提供八个命名位置(第一项key=timer,其余timer-2至timer-8),选择同位置保存即替换,不默默覆盖其他位置。可输入1至48个UTF-16单元的标题(拒绝控制字符,沿原通知限制),时长为正整数,支持秒/分/小时/天,合计最多30天;默认5分钟。保存时快照用户输入,握手后才计算dueAt,仍保留一小时有效期。清单显示名称、日期及位置,可选择对应位置取消或清空本实例;不读取其他实例提醒。隐藏不改变工具执行,彻底退出不投递。
页面只持有一个提醒操作槽。写入与随后列表读取共用取消范围,配置失效/通知撤权或离开取消在途并拒绝迟到结果;输入与按钮在槽占用时禁用。取消不撤回已成功持久提交,失败提示要求手动刷新核对;撤权后仍可删除或清空,不把列表拒绝误报为删除失败。输入错误在调用前拒绝,列表与删除不受无关时长/标题输入错误阻塞。接口与持久事务归Services,通知权限保持可拒绝,不注册后台任务。
接口定义
计算画布提供“取消当前操作”:握手、保存或清单读取等待中可取消,本页面仍占用原操作槽直至请求结束,避免连续取消产生挂起队列。刷新取消只停止读取;保存/删除/清空在成功回复尚未被页面确认时取消,显示“修改未完成确认,请手动刷新核对”,不能承诺撤回服务已成功提交的记录。取消后的迟到回复不更新清单,输入和其他操作在原槽释放后恢复;不删除已保存提醒。
计算画布区分已确认提交与后续清单刷新:成功回复已消费后,取消仅停止随后的列表读取,保留保存/删除/清空成功提示并明确“已取消列表刷新;修改已提交”。取消后的迟到清单/错误不得覆盖此提示;开始下一项时清除上项确认状态。配置/权限失效优先,已经取消的旧操作不能再用取消按钮覆盖失效提示;原单槽仍等收尾才释放。确认信息只在当前页面/操作内,不新增存储、协议或撤回操作。
reminders.set {key,dueAt,expiresAt,title,body}返回{}:按当前实例的 key 替换;最后成功提交生效。key 为 1–64 个 ASCII 字母、数字、下划线或短横线,首字符为字母。时间是 UTC Unix 毫秒整数,dueAt 必须晚于现在且最多 30 天,expiresAt 晚于 dueAt 且最多晚 24 小时。标题/正文沿用即时通知的限制。reminders.list {}返回{items:[{key,dueAt,expiresAt,title,body}]}:只含当前实例尚未消耗、尚未过期的记录,按到期时间排序;不含通知历史。reminders.remove {key}返回{}:幂等删除自己的 key。reminders.clear {}返回{}:删除自己全部提醒,也用于明确丢弃损坏的提醒记录。remove / clear 是清理操作,不要求通知授权,但仍要求有效、启用的原实例调用。
每实例 8 条、每安装 32 条、全宿主 128 条;set 每分钟每安装 30 次、全宿主 120 次。投递与即时通知共用每分钟每安装 3 条、全宿主 10 条的额度;不足时保留至之后的轮询或过期。宿主约每秒检查,只有一个在途检查/投递,不保证精确计时。系统时钟回拨推迟投递,前跳超过有效期则丢弃;休眠/退出不产生周期补发。
所有权、取消和持久化
Services 独占事务所有权;提醒按实例独立保存到宿主内部 current-only 原子记录,不进入布局、配置、包版本或元数据的 previous 回退。页面重载、隐藏、包版本切换保留仍有效提醒;停用、删除实例、卸载或通知权限变化清空对应记录,再授予/再启用不恢复。布局只影响启用状态,不复制提醒。
停用/删除的取消在元数据提交后执行;提交失败保留原提醒。提交后清理失败仍由停用/删除状态阻止投递,再启用之前必须成功清空旧记录。撤权沿用优先拒绝标记,再授权之前清空旧记录。若宿主元数据损坏而退到 previous,先清空提醒,不用较旧启用状态恢复它们;此故障恢复会丢弃尚待投递提醒。损坏提醒文件保留,set / list 返回 RESOURCE_UNAVAILABLE,不从旧副本恢复;clear 明确重置。不记录正文或个人路径到日志。
到期先原子删除记录再投递,最多尝试一次;崩溃、退出或 Shell 拒绝发生在两步之间可能丢失该次提醒,不承诺恰好一次或用户可见。取消、替换、撤权、停用使尚未开始的投递失效;最终短锁只串行化开始发送的边界,不在锁内调用 Shell。已经开始发送或交给系统的通知不能撤回。到期后仍检查原实例及权限,过期不发送。点击沿用可信通知入口,只打开工坊,不执行作者动作或启用组件。
文件操作在有界存储队列执行,提交前检查取消;同步磁盘操作没有硬取消时限。定时调度不会积压通知正文或为每个提醒建立线程、定时器。
投递复用 Shell 通知 的 NIF_REALTIME / NIIF_RESPECT_QUIET_TIME:忙碌和安静时段可能抑制显示,API 成功不是用户已看到的证明。实际验证状态见实现说明(宿主文档:../implementation.md)。