Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

docs: plugin guide says what four rules do when a plugin gets them wrong (plugins#468)

yetone1319a44bbc73
diff --git a/docs/subsystems/provider-plugins.md b/docs/subsystems/provider-plugins.md
index 81753e45a..17bc8c960 100644
--- a/docs/subsystems/provider-plugins.md
+++ b/docs/subsystems/provider-plugins.md
@@ -42,6 +42,8 @@ The gateway parses the field into `Usage.Deferred` ([`cUsage`](../../internal/ga
A usage window's `used` (percent) may be left out when the plugin can't tell it: the Loomy plugins send only `display` ([#3650](https://github.com/yetone/magpie/issues/3650)). Left out is not 0. The host passes it on as `null` (`usageOf` in [`host.js`](../../internal/plugin/host.js)), `plugin.UsageWindow.Used` is a `*float64`, and [`quotaOfPlugin`](../../internal/provider/plugin_usage.go) makes such a window `Text` and `Aside`: the card shows its `display` (else "No allowance reported"), never a percentage or a meter (`quotaNoShare` in `app.js`), and `allowanceOf` leaves it out. An account whose windows all tell no share has no allowance, so routing counts it not known (`routedAllowance` in [`routing.go`](../../internal/provider/routing.go), for a fresh reading and the one kept on disk alike), as one never read, rather than as the one with all of it left. A window that says `used: 0` is a reading at 0, as before. [`plugin_usage_absent_test.go`](../../internal/provider/plugin_usage_absent_test.go) and `usage-no-reading.test.cjs` cover both.
+A window that leaves out `used` but tells its count, `amount` of `limit` with both above 0, has the count's share (370 of 1000 is 37 used): [`quotaOfPlugin`](../../internal/provider/plugin_usage.go) fills `Used` from it, so the window is neither `Text` nor, unless the plugin set it, `Aside`, and routing reads it ([magpie-community/plugins#468](https://github.com/magpie-community/plugins/issues/468)). Before, such a window was text alone, and an account whose windows all told counts so was unknown to routing. An `amount` of 0 is what a left-out amount reads as, so a `limit` alone still says nothing. `aside: true` keeps a window out of routing (`allowanceOf`) whatever its count; the card and `/v1/magpie/quotas` still show it. `TestAWindowsCountIsItsShare` in [`plugin_usage_absent_test.go`](../../internal/provider/plugin_usage_absent_test.go) covers it.
+
## A wallet's balance
A prepaid wallet (SuperMagic's points, [#3950](https://github.com/yetone/magpie/issues/3950)) has a balance and nothing it is a share of. A usage window may send `balance` (a number, in `unit`) and leave out `used`, `limit` and `aside`: `{name: "积分", balance: 6291, unit: "积分"}`. The host passes a finite number on, at least 0, and anything else as `null` (`usageOf` in [`host.js`](../../internal/plugin/host.js)); `plugin.UsageWindow.Balance` and `provider.QuotaWindow.Balance` are `*float64`. [`quotaOfPlugin`](../../internal/provider/plugin_usage.go) keeps the figure and does not make the window `Text` or `Aside`, so the account is known to routing with no `Used` invented. `allowanceOf` copies it into `Limit.Balance`, and an empty wallet (0) counts as used up. `Allowance.Left(model)` is the least balance of the windows that count the model, with its unit. `weighRouted` sets `routes.Seat.Left` to it and `Seat.LeftIn` to the account's provider and unit; Smart, `pace` and `usage` put the seat with more left first where they would otherwise tie (`byLeft` in [`strategies.go`](../../internal/routes/strategies.go)), and only when every seat that has a balance shares one `LeftIn`, so balances in two units or two providers are never weighed against each other. The card, the Routing page (`Weighed.Balance`) and the CLI show the figure ("6,291 积分 left", `provider.BalanceText`) and no meter. A wallet window's `runsOutAt`/`runsOut` (its soonest batch to lapse) and the rows set aside after it (`aside` text: SuperMagic's day's, timed and permanent points) are display only: the card says them, and the Routing page reads them from the same card (`cardOf` in the routing plugin's `client.js`, live requests only), its row saying the lapse after the figure ("6,291 积分 left · 185 积分 expire 23:59", `runsOutText`, #3964) and its tooltip and account list each window (`winsOf`). Routing goes by the balance alone. Tests: `TestPluginWalletBalanceIsAReading`, `TestPluginHostPassesABalanceOn`, `TestWalletsGoByWhatTheyHaveLeft`, `TestWalletWithMoreLeftGoesFirst`, `usage-wallet-balance.test.cjs`, `routing-wallet-balance.test.cjs`, `routing-wallet-lapse.test.cjs`.
@@ -138,6 +140,18 @@ How the store handles picks and names:
The host loads every plugin side by side (`loadPlugins` in [`host.js`](../../internal/plugin/host.js)) and gives each one `pluginLoadWait` (20s, [`host.go`](../../internal/plugin/host.go)) for its import and its plugin function, and each config hook as long. A plugin still loading then is told as not loaded ("the plugin's load didn't finish in 20s") and the host answers `init` with the rest; what it returns later is dropped until the host starts again. Hooks are still kept in the list's order. A listing (`providers`) asks every provider side by side too, and gives each models hook `pluginListWait` (20s, inside `refreshDeadline`'s 30s): one that hasn't answered is listed as fallen back with that as its `listError`, so magpie keeps the list it had, and that answer isn't kept for requests (`keepInfo`). Before, one plugin whose sign-in kept failing held every plugin after it until `init`'s two-minute deadline failed the whole host, and one stuck models hook failed the whole list (shualaitianduai on Discord). `TestStuckPluginLoadHoldsNoOther` and `TestStuckModelListHoldsNoOther` hold both.
+## A plugin's 401 about the model
+
+A 401 marks the account's sign-in by default (`notePluginSignIn` in [`plugins.go`](../../internal/provider/plugins.go)), and the gateway fails a 401 over to the provider's next account (`retryable` in [`fallback.go`](../../internal/gateway/fallback.go)), which a model the plan doesn't serve answers the same way. So a plugin that answered "this model isn't available to you" with 401 marked every account of the provider as needing a new sign-in, for credentials that were fine ([magpie-community/plugins#468](https://github.com/magpie-community/plugins/issues/468)). A 401 without `X-Magpie-Sign-In` whose body says the model isn't served (`provider.ModelUnserved`, the gateway's `unservedWords`, read decoded by `catalog.Words`) and nothing of a token, key, credential, session or sign-in (`signInWords`) is now read as `kept` (`modelOnly401`). Only the body's first 64KB is read, and the body goes on whole. The gateway still rests the account under its usual failure backoff for that answer; the guide asks for 403 or 404 for a model the account may not use, which `modelRefused` reads as the model refused. `TestPluginModel401KeepsSignIn` in [`plugin_signin_model_test.go`](../../internal/provider/plugin_signin_model_test.go) covers both kinds of 401.
+
+## A model's free and rate
+
+magpie never reads `free` from `rate`: `rate` 0 is none given (`plugin.Model.Rate` in [`providers.go`](../../internal/plugin/providers.go)), and a model is free only by its own `free: true` or a $0 list price (`FreeModel` in [`models.go`](../../internal/provider/models.go)). A plugin sets `free` from the vendor's word; the guide says so ([magpie-community/plugins#468](https://github.com/magpie-community/plugins/issues/468)).
+
+## A GitHub listing's licence
+
+A repository tagged `magpie-plugin` shows the licence GitHub's search reads from its `LICENSE` file. GitHub gives `NOASSERTION` for a file it can't match to one (MIT's text with a line of credit added) and nothing for none, and magpie drops `NOASSERTION`, so such a card had no licence while the same package on npm shows its `package.json` `license`. `readTagged` in [`github.go`](../../internal/plugin/github.go) now keeps `package.json`'s `license` (a string) as `PkgLicense`, and `License` falls back to it, on a fresh read and on one kept across searches (`fresh`) ([magpie-community/plugins#468](https://github.com/magpie-community/plugins/issues/468)). `TestTaggedRepos` covers both cases and the one with neither.
+
## How ownership changes
Migration records use five states:
diff --git a/site/public/docs/ja/plugins.html b/site/public/docs/ja/plugins.html
index f721b90d2..1c0f870a1 100644
--- a/site/public/docs/ja/plugins.html
+++ b/site/public/docs/ja/plugins.html
@@ -347,8 +347,8 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<code>provider.models</code> のモデルを展開していくつかのフィールドを変えるのが簡単です。<code>status</code> が <code>"deprecated"</code> のモデルは表示されません。</li>
<li>magpie は、OpenCode が無視する次のフィールドもモデルから読み取ります:
<ul>
- <li><code>free: true</code>:プランの枠を消費せずに使えます。</li>
- <li><code>rate</code>:1 リクエストが消費するクレジットの倍率。数値(<code>0.5</code>)でも、ベンダーの表記(<code>"x0.5"</code>)でも構いません。</li>
+ <li><code>free: true</code>:プランの枠を消費せずに使えます。モデルを無料とするのはこのフィールドだけで、magpie は <code>rate</code> から推測しません。自分で計算した倍率ではなく、ベンダー自身の表示(一覧で無料と示している、または $0 の価格)に従って設定してください。</li>
+ <li><code>rate</code>:1 リクエストが消費するクレジットの倍率。数値(<code>0.5</code>)でも、ベンダーの表記(<code>"x0.5"</code>)でも構いません。<code>0</code> は倍率の指定なしとして扱われ、無料にはなりません。</li>
<li><code>rateWas</code>:現在実施中の割引の前の倍率。</li>
</ul>
モデル選択画面に表示されます。</li>
@@ -485,7 +485,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<p><code>Response</code> を返してください。そのステータス、ヘッダー、本文はそのまま、チャンクごとにストリームで返されます。ストリーミングの本文を書き換える場合は、ヘッダーから <code>content-length</code> と <code>content-encoding</code> を取り除いてください。</p>
<h3>失敗とフェイルオーバー</h3>
<ul>
- <li>2xx 以外の応答はベンダーの応答です。ゲートウェイはほかのプロバイダと同じように扱います:レート制限やサーバーエラーならリクエストを次のアカウントやモデルに移し、401 ならアカウントに記録を付けます(<a href="#signin-state">サインイン状態</a>を参照)。</li>
+ <li>2xx 以外の応答はベンダーの応答です。ゲートウェイはほかのプロバイダと同じように扱います:レート制限やサーバーエラーならリクエストを次のアカウントやモデルに移し、401 ならアカウントに記録を付けます(<a href="#signin-state">サインイン状態</a>を参照)。アカウントが使えないモデルには、401 ではなく 403 か 404 とベンダーの文言で応答してください。ゲートウェイはそれをサインインではなくモデルの拒否として扱います。</li>
<li>例外を投げるとリクエストは失敗し、フェイルオーバーが次に進みます。</li>
<li>可能なら API 自身のエラー形式で応答してください。エージェントがベンダーのメッセージを表示できます。</li>
</ul>
@@ -506,6 +506,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<tr><td><code>kept</code></td><td>アカウントをそのままにする(別の理由による 401)。</td></tr>
<tr><td><code>renewed</code></td><td>サインインが更新された:リクエストがその後どうなっても記録を消す。</td></tr>
</table></div>
+ <p>ヘッダーのない 401 で、本文がモデルが提供されていないこと(「model … not available」、<code>model_not_found</code>、「模型不支持」)だけを述べ、トークン、キー、セッション、サインインに触れていないものは <code>kept</code> として扱います。以前は、リクエストがフェイルオーバーした先のすべてのアカウントに再サインインが必要という記録が付いていました。モデル名とともにトークンが無効だと述べる 401 は、引き続きアカウントに記録を付けます。</p>
<p><code>fetch</code> や <code>provider.models</code> から <code>signIn: "expired"</code> を付けたエラーを投げても同じ効果があります:</p>
<div class="code">
<span class="lang">index.mjs</span>
@@ -541,6 +542,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
}</pre>
</div>
<p>時刻は ISO 文字列か、秒またはミリ秒のエポック数値です。<code>signIn</code> がない場合、再サインインを求める <code>error</code> はアカウントに記録を付け、問題なく読み取れれば記録は消えます。</p>
+ <p>ベンダーが <code>used</code> を示さないときは省略し、「不明」の意味で 0 を送らないでください。<code>used</code> を省略して <code>amount</code> と <code>limit</code> を送ると、使用率はそこから計算されます(1000 のうち 370 なら 37)。数値もない場合、ウィンドウは <code>display</code> の表示だけになり、ルーティングは読みません。すべてのウィンドウが何も示さないアカウントは、残りが最も多いものではなく、まだ読み取っていないものとして扱われます。<code>aside: true</code> のウィンドウは、使用率と数値とともにアカウントのカードと <code>GET /v1/magpie/quotas</code> に表示されますが、ルーティングは読みません。<code>amount</code> や <code>limit</code> が何であっても、使い切ってもアカウントは止まらず、ほかのアカウントとの比較で不利にもなりません。アカウントが実際に止まるウィンドウには <code>aside</code> を付けないでください。</p>
<h2 id="checkin"><a class="anchor" href="#checkin">チェックイン</a></h2>
<p>毎日のチェックインでクレジットをくれるベンダーなら、プラグインが <code>auth.checkin</code> で押せます。magpie 独自の hook です(OpenCode は無視します)。ユーザーがそのプロバイダーのチェックインをオンにしている間、magpie はサインイン済みの各アカウントについて北京時間の 1 日に 1 回呼び、結果をアカウントの使用量カードと設定に表示します。</p>
@@ -631,7 +633,7 @@ m plugin logout acme</pre>
<span class="s">"summary"</span>: { <span class="s">"en"</span>: <span class="s">"Your Acme Coding Plan."</span>, <span class="s">"zh"</span>: <span class="s">"使用你的 Acme Coding Plan。"</span> } }</pre>
</div>
ミドルウェアのエントリには <code>"kind": "middleware"</code> を書き、<code>providers</code> は書きません。<span class="ui">ゲートウェイミドルウェア</span> の下に表示されます。ほかの種類も同じで、<code>"kind": "tools"</code> は <span class="ui">エージェント向けツール</span>、<code>"kind": "page"</code> は <span class="ui">ページ</span>、<code>"kind": "agent"</code> は <span class="ui">エージェント</span> の下に表示されます。<code>MAGPIE_PLUGIN_MARKET=&lt;url&gt;</code> は magpie に別の一覧を参照させます(自分の一覧の確認に便利です)。<code>off</code> にすると内蔵のコピーだけを使います。</li>
- <li><b>GitHub のトピック。</b>GitHub で <code>magpie-plugin</code> トピックを付けたリポジトリは、<span class="ui">プラグイン → 発見 → 非公式 · GitHub</span> に、スターの多い順に、誰もレビューしていないものとして表示されます。<code>package.json</code> はリポジトリのルートに置いてください。<code>repository</code> がそのリポジトリを指す形で npm に公開されていれば npm からインストールされ、そうでなければリポジトリの現在のコードがインストールされます。そのため読み込むファイルはコミットしておく必要があり、<code>dist</code> を公開時にしかビルドしないリポジトリは表示されません。フォーク、アーカイブ済みのリポジトリ、magpie-community 自身のものも表示されません。magpie が GitHub に問い合わせるのは最大で 10 分に 1 回なので、トピックを付けたリポジトリは数分で表示されます。カードには <code>package.json</code> の <code>"magpie": { "icon": "…" }</code> で指定したアイコンが表示され、ない場合はパズルのアイコンになります。</li>
+ <li><b>GitHub のトピック。</b>GitHub で <code>magpie-plugin</code> トピックを付けたリポジトリは、<span class="ui">プラグイン → 発見 → 非公式 · GitHub</span> に、スターの多い順に、誰もレビューしていないものとして表示されます。<code>package.json</code> はリポジトリのルートに置いてください。<code>repository</code> がそのリポジトリを指す形で npm に公開されていれば npm からインストールされ、そうでなければリポジトリの現在のコードがインストールされます。そのため読み込むファイルはコミットしておく必要があり、<code>dist</code> を公開時にしかビルドしないリポジトリは表示されません。フォーク、アーカイブ済みのリポジトリ、magpie-community 自身のものも表示されません。magpie が GitHub に問い合わせるのは最大で 10 分に 1 回なので、トピックを付けたリポジトリは数分で表示されます。カードには <code>package.json</code> の <code>"magpie": { "icon": "…" }</code> で指定したアイコンが表示され、ない場合はパズルのアイコンになります。ライセンスは GitHub がリポジトリの <code>LICENSE</code> ファイルから読み取ったものです。GitHub がどのライセンスか判定できない場合(<code>NOASSERTION</code>。MIT の本文に 1 行加えた場合など)やファイルがない場合は、<code>package.json</code> の <code>license</code> を表示します。npm からインストールされるプラグインは <code>package.json</code> のものを表示します。</li>
<li><b>コミュニティのパッケージ。</b><a href="https://github.com/magpie-community/plugins">magpie-community/plugins</a> に貢献するには:
<ul>
<li><code>packages/&lt;name&gt;</code> に置き、名前はプロバイダなら <code>@magpie-community/opencode-&lt;name&gt;-auth</code>、ミドルウェアやルーティング戦略なら <code>@magpie-community/middleware-&lt;name&gt;</code>、ツールなら <code>@magpie-community/tools-&lt;name&gt;</code>、ページなら <code>@magpie-community/page-&lt;name&gt;</code>、エージェントなら <code>@magpie-community/agent-&lt;name&gt;</code> とします。本当に必要でない限り、ランタイムの依存は持たせないでください。</li>
diff --git a/site/public/docs/plugins.html b/site/public/docs/plugins.html
index 84b8fbd16..4e0e497b2 100644
--- a/site/public/docs/plugins.html
+++ b/site/public/docs/plugins.html
@@ -347,8 +347,8 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
Spreading a model from <code>provider.models</code> and changing a few fields is the easy way. A model whose <code>status</code> is <code>"deprecated"</code> isn’t shown.</li>
<li>magpie also reads these fields on a model, which OpenCode ignores:
<ul>
- <li><code>free: true</code>: the plan serves it at no cost to its allowance.</li>
- <li><code>rate</code>: the credits a request costs, as a multiple, given as a number (<code>0.5</code>) or as the vendor writes it (<code>"x0.5"</code>).</li>
+ <li><code>free: true</code>: the plan serves it at no cost to its allowance. Only this flag makes a model free, and magpie never reads it from <code>rate</code>: set it from the vendor’s own word (its list marks the model free, or prices it at $0), not from a rate you worked out.</li>
+ <li><code>rate</code>: the credits a request costs, as a multiple, given as a number (<code>0.5</code>) or as the vendor writes it (<code>"x0.5"</code>). <code>0</code> reads as no rate given, not as free.</li>
<li><code>rateWas</code>: the rate before a discount that is running now.</li>
</ul>
Model pickers show them.</li>
@@ -485,7 +485,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<p>Return a <code>Response</code>. Its status, headers and body go back as they come, streamed chunk by chunk. If you rewrite a streaming body, drop <code>content-length</code> and <code>content-encoding</code> from the headers.</p>
<h3>Failures and failover</h3>
<ul>
- <li>A non-2xx response is the vendor’s answer. The gateway handles it as it would any provider’s: a rate limit or a server error moves the request to the next account or model, and a 401 marks the account (see <a href="#signin-state">Sign-in state</a>).</li>
+ <li>A non-2xx response is the vendor’s answer. The gateway handles it as it would any provider’s: a rate limit or a server error moves the request to the next account or model, and a 401 marks the account (see <a href="#signin-state">Sign-in state</a>). Answer a model the account may not use with 403 or 404 and the vendor’s words, not 401: the gateway reads that as the model refused, not the sign-in.</li>
<li>A thrown error fails the request, and failover moves on.</li>
<li>Answer in the API’s own error shape where you can, so the agent shows the vendor’s message.</li>
</ul>
@@ -506,6 +506,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<tr><td><code>kept</code></td><td>Leave the account as it is (a 401 that is about something else).</td></tr>
<tr><td><code>renewed</code></td><td>The sign-in renewed: clear the mark, whatever the request then met.</td></tr>
</table></div>
+ <p>A 401 without the header whose body says only that the model isn’t served (“model … not available”, <code>model_not_found</code>, “模型不支持”) and nothing of a token, key, session or sign-in is read as <code>kept</code>. Before, it marked every account the request failed over to as needing a new sign-in. A 401 that names the model and also says the token is invalid still marks the account.</p>
<p>From <code>fetch</code> or <code>provider.models</code>, throw an error with <code>signIn: "expired"</code> on it for the same effect:</p>
<div class="code">
<span class="lang">index.mjs</span>
@@ -541,6 +542,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
}</pre>
</div>
<p>Times are ISO strings or epoch numbers, in seconds or in milliseconds. Without <code>signIn</code>, an <code>error</code> that says to sign in again marks the account, and a clean read clears the mark.</p>
+ <p>Leave <code>used</code> out when the vendor doesn’t tell it, never send 0 for “not known”. Left out with <code>amount</code> and <code>limit</code>, the share is theirs (370 of 1000 is 37 used). Left out with no count, the window is its <code>display</code> alone: routing doesn’t read it, and an account whose windows all say nothing is weighed as one never read, not as the one with the most left. A window with <code>aside: true</code> is shown on the account’s card, with its share and count, and in <code>GET /v1/magpie/quotas</code>, but routing never reads it: using it up doesn’t stop the account or weigh it against the others, whatever <code>amount</code> and <code>limit</code> say. Leave <code>aside</code> off a window the account really stops at.</p>
<h2 id="checkin"><a class="anchor" href="#checkin">Check-in</a></h2>
<p>A vendor that gives credits for a daily check-in can have the plugin press it with <code>auth.checkin</code>, magpie’s own hook (OpenCode ignores it). magpie runs it for each signed-in account once a Beijing day while the user has check-in on for the provider, and shows what came of it on the account’s Usage card and in Settings.</p>
@@ -631,7 +633,7 @@ m plugin logout acme</pre>
<span class="s">"summary"</span>: { <span class="s">"en"</span>: <span class="s">"Your Acme Coding Plan."</span>, <span class="s">"zh"</span>: <span class="s">"使用你的 Acme Coding Plan。"</span> } }</pre>
</div>
A middleware’s entry has <code>"kind": "middleware"</code> and no <code>providers</code>; it is listed under <span class="ui">Gateway middleware</span>. The other kinds are listed the same way: <code>"kind": "tools"</code> under <span class="ui">Tools for agents</span>, <code>"kind": "page"</code> under <span class="ui">Pages</span> and <code>"kind": "agent"</code> under <span class="ui">Agents</span>. <code>MAGPIE_PLUGIN_MARKET=&lt;url&gt;</code> points magpie at another list, which is useful to check yours, and <code>off</code> keeps to the built-in copy.</li>
- <li><b>A GitHub topic.</b> A repository tagged <code>magpie-plugin</code> on GitHub is shown under <span class="ui">Plugins → Discover → Unofficial, on GitHub</span>, the most starred first, marked as reviewed by no one. Keep <code>package.json</code> at the repository’s root. Published to npm with <code>repository</code> naming the repository, it is installed from npm; otherwise from the repository as it stands, so the file it loads must be committed: one whose <code>dist</code> is built only to publish is left out. Forks, archived repositories and magpie-community’s own are left out too. magpie asks GitHub at most every ten minutes, so a repository shows within minutes of being tagged. Its card shows the icon <code>"magpie": { "icon": "…" }</code> in its <code>package.json</code> gives, else a puzzle piece.</li>
+ <li><b>A GitHub topic.</b> A repository tagged <code>magpie-plugin</code> on GitHub is shown under <span class="ui">Plugins → Discover → Unofficial, on GitHub</span>, the most starred first, marked as reviewed by no one. Keep <code>package.json</code> at the repository’s root. Published to npm with <code>repository</code> naming the repository, it is installed from npm; otherwise from the repository as it stands, so the file it loads must be committed: one whose <code>dist</code> is built only to publish is left out. Forks, archived repositories and magpie-community’s own are left out too. magpie asks GitHub at most every ten minutes, so a repository shows within minutes of being tagged. Its card shows the icon <code>"magpie": { "icon": "…" }</code> in its <code>package.json</code> gives, else a puzzle piece. Its licence is the one GitHub reads from the repository’s <code>LICENSE</code> file; when GitHub can’t match the file to a licence (it says <code>NOASSERTION</code>, as for MIT’s text with a line added) or there is none, the card shows <code>package.json</code>’s <code>license</code>. A plugin installed from npm shows <code>package.json</code>’s.</li>
<li><b>The community packages.</b> To contribute one to <a href="https://github.com/magpie-community/plugins">magpie-community/plugins</a>:
<ul>
<li>Put it under <code>packages/&lt;name&gt;</code>, named <code>@magpie-community/opencode-&lt;name&gt;-auth</code> (a provider) , <code>@magpie-community/middleware-&lt;name&gt;</code> (middleware or a routing strategy), <code>@magpie-community/tools-&lt;name&gt;</code> (tools), <code>@magpie-community/page-&lt;name&gt;</code> (a page) or <code>@magpie-community/agent-&lt;name&gt;</code> (an agent), with no runtime dependencies unless one is really needed.</li>
diff --git a/site/public/docs/zh/plugins.html b/site/public/docs/zh/plugins.html
index ed51fed81..a35f45b74 100644
--- a/site/public/docs/zh/plugins.html
+++ b/site/public/docs/zh/plugins.html
@@ -347,8 +347,8 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
最省事的做法是展开 <code>provider.models</code> 里的模型,再改几个字段。<code>status</code> 为 <code>"deprecated"</code> 的模型不会显示。</li>
<li>magpie 还会读取模型上的这些字段,OpenCode 会忽略它们:
<ul>
- <li><code>free: true</code>:套餐免费提供,不占额度。</li>
- <li><code>rate</code>:一次请求消耗的点数倍率,可以是数字(<code>0.5</code>),也可以照厂商的写法(<code>"x0.5"</code>)。</li>
+ <li><code>free: true</code>:套餐免费提供,不占额度。只有这个字段会让模型算作免费,magpie 不会从 <code>rate</code> 推断:请按厂商自己的说法设置(它的列表标明免费,或标价 $0),不要用自己算出的倍率。</li>
+ <li><code>rate</code>:一次请求消耗的点数倍率,可以是数字(<code>0.5</code>),也可以照厂商的写法(<code>"x0.5"</code>)。<code>0</code> 视为没有给出倍率,而不是免费。</li>
<li><code>rateWas</code>:当前优惠之前的倍率。</li>
</ul>
模型选择器会显示它们。</li>
@@ -485,7 +485,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<p>返回一个 <code>Response</code>。它的状态码、头和正文原样传回,正文逐块流式传输。如果你改写了流式正文,要去掉头里的 <code>content-length</code> 和 <code>content-encoding</code>。</p>
<h3>失败与故障切换</h3>
<ul>
- <li>非 2xx 的响应就是厂商的回答,网关会像对待其他供应商一样处理:限流或服务端错误会把请求转到下一个账号或模型,401 会标记账号(见<a href="#signin-state">登录状态</a>)。</li>
+ <li>非 2xx 的响应就是厂商的回答,网关会像对待其他供应商一样处理:限流或服务端错误会把请求转到下一个账号或模型,401 会标记账号(见<a href="#signin-state">登录状态</a>)。账号不能用某个模型时,请用 403 或 404 加上厂商的原话回答,不要用 401:网关会把它当作模型被拒,而不是登录失效。</li>
<li>抛出异常会让请求失败,然后故障切换继续。</li>
<li>尽量用该 API 自己的错误格式回答,这样 agent 会显示厂商的原话。</li>
</ul>
@@ -506,6 +506,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
<tr><td><code>kept</code></td><td>账号保持原样(这个 401 说的是别的问题)。</td></tr>
<tr><td><code>renewed</code></td><td>登录已续期:清除标记,无论请求接下来遇到什么。</td></tr>
</table></div>
+ <p>没有这个头的 401,如果正文只说模型不可用(“model … not available”、<code>model_not_found</code>、“模型不支持”),而没有提到 token、key、session 或登录,就按 <code>kept</code> 处理。以前它会把请求转移经过的每个账号都标记为需要重新登录。既提到模型、又说 token 无效的 401 仍然会标记账号。</p>
<p>在 <code>fetch</code> 或 <code>provider.models</code> 里,抛出带 <code>signIn: "expired"</code> 的错误效果相同:</p>
<div class="code">
<span class="lang">index.mjs</span>
@@ -541,6 +542,7 @@ magpie quota <span class="c"># acme · Pro · 5h 37%
}</pre>
</div>
<p>时间可以是 ISO 字符串,也可以是以秒或毫秒为单位的时间戳。没有 <code>signIn</code> 时,提示要重新登录的 <code>error</code> 会标记账号,一次正常读取会清除标记。</p>
+ <p>厂商没有给出 <code>used</code> 时就不要传,不要用 0 表示“不知道”。没传 <code>used</code> 但给了 <code>amount</code> 和 <code>limit</code> 时,用量就按它们算(1000 用了 370 就是 37)。没传也没有计数时,窗口只显示它的 <code>display</code>:路由不读它,所有窗口都没给用量的账号,按从未读到用量来权衡,而不是当作剩得最多的那个。<code>aside: true</code> 的窗口会连同用量和计数显示在账号卡片上,也会出现在 <code>GET /v1/magpie/quotas</code> 里,但路由从不读它:不管 <code>amount</code> 和 <code>limit</code> 是多少,用完它不会让账号停用,也不会让账号在比较中靠后。账号真正会被它卡住的窗口,不要设 <code>aside</code>。</p>
<h2 id="checkin"><a class="anchor" href="#checkin">签到</a></h2>
<p>每日签到送额度的供应商,可以让插件用 <code>auth.checkin</code> 去签,这是 magpie 自己的 hook(OpenCode 会忽略)。用户为这个供应商开着签到时,magpie 每个北京日为每个已登录账号调用一次,结果显示在账号的用量卡片和设置里。</p>
@@ -631,7 +633,7 @@ m plugin logout acme</pre>
<span class="s">"summary"</span>: { <span class="s">"en"</span>: <span class="s">"Your Acme Coding Plan."</span>, <span class="s">"zh"</span>: <span class="s">"使用你的 Acme Coding Plan。"</span> } }</pre>
</div>
中间件的条目写 <code>"kind": "middleware"</code>,不写 <code>providers</code>,列在<span class="ui">网关中间件</span>下。其他类型也一样:<code>"kind": "tools"</code> 列在<span class="ui">给 Agent 的工具</span>下,<code>"kind": "page"</code> 列在<span class="ui">页面</span>下,<code>"kind": "agent"</code> 列在 <span class="ui">Agent</span> 下。<code>MAGPIE_PLUGIN_MARKET=&lt;url&gt;</code> 让 magpie 改用另一份列表,可以用来检查你的条目;设为 <code>off</code> 则只用内置副本。</li>
- <li><b>GitHub 标签。</b>在 GitHub 上打了 <code>magpie-plugin</code> topic 的仓库,会显示在 <span class="ui">插件 → 发现 → 非官方插件 · GitHub</span> 里,Star 多的在前,并标明没有人审阅过。<code>package.json</code> 要放在仓库根目录。发布到 npm 且 <code>repository</code> 指向这个仓库的,从 npm 安装;否则按仓库当前的代码安装,所以它加载的文件必须提交进仓库:<code>dist</code> 只在发布时才构建的仓库不会显示。fork、已归档的仓库和 magpie-community 自己的仓库也不显示。magpie 最多每十分钟问一次 GitHub,仓库打上标签后几分钟内就会出现。卡片显示 <code>package.json</code> 里 <code>"magpie": { "icon": "…" }</code> 给的图标,没有就显示拼图图标。</li>
+ <li><b>GitHub 标签。</b>在 GitHub 上打了 <code>magpie-plugin</code> topic 的仓库,会显示在 <span class="ui">插件 → 发现 → 非官方插件 · GitHub</span> 里,Star 多的在前,并标明没有人审阅过。<code>package.json</code> 要放在仓库根目录。发布到 npm 且 <code>repository</code> 指向这个仓库的,从 npm 安装;否则按仓库当前的代码安装,所以它加载的文件必须提交进仓库:<code>dist</code> 只在发布时才构建的仓库不会显示。fork、已归档的仓库和 magpie-community 自己的仓库也不显示。magpie 最多每十分钟问一次 GitHub,仓库打上标签后几分钟内就会出现。卡片显示 <code>package.json</code> 里 <code>"magpie": { "icon": "…" }</code> 给的图标,没有就显示拼图图标。许可证取 GitHub 从仓库 <code>LICENSE</code> 文件识别出的那个;GitHub 认不出是哪种许可证(显示 <code>NOASSERTION</code>,比如 MIT 正文多加了一行)或者没有这个文件时,卡片显示 <code>package.json</code> 的 <code>license</code>。从 npm 安装的插件显示 <code>package.json</code> 里的。</li>
<li><b>社区包。</b>想把插件贡献到 <a href="https://github.com/magpie-community/plugins">magpie-community/plugins</a>:
<ul>
<li>放在 <code>packages/&lt;name&gt;</code> 下,包名为 <code>@magpie-community/opencode-&lt;name&gt;-auth</code>(供应商)、<code>@magpie-community/middleware-&lt;name&gt;</code>(中间件或路由策略)、<code>@magpie-community/tools-&lt;name&gt;</code>(工具)、<code>@magpie-community/page-&lt;name&gt;</code>(页面)或 <code>@magpie-community/agent-&lt;name&gt;</code>(Agent),除非确实需要,不要有运行时依赖。</li>