@naced/llm-multi-rate-limiter 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [0.1.0] - 2026-10-26
+
+Fork of `@leaf233/dsh-llm-rate-limiter` 0.3.0, retargeted at the DSH 0.2.1 client contract.
+
+### Changed
+
+- **Settings UI**: the configuration form is now a `settings.section` entry (Settings → 多模型限速) instead of a `plugins.item` card. The old card never rendered on 0.2.1 shells whose sidebar comes from a third-party bundle, because `.dsh/market/*` page ownership — not this plugin — decides which page hosts `plugins.item`.
+- The page owns its own `ConfigFormController` through `ctx.configForms.get("llm-multi-rate-limiter")` and binds it with `hooks: { snapshot: form.store }`, so it no longer depends on a host page passing `props.form`.
+- Package renamed to `@naced/llm-multi-rate-limiter`; client no longer injects `dsh-client-ui-plugin-manager`.
+- `plugins.row.config` entry point removed.
+
+### Added
+
+- Model picker with a text field (`provider/model`) plus per-row RPM / concurrency / burst inputs and enable-remove actions.
+- Effective-limit readout per model (override or inherited default).
+- Bilingual dictionaries (zh/en) registered for the section, so labels follow the UI locale instead of hard-coded Chinese.
+- Sidebar entry: `sidebar.panellist` registration (`order: 40`) plus the matching `main` panel, so the page is reachable from the app sidebar on shells that draw navigation there. Both surfaces share one `inject` factory.
+
+### Fixed
+
+- **Fail-open interceptor**: if config parsing or a strategy throws, the call is now forwarded unthrottled with a warning instead of failing. Previously an exception escaped the `llm/stream` generator and every model call failed.
+- Duplicate-limiter warning when `@leaf233/dsh-llm-rate-limiter` is also installed (both hook `llm/stream`, so calls would be limited twice).
+
+### Security
+
+- README documents exactly what the `llm/stream` position touches: `options.provider`, `options.model`, `options.signal` only; no prompt, response or credential access; no outbound network calls; no `fs` / `child_process` / `eval`; no install scripts.
+- `engines.dsh` (`>=0.2.1-rc.2`) now states the tested runtime, so DSH's compatibility check has a real range to evaluate instead of relying on an unbounded peer range.
+- `exports` gained `./package.json` (consistent with other DSH plugins; the loader's directory walk no longer has to carry it).
+- Internal provider names removed from the README samples and the model input placeholder.
+- LICENSE carries both copyright lines (upstream MIT + this fork).
+
+### Unchanged
+
+- Host half: `llm/stream` waterfall interception, token-bucket and sliding-window strategies, `/llm-multi-rate-limiter` status channel with its self-registered fallback route, queueing with `maxQueueWaitMs`.
+- Settings storage: the profile entry's volatile `Config` references, written through `settings.mutate` into `cordis.patch.yml`.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dsh-llm-rate-limiter contributors (https://github.com/Leafyezi233/dsh-llm-rate-limiter)
+Copyright (c) 2026 @naced/llm-multi-rate-limiter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @naced/llm-multi-rate-limiter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Per-`provider/model` LLM rate limiting for DeepSeek Harness, with an editable **Settings** page (Settings → Multi-model limits) and a live status panel.
+
+Forked from [`@leaf233/dsh-llm-rate-limiter`](https://github.com/Leafyezi233/dsh-llm-rate-limiter) 0.3.0 (MIT, © the upstream contributors). The configuration surface moved from the "built-in plugin config" card to a `settings.section` page and a sidebar entry; the card entry is gone.
+
+## Features
+
+- **Two strategies**: token bucket (bursts allowed) or sliding window (strict N per minute).
+- **Per-model overrides**, keyed `provider/model`, e.g. `openai/gpt-5.1`.
+- **Queue or reject** throttled calls (`onThrottled`, bounded by `maxQueueWaitMs`).
+- **Live panel**: polls the `/llm-multi-rate-limiter` status channel once per second — per-model token/window usage, granted calls, average wait, recent events.
+
+## Configuration
+
+`~/.dsh/profiles/desktop/cordis.patch.yml`:
+
+```yaml
+- id: llm-multi-rate-limiter
+  name: "@naced/llm-multi-rate-limiter"
+  config:
+    enabled: true
+    strategy: sliding-window
+    defaults:
+      maxConcurrent: 5
+      maxRpm: 60
+      burstSize: 10
+      refillRate: 1
+    models:
+      openai/gpt-5.1:
+        maxRpm: 20
+        maxConcurrent: 2
+      deepseek/deepseek-chat:
+        maxRpm: 60
+        maxConcurrent: 5
+    onThrottled: queue
+    maxQueueWaitMs: 240000
+```
+
+- The row `id` is also the settings namespace (`dsh-settings` keys forms by `entry.options.id`), so keep it in step with the row.
+- `models[<key>]` only needs the fields you override; the rest inherits `defaults`.
+- Under the token bucket, an omitted `refillRate` (tokens/second) is derived from `maxRpm / 60`.
+
+Edits made in the Settings page are written back to `cordis.patch.yml` immediately and hot-reload through `dsh-hmr`.
+
+## Install
+
+1. Place the package in the profile's `packages/llm-multi-rate-limiter` and add the dependency to the profile `package.json`:
+   ```json
+   "@naced/llm-multi-rate-limiter": "file:./packages/llm-multi-rate-limiter"
+   ```
+2. Add `"@naced/llm-multi-rate-limiter"` to `dsh.profile.bundles`.
+3. Append the `cordis.patch.yml` row above, then restart DSH.
+
+## Security
+
+This plugin intercepts the `llm/stream` waterfall, so it sits in front of every model call. What it actually does with that position:
+
+- Reads only `options.provider`, `options.model` and `options.signal`. Prompts, messages, responses and credentials are never inspected, logged or transmitted.
+- Makes no outbound network calls. The only HTTP surface is its own status channel (`/llm-multi-rate-limiter`), which is fenced by `connection.requestRejection()`, accepts `POST` + `application/json` only, and returns counters plus `provider/model` keys — no conversation content.
+- Makes no filesystem or process calls (`fs`, `child_process`, `eval` are not imported); configuration is written through the host's settings service.
+- Ships no install scripts.
+
+If the limiter itself throws, the call is passed through untouched rather than failing, so a bug here cannot take the assistant offline.
+
+## License
+
+MIT. Based on `@leaf233/dsh-llm-rate-limiter`; see [LICENSE](LICENSE) for both copyright lines.

package/README.zh.md

@@ -0,0 +1,72 @@
+# @naced/llm-multi-rate-limiter
+
+按 **provider/model** 限制 LLM 请求频率的 DeepSeek Harness 插件，带一个可编辑的「设置」页（Settings → 多模型限速），以及实时状态面板。
+
+本包 fork 自 [`@leaf233/dsh-llm-rate-limiter`](https://github.com/Leafyezi233/dsh-llm-rate-limiter) 0.3.0（MIT，版权归上游作者），主要改动是把配置界面从「内置插件配置」卡片改为 `settings.section` 设置页 + 侧边栏入口，并移除了卡片入口。
+
+## 功能
+
+- **两种限速策略**：令牌桶 `token-bucket`（允许突发）／滑动窗口 `sliding-window`（严格每分钟 N 次）。
+- **按模型独立配置**：key 为 `provider/model`，例如 `openai/gpt-5.1`。
+- **排队或拒绝**：`onThrottled: queue` 时请求等待空位（受 `maxQueueWaitMs` 约束），`reject` 时立即返回错误。
+- **实时面板**：每秒拉取 `/llm-multi-rate-limiter` 状态通道，显示各模型当前令牌/窗口占用、累计放行、平均等待，以及最近事件。
+
+## 配置
+
+配置写在 profile 的 `cordis.patch.yml`（`~/.dsh/profiles/desktop/cordis.patch.yml`）：
+
+```yaml
+- id: llm-multi-rate-limiter
+  name: "@naced/llm-multi-rate-limiter"
+  config:
+    enabled: true
+    strategy: sliding-window
+    defaults:
+      maxConcurrent: 5
+      maxRpm: 60
+      burstSize: 10
+      refillRate: 1
+    models:
+      openai/gpt-5.1:
+        maxRpm: 20
+        maxConcurrent: 2
+      deepseek/deepseek-chat:
+        maxRpm: 60
+        maxConcurrent: 5
+    onThrottled: queue
+    maxQueueWaitMs: 240000
+```
+
+- 行 `id` 同时是设置命名空间（`dsh-settings` 按 `entry.options.id` 建表单），改名需与 `cordis.patch.yml` 一致。
+- `models[<key>]` 只写需要覆盖的字段，其余继承 `defaults`。
+- 令牌桶下 `refillRate`（个/秒）若省略，会按 `maxRpm / 60` 推导。
+
+设置页里改任何字段都会立即写回 `cordis.patch.yml` 并热生效（`dsh-hmr` 监听 profile patch）。
+
+## 安装
+
+1. 把包放到 profile 的 `packages/llm-multi-rate-limiter`，并在 profile `package.json` 里加依赖：
+   ```json
+   "@naced/llm-multi-rate-limiter": "file:./packages/llm-multi-rate-limiter"
+   ```
+2. `dsh.profile.bundles` 列表中加入 `"@naced/llm-multi-rate-limiter"`。
+3. 在 `cordis.patch.yml` 加上面那段配置，重启 DSH。
+
+## 卸载
+
+删除 `cordis.patch.yml` 中该行与 `bundles` 里的包名，再删 `node_modules/@naced/llm-multi-rate-limiter` 即可。
+
+## 安全说明
+
+本插件拦截 `llm/stream` 瀑布，位于每一次模型调用之前。它到底用这个位置做了什么：
+
+- 只读 `options.provider`、`options.model`、`options.signal`；不检查、不记录、不外发 prompt、messages、响应或凭据。
+- 不发起任何对外网络请求。唯一的 HTTP 面是自带状态通道 `/llm-multi-rate-limiter`，由 `connection.requestRejection()` 加鉴权栅栏，只接受 `POST` + `application/json`，返回的是计数器与 `provider/model` 键，不含对话内容。
+- 不使用 `fs`、`child_process`、`eval`；配置写入走宿主 settings 服务。
+- 没有安装脚本。
+
+限速器自身抛错时会原样放行请求，而不是让调用失败——这里的 bug 不会把助手整体弄挂。
+
+## License
+
+MIT。基于 `@leaf233/dsh-llm-rate-limiter`，双版权行见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: llm-multi-rate-limiter
+      name: '@naced/llm-multi-rate-limiter'