baa-conductor

commit

4cfc0f6

parent

b9ce589

author

claude@macbookpro

date

2026-03-30 17:40:32 +0800 CST

docs: add OPT-007 dispatcher jitter requirement

Renewal dispatcher needs inter-job jitter and retry backoff
randomization to avoid triggering upstream rate limits when
dispatching multiple jobs in a single tick.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

1@@ -21,6 +21,7 @@ bugs/
2 - `OPT-003`：[`OPT-003-policy-configurable.md`](./OPT-003-policy-configurable.md)
3 - `OPT-004`：[`OPT-004-final-message-claude-sse-fallback.md`](./OPT-004-final-message-claude-sse-fallback.md)
4 - `OPT-005`：[`OPT-005-normalize-parse-error-isolation.md`](./OPT-005-normalize-parse-error-isolation.md)
5+- `OPT-007`：[`plans/OPT-007-DISPATCHER-JITTER.md`](../plans/OPT-007-DISPATCHER-JITTER.md) — renewal dispatcher 加入随机抖动避免限流
6 
7 ## 已归档（archive/）
8 

 1@@ -0,0 +1,56 @@
 2+# OPT-007: Renewal dispatcher 加入随机抖动避免限流
 3+
 4+日期：`2026-03-30`
 5+优先级：`P2`
 6+状态：`proposed`
 7+
 8+## 背景
 9+
10+当前 renewal dispatcher 在一个 tick 内连续派发多个 job 时，请求之间没有任何延迟，可能在短时间内向同一平台发出大量请求触发上游限流。此外，重试退避使用纯指数计算（`baseDelay * 2^n`），多个 job 在同一时刻失败后会在完全相同的时间点重试，形成 thundering herd。
11+
12+浏览器请求链路本身已经有 `browser-request-policy` 的 Gaussian jitter（1~5s），但 dispatcher 层面的批量派发和重试调度不受该策略控制。
13+
14+## 需求
15+
16+### 1. Inter-job jitter
17+
18+同一 tick 内连续 dispatch 多个 job 时，从第二个 job 起在派发前加入随机等待。
19+
20+- 默认区间：`500ms ~ 3000ms`（均匀分布）
21+- 可通过 options 配置 `interJobJitterMinMs`、`interJobJitterMaxMs`
22+
23+### 2. Retry backoff jitter
24+
25+在现有指数退避基础上叠加随机偏移，防止多个 job 在同一时间点重试。
26+
27+- 默认 jitter factor：`±30%`
28+- 计算方式：`baseDelay * 2^n ± (baseDelay * 2^n * jitterFactor * random)`
29+- 可通过 options 配置 `retryJitterFactor`
30+
31+### 3. 可测试性
32+
33+- 新增 `random?: () => number` option，测试时注入确定性随机源
34+- 现有测试不应因抖动引入 flaky
35+
36+## 改动范围
37+
38+仅 `apps/conductor-daemon/src/renewal/dispatcher.ts`：
39+
40+- 新增常量：`DEFAULT_INTER_JOB_JITTER_MIN_MS`、`DEFAULT_INTER_JOB_JITTER_MAX_MS`、`DEFAULT_RETRY_JITTER_FACTOR`
41+- `RenewalDispatcherRunnerOptions` 增加 `interJobJitterMinMs`、`interJobJitterMaxMs`、`retryJitterFactor`、`random`
42+- `runRenewalDispatcher` 主循环在连续派发之间插入 sleep
43+- `computeRetryDelayMs` 增加 jitter 偏移
44+- 新增 `sampleUniformJitterMs`、`sleep` 辅助函数
45+
46+## 不需要改动的地方
47+
48+- `browser-request-policy.ts`：已有独立的 Gaussian jitter，不重复
49+- `instructions/loop.ts`：指令走本地 API 然后经 browser-request-policy，已有抖动
50+- schema / 数据库 / API 端点：无变化
51+
52+## 验收标准
53+
54+- 单 tick 内 3+ job 时，第 2/3 个 job 的 dispatch 时间与前一个有可观测的随机间隔
55+- 两个相同 attemptCount 的 failed job 重试时间不完全相同
56+- 现有 dispatcher 测试全部通过
57+- `random` option 可注入，测试可使用固定种子验证抖动范围

1@@ -77,6 +77,8 @@
2    为 Claude final-message 增加更稳的 SSE fallback
3 4. `OPT-005`
4    让 normalize / parse 错误进一步隔离，不拖累整批指令
5+5. `OPT-007`
6+   renewal dispatcher 加入随机抖动避免限流（[需求文档](./OPT-007-DISPATCHER-JITTER.md)）
7 
8 **已关闭的优化项：**
9