ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Schedule:重复规则、时区输入与追赶语义到底怎么算才不容易跑错

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessSchedule重复规则时区
每日或每周任务在时区边界错跑,或错过一次后连续补跑。本文讲七种权威时间类型、scheduledAt 的规范 UTC 语义、Cron 与 RRULE 的差异、三种投递目标,以及追赶与崩溃窗口。

定时任务最容易错在两处:把本地时间当成绝对时间,以及把“错过一次”理解成“逐次补跑”。 DSH plugin 的 Schedule 用七种权威时间类型加一条规范 UTC 时刻来消除歧义;追赶策略则明确是合并而非重放。 DSH插件 配定时任务时,本地时间与绝对时间是两回事。

七种时间类型都是权威的

规范化保留已提交的发生时点,不做类型转换。(来源)

Schedule 独立于 Session 的激活状态存储宿主任务。同一管理 API 按 id 操作任务,同一求值器处理七种权威时间类型:

类型输入
after正整数 afterSeconds 加一次性 UTC 目标
at一次性 UTC 目标,接受显式偏移或本地日期时间加时区
every不小于 60 的整数 everySeconds,对齐已提交锚点
dailyHH:mm:ss.SSS 的本地 time 加显式 timeZone
weeklyDaily 字段加非空、唯一、升序的 ISO weekdays(周一为 1)
cron规范五字段 expression 加显式 timeZone
rrule一条规范 DTSTART 与一条 RRULE 行

七种时间类型均保持权威性;规范化保留已提交发生时点,不将 Cron 转为 RRULE。损坏的存储、无效行、与任务身份不一致的键及不支持的版本,都会在任务激活前拒绝。文件不存在时从空域开始;目标 Session 缺失的任务仍在管理界面中可见,而读取任务从不激活其 Session。

scheduledAt 与追赶语义

每个已存时刻都是规范 UTC,解码不会按当前时区重算。(来源)

每个已存 scheduledAt 都是带毫秒精度、年份为 0001 至 9999 的规范 RFC 3339 UTC 时刻。解码不会根据当前时区数据重新计算它——这一点决定了“改系统时区不会挪动历史任务”。

追赶策略的口径是“只追赶最新一次”:保留该已提交下界,投递最新到期时点一次,再提交第一个未来时点。规则耗尽后任务以 ended 状态保留,而不是被删除。

固定频率的追赶更明确:停机后合并错过的间隔,而非逐次重放。所以“停了三天,起来收到三条”不应该发生。

本地日历规则还有两条细节:跳过不存在的墙钟时间,重叠时选择较早的时刻。固定间隔则保留经过时间的含义。一次性延迟可以短于一分钟,但首次投递之后仍适用单任务最小投递间隔。

Cron 与 RRULE 的差异不是风格

两者的匹配语义不同,转换会改变行为。(来源)

Cron 输入是 { expression, time_zone }:五个数字字段依次为分钟、小时、月内日期、月份与星期。支持 *、单值、闭区间、星号或区间步长,以及逗号分隔列表;周日接受 0 或 7,规范为 0;拒绝名称、宏、秒字段与“单值后跟步长”的形式。

Cron 保留 Vixie 的日期匹配方式:两个日期字段都受限时,月内日期或星期任意一个匹配即可;任一字段以 * 开头(包括带步长的星号)时,两组匹配值均须匹配。搜索受 400 年公历周期与四位 UTC 年份范围约束;启用时拒绝没有可表示未来时点的规则。

RRULE 接受有界的 RFC 5545 子集:输入恰好包含两条非空内容行,先 DTSTART 再 RRULE;开始时间使用 UTC Z 或显式 IANA TZID,拒绝浮动本地时间、数字偏移、仅日期值与额外内容行。引擎使用 rrule 2.8.1,支持 MINUTELY 到 YEARLY;一次性投递用 COUNT=1。

验证发生在枚举之前:拒绝 SECONDLY、多个 BYSECOND 值,以及一个频率周期中超过 10,080 个可能候选时点的规则。COUNT 为 1 至 1,000 且不能与 UNTIL 共存;UNTIL 是以 Z 结尾的绝对 UTC 日期时间;开始与截止年份为 0100 至 9999。

两条本地时间细节:不存在的本地 DTSTART 会被拒绝;后续不存在的本地发生时点会跳过且不消耗 COUNT,重叠时间选择较早时刻。

投递目标三种,默认 new_once

目标决定复用还是新建,默认不是每次新建。(来源)

  • session — 投递到一个已有 Session。启用时在管理 FIFO 内检查其存在、未归档且不属于委托子 Agent;投递时再次检查归档状态。
  • new_once — 首次投递前预留 Session id,需要时创建该 Session,然后保存为 session 并复用。重试和重启保留该预留标识。
  • new — 每次投递创建 Session。创建前持久化 pendingDelivery.targetSessionId,使失败尝试重用同一 Session。

创建时省略目标则默认 new_once。新增或替换 new、new_once 目标需要嵌入环境提供 Session 创建能力;SDK 组合缺少该能力时,会在保存前以 invalid_rule 拒绝这些请求,而已有 session 目标仍可使用。

创建值 cwd 与 agentPreset 可省略,使用 Host 默认值。创建的 Session 会加入其目录已注册的 Workspace(如有),且尚无标题时使用任务标题;new 另加该规则时区中的创建分钟。加入或重命名失败会记录日志,但不阻断投递。

管理操作与时间编辑

编辑是原子的补丁,乐观并发靠 expectedUpdatedAt。(来源)

所有调用方使用相同的 ScheduleCreateRequest、ScheduleCatalogEntry、ScheduleTiming 与 ScheduleEditRequest,不存在 Session 绑定的管理入口或第二套类型别名。

关键操作:list 默认 100、最多 500,可选 active 过滤与非负 offset;history 不激活 Session 地读取已保存投递,limit 为 1 至 100;edit 按 id 原子应用 update patch 或 delete;deleteInactive 一次批量写入仅删除 ended 任务,空集合不写入;run 经正常准入立即投递,不改变已计划发生时点或生命周期。

更新可以替换标题、指令、带类型时间、目标或活动状态,省略字段保留原值。规则改变或显式恢复时,在 FIFO 接受时刻计算未来时点;等价时间及描述性编辑保留已提交目标。已投递的一次性任务需要新的未来时间才能恢复;重新指定目标不要求转换时间类型。

expectedUpdatedAt 是可选乐观比较:字符串与已存修订比较,显式 null 与缺失的修订比较,不一致返回 schedule_conflict。编辑没有修订的行会创建修订;即使时钟回拨,后续修订仍单调递增。开始写入前检查取消,已经开始的持久写入不回滚。

宿主投递与两个崩溃窗口

收件箱先写、回执后写,所以两库之间崩溃可能重复投递。(来源)

一个 Host 定时器驱动活动任务,运行时与管理写入共用一个 FIFO。已有和预留 Session 通过 schedule/resolve-agent 解析;复用 Session 的任务占用执行槽直到目标 Agent 空闲,期间发生的时点会合并;new 目标允许多个执行并行。到期且投向相同已有 Session 的重复记录共享一条消息,after 与 at 单独投递。

定时与手动投递都遵守单任务 60 秒最小间隔。newSessionIntervalSeconds 可为 new 目标提高间隔,最多一周。已存后继时点保持间隔时,下界从上次发生时点计算;否则从上次确认计算,因此投递延迟不会移动规则锚点。

崩溃窗口要记住:Session 收件箱持久化先于任务回执写入,所以两份存储之间崩溃可能重复投递。Host 必须运行。指向某 Session 的活动任务会参与其归档准入;归档停止操作会删除这些活动任务。

回执记录 scheduledAt、deliveredAt、messageId 与 targetSessionId,它确认的是持久 Session 收件箱写入,而非模型完成。历史按追加顺序排列,不受时钟回拨影响;确认在同一任务提交中追加并裁剪,默认保留最多 200 条、30 天,同时保留最新回执。

验证:跨时区与错过窗口

验证要同时测时区边界、追赶次数与目标复用。(来源) 六步:

  1. 用 daily 在 Asia/Shanghai 建一个 09:00 任务,断言已存 scheduledAt 是 UTC 且换算回本地正好 09:00。
  2. 把系统时区改成另一个值,重启后读任务,断言 scheduledAt 未变。
  3. 停机跨过三次到期,恢复后断言只投递最新一次,而不是三次。
  4. 用 every 建一个 60 秒任务并修改 every_seconds,断言新锚点从编辑接受时刻开始。
  5. 用默认目标创建任务,连续两次投递,断言复用同一个 Session id。
  6. 用旧 expectedUpdatedAt 调 edit,断言返回 schedule_conflict 且原任务未被修改。

如果第 3 步收到多条,先确认规则类型是不是 at 或 after——一次性类型本来就会单独投递。

定时任务的配置方式见定时任务配置;会话绑定异常见定时任务会话绑定。

一句话收束: 七种类型都权威、scheduledAt 是规范 UTC、Cron 不转 RRULE、追赶只取最新、目标默认复用、收件箱先于回执所以可能重复。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 Cron 会被转成 RRULE 吗?

不会,DSH plugin 明确保留已存表达式与时区作为权威来源。DSH plugin 的读取、描述性编辑、重新指定目标与重启都不会把 Cron 记录转换成 RRULE。

DSH plugin 停机之后,会把错过的时点逐次补跑一遍吗?

不会,DSH plugin 合并错过的间隔。DSH plugin 的固定频率在停机后合并,而不是逐次重放;只追赶最新一次的策略只投递最新到期时点一次。

DSH plugin 的 weekly 规则里,星期几是用 1 到 7 表示吗?

是的,DSH plugin 的 weekly 用 ISO weekday,周一为 1、周日为 7。DSH plugin 的 Cron 则接受 0 或 7 表示周日,并规范为 0。

DSH plugin 的 session 目标会在投递时再检查归档吗?

会,DSH plugin 在启用与投递两个时点都检查。DSH plugin 在启用时检查会话存在、未归档且不属于委托子 Agent,投递时再检查一次归档状态。

相关术语

scheduledAt
scheduledAt 是已存的规范 RFC 3339 UTC 时刻,带毫秒精度,年份范围为 0001 至 9999。— packages/schedule/schedule/src/types.ts
new_once
new_once 是默认投递目标,首次投递前预留 Session id,创建后保存为 session 并复用。— packages/schedule/schedule/src/types.ts
expectedUpdatedAt
expectedUpdatedAt 是可选的乐观并发比较;不一致时返回 schedule_conflict。— packages/schedule/schedule/src/types.ts
deliveryHistory
deliveryHistory 是按追加顺序保存的投递回执历史,默认最多 200 条、30 天,并保留最新回执。— DeepSeek Harness 官方参考 - 宿主级 Schedule

来源