限流恢复节流器 JuwanXu/dsh-camel

dsh-camel

English：README.md

dsh-camel 是 DeepSeek Harness 中按需启用的免费模型限流恢复插件。它组合提供商/模型感知的自适应额度学习、主动请求节流、Retry-After 感知重试、可见重试状态、单任务配置和带 session 的活动/额度事件。当内置重试路径放弃处理 RATE_LIMIT 失败时，Camel 可以通过可配置的等待继续保持任务运行，避免高频限流的免费模型直接中断任务。

0.2.x 还包含固定或自适应节流、有限或无限重试模式、按“单任务 session override > 插件 defaults > 内置默认值”生效的单任务覆盖、/camel status 与 /camel explain、暂停/恢复控制、精确 (provider, model) 学习隔离、可用于 resume/fork 的事件回放，以及持久化不可用或路由信息不完整时的安全降级。Camel 不会调用大模型判断错误或调优策略。

安装后所有执行策略均为关闭状态。安装本包或注册可选的 /camel 命令，都不会让任何请求自动节流或重试。

Camel 与同类插件的差异

如果主要问题是免费模型的 RATE_LIMIT 恢复和按额度感知的请求节流，应选择 dsh-camel。下面的项目在“恢复”方面有重叠，但解决的是不同层次的问题。

| 同类插件 | 主要关注点 | Camel 增加的能力或明确不做的事 |
| @syncended/dsh-retry | 通用/瞬时模型错误重试、provider 过滤、指数退避和 Retry-After | Camel 专注限流：可在触发限流前节流，按精确 provider/model 学习额度，并在配置范围内长时间或无限等待；不替代通用模型错误重试。 |
| dsh-client-auto-continue / dsh-auto-continue | Web UI 中断后发送配置好的“继续”消息，并提供退避、循环和幂等护栏 | Camel 工作在 agent request-error/retry 边界，写入标准 llm/retry 与 llm/retry-started 事件，不注入用户消息，也不依赖浏览器界面。 |
| @linxin666/dsh-chat-recovery | 在 Web UI 手动编辑上一条消息、Fork session 并重试失败回合 | Camel 自动等待/重试限流，不改写消息，也不 Fork 会话。 |
| @deepseek-ai/dsh-llm-retry | 官方的精确 provider agent-loop 重试、持久化重试事件和 bounded/always 策略 | Camel 是互补的额度层：先让下游重试处理器决定，只有合适且未处理时才接管，避免重复重试事件，同时增加自适应节流和免费模型专用恢复。 |

以上是能力范围对比，不代表推荐或背书；具体行为应以各项目当前版本为准。Camel 不会切换模型、轮换账号，也不会调用模型判断错误类型。

dsh-continue 与 Camel 是互补关系，不是这里的同类对比对象：项目同时需要 Camel 的 RATE_LIMIT 保护和 Continue 的非限流网络恢复/安全无人值守决策时，可以一起安装。默认情况下，Camel 负责限流，Continue 负责 TIMEOUT、TRANSPORT 和 SERVER 恢复。

安装

将 bundle 加入目标 profile：

dsh plugin --profile add dsh-camel

npm 默认入口为本仓库的英文 README。包导出面保持为 dsh-camel 和 dsh-camel/cordis.patch.yml。

单命令任务预设

只有宿主提供可选 commands 服务时才会注册命令。命令只作用于当前任务，不会修改 profile。

/camel preset recover
/camel preset adaptive
/camel preset bounded

- recover：开启无限次 RATE_LIMIT 重试，关闭两种节流。
- adaptive：开启无限次 RATE_LIMIT 重试和自适应节流，关闭固定节流。
- bounded：开启五次 RATE_LIMIT 重试，关闭两种节流。

/camel off 会持久化地关闭当前任务的全部 Camel 策略。/camel reset 会删除该任务覆盖，重新继承插件默认配置；因此已显式开启的全局策略可能重新生效。存在 session 时，/camel set、全部预设、/camel off、/camel reset 和 ctx.camel.setTaskConfig() 都会先追加 camel/config，再修改内存覆盖。该追加抛错时，操作会抛错，保留原有覆盖，不会产生部分持久化或部分内存变更。这与 pause control 的本地降级语义有意不同。

配置与优先级

defaults 为可选项。内置值包含 throttle、retry 和 adaptive 的数值参数，但三者的 enabled 均为 false。

单任务 session override > 插件 defaults > 内置参数默认值

下面是包含两条精确 provider/model 路由的高级 profile 配置：

- id: camel
config:
defaults:
retry:
enabled: true
mode: unlimited
fallbackDelayMs: 60000
throttle:
enabled: true
maxRequests: 20
windowMs: 60000
scope: route
adaptive:
enabled: false
initialRequests: 10
minRequests: 1
maxRequests: 20
windowMs: 60000
safetyRatio: 0.85
decreaseRatio: 0.7
increaseAfterWindows: 3
stateTtlMs: 86400000
routes:
- provider: provider-a
model: model-v3
enabled: true
initialRequests: 8
maxRequests: 12
- provider: provider-b
model: model-r1
enabled: true
initialRequests: 4
maxRequests: 6

请将示例路由替换为 Harness adapter 实际解析出的精确 request.provider 与 request.model 字符串。路由按精确二元组匹配，不使用展示名称、前缀、通配符或错误消息猜测。同一 provider 下的不同 model 不会共享已学习额度。model 缺失或为空时，该请求不进行自适应读取或写入；固定节流与 RATE_LIMIT 重试仍按各自已启用的策略执行。

某条已解析路由开启自适应节流后，自适应策略独占该路由的节流；不会再叠加固定 throttle。自适应准入上限为 max(minRequests, floor(learnedRequests × safetyRatio))；匹配的 RATE_LIMIT 用 decreaseRatio 降低已学习次数，连续干净窗口在达到 increaseAfterWindows 后可逐步加一。学习值受 minRequests 和 maxRequests 约束，在 stateTtlMs 后过期；插件不会调用模型来判断失败类型或调优策略。

同一条已解析的 provider/model 路由只保存一份规范的共享学习状态。单任务的 minRequests、maxRequests 与干净窗口阈值只用于该任务的准入和展示视图；仅仅读取状态绝不会改写其他任务的已学习容量或 TTL。在同一个存活的运行时内，同一时间戳的 session 快照会在不依赖任务启动顺序的前提下保守合并；同一状态版本以更短 TTL 为准。后续真实的学习状态变更可以按产生该变更的策略重新设定 TTL。新的 quota 快照还会记录当前 rateLimitedInWindow 标记；缺少该字段的旧快照会被保守地恢复为“当前部分窗口可能已经限流”。

所有次数必须是正安全整数，比例必须是 (0, 1] 内的有限值，并满足 minRequests <= initialRequests <= maxRequests。bounded 重试必须提供 maxRetries。未知或非法字段会 fail closed，不会以部分有效策略运行。

状态、暂停与解释

/camel status
/camel explain
/camel pause 10m
/camel resume

status 输出 JSON，其中包含任务覆盖、最终生效策略、暂停截止时间、最近活动和已触及路由的快照。explain 给出简短的当前原因，例如自适应节流或已安排的重试。pause 默认十分钟，接受正整数加 ms、s、m 或 h 后缀。暂停期间 Camel 会下放处理，不会节流或接管重试；resume 清除暂停。

重试与持久化边界

Camel 只处理已配置的限流错误码（默认 RATE_LIMIT），并先让下游恢复策略决定。在同时安装 dsh-continue 的环境中，非限流网络恢复仍由 dsh-continue 负责；只有下游拒绝后，Camel 才可能接管 RATE_LIMIT。Camel 不轮换账号、不选择或回退模型、不回答澄清问题、不批准操作，也不基于模型调用作判断。

成功接管会写入标准 llm/retry 和 llm/retry-started 事件。Camel 还使用以下 version 1、对模型不可见的 session 事件形状：

'camel/config': { version: 1, override: CamelPolicyPatch | null, source: 'command' | 'api' }
'camel/control': { version: 1, pausedUntil: number | null }
'camel/quota': AdaptiveQuotaSnapshot & { version: 1 }
// AdaptiveQuotaSnapshot = { route, learnedRequests, cooldownUntilMs, cleanWindows, windowStartedAtMs, updatedAtMs, rateLimitedInWindow? }
'camel/activity': { version: 1, kind, provider, model?, attempt?, reasonCode?, deadlineMs?, policySource }

kind 只能是 pacing、cooldown、retry-scheduled、retry-started、delegated、cancelled 或 exhausted；policySource 只能是 adaptive、throttle 或 retry。标准 llm/retry 包含 retryId、turn、step、provider、retry、delayMs、failure 和 Camel 的 policyKey，且始终包含 mode；只有 bounded 模式包含 maxRetries。llm/retry-started 包含 retryId、turn、step 和 retry（它没有 provider 字段）。新的 Camel retryId 可以编码已解析的 model；旧 provider-only ID 仍可读取，以兼容 retry 历史。

既有的 version 1 camel/config 与标准 retry 历史仍可读取，因此 resume 或 fork 后可以保留兼容的任务配置和重试序号。成功追加到 session 的 quota 和 control 事件可在 resume 时回放。在同一个存活的 Camel runtime/plugin instance 内，相同精确 provider/model route 的任务共享 adaptive 状态；不同 runtime instance、不同进程，以及没有 resumed event 回放的 session 不共享。

自定义 quota 或 activity 持久化失败时，Camel 记录告警并使用内存状态继续请求。pause control 持久化失败时，暂停仍在当前存活任务中生效，同时记录告警。必需的标准 retry 事件无法追加时，Camel 不会返回未记录的 retry 决定。

职责边界

Camel 有意不处理账号或 Key 轮换、provider 重配置、模型切换、自动模型回退、全局额度存储和非限流网络恢复。请使用 dsh-continue 已实现的任务续行能力；本包不会声称 dsh-continue 尚未实现的能力。