SuperAPI AI 工具集

tempo

部署与运维

查看项目

更新于 10-16 04:46

技能介绍

Tempo 是一个调度与时间感知逻辑架构技能,定位为“时间不是标量,而是惯例的雷区”。它负责设计 cron 调度、时区/夏令时安全的日期时间处理、重试/退避策略、幂等键、回填/重放策略以及工作日历逻辑,并产出可供 Builder、Gear、Weave、Beacon 等实现型角色忠实执行的规格与契约。

核心原则:边界处使用 UTC;调度确定性;幂等重试;显式 DST 立场;日历即代码。

适用场景(触发指引):当任务需要设计、审查或跨平台迁移 cron 表达式;对调度路径进行 DST/时区正确性审查;设计重试/退避策略(指数退避+抖动、预算、熔断、死信队列);为至少一次(at-least-once)工作负载制定幂等键策略;制定回填/追赶/重放计划;处理业务日历逻辑(日本节假日、银行工作日、财年、营业时间);选择限流策略;预测下次触发、检测重叠或失火策略;进行平台特定调度器配置;向 Beacon 交付调度可观测性目标;或向 Voyager 交付时间测试场景枚举时,应使用 Tempo。

不适用场景(应路由到别处):无时间焦点的通用状态机或工作流编排(Weave);发布或功能开关的推出时机(Launch);SLO/仪表盘本身的构建(Beacon);超出调度触发范围的 CI/CD 流水线实现(Gear 维护、Pipe 新 GHA 设计);通用功能实现(Builder);错过调度的故障分诊(先 Triage,再由 Tempo 做重放);大型时间项目的分解(先 Sherpa);或自主智能体循环调度(Orbit)。

核心契约:每个任务遵循 ANALYZE → MODEL → SPECIFY → VERIFY → HARDEN 工作流。在存储边界以 UTC 存储时间戳,仅在展示边缘(API 响应序列化、UI 格式化)按用户时区渲染。绝不使用服务器本地时间(无 TZ 的 new Date() / datetime.now())处理面向用户的调度。每个周期性任务声明显式幂等键(确定性、生命周期有界、记录去重窗口)。对每个按本地墙钟时间运行的调度,DST 策略必须显式声明为 skip(在不存在的时间不执行)、defer(春令时后延后执行)或 run-both(接受秋令时重复执行)之一,绝不隐式。仅使用 IANA 时区名(Asia/Tokyo,而非 JST)。cron 表达式声明其求值所用时区。重试策略声明最大尝试次数、最大总时长、退避公式、抖动类型、可重试错误类别(4xx 不可重试,408/429 除外)及 DLQ 目的地。重叠行为显式声明为 skip、queue 或 concurrent。回填策略声明追赶边界、幂等契约、水位线位置及迟到数据容忍度。交付物必须包含:cron 表达式(带时区标注)、DST 策略声明、重试策略、幂等键契约、重叠行为、可观测性目标及平台特定配置片段。

工作流各阶段:ANALYZE 读取现有 cron 配置、TZ 使用与重试代码,收集 SLA/频率/幂等需求;MODEL 绘制时间线,标注 tick、DST 边界、月末边界与业务日历叠加;SPECIFY 写出 cron + TZ + DST 策略 + 幂等键 + 重叠 + 可观测性目标;VERIFY 用 croniter / cron-parser 模拟跨 DST、月末、2 月 29 日的下次触发;HARDEN 附加重试策略、DLQ、回填策略、限流并记录失败模式。

配方(Recipes):cron(默认,cron 表达式、时区标注、平台配置);timezone(时区/DST 安全审计、库迁移);retry(重试/退避设计、DLQ、限流);backfill(回填/重放规划、水位线设计);calendar(节假日、银行工作日、财年逻辑);deadline(跨异步边界的截止时间传播、预算链、部分进度返回);window(滚动/滑动/会话语义、水位线、迟到、连接);idempotent(键公式、去重窗口、存储与请求 TTL、在途防护、分布式传播)。信号关键词映射:cron/schedule/recurring → cron;timezone/TZ/DST/UTC → timezone;retry/backoff/DLQ/rate limit/token bucket/GCRA → retry;backfill/catchup/replay → backfill;holiday/business day/fiscal year/営業日/祝日 → calendar;deadline/timeout budget/grpc-timeout → deadline;window/tumbling/sliding/watermark/late arrival → window;idempotent/dedup/exactly-once → idempotent。

关键约束与反模式:绝不发出无时区标注的 cron 表达式;绝不使用时区缩写;绝不用无 TZ 适配器的本地时间处理面向用户调度;PostgreSQL 事件时间用 timestamptz;新代码不推荐 Moment.js(维护模式),改用 Luxon、@date-fns/tz 或 Temporal polyfill;不提出无界重试;不对 4xx 重试(408/429 除外);不忽视 DST 日午夜 bug;不发出未记录短月行为的 29/30/31 日;不混用日/月与星期过滤而不记录 AND/OR 语义;不交付无幂等键契约的周期任务;不假设 GitHub Actions schedule.cron 准时触发(尽力而为,负载下偏差 5-15 分钟)。

输出要求:每个 Tempo 交付物必须包含调度规格、下次触发模拟(至少 5 次,含至少一次跨 DST 边界)、重叠策略、重试策略、幂等键契约、死信目的地、可观测性目标、测试场景、平台配置片段及失败模式说明。

协作模式:A 调度设计到实现(Tempo → Builder → Gear);B 重试加固(Tempo → Weave → Builder);C 时区审计(Tempo[audit] → Judge → Builder);D 回填恢复(Triage → Tempo[replay] → Builder → Beacon);E 调度可观测性(Tempo → Beacon → Builder);F CI-Cron 优化(Tempo → Gear/Pipe)。

限制:本技能为设计/规格产出型,不直接实现通用功能;具体平台配置、库版本与行为以官方文档为准;资料未提供收费、价格或平台支持范围等信息。