@leaf233/dsh-llm-rate-limiter 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,216 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.3.0] - 2026-09-28
+
+**Requires DSH 0.1.7-rc.1 or newer.** For DSH 0.1.5-rc.3, stay on `0.2.x`.
+
+### Changed (breaking)
+
+DSH 0.1.7 replaced both client services this plugin used for its settings UI, and
+removed the host namespace API. All four breakpoints are source-verified against
+the installed 0.1.7-rc.1 tree:
+
+- **Client: `settingsScope` → `configForms`.** `SettingsScopeController` is gone;
+  the page now hands each `plugins.item` entry a `ConfigForm` as
+  `props.form` (`dsh-client-ui-plugin-manager/lib/client.js:2627-2634`, `:2832`).
+  The snapshot shape is unchanged (`{status, value, base, user, revision, writable,
+  mode}`), so the card reads `props.form.state.value` exactly as it read
+  `settingsScope.getSnapshot().value`.
+- **Client slot: `settings.plugin.item` → `plugins.item`**, declared by
+  `dsh-client-ui-plugin-manager` (`slot-contract.d.ts:90`). The page draws the
+  card chrome itself and asks the entry for `view: "summary"` and
+  `view: "page"`; the plugin renders the one-liner and the body respectively.
+  `id` replaces `key` (a list slot requires `id`, `dsh-client-ui-slots/lib/index.js:182`),
+  and `order: 900` parks the card after the official pages (10/20/30/40).
+- **Client inject: `["slots", "locale", "configForms"]`**, and the plugin now
+  registers its own locale dictionary — an entry that `declares locale namespace`
+  with no dictionary installed throws `SlotAssemblyError`
+  (`dsh-client-ui-renderer/lib/client.js:723`). Previously the plugin declared
+  `locale: name` without ever registering it.
+- **Host: `ctx.settings.register()` / `scope.watch()` removed.** Configuration is
+  now the profile entry's own `Config`, which the plugin exports
+  (`export { apply, name, SETTINGS_NS, Config }`) and reads through volatile
+  references. Every editable leaf is marked `.volatile()`.
+
+### Fixed
+
+- **The plugin no longer hangs in `pending` on DSH 0.1.7.** It previously waited
+  for a `settingsScope` service the framework no longer provides.
+
+### Changed
+
+- **`models` is volatile as ONE BLOCK** — `z.dict(ModelOverride).volatile()`,
+  never `z.dict(ModelOverride.volatile())`. The latter is rejected by
+  schemastery ("volatile fields require a fixed object path without an enclosing
+  volatile field", `schemastery/lib/index.mjs:246`). Because
+  `isVolatilePath` returns true on reaching ANY volatile node without inspecting
+  its descendants (`dsh-settings/lib/index.js:153-158`), nested writes such as
+  `["models", "provider/model", "maxRpm"]` still work — the plugin's per-model
+  editor is unaffected.
+- Configuration is now read **at each use** (`config.enabled.get()`) rather than
+  cached. A volatile-only settings write updates the references in place via the
+  loader's `_commitVolatile()` (`cordis-plugin-loader/lib/index.js:393`)
+  **without re-running `apply()`**, so a cached snapshot would go stale.
+- The plugin opts out of schema-generated pages with
+  `settings.configure({ auto: false }, ctx.fiber)` from an optional
+  `ctx.inject(["settings"], ...)` child, following the shipped idiom
+  (`dsh-settings/README.md:39`; `dsh-client-locale/lib/index.js:24`). It is not
+  currently required — nothing shipped consumes `autoGenerate` — but it is cheap
+  and matches the official pages.
+- `dependencies`: `@deepseek-ai/schemastery` `^3.18.0` → `^3.18.4`.
+  `.volatile()` does not exist in 3.18.2 (0 occurrences; 28 in 3.18.4).
+- `peerDependencies`: added `"@deepseek-ai/dsh-settings": ">=0.1.7-rc.1"` and
+  raised schemastery to `>=3.18.4`.
+- The DSH gate is a **dsh-* subpackage** peer, not the `@deepseek-ai/dsh`
+  umbrella. `evaluatePluginCompatibility()` treats both identically — verified by
+  importing the real exported function and comparing its verdict for
+  `@deepseek-ai/dsh` against `@deepseek-ai/dsh-settings` across
+  `0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.6-alpha.2 / 0.1.7-rc.1 / 0.1.7-rc.2` (identical
+  every time: blocked on 0.1.5, allowed from 0.1.7-rc.1). The umbrella form costs
+  far more: a `pnpm install --lockfile-only` comparison measured **777,850 bytes**
+  for `@deepseek-ai/dsh` versus **27,725 bytes** with the subpackage — the umbrella
+  resolves the entire DSH dependency graph (~600 packages) into the lockfile.
+  Marking it `optional` in `peerDependenciesMeta` does NOT help (measured:
+  777,588 bytes, effectively identical), because the gate reads
+  `peerDependencies` and never consults that field
+  (`dsh-app-boot/lib/index.js:289-301`) while pnpm's `autoInstallPeers` still
+  materializes it. This also matches the shipped convention: `dsh-free-search`,
+  `dsh-context`, and `@leaf233/dsh-model-relay` all gate on dsh-* subpackages.
+  Lockfile growth for this release is **+464/-8 lines (~26 KB)**, down from 8,015
+  lines with the umbrella peer.
+- `devDependencies` holds only `@deepseek-ai/dsh-settings` — the one package the
+  schema test needs in order to exercise the real helpers. The previously listed
+  `dsh-client-store` / `dsh-client-ui-primitives` / `dsh-client-ui-slots`
+  entries were imported by nothing and were dropped.
+- `dsh.client.inject` now also declares `dsh-client-locale` and
+  `dsh-client-ui-plugin-manager`.
+
+### Removed
+
+- **`dsh.compatibility.dshReleases`** — a dead field. It has zero occurrences in
+  both the 0.1.5 and 0.1.7 trees; the real compatibility gate is
+  `evaluatePluginCompatibility()` (`dsh-app-boot/lib/index.js:286-313`), which
+  reads only `peerDependencies` matching `@deepseek-ai/dsh` / `dsh-*`.
+- `lib/client.js`'s `RateLimiterConfig` export is now `Config` (also re-exported
+  from `lib/types/index.js`).
+
+### Added
+
+- **`test-config-schema.mjs` (36 assertions)** — pins the contract the settings
+  page depends on: `Config` yields a non-empty `volatileForm`; `models` is
+  whole-block volatile and nested paths stay writable; `dict(inner.volatile())`
+  is refused; and a Config with no volatile field is dropped — the regression
+  guard against deleting a `.volatile()` mark.
+- `test-host-integration.mjs` §13 proves volatile references are read in place:
+  it mutates the reference the plugin already holds and asserts the change
+  reaches the snapshot with no remount.
+- `test-client-bundle.mjs` now covers the page protocol: both views, six write
+  paths through `props.form.mutate` (including the nested per-model case),
+  read-only/unavailable/missing-form degradation, and the `whileServed` gate.
+- **`README.zh.md`** — full Simplified Chinese README, following the DSH house
+  convention of a `README.md` + `README.zh.md` pair (every official package
+  ships both). Both files carry a language switcher line under the badges, and
+  the Chinese file is listed in `package.json`'s `files` so it ships to npm.
+  Code blocks, tables, and section structure are 1:1 with the English original
+  (verified: 16 fence lines, 48 table rows, 1 YAML block each).
+- The "Via file" section in both languages now describes 0.1.7 accurately:
+  configuration persists as the entry's own `config` in the profile's Cordis
+  patch, and a legacy `settings.yaml` is imported by DSH once at first start
+  (then renamed) rather than being the live store.
+
+### Fixed (tooling and docs)
+
+- **`test-config-schema.mjs` now exercises the REAL framework helpers.** Its
+  resolution previously asked for `@deepseek-ai/dsh-settings/lib/types/schema.js`
+  directly, which can never resolve — that path is not in the package's
+  `exports` map (only `.`, `./types`, `./src/*`), so the suite silently fell back to a
+  local re-implementation on every run. It now resolves the package ROOT and
+  appends the file path, converts it with `pathToFileURL()` (a native Windows
+  path makes `import()` fail with `ERR_UNSUPPORTED_ESM_URL_SCHEME`), and
+  `@deepseek-ai/dsh-settings` is a devDependency so the real path is reachable.
+  Confirmed by the run header switching from "\u25cb not resolvable — using
+  equivalent local helpers" to "\u25cf using the real @deepseek-ai/dsh-settings
+  schema helpers" (36/36 pass). The fallback branch now prints a
+  `DSH_REAL_PACKAGES` hint, so a silent fallback is never mistaken for
+  framework-level proof.
+- **CI now runs `test-config-schema.mjs`** and `node --check`s **all seven**
+  shipped lib modules (previously 5 of 6 suites and 3 files). The contract that
+  decides whether the settings card exists at all — an entry with no volatile
+  field is dropped (`dsh-settings/lib/index.js:419`) — had no regression
+  protection in CI, while being the one failure mode that leaves the rate
+  limiter working and the card silently missing.
+- **CI Node matrix is now `[20, 22, 24]`** (was `[18, 20, 22]`): 18 is EOL and 24
+  is the version the plugin is developed and run on.
+- **`tools/verify-install.mjs` skips its install half instead of failing** when
+  the plugin is not present in the profile, and falls back to importing the
+  source tree. Exit codes are now 0 = fully verified, 1 = a check failed,
+  2 = source-tree checks passed but the install half was skipped (the same
+  contract as `tools/verify-live-route.mjs`). A local run without an installed
+  profile goes from 2 misleading failures to **31 passed / 0 failed / exit 2**.
+- Removed the dangling `COMPATIBILITY.md` references left when that file was
+  deleted: the `package.json` `files` entry, the README badge link in both
+  languages, and the closing "see COMPATIBILITY.md" links (now pointing at
+  `CHANGELOG.md` and the inline source comments). The historical `CHANGELOG.md`
+  mention under `[0.1.0]` is intentionally kept, and the `lib/index.js` header
+  comment no longer points at the deleted file.
+
+### Notes
+
+- `test-3rpm.mjs` is deliberately **left out of the `test` script**. It prints
+  conclusions rather than making assertions, and it re-implements
+  `resolveModelConfig` instead of importing it (`test-3rpm.mjs:15-28`), so it
+  cannot detect a drift between itself and `lib/index.js`. It still runs
+  cleanly against 0.3.0. Converting it into a real assertion suite would mean
+  exporting the resolver or driving the interceptor — out of scope for this
+  migration.
+
+### Verified
+
+- All six suites green on DSH `0.1.7-rc.1` packages with Cordis 4.0.4,
+  schemastery 3.18.4, Node 24.21.0: **19 + 61 + 106 + 80 + 73 + 36 = 375
+  assertions, 0 failures**.
+- `node tools/verify-install.mjs`: 37 passed, 0 failed.
+- Against the **real** `@deepseek-ai/dsh-settings` service: `describe()` returns
+  the entry with all six volatile fields, `autoGenerate: false`, and
+  `models` unwrapped to a plain object; a nested
+  `["models", "c/d", "maxRpm"]` mutation passes `write()`'s volatile gate while
+  a non-volatile path is still refused (12/12).
+- The status channel needs no change: the `dsh-client-connection` `inject`
+  mismatch that forces the fallback is **still unfixed in 0.1.7-rc.1**
+  (`dsh-client-connection/lib/index.js:798` keeps `inject = ["credentials"]`),
+  so the v0.2.1 dual-path carrier continues to work as designed.
+- Producer: **deepseek-v4.1-flash**.
+
+### Migration
+
+- On DSH 0.1.7+: install `0.3.0`. Your existing `llm-rate-limiter` configuration
+  in the profile's settings/cordis patch is read as the entry's own `config`;
+  no manual migration was performed by the plugin.
+- On DSH 0.1.5-rc.3: keep `0.2.x`.
+
+## [0.2.1] - 2026-09-25
+
+### Fixed
+- **Live status panel stopped working on DSH 0.1.5-rc.3** — the channel silently failed to mount and the panel sat on "○ 重试中" forever. Root cause is upstream: DSH 0.1.5-rc.3 changed `@deepseek-ai/dsh-client-connection`'s own `inject` from `["webServer", "credentials"]` to `["credentials"]`, while `HostConnectionService.register()` still dereferences `owner.webServer`. Cordis rebinds a cross-fiber service's `ctx` to the *reader's* fiber, so `connection.rpc.handle()` threw `cannot get property "webServer" without inject` — which the plugin's own try/catch swallowed.
+- The plugin now falls back to a **self-registered `kind: "prefix"` route** on its own fiber (which can see `webServer`) and reuses `connection.requestRejection()` for the 403/401 fence. Both carriers speak the identical wire protocol, so **`lib/client.js` is unchanged**.
+
+### Added
+- `createChannelRoute({ channel, handler, reject })` and `endpointFromPath()` in `lib/status-rpc.js` — a Connection-RPC-compatible webserver prefix route, mirroring the framework's `rpcFetchHandler` request-shape decisions (404 / 415 / 413 / 400 / `gateway/bad-request` / 500 / 200)
+- `test-status-route.mjs` (73 assertions) in four layers: route grammar, request-shape decisions, a simulated 0.1.5 regression (proves both the fallback *and* the preference for `rpc.handle` when it works), and the real 0.1.5 package (auto-skips when DSH is absent)
+- `tools/verify-live-route.mjs` (19 assertions) — boots the real `dsh-host-webserver` on a real socket plus the real `dsh-client-connection`, then issues real HTTP requests; exits 2 (skipped) without a DSH install
+- `pnpm run verify:live` script
+
+### Changed
+- `dsh.compatibility.dshReleases` now declares `0.1.5-rc.3` as compatible alongside `0.1.2-rc.1`
+- The status channel's mount log now names the active carrier (`connection.rpc` vs `self-registered route`), and a failed path-1 registration is reported as a warning instead of being swallowed
+- If `connection.requestRejection()` is unavailable or throws, the plugin **refuses to mount** rather than publishing an unauthenticated route
+
+### Notes
+- Path 1 (`connection.rpc.handle`) is still preferred: it keeps route ownership, request validation, and withdrawal with the framework. The fallback exists only for hosts where path 1 is broken.
+- When DSH fixes the upstream `inject` mismatch, path 1 succeeds again and the fallback goes unused — no plugin change required.
+- Verified on: DSH `0.1.5-rc.3` (client-connection 0.1.5-rc.3, host-webserver 0.1.5-rc.3), Cordis 4.0.2, Node 24.21.0. Test totals: 19 + 61 + 70 + 77 + 73 = **300 assertions**, plus 31 in `tools/verify-install.mjs` and 19 in `tools/verify-live-route.mjs`. Producer: **deepseek-v4.1-flash**.
+
 ## [0.2.0] - 2026-09-13
 
 ### Added
@@ -49,4 +259,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 - `maxQueueWaitMs` timeout for queue mode
 - 19 unit tests covering concurrency, burst, queue, abort, and hot-reload
 - E2E test (`test-3rpm.mjs`) verifying 3 rpm limit
-- DSH version compatibility analysis (COMPATIBILITY.md)
+- DSH version compatibility analysis (COMPATIBILITY.md)

package/README.md

@@ -2,9 +2,11 @@
 
 [![npm](https://img.shields.io/npm/v/@leaf233/dsh-llm-rate-limiter.svg)](https://www.npmjs.com/package/@leaf233/dsh-llm-rate-limiter)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![DSH 0.1.x](https://img.shields.io/badge/DSH-0.1.x-brightgreen.svg)](COMPATIBILITY.md)
-[![Cordis 4.x](https://img.shields.io/badge/Cordis-%3E%3D4.0.2-brightgreen.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-19%2F19%20passing-brightgreen.svg)](test-strategies.mjs)
+![DSH 0.1.7+](https://img.shields.io/badge/DSH-0.1.7--rc.1%2B-brightgreen.svg)
+[![Cordis 4.x](https://img.shields.io/badge/Cordis-%3E%3D4.0.0-brightgreen.svg)](package.json)
+[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen.svg)](test-config-schema.mjs)
+
+English | [中文](README.zh.md)
 
 Per-model LLM call rate limiter for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) with queue/reject support and interactive GUI configuration.
 
@@ -39,7 +41,8 @@ Expanding the card shows a live panel at the top of its body:
 
 | Aspect | Behaviour |
 |--------|-----------|
-| Data channel | Framework `connection.rpc` channel `/llm-rate-limiter` — authenticated (401/403 fence), POST+JSON, auto-cleaned with the plugin fiber |
+| Data channel | Channel `/llm-rate-limiter` — authenticated (401/403 fence), POST+JSON, auto-cleaned with the plugin fiber |
+| Carrier | Prefers the framework's `connection.rpc.handle()`; falls back to a self-registered prefix route that reuses `connection.requestRejection()` when the framework path is broken (see below) |
 | Cadence | 1 s polling while the card is expanded; backs off 2 s → 4 s → 8 s after failures |
 | Collapsed card | The panel unmounts, so **no polling runs at all** |
 | Endpoints | `snapshot` (live counters) and `reset` (zero the statistics) |
@@ -47,7 +50,29 @@ Expanding the card shows a live panel at the top of its body:
 | Counters | `requests` / `granted` / `rejected` / `timeouts` / `aborted` / `totalWaitMs`, plus the last 8 events (ring buffer of 64) |
 | Progress bars | Token bucket shows `tokens/burstSize`; sliding window shows `countInWindow/maxRpm`; both turn amber as the limit approaches |
 
-> 🧠 **From Hindsight memory (dsh-context-host-client)** — the channel idiom is dsh-context's: `ctx.inject(["connection"])` → `conn.rpc.handle(channel, handler)`, with the browser side resolving `ctx.get("connection")?.rpc.call` defensively so a missing service degrades instead of throwing.
+### Carrier fallback (DSH 0.1.5-rc.3 onward)
+
+DSH 0.1.5-rc.3 changed `@deepseek-ai/dsh-client-connection`'s own `inject` from
+`["webServer", "credentials"]` to `["credentials"]`, but its
+`HostConnectionService.register()` still dereferences `owner.webServer`.
+Cordis rebinds a cross-fiber service's `ctx` to the *reader's* fiber, so
+`connection.rpc.handle()` throws: **still present in 0.1.7-rc.1** — see below.
+
+```
+cannot get property "webServer" without inject
+```
+
+The plugin now detects that and mounts the same channel itself:
+
+| Path | When | How |
+|------|------|-----|
+| 1 (preferred) | `connection.rpc.handle()` works | The framework owns the route, request validation, and fiber-scoped withdrawal |
+| 2 (fallback) | Path 1 throws | The plugin registers a `kind: "prefix"` route on its own fiber (which *can* see `webServer`) and reuses `connection.requestRejection()` for the 403/401 fence |
+
+Both carriers speak the identical wire protocol, so **the browser half is
+unchanged** — the panel cannot tell which one is live. If
+`connection.requestRejection()` is unavailable, the plugin refuses to mount
+rather than publishing an unauthenticated route.
 
 
 ---
@@ -72,6 +97,9 @@ dsh plugin add ./path/to/dsh-llm-rate-limiter   # default profile
 
 > The plugin must be added as a dependency in the profile's `package.json`.
 > The bundle entry (`cordis.patch.yml`) is auto-detected by `reconcilePlugins`.
+>
+> **0.3.0 requires DSH 0.1.7-rc.1 or newer.** Pin `@leaf233/dsh-llm-rate-limiter@0.2.x`
+> for DSH 0.1.5. See the [compatibility table](#compatibility).
 
 ### Option 3: from GitHub
 
@@ -96,13 +124,20 @@ dsh plugin add <your-profile> github:Leafyezi233/dsh-llm-rate-limiter
 ### Via GUI
 
 1. Open DSH Web UI (`dsh web`)
-2. Go to **Settings → Plugins**
-3. Find **⚙ LLM 调用限速** card — click to expand
-4. Configure defaults, per-model overrides, and throttle behavior
+2. Go to **Settings → Plugins** and open the **Official** group
+3. Find the **LLM 调用限速** card (`data-plugin-item="llm-rate-limiter"`) and open it
+4. Configure defaults, per-model overrides, and throttle behavior — changes save
+   through the page's own form, so the live status panel is right there
+
+> The card lives in the **Official** group because DSH lists every `plugins.item`
+> registrant there; the plugin's order is `900`, so it follows the five official
+> settings pages.
 
 ### Via file
 
-Edit the profile's `settings.yaml` or use the GUI — changes are persisted to the DSH settings store:
+Changes persist into the profile's Cordis patch, in the entry's own `config`
+(0.1.7 reads configuration from the entry's exported `Config`; a legacy
+`settings.yaml` is imported by DSH once at first start and then renamed). The shape is:
 
 ```yaml
 llm-rate-limiter:
@@ -189,8 +224,19 @@ cd dsh-llm-rate-limiter
 # Install deps
 pnpm install
 
-# Run tests (19 tests)
-node test-strategies.mjs
+# Run the full suite (375 assertions across 6 files)
+pnpm test
+
+# Individual suites
+node test-strategies.mjs       # 19 — rate-limit algorithms
+node test-status-rpc.mjs       # 61 — channel handler + counters
+node test-client-bundle.mjs    # 106 — real client bundle on a miniature React runtime
+node test-host-integration.mjs # 80 — real apply(ctx, config) wiring + volatile refs
+node test-status-route.mjs     # 73 — self-registered route + the 0.1.5 regression
+node test-config-schema.mjs    # 36 — Config volatile contract the settings page needs
+
+# Live HTTP proof against a real DSH install (real socket, real webserver)
+pnpm run verify:live           # 19 — exits 2 (skipped) when DSH is absent
 
 # Run E2E rate-limit test
 node test-3rpm.mjs
@@ -205,13 +251,30 @@ The plugin uses a live symlink when installed via `link:` — edits to `lib/` ta
 
 ## Compatibility
 
-| DSH Version | Status | Notes |
-|-------------|--------|-------|
-| 0.1.x (RC) | ✅ Tested | Verified against 0.1.2-rc.1, cordis 4.0.2 |
-| 0.2.x | ⚠️ Untested | May need API adjustments |
-| Cordis 5+ | ⚠️ Untested | Major version change likely requires rewrite |
+| DSH Version | Plugin version | Status | Notes |
+|-------------|----------------|--------|-------|
+| 0.1.2-rc.1 | 0.2.x | ✅ Tested | Original target; `connection.rpc` carrier |
+| 0.1.5-rc.3 | 0.2.x | ✅ Tested | Requires the carrier fallback; verified over real HTTP |
+| **0.1.7-rc.1+** | **0.3.x** | ✅ **Tested** | **`settingsScope` → `configForms`; `settings.plugin.item` → `plugins.item`; Config-based settings** |
+| 0.2.x (DSH) | — | ⚠️ Untested | May need API adjustments |
+| Cordis 5+ | — | ⚠️ Untested | Major version change likely requires rewrite |
+
+### Breaking change in 0.3.0
+
+DSH 0.1.7 removed the two client services this plugin used for its settings UI:
+
+| 0.1.5 | 0.1.7 |
+|-------|-------|
+| `settingsScope` service | `configForms` service |
+| `settings.plugin.item` slot | `plugins.item` slot |
+| host `ctx.settings.register(ns, schema, { base })` | the entry's own exported `Config` schema |
+| host `scope.get()` / `scope.watch()` | `.volatile()` references, read with `.get()` |
+
+**0.3.0 only supports DSH 0.1.7-rc.1+. Use `0.2.x` for 0.1.5.**
 
-See [COMPATIBILITY.md](COMPATIBILITY.md) for detailed API dependency analysis.
+The four breakpoints this migration rests on are documented inline in
+`lib/index.js` and `lib/types/config.js`, and the reasoning is recorded in
+[CHANGELOG.md](CHANGELOG.md) under `[0.3.0]`.
 
 ---
 

package/README.zh.md

@@ -0,0 +1,284 @@
+# dsh-llm-rate-limiter
+
+[![npm](https://img.shields.io/npm/v/@leaf233/dsh-llm-rate-limiter.svg)](https://www.npmjs.com/package/@leaf233/dsh-llm-rate-limiter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![DSH 0.1.7+](https://img.shields.io/badge/DSH-0.1.7--rc.1%2B-brightgreen.svg)
+[![Cordis 4.x](https://img.shields.io/badge/Cordis-%3E%3D4.0.0-brightgreen.svg)](package.json)
+[![Tests](https://img.shields.io/badge/tests-375%20passing-brightgreen.svg)](test-config-schema.mjs)
+
+[English](README.md) | 中文
+
+[DeepSeek Harness](https://github.com/deepseek-ai/dsh) 的**按模型 LLM 调用限速插件**，支持排队/拒绝两种节流策略，并带交互式图形配置界面。
+
+---
+
+## 功能
+
+- **按模型限速** —— 每个 `provider/model` 独立的并发数、RPM 与突发容量限制
+- **两种算法** —— 令牌桶（允许突发）或滑动窗口（平滑、严格 RPM）
+- **排队模式** —— 被限流的请求排队等待，有槽位空出时放行
+- **拒绝模式** —— 被限流的请求立即失败（可与 `dsh-llm-retry` 配合自动退避重试）
+- **交互式界面** —— DSH 设置 → 插件页内的可展开配置卡片
+- **实时状态面板** —— 实时计数器、按模型的进度条与事件日志（v0.2.0 起）
+- **热更新** —— 配置改动立即生效，无需重启
+- **全量检查** —— 拦截 `llm/stream` waterfall，覆盖每个 agent 轮次里的每一次 LLM 调用
+
+---
+
+## 状态面板（v0.2.0）
+
+打开卡片后，其正文顶部会显示实时面板：
+
+```
+📊 实时状态                          ● 实时   [清零]
+ 请求 42 · 通过 38 · 拒绝 2 · 超时 1 · 中止 1 · 平均等待 214ms
+ deepseek/deepseek-chat   [令牌桶]  ▓▓▓▓▓▓▓░░░ 7.5/10   并发 2/5   排队 1
+ openai/gpt-4o            [滑动窗口] ▓▓▓▓▓▓▓▓▓▓ 3/3 rpm  并发 1/5
+ 12:00:03  timeout   openai/gpt-4o              等待 1m
+ 12:00:01  rejected  openai/gpt-4o
+ 12:00:00  granted   deepseek/deepseek-chat     等待 4.2s
+```
+
+| 方面 | 行为 |
+|------|------|
+| 数据通道 | 通道 `/llm-rate-limiter` —— 带认证（401/403 栅栏），POST+JSON，随插件 fiber 自动清理 |
+| 载体 | 优先用框架的 `connection.rpc.handle()`；框架路径失效时，退回到插件自注册的前缀路由并复用 `connection.requestRejection()`（见下文） |
+| 轮询节奏 | 卡片展开时 1 秒轮询；连续失败后退避 2 秒 → 4 秒 → 8 秒 |
+| 折叠状态 | 面板卸载，因此**完全不轮询** |
+| 端点 | `snapshot`（实时计数）与 `reset`（清零统计） |
+| 通道不可用时 | 显示「状态通道不可用」，卡片其余部分功能不受影响 |
+| 计数器 | `requests` / `granted` / `rejected` / `timeouts` / `aborted` / `totalWaitMs`，外加最近 8 条事件（环形缓冲为 64） |
+| 进度条 | 令牌桶显示 `tokens/burstSize`；滑动窗口显示 `countInWindow/maxRpm`；接近上限时变琥珀色 |
+
+### 载体兜底（DSH 0.1.5-rc.3 起）
+
+DSH 0.1.5-rc.3 把 `@deepseek-ai/dsh-client-connection` **这个框架插件自身**的 `inject` 从
+`["webServer", "credentials"]` 改成了 `["credentials"]`，但其
+`HostConnectionService.register()` 仍然解引用 `owner.webServer`。
+Cordis 会把跨 fiber 读取的 service 的 `ctx` 重绑定到**读取者**的 fiber，因此
+`connection.rpc.handle()` 会抛错：**在 0.1.7-rc.1 中依然存在** —— 见下文。
+
+```
+cannot get property "webServer" without inject
+```
+
+插件会检测到该错误，并自行挂载同一条通道：
+
+| 路径 | 触发条件 | 做法 |
+|------|---------|------|
+| 1（首选） | `connection.rpc.handle()` 正常 | 由框架持有路由、请求校验与 fiber 级撤销 |
+| 2（兜底） | 路径 1 抛错 | 插件在**自己的 fiber**（能看到 `webServer`）注册 `kind: "prefix"` 路由，并复用 `connection.requestRejection()` 作为 403/401 栅栏 |
+
+两条载体使用逐字相同的 wire 协议，因此**浏览器端无需改动** —— 面板也分辨不出
+当前是哪一条。若 `connection.requestRejection()` 不可用，插件会**拒绝挂载**，
+而不是发布一条未鉴权的路由。
+
+---
+
+## 安装
+
+### 方式 1：npm（推荐）
+
+```bash
+dsh plugin add <your-profile> @leaf233/dsh-llm-rate-limiter
+# 或在该 profile 目录内：
+pnpm add @leaf233/dsh-llm-rate-limiter
+```
+
+### 方式 2：本地路径（开发）
+
+```bash
+dsh plugin add <your-profile> ./path/to/dsh-llm-rate-limiter
+# 或
+dsh plugin add ./path/to/dsh-llm-rate-limiter   # 默认 profile
+```
+
+> 插件必须被加入该 profile 的 `package.json` 依赖中。
+> bundle 入口（`cordis.patch.yml`）由 `reconcilePlugins` 自动识别。
+>
+> **0.3.0 要求 DSH 0.1.7-rc.1 或更新版本。** 若使用 DSH 0.1.5，请锁定
+> `@leaf233/dsh-llm-rate-limiter@0.2.x`。见[兼容性表](#兼容性)。
+
+### 方式 3：从 GitHub 安装
+
+```bash
+dsh plugin add <your-profile> github:Leafyezi233/dsh-llm-rate-limiter
+```
+
+> ⚠️ **重要**：从 Git 安装的插件在首次安装时会被 pnpm 的 `allowBuilds` 限制拦下。
+> 若安装失败，请查看报错信息中 pnpm 给出的确切键名，然后加入该 profile 的
+> `pnpm-workspace.yaml`：
+>
+> ```yaml
+> pnpm:
+>   allowBuilds:
+>     - '@leaf233/dsh-llm-rate-limiter'
+> ```
+>
+> 然后重新执行安装命令。
+
+---
+
+## 配置
+
+### 通过图形界面
+
+1. 打开 DSH Web UI（`dsh web`）
+2. 进入**设置 → 插件**，展开 **Official** 分组
+3. 找到 **LLM 调用限速** 卡片（`data-plugin-item="llm-rate-limiter"`）并打开
+4. 配置全局默认值、按模型覆盖与节流行为 —— 改动经页面自带的表单保存，
+   实时状态面板就在同一页
+
+> 卡片出现在 **Official** 分组里，是因为 DSH 把所有 `plugins.item` 的注册者
+> 都列在那里；本插件的 `order` 为 `900`，因此排在五个官方设置页之后。
+
+### 通过配置文件
+
+改动会被持久化到该 profile 的 Cordis patch 中该条目的 `config` 里
+（0.1.7 起，插件以自己的 `Config` 作为配置来源；旧版 `settings.yaml` 由
+DSH 在首次启动时导入一次并改名）。形状如下：
+
+```yaml
+llm-rate-limiter:
+  enabled: true
+  strategy: token-bucket       # "token-bucket" | "sliding-window"
+  defaults:
+    maxConcurrent: 5
+    maxRpm: 60
+    burstSize: 10               # 仅令牌桶
+    refillRate: 1               # 仅令牌桶（每秒补充的令牌数）
+  models:
+    "deepseek/deepseek-chat":
+      maxConcurrent: 8
+      maxRpm: 120
+    "openai/gpt-4o":
+      maxConcurrent: 2
+      maxRpm: 10
+      burstSize: 3
+    "anthropic/claude-3-5-sonnet":
+      enabled: false            # 对该模型跳过限速
+  onThrottled: queue            # "queue" | "reject"
+  maxQueueWaitMs: 60000
+```
+
+---
+
+## 设置项参考
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `enabled` | `true` | 全局总开关。关闭时零开销直接放行。 |
+| `strategy` | `"token-bucket"` | `"token-bucket"`（允许突发）或 `"sliding-window"`（平滑、严格 RPM） |
+| `defaults.maxConcurrent` | `5` | 每个模型的最大同时请求数 |
+| `defaults.maxRpm` | `60` | 每个模型每分钟最大请求数 |
+| `defaults.burstSize` | `10` | 令牌桶容量 —— 一次最多可突发多少个请求 |
+| `defaults.refillRate` | `1` | 每秒补充的令牌数（令牌桶）。未设置时由 `maxRpm / 60` 自动推导。 |
+| `models.<key>.maxConcurrent` | — | 该模型的并发数覆盖 |
+| `models.<key>.maxRpm` | — | 该模型的 RPM 覆盖 |
+| `models.<key>.burstSize` | — | 该模型的突发容量覆盖 |
+| `models.<key>.refillRate` | — | 该模型的补充速率覆盖 |
+| `models.<key>.enabled` | — | 设为 `false` 可对该模型跳过限速 |
+| `onThrottled` | `"queue"` | 请求触限时的行为：`"queue"`（等待）或 `"reject"`（立即失败） |
+| `maxQueueWaitMs` | `60000` | 请求在队列中等待多久（毫秒）后放弃并被拒绝 |
+
+> **注意**：当模型覆盖了 `maxRpm` 但未显式设置 `refillRate` 时，补充速率会
+> 自动按 `maxRpm / 60`（每秒令牌数）推导。这样才能保证「设 maxRpm=3」真的限制到
+> 每分钟 3 个请求。
+
+---
+
+## 算法对比
+
+| | 令牌桶 | 滑动窗口 |
+|---|--------|----------|
+| **突发** | 允许（由 `burstSize` 控制） | 不允许 —— 严格平滑 |
+| **恢复** | 令牌按 `refillRate`/秒补充 | 窗口持续滑动 |
+| **最适合** | 容忍请求尖峰 | 有硬性每分钟上限的 API |
+| **界面名称** | 令牌桶 (Token Bucket) | 滑动窗口 (Sliding Window) |
+
+---
+
+## 工作原理
+
+```
+Agent 轮次
+  → LLM 调用（例如 deepseek/deepseek-chat）
+    → ctx.on("llm/stream") 拦截器
+      → 为该 provider/model 解析对应的限速器
+      → 令牌桶：还有令牌且并发未满？
+      → 是：消耗令牌、占用槽位、转发到 API
+      → 否（拒绝模式）：立即返回 RATE_LIMIT 错误
+      → 否（排队模式）：进入 waiters[] 等待令牌补充
+    → 请求完成 → 释放槽位 → 唤醒等待中的请求
+  → dsh-llm-retry 捕获 RATE_LIMIT → 指数退避 → 重试
+```
+
+---
+
+## 开发
+
+```bash
+# 克隆
+git clone https://github.com/Leafyezi233/dsh-llm-rate-limiter.git
+cd dsh-llm-rate-limiter
+
+# 安装依赖
+pnpm install
+
+# 跑完整测试套件（6 个文件，375 条断言）
+pnpm test
+
+# 单独运行各套件
+node test-strategies.mjs       # 19 —— 限速算法
+node test-status-rpc.mjs       # 61 —— 通道处理器与计数器
+node test-client-bundle.mjs    # 106 —— 真实客户端 bundle 跑在迷你 React 运行时上
+node test-host-integration.mjs # 80 —— 真实 apply(ctx, config) 接线与 volatile 引用
+node test-status-route.mjs     # 73 —— 自注册路由与 0.1.5 回归
+node test-config-schema.mjs    # 36 —— 设置页所依赖的 Config volatile 契约
+
+# 针对真实 DSH 安装的实机 HTTP 验证（真实 socket、真实 webserver）
+pnpm run verify:live           # 19 —— 无 DSH 时以退出码 2 跳过
+
+# 运行端到端限速测试
+node test-3rpm.mjs
+
+# 安装到某个 DSH profile 里测试
+dsh plugin add <your-profile> .
+```
+
+通过 `link:` 安装时，插件走实时符号链接 —— 对 `lib/` 的改动在浏览器硬刷新
+（`Ctrl+Shift+R`）后即生效，无需重新安装。
+
+---
+
+## 兼容性
+
+| DSH 版本 | 插件版本 | 状态 | 说明 |
+|----------|---------|------|------|
+| 0.1.2-rc.1 | 0.2.x | ✅ 已测 | 最初目标；`connection.rpc` 载体 |
+| 0.1.5-rc.3 | 0.2.x | ✅ 已测 | 需要载体兜底；已通过实机 HTTP 验证 |
+| **0.1.7-rc.1+** | **0.3.x** | ✅ **已测** | **`settingsScope` → `configForms`；`settings.plugin.item` → `plugins.item`；基于 Config 的设置** |
+| 0.2.x（DSH） | — | ⚠️ 未测 | 可能需要调整 API |
+| Cordis 5+ | — | ⚠️ 未测 | 大版本升级多半需要重写 |
+
+### 0.3.0 的破坏性变更
+
+DSH 0.1.7 移除了本插件设置界面所用的两个客户端服务：
+
+| 0.1.5 | 0.1.7 |
+|-------|-------|
+| `settingsScope` 服务 | `configForms` 服务 |
+| `settings.plugin.item` 槽位 | `plugins.item` 槽位 |
+| 宿主 `ctx.settings.register(ns, schema, { base })` | 条目自己导出的 `Config` schema |
+| 宿主 `scope.get()` / `scope.watch()` | `.volatile()` 引用，用 `.get()` 读取 |
+
+**0.3.0 只支持 DSH 0.1.7-rc.1+。使用 0.1.5 请安装 `0.2.x`。**
+
+本次迁移所依赖的四个断裂点，已就地写在 `lib/index.js` 与 `lib/types/config.js`
+的注释里；完整推理记录在 [CHANGELOG.md](CHANGELOG.md) 的 `[0.3.0]` 段落。
+
+---
+
+## 许可证
+
+[MIT](LICENSE)