dsh-inhibition

Readme

# dsh-inhibition

[![npm](https://img.shields.io/npm/v/dsh-inhibition)](https://www.npmjs.com/package/dsh-inhibition) [![GitHub](https://img.shields.io/badge/GitHub-dncore%2Fdsh--inhibition-blue)](https://github.com/dncore/dsh-inhibition)

DeepSeek Harness (DSH) 模型请求限流插件:在 `llm/stream` waterfall 接缝上为每个 provider/model 桶建立 FIFO 队列,用 `minIntervalMs` + `maxConcurrent` 人为控制 API 请求下发频率,避免触发第三方 API 限频。

## 安装

```bash
# 在官方仓库中运行 CLI(或使用你已安装的 dsh)
dsh plugin --profile <名字> add /path/to/dsh-inhibition

# 验证加载
dsh --profile <名字> --dump-config | grep -A 5 inhibition
dsh plugin --profile <名字> why dsh-inhibition
```

建议为插件开发使用独立 profile(如 `dev`),不影响日常的 web profile。

## 配置

在 profile 的 `~/.dsh/profiles/<名字>/cordis.patch.yml` 中添加:

```yaml
- id: inhibition
  config:
    enabled: true            # 总开关,默认 true;false = 全部直通
    default:                 # 所有未命中桶的兜底(缺省 = 不限流)
      minIntervalMs: 3000
      maxConcurrent: 1
    providers:
      deepseek:
        minIntervalMs: 5000
        models:
          deepseek-chat:     # 模型级覆盖
            minIntervalMs: 2000
            maxConcurrent: 2
      openrouter:
        minIntervalMs: 1000
```

### 参数语义

| 参数 | 语义 |
|---|---|
| `minIntervalMs` | 相邻两次请求**开始下发**的最小间隔(毫秒),即频率的倒数 |
| `maxConcurrent` | 桶内同时在途请求上限;`1` = 严格串行队列;缺省 = 不限制 |

### 字段级继承

每个字段独立沿 `models[model] → providers[provider] → default` 取就近定义值。例如 `deepseek-chat` 只覆盖了 `minIntervalMs`,则其 `maxConcurrent` 继承 `providers.deepseek` 或 `default` 的值。完全未配置的 provider(无 default 时)不限流、零开销。

### ⚠️ 桶拆分的聚合效应

**只有当多个模型解析出相同参数时,它们才共享同一个队列**。一旦给某个模型设置覆盖,它会分裂成独立的桶:例如 provider 级 `minIntervalMs: 5000` + 两个模型各自覆盖,则两个模型各有一条 5s 间隔的独立队列——对同一个 API 的聚合速率可达 2.5s 一次,可能超出你的预期。

如果你要限制的是 **provider 整体的请求速率**(多数第三方 API 的限频口径),请把参数配在 provider 级或 `default` 级,**不要**给模型配覆盖,这样该 provider 的所有模型共享一条队列。

## 工作原理

- 插件注册一个 `llm/stream` waterfall 监听器,包裹每一次流式模型调用;请求先进入对应桶的 FIFO 队列,同时满足间隔与并发约束后才放行到真实 adapter。
- 排队期间请求被取消(`AbortSignal` 中止)时,该请求立即出队且**不消耗限流名额**。
- 实际等待 > 0 的派发会记录日志:`inhibition: deepseek/deepseek-chat dispatched, waited 2340ms (in-flight 1, queued 2)`。
- 插件卸载时唤醒所有排队请求(放行为直通,由 adapter 按 abort 语义处理),不留悬挂定时器。

## 发布与分发

三种方式,按覆盖范围递增:

1. **本地/私有**: `dsh plugin --profile <名字> add /path/to/dsh-inhibition`
2. **npm**: `npm publish --access public` 后,用户执行 `dsh plugin --profile web add dsh-inhibition`(本包产物 `lib/` 已提交、无 prepare 脚本,git/npm 安装均无需构建)
3. **[dsh-plugin.org 插件中心](https://dsh-plugin.org)**: 推送到公开 GitHub 仓库 → 仓库添加 topic `dsh-plugin` → README 含安装命令(✅)且插件导出 `apply(ctx)`(✅),爬虫自动收录

## 开发

```bash
npm install
npm test        # vitest 单测 + LlmRuntime 集成测试
npm run build   # tsc 产物输出 lib/(已提交,本地安装无需构建)
```

设计文档见 `docs/superpowers/specs/`,实现计划见 `docs/superpowers/plans/`。

## License

MIT