science-agent-scheduling

1# 任务调度：租约、幂等与背压
2 
3## 一条总原则
4 
5**调度器是唯一能改状态的人。** 模型、脚本、人都不直接写 task 状态；
6所有状态变化只由 `science_campaign_run` 的动作（claim / heartbeat / complete / fail /
7release）产生。手工改 state 会让事件流与状态表对不上，之后每一次重跑都不可信。
8 
9## 租约（lease）
10 
11- 领取任务即获得租约，`leaseMs` 默认 120000（2 分钟）。
12- 租约不是所有权，是**临时独占**；到期未续，任务自动回到 pending，任何人可再领。
13- 领取前必须写 `owner`、`leaseUntil`、`attempt`。三项缺一，这次领取无效。
14- 续租用 `heartbeat`，间隔取 `leaseMs/3`（约 40 秒）。不要等到快到期才续。
15- **不要在长任务里省心跳**。一次 LLM 调用超过 2 分钟就该拆片，而不是把租约调长。
16 
17## 心跳
18 
19心跳要带三样：`taskId`、`attempt`、`progress`（已完成/总数）。
20只发空心跳会被判为僵尸——有租约没进展，与没心跳等价。
21 
22| 现象 | 判断 | 动作 |
23| --- | --- | --- |
24| 有心跳、progress 在涨 | 正常 | 继续 |
25| 有心跳、progress 不动超过 2 个周期 | 卡住 | 记录事件，下一轮换策略 |
26| 无心跳、租约未到期 | 可能正在长调用 | 等到期，不要抢 |
27| 无心跳、租约已到期 | 僵尸 | 允许重新领取，attempt+1 |
28 
29## 幂等键
30 
31- 每个 shard 的 `idempotencyKey` 必须只由输入决定：`taskId + 输入指纹`。
32- 写入产物前先按键查一次：已存在且校验通过 → 直接返回旧结果，不重算。
33- 重试沿用同一个 key。**重试换 key 是最常见的重复产物来源。**
34- 部分失败（50 条里成了 30 条）按子键续跑，不要整片重来；子键同样是输入指纹。
35 
36## 退避
37 
38失败后按 attempt 指数退避，并在抖动区间内随机：
39 
40```
41delay = min(base * 2^(attempt-1), cap) * (0.5 + random()*0.5)
42base = 2s, cap = 120s
43```
44 
45- `429` / 限流 / 超时 → 退避，属于可重试。
46- `401` / `403` / 参数非法 / 数据不存在 → 不退避，直接 fail 并写原因。
47- `defaultMaxAttempts` 3。第三次失败后转 blocked，附最后一次错误摘要与事件 id。
48- 同一源连续 3 次 429，触发该源的熔断，改用备用源，不要继续打。
49 
50## 背压
51 
52- 全局并发受 `llmConcurrency`（默认 6）约束；单片内并发不要再叠。
53- 队列积压超过在跑数的 5 倍，说明分片过细或下游太慢：先停派单，再合并分片。
54- 上游产出速率低于下游消费速率时，**降并发而不是加机器**；加机器只会更快把队列打空。
55- 某一类分片长期 pending 而其他类型空闲，是路由问题，不是容量问题。
56 
57## 预算熔断
58 
59- 进 Campaign 前设总预算与单价上限；每次调用后累计，不靠事后对账。
60- 达到 80% 预算：只允许收尾类任务（合并、校验、出报告），停止新分片。
61…