Cron Add 加固与 Schema 对齐
背景
最近的 gateway 日志显示反复出现 cron.add 失败,原因是参数无效(缺少 sessionTarget、wakeMode、payload,以及 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.add与cron.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.kind与payload.kind。 - 默认值:当缺少
wakeMode与sessionTarget时应用安全默认值。 - 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 中会被过滤)?