# dsh-camel

English：[README.md](../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`](https://www.npmjs.com/package/@syncended/dsh-retry) | 通用/瞬时模型错误重试、provider 过滤、指数退避和 `Retry-After` | Camel 专注限流：可在触发限流前节流，按精确 provider/model 学习额度，并在配置范围内长时间或无限等待；不替代通用模型错误重试。 |
| [`dsh-client-auto-continue`](https://www.npmjs.com/package/dsh-client-auto-continue) / [`dsh-auto-continue`](https://github.com/HsiangNianian/dsh-auto-continue) | Web UI 中断后发送配置好的“继续”消息，并提供退避、循环和幂等护栏 | Camel 工作在 agent request-error/retry 边界，写入标准 `llm/retry` 与 `llm/retry-started` 事件，不注入用户消息，也不依赖浏览器界面。 |
| [`@linxin666/dsh-chat-recovery`](https://www.npmjs.com/package/@linxin666/dsh-chat-recovery) | 在 Web UI 手动编辑上一条消息、Fork session 并重试失败回合 | Camel 自动等待/重试限流，不改写消息，也不 Fork 会话。 |
| [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@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：

```sh
dsh plugin --profile <profile-name> add dsh-camel
```

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

## 单命令任务预设

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

```text
/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`。

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

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

```yaml
- 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，不会以部分有效策略运行。

## 状态、暂停与解释

```text
/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 事件形状：

```ts
'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` 尚未实现的能力。