Crons：调度、保留与并发

Cron 是周期性 Run。无 Thread 的 Cron 每次在隔离 Thread 中执行；Thread Cron 复用指定 Thread，从而累积 state，但也必须处理同一 Thread 的并发。

八个路由

能力	方法与路径	说明
创建隔离 Cron	`POST /runs/crons`	新执行各用独立 Thread；根文档是 Thread Cron 创建入口，需注意两个入口含义不同
创建 Thread Cron	`POST /threads/{thread_id}/runs/crons`	固定在一个 Thread 上运行
读取/删除	`GET`、`DELETE /runs/crons/{cron_id}`	不存在 404
Patch	`PATCH /runs/crons/{cron_id}`	更新调度与 Run payload
搜索	`POST /runs/crons/search`	assistant/thread/enabled/metadata 过滤，分页排序与字段选择
计数	`POST /runs/crons/count`	assistant/thread/metadata 过滤

创建契约

两类创建都必填 schedule 和 assistant_id（可使用 Assistant UUID 或 graph 名）。共同可选：

IANA timezone；为空按 UTC；
ISO date-time end_time；
input、metadata、config、runtime context、webhook；
interrupt before/after；
enabled（默认 true）；
stream mode/subgraphs/resumable；
durability（sync/async/exit，默认 async）。

隔离 Cron 用 on_run_completed 控制每次临时 Thread：delete 默认清理，keep 为每次执行保留新 Thread。Thread Cron 则用 multitask_strategy（reject/rollback/interrupt/enqueue，默认 enqueue）处理重叠执行。

返回 Cron 包含 cron/assistant/thread IDs、schedule、end/next run 时间、payload、metadata、enabled 与创建更新时间。

搜索与运维

搜索默认 limit 10、offset 0，可按 cron/assistant/thread ID、next run/end/created/updated 时间排序；默认 created_at desc。select 可只返回需要字段。enabled=false 是暂停，不会删除；Patch 调度或时区后应读取 next_run_date 验证。

生产设计

cron expression 与时区作为一对配置审计；DST 切换、月末和闰日必须有测试。
创建前生成稳定业务 ID/metadata，重复请求先搜索；API 没有显式幂等键时由调用方防重。
Thread Cron 的任务必须幂等。enqueue 可能堆积，interrupt/rollback 可能留下外部副作用，reject 会漏执行；按业务语义选择并监控。
keep 会持续增长 Thread 与 checkpoint，配套 TTL/归档；delete 前确认 Trace 与结果已交付。
disabled、end_time、删除分别表示暂停、自然终止、移除调度；控制台要明确区分。
webhook、外部工具和定时输入都遵循最小权限；敏感任务加入审批或把高风险副作用拆到受控服务。