Skip to content

Cron Add 加固与 Schema 对齐

背景

最近的 gateway 日志显示反复出现 cron.add 失败,原因是参数无效(缺少 sessionTargetwakeModepayload,以及 schedule 格式不正确)。这表明至少有一个客户端(很可能是 agent 的 tool call 路径)正在发送被包了一层或只写了一部分字段的 job payload。

另外,cron provider 的枚举在 TypeScript、gateway schema、CLI flags 与 UI form 类型之间存在漂移;同时 cron.status 的 UI 也有字段不匹配(UI 期望 jobCount,而 gateway 返回 jobs)。

目标

  • 通过对常见的 wrapper payload 做归一化、并推断缺失的 kind 字段,停止 cron.add 的 INVALID_REQUEST 噪音(spam)。
  • 对齐 gateway schema、cron types、CLI 文档与 UI forms 中的 cron provider 列表。
  • 将 agent cron tool schema 明确化,使 LLM 产出的 job payload 正确。
  • 修复 Control UI 中 cron status 的 job count 显示。
  • 添加测试以覆盖归一化与工具行为。

非目标

  • 改变 cron 的调度语义或 job 执行行为。
  • 新增 schedule kind 或 cron 表达式解析。
  • 除必要字段修复外,大幅重做 cron 的 UI/UX。

发现(当前缺口)

  • gateway 的 CronPayloadSchema 不包含 signal + imessage,但 TS 类型包含。
  • Control UI 的 CronStatus 期望 jobCount,但 gateway 返回 jobs
  • agent cron tool schema 允许任意 job 对象,从而允许不合法输入。
  • gateway 严格校验 cron.add 且没有归一化,因此被包裹的 payload 会失败。

做了哪些改变

  • cron.addcron.update 现在会对常见的 wrapper shape 做归一化,并在安全时推断缺失的 kind 字段。
  • agent cron tool schema 与 gateway schema 一致,从而减少无效 payload。
  • provider 枚举在 gateway、CLI、UI 与 macOS picker 之间对齐。
  • Control UI 在 status 中使用 gateway 返回的 jobs 数量字段。

当前行为

  • 归一化:对被包裹在 data/job 中的 payload 进行解包;在安全时推断 schedule.kindpayload.kind
  • 默认值:当缺少 wakeModesessionTarget 时应用安全默认值。
  • Providers:Discord/Slack/Signal/iMessage 现在会在 CLI/UI 中一致呈现。

规范化后的结构与示例参见 Cron jobs

验证

  • 观察 gateway 日志,确认 cron.add 的 INVALID_REQUEST 错误显著减少。
  • 刷新后确认 Control UI 的 cron status 会显示 job count。

可选后续

  • Control UI 手工 smoke:为每个 provider 添加一个 cron job,并验证 status 中 job count。

未决问题

  • cron.add 是否应该允许客户端显式传入 state(目前 schema 不允许)?
  • 是否允许 webchat 作为显式的 delivery provider(当前在 delivery resolution 中会被过滤)?